chore: release api v0.3.4

- Add PlanAgentImpl with read-only tools only
- System prompts optimized for architecture planning
- Outputs step-by-step implementation plans with critical files
- 15 unit tests for registration, tools, and API
- Update COVERAGE.md to ~70% complete

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.gitea/workflows/build-api.yml

@@ -1,20 +1,31 @@
-name: Build and Push
+name: Build and Push API
 
 on:
   push:
     tags:
-      - 'v*'
+      - 'api/v*'
+
+env:
+  IMAGE_NAME: git.schweitz.internal/jpmschweitzer/webber-api
 
 jobs:
   release:
     runs-on: ubuntu-latest
     steps:
+      - name: Extract version from tag
+        id: version
+        run: |
+          # Extract version from api/v0.3.0 -> v0.3.0
+          VERSION="${{ github.ref_name }}"
+          VERSION="${VERSION#api/}"
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
       - name: Create Gitea Release
         run: |
           curl -sf -X POST \
             -H "Authorization: token ${{ secrets.GITHUB_TOKEN }}" \
             -H "Content-Type: application/json" \
-            -d '{"tag_name": "${{ github.ref_name }}", "name": "Release ${{ github.ref_name }}", "body": "Automated release for ${{ github.ref_name }}"}' \
+            -d '{"tag_name": "${{ github.ref_name }}", "name": "API Release ${{ steps.version.outputs.version }}", "body": "Automated release for webber-api ${{ steps.version.outputs.version }}"}' \
             "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/releases"
 
   build:
@@ -23,6 +34,13 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
+      - name: Extract version from tag
+        id: version
+        run: |
+          VERSION="${{ github.ref_name }}"
+          VERSION="${VERSION#api/}"
+          echo "version=$VERSION" >> $GITHUB_OUTPUT
+
       - name: Login to Gitea Registry
         uses: docker/login-action@v3
         with:
@@ -33,11 +51,11 @@ jobs:
       - name: Build and push
         uses: docker/build-push-action@v5
         with:
-          context: .
+          context: ./webber-api
           push: true
           tags: |
-            git.schweitz.internal/jpmschweitzer/webber:latest
-            git.schweitz.internal/jpmschweitzer/webber:${{ github.ref_name }}
+            ${{ env.IMAGE_NAME }}:latest
+            ${{ env.IMAGE_NAME }}:${{ steps.version.outputs.version }}
 
       - name: Trigger Watchtower update
         if: success()

.gitea/workflows/build-cli.yml

@@ -0,0 +1,25 @@
+name: Build and Release CLI
+
+on:
+  push:
+    tags:
+      - 'cli/v*'
+
+# TODO: Implement CLI installer build
+# This workflow will be implemented when CLI distribution is ready.
+# Possible targets:
+# - PyPI package
+# - Standalone binary (PyInstaller)
+# - Platform-specific installers
+
+jobs:
+  placeholder:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Extract version from tag
+        id: version
+        run: |
+          VERSION="${{ github.ref_name }}"
+          VERSION="${VERSION#cli/}"
+          echo "CLI release triggered for version: $VERSION"
+          echo "TODO: Implement CLI build and distribution"

.gitignore

@@ -64,3 +64,14 @@ Thumbs.db
 # Project specific
 *.db
 *.sqlite3
+
+# Monorepo - subproject venvs (explicit for clarity)
+webber-api/.venv/
+webber-cli/.venv/
+webber-sandbox/.venv/
+
+# Sandbox marker file
+webber-sandbox/.current_template
+
+# Ruff cache
+.ruff_cache/

AGENTS.md

@@ -1,116 +1,255 @@
-
-# AGENTS.md
+# Webber Monorepo - Agent Instructions
 
 > **Start every session by reading this file.**
-> This file outlines the operational protocols, coding standards, and architectural decisions for this FastAPI project.
+> This file contains everything you need to work with this codebase efficiently.
 
-## 1. Agent Operational Protocols
+## Quick Reference
 
