webber/AGENTS.md

Webber Monorepo - Agent Instructions

Start every session by reading this file. This file contains everything you need to work with this codebase efficiently.

Quick Reference

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

---

Repository Structure

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

---

Development Workflow

1. Start the API Server

cd webber-api
./wakeup.sh

• 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

# 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

3. Use the CLI

cd webber-cli

# Check API connection
.venv/bin/webber-cli status

# Interactive chat (default mode - full capabilities)
.venv/bin/webber-cli chat -d ../webber-sandbox

# Read-only mode (safe exploration and planning)
.venv/bin/webber-cli chat --mode plan -d ../webber-sandbox

# Auto-accept mode (no approval prompts - use with caution)
.venv/bin/webber-cli chat --mode auto_accept -d ../webber-sandbox

# List previous sessions
.venv/bin/webber-cli sessions

# Resume a previous session
.venv/bin/webber-cli chat --resume <session-id>

CLI Features:

• Tab completion for commands and file paths
• Command history persisted to ~/.webber_history
• Session persistence - conversations saved and resumable
• Config file - persistent settings via ~/.webber/config.toml
• Runtime mode switching via mode plan|default|auto_accept
• Directory navigation via cd <path>

Configuration:

# Show current config
.venv/bin/webber-cli config

# Initialize config file with defaults
.venv/bin/webber-cli config --init

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

# 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

After Loading a Template

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

---

Testing Webber's Capabilities

Scenario: Find bugs in calculator-cli

# 1. Load the template
./sandbox.sh load calculator-cli

# 2. Have Webber explore it (plan mode = read-only)
cd webber-cli
.venv/bin/webber-cli chat --mode plan -d ../webber-sandbox
# Then ask: "find all bugs in the code"

# 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:

# For API releases:
# 1. Update version in webber-api/pyproject.toml
# 2. Update webber-api/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

# For CLI releases:
# 1. Update version in webber-cli/pyproject.toml
# 2. Update webber-cli/CHANGELOG.md with release notes
# 3. Commit the version bump
git add -A && git commit -m "chore: release cli vX.Y.Z"
# 4. Create the tag (AFTER the commit)
git tag cli/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

# Check if port is in use
lsof -i :8095

# Kill stuck process
pkill -f "uvicorn src.main:app"

CLI can't connect

# Check API is running
curl http://localhost:8095/health

# Check CLI config
echo $WEBBER_API_URL  # Should be http://localhost:8095

Ollama errors

# 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

# 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

See webber-api/docs/COVERAGE.md for full feature coverage status.