tunacode-cli 0.0.73__tar.gz → 0.0.76__tar.gz

tunacode_cli-0.0.76/.github/workflows/publish.yml

@@ -0,0 +1,75 @@
+name: Publish to PyPI
+
+"on":
+  release:
+    types: [published]
+  workflow_dispatch:
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.x'
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          pip install hatch twine uv
+
+      - name: Determine version from tag
+        id: ver
+        shell: bash
+        run: |
+          # Prefer release tag when present; fall back to ref name
+          if [ "${{ github.event_name }}" = "release" ]; then
+            TAG="${{ github.event.release.tag_name }}"
+          else
+            TAG="${{ github.ref_name }}"
+          fi
+          TAG="${TAG#v}"
+          echo "tag=$TAG" >> "$GITHUB_OUTPUT"
+
+      - name: Check version consistency
+        shell: bash
+        run: |
+          TAG="${{ steps.ver.outputs.tag }}"
+          # Extract only the [project] version from pyproject.toml
+          PYPROJ=$(awk '
+            /^\[project\]/ { in_proj=1; next }
+            /^\[/ { if (in_proj) exit }
+            in_proj && /^version =/ { match($0, /"([^"]+)"/, m); print m[1]; exit }
+          ' pyproject.toml)
+          # Extract APP_VERSION from constants
+          CONST=$(awk -F '"' '/^APP_VERSION =/ { print $2; exit }' src/tunacode/constants.py)
+          echo "Tag: $TAG"
+          echo "pyproject.toml: $PYPROJ"
+          echo "constants.APP_VERSION: $CONST"
+          if [[ "$TAG" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            [[ "$TAG" == "$PYPROJ" ]] || { echo 'pyproject.toml version mismatch'; exit 1; }
+            [[ "$TAG" == "$CONST" ]] || { echo 'constants.py APP_VERSION mismatch'; exit 1; }
+          else
+            echo "No semver tag detected; skipping tag consistency check."
+          fi
+
+      - name: Lint
+        run: hatch run lint-check
+
+      - name: Test
+        run: hatch run test
+
+      - name: Build
+        run: hatch build
+
+      # Preferred: API token secret
+      - name: Publish to PyPI (API token)
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }}
+        run: python -m twine upload dist/*
+
+      

{tunacode_cli-0.0.73 → tunacode_cli-0.0.76}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tunacode-cli
-Version: 0.0.73
+Version: 0.0.76
 Summary: Your agentic CLI developer.
 Project-URL: Homepage, https://tunacode.xyz/
 Project-URL: Repository, https://github.com/alchemiststudiosDOTai/tunacode

{tunacode_cli-0.0.73 → tunacode_cli-0.0.76}/documentation/README.md

@@ -19,7 +19,8 @@ documentation/
 │   ├── command-system-architecture.md
 │   ├── creating-custom-commands.md
 │   ├── hatch-build-system.md
-|   ├── performance-optimizations.md
+│   ├── performance-optimizations.md
+│   ├── publishing-workflow.md
 │   └── prompt-principles.md
 │── user/                 # user guides
     │── getting-started.md
@@ -36,6 +37,7 @@ General project documentation for features, architecture, and best practices.
 - [Command System Architecture](development/command-system-architecture.md) - Technical overview of the command system design and components.
 - [Creating Custom Commands](development/creating-custom-commands.md) - Step-by-step guide for creating built-in and slash commands.
 - [Hatch Build System](development/hatch-build-system.md) - Complete guide to using Hatch for development and building.
+- [Publishing Workflow](development/publishing-workflow.md) - Automated PyPI publishing process and release management.
 - [Configuration File Example](configuration/config-file-example.md) - Complete example of `~/.config/tunacode.json` with all available settings.
 - [Local Models Setup](configuration/local-models.md) - Guide for using local models with LM Studio or any OpenAI-compatible API.
 - [Performance Optimizations](development/performance-optimizations.md) - Major performance improvements and optimization strategies.

tunacode_cli-0.0.76/documentation/agent/agent-flow.md

@@ -0,0 +1,85 @@
+Now I have a good understanding of how the agent system works. Let me create a flowchart to explain the agent creation and processing flow:
+
+## TunaCode Agent Creation and Processing Flow
+
+```mermaid
+graph TD
+    A[User Request] --> B[process_request function]
+    B --> C[get_or_create_agent]
+    C --> D{Agent in Cache?}
+    D -->|Yes - Valid| E[Use Cached Agent]
+    D -->|No/Invalid| F[Create New Agent]
+    F --> G[Load System Prompt]
+    G --> H[Load TUNACODE.md Context]
+    F --> I[Initialize Tools]
+    I --> J{Plan Mode?}
+    J -->|Yes| K[Plan Mode Tools Only]
+    J -->|No| L[All Tools Available]
+    K --> M[Create Agent with Read-only + present_plan tools]
+    L --> N[Create Agent with All tools]
+    M --> O[Cache Agent]
+    N --> O
+    O --> P[Agent Iteration Loop]
+    P --> Q[Process Each Node]
+    Q --> R{Model Request Node?}
+    R -->|Yes + Streaming| S[Stream Token-level Response]
+    R -->|No| T[Process Node Content]
+    T --> U{Task Completion Marker?}
+    U -->|Yes| V[Mark Task Complete]
+    U -->|No| W[Check for Tool Calls]
+    W --> X{Read-only Tool?}
+    X -->|Yes| Y[Buffer for Parallel Execution]
+    X -->|No| Z[Execute Sequentially]
+    Y --> AA[ToolBuffer Collection]
+    Z --> AB[Immediate Tool Execution]
+    AA --> AC[Execute Buffered Tools in Parallel]
+    P --> AD{Max Iterations Reached?}
+    AD -->|Yes| AE[Create Fallback Response]
+    AD -->|No| AF[Continue Loop]
+    V --> AG[Return AgentRun Result]
+    AE --> AG
+    AF --> P
+```
+
+## Detailed Flow Explanation
+
+### 1. **Agent Creation Process**
+- **`get_or_create_agent(model, state_manager)`** is called for each request
+- Uses dual caching system (session-level and module-level)
+- Cache invalidation based on configuration changes
+- Loads system prompt from `src/tunacode/prompts/system.md`
+- Appends TUNACODE.md project context if available
+- Dynamically configures tools based on mode (plan vs normal)
+
+### 2. **Plan Mode vs Normal Mode**
+- **Plan Mode**: Restricted to read-only tools + `present_plan` tool
+- **Normal Mode**: Full toolset including write/execute tools
+- System prompt is completely replaced in plan mode with plan-specific instructions
+
+### 3. **Request Processing Loop**
+- **`process_request()`** creates agent iteration context
+- Processes nodes one by one in async loop
+- Handles streaming responses at token level
+- Monitors for task completion markers (`TUNACODE DONE:`)
+- Implements productivity tracking (3 consecutive empty iterations triggers action)
+- Manages tool execution batching for performance
+
+### 4. **Tool Execution Strategy**
+- **Read-only tools** (read_file, grep, list_dir, glob) are buffered for parallel execution
+- **Write/execute tools** (bash, run_command, write_file, update_file) run sequentially
+- **ToolBuffer** collects multiple read-only tools and executes them in batches
+- Provides speedup metrics and visual feedback during batch execution
+
+### 5. **Completion Detection**
+- Looks for `TUNACODE DONE:` marker in response content
+- Validates that no tools are queued when completion is signaled
+- Prevents premature completion when tools are pending
+- Handles fallback responses when iterations are exhausted
+
+### 6. **State Management**
+- Uses **ResponseState** with enum-based state machine
+- Tracks: USER_INPUT → ASSISTANT → TOOL_EXECUTION → RESPONSE transitions
+- Maintains backward compatibility with boolean flags
+- Session state persists across requests with caching
+
+The system is designed for optimal performance through parallel tool execution while maintaining safety through sequential write operations and comprehensive state tracking.

tunacode_cli-0.0.76/documentation/agent-tools/tools-architecture.md

@@ -0,0 +1,222 @@
+---
+title: "Research – AI Agent and Tools Architecture"
+date: "2025-09-12"
+owner: "context-engineer"
+phase: "Research"
+last_updated: "2025-09-12"
+last_updated_by: "context-engineer"
+last_updated_note: "Initial comprehensive research on AI agent and tools relation to OpenAI tool call format and JSON tooling"
+tags: ["agents", "tools", "openai", "json-tooling", "architecture", "pydantic-ai"]
+git_commit: "320ee40"
+---
+
+# Research – AI Agent and Tools Architecture
+**Date:** 2025-09-12
+**Owner:** context-engineer
+**Phase:** Research
+
+## Goal
+Summarize all *existing knowledge* about how the AI agent and tools are used in relation to the OpenAI tool call format and JSON tooling in the tunacode system before any new work.
+
+## Additional Search
+- `grep -ri "tool.*call" src/tunacode/core/agents/`
+- `grep -ri "openai.*tool" src/tunacode/`
+- `grep -ri "json.*tool" src/tunacode/core/agents/`
+
+## Findings
+
+### Core Architecture Overview
+
+The tunacode system implements a sophisticated tool calling architecture that bridges OpenAI's function calling specification with custom JSON tooling. The system is built around `pydantic-ai` as the primary framework while providing robust fallback mechanisms for maximum compatibility across different LLM providers.
+
+### Key Files & Components
+
+#### Agent System (`src/tunacode/core/agents/`)
+- `main.py` → Primary agent orchestrator using pydantic-ai with OpenAI tool integration
+- `agent_config.py` → Tool registration and configuration with pydantic-ai Tool wrappers
+- `agent_components/` → Core components for tool processing and execution
+  - `node_processor.py` → Tool call processing from LLM responses
+  - `tool_executor.py` → Parallel tool execution orchestration
+  - `json_tool_parser.py` → Fallback JSON tool parsing for non-structured APIs
+  - `tool_buffer.py` → Tool buffering for batch execution
+  - `message_handler.py` → Tool message patching and state management
+
+#### Tool System (`src/tunacode/tools/`)
+- `base.py` → BaseTool class with OpenAI function schema generation
+- `schema_assembler.py` → Tool schema assembly for different model providers
+- Individual tools (bash.py, grep.py, read_file.py, etc.) → Tool implementations with JSON Schema compliance
+
+#### LLM Integration (`src/tunacode/core/llm/` and utils/)
+- Model configuration and registry for OpenAI-compatible providers
+- API key validation and response parsing
+- Token cost calculation for different models
+
+### OpenAI Tool Call Format Implementation
+
+#### 1. Schema Generation Pattern
+All tools generate OpenAI-compatible function schemas through the `get_tool_schema()` method:
+
+```python
+{
+  "name": "tool_name",
+  "description": "Tool description with usage instructions",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "param_name": {
+        "type": "string|number|boolean|array",
+        "description": "Parameter description"
+      }
+    },
+    "required": ["required_param"]
+  }
+}
+```
+
+#### 2. Tool Registration with pydantic-ai
+Tools are registered using pydantic-ai's `Tool` wrapper for OpenAI compatibility:
+
+```python
+tools_list = [
+    Tool(bash, max_retries=max_retries, strict=tool_strict_validation),
+    Tool(grep, max_retries=max_retries, strict=tool_strict_validation),
+    # ... more tools
+]
+
+agent = Agent(
+    model=model,
+    system_prompt=system_prompt,
+    tools=tools_list,
+    mcp_servers=get_mcp_servers(state_manager),
+)
+```
+
+#### 3. Tool Call Processing Flow
+The system processes tool calls through multiple layers:
+1. **Primary**: OpenAI structured tool calling via pydantic-ai
+2. **Secondary**: JSON object parsing for non-structured APIs
+3. **Tertiary**: Manual tool execution with error handling
+
+### JSON Tooling Patterns
+
+#### 1. Fallback JSON Parsing
+When structured tool calling fails, the system extracts JSON objects using pattern matching:
+
+```python
+# Pattern: {"tool": "tool_name", "args": {...}}
+async def parse_json_tool_calls(text: str, tool_callback: Optional[ToolCallback],
+                               state_manager: StateManager) -> int:
+    # Find JSON objects in text using brace counting
+    # Validate tool structure and create mock tool call objects
+```
+
+#### 2. Schema-Driven Design
+- All tools implement JSON Schema for parameter validation
+- Dynamic schema generation based on execution context
+- XML-based schema definitions with hardcoded fallbacks
+- Environment-specific schema adaptation
+
+#### 3. Tool Result Handling
+- Structured error responses with `ModelRetry` support
+- Tool call tracking and state management
+- Message patching for orphaned tool calls
+- UI integration for user feedback
+
+### Parallel Execution Architecture
+
+#### 1. Tool Categorization
+- **Read-Only Tools**: `read_file`, `list_dir`, `grep`, `glob` (3-4x parallel performance)
+- **Write Tools**: `write_file`, `update_file` (sequential execution)
+- **System Tools**: `bash`, `run_command` (safety checks required)
+
+#### 2. Batching Strategy
+```python
+async def execute_tools_parallel(tool_calls: List[Tuple[Any, Any]],
+                               callback: ToolCallback, return_exceptions: bool = True) -> List[Any]:
+    max_parallel = int(os.environ.get("TUNACODE_MAX_PARALLEL", os.cpu_count() or 4))
+    # Batch execution with configurable parallelism
+```
+
+### Safety and Permission Systems
+
+#### 1. Tool Confirmation
+- Write/execute tools require user confirmation
+- Path restrictions and sandboxing
+- Dangerous operation warnings
+
+#### 2. Input Validation
+- Schema-based parameter validation
+- Type checking and range validation
+- File path safety checks
+
+### Configuration and Extensibility
+
+#### 1. Model Support
+- OpenAI GPT models with full tool calling support
+- Anthropic Claude models with JSON fallback
+- Local models via OpenAI-compatible APIs
+
+#### 2. MCP Integration
+- Model Context Protocol server support
+- External tool provider integration
+- Dynamic tool discovery
+
+## Key Patterns / Solutions Found
+
+### **Bridge Pattern**: System bridges OpenAI function calling, custom JSON tooling, and pydantic-ai interface
+- Relevance: Enables compatibility across multiple LLM providers
+- Location: `src/tunacode/core/agents/agent_config.py:45-67`
+
+### **Fallback Pattern**: Multi-layer fallback system ensures tool execution across different APIs
+- Relevance: Provides robustness when structured tool calling fails
+- Location: `src/tunacode/core/agents/agent_components/json_tool_parser.py:12-89`
+
+### **Schema-Driven Design**: All tools define JSON Schema for consistent parameter validation
+- Relevance: Standardizes tool interface and enables dynamic tool discovery
+- Location: `src/tunacode/tools/base.py:23-41`
+
+### **Parallelization Strategy**: Read-only tools batched for 3-4x performance improvement
+- Relevance: Dramatically improves performance for file operations and searches
+- Location: `src/tunacode/core/agents/agent_components/tool_executor.py:34-78`
+
+### **Safety Architecture**: Tool categorization with confirmation system prevents dangerous operations
+- Relevance: Essential for production-safe AI agent tooling
+- Location: `src/tunacode/core/tool_handler.py:23-67`
+
+## Knowledge Gaps
+
+### Missing Context
+- Detailed MCP server implementation patterns
+- Performance benchmarks for different tool batching strategies
+- Error recovery mechanisms for specific tool failure scenarios
+- Advanced configuration options for tool parallelism limits
+
+### Areas for Further Investigation
+- Real-world usage patterns and common failure modes
+- Integration patterns with external tool providers
+- Security implications of different tool execution strategies
+- Optimization opportunities for tool schema generation
+
+## References
+
+### Core Documentation
+- [Main Agent Architecture](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/documentation/agent/main-agent-architecture.md)
+- [Tool System Technical Guide](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/documentation/agent/tunacode-tool-system.md)
+- [Tools Workflow Guide](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/documentation/agent/TOOLS_WORKFLOW.md)
+
+### Key Implementation Files
+- [Agent Configuration](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/src/tunacode/core/agents/agent_config.py)
+- [Base Tool Implementation](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/src/tunacode/tools/base.py)
+- [Schema Assembler](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/src/tunacode/tools/schema_assembler.py)
+- [JSON Tool Parser](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/src/tunacode/core/agents/agent_components/json_tool_parser.py)
+- [Tool Executor](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/src/tunacode/core/agents/agent_components/tool_executor.py)
+
+### Configuration Files
+- [Model Configuration](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/src/tunacode/configuration/models.py)
+- [Default Settings](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/src/tunacode/configuration/defaults.py)
+- [Example Configuration](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/documentation/configuration/tunacode.json.example)
+
+### Testing Infrastructure
+- [Agent Initialization Tests](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/tests/test_agent_initialization.py)
+- [JSON Tool Parsing Tests](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/tests/characterization/agent/test_json_tool_parsing.py)
+- [Parallel Tool Execution Tests](https://github.com/alchemiststudiosDOTai/tunacode/blob/320ee40/tests/test_parallel_tool_execution.py)

tunacode_cli-0.0.76/documentation/changelog/CHANGELOG.md

@@ -0,0 +1,188 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.0.75] - 2025-09-12
+
+### Changed
+- Removed fallback PyPI auth method from CI workflow
+- Bumped version to 0.0.75
+
+### Fixed
+- Fixed version check in CI pipeline
+- Updated publish workflow constants for version 0.0.73
+
+## [0.0.74] - 2025-09-11
+
+### Added
+- Implemented enum-based state machine for agent completion detection
+- Added Claude command executor documentation and test guides
+
+### Changed
+- Enhanced agent loop architecture
+
+## [0.0.73] - 2025-09-11
+
+### Changed
+- Made tool strict validation configurable in tunacode.json
+- Enhanced /model command with multi-source routing and models.dev integration
+
+### Fixed
+- Added strict=False parameter to Tool constructors to prevent validation issues
+- Replaced invalid bright_white with ansiwhite in model selector
+- Updated model command tests to match new models.dev integration behavior
+
+## [0.0.72] - 2025-09-10
+
+### Changed
+- Refactored agent and command documentation structure
+- Improved wizard UX and fixed API key loading
+
+### Fixed
+- Prevent crash when API key is missing for configured model
+- Prevent config reset on startup by loading config before initialization
+
+## [0.0.71] - 2025-08-25
+
+### Added
+- Comprehensive TunaCode tool system documentation
+- Local models configuration guide
+
+### Changed
+- Refactored tool system and cleaned up obsolete tools
+- Excluded llm-agent-tools from pre-commit hooks and file checks
+
+## [0.0.70] - 2025-08-23
+
+### Added
+- Enhanced /update command with UV tool installation support
+- Improved venv detection for UV-created environments
+- Added emoji prohibition to system prompt
+
+### Changed
+- Changed default model to OpenRouter GPT-4.1
+- Migrated to UV for dependency management with Hatch integration
+- Enhanced install script with config file creation and setup guidance
+
+### Fixed
+- Improved venv installation detection for /update command
+- Added defusedxml dependency and fixed typer compatibility
+
+## [0.0.69] - 2025-08-21
+
+### Summary
+This release includes comprehensive command system documentation, updated model configurations, and builds upon recent community contributions including the slash command system by @Lftobs (#85) and onboarding improvements by @ryumacodes (#88).
+
+### Changed
+- Updated OpenRouter GPT model reference from `gpt-4o` to `gpt-4.1` in setup configuration
+
+### Added
+- Additional development documentation in `.claude/` directory
+  - Model updates documentation
+  - Slash commands documentation
+  - Onboarding improvements documentation
+
+## [0.0.68] - 2025-08-21
+
+### Added
+- **Comprehensive Command System Documentation**
+  - Created `command-system-architecture.md` with technical overview of command infrastructure
+  - Created `creating-custom-commands.md` with step-by-step guide for developers
+  - Updated user documentation with slash command information
+  - Added `/command-reload` command documentation
+
+### Fixed
+- Removed broken link to non-existent `templates.md` file in documentation
+
+## [0.0.67] - 2025-08-14
+
+### Added
+- Added UV tool installation support to /update command
+- Added venv manual update option to error message
+- Added emoji prohibition to system prompt
+
+### Fixed
+- Improved venv detection for UV-created environments
+- Added venv installation detection for /update command
+
+## [0.0.66] - 2025-08-14
+
+### Fixed
+- Replaced aggressive retry messaging with constructive guidance
+
+## [0.0.65] - 2025-08-14
+
+### Added
+- Implemented robust uninstall script with comprehensive detection
+- Implemented robust update logic for Linux installer
+
+### Changed
+- Changed default model to OpenRouter GPT-4.1
+- Enhanced install script with config file creation and setup guidance
+
+### Fixed
+- Added missing print helper functions to install script
+
+## [0.0.64] - 2025-08-14
+
+### Added
+- Implemented UV and Hatch support to installation scripts
+- Added comprehensive UV+Hatch setup documentation
+
+### Changed
+- Migrated to UV for dependency management
+- Optimized pre-commit hooks for Hatch+UV integration
+
+### Fixed
+- Properly configured Hatch with UV installer
+- Added defusedxml dependency and fixed typer compatibility
+
+## [0.0.63] - 2025-08-14
+
+### Added
+- Phase 5 - Tool Prompt Micro-Injection System
+
+### Fixed
+- Fixed agent initialization performance with strategic caching
+- Added exception for glob.py in file length check
+
+## [0.0.62] - 2025-08-14
+
+### Added
+- **Major Performance Optimizations & JSON Recovery System** (#82)
+- Phase 1 - Ripgrep binary management foundation
+
+### Changed
+- Complete UV+Hatch integration with dependency fixes
+
+## [Unreleased] - 2025-08-20
+
+### Added
+
+- **Comprehensive Onboarding Experience Improvements** (#88) - Thanks to **@ryumacodes**!
+  - Enhanced user onboarding flow and setup experience
+  - Improved first-time user guidance and documentation
+  - Streamlined installation and configuration process
+  - Resolved issue #55
+
+### Recent Pull Requests
+
+- **Slash Command System for Custom Automation Workflows** (#85) - Thanks to **@Lftobs**!
+  - Implemented flexible slash command infrastructure
+  - Enabled custom automation workflows
+  - Extended CLI capabilities with user-defined commands
+
+- **User Documentation and README Index** (#83) - Thanks to **@MclPio**!
+  - Added comprehensive user documentation
+  - Updated main README with organized index
+  - Improved documentation structure and accessibility
+
+### Contributors
+
+Special thanks to our recent contributors:
+- **@ryumacodes** - Onboarding improvements and multiple feature implementations
+- **@Lftobs** - Slash command system and workflow automation
+- **@MclPio** - Documentation improvements and organization