-### 🧠 Work Patterns (Plan-Act-Reflect)
-* **Plan:** Before writing code, briefly outline your plan. Identify which files you will touch and what the side effects might be.
-* **Act:** Execute the changes in small, atomic steps.
-* **Reflect:** After coding, verify your work. Did you break existing tests? Did you add new tests?
-
-### 🛡️ Git Discipline
-* **ALWAYS add the relevant tests for the added code** Make sure to keep the test coverage up as we go, and run tests before commiting.
-* **NEVER commit to `main` or `master` directly.** Always create a feature branch: `feature/your-feature-name` or `fix/issue-description`.
-* **Commit Messages:** Use the [Conventional Commits](https://www.conventionalcommits.org/) format.
-    * `feat: add user login endpoint`
-    * `fix: resolve database connection timeout`
-    * `refactor: split monolith dependency file`
-* **Atomic Commits:** Keep commits small. One logical change = one commit.
-
-### 📝 Changelog Maintenance
-* **Update `CHANGELOG.md`** with every user-facing change.
-* Format: `## [Unreleased] - YYYY-MM-DD` followed by `### Added`, `### Changed`, or `### Fixed`.
-
-### 🚀 Release Flow
-When changes are ready for deployment:
-
-1. **Ask user if deploy cycle is desired **
-
-2. **Update version** in `pyproject.toml`:
-   - Bug fixes: bump patch version (1.8.3 → 1.8.4)
-   - New features: bump minor version (1.8.4 → 1.9.0)
-
-3. **Update CHANGELOG.md**:
-   - Move items from `[Unreleased]` to new version section
-   - Add release date: `## [1.8.4] - 2025-12-16`
-
-4. **Commit and tag**:
-   ```bash
-   git add -A
-   git commit -m "fix: description of changes"
-   git tag v1.8.4
-   git push origin main --tags
-   ```
-
-5. **CI/CD triggers automatically**:
-   - Gitea CI builds Docker image on new version tag (starts with "v")
-   - Watchtower pulls and deploys to production
-   - Verify deployment: `curl http://192.168.86.149:8086/health`
+| Action | Command |
+|--------|---------|
+| Start API server | `cd webber-api && ./wakeup.sh` |
+| View API logs | `tail -f webber-api/logs/server.log` |
+| Run API tests | `cd webber-api && .venv/bin/python -m pytest tests/ -v` |
+| Check CLI status | `cd webber-cli && .venv/bin/webber-cli status` |
+| Load sandbox | `./sandbox.sh load calculator-cli` |
+| Explore sandbox | `cd webber-cli && .venv/bin/webber-cli explore "query" -d ../webber-sandbox` |
 
 ---
 
-### 🧪 Local Development Setup
+## Repository Structure
 
-* **Always test locally first** before committing and deploying. The build-deploy loop is slow.
-* **Only deploy** when a phase or feature is complete and tested locally
-* **Environment**: Copy `.env.example` to `.env` and configure for your local setup
+```
+webber/
+├── webber-api/          # FastAPI backend server
+│   ├── src/             # API source code
+│   ├── tests/           # API tests (pytest)
+│   ├── docs/            # Architecture docs, COVERAGE.md
+│   ├── logs/            # Runtime logs (server.log)
+│   ├── .venv/           # API virtual environment
+│   ├── wakeup.sh        # Dev server startup script
+│   └── AGENTS.md        # API-specific development guide
+│
+├── webber-cli/          # CLI client
+│   ├── webber_cli/      # Python package (underscore!)
+│   ├── .venv/           # CLI virtual environment
+│   └── README.md        # CLI usage guide
+│
+├── webber-sandbox/      # Active test project (contents swappable)
+│   ├── src/             # Current project source
+│   ├── tests/           # Current project tests
+│   ├── .venv/           # Sandbox virtual environment
+│   └── TASKS.md         # Tasks for Webber to complete
+│
+├── sandbox-templates/   # Template storage
+│   ├── calculator-cli/  # Simple CLI with intentional bugs
+│   └── empty/           # Blank starter project
+│
+├── sandbox.sh           # Sandbox management script
+└── AGENTS.md            # THIS FILE
+```
 
-#### ⚠️ CRITICAL: Starting the Local Server
+---
 
-**ALWAYS use `./wakeup.sh` to start the local server. NEVER use raw uvicorn commands.**
+## Development Workflow
+
+### 1. Start the API Server
 
 ```bash
+cd webber-api
 ./wakeup.sh
 ```
 
-The wakeup script provides:
-- **Port conflict detection** - Warns if port 8086 is already in use
-- **Virtual environment activation** - Ensures correct Python environment
-- **Centralized logging** - All logs written to `logs/server.log` for easy tailing
-- **Auto-reload** - Code changes picked up automatically (except requirements.txt changes)
-- **Consistent configuration** - Same startup every time
+- **Port:** 8095 (dev), 8086 (production Docker)
+- **Logs:** `webber-api/logs/server.log`
+- **Health check:** `curl http://localhost:8095/health`
+- **API docs:** http://localhost:8095/docs
+
+To stop: `Ctrl+C` or `pkill -f "uvicorn src.main:app"`
+
+### 2. Run Tests
 
-To monitor logs in another terminal:
 ```bash
-tail -f logs/server.log
+# API tests (39 tests)
+cd webber-api
+.venv/bin/python -m pytest tests/ -v
+
+# With coverage
+.venv/bin/python -m pytest tests/ --cov=src
+
+# Single test file
+.venv/bin/python -m pytest tests/test_tools.py -v
 ```
 
-To stop the server: Press `Ctrl+C`
+### 3. Use the CLI
 
-To kill a stuck server:
 ```bash
-pkill -f "uvicorn src.main:app"
-# or
-kill $(lsof -t -i:8086)
+cd webber-cli
+
+# Check API connection
+.venv/bin/webber-cli status
+
+# Explore a directory
+.venv/bin/webber-cli explore "find all python files" -d ../webber-sandbox
+
+# Interactive chat mode
+.venv/bin/webber-cli chat -d ../webber-sandbox
 ```
 
-#### Testing
+**Note:** The API server must be running for CLI commands to work.
+
+---
+
+## Sandbox Management
+
+The sandbox is a swappable test project for functional testing.
+
+### Available Templates
+
+| Template | Description |
+|----------|-------------|
+| `calculator-cli` | Python CLI with intentional bugs (div-by-zero, missing tests) |
+| `empty` | Blank starter project |
+
+### Commands
 
-**Test REST endpoints** against `http://localhost:8086`:
 ```bash
-curl http://localhost:8086/health
-curl http://localhost:8086/
-curl http://localhost:8086/docs   # Swagger UI
+# List available templates
+./sandbox.sh list
+
+# Load a template (clears sandbox, preserves .venv)
+./sandbox.sh load calculator-cli
+
+# Reset to last loaded template
+./sandbox.sh reset
+
+# Save current sandbox as new template
+./sandbox.sh save my-template
+
+# Check current status
+./sandbox.sh status
 ```
 
-**Running tests**: Always use the venv explicitly to avoid environment mismatches:
+### After Loading a Template
+
 ```bash
-.venv/bin/python -m pytest tests/           # All tests
-.venv/bin/python -m pytest tests/ -v        # Verbose output
-.venv/bin/python -m pytest tests/ --cov     # With coverage
+cd webber-sandbox
+source .venv/bin/activate  # Create .venv first if missing
+pip install -r requirements.txt
+
+# Read the tasks
+cat TASKS.md
+
+# Run the project's tests
+pytest tests/ -v
 ```
 
 ---
 
-## 2. FastAPI Architecture & Best Practices
-*Reference: [FastAPI Best Practices](https://github.com/zhanymkanov/fastapi-best-practices)*
+## Testing Webber's Capabilities
 
-### 📂 Project Structure (Directory-based, NOT File-type based)
-Do **not** group files by type (e.g., one huge `routers` folder). Group by **domain/module** inside a `src/` directory.
+### Scenario: Find bugs in calculator-cli
 
-**Correct Structure:**
-```text
-to be determined
+```bash
+# 1. Load the template
+./sandbox.sh load calculator-cli
+
+# 2. Have Webber explore it
+cd webber-cli
+.venv/bin/webber-cli explore "find all bugs in the code" -d ../webber-sandbox
+
+# 3. Check TASKS.md for expected bugs
+cat ../webber-sandbox/TASKS.md
+```
+
+### Known bugs in calculator-cli:
+- Division by zero not handled (`operations.py:divide`)
+- Invalid operation causes KeyError (`main.py:get_operation`)
+- Power function broken for fractional exponents
+- Missing tests for divide and power functions
+
+---
+
+## Key Files for Debugging
+
+| File | Purpose |
+|------|---------|
+| `webber-api/logs/server.log` | API server logs |
+| `webber-api/src/domains/agents/explore/prompts.py` | Explore agent system prompts |
+| `webber-api/src/domains/agents/explore/agent.py` | Explore agent implementation |
+| `webber-api/src/ollama/provider.py` | Ollama integration (sanitizes content:null) |
+| `webber-api/docs/COVERAGE.md` | Feature coverage and known issues |
+
+---
+
+## Versioning & Releases
+
+Uses prefixed tags:
+- `api/vX.Y.Z` → Triggers API Docker build
+- `cli/vX.Y.Z` → Triggers CLI build (future)
+
+### MANDATORY Release Procedure
+
+**NEVER push a tag before updating version files.** Follow this exact order:
+
+```bash
+# 1. Update version in pyproject.toml
+# 2. Update CHANGELOG.md with release notes
+# 3. Commit the version bump
+git add -A && git commit -m "chore: release api vX.Y.Z"
+
+# 4. Create the tag (AFTER the commit)
+git tag api/vX.Y.Z
+
+# 5. Push everything together
+git push origin main --tags
+```
+
+**Why this matters:** Pushing a tag before the version commit requires deleting and recreating the tag, which can trigger CI/CD pipelines prematurely and cause deployment issues.
+
+---
+
+## Troubleshooting
+
+### API server won't start
+```bash
+# Check if port is in use
+lsof -i :8095
+
+# Kill stuck process
+pkill -f "uvicorn src.main:app"
+```
+
+### CLI can't connect
+```bash
+# Check API is running
+curl http://localhost:8095/health
+
+# Check CLI config
+echo $WEBBER_API_URL  # Should be http://localhost:8095
+```
+
+### Ollama errors
+```bash
+# Check Ollama is running
+curl http://192.168.86.149:11434/api/tags
+
+# Check model is available
+curl http://192.168.86.149:11434/api/tags | grep mistral-nemo
+```
+
+### Tests failing
+```bash
+# Run with verbose output
+cd webber-api
+.venv/bin/python -m pytest tests/ -v --tb=short
+```
+
+---
+
+## Known Limitations
+
+1. **Model hallucination** - Mistral Nemo sometimes makes up file contents instead of using tool results
+2. **No conversation memory** - CLI chat mode doesn't persist between sessions
+3. **No streaming** - Responses appear all at once
+
+See `webber-api/docs/COVERAGE.md` for full feature coverage status.

CHANGELOG.md

@@ -7,6 +7,72 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.4] - 2026-01-11
+
+### Added
+- Task Agent - Full orchestrator for autonomous multi-step task execution
+  - Has ALL tools: read, write, edit, bash (full), web_search
+  - New `spawn_agent` tool to launch sub-agents (Explore, Plan) for focused work
+  - Recursion prevention: cannot spawn nested Task agents
+  - 22 unit tests for registration, tools, spawn_agent, and API
+- Complete agent hierarchy: Explore (read-only) → Plan (read-only) → Task (orchestrator)
+
+## [0.3.3] - 2026-01-11
+
+### Added
+- Plan Agent - READ-ONLY software architect that designs implementation strategies
+  - Uses only read-only tools: `read_file`, `glob_files`, `grep_content`, `bash_readonly`
+  - Creates step-by-step implementation plans with critical files list
+  - 15 unit tests for registration, tools, and API
+- Web search summarizer added to roadmap (future feature)
+
+### Changed
+- Updated COVERAGE.md to ~70% complete
+
+## [0.3.2] - 2026-01-11
+
+### Added
+- Mandatory release procedure documentation in AGENTS.md
+
+## [0.3.1] - 2026-01-11
+
+### Added
+- Integration test infrastructure with pytest markers (integration, e2e, slow)
+- 10 LLM integration tests (requires Ollama)
+- 12 E2E API tests (requires running server)
+- Command line options: `--run-integration`, `--run-e2e`, `--ollama-url`, `--api-url`
+- Sample project fixtures for testing
+- 14 security tests (path traversal, command injection, input validation)
+- Helper functions: `assert_contains_any`, `assert_contains_all`
+
+### Changed
+- Updated COVERAGE.md to ~65% complete
+
+## [0.3.0] - 2026-01-10
+
+### Added
+- Explore agent with PydanticAI tool calling and Mistral Nemo
+- Coding tools: `edit_file`, `write_file`, `bash` (full)
+- Web search tool using SearXNG integration
+- Streaming responses via SSE for API and CLI
+- CLI commands: `explore`, `chat`, `status`
+- Sanitized Ollama provider (fixes `content: null` issue)
+
+### Changed
+- Reorganized into monorepo structure (webber-api/, webber-cli/, webber-sandbox/)
+- Added ruff linter and fixed mypy errors
+
+## [0.2.3] - 2026-01-09
+
+### Added
+- Docker healthcheck for container health monitoring
+
+## [0.2.2] - 2026-01-09
+
+### Fixed
+- Config parsing for empty environment variables (allowed_paths, cors_*)
+- Use `env_parse_none_str=""` to treat empty strings as None
+
 ## [0.2.1] - 2026-01-09
 
 ### Fixed

README.md

@@ -0,0 +1,100 @@
+# Webber - Multi-Agent AI Development System
+
+A Claude Code-inspired development assistant powered by local LLMs via Ollama.
+
+## Features
+
+- **Explore Agent** - Search, read, and understand codebases
+- **8 Tools** - File read/write, glob, grep, bash, web search
+- **Streaming** - Real-time response display
+- **Self-hosted** - Runs on your own hardware with Ollama
+
+## Structure
+
+This is a monorepo containing three subprojects:
+
+| Directory | Description |
+|-----------|-------------|
+| `webber-api/` | FastAPI backend server with agent orchestration |
+| `webber-cli/` | Command-line client for interacting with the API |
+| `webber-sandbox/` | Test project for functional testing |
+
+### Additional Directories
+
+| Directory | Description |
+|-----------|-------------|
+| `sandbox-templates/` | Reusable project templates for the sandbox |
+| `.gitea/workflows/` | CI/CD workflows for releases |
+
+## Quick Start
+
+### 1. Start the API Server
+
+```bash
+cd webber-api
+python3.12 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt -r requirements-dev.txt
+./wakeup.sh
+```
+
+### 2. Set Up the CLI
+
+```bash
+cd webber-cli
+python3.12 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+pip install -e .
+
+# Test connection
+webber-cli status
+```
+
+### 3. Explore with Webber
+
+```bash
+# One-shot exploration
+webber-cli explore "find all bugs in the code" -d /path/to/project
+
+# Interactive chat
+webber-cli chat -d /path/to/project
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `read_file` | Read file contents with line numbers |
+| `glob_files` | Find files by pattern |
+| `grep_content` | Search file contents with regex |
+| `bash_readonly` | Safe bash commands (ls, git status, etc.) |
+| `edit_file` | Find-and-replace editing |
+| `write_file` | Create/overwrite files |
+| `bash` | Full bash with safety controls |
+| `web_search` | Search web via SearXNG |
+
+## Versioning
+
+This project uses prefixed tags for independent release cycles:
+
+- `api/v0.3.0` - Triggers API Docker build and deployment
+- `cli/v0.1.0` - Triggers CLI installer build (future)
+
+## Requirements
+
+- Python 3.12+
+- Ollama running with `mistral-nemo:latest` model
+- Docker (for production deployment)
+- SearXNG (optional, for web search)
+
+## Documentation
+
+- `webber-api/AGENTS.md` - API development guidelines
+- `webber-api/docs/COVERAGE.md` - Feature coverage and roadmap
+- `webber-api/docs/architecture.md` - System architecture
+- `webber-cli/README.md` - CLI usage guide
+
+## License
+
+MIT

implementation-plan.md

@@ -1,628 +0,0 @@
-# Webber FastAPI Boilerplate Plan
-
-## Overview
-Set up FastAPI boilerplate for "Webber" - a multi-agent AI development system (similar to Claude Code, but local with different models). Follows core-api patterns with defensive coding practices.
-
-**Key Decision: PydanticAI Framework**
-After research, [PydanticAI](https://ai.pydantic.dev/) is the recommended agent coordination framework:
-- Model-agnostic: supports Ollama, OpenAI, Anthropic, and 20+ providers
-- Type-safe with Pydantic validation (same ecosystem as FastAPI)
-- Built-in tool/function calling with automatic schema generation
-- Multi-agent support for complex workflows
-- Maintained by Pydantic team (285M+ monthly downloads)
-
-**Port: 8086** (next available slot after Headscale 8085 per CONTAINERS.md)
-
-**Default Models (always hot in VRAM on tower-of-joy):**
-- Agent reasoning: `mistral-nemo-large:latest`
-- Embeddings: `nomic-embed-text:latest`
-
-**Target Clients:**
-- **Tatlock Butler**: External advisor integration for coding/software guidance
-- **CLI Interface**: TBD - command-line interface for local development
-
-**Multi-tenancy:** API key authentication integrated with tatlock-ui/core-api user management
-
----
-
-## 1. Directory Structure
-
-```
-webber/
-├── AGENTS.md                    # Expanded with defensive LLM guidelines
-├── README.md                    # Project overview
-├── CHANGELOG.md                 # Version history
-├── pyproject.toml               # Package metadata
-├── requirements.txt             # Production dependencies only (~= pinned)
-├── requirements-dev.txt         # Dev/test dependencies (pytest, pip-audit, etc.)
-├── .env.example                 # Environment template
-├── wakeup.sh                    # Dev startup (update port to 8086)
-│
-├── src/
-│   ├── __init__.py
-│   ├── main.py                  # FastAPI app, lifespan, user provider init
-│   │                            # NO routes here - delegates to domain routers
-│   │
-│   ├── shared/                  # Cross-cutting concerns
-│   │   ├── __init__.py
-│   │   ├── base.py              # BaseController, BaseSchema
-│   │   ├── config.py            # Pydantic BaseSettings
-│   │   ├── logging.py           # Logger decorator + centralized setup
-│   │   ├── exceptions.py        # Custom exception hierarchy
-│   │   ├── auth.py              # API key validation, multi-tenant support
-│   │   └── context.py           # UserProvider singleton, request context
-│   │
-│   └── domains/                 # Feature domains (each with router.py)
-│       ├── __init__.py
-│       ├── router.py            # Root router - includes all domain routers
-│       │
-│       ├── health/              # Health endpoints
-│       │   ├── __init__.py
-│       │   ├── router.py        # Health routes
-│       │   └── controller.py    # Health logic
-│       │
-│       ├── auth/                # Authentication domain
-│       │   ├── __init__.py
-│       │   ├── router.py        # Auth routes (API key mgmt)
-│       │   ├── controller.py
-│       │   └── schemas.py
-│       │
-│       │── agents/              # Agent domain container
-│       │   ├── __init__.py
-│       │   ├── router.py        # Agent routes (lists agents, runs them)
-│       │   ├── controller.py    # Agent orchestration logic
-│       │   ├── schemas.py
-│       │   │
-│       │   ├── explore/         # Explore agent (codebase navigation)
-│       │   │   ├── __init__.py
-│       │   │   ├── agent.py     # PydanticAI agent definition
-│       │   │   └── prompts.py   # System prompts
-│       │   │
-│       │   ├── plan/            # Plan agent (implementation design)
-│       │   │   ├── __init__.py
-│       │   │   ├── agent.py
-│       │   │   └── prompts.py
-│       │   │
-│       │   └── task/            # Task agent (execution)
-│       │       ├── __init__.py
-│       │       ├── agent.py
-│       │       └── prompts.py
-│       │
-│       └── tools/               # Tool domain container
-│           ├── __init__.py
-│           ├── router.py        # Tool routes (list tools, execute)
-│           ├── controller.py    # Tool orchestration
-│           ├── schemas.py
-│           │
-│           ├── file/            # File operation tools
-│           │   ├── __init__.py
-│           │   ├── read.py
-│           │   ├── write.py
-│           │   └── glob.py
-│           │
-│           ├── shell/           # Shell execution tools
-│           │   ├── __init__.py
-│           │   └── bash.py
-│           │
-│           └── search/          # Search tools
-│               ├── __init__.py
-│               ├── grep.py
-│               └── web.py
-│
-├── tests/
-│   ├── __init__.py
-│   ├── conftest.py
-│   └── test_health.py
-│
-└── docs/
-    └── architecture.md
-```
-
-### Key Architectural Decisions
-
-1. **Clean main.py**: Only app creation, lifespan, and UserProvider init. All routes in domain routers.
-2. **Domain routers**: Each domain has `router.py` that defines routes. Root `domains/router.py` composes them.
-3. **Separate agent domains**: Each agent type (explore, plan, task) in its own subdir under `agents/`.
-4. **Separate tool domains**: Each tool category (file, shell, search) in its own subdir under `tools/`.
-5. **UserProvider singleton**: Set once in main.py lifespan, accessible everywhere via `shared/context.py`.
-6. **Multi-tenant auth**: API key validation in `shared/auth.py`, integrates with tatlock-ui/core-api.
-
----
-
-## 2. Key Files to Create
-
-### Phase 1: Foundation (fully implemented)
-| File | Purpose |
-|------|---------|
-| `src/shared/base.py` | BaseController, BaseSchema |
-| `src/shared/config.py` | Settings via Pydantic BaseSettings |
-| `src/shared/logging.py` | Logger decorator + centralized setup |
-| `src/shared/exceptions.py` | Custom exception hierarchy |
-| `src/shared/auth.py` | API key validation, tatlock integration stub |
-| `src/shared/context.py` | UserProvider singleton pattern |
-| `src/main.py` | FastAPI app, lifespan, UserProvider init (no routes!) |
-| `src/domains/router.py` | Root router composing all domain routers |
-| `src/domains/health/router.py` | Health routes |
-| `src/domains/health/controller.py` | Health logic |
-| `pyproject.toml` | Package metadata, pytest config |
-| `requirements.txt` | Production deps (~= pinned) |
-| `requirements-dev.txt` | Dev/test deps (pytest, pip-audit) |
-| `.env.example` | Environment variable template |
-| `tests/conftest.py` | Pytest fixtures |
-| `tests/test_health.py` | Basic endpoint tests |
-
-### Phase 2: Placeholders (structure + README docs)
-| Directory | Purpose |
-|-----------|---------|
-| `src/domains/auth/` | API key management (stub) |
-| `src/domains/agents/` | Agent container with explore/plan/task subdirs |
-| `src/domains/tools/` | Tool container with file/shell/search subdirs |
-| `docs/architecture.md` | System design documentation |
-
----
-
-## 3. Dependency Management
-
-### requirements.txt (Production - baked into Docker)
-```
-# Webber Production Dependencies
-# Minor version pinning (~=) for security patches
-# CVE check date: 2026-01-09
-# CVE check sources: PyPI, GitHub Advisories, Snyk, NVD
-
-# Core FastAPI
-fastapi~=0.115.0
-starlette~=0.45.0
-uvicorn[standard]~=0.34.0
-pydantic~=2.11.0
-pydantic-settings~=2.7.0
-
-# Agent Framework
-pydantic-ai~=0.0.39            # Multi-agent LLM orchestration
-
-# HTTP
-httpx~=0.28.0
-aiofiles~=24.1.0
-
-# Utilities
-python-multipart~=0.0.18
-python-dotenv~=1.0.0
-```
-
-### requirements-dev.txt (Dev/Test only - NOT in Docker)
-```
-# Webber Development Dependencies
-# Install with: pip install -r requirements-dev.txt
-
--r requirements.txt            # Include production deps
-
-# Testing
-pytest~=8.3.0
-pytest-asyncio~=0.24.0
-pytest-cov~=6.0.0
-
-# Security auditing
-pip-audit~=2.7.0               # Run before releases: pip-audit
-
-# Type checking
-mypy~=1.13.0
-
-# Code formatting (optional)
-# ruff~=0.8.0
-```
-
----
-
-## 4. AGENTS.md Additions
-
-Add these new sections:
-
-### Section 3: Defensive LLM Coding Practices
-- Input validation requirements
-- Output parsing guidelines (expect malformed responses)
-- Timeout and retry policies
-- Security: no secrets in prompts, sandbox execution
-
-### Section 4: Pattern Reuse Requirements
-- Search existing code before writing new
-- Check `src/shared/` for base classes
-- Follow domain structure template
-- Code review checklist
-
-### Section 5: CVE Check Process
-- Check PyPI, GitHub Advisories, Snyk, NVD before adding deps
-- Document CVE decisions in requirements.txt
-- Run `pip-audit` before releases
-
-### Section 6: Mandatory Documentation
-- Required reading before work: AGENTS.md, docs/architecture.md, src/shared/base.py
-- Changelog and docstring requirements
-
-### Section 7: Project Structure Reference
-- Directory tree with explanations
-- Domain structure template
-
----
-
-## 5. Configuration (Settings)
-
-Environment variables for:
-- **App**: DEBUG, LOG_LEVEL
-- **Server**: HOST, PORT (default **8086** per CONTAINERS.md allocation)
-- **CORS**: origins, methods, headers
-- **LLM Models** (hot in VRAM on tower-of-joy):
-  - OLLAMA_URL (default: http://192.168.86.149:11434)
-  - OLLAMA_AGENT_MODEL (default: mistral-nemo-large:latest)
-  - OLLAMA_EMBED_MODEL (default: nomic-embed-text:latest)
-- **Auth**:
-  - TATLOCK_API_URL (default: http://192.168.86.149:8000)
-  - Internal API key for tatlock user validation
-- **Tools**: TOOL_TIMEOUT_SECONDS, SANDBOX_ENABLED, ALLOWED_PATHS
-- **Sessions**: SESSION_TTL_HOURS, MAX_CONTEXT_TOKENS
-
----
-
-## 6. Core Patterns
-
-### Logger Decorator with Temporal Benchmarking (shared/logging.py)
-```python
-import functools
-import asyncio
-import time
-import logging
-from typing import Callable, Optional
-from contextvars import ContextVar
-from dataclasses import dataclass, field
-from uuid import uuid4
-
-# Trace context for nested timing
-@dataclass
-class TraceSpan:
-    name: str
-    trace_id: str
-    parent_id: Optional[str] = None
-    span_id: str = field(default_factory=lambda: uuid4().hex[:8])
-    start_time: float = field(default_factory=time.perf_counter)
-    end_time: Optional[float] = None
-
-    @property
-    def duration_ms(self) -> float:
-        if self.end_time is None:
-            return (time.perf_counter() - self.start_time) * 1000
-        return (self.end_time - self.start_time) * 1000
-
-# Context variable for trace propagation
-_current_span: ContextVar[Optional[TraceSpan]] = ContextVar('current_span', default=None)
-_trace_id: ContextVar[Optional[str]] = ContextVar('trace_id', default=None)
-
-def get_current_trace_id() -> Optional[str]:
-    """Get current trace ID for correlation."""
-    return _trace_id.get()
-
-def logged(
-    logger: logging.Logger = None,
-    slow_threshold_ms: float = 100.0,
-    warn_threshold_ms: float = 500.0,
-    include_args: bool = False,
-):
-    """
-    Decorator for automatic function logging with temporal benchmarking.
-
-    Args:
-        logger: Logger instance (defaults to module logger)
-        slow_threshold_ms: Log INFO if execution exceeds this (default 100ms)
-        warn_threshold_ms: Log WARNING if execution exceeds this (default 500ms)
-        include_args: Include function arguments in log (careful with sensitive data)
-
-    Usage:
-        @logged()
-        async def my_function(): ...
-
-        @logged(slow_threshold_ms=50, warn_threshold_ms=200)
-        def critical_path(): ...
-    """
-    def decorator(func: Callable):
-        nonlocal logger
-        if logger is None:
-            logger = logging.getLogger(func.__module__)
-
-        func_name = f"{func.__module__}.{func.__qualname__}"
-
-        def _create_span() -> TraceSpan:
-            parent = _current_span.get()
-            trace_id = _trace_id.get() or uuid4().hex[:16]
-            if _trace_id.get() is None:
-                _trace_id.set(trace_id)
-            return TraceSpan(
-                name=func_name,
-                trace_id=trace_id,
-                parent_id=parent.span_id if parent else None,
-            )
-
-        def _log_completion(span: TraceSpan, error: Exception = None):
-            span.end_time = time.perf_counter()
-            duration = span.duration_ms
-
-            # Build log context
-            ctx = {
-                "trace_id": span.trace_id,
-                "span_id": span.span_id,
-                "duration_ms": round(duration, 2),
-                "func": func_name,
-            }
-            if span.parent_id:
-                ctx["parent_id"] = span.parent_id
-
-            if error:
-                logger.error(
-                    f"[{span.trace_id[:8]}] {func_name} FAILED after {duration:.2f}ms: {error}",
-                    extra=ctx,
-                    exc_info=True
-                )
-            elif duration >= warn_threshold_ms:
-                logger.warning(
-                    f"[{span.trace_id[:8]}] {func_name} SLOW: {duration:.2f}ms (threshold: {warn_threshold_ms}ms)",
-                    extra=ctx
-                )
-            elif duration >= slow_threshold_ms:
-                logger.info(
-                    f"[{span.trace_id[:8]}] {func_name} completed in {duration:.2f}ms",
-                    extra=ctx
-                )
-            else:
-                logger.debug(
-                    f"[{span.trace_id[:8]}] {func_name} completed in {duration:.2f}ms",
-                    extra=ctx
-                )
-
-        @functools.wraps(func)
-        async def async_wrapper(*args, **kwargs):
-            span = _create_span()
-            token = _current_span.set(span)
-
-            if include_args:
-                logger.debug(f"[{span.trace_id[:8]}] -> {func_name}({args}, {kwargs})")
-            else:
-                logger.debug(f"[{span.trace_id[:8]}] -> {func_name}")
-
-            try:
-                result = await func(*args, **kwargs)
-                _log_completion(span)
-                return result
-            except Exception as e:
-                _log_completion(span, error=e)
-                raise
-            finally:
-                _current_span.reset(token)
-
-        @functools.wraps(func)
-        def sync_wrapper(*args, **kwargs):
-            span = _create_span()
-            token = _current_span.set(span)
-
-            if include_args:
-                logger.debug(f"[{span.trace_id[:8]}] -> {func_name}({args}, {kwargs})")
-            else:
-                logger.debug(f"[{span.trace_id[:8]}] -> {func_name}")
-
-            try:
-                result = func(*args, **kwargs)
-                _log_completion(span)
-                return result
-            except Exception as e:
-                _log_completion(span, error=e)
-                raise
-            finally:
-                _current_span.reset(token)
-
-        return async_wrapper if asyncio.iscoroutinefunction(func) else sync_wrapper
-    return decorator
-
-
-# Convenience for manual span creation (context manager)
-class trace_span:
-    """
-    Context manager for manual span creation.
-
-    Usage:
-        with trace_span("database_query"):
-            result = await db.execute(query)
-
-        async with trace_span("llm_call"):
-            response = await agent.run(prompt)
-    """
-    def __init__(self, name: str, logger: logging.Logger = None):
-        self.name = name
-        self.logger = logger or logging.getLogger(__name__)
-        self.span: Optional[TraceSpan] = None
-        self.token = None
-
-    def __enter__(self):
-        parent = _current_span.get()
-        trace_id = _trace_id.get() or uuid4().hex[:16]
-        if _trace_id.get() is None:
-            _trace_id.set(trace_id)
-
-        self.span = TraceSpan(
-            name=self.name,
-            trace_id=trace_id,
-            parent_id=parent.span_id if parent else None,
-        )
-        self.token = _current_span.set(self.span)
-        self.logger.debug(f"[{self.span.trace_id[:8]}] -> {self.name}")
-        return self.span
-
-    def __exit__(self, exc_type, exc_val, exc_tb):
-        if self.span:
-            self.span.end_time = time.perf_counter()
-            duration = self.span.duration_ms
-            if exc_val:
-                self.logger.error(f"[{self.span.trace_id[:8]}] {self.name} FAILED: {duration:.2f}ms")
-            else:
-                self.logger.debug(f"[{self.span.trace_id[:8]}] {self.name}: {duration:.2f}ms")
-        if self.token:
-            _current_span.reset(self.token)
-        return False
-
-    async def __aenter__(self):
-        return self.__enter__()
-
-    async def __aexit__(self, exc_type, exc_val, exc_tb):
-        return self.__exit__(exc_type, exc_val, exc_tb)
-```
-
-**Example output:**
-```
-DEBUG [a1b2c3d4] -> src.domains.agents.controller.run_agent
-DEBUG [a1b2c3d4] -> src.domains.llm.service.call_ollama
-DEBUG [a1b2c3d4] src.domains.llm.service.call_ollama: 45.23ms
-INFO  [a1b2c3d4] src.domains.agents.controller.run_agent completed in 156.78ms
-WARN  [a1b2c3d4] src.domains.tools.file.read.read_file SLOW: 523.45ms (threshold: 500ms)
-```
-
-**Features:**
-- **Trace IDs**: Correlate logs across nested calls
-- **Parent/child spans**: Track call hierarchy
-- **Configurable thresholds**: `slow_threshold_ms` (INFO), `warn_threshold_ms` (WARNING)
-- **Context manager**: `trace_span()` for manual instrumentation of code blocks
-- **Zero overhead path**: Fast path for sub-threshold calls (DEBUG only)
-
-### UserProvider Singleton (shared/context.py)
-```python
-from dataclasses import dataclass
-from typing import Optional
-from contextvars import ContextVar
-
-@dataclass
-class User:
-    id: str
-    email: str
-    api_key: str
-    tenant_id: Optional[str] = None
-
-# Context variable for request-scoped user
-_current_user: ContextVar[Optional[User]] = ContextVar('current_user', default=None)
-
-class UserProvider:
-    """Singleton for user context management."""
-    _instance = None
-
-    def __new__(cls):
-        if cls._instance is None:
-            cls._instance = super().__new__(cls)
-        return cls._instance
-
-    def set_user(self, user: User) -> None:
-        _current_user.set(user)
-
-    def get_user(self) -> Optional[User]:
-        return _current_user.get()
-
-    def clear_user(self) -> None:
-        _current_user.set(None)
-
-# Global singleton
-user_provider = UserProvider()
-```
-
-### BaseController (from core-api)
-```python
-class BaseController(ABC):
-    def __init__(self, prefix: str, tags: list[str]):
-        self.prefix = prefix
-        self.tags = tags
-        self._router = None
-
-    @abstractmethod
-    def create_router(self) -> APIRouter: pass
-
-    @property
-    def router(self) -> APIRouter:
-        if self._router is None:
-            self._router = self.create_router()
-        return self._router
-```
-
-### PydanticAI Agent Pattern (placeholder for future)
-```python
-from pydantic_ai import Agent
-from pydantic_ai.models.ollama import OllamaModel
-
-# Use the hot model from VRAM
-agent = Agent(
-    OllamaModel('mistral-nemo-large:latest'),
-    system_prompt='You are a helpful assistant.',
-)
-
-@agent.tool
-async def search_files(ctx, pattern: str) -> str:
-    """Search for files matching pattern."""
-    pass  # Implementation in tools/search/
-```
-
----
-
-## 7. Implementation Order
-
-1. **Create directory structure** (`src/`, `src/shared/`, `src/domains/`)
-2. **Implement shared modules** (base.py, config.py, logging.py, exceptions.py)
-3. **Create main.py** with FastAPI app and lifespan
-4. **Add health domain** as working example
-5. **Set up tests** (conftest.py, test_health.py)
-6. **Create placeholder domains** (llm, agents, tools - structure only)
-7. **Update AGENTS.md** with new sections
-8. **Create supporting files** (pyproject.toml, requirements.txt, .env.example)
-9. **Add docs/architecture.md**
-
----
-
-## 8. Verification
-
-After implementation:
-1. `./wakeup.sh` starts server without errors
-2. `curl http://localhost:8086/health` returns healthy
-3. `http://localhost:8086/docs` shows API documentation
-4. `.venv/bin/python -m pytest tests/ -v` passes
-5. Code follows patterns in AGENTS.md
-
----
-
-## 9. Critical Reference Files
-
-- `/mnt/media/Projects/core-api/src/shared/base.py` - BaseController pattern
-- `/mnt/media/Projects/core-api/src/shared/config.py` - Settings pattern
-- `/mnt/media/Projects/core-api/src/domains/health/controller.py` - Controller example
-- https://ai.pydantic.dev/ - PydanticAI documentation
-
----
-
-## Summary
-
-**What will be created:**
-- Complete FastAPI project structure following core-api patterns
-- Working health endpoint at `http://localhost:8086/health`
-- **Clean main.py** - no routes, just app init and UserProvider setup
-- **Domain routers** - each domain has router.py, composed by root router
-- **Logger decorator** - centralized logging via `@logged` decorator
-- **UserProvider singleton** - request-scoped user context, no parameter passing
-- **Multi-tenant auth stub** - API key validation ready for tatlock integration
-- Separate **requirements.txt** (prod) and **requirements-dev.txt** (dev/test)
-- Placeholder domains with agent/tool subdirectories (explore, plan, task / file, shell, search)
-- Comprehensive AGENTS.md with defensive LLM coding practices, CVE checks, pattern reuse
-- Test infrastructure with pytest
-- docs/architecture.md explaining the system design
-
-**What will NOT be created (deferred):**
-- Database layer (add when needed)
-- Full agent/tool implementations (PydanticAI patterns documented for future work)
-- Docker/deployment configuration (can add later)
-- CLI interface (TBD)
-
-**Key decisions:**
-- Port: **8086**
-- Agent framework: **PydanticAI**
-- Default model: **mistral-nemo-large:latest** (hot in VRAM)
-- Embeddings: **nomic-embed-text:latest** (hot in VRAM)
-- No database initially
-- Separate prod/dev requirements
-- UserProvider singleton pattern for multi-tenancy

pyproject.toml

@@ -1,37 +0,0 @@
-[project]
-name = "webber"
-version = "0.2.1"
-description = "Mrs. Webber - Multi-Agent AI Development System"
-authors = [
-    {name = "jpmschweitzer"}
-]
-readme = "README.md"
-requires-python = ">=3.12"
-license = {text = "MIT"}
-classifiers = [
-    "Development Status :: 3 - Alpha",
-    "Framework :: FastAPI",
-    "Programming Language :: Python :: 3.12",
-    "Topic :: Software Development :: Code Generators",
-]
-
-[build-system]
-requires = ["setuptools>=75.0", "wheel"]
-build-backend = "setuptools.build_meta"
-
-[tool.setuptools.packages.find]
-where = ["."]
-include = ["src*"]
-
-[tool.pytest.ini_options]
-testpaths = ["tests"]
-python_files = ["test_*.py"]
-python_functions = ["test_*"]
-addopts = "-v"
-
-[tool.mypy]
-python_version = "3.12"
-warn_return_any = true
-warn_unused_ignores = true
-strict = false
-ignore_missing_imports = true

sandbox-templates/calculator-cli/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+
+# Virtual environments
+.venv/
+venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Project
+.current_template

sandbox-templates/calculator-cli/TASKS.md

@@ -0,0 +1,64 @@
+# Calculator CLI - Tasks for Webber
+
+A simple calculator with intentional bugs and missing features for testing Webber's capabilities.
+
+## Bugs to Fix
+
+### High Priority
+- [ ] **Division by zero** - `operations.py:divide()` crashes when dividing by zero instead of returning an error
+- [ ] **Invalid operation name** - `main.py:get_operation()` raises KeyError for unknown operations instead of helpful error message
+
+### Medium Priority
+- [ ] **Power function broken** - `operations.py:power()` doesn't handle negative exponents or fractional exponents correctly
+- [ ] **No input validation** - `main.py` doesn't validate that command-line arguments are valid numbers
+
+## Missing Tests
+
+- [ ] Add `TestDivide` class with tests for:
+  - Normal division
+  - Division by zero (should test error handling once bug is fixed)
+  - Division with negative numbers
+
+- [ ] Add `TestPower` class with tests for:
+  - Positive integer exponents
+  - Zero exponent (should return 1)
+  - Negative exponents
+
+- [ ] Complete existing test classes:
+  - `test_add_zero`
+  - `test_add_floats`
+  - `test_subtract_negative`
+  - `test_multiply_by_zero`
+
+## Features to Add
+
+- [ ] **Expose power operation** - Add 'pow' to the operations dictionary in `main.py`
+- [ ] **Add modulo operation** - Implement `modulo(a, b)` in operations.py
+- [ ] **Add --verbose flag** - Show step-by-step calculation
+- [ ] **Add history command** - Track and display recent calculations
+- [ ] **Add REPL mode** - Interactive calculator loop
+
+## Code Quality
+
+- [ ] Add type hints to all functions
+- [ ] Add docstrings following Google style
+- [ ] Fix any linting errors (run `ruff check src/`)
+
+## How to Run
+
+```bash
+# Setup
+python3.12 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+
+# Run calculator
+python -m calculator.main 10 5 add
+python -m calculator.main 10 5 div
+
+# Run tests
+pytest tests/ -v
+
+# See failing tests (division by zero)
+python -m calculator.main 10 0 div
+```

sandbox-templates/calculator-cli/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "calculator"
+version = "0.1.0"
+description = "A simple calculator CLI with some bugs"
+requires-python = ">=3.12"
+
+[build-system]
+requires = ["setuptools>=75.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-v"

sandbox-templates/calculator-cli/requirements.txt

@@ -0,0 +1,2 @@
+# Calculator CLI dependencies
+pytest>=8.0.0

sandbox-templates/calculator-cli/src/calculator/__init__.py

@@ -0,0 +1,3 @@
+"""Calculator CLI - A simple calculator with some bugs for testing."""
+
+__version__ = "0.1.0"

sandbox-templates/calculator-cli/src/calculator/main.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+"""
+Calculator CLI - A simple command-line calculator.
+
+NOTE: This file contains intentional bugs for testing purposes.
+
+Usage:
+    python -m calculator.main 10 5 add
+    python -m calculator.main 10 5 sub
+    python -m calculator.main 10 5 mul
+    python -m calculator.main 10 5 div
+"""
+import sys
+
+from calculator.operations import add, subtract, multiply, divide
+
+
+def get_operation(op_name: str):
+    """
+    Get the operation function by name.
+
+    BUG: No validation - invalid operation names cause KeyError!
+    """
+    operations = {
+        "add": add,
+        "sub": subtract,
+        "mul": multiply,
+        "div": divide,
+        # BUG: 'power' is implemented in operations.py but not exposed here
+    }
+    # BUG: Should handle KeyError gracefully
+    return operations[op_name]
+
+
+def main():
+    """Main entry point."""
+    if len(sys.argv) != 4:
+        print("Usage: python -m calculator.main <a> <b> <operation>")
+        print("Operations: add, sub, mul, div")
+        sys.exit(1)
+
+    # BUG: No validation that a and b are valid numbers
+    a = float(sys.argv[1])
+    b = float(sys.argv[2])
+    op_name = sys.argv[3]
+
+    # BUG: This will crash with KeyError for invalid operation
+    operation = get_operation(op_name)
+    result = operation(a, b)
+
+    print(f"Result: {result}")
+
+
+if __name__ == "__main__":
+    main()

sandbox-templates/calculator-cli/src/calculator/operations.py

@@ -0,0 +1,43 @@
+"""
+Math operations for the calculator.
+
+NOTE: This file contains intentional bugs for testing purposes.
+"""
+
+
+def add(a: float, b: float) -> float:
+    """Add two numbers."""
+    return a + b
+
+
+def subtract(a: float, b: float) -> float:
+    """Subtract b from a."""
+    return a - b
+
+
+def multiply(a: float, b: float) -> float:
+    """Multiply two numbers."""
+    return a * b
+
+
+def divide(a: float, b: float) -> float:
+    """
+    Divide a by b.
+
+    BUG: Does not handle division by zero!
+    """
+    # BUG: No check for b == 0
+    return a / b
+
+
+def power(a: float, b: float) -> float:
+    """
+    Raise a to the power of b.
+
+    BUG: Negative exponents not handled correctly for some cases.
+    """
+    # BUG: This naive implementation has issues with negative bases and fractional exponents
+    result = 1
+    for _ in range(int(b)):
+        result *= a
+    return result

sandbox-templates/calculator-cli/tests/__init__.py

@@ -0,0 +1 @@
+"""Calculator tests."""

sandbox-templates/calculator-cli/tests/test_operations.py

@@ -0,0 +1,46 @@
+"""
+Tests for calculator operations.
+
+NOTE: Test coverage is intentionally incomplete for testing purposes.
+"""
+import pytest
+
+from calculator.operations import add, subtract, multiply
+
+
+class TestAdd:
+    """Tests for add operation."""
+
+    def test_add_positive_numbers(self):
+        assert add(2, 3) == 5
+
+    def test_add_negative_numbers(self):
+        assert add(-2, -3) == -5
+
+    # MISSING: test_add_zero, test_add_floats
+
+
+class TestSubtract:
+    """Tests for subtract operation."""
+
+    def test_subtract_positive(self):
+        assert subtract(5, 3) == 2
+
+    # MISSING: test_subtract_negative, test_subtract_resulting_negative
+
+
+class TestMultiply:
+    """Tests for multiply operation."""
+
+    def test_multiply_positive(self):
+        assert multiply(3, 4) == 12
+
+    # MISSING: test_multiply_by_zero, test_multiply_negative
+
+
+# MISSING: TestDivide class entirely!
+# - test_divide_positive
+# - test_divide_by_zero (should test error handling)
+# - test_divide_negative
+
+# MISSING: TestPower class entirely!

sandbox-templates/empty/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+
+# Virtual environments
+.venv/
+venv/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# Project
+.current_template

sandbox-templates/empty/TASKS.md

@@ -0,0 +1,18 @@
+# My Project - Tasks
+
+A blank starter template. Define your own tasks here.
+
+## Setup
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+## Tasks
+
+- [ ] Define your project goals
+- [ ] Add source files to `src/myproject/`
+- [ ] Add tests to `tests/`
+- [ ] Update `requirements.txt` with dependencies

sandbox-templates/empty/pyproject.toml

@@ -0,0 +1,17 @@
+[project]
+name = "myproject"
+version = "0.1.0"
+description = "A blank starter project"
+requires-python = ">=3.12"
+
+[build-system]
+requires = ["setuptools>=75.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = "-v"

sandbox-templates/empty/requirements.txt

@@ -0,0 +1,2 @@
+# Add your dependencies here
+pytest>=8.0.0

sandbox-templates/empty/src/myproject/__init__.py

@@ -0,0 +1,3 @@
+"""My Project - A blank starter template."""
+
+__version__ = "0.1.0"

sandbox-templates/empty/tests/__init__.py

@@ -0,0 +1 @@
+"""Tests for myproject."""

sandbox.sh

@@ -0,0 +1,193 @@
+#!/bin/bash
+# Sandbox management script for Webber testing
+#
+# Usage:
+#   ./sandbox.sh list              - List available templates
+#   ./sandbox.sh load <template>   - Load a template into sandbox
+#   ./sandbox.sh reset             - Reset sandbox to last loaded template
+#   ./sandbox.sh save <name>       - Save current sandbox as new template
+#   ./sandbox.sh status            - Show current sandbox status
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SANDBOX_DIR="$SCRIPT_DIR/webber-sandbox"
+TEMPLATES_DIR="$SCRIPT_DIR/sandbox-templates"
+MARKER_FILE="$SANDBOX_DIR/.current_template"
+
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+usage() {
+    echo "Webber Sandbox Manager"
+    echo ""
+    echo "Usage: ./sandbox.sh <command> [template]"
+    echo ""
+    echo "Commands:"
+    echo "  list              List available templates"
+    echo "  load <template>   Load a template into sandbox (preserves .venv)"
+    echo "  reset             Reset sandbox to last loaded template"
+    echo "  save <name>       Save current sandbox as new template"
+    echo "  status            Show current sandbox status"
+    echo ""
+    echo "Available templates:"
+    ls -1 "$TEMPLATES_DIR" 2>/dev/null || echo "  (none)"
+}
+
+list_templates() {
+    echo "Available templates:"
+    echo ""
+    for dir in "$TEMPLATES_DIR"/*/; do
+        if [ -d "$dir" ]; then
+            name=$(basename "$dir")
+            desc=""
+            if [ -f "$dir/TASKS.md" ]; then
+                desc=$(head -1 "$dir/TASKS.md" | sed 's/^#\s*//')
+            fi
+            printf "  %-20s %s\n" "$name" "$desc"
+        fi
+    done
+}
+
+load_template() {
+    local template="$1"
+
+    if [ -z "$template" ]; then
+        echo -e "${RED}Error: Template name required${NC}"
+        echo "Usage: ./sandbox.sh load <template>"
+        exit 1
+    fi
+
+    if [ ! -d "$TEMPLATES_DIR/$template" ]; then
+        echo -e "${RED}Error: Template '$template' not found${NC}"
+        echo "Available templates:"
+        ls -1 "$TEMPLATES_DIR"
+        exit 1
+    fi
+
+    echo -e "${YELLOW}Loading template: $template${NC}"
+
+    # Create sandbox dir if needed
+    mkdir -p "$SANDBOX_DIR"
+
+    # Clear sandbox contents (except .venv and .git)
+    find "$SANDBOX_DIR" -mindepth 1 -maxdepth 1 ! -name '.venv' ! -name '.git' -exec rm -rf {} +
+
+    # Copy template contents (including hidden files)
+    cp -r "$TEMPLATES_DIR/$template/." "$SANDBOX_DIR/"
+
+    # Mark which template was loaded
+    echo "$template" > "$MARKER_FILE"
+
+    echo -e "${GREEN}Loaded template: $template${NC}"
+    echo ""
+    echo "Next steps:"
+    echo "  cd webber-sandbox"
+    if [ ! -d "$SANDBOX_DIR/.venv" ]; then
+        echo "  python3.12 -m venv .venv"
+    fi
+    echo "  source .venv/bin/activate"
+    echo "  pip install -r requirements.txt"
+    echo ""
+    if [ -f "$SANDBOX_DIR/TASKS.md" ]; then
+        echo "Tasks available in TASKS.md"
+    fi
+}
+
+reset_template() {
+    if [ ! -f "$MARKER_FILE" ]; then
+        echo -e "${RED}Error: No template loaded yet${NC}"
+        echo "Use './sandbox.sh load <template>' first"
+        exit 1
+    fi
+
+    local template=$(cat "$MARKER_FILE")
+    echo "Resetting to template: $template"
+    load_template "$template"
+}
+
+save_template() {
+    local name="$1"
+
+    if [ -z "$name" ]; then
+        echo -e "${RED}Error: Template name required${NC}"
+        echo "Usage: ./sandbox.sh save <name>"
+        exit 1
+    fi
+
+    if [ -d "$TEMPLATES_DIR/$name" ]; then
+        echo -e "${YELLOW}Warning: Template '$name' already exists${NC}"
+        read -p "Overwrite? [y/N] " -n 1 -r
+        echo
+        if [[ ! $REPLY =~ ^[Yy]$ ]]; then
+            echo "Cancelled"
+            exit 0
+        fi
+        rm -rf "$TEMPLATES_DIR/$name"
+    fi
+
+    mkdir -p "$TEMPLATES_DIR/$name"
+
+    # Copy sandbox contents (except .venv, .git, __pycache__)
+    rsync -a --exclude='.venv' --exclude='.git' --exclude='__pycache__' \
+          --exclude='*.pyc' --exclude='.pytest_cache' --exclude='.mypy_cache' \
+          "$SANDBOX_DIR/" "$TEMPLATES_DIR/$name/"
+
+    echo -e "${GREEN}Saved template: $name${NC}"
+}
+
+show_status() {
+    echo "Sandbox Status"
+    echo "=============="
+    echo ""
+    echo "Sandbox directory: $SANDBOX_DIR"
+
+    if [ -f "$MARKER_FILE" ]; then
+        echo "Current template:  $(cat "$MARKER_FILE")"
+    else
+        echo "Current template:  (none loaded)"
+    fi
+
+    if [ -d "$SANDBOX_DIR/.venv" ]; then
+        echo "Virtual env:       exists"
+    else
+        echo "Virtual env:       not created"
+    fi
+
+    echo ""
+    echo "Contents:"
+    if [ -d "$SANDBOX_DIR" ]; then
+        ls -la "$SANDBOX_DIR" 2>/dev/null | tail -n +4
+    else
+        echo "  (sandbox not initialized)"
+    fi
+}
+
+# Main command dispatch
+case "${1:-}" in
+    list)
+        list_templates
+        ;;
+    load)
+        load_template "$2"
+        ;;
+    reset)
+        reset_template
+        ;;
+    save)
+        save_template "$2"
+        ;;
+    status)
+        show_status
+        ;;
+    -h|--help|"")
+        usage
+        ;;
+    *)
+        echo -e "${RED}Unknown command: $1${NC}"
+        usage
+        exit 1
+        ;;
+esac

