feat: package restructure with backward compatibility and error handling

[allenday]

This PR implements the package restructuring (PR1) with critical error
handling improvements added for production resilience.

Package Structure & Backward Compatibility

New Package Structure

• Moved all modules to agentproxy/ package directory
• Created pyproject.toml with entry points for pa and pa-server
• Added agentproxy/__init__.py with proper exports
• Added agentproxy/__main__.py for module execution

Backward Compatibility (CRITICAL)

• cli.py - Shim for old python cli.py entry point
• server.py - Shim for old python server.py entry point
• All old entry points continue to work without modification
• New entry points available after pip install -e .:
  • pa command
  • pa-server command
  • python -m agentproxy
  • python -m agentproxy.server

Tests (29 passing)

• tests/test_baseline_compatibility.py - 23 tests covering:
  • Old entry points (python cli.py, python server.py)
  • New entry points (pa, pa-server, python -m agentproxy)
  • Package imports and structure
  • Core components
• tests/unit/test_gemini_error_handling.py - 4 unit tests
• tests/integration/test_integration_error_handling.py - 2 integration tests

Gemini Error Handling & Resilience (Critical Addition)

Problem Solved

Previous implementation had no retry logic or error recovery, causing:

• Lost instruction context during transient API errors
• Abrupt failures on rate limits or network issues
• No graceful degradation

Solution Implemented

1. Retry Logic with Exponential Backoff (gemini_client.py)

• GeminiAPIError exception with retry metadata
• Automatic retry on 5xx errors (max 3 attempts)
• Exponential backoff: 1s, 2s, 4s
• No retry on 4xx client errors (won't succeed)
• Structured error messages for upstream handling

2. Error Recovery & Context Preservation (pa_agent.py)

• Track consecutive errors (resets on success)
• First 2 errors: Return NO_OP to preserve instruction context
• 3rd consecutive error: Trigger SAVE_SESSION for graceful exit
• Parse error strings to extract type, status code, message
• Increment error counter on both API and parse failures

3. Instruction Preservation (pa.py)

• Track _original_task and _last_valid_instruction
• NO_OP returns empty string (signals "no change")
• Main loop keeps last valid instruction during errors
• Prevents sending vague "Continue" during error states

4. Session Save Function (function_executor.py)

• New SAVE_SESSION function for graceful exit
• Saves session state with error context
• Returns session ID for resumption
• Metadata includes error type, status code, reason

Error Flow

Gemini API Error
  ↓
Retry 3 times with exponential backoff
  ↓
If all retries fail → Return [GEMINI_ERROR:type:code:message]
  ↓
PA Agent detects error string
  ↓
Error #1-2: Return NO_OP (preserve instruction)
  ↓
Error #3: Trigger SAVE_SESSION (graceful exit)

Testing

• Unit tests verify error detection, counter increment, session save
• Integration tests verify instruction preservation across error cycles
• All 29 tests passing

Files Changed

New Files

• cli.py - Backward compatibility shim
• server.py - Backward compatibility shim
• tests/test_baseline_compatibility.py - Package structure tests
• tests/unit/test_gemini_error_handling.py - Error handling unit tests
• tests/integration/test_integration_error_handling.py - Integration tests
• tests/__init__.py, tests/unit/__init__.py, tests/integration/__init__.py

Modified Files

• agentproxy/gemini_client.py - Retry logic, GeminiAPIError exception
• agentproxy/pa_agent.py - Error detection, consecutive error tracking
• agentproxy/pa.py - Instruction preservation during errors
• agentproxy/function_executor.py - SAVE_SESSION function
• .gitignore - Updated patterns

Deleted Files

• test_state_detection.py - Obsolete test file

Verification

All entry points tested and working:

• ✅ python cli.py --help
• ✅ python server.py --help
• ✅ pa --help
• ✅ pa-server --help
• ✅ python -m agentproxy --help
• ✅ python -m agentproxy.server --help
• ✅ Package imports work correctly
• ✅ All 29 tests passing

Breaking Changes

None - full backward compatibility maintained.