Overview

Add type safety to TunaCode tools while preserving the XML prompt injection system that provides crucial behavioral steering.

Motivation

• Improve developer experience with IDE autocomplete and type checking
• Catch errors at development time rather than runtime
• Maintain XML prompts for agent behavioral hints that can't fit in docstrings
• Best of both worlds: clean typed code + rich prompt engineering

Implementation Details

New Decorator Pattern

@tunacode_tool(xml_prompt="read_file_prompt.xml")
def read_file(file_path: Path, offset: Optional[int] = None) -> FileContent:
    """Read file contents with line numbers."""
    return FileContent(path=file_path, content=content, lines=line_count)

Deliverables

• Create @tunacode_tool decorator that:
  • Extracts type hints for validation
  • Loads associated XML prompt if specified
  • Generates OpenAI-compatible schema
  • Preserves backward compatibility
• Define Pydantic return models:
  • FileContent, GrepResult, CommandOutput, etc.
  • Structured data instead of strings
  • Better error handling
• Migrate all tools to typed signatures
• Maintain backward compatibility during transition

Files to Modify

• src/tunacode/tools/*.py - Add type hints
• src/tunacode/types.py - New type definitions
• New file: src/tunacode/tools/decorators.py - Tool decorator implementation

Success Criteria

• All tools have typed signatures with IDE autocomplete
• XML prompts continue to provide behavioral steering
• No breaking changes to existing functionality
• Type checking passes with mypy/pyright

Priority

High - This is a foundational improvement that enhances developer experience