src/shared/config.py

@@ -1,76 +0,0 @@
-"""
-Application configuration via Pydantic Settings.
-
-All settings loaded from environment variables or .env file.
-"""
-import tomllib
-from pathlib import Path
-from functools import lru_cache
-from typing import Optional
-
-from pydantic_settings import BaseSettings, SettingsConfigDict
-
-
-def _get_version() -> str:
-    """Load version from pyproject.toml."""
-    pyproject_path = Path(__file__).parent.parent.parent / "pyproject.toml"
-    try:
-        with open(pyproject_path, "rb") as f:
-            return tomllib.load(f).get("project", {}).get("version", "0.0.0")
-    except FileNotFoundError:
-        return "0.0.0"
-
-
-__version__ = _get_version()
-
-
-class Settings(BaseSettings):
-    """Application settings loaded from environment."""
-
-    # Application
-    app_name: str = "Webber"
-    app_version: str = __version__
-    debug: bool = False
-
-    # Server
-    host: str = "0.0.0.0"
-    port: int = 8086
-
-    # Logging
-    log_level: str = "INFO"
-
-    # CORS
-    cors_origins: list[str] = ["http://localhost:3000", "http://localhost:8080"]
-    cors_credentials: bool = True
-    cors_methods: list[str] = ["*"]
-    cors_headers: list[str] = ["*"]
-
-    # LLM - Ollama (always hot in VRAM on tower-of-joy)
-    ollama_url: str = "http://192.168.86.149:11434"
-    ollama_agent_model: str = "mistral-nemo-large:latest"
-    ollama_embed_model: str = "nomic-embed-text:latest"
-
-    # Auth - Tatlock integration
-    tatlock_api_url: Optional[str] = "http://192.168.86.149:8000"
-    internal_api_key: Optional[str] = None
-
-    # Tool execution
-    tool_timeout_seconds: int = 120
-    sandbox_enabled: bool = True
-    allowed_paths: list[str] = []
-
-    # Sessions
-    session_ttl_hours: int = 24
-    max_context_tokens: int = 128000
-
-    model_config = SettingsConfigDict(
-        env_file=".env",
-        case_sensitive=False,
-        extra="ignore",
-    )
-
-
-@lru_cache()
-def get_settings() -> Settings:
-    """Cached settings singleton."""
-    return Settings()

tests/conftest.py

@@ -1,34 +0,0 @@
-"""
-Pytest configuration and fixtures.
-"""
-import pytest
-from httpx import AsyncClient, ASGITransport
-
-from src.main import app
-
-
-@pytest.fixture
-def anyio_backend():
-    """Use asyncio for async tests."""
-    return "asyncio"
-
-
-@pytest.fixture
-async def client():
-    """Async HTTP client for testing."""
-    async with AsyncClient(
-        transport=ASGITransport(app=app),
-        base_url="http://test"
-    ) as ac:
-        yield ac
-
-
-@pytest.fixture
-async def auth_client():
-    """Async HTTP client with API key for authenticated requests."""
-    async with AsyncClient(
-        transport=ASGITransport(app=app),
-        base_url="http://test",
-        headers={"X-API-Key": "test-api-key"}
-    ) as ac:
-        yield ac

webber-api/AGENTS.md

@@ -0,0 +1,128 @@
+
+# AGENTS.md
+
+> **Start every session by reading this file.**
+> This file outlines the operational protocols, coding standards, and architectural decisions for this FastAPI project.
+
+## 1. Agent Operational Protocols
+
+### 🧠 Work Patterns (Plan-Act-Reflect)
+* **Plan:** Before writing code, briefly outline your plan. Identify which files you will touch and what the side effects might be.
+* **Act:** Execute the changes in small, atomic steps.
+* **Reflect:** After coding, verify your work. Did you break existing tests? Did you add new tests?
+
+### 🛡️ Git Discipline
+* **ALWAYS add the relevant tests for the added code** Make sure to keep the test coverage up as we go, and run tests before commiting.
+* **NEVER commit to `main` or `master` directly.** Always create a feature branch: `feature/your-feature-name` or `fix/issue-description`.
+* **Commit Messages:** Use the [Conventional Commits](https://www.conventionalcommits.org/) format.
+    * `feat: add user login endpoint`
+    * `fix: resolve database connection timeout`
+    * `refactor: split monolith dependency file`
+* **Atomic Commits:** Keep commits small. One logical change = one commit.
+
+### 📝 Changelog Maintenance
+* **Update `CHANGELOG.md`** with every user-facing change.
+* Format: `## [Unreleased] - YYYY-MM-DD` followed by `### Added`, `### Changed`, or `### Fixed`.
+
+### 🚀 Release Flow
+When changes are ready for deployment:
+
+1. **Ask user if deploy cycle is desired **
+
+2. **Update version** in `pyproject.toml`:
+   - Bug fixes: bump patch version (1.8.3 → 1.8.4)
+   - New features: bump minor version (1.8.4 → 1.9.0)
+
+3. **Update CHANGELOG.md**:
+   - Move items from `[Unreleased]` to new version section
+   - Add release date: `## [1.8.4] - 2025-12-16`
+
+4. **Commit and tag**:
+   ```bash
+   git add -A
+   git commit -m "fix: description of changes"
+   git tag v1.8.4
+   git push origin main --tags
+   ```
+
+5. **CI/CD triggers automatically**:
+   - Gitea CI builds Docker image on new version tag (starts with "v")
+   - Watchtower pulls and deploys to production
+   - Verify deployment: `curl http://192.168.86.149:8086/health`
+
+---
+
+### 🧪 Local Development Setup
+
+* **Always test locally first** before committing and deploying. The build-deploy loop is slow.
+* **Only deploy** when a phase or feature is complete and tested locally
+* **Environment**: Copy `.env.example` to `.env` and configure for your local setup
+
+#### ⚠️ CRITICAL: Starting the Local Server
+
+**ALWAYS use `./wakeup.sh` to start the local server. NEVER use raw uvicorn commands.**
+
+```bash
+./wakeup.sh
+```
+
+The wakeup script provides:
+- **Port conflict detection** - Warns if port 8086 is already in use
+- **Virtual environment activation** - Ensures correct Python environment
+- **Centralized logging** - All logs written to `logs/server.log` for easy tailing
+- **Auto-reload** - Code changes picked up automatically (except requirements.txt changes)
+- **Consistent configuration** - Same startup every time
+
+To monitor logs in another terminal:
+```bash
+tail -f logs/server.log
+```
+
+To stop the server: Press `Ctrl+C`
+
+To kill a stuck server:
+```bash
+pkill -f "uvicorn src.main:app"
+# or
+kill $(lsof -t -i:8086)
+```
+
+#### Testing
+
+**Test REST endpoints** against `http://localhost:8086`:
+```bash
+curl http://localhost:8086/health
+curl http://localhost:8086/
+curl http://localhost:8086/docs   # Swagger UI
+```
+
+**Running tests**: Always use the venv explicitly to avoid environment mismatches:
+```bash
+.venv/bin/python -m pytest tests/           # All tests
+.venv/bin/python -m pytest tests/ -v        # Verbose output
+.venv/bin/python -m pytest tests/ --cov     # With coverage
+```
+
+---
+
+## 1.5 Known Issues & Future Improvements
+
+### Explore Agent
+
+- **Model Hallucination**: Mistral Nemo sometimes hallucinates file contents instead of using actual tool results. Consider using a more capable model (codestral, qwen2.5-coder) or adding response validation.
+
+- **Ollama Provider**: We use a custom `WebberOllamaProvider` (ported from tatlock) that sanitizes `content: null` to `content: ""` for assistant messages with tool calls. This works around an Ollama API limitation.
+
+- **Gitignore Support**: ✅ Fixed - The filesystem tools now honor `.gitignore` patterns and default ignores (`.venv/`, `__pycache__/`, `node_modules/`, etc.).
+
+---
+
+## 2. FastAPI Architecture & Best Practices
+*Reference: [FastAPI Best Practices](https://github.com/zhanymkanov/fastapi-best-practices)*
+
+### 📂 Project Structure (Directory-based, NOT File-type based)
+Do **not** group files by type (e.g., one huge `routers` folder). Group by **domain/module** inside a `src/` directory.
+
+**Correct Structure:**
+```text
+to be determined

webber-api/Dockerfile

@@ -19,4 +19,7 @@ ENV PYTHONPATH=/app
 
 EXPOSE 8086
 
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+  CMD curl -f http://localhost:8086/health || exit 1
+
 CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8086", "--workers", "1"]

webber-api/docs/COVERAGE.md

@@ -0,0 +1,249 @@
+# Webber Feature Coverage
+
+> Tracking progress towards Claude Code-like functionality
+
+## Current Status: ~70% Complete
+
+Last updated: 2026-01-11
+
+---
+
+## Phase 1-6: Foundation (Original Plan)
+
+### Phase 1: Tool Infrastructure ✅ Complete
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| `BaseTool` abstract class | ✅ | `src/domains/tools/base.py` |
+| `ToolResult` dataclass | ✅ | Consistent success/error/truncated handling |
+| `ReadFileTool` | ✅ | With line numbers, offset/limit support |
+| `GlobFilesTool` | ✅ | Pattern matching, sorted by mtime |
+| `GrepContentTool` | ✅ | Regex search with context lines |
+| `BashReadOnlyTool` | ✅ | Allowlist-based command filtering |
+| `EditFileTool` | ✅ | Find-and-replace with unique match validation |
+| `WriteFileTool` | ✅ | Create/overwrite files with size limits |
+| `BashTool` (full) | ✅ | Write-enabled shell with safety controls |
+| `WebSearchTool` | ✅ | SearXNG integration for web search |
+| Path validation | ✅ | `allowed_paths` restriction |
+
+**Status:** Tools honor `.gitignore` patterns and default ignores (`.venv/`, `__pycache__/`, etc.)
+
+### Phase 2: Explore Agent ✅ Complete
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| `BaseAgent` abstract class | ✅ | `src/domains/agents/base.py` |
+| Agent registry | ✅ | `register_agent()`, `get_agent()`, `list_agents()` |
+| `ExploreAgentImpl` | ✅ | PydanticAI-based implementation |
+| System prompts | ✅ | Mistral-optimized with tool examples |
+| Tool registration | ✅ | `@agent.tool` decorator pattern |
+| Sanitized Ollama provider | ✅ | Fixes `content: null` issue |
+| Streaming support | ✅ | `run_stream()` method with SSE |
+
+**Available tools:** `read_file`, `glob_files`, `grep_content`, `bash_readonly`, `edit_file`, `write_file`, `bash`, `web_search`
+
+**Gap:** Mistral Nemo sometimes hallucinates instead of using tool results.
+
+### Phase 2b: Plan Agent ✅ Complete
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| `PlanAgentImpl` | ✅ | READ-ONLY software architect agent |
+| System prompts | ✅ | Architecture-focused with tool examples |
+| Tool registration | ✅ | Only read-only tools (4 tools) |
+| Streaming support | ✅ | `run_stream()` method with SSE |
+| Unit tests | ✅ | 15 tests for registration, tools, API |
+
+**Available tools:** `read_file`, `glob_files`, `grep_content`, `bash_readonly` (read-only only)
+
+**Purpose:** Design implementation strategies before coding - explores codebase and creates step-by-step plans.
+
+### Phase 3: CLI Foundation ✅ Complete
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| Typer + Rich setup | ✅ | Standalone `webber-cli/` package |
+| `webber-cli --version` | ✅ | Shows version from pyproject.toml |
+| Console theming | ✅ | Centralized color palette |
+| Markdown rendering | ✅ | Rich markdown output |
+| Streaming display | ✅ | Real-time token output with `--stream` flag |
+
+### Phase 4: Agentic Loop ⚠️ Partial
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| `webber-cli chat` command | ✅ | Interactive mode with streaming |
+| `webber-cli explore` command | ✅ | One-shot query with streaming |
+| `SessionState` dataclass | ✅ | Basic context tracking |
+| `AgenticLoop` class | ⚠️ | Basic implementation, not fully utilized |
+| Conversation history | ❌ | Not persisted between turns in CLI |
+| Context management | ❌ | No token counting or summarization |
+
+### Phase 5: REST API ✅ Complete
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| `POST /agents/run` | ✅ | Execute agent with prompt |
+| `POST /agents/stream` | ✅ | SSE streaming responses |
+| `GET /agents/` | ✅ | List available agents |
+| `GET /agents/{name}` | ✅ | Get agent info |
+| Request/response schemas | ✅ | Pydantic models |
+
+### Phase 6: Polish & Tests ✅ Complete
+
+| Component | Status | Notes |
+|-----------|--------|-------|
+| Tool unit tests | ✅ | 109 tests total |
+| API endpoint tests | ✅ | 11 tests for agent routes |
+| Health check tests | ✅ | 2 tests |
+| Security tests | ✅ | 14 tests for path traversal, injection |
+| Integration tests | ✅ | 10 tests with real LLM (requires Ollama) |
+| E2E tests | ✅ | 12 tests against running API server |
+
+---
+
+## Future Work: Remaining Features
+
+### High Priority
+
+| Feature | Category | Description | Complexity |
+|---------|----------|-------------|------------|
+| ~~**Plan Agent**~~ | Agents | ✅ Design implementation approaches | High |
+| **Task Agent** | Agents | Autonomous multi-step execution | High |
+| **Context summarization** | Infrastructure | Compress history at token limit | High |
+| **Conversation persistence** | CLI | Multi-turn memory in chat mode | Medium |
+
+### Medium Priority
+
+| Feature | Category | Description | Complexity |
+|---------|----------|-------------|------------|
+| **Web search summarizer** | Tools | Agent to extract core content from web pages (remove nav, footers, etc.) and preserve relevant links for nested fetching | Medium |
+| **Tool result caching** | Infrastructure | Cache file reads for performance | Low |
+| **Session persistence** | CLI | Save/resume conversations | Medium |
+| **Todo tracking** | CLI | Built-in task list (`/todo`) | Medium |
+| **Git integration** | CLI | Auto-commit, branch management | Medium |
+| **Agent handoff** | Orchestration | Explore → Plan → Task workflow | High |
+| **Retry logic** | Infrastructure | Auto-retry on tool failures | Low |
+
+### Low Priority
+
+| Feature | Category | Description | Complexity |
+|---------|----------|-------------|------------|
+| **Notebook editing** | Tools | Jupyter cell manipulation | Medium |
+| **MCP support** | Infrastructure | Model Context Protocol | High |
+| **Config file** | CLI | `~/.webber/config.toml` | Low |
+| **IDE integration** | CLI | VS Code extension | High |
+| **Parallel agents** | Orchestration | Concurrent agent execution | High |
+| **Agent memory** | Orchestration | Shared context between agents | Medium |
+
+---
+
+## Testing Coverage
+
+| Area | Current | Target | Status |
+|------|---------|--------|--------|
+| Tool unit tests | 109 | 109 | ✅ |
+| API tests | 11 | 11 | ✅ |
+| Plan agent tests | 15 | 15 | ✅ |
+| Security tests | 14 | 14 | ✅ |
+| Integration tests | 10 | 10 | ✅ Agent + real LLM |
+| E2E tests | 12 | 12 | ✅ Full API workflow |
+
+**Test breakdown:**
+- Read/Glob/Grep tools: 17 tests
+- Edit/Write tools: 22 tests
+- Bash tools: 22 tests
+- Web search: 10 tests
+- Gitignore filtering: 10 tests
+- API endpoints: 11 tests
+- Plan agent: 15 tests
+- Security: 14 tests
+- Health checks: 2 tests
+- Integration (LLM): 10 tests
+- E2E (API): 12 tests
+
+**Running tests:**
+```bash
+# Unit tests only (default)
+pytest tests/
+
+# Include integration tests (requires Ollama)
+pytest tests/ --run-integration
+
+# Include E2E tests (requires running API server)
+pytest tests/ --run-e2e
+
+# All tests
+pytest tests/ --run-integration --run-e2e
+```
+
+---
+
+## Known Issues
+
+1. **Model hallucination** - Mistral Nemo sometimes makes up file contents instead of using actual tool results.
+
+2. **No conversation memory** - CLI chat mode doesn't persist context between sessions.
+
+3. **Temperature setting** - Changed from 0.0 to 0.3 for Mistral Nemo compatibility, may affect determinism.
+
+---
+
+## Architecture Decisions Made
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Monorepo structure | `webber-api/`, `webber-cli/` | Separate packages, shared root |
+| Sanitized Ollama provider | Custom wrapper | Fixes PydanticAI + Ollama `content: null` bug |
+| Dev port 8095 | Separate from prod 8086 | Avoid conflicts with Docker deployment |
+| Tool choice "required" | Force tool use | Mistral Nemo needs explicit instruction |
+| Temperature 0.3 | Mistral recommendation | 0.0 caused issues with Nemo |
+| SearXNG for search | Self-hosted | Privacy, no API keys needed |
+| SSE for streaming | Server-Sent Events | Simple, well-supported |
+
+---
+
+## Quick Reference: What Works Now
+
+```bash
+# Start dev server
+cd webber-api && ./wakeup.sh
+
+# CLI commands (from webber-cli/)
+.venv/bin/webber-cli status                    # Check API connection
+.venv/bin/webber-cli explore "find tests"      # One-shot exploration
+.venv/bin/webber-cli explore "query" --no-stream  # Batch mode
+.venv/bin/webber-cli chat                      # Interactive mode
+
+# API endpoints
+curl http://localhost:8095/health
+curl http://localhost:8095/agents/
+curl -X POST http://localhost:8095/agents/run \
+  -H "Content-Type: application/json" \
+  -d '{"agent_type":"explore","prompt":"list python files","working_dir":"."}'
+
+# Plan agent (read-only, creates implementation plans)
+curl -X POST http://localhost:8095/agents/run \
+  -H "Content-Type: application/json" \
+  -d '{"agent_type":"plan","prompt":"plan how to add user auth","working_dir":"."}'
+
+# Streaming endpoint
+curl -N http://localhost:8095/agents/stream \
+  -H "Content-Type: application/json" \
+  -d '{"agent_type":"explore","prompt":"find config files","working_dir":"."}'
+```
+
+---
+
+## Tools Available
+
+| Tool | Type | Description |
+|------|------|-------------|
+| `read_file` | Read | Read file contents with line numbers |
+| `glob_files` | Read | Find files by pattern |
+| `grep_content` | Read | Search file contents with regex |
+| `bash_readonly` | Read | Safe bash commands (ls, git status, etc.) |
+| `edit_file` | Write | Find-and-replace editing |
+| `write_file` | Write | Create/overwrite files |
+| `bash` | Write | Full bash with safety controls |
+| `web_search` | External | Search web via SearXNG |

webber-api/docs/architecture.md

@@ -0,0 +1,349 @@
+# Webber Architecture
+
+Multi-Agent AI Development System - similar to Claude Code but running locally with configurable models.
+
+## Overview
+
+Webber is a FastAPI-based agent orchestration service that provides:
+- Multi-agent execution (Explore, Plan, Task)
+- Tool capabilities (file operations, shell, search)
+- Multi-tenant authentication via Tatlock integration
+- PydanticAI framework for LLM orchestration
+
+**Port:** 8086
+**Runtime:** Python 3.12, FastAPI, Uvicorn
+**Agent Framework:** PydanticAI
+**Default LLM:** Ollama with mistral-nemo-large:latest
+
+---
+
+## Directory Structure
+
+```
+webber/
+├── src/
+│   ├── main.py              # App entry point (NO routes)
+│   │
+│   ├── shared/              # Cross-cutting concerns
+│   │   ├── base.py          # BaseController, BaseSchema
+│   │   ├── config.py        # Pydantic Settings
+│   │   ├── logging.py       # @logged decorator, trace_span
+│   │   ├── exceptions.py    # Custom exception hierarchy
+│   │   ├── auth.py          # API key validation
+│   │   └── context.py       # UserProvider singleton
+│   │
+│   └── domains/             # Feature domains
+│       ├── router.py        # Root router (composes all)
+│       ├── health/          # Health endpoints
+│       ├── auth/            # Authentication
+│       ├── agents/          # Agent orchestration
+│       │   ├── explore/     # Codebase navigation
+│       │   ├── plan/        # Implementation design
+│       │   └── task/        # Execution
+│       └── tools/           # Tool execution
+│           ├── file/        # Read, write, glob
+│           ├── shell/       # Bash execution
+│           └── search/      # Grep, web search
+│
+├── tests/
+├── docs/
+└── logs/
+```
+
+---
+
+## Core Patterns
+
+### 1. Clean main.py
+
+The entry point contains ONLY:
+- FastAPI app creation with lifespan
+- CORS middleware
+- Auth middleware (sets UserProvider)
+- Exception handlers
+- Single router include (`root_router`)
+
+All routes live in domain routers. This keeps main.py focused on app initialization.
+
+### 2. Domain-Based Structure
+
+Each feature domain has its own directory:
+```
+domains/
+├── router.py           # Root router composing all domains
+├── health/
+│   ├── router.py       # Domain routes
+│   └── controller.py   # Business logic
+├── agents/
+│   ├── router.py       # Agent routes
+│   ├── controller.py   # Orchestration logic
+│   ├── schemas.py      # Request/response models
+│   └── explore/        # Agent implementation
+│       ├── agent.py    # PydanticAI agent
+│       └── prompts.py  # System prompts
+```
+
+### 3. BaseController Pattern
+
+Controllers use lazy router instantiation:
+
+```python
+from src.shared.base import BaseController
+
+class MyController(BaseController):
+    def __init__(self):
+        super().__init__(prefix="/my", tags=["My"])
+
+    def create_router(self) -> APIRouter:
+        router = APIRouter(prefix=self.prefix, tags=self.tags)
+
+        @router.get("/")
+        async def list_items():
+            return []
+
+        return router
+
+my_controller = MyController()
+# Use: my_controller.router
+```
+
+### 4. UserProvider Singleton
+
+Request-scoped user context without parameter passing:
+
+```python
+# In middleware (main.py):
+user = await validate_api_key(api_key)
+user_provider.set_user(user)
+try:
+    response = await call_next(request)
+finally:
+    user_provider.clear_user()
+
+# Anywhere in code:
+from src.shared.context import get_current_user, require_user
+
+user = get_current_user()  # Returns None if not authenticated
+user = require_user()      # Raises if not authenticated
+```
+
+Uses Python's `contextvars` for async-safe request isolation.
+
+### 5. Logger with Temporal Benchmarking
+
+The `@logged()` decorator automatically tracks execution time:
+
+```python
+from src.shared.logging import logged, trace_span, get_logger
+
+logger = get_logger(__name__)
+
+@logged()
+async def my_function():
+    # Automatically logs entry, exit, and duration
+    pass
+
+@logged(slow_threshold_ms=50, warn_threshold_ms=200)
+def critical_path():
+    # Custom thresholds for performance-critical code
+    pass
+
+async def complex_operation():
+    async with trace_span("llm_call"):
+        # Manual span for specific sections
+        result = await agent.run(prompt)
+```
+
+Features:
+- Trace ID correlation across nested calls
+- Configurable slow/warn thresholds
+- DEBUG: all calls logged with timing
+- INFO: slow calls (>100ms default)
+- WARNING: very slow calls (>500ms default)
+- ERROR: failed calls with stack trace
+
+### 6. Exception Hierarchy
+
+```python
+from src.shared.exceptions import (
+    AppException,
+    NotFoundError,
+    ValidationError,
+    AuthenticationError,
+    AuthorizationError,
+)
+
+# Raise with context:
+raise NotFoundError("User", user_id)
+raise ValidationError("email", "Invalid format")
+
+# Automatic JSON response via exception handlers in main.py
+```
+
+---
+
+## Configuration
+
+All settings via environment variables or `.env`:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| DEBUG | false | Enable debug mode |
+| LOG_LEVEL | INFO | Logging level |
+| HOST | 0.0.0.0 | Server host |
+| PORT | 8086 | Server port |
+| OLLAMA_URL | http://192.168.86.149:11434 | Ollama API URL |
+| OLLAMA_AGENT_MODEL | mistral-nemo-large:latest | Agent reasoning model |
+| OLLAMA_EMBED_MODEL | nomic-embed-text:latest | Embedding model |
+| TATLOCK_API_URL | http://192.168.86.149:8000 | Tatlock auth service |
+| TOOL_TIMEOUT_SECONDS | 120 | Tool execution timeout |
+| SANDBOX_ENABLED | true | Enable sandboxed execution |
+| ALLOWED_PATHS | [] | Paths accessible to tools |
+| SESSION_TTL_HOURS | 24 | Session expiry |
+| MAX_CONTEXT_TOKENS | 128000 | Max context window |
+
+---
+
+## Agent Architecture
+
+Webber uses PydanticAI for agent orchestration. Each agent type is purpose-built:
+
+### Explore Agent
+Fast codebase exploration for:
+- Finding files by pattern
+- Searching code for keywords
+- Answering questions about structure
+
+### Plan Agent
+Implementation design for:
+- Analyzing requirements
+- Creating step-by-step plans
+- Identifying files to modify
+- Considering trade-offs
+
+### Task Agent
+Autonomous execution for:
+- Multi-step implementations
+- Tool orchestration
+- Code generation and modification
+
+---
+
+## Tool Architecture
+
+Tools are sandboxed operations agents can invoke:
+
+### File Tools
+- **Read**: Read file contents with line limits
+- **Write**: Create or overwrite files
+- **Edit**: String replacement in files
+- **Glob**: Pattern-based file search
+
+### Shell Tools
+- **Bash**: Command execution with timeout
+- Sandboxed to allowed paths
+- Captures stdout/stderr
+
+### Search Tools
+- **Grep**: Regex content search via ripgrep
+- **WebSearch**: Web search integration (optional)
+
+---
+
+## Authentication Flow
+
+1. Client sends `X-API-Key` header
+2. Auth middleware calls `validate_api_key()`
+3. Tatlock validates key and returns user info
+4. UserProvider stores user in request context
+5. Routes access via `get_current_user()` or `require_user()`
+6. Middleware clears user in `finally` block
+
+---
+
+## Deployment
+
+### Docker
+
+```dockerfile
+FROM python:3.12-slim
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY pyproject.toml .
+COPY src/ ./src/
+ENV PYTHONPATH=/app
+EXPOSE 8086
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+  CMD curl -f http://localhost:8086/health || exit 1
+CMD ["uvicorn", "src.main:app", "--host", "0.0.0.0", "--port", "8086"]
+```
+
+### CI/CD
+
+Gitea Actions workflow:
+1. Push tag `v*` triggers build
+2. Creates Gitea release
+3. Builds and pushes Docker image to registry
+4. Watchtower auto-deploys to production
+
+### Production Stack
+
+Deployed in Portainer `agents` stack alongside Tatlock:
+- Network: `docker-dataplane`
+- Registry: `git.schweitz.internal/jpmschweitzer/webber`
+- Auto-update: Watchtower with label `com.centurylinklabs.watchtower.enable=true`
+
+---
+
+## Adding New Domains
+
+1. Create domain directory under `src/domains/`
+2. Add `router.py` with routes
+3. Add `controller.py` with business logic
+4. Add `schemas.py` for request/response models
+5. Import and include router in `src/domains/router.py`
+6. Add tests in `tests/test_<domain>.py`
+
+---
+
+## Adding New Agents
+
+1. Create agent directory under `src/domains/agents/`
+2. Add `agent.py` with PydanticAI agent definition
+3. Add `prompts.py` with system prompts
+4. Register in agents controller
+5. Document in `src/domains/agents/README.md`
+
+---
+
+## Adding New Tools
+
+1. Create tool file under appropriate `src/domains/tools/` subdir
+2. Implement tool function with type hints
+3. Register as PydanticAI tool
+4. Document in `src/domains/tools/README.md`
+
+---
+
+## Testing
+
+```bash
+# Run all tests
+./wakeup.sh  # Start server first
+pytest tests/ -v
+
+# With coverage
+pytest tests/ --cov=src --cov-report=html
+```
+
+---
+
+## Security Considerations
+
+- All tool execution is sandboxed when `SANDBOX_ENABLED=true`
+- File operations restricted to `ALLOWED_PATHS`
+- No secrets in prompts
+- Input validation via Pydantic
+- Output parsing expects malformed LLM responses
+- Timeouts on all tool execution

webber-api/docs/mistral-instructions.md

@@ -0,0 +1,14 @@
+## Background
+
+Research with Gemini identified key issues with mistral-nemo and tool calling:
+- "Pre-computation Hallucination" - model answers before using tools
+- High default temperature (0.7-0.8) causes wandering
+- Model is "chatty and confident" - needs explicit constraints
+
+## Key Recommendations from Gemini Research
+
+1. **Temperature 0.0** for tool-calling agents (deterministic, follows schema)
+2. **Chain of Thought (CoT)** - force step-by-step reasoning
+3. **Negative constraints** - tell model what NOT to do (Nemo responds better)
+4. **Explicit tool descriptions** - verbose docstrings with "never estimate yourself"
+5. **"Strictly tool-based assistant"** pattern - NO internal knowledge claim

webber-api/pyproject.toml

@@ -0,0 +1,77 @@
+[project]
+name = "webber-api"
+version = "0.3.4"
+description = "Webber API - Multi-Agent AI Development Server"
+authors = [
+    {name = "jpmschweitzer"}
+]
+readme = "README.md"
+requires-python = ">=3.12"
+license = {text = "MIT"}
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: FastAPI",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Code Generators",
+]
+
+[build-system]
+requires = ["setuptools>=75.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["src*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_functions = ["test_*"]
+addopts = "-v --strict-markers"
+markers = [
+    "integration: marks tests as integration tests (require Ollama to be running)",
+    "e2e: marks tests as end-to-end tests (require API server to be running)",
+    "slow: marks tests as slow (may take > 10 seconds)",
+]
+filterwarnings = [
+    "ignore::pytest.PytestUnraisableExceptionWarning",
+]
+
+[tool.mypy]
+python_version = "3.12"
+warn_return_any = true
+warn_unused_ignores = true
+strict = false
+ignore_missing_imports = true
+
+[tool.ruff]
+target-version = "py312"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "E",      # pycodestyle errors
+    "W",      # pycodestyle warnings
+    "F",      # Pyflakes
+    "I",      # isort
+    "B",      # flake8-bugbear
+    "C4",     # flake8-comprehensions
+    "UP",     # pyupgrade
+    "SIM",    # flake8-simplify
+    "TCH",    # flake8-type-checking
+    "RUF",    # Ruff-specific rules
+]
+ignore = [
+    "E501",   # line too long (handled by formatter)
+    "B008",   # function call in default argument (FastAPI Depends)
+    "B904",   # raise without from (sometimes intentional)
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["src"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+skip-magic-trailing-comma = false

webber-api/requirements-dev.txt

@@ -15,3 +15,6 @@ pip-audit~=2.9.0
 
 # Type checking
 mypy~=1.19.1
+
+# Linting and formatting
+ruff~=0.9.4

webber-api/requirements.txt

@@ -17,6 +17,11 @@ pydantic-ai~=1.40.0
 httpx~=0.28.1
 aiofiles~=25.1.0
 
+# CLI
+typer~=0.15.0
+rich~=13.9.0
+
 # Utilities
 python-multipart~=0.0.21
 python-dotenv~=1.2.1
+pathspec~=0.12.1                       # Gitignore pattern matching

webber-api/src/cli/__init__.py

@@ -0,0 +1,3 @@
+"""
+Webber CLI - Command-line interface for the multi-agent system.
+"""

webber-api/src/cli/commands/__init__.py

@@ -0,0 +1,6 @@
+"""
+CLI commands.
+"""
+from src.cli.commands import chat, explore, version
+
+__all__ = ["chat", "explore", "version"]

webber-api/src/cli/commands/chat.py

@@ -0,0 +1,128 @@
+"""
+Chat command - interactive conversation mode.
+"""
+import asyncio
+from pathlib import Path
+
+import typer
+
+from src.cli.theme import get_theme
+from src.cli.ui.console import get_console
+from src.cli.session.loop import AgenticLoop
+from src.shared.logging import setup_logging
+
+console = get_console()
+
+
+def chat_command(
+    directory: str = typer.Option(
+        ".",
+        "--directory",
+        "-d",
+        help="Working directory to explore",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-V",
+        help="Show detailed output and debug logging",
+    ),
+) -> None:
+    """
+    Start interactive chat session.
+
+    Enters a conversation loop where you can ask questions about the codebase.
+    The explore agent will search files, read code, and answer questions.
+
+    Examples:
+        webber chat
+        webber chat -d ./src
+        webber chat --verbose
+    """
+    # Set up logging
+    log_level = "DEBUG" if verbose else "WARNING"
+    setup_logging(log_level)
+
+    # Resolve directory
+    working_dir = str(Path(directory).resolve())
+
+    if not Path(working_dir).exists():
+        console.print(f"[error]Error:[/] Directory not found: {working_dir}")
+        raise typer.Exit(1)
+
+    # Run the async chat loop
+    try:
+        asyncio.run(_chat_loop(working_dir, verbose))
+    except KeyboardInterrupt:
+        console.print("\n[dim]Goodbye![/]")
+
+
+async def _chat_loop(working_dir: str, verbose: bool) -> None:
+    """Async chat loop implementation."""
+    from src.domains.agents.explore import explore_agent
+
+    # Create the agentic loop
+    loop = AgenticLoop(
+        agent=explore_agent,
+        console=console,
+        working_dir=working_dir,
+    )
+
+    # Display welcome
+    loop.display_welcome()
+
+    # Main conversation loop
+    while True:
+        try:
+            # Get user input
+            user_input = console.input("[prompt]>[/] ").strip()
+
+            # Handle special commands
+            if not user_input:
+                continue
+
+            if user_input.lower() in ("exit", "quit", "/exit", "/quit"):
+                console.print("[dim]Goodbye![/]")
+                break
+
+            if user_input.lower() in ("clear", "/clear"):
+                loop.state.clear_history()
+                console.print("[info]History cleared.[/]")
+                continue
+
+            if user_input.lower() in ("status", "/status"):
+                loop.display_status()
+                continue
+
+            if user_input.lower().startswith("cd "):
+                new_dir = user_input[3:].strip()
+                new_path = Path(new_dir).resolve()
+                if new_path.exists() and new_path.is_dir():
+                    loop.set_working_dir(str(new_path))
+                else:
+                    console.print(f"[error]Directory not found:[/] {new_dir}")
+                continue
+
+            # Process with agent
+            theme = get_theme()
+            with console.status("[info]Thinking...[/]", spinner=theme.spinner):
+                response = await loop.run_turn(user_input)
+
+            # Display response
+            console.print()
+            loop.display_response(response)
+            console.print()
+
+        except KeyboardInterrupt:
+            console.print("\n[dim]Use 'exit' to quit or press Ctrl+C again.[/]")
+            try:
+                # Wait briefly for second Ctrl+C
+                await asyncio.sleep(0.5)
+            except KeyboardInterrupt:
+                console.print("\n[dim]Goodbye![/]")
+                break
+
+        except Exception as e:
+            console.print(f"[error]Error:[/] {e}")
+            if verbose:
+                console.print_exception()

webber-api/src/cli/commands/explore.py

@@ -0,0 +1,83 @@
+"""
+Explore command - one-shot codebase exploration.
+"""
+import asyncio
+from pathlib import Path
+
+import typer
+from rich.panel import Panel
+
+from src.cli.theme import get_theme
+from src.cli.ui.console import get_console
+from src.cli.ui.display import format_response
+from src.shared.logging import setup_logging
+
+console = get_console()
+
+
+def explore_command(
+    query: str = typer.Argument(..., help="What to search for in the codebase"),
+    directory: str = typer.Option(
+        ".",
+        "--directory",
+        "-d",
+        help="Working directory to explore",
+    ),
+    verbose: bool = typer.Option(
+        False,
+        "--verbose",
+        "-V",
+        help="Show detailed output",
+    ),
+) -> None:
+    """
+    One-shot codebase exploration.
+
+    Searches the codebase for the given query and returns findings.
+
+    Examples:
+        webber explore "where is config loaded"
+        webber explore "find all API endpoints" -d ./src
+        webber explore "how does authentication work"
+    """
+    # Set up logging based on verbosity
+    log_level = "DEBUG" if verbose else "WARNING"
+    setup_logging(log_level)
+
+    # Resolve directory
+    working_dir = str(Path(directory).resolve())
+
+    if not Path(working_dir).exists():
+        console.print(f"[error]Error:[/] Directory not found: {working_dir}")
+        raise typer.Exit(1)
+
+    console.print(f"[dim]Exploring:[/] [path]{working_dir}[/]")
+    console.print(f"[dim]Query:[/] {query}\n")
+
+    # Run the exploration
+    asyncio.run(_explore_async(query, working_dir, verbose))
+
+
+async def _explore_async(query: str, working_dir: str, verbose: bool) -> None:
+    """Async exploration implementation."""
+    from src.domains.agents.explore import explore
+
+    theme = get_theme()
+
+    try:
+        with console.status("[info]Searching codebase...[/]", spinner=theme.spinner):
+            result = await explore(query, working_dir=working_dir)
+
+        # Display result
+        formatted = format_response(result)
+        console.print(Panel(
+            formatted,
+            title="[success]Findings[/]",
+            border_style=theme.colors.border_success,
+        ))
+
+    except Exception as e:
+        console.print(f"[error]Error:[/] {e}")
+        if verbose:
+            console.print_exception()
+        raise typer.Exit(1)

webber-api/src/cli/commands/version.py

@@ -0,0 +1,26 @@
+"""
+Version command.
+"""
+from rich.console import Console
+from rich.panel import Panel
+
+from src.shared.config import get_settings
+
+console = Console()
+
+
+def show_version() -> None:
+    """Display version information."""
+    settings = get_settings()
+
+    version_info = f"""[bold blue]{settings.app_name}[/] [green]v{settings.app_version}[/]
+
+{settings.app_description}
+
+[dim]Configuration:[/]
+  Ollama URL: {settings.ollama_url}
+  Model: {settings.ollama_agent_model}
+  Debug: {settings.debug}
+"""
+
+    console.print(Panel(version_info, title="Version Info", border_style="blue"))

webber-api/src/cli/main.py

@@ -0,0 +1,64 @@
+"""
+Webber CLI main entry point.
+
+Usage:
+    webber --help
+    webber --version
+    webber chat [OPTIONS]
+    webber explore QUERY [OPTIONS]
+"""
+import typer
+from rich.console import Console
+
+from src.shared.config import get_settings
+
+# Create Typer app
+app = typer.Typer(
+    name="webber",
+    help="Multi-Agent AI Development System",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+console = Console()
+
+
+def version_callback(value: bool) -> None:
+    """Display version and exit."""
+    if value:
+        settings = get_settings()
+        console.print(f"[bold blue]{settings.app_name}[/] version [green]{settings.app_version}[/]")
+        console.print(f"[dim]{settings.app_description}[/]")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-v",
+        callback=version_callback,
+        is_eager=True,
+        help="Show version and exit",
+    ),
+) -> None:
+    """
+    Webber - Multi-Agent AI Development System.
+
+    A CLI tool for codebase exploration and development assistance
+    powered by local LLMs via Ollama.
+    """
+    pass
+
+
+# Import and register commands
+from src.cli.commands import chat, explore, version  # noqa: E402, F401
+
+# Register subcommands
+app.command(name="chat")(chat.chat_command)
+app.command(name="explore")(explore.explore_command)
+
+
+if __name__ == "__main__":
+    app()

webber-api/src/cli/session/__init__.py

@@ -0,0 +1,7 @@
+"""
+Session management for CLI.
+"""
+from src.cli.session.context import SessionState
+from src.cli.session.loop import AgenticLoop
+
+__all__ = ["SessionState", "AgenticLoop"]

webber-api/src/cli/session/context.py

@@ -0,0 +1,60 @@
+"""
+Session state management.
+"""
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Literal
+
+
+@dataclass
+class Message:
+    """Single message in conversation history."""
+    role: Literal["user", "assistant", "system"]
+    content: str
+    timestamp: datetime = field(default_factory=datetime.now)
+
+    def __str__(self) -> str:
+        return f"[{self.role}] {self.content[:50]}..."
+
+
+@dataclass
+class SessionState:
+    """
+    Persistent state for a CLI session.
+
+    Tracks conversation history and context.
+    """
+    working_dir: str
+    messages: list[Message] = field(default_factory=list)
+    started_at: datetime = field(default_factory=datetime.now)
+
+    # Token tracking (for future context management)
+    estimated_tokens: int = 0
+    max_tokens: int = 128000
+
+    def add_message(self, role: Literal["user", "assistant", "system"], content: str) -> None:
+        """Add a message to history."""
+        self.messages.append(Message(role=role, content=content))
+        # Rough token estimate (4 chars per token)
+        self.estimated_tokens += len(content) // 4
+
+    def get_history(self, limit: int | None = None) -> list[Message]:
+        """Get recent message history."""
+        if limit:
+            return self.messages[-limit:]
+        return self.messages
+
+    def clear_history(self) -> None:
+        """Clear message history."""
+        self.messages.clear()
+        self.estimated_tokens = 0
+
+    @property
+    def message_count(self) -> int:
+        """Number of messages in history."""
+        return len(self.messages)
+
+    @property
+    def is_near_limit(self) -> bool:
+        """Check if approaching token limit."""
+        return self.estimated_tokens > (self.max_tokens * 0.8)

webber-api/src/cli/session/loop.py

@@ -0,0 +1,104 @@
+"""
+Agentic conversation loop for interactive CLI.
+"""
+from typing import Any
+
+from rich.console import Console
+
+from src.cli.session.context import SessionState
+from src.cli.ui.display import format_response
+from src.domains.agents.base import BaseAgent
+from src.shared.logging import logged, trace_span, get_logger
+
+logger = get_logger(__name__)
+
+
+class AgenticLoop:
+    """
+    Main conversation loop for interactive CLI sessions.
+
+    Manages state, executes agent turns, and handles display.
+    """
+
+    def __init__(
+        self,
+        agent: BaseAgent,
+        console: Console,
+        working_dir: str,
+    ):
+        """
+        Initialize the agentic loop.
+
+        Args:
+            agent: The agent to use for responses
+            console: Rich console for output
+            working_dir: Working directory for exploration
+        """
+        self.agent = agent
+        self.console = console
+        self.state = SessionState(working_dir=working_dir)
+
+    @logged()
+    async def run_turn(self, user_input: str) -> str:
+        """
+        Execute a single conversation turn.
+
+        Args:
+            user_input: User's prompt/question
+
+        Returns:
+            Agent's response
+        """
+        # Record user message
+        self.state.add_message("user", user_input)
+
+        async with trace_span("agentic_turn"):
+            try:
+                # Run the agent
+                response = await self.agent.run(
+                    user_input,
+                    working_dir=self.state.working_dir,
+                )
+
+                # Record assistant response
+                self.state.add_message("assistant", response)
+
+                return response
+
+            except Exception as e:
+                logger.exception(f"Agent error: {e}")
+                error_msg = f"Error: {e}"
+                self.state.add_message("assistant", error_msg)
+                raise
+
+    def display_response(self, response: str) -> None:
+        """Display agent response with formatting."""
+        formatted = format_response(response)
+        self.console.print(formatted)
+
+    def display_welcome(self) -> None:
+        """Display welcome message."""
+        from src.shared.config import get_settings
+        settings = get_settings()
+
+        self.console.print()
+        self.console.print(f"[title]{settings.app_name}[/] [dim]v{settings.app_version}[/]")
+        self.console.print(f"[dim]Working in:[/] [path]{self.state.working_dir}[/]")
+        self.console.print(f"[dim]Agent:[/] {self.agent.name} - {self.agent.description}")
+        self.console.print()
+        self.console.print("[dim]Type 'exit' or Ctrl+C to quit. Type 'clear' to reset history.[/]")
+        self.console.print()
+
+    def display_status(self) -> None:
+        """Display session status."""
+        self.console.print(f"[dim]Messages: {self.state.message_count} | Tokens: ~{self.state.estimated_tokens}[/]")
+
+    @property
+    def working_dir(self) -> str:
+        """Get current working directory."""
+        return self.state.working_dir
+
+    def set_working_dir(self, path: str) -> None:
+        """Change working directory."""
+        self.state.working_dir = path
+        self.console.print(f"[info]Changed directory to:[/] [path]{path}[/]")

webber-api/src/cli/theme.py

@@ -0,0 +1,70 @@
+"""
+CLI theme configuration.
+
+Centralized color and style definitions for the Webber CLI.
+All color choices should be defined here for easy customization.
+"""
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class ThemeColors:
+    """Color palette for the CLI."""
+
+    # Semantic colors
+    info: str = "steel_blue"
+    warning: str = "dark_orange"
+    error: str = "red3"
+    success: str = "sea_green3"
+
+    # UI elements
+    prompt: str = "steel_blue bold"
+    title: str = "steel_blue bold"
+    path: str = "steel_blue underline"
+    code: str = "sea_green3"
+    highlight: str = "medium_purple1"
+    dim: str = "dim white"
+
+    # Panel borders
+    border_default: str = "steel_blue"
+    border_success: str = "sea_green3"
+    border_error: str = "red3"
+    border_warning: str = "dark_orange"
+
+
+@dataclass(frozen=True)
+class ThemeConfig:
+    """Complete theme configuration."""
+
+    colors: ThemeColors = ThemeColors()
+
+    # Spinner style for loading indicators
+    spinner: str = "dots"
+
+    # Code syntax highlighting theme
+    syntax_theme: str = "monokai"
+
+    def to_rich_theme_dict(self) -> dict[str, str]:
+        """Convert to Rich theme dictionary."""
+        return {
+            "info": self.colors.info,
+            "warning": self.colors.warning,
+            "error": self.colors.error,
+            "success": self.colors.success,
+            "prompt": self.colors.prompt,
+            "title": self.colors.title,
+            "path": self.colors.path,
+            "code": self.colors.code,
+            "highlight": self.colors.highlight,
+            "dim": self.colors.dim,
+        }
+
+
+# Default theme instance
+DEFAULT_THEME = ThemeConfig()
+
+
+def get_theme() -> ThemeConfig:
+    """Get the current theme configuration."""
+    # Future: could load from config file or env vars
+    return DEFAULT_THEME

webber-api/src/cli/ui/__init__.py

@@ -0,0 +1,7 @@
+"""
+CLI UI components.
+"""
+from src.cli.ui.console import get_console
+from src.cli.ui.display import format_response, format_code
+
+__all__ = ["get_console", "format_response", "format_code"]

webber-api/src/cli/ui/console.py

@@ -0,0 +1,37 @@
+"""
+Rich console helpers.
+"""
+from functools import lru_cache
+
+from rich.console import Console
+from rich.theme import Theme
+
+from src.cli.theme import get_theme
+
+
+@lru_cache
+def get_console() -> Console:
+    """Get the shared console instance with theme applied."""
+    theme = get_theme()
+    rich_theme = Theme(theme.to_rich_theme_dict())
+    return Console(theme=rich_theme)
+
+
+def print_info(message: str) -> None:
+    """Print an info message."""
+    get_console().print(f"[info]{message}[/]")
+
+
+def print_warning(message: str) -> None:
+    """Print a warning message."""
+    get_console().print(f"[warning]Warning:[/] {message}")
+
+
+def print_error(message: str) -> None:
+    """Print an error message."""
+    get_console().print(f"[error]Error:[/] {message}")
+
+
+def print_success(message: str) -> None:
+    """Print a success message."""
+    get_console().print(f"[success]{message}[/]")

webber-api/src/cli/ui/display.py

@@ -0,0 +1,84 @@
+"""
+Output formatting and display helpers.
+"""
+import re
+
+from rich.markdown import Markdown
+from rich.syntax import Syntax
+from rich.text import Text
+
+from src.cli.theme import get_theme
+from src.cli.ui.console import get_console
+
+
+def format_response(text: str) -> Markdown | Text:
+    """
+    Format agent response for display.
+
+    Detects markdown and formats appropriately.
+    """
+    # Check if response contains markdown patterns
+    has_markdown = any([
+        "```" in text,  # Code blocks
+        text.startswith("#"),  # Headers
+        "**" in text or "__" in text,  # Bold
+        "- " in text or "* " in text,  # Lists
+    ])
+
+    if has_markdown:
+        return Markdown(text)
+    else:
+        return Text(text)
+
+
+def format_code(code: str, language: str = "python") -> Syntax:
+    """
+    Format code with syntax highlighting.
+
+    Args:
+        code: Source code to format
+        language: Programming language for highlighting
+    """
+    theme = get_theme()
+    return Syntax(
+        code,
+        language,
+        theme=theme.syntax_theme,
+        line_numbers=True,
+        word_wrap=True,
+    )
+
+
+def format_file_path(path: str, line: int | None = None) -> Text:
+    """
+    Format a file path for display.
+
+    Args:
+        path: File path
+        line: Optional line number
+    """
+    text = Text()
+    text.append(path, style="path")
+    if line:
+        text.append(f":{line}", style="dim")
+    return text
+
+
+def truncate_text(text: str, max_length: int = 500, suffix: str = "...") -> str:
+    """
+    Truncate text to maximum length.
+
+    Args:
+        text: Text to truncate
+        max_length: Maximum character length
+        suffix: Suffix to add if truncated
+    """
+    if len(text) <= max_length:
+        return text
+    return text[:max_length - len(suffix)] + suffix
+
+
+def strip_ansi(text: str) -> str:
+    """Remove ANSI escape codes from text."""
+    ansi_pattern = re.compile(r'\x1b\[[0-9;]*m')
+    return ansi_pattern.sub('', text)

webber-api/src/domains/agents/__init__.py

@@ -0,0 +1,37 @@
+"""
+Agent implementations.
+
+All agents inherit from BaseAgent and are registered in the global registry.
+"""
+from src.domains.agents.base import (
+    BaseAgent,
+    AgentContext,
+    AgentProtocol,
+    register_agent,
+    get_agent,
+    list_agents,
+    get_registry,
+)
+from src.domains.agents.explore import (
+    ExploreAgentImpl,
+    ExploreContext,
+    explore_agent,
+    explore,
+)
+
+__all__ = [
+    # Base classes
+    "BaseAgent",
+    "AgentContext",
+    "AgentProtocol",
+    # Registry functions
+    "register_agent",
+    "get_agent",
+    "list_agents",
+    "get_registry",
+    # Explore agent
+    "ExploreAgentImpl",
+    "ExploreContext",
+    "explore_agent",
+    "explore",
+]

webber-api/src/domains/agents/base.py

@@ -0,0 +1,184 @@
+"""
+Base classes and registry for agent implementations.
+
+All agents are built on PydanticAI and registered in a central registry.
+"""
+from abc import ABC, abstractmethod
+from collections.abc import AsyncIterator
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+from pydantic_ai import Agent
+
+from src.shared.logging import get_logger
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class AgentContext:
+    """
+    Base context passed to all agent tools.
+
+    Subclass this for agent-specific context (e.g., ExploreContext).
+    """
+    working_dir: str
+    allowed_paths: list[str] = field(default_factory=list)
+    timeout_seconds: int = 120
+
+
+@runtime_checkable
+class AgentProtocol(Protocol):
+    """Protocol that all agents must implement."""
+
+    @property
+    def name(self) -> str:
+        """Unique identifier for the agent."""
+        ...
+
+    @property
+    def description(self) -> str:
+        """Human-readable description of what the agent does."""
+        ...
+
+    @property
+    def agent(self) -> Agent:
+        """The underlying PydanticAI agent."""
+        ...
+
+    async def run(self, prompt: str, **kwargs: Any) -> str:
+        """
+        Execute the agent with a prompt.
+
+        Args:
+            prompt: User prompt/query
+            **kwargs: Additional arguments (working_dir, etc.)
+
+        Returns:
+            Agent response as string
+        """
+        ...
+
+
+class BaseAgent(ABC):
+    """
+    Abstract base class for agent implementations.
+
+    Provides common functionality and enforces interface.
+
+    Usage:
+        class ExploreAgent(BaseAgent):
+            name = "explore"
+            description = "Fast codebase exploration"
+
+            def _create_agent(self) -> Agent:
+                # Create and configure PydanticAI agent
+                ...
+
+            async def run(self, prompt: str, **kwargs) -> str:
+                # Execute agent
+                ...
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Unique identifier for the agent."""
+        pass
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """Human-readable description."""
+        pass
+
+    @property
+    def agent(self) -> Agent:
+        """Lazy-loaded PydanticAI agent."""
+        if not hasattr(self, '_agent') or self._agent is None:
+            self._agent = self._create_agent()
+        return self._agent
+
+    @abstractmethod
+    def _create_agent(self) -> Agent:
+        """
+        Create and configure the PydanticAI agent.
+
+        Override this to set up model, system prompt, and tools.
+        """
+        pass
+
+    @abstractmethod
+    async def run(self, prompt: str, **kwargs: Any) -> str:
+        """Execute the agent."""
+        pass
+
+    async def run_stream(
+        self, prompt: str, **kwargs: Any
+    ) -> AsyncIterator[str]:
+        """
+        Execute the agent with streaming output.
+
+        Default implementation falls back to non-streaming run().
+        Override this for true streaming support.
+
+        Yields:
+            Text chunks as they become available
+        """
+        # Default: fall back to non-streaming
+        result = await self.run(prompt, **kwargs)
+        yield result
+
+
+# === Agent Registry ===
+
+_AGENT_REGISTRY: dict[str, BaseAgent] = {}
+
+
+def register_agent(agent: BaseAgent) -> BaseAgent:
+    """
+    Register an agent in the global registry.
+
+    Args:
+        agent: Agent instance to register
+
+    Returns:
+        The registered agent (for decorator chaining)
+    """
+    if agent.name in _AGENT_REGISTRY:
+        logger.warning(f"Overwriting existing agent: {agent.name}")
+
+    _AGENT_REGISTRY[agent.name] = agent
+    logger.info(f"Registered agent: {agent.name}")
+    return agent
+
+
+def get_agent(name: str) -> BaseAgent | None:
+    """
+    Get an agent by name.
+
+    Args:
+        name: Agent name
+
+    Returns:
+        Agent instance or None if not found
+    """
+    return _AGENT_REGISTRY.get(name)
+
+
+def list_agents() -> list[dict[str, str]]:
+    """
+    List all registered agents.
+
+    Returns:
+        List of agent info dicts with name and description
+    """
+    return [
+        {"name": agent.name, "description": agent.description}
+        for agent in _AGENT_REGISTRY.values()
+    ]
+
+
+def get_registry() -> dict[str, BaseAgent]:
+    """Get the full agent registry."""
+    return _AGENT_REGISTRY.copy()

webber-api/src/domains/agents/explore/__init__.py

@@ -0,0 +1,16 @@
+"""
+Explore Agent - Fast codebase exploration.
+"""
+from src.domains.agents.explore.agent import (
+    ExploreAgentImpl,
+    ExploreContext,
+    explore_agent,
+    explore,
+)
+
+__all__ = [
+    "ExploreAgentImpl",
+    "ExploreContext",
+    "explore_agent",
+    "explore",
+]

webber-api/src/domains/agents/explore/agent.py

@@ -0,0 +1,166 @@
+"""
+Explore Agent implementation using PydanticAI.
+
+Fast codebase exploration with read-only tools.
+Uses sanitized Ollama provider for reliable tool calling.
+"""
+import os
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic_ai import Agent
+from pydantic_ai.models.openai import OpenAIModel
+
+from src.domains.agents.base import BaseAgent, AgentContext, register_agent
+from src.domains.agents.explore.prompts import EXPLORE_SYSTEM_PROMPT
+from src.ollama.provider import get_ollama_provider
+from src.shared.config import get_settings
+from src.shared.logging import logged, get_logger, trace_span
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class ExploreContext(AgentContext):
+    """
+    Context for explore agent tools.
+
+    Passed to all tool functions via RunContext.
+    """
+    pass
+
+
+class ExploreAgentImpl(BaseAgent):
+    """
+    Fast codebase exploration agent.
+
+    Uses glob, grep, read, and bash tools to search and analyze codebases.
+    Read-only mode - cannot modify files.
+    """
+
+    name = "explore"
+    description = "Fast codebase exploration - find files, search content, read code"
+
+    def __init__(self):
+        """Initialize the explore agent."""
+        self._agent: Agent[ExploreContext, str] | None = None
+        self._settings = get_settings()
+
+    def _create_agent(self) -> Agent[ExploreContext, str]:
+        """Create the PydanticAI agent with Ollama backend."""
+        # Use sanitized Ollama provider to fix content: null issues
+        model = OpenAIModel(
+            model_name=self._settings.ollama_agent_model,
+            provider=get_ollama_provider(),
+        )
+
+        agent: Agent[ExploreContext, str] = Agent(
+            model=model,
+            system_prompt=EXPLORE_SYSTEM_PROMPT,
+            deps_type=ExploreContext,
+            output_type=str,
+            # Mistral Nemo settings:
+            # - temperature 0.3 (Nemo needs slightly higher than 0.0)
+            # - tool_choice "required" forces tool use
+            model_settings={
+                "temperature": 0.3,
+                "extra_body": {"tool_choice": "required"},
+            },
+        )
+
+        # Register tools
+        self._register_tools(agent)
+
+        return agent
+
+    def _register_tools(self, agent: Agent[ExploreContext, str]) -> None:
+        """Register all exploration tools with the agent."""
+        from src.domains.agents.explore.tools import register_explore_tools
+        register_explore_tools(agent)
+
+    @logged()
+    async def run(
+        self,
+        prompt: str,
+        working_dir: str | None = None,
+        allowed_paths: list[str] | None = None,
+        **kwargs: Any
+    ) -> str:
+        """
+        Run the explore agent with a prompt.
+
+        Args:
+            prompt: User query about the codebase
+            working_dir: Working directory for exploration
+            allowed_paths: Restrict tool access to these paths
+
+        Returns:
+            Agent response with findings
+        """
+        ctx = ExploreContext(
+            working_dir=working_dir or os.getcwd(),
+            allowed_paths=allowed_paths or self._settings.effective_allowed_paths,
+            timeout_seconds=self._settings.tool_timeout_seconds,
+        )
+
+        async with trace_span("explore_agent_run"):
+            try:
+                # Use run() not run_stream() - Ollama has bugs with streaming + tools
+                result = await self.agent.run(prompt, deps=ctx)
+                return result.output
+            except Exception as e:
+                logger.exception(f"Explore agent error: {e}")
+                raise
+
+
+    async def run_stream(
+        self,
+        prompt: str,
+        working_dir: str | None = None,
+        allowed_paths: list[str] | None = None,
+        **kwargs: Any
+    ) -> AsyncIterator[str]:
+        """
+        Run the explore agent with streaming output.
+
+        Yields text chunks as they become available.
+        """
+        ctx = ExploreContext(
+            working_dir=working_dir or os.getcwd(),
+            allowed_paths=allowed_paths or self._settings.effective_allowed_paths,
+            timeout_seconds=self._settings.tool_timeout_seconds,
+        )
+
+        async with trace_span("explore_agent_stream"):
+            try:
+                async with self.agent.run_stream(prompt, deps=ctx) as result:
+                    async for chunk in result.stream_text():
+                        yield chunk
+            except Exception as e:
+                logger.exception(f"Explore agent stream error: {e}")
+                raise
+
+
+# Create and register the singleton instance
+explore_agent = ExploreAgentImpl()
+register_agent(explore_agent)
+
+
+async def explore(
+    prompt: str,
+    working_dir: str | None = None,
+    **kwargs: Any
+) -> str:
+    """Run exploration query."""
+    return await explore_agent.run(prompt, working_dir=working_dir, **kwargs)
+
+
+async def explore_stream(
+    prompt: str,
+    working_dir: str | None = None,
+    **kwargs: Any
+) -> AsyncIterator[str]:
+    """Run exploration query with streaming."""
+    async for chunk in explore_agent.run_stream(prompt, working_dir=working_dir, **kwargs):
+        yield chunk

webber-api/src/domains/agents/explore/prompts.py

@@ -0,0 +1,98 @@
+"""
+System prompts for the Explore agent.
+
+Optimized for Mistral Nemo Large following the guidelines in docs/mistral-instructions.md:
+- Temperature 0.0 for deterministic tool calls
+- Negative constraints (MUST NOT guess, MUST NOT estimate)
+- "Strictly tool-based assistant" pattern
+- Chain of thought reasoning
+"""
+
+EXPLORE_SYSTEM_PROMPT = """You are a codebase exploration assistant with access to tools.
+
+CRITICAL: You MUST provide ALL required arguments when calling tools.
+
+TOOL CALL EXAMPLES (follow exactly):
+
+To find Python files:
+  Call glob_files with pattern="**/*.py"
+
+To find a specific file:
+  Call glob_files with pattern="**/config.py"
+
+To read a file:
+  Call read_file with file_path="/absolute/path/to/file.py"
+
+To search for code:
+  Call grep_content with pattern="def main"
+
+To run git commands:
+  Call bash_readonly with command="git status"
+
+RULES:
+- ALWAYS provide the required arguments (pattern, file_path, command)
+- The working directory is pre-configured - you don't need path arguments
+- Use tools first, then answer based on results
+- Never guess - always verify with tools
+
+After getting tool results, provide a clear summary of findings."""
+
+
+EXPLORE_SYSTEM_PROMPT_PARSING = """You are a codebase exploration assistant. Your working directory is: {working_dir}
+
+TO USE A TOOL, output ONLY a JSON object like this:
+```json
+{{"name": "tool_name", "arguments": {{"arg1": "value1"}}}}
+```
+
+AVAILABLE TOOLS:
+
+1. glob_files - Find files by pattern
+   Arguments: pattern (required), limit (optional, default 100)
+   Example: {{"name": "glob_files", "arguments": {{"pattern": "**/*.py"}}}}
+
+2. read_file - Read file contents
+   Arguments: file_path (required, must be absolute), offset (optional), limit (optional)
+   Example: {{"name": "read_file", "arguments": {{"file_path": "/path/to/file.py"}}}}
+
+3. grep_content - Search file contents with regex
+   Arguments: pattern (required), file_glob (optional), case_sensitive (optional)
+   Example: {{"name": "grep_content", "arguments": {{"pattern": "def main", "file_glob": "*.py"}}}}
+
+4. bash_readonly - Run read-only shell commands (ls, git status, git log, etc.)
+   Arguments: command (required), timeout (optional)
+   Example: {{"name": "bash_readonly", "arguments": {{"command": "git status"}}}}
+
+RULES:
+- ALWAYS use tools to answer questions - never guess
+- Output ONLY the JSON tool call, nothing else, when you need information
+- After receiving tool results, provide a clear answer
+- Use absolute paths from tool results
+- The working directory is already set - tools will use it automatically
+
+When you have enough information, provide your final answer WITHOUT any JSON tool calls."""
+
+
+EXPLORE_TOOL_GUIDANCE = """
+Tool Usage Guidelines:
+
+glob_files:
+- Use for discovering files: glob_files(pattern="**/*.py")
+- Filter by directory: glob_files(pattern="*.ts", path="src/")
+- Find test files: glob_files(pattern="**/test_*.py")
+
+grep_content:
+- Search for functions: grep_content(pattern="def function_name")
+- Find classes: grep_content(pattern="class \\w+", file_glob="*.py")
+- Search imports: grep_content(pattern="from.*import", file_glob="*.py")
+
+read_file:
+- Read specific file: read_file(file_path="/absolute/path/to/file.py")
+- Read portion: read_file(file_path="/path/file.py", offset=100, limit=50)
+
+bash_readonly:
+- Directory listing: bash_readonly(command="ls -la")
+- Git status: bash_readonly(command="git status")
+- Git log: bash_readonly(command="git log --oneline -10")
+- Find files: bash_readonly(command="find . -name '*.md' -type f")
+"""

webber-api/src/domains/agents/explore/tools.py

@@ -0,0 +1,313 @@
+"""
+Tool registrations for the Explore agent.
+
+Registers our tool implementations with the PydanticAI agent.
+"""
+from pydantic_ai import Agent, RunContext
+
+from src.domains.agents.base import AgentContext
+from src.domains.tools.file.read import ReadFileTool
+from src.domains.tools.file.glob import GlobFilesTool
+from src.domains.tools.file.edit import EditFileTool
+from src.domains.tools.file.write import WriteFileTool
+from src.domains.tools.search.grep import GrepContentTool
+from src.domains.tools.search.web import WebSearchTool
+from src.domains.tools.shell.bash import BashReadOnlyTool
+from src.domains.tools.shell.bash_full import BashTool
+
+
+def register_explore_tools(agent: Agent[AgentContext, str]) -> None:
+    """
+    Register all exploration tools with the agent.
+
+    Each tool is wrapped to use context from RunContext.
+    """
+
+    @agent.tool
+    async def read_file(
+        ctx: RunContext[AgentContext],
+        file_path: str,
+        offset: int = 0,
+        limit: int = 2000
+    ) -> str:
+        """Read contents of a file with line numbers.
+
+        Args:
+            file_path: Absolute path to the file to read
+            offset: Line number to start from (0-based, default: 0)
+            limit: Maximum number of lines to read (default: 2000)
+
+        Returns:
+            File contents with line numbers, or error message.
+
+        IMPORTANT: Always use absolute paths. Never guess file contents.
+        """
+        tool = ReadFileTool(allowed_paths=ctx.deps.allowed_paths)
+        result = await tool.execute(
+            file_path=file_path,
+            offset=offset,
+            limit=limit
+        )
+        return result.to_string()
+
+    @agent.tool
+    async def glob_files(
+        ctx: RunContext[AgentContext],
+        pattern: str,
+        path: str | None = None,
+        limit: int = 100
+    ) -> str:
+        """Find files matching a glob pattern.
+
+        Args:
+            pattern: Glob pattern (e.g., "**/*.py", "src/**/*.ts", "*.md")
+            path: Directory to search in (default: working directory)
+            limit: Maximum number of files to return (default: 100)
+
+        Returns:
+            List of absolute file paths, sorted by modification time (newest first).
+
+        Examples:
+            - "**/*.py" finds all Python files
+            - "src/**/*.ts" finds TypeScript files in src/
+            - "**/test_*.py" finds all test files
+
+        IMPORTANT: Use this to discover files before reading them.
+        """
+        tool = GlobFilesTool(allowed_paths=ctx.deps.allowed_paths)
+        search_path = path or ctx.deps.working_dir
+        result = await tool.execute(
+            pattern=pattern,
+            path=search_path,
+            limit=limit
+        )
+        return result.to_string()
+
+    @agent.tool
+    async def grep_content(
+        ctx: RunContext[AgentContext],
+        pattern: str,
+        path: str | None = None,
+        file_glob: str | None = None,
+        context_lines: int = 0,
+        case_sensitive: bool = True
+    ) -> str:
+        """Search file contents using regex pattern.
+
+        Args:
+            pattern: Regex pattern to search for (Python re syntax)
+            path: Directory or file to search (default: working directory)
+            file_glob: Filter files by glob (e.g., "*.py", "*.ts")
+            context_lines: Lines of context before/after matches (default: 0)
+            case_sensitive: Case-sensitive search (default: True)
+
+        Returns:
+            Matching lines with file paths and line numbers.
+            Format: "filepath:line_num: content"
+
+        Examples:
+            - pattern="def.*__init__" finds init methods
+            - pattern="class\\s+\\w+" finds class definitions
+            - pattern="TODO|FIXME" finds todo comments
+
+        IMPORTANT: Use this to search for code patterns. Escape regex special chars.
+        """
+        tool = GrepContentTool(allowed_paths=ctx.deps.allowed_paths)
+        search_path = path or ctx.deps.working_dir
+        result = await tool.execute(
+            pattern=pattern,
+            path=search_path,
+            file_glob=file_glob,
+            context_lines=context_lines,
+            case_sensitive=case_sensitive
+        )
+        return result.to_string()
+
+    @agent.tool
+    async def bash_readonly(
+        ctx: RunContext[AgentContext],
+        command: str,
+        cwd: str | None = None,
+        timeout: int = 30
+    ) -> str:
+        """Execute a read-only bash command.
+
+        ALLOWED commands:
+        - File inspection: ls, find, cat, head, tail, wc, file, stat, tree, du
+        - Git (read-only): git status, git log, git diff, git show, git branch
+        - Text processing: grep, awk, sed (read-only), sort, uniq
+        - System info: pwd, whoami, hostname, which
+
+        FORBIDDEN:
+        - File modification (rm, mv, cp, mkdir, touch)
+        - Redirects (>, >>)
+        - Command chaining (&&, ||, ;)
+        - Network (curl, wget)
+
+        Args:
+            command: The bash command to execute
+            cwd: Working directory (default: agent working directory)
+            timeout: Timeout in seconds (default: 30)
+
+        Returns:
+            Command output or error message.
+
+        Examples:
+            - "ls -la" lists files with details
+            - "git status" shows git status
+            - "git log --oneline -10" shows recent commits
+        """
+        tool = BashReadOnlyTool(allowed_paths=ctx.deps.allowed_paths)
+        working_dir = cwd or ctx.deps.working_dir
+        result = await tool.execute(
+            command=command,
+            cwd=working_dir,
+            timeout=min(timeout, ctx.deps.timeout_seconds)
+        )
+        return result.to_string()
+
+    # === Write-capable tools ===
+
+    @agent.tool
+    async def edit_file(
+        ctx: RunContext[AgentContext],
+        file_path: str,
+        old_string: str,
+        new_string: str,
+        replace_all: bool = False
+    ) -> str:
+        """Make targeted edits to a file using find-and-replace.
+
+        Args:
+            file_path: Absolute path to the file to edit
+            old_string: The exact text to find and replace (must exist in file)
+            new_string: The replacement text
+            replace_all: If True, replace all occurrences. If False (default),
+                         old_string must be unique (appear exactly once).
+
+        Returns:
+            Success message with diff preview, or error.
+
+        IMPORTANT:
+        - old_string must exactly match file content (including whitespace)
+        - By default, old_string must appear exactly once (for safety)
+        - Always read the file first to verify exact content before editing
+        """
+        tool = EditFileTool(allowed_paths=ctx.deps.allowed_paths)
+        result = await tool.execute(
+            file_path=file_path,
+            old_string=old_string,
+            new_string=new_string,
+            replace_all=replace_all
+        )
+        return result.to_string()
+
+    @agent.tool
+    async def write_file(
+        ctx: RunContext[AgentContext],
+        file_path: str,
+        content: str
+    ) -> str:
+        """Create a new file or overwrite an existing file.
+
+        Args:
+            file_path: Absolute path to the file to create/write
+            content: The content to write to the file
+
+        Returns:
+            Success message with file path and size.
+
+        IMPORTANT:
+        - Parent directory must exist (use mkdir first if needed)
+        - For editing existing files, prefer edit_file instead
+        - Will overwrite existing files without confirmation
+        """
+        tool = WriteFileTool(allowed_paths=ctx.deps.allowed_paths)
+        result = await tool.execute(
+            file_path=file_path,
+            content=content
+        )
+        return result.to_string()
+
+    @agent.tool
+    async def bash(
+        ctx: RunContext[AgentContext],
+        command: str,
+        cwd: str | None = None,
+        timeout: int = 60
+    ) -> str:
+        """Execute a bash command with write capabilities.
+
+        ALLOWED:
+        - File operations: ls, find, mkdir, touch, cp, mv, rm (single files)
+        - Git (full): git add, git commit, git checkout, git merge, git pull
+        - Python: python, pip install, pytest, mypy, ruff
+        - Text processing: grep, awk, sed, sort
+        - Command chaining: && and || are allowed
+
+        FORBIDDEN:
+        - sudo, su (privilege escalation)
+        - Network: curl, wget, ssh, scp, rsync
+        - Dangerous: rm -rf, chmod 777, dd, mkfs
+
+        Args:
+            command: The bash command to execute
+            cwd: Working directory (default: agent working directory)
+            timeout: Timeout in seconds (default: 60)
+
+        Returns:
+            Command output or error message.
+
+        Examples:
+            - "mkdir -p src/utils" creates directory
+            - "git add . && git commit -m 'fix: bug'" commits changes
+            - "pytest tests/ -v" runs tests
+            - "rm old_file.py" removes single file
+        """
+        tool = BashTool(allowed_paths=ctx.deps.allowed_paths)
+        working_dir = cwd or ctx.deps.working_dir
+        result = await tool.execute(
+            command=command,
+            cwd=working_dir,
+            timeout=min(timeout, ctx.deps.timeout_seconds)
+        )
+        return result.to_string()
+
+    # === Web search ===
+
+    @agent.tool
+    async def web_search(
+        ctx: RunContext[AgentContext],
+        query: str,
+        num_results: int = 5,
+        categories: str | None = None
+    ) -> str:
+        """Search the web for current information.
+
+        Args:
+            query: Search query (e.g., "Python 3.12 new features")
+            num_results: Number of results to return (1-10, default: 5)
+            categories: Optional category filter ("general", "it", "news", "science")
+
+        Returns:
+            Search results with titles, URLs, and snippets.
+
+        Use this for:
+        - Current events or recent information
+        - Documentation updates since your training
+        - Facts you're uncertain about
+        - Technical references with URLs
+
+        IMPORTANT: Always include a "Sources:" section with URLs in your response.
+
+        Examples:
+            - query="FastAPI best practices 2024"
+            - query="CVE-2024" categories="it"
+        """
+        tool = WebSearchTool()
+        result = await tool.execute(
+            query=query,
+            num_results=num_results,
+            categories=categories
+        )
+        return result.to_string()

webber-api/src/domains/agents/plan/__init__.py

@@ -0,0 +1,30 @@
+"""
+Plan Agent - Software architect for implementation planning.
+
+The Plan agent explores codebases and designs step-by-step implementation
+strategies. It uses only read-only tools and cannot modify any files.
+
+Usage:
+    from src.domains.agents.plan import plan_agent, plan
+
+    # Direct agent access
+    result = await plan_agent.run("Plan how to add user authentication")
+
+    # Convenience function
+    result = await plan("Plan how to add user authentication")
+"""
+from src.domains.agents.plan.agent import (
+    PlanAgentImpl,
+    PlanContext,
+    plan_agent,
+    plan,
+    plan_stream,
+)
+
+__all__ = [
+    "PlanAgentImpl",
+    "PlanContext",
+    "plan_agent",
+    "plan",
+    "plan_stream",
+]

webber-api/src/domains/agents/plan/agent.py

@@ -0,0 +1,168 @@
+"""
+Plan Agent implementation using PydanticAI.
+
+Software architect agent that explores codebases and designs implementation plans.
+Uses only read-only tools - cannot modify any files.
+"""
+import os
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic_ai import Agent
+from pydantic_ai.models.openai import OpenAIModel
+
+from src.domains.agents.base import BaseAgent, AgentContext, register_agent
+from src.domains.agents.plan.prompts import PLAN_SYSTEM_PROMPT
+from src.ollama.provider import get_ollama_provider
+from src.shared.config import get_settings
+from src.shared.logging import logged, get_logger, trace_span
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class PlanContext(AgentContext):
+    """
+    Context for plan agent tools.
+
+    Passed to all tool functions via RunContext.
+    Uses the same fields as base AgentContext.
+    """
+    pass
+
+
+class PlanAgentImpl(BaseAgent):
+    """
+    Software architect agent for implementation planning.
+
+    Explores codebases to understand patterns and conventions,
+    then designs step-by-step implementation plans.
+
+    READ-ONLY: Cannot modify files - uses only exploration tools.
+    """
+
+    name = "plan"
+    description = "Software architect for designing implementation plans - explores codebase and creates step-by-step strategies"
+
+    def __init__(self):
+        """Initialize the plan agent."""
+        self._agent: Agent[PlanContext, str] | None = None
+        self._settings = get_settings()
+
+    def _create_agent(self) -> Agent[PlanContext, str]:
+        """Create the PydanticAI agent with Ollama backend."""
+        # Use sanitized Ollama provider to fix content: null issues
+        model = OpenAIModel(
+            model_name=self._settings.ollama_agent_model,
+            provider=get_ollama_provider(),
+        )
+
+        agent: Agent[PlanContext, str] = Agent(
+            model=model,
+            system_prompt=PLAN_SYSTEM_PROMPT,
+            deps_type=PlanContext,
+            output_type=str,
+            # Mistral Nemo settings:
+            # - temperature 0.3 (Nemo needs slightly higher than 0.0)
+            # - tool_choice "required" forces tool use
+            model_settings={
+                "temperature": 0.3,
+                "extra_body": {"tool_choice": "required"},
+            },
+        )
+
+        # Register read-only tools
+        self._register_tools(agent)
+
+        return agent
+
+    def _register_tools(self, agent: Agent[PlanContext, str]) -> None:
+        """Register read-only exploration tools with the agent."""
+        from src.domains.agents.plan.tools import register_plan_tools
+        register_plan_tools(agent)
+
+    @logged()
+    async def run(
+        self,
+        prompt: str,
+        working_dir: str | None = None,
+        allowed_paths: list[str] | None = None,
+        **kwargs: Any
+    ) -> str:
+        """
+        Run the plan agent to design an implementation strategy.
+
+        Args:
+            prompt: Description of what to implement
+            working_dir: Working directory for exploration
+            allowed_paths: Restrict tool access to these paths
+
+        Returns:
+            Implementation plan with steps and critical files
+        """
+        ctx = PlanContext(
+            working_dir=working_dir or os.getcwd(),
+            allowed_paths=allowed_paths or self._settings.effective_allowed_paths,
+            timeout_seconds=self._settings.tool_timeout_seconds,
+        )
+
+        async with trace_span("plan_agent_run"):
+            try:
+                # Use run() not run_stream() - Ollama has bugs with streaming + tools
+                result = await self.agent.run(prompt, deps=ctx)
+                return result.output
+            except Exception as e:
+                logger.exception(f"Plan agent error: {e}")
+                raise
+
+    async def run_stream(
+        self,
+        prompt: str,
+        working_dir: str | None = None,
+        allowed_paths: list[str] | None = None,
+        **kwargs: Any
+    ) -> AsyncIterator[str]:
+        """
+        Run the plan agent with streaming output.
+
+        Yields text chunks as they become available.
+        """
+        ctx = PlanContext(
+            working_dir=working_dir or os.getcwd(),
+            allowed_paths=allowed_paths or self._settings.effective_allowed_paths,
+            timeout_seconds=self._settings.tool_timeout_seconds,
+        )
+
+        async with trace_span("plan_agent_stream"):
+            try:
+                async with self.agent.run_stream(prompt, deps=ctx) as result:
+                    async for chunk in result.stream_text():
+                        yield chunk
+            except Exception as e:
+                logger.exception(f"Plan agent stream error: {e}")
+                raise
+
+
+# Create and register the singleton instance
+plan_agent = PlanAgentImpl()
+register_agent(plan_agent)
+
+
+async def plan(
+    prompt: str,
+    working_dir: str | None = None,
+    **kwargs: Any
+) -> str:
+    """Run planning query."""
+    return await plan_agent.run(prompt, working_dir=working_dir, **kwargs)
+
+
+async def plan_stream(
+    prompt: str,
+    working_dir: str | None = None,
+    **kwargs: Any
+) -> AsyncIterator[str]:
+    """Run planning query with streaming."""
+    async for chunk in plan_agent.run_stream(prompt, working_dir=working_dir, **kwargs):
+        yield chunk

webber-api/src/domains/agents/plan/prompts.py

@@ -0,0 +1,63 @@
+"""
+System prompts for the Plan agent.
+
+The Plan agent is a READ-ONLY software architect that explores codebases
+and designs implementation plans without modifying any files.
+"""
+
+PLAN_SYSTEM_PROMPT = """You are a software architect and planning specialist.
+
+Your role is to explore codebases and design implementation plans.
+
+CRITICAL: You are READ-ONLY. You CANNOT modify any files.
+
+AVAILABLE TOOLS:
+- glob_files: Find files by pattern
+- read_file: Read file contents
+- grep_content: Search code with regex
+- bash_readonly: Run read-only commands (ls, git status, git log, etc.)
+
+WORKFLOW:
+1. Understand the requirements
+2. Explore the codebase to find relevant patterns and conventions
+3. Design an implementation approach
+4. Create a step-by-step plan with specific files and changes
+
+TOOL CALL EXAMPLES (follow exactly):
+
+To find Python files:
+  Call glob_files with pattern="**/*.py"
+
+To find a specific file:
+  Call glob_files with pattern="**/config.py"
+
+To read a file:
+  Call read_file with file_path="/absolute/path/to/file.py"
+
+To search for code patterns:
+  Call grep_content with pattern="class.*Controller"
+
+To check git history:
+  Call bash_readonly with command="git log --oneline -10"
+
+OUTPUT FORMAT:
+End your response with:
+
+### Implementation Steps
+1. [First step with specific file and changes]
+2. [Second step...]
+3. [Continue...]
+
+### Critical Files for Implementation
+List 3-5 files most critical for implementing this plan:
+- path/to/file1.py - [Brief reason: e.g., "Core logic to modify"]
+- path/to/file2.py - [Brief reason: e.g., "Pattern to follow"]
+
+RULES:
+- ALWAYS use tools first, then analyze results
+- Follow existing patterns in the codebase
+- Consider trade-offs and alternatives
+- Identify dependencies and sequencing
+- Never guess - verify with tools
+- Provide specific file paths and code locations
+"""

webber-api/src/domains/agents/plan/tools.py

@@ -0,0 +1,170 @@
+"""
+Tool registrations for the Plan agent.
+
+The Plan agent only has access to READ-ONLY tools.
+It cannot modify files - only explore and analyze.
+"""
+from pydantic_ai import Agent, RunContext
+
+from src.domains.agents.base import AgentContext
+from src.domains.tools.file.read import ReadFileTool
+from src.domains.tools.file.glob import GlobFilesTool
+from src.domains.tools.search.grep import GrepContentTool
+from src.domains.tools.shell.bash import BashReadOnlyTool
+
+
+def register_plan_tools(agent: Agent[AgentContext, str]) -> None:
+    """
+    Register read-only exploration tools with the Plan agent.
+
+    The Plan agent is restricted to read-only tools:
+    - read_file: Read file contents
+    - glob_files: Find files by pattern
+    - grep_content: Search file contents
+    - bash_readonly: Read-only shell commands
+
+    Write tools (edit_file, write_file, bash) are NOT available.
+    """
+
+    @agent.tool
+    async def read_file(
+        ctx: RunContext[AgentContext],
+        file_path: str,
+        offset: int = 0,
+        limit: int = 2000
+    ) -> str:
+        """Read contents of a file with line numbers.
+
+        Args:
+            file_path: Absolute path to the file to read
+            offset: Line number to start from (0-based, default: 0)
+            limit: Maximum number of lines to read (default: 2000)
+
+        Returns:
+            File contents with line numbers, or error message.
+
+        IMPORTANT: Always use absolute paths. Use this to understand existing code.
+        """
+        tool = ReadFileTool(allowed_paths=ctx.deps.allowed_paths)
+        result = await tool.execute(
+            file_path=file_path,
+            offset=offset,
+            limit=limit
+        )
+        return result.to_string()
+
+    @agent.tool
+    async def glob_files(
+        ctx: RunContext[AgentContext],
+        pattern: str,
+        path: str | None = None,
+        limit: int = 100
+    ) -> str:
+        """Find files matching a glob pattern.
+
+        Args:
+            pattern: Glob pattern (e.g., "**/*.py", "src/**/*.ts", "*.md")
+            path: Directory to search in (default: working directory)
+            limit: Maximum number of files to return (default: 100)
+
+        Returns:
+            List of absolute file paths, sorted by modification time (newest first).
+
+        Examples:
+            - "**/*.py" finds all Python files
+            - "src/**/*.ts" finds TypeScript files in src/
+            - "**/test_*.py" finds all test files
+
+        IMPORTANT: Use this to discover files before reading them.
+        """
+        tool = GlobFilesTool(allowed_paths=ctx.deps.allowed_paths)
+        search_path = path or ctx.deps.working_dir
+        result = await tool.execute(
+            pattern=pattern,
+            path=search_path,
+            limit=limit
+        )
+        return result.to_string()
+
+    @agent.tool
+    async def grep_content(
+        ctx: RunContext[AgentContext],
+        pattern: str,
+        path: str | None = None,
+        file_glob: str | None = None,
+        context_lines: int = 0,
+        case_sensitive: bool = True
+    ) -> str:
+        """Search file contents using regex pattern.
+
+        Args:
+            pattern: Regex pattern to search for (Python re syntax)
+            path: Directory or file to search (default: working directory)
+            file_glob: Filter files by glob (e.g., "*.py", "*.ts")
+            context_lines: Lines of context before/after matches (default: 0)
+            case_sensitive: Case-sensitive search (default: True)
+
+        Returns:
+            Matching lines with file paths and line numbers.
+            Format: "filepath:line_num: content"
+
+        Examples:
+            - pattern="def.*__init__" finds init methods
+            - pattern="class\\s+\\w+" finds class definitions
+            - pattern="TODO|FIXME" finds todo comments
+
+        IMPORTANT: Use this to find code patterns and implementations.
+        """
+        tool = GrepContentTool(allowed_paths=ctx.deps.allowed_paths)
+        search_path = path or ctx.deps.working_dir
+        result = await tool.execute(
+            pattern=pattern,
+            path=search_path,
+            file_glob=file_glob,
+            context_lines=context_lines,
+            case_sensitive=case_sensitive
+        )
+        return result.to_string()
+
+    @agent.tool
+    async def bash_readonly(
+        ctx: RunContext[AgentContext],
+        command: str,
+        cwd: str | None = None,
+        timeout: int = 30
+    ) -> str:
+        """Execute a read-only bash command.
+
+        ALLOWED commands:
+        - File inspection: ls, find, cat, head, tail, wc, file, stat, tree, du
+        - Git (read-only): git status, git log, git diff, git show, git branch
+        - Text processing: grep, awk, sed (read-only), sort, uniq
+        - System info: pwd, whoami, hostname, which
+
+        FORBIDDEN:
+        - File modification (rm, mv, cp, mkdir, touch)
+        - Redirects (>, >>)
+        - Command chaining (&&, ||, ;)
+        - Network (curl, wget)
+
+        Args:
+            command: The bash command to execute
+            cwd: Working directory (default: agent working directory)
+            timeout: Timeout in seconds (default: 30)
+
+        Returns:
+            Command output or error message.
+
+        Examples:
+            - "ls -la" lists files with details
+            - "git status" shows git status
+            - "git log --oneline -10" shows recent commits
+        """
+        tool = BashReadOnlyTool(allowed_paths=ctx.deps.allowed_paths)
+        working_dir = cwd or ctx.deps.working_dir
+        result = await tool.execute(
+            command=command,
+            cwd=working_dir,
+            timeout=min(timeout, ctx.deps.timeout_seconds)
+        )
+        return result.to_string()

webber-api/src/domains/agents/router.py

@@ -0,0 +1,135 @@
+"""
+REST API routes for agents.
+"""
+import json
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import StreamingResponse
+
+from src.domains.agents.base import get_agent, list_agents
+
+# Import agents to ensure they're registered
+import src.domains.agents.explore  # noqa: F401
+import src.domains.agents.plan  # noqa: F401
+import src.domains.agents.task  # noqa: F401
+from src.domains.agents.schemas import (
+    AgentRunRequest,
+    AgentRunResponse,
+    AgentInfo,
+    AgentListResponse,
+)
+from src.shared.logging import logged, get_logger
+
+logger = get_logger(__name__)
+
+router = APIRouter(prefix="/agents", tags=["Agents"])
+
+
+@router.get("/", response_model=AgentListResponse)
+async def list_available_agents() -> AgentListResponse:
+    """List all available agents."""
+    agents = list_agents()
+    return AgentListResponse(
+        agents=[AgentInfo(**a) for a in agents]
+    )
+
+
+@router.post("/run", response_model=AgentRunResponse)
+@logged()
+async def run_agent(request: AgentRunRequest) -> AgentRunResponse:
+    """
+    Run an agent with the given prompt.
+
+    The agent will use tools to explore the codebase and answer questions.
+    """
+    # Get the requested agent
+    agent = get_agent(request.agent_type)
+    if not agent:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Unknown agent type: {request.agent_type}"
+        )
+
+    try:
+        # Run the agent
+        response = await agent.run(
+            request.prompt,
+            working_dir=request.working_dir,
+        )
+
+        return AgentRunResponse(
+            response=response,
+            agent_type=request.agent_type,
+            success=True,
+        )
+
+    except Exception as e:
+        logger.exception(f"Agent execution failed: {e}")
+        return AgentRunResponse(
+            response="",
+            agent_type=request.agent_type,
+            success=False,
+            error=str(e),
+        )
+
+
+@router.post("/stream")
+@logged()
+async def stream_agent(request: AgentRunRequest) -> StreamingResponse:
+    """
+    Run an agent with streaming response.
+
+    Returns Server-Sent Events (SSE) with text chunks.
+    Event types:
+    - "chunk": Text chunk from the agent
+    - "done": Stream complete
+    - "error": Error occurred
+    """
+    agent = get_agent(request.agent_type)
+    if not agent:
+        raise HTTPException(
+            status_code=400,
+            detail=f"Unknown agent type: {request.agent_type}"
+        )
+
+    async def generate():
+        try:
+            async for chunk in agent.run_stream(
+                request.prompt,
+                working_dir=request.working_dir,
+            ):
+                # SSE format: data: {json}\n\n
+                event = {"event": "chunk", "data": chunk}
+                yield f"data: {json.dumps(event)}\n\n"
+
+            # Signal completion
+            yield f"data: {json.dumps({'event': 'done'})}\n\n"
+
+        except Exception as e:
+            logger.exception(f"Stream error: {e}")
+            error_event = {"event": "error", "data": str(e)}
+            yield f"data: {json.dumps(error_event)}\n\n"
+
+    return StreamingResponse(
+        generate(),
+        media_type="text/event-stream",
+        headers={
+            "Cache-Control": "no-cache",
+            "Connection": "keep-alive",
+        }
+    )
+
+
+@router.get("/{agent_type}", response_model=AgentInfo)
+async def get_agent_info(agent_type: str) -> AgentInfo:
+    """Get information about a specific agent."""
+    agent = get_agent(agent_type)
+    if not agent:
+        raise HTTPException(
+            status_code=404,
+            detail=f"Agent not found: {agent_type}"
+        )
+
+    return AgentInfo(
+        name=agent.name,
+        description=agent.description,
+    )

webber-api/src/domains/agents/schemas.py

@@ -0,0 +1,30 @@
+"""
+Request and response schemas for agent API.
+"""
+from src.shared.base import BaseSchema
+
+
+class AgentRunRequest(BaseSchema):
+    """Request to run an agent."""
+    prompt: str
+    working_dir: str = "."
+    agent_type: str = "explore"
+
+
+class AgentRunResponse(BaseSchema):
+    """Response from agent execution."""
+    response: str
+    agent_type: str
+    success: bool = True
+    error: str | None = None
+
+
+class AgentInfo(BaseSchema):
+    """Information about an agent."""
+    name: str
+    description: str
+
+
+class AgentListResponse(BaseSchema):
+    """List of available agents."""
+    agents: list[AgentInfo]

webber-api/src/domains/agents/task/__init__.py

@@ -0,0 +1,33 @@
+"""
+Task Agent - Full orchestrator for autonomous task execution.
+
+The Task agent can:
+- Execute multi-step tasks autonomously
+- Use all tools (read + write + bash)
+- Spawn sub-agents (Explore, Plan) for focused work
+- Return consolidated task summaries
+
+Usage:
+    from src.domains.agents.task import task_agent, task
+
+    # Direct agent access
+    result = await task_agent.run("Create a new user model with tests")
+
+    # Convenience function
+    result = await task("Create a new user model with tests")
+"""
+from src.domains.agents.task.agent import (
+    TaskAgentImpl,
+    TaskContext,
+    task_agent,
+    task,
+    task_stream,
+)
+
+__all__ = [
+    "TaskAgentImpl",
+    "TaskContext",
+    "task_agent",
+    "task",
+    "task_stream",
+]

webber-api/src/domains/agents/task/agent.py

@@ -0,0 +1,174 @@
+"""
+Task Agent implementation using PydanticAI.
+
+Full orchestrator agent that can:
+- Execute multi-step tasks autonomously
+- Use all tools (read + write)
+- Spawn sub-agents (Explore, Plan) for focused work
+"""
+import os
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from typing import Any
+
+from pydantic_ai import Agent
+from pydantic_ai.models.openai import OpenAIModel
+
+from src.domains.agents.base import BaseAgent, AgentContext, register_agent
+from src.domains.agents.task.prompts import TASK_SYSTEM_PROMPT
+from src.ollama.provider import get_ollama_provider
+from src.shared.config import get_settings
+from src.shared.logging import logged, get_logger, trace_span
+
+logger = get_logger(__name__)
+
+
+@dataclass
+class TaskContext(AgentContext):
+    """
+    Context for task agent tools.
+
+    Passed to all tool functions via RunContext.
+    Uses the same fields as base AgentContext.
+    """
+    pass
+
+
+class TaskAgentImpl(BaseAgent):
+    """
+    Full orchestrator agent for autonomous task execution.
+
+    Has access to ALL tools:
+    - Read-only: read_file, glob_files, grep_content, bash_readonly
+    - Write: edit_file, write_file, bash
+    - External: web_search
+    - Orchestration: spawn_agent (launch sub-agents)
+
+    Can spawn Explore and Plan agents to offload focused tasks,
+    keeping context efficient across complex multi-step work.
+    """
+
+    name = "task"
+    description = "Autonomous multi-step task execution with sub-agent orchestration"
+
+    def __init__(self):
+        """Initialize the task agent."""
+        self._agent: Agent[TaskContext, str] | None = None
+        self._settings = get_settings()
+
+    def _create_agent(self) -> Agent[TaskContext, str]:
+        """Create the PydanticAI agent with Ollama backend."""
+        # Use sanitized Ollama provider to fix content: null issues
+        model = OpenAIModel(
+            model_name=self._settings.ollama_agent_model,
+            provider=get_ollama_provider(),
+        )
+
+        agent: Agent[TaskContext, str] = Agent(
+            model=model,
+            system_prompt=TASK_SYSTEM_PROMPT,
+            deps_type=TaskContext,
+            output_type=str,
+            # Mistral Nemo settings:
+            # - temperature 0.3 (Nemo needs slightly higher than 0.0)
+            # - tool_choice "required" forces tool use
+            model_settings={
+                "temperature": 0.3,
+                "extra_body": {"tool_choice": "required"},
+            },
+        )
+
+        # Register all tools including orchestration
+        self._register_tools(agent)
+
+        return agent
+
+    def _register_tools(self, agent: Agent[TaskContext, str]) -> None:
+        """Register all tools with the agent."""
+        from src.domains.agents.task.tools import register_task_tools
+        register_task_tools(agent)
+
+    @logged()
+    async def run(
+        self,
+        prompt: str,
+        working_dir: str | None = None,
+        allowed_paths: list[str] | None = None,
+        **kwargs: Any
+    ) -> str:
+        """
+        Run the task agent to execute a multi-step task.
+
+        Args:
+            prompt: Description of the task to execute
+            working_dir: Working directory for the agent
+            allowed_paths: Restrict tool access to these paths
+
+        Returns:
+            Consolidated task summary with results
+        """
+        ctx = TaskContext(
+            working_dir=working_dir or os.getcwd(),
+            allowed_paths=allowed_paths or self._settings.effective_allowed_paths,
+            timeout_seconds=self._settings.tool_timeout_seconds,
+        )
+
+        async with trace_span("task_agent_run"):
+            try:
+                # Use run() not run_stream() - Ollama has bugs with streaming + tools
+                result = await self.agent.run(prompt, deps=ctx)
+                return result.output
+            except Exception as e:
+                logger.exception(f"Task agent error: {e}")
+                raise
+
+    async def run_stream(
+        self,
+        prompt: str,
+        working_dir: str | None = None,
+        allowed_paths: list[str] | None = None,
+        **kwargs: Any
+    ) -> AsyncIterator[str]:
+        """
+        Run the task agent with streaming output.
+
+        Yields text chunks as they become available.
+        """
+        ctx = TaskContext(
+            working_dir=working_dir or os.getcwd(),
+            allowed_paths=allowed_paths or self._settings.effective_allowed_paths,
+            timeout_seconds=self._settings.tool_timeout_seconds,
+        )
+
+        async with trace_span("task_agent_stream"):
+            try:
+                async with self.agent.run_stream(prompt, deps=ctx) as result:
+                    async for chunk in result.stream_text():
+                        yield chunk
+            except Exception as e:
+                logger.exception(f"Task agent stream error: {e}")
+                raise
+
+
+# Create and register the singleton instance
+task_agent = TaskAgentImpl()
+register_agent(task_agent)
+
+
+async def task(
+    prompt: str,
+    working_dir: str | None = None,
+    **kwargs: Any
+) -> str:
+    """Run task execution."""
+    return await task_agent.run(prompt, working_dir=working_dir, **kwargs)
+
+
+async def task_stream(
+    prompt: str,
+    working_dir: str | None = None,
+    **kwargs: Any
+) -> AsyncIterator[str]:
+    """Run task execution with streaming."""
+    async for chunk in task_agent.run_stream(prompt, working_dir=working_dir, **kwargs):
+        yield chunk

webber-api/src/domains/agents/task/prompts.py

@@ -0,0 +1,83 @@
+"""
+System prompts for the Task agent.
+
+The Task agent is a full orchestrator that can:
+- Execute multi-step tasks autonomously
+- Use all tools (read + write)
+- Spawn sub-agents (Explore, Plan) for focused work
+"""
+
+TASK_SYSTEM_PROMPT = """You are an autonomous task execution agent.
+
+You have access to ALL tools including file editing, writing, and bash execution.
+You can also spawn sub-agents to help with complex tasks.
+
+AVAILABLE TOOLS:
+
+File Operations:
+- read_file: Read file contents with line numbers
+- glob_files: Find files by pattern
+- grep_content: Search file contents with regex
+- edit_file: Make targeted edits via find-and-replace
+- write_file: Create or overwrite files
+
+Shell:
+- bash_readonly: Read-only commands (ls, git status, git log, etc.)
+- bash: Full bash execution (git commit, pytest, mkdir, etc.)
+
+External:
+- web_search: Search the web for current information
+
+Orchestration:
+- spawn_agent: Launch sub-agents for focused tasks
+
+WORKFLOW:
+1. Understand the task requirements
+2. Break down into sub-tasks if complex
+3. Use spawn_agent for research (explore) or planning (plan)
+4. Execute implementation steps using write tools
+5. Validate changes (run tests if applicable)
+6. Return consolidated summary
+
+TOOL CALL EXAMPLES:
+
+To spawn an Explore agent for research:
+  Call spawn_agent with agent_type="explore" and prompt="find all config files"
+
+To spawn a Plan agent for design:
+  Call spawn_agent with agent_type="plan" and prompt="design user auth feature"
+
+To edit a file:
+  Call edit_file with file_path="/path/to/file.py" and old_string="old" and new_string="new"
+
+To run tests:
+  Call bash with command="pytest tests/ -v"
+
+SPAWN_AGENT USAGE:
+- Use spawn_agent to offload focused tasks to specialized agents
+- Explore agent: Fast codebase searches and analysis
+- Plan agent: Design implementation strategies
+- Keep each agent's context focused and efficient
+
+GIT DISCIPLINE:
+- Create feature branches for changes
+- Use conventional commit format (feat:, fix:, docs:, etc.)
+- Never commit directly to main
+- Run tests before committing
+
+RULES:
+- ALWAYS use tools first, then analyze results
+- Never guess file contents - read them first
+- Prefer edit_file over write_file for existing files
+- Use spawn_agent to keep context focused
+- Validate changes by running tests when applicable
+
+OUTPUT FORMAT:
+End your response with a summary:
+
+### Task Summary
+- **Accomplished:** What was done
+- **Files modified:** List of changed files
+- **Commands run:** Key commands executed
+- **Issues:** Any problems encountered
+"""

webber-api/src/domains/agents/task/tools.py

@@ -0,0 +1,350 @@
+"""
+Tool registrations for the Task agent.
+
+The Task agent has access to ALL tools:
+- Read-only tools (same as Explore/Plan)
+- Write tools (edit, write, bash full)
+- External tools (web search)
+- Orchestration (spawn sub-agents)
+"""
+from pydantic_ai import Agent, RunContext
+
+from src.domains.agents.base import AgentContext
+from src.domains.tools.file.read import ReadFileTool
+from src.domains.tools.file.glob import GlobFilesTool
+from src.domains.tools.file.edit import EditFileTool
+from src.domains.tools.file.write import WriteFileTool
+from src.domains.tools.search.grep import GrepContentTool
+from src.domains.tools.search.web import WebSearchTool
+from src.domains.tools.shell.bash import BashReadOnlyTool
+from src.domains.tools.shell.bash_full import BashTool
+
+
+def register_task_tools(agent: Agent[AgentContext, str]) -> None:
+    """
+    Register all tools with the Task agent.
+
+    Includes:
+    - Read-only tools: read_file, glob_files, grep_content, bash_readonly
+    - Write tools: edit_file, write_file, bash
+    - External: web_search
+    - Orchestration: spawn_agent
+    """
+
+    # === Read-only tools ===
+
+    @agent.tool
+    async def read_file(
+        ctx: RunContext[AgentContext],
+        file_path: str,
+        offset: int = 0,
+        limit: int = 2000
+    ) -> str:
+        """Read contents of a file with line numbers.
+
+        Args:
+            file_path: Absolute path to the file to read
+            offset: Line number to start from (0-based, default: 0)
+            limit: Maximum number of lines to read (default: 2000)
+
+        Returns:
+            File contents with line numbers, or error message.
+
+        IMPORTANT: Always use absolute paths. Read files before editing them.
+        """
+        tool = ReadFileTool(allowed_paths=ctx.deps.allowed_paths)
+        result = await tool.execute(
+            file_path=file_path,
+            offset=offset,
+            limit=limit
+        )
+        return result.to_string()
+
+    @agent.tool
+    async def glob_files(
+        ctx: RunContext[AgentContext],
+        pattern: str,
+        path: str | None = None,
+        limit: int = 100
+    ) -> str:
+        """Find files matching a glob pattern.
+
+        Args:
+            pattern: Glob pattern (e.g., "**/*.py", "src/**/*.ts", "*.md")
+            path: Directory to search in (default: working directory)
+            limit: Maximum number of files to return (default: 100)
+
+        Returns:
+            List of absolute file paths, sorted by modification time (newest first).
+
+        Examples:
+            - "**/*.py" finds all Python files
+            - "src/**/*.ts" finds TypeScript files in src/
+            - "**/test_*.py" finds all test files
+        """
+        tool = GlobFilesTool(allowed_paths=ctx.deps.allowed_paths)
+        search_path = path or ctx.deps.working_dir
+        result = await tool.execute(
+            pattern=pattern,
+            path=search_path,
+            limit=limit
+        )
+        return result.to_string()
+
+    @agent.tool
+    async def grep_content(
+        ctx: RunContext[AgentContext],
+        pattern: str,
+        path: str | None = None,
+        file_glob: str | None = None,
+        context_lines: int = 0,
+        case_sensitive: bool = True
+    ) -> str:
+        """Search file contents using regex pattern.
+
+        Args:
+            pattern: Regex pattern to search for (Python re syntax)
+            path: Directory or file to search (default: working directory)
+            file_glob: Filter files by glob (e.g., "*.py", "*.ts")
+            context_lines: Lines of context before/after matches (default: 0)
+            case_sensitive: Case-sensitive search (default: True)
+
+        Returns:
+            Matching lines with file paths and line numbers.
+            Format: "filepath:line_num: content"
+        """
+        tool = GrepContentTool(allowed_paths=ctx.deps.allowed_paths)
+        search_path = path or ctx.deps.working_dir
+        result = await tool.execute(
+            pattern=pattern,
+            path=search_path,
+            file_glob=file_glob,
+            context_lines=context_lines,
+            case_sensitive=case_sensitive
+        )
+        return result.to_string()
+
+    @agent.tool
+    async def bash_readonly(
+        ctx: RunContext[AgentContext],
+        command: str,
+        cwd: str | None = None,
+        timeout: int = 30
+    ) -> str:
+        """Execute a read-only bash command.
+
+        ALLOWED commands:
+        - File inspection: ls, find, cat, head, tail, wc, file, stat, tree, du
+        - Git (read-only): git status, git log, git diff, git show, git branch
+        - Text processing: grep, awk, sed (read-only), sort, uniq
+        - System info: pwd, whoami, hostname, which
+
+        FORBIDDEN:
+        - File modification (rm, mv, cp, mkdir, touch)
+        - Redirects (>, >>)
+        - Command chaining (&&, ||, ;)
+        - Network (curl, wget)
+
+        Args:
+            command: The bash command to execute
+            cwd: Working directory (default: agent working directory)
+            timeout: Timeout in seconds (default: 30)
+        """
+        tool = BashReadOnlyTool(allowed_paths=ctx.deps.allowed_paths)
+        working_dir = cwd or ctx.deps.working_dir
+        result = await tool.execute(
+            command=command,
+            cwd=working_dir,
+            timeout=min(timeout, ctx.deps.timeout_seconds)
+        )
+        return result.to_string()
+
+    # === Write tools ===
+
+    @agent.tool
+    async def edit_file(
+        ctx: RunContext[AgentContext],
+        file_path: str,
+        old_string: str,
+        new_string: str,
+        replace_all: bool = False
+    ) -> str:
+        """Make targeted edits to a file using find-and-replace.
+
+        Args:
+            file_path: Absolute path to the file to edit
+            old_string: The exact text to find and replace (must exist in file)
+            new_string: The replacement text
+            replace_all: If True, replace all occurrences. If False (default),
+                         old_string must be unique (appear exactly once).
+
+        Returns:
+            Success message with diff preview, or error.
+
+        IMPORTANT:
+        - old_string must exactly match file content (including whitespace)
+        - By default, old_string must appear exactly once (for safety)
+        - Always read the file first to verify exact content before editing
+        """
+        tool = EditFileTool(allowed_paths=ctx.deps.allowed_paths)
+        result = await tool.execute(
+            file_path=file_path,
+            old_string=old_string,
+            new_string=new_string,
+            replace_all=replace_all
+        )
+        return result.to_string()
+
+    @agent.tool
+    async def write_file(
+        ctx: RunContext[AgentContext],
+        file_path: str,
+        content: str
+    ) -> str:
+        """Create a new file or overwrite an existing file.
+
+        Args:
+            file_path: Absolute path to the file to create/write
+            content: The content to write to the file
+
+        Returns:
+            Success message with file path and size.
+
+        IMPORTANT:
+        - Parent directory must exist (use bash mkdir first if needed)
+        - For editing existing files, prefer edit_file instead
+        - Will overwrite existing files without confirmation
+        """
+        tool = WriteFileTool(allowed_paths=ctx.deps.allowed_paths)
+        result = await tool.execute(
+            file_path=file_path,
+            content=content
+        )
+        return result.to_string()
+
+    @agent.tool
+    async def bash(
+        ctx: RunContext[AgentContext],
+        command: str,
+        cwd: str | None = None,
+        timeout: int = 60
+    ) -> str:
+        """Execute a bash command with write capabilities.
+
+        ALLOWED:
+        - File operations: ls, find, mkdir, touch, cp, mv, rm (single files)
+        - Git (full): git add, git commit, git checkout, git merge, git pull
+        - Python: python, pip install, pytest, mypy, ruff
+        - Text processing: grep, awk, sed, sort
+        - Command chaining: && and || are allowed
+
+        FORBIDDEN:
+        - sudo, su (privilege escalation)
+        - Network: curl, wget, ssh, scp, rsync
+        - Dangerous: rm -rf, chmod 777, dd, mkfs
+
+        Args:
+            command: The bash command to execute
+            cwd: Working directory (default: agent working directory)
+            timeout: Timeout in seconds (default: 60)
+
+        Examples:
+            - "mkdir -p src/utils" creates directory
+            - "git add . && git commit -m 'fix: bug'" commits changes
+            - "pytest tests/ -v" runs tests
+        """
+        tool = BashTool(allowed_paths=ctx.deps.allowed_paths)
+        working_dir = cwd or ctx.deps.working_dir
+        result = await tool.execute(
+            command=command,
+            cwd=working_dir,
+            timeout=min(timeout, ctx.deps.timeout_seconds)
+        )
+        return result.to_string()
+
+    # === External tools ===
+
+    @agent.tool
+    async def web_search(
+        ctx: RunContext[AgentContext],
+        query: str,
+        num_results: int = 5,
+        categories: str | None = None
+    ) -> str:
+        """Search the web for current information.
+
+        Args:
+            query: Search query (e.g., "Python 3.12 new features")
+            num_results: Number of results to return (1-10, default: 5)
+            categories: Optional category filter ("general", "it", "news", "science")
+
+        Returns:
+            Search results with titles, URLs, and snippets.
+
+        Use this for:
+        - Current events or recent information
+        - Documentation updates
+        - Technical references with URLs
+        """
+        tool = WebSearchTool()
+        result = await tool.execute(
+            query=query,
+            num_results=num_results,
+            categories=categories
+        )
+        return result.to_string()
+
+    # === Orchestration tools ===
+
+    @agent.tool
+    async def spawn_agent(
+        ctx: RunContext[AgentContext],
+        agent_type: str,
+        prompt: str,
+        working_dir: str | None = None
+    ) -> str:
+        """Spawn a sub-agent to handle a focused task.
+
+        Use this to offload work to specialized agents:
+        - "explore": Fast codebase searches and analysis (read-only)
+        - "plan": Design implementation strategies (read-only)
+
+        Args:
+            agent_type: Type of agent to spawn ("explore" or "plan")
+            prompt: Task description for the sub-agent
+            working_dir: Working directory for the sub-agent (default: current)
+
+        Returns:
+            Sub-agent's consolidated response.
+
+        Examples:
+            - spawn_agent(agent_type="explore", prompt="find all test files")
+            - spawn_agent(agent_type="plan", prompt="design user auth feature")
+
+        IMPORTANT:
+        - Use sub-agents to keep context focused and efficient
+        - Explore agent for research, Plan agent for design
+        - Cannot spawn nested Task agents (recursion risk)
+        """
+        from src.domains.agents.base import get_agent
+
+        # Validate agent type
+        allowed_types = ["explore", "plan"]
+        if agent_type not in allowed_types:
+            if agent_type == "task":
+                return "Error: Cannot spawn nested Task agents (recursion risk)"
+            return f"Error: Unknown agent type '{agent_type}'. Allowed: {allowed_types}"
+
+        sub_agent = get_agent(agent_type)
+        if not sub_agent:
+            return f"Error: Agent '{agent_type}' not found in registry"
+
+        try:
+            result = await sub_agent.run(
+                prompt=prompt,
+                working_dir=working_dir or ctx.deps.working_dir,
+                allowed_paths=ctx.deps.allowed_paths,
+            )
+            return result
+        except Exception as e:
+            return f"Sub-agent error: {e}"

webber-api/src/domains/health/router.py

@@ -1,7 +1,6 @@
 """
 Health check routes.
 """
-from fastapi import APIRouter
 
 from src.domains.health.controller import health_controller
 

webber-api/src/domains/router.py

@@ -7,8 +7,9 @@ main.py only includes this root_router.
 from fastapi import APIRouter
 
 from src.domains.health.router import router as health_router
+from src.domains.agents.router import router as agents_router
+
 # from src.domains.auth.router import router as auth_router
-# from src.domains.agents.router import router as agents_router
 # from src.domains.tools.router import router as tools_router
 
 root_router = APIRouter()
@@ -16,11 +17,11 @@ root_router = APIRouter()
 # Health (no prefix - root level)
 root_router.include_router(health_router)
 
+# Agents domain (prefix defined in router)
+root_router.include_router(agents_router)
+
 # Auth domain
 # root_router.include_router(auth_router, prefix="/auth", tags=["Auth"])
 
-# Agents domain
-# root_router.include_router(agents_router, prefix="/agents", tags=["Agents"])
-
 # Tools domain
 # root_router.include_router(tools_router, prefix="/tools", tags=["Tools"])

webber-api/src/domains/tools/__init__.py

@@ -0,0 +1,22 @@
+"""
+Tool implementations for agent use.
+
+All tools inherit from BaseTool and return ToolResult.
+"""
+from src.domains.tools.base import BaseTool, ToolResult
+from src.domains.tools.file import ReadFileTool, GlobFilesTool, EditFileTool, WriteFileTool
+from src.domains.tools.search import GrepContentTool, WebSearchTool
+from src.domains.tools.shell import BashReadOnlyTool, BashTool
+
+__all__ = [
+    "BaseTool",
+    "ToolResult",
+    "ReadFileTool",
+    "GlobFilesTool",
+    "EditFileTool",
+    "WriteFileTool",
+    "GrepContentTool",
+    "WebSearchTool",
+    "BashReadOnlyTool",
+    "BashTool",
+]

webber-api/src/domains/tools/base.py

@@ -0,0 +1,134 @@
+"""
+Base classes for tool implementations.
+
+All tools inherit from BaseTool and return ToolResult for consistent handling.
+"""
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class ToolResult:
+    """
+    Standardized result from tool execution.
+
+    All tools return this for consistent error handling and LLM consumption.
+    """
+    success: bool
+    data: Any
+    error: str | None = None
+    truncated: bool = False
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def to_string(self, max_length: int = 30000) -> str:
+        """
+        Convert result to string for LLM consumption.
+
+        Args:
+            max_length: Maximum string length before truncation
+        """
+        if not self.success:
+            return f"ERROR: {self.error}"
+
+        if isinstance(self.data, str):
+            content = self.data
+        else:
+            content = str(self.data)
+
+        if len(content) > max_length:
+            self.truncated = True
+            content = content[:max_length] + "\n... (truncated)"
+
+        if self.truncated:
+            content += "\n[Output was truncated]"
+
+        return content
+
+    def __str__(self) -> str:
+        return self.to_string()
+
+
+class BaseTool(ABC):
+    """
+    Abstract base class for all tools.
+
+    All domain tools (file, shell, search) inherit from this and implement execute().
+
+    Usage:
+        class MyTool(BaseTool):
+            name = "my_tool"
+            description = "Does something useful"
+
+            async def execute(self, **kwargs) -> ToolResult:
+                return ToolResult(success=True, data="result")
+    """
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Tool name for registration and identification."""
+        pass
+
+    @property
+    @abstractmethod
+    def description(self) -> str:
+        """
+        Tool description for LLM.
+
+        Should include:
+        - What the tool does
+        - Arguments and their types
+        - Return value description
+        - Usage constraints/examples
+        """
+        pass
+
+    @abstractmethod
+    async def execute(self, **kwargs: Any) -> ToolResult:
+        """
+        Execute the tool with given arguments.
+
+        Returns:
+            ToolResult with success status and data or error
+        """
+        pass
+
+    def _validate_path(self, path: str | Path, allowed_paths: list[str]) -> bool:
+        """
+        Validate that a path is within allowed directories.
+
+        Args:
+            path: Path to validate
+            allowed_paths: List of allowed directory prefixes
+
+        Returns:
+            True if path is allowed, False otherwise
+        """
+        if not allowed_paths:
+            return True  # No restrictions when allowed_paths is empty
+
+        resolved = Path(path).resolve()
+        return any(
+            str(resolved).startswith(str(Path(allowed).resolve()))
+            for allowed in allowed_paths
+        )
+
+    def _error(self, message: str) -> ToolResult:
+        """Create an error result."""
+        return ToolResult(success=False, data=None, error=message)
+
+    def _success(
+        self,
+        data: Any,
+        truncated: bool = False,
+        **metadata: Any
+    ) -> ToolResult:
+        """Create a success result."""
+        return ToolResult(
+            success=True,
+            data=data,
+            truncated=truncated,
+            metadata=metadata
+        )

webber-api/src/domains/tools/file/__init__.py

@@ -0,0 +1,9 @@
+"""
+File operation tools.
+"""
+from src.domains.tools.file.read import ReadFileTool
+from src.domains.tools.file.glob import GlobFilesTool
+from src.domains.tools.file.edit import EditFileTool
+from src.domains.tools.file.write import WriteFileTool
+
+__all__ = ["ReadFileTool", "GlobFilesTool", "EditFileTool", "WriteFileTool"]

webber-api/src/domains/tools/file/edit.py

@@ -0,0 +1,194 @@
+"""
+File editing tool with find-and-replace functionality.
+"""
+import difflib
+import aiofiles
+from pathlib import Path
+
+from src.domains.tools.base import BaseTool, ToolResult
+from src.shared.logging import logged, get_logger
+
+logger = get_logger(__name__)
+
+# Binary file extensions to skip
+BINARY_EXTENSIONS = {
+    '.pyc', '.pyo', '.so', '.o', '.a', '.lib', '.dll', '.exe',
+    '.bin', '.dat', '.db', '.sqlite', '.sqlite3',
+    '.png', '.jpg', '.jpeg', '.gif', '.ico', '.bmp', '.webp',
+    '.pdf', '.doc', '.docx', '.xls', '.xlsx',
+    '.zip', '.tar', '.gz', '.bz2', '.7z', '.rar',
+    '.mp3', '.mp4', '.avi', '.mov', '.wav',
+    '.woff', '.woff2', '.ttf', '.eot',
+}
+
+
+class EditFileTool(BaseTool):
+    """
+    Edit files using find-and-replace.
+
+    Safely modifies files by finding exact text matches and replacing them.
+    Includes safety checks to prevent accidental edits.
+    """
+
+    name = "edit_file"
+    description = """Make targeted edits to a file using find-and-replace.
+
+Args:
+    file_path: Absolute path to the file to edit
+    old_string: The exact text to find and replace (must exist in file)
+    new_string: The replacement text
+    replace_all: If True, replace all occurrences. If False (default),
+                 old_string must be unique in the file (appear exactly once).
+
+Returns:
+    Success message with diff preview showing changes, or error.
+
+IMPORTANT:
+- The old_string must exactly match text in the file (including whitespace/indentation)
+- By default, old_string must appear exactly once in the file (for safety)
+- Use replace_all=True only when you intentionally want to replace all occurrences
+- Always read the file first to verify exact content before editing
+- Cannot edit binary files
+
+Examples:
+    - Fix a bug: old_string="return x + y", new_string="return x * y"
+    - Rename function: old_string="def old_name(", new_string="def new_name("
+    - Add import: old_string="import os", new_string="import os\\nimport sys"
+"""
+
+    def __init__(
+        self,
+        allowed_paths: list[str] | None = None,
+        max_file_size: int = 1_000_000,  # 1MB
+    ):
+        """
+        Initialize EditFileTool.
+
+        Args:
+            allowed_paths: List of allowed directory prefixes (empty = no restrictions)
+            max_file_size: Maximum file size to edit in bytes
+        """
+        self.allowed_paths = allowed_paths or []
+        self.max_file_size = max_file_size
+
+    def _is_binary_file(self, path: Path) -> bool:
+        """Check if file is likely binary based on extension."""
+        return path.suffix.lower() in BINARY_EXTENSIONS
+
+    def _generate_diff(
+        self,
+        original: str,
+        modified: str,
+        file_path: str
+    ) -> str:
+        """Generate a unified diff between original and modified content."""
+        original_lines = original.splitlines(keepends=True)
+        modified_lines = modified.splitlines(keepends=True)
+
+        diff = difflib.unified_diff(
+            original_lines,
+            modified_lines,
+            fromfile=f"a/{Path(file_path).name}",
+            tofile=f"b/{Path(file_path).name}",
+            lineterm=""
+        )
+        return "".join(diff)
+
+    @logged()
+    async def execute(
+        self,
+        file_path: str,
+        old_string: str,
+        new_string: str,
+        replace_all: bool = False
+    ) -> ToolResult:
+        """
+        Edit a file by replacing old_string with new_string.
+
+        Args:
+            file_path: Absolute path to the file
+            old_string: Text to find (must exist)
+            new_string: Replacement text
+            replace_all: Replace all occurrences (default: False)
+
+        Returns:
+            ToolResult with diff preview or error
+        """
+        path = Path(file_path)
+
+        # Validate path is allowed
+        if not self._validate_path(path, self.allowed_paths):
+            return self._error(f"Path not in allowed paths: {file_path}")
+
+        # Check file exists
+        if not path.exists():
+            return self._error(f"File not found: {file_path}")
+
+        if not path.is_file():
+            return self._error(f"Not a file: {file_path}")
+
+        # Check for binary files
+        if self._is_binary_file(path):
+            return self._error(f"Cannot edit binary file: {file_path}")
+
+        # Check file size
+        file_size = path.stat().st_size
+        if file_size > self.max_file_size:
+            return self._error(
+                f"File too large ({file_size} bytes). Max: {self.max_file_size} bytes"
+            )
+
+        # Validate inputs
+        if not old_string:
+            return self._error("old_string cannot be empty")
+
+        if old_string == new_string:
+            return self._error("old_string and new_string are identical")
+
+        try:
+            # Read file content
+            async with aiofiles.open(path, 'r', encoding='utf-8', errors='replace') as f:
+                content = await f.read()
+
+            # Check if old_string exists
+            count = content.count(old_string)
+            if count == 0:
+                return self._error(
+                    f"old_string not found in file. "
+                    f"Make sure to match exact whitespace and indentation."
+                )
+
+            # Check uniqueness if replace_all is False
+            if not replace_all and count > 1:
+                return self._error(
+                    f"old_string appears {count} times in file. "
+                    f"Use replace_all=True to replace all, or provide a more specific string."
+                )
+
+            # Perform replacement
+            if replace_all:
+                modified = content.replace(old_string, new_string)
+            else:
+                modified = content.replace(old_string, new_string, 1)
+
+            # Generate diff for preview
+            diff = self._generate_diff(content, modified, file_path)
+
+            # Write modified content
+            async with aiofiles.open(path, 'w', encoding='utf-8') as f:
+                await f.write(modified)
+
+            replacements = count if replace_all else 1
+            return self._success(
+                data=f"Successfully edited {file_path}\n\n{diff}",
+                replacements=replacements,
+                file_path=str(path.resolve())
+            )
+
+        except PermissionError:
+            return self._error(f"Permission denied: {file_path}")
+        except UnicodeDecodeError as e:
+            return self._error(f"Unable to decode file (binary?): {e}")
+        except Exception as e:
+            logger.exception(f"Error editing file: {file_path}")
+            return self._error(f"Error editing file: {e}")

webber-api/src/domains/tools/file/glob.py

@@ -0,0 +1,149 @@
+"""
+File glob/pattern matching tool.
+"""
+import os
+from pathlib import Path
+
+from src.domains.tools.base import BaseTool, ToolResult
+from src.domains.tools.gitignore import filter_gitignored
+from src.shared.logging import logged, get_logger
+
+logger = get_logger(__name__)
+
+
+class GlobFilesTool(BaseTool):
+    """
+    Find files matching a glob pattern.
+
+    Returns files sorted by modification time (newest first).
+    """
+
+    name = "glob_files"
+    description = """Find files matching a glob pattern.
+
+Args:
+    pattern: Glob pattern (e.g., "**/*.py", "src/**/*.ts", "*.md")
+    path: Directory to search in (default: working directory)
+    limit: Maximum number of files to return (default: 100)
+    honor_gitignore: Filter out gitignored files (default: True)
+
+Returns:
+    List of matching absolute file paths, sorted by modification time (newest first).
+    Returns error if path not found or not allowed.
+    By default, excludes files matching .gitignore patterns and common ignored
+    directories like .venv/, node_modules/, __pycache__/, etc.
+
+Examples:
+    - "**/*.py" - All Python files recursively
+    - "src/**/*.ts" - TypeScript files in src
+    - "*.md" - Markdown files in current directory only
+    - "**/test_*.py" - All test files
+
+IMPORTANT:
+- Use this tool to find files before reading them
+- Never guess file locations - use glob to discover
+"""
+
+    def __init__(
+        self,
+        allowed_paths: list[str] | None = None,
+        max_results: int = 100,
+        honor_gitignore: bool = True
+    ):
+        """
+        Initialize GlobFilesTool.
+
+        Args:
+            allowed_paths: List of allowed directory prefixes
+            max_results: Maximum files to return
+            honor_gitignore: Whether to filter out gitignored files by default
+        """
+        self.allowed_paths = allowed_paths or []
+        self.max_results = max_results
+        self.honor_gitignore = honor_gitignore
+
+    @logged()
+    async def execute(
+        self,
+        pattern: str,
+        path: str | None = None,
+        limit: int | None = None,
+        honor_gitignore: bool | None = None
+    ) -> ToolResult:
+        """
+        Find files matching glob pattern.
+
+        Args:
+            pattern: Glob pattern to match
+            path: Directory to search (default: current directory)
+            limit: Maximum results to return
+            honor_gitignore: Filter out gitignored files (default: instance setting)
+
+        Returns:
+            ToolResult with list of matching file paths
+        """
+        limit = limit or self.max_results
+        should_filter_gitignore = honor_gitignore if honor_gitignore is not None else self.honor_gitignore
+        search_path = Path(path) if path else Path.cwd()
+
+        # Validate search path is allowed
+        if not self._validate_path(search_path, self.allowed_paths):
+            return self._error(f"Path not in allowed paths: {search_path}")
+
+        if not search_path.exists():
+            return self._error(f"Directory not found: {search_path}")
+
+        if not search_path.is_dir():
+            return self._error(f"Not a directory: {search_path}")
+
+        try:
+            # Find matching files
+            matches = list(search_path.glob(pattern))
+
+            # Filter to files only (exclude directories)
+            files = [f for f in matches if f.is_file()]
+
+            # Validate each result is in allowed paths
+            if self.allowed_paths:
+                files = [f for f in files if self._validate_path(f, self.allowed_paths)]
+
+            # Filter out gitignored files
+            if should_filter_gitignore:
+                files = filter_gitignored(files, search_path)
+
+            # Sort by modification time (newest first)
+            files_with_mtime = []
+            for f in files:
+                try:
+                    mtime = os.path.getmtime(f)
+                    files_with_mtime.append((f, mtime))
+                except OSError:
+                    # Skip files we can't stat
+                    continue
+
+            files_with_mtime.sort(key=lambda x: x[1], reverse=True)
+            sorted_files = [f for f, _ in files_with_mtime]
+
+            # Apply limit
+            truncated = len(sorted_files) > limit
+            result_files = sorted_files[:limit]
+
+            # Format output as absolute paths
+            output_lines = [str(f.resolve()) for f in result_files]
+            result = "\n".join(output_lines)
+
+            if not output_lines:
+                result = f"No files found matching '{pattern}' in {search_path}"
+
+            return self._success(
+                data=result,
+                truncated=truncated,
+                total_matches=len(sorted_files),
+                returned=len(result_files)
+            )
+
+        except PermissionError:
+            return self._error(f"Permission denied: {search_path}")
+        except Exception as e:
+            logger.exception(f"Error globbing: {pattern} in {search_path}")
+            return self._error(f"Error searching files: {e}")

webber-api/src/domains/tools/file/read.py

@@ -0,0 +1,127 @@
+"""
+File reading tool with line number formatting and sandboxing.
+"""
+import aiofiles
+from pathlib import Path
+
+from src.domains.tools.base import BaseTool, ToolResult
+from src.shared.logging import logged, get_logger
+
+logger = get_logger(__name__)
+
+
+class ReadFileTool(BaseTool):
+    """
+    Read file contents with line numbers.
+
+    Supports offset and limit for handling large files.
+    Returns content in a format similar to `cat -n`.
+    """
+
+    name = "read_file"
+    description = """Read contents of a file with line numbers.
+
+Args:
+    file_path: Absolute path to the file to read
+    offset: Line number to start from (0-based, default: 0)
+    limit: Maximum number of lines to read (default: 2000)
+
+Returns:
+    File contents with line numbers in format "  123| content"
+    Returns error if file not found or path not allowed.
+
+IMPORTANT:
+- Always use absolute paths
+- Never estimate file contents - use this tool to verify
+- Check if truncated flag is set for large files
+"""
+
+    def __init__(
+        self,
+        allowed_paths: list[str] | None = None,
+        max_lines: int = 2000,
+        max_line_length: int = 2000
+    ):
+        """
+        Initialize ReadFileTool.
+
+        Args:
+            allowed_paths: List of allowed directory prefixes (empty = no restrictions)
+            max_lines: Default maximum lines to read
+            max_line_length: Maximum characters per line before truncation
+        """
+        self.allowed_paths = allowed_paths or []
+        self.max_lines = max_lines
+        self.max_line_length = max_line_length
+
+    @logged()
+    async def execute(
+        self,
+        file_path: str,
+        offset: int = 0,
+        limit: int | None = None
+    ) -> ToolResult:
+        """
+        Read file contents with line numbers.
+
+        Args:
+            file_path: Absolute path to the file
+            offset: Starting line (0-based)
+            limit: Maximum lines to return
+
+        Returns:
+            ToolResult with formatted file contents or error
+        """
+        limit = limit or self.max_lines
+        path = Path(file_path)
+
+        # Validate path is allowed
+        if not self._validate_path(path, self.allowed_paths):
+            return self._error(f"Path not in allowed paths: {file_path}")
+
+        # Check file exists
+        if not path.exists():
+            return self._error(f"File not found: {file_path}")
+
+        if not path.is_file():
+            return self._error(f"Not a file: {file_path}")
+
+        try:
+            async with aiofiles.open(path, 'r', encoding='utf-8', errors='replace') as f:
+                content = await f.read()
+
+            lines = content.splitlines()
+            total_lines = len(lines)
+
+            # Apply offset and limit
+            selected = lines[offset:offset + limit]
+            truncated = total_lines > offset + limit
+
+            # Format with line numbers (right-aligned, 6 chars)
+            numbered_lines = []
+            for i, line in enumerate(selected):
+                line_num = offset + i + 1  # 1-based for display
+
+                # Truncate long lines
+                if len(line) > self.max_line_length:
+                    line = line[:self.max_line_length] + "..."
+
+                numbered_lines.append(f"{line_num:>6}| {line}")
+
+            result = "\n".join(numbered_lines)
+
+            return self._success(
+                data=result,
+                truncated=truncated,
+                total_lines=total_lines,
+                lines_returned=len(selected),
+                offset=offset
+            )
+
+        except PermissionError:
+            return self._error(f"Permission denied: {file_path}")
+        except UnicodeDecodeError as e:
+            return self._error(f"Unable to decode file (not text?): {e}")
+        except Exception as e:
+            logger.exception(f"Error reading file: {file_path}")
+            return self._error(f"Error reading file: {e}")