[ { "path": ".claude/commands/fix-github-issue.md", "content": "Please analyze and fix the GitHub issue: $ARGUMENTS.\n\nFollow these steps:\n\n1. Use `gh issue view` to get the issue details\n2. Understand the problem described in the issue\n3. Search the codebase for relevant files\n4. Implement the necessary changes to fix the issue\n5. Write and run tests to verify the fix\n6. Ensure code passes linting and type checking\n7. Create a descriptive commit message\n8. Push and create a PR\n\nRemember to use the GitHub CLI (`gh`) for all GitHub-related tasks.\n" }, { "path": ".claude/settings.json", "content": "{\n \"permissions\": {\n \"allow\": [\n ],\n \"deny\": []\n }\n}" }, { "path": ".coveragerc", "content": "[run]\nsource = gemini_server\nomit = \n */tests/*\n */venv/*\n */__pycache__/*\n */site-packages/*\n\n[report]\nexclude_lines =\n pragma: no cover\n def __repr__\n if self.debug:\n if settings.DEBUG\n raise AssertionError\n raise NotImplementedError\n if 0:\n if __name__ == .__main__.:\n if TYPE_CHECKING:\n class .*\\bProtocol\\):\n @(abc\\.)?abstractmethod\n\n[html]\ndirectory = htmlcov" }, { "path": ".dockerignore", "content": "# Git\n.git\n.gitignore\n\n# Python\n__pycache__/\n*.py[cod]\n*$py.class\n*.so\n.Python\nenv/\nvenv/\n.venv/\n.pal_venv/\nENV/\nenv.bak/\nvenv.bak/\n\n# IDE\n.vscode/\n.idea/\n*.swp\n*.swo\n\n# OS\n.DS_Store\nThumbs.db\n\n# Logs\nlogs/*.log*\n*.log\n\n# Docker\nDockerfile*\ndocker-compose*\n.dockerignore\n\n# Documentation\ndocs/\nREADME.md\n*.md\n\n# Tests\ntests/\nsimulator_tests/\ntest_simulation_files/\npytest.ini\n\n# Development\n.env\n.env.local\nexamples/\ncode_quality_checks.sh\nrun_integration_tests.sh\n\n# Security - Sensitive files\n*.key\n*.pem\n*.p12\n*.pfx\n*.crt\n*.csr\nsecrets/\nprivate/\n" }, { "path": ".gitattributes", "content": "# Ensure shell scripts always have LF line endings on checkout\n*.sh text eol=lf\n*.bash text eol=lf\n\n# Python files\n*.py text eol=lf\n\n# Shell script without extension\nrun-server text eol=lf\ncode_quality_checks text eol=lf\nrun_integration_tests text eol=lf\n\n# General text files\n*.md text\n*.txt text\n*.yml text\n*.yaml text\n*.json text\n*.xml text\n\n# Binary files\n*.png binary\n*.jpg binary\n*.jpeg binary\n*.gif binary\n*.ico binary\n*.pdf binary" }, { "path": ".github/FUNDING.yml", "content": "# These are supported funding model platforms\n\ngithub: [guidedways]\n" }, { "path": ".github/ISSUE_TEMPLATE/bug_report.yml", "content": "name: 🐞 Bug Report\ndescription: Create a report to help us improve\nlabels: [\"bug\", \"needs-triage\"]\nbody:\n - type: markdown\n attributes:\n value: |\n Thank you for taking the time to file a bug report! Please provide as much detail as possible to help us reproduce and fix the issue.\n\n - type: input\n id: version\n attributes:\n label: Project Version\n description: \"Which version are you using? (To see version: ./run-server.sh -v)\"\n placeholder: \"e.g., 9.4.1\"\n validations:\n required: true\n\n - type: textarea\n id: description\n attributes:\n label: Bug Description\n description: A clear and concise description of what the bug is.\n placeholder: \"When I run the `codereview` nothing happens\"\n validations:\n required: true\n\n - type: textarea\n id: logs\n attributes:\n label: Relevant Log Output\n description: \"Please copy and paste any relevant log output. Logs are stored under the `logs` folder in the pal folder. You an also use `./run-server.sh -f` to see logs\"\n render: shell\n\n - type: dropdown\n id: environment\n attributes:\n label: Operating System\n description: What operating system are you running the Docker client on?\n options:\n - macOS\n - Windows\n - Linux\n validations:\n required: true\n\n - type: checkboxes\n id: no-duplicate-issues\n attributes:\n label: Sanity Checks\n description: \"Before submitting, please confirm the following:\"\n options:\n - label: I have searched the existing issues and this is not a duplicate.\n required: true\n - label: I am using `GEMINI_API_KEY`\n required: true\n - label: I am using `OPENAI_API_KEY`\n required: true\n - label: I am using `OPENROUTER_API_KEY`\n required: true\n - label: I am using `CUSTOM_API_URL`\n required: true\n" }, { "path": ".github/ISSUE_TEMPLATE/config.yml", "content": "blank_issues_enabled: false\ncontact_links:\n - name: πŸ’¬ General Discussion\n url: https://github.com/BeehiveInnovations/pal-mcp-server/discussions\n about: Ask questions, share ideas, or discuss usage patterns with the community\n - name: πŸ“š Documentation\n url: https://github.com/BeehiveInnovations/pal-mcp-server/blob/main/README.md\n about: Check the README for setup instructions and usage examples\n - name: 🀝 Contributing Guide\n url: https://github.com/BeehiveInnovations/pal-mcp-server/blob/main/CONTRIBUTING.md\n about: Learn how to contribute to the project\n\n" }, { "path": ".github/ISSUE_TEMPLATE/documentation.yml", "content": "name: πŸ“– Documentation Improvement\ndescription: Report an issue or suggest an improvement for the documentation\nlabels: [\"documentation\", \"good first issue\"]\nbody:\n - type: input\n id: location\n attributes:\n label: Documentation Location\n description: \"Which file or page has the issue? (e.g., README.md, CONTRIBUTING.md, CLAUDE.md)\"\n placeholder: \"e.g., README.md\"\n validations:\n required: true\n\n - type: dropdown\n id: issue-type\n attributes:\n label: Type of Documentation Issue\n description: What kind of documentation improvement is this?\n options:\n - Typo or grammar error\n - Unclear or confusing explanation\n - Outdated information\n - Missing information\n - Code example doesn't work\n - Installation/setup instructions unclear\n - Tool usage examples need improvement\n - Other\n validations:\n required: true\n\n - type: textarea\n id: problem\n attributes:\n label: What is wrong with the documentation?\n description: \"Please describe the problem. Be specific about what is unclear, incorrect, or missing.\"\n placeholder: \"README is missing some details\"\n validations:\n required: true\n\n - type: textarea\n id: suggestion\n attributes:\n label: Suggested Improvement\n description: \"How can we make it better? If you can, please provide the exact text or changes you'd like to see.\"\n placeholder: \"Please improve....\"\n\n\n - type: dropdown\n id: audience\n attributes:\n label: Target Audience\n description: Which audience would benefit most from this improvement?\n options:\n - New users (first-time setup)\n - Developers (contributing to the project)\n - Advanced users (complex workflows)\n - All users\n validations:\n required: true\n\n" }, { "path": ".github/ISSUE_TEMPLATE/feature_request.yml", "content": "name: ✨ Feature Request\ndescription: Suggest an idea for this project\nlabels: [\"enhancement\", \"needs-triage\"]\nbody:\n - type: textarea\n id: problem-description\n attributes:\n label: What problem is this feature trying to solve?\n description: \"A clear and concise description of the problem or user need. Why is this change needed?\"\n placeholder: \"Currently, I can only use one Gemini tool at a time. I want to be able to chain multiple tools together (e.g., analyze -> codereview -> thinkdeep) in a single workflow.\"\n validations:\n required: true\n\n - type: textarea\n id: proposed-solution\n attributes:\n label: Describe the solution you'd like\n description: A clear and concise description of what you want to happen. How would it work from a user's perspective?\n placeholder: \"I'd like to be able to specify a workflow like 'analyze src/ then codereview the findings then use thinkdeep to suggest improvements' in a single command or configuration.\"\n validations:\n required: true\n\n - type: textarea\n id: alternatives\n attributes:\n label: Describe alternatives you've considered\n description: A clear and concise description of any alternative solutions or features you've considered.\n placeholder: \"I considered manually running each tool sequentially, but automatic workflow chaining would be more efficient and ensure context is preserved between steps.\"\n\n - type: dropdown\n id: feature-type\n attributes:\n label: Feature Category\n description: What type of enhancement is this?\n options:\n - New tool (chat, codereview, debug, etc.)\n - Workflow improvement\n - Integration enhancement\n - Performance optimization\n - User experience improvement\n - Documentation enhancement\n - Other\n validations:\n required: true\n\n - type: checkboxes\n id: contribution\n attributes:\n label: Contribution\n options:\n - label: I am willing to submit a Pull Request to implement this feature.\n\n" }, { "path": ".github/ISSUE_TEMPLATE/tool_addition.yml", "content": "name: πŸ› οΈ New Gemini Tool Proposal\ndescription: Propose a new PAL MCP tool (e.g., `summarize`, `fixer`, `refactor`)\nlabels: [\"enhancement\", \"new-tool\"]\nbody:\n - type: input\n id: tool-name\n attributes:\n label: Proposed Tool Name\n description: \"What would the tool be called? (e.g., `summarize`, `docgen`, `refactor`)\"\n placeholder: \"e.g., `docgen`\"\n validations:\n required: true\n\n - type: textarea\n id: purpose\n attributes:\n label: What is the primary purpose of this tool?\n description: \"Explain the tool's core function and the value it provides to developers using Claude + PAL.\"\n placeholder: \"This tool will automatically generate comprehensive documentation from code, extracting class and function signatures, docstrings, and creating usage examples.\"\n validations:\n required: true\n\n - type: textarea\n id: example-usage\n attributes:\n label: Example Usage in Claude Desktop\n description: \"Show how a user would invoke this tool through Claude and what the expected output would look like.\"\n placeholder: |\n **User prompt to Claude:**\n \"Use pal to generate documentation for my entire src/ directory\"\n\n **Expected behavior:**\n - Analyze all Python files in src/\n - Extract classes, functions, and their docstrings\n - Generate structured markdown documentation\n - Include usage examples where possible\n - Return organized documentation with table of contents\n render: markdown\n validations:\n required: true\n\n - type: dropdown\n id: tool-category\n attributes:\n label: Tool Category\n description: What category does this tool fit into?\n options:\n - Code Analysis (like analyze)\n - Code Quality (like codereview)\n - Code Generation/Refactoring\n - Documentation Generation\n - Testing Support\n - Debugging Support (like debug)\n - Workflow Automation\n - Architecture Planning (like thinkdeep)\n - Other\n validations:\n required: true\n\n - type: textarea\n id: system-prompt\n attributes:\n label: Proposed System Prompt (Optional)\n description: \"If you have ideas for how pal should be prompted for this tool, share them here.\"\n placeholder: |\n You are an expert technical documentation generator. Your task is to create comprehensive, user-friendly documentation from source code...\n\n - type: checkboxes\n id: contribution\n attributes:\n label: Contribution\n options:\n - label: I am willing to submit a Pull Request to implement this new tool.\n - label: I have checked that this tool doesn't overlap significantly with existing tools (analyze, codereview, debug, thinkdeep, chat).\n\n" }, { "path": ".github/pull_request_template.md", "content": "## PR Title Format\n\n**Please ensure your PR title follows [Conventional Commits](https://www.conventionalcommits.org/) format:**\n\n### Version Bumping Types (trigger semantic release):\n- `feat: ` - New features β†’ **MINOR** version bump (1.1.0 β†’ 1.2.0)\n- `fix: ` - Bug fixes β†’ **PATCH** version bump (1.1.0 β†’ 1.1.1) \n- `perf: ` - Performance improvements β†’ **PATCH** version bump (1.1.0 β†’ 1.1.1)\n\n### Breaking Changes (trigger MAJOR version bump):\nFor breaking changes, use any commit type above with `BREAKING CHANGE:` in the commit body or `!` after the type:\n- `feat!: ` β†’ **MAJOR** version bump (1.1.0 β†’ 2.0.0)\n- `fix!: ` β†’ **MAJOR** version bump (1.1.0 β†’ 2.0.0)\n\n### Non-Versioning Types (no release):\n- `build: ` - Build system changes\n- `chore: ` - Maintenance tasks\n- `ci: ` - CI/CD changes\n- `docs: ` - Documentation only\n- `refactor: ` - Code refactoring (no functional changes)\n- `style: ` - Code style/formatting changes\n- `test: ` - Test additions/changes\n\n### Docker Build Triggering:\n\nDocker builds are **independent** of versioning and trigger based on:\n\n**Automatic**: When PRs modify relevant files:\n- Python files (`*.py`), `requirements*.txt`, `pyproject.toml`\n- Docker files (`Dockerfile`, `docker-compose.yml`, `.dockerignore`)\n\n**Manual**: Add the `docker-build` label to force builds for any PR.\n\n## Description\n\nPlease provide a clear and concise description of what this PR does.\n\n## Changes Made\n\n- [ ] List the specific changes made\n- [ ] Include any breaking changes\n- [ ] Note any dependencies added/removed\n\n## Testing\n\n**Please review our [Testing Guide](../docs/testing.md) before submitting.**\n\n### Run all linting and tests (required):\n```bash\n# Activate virtual environment first\nsource venv/bin/activate\n\n# Run comprehensive code quality checks (recommended)\n./code_quality_checks.sh\n\n# If you made tool changes, also run simulator tests\npython communication_simulator_test.py\n```\n\n- [ ] All linting passes (ruff, black, isort)\n- [ ] All unit tests pass\n- [ ] **For new features**: Unit tests added in `tests/`\n- [ ] **For tool changes**: Simulator tests added in `simulator_tests/`\n- [ ] **For bug fixes**: Tests added to prevent regression\n- [ ] Simulator tests pass (if applicable)\n- [ ] Manual testing completed with realistic scenarios\n\n## Related Issues\n\nFixes #(issue number)\n\n## Checklist\n\n- [ ] PR title follows the format guidelines above\n- [ ] **Activated venv and ran code quality checks: `source venv/bin/activate && ./code_quality_checks.sh`**\n- [ ] Self-review completed\n- [ ] **Tests added for ALL changes** (see Testing section above)\n- [ ] Documentation updated as needed\n- [ ] All unit tests passing\n- [ ] Relevant simulator tests passing (if tool changes)\n- [ ] Ready for review\n\n## Additional Notes\n\nAny additional information that reviewers should know." }, { "path": ".github/workflows/docker-pr.yml", "content": "name: PR Docker Build\n\non:\n pull_request:\n types: [opened, synchronize, reopened, labeled, unlabeled]\n paths:\n - '**.py'\n - 'requirements*.txt'\n - 'pyproject.toml'\n - 'Dockerfile'\n - 'docker-compose.yml'\n - '.dockerignore'\n\npermissions:\n contents: read\n packages: write\n pull-requests: write\n\njobs:\n docker:\n name: Build Docker Image\n runs-on: ubuntu-latest\n if: |\n github.event.action == 'opened' ||\n github.event.action == 'synchronize' ||\n github.event.action == 'reopened' ||\n contains(github.event.pull_request.labels.*.name, 'docker-build')\n \n steps:\n - name: Checkout\n uses: actions/checkout@v4\n\n - name: Set up Docker Buildx\n uses: docker/setup-buildx-action@v3\n\n - name: Login to GitHub Container Registry\n if: github.event.pull_request.head.repo.full_name == github.repository\n uses: docker/login-action@v3\n with:\n registry: ghcr.io\n username: ${{ github.actor }}\n password: ${{ secrets.GITHUB_TOKEN }}\n\n - name: Extract metadata\n id: meta\n uses: docker/metadata-action@v5\n with:\n images: ghcr.io/${{ github.repository }}\n tags: |\n # PR-specific tag for testing\n type=raw,value=pr-${{ github.event.number }}-${{ github.sha }}\n type=raw,value=pr-${{ github.event.number }}\n\n - name: Build and push Docker image (internal PRs)\n if: github.event.pull_request.head.repo.full_name == github.repository\n uses: docker/build-push-action@v5\n with:\n context: .\n platforms: linux/amd64,linux/arm64\n push: true\n tags: ${{ steps.meta.outputs.tags }}\n labels: ${{ steps.meta.outputs.labels }}\n cache-from: type=gha\n cache-to: type=gha,mode=max\n\n - name: Build Docker image (fork PRs)\n if: github.event.pull_request.head.repo.full_name != github.repository\n uses: docker/build-push-action@v5\n with:\n context: .\n platforms: linux/amd64,linux/arm64\n push: false\n tags: ${{ steps.meta.outputs.tags }}\n labels: ${{ steps.meta.outputs.labels }}\n cache-from: type=gha\n cache-to: type=gha,mode=max\n\n - name: Add Docker build comment (internal PRs)\n if: github.event.pull_request.head.repo.full_name == github.repository\n uses: marocchino/sticky-pull-request-comment@d2ad0de260ae8b0235ce059e63f2949ba9e05943 # v2.9.3\n with:\n header: docker-build\n message: |\n ## 🐳 Docker Build Complete\n \n **PR**: #${{ github.event.number }} | **Commit**: `${{ github.sha }}`\n \n ```\n ${{ steps.meta.outputs.tags }}\n ```\n \n **Test:** `docker pull ghcr.io/${{ github.repository }}:pr-${{ github.event.number }}`\n \n **Claude config:**\n ```json\n {\n \"mcpServers\": {\n \"pal\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"-e\", \"GEMINI_API_KEY\", \"ghcr.io/${{ github.repository }}:pr-${{ github.event.number }}\"],\n \"env\": { \"GEMINI_API_KEY\": \"your-key\" }\n }\n }\n }\n ```\n \n πŸ’‘ Add `docker-build` label to manually trigger builds\n\n\n - name: Update job summary (internal PRs)\n if: github.event.pull_request.head.repo.full_name == github.repository\n run: |\n {\n echo \"## 🐳 Docker Build Complete\"\n echo \"**PR**: #${{ github.event.number }} | **Commit**: ${{ github.sha }}\"\n echo '```'\n echo \"${{ steps.meta.outputs.tags }}\"\n echo '```'\n } >> $GITHUB_STEP_SUMMARY\n\n - name: Update job summary (fork PRs)\n if: github.event.pull_request.head.repo.full_name != github.repository\n run: |\n {\n echo \"## 🐳 Docker Build Complete (Build Only)\"\n echo \"**PR**: #${{ github.event.number }} | **Commit**: ${{ github.sha }}\"\n echo \"βœ… Multi-platform Docker build successful\"\n echo \"Note: Fork PRs only build (no push) for security\"\n } >> $GITHUB_STEP_SUMMARY\n" }, { "path": ".github/workflows/docker-release.yml", "content": "name: Docker Release Build\n\non:\n release:\n types: [published]\n workflow_dispatch:\n inputs:\n tag:\n description: 'Tag to build (leave empty for latest release)'\n required: false\n type: string\n\npermissions:\n contents: read\n packages: write\n\njobs:\n docker:\n name: Build and Push Docker Image\n runs-on: ubuntu-latest\n \n steps:\n - name: Checkout\n uses: actions/checkout@v4\n with:\n # If triggered by workflow_dispatch with a tag, checkout that tag\n ref: ${{ inputs.tag || github.event.release.tag_name }}\n\n - name: Set up Docker Buildx\n uses: docker/setup-buildx-action@v3\n\n - name: Login to GitHub Container Registry\n uses: docker/login-action@v3\n with:\n registry: ghcr.io\n username: ${{ github.actor }}\n password: ${{ secrets.GITHUB_TOKEN }}\n\n - name: Extract metadata\n id: meta\n uses: docker/metadata-action@v5\n with:\n images: ghcr.io/${{ github.repository }}\n tags: |\n # Tag with the release version\n type=semver,pattern={{version}},value=${{ inputs.tag || github.event.release.tag_name }}\n type=semver,pattern={{major}}.{{minor}},value=${{ inputs.tag || github.event.release.tag_name }}\n type=semver,pattern={{major}},value=${{ inputs.tag || github.event.release.tag_name }}\n # Also tag as latest for the most recent release\n type=raw,value=latest,enable={{is_default_branch}}\n\n - name: Build and push Docker image\n uses: docker/build-push-action@v5\n with:\n context: .\n platforms: linux/amd64,linux/arm64\n push: true\n tags: ${{ steps.meta.outputs.tags }}\n labels: ${{ steps.meta.outputs.labels }}\n cache-from: type=gha\n cache-to: type=gha,mode=max\n\n - name: Update release with Docker info\n if: github.event_name == 'release'\n run: |\n RELEASE_TAG=\"${{ github.event.release.tag_name }}\"\n DOCKER_TAGS=$(echo \"${{ steps.meta.outputs.tags }}\" | tr '\\n' ' ')\n \n # Add Docker information to the release\n gh release edit \"$RELEASE_TAG\" --notes-file - << EOF\n ${{ github.event.release.body }}\n \n ---\n \n ## 🐳 Docker Images\n \n This release is available as Docker images:\n \n $(echo \"$DOCKER_TAGS\" | sed 's/ghcr.io/- `ghcr.io/g' | sed 's/ /`\\n/g')\n \n **Quick start with Docker:**\n \\`\\`\\`bash\n docker pull ghcr.io/${{ github.repository }}:$RELEASE_TAG\n \\`\\`\\`\n \n **Claude Desktop configuration:**\n \\`\\`\\`json\n {\n \"mcpServers\": {\n \"pal-mcp-server\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"--rm\", \"-i\",\n \"-e\", \"GEMINI_API_KEY\",\n \"ghcr.io/${{ github.repository }}:$RELEASE_TAG\"\n ],\n \"env\": {\n \"GEMINI_API_KEY\": \"your-api-key-here\"\n }\n }\n }\n }\n \\`\\`\\`\n EOF\n env:\n GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n\n - name: Create deployment summary\n run: |\n echo \"## 🐳 Docker Release Build Complete\" >> $GITHUB_STEP_SUMMARY\n echo \"\" >> $GITHUB_STEP_SUMMARY\n echo \"**Release**: ${{ inputs.tag || github.event.release.tag_name }}\" >> $GITHUB_STEP_SUMMARY\n echo \"**Images built:**\" >> $GITHUB_STEP_SUMMARY\n echo \"\\`\\`\\`\" >> $GITHUB_STEP_SUMMARY\n echo \"${{ steps.meta.outputs.tags }}\" >> $GITHUB_STEP_SUMMARY\n echo \"\\`\\`\\`\" >> $GITHUB_STEP_SUMMARY" }, { "path": ".github/workflows/semantic-pr.yml", "content": "---\nname: Semantic PR\n\non:\n pull_request:\n types: [opened, edited, synchronize]\n\nconcurrency:\n group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}\n cancel-in-progress: true\n\npermissions:\n contents: read\n pull-requests: write\n\njobs:\n semantic-pr:\n name: Validate PR\n runs-on: ubuntu-latest\n timeout-minutes: 5\n steps:\n - name: Check PR Title\n id: lint-pr-title\n uses: amannn/action-semantic-pull-request@0723387faaf9b38adef4775cd42cfd5155ed6017 # v5.5.3\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n\n - name: Add PR error comment\n uses: marocchino/sticky-pull-request-comment@d2ad0de260ae8b0235ce059e63f2949ba9e05943 # v2.9.3\n if: always() && (steps.lint-pr-title.outputs.error_message != null)\n with:\n header: pr-title-lint-error\n message: |\n We require pull request titles to follow the [Conventional Commits specification](https://www.conventionalcommits.org/en/v1.0.0/) and it looks like your proposed title needs to be adjusted.\n\n Details:\n\n ```\n ${{ steps.lint-pr-title.outputs.error_message }}\n ```\n\n - name: Delete PR error comment\n uses: marocchino/sticky-pull-request-comment@d2ad0de260ae8b0235ce059e63f2949ba9e05943 # v2.9.3\n if: ${{ steps.lint-pr-title.outputs.error_message == null }}\n with:\n header: pr-title-lint-error\n delete: true" }, { "path": ".github/workflows/semantic-release.yml", "content": "name: Semantic Release\n\non:\n push:\n branches:\n - main\n\npermissions:\n contents: write\n issues: write\n pull-requests: write\n\njobs:\n release:\n runs-on: ubuntu-latest\n concurrency: release\n\n steps:\n - name: Checkout\n uses: actions/checkout@v4\n with:\n fetch-depth: 0\n token: ${{ secrets.GITHUB_TOKEN }}\n persist-credentials: true\n\n - name: Setup Python\n uses: actions/setup-python@v4\n with:\n python-version: \"3.11\"\n\n - name: Install dependencies\n run: |\n python -m pip install --upgrade pip\n pip install python-semantic-release\n\n - name: Verify tests pass\n run: |\n pip install -r requirements.txt\n pip install -r requirements-dev.txt\n python -m pytest tests/ -v --ignore=simulator_tests/ -m \"not integration\"\n\n - name: Run semantic release\n env:\n GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n run: |\n git config --global user.name \"github-actions[bot]\"\n git config --global user.email \"github-actions[bot]@users.noreply.github.com\"\n semantic-release version\n semantic-release publish\n \n - name: Sync version to config.py\n run: |\n pip install toml\n python scripts/sync_version.py\n if git diff --quiet config.py; then\n echo \"No version changes in config.py\"\n else\n git add config.py\n git commit -m \"chore: sync version to config.py [skip ci]\"\n git push\n fi\n\n - name: Upload build artifacts to release\n if: hashFiles('dist/*') != ''\n run: |\n # Get the latest release tag\n LATEST_TAG=$(gh release list --limit 1 --json tagName --jq '.[0].tagName')\n if [ ! -z \"$LATEST_TAG\" ]; then\n echo \"Uploading artifacts to release $LATEST_TAG\"\n gh release upload \"$LATEST_TAG\" dist/* --clobber\n fi\n env:\n GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n" }, { "path": ".github/workflows/test.yml", "content": "name: Tests\n\non:\n pull_request:\n branches: [main]\n\njobs:\n test:\n runs-on: ubuntu-latest\n strategy:\n matrix:\n python-version: [\"3.10\", \"3.11\", \"3.12\"]\n\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python ${{ matrix.python-version }}\n uses: actions/setup-python@v4\n with:\n python-version: ${{ matrix.python-version }}\n\n - name: Install dependencies\n run: |\n python -m pip install --upgrade pip\n pip install -r requirements.txt\n pip install -r requirements-dev.txt\n\n - name: Run unit tests\n run: |\n # Run only unit tests (exclude simulation tests and integration tests)\n # Integration tests require local-llama which isn't available in CI\n python -m pytest tests/ -v --ignore=simulator_tests/ -m \"not integration\"\n env:\n # Ensure no API key is accidentally used in CI\n GEMINI_API_KEY: \"\"\n OPENAI_API_KEY: \"\"\n\n lint:\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n\n - name: Set up Python\n uses: actions/setup-python@v4\n with:\n python-version: \"3.11\"\n\n - name: Install dependencies\n run: |\n python -m pip install --upgrade pip\n pip install -r requirements-dev.txt\n\n - name: Run black formatter check\n run: black --check . --exclude=\"test_simulation_files/\"\n\n - name: Run ruff linter\n run: ruff check . --exclude test_simulation_files\n" }, { "path": ".gitignore", "content": "# Byte-compiled / optimized / DLL files\n__pycache__/\n*.py[cod]\n*$py.class\n\n# C extensions\n*.so\n\n# Distribution / packaging\n.Python\nbuild/\ndevelop-eggs/\ndist/\ndownloads/\neggs/\n.eggs/\nlib/\nlib64/\nparts/\nsdist/\nvar/\nwheels/\nshare/python-wheels/\n*.egg-info/\n.installed.cfg\n*.egg\nMANIFEST\n\n# PyInstaller\n*.manifest\n*.spec\n\n# Installer logs\npip-log.txt\npip-delete-this-directory.txt\n\n# Unit test / coverage reports\nhtmlcov/\n.tox/\n.nox/\n.coverage\n.coverage.*\n.cache\nnosetests.xml\ncoverage.xml\n*.cover\n*.py,cover\n.hypothesis/\n.pytest_cache/\ncover/\n\n# Translations\n*.mo\n*.pot\n\n# Django stuff:\n*.log\nlocal_settings.py\ndb.sqlite3\ndb.sqlite3-journal\n\n# Flask stuff:\ninstance/\n.webassets-cache\n\n# Scrapy stuff:\n.scrapy\n\n# Sphinx documentation\ndocs/_build/\n\n# PyBuilder\n.pybuilder/\ntarget/\n\n# Jupyter Notebook\n.ipynb_checkpoints\n\n# IPython\nprofile_default/\nipython_config.py\n\n# pyenv\n.python-version\n\n# pipenv\nPipfile.lock\n\n# poetry\npoetry.lock\n\n# pdm\n.pdm.toml\n.pdm-python\npdm.lock\n\n# PEP 582\n__pypackages__/\n\n# Celery stuff\ncelerybeat-schedule\ncelerybeat.pid\n\n# SageMath parsed files\n*.sage.py\n\n# Environments\n.env\n.env~\n.venv\nenv/\nvenv/\nENV/\nenv.bak/\nvenv.bak/\n\n# Spyder project settings\n.spyderproject\n.spyproject\n\n# Rope project settings\n.ropeproject\n\n# mkdocs documentation\n/site\n\n# mypy\n.mypy_cache/\n.dmypy.json\ndmypy.json\n\n# Pyre type checker\n.pyre/\n\n# pytype static type analyzer\n.pytype/\n\n# Cython debug symbols\ncython_debug/\n\n# PyCharm\n.idea/\n\n# VS Code\n.vscode/\n\n# macOS\n.DS_Store\n\n# API Keys and secrets\n*.key\n*.pem\n.env.local\n.env.*.local\n\n# Test outputs\ntest_output/\n*.test.log\n.coverage\nhtmlcov/\ncoverage.xml\n.pytest_cache/\n\n# Test simulation artifacts (dynamically created during testing)\ntest_simulation_files/.claude/\n\n# Temporary test directories\ntest-setup/\n\n# Scratch feature documentation files\nFEATURE_*.md\n# Temporary files\n/tmp/\n\n# Local user instructions\nCLAUDE.local.md\n\n# Claude Code personal settings\n.claude/settings.local.json\n\n# Standalone mode files\n.pal_venv/\n.docker_cleaned\nlogs/\n*.backup\n*.backup-*.json\n/.desktop_configured\n\n/worktrees/\ntest_simulation_files/\n.mcp.json\n" }, { "path": ".pre-commit-config.yaml", "content": "---\ndefault_stages: [pre-commit, pre-push]\nrepos:\n - repo: https://github.com/psf/black\n rev: 25.1.0\n hooks:\n - id: black\n\n - repo: https://github.com/pycqa/isort\n rev: 6.0.1\n hooks:\n - id: isort\n args: [\"--profile\", \"black\"]\n\n - repo: https://github.com/astral-sh/ruff-pre-commit\n rev: v0.12.8\n hooks:\n - id: ruff\n args: [--fix]\n\n# Configuration for specific tools\ndefault_language_version:\n python: python3\n\n# Exclude patterns\nexclude: |\n (?x)^(\n \\.git/|\n \\.venv/|\n venv/|\n \\.pal_venv/|\n __pycache__/|\n \\.pytest_cache/|\n logs/|\n dist/|\n build/|\n test_simulation_files/\n )\n" }, { "path": "AGENTS.md", "content": "# Repository Guidelines\n\nSee `requirements.txt` and `requirements-dev.txt`\n\nAlso read CLAUDE.md and CLAUDE.local.md if available.\n\n## Project Structure & Module Organization\nPAL MCP Server centers on `server.py`, which exposes MCP entrypoints and coordinates multi-model workflows. \nFeature-specific tools live in `tools/`, provider integrations in `providers/`, and shared helpers in `utils/`. \nPrompt and system context assets stay in `systemprompts/`, while configuration templates and automation scripts live under `conf/`, `scripts/`, and `docker/`. \nUnit tests sit in `tests/`; simulator-driven scenarios and log utilities are in `simulator_tests/` with the `communication_simulator_test.py` harness. \nAuthoritative documentation and samples live in `docs/`, and runtime diagnostics are rotated in `logs/`.\n\n## Build, Test, and Development Commands\n- `source .pal_venv/bin/activate` – activate the managed Python environment.\n- `./run-server.sh` – install dependencies, refresh `.env`, and launch the MCP server locally.\n- `./code_quality_checks.sh` – run Ruff autofix, Black, isort, and the default pytest suite.\n- `python communication_simulator_test.py --quick` – smoke-test orchestration across tools and providers.\n- `./run_integration_tests.sh [--with-simulator]` – exercise provider-dependent flows against remote or Ollama models.\n\nRun code quality checks:\n```bash\n.pal_venv/bin/activate && ./code_quality_checks.sh\n```\n\nFor example, this is how we run an individual / all tests:\n\n```bash\n.pal_venv/bin/activate && pytest tests/test_auto_mode_model_listing.py -q\n.pal_venv/bin/activate && pytest -q\n```\n\n## Coding Style & Naming Conventions\nTarget Python 3.9+ with Black and isort using a 120-character line limit; Ruff enforces pycodestyle, pyflakes, bugbear, comprehension, and pyupgrade rules. Prefer explicit type hints, snake_case modules, and imperative commit-time docstrings. Extend workflows by defining hook or abstract methods instead of checking `hasattr()`/`getattr()`β€”inheritance-backed contracts keep behavior discoverable and testable.\n\n## Testing Guidelines\nMirror production modules inside `tests/` and name tests `test_` or `Test` classes. Run `python -m pytest tests/ -v -m \"not integration\"` before every commit, adding `--cov=. --cov-report=html` for coverage-sensitive changes. Use `python communication_simulator_test.py --verbose` or `--individual ` to validate cross-agent flows, and reserve `./run_integration_tests.sh` for provider or transport modifications. Capture relevant excerpts from `logs/mcp_server.log` or `logs/mcp_activity.log` when documenting failures.\n\n## Commit & Pull Request Guidelines\nFollow Conventional Commits: `type(scope): summary`, where `type` is one of `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, or `chore`. Keep commits focused, referencing issues or simulator cases when helpful. Pull requests should outline intent, list validation commands executed, flag configuration or tool toggles, and attach screenshots or log snippets when user-visible behavior changes.\n\n## GitHub CLI Commands\nThe GitHub CLI (`gh`) streamlines issue and PR management directly from the terminal.\n\n### Viewing Issues\n```bash\n# View issue details in current repository\ngh issue view \n\n# View issue from specific repository\ngh issue view --repo owner/repo-name\n\n# View issue with all comments\ngh issue view --comments\n\n# Get issue data as JSON for scripting\ngh issue view --json title,body,author,state,labels,comments\n\n# Open issue in web browser\ngh issue view --web\n```\n\n### Managing Issues\n```bash\n# List all open issues\ngh issue list\n\n# List issues with filters\ngh issue list --label bug --state open\n\n# Create a new issue\ngh issue create --title \"Issue title\" --body \"Description\"\n\n# Close an issue\ngh issue close \n\n# Reopen an issue\ngh issue reopen \n```\n\n### Pull Request Operations\n```bash\n# View PR details\ngh pr view \n\n# List pull requests\ngh pr list\n\n# Create a PR from current branch\ngh pr create --title \"PR title\" --body \"Description\"\n\n# Check out a PR locally\ngh pr checkout \n\n# Merge a PR\ngh pr merge \n```\n\nInstall GitHub CLI: `brew install gh` (macOS) or visit https://cli.github.com for other platforms.\n\n## Security & Configuration Tips\nStore API keys and provider URLs in `.env` or your MCP client config; never commit secrets or generated log artifacts. Use `run-server.sh` to regenerate environments and verify connectivity after dependency changes. When adding providers or tools, sanitize prompts and responses, document required environment variables in `docs/`, and update `claude_config_example.json` if new capabilities ship by default.\n" }, { "path": "CHANGELOG.md", "content": "# CHANGELOG\n\n\n\n## v9.8.2 (2025-12-15)\n\n### Bug Fixes\n\n- Allow home subdirectories through is_dangerous_path()\n ([`e5548ac`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/e5548acb984ca4f8b2ae8381f879a0285094257f))\n\n- Path traversal vulnerability - use prefix matching in is_dangerous_path()\n ([`9ed15f4`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/9ed15f405a9462b4db7aa44ca2d989e092c008e4))\n\n- Use Path.is_relative_to() for cross-platform dangerous path detection\n ([`91ffb51`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/91ffb51564e5655ec91111938039ed81e0d8e4c6))\n\n- **security**: Handle macOS symlinked system dirs\n ([`ba08308`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/ba08308a23d1c1491099c5d0eae548077bd88f9f))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`c492735`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/c4927358720277efa0373b339bd8e06ee06498d0))\n\n\n## v9.8.1 (2025-12-15)\n\n### Bug Fixes\n\n- **providers**: Omit store parameter for OpenRouter responses endpoint\n ([`1f8b58d`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/1f8b58d607c2809b9fa78860718a69207cb66e32))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`69a42a7`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/69a42a71d19d66f1d94d51fa27db29323e3d9a63))\n\n### Refactoring\n\n- **tests**: Address code review feedback\n ([`0c3e63c`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/0c3e63c0c7f1556f4b6686f9c6f30e4bb4a48c7c))\n\n- **tests**: Remove unused setUp method\n ([`b6a8d68`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/b6a8d682d920c2283724b588818bc1162a865d74))\n\n\n## v9.8.0 (2025-12-15)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`cb97a89`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/cb97a891dec6ab7c56b8b35c277ab3680af384d9))\n\n### Features\n\n- Add Claude Opus 4.5 model via OpenRouter\n ([`813ce5c`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/813ce5c9f7db2910eb12d8c84d3d99f464c430ed))\n\n### Testing\n\n- Add comprehensive test coverage for Opus 4.5 aliases\n ([`cf63fd2`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/cf63fd25440d599f2ec006bb8cfda5b8a6f61524))\n\n\n## v9.7.0 (2025-12-15)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`aa85644`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/aa85644c9b15893443107c3a62ec58cd7b9dc532))\n\n### Features\n\n- Re-enable web search for clink codex using correct --enable flag\n ([`e7b9f3a`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/e7b9f3a5d7e06c690c82b9fd13a93310bcf388ed))\n\n\n## v9.6.0 (2025-12-15)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`94ff26c`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/94ff26c673a64087eb29f8f54c1828f1157c594a))\n\n### Features\n\n- Support native installed Claude CLI detection\n ([`adc6231`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/adc6231b98886f0bc35cb04d04d948eba2f0f058))\n\n\n## v9.5.0 (2025-12-11)\n\n### Bug Fixes\n\n- Grok test\n ([`39c7721`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/39c77215e5d6892269e523ff25b706dd5671c042))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`5c3dd75`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/5c3dd75ca6b259f590bfd5078ea8e2f684e52de4))\n\n- Sync version to config.py [skip ci]\n ([`605633b`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/605633b2a2b044bbc5e41f2994dde27409a5b9b4))\n\n### Documentation\n\n- Cleanup\n ([`74f26e8`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/74f26e82e7a9c8a0214deef1cb18a3b2fa074050))\n\n- Cleanup\n ([`2b22174`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/2b221746fee6f7749d8aed8d07a85e428ac8e00f))\n\n- Update subheading\n ([`591287c`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/591287cb2f442a1fa34cd1139e3a0ad887388e5b))\n\n### Features\n\n- GPT-5.2 support\n ([`8b16405`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/8b16405f0609e232ff808361dc2a4d8ec258b0f3))\n\n- Grok-4.1 support https://github.com/BeehiveInnovations/pal-mcp-server/issues/339\n ([`514c9c5`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/514c9c58fcc91933348d2188ed8c82bbe98132f2))\n\n\n## v9.4.2 (2025-12-04)\n\n### Bug Fixes\n\n- Rebranding, see [docs/name-change.md](docs/name-change.md) for details\n ([`b2dc849`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/b2dc84992d70839b29b611178b3871f4922b747f))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`bcfacce`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/bcfaccecd490859fe189f45df4cf5b8e102d7874))\n\n\n## v9.4.1 (2025-11-21)\n\n### Bug Fixes\n\n- Regression https://github.com/BeehiveInnovations/pal-mcp-server/issues/338\n ([`aceddb6`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/aceddb655fc36918108b3da1f926bdd4e94875a2))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`c4461a4`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/c4461a466fab9c647b0a5035328c4d0f3e28f647))\n\n\n## v9.4.0 (2025-11-18)\n\n### Bug Fixes\n\n- Failing test for gemini 3.0 pro open router\n ([`19a2a89`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/19a2a89b12c5dec53aea21a4244aff7796a5e049))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`d3de61f`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/d3de61f8787ab60261d09f2c7f362c50d2093799))\n\n### Features\n\n- Gemini 3.0 Pro Preview for Open Router\n ([`bbfdfac`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/bbfdfac511668e8ae60f9b9b5d41eb9ab55d74cf))\n\n### Refactoring\n\n- Enable search on codex CLI\n ([`1579d9f`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/1579d9f806a653bb04c9c73ab304cdd0e78fbdfa))\n\n\n## v9.3.1 (2025-11-18)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`d256098`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/d2560983402abf084608f7750f05407a8d3e20a0))\n\n\n## v9.3.0 (2025-11-18)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`3748d47`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/3748d47faba7d871f2dd379f2c8646aa8cd3c6e9))\n\n\n## v9.2.2 (2025-11-18)\n\n### Bug Fixes\n\n- **build**: Include clink resources in package\n ([`e9ac1ce`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/e9ac1ce3354fbb124a72190702618f94266b8459))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`749bc73`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/749bc7307949fa0b0e026bfcfbd546d7619eba8b))\n\n\n## v9.2.1 (2025-11-18)\n\n### Bug Fixes\n\n- **server**: Iterate provider instances during shutdown\n ([`d40fc83`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/d40fc83d7549293372f3d20cc599a79ec355acef))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`84f6c4f`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/84f6c4fb241257b611f4b954c22a6b9340007a73))\n\n\n## v9.2.0 (2025-11-18)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`7a1de64`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/7a1de6477aae88bfe7a2f677faf0794169651354))\n\n### Documentation\n\n- Streamline advanced usage guide by reorganizing table of contents for improved navigation\n ([`698d391`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/698d391b26a0dd565eada8bfa6e67e549ce1dd20))\n\n- Update .env.example to include new GPT-5.1 model options and clarify existing model descriptions\n ([`dbbfef2`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/dbbfef292c67ed54f90f7612c9c14d4095bd6c45))\n\n- Update advanced usage and configuration to include new GPT-5.1 models and enhance tool parameters\n ([`807c9df`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/807c9df70e3b54031ec6beea10f3975455b36dfb))\n\n### Features\n\n- Add new GPT-5.1 models to configuration files and update model selection logic in OpenAI provider\n ([`8e9aa23`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/8e9aa2304d5e9ea9a9f8dc2a13a27a1ced6b1608))\n\n- Enhance model support by adding GPT-5.1 to .gitignore and updating cassette maintenance\n documentation for dual-model testing\n ([`f713d8a`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/f713d8a354a37c32a806c98994e6f949ecd64237))\n\n\n## v9.1.4 (2025-11-18)\n\n### Bug Fixes\n\n- Replaced deprecated Codex web search configuration\n ([`2ec64ba`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/2ec64ba7489acc586846b25eedf94a4f05d5bd2d))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`4d3d177`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/4d3d177d91370097ca7ac4f922fa3a8b69ce3250))\n\n\n## v9.1.3 (2025-10-22)\n\n### Bug Fixes\n\n- Reduced token usage, removed parameters from schema that CLIs never seem to use\n ([`3e27319`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/3e27319e60b0287df918856b58b2bbf042c948a8))\n\n- Telemetry option no longer available in gemini 0.11\n ([`2a8dff0`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/2a8dff0cc8a3f33111533cdb971d654637ed0578))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`9e163f9`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/9e163f9dc0654fc28961c9897b7c787a2b96e57d))\n\n- Sync version to config.py [skip ci]\n ([`557e443`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/557e443a63ffd733fb41faaa8696f6f4bb2c2fd1))\n\n### Refactoring\n\n- Improved precommit system prompt\n ([`3efff60`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/3efff6056e322ee1531d7bed5601038c129a8b29))\n\n\n## v9.1.2 (2025-10-21)\n\n### Bug Fixes\n\n- Configure codex with a longer timeout\n ([`d2773f4`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/d2773f488af28986632846652874de9ff633049c))\n\n- Handle claude's array style JSON https://github.com/BeehiveInnovations/pal-mcp-server/issues/295\n ([`d5790a9`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/d5790a9bfef719f03d17f2d719f1882e55d13b3b))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`04132f1`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/04132f1459f1e086afd8e3d456f671b63338f846))\n\n\n## v9.1.1 (2025-10-17)\n\n### Bug Fixes\n\n- Failing test\n ([`aed3e3e`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/aed3e3ee80c440ac8ab0d4abbf235b84df723d18))\n\n- Handler for parsing multiple generated code blocks\n ([`f4c20d2`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/f4c20d2a20e1c57d8b10e8f508e07e2a8d72f94a))\n\n- Improved error reporting; codex cli would at times fail to figure out how to handle plain-text /\n JSON errors\n ([`95e69a7`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/95e69a7cb234305dcd37dcdd2f22be715922e9a8))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`942757a`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/942757a360a74c021b2a1aa63e394f18f5abcecd))\n\n\n## v9.1.0 (2025-10-17)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`3ee0c8f`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/3ee0c8f555cb51b975700290919c2a8e2ada8cc4))\n\n### Features\n\n- Enhance review prompts to emphasize static analysis\n ([`36e66e2`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/36e66e2e9a44a73a466545d4d3477ecb2cb3e669))\n\n\n## v9.0.4 (2025-10-17)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`8c6f653`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/8c6f6532d843f7f1b283ce9b6472e5ba991efe16))\n\n\n## v9.0.3 (2025-10-16)\n\n### Bug Fixes\n\n- Remove duplicate -o json flag in gemini CLI config\n ([`3b2eff5`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/3b2eff58ac0e2388045a7442c63f56ce259b54ba))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`b205d71`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/b205d7159b674ce47ebc11af7255d1e3556fff93))\n\n\n## v9.0.2 (2025-10-15)\n\n### Bug Fixes\n\n- Update Claude CLI commands to new mcp syntax\n ([`a2189cb`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/a2189cb88a295ebad6268b9b08c893cd65bc1d89))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`d08cdc6`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/d08cdc6691e0f68917f2824945905b7256e0e568))\n\n\n## v9.0.1 (2025-10-14)\n\n### Bug Fixes\n\n- Add JSON output flag to gemini CLI configuration\n ([`eb3dff8`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/eb3dff845828f60ff2659586883af622b8b035eb))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`b9408aa`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/b9408aae8860d43b1da0ba67f9db98db7e4de2cf))\n\n\n## v9.0.0 (2025-10-08)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`23c9b35`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/23c9b35d5226b07b59a4c4b3d7833ba81b019ea8))\n\n### Features\n\n- Claude Code as a CLI agent now supported. Mix and match: spawn claude code from within claude\n code, or claude code from within codex.\n ([`4cfaa0b`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/4cfaa0b6060769adfbd785a072526a5368421a73))\n\n\n## v8.0.2 (2025-10-08)\n\n### Bug Fixes\n\n- Restore run-server quote trimming regex\n ([`1de4542`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/1de454224c105891137134e2a25c2ee4f00dba45))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`728fb43`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/728fb439b929c9dc37646b24537ae043208fda7d))\n\n\n## v8.0.1 (2025-10-08)\n\n### Bug Fixes\n\n- Resolve executable path for cross-platform compatibility in CLI agent\n ([`f98046c`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/f98046c2fccaa7f9a24665a0d705a98006461da5))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`52245b9`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/52245b91eaa5d720f8c3b21ead55248dd8e8bd57))\n\n### Testing\n\n- Fix clink agent tests to mock shutil.which() for executable resolution\n ([`4370be3`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/4370be33b4b69a40456527213bcd62321a925a57))\n\n\n## v8.0.0 (2025-10-07)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`4c34541`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/4c3454121c3c678cdfe8ea03fa77f4dd414df9bc))\n\n\n## v7.8.1 (2025-10-07)\n\n### Bug Fixes\n\n- Updated model description to fix test\n ([`04f7ce5`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/04f7ce5b03804564263f53a765931edba9c320cd))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`c27e81d`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/c27e81d6d2f22978816f798a161a869d1ab5f025))\n\n### Refactoring\n\n- Moved registries into a separate module and code cleanup\n ([`7c36b92`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/7c36b9255a13007a10af4fadefc21aadfce482b0))\n\n\n## v7.8.0 (2025-10-07)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`3e5fa96`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/3e5fa96c981bbd7b844a9887a518ffe266b78e9b))\n\n### Documentation\n\n- Consensus video\n ([`2352684`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/23526841922a73c68094e5205e19af04a1f6c8cc))\n\n- Formatting\n ([`7d7c74b`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/7d7c74b5a38b7d1adf132b8e28034017df7aa852))\n\n- Link to videos from main page\n ([`e8ef193`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/e8ef193daba393b55a3beaaba49721bb9182378a))\n\n- Update README.md\n ([`7b13543`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/7b13543824fc0af729daf753ecdddba9ee7d9f1e))\n\n### Features\n\n- All native providers now read from catalog files like OpenRouter / Custom configs. Allows for\n greater control over the capabilities\n ([`2a706d5`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/2a706d5720c0bf97b71c3e0fc95c15f78015bedf))\n\n- Provider cleanup\n ([`9268dda`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/9268ddad2a07306351765b47098134512739f49f))\n\n### Refactoring\n\n- New base class for model registry / loading\n ([`02d13da`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/02d13da897016d7491b4a10a1195983385d66654))\n\n\n## v7.7.0 (2025-10-07)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`70ae62a`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/70ae62a2cd663c3abcabddd1be1bc6ed9512d7df))\n\n### Documentation\n\n- Video\n ([`ed5dda7`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/ed5dda7c5a9439c2835cc69d76e6377169ad048a))\n\n### Features\n\n- More aliases\n ([`5f0aaf5`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/5f0aaf5f69c9d188d817b5ffbf6738c61da40ec7))\n\n\n## v7.6.0 (2025-10-07)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`c1c75ba`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/c1c75ba304c2840329650c46273e87eab9b05906))\n\n- Sync version to config.py [skip ci]\n ([`0fa9b66`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/0fa9b6658099c8e0d79fda0c7d2347f62d0e6137))\n\n### Documentation\n\n- Info about AI client timeouts\n ([`3ddfed5`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/3ddfed5ef09000791e1c94b041c43dc273ed53a8))\n\n### Features\n\n- Add support for openai/gpt-5-pro model\n ([`abed075`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/abed075b2eaa99e9618202f47ff921094baae952))\n\n\n## v7.5.2 (2025-10-06)\n\n### Bug Fixes\n\n- Handle 429 response https://github.com/BeehiveInnovations/pal-mcp-server/issues/273\n ([`cbe1d79`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/cbe1d7993276bd014b495cbd2d0ece1f5d7583d9))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`74fdd36`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/74fdd36de92d34681fcc5a2f772c3d05634f0a55))\n\n\n## v7.5.1 (2025-10-06)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`004e379`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/004e379cf2f1853829dccb15fa72ec18d282f1a4))\n\n\n## v7.5.0 (2025-10-06)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`71e7cd5`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/71e7cd55b1f4955a6d718fddc0de419414d133b6))\n\n### Documentation\n\n- Video\n ([`775e4d5`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/775e4d50b826858095c5f2a61a07fc01c4a00816))\n\n- Videos\n ([`bb2066c`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/bb2066c909f6581ba40fc5ddef3870954ae553ab))\n\n### Features\n\n- Support for GPT-5-Pro highest reasoning model\n https://github.com/BeehiveInnovations/pal-mcp-server/issues/275\n ([`a65485a`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/a65485a1e52fc79739000426295a27d096f4c9d8))\n\n\n## v7.4.0 (2025-10-06)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`76bf98e`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/76bf98e5cd972dabd3c79b25fcb9b9a717b23f6d))\n\n### Features\n\n- Improved prompt\n ([`b1e9963`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/b1e9963991a41dff082ec1dce5691c318f105e6d))\n\n\n## v7.3.0 (2025-10-06)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`e7920d0`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/e7920d0ed16c0e6de9d1ccaa0b58d3fb5cbd7f2f))\n\n### Documentation\n\n- Fixed typo\n ([`3ab0aa8`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/3ab0aa8314ad5992bcb00de549a0fab2e522751d))\n\n- Fixed typo\n ([`c17ce3c`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/c17ce3cf958d488b97fa7127942542ab514b58bd))\n\n- Update apilookup.md\n ([`1918679`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/19186794edac4fce5523e671310aecff4cbfdc81))\n\n- Update README.md\n ([`23c6c78`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/23c6c78bf152ede6e7b5f7b7770b12a8442845a3))\n\n### Features\n\n- Codex supports web-search natively but needs to be turned on, run-server script asks if the user\n would like this done\n ([`97ba7e4`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/97ba7e44ce7e3fd874759514ed2f0738033fc801))\n\n\n## v7.2.0 (2025-10-06)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`1854b1e`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/1854b1e26b705cda0dc3f4d733647f1454aa0352))\n\n### Documentation\n\n- Updated\n ([`bb57f71`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/bb57f719666ab6a586d835688ff8086282a5a0dc))\n\n### Features\n\n- New tool to perform apilookup (latest APIs / SDKs / language features etc)\n https://github.com/BeehiveInnovations/pal-mcp-server/issues/204\n ([`5bea595`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/5bea59540f58b3c45044828c10f131aed104dd1c))\n\n### Refactoring\n\n- De-duplicate roles to avoid explosion when more CLIs get added\n ([`c42e9e9`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/c42e9e9c34d7ae4732e2e4fbed579b681a6d170d))\n\n\n## v7.1.1 (2025-10-06)\n\n### Bug Fixes\n\n- Clink missing in toml\n ([`1ff77fa`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/1ff77faa800ad6c2dde49cad98dfa72035fe1c81))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`e02e78d`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/e02e78d903b35f4c01b8039f4157e97b38d3ec7b))\n\n### Documentation\n\n- Example for codex cli\n ([`344c42b`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/344c42bcbfb543bfd05cbc27fd5b419c76b77954))\n\n- Example for codex cli\n ([`c3044de`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/c3044de7424e638dde5c8ec49adb6c3c7c5a60b2))\n\n- Update README.md\n ([`2e719ae`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/2e719ae35e7979f7b83bd910867e79863a7f9ceb))\n\n\n## v7.1.0 (2025-10-05)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`d54bfdd`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/d54bfdd49797d076ec9cade44c56292a8089c744))\n\n### Features\n\n- Support for codex as external CLI\n ([`561e4aa`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/561e4aaaa8a89eb89c03985b9e7720cc98ef666c))\n\n\n## v7.0.2 (2025-10-05)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`f2142a2`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/f2142a22ec50abc54b464eedd6b8239d20c509be))\n\n\n## v7.0.1 (2025-10-05)\n\n### Bug Fixes\n\n- --yolo needed for running shell commands, documentation added\n ([`15ae3f2`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/15ae3f24babccf42f43be5028bf8c60c05a6beaf))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`bc4a27b`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/bc4a27b18a4a3f45afb22178e61ea0be4d6a273c))\n\n### Documentation\n\n- Updated intro\n ([`fb668c3`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/fb668c39b5f6e3dd37f7027f953f6004f258f2bf))\n\n\n## v7.0.0 (2025-10-05)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`0d46976`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/0d46976a8aa85254e4dbe06f5e71161cd3b13938))\n\n- Sync version to config.py [skip ci]\n ([`8296bf8`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/8296bf871c39597a904c70e7d98c72fcb4dc5a84))\n\n### Documentation\n\n- Instructions for OpenCode\n ([`bd66622`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/bd666227c8f7557483f7e24fb8544fc0456600dc))\n\n- Updated intro\n ([`615873c`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/615873c3db2ecf5ce6475caa3445e1da9a2517bd))\n\n### Features\n\n- Huge update - Link another CLI (such as `gemini` directly from with Claude Code / Codex).\n https://github.com/BeehiveInnovations/pal-mcp-server/issues/208\n ([`a2ccb48`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/a2ccb48e9a5080a75dbfd483b5f09fc719c887e5))\n\n### Refactoring\n\n- Fixed test\n ([`9c99b9b`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/9c99b9b35219f54db8d7be0958d4390a106631ae))\n\n- Include file modification dates too\n ([`47973e9`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/47973e945efa2cdbdb8f3404d467d7f1abc62b0a))\n\n\n## v6.1.0 (2025-10-04)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`18095d7`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/18095d7d398e4bf3d24c57a52c81ac619acb1b89))\n\n### Documentation\n\n- Updated intro\n ([`aa65394`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/aa6539472c4ddf1c3c1bac446fdee03e75e1cb50))\n\n### Features\n\n- Support for Qwen Code\n ([`fe9968b`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/fe9968b633d0312b82426e9ebddfe1d6515be3c5))\n\n\n## v6.0.0 (2025-10-04)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`ae8749a`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/ae8749ab37bdaa7e225b5219820adeb74ca9a552))\n\n### Documentation\n\n- Updated\n ([`e91ed2a`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/e91ed2a924b1702edf9e1417479ac0dee0ca1553))\n\n### Features\n\n- Azure OpenAI / Azure AI Foundry support. Models should be defined in conf/azure_models.json (or a\n custom path). See .env.example for environment variables or see readme.\n https://github.com/BeehiveInnovations/pal-mcp-server/issues/265\n ([`ff9a07a`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/ff9a07a37adf7a24aa87c63b3ba9db88bdff467b))\n\n- Breaking change - OpenRouter models are now read from conf/openrouter_models.json while Custom /\n Self-hosted models are read from conf/custom_models.json\n ([`ff9a07a`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/ff9a07a37adf7a24aa87c63b3ba9db88bdff467b))\n\n- OpenAI/compatible models (such as Azure OpenAI) can declare if they use the response API instead\n via `use_openai_responses_api`\n ([`3824d13`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/3824d131618683572e9e8fffa6b25ccfabf4cf50))\n\n- OpenRouter / Custom Models / Azure can separately also use custom config paths now (see\n .env.example )\n ([`ff9a07a`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/ff9a07a37adf7a24aa87c63b3ba9db88bdff467b))\n\n### Refactoring\n\n- Breaking change: `is_custom` property has been removed from model_capabilities.py (and thus\n custom_models.json) given each models are now read from separate configuration files\n ([`ff9a07a`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/ff9a07a37adf7a24aa87c63b3ba9db88bdff467b))\n\n- Model registry class made abstract, OpenRouter / Custom Provider / Azure OpenAI now subclass these\n ([`ff9a07a`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/ff9a07a37adf7a24aa87c63b3ba9db88bdff467b))\n\n\n## v5.22.0 (2025-10-04)\n\n### Bug Fixes\n\n- CI test\n ([`bc93b53`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/bc93b5343bbd8657b95ab47c00a2cb99a68a009f))\n\n- Listmodels to always honor restricted models\n ([`4015e91`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/4015e917ed32ae374ec6493b74993fcb34f4a971))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`054e34e`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/054e34e31ca5bee5a11c0e3e6537f58e8897c79c))\n\n- Sync version to config.py [skip ci]\n ([`c0334d7`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/c0334d77922f1b05e3fd755851da112567fb9ae6))\n\n### Features\n\n- Centralized environment handling, ensures PAL_MCP_FORCE_ENV_OVERRIDE is honored correctly\n ([`2c534ac`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/2c534ac06e4c6078b96781dfb55c5759b982afe8))\n\n### Refactoring\n\n- Don't retry on 429\n ([`d184024`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/d18402482087f52b7bd07755c9304ed00ed20592))\n\n- Improved retry logic and moved core logic to base class\n ([`f955100`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/f955100f3a82973ccd987607e1d8a1bbe07828c8))\n\n- Removed subclass override when the base class should be resolving the model name\n ([`06d7701`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/06d7701cc3ee09732ab713fa9c7c004199154483))\n\n\n## v5.21.0 (2025-10-03)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`ddb20a6`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/ddb20a6cdb8cdeee27c0aacb0b9c794283b5774c))\n\n\n## v5.20.1 (2025-10-03)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`03addcf`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/03addcfa2d3aed5086fe4c94e8b9ae56229a93ae))\n\n\n## v5.20.0 (2025-10-03)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`539bc72`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/539bc72f1ca2a2cadcccad02de1fd5fc22cd0415))\n\n\n## v5.19.0 (2025-10-03)\n\n### Bug Fixes\n\n- Add GPT-5-Codex to Responses API routing and simplify comments\n ([`82b021d`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/82b021d75acc791e68c7afb35f6492f68cf02bec))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`8e32ef3`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/8e32ef33e3ce7ab2a9d7eb5c90fe5b93b12d5c26))\n\n### Documentation\n\n- Bumped defaults\n ([`95d98a9`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/95d98a9bc0a5bafadccb9f6d1e4eda97a0dd2ce7))\n\n### Features\n\n- Add GPT-5-Codex support with Responses API integration\n ([`f265342`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/f2653427ca829368e7145325d20a98df3ee6d6b4))\n\n### Testing\n\n- Cross tool memory recall, testing continuation via cassette recording\n ([`88493bd`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/88493bd357c6a12477c3160813100dae1bc46493))\n\n\n## v5.18.3 (2025-10-03)\n\n### Bug Fixes\n\n- External model name now recorded properly in responses\n ([`d55130a`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/d55130a430401e106cd86f3e830b3d756472b7ff))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`5714e20`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/5714e2016405f7607b44d78f85081c7ccee706e5))\n\n### Documentation\n\n- Updated docs\n ([`b4e5090`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/b4e50901ba60c88137a29d00ecf99718582856d3))\n\n### Refactoring\n\n- Generic name for the CLI agent\n ([`e9b6947`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/e9b69476cd922c12931d62ccc3be9082bbbf6014))\n\n- Generic name for the CLI agent\n ([`7a6fa0e`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/7a6fa0e77a8c4a682dc11c9bbb16bdaf86d9edf4))\n\n- Generic name for the CLI agent\n ([`b692da2`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/b692da2a82facce7455b8f2ec0108e1db84c07c3))\n\n- Generic name for the CLI agent\n ([`f76ebbf`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/f76ebbf280cc78ffcfe17cb4590aeaa231db8aa1))\n\n- Generic name for the CLI agent\n ([`c05913a`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/c05913a09e53e195b9a108647c09c061ced19d17))\n\n- Generic name for the CLI agent\n ([`0dfaa63`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/0dfaa6312ed95ac3d1ae0032334ae1286871b15e))\n\n### Testing\n\n- Fixed integration tests, removed magicmock\n ([`87ccb6b`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/87ccb6b25ba32a3cb9c4cc64fc0e96294f492c04))\n\n\n## v5.18.2 (2025-10-02)\n\n### Bug Fixes\n\n- Https://github.com/BeehiveInnovations/pal-mcp-server/issues/194\n ([`8b3a286`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/8b3a2867fb83eccb3a8e8467e7e3fc5b8ebe1d0c))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`bf2196c`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/bf2196cdd58ae8d8d93597f2be69c798265d678f))\n\n\n## v5.18.1 (2025-10-02)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`e434a26`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/e434a2614af82efd15de4dd94b2c30559c91414e))\n\n\n## v5.18.0 (2025-10-02)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`e78fe35`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/e78fe35a1b64cc0ed89664440ef7c7b94495d7dc))\n\n### Features\n\n- Added `intelligence_score` to the model capabilities schema; a 1-20 number that can be specified\n to influence the sort order of models presented to the CLI in `auto selection` mode\n ([`6cab9e5`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/6cab9e56fc5373da5c11d4545bcb85371d4803a4))\n\n\n## v5.17.4 (2025-10-02)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`a6c9b92`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/a6c9b9212c77852d9e9a8780f4bc3e53b3bfed2f))\n\n\n## v5.17.3 (2025-10-02)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`722f6f8`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/722f6f86ae228206ce0094d109a3b20499d4e11a))\n\n\n## v5.17.2 (2025-10-02)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`e47a7e8`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/e47a7e89d5bfad0bb0150cb3207f1a37dc91b170))\n\n\n## v5.17.1 (2025-10-02)\n\n### Bug Fixes\n\n- Baseclass should return MODEL_CAPABILITIES\n ([`82a03ce`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/82a03ce63f28fece17bfc1d70bdb75aadec4c6bb))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`7ce66bd`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/7ce66bd9508865cef64dc30936e86e37c1a306d0))\n\n### Documentation\n\n- Document custom timeout values\n ([`218fbdf`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/218fbdf49cb90f2353f58bbaef567519dd876634))\n\n### Refactoring\n\n- Clean temperature inference\n ([`9c11ecc`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/9c11ecc4bf37562aa08dc3ecfa70f380e0ead357))\n\n- Cleanup\n ([`6ec2033`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/6ec2033f34c74ad139036de83a34cf6d374db77b))\n\n- Cleanup provider base class; cleanup shared responsibilities; cleanup public contract\n ([`693b84d`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/693b84db2b87271ac809abcf02100eee7405720b))\n\n- Cleanup token counting\n ([`7fe9fc4`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/7fe9fc49f8e3cd92be4c45a6645d5d4ab3014091))\n\n- Code cleanup\n ([`bb138e2`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/bb138e2fb552f837b0f9f466027580e1feb26f7c))\n\n- Code cleanup\n ([`182aa62`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/182aa627dfba6c578089f83444882cdd2635a7e3))\n\n- Moved image related code out of base provider into a separate utility\n ([`14a35af`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/14a35afa1d25408e62b968d9846be7bffaede327))\n\n- Moved temperature method from base provider to model capabilities\n ([`6d237d0`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/6d237d09709f757a042baf655f47eb4ddfc078ad))\n\n- Moved temperature method from base provider to model capabilities\n ([`f461cb4`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/f461cb451953f882bbde096a9ecf0584deb1dde8))\n\n- Removed hard coded checks, use model capabilities instead\n ([`250545e`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/250545e34f8d4f8026bfebb3171f3c2bc40f4692))\n\n- Removed hook from base class, turned into helper static method instead\n ([`2b10adc`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/2b10adcaf2b8741f0da5de84cc3483eae742a014))\n\n- Removed method from provider, should use model capabilities instead\n ([`a254ff2`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/a254ff2220ba00ec30f5110c69a4841419917382))\n\n- Renaming to reflect underlying type\n ([`1dc25f6`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/1dc25f6c3d4cdbf01f041cc424e3b5235c23175b))\n\n\n## v5.17.0 (2025-10-02)\n\n### Bug Fixes\n\n- Use types.HttpOptions from module imports instead of local import\n ([`956e8a6`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/956e8a6927837f5c7f031a0db1dd0b0b5483c626))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`0836213`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/0836213071d0037d8a6d2e64d34ab5df79b8e684))\n\n### Code Style\n\n- Apply Black formatting to use double quotes\n ([`33ea896`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/33ea896c511764904bf2b6b22df823928f88a148))\n\n### Features\n\n- Add custom Gemini endpoint support\n ([`462bce0`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/462bce002e2141b342260969588e69f55f8bb46a))\n\n### Refactoring\n\n- Simplify Gemini provider initialization using kwargs dict\n ([`023940b`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/023940be3e38a7eedbc8bf8404a4a5afc50f8398))\n\n\n## v5.16.0 (2025-10-01)\n\n### Bug Fixes\n\n- Resolve logging timing and import organization issues\n ([`d34c299`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/d34c299f02a233af4f17bdcc848219bf07799723))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`b6c4bca`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/b6c4bca158e4cee1ae4abd08b7e55216ebffba2d))\n\n### Code Style\n\n- Fix ruff import sorting issue\n ([`4493a69`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/4493a693332e0532d04ad3634de2a2f5b1249b64))\n\n### Features\n\n- Add configurable environment variable override system\n ([`93ce698`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/93ce6987b6e7d8678ffa5ac51f5106a7a21ce67b))\n\n\n## v5.15.0 (2025-10-01)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`b0fe956`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/b0fe956f8a50240507e0fc911f0800634c15e9f7))\n\n### Features\n\n- Depending on the number of tools in use, this change should save ~50% of overall tokens used.\n fixes https://github.com/BeehiveInnovations/pal-mcp-server/issues/255 but also refactored\n individual tools to instead encourage the agent to use the listmodels tool if needed.\n ([`d9449c7`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/d9449c7bb607caff3f0454f210ddfc36256c738a))\n\n### Performance Improvements\n\n- Tweaks to schema descriptions, aiming to reduce token usage without performance degradation\n ([`cc8a4df`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/cc8a4dfd21b6f3dae4972a833b619e53c964693b))\n\n### Refactoring\n\n- Trimmed some prompts\n ([`f69ff03`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/f69ff03c4d10e606a1dfed2a167f3ba2e2236ba8))\n\n\n## v5.14.1 (2025-10-01)\n\n### Bug Fixes\n\n- Https://github.com/BeehiveInnovations/pal-mcp-server/issues/258\n ([`696b45f`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/696b45f25e80faccb67034254cf9a8fc4c643dbd))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`692016c`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/692016c6205ed0a0c3d9e830482d88231aca2e31))\n\n\n## v5.14.0 (2025-10-01)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`c0f822f`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/c0f822ffa23292d668f7b5dd3cb62e3f23fb29af))\n\n### Features\n\n- Add Claude Sonnet 4.5 and update alias configuration\n ([`95c4822`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/95c4822af2dc55f59c0e4ed9454673d6ca964731))\n\n### Testing\n\n- Update tests to match new Claude Sonnet 4.5 alias configuration\n ([`7efb409`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/7efb4094d4eb7db006340d3d9240b9113ac25cd3))\n\n\n## v5.13.0 (2025-10-01)\n\n### Bug Fixes\n\n- Add sonnet alias for Claude Sonnet 4.1 to match opus/haiku pattern\n ([`dc96344`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/dc96344db043e087ee4f8bf264a79c51dc2e0b7a))\n\n- Missing \"optenai/\" in name\n ([`7371ed6`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/7371ed6487b7d90a1b225a67dca2a38c1a52f2ad))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`b8479fc`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/b8479fc638083d6caa4bad6205e3d3fcab830aca))\n\n### Features\n\n- Add comprehensive GPT-5 series model support\n ([`4930824`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/493082405237e66a2f033481a5f8bf8293b0d553))\n\n\n## v5.12.1 (2025-10-01)\n\n### Bug Fixes\n\n- Resolve consensus tool model_context parameter missing issue\n ([`9044b63`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/9044b63809113047fe678d659e4fcd175f58e87a))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`e3ebf4e`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/e3ebf4e94eba63acdc4df5a0b0493e44e3343dd1))\n\n### Code Style\n\n- Fix trailing whitespace in consensus.py\n ([`0760b31`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/0760b31f8a6d03c4bea3fd2a94dfbbfab0ad5079))\n\n### Refactoring\n\n- Optimize ModelContext creation in consensus tool\n ([`30a8952`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/30a8952fbccd22bebebd14eb2c8005404b79bcd6))\n\n\n## v5.12.0 (2025-10-01)\n\n### Bug Fixes\n\n- Removed use_websearch; this parameter was confusing Codex. It started using this to prompt the\n external model to perform searches! web-search is enabled by Claude / Codex etc by default and the\n external agent can ask claude to search on its behalf.\n ([`cff6d89`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/cff6d8998f64b73265c4e31b2352462d6afe377f))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`28cabe0`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/28cabe0833661b0bab56d4227781ee2da332b00c))\n\n### Features\n\n- Implement semantic cassette matching for o3 models\n ([`70fa088`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/70fa088c32ac4e6153d5e7b30a3e32022be2f908))\n\n\n## v5.11.2 (2025-10-01)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`4d6f1b4`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/4d6f1b41005dee428c955e33f04f8f9f6259e662))\n\n\n## v5.11.1 (2025-10-01)\n\n### Bug Fixes\n\n- Remove duplicate OpenAI models from listmodels output\n ([`c29e762`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/c29e7623ace257eb45396cdf8c19e1659e29edb9))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`1209064`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/12090646ee83f2368311d595d87ae947e46ddacd))\n\n### Testing\n\n- Update OpenAI provider alias tests to match new format\n ([`d13700c`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/d13700c14c7ee3d092302837cb1726d17bab1ab8))\n\n\n## v5.11.0 (2025-08-26)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`9735469`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/973546990f2c45afa93f1aa6de33ff461ecf1a83))\n\n### Features\n\n- Codex CLI support\n ([`ce56d16`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/ce56d16240ddcc476145a512561efe5c66438f0d))\n\n\n## v5.10.3 (2025-08-24)\n\n### Bug Fixes\n\n- Address test failures and PR feedback\n ([`6bd9d67`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/6bd9d6709acfb584ab30a0a4d6891cabdb6d3ccf))\n\n- Resolve temperature handling issues for O3/custom models\n ([#245](https://github.com/BeehiveInnovations/pal-mcp-server/pull/245),\n [`3b4fd88`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/3b4fd88d7e9a3f09fea616a10cb3e9d6c1a0d63b))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`d6e6808`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/d6e6808be525192ab8388c0f01bc1bbd016fc23a))\n\n\n## v5.10.2 (2025-08-24)\n\n### Bug Fixes\n\n- Another fix for https://github.com/BeehiveInnovations/pal-mcp-server/issues/251\n ([`a07036e`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/a07036e6805042895109c00f921c58a09caaa319))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`9da5c37`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/9da5c37809cbde19d0c7ffed273ae93ca883a016))\n\n\n## v5.10.0 (2025-08-22)\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`1254205`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/12542054a214022d3f515e53367f5bf3a77fb289))\n\n### Features\n\n- Refactored and tweaked model descriptions / schema to use fewer tokens at launch (average\n reduction per field description: 60-80%) without sacrificing tool effectiveness\n ([`4b202f5`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/4b202f5d1d24cea1394adab26a976188f847bd09))\n\n\n## v5.9.0 (2025-08-21)\n\n### Documentation\n\n- Update instructions for precommit\n ([`90821b5`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/90821b51ff653475d9fb1bc70b57951d963e8841))\n\n### Features\n\n- Refactored and improved codereview in line with precommit. Reviews are now either external\n (default) or internal. Takes away anxiety and loss of tokens when Claude incorrectly decides to be\n 'confident' about its own changes and bungle things up.\n ([`80d21e5`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/80d21e57c0246762c0a306ede5b93d6aeb2315d8))\n\n### Refactoring\n\n- Minor prompt tweaks\n ([`d30c212`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/d30c212029c05b767d99b5391c1dd4cee78ef336))\n\n\n## v5.8.6 (2025-08-20)\n\n### Bug Fixes\n\n- Escape backslashes in TOML regex pattern\n ([`1c973af`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/1c973afb002650b9bbee8a831b756bef848915a1))\n\n- Establish version 5.8.6 and add version sync automation\n ([`90a4195`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/90a419538128b54fbd30da4b8a8088ac59f8c691))\n\n- Restore proper version 5.8.6\n ([`340b58f`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/340b58f2e790b84c3736aa96df7f6f5f2d6a13c9))\n\n### Chores\n\n- Sync version to config.py [skip ci]\n ([`4f82f65`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/4f82f6500502b7b6ba41875a560c41f6a63b683b))\n\n\n## v1.1.0 (2025-08-20)\n\n### Features\n\n- Improvements to precommit\n ([`2966dcf`](https://github.com/BeehiveInnovations/pal-mcp-server/commit/2966dcf2682feb7eef4073738d0c225a44ce0533))\n\n\n## v1.0.0 (2025-08-20)\n\n- Initial Release\n" }, { "path": "CLAUDE.md", "content": "# Claude Development Guide for PAL MCP Server\n\nThis file contains essential commands and workflows for developing and maintaining the PAL MCP Server when working with Claude. Use these instructions to efficiently run quality checks, manage the server, check logs, and run tests.\n\n## Quick Reference Commands\n\n### Code Quality Checks\n\nBefore making any changes or submitting PRs, always run the comprehensive quality checks:\n\n```bash\n# Activate virtual environment first\nsource venv/bin/activate\n\n# Run all quality checks (linting, formatting, tests)\n./code_quality_checks.sh\n```\n\nThis script automatically runs:\n- Ruff linting with auto-fix\n- Black code formatting \n- Import sorting with isort\n- Complete unit test suite (excluding integration tests)\n- Verification that all checks pass 100%\n\n**Run Integration Tests (requires API keys):**\n```bash\n# Run integration tests that make real API calls\n./run_integration_tests.sh\n\n# Run integration tests + simulator tests\n./run_integration_tests.sh --with-simulator\n```\n\n### Server Management\n\n#### Setup/Update the Server\n```bash\n# Run setup script (handles everything)\n./run-server.sh\n```\n\nThis script will:\n- Set up Python virtual environment\n- Install all dependencies\n- Create/update .env file\n- Configure MCP with Claude\n- Verify API keys\n\n#### View Logs\n```bash\n# Follow logs in real-time\n./run-server.sh -f\n\n# Or manually view logs\ntail -f logs/mcp_server.log\n```\n\n### Log Management\n\n#### View Server Logs\n```bash\n# View last 500 lines of server logs\ntail -n 500 logs/mcp_server.log\n\n# Follow logs in real-time\ntail -f logs/mcp_server.log\n\n# View specific number of lines\ntail -n 100 logs/mcp_server.log\n\n# Search logs for specific patterns\ngrep \"ERROR\" logs/mcp_server.log\ngrep \"tool_name\" logs/mcp_activity.log\n```\n\n#### Monitor Tool Executions Only\n```bash\n# View tool activity log (focused on tool calls and completions)\ntail -n 100 logs/mcp_activity.log\n\n# Follow tool activity in real-time\ntail -f logs/mcp_activity.log\n\n# Use simple tail commands to monitor logs\ntail -f logs/mcp_activity.log | grep -E \"(TOOL_CALL|TOOL_COMPLETED|ERROR|WARNING)\"\n```\n\n#### Available Log Files\n\n**Current log files (with proper rotation):**\n```bash\n# Main server log (all activity including debug info) - 20MB max, 10 backups\ntail -f logs/mcp_server.log\n\n# Tool activity only (TOOL_CALL, TOOL_COMPLETED, etc.) - 20MB max, 5 backups \ntail -f logs/mcp_activity.log\n```\n\n**For programmatic log analysis (used by tests):**\n```python\n# Import the LogUtils class from simulator tests\nfrom simulator_tests.log_utils import LogUtils\n\n# Get recent logs\nrecent_logs = LogUtils.get_recent_server_logs(lines=500)\n\n# Check for errors\nerrors = LogUtils.check_server_logs_for_errors()\n\n# Search for specific patterns\nmatches = LogUtils.search_logs_for_pattern(\"TOOL_CALL.*debug\")\n```\n\n### Testing\n\nSimulation tests are available to test the MCP server in a 'live' scenario, using your configured\nAPI keys to ensure the models are working and the server is able to communicate back and forth. \n\n**IMPORTANT**: After any code changes, restart your Claude session for the changes to take effect.\n\n#### Run All Simulator Tests\n```bash\n# Run the complete test suite\npython communication_simulator_test.py\n\n# Run tests with verbose output\npython communication_simulator_test.py --verbose\n```\n\n#### Quick Test Mode (Recommended for Time-Limited Testing)\n```bash\n# Run quick test mode - 6 essential tests that provide maximum functionality coverage\npython communication_simulator_test.py --quick\n\n# Run quick test mode with verbose output\npython communication_simulator_test.py --quick --verbose\n```\n\n**Quick mode runs these 6 essential tests:**\n- `cross_tool_continuation` - Cross-tool conversation memory testing (chat, thinkdeep, codereview, analyze, debug)\n- `conversation_chain_validation` - Core conversation threading and memory validation\n- `consensus_workflow_accurate` - Consensus tool with flash model and stance testing\n- `codereview_validation` - CodeReview tool with flash model and multi-step workflows\n- `planner_validation` - Planner tool with flash model and complex planning workflows\n- `token_allocation_validation` - Token allocation and conversation history buildup testing\n\n**Why these 6 tests:** They cover the core functionality including conversation memory (`utils/conversation_memory.py`), chat tool functionality, file processing and deduplication, model selection (flash/flashlite/o3), and cross-tool conversation workflows. These tests validate the most critical parts of the system in minimal time.\n\n**Note:** Some workflow tools (analyze, codereview, planner, consensus, etc.) require specific workflow parameters and may need individual testing rather than quick mode testing.\n\n#### Run Individual Simulator Tests (For Detailed Testing)\n```bash\n# List all available tests\npython communication_simulator_test.py --list-tests\n\n# RECOMMENDED: Run tests individually for better isolation and debugging\npython communication_simulator_test.py --individual basic_conversation\npython communication_simulator_test.py --individual content_validation\npython communication_simulator_test.py --individual cross_tool_continuation\npython communication_simulator_test.py --individual memory_validation\n\n# Run multiple specific tests\npython communication_simulator_test.py --tests basic_conversation content_validation\n\n# Run individual test with verbose output for debugging\npython communication_simulator_test.py --individual memory_validation --verbose\n```\n\nAvailable simulator tests include:\n- `basic_conversation` - Basic conversation flow with chat tool\n- `content_validation` - Content validation and duplicate detection\n- `per_tool_deduplication` - File deduplication for individual tools\n- `cross_tool_continuation` - Cross-tool conversation continuation scenarios\n- `cross_tool_comprehensive` - Comprehensive cross-tool file deduplication and continuation\n- `line_number_validation` - Line number handling validation across tools\n- `memory_validation` - Conversation memory validation\n- `model_thinking_config` - Model-specific thinking configuration behavior\n- `o3_model_selection` - O3 model selection and usage validation\n- `ollama_custom_url` - Ollama custom URL endpoint functionality\n- `openrouter_fallback` - OpenRouter fallback behavior when only provider\n- `openrouter_models` - OpenRouter model functionality and alias mapping\n- `token_allocation_validation` - Token allocation and conversation history validation\n- `testgen_validation` - TestGen tool validation with specific test function\n- `refactor_validation` - Refactor tool validation with codesmells\n- `conversation_chain_validation` - Conversation chain and threading validation\n- `consensus_stance` - Consensus tool validation with stance steering (for/against/neutral)\n\n**Note**: All simulator tests should be run individually for optimal testing and better error isolation.\n\n#### Run Unit Tests Only\n```bash\n# Run all unit tests (excluding integration tests that require API keys)\npython -m pytest tests/ -v -m \"not integration\"\n\n# Run specific test file\npython -m pytest tests/test_refactor.py -v\n\n# Run specific test function\npython -m pytest tests/test_refactor.py::TestRefactorTool::test_format_response -v\n\n# Run tests with coverage\npython -m pytest tests/ --cov=. --cov-report=html -m \"not integration\"\n```\n\n#### Run Integration Tests (Uses Free Local Models)\n\n**Setup Requirements:**\n```bash\n# 1. Install Ollama (if not already installed)\n# Visit https://ollama.ai or use brew install ollama\n\n# 2. Start Ollama service\nollama serve\n\n# 3. Pull a model (e.g., llama3.2)\nollama pull llama3.2\n\n# 4. Set environment variable for custom provider\nexport CUSTOM_API_URL=\"http://localhost:11434\"\n```\n\n**Run Integration Tests:**\n```bash\n# Run integration tests that make real API calls to local models\npython -m pytest tests/ -v -m \"integration\"\n\n# Run specific integration test\npython -m pytest tests/test_prompt_regression.py::TestPromptIntegration::test_chat_normal_prompt -v\n\n# Run all tests (unit + integration)\npython -m pytest tests/ -v\n```\n\n**Note**: Integration tests use the local-llama model via Ollama, which is completely FREE to run unlimited times. Requires `CUSTOM_API_URL` environment variable set to your local Ollama endpoint. They can be run safely in CI/CD but are excluded from code quality checks to keep them fast.\n\n### Development Workflow\n\n#### Before Making Changes\n1. Ensure virtual environment is activated: `source .pal_venv/bin/activate`\n2. Run quality checks: `./code_quality_checks.sh`\n3. Check logs to ensure server is healthy: `tail -n 50 logs/mcp_server.log`\n\n#### After Making Changes\n1. Run quality checks again: `./code_quality_checks.sh`\n2. Run integration tests locally: `./run_integration_tests.sh`\n3. Run quick test mode for fast validation: `python communication_simulator_test.py --quick`\n4. Run relevant specific simulator tests if needed: `python communication_simulator_test.py --individual `\n5. Check logs for any issues: `tail -n 100 logs/mcp_server.log`\n6. Restart Claude session to use updated code\n\n#### Before Committing/PR\n1. Final quality check: `./code_quality_checks.sh`\n2. Run integration tests: `./run_integration_tests.sh`\n3. Run quick test mode: `python communication_simulator_test.py --quick`\n4. Run full simulator test suite (optional): `./run_integration_tests.sh --with-simulator`\n5. Verify all tests pass 100%\n\n### Common Troubleshooting\n\n#### Server Issues\n```bash\n# Check if Python environment is set up correctly\n./run-server.sh\n\n# View recent errors\ngrep \"ERROR\" logs/mcp_server.log | tail -20\n\n# Check virtual environment\nwhich python\n# Should show: .../pal-mcp-server/.pal_venv/bin/python\n```\n\n#### Test Failures\n```bash\n# First try quick test mode to see if it's a general issue\npython communication_simulator_test.py --quick --verbose\n\n# Run individual failing test with verbose output\npython communication_simulator_test.py --individual --verbose\n\n# Check server logs during test execution\ntail -f logs/mcp_server.log\n\n# Run tests with debug output\nLOG_LEVEL=DEBUG python communication_simulator_test.py --individual \n```\n\n#### Linting Issues\n```bash\n# Auto-fix most linting issues\nruff check . --fix\nblack .\nisort .\n\n# Check what would be changed without applying\nruff check .\nblack --check .\nisort --check-only .\n```\n\n### File Structure Context\n\n- `./code_quality_checks.sh` - Comprehensive quality check script\n- `./run-server.sh` - Server setup and management\n- `communication_simulator_test.py` - End-to-end testing framework\n- `simulator_tests/` - Individual test modules\n- `tests/` - Unit test suite\n- `tools/` - MCP tool implementations\n- `providers/` - AI provider implementations\n- `systemprompts/` - System prompt definitions\n- `logs/` - Server log files\n\n### Environment Requirements\n\n- Python 3.9+ with virtual environment\n- All dependencies from `requirements.txt` installed\n- Proper API keys configured in `.env` file\n\nThis guide provides everything needed to efficiently work with the PAL MCP Server codebase using Claude. Always run quality checks before and after making changes to ensure code integrity." }, { "path": "Dockerfile", "content": "# ===========================================\n# STAGE 1: Build dependencies\n# ===========================================\nFROM python:3.11-slim AS builder\n\n# Install system dependencies for building\nRUN apt-get update && apt-get install -y \\\n build-essential \\\n curl \\\n && rm -rf /var/lib/apt/lists/*\n\n# Set working directory\nWORKDIR /app\n\n# Copy requirements files\nCOPY requirements.txt ./\n\n# Create virtual environment and install dependencies\nRUN python -m venv /opt/venv\nENV PATH=\"/opt/venv/bin:$PATH\"\n\n# Install Python dependencies\nRUN pip install --no-cache-dir --upgrade pip setuptools wheel && \\\n pip install --no-cache-dir -r requirements.txt\n\n# ===========================================\n# STAGE 2: Runtime image\n# ===========================================\nFROM python:3.11-slim AS runtime\n\n# Add metadata labels for traceability\nLABEL maintainer=\"PAL MCP Server Team\"\nLABEL version=\"1.0.0\"\nLABEL description=\"PAL MCP Server - AI-powered Model Context Protocol server\"\nLABEL org.opencontainers.image.title=\"pal-mcp-server\"\nLABEL org.opencontainers.image.description=\"AI-powered Model Context Protocol server with multi-provider support\"\nLABEL org.opencontainers.image.version=\"1.0.0\"\nLABEL org.opencontainers.image.source=\"https://github.com/BeehiveInnovations/pal-mcp-server\"\nLABEL org.opencontainers.image.documentation=\"https://github.com/BeehiveInnovations/pal-mcp-server/blob/main/README.md\"\nLABEL org.opencontainers.image.licenses=\"Apache 2.0 License\"\n\n# Create non-root user for security\nRUN groupadd -r paluser && useradd -r -g paluser paluser\n\n# Install minimal runtime dependencies\nRUN apt-get update && apt-get install -y \\\n ca-certificates \\\n procps \\\n && rm -rf /var/lib/apt/lists/* \\\n && apt-get clean\n\n# Copy virtual environment from builder\nCOPY --from=builder /opt/venv /opt/venv\nENV PATH=\"/opt/venv/bin:$PATH\"\n\n# Set working directory\nWORKDIR /app\n\n# Copy application code\nCOPY --chown=paluser:paluser . .\n\n# Create logs directory with proper permissions\nRUN mkdir -p logs && chown -R paluser:paluser logs\n\n# Create tmp directory for container operations\nRUN mkdir -p tmp && chown -R paluser:paluser tmp\n\n# Copy health check script\nCOPY --chown=paluser:paluser docker/scripts/healthcheck.py /usr/local/bin/healthcheck.py\nRUN chmod +x /usr/local/bin/healthcheck.py\n\n# Switch to non-root user\nUSER paluser\n\n# Health check configuration\nHEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \\\n CMD python /usr/local/bin/healthcheck.py\n\n# Set environment variables\nENV PYTHONUNBUFFERED=1\nENV PYTHONPATH=/app\n\n# Default command\nCMD [\"python\", \"server.py\"]\n" }, { "path": "LICENSE", "content": "Apache License\n Version 2.0, January 2004\n http://www.apache.org/licenses/\n\n TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION\n\n 1. Definitions.\n\n \"License\" shall mean the terms and conditions for use, reproduction,\n and distribution as defined by Sections 1 through 9 of this document.\n\n \"Licensor\" shall mean the copyright owner or entity granting the License.\n\n \"Legal Entity\" shall mean the union of the acting entity and all\n other entities that control, are controlled by, or are under common\n control with that entity. For the purposes of this definition,\n \"control\" means (i) the power, direct or indirect, to cause the\n direction or management of such entity, whether by contract or\n otherwise, or (ii) ownership of fifty percent (50%) or more of the\n outstanding shares, or (iii) beneficial ownership of such entity.\n\n \"You\" (or \"Your\") shall mean an individual or Legal Entity\n exercising permissions granted by this License.\n\n \"Source\" shall mean the preferred form for making modifications,\n including but not limited to software source code, documentation\n source, and configuration files.\n\n \"Object\" shall mean any form resulting from mechanical\n transformation or translation of a Source form, including but\n not limited to compiled object code, generated documentation,\n and conversions to other media types.\n\n \"Work\" shall mean the work of authorship covered by this License,\n whether in source or binary form, which is made available under the\n License, as indicated by a copyright notice that is included in or\n attached to the work. (The copyright notice requirement does not\n apply to derivative works of the License holder.)\n\n \"Derivative Works\" shall mean any work, whether in Source or Object\n form, that is based upon (or derived from) the Work and for which the\n editorial revisions, annotations, elaborations, or other modifications\n represent, as a whole, an original work of authorship. For the purposes\n of this License, Derivative Works shall not include works that remain\n separable from, or merely link (or bind by name) to the interfaces of,\n the Work and derivative works thereof.\n\n \"Contribution\" shall mean any work of authorship, including\n the original version of the Work and any modifications or additions\n to that Work or Derivative Works thereof, that is intentionally\n submitted to Licensor for inclusion in the Work by the copyright owner\n or by an individual or Legal Entity authorized to submit on behalf of\n the copyright owner. For the purposes of this definition, \"submitted\"\n means any form of electronic, verbal, or written communication sent\n to the Licensor or its representatives, including but not limited to\n communication on electronic mailing lists, source code control\n systems, and issue tracking systems that are managed by, or on behalf\n of, the Licensor for the purpose of discussing and improving the Work,\n but excluding communication that is conspicuously marked or otherwise\n designated in writing by the copyright owner as \"Not a Contribution.\"\n\n \"Contributor\" shall mean Licensor and any individual or Legal Entity\n on behalf of whom a Contribution has been received by Licensor and\n subsequently incorporated within the Work.\n\n 2. Grant of Copyright License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n copyright license to use, reproduce, modify, distribute, and otherwise\n transfer the Work as part of a Derivative Work.\n\n 3. Grant of Patent License. Subject to the terms and conditions of\n this License, each Contributor hereby grants to You a perpetual,\n worldwide, non-exclusive, no-charge, royalty-free, irrevocable\n (except as stated in this section) patent license to make, have made,\n use, offer to sell, sell, import, and otherwise transfer the Work,\n where such license applies only to those patent claims licensable\n by such Contributor that are necessarily infringed by their\n Contribution(s) alone or by combination of their Contribution(s)\n with the Work to which such Contribution(s) was submitted. If You\n institute patent litigation against any entity (including a\n cross-claim or counterclaim in a lawsuit) alleging that the Work\n or a Contribution incorporated within the Work constitutes direct\n or contributory patent infringement, then any patent licenses\n granted to You under this License for that Work shall terminate\n as of the date such litigation is filed.\n\n 4. Redistribution. You may reproduce and distribute copies of the\n Work or Derivative Works thereof in any medium, with or without\n modifications, and in Source or Object form, provided that You\n meet the following conditions:\n\n (a) You must give any other recipients of the Work or\n Derivative Works a copy of this License; and\n\n (b) You must cause any modified files to carry prominent notices\n stating that You changed the files; and\n\n (c) You must retain, in the Source form of any Derivative Works\n that You distribute, all copyright, patent, trademark, and\n attribution notices from the Source form of the Work,\n excluding those notices that do not pertain to any part of\n the Derivative Works; and\n\n (d) If the Work includes a \"NOTICE\" file as part of its\n distribution, then any Derivative Works that You distribute must\n include a readable copy of the attribution notices contained\n within such NOTICE file, excluding those notices that do not\n pertain to any part of the Derivative Works, in at least one\n of the following places: within a NOTICE file distributed\n as part of the Derivative Works; within the Source form or\n documentation, if provided along with the Derivative Works; or,\n within a display generated by the Derivative Works, if and\n wherever such third-party notices normally appear. The contents\n of the NOTICE file are for informational purposes only and\n do not modify the License. You may add Your own attribution\n notices within Derivative Works that You distribute, alongside\n or as an addendum to the NOTICE text from the Work, provided\n that such additional attribution notices cannot be construed\n as modifying the License.\n\n You may add Your own copyright notice to Your modifications and\n may provide additional or different license terms and conditions\n for use, reproduction, or distribution of Your modifications, or\n for any such Derivative Works as a whole, provided Your use,\n reproduction, and distribution of the Work otherwise complies with\n the conditions stated in this License.\n\n 5. Submission of Contributions. Unless You explicitly state otherwise,\n any Contribution intentionally submitted for inclusion in the Work\n by You to the Licensor shall be under the terms and conditions of\n this License, without any additional terms or conditions.\n Notwithstanding the above, nothing herein shall supersede or modify\n the terms of any separate license agreement you may have executed\n with Licensor regarding such Contributions.\n\n 6. Trademarks. This License does not grant permission to use the trade\n names, trademarks, service marks, or product names of the Licensor,\n except as required for reasonable and customary use in describing the\n origin of the Work and reproducing the content of the NOTICE file.\n\n 7. Disclaimer of Warranty. Unless required by applicable law or\n agreed to in writing, Licensor provides the Work (and each\n Contributor provides its Contributions) on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or\n implied, including, without limitation, any warranties or conditions\n of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A\n PARTICULAR PURPOSE. You are solely responsible for determining the\n appropriateness of using or redistributing the Work and assume any\n risks associated with Your exercise of permissions under this License.\n\n 8. Limitation of Liability. In no event and under no legal theory,\n whether in tort (including negligence), contract, or otherwise,\n unless required by applicable law (such as deliberate and grossly\n negligent acts) or agreed to in writing, shall any Contributor be\n liable to You for damages, including any direct, indirect, special,\n incidental, or consequential damages of any character arising as a\n result of this License or out of the use or inability to use the\n Work (including but not limited to damages for loss of goodwill,\n work stoppage, computer failure or malfunction, or any and all\n other commercial damages or losses), even if such Contributor\n has been advised of the possibility of such damages.\n\n 9. Accepting Warranty or Support. You may choose to offer, and to\n charge a fee for, warranty, support, indemnity or other liability\n obligations and/or rights consistent with this License. However,\n in accepting such obligations, You may act only on Your own behalf\n and on Your sole responsibility, not on behalf of any other\n Contributor, and only if You agree to indemnify, defend, and hold\n each Contributor harmless for any liability incurred by, or claims\n asserted against, such Contributor by reason of your accepting any\n such warranty or support.\n\n END OF TERMS AND CONDITIONS\n\n APPENDIX: How to apply the Apache License to your work.\n\n To apply the Apache License to your work, attach the following\n boilerplate notice, with the fields enclosed by brackets \"[]\"\n replaced with your own identifying information. (Don't include\n the brackets!) The text should be enclosed in comments for the\n particular file format. An identification line is also useful.\n\n Copyright 2025 Beehive Innovations\n https://github.com/BeehiveInnovations\n\n Licensed under the Apache License, Version 2.0 (the \"License\");\n you may not use this file except in compliance with the License.\n You may obtain a copy of the License at\n\n http://www.apache.org/licenses/LICENSE-2.0\n\n Unless required by applicable law or agreed to in writing, software\n distributed under the License is distributed on an \"AS IS\" BASIS,\n WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n See the License for the specific language governing permissions and\n limitations under the License." }, { "path": "README.md", "content": "# PAL MCP: Many Workflows. One Context.\n\n
\n\n Your AI's PAL – a Provider Abstraction Layer
\n Formerly known as Zen MCP\n\n [PAL in action](https://github.com/user-attachments/assets/0d26061e-5f21-4ab1-b7d0-f883ddc2c3da)\n\nπŸ‘‰ **[Watch more examples](#-watch-tools-in-action)**\n\n### Your CLI + Multiple Models = Your AI Dev Team\n\n**Use the πŸ€– CLI you love:** \n[Claude Code](https://www.anthropic.com/claude-code) Β· [Gemini CLI](https://github.com/google-gemini/gemini-cli) Β· [Codex CLI](https://github.com/openai/codex) Β· [Qwen Code CLI](https://qwenlm.github.io/qwen-code-docs/) Β· [Cursor](https://cursor.com) Β· _and more_\n\n**With multiple models within a single prompt:** \nGemini Β· OpenAI Β· Anthropic Β· Grok Β· Azure Β· Ollama Β· OpenRouter Β· DIAL Β· On-Device Model\n\n
\n\n---\n\n## πŸ†• Now with CLI-to-CLI Bridge\n\nThe new **[`clink`](docs/tools/clink.md)** (CLI + Link) tool connects external AI CLIs directly into your workflow:\n\n- **Connect external CLIs** like [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Codex CLI](https://github.com/openai/codex), and [Claude Code](https://www.anthropic.com/claude-code) directly into your workflow\n- **CLI Subagents** - Launch isolated CLI instances from _within_ your current CLI! Claude Code can spawn Codex subagents, Codex can spawn Gemini CLI subagents, etc. Offload heavy tasks (code reviews, bug hunting) to fresh contexts while your main session's context window remains unpolluted. Each subagent returns only final results.\n- **Context Isolation** - Run separate investigations without polluting your primary workspace\n- **Role Specialization** - Spawn `planner`, `codereviewer`, or custom role agents with specialized system prompts\n- **Full CLI Capabilities** - Web search, file inspection, MCP tool access, latest documentation lookups\n- **Seamless Continuity** - Sub-CLIs participate as first-class members with full conversation context between tools\n\n```bash\n# Codex spawns Codex subagent for isolated code review in fresh context\nclink with codex codereviewer to audit auth module for security issues\n# Subagent reviews in isolation, returns final report without cluttering your context as codex reads each file and walks the directory structure\n\n# Consensus from different AI models β†’ Implementation handoff with full context preservation between tools\nUse consensus with gpt-5 and gemini-pro to decide: dark mode or offline support next\nContinue with clink gemini - implement the recommended feature\n# Gemini receives full debate context and starts coding immediately\n```\n\nπŸ‘‰ **[Learn more about clink](docs/tools/clink.md)**\n\n---\n\n## Why PAL MCP?\n\n**Why rely on one AI model when you can orchestrate them all?**\n\nA Model Context Protocol server that supercharges tools like [Claude Code](https://www.anthropic.com/claude-code), [Codex CLI](https://developers.openai.com/codex/cli), and IDE clients such\nas [Cursor](https://cursor.com) or the [Claude Dev VS Code extension](https://marketplace.visualstudio.com/items?itemName=Anthropic.claude-vscode). **PAL MCP connects your favorite AI tool\nto multiple AI models** for enhanced code analysis, problem-solving, and collaborative development.\n\n### True AI Collaboration with Conversation Continuity\n\nPAL supports **conversation threading** so your CLI can **discuss ideas with multiple AI models, exchange reasoning, get second opinions, and even run collaborative debates between models** to help you reach deeper insights and better solutions.\n\nYour CLI always stays in control but gets perspectives from the best AI for each subtask. Context carries forward seamlessly across tools and models, enabling complex workflows like: code reviews with multiple models β†’ automated planning β†’ implementation β†’ pre-commit validation.\n\n> **You're in control.** Your CLI of choice orchestrates the AI team, but you decide the workflow. Craft powerful prompts that bring in Gemini Pro, GPT 5, Flash, or local offline models exactly when needed.\n\n
\nReasons to Use PAL MCP\n\nA typical workflow with Claude Code as an example:\n\n1. **Multi-Model Orchestration** - Claude coordinates with Gemini Pro, O3, GPT-5, and 50+ other models to get the best analysis for each task\n\n2. **Context Revival Magic** - Even after Claude's context resets, continue conversations seamlessly by having other models \"remind\" Claude of the discussion\n\n3. **Guided Workflows** - Enforces systematic investigation phases that prevent rushed analysis and ensure thorough code examination\n\n4. **Extended Context Windows** - Break Claude's limits by delegating to Gemini (1M tokens) or O3 (200K tokens) for massive codebases\n\n5. **True Conversation Continuity** - Full context flows across tools and models - Gemini remembers what O3 said 10 steps ago\n\n6. **Model-Specific Strengths** - Extended thinking with Gemini Pro, blazing speed with Flash, strong reasoning with O3, privacy with local Ollama\n\n7. **Professional Code Reviews** - Multi-pass analysis with severity levels, actionable feedback, and consensus from multiple AI experts\n\n8. **Smart Debugging Assistant** - Systematic root cause analysis with hypothesis tracking and confidence levels\n\n9. **Automatic Model Selection** - Claude intelligently picks the right model for each subtask (or you can specify)\n\n10. **Vision Capabilities** - Analyze screenshots, diagrams, and visual content with vision-enabled models\n\n11. **Local Model Support** - Run Llama, Mistral, or other models locally for complete privacy and zero API costs\n\n12. **Bypass MCP Token Limits** - Automatically works around MCP's 25K limit for large prompts and responses\n\n**The Killer Feature:** When Claude's context resets, just ask to \"continue with O3\" - the other model's response magically revives Claude's understanding without re-ingesting documents!\n\n#### Example: Multi-Model Code Review Workflow\n\n1. `Perform a codereview using gemini pro and o3 and use planner to generate a detailed plan, implement the fixes and do a final precommit check by continuing from the previous codereview`\n2. This triggers a [`codereview`](docs/tools/codereview.md) workflow where Claude walks the code, looking for all kinds of issues\n3. After multiple passes, collects relevant code and makes note of issues along the way\n4. Maintains a `confidence` level between `exploring`, `low`, `medium`, `high` and `certain` to track how confidently it's been able to find and identify issues\n5. Generates a detailed list of critical -> low issues\n6. Shares the relevant files, findings, etc with **Gemini Pro** to perform a deep dive for a second [`codereview`](docs/tools/codereview.md)\n7. Comes back with a response and next does the same with o3, adding to the prompt if a new discovery comes to light\n8. When done, Claude takes in all the feedback and combines a single list of all critical -> low issues, including good patterns in your code. The final list includes new findings or revisions in case Claude misunderstood or missed something crucial and one of the other models pointed this out\n9. It then uses the [`planner`](docs/tools/planner.md) workflow to break the work down into simpler steps if a major refactor is required\n10. Claude then performs the actual work of fixing highlighted issues\n11. When done, Claude returns to Gemini Pro for a [`precommit`](docs/tools/precommit.md) review\n\nAll within a single conversation thread! Gemini Pro in step 11 _knows_ what was recommended by O3 in step 7! Taking that context\nand review into consideration to aid with its final pre-commit review.\n\n**Think of it as Claude Code _for_ Claude Code.** This MCP isn't magic. It's just **super-glue**.\n\n> **Remember:** Claude stays in full control β€” but **YOU** call the shots.\n> PAL is designed to have Claude engage other models only when needed β€” and to follow through with meaningful back-and-forth.\n> **You're** the one who crafts the powerful prompt that makes Claude bring in Gemini, Flash, O3 β€” or fly solo.\n> You're the guide. The prompter. The puppeteer.\n> #### You are the AI - **Actually Intelligent**.\n
\n\n#### Recommended AI Stack\n\n
\nFor Claude Code Users\n\nFor best results when using [Claude Code](https://claude.ai/code): \n\n- **Sonnet 4.5** - All agentic work and orchestration\n- **Gemini 3.0 Pro** OR **GPT-5.2 / Pro** - Deep thinking, additional code reviews, debugging and validations, pre-commit analysis\n
\n\n
\nFor Codex Users\n\nFor best results when using [Codex CLI](https://developers.openai.com/codex/cli): \n\n- **GPT-5.2 Codex Medium** - All agentic work and orchestration\n- **Gemini 3.0 Pro** OR **GPT-5.2-Pro** - Deep thinking, additional code reviews, debugging and validations, pre-commit analysis\n
\n\n## Quick Start (5 minutes)\n\n**Prerequisites:** Python 3.10+, Git, [uv installed](https://docs.astral.sh/uv/getting-started/installation/)\n\n**1. Get API Keys** (choose one or more):\n- **[OpenRouter](https://openrouter.ai/)** - Access multiple models with one API\n- **[Gemini](https://makersuite.google.com/app/apikey)** - Google's latest models\n- **[OpenAI](https://platform.openai.com/api-keys)** - O3, GPT-5 series\n- **[Azure OpenAI](https://learn.microsoft.com/azure/ai-services/openai/)** - Enterprise deployments of GPT-4o, GPT-4.1, GPT-5 family\n- **[X.AI](https://console.x.ai/)** - Grok models\n- **[DIAL](https://dialx.ai/)** - Vendor-agnostic model access\n- **[Ollama](https://ollama.ai/)** - Local models (free)\n\n**2. Install** (choose one):\n\n**Option A: Clone and Automatic Setup** (recommended)\n```bash\ngit clone https://github.com/BeehiveInnovations/pal-mcp-server.git\ncd pal-mcp-server\n\n# Handles everything: setup, config, API keys from system environment. \n# Auto-configures Claude Desktop, Claude Code, Gemini CLI, Codex CLI, Qwen CLI\n# Enable / disable additional settings in .env\n./run-server.sh \n```\n\n**Option B: Instant Setup with [uvx](https://docs.astral.sh/uv/getting-started/installation/)**\n```json\n// Add to ~/.claude/settings.json or .mcp.json\n// Don't forget to add your API keys under env\n{\n \"mcpServers\": {\n \"pal\": {\n \"command\": \"bash\",\n \"args\": [\"-c\", \"for p in $(which uvx 2>/dev/null) $HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \\\"$p\\\" ] && exec \\\"$p\\\" --from git+https://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server; done; echo 'uvx not found' >&2; exit 1\"],\n \"env\": {\n \"PATH\": \"/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/bin\",\n \"GEMINI_API_KEY\": \"your-key-here\",\n \"DISABLED_TOOLS\": \"analyze,refactor,testgen,secaudit,docgen,tracer\",\n \"DEFAULT_MODEL\": \"auto\"\n }\n }\n }\n}\n```\n\n**3. Start Using!**\n```\n\"Use pal to analyze this code for security issues with gemini pro\"\n\"Debug this error with o3 and then get flash to suggest optimizations\"\n\"Plan the migration strategy with pal, get consensus from multiple models\"\n\"clink with cli_name=\\\"gemini\\\" role=\\\"planner\\\" to draft a phased rollout plan\"\n```\n\nπŸ‘‰ **[Complete Setup Guide](docs/getting-started.md)** with detailed installation, configuration for Gemini / Codex / Qwen, and troubleshooting\nπŸ‘‰ **[Cursor & VS Code Setup](docs/getting-started.md#ide-clients)** for IDE integration instructions\nπŸ“Ί **[Watch tools in action](#-watch-tools-in-action)** to see real-world examples\n\n## Provider Configuration\n\nPAL activates any provider that has credentials in your `.env`. See `.env.example` for deeper customization.\n\n## Core Tools\n\n> **Note:** Each tool comes with its own multi-step workflow, parameters, and descriptions that consume valuable context window space even when not in use. To optimize performance, some tools are disabled by default. See [Tool Configuration](#tool-configuration) below to enable them.\n\n**Collaboration & Planning** *(Enabled by default)*\n- **[`clink`](docs/tools/clink.md)** - Bridge requests to external AI CLIs (Gemini planner, codereviewer, etc.)\n- **[`chat`](docs/tools/chat.md)** - Brainstorm ideas, get second opinions, validate approaches. With capable models (GPT-5.2 Pro, Gemini 3.0 Pro), generates complete code / implementation\n- **[`thinkdeep`](docs/tools/thinkdeep.md)** - Extended reasoning, edge case analysis, alternative perspectives\n- **[`planner`](docs/tools/planner.md)** - Break down complex projects into structured, actionable plans\n- **[`consensus`](docs/tools/consensus.md)** - Get expert opinions from multiple AI models with stance steering\n\n**Code Analysis & Quality**\n- **[`debug`](docs/tools/debug.md)** - Systematic investigation and root cause analysis\n- **[`precommit`](docs/tools/precommit.md)** - Validate changes before committing, prevent regressions\n- **[`codereview`](docs/tools/codereview.md)** - Professional reviews with severity levels and actionable feedback\n- **[`analyze`](docs/tools/analyze.md)** *(disabled by default - [enable](#tool-configuration))* - Understand architecture, patterns, dependencies across entire codebases\n\n**Development Tools** *(Disabled by default - [enable](#tool-configuration))*\n- **[`refactor`](docs/tools/refactor.md)** - Intelligent code refactoring with decomposition focus\n- **[`testgen`](docs/tools/testgen.md)** - Comprehensive test generation with edge cases\n- **[`secaudit`](docs/tools/secaudit.md)** - Security audits with OWASP Top 10 analysis\n- **[`docgen`](docs/tools/docgen.md)** - Generate documentation with complexity analysis\n\n**Utilities**\n- **[`apilookup`](docs/tools/apilookup.md)** - Forces current-year API/SDK documentation lookups in a sub-process (saves tokens within the current context window), prevents outdated training data responses\n- **[`challenge`](docs/tools/challenge.md)** - Prevent \"You're absolutely right!\" responses with critical analysis\n- **[`tracer`](docs/tools/tracer.md)** *(disabled by default - [enable](#tool-configuration))* - Static analysis prompts for call-flow mapping\n\n
\nπŸ‘‰ Tool Configuration\n\n### Default Configuration\n\nTo optimize context window usage, only essential tools are enabled by default:\n\n**Enabled by default:**\n- `chat`, `thinkdeep`, `planner`, `consensus` - Core collaboration tools\n- `codereview`, `precommit`, `debug` - Essential code quality tools\n- `apilookup` - Rapid API/SDK information lookup\n- `challenge` - Critical thinking utility\n\n**Disabled by default:**\n- `analyze`, `refactor`, `testgen`, `secaudit`, `docgen`, `tracer`\n\n### Enabling Additional Tools\n\nTo enable additional tools, remove them from the `DISABLED_TOOLS` list:\n\n**Option 1: Edit your .env file**\n```bash\n# Default configuration (from .env.example)\nDISABLED_TOOLS=analyze,refactor,testgen,secaudit,docgen,tracer\n\n# To enable specific tools, remove them from the list\n# Example: Enable analyze tool\nDISABLED_TOOLS=refactor,testgen,secaudit,docgen,tracer\n\n# To enable ALL tools\nDISABLED_TOOLS=\n```\n\n**Option 2: Configure in MCP settings**\n```json\n// In ~/.claude/settings.json or .mcp.json\n{\n \"mcpServers\": {\n \"pal\": {\n \"env\": {\n // Tool configuration\n \"DISABLED_TOOLS\": \"refactor,testgen,secaudit,docgen,tracer\",\n \"DEFAULT_MODEL\": \"pro\",\n \"DEFAULT_THINKING_MODE_THINKDEEP\": \"high\",\n \n // API configuration\n \"GEMINI_API_KEY\": \"your-gemini-key\",\n \"OPENAI_API_KEY\": \"your-openai-key\",\n \"OPENROUTER_API_KEY\": \"your-openrouter-key\",\n \n // Logging and performance\n \"LOG_LEVEL\": \"INFO\",\n \"CONVERSATION_TIMEOUT_HOURS\": \"6\",\n \"MAX_CONVERSATION_TURNS\": \"50\"\n }\n }\n }\n}\n```\n\n**Option 3: Enable all tools**\n```json\n// Remove or empty the DISABLED_TOOLS to enable everything\n{\n \"mcpServers\": {\n \"pal\": {\n \"env\": {\n \"DISABLED_TOOLS\": \"\"\n }\n }\n }\n}\n```\n\n**Note:**\n- Essential tools (`version`, `listmodels`) cannot be disabled\n- After changing tool configuration, restart your Claude session for changes to take effect\n- Each tool adds to context window usage, so only enable what you need\n\n
\n\n## πŸ“Ί Watch Tools In Action\n\n
\nChat Tool - Collaborative decision making and multi-turn conversations\n\n**Picking Redis vs Memcached:**\n\n[Chat Redis or Memcached_web.webm](https://github.com/user-attachments/assets/41076cfe-dd49-4dfc-82f5-d7461b34705d)\n\n**Multi-turn conversation with continuation:**\n\n[Chat With Gemini_web.webm](https://github.com/user-attachments/assets/37bd57ca-e8a6-42f7-b5fb-11de271e95db)\n\n
\n\n
\nConsensus Tool - Multi-model debate and decision making\n\n**Multi-model consensus debate:**\n\n[PAL Consensus Debate](https://github.com/user-attachments/assets/76a23dd5-887a-4382-9cf0-642f5cf6219e)\n\n
\n\n
\nPreCommit Tool - Comprehensive change validation\n\n**Pre-commit validation workflow:**\n\n
\n \n
\n\n
\n\n
\nAPI Lookup Tool - Current vs outdated API documentation\n\n**Without PAL - outdated APIs:**\n\n[API without PAL](https://github.com/user-attachments/assets/01a79dc9-ad16-4264-9ce1-76a56c3580ee)\n\n**With PAL - current APIs:**\n\n[API with PAL](https://github.com/user-attachments/assets/5c847326-4b66-41f7-8f30-f380453dce22)\n\n
\n\n
\nChallenge Tool - Critical thinking vs reflexive agreement\n\n**Without PAL:**\n\n![without_pal@2x](https://github.com/user-attachments/assets/64f3c9fb-7ca9-4876-b687-25e847edfd87)\n\n**With PAL:**\n\n![with_pal@2x](https://github.com/user-attachments/assets/9d72f444-ba53-4ab1-83e5-250062c6ee70)\n\n
\n\n## Key Features\n\n**AI Orchestration**\n- **Auto model selection** - Claude picks the right AI for each task\n- **Multi-model workflows** - Chain different models in single conversations\n- **Conversation continuity** - Context preserved across tools and models\n- **[Context revival](docs/context-revival.md)** - Continue conversations even after context resets\n\n**Model Support**\n- **Multiple providers** - Gemini, OpenAI, Azure, X.AI, OpenRouter, DIAL, Ollama\n- **Latest models** - GPT-5, Gemini 3.0 Pro, O3, Grok-4, local Llama\n- **[Thinking modes](docs/advanced-usage.md#thinking-modes)** - Control reasoning depth vs cost\n- **Vision support** - Analyze images, diagrams, screenshots\n\n**Developer Experience**\n- **Guided workflows** - Systematic investigation prevents rushed analysis\n- **Smart file handling** - Auto-expand directories, manage token limits\n- **Web search integration** - Access current documentation and best practices\n- **[Large prompt support](docs/advanced-usage.md#working-with-large-prompts)** - Bypass MCP's 25K token limit\n\n## Example Workflows\n\n**Multi-model Code Review:**\n```\n\"Perform a codereview using gemini pro and o3, then use planner to create a fix strategy\"\n```\nβ†’ Claude reviews code systematically β†’ Consults Gemini Pro β†’ Gets O3's perspective β†’ Creates unified action plan\n\n**Collaborative Debugging:**\n```\n\"Debug this race condition with max thinking mode, then validate the fix with precommit\"\n```\nβ†’ Deep investigation β†’ Expert analysis β†’ Solution implementation β†’ Pre-commit validation\n\n**Architecture Planning:**\n```\n\"Plan our microservices migration, get consensus from pro and o3 on the approach\"\n```\nβ†’ Structured planning β†’ Multiple expert opinions β†’ Consensus building β†’ Implementation roadmap\n\nπŸ‘‰ **[Advanced Usage Guide](docs/advanced-usage.md)** for complex workflows, model configuration, and power-user features\n\n## Quick Links\n\n**πŸ“– Documentation**\n- [Docs Overview](docs/index.md) - High-level map of major guides\n- [Getting Started](docs/getting-started.md) - Complete setup guide\n- [Tools Reference](docs/tools/) - All tools with examples\n- [Advanced Usage](docs/advanced-usage.md) - Power user features\n- [Configuration](docs/configuration.md) - Environment variables, restrictions\n- [Adding Providers](docs/adding_providers.md) - Provider-specific setup (OpenAI, Azure, custom gateways)\n- [Model Ranking Guide](docs/model_ranking.md) - How intelligence scores drive auto-mode suggestions\n\n**πŸ”§ Setup & Support**\n- [WSL Setup](docs/wsl-setup.md) - Windows users\n- [Troubleshooting](docs/troubleshooting.md) - Common issues\n- [Contributing](docs/contributions.md) - Code standards, PR process\n\n## License\n\nApache 2.0 License - see [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\nBuilt with the power of **Multi-Model AI** collaboration 🀝\n- **A**ctual **I**ntelligence by real Humans\n- [MCP (Model Context Protocol)](https://modelcontextprotocol.com)\n- [Codex CLI](https://developers.openai.com/codex/cli)\n- [Claude Code](https://claude.ai/code)\n- [Gemini](https://ai.google.dev/)\n- [OpenAI](https://openai.com/)\n- [Azure OpenAI](https://learn.microsoft.com/azure/ai-services/openai/)\n\n### Star History\n\n[![Star History Chart](https://api.star-history.com/svg?repos=BeehiveInnovations/pal-mcp-server&type=Date)](https://www.star-history.com/#BeehiveInnovations/pal-mcp-server&Date)\n" }, { "path": "SECURITY.md", "content": "# Security Policy\n\n## Supported Versions\n\n| Version | Supported |\n| ------- | ------------------ |\n| 9.x.x | :white_check_mark: |\n| < 9.0 | :x: |\n\n## Important Disclaimer\n\nPAL MCP is an open-source Model Context Protocol (MCP) server that acts as middleware between AI clients (Claude Code, Codex CLI, Cursor, etc.) and various AI model providers.\n\n**Please understand the following:**\n\n- **No Warranty**: This software is provided \"AS IS\" under the Apache 2.0 License, without warranties of any kind. See the [LICENSE](LICENSE) file for full terms.\n- **User Responsibility**: The AI client (not PAL MCP) controls tool invocations and workflows. Users are responsible for reviewing AI-generated outputs and actions.\n- **API Key Security**: You are responsible for securing your own API keys. Never commit keys to version control or share them publicly.\n- **Third-Party Services**: PAL MCP connects to external AI providers (Google, OpenAI, Azure, etc.). Their terms of service and privacy policies apply to data sent through this server.\n\n## Reporting a Vulnerability\n\n**Please do not report security vulnerabilities through public GitHub issues.**\n\n### Preferred Method\n\nUse [GitHub Security Advisories](https://github.com/BeehiveInnovations/pal-mcp-server/security/advisories/new) to report vulnerabilities privately.\n\n### What to Include\n\n- Description of the vulnerability\n- Steps to reproduce\n- Affected versions\n- Potential impact\n- Suggested fix (optional)\n\n### What to Expect\n\n- We will acknowledge your report and assess the issue\n- Critical issues will be prioritized\n- We'll keep you informed of progress as work proceeds\n\nWe cannot commit to specific response timelines, but we take security seriously.\n\n### After Resolution\n\nWe welcome security researchers to submit a pull request with the fix. This is an open-source project and we appreciate community contributions to improve security.\n\n## Disclosure Policy\n\nWe practice coordinated disclosure. Please allow reasonable time to address issues before public disclosure. We'll work with you on timing.\n\n## Scope\n\n### In Scope\n\n- Authentication/authorization bypasses\n- Injection vulnerabilities (command injection, prompt injection with security impact)\n- Information disclosure (API keys, sensitive data leakage)\n- Denial of service vulnerabilities in the MCP server itself\n- Dependency vulnerabilities with exploitable impact\n\n### Out of Scope\n\n- Issues in upstream AI providers (report to Google, OpenAI, etc. directly)\n- Issues in AI client software (report to Anthropic, OpenAI, Cursor, etc.)\n- AI model behavior or outputs (this is controlled by the AI client and model providers)\n- Social engineering attacks\n- Rate limiting or resource exhaustion on third-party APIs\n\n## Security Best Practices for Users\n\n1. **Protect API Keys**: Store keys in `.env` files (gitignored) or environment variables\n2. **Review AI Actions**: Always review AI-suggested code changes before applying\n3. **Use Local Models**: For sensitive codebases, consider using Ollama with local models\n4. **Network Security**: When self-hosting, ensure appropriate network controls\n5. **Keep Updated**: Regularly update to the latest version for security fixes\n\n## Recognition\n\nWe appreciate responsible disclosure and will credit security researchers in release notes (unless you prefer anonymity).\n" }, { "path": "claude_config_example.json", "content": "{\n \"comment\": \"Example Claude Desktop configuration for PAL MCP Server\",\n \"comment2\": \"Run './run-server.sh -c' to get the exact configuration for your system\",\n \"comment3\": \"For platform-specific examples, see the examples/ directory\",\n \"mcpServers\": {\n \"pal\": {\n \"command\": \"/path/to/pal-mcp-server/.pal_venv/bin/python\",\n \"args\": [\"/path/to/pal-mcp-server/server.py\"]\n }\n }\n}" }, { "path": "clink/__init__.py", "content": "\"\"\"Public helpers for clink components.\"\"\"\n\nfrom __future__ import annotations\n\nfrom .registry import ClinkRegistry, get_registry\n\n__all__ = [\"ClinkRegistry\", \"get_registry\"]\n" }, { "path": "clink/agents/__init__.py", "content": "\"\"\"Agent factory for clink CLI integrations.\"\"\"\n\nfrom __future__ import annotations\n\nfrom clink.models import ResolvedCLIClient\n\nfrom .base import AgentOutput, BaseCLIAgent, CLIAgentError\nfrom .claude import ClaudeAgent\nfrom .codex import CodexAgent\nfrom .gemini import GeminiAgent\n\n_AGENTS: dict[str, type[BaseCLIAgent]] = {\n \"gemini\": GeminiAgent,\n \"codex\": CodexAgent,\n \"claude\": ClaudeAgent,\n}\n\n\ndef create_agent(client: ResolvedCLIClient) -> BaseCLIAgent:\n agent_key = (client.runner or client.name).lower()\n agent_cls = _AGENTS.get(agent_key, BaseCLIAgent)\n return agent_cls(client)\n\n\n__all__ = [\n \"AgentOutput\",\n \"BaseCLIAgent\",\n \"CLIAgentError\",\n \"create_agent\",\n]\n" }, { "path": "clink/agents/base.py", "content": "\"\"\"Execute configured CLI agents for the clink tool and parse output.\"\"\"\n\nfrom __future__ import annotations\n\nimport asyncio\nimport logging\nimport os\nimport shlex\nimport shutil\nimport tempfile\nimport time\nfrom collections.abc import Sequence\nfrom dataclasses import dataclass\nfrom pathlib import Path\n\nfrom clink.constants import DEFAULT_STREAM_LIMIT\nfrom clink.models import ResolvedCLIClient, ResolvedCLIRole\nfrom clink.parsers import BaseParser, ParsedCLIResponse, ParserError, get_parser\n\nlogger = logging.getLogger(\"clink.agent\")\n\n\n@dataclass\nclass AgentOutput:\n \"\"\"Container returned by CLI agents after successful execution.\"\"\"\n\n parsed: ParsedCLIResponse\n sanitized_command: list[str]\n returncode: int\n stdout: str\n stderr: str\n duration_seconds: float\n parser_name: str\n output_file_content: str | None = None\n\n\nclass CLIAgentError(RuntimeError):\n \"\"\"Raised when a CLI agent fails (non-zero exit, timeout, parse errors).\"\"\"\n\n def __init__(self, message: str, *, returncode: int | None = None, stdout: str = \"\", stderr: str = \"\") -> None:\n super().__init__(message)\n self.returncode = returncode\n self.stdout = stdout\n self.stderr = stderr\n\n\nclass BaseCLIAgent:\n \"\"\"Execute a configured CLI command and parse its output.\"\"\"\n\n def __init__(self, client: ResolvedCLIClient):\n self.client = client\n self._parser: BaseParser = get_parser(client.parser)\n self._logger = logging.getLogger(f\"clink.runner.{client.name}\")\n\n async def run(\n self,\n *,\n role: ResolvedCLIRole,\n prompt: str,\n system_prompt: str | None = None,\n files: Sequence[str],\n images: Sequence[str],\n ) -> AgentOutput:\n # Files and images are already embedded into the prompt by the tool; they are\n # accepted here only to keep parity with SimpleTool callers.\n _ = (files, images)\n # The runner simply executes the configured CLI command for the selected role.\n command = self._build_command(role=role, system_prompt=system_prompt)\n env = self._build_environment()\n\n # Resolve executable path for cross-platform compatibility (especially Windows)\n executable_name = command[0]\n resolved_executable = shutil.which(executable_name)\n if resolved_executable is None:\n raise CLIAgentError(\n f\"Executable '{executable_name}' not found in PATH for CLI '{self.client.name}'. \"\n f\"Ensure the command is installed and accessible.\"\n )\n command[0] = resolved_executable\n\n sanitized_command = list(command)\n\n cwd = str(self.client.working_dir) if self.client.working_dir else None\n limit = DEFAULT_STREAM_LIMIT\n\n stdout_text = \"\"\n stderr_text = \"\"\n output_file_content: str | None = None\n start_time = time.monotonic()\n\n output_file_path: Path | None = None\n command_with_output_flag = list(command)\n\n if self.client.output_to_file:\n fd, tmp_path = tempfile.mkstemp(prefix=\"clink-\", suffix=\".json\")\n os.close(fd)\n output_file_path = Path(tmp_path)\n flag_template = self.client.output_to_file.flag_template\n try:\n rendered_flag = flag_template.format(path=str(output_file_path))\n except KeyError as exc: # pragma: no cover - defensive\n raise CLIAgentError(f\"Invalid output flag template '{flag_template}': missing placeholder {exc}\")\n command_with_output_flag.extend(shlex.split(rendered_flag))\n sanitized_command = list(command_with_output_flag)\n\n self._logger.debug(\"Executing CLI command: %s\", \" \".join(sanitized_command))\n if cwd:\n self._logger.debug(\"Working directory: %s\", cwd)\n\n try:\n process = await asyncio.create_subprocess_exec(\n *command_with_output_flag,\n stdin=asyncio.subprocess.PIPE,\n stdout=asyncio.subprocess.PIPE,\n stderr=asyncio.subprocess.PIPE,\n cwd=cwd,\n limit=limit,\n env=env,\n )\n except FileNotFoundError as exc:\n raise CLIAgentError(f\"Executable not found for CLI '{self.client.name}': {exc}\") from exc\n\n try:\n stdout_bytes, stderr_bytes = await asyncio.wait_for(\n process.communicate(prompt.encode(\"utf-8\")),\n timeout=self.client.timeout_seconds,\n )\n except asyncio.TimeoutError as exc:\n process.kill()\n await process.communicate()\n raise CLIAgentError(\n f\"CLI '{self.client.name}' timed out after {self.client.timeout_seconds} seconds\",\n returncode=None,\n ) from exc\n\n duration = time.monotonic() - start_time\n return_code = process.returncode\n stdout_text = stdout_bytes.decode(\"utf-8\", errors=\"replace\")\n stderr_text = stderr_bytes.decode(\"utf-8\", errors=\"replace\")\n\n if output_file_path and output_file_path.exists():\n output_file_content = output_file_path.read_text(encoding=\"utf-8\", errors=\"replace\")\n if self.client.output_to_file and self.client.output_to_file.cleanup:\n try:\n output_file_path.unlink()\n except OSError: # pragma: no cover - best effort cleanup\n pass\n\n if output_file_content and not stdout_text.strip():\n stdout_text = output_file_content\n\n if return_code != 0:\n recovered = self._recover_from_error(\n returncode=return_code,\n stdout=stdout_text,\n stderr=stderr_text,\n sanitized_command=sanitized_command,\n duration_seconds=duration,\n output_file_content=output_file_content,\n )\n if recovered is not None:\n return recovered\n\n if return_code != 0:\n raise CLIAgentError(\n f\"CLI '{self.client.name}' exited with status {return_code}\",\n returncode=return_code,\n stdout=stdout_text,\n stderr=stderr_text,\n )\n\n try:\n parsed = self._parser.parse(stdout_text, stderr_text)\n except ParserError as exc:\n raise CLIAgentError(\n f\"Failed to parse output from CLI '{self.client.name}': {exc}\",\n returncode=return_code,\n stdout=stdout_text,\n stderr=stderr_text,\n ) from exc\n\n return AgentOutput(\n parsed=parsed,\n sanitized_command=sanitized_command,\n returncode=return_code,\n stdout=stdout_text,\n stderr=stderr_text,\n duration_seconds=duration,\n parser_name=self._parser.name,\n output_file_content=output_file_content,\n )\n\n def _build_command(self, *, role: ResolvedCLIRole, system_prompt: str | None) -> list[str]:\n base = list(self.client.executable)\n base.extend(self.client.internal_args)\n base.extend(self.client.config_args)\n base.extend(role.role_args)\n\n return base\n\n def _build_environment(self) -> dict[str, str]:\n env = os.environ.copy()\n env.update(self.client.env)\n return env\n\n # ------------------------------------------------------------------\n # Error recovery hooks\n # ------------------------------------------------------------------\n\n def _recover_from_error(\n self,\n *,\n returncode: int,\n stdout: str,\n stderr: str,\n sanitized_command: list[str],\n duration_seconds: float,\n output_file_content: str | None,\n ) -> AgentOutput | None:\n \"\"\"Hook for subclasses to convert CLI errors into successful outputs.\n\n Return an AgentOutput to treat the failure as success, or None to signal\n that normal error handling should proceed.\n \"\"\"\n\n return None\n" }, { "path": "clink/agents/claude.py", "content": "\"\"\"Claude-specific CLI agent hooks.\"\"\"\n\nfrom __future__ import annotations\n\nfrom clink.models import ResolvedCLIRole\nfrom clink.parsers.base import ParserError\n\nfrom .base import AgentOutput, BaseCLIAgent\n\n\nclass ClaudeAgent(BaseCLIAgent):\n \"\"\"Claude CLI agent with system-prompt injection support.\"\"\"\n\n def _build_command(self, *, role: ResolvedCLIRole, system_prompt: str | None) -> list[str]:\n command = list(self.client.executable)\n command.extend(self.client.internal_args)\n command.extend(self.client.config_args)\n\n if system_prompt and \"--append-system-prompt\" not in self.client.config_args:\n command.extend([\"--append-system-prompt\", system_prompt])\n\n command.extend(role.role_args)\n return command\n\n def _recover_from_error(\n self,\n *,\n returncode: int,\n stdout: str,\n stderr: str,\n sanitized_command: list[str],\n duration_seconds: float,\n output_file_content: str | None,\n ) -> AgentOutput | None:\n try:\n parsed = self._parser.parse(stdout, stderr)\n except ParserError:\n return None\n\n return AgentOutput(\n parsed=parsed,\n sanitized_command=sanitized_command,\n returncode=returncode,\n stdout=stdout,\n stderr=stderr,\n duration_seconds=duration_seconds,\n parser_name=self._parser.name,\n output_file_content=output_file_content,\n )\n" }, { "path": "clink/agents/codex.py", "content": "\"\"\"Codex-specific CLI agent hooks.\"\"\"\n\nfrom __future__ import annotations\n\nfrom clink.models import ResolvedCLIClient\nfrom clink.parsers.base import ParserError\n\nfrom .base import AgentOutput, BaseCLIAgent\n\n\nclass CodexAgent(BaseCLIAgent):\n \"\"\"Codex CLI agent with JSONL recovery support.\"\"\"\n\n def __init__(self, client: ResolvedCLIClient):\n super().__init__(client)\n\n def _recover_from_error(\n self,\n *,\n returncode: int,\n stdout: str,\n stderr: str,\n sanitized_command: list[str],\n duration_seconds: float,\n output_file_content: str | None,\n ) -> AgentOutput | None:\n try:\n parsed = self._parser.parse(stdout, stderr)\n except ParserError:\n return None\n\n return AgentOutput(\n parsed=parsed,\n sanitized_command=sanitized_command,\n returncode=returncode,\n stdout=stdout,\n stderr=stderr,\n duration_seconds=duration_seconds,\n parser_name=self._parser.name,\n output_file_content=output_file_content,\n )\n" }, { "path": "clink/agents/gemini.py", "content": "\"\"\"Gemini-specific CLI agent hooks.\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nfrom typing import Any\n\nfrom clink.models import ResolvedCLIClient\nfrom clink.parsers.base import ParsedCLIResponse\n\nfrom .base import AgentOutput, BaseCLIAgent\n\n\nclass GeminiAgent(BaseCLIAgent):\n \"\"\"Gemini-specific behaviour.\"\"\"\n\n def __init__(self, client: ResolvedCLIClient):\n super().__init__(client)\n\n def _recover_from_error(\n self,\n *,\n returncode: int,\n stdout: str,\n stderr: str,\n sanitized_command: list[str],\n duration_seconds: float,\n output_file_content: str | None,\n ) -> AgentOutput | None:\n combined = \"\\n\".join(part for part in (stderr, stdout) if part)\n if not combined:\n return None\n\n brace_index = combined.find(\"{\")\n if brace_index == -1:\n return None\n\n json_candidate = combined[brace_index:]\n try:\n payload: dict[str, Any] = json.loads(json_candidate)\n except json.JSONDecodeError:\n return None\n\n error_block = payload.get(\"error\")\n if not isinstance(error_block, dict):\n return None\n\n code = error_block.get(\"code\")\n err_type = error_block.get(\"type\")\n detail_message = error_block.get(\"message\")\n\n prologue = combined[:brace_index].strip()\n lines: list[str] = []\n if prologue and (not detail_message or prologue not in detail_message):\n lines.append(prologue)\n if detail_message:\n lines.append(detail_message)\n\n header = \"Gemini CLI reported a tool failure\"\n if code:\n header = f\"{header} ({code})\"\n elif err_type:\n header = f\"{header} ({err_type})\"\n\n content_lines = [header.rstrip(\".\") + \".\"]\n content_lines.extend(lines)\n message = \"\\n\".join(content_lines).strip()\n\n metadata = {\n \"cli_error_recovered\": True,\n \"cli_error_code\": code,\n \"cli_error_type\": err_type,\n \"cli_error_payload\": payload,\n }\n\n parsed = ParsedCLIResponse(content=message or header, metadata=metadata)\n return AgentOutput(\n parsed=parsed,\n sanitized_command=sanitized_command,\n returncode=returncode,\n stdout=stdout,\n stderr=stderr,\n duration_seconds=duration_seconds,\n parser_name=self._parser.name,\n output_file_content=output_file_content,\n )\n" }, { "path": "clink/constants.py", "content": "\"\"\"Internal defaults and constants for clink.\"\"\"\n\nfrom __future__ import annotations\n\nfrom dataclasses import dataclass, field\nfrom pathlib import Path\n\nDEFAULT_TIMEOUT_SECONDS = 1800\nDEFAULT_STREAM_LIMIT = 10 * 1024 * 1024 # 10MB per stream\n\nPROJECT_ROOT = Path(__file__).resolve().parent.parent\nBUILTIN_PROMPTS_DIR = PROJECT_ROOT / \"systemprompts\" / \"clink\"\nCONFIG_DIR = PROJECT_ROOT / \"conf\" / \"cli_clients\"\nUSER_CONFIG_DIR = Path.home() / \".pal\" / \"cli_clients\"\n\n\n@dataclass(frozen=True)\nclass CLIInternalDefaults:\n \"\"\"Internal defaults applied to a CLI client during registry load.\"\"\"\n\n parser: str\n additional_args: list[str] = field(default_factory=list)\n env: dict[str, str] = field(default_factory=dict)\n default_role_prompt: str | None = None\n timeout_seconds: int = DEFAULT_TIMEOUT_SECONDS\n runner: str | None = None\n\n\nINTERNAL_DEFAULTS: dict[str, CLIInternalDefaults] = {\n \"gemini\": CLIInternalDefaults(\n parser=\"gemini_json\",\n additional_args=[\"-o\", \"json\"],\n default_role_prompt=\"systemprompts/clink/default.txt\",\n runner=\"gemini\",\n ),\n \"codex\": CLIInternalDefaults(\n parser=\"codex_jsonl\",\n additional_args=[\"exec\"],\n default_role_prompt=\"systemprompts/clink/default.txt\",\n runner=\"codex\",\n ),\n \"claude\": CLIInternalDefaults(\n parser=\"claude_json\",\n additional_args=[\"--print\", \"--output-format\", \"json\"],\n default_role_prompt=\"systemprompts/clink/default.txt\",\n runner=\"claude\",\n ),\n}\n" }, { "path": "clink/models.py", "content": "\"\"\"Pydantic models for clink configuration and runtime structures.\"\"\"\n\nfrom __future__ import annotations\n\nfrom pathlib import Path\nfrom typing import Any\n\nfrom pydantic import BaseModel, Field, PositiveInt, field_validator\n\n\nclass OutputCaptureConfig(BaseModel):\n \"\"\"Optional configuration for CLIs that write output to disk.\"\"\"\n\n flag_template: str = Field(..., description=\"Template used to inject the output path, e.g. '--output {path}'.\")\n cleanup: bool = Field(\n default=True,\n description=\"Whether the temporary file should be removed after reading.\",\n )\n\n\nclass CLIRoleConfig(BaseModel):\n \"\"\"Role-specific configuration loaded from JSON manifests.\"\"\"\n\n prompt_path: str | None = Field(\n default=None,\n description=\"Path to the prompt file that seeds this role.\",\n )\n role_args: list[str] = Field(default_factory=list)\n description: str | None = Field(default=None)\n\n @field_validator(\"role_args\", mode=\"before\")\n @classmethod\n def _ensure_list(cls, value: Any) -> list[str]:\n if value is None:\n return []\n if isinstance(value, list):\n return [str(item) for item in value]\n if isinstance(value, str):\n return [value]\n raise TypeError(\"role_args must be a list of strings or a single string\")\n\n\nclass CLIClientConfig(BaseModel):\n \"\"\"Raw CLI client configuration before internal defaults are applied.\"\"\"\n\n name: str\n command: str | None = None\n working_dir: str | None = None\n additional_args: list[str] = Field(default_factory=list)\n env: dict[str, str] = Field(default_factory=dict)\n timeout_seconds: PositiveInt | None = Field(default=None)\n roles: dict[str, CLIRoleConfig] = Field(default_factory=dict)\n output_to_file: OutputCaptureConfig | None = None\n\n @field_validator(\"additional_args\", mode=\"before\")\n @classmethod\n def _ensure_args_list(cls, value: Any) -> list[str]:\n if value is None:\n return []\n if isinstance(value, list):\n return [str(item) for item in value]\n if isinstance(value, str):\n return [value]\n raise TypeError(\"additional_args must be a list of strings or a single string\")\n\n\nclass ResolvedCLIRole(BaseModel):\n \"\"\"Runtime representation of a CLI role with resolved prompt path.\"\"\"\n\n name: str\n prompt_path: Path\n role_args: list[str] = Field(default_factory=list)\n description: str | None = None\n\n\nclass ResolvedCLIClient(BaseModel):\n \"\"\"Runtime configuration after merging defaults and validating paths.\"\"\"\n\n name: str\n executable: list[str]\n working_dir: Path | None\n internal_args: list[str] = Field(default_factory=list)\n config_args: list[str] = Field(default_factory=list)\n env: dict[str, str] = Field(default_factory=dict)\n timeout_seconds: int\n parser: str\n runner: str | None = None\n roles: dict[str, ResolvedCLIRole]\n output_to_file: OutputCaptureConfig | None = None\n\n def list_roles(self) -> list[str]:\n return list(self.roles.keys())\n\n def get_role(self, role_name: str | None) -> ResolvedCLIRole:\n key = role_name or \"default\"\n if key not in self.roles:\n available = \", \".join(sorted(self.roles.keys()))\n raise KeyError(f\"Role '{role_name}' not configured for CLI '{self.name}'. Available roles: {available}\")\n return self.roles[key]\n" }, { "path": "clink/parsers/__init__.py", "content": "\"\"\"Parser registry for clink.\"\"\"\n\nfrom __future__ import annotations\n\nfrom .base import BaseParser, ParsedCLIResponse, ParserError\nfrom .claude import ClaudeJSONParser\nfrom .codex import CodexJSONLParser\nfrom .gemini import GeminiJSONParser\n\n_PARSER_CLASSES: dict[str, type[BaseParser]] = {\n CodexJSONLParser.name: CodexJSONLParser,\n GeminiJSONParser.name: GeminiJSONParser,\n ClaudeJSONParser.name: ClaudeJSONParser,\n}\n\n\ndef get_parser(name: str) -> BaseParser:\n normalized = (name or \"\").lower()\n if normalized not in _PARSER_CLASSES:\n raise ParserError(f\"No parser registered for '{name}'\")\n parser_cls = _PARSER_CLASSES[normalized]\n return parser_cls()\n\n\n__all__ = [\n \"BaseParser\",\n \"ParsedCLIResponse\",\n \"ParserError\",\n \"get_parser\",\n]\n" }, { "path": "clink/parsers/base.py", "content": "\"\"\"Parser interfaces for clink runner outputs.\"\"\"\n\nfrom __future__ import annotations\n\nfrom dataclasses import dataclass\nfrom typing import Any\n\n\n@dataclass\nclass ParsedCLIResponse:\n \"\"\"Result of parsing CLI stdout/stderr.\"\"\"\n\n content: str\n metadata: dict[str, Any]\n\n\nclass ParserError(RuntimeError):\n \"\"\"Raised when CLI output cannot be parsed into a structured response.\"\"\"\n\n\nclass BaseParser:\n \"\"\"Base interface for CLI output parsers.\"\"\"\n\n name: str = \"base\"\n\n def parse(self, stdout: str, stderr: str) -> ParsedCLIResponse:\n raise NotImplementedError(\"Parsers must implement parse()\")\n" }, { "path": "clink/parsers/claude.py", "content": "\"\"\"Parser for Claude CLI JSON output.\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nfrom typing import Any\n\nfrom .base import BaseParser, ParsedCLIResponse, ParserError\n\n\nclass ClaudeJSONParser(BaseParser):\n \"\"\"Parse stdout produced by `claude --output-format json`.\"\"\"\n\n name = \"claude_json\"\n\n def parse(self, stdout: str, stderr: str) -> ParsedCLIResponse:\n if not stdout.strip():\n raise ParserError(\"Claude CLI returned empty stdout while JSON output was expected\")\n\n try:\n loaded = json.loads(stdout)\n except json.JSONDecodeError as exc: # pragma: no cover - defensive logging\n raise ParserError(f\"Failed to decode Claude CLI JSON output: {exc}\") from exc\n\n events: list[dict[str, Any]] | None = None\n assistant_entry: dict[str, Any] | None = None\n\n if isinstance(loaded, dict):\n payload: dict[str, Any] = loaded\n elif isinstance(loaded, list):\n events = [item for item in loaded if isinstance(item, dict)]\n result_entry = next(\n (item for item in events if item.get(\"type\") == \"result\" or \"result\" in item),\n None,\n )\n assistant_entry = next(\n (item for item in reversed(events) if item.get(\"type\") == \"assistant\"),\n None,\n )\n payload = result_entry or assistant_entry or (events[-1] if events else {})\n if not payload:\n raise ParserError(\"Claude CLI JSON array did not contain any parsable objects\")\n else:\n raise ParserError(\"Claude CLI returned unexpected JSON payload\")\n\n metadata = self._build_metadata(payload, stderr)\n if events is not None:\n metadata[\"raw_events\"] = events\n metadata[\"raw\"] = loaded\n\n result = payload.get(\"result\")\n content: str = \"\"\n if isinstance(result, str):\n content = result.strip()\n elif isinstance(result, list):\n # Some CLI flows may emit a list of strings; join them conservatively.\n joined = [part.strip() for part in result if isinstance(part, str) and part.strip()]\n content = \"\\n\".join(joined)\n\n if content:\n return ParsedCLIResponse(content=content, metadata=metadata)\n\n message = self._extract_message(payload)\n if message is None and assistant_entry and assistant_entry is not payload:\n message = self._extract_message(assistant_entry)\n if message:\n return ParsedCLIResponse(content=message, metadata=metadata)\n\n stderr_text = stderr.strip()\n if stderr_text:\n metadata.setdefault(\"stderr\", stderr_text)\n return ParsedCLIResponse(\n content=\"Claude CLI returned no textual result. Raw stderr was preserved for troubleshooting.\",\n metadata=metadata,\n )\n\n raise ParserError(\"Claude CLI response did not contain a textual result\")\n\n def _build_metadata(self, payload: dict[str, Any], stderr: str) -> dict[str, Any]:\n metadata: dict[str, Any] = {\n \"raw\": payload,\n \"is_error\": bool(payload.get(\"is_error\")),\n }\n\n type_field = payload.get(\"type\")\n if isinstance(type_field, str):\n metadata[\"type\"] = type_field\n subtype_field = payload.get(\"subtype\")\n if isinstance(subtype_field, str):\n metadata[\"subtype\"] = subtype_field\n\n duration_ms = payload.get(\"duration_ms\")\n if isinstance(duration_ms, (int, float)):\n metadata[\"duration_ms\"] = duration_ms\n api_duration = payload.get(\"duration_api_ms\")\n if isinstance(api_duration, (int, float)):\n metadata[\"duration_api_ms\"] = api_duration\n\n usage = payload.get(\"usage\")\n if isinstance(usage, dict):\n metadata[\"usage\"] = usage\n\n model_usage = payload.get(\"modelUsage\")\n if isinstance(model_usage, dict) and model_usage:\n metadata[\"model_usage\"] = model_usage\n first_model = next(iter(model_usage.keys()))\n metadata[\"model_used\"] = first_model\n\n permission_denials = payload.get(\"permission_denials\")\n if isinstance(permission_denials, list) and permission_denials:\n metadata[\"permission_denials\"] = permission_denials\n\n session_id = payload.get(\"session_id\")\n if isinstance(session_id, str) and session_id:\n metadata[\"session_id\"] = session_id\n uuid_field = payload.get(\"uuid\")\n if isinstance(uuid_field, str) and uuid_field:\n metadata[\"uuid\"] = uuid_field\n\n stderr_text = stderr.strip()\n if stderr_text:\n metadata.setdefault(\"stderr\", stderr_text)\n\n return metadata\n\n def _extract_message(self, payload: dict[str, Any]) -> str | None:\n message = payload.get(\"message\")\n if isinstance(message, str) and message.strip():\n return message.strip()\n\n error_field = payload.get(\"error\")\n if isinstance(error_field, dict):\n error_message = error_field.get(\"message\")\n if isinstance(error_message, str) and error_message.strip():\n return error_message.strip()\n\n return None\n" }, { "path": "clink/parsers/codex.py", "content": "\"\"\"Parser for Codex CLI JSONL output.\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nfrom typing import Any\n\nfrom .base import BaseParser, ParsedCLIResponse, ParserError\n\n\nclass CodexJSONLParser(BaseParser):\n \"\"\"Parse stdout emitted by `codex exec --json`.\"\"\"\n\n name = \"codex_jsonl\"\n\n def parse(self, stdout: str, stderr: str) -> ParsedCLIResponse:\n lines = [line.strip() for line in (stdout or \"\").splitlines() if line.strip()]\n events: list[dict[str, Any]] = []\n agent_messages: list[str] = []\n errors: list[str] = []\n usage: dict[str, Any] | None = None\n\n for line in lines:\n if not line.startswith(\"{\"):\n continue\n try:\n event = json.loads(line)\n except json.JSONDecodeError:\n continue\n\n events.append(event)\n event_type = event.get(\"type\")\n if event_type == \"item.completed\":\n item = event.get(\"item\") or {}\n if item.get(\"type\") == \"agent_message\":\n text = item.get(\"text\")\n if isinstance(text, str) and text.strip():\n agent_messages.append(text.strip())\n elif event_type == \"error\":\n message = event.get(\"message\")\n if isinstance(message, str) and message.strip():\n errors.append(message.strip())\n elif event_type == \"turn.completed\":\n turn_usage = event.get(\"usage\")\n if isinstance(turn_usage, dict):\n usage = turn_usage\n\n if not agent_messages and errors:\n agent_messages.extend(errors)\n\n if not agent_messages:\n raise ParserError(\"Codex CLI JSONL output did not include an agent_message item\")\n\n content = \"\\n\\n\".join(agent_messages).strip()\n metadata: dict[str, Any] = {\"events\": events}\n if errors:\n metadata[\"errors\"] = errors\n if usage:\n metadata[\"usage\"] = usage\n if stderr and stderr.strip():\n metadata[\"stderr\"] = stderr.strip()\n\n return ParsedCLIResponse(content=content, metadata=metadata)\n" }, { "path": "clink/parsers/gemini.py", "content": "\"\"\"Parser for Gemini CLI JSON output.\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nfrom typing import Any\n\nfrom .base import BaseParser, ParsedCLIResponse, ParserError\n\n\nclass GeminiJSONParser(BaseParser):\n \"\"\"Parse stdout produced by `gemini -o json`.\"\"\"\n\n name = \"gemini_json\"\n\n def parse(self, stdout: str, stderr: str) -> ParsedCLIResponse:\n if not stdout.strip():\n raise ParserError(\"Gemini CLI returned empty stdout while JSON output was expected\")\n\n try:\n payload: dict[str, Any] = json.loads(stdout)\n except json.JSONDecodeError as exc: # pragma: no cover - defensive logging\n raise ParserError(f\"Failed to decode Gemini CLI JSON output: {exc}\") from exc\n\n response = payload.get(\"response\")\n response_text = response.strip() if isinstance(response, str) else \"\"\n\n metadata: dict[str, Any] = {\"raw\": payload}\n\n stats = payload.get(\"stats\")\n if isinstance(stats, dict):\n metadata[\"stats\"] = stats\n models = stats.get(\"models\")\n if isinstance(models, dict) and models:\n model_name = next(iter(models.keys()))\n metadata[\"model_used\"] = model_name\n model_stats = models.get(model_name) or {}\n tokens = model_stats.get(\"tokens\")\n if isinstance(tokens, dict):\n metadata[\"token_usage\"] = tokens\n api_stats = model_stats.get(\"api\")\n if isinstance(api_stats, dict):\n metadata[\"latency_ms\"] = api_stats.get(\"totalLatencyMs\")\n\n if response_text:\n if stderr and stderr.strip():\n metadata[\"stderr\"] = stderr.strip()\n return ParsedCLIResponse(content=response_text, metadata=metadata)\n\n fallback_message, extra_metadata = self._build_fallback_message(payload, stderr)\n if fallback_message:\n metadata.update(extra_metadata)\n if stderr and stderr.strip():\n metadata[\"stderr\"] = stderr.strip()\n return ParsedCLIResponse(content=fallback_message, metadata=metadata)\n\n raise ParserError(\"Gemini CLI response is missing a textual 'response' field\")\n\n def _build_fallback_message(self, payload: dict[str, Any], stderr: str) -> tuple[str | None, dict[str, Any]]:\n \"\"\"Derive a human friendly message when Gemini returns empty content.\"\"\"\n\n stderr_text = stderr.strip() if stderr else \"\"\n stderr_lower = stderr_text.lower()\n extra_metadata: dict[str, Any] = {\"empty_response\": True}\n\n if \"429\" in stderr_lower or \"rate limit\" in stderr_lower:\n extra_metadata[\"rate_limit_status\"] = 429\n message = (\n \"Gemini request returned no content because the API reported a 429 rate limit. \"\n \"Retry after reducing the request size or waiting for quota to replenish.\"\n )\n return message, extra_metadata\n\n stats = payload.get(\"stats\")\n if isinstance(stats, dict):\n models = stats.get(\"models\")\n if isinstance(models, dict) and models:\n first_model = next(iter(models.values()))\n if isinstance(first_model, dict):\n api_stats = first_model.get(\"api\")\n if isinstance(api_stats, dict):\n total_errors = api_stats.get(\"totalErrors\")\n total_requests = api_stats.get(\"totalRequests\")\n if isinstance(total_errors, int) and total_errors > 0:\n extra_metadata[\"api_total_errors\"] = total_errors\n if isinstance(total_requests, int):\n extra_metadata[\"api_total_requests\"] = total_requests\n message = (\n \"Gemini CLI returned no textual output. The API reported \"\n f\"{total_errors} error(s); see stderr for details.\"\n )\n return message, extra_metadata\n\n if stderr_text:\n message = \"Gemini CLI returned no textual output. Raw stderr was preserved for troubleshooting.\"\n return message, extra_metadata\n\n return None, extra_metadata\n" }, { "path": "clink/registry.py", "content": "\"\"\"Configuration registry for clink CLI integrations.\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport logging\nimport shlex\nfrom collections.abc import Iterable\nfrom pathlib import Path\n\nfrom clink.constants import (\n CONFIG_DIR,\n DEFAULT_TIMEOUT_SECONDS,\n INTERNAL_DEFAULTS,\n PROJECT_ROOT,\n USER_CONFIG_DIR,\n CLIInternalDefaults,\n)\nfrom clink.models import (\n CLIClientConfig,\n CLIRoleConfig,\n ResolvedCLIClient,\n ResolvedCLIRole,\n)\nfrom utils.env import get_env\nfrom utils.file_utils import read_json_file\n\nlogger = logging.getLogger(\"clink.registry\")\n\nCONFIG_ENV_VAR = \"CLI_CLIENTS_CONFIG_PATH\"\n\n\nclass RegistryLoadError(RuntimeError):\n \"\"\"Raised when configuration files are invalid or missing critical data.\"\"\"\n\n\nclass ClinkRegistry:\n \"\"\"Loads CLI client definitions and exposes them for schema generation/runtime use.\"\"\"\n\n def __init__(self) -> None:\n self._clients: dict[str, ResolvedCLIClient] = {}\n self._load()\n\n def _load(self) -> None:\n self._clients.clear()\n for config_path in self._iter_config_files():\n try:\n data = read_json_file(str(config_path))\n except json.JSONDecodeError as exc:\n raise RegistryLoadError(f\"Invalid JSON in {config_path}: {exc}\") from exc\n\n if not data:\n logger.debug(\"Skipping empty configuration file: %s\", config_path)\n continue\n\n config = CLIClientConfig.model_validate(data)\n resolved = self._resolve_config(config, source_path=config_path)\n key = resolved.name.lower()\n if key in self._clients:\n logger.info(\"Overriding CLI configuration for '%s' from %s\", resolved.name, config_path)\n else:\n logger.debug(\"Loaded CLI configuration for '%s' from %s\", resolved.name, config_path)\n self._clients[key] = resolved\n\n if not self._clients:\n raise RegistryLoadError(\n \"No CLI clients configured. Ensure conf/cli_clients contains at least one definition or set \"\n f\"{CONFIG_ENV_VAR}.\"\n )\n\n def reload(self) -> None:\n \"\"\"Reload configurations from disk.\"\"\"\n self._load()\n\n def list_clients(self) -> list[str]:\n return sorted(client.name for client in self._clients.values())\n\n def list_roles(self, cli_name: str) -> list[str]:\n config = self.get_client(cli_name)\n return sorted(config.roles.keys())\n\n def get_client(self, cli_name: str) -> ResolvedCLIClient:\n key = cli_name.lower()\n if key not in self._clients:\n available = \", \".join(self.list_clients())\n raise KeyError(f\"CLI '{cli_name}' is not configured. Available clients: {available}\")\n return self._clients[key]\n\n # ------------------------------------------------------------------\n # Internal helpers\n # ------------------------------------------------------------------\n\n def _iter_config_files(self) -> Iterable[Path]:\n search_paths: list[Path] = []\n\n # 1. Built-in configs\n search_paths.append(CONFIG_DIR)\n\n # 2. CLI_CLIENTS_CONFIG_PATH environment override (file or directory)\n env_path_raw = get_env(CONFIG_ENV_VAR)\n if env_path_raw:\n env_path = Path(env_path_raw).expanduser()\n search_paths.append(env_path)\n\n # 3. User overrides in ~/.pal/cli_clients\n search_paths.append(USER_CONFIG_DIR)\n\n seen: set[Path] = set()\n\n for base in search_paths:\n if not base:\n continue\n if base in seen:\n continue\n seen.add(base)\n\n if base.is_file() and base.suffix.lower() == \".json\":\n yield base\n continue\n\n if base.is_dir():\n for path in sorted(base.glob(\"*.json\")):\n if path.is_file():\n yield path\n else:\n logger.debug(\"Configuration path does not exist: %s\", base)\n\n def _resolve_config(self, raw: CLIClientConfig, *, source_path: Path) -> ResolvedCLIClient:\n if not raw.name:\n raise RegistryLoadError(f\"CLI configuration at {source_path} is missing a 'name' field\")\n\n normalized_name = raw.name.strip()\n internal_defaults = INTERNAL_DEFAULTS.get(normalized_name.lower())\n if internal_defaults is None:\n raise RegistryLoadError(f\"CLI '{raw.name}' is not supported by clink\")\n\n executable = self._resolve_executable(raw, internal_defaults, source_path)\n\n internal_args = list(internal_defaults.additional_args) if internal_defaults else []\n config_args = list(raw.additional_args)\n\n timeout_seconds = raw.timeout_seconds or (\n internal_defaults.timeout_seconds if internal_defaults else DEFAULT_TIMEOUT_SECONDS\n )\n\n parser_name = internal_defaults.parser\n if not parser_name:\n raise RegistryLoadError(\n f\"CLI '{raw.name}' must define a parser either in configuration or internal defaults\"\n )\n\n runner_name = internal_defaults.runner if internal_defaults else None\n\n env = self._merge_env(raw, internal_defaults)\n working_dir = self._resolve_optional_path(raw.working_dir, source_path.parent)\n roles = self._resolve_roles(raw, internal_defaults, source_path)\n\n output_to_file = raw.output_to_file\n\n return ResolvedCLIClient(\n name=normalized_name,\n executable=executable,\n internal_args=internal_args,\n config_args=config_args,\n env=env,\n timeout_seconds=int(timeout_seconds),\n parser=parser_name,\n runner=runner_name,\n roles=roles,\n output_to_file=output_to_file,\n working_dir=working_dir,\n )\n\n def _resolve_executable(\n self,\n raw: CLIClientConfig,\n internal_defaults: CLIInternalDefaults | None,\n source_path: Path,\n ) -> list[str]:\n command = raw.command\n if not command:\n raise RegistryLoadError(f\"CLI '{raw.name}' must specify a 'command' in configuration\")\n return shlex.split(command)\n\n def _merge_env(\n self,\n raw: CLIClientConfig,\n internal_defaults: CLIInternalDefaults | None,\n ) -> dict[str, str]:\n merged: dict[str, str] = {}\n if internal_defaults and internal_defaults.env:\n merged.update(internal_defaults.env)\n merged.update(raw.env)\n return merged\n\n def _resolve_roles(\n self,\n raw: CLIClientConfig,\n internal_defaults: CLIInternalDefaults | None,\n source_path: Path,\n ) -> dict[str, ResolvedCLIRole]:\n roles: dict[str, CLIRoleConfig] = dict(raw.roles)\n\n default_role_prompt = internal_defaults.default_role_prompt if internal_defaults else None\n if \"default\" not in roles:\n roles[\"default\"] = CLIRoleConfig(prompt_path=default_role_prompt)\n elif roles[\"default\"].prompt_path is None and default_role_prompt:\n roles[\"default\"].prompt_path = default_role_prompt\n\n resolved: dict[str, ResolvedCLIRole] = {}\n for role_name, role_config in roles.items():\n prompt_path_str = role_config.prompt_path or default_role_prompt\n if not prompt_path_str:\n raise RegistryLoadError(f\"Role '{role_name}' for CLI '{raw.name}' must define a prompt_path\")\n prompt_path = self._resolve_prompt_path(prompt_path_str, source_path.parent)\n resolved[role_name] = ResolvedCLIRole(\n name=role_name,\n prompt_path=prompt_path,\n role_args=list(role_config.role_args),\n description=role_config.description,\n )\n return resolved\n\n def _resolve_prompt_path(self, prompt_path: str, base_dir: Path) -> Path:\n resolved = self._resolve_path(prompt_path, base_dir)\n if not resolved.exists():\n raise RegistryLoadError(f\"Prompt file not found: {resolved}\")\n return resolved\n\n def _resolve_optional_path(self, candidate: str | None, base_dir: Path) -> Path | None:\n if not candidate:\n return None\n return self._resolve_path(candidate, base_dir)\n\n def _resolve_path(self, candidate: str, base_dir: Path) -> Path:\n path = Path(candidate)\n if path.is_absolute():\n return path\n\n candidate_path = (base_dir / path).resolve()\n if candidate_path.exists():\n return candidate_path\n\n project_relative = (PROJECT_ROOT / path).resolve()\n return project_relative\n\n\n_REGISTRY: ClinkRegistry | None = None\n\n\ndef get_registry() -> ClinkRegistry:\n global _REGISTRY\n if _REGISTRY is None:\n _REGISTRY = ClinkRegistry()\n return _REGISTRY\n" }, { "path": "code_quality_checks.ps1", "content": "<#\n.SYNOPSIS\n Code quality checks script for PAL MCP server on Windows.\n\n.DESCRIPTION\n This PowerShell script performs code quality checks for the PAL MCP server project:\n - Runs static analysis and linting tools on the codebase\n - Ensures code style compliance and detects potential issues\n - Can be integrated into CI/CD pipelines or used locally before commits\n\n.PARAMETER Help\n Displays help information for using the script.\n\n.PARAMETER Verbose\n Enables detailed output during code quality checks.\n\n.EXAMPLE\n .\\code_quality_checks.ps1\n Runs all code quality checks on the project.\n\n .\\code_quality_checks.ps1 -Verbose\n Runs code quality checks with detailed output.\n\n.NOTES\n Project Author : BeehiveInnovations\n Script Author : GiGiDKR (https://github.com/GiGiDKR)\n Date : 07-05-2025\n Version : See project documentation\n References : https://github.com/BeehiveInnovations/pal-mcp-server\n#>\n#Requires -Version 5.1\n[CmdletBinding()]\nparam(\n [switch]$SkipTests,\n [switch]$SkipLinting,\n [switch]$VerboseOutput\n)\n\n# Set error action preference\n$ErrorActionPreference = \"Stop\"\n\n# Colors for output\nfunction Write-ColorText {\n param(\n [Parameter(Mandatory)]\n [string]$Text,\n [string]$Color = \"White\"\n )\n Write-Host $Text -ForegroundColor $Color\n}\n\nfunction Write-Emoji {\n param(\n [Parameter(Mandatory)]\n [string]$Emoji,\n [Parameter(Mandatory)]\n [string]$Text,\n [string]$Color = \"White\"\n )\n Write-Host \"$Emoji \" -NoNewline\n Write-ColorText $Text -Color $Color\n}\n\nWrite-Emoji \"πŸ”\" \"Running Code Quality Checks for PAL MCP Server\" -Color Cyan\nWrite-ColorText \"=================================================\" -Color Cyan\n\n# Determine Python command\n$pythonCmd = $null\n$pipCmd = $null\n\nif (Test-Path \".pal_venv\") {\n if ($IsWindows -or $env:OS -eq \"Windows_NT\") {\n if (Test-Path \".pal_venv\\Scripts\\python.exe\") {\n $pythonCmd = \".pal_venv\\Scripts\\python.exe\"\n $pipCmd = \".pal_venv\\Scripts\\pip.exe\"\n }\n } else {\n if (Test-Path \".pal_venv/bin/python\") {\n $pythonCmd = \".pal_venv/bin/python\"\n $pipCmd = \".pal_venv/bin/pip\"\n }\n }\n \n if ($pythonCmd) {\n Write-Emoji \"βœ…\" \"Using venv\" -Color Green\n }\n} elseif ($env:VIRTUAL_ENV) {\n $pythonCmd = \"python\"\n $pipCmd = \"pip\"\n Write-Emoji \"βœ…\" \"Using activated virtual environment: $env:VIRTUAL_ENV\" -Color Green\n} else {\n Write-Emoji \"❌\" \"No virtual environment found!\" -Color Red\n Write-ColorText \"Please run: .\\run-server.ps1 first to set up the environment\" -Color Yellow\n exit 1\n}\n\nWrite-Host \"\"\n\n# Check and install dev dependencies if needed\nWrite-Emoji \"πŸ”\" \"Checking development dependencies...\" -Color Cyan\n$devDepsNeeded = $false\n\n# List of dev tools to check\n$devTools = @(\"ruff\", \"black\", \"isort\", \"pytest\")\n\nforeach ($tool in $devTools) {\n $toolFound = $false\n \n # Check in venv\n if ($IsWindows -or $env:OS -eq \"Windows_NT\") {\n if (Test-Path \".pal_venv\\Scripts\\$tool.exe\") {\n $toolFound = $true\n }\n } else {\n if (Test-Path \".pal_venv/bin/$tool\") {\n $toolFound = $true\n }\n }\n \n # Check in PATH\n if (!$toolFound) {\n try {\n $null = Get-Command $tool -ErrorAction Stop\n $toolFound = $true\n } catch {\n # Tool not found\n }\n }\n \n if (!$toolFound) {\n $devDepsNeeded = $true\n break\n }\n}\n\nif ($devDepsNeeded) {\n Write-Emoji \"πŸ“¦\" \"Installing development dependencies...\" -Color Yellow\n try {\n & $pipCmd install -q -r requirements-dev.txt\n if ($LASTEXITCODE -ne 0) {\n throw \"Failed to install dev dependencies\"\n }\n Write-Emoji \"βœ…\" \"Development dependencies installed\" -Color Green\n } catch {\n Write-Emoji \"❌\" \"Failed to install development dependencies\" -Color Red\n Write-ColorText \"Error: $_\" -Color Red\n exit 1\n }\n} else {\n Write-Emoji \"βœ…\" \"Development dependencies already installed\" -Color Green\n}\n\n# Set tool paths\nif ($IsWindows -or $env:OS -eq \"Windows_NT\") {\n $ruffCmd = if (Test-Path \".pal_venv\\Scripts\\ruff.exe\") { \".pal_venv\\Scripts\\ruff.exe\" } else { \"ruff\" }\n $blackCmd = if (Test-Path \".pal_venv\\Scripts\\black.exe\") { \".pal_venv\\Scripts\\black.exe\" } else { \"black\" }\n $isortCmd = if (Test-Path \".pal_venv\\Scripts\\isort.exe\") { \".pal_venv\\Scripts\\isort.exe\" } else { \"isort\" }\n $pytestCmd = if (Test-Path \".pal_venv\\Scripts\\pytest.exe\") { \".pal_venv\\Scripts\\pytest.exe\" } else { \"pytest\" }\n} else {\n $ruffCmd = if (Test-Path \".pal_venv/bin/ruff\") { \".pal_venv/bin/ruff\" } else { \"ruff\" }\n $blackCmd = if (Test-Path \".pal_venv/bin/black\") { \".pal_venv/bin/black\" } else { \"black\" }\n $isortCmd = if (Test-Path \".pal_venv/bin/isort\") { \".pal_venv/bin/isort\" } else { \"isort\" }\n $pytestCmd = if (Test-Path \".pal_venv/bin/pytest\") { \".pal_venv/bin/pytest\" } else { \"pytest\" }\n}\n\nWrite-Host \"\"\n\n# Step 1: Linting and Formatting\nif (!$SkipLinting) {\n Write-Emoji \"πŸ“‹\" \"Step 1: Running Linting and Formatting Checks\" -Color Cyan\n Write-ColorText \"--------------------------------------------------\" -Color Cyan\n\n try {\n Write-Emoji \"πŸ”§\" \"Running ruff linting with auto-fix...\" -Color Yellow\n & $ruffCmd check --fix --exclude test_simulation_files --exclude .pal_venv\n if ($LASTEXITCODE -ne 0) {\n throw \"Ruff linting failed\"\n }\n\n Write-Emoji \"🎨\" \"Running black code formatting...\" -Color Yellow\n & $blackCmd . --exclude=\"test_simulation_files/\" --exclude=\".pal_venv/\"\n if ($LASTEXITCODE -ne 0) {\n throw \"Black formatting failed\"\n }\n\n Write-Emoji \"πŸ“¦\" \"Running import sorting with isort...\" -Color Yellow\n & $isortCmd . --skip-glob=\".pal_venv/*\" --skip-glob=\"test_simulation_files/*\"\n if ($LASTEXITCODE -ne 0) {\n throw \"Import sorting failed\"\n }\n\n Write-Emoji \"βœ…\" \"Verifying all linting passes...\" -Color Yellow\n & $ruffCmd check --exclude test_simulation_files --exclude .pal_venv\n if ($LASTEXITCODE -ne 0) {\n throw \"Final linting verification failed\"\n }\n\n Write-Emoji \"βœ…\" \"Step 1 Complete: All linting and formatting checks passed!\" -Color Green\n } catch {\n Write-Emoji \"❌\" \"Step 1 Failed: Linting and formatting checks failed\" -Color Red\n Write-ColorText \"Error: $_\" -Color Red\n exit 1\n }\n} else {\n Write-Emoji \"⏭️\" \"Skipping linting and formatting checks\" -Color Yellow\n}\n\nWrite-Host \"\"\n\n# Step 2: Unit Tests\nif (!$SkipTests) {\n Write-Emoji \"πŸ§ͺ\" \"Step 2: Running Complete Unit Test Suite\" -Color Cyan\n Write-ColorText \"---------------------------------------------\" -Color Cyan\n\n try {\n Write-Emoji \"πŸƒ\" \"Running unit tests (excluding integration tests)...\" -Color Yellow\n \n $pytestArgs = @(\"tests/\", \"-v\", \"-x\", \"-m\", \"not integration\")\n if ($VerboseOutput) {\n $pytestArgs += \"--verbose\"\n }\n \n & $pythonCmd -m pytest @pytestArgs\n if ($LASTEXITCODE -ne 0) {\n throw \"Unit tests failed\"\n }\n\n Write-Emoji \"βœ…\" \"Step 2 Complete: All unit tests passed!\" -Color Green\n } catch {\n Write-Emoji \"❌\" \"Step 2 Failed: Unit tests failed\" -Color Red\n Write-ColorText \"Error: $_\" -Color Red\n exit 1\n }\n} else {\n Write-Emoji \"⏭️\" \"Skipping unit tests\" -Color Yellow\n}\n\nWrite-Host \"\"\n\n# Step 3: Final Summary\nWrite-Emoji \"πŸŽ‰\" \"All Code Quality Checks Passed!\" -Color Green\nWrite-ColorText \"==================================\" -Color Green\n\nif (!$SkipLinting) {\n Write-Emoji \"βœ…\" \"Linting (ruff): PASSED\" -Color Green\n Write-Emoji \"βœ…\" \"Formatting (black): PASSED\" -Color Green\n Write-Emoji \"βœ…\" \"Import sorting (isort): PASSED\" -Color Green\n} else {\n Write-Emoji \"⏭️\" \"Linting: SKIPPED\" -Color Yellow\n}\n\nif (!$SkipTests) {\n Write-Emoji \"βœ…\" \"Unit tests: PASSED\" -Color Green\n} else {\n Write-Emoji \"⏭️\" \"Unit tests: SKIPPED\" -Color Yellow\n}\n\nWrite-Host \"\"\nWrite-Emoji \"πŸš€\" \"Your code is ready for commit and GitHub Actions!\" -Color Green\nWrite-Emoji \"πŸ’‘\" \"Remember to add simulator tests if you modified tools\" -Color Yellow\n" }, { "path": "code_quality_checks.sh", "content": "#!/bin/bash\n\n# PAL MCP Server - Code Quality Checks\n# This script runs all required linting and testing checks before committing changes.\n# ALL checks must pass 100% for CI/CD to succeed.\n\nset -e # Exit on any error\n\necho \"πŸ” Running Code Quality Checks for PAL MCP Server\"\necho \"=================================================\"\n\n# Determine Python command\nif [[ -f \".pal_venv/bin/python\" ]]; then\n PYTHON_CMD=\".pal_venv/bin/python\"\n PIP_CMD=\".pal_venv/bin/pip\"\n echo \"βœ… Using venv\"\nelif [[ -n \"$VIRTUAL_ENV\" ]]; then\n PYTHON_CMD=\"python\"\n PIP_CMD=\"pip\"\n echo \"βœ… Using activated virtual environment: $VIRTUAL_ENV\"\nelse\n echo \"❌ No virtual environment found!\"\n echo \"Please run: ./run-server.sh first to set up the environment\"\n exit 1\nfi\necho \"\"\n\n# Check and install dev dependencies if needed\necho \"πŸ” Checking development dependencies...\"\nDEV_DEPS_NEEDED=false\n\n# Check each dev dependency\nfor tool in ruff black isort pytest; do\n # Check if tool exists in venv or in PATH\n if [[ -f \".pal_venv/bin/$tool\" ]] || command -v $tool &> /dev/null; then\n continue\n else\n DEV_DEPS_NEEDED=true\n break\n fi\ndone\n\nif [ \"$DEV_DEPS_NEEDED\" = true ]; then\n echo \"πŸ“¦ Installing development dependencies...\"\n $PIP_CMD install -q -r requirements-dev.txt\n echo \"βœ… Development dependencies installed\"\nelse\n echo \"βœ… Development dependencies already installed\"\nfi\n\n# Set tool paths\nif [[ -f \".pal_venv/bin/ruff\" ]]; then\n RUFF=\".pal_venv/bin/ruff\"\n BLACK=\".pal_venv/bin/black\"\n ISORT=\".pal_venv/bin/isort\"\n PYTEST=\".pal_venv/bin/pytest\"\nelse\n RUFF=\"ruff\"\n BLACK=\"black\"\n ISORT=\"isort\"\n PYTEST=\"pytest\"\nfi\necho \"\"\n\n# Step 1: Linting and Formatting\necho \"πŸ“‹ Step 1: Running Linting and Formatting Checks\"\necho \"--------------------------------------------------\"\n\necho \"πŸ”§ Running ruff linting with auto-fix...\"\n$RUFF check --fix --exclude test_simulation_files --exclude .pal_venv\n\necho \"🎨 Running black code formatting...\"\n$BLACK . --exclude=\"test_simulation_files/\" --exclude=\".pal_venv/\"\n\necho \"πŸ“¦ Running import sorting with isort...\"\n$ISORT . --skip-glob=\".pal_venv/*\" --skip-glob=\"test_simulation_files/*\"\n\necho \"βœ… Verifying all linting passes...\"\n$RUFF check --exclude test_simulation_files --exclude .pal_venv\n\necho \"βœ… Step 1 Complete: All linting and formatting checks passed!\"\necho \"\"\n\n# Step 2: Unit Tests\necho \"πŸ§ͺ Step 2: Running Complete Unit Test Suite\"\necho \"---------------------------------------------\"\n\necho \"πŸƒ Running unit tests (excluding integration tests)...\"\n$PYTHON_CMD -m pytest tests/ -v -x -m \"not integration\"\n\necho \"βœ… Step 2 Complete: All unit tests passed!\"\necho \"\"\n\n# Step 3: Final Summary\necho \"πŸŽ‰ All Code Quality Checks Passed!\"\necho \"==================================\"\necho \"βœ… Linting (ruff): PASSED\"\necho \"βœ… Formatting (black): PASSED\" \necho \"βœ… Import sorting (isort): PASSED\"\necho \"βœ… Unit tests: PASSED\"\necho \"\"\necho \"πŸš€ Your code is ready for commit and GitHub Actions!\"\necho \"πŸ’‘ Remember to add simulator tests if you modified tools\"" }, { "path": "communication_simulator_test.py", "content": "\"\"\"\nCommunication Simulator Test for PAL MCP Server\n\nThis script provides comprehensive end-to-end testing of the PAL MCP Server\nby simulating real Claude CLI communications and validating conversation\ncontinuity, file handling, deduplication features, and clarification scenarios.\n\nTest Flow:\n1. Setup standalone server environment\n2. Load and run individual test modules\n3. Validate system behavior through logs and memory\n4. Cleanup and report results\n\nUsage:\n python communication_simulator_test.py [--verbose] [--keep-logs] [--tests TEST_NAME...] [--individual TEST_NAME] [--setup]\n\n --tests: Run specific tests only (space-separated)\n --list-tests: List all available tests\n --individual: Run a single test individually\n --setup: Force setup standalone server environment using run-server.sh\n\nAvailable tests:\n basic_conversation - Basic conversation flow with chat tool\n content_validation - Content validation and duplicate detection\n per_tool_deduplication - File deduplication for individual tools\n cross_tool_continuation - Cross-tool conversation continuation scenarios\n cross_tool_comprehensive - Comprehensive cross-tool integration testing\n line_number_validation - Line number handling validation across tools\n memory_validation - Conversation memory validation\n model_thinking_config - Model thinking configuration testing\n o3_model_selection - O3 model selection and routing testing\n ollama_custom_url - Ollama custom URL configuration testing\n openrouter_fallback - OpenRouter fallback mechanism testing\n openrouter_models - OpenRouter models availability testing\n token_allocation_validation - Token allocation and limits validation\n testgen_validation - TestGen tool validation with specific test function\n refactor_validation - Refactor tool validation with codesmells\n debug_validation - Debug tool validation with actual bugs\n conversation_chain_validation - Conversation chain continuity validation\n\nQuick Test Mode (for time-limited testing):\n Use --quick to run the essential 6 tests that provide maximum coverage:\n - cross_tool_continuation (cross-tool conversation memory)\n - basic_conversation (basic chat functionality)\n - content_validation (content validation and deduplication)\n - model_thinking_config (flash/flashlite model testing)\n - o3_model_selection (o3 model selection testing)\n - per_tool_deduplication (file deduplication for individual tools)\n\nExamples:\n # Run all tests\n python communication_simulator_test.py\n\n # Run only basic conversation and content validation tests\n python communication_simulator_test.py --tests basic_conversation content_validation\n\n # Run a single test individually (with full standalone setup)\n python communication_simulator_test.py --individual content_validation\n\n # Run quick test mode (essential 6 tests for time-limited testing)\n python communication_simulator_test.py --quick\n\n # Force setup standalone server environment before running tests\n python communication_simulator_test.py --setup\n\n # List available tests\n python communication_simulator_test.py --list-tests\n\"\"\"\n\nimport argparse\nimport logging\nimport os\nimport shutil\nimport subprocess\nimport sys\nimport tempfile\n\n\nclass CommunicationSimulator:\n \"\"\"Simulates real-world Claude CLI communication with MCP Gemini server\"\"\"\n\n def __init__(\n self,\n verbose: bool = False,\n keep_logs: bool = False,\n selected_tests: list[str] = None,\n setup: bool = False,\n quick_mode: bool = False,\n ):\n self.verbose = verbose\n self.keep_logs = keep_logs\n self.selected_tests = selected_tests or []\n self.setup = setup\n self.quick_mode = quick_mode\n self.temp_dir = None\n self.server_process = None\n\n # Configure logging first\n log_level = logging.DEBUG if verbose else logging.INFO\n logging.basicConfig(level=log_level, format=\"%(asctime)s - %(levelname)s - %(message)s\")\n self.logger = logging.getLogger(__name__)\n\n self.python_path = self._get_python_path()\n\n # Import test registry\n from simulator_tests import TEST_REGISTRY\n\n self.test_registry = TEST_REGISTRY\n\n # Define quick mode tests (essential tests for time-limited testing)\n # Focus on tests that work with current tool configurations\n self.quick_mode_tests = [\n \"cross_tool_continuation\", # Cross-tool conversation memory\n \"basic_conversation\", # Basic chat functionality\n \"content_validation\", # Content validation and deduplication\n \"model_thinking_config\", # Flash/flashlite model testing\n \"o3_model_selection\", # O3 model selection testing\n \"per_tool_deduplication\", # File deduplication for individual tools\n ]\n\n # If quick mode is enabled, override selected_tests\n if self.quick_mode:\n self.selected_tests = self.quick_mode_tests\n self.logger.info(f\"Quick mode enabled - running {len(self.quick_mode_tests)} essential tests\")\n\n # Available test methods mapping\n self.available_tests = {\n name: self._create_test_runner(test_class) for name, test_class in self.test_registry.items()\n }\n\n # Test result tracking\n self.test_results = dict.fromkeys(self.test_registry.keys(), False)\n\n def _get_python_path(self) -> str:\n \"\"\"Get the Python path for the virtual environment\"\"\"\n current_dir = os.getcwd()\n\n # Try .venv first (modern convention)\n venv_python = os.path.join(current_dir, \".venv\", \"bin\", \"python\")\n if os.path.exists(venv_python):\n return venv_python\n\n # Try venv as fallback\n venv_python = os.path.join(current_dir, \"venv\", \"bin\", \"python\")\n if os.path.exists(venv_python):\n return venv_python\n\n # Try .pal_venv as fallback\n pal_venv_python = os.path.join(current_dir, \".pal_venv\", \"bin\", \"python\")\n if os.path.exists(pal_venv_python):\n return pal_venv_python\n\n # Fallback to system python if venv doesn't exist\n self.logger.warning(\"Virtual environment not found, using system python\")\n return \"python\"\n\n def _create_test_runner(self, test_class):\n \"\"\"Create a test runner function for a test class\"\"\"\n\n def run_test():\n test_instance = test_class(verbose=self.verbose)\n result = test_instance.run_test()\n # Update results\n test_name = test_instance.test_name\n self.test_results[test_name] = result\n return result\n\n return run_test\n\n def setup_test_environment(self) -> bool:\n \"\"\"Setup test environment\"\"\"\n try:\n self.logger.info(\"Setting up test environment...\")\n\n # Create temporary directory for test files\n self.temp_dir = tempfile.mkdtemp(prefix=\"mcp_test_\")\n self.logger.debug(f\"Created temp directory: {self.temp_dir}\")\n\n # Only run run-server.sh if setup is requested\n if self.setup:\n if not self._run_server_script():\n return False\n\n # Always verify server environment is available\n return self._verify_server_environment()\n\n except Exception as e:\n self.logger.error(f\"Failed to setup test environment: {e}\")\n return False\n\n def _run_server_script(self) -> bool:\n \"\"\"Run the run-server.sh script\"\"\"\n try:\n self.logger.info(\"Running run-server.sh...\")\n\n # Check if run-server.sh exists\n setup_script = \"./run-server.sh\"\n if not os.path.exists(setup_script):\n self.logger.error(f\"run-server.sh not found at {setup_script}\")\n return False\n\n # Make sure it's executable\n result = self._run_command([\"chmod\", \"+x\", setup_script], capture_output=True)\n if result.returncode != 0:\n self.logger.error(f\"Failed to make run-server.sh executable: {result.stderr}\")\n return False\n\n # Run the setup script\n result = self._run_command([setup_script], capture_output=True)\n if result.returncode != 0:\n self.logger.error(f\"run-server.sh failed: {result.stderr}\")\n return False\n\n self.logger.info(\"run-server.sh completed successfully\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Failed to run run-server.sh: {e}\")\n return False\n\n def _verify_server_environment(self) -> bool:\n \"\"\"Verify that server environment is ready\"\"\"\n try:\n self.logger.info(\"Verifying standalone server environment...\")\n\n # Check if server.py exists\n server_file = \"server.py\"\n if not os.path.exists(server_file):\n self.logger.error(f\"Server file not found: {server_file}\")\n self.logger.error(\"Please ensure you're in the correct directory and server.py exists\")\n return False\n\n # Check if virtual environment is available\n if not os.path.exists(self.python_path):\n self.logger.error(f\"Python executable not found: {self.python_path}\")\n self.logger.error(\"Please run ./run-server.sh first to set up the environment\")\n return False\n\n # Check if required dependencies are available\n try:\n result = self._run_command([self.python_path, \"-c\", \"import json; print('OK')\"], capture_output=True)\n if result.returncode != 0:\n self.logger.error(\"Python environment validation failed\")\n return False\n except Exception as e:\n self.logger.error(f\"Python environment check failed: {e}\")\n return False\n\n self.logger.info(\"Standalone server environment is ready\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Server environment verification failed: {e}\")\n self.logger.error(\"Please ensure the server environment is set up correctly, or use --setup\")\n return False\n\n def simulate_claude_cli_session(self) -> bool:\n \"\"\"Simulate a complete Claude CLI session with conversation continuity\"\"\"\n try:\n self.logger.info(\"Starting Claude CLI simulation...\")\n\n # If specific tests are selected, run only those\n if self.selected_tests:\n return self._run_selected_tests()\n\n # Otherwise run all tests in order\n test_sequence = list(self.test_registry.keys())\n\n for test_name in test_sequence:\n if not self._run_single_test(test_name):\n return False\n\n self.logger.info(\"All tests passed\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Claude CLI simulation failed: {e}\")\n return False\n\n def _run_selected_tests(self) -> bool:\n \"\"\"Run only the selected tests\"\"\"\n try:\n self.logger.info(f\"Running selected tests: {', '.join(self.selected_tests)}\")\n\n for test_name in self.selected_tests:\n if not self._run_single_test(test_name):\n return False\n\n self.logger.info(\"All selected tests passed\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Selected tests failed: {e}\")\n return False\n\n def _run_single_test(self, test_name: str) -> bool:\n \"\"\"Run a single test by name\"\"\"\n try:\n if test_name not in self.available_tests:\n self.logger.error(f\"Unknown test: {test_name}\")\n self.logger.info(f\"Available tests: {', '.join(self.available_tests.keys())}\")\n return False\n\n self.logger.info(f\"Running test: {test_name}\")\n test_function = self.available_tests[test_name]\n result = test_function()\n\n if result:\n self.logger.info(f\"Test {test_name} passed\")\n else:\n self.logger.error(f\"Test {test_name} failed\")\n\n return result\n\n except Exception as e:\n self.logger.error(f\"Test {test_name} failed with exception: {e}\")\n return False\n\n def run_individual_test(self, test_name: str) -> bool:\n \"\"\"Run a single test individually\"\"\"\n try:\n if test_name not in self.available_tests:\n self.logger.error(f\"Unknown test: {test_name}\")\n self.logger.info(f\"Available tests: {', '.join(self.available_tests.keys())}\")\n return False\n\n self.logger.info(f\"Running individual test: {test_name}\")\n\n # Setup environment\n if not self.setup_test_environment():\n self.logger.error(\"Environment setup failed\")\n return False\n\n # Run the single test\n test_function = self.available_tests[test_name]\n result = test_function()\n\n if result:\n self.logger.info(f\"Individual test {test_name} passed\")\n else:\n self.logger.error(f\"Individual test {test_name} failed\")\n\n return result\n\n except Exception as e:\n self.logger.error(f\"Individual test {test_name} failed with exception: {e}\")\n return False\n finally:\n if not self.keep_logs:\n self.cleanup()\n\n def get_available_tests(self) -> dict[str, str]:\n \"\"\"Get available tests with descriptions\"\"\"\n descriptions = {}\n for name, test_class in self.test_registry.items():\n # Create temporary instance to get description\n temp_instance = test_class(verbose=False)\n descriptions[name] = temp_instance.test_description\n return descriptions\n\n def print_test_summary(self):\n \"\"\"Print comprehensive test results summary\"\"\"\n self.logger.info(\"\\n\" + \"=\" * 70)\n self.logger.info(\"PAL MCP COMMUNICATION SIMULATOR - TEST RESULTS SUMMARY\")\n self.logger.info(\"=\" * 70)\n\n passed_count = sum(1 for result in self.test_results.values() if result)\n total_count = len(self.test_results)\n\n for test_name, result in self.test_results.items():\n status = \"PASS\" if result else \"FAIL\"\n # Get test description\n temp_instance = self.test_registry[test_name](verbose=False)\n description = temp_instance.test_description\n if result:\n self.logger.info(f\"{description}: {status}\")\n else:\n self.logger.error(f\"{description}: {status}\")\n\n if passed_count == total_count:\n self.logger.info(\"\\nOVERALL RESULT: SUCCESS\")\n else:\n self.logger.error(\"\\nOVERALL RESULT: FAILURE\")\n self.logger.info(f\"{passed_count}/{total_count} tests passed\")\n self.logger.info(\"=\" * 70)\n return passed_count == total_count\n\n def run_full_test_suite(self) -> bool:\n \"\"\"Run the complete test suite\"\"\"\n try:\n self.logger.info(\"Starting PAL MCP Communication Simulator Test Suite\")\n\n # Setup\n if not self.setup_test_environment():\n self.logger.error(\"Environment setup failed\")\n return False\n\n # Main simulation\n if not self.simulate_claude_cli_session():\n self.logger.error(\"Claude CLI simulation failed\")\n return False\n\n # Print comprehensive summary\n overall_success = self.print_test_summary()\n\n return overall_success\n\n except Exception as e:\n self.logger.error(f\"Test suite failed: {e}\")\n return False\n finally:\n if not self.keep_logs:\n self.cleanup()\n\n def cleanup(self):\n \"\"\"Cleanup test environment\"\"\"\n try:\n self.logger.info(\"Cleaning up test environment...\")\n\n # Stop any running server processes\n if self.server_process and self.server_process.poll() is None:\n self.logger.info(\"Stopping server process...\")\n self.server_process.terminate()\n try:\n self.server_process.wait(timeout=5)\n except subprocess.TimeoutExpired:\n self.server_process.kill()\n self.server_process.wait()\n\n if not self.keep_logs:\n self.logger.info(\"Test completed. Standalone server process stopped.\")\n else:\n self.logger.info(\"Keeping logs for inspection\")\n\n # Remove temp directory\n if self.temp_dir and os.path.exists(self.temp_dir):\n shutil.rmtree(self.temp_dir)\n self.logger.debug(f\"Removed temp directory: {self.temp_dir}\")\n\n except Exception as e:\n self.logger.error(f\"Cleanup failed: {e}\")\n\n def _run_command(self, cmd: list[str], check: bool = True, capture_output: bool = False, **kwargs):\n \"\"\"Run a shell command with logging\"\"\"\n if self.verbose:\n self.logger.debug(f\"Running: {' '.join(cmd)}\")\n\n return subprocess.run(cmd, check=check, capture_output=capture_output, **kwargs)\n\n\ndef parse_arguments():\n \"\"\"Parse and validate command line arguments\"\"\"\n parser = argparse.ArgumentParser(description=\"PAL MCP Communication Simulator Test\")\n parser.add_argument(\"--verbose\", \"-v\", action=\"store_true\", help=\"Enable verbose logging\")\n parser.add_argument(\"--keep-logs\", action=\"store_true\", help=\"Keep logs for inspection after test completion\")\n parser.add_argument(\"--tests\", \"-t\", nargs=\"+\", help=\"Specific tests to run (space-separated)\")\n parser.add_argument(\"--list-tests\", action=\"store_true\", help=\"List available tests and exit\")\n parser.add_argument(\"--individual\", \"-i\", help=\"Run a single test individually\")\n parser.add_argument(\n \"--quick\", \"-q\", action=\"store_true\", help=\"Run quick test mode (6 essential tests for time-limited testing)\"\n )\n parser.add_argument(\n \"--setup\", action=\"store_true\", help=\"Force setup standalone server environment using run-server.sh\"\n )\n\n return parser.parse_args()\n\n\ndef list_available_tests():\n \"\"\"List all available tests and exit\"\"\"\n simulator = CommunicationSimulator()\n # Create a simple logger for this function\n logger = logging.getLogger(\"list_tests\")\n logging.basicConfig(level=logging.INFO, format=\"%(message)s\")\n\n logger.info(\"Available tests:\")\n for test_name, description in simulator.get_available_tests().items():\n logger.info(f\" {test_name:<25} - {description}\")\n\n\ndef run_individual_test(simulator, test_name):\n \"\"\"Run a single test individually\"\"\"\n logger = simulator.logger\n try:\n success = simulator.run_individual_test(test_name)\n\n if success:\n logger.info(f\"\\nINDIVIDUAL TEST {test_name.upper()}: PASSED\")\n return 0\n else:\n logger.error(f\"\\nINDIVIDUAL TEST {test_name.upper()}: FAILED\")\n return 1\n\n except KeyboardInterrupt:\n logger.warning(f\"\\nIndividual test {test_name} interrupted by user\")\n simulator.cleanup()\n return 130\n except Exception as e:\n logger.error(f\"\\nIndividual test {test_name} failed with error: {e}\")\n simulator.cleanup()\n return 1\n\n\ndef run_test_suite(simulator):\n \"\"\"Run the full test suite or selected tests\"\"\"\n logger = simulator.logger\n try:\n success = simulator.run_full_test_suite()\n\n if success:\n logger.info(\"\\nCOMPREHENSIVE MCP COMMUNICATION TEST: PASSED\")\n return 0\n else:\n logger.error(\"\\nCOMPREHENSIVE MCP COMMUNICATION TEST: FAILED\")\n logger.error(\"Check detailed results above\")\n return 1\n\n except KeyboardInterrupt:\n logger.warning(\"\\nTest interrupted by user\")\n simulator.cleanup()\n return 130\n except Exception as e:\n logger.error(f\"\\nUnexpected error: {e}\")\n simulator.cleanup()\n return 1\n\n\ndef main():\n \"\"\"Main entry point\"\"\"\n args = parse_arguments()\n\n # Handle list tests request\n if args.list_tests:\n list_available_tests()\n return\n\n # Initialize simulator consistently for all use cases\n simulator = CommunicationSimulator(\n verbose=args.verbose,\n keep_logs=args.keep_logs,\n selected_tests=args.tests,\n setup=args.setup,\n quick_mode=args.quick,\n )\n\n # Determine execution mode and run\n if args.individual:\n exit_code = run_individual_test(simulator, args.individual)\n else:\n exit_code = run_test_suite(simulator)\n\n sys.exit(exit_code)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "conf/__init__.py", "content": "\"\"\"Configuration data for PAL MCP Server.\"\"\"\n" }, { "path": "conf/azure_models.json", "content": "{\n \"_README\": {\n \"description\": \"Model metadata for Azure OpenAI / Azure AI Foundry-backed provider. The `models` definition can be copied from openrouter_models.json / custom_models.json\",\n \"documentation\": \"https://github.com/BeehiveInnovations/pal-mcp-server/blob/main/docs/azure_models.md\",\n \"usage\": \"Models listed here are exposed through Azure AI Foundry. Aliases are case-insensitive.\",\n \"field_notes\": \"Matches providers/shared/model_capabilities.py.\",\n \"field_descriptions\": {\n \"model_name\": \"The model identifier e.g., 'gpt-4'\",\n \"deployment\": \"Azure model deployment name\",\n \"aliases\": \"Array of short names users can type instead of the full model name\",\n \"context_window\": \"Total number of tokens the model can process (input + output combined)\",\n \"max_output_tokens\": \"Maximum number of tokens the model can generate in a single response\",\n \"supports_extended_thinking\": \"Whether the model supports extended reasoning tokens (currently none do via OpenRouter or custom APIs)\",\n \"supports_json_mode\": \"Whether the model can guarantee valid JSON output\",\n \"supports_function_calling\": \"Whether the model supports function/tool calling\",\n \"supports_images\": \"Whether the model can process images/visual input\",\n \"max_image_size_mb\": \"Maximum total size in MB for all images combined (capped at 40MB max for custom models)\",\n \"supports_temperature\": \"Whether the model accepts temperature parameter in API calls (set to false for O3/O4 reasoning models)\",\n \"temperature_constraint\": \"Type of temperature constraint: 'fixed' (fixed value), 'range' (continuous range), 'discrete' (specific values), or omit for default range\",\n \"use_openai_response_api\": \"Set to true when the deployment must call Azure's /responses endpoint (O-series reasoning models). Leave false/omit for standard chat completions.\",\n \"default_reasoning_effort\": \"Default reasoning effort level for models that support it (e.g., 'low', 'medium', 'high'). Omit if not applicable.\",\n \"description\": \"Human-readable description of the model\",\n \"intelligence_score\": \"1-20 human rating used as the primary signal for auto-mode model ordering\"\n }\n },\n \"_example_models\": [\n {\n \"model_name\": \"gpt-4\",\n \"deployment\": \"gpt-4\",\n \"aliases\": [\n \"gpt4\"\n ],\n \"context_window\": 128000,\n \"max_output_tokens\": 16384,\n \"supports_extended_thinking\": false,\n \"supports_json_mode\": true,\n \"supports_function_calling\": false,\n \"supports_images\": false,\n \"max_image_size_mb\": 0.0,\n \"supports_temperature\": false,\n \"temperature_constraint\": \"fixed\",\n \"use_openai_response_api\": false,\n \"description\": \"GPT-4 (128K context, 16K output)\",\n \"intelligence_score\": 10\n }\n ],\n \"models\": []\n}\n" }, { "path": "conf/cli_clients/claude.json", "content": "{\n \"name\": \"claude\",\n \"command\": \"claude\",\n \"additional_args\": [\n \"--permission-mode\",\n \"acceptEdits\",\n \"--model\",\n \"sonnet\"\n ],\n \"env\": {},\n \"roles\": {\n \"default\": {\n \"prompt_path\": \"systemprompts/clink/default.txt\",\n \"role_args\": []\n },\n \"planner\": {\n \"prompt_path\": \"systemprompts/clink/default_planner.txt\",\n \"role_args\": []\n },\n \"codereviewer\": {\n \"prompt_path\": \"systemprompts/clink/default_codereviewer.txt\",\n \"role_args\": []\n }\n }\n}\n" }, { "path": "conf/cli_clients/codex.json", "content": "{\n \"name\": \"codex\",\n \"command\": \"codex\",\n \"additional_args\": [\n \"--json\",\n \"--dangerously-bypass-approvals-and-sandbox\",\n \"--enable\",\n \"web_search_request\"\n ],\n \"env\": {},\n \"roles\": {\n \"default\": {\n \"prompt_path\": \"systemprompts/clink/default.txt\",\n \"role_args\": []\n },\n \"planner\": {\n \"prompt_path\": \"systemprompts/clink/default_planner.txt\",\n \"role_args\": []\n },\n \"codereviewer\": {\n \"prompt_path\": \"systemprompts/clink/codex_codereviewer.txt\",\n \"role_args\": []\n }\n }\n}\n" }, { "path": "conf/cli_clients/gemini.json", "content": "{\n \"name\": \"gemini\",\n \"command\": \"gemini\",\n \"additional_args\": [\n \"--yolo\"\n ],\n \"env\": {},\n \"roles\": {\n \"default\": {\n \"prompt_path\": \"systemprompts/clink/default.txt\",\n \"role_args\": []\n },\n \"planner\": {\n \"prompt_path\": \"systemprompts/clink/default_planner.txt\",\n \"role_args\": []\n },\n \"codereviewer\": {\n \"prompt_path\": \"systemprompts/clink/default_codereviewer.txt\",\n \"role_args\": []\n }\n }\n}\n" }, { "path": "conf/custom_models.json", "content": "{\n \"_README\": {\n \"description\": \"Model metadata for local/self-hosted OpenAI-compatible endpoints (Custom provider).\",\n \"documentation\": \"https://github.com/BeehiveInnovations/pal-mcp-server/blob/main/docs/custom_models.md\",\n \"usage\": \"Each entry will be advertised by the Custom provider. Aliases are case-insensitive.\",\n \"field_notes\": \"Matches providers/shared/model_capabilities.py.\",\n \"field_descriptions\": {\n \"model_name\": \"The model identifier e.g., 'llama3.2'\",\n \"aliases\": \"Array of short names users can type instead of the full model name\",\n \"context_window\": \"Total number of tokens the model can process (input + output combined)\",\n \"max_output_tokens\": \"Maximum number of tokens the model can generate in a single response\",\n \"supports_extended_thinking\": \"Whether the model supports extended reasoning tokens\",\n \"supports_json_mode\": \"Whether the model can guarantee valid JSON output\",\n \"supports_function_calling\": \"Whether the model supports function/tool calling\",\n \"supports_images\": \"Whether the model can process images/visual input\",\n \"max_image_size_mb\": \"Maximum total size in MB for all images combined (capped at 40MB max for custom models)\",\n \"supports_temperature\": \"Whether the model accepts temperature parameter in API calls (set to false for O3/O4 reasoning models)\",\n \"temperature_constraint\": \"Type of temperature constraint: 'fixed' (fixed value), 'range' (continuous range), 'discrete' (specific values), or omit for default range\",\n \"description\": \"Human-readable description of the model\",\n \"intelligence_score\": \"1-20 human rating used as the primary signal for auto-mode model ordering\"\n }\n },\n \"models\": [\n {\n \"model_name\": \"llama3.2\",\n \"aliases\": [\n \"local-llama\",\n \"ollama-llama\"\n ],\n \"context_window\": 128000,\n \"max_output_tokens\": 64000,\n \"supports_extended_thinking\": false,\n \"supports_json_mode\": false,\n \"supports_function_calling\": false,\n \"supports_images\": false,\n \"max_image_size_mb\": 0.0,\n \"description\": \"Local Llama 3.2 model via custom endpoint (Ollama/vLLM) - 128K context window (text-only)\",\n \"intelligence_score\": 6\n }\n ]\n}\n" }, { "path": "conf/dial_models.json", "content": "{\n \"_README\": {\n \"description\": \"Model metadata for the DIAL (Data & AI Layer) aggregation provider.\",\n \"documentation\": \"https://github.com/BeehiveInnovations/pal-mcp-server/blob/main/docs/configuration.md\",\n \"usage\": \"Models listed here are exposed through the DIAL provider. Aliases are case-insensitive.\",\n \"field_notes\": \"Matches providers/shared/model_capabilities.py.\",\n \"field_descriptions\": {\n \"model_name\": \"The model identifier as exposed by DIAL (typically deployment name)\",\n \"aliases\": \"Array of shorthand names users can type instead of the full model name\",\n \"context_window\": \"Total number of tokens the model can process (input + output combined)\",\n \"max_output_tokens\": \"Maximum number of tokens the model can generate in a single response\",\n \"supports_extended_thinking\": \"Whether the model supports extended reasoning tokens\",\n \"supports_json_mode\": \"Whether the model can guarantee valid JSON output\",\n \"supports_function_calling\": \"Whether the model supports function/tool calling\",\n \"supports_images\": \"Whether the model can process images/visual input\",\n \"max_image_size_mb\": \"Maximum total size in MB for all images combined\",\n \"supports_temperature\": \"Whether the model accepts the temperature parameter\",\n \"temperature_constraint\": \"Temperature constraint hint: 'fixed', 'range', or 'discrete'\",\n \"description\": \"Human-readable description of the model\",\n \"intelligence_score\": \"1-20 human rating used as the primary signal for auto-mode ordering\"\n }\n },\n \"models\": [\n {\n \"model_name\": \"o3-2025-04-16\",\n \"friendly_name\": \"DIAL (O3)\",\n \"aliases\": [\"o3\"],\n \"intelligence_score\": 14,\n \"description\": \"OpenAI O3 via DIAL - Strong reasoning model\",\n \"context_window\": 200000,\n \"max_output_tokens\": 100000,\n \"supports_extended_thinking\": false,\n \"supports_function_calling\": false,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 20.0,\n \"supports_temperature\": false,\n \"temperature_constraint\": \"fixed\"\n },\n {\n \"model_name\": \"o4-mini-2025-04-16\",\n \"friendly_name\": \"DIAL (O4-mini)\",\n \"aliases\": [\"o4-mini\"],\n \"intelligence_score\": 11,\n \"description\": \"OpenAI O4-mini via DIAL - Fast reasoning model\",\n \"context_window\": 200000,\n \"max_output_tokens\": 100000,\n \"supports_extended_thinking\": false,\n \"supports_function_calling\": false,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 20.0,\n \"supports_temperature\": false,\n \"temperature_constraint\": \"fixed\"\n },\n {\n \"model_name\": \"anthropic.claude-sonnet-4.1-20250805-v1:0\",\n \"friendly_name\": \"DIAL (Sonnet 4.1)\",\n \"aliases\": [\"sonnet-4.1\", \"sonnet-4\"],\n \"intelligence_score\": 10,\n \"description\": \"Claude Sonnet 4.1 via DIAL - Balanced performance\",\n \"context_window\": 200000,\n \"max_output_tokens\": 64000,\n \"supports_extended_thinking\": false,\n \"supports_function_calling\": false,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 5.0,\n \"supports_temperature\": true,\n \"temperature_constraint\": \"range\"\n },\n {\n \"model_name\": \"anthropic.claude-sonnet-4.1-20250805-v1:0-with-thinking\",\n \"friendly_name\": \"DIAL (Sonnet 4.1 Thinking)\",\n \"aliases\": [\"sonnet-4.1-thinking\", \"sonnet-4-thinking\"],\n \"intelligence_score\": 11,\n \"description\": \"Claude Sonnet 4.1 with thinking mode via DIAL\",\n \"context_window\": 200000,\n \"max_output_tokens\": 64000,\n \"supports_extended_thinking\": true,\n \"supports_function_calling\": false,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 5.0,\n \"supports_temperature\": true,\n \"temperature_constraint\": \"range\"\n },\n {\n \"model_name\": \"anthropic.claude-opus-4.1-20250805-v1:0\",\n \"friendly_name\": \"DIAL (Opus 4.1)\",\n \"aliases\": [\"opus-4.1\", \"opus-4\"],\n \"intelligence_score\": 14,\n \"description\": \"Claude Opus 4.1 via DIAL - Most capable Claude model\",\n \"context_window\": 200000,\n \"max_output_tokens\": 64000,\n \"supports_extended_thinking\": false,\n \"supports_function_calling\": false,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 5.0,\n \"supports_temperature\": true,\n \"temperature_constraint\": \"range\"\n },\n {\n \"model_name\": \"anthropic.claude-opus-4.1-20250805-v1:0-with-thinking\",\n \"friendly_name\": \"DIAL (Opus 4.1 Thinking)\",\n \"aliases\": [\"opus-4.1-thinking\", \"opus-4-thinking\"],\n \"intelligence_score\": 15,\n \"description\": \"Claude Opus 4.1 with thinking mode via DIAL\",\n \"context_window\": 200000,\n \"max_output_tokens\": 64000,\n \"supports_extended_thinking\": true,\n \"supports_function_calling\": false,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 5.0,\n \"supports_temperature\": true,\n \"temperature_constraint\": \"range\"\n },\n {\n \"model_name\": \"gemini-2.5-pro-preview-03-25-google-search\",\n \"friendly_name\": \"DIAL (Gemini 2.5 Pro Search)\",\n \"aliases\": [\"gemini-2.5-pro-search\"],\n \"intelligence_score\": 17,\n \"description\": \"Gemini 2.5 Pro with Google Search via DIAL\",\n \"context_window\": 1000000,\n \"max_output_tokens\": 65536,\n \"supports_extended_thinking\": false,\n \"supports_function_calling\": false,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 20.0,\n \"supports_temperature\": true,\n \"temperature_constraint\": \"range\"\n },\n {\n \"model_name\": \"gemini-2.5-pro-preview-05-06\",\n \"friendly_name\": \"DIAL (Gemini 2.5 Pro)\",\n \"aliases\": [\"gemini-2.5-pro\"],\n \"intelligence_score\": 18,\n \"description\": \"Gemini 2.5 Pro via DIAL - Deep reasoning\",\n \"context_window\": 1000000,\n \"max_output_tokens\": 65536,\n \"supports_extended_thinking\": false,\n \"supports_function_calling\": false,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 20.0,\n \"supports_temperature\": true,\n \"temperature_constraint\": \"range\"\n },\n {\n \"model_name\": \"gemini-2.5-flash-preview-05-20\",\n \"friendly_name\": \"DIAL (Gemini Flash 2.5)\",\n \"aliases\": [\"gemini-2.5-flash\"],\n \"intelligence_score\": 10,\n \"description\": \"Gemini 2.5 Flash via DIAL - Ultra-fast\",\n \"context_window\": 1000000,\n \"max_output_tokens\": 65536,\n \"supports_extended_thinking\": false,\n \"supports_function_calling\": false,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 20.0,\n \"supports_temperature\": true,\n \"temperature_constraint\": \"range\"\n }\n ]\n}\n" }, { "path": "conf/gemini_models.json", "content": "{\n \"_README\": {\n \"description\": \"Model metadata for Google's Gemini API access.\",\n \"documentation\": \"https://github.com/BeehiveInnovations/pal-mcp-server/blob/main/docs/custom_models.md\",\n \"usage\": \"Models listed here are exposed directly through the Gemini provider. Aliases are case-insensitive.\",\n \"field_notes\": \"Matches providers/shared/model_capabilities.py.\",\n \"field_descriptions\": {\n \"model_name\": \"The model identifier (e.g., 'gemini-2.5-pro', 'gemini-2.0-flash')\",\n \"aliases\": \"Array of short names users can type instead of the full model name\",\n \"context_window\": \"Total number of tokens the model can process (input + output combined)\",\n \"max_output_tokens\": \"Maximum number of tokens the model can generate in a single response\",\n \"max_thinking_tokens\": \"Maximum reasoning/thinking tokens the model will allocate when extended thinking is requested\",\n \"supports_extended_thinking\": \"Whether the model supports extended reasoning tokens (currently none do via OpenRouter or custom APIs)\",\n \"supports_json_mode\": \"Whether the model can guarantee valid JSON output\",\n \"supports_function_calling\": \"Whether the model supports function/tool calling\",\n \"supports_images\": \"Whether the model can process images/visual input\",\n \"max_image_size_mb\": \"Maximum total size in MB for all images combined (capped at 40MB max for custom models)\",\n \"supports_temperature\": \"Whether the model accepts temperature parameter in API calls (set to false for O3/O4 reasoning models)\",\n \"temperature_constraint\": \"Type of temperature constraint: 'fixed' (fixed value), 'range' (continuous range), 'discrete' (specific values), or omit for default range\",\n \"use_openai_response_api\": \"Set to true when the model must use the /responses endpoint (reasoning models like GPT-5.2 Pro). Leave false/omit for standard chat completions.\",\n \"default_reasoning_effort\": \"Default reasoning effort level for models that support it (e.g., 'low', 'medium', 'high'). Omit if not applicable.\",\n \"description\": \"Human-readable description of the model\",\n \"intelligence_score\": \"1-20 human rating used as the primary signal for auto-mode model ordering\",\n \"allow_code_generation\": \"Whether this model can generate and suggest fully working code - complete with functions, files, and detailed implementation instructions - for your AI tool to use right away. Only set this to 'true' for a model more capable than the AI model / CLI you're currently using.\"\n }\n },\n \"models\": [\n {\n \"model_name\": \"gemini-3-pro-preview\",\n \"friendly_name\": \"Gemini Pro 3.0 Preview\",\n \"aliases\": [\n \"pro\",\n \"gemini3\",\n \"gemini-pro\"\n ],\n \"intelligence_score\": 18,\n \"description\": \"Deep reasoning + thinking mode (1M context) - Complex problems, architecture, deep analysis\",\n \"context_window\": 1048576,\n \"max_output_tokens\": 65536,\n \"max_thinking_tokens\": 32768,\n \"supports_extended_thinking\": true,\n \"supports_system_prompts\": true,\n \"supports_streaming\": true,\n \"supports_function_calling\": true,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"supports_temperature\": true,\n \"allow_code_generation\": true,\n \"max_image_size_mb\": 32.0\n },\n {\n \"model_name\": \"gemini-2.5-pro\",\n \"friendly_name\": \"Gemini Pro 2.5\",\n \"aliases\": [\n \"gemini-pro-2.5\"\n ],\n \"intelligence_score\": 18,\n \"description\": \"Older Model. 1M context - Complex problems, architecture, deep analysis\",\n \"context_window\": 1048576,\n \"max_output_tokens\": 65536,\n \"max_thinking_tokens\": 32768,\n \"supports_extended_thinking\": true,\n \"supports_system_prompts\": true,\n \"supports_streaming\": true,\n \"supports_function_calling\": true,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"supports_temperature\": true,\n \"allow_code_generation\": true,\n \"max_image_size_mb\": 32.0\n },\n {\n \"model_name\": \"gemini-2.0-flash\",\n \"friendly_name\": \"Gemini (Flash 2.0)\",\n \"aliases\": [\n \"flash-2.0\",\n \"flash2\"\n ],\n \"intelligence_score\": 9,\n \"description\": \"Gemini 2.0 Flash (1M context) - Latest fast model with experimental thinking, supports audio/video input\",\n \"context_window\": 1048576,\n \"max_output_tokens\": 65536,\n \"max_thinking_tokens\": 24576,\n \"supports_extended_thinking\": true,\n \"supports_system_prompts\": true,\n \"supports_streaming\": true,\n \"supports_function_calling\": true,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"supports_temperature\": true,\n \"max_image_size_mb\": 20.0\n },\n {\n \"model_name\": \"gemini-2.0-flash-lite\",\n \"friendly_name\": \"Gemini (Flash Lite 2.0)\",\n \"aliases\": [\n \"flashlite\",\n \"flash-lite\"\n ],\n \"intelligence_score\": 7,\n \"description\": \"Gemini 2.0 Flash Lite (1M context) - Lightweight fast model, text-only\",\n \"context_window\": 1048576,\n \"max_output_tokens\": 65536,\n \"supports_extended_thinking\": false,\n \"supports_system_prompts\": true,\n \"supports_streaming\": true,\n \"supports_function_calling\": true,\n \"supports_json_mode\": true,\n \"supports_images\": false,\n \"supports_temperature\": true\n },\n {\n \"model_name\": \"gemini-2.5-flash\",\n \"friendly_name\": \"Gemini (Flash 2.5)\",\n \"aliases\": [\n \"flash\",\n \"flash2.5\"\n ],\n \"intelligence_score\": 10,\n \"description\": \"Ultra-fast (1M context) - Quick analysis, simple queries, rapid iterations\",\n \"context_window\": 1048576,\n \"max_output_tokens\": 65536,\n \"max_thinking_tokens\": 24576,\n \"supports_extended_thinking\": true,\n \"supports_system_prompts\": true,\n \"supports_streaming\": true,\n \"supports_function_calling\": true,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"supports_temperature\": true,\n \"max_image_size_mb\": 20.0\n }\n ]\n}\n" }, { "path": "conf/openai_models.json", "content": "{\n \"_README\": {\n \"description\": \"Model metadata for native OpenAI API access.\",\n \"documentation\": \"https://github.com/BeehiveInnovations/pal-mcp-server/blob/main/docs/custom_models.md\",\n \"usage\": \"Models listed here are exposed directly through the OpenAI provider. Aliases are case-insensitive.\",\n \"field_notes\": \"Matches providers/shared/model_capabilities.py.\",\n \"field_descriptions\": {\n \"model_name\": \"The model identifier (e.g., 'gpt-5', 'o3-pro')\",\n \"aliases\": \"Array of short names users can type instead of the full model name\",\n \"context_window\": \"Total number of tokens the model can process (input + output combined)\",\n \"max_output_tokens\": \"Maximum number of tokens the model can generate in a single response\",\n \"max_thinking_tokens\": \"Maximum reasoning/thinking tokens the model will allocate when extended thinking is requested\",\n \"supports_extended_thinking\": \"Whether the model supports extended reasoning tokens (currently none do via OpenRouter or custom APIs)\",\n \"supports_json_mode\": \"Whether the model can guarantee valid JSON output\",\n \"supports_function_calling\": \"Whether the model supports function/tool calling\",\n \"supports_images\": \"Whether the model can process images/visual input\",\n \"max_image_size_mb\": \"Maximum total size in MB for all images combined (capped at 40MB max for custom models)\",\n \"supports_temperature\": \"Whether the model accepts temperature parameter in API calls (set to false for O3/O4 reasoning models)\",\n \"temperature_constraint\": \"Type of temperature constraint: 'fixed' (fixed value), 'range' (continuous range), 'discrete' (specific values), or omit for default range\",\n \"use_openai_response_api\": \"Set to true when the model must use the /responses endpoint (reasoning models like GPT-5.2 Pro). Leave false/omit for standard chat completions.\",\n \"default_reasoning_effort\": \"Default reasoning effort level for models that support it (e.g., 'low', 'medium', 'high'). Omit if not applicable.\",\n \"description\": \"Human-readable description of the model\",\n \"intelligence_score\": \"1-20 human rating used as the primary signal for auto-mode model ordering\",\n \"allow_code_generation\": \"Whether this model can generate and suggest fully working code - complete with functions, files, and detailed implementation instructions - for your AI tool to use right away. Only set this to 'true' for a model more capable than the AI model / CLI you're currently using.\"\n }\n },\n \"models\": [\n {\n \"model_name\": \"gpt-5\",\n \"friendly_name\": \"OpenAI (GPT-5)\",\n \"aliases\": [\n \"gpt5\",\n \"gpt-5\"\n ],\n \"intelligence_score\": 16,\n \"description\": \"GPT-5 (400K context, 128K output) - Advanced model with reasoning support\",\n \"context_window\": 400000,\n \"max_output_tokens\": 128000,\n \"supports_extended_thinking\": true,\n \"supports_system_prompts\": true,\n \"supports_streaming\": false,\n \"supports_function_calling\": true,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"supports_temperature\": true,\n \"max_image_size_mb\": 20.0,\n \"temperature_constraint\": \"fixed\"\n },\n {\n \"model_name\": \"gpt-5.2-pro\",\n \"friendly_name\": \"OpenAI (GPT-5.2 Pro)\",\n \"aliases\": [\n \"gpt5.2-pro\",\n \"gpt5.2pro\",\n \"gpt5pro\",\n \"gpt5-pro\"\n ],\n \"intelligence_score\": 18,\n \"description\": \"GPT-5.2 Pro (400K context, 272K output) - Very advanced, reasoning model\",\n \"context_window\": 400000,\n \"max_output_tokens\": 272000,\n \"supports_extended_thinking\": true,\n \"supports_system_prompts\": true,\n \"supports_streaming\": false,\n \"supports_function_calling\": true,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"supports_temperature\": true,\n \"max_image_size_mb\": 20.0,\n \"use_openai_response_api\": true,\n \"default_reasoning_effort\": \"high\",\n \"allow_code_generation\": true,\n \"temperature_constraint\": \"fixed\"\n },\n {\n \"model_name\": \"gpt-5-mini\",\n \"friendly_name\": \"OpenAI (GPT-5-mini)\",\n \"aliases\": [\n \"gpt5-mini\",\n \"gpt5mini\",\n \"mini\"\n ],\n \"intelligence_score\": 15,\n \"description\": \"GPT-5-mini (400K context, 128K output) - Efficient variant with reasoning support\",\n \"context_window\": 400000,\n \"max_output_tokens\": 128000,\n \"supports_extended_thinking\": true,\n \"supports_system_prompts\": true,\n \"supports_streaming\": false,\n \"supports_function_calling\": true,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"supports_temperature\": true,\n \"max_image_size_mb\": 20.0,\n \"temperature_constraint\": \"fixed\"\n },\n {\n \"model_name\": \"gpt-5-nano\",\n \"friendly_name\": \"OpenAI (GPT-5 nano)\",\n \"aliases\": [\n \"gpt5nano\",\n \"gpt5-nano\",\n \"nano\"\n ],\n \"intelligence_score\": 13,\n \"description\": \"GPT-5 nano (400K context) - Fastest, cheapest version of GPT-5 for summarization and classification tasks\",\n \"context_window\": 400000,\n \"max_output_tokens\": 128000,\n \"supports_extended_thinking\": true,\n \"supports_system_prompts\": true,\n \"supports_streaming\": true,\n \"supports_function_calling\": true,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"supports_temperature\": true,\n \"max_image_size_mb\": 20.0,\n \"temperature_constraint\": \"fixed\"\n },\n {\n \"model_name\": \"o3\",\n \"friendly_name\": \"OpenAI (O3)\",\n \"intelligence_score\": 14,\n \"description\": \"Strong reasoning (200K context) - Logical problems, code generation, systematic analysis\",\n \"context_window\": 200000,\n \"max_output_tokens\": 65536,\n \"supports_extended_thinking\": false,\n \"supports_system_prompts\": true,\n \"supports_streaming\": true,\n \"supports_function_calling\": true,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"supports_temperature\": false,\n \"max_image_size_mb\": 20.0,\n \"temperature_constraint\": \"fixed\"\n },\n {\n \"model_name\": \"o3-mini\",\n \"friendly_name\": \"OpenAI (O3-mini)\",\n \"aliases\": [\n \"o3mini\"\n ],\n \"intelligence_score\": 12,\n \"description\": \"Fast O3 variant (200K context) - Balanced performance/speed, moderate complexity\",\n \"context_window\": 200000,\n \"max_output_tokens\": 65536,\n \"supports_extended_thinking\": false,\n \"supports_system_prompts\": true,\n \"supports_streaming\": true,\n \"supports_function_calling\": true,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"supports_temperature\": false,\n \"max_image_size_mb\": 20.0,\n \"temperature_constraint\": \"fixed\"\n },\n {\n \"model_name\": \"o3-pro\",\n \"friendly_name\": \"OpenAI (O3-Pro)\",\n \"aliases\": [\n \"o3pro\"\n ],\n \"intelligence_score\": 15,\n \"description\": \"Professional-grade reasoning with advanced capabilities (200K context)\",\n \"context_window\": 200000,\n \"max_output_tokens\": 65536,\n \"supports_extended_thinking\": false,\n \"supports_system_prompts\": true,\n \"supports_streaming\": true,\n \"supports_function_calling\": true,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"supports_temperature\": false,\n \"max_image_size_mb\": 20.0,\n \"use_openai_response_api\": true,\n \"temperature_constraint\": \"fixed\"\n },\n {\n \"model_name\": \"o4-mini\",\n \"friendly_name\": \"OpenAI (O4-mini)\",\n \"aliases\": [\n \"o4mini\"\n ],\n \"intelligence_score\": 11,\n \"description\": \"Latest reasoning model (200K context) - Optimized for shorter contexts, rapid reasoning\",\n \"context_window\": 200000,\n \"supports_extended_thinking\": false,\n \"supports_system_prompts\": true,\n \"supports_streaming\": true,\n \"supports_function_calling\": true,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"supports_temperature\": false,\n \"max_image_size_mb\": 20.0,\n \"temperature_constraint\": \"fixed\"\n },\n {\n \"model_name\": \"gpt-4.1\",\n \"friendly_name\": \"OpenAI (GPT 4.1)\",\n \"aliases\": [\n \"gpt4.1\"\n ],\n \"intelligence_score\": 13,\n \"description\": \"GPT-4.1 (1M context) - Advanced reasoning model with large context window\",\n \"context_window\": 1000000,\n \"max_output_tokens\": 32768,\n \"supports_extended_thinking\": false,\n \"supports_system_prompts\": true,\n \"supports_streaming\": true,\n \"supports_function_calling\": true,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"supports_temperature\": true,\n \"max_image_size_mb\": 20.0\n },\n {\n \"model_name\": \"gpt-5-codex\",\n \"friendly_name\": \"OpenAI (GPT-5 Codex)\",\n \"aliases\": [\n \"gpt5-codex\",\n \"codex\",\n \"gpt-5-code\",\n \"gpt5-code\"\n ],\n \"intelligence_score\": 17,\n \"description\": \"GPT-5 Codex (400K context) Specialized for coding, refactoring, and software architecture.\",\n \"context_window\": 400000,\n \"max_output_tokens\": 128000,\n \"supports_extended_thinking\": true,\n \"supports_system_prompts\": true,\n \"supports_streaming\": true,\n \"supports_function_calling\": true,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"supports_temperature\": true,\n \"max_image_size_mb\": 20.0,\n \"use_openai_response_api\": true\n },\n {\n \"model_name\": \"gpt-5.2\",\n \"friendly_name\": \"OpenAI (GPT-5.2)\",\n \"aliases\": [\n \"gpt5.2\",\n \"gpt-5.2\",\n \"5.2\",\n \"gpt5.1\",\n \"gpt-5.1\",\n \"5.1\"\n ],\n \"intelligence_score\": 18,\n \"description\": \"GPT-5.2 (400K context, 128K output) - Flagship reasoning model with configurable thinking effort and vision support.\",\n \"context_window\": 400000,\n \"max_output_tokens\": 128000,\n \"supports_extended_thinking\": true,\n \"supports_system_prompts\": true,\n \"supports_streaming\": true,\n \"supports_function_calling\": true,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"supports_temperature\": true,\n \"max_image_size_mb\": 20.0,\n \"default_reasoning_effort\": \"medium\",\n \"allow_code_generation\": true,\n \"temperature_constraint\": \"fixed\"\n },\n {\n \"model_name\": \"gpt-5.1-codex\",\n \"friendly_name\": \"OpenAI (GPT-5.1 Codex)\",\n \"aliases\": [\n \"gpt5.1-codex\",\n \"gpt-5.1-codex\",\n \"gpt5.1code\",\n \"gpt-5.1-code\",\n \"codex-5.1\"\n ],\n \"intelligence_score\": 19,\n \"description\": \"GPT-5.1 Codex (400K context, 128K output) - Agentic coding specialization available through the Responses API.\",\n \"context_window\": 400000,\n \"max_output_tokens\": 128000,\n \"supports_extended_thinking\": true,\n \"supports_system_prompts\": true,\n \"supports_streaming\": false,\n \"supports_function_calling\": true,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"supports_temperature\": true,\n \"max_image_size_mb\": 20.0,\n \"use_openai_response_api\": true,\n \"default_reasoning_effort\": \"high\",\n \"allow_code_generation\": true,\n \"temperature_constraint\": \"fixed\"\n },\n {\n \"model_name\": \"gpt-5.1-codex-mini\",\n \"friendly_name\": \"OpenAI (GPT-5.1 Codex mini)\",\n \"aliases\": [\n \"gpt5.1-codex-mini\",\n \"gpt-5.1-codex-mini\",\n \"codex-mini\",\n \"5.1-codex-mini\"\n ],\n \"intelligence_score\": 16,\n \"description\": \"GPT-5.1 Codex mini (400K context, 128K output) - Cost-efficient Codex variant with streaming support.\",\n \"context_window\": 400000,\n \"max_output_tokens\": 128000,\n \"supports_extended_thinking\": true,\n \"supports_system_prompts\": true,\n \"supports_streaming\": true,\n \"supports_function_calling\": true,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"supports_temperature\": true,\n \"max_image_size_mb\": 20.0,\n \"allow_code_generation\": true,\n \"temperature_constraint\": \"fixed\"\n }\n ]\n}\n" }, { "path": "conf/openrouter_models.json", "content": "{\n \"_README\": {\n \"description\": \"Model metadata for OpenRouter-backed providers.\",\n \"documentation\": \"https://github.com/BeehiveInnovations/pal-mcp-server/blob/main/docs/custom_models.md\",\n \"usage\": \"Models listed here are exposed through OpenRouter. Aliases are case-insensitive.\",\n \"field_notes\": \"Matches providers/shared/model_capabilities.py.\",\n \"field_descriptions\": {\n \"model_name\": \"The model identifier - OpenRouter format (e.g., 'anthropic/claude-opus-4') or custom model name (e.g., 'llama3.2')\",\n \"aliases\": \"Array of short names users can type instead of the full model name\",\n \"context_window\": \"Total number of tokens the model can process (input + output combined)\",\n \"max_output_tokens\": \"Maximum number of tokens the model can generate in a single response\",\n \"supports_extended_thinking\": \"Whether the model supports extended reasoning tokens (currently none do via OpenRouter or custom APIs)\",\n \"supports_json_mode\": \"Whether the model can guarantee valid JSON output\",\n \"supports_function_calling\": \"Whether the model supports function/tool calling\",\n \"supports_images\": \"Whether the model can process images/visual input\",\n \"max_image_size_mb\": \"Maximum total size in MB for all images combined (capped at 40MB max for custom models)\",\n \"supports_temperature\": \"Whether the model accepts temperature parameter in API calls (set to false for O3/O4 reasoning models)\",\n \"temperature_constraint\": \"Type of temperature constraint: 'fixed' (fixed value), 'range' (continuous range), 'discrete' (specific values), or omit for default range\",\n \"use_openai_response_api\": \"Set to true when the model must use the /responses endpoint (reasoning models like GPT-5.2 Pro). Leave false/omit for standard chat completions.\",\n \"default_reasoning_effort\": \"Default reasoning effort level for models that support it (e.g., 'low', 'medium', 'high'). Omit if not applicable.\",\n \"description\": \"Human-readable description of the model\",\n \"intelligence_score\": \"1-20 human rating used as the primary signal for auto-mode model ordering\",\n \"allow_code_generation\": \"Whether this model can generate and suggest fully working code - complete with functions, files, and detailed implementation instructions - for your AI tool to use right away. Only set this to 'true' for a model more capable than the AI model / CLI you're currently using.\"\n }\n },\n \"models\": [\n {\n \"model_name\": \"anthropic/claude-opus-4.5\",\n \"aliases\": [\n \"opus\",\n \"opus4.5\",\n \"claude-opus\"\n ],\n \"context_window\": 200000,\n \"max_output_tokens\": 64000,\n \"supports_extended_thinking\": false,\n \"supports_json_mode\": false,\n \"supports_function_calling\": false,\n \"supports_images\": true,\n \"max_image_size_mb\": 5.0,\n \"description\": \"Claude Opus 4.5 - Anthropic's frontier reasoning model for complex software engineering and agentic workflows\",\n \"intelligence_score\": 18\n },\n {\n \"model_name\": \"anthropic/claude-sonnet-4.5\",\n \"aliases\": [\n \"sonnet\",\n \"sonnet4.5\"\n ],\n \"context_window\": 200000,\n \"max_output_tokens\": 64000,\n \"supports_extended_thinking\": false,\n \"supports_json_mode\": false,\n \"supports_function_calling\": false,\n \"supports_images\": true,\n \"max_image_size_mb\": 5.0,\n \"description\": \"Claude Sonnet 4.5 - High-performance model with exceptional reasoning and efficiency\",\n \"intelligence_score\": 12\n },\n {\n \"model_name\": \"anthropic/claude-opus-4.1\",\n \"aliases\": [\n \"opus4.1\"\n ],\n \"context_window\": 200000,\n \"max_output_tokens\": 64000,\n \"supports_extended_thinking\": false,\n \"supports_json_mode\": false,\n \"supports_function_calling\": false,\n \"supports_images\": true,\n \"max_image_size_mb\": 5.0,\n \"description\": \"Claude Opus 4.1 - Last generation flagship model with strong coding and reasoning\",\n \"intelligence_score\": 14\n },\n {\n \"model_name\": \"anthropic/claude-sonnet-4.1\",\n \"aliases\": [\n \"sonnet4.1\"\n ],\n \"context_window\": 200000,\n \"max_output_tokens\": 64000,\n \"supports_extended_thinking\": false,\n \"supports_json_mode\": false,\n \"supports_function_calling\": false,\n \"supports_images\": true,\n \"max_image_size_mb\": 5.0,\n \"description\": \"Claude Sonnet 4.1 - Last generation high-performance model with exceptional reasoning and efficiency\",\n \"intelligence_score\": 10\n },\n {\n \"model_name\": \"anthropic/claude-3.5-haiku\",\n \"aliases\": [\n \"haiku\"\n ],\n \"context_window\": 200000,\n \"max_output_tokens\": 64000,\n \"supports_extended_thinking\": false,\n \"supports_json_mode\": false,\n \"supports_function_calling\": false,\n \"supports_images\": true,\n \"max_image_size_mb\": 5.0,\n \"description\": \"Claude 3 Haiku - Fast and efficient with vision\",\n \"intelligence_score\": 8\n },\n {\n \"model_name\": \"google/gemini-3-pro-preview\",\n \"aliases\": [\n \"pro\",\n \"gemini-pro\",\n \"gemini\",\n \"gemini3\",\n \"pro-openrouter\"\n ],\n \"context_window\": 1048576,\n \"max_output_tokens\": 65536,\n \"supports_extended_thinking\": true,\n \"supports_json_mode\": true,\n \"supports_function_calling\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 20.0,\n \"allow_code_generation\": true,\n \"description\": \"Google's Gemini 3.0 Pro via OpenRouter with vision\",\n \"intelligence_score\": 18\n },\n {\n \"model_name\": \"google/gemini-2.5-pro\",\n \"aliases\": [\n \"gemini-2.5\",\n \"pro-2.5-openrouter\"\n ],\n \"context_window\": 1048576,\n \"max_output_tokens\": 65536,\n \"supports_extended_thinking\": true,\n \"supports_json_mode\": true,\n \"supports_function_calling\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 20.0,\n \"allow_code_generation\": true,\n \"description\": \"Google's Gemini 2.5 Pro via OpenRouter with vision\",\n \"intelligence_score\": 18\n },\n {\n \"model_name\": \"google/gemini-2.5-flash\",\n \"aliases\": [\n \"flash\",\n \"gemini-flash\"\n ],\n \"context_window\": 1048576,\n \"max_output_tokens\": 65536,\n \"supports_extended_thinking\": true,\n \"supports_json_mode\": true,\n \"supports_function_calling\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 15.0,\n \"description\": \"Google's Gemini 2.5 Flash via OpenRouter with vision\",\n \"intelligence_score\": 10\n },\n {\n \"model_name\": \"mistralai/mistral-large-2411\",\n \"aliases\": [\n \"mistral-large\",\n \"mistral\"\n ],\n \"context_window\": 128000,\n \"max_output_tokens\": 32000,\n \"supports_extended_thinking\": false,\n \"supports_json_mode\": true,\n \"supports_function_calling\": true,\n \"supports_images\": false,\n \"max_image_size_mb\": 0.0,\n \"description\": \"Mistral's largest model (text-only)\",\n \"intelligence_score\": 11\n },\n {\n \"model_name\": \"meta-llama/llama-3-70b\",\n \"aliases\": [\n \"llama\",\n \"llama3\",\n \"llama3-70b\",\n \"llama-70b\",\n \"llama3-openrouter\"\n ],\n \"context_window\": 8192,\n \"max_output_tokens\": 8192,\n \"supports_extended_thinking\": false,\n \"supports_json_mode\": false,\n \"supports_function_calling\": false,\n \"supports_images\": false,\n \"max_image_size_mb\": 0.0,\n \"description\": \"Meta's Llama 3 70B model (text-only)\",\n \"intelligence_score\": 9\n },\n {\n \"model_name\": \"deepseek/deepseek-r1-0528\",\n \"aliases\": [\n \"deepseek-r1\",\n \"deepseek\",\n \"r1\",\n \"deepseek-thinking\"\n ],\n \"context_window\": 65536,\n \"max_output_tokens\": 32768,\n \"supports_extended_thinking\": true,\n \"supports_json_mode\": true,\n \"supports_function_calling\": false,\n \"supports_images\": false,\n \"max_image_size_mb\": 0.0,\n \"description\": \"DeepSeek R1 with thinking mode - advanced reasoning capabilities (text-only)\",\n \"intelligence_score\": 15\n },\n {\n \"model_name\": \"perplexity/llama-3-sonar-large-32k-online\",\n \"aliases\": [\n \"perplexity\",\n \"sonar\",\n \"perplexity-online\"\n ],\n \"context_window\": 32768,\n \"max_output_tokens\": 32768,\n \"supports_extended_thinking\": false,\n \"supports_json_mode\": false,\n \"supports_function_calling\": false,\n \"supports_images\": false,\n \"max_image_size_mb\": 0.0,\n \"description\": \"Perplexity's online model with web search (text-only)\",\n \"intelligence_score\": 9\n },\n {\n \"model_name\": \"openai/o3\",\n \"aliases\": [\n \"o3\"\n ],\n \"context_window\": 200000,\n \"max_output_tokens\": 100000,\n \"supports_extended_thinking\": false,\n \"supports_json_mode\": true,\n \"supports_function_calling\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 20.0,\n \"supports_temperature\": false,\n \"temperature_constraint\": \"fixed\",\n \"description\": \"OpenAI's o3 model - well-rounded and powerful across domains with vision\",\n \"intelligence_score\": 14\n },\n {\n \"model_name\": \"openai/o3-mini\",\n \"aliases\": [\n \"o3-mini\",\n \"o3mini\"\n ],\n \"context_window\": 200000,\n \"max_output_tokens\": 100000,\n \"supports_extended_thinking\": false,\n \"supports_json_mode\": true,\n \"supports_function_calling\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 20.0,\n \"supports_temperature\": false,\n \"temperature_constraint\": \"fixed\",\n \"description\": \"OpenAI's o3-mini model - balanced performance and speed with vision\",\n \"intelligence_score\": 12\n },\n {\n \"model_name\": \"openai/o3-mini-high\",\n \"aliases\": [\n \"o3-mini-high\",\n \"o3mini-high\"\n ],\n \"context_window\": 200000,\n \"max_output_tokens\": 100000,\n \"supports_extended_thinking\": false,\n \"supports_json_mode\": true,\n \"supports_function_calling\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 20.0,\n \"supports_temperature\": false,\n \"temperature_constraint\": \"fixed\",\n \"description\": \"OpenAI's o3-mini with high reasoning effort - optimized for complex problems with vision\",\n \"intelligence_score\": 13\n },\n {\n \"model_name\": \"openai/o3-pro\",\n \"aliases\": [\n \"o3pro\"\n ],\n \"context_window\": 200000,\n \"max_output_tokens\": 100000,\n \"supports_extended_thinking\": false,\n \"supports_json_mode\": true,\n \"supports_function_calling\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 20.0,\n \"supports_temperature\": false,\n \"temperature_constraint\": \"fixed\",\n \"description\": \"OpenAI's o3-pro model - professional-grade reasoning and analysis with vision\",\n \"intelligence_score\": 15\n },\n {\n \"model_name\": \"openai/o4-mini\",\n \"aliases\": [\n \"o4-mini\",\n \"o4mini\"\n ],\n \"context_window\": 200000,\n \"max_output_tokens\": 100000,\n \"supports_extended_thinking\": false,\n \"supports_json_mode\": true,\n \"supports_function_calling\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 20.0,\n \"supports_temperature\": false,\n \"temperature_constraint\": \"fixed\",\n \"description\": \"OpenAI's o4-mini model - optimized for shorter contexts with rapid reasoning and vision\",\n \"intelligence_score\": 11\n },\n {\n \"model_name\": \"openai/gpt-5\",\n \"aliases\": [\n \"gpt5\"\n ],\n \"context_window\": 400000,\n \"max_output_tokens\": 128000,\n \"supports_extended_thinking\": true,\n \"supports_json_mode\": true,\n \"supports_function_calling\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 20.0,\n \"supports_temperature\": true,\n \"temperature_constraint\": \"range\",\n \"description\": \"GPT-5 (400K context, 128K output) - Advanced model with reasoning support\",\n \"intelligence_score\": 16\n },\n {\n \"model_name\": \"openai/gpt-5.2-pro\",\n \"aliases\": [\n \"gpt5.2-pro\",\n \"gpt5.2pro\",\n \"gpt5pro\"\n ],\n \"context_window\": 400000,\n \"max_output_tokens\": 272000,\n \"supports_extended_thinking\": true,\n \"supports_json_mode\": true,\n \"supports_function_calling\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 20.0,\n \"supports_temperature\": false,\n \"temperature_constraint\": \"fixed\",\n \"use_openai_response_api\": true,\n \"default_reasoning_effort\": \"high\",\n \"allow_code_generation\": true,\n \"description\": \"GPT-5.2 Pro - Advanced reasoning model with highest quality responses (text+image input, text output only)\",\n \"intelligence_score\": 18\n },\n {\n \"model_name\": \"openai/gpt-5-codex\",\n \"aliases\": [\n \"codex\",\n \"gpt5codex\"\n ],\n \"context_window\": 400000,\n \"max_output_tokens\": 128000,\n \"supports_extended_thinking\": false,\n \"supports_json_mode\": true,\n \"supports_function_calling\": false,\n \"supports_images\": false,\n \"max_image_size_mb\": 0.0,\n \"description\": \"GPT-5-Codex is a specialized version of GPT-5 optimized for software engineering and coding workflows\",\n \"intelligence_score\": 17\n },\n {\n \"model_name\": \"openai/gpt-5-mini\",\n \"aliases\": [\n \"gpt5mini\"\n ],\n \"context_window\": 400000,\n \"max_output_tokens\": 128000,\n \"supports_extended_thinking\": false,\n \"supports_json_mode\": true,\n \"supports_function_calling\": false,\n \"supports_images\": false,\n \"max_image_size_mb\": 0.0,\n \"supports_temperature\": true,\n \"temperature_constraint\": \"fixed\",\n \"description\": \"GPT-5-mini (400K context, 128K output) - Efficient variant with reasoning support\",\n \"intelligence_score\": 10\n },\n {\n \"model_name\": \"openai/gpt-5-nano\",\n \"aliases\": [\n \"gpt5nano\"\n ],\n \"context_window\": 400000,\n \"max_output_tokens\": 128000,\n \"supports_extended_thinking\": false,\n \"supports_json_mode\": true,\n \"supports_function_calling\": false,\n \"supports_images\": false,\n \"max_image_size_mb\": 0.0,\n \"supports_temperature\": true,\n \"temperature_constraint\": \"fixed\",\n \"description\": \"GPT-5 nano (400K context, 128K output) - Fastest, cheapest version of GPT-5 for summarization and classification tasks\",\n \"intelligence_score\": 8\n },\n {\n \"model_name\": \"openai/gpt-5.2\",\n \"aliases\": [\n \"gpt5.2\",\n \"gpt-5.2\",\n \"5.2\",\n \"gpt5.1\",\n \"gpt-5.1\",\n \"5.1\"\n ],\n \"context_window\": 400000,\n \"max_output_tokens\": 128000,\n \"supports_extended_thinking\": true,\n \"supports_json_mode\": true,\n \"supports_function_calling\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 20.0,\n \"supports_temperature\": true,\n \"temperature_constraint\": \"fixed\",\n \"default_reasoning_effort\": \"medium\",\n \"allow_code_generation\": true,\n \"description\": \"GPT-5.2 (400K context, 128K output) - Flagship reasoning model with configurable thinking effort and vision support\",\n \"intelligence_score\": 18\n },\n {\n \"model_name\": \"openai/gpt-5.1-codex\",\n \"aliases\": [\n \"gpt5.1-codex\",\n \"gpt-5.1-codex\",\n \"gpt5.1code\",\n \"gpt-5.1-code\",\n \"codex-5.1\"\n ],\n \"context_window\": 400000,\n \"max_output_tokens\": 128000,\n \"supports_extended_thinking\": true,\n \"supports_json_mode\": true,\n \"supports_function_calling\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 20.0,\n \"supports_temperature\": true,\n \"temperature_constraint\": \"fixed\",\n \"use_openai_response_api\": true,\n \"default_reasoning_effort\": \"high\",\n \"allow_code_generation\": true,\n \"description\": \"GPT-5.1 Codex (400K context, 128K output) - Agentic coding specialization available through the Responses API\",\n \"intelligence_score\": 19\n },\n {\n \"model_name\": \"openai/gpt-5.1-codex-mini\",\n \"aliases\": [\n \"gpt5.1-codex-mini\",\n \"gpt-5.1-codex-mini\",\n \"codex-mini\",\n \"5.1-codex-mini\"\n ],\n \"context_window\": 400000,\n \"max_output_tokens\": 128000,\n \"supports_extended_thinking\": true,\n \"supports_json_mode\": true,\n \"supports_function_calling\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 20.0,\n \"supports_temperature\": true,\n \"temperature_constraint\": \"fixed\",\n \"allow_code_generation\": true,\n \"description\": \"GPT-5.1 Codex mini (400K context, 128K output) - Cost-efficient Codex variant with streaming support\",\n \"intelligence_score\": 16\n },\n {\n \"model_name\": \"x-ai/grok-4\",\n \"aliases\": [\n \"grok-4\",\n \"grok4\",\n \"grok\"\n ],\n \"context_window\": 256000,\n \"max_output_tokens\": 256000,\n \"supports_extended_thinking\": true,\n \"supports_json_mode\": true,\n \"supports_function_calling\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 20.0,\n \"supports_temperature\": true,\n \"temperature_constraint\": \"range\",\n \"description\": \"xAI's Grok 4 via OpenRouter with vision and advanced reasoning\",\n \"intelligence_score\": 15\n },\n {\n \"model_name\": \"x-ai/grok-4.1-fast\",\n \"aliases\": [\n \"grok-4.1-fast-openrouter\",\n \"grok-4.1-openrouter\"\n ],\n \"context_window\": 2000000,\n \"max_output_tokens\": 2000000,\n \"supports_extended_thinking\": true,\n \"supports_json_mode\": true,\n \"supports_function_calling\": true,\n \"supports_images\": true,\n \"max_image_size_mb\": 20.0,\n \"supports_temperature\": true,\n \"temperature_constraint\": \"range\",\n \"description\": \"xAI's Grok 4.1 Fast Reasoning via OpenRouter (2M context) with vision and advanced reasoning\",\n \"intelligence_score\": 15\n }\n ]\n}\n" }, { "path": "conf/xai_models.json", "content": "{\n \"_README\": {\n \"description\": \"Model metadata for X.AI (GROK) API access.\",\n \"documentation\": \"https://github.com/BeehiveInnovations/pal-mcp-server/blob/main/docs/custom_models.md\",\n \"usage\": \"Models listed here are exposed directly through the X.AI provider. Aliases are case-insensitive.\",\n \"field_notes\": \"Matches providers/shared/model_capabilities.py.\",\n \"field_descriptions\": {\n \"model_name\": \"The model identifier (e.g., 'grok-4', 'grok-4.1-fast')\",\n \"aliases\": \"Array of short names users can type instead of the full model name\",\n \"context_window\": \"Total number of tokens the model can process (input + output combined)\",\n \"max_output_tokens\": \"Maximum number of tokens the model can generate in a single response\",\n \"max_thinking_tokens\": \"Maximum reasoning/thinking tokens the model will allocate when extended thinking is requested\",\n \"supports_extended_thinking\": \"Whether the model supports extended reasoning tokens (currently none do via OpenRouter or custom APIs)\",\n \"supports_json_mode\": \"Whether the model can guarantee valid JSON output\",\n \"supports_function_calling\": \"Whether the model supports function/tool calling\",\n \"supports_images\": \"Whether the model can process images/visual input\",\n \"max_image_size_mb\": \"Maximum total size in MB for all images combined (capped at 40MB max for custom models)\",\n \"supports_temperature\": \"Whether the model accepts temperature parameter in API calls (set to false for O3/O4 reasoning models)\",\n \"temperature_constraint\": \"Type of temperature constraint: 'fixed' (fixed value), 'range' (continuous range), 'discrete' (specific values), or omit for default range\",\n \"use_openai_response_api\": \"Set to true when the model must use the /responses endpoint (reasoning models like GPT-5.2 Pro). Leave false/omit for standard chat completions.\",\n \"default_reasoning_effort\": \"Default reasoning effort level for models that support it (e.g., 'low', 'medium', 'high'). Omit if not applicable.\",\n \"description\": \"Human-readable description of the model\",\n \"intelligence_score\": \"1-20 human rating used as the primary signal for auto-mode model ordering\"\n }\n },\n \"models\": [\n {\n \"model_name\": \"grok-4\",\n \"friendly_name\": \"X.AI (Grok 4)\",\n \"aliases\": [\n \"grok\",\n \"grok4\",\n \"grok-4\"\n ],\n \"intelligence_score\": 16,\n \"description\": \"GROK-4 (256K context) - Frontier multimodal reasoning model with advanced capabilities\",\n \"context_window\": 256000,\n \"max_output_tokens\": 256000,\n \"supports_extended_thinking\": true,\n \"supports_system_prompts\": true,\n \"supports_streaming\": true,\n \"supports_function_calling\": true,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"supports_temperature\": true,\n \"max_image_size_mb\": 20.0\n },\n {\n \"model_name\": \"grok-4-1-fast-reasoning\",\n \"friendly_name\": \"X.AI (Grok 4.1 Fast Reasoning)\",\n \"aliases\": [\n \"grok-4.1\",\n \"grok-4-1\",\n \"grok-4.1-fast-reasoning\",\n \"grok-4.1-fast-reasoning-latest\",\n \"grok-4.1-fast\"\n ],\n \"intelligence_score\": 15,\n \"description\": \"GROK-4.1 Fast Reasoning (2M context) - High-performance multimodal reasoning model with function calling\",\n \"context_window\": 2000000,\n \"max_output_tokens\": 2000000,\n \"supports_extended_thinking\": true,\n \"supports_system_prompts\": true,\n \"supports_streaming\": true,\n \"supports_function_calling\": true,\n \"supports_json_mode\": true,\n \"supports_images\": true,\n \"supports_temperature\": true,\n \"max_image_size_mb\": 20.0\n }\n ]\n}\n" }, { "path": "config.py", "content": "\"\"\"\nConfiguration and constants for PAL MCP Server\n\nThis module centralizes all configuration settings for the PAL MCP Server.\nIt defines model configurations, token limits, temperature defaults, and other\nconstants used throughout the application.\n\nConfiguration values can be overridden by environment variables where appropriate.\n\"\"\"\n\nfrom utils.env import get_env\n\n# Version and metadata\n# These values are used in server responses and for tracking releases\n# IMPORTANT: This is the single source of truth for version and author info\n# Semantic versioning: MAJOR.MINOR.PATCH\n__version__ = \"9.8.2\"\n# Last update date in ISO format\n__updated__ = \"2025-12-15\"\n# Primary maintainer\n__author__ = \"Fahad Gilani\"\n\n# Model configuration\n# DEFAULT_MODEL: The default model used for all AI operations\n# This should be a stable, high-performance model suitable for code analysis\n# Can be overridden by setting DEFAULT_MODEL environment variable\n# Special value \"auto\" means Claude should pick the best model for each task\nDEFAULT_MODEL = get_env(\"DEFAULT_MODEL\", \"auto\") or \"auto\"\n\n# Auto mode detection - when DEFAULT_MODEL is \"auto\", Claude picks the model\nIS_AUTO_MODE = DEFAULT_MODEL.lower() == \"auto\"\n\n# Each provider (gemini.py, openai.py, xai.py, dial.py, openrouter.py, custom.py, azure_openai.py)\n# defines its own MODEL_CAPABILITIES\n# with detailed descriptions. Tools use ModelProviderRegistry.get_available_model_names()\n# to get models only from enabled providers (those with valid API keys).\n#\n# This architecture ensures:\n# - No namespace collisions (models only appear when their provider is enabled)\n# - API key-based filtering (prevents wrong models from being shown to Claude)\n# - Proper provider routing (models route to the correct API endpoint)\n# - Clean separation of concerns (providers own their model definitions)\n\n\n# Temperature defaults for different tool types\n# NOTE: Gemini 3.0 Pro notes suggest temperature should be set at 1.0\n# in most cases. Lowering it can affect the models 'reasoning' abilities.\n# Newer models / inference stacks are able to handle their randomness better.\n\n# Temperature controls the randomness/creativity of model responses\n# Lower values (0.0-0.3) produce more deterministic, focused responses\n# Higher values (0.7-1.0) produce more creative, varied responses\n\n# TEMPERATURE_ANALYTICAL: Used for tasks requiring precision and consistency\n# Ideal for code review, debugging, and error analysis where accuracy is critical\nTEMPERATURE_ANALYTICAL = 1.0 # For code review, debugging\n\n# TEMPERATURE_BALANCED: Middle ground for general conversations\n# Provides a good balance between consistency and helpful variety\nTEMPERATURE_BALANCED = 1.0 # For general chat\n\n# TEMPERATURE_CREATIVE: Higher temperature for exploratory tasks\n# Used when brainstorming, exploring alternatives, or architectural discussions\nTEMPERATURE_CREATIVE = 1.0 # For architecture, deep thinking\n\n# Thinking Mode Defaults\n# DEFAULT_THINKING_MODE_THINKDEEP: Default thinking depth for extended reasoning tool\n# Higher modes use more computational budget but provide deeper analysis\nDEFAULT_THINKING_MODE_THINKDEEP = get_env(\"DEFAULT_THINKING_MODE_THINKDEEP\", \"high\") or \"high\"\n\n# Consensus Tool Defaults\n# Consensus timeout and rate limiting settings\nDEFAULT_CONSENSUS_TIMEOUT = 120.0 # 2 minutes per model\nDEFAULT_CONSENSUS_MAX_INSTANCES_PER_COMBINATION = 2\n\n# NOTE: Consensus tool now uses sequential processing for MCP compatibility\n# Concurrent processing was removed to avoid async pattern violations\n\n# MCP Protocol Transport Limits\n#\n# IMPORTANT: This limit ONLY applies to the Claude CLI ↔ MCP Server transport boundary.\n# It does NOT limit internal MCP Server operations like system prompts, file embeddings,\n# conversation history, or content sent to external models (Gemini/OpenAI/OpenRouter).\n#\n# MCP Protocol Architecture:\n# Claude CLI ←→ MCP Server ←→ External Model (Gemini/OpenAI/etc.)\n# ↑ ↑\n# β”‚ β”‚\n# MCP transport Internal processing\n# (token limit from MAX_MCP_OUTPUT_TOKENS) (No MCP limit - can be 1M+ tokens)\n#\n# MCP_PROMPT_SIZE_LIMIT: Maximum character size for USER INPUT crossing MCP transport\n# The MCP protocol has a combined request+response limit controlled by MAX_MCP_OUTPUT_TOKENS.\n# To ensure adequate space for MCP Server β†’ Claude CLI responses, we limit user input\n# to roughly 60% of the total token budget converted to characters. Larger user prompts\n# must be sent as prompt.txt files to bypass MCP's transport constraints.\n#\n# Token to character conversion ratio: ~4 characters per token (average for code/text)\n# Default allocation: 60% of tokens for input, 40% for response\n#\n# What IS limited by this constant:\n# - request.prompt field content (user input from Claude CLI)\n# - prompt.txt file content (alternative user input method)\n# - Any other direct user input fields\n#\n# What is NOT limited by this constant:\n# - System prompts added internally by tools\n# - File content embedded by tools\n# - Conversation history loaded from storage\n# - Web search instructions or other internal additions\n# - Complete prompts sent to external models (managed by model-specific token limits)\n#\n# This ensures MCP transport stays within protocol limits while allowing internal\n# processing to use full model context windows (200K-1M+ tokens).\n\n\ndef _calculate_mcp_prompt_limit() -> int:\n \"\"\"\n Calculate MCP prompt size limit based on MAX_MCP_OUTPUT_TOKENS environment variable.\n\n Returns:\n Maximum character count for user input prompts\n \"\"\"\n # Check for Claude's MAX_MCP_OUTPUT_TOKENS environment variable\n max_tokens_str = get_env(\"MAX_MCP_OUTPUT_TOKENS\")\n\n if max_tokens_str:\n try:\n max_tokens = int(max_tokens_str)\n # Allocate 60% of tokens for input, convert to characters (~4 chars per token)\n input_token_budget = int(max_tokens * 0.6)\n character_limit = input_token_budget * 4\n return character_limit\n except (ValueError, TypeError):\n # Fall back to default if MAX_MCP_OUTPUT_TOKENS is not a valid integer\n pass\n\n # Default fallback: 60,000 characters (equivalent to ~15k tokens input of 25k total)\n return 60_000\n\n\nMCP_PROMPT_SIZE_LIMIT = _calculate_mcp_prompt_limit()\n\n# Language/Locale Configuration\n# LOCALE: Language/locale specification for AI responses\n# When set, all AI tools will respond in the specified language while\n# maintaining their analytical capabilities\n# Examples: \"fr-FR\", \"en-US\", \"zh-CN\", \"zh-TW\", \"ja-JP\", \"ko-KR\", \"es-ES\",\n# \"de-DE\", \"it-IT\", \"pt-PT\"\n# Leave empty for default language (English)\nLOCALE = get_env(\"LOCALE\", \"\") or \"\"\n\n# Threading configuration\n# Simple in-memory conversation threading for stateless MCP environment\n# Conversations persist only during the Claude session\n" }, { "path": "docker/README.md", "content": "# PAL MCP Server - Docker Setup\n\n## Quick Start\n\n### 1. Prerequisites\n\n- Docker installed (Docker Compose optional)\n- At least one API key (Gemini, OpenAI, xAI, etc.)\n\n### 2. Configuration\n\n```bash\n# Copy environment template\ncp .env.example .env\n\n# Edit with your API keys (at least one required)\n# Required: GEMINI_API_KEY or OPENAI_API_KEY or XAI_API_KEY\nnano .env\n```\n\n### 3. Build Image\n\n```bash\n# Build the Docker image\ndocker build -t pal-mcp-server:latest .\n\n# Or use the build script (Bash)\nchmod +x docker/scripts/build.sh\n./docker/scripts/build.sh\n\n# Build with PowerShell\ndocker/scripts/build.ps1\n\n```\n\n### 4. Usage Options\n\n#### A. Direct Docker Run (Recommended for MCP)\n\n```bash\n# Run with environment file\ndocker run --rm -i --env-file .env \\\n -v $(pwd)/logs:/app/logs \\\n pal-mcp-server:latest\n\n# Run with inline environment variables\ndocker run --rm -i \\\n -e GEMINI_API_KEY=\"your_key_here\" \\\n -e LOG_LEVEL=INFO \\\n -v $(pwd)/logs:/app/logs \\\n pal-mcp-server:latest\n```\n\n#### B. Docker Compose (For Development/Monitoring)\n\n```bash\n# Deploy with Docker Compose\nchmod +x docker/scripts/deploy.sh\n./docker/scripts/deploy.sh\n\n# Or use PowerShell script\ndocker/scripts/deploy.ps1\n\n# Interactive stdio mode\ndocker-compose exec pal-mcp python server.py\n```\n\n## Service Management\n\n### Docker Commands\n\n```bash\n# View running containers\ndocker ps\n\n# View logs from container\ndocker logs \n\n# Stop all pal-mcp containers\ndocker stop $(docker ps -q --filter \"ancestor=pal-mcp-server:latest\")\n\n# Remove old containers and images\ndocker container prune\ndocker image prune\n```\n\n### Docker Compose Management (Optional)\n\n```bash\n# View logs\ndocker-compose logs -f pal-mcp\n\n# Check status\ndocker-compose ps\n\n# Restart service\ndocker-compose restart pal-mcp\n\n# Stop services\ndocker-compose down\n\n# Rebuild and update\ndocker-compose build --no-cache pal-mcp\ndocker-compose up -d pal-mcp\n```\n\n## Health Monitoring\n\nThe container includes health checks that verify:\n- Server process is running\n- Python modules can be imported\n- Log directory is writable \n- API keys are configured\n\n## Volumes and Persistent Data\n\nThe Docker setup includes persistent volumes to preserve data between container runs:\n\n- **`./logs:/app/logs`** - Persistent log storage (local folder mount)\n- **`pal-mcp-config:/app/conf`** - Configuration persistence (named Docker volume)\n- **`/etc/localtime:/etc/localtime:ro`** - Host timezone synchronization (read-only)\n\n### How Persistent Volumes Work\n\nThe `pal-mcp` service (used by `pal-docker-compose` and Docker Compose commands) mounts the named volume `pal-mcp-config` persistently. All data placed in `/app/conf` inside the container is preserved between runs thanks to this Docker volume.\n\nIn the `docker-compose.yml` file, you will find:\n\n```yaml\nvolumes:\n - ./logs:/app/logs\n - pal-mcp-config:/app/conf\n - /etc/localtime:/etc/localtime:ro\n```\n\nand the named volume definition:\n\n```yaml\nvolumes:\n pal-mcp-config:\n driver: local\n```\n\n## Security\n\n- Runs as non-root user `paluser`\n- Read-only filesystem with tmpfs for temporary files\n- No network ports exposed (stdio communication only)\n- Secrets managed via environment variables\n\n## Troubleshooting\n\n### Container won't start\n\n```bash\n# Check if image exists\ndocker images pal-mcp-server\n\n# Test container interactively\ndocker run --rm -it --env-file .env pal-mcp-server:latest bash\n\n# Check environment variables\ndocker run --rm --env-file .env pal-mcp-server:latest env | grep API\n\n# Test with minimal configuration\ndocker run --rm -i -e GEMINI_API_KEY=\"test\" pal-mcp-server:latest python server.py\n```\n\n### MCP Connection Issues\n\n```bash\n# Test Docker connectivity\ndocker run --rm hello-world\n\n# Verify container stdio\necho '{\"jsonrpc\": \"2.0\", \"method\": \"ping\"}' | docker run --rm -i --env-file .env pal-mcp-server:latest python server.py\n\n# Check Claude Desktop logs for connection errors\n```\n\n### API Key Problems\n\n```bash\n# Verify API keys are loaded\ndocker run --rm --env-file .env pal-mcp-server:latest python -c \"import os; print('GEMINI_API_KEY:', bool(os.getenv('GEMINI_API_KEY')))\"\n\n# Test API connectivity\ndocker run --rm --env-file .env pal-mcp-server:latest python /usr/local/bin/healthcheck.py\n```\n\n### Permission Issues\n\n```bash\n# Fix log directory permissions (Linux/macOS)\nsudo chown -R $USER:$USER logs/\nchmod 755 logs/\n\n# Windows: Run Docker Desktop as Administrator if needed\n```\n\n### Memory/Performance Issues\n\n```bash\n# Check container resource usage\ndocker stats\n\n# Run with memory limits\ndocker run --rm -i --memory=\"512m\" --env-file .env pal-mcp-server:latest\n\n# Monitor Docker logs\ndocker run --rm -i --env-file .env pal-mcp-server:latest 2>&1 | tee docker.log\n```\n\n## MCP Integration (Claude Desktop)\n\n### Recommended Configuration (docker run)\n\n```json\n{\n \"servers\": {\n \"pal-docker\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"--env-file\",\n \"/absolute/path/to/pal-mcp-server/.env\",\n \"-v\",\n \"/absolute/path/to/pal-mcp-server/logs:/app/logs\",\n \"pal-mcp-server:latest\"\n ]\n }\n }\n}\n```\n\n### Windows Example\n\n```json\n{\n \"servers\": {\n \"pal-docker\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"--env-file\",\n \"C:/Users/YourName/path/to/pal-mcp-server/.env\",\n \"-v\",\n \"C:/Users/YourName/path/to/pal-mcp-server/logs:/app/logs\",\n \"pal-mcp-server:latest\"\n ]\n }\n }\n}\n```\n\n### Advanced Option: docker-compose run (uses compose configuration)\n\n```json\n{\n \"servers\": {\n \"pal-docker\": {\n \"command\": \"docker-compose\",\n \"args\": [\n \"-f\",\n \"/absolute/path/to/pal-mcp-server/docker-compose.yml\",\n \"run\",\n \"--rm\",\n \"pal-mcp\"\n ]\n }\n }\n}\n```\n\n### Environment File Template\n\nCreate a `.env` file with at least one API key:\n\n```bash\n# Required: At least one API key\nGEMINI_API_KEY=your_gemini_key_here\nOPENAI_API_KEY=your_openai_key_here\n\n# Optional configuration\nLOG_LEVEL=INFO\nDEFAULT_MODEL=auto\nDEFAULT_THINKING_MODE_THINKDEEP=high\n\n# Optional API keys (leave empty if not used)\nANTHROPIC_API_KEY=\nXAI_API_KEY=\nDIAL_API_KEY=\nOPENROUTER_API_KEY=\nCUSTOM_API_URL=\n```\n\n## Quick Test & Validation\n\n### 1. Test Docker Image\n\n```bash\n# Test container starts correctly\ndocker run --rm pal-mcp-server:latest python --version\n\n# Test health check\ndocker run --rm -e GEMINI_API_KEY=\"test\" pal-mcp-server:latest python /usr/local/bin/healthcheck.py\n```\n\n### 2. Test MCP Protocol\n\n```bash\n# Test basic MCP communication\necho '{\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}}' | \\\n docker run --rm -i --env-file .env pal-mcp-server:latest python server.py\n```\n\n### 3. Validate Configuration\n\n```bash\n# Run validation script\npython test_mcp_config.py\n\n# Or validate JSON manually\npython -m json.tool .vscode/mcp.json\n```\n\n## Available Tools\n\nThe PAL MCP Server provides these tools when properly configured:\n\n- **chat** - General AI conversation and collaboration\n- **thinkdeep** - Multi-stage investigation and reasoning \n- **planner** - Interactive sequential planning\n- **consensus** - Multi-model consensus workflow\n- **codereview** - Comprehensive code review\n- **debug** - Root cause analysis and debugging\n- **analyze** - Code analysis and assessment\n- **refactor** - Refactoring analysis and suggestions\n- **secaudit** - Security audit workflow\n- **testgen** - Test generation with edge cases\n- **docgen** - Documentation generation\n- **tracer** - Code tracing and dependency mapping\n- **precommit** - Pre-commit validation workflow\n- **listmodels** - Available AI models information\n- **version** - Server version and configuration\n\n## Performance Notes\n\n- **Image size**: ~293MB optimized multi-stage build\n- **Memory usage**: ~256MB base + model overhead\n- **Startup time**: ~2-3 seconds for container initialization\n- **API response**: Varies by model and complexity (1-30 seconds)\n\nFor production use, consider:\n- Using specific API keys for rate limiting\n- Monitoring container resource usage\n- Setting up log rotation for persistent logs\n- Using Docker health checks for reliability\n" }, { "path": "docker/scripts/build.ps1", "content": "#!/usr/bin/env pwsh\n#Requires -Version 5.1\n[CmdletBinding()]\nparam()\n\n# Set error action preference\n$ErrorActionPreference = \"Stop\"\n\n# Colors for output (using Write-Host with colors)\nfunction Write-ColorText {\n param(\n [Parameter(Mandatory)]\n [string]$Text,\n [string]$Color = \"White\",\n [switch]$NoNewline\n )\n if ($NoNewline) {\n Write-Host $Text -ForegroundColor $Color -NoNewline\n } else {\n Write-Host $Text -ForegroundColor $Color\n }\n}\n\nWrite-ColorText \"=== Building PAL MCP Server Docker Image ===\" -Color Green\n\n# Check if .env file exists\nif (!(Test-Path \".env\")) {\n Write-ColorText \"Warning: .env file not found. Copying from .env.example\" -Color Yellow\n if (Test-Path \".env.example\") {\n Copy-Item \".env.example\" \".env\"\n Write-ColorText \"Please edit .env file with your API keys before running the server\" -Color Yellow\n } else {\n Write-ColorText \"Error: .env.example not found\" -Color Red\n exit 1\n }\n}\n\n# Build the Docker image\nWrite-ColorText \"Building Docker image...\" -Color Green\ntry {\n docker-compose build --no-cache\n if ($LASTEXITCODE -ne 0) {\n throw \"Docker build failed\"\n }\n} catch {\n Write-ColorText \"Error: Failed to build Docker image\" -Color Red\n exit 1\n}\n\n# Verify the build\nWrite-ColorText \"Verifying build...\" -Color Green\n$images = docker images --format \"table {{.Repository}}\\t{{.Tag}}\\t{{.Size}}\\t{{.CreatedAt}}\" | Select-String \"pal-mcp-server\"\n\nif ($images) {\n Write-ColorText \"βœ“ Docker image built successfully\" -Color Green\n Write-ColorText \"Image details:\" -Color Green\n $images | ForEach-Object { Write-Host $_.Line }\n} else {\n Write-ColorText \"βœ— Failed to build Docker image\" -Color Red\n exit 1\n}\n\nWrite-ColorText \"=== Build Complete ===\" -Color Green\nWrite-ColorText \"Next steps:\" -Color Yellow\nWrite-Host \" 1. Edit .env file with your API keys\"\nWrite-ColorText \" 2. Run: \" -Color White -NoNewline\nWrite-ColorText \"docker-compose up -d\" -Color Green\n\nWrite-ColorText \"Or use the deploy script: \" -Color White -NoNewline\nWrite-ColorText \".\\deploy.ps1\" -Color Green\n" }, { "path": "docker/scripts/build.sh", "content": "#!/bin/bash\nset -euo pipefail\n\n# Colors for output\nGREEN='\\033[0;32m'\nYELLOW='\\033[1;33m'\nRED='\\033[0;31m'\nNC='\\033[0m'\n\necho -e \"${GREEN}=== Building PAL MCP Server Docker Image ===${NC}\"\n\n# Check if .env file exists\nif [[ ! -f .env ]]; then\n echo -e \"${YELLOW}Warning: .env file not found. Copying from .env.example${NC}\"\n if [[ -f .env.example ]]; then\n cp .env.example .env\n echo -e \"${YELLOW}Please edit .env file with your API keys before running the server${NC}\"\n else\n echo -e \"${RED}Error: .env.example not found${NC}\"\n exit 1\n fi\nfi\n\n# Build the Docker image\necho -e \"${GREEN}Building Docker image...${NC}\"\ndocker-compose build --no-cache\n\n# Verify the build\nif docker images | grep -q \"pal-mcp-server\"; then\n echo -e \"${GREEN}βœ“ Docker image built successfully${NC}\"\n echo -e \"${GREEN}Image details:${NC}\"\n docker images | grep pal-mcp-server\nelse\n echo -e \"${RED}βœ— Failed to build Docker image${NC}\"\n exit 1\nfi\n\necho -e \"${GREEN}=== Build Complete ===${NC}\"\necho -e \"${YELLOW}Next steps:${NC}\"\necho -e \" 1. Edit .env file with your API keys\"\necho -e \" 2. Run: ${GREEN}docker-compose up -d${NC}\"\n" }, { "path": "docker/scripts/deploy.ps1", "content": "#!/usr/bin/env pwsh\n#Requires -Version 5.1\n[CmdletBinding()]\nparam(\n [switch]$SkipHealthCheck,\n [int]$HealthCheckTimeout = 60\n)\n\n# Set error action preference\n$ErrorActionPreference = \"Stop\"\n\n# Colors for output\nfunction Write-ColorText {\n param(\n [Parameter(Mandatory)]\n [string]$Text,\n [string]$Color = \"White\",\n [switch]$NoNewline\n )\n if ($NoNewline) {\n Write-Host $Text -ForegroundColor $Color -NoNewline\n } else {\n Write-Host $Text -ForegroundColor $Color\n }\n}\n\nWrite-ColorText \"=== Deploying PAL MCP Server ===\" -Color Green\n\n# Function to check if required environment variables are set\nfunction Test-EnvironmentVariables {\n # At least one of these API keys must be set\n $requiredVars = @(\n \"GEMINI_API_KEY\",\n \"GOOGLE_API_KEY\", \n \"OPENAI_API_KEY\",\n \"XAI_API_KEY\",\n \"DIAL_API_KEY\",\n \"OPENROUTER_API_KEY\"\n )\n \n $hasApiKey = $false\n foreach ($var in $requiredVars) {\n $value = [Environment]::GetEnvironmentVariable($var)\n if (![string]::IsNullOrWhiteSpace($value)) {\n $hasApiKey = $true\n break\n }\n }\n\n if (!$hasApiKey) {\n Write-ColorText \"Error: At least one API key must be set in your .env file\" -Color Red\n Write-ColorText \"Required variables (at least one):\" -Color Yellow\n $requiredVars | ForEach-Object { Write-Host \" $_\" }\n exit 1\n }\n}\n\n# Load environment variables from .env file\nif (Test-Path \".env\") {\n Write-ColorText \"Loading environment variables from .env...\" -Color Green\n \n # Read .env file and set environment variables\n Get-Content \".env\" | ForEach-Object {\n if ($_ -match '^([^#][^=]*?)=(.*)$') {\n $name = $matches[1].Trim()\n $value = $matches[2].Trim()\n # Remove quotes if present\n $value = $value -replace '^[\"'']|[\"'']$', ''\n [Environment]::SetEnvironmentVariable($name, $value, \"Process\")\n }\n }\n Write-ColorText \"βœ“ Environment variables loaded from .env\" -Color Green\n} else {\n Write-ColorText \"Error: .env file not found\" -Color Red\n Write-ColorText \"Please copy .env.example to .env and configure your API keys\" -Color Yellow\n exit 1\n}\n\n# Check required environment variables\nTest-EnvironmentVariables\n\n# Function to wait for service health with exponential backoff\nfunction Wait-ForHealth {\n param(\n [int]$MaxAttempts = 6,\n [int]$InitialDelay = 2\n )\n \n $attempt = 1\n $delay = $InitialDelay\n\n while ($attempt -le $MaxAttempts) {\n try {\n # Get container ID for pal-mcp service\n $containerId = docker-compose ps -q pal-mcp\n if ([string]::IsNullOrWhiteSpace($containerId)) {\n $status = \"unavailable\"\n } else {\n $status = docker inspect -f \"{{.State.Health.Status}}\" $containerId 2>$null\n if ($LASTEXITCODE -ne 0) {\n $status = \"unavailable\"\n }\n }\n \n if ($status -eq \"healthy\") {\n return $true\n }\n \n Write-ColorText \"Waiting for service to be healthy... (attempt $attempt/$MaxAttempts, retrying in ${delay}s)\" -Color Yellow\n Start-Sleep -Seconds $delay\n $delay = $delay * 2\n $attempt++\n } catch {\n Write-ColorText \"Error checking health status: $_\" -Color Red\n $attempt++\n Start-Sleep -Seconds $delay\n }\n }\n\n Write-ColorText \"Service failed to become healthy after $MaxAttempts attempts\" -Color Red\n Write-ColorText \"Checking logs:\" -Color Yellow\n docker-compose logs pal-mcp\n return $false\n}\n\n# Create logs directory if it doesn't exist\nif (!(Test-Path \"logs\")) {\n Write-ColorText \"Creating logs directory...\" -Color Green\n New-Item -ItemType Directory -Path \"logs\" -Force | Out-Null\n}\n\n# Stop existing containers\nWrite-ColorText \"Stopping existing containers...\" -Color Green\ntry {\n docker-compose down\n if ($LASTEXITCODE -ne 0) {\n Write-ColorText \"Warning: Failed to stop existing containers (they may not be running)\" -Color Yellow\n }\n} catch {\n Write-ColorText \"Warning: Error stopping containers: $_\" -Color Yellow\n}\n\n# Start the services\nWrite-ColorText \"Starting PAL MCP Server...\" -Color Green\ntry {\n docker-compose up -d\n if ($LASTEXITCODE -ne 0) {\n throw \"Failed to start services\"\n }\n} catch {\n Write-ColorText \"Error: Failed to start services\" -Color Red\n Write-ColorText \"Checking logs:\" -Color Yellow\n docker-compose logs pal-mcp\n exit 1\n}\n\n# Wait for health check (unless skipped)\nif (!$SkipHealthCheck) {\n Write-ColorText \"Waiting for service to be healthy...\" -Color Green\n \n # Try simple timeout first, then use exponential backoff if needed\n $timeout = $HealthCheckTimeout\n $elapsed = 0\n $healthy = $false\n \n while ($elapsed -lt $timeout) {\n try {\n $containerId = docker-compose ps -q pal-mcp\n if (![string]::IsNullOrWhiteSpace($containerId)) {\n $status = docker inspect -f \"{{.State.Health.Status}}\" $containerId 2>$null\n if ($status -eq \"healthy\") {\n $healthy = $true\n break\n }\n }\n } catch {\n # Continue checking\n }\n \n Start-Sleep -Seconds 2\n $elapsed += 2\n }\n\n if (!$healthy) {\n # Use exponential backoff retry mechanism\n if (!(Wait-ForHealth)) {\n Write-ColorText \"Service failed to become healthy\" -Color Red\n Write-ColorText \"Checking logs:\" -Color Yellow\n docker-compose logs pal-mcp\n exit 1\n }\n }\n}\n\nWrite-ColorText \"βœ“ PAL MCP Server deployed successfully\" -Color Green\nWrite-ColorText \"Service Status:\" -Color Green\ndocker-compose ps\n\nWrite-ColorText \"=== Deployment Complete ===\" -Color Green\nWrite-ColorText \"Useful commands:\" -Color Yellow\nWrite-ColorText \" View logs: \" -Color White -NoNewline\nWrite-ColorText \"docker-compose logs -f pal-mcp\" -Color Green\n\nWrite-ColorText \" Stop service: \" -Color White -NoNewline\nWrite-ColorText \"docker-compose down\" -Color Green\n\nWrite-ColorText \" Restart service: \" -Color White -NoNewline\nWrite-ColorText \"docker-compose restart pal-mcp\" -Color Green\n\nWrite-ColorText \" PowerShell logs: \" -Color White -NoNewline\nWrite-ColorText \"Get-Content logs\\mcp_server.log -Wait\" -Color Green\n" }, { "path": "docker/scripts/deploy.sh", "content": "#!/bin/bash\nset -euo pipefail\n\n# Colors for output\nGREEN='\\033[0;32m'\nYELLOW='\\033[1;33m'\nRED='\\033[0;31m'\nNC='\\033[0m'\n\necho -e \"${GREEN}=== Deploying PAL MCP Server ===${NC}\"\n\n# Function to check if required environment variables are set\ncheck_env_vars() {\n # At least one of these API keys must be set\n local required_vars=(\"GEMINI_API_KEY\" \"GOOGLE_API_KEY\" \"OPENAI_API_KEY\" \"XAI_API_KEY\" \"DIAL_API_KEY\" \"OPENROUTER_API_KEY\")\n \n local has_api_key=false\n for var in \"${required_vars[@]}\"; do\n if [[ -n \"${!var:-}\" ]]; then\n has_api_key=true\n break\n fi\n done\n\n if [[ \"$has_api_key\" == false ]]; then\n echo -e \"${RED}Error: At least one API key must be set in your .env file${NC}\"\n printf ' %s\\n' \"${required_vars[@]}\"\n exit 1\n fi\n}\n\n# Load environment variables\nif [[ -f .env ]]; then\n set -a\n source .env\n set +a\n echo -e \"${GREEN}βœ“ Environment variables loaded from .env${NC}\"\nelse\n echo -e \"${RED}Error: .env file not found${NC}\"\n echo -e \"${YELLOW}Please copy .env.example to .env and configure your API keys${NC}\"\n exit 1\nfi\n\n# Check required environment variables\ncheck_env_vars\n\n# Exponential backoff health check function\nwait_for_health() {\n local max_attempts=6\n local attempt=1\n local delay=2\n\n while (( attempt <= max_attempts )); do\n status=$(docker-compose ps -q pal-mcp | xargs docker inspect -f \"{{.State.Health.Status}}\" 2>/dev/null || echo \"unavailable\")\n if [[ \"$status\" == \"healthy\" ]]; then\n return 0\n fi\n echo -e \"${YELLOW}Waiting for service to be healthy... (attempt $attempt/${max_attempts}, retrying in ${delay}s)${NC}\"\n sleep $delay\n delay=$(( delay * 2 ))\n attempt=$(( attempt + 1 ))\n done\n\n echo -e \"${RED}Service failed to become healthy after $max_attempts attempts${NC}\"\n echo -e \"${YELLOW}Checking logs:${NC}\"\n docker-compose logs pal-mcp\n exit 1\n}\n\n# Create logs directory if it doesn't exist\nmkdir -p logs\n\n# Stop existing containers\necho -e \"${GREEN}Stopping existing containers...${NC}\"\ndocker-compose down\n\n# Start the services\necho -e \"${GREEN}Starting PAL MCP Server...${NC}\"\ndocker-compose up -d\n\n# Wait for health check\necho -e \"${GREEN}Waiting for service to be healthy...${NC}\"\ntimeout 60 bash -c 'while [[ \"$(docker-compose ps -q pal-mcp | xargs docker inspect -f \"{{.State.Health.Status}}\")\" != \"healthy\" ]]; do sleep 2; done' || {\n wait_for_health\n echo -e \"${RED}Service failed to become healthy${NC}\"\n echo -e \"${YELLOW}Checking logs:${NC}\"\n docker-compose logs pal-mcp\n exit 1\n}\n\necho -e \"${GREEN}βœ“ PAL MCP Server deployed successfully${NC}\"\necho -e \"${GREEN}Service Status:${NC}\"\ndocker-compose ps\n\necho -e \"${GREEN}=== Deployment Complete ===${NC}\"\necho -e \"${YELLOW}Useful commands:${NC}\"\necho -e \" View logs: ${GREEN}docker-compose logs -f pal-mcp${NC}\"\necho -e \" Stop service: ${GREEN}docker-compose down${NC}\"\necho -e \" Restart service: ${GREEN}docker-compose restart pal-mcp${NC}\"\n" }, { "path": "docker/scripts/healthcheck.py", "content": "#!/usr/bin/env python3\n\"\"\"\nHealth check script for PAL MCP Server Docker container\n\"\"\"\n\nimport os\nimport subprocess\nimport sys\nfrom pathlib import Path\n\ntry:\n from utils.env import get_env\nexcept ImportError: # pragma: no cover - resolves module path inside container\n project_root = Path(__file__).resolve().parents[2]\n if str(project_root) not in sys.path:\n sys.path.insert(0, str(project_root))\n from utils.env import get_env # type: ignore[import-error]\n\n\ndef check_process():\n \"\"\"Check if the main server process is running\"\"\"\n result = subprocess.run([\"pgrep\", \"-f\", \"server.py\"], capture_output=True, text=True, timeout=10)\n if result.returncode == 0:\n return True\n print(f\"Process check failed: {result.stderr}\", file=sys.stderr)\n return False\n\n\ndef check_python_imports():\n \"\"\"Check if critical Python modules can be imported\"\"\"\n critical_modules = [\"mcp\", \"google.genai\", \"openai\", \"pydantic\", \"dotenv\"]\n\n for module in critical_modules:\n try:\n __import__(module)\n except ImportError as e:\n print(f\"Critical module {module} cannot be imported: {e}\", file=sys.stderr)\n return False\n except Exception as e:\n print(f\"Error importing {module}: {e}\", file=sys.stderr)\n return False\n return True\n\n\ndef check_log_directory():\n \"\"\"Check if logs directory is writable\"\"\"\n log_dir = \"/app/logs\"\n try:\n if not os.path.exists(log_dir):\n print(f\"Log directory {log_dir} does not exist\", file=sys.stderr)\n return False\n\n test_file = os.path.join(log_dir, \".health_check\")\n with open(test_file, \"w\") as f:\n f.write(\"health_check\")\n os.remove(test_file)\n return True\n except Exception as e:\n print(f\"Log directory check failed: {e}\", file=sys.stderr)\n return False\n\n\ndef check_environment():\n \"\"\"Check if essential environment variables are present\"\"\"\n # At least one API key should be present\n api_keys = [\n \"GEMINI_API_KEY\",\n \"GOOGLE_API_KEY\",\n \"OPENAI_API_KEY\",\n \"XAI_API_KEY\",\n \"DIAL_API_KEY\",\n \"OPENROUTER_API_KEY\",\n ]\n\n has_api_key = any(get_env(key) for key in api_keys)\n if not has_api_key:\n print(\"No API keys found in environment\", file=sys.stderr)\n return False\n\n # Validate API key formats (basic checks)\n for key in api_keys:\n value = get_env(key)\n if value:\n if len(value.strip()) < 10:\n print(f\"API key {key} appears too short or invalid\", file=sys.stderr)\n return False\n\n return True\n\n\ndef main():\n \"\"\"Main health check function\"\"\"\n checks = [\n (\"Process\", check_process),\n (\"Python imports\", check_python_imports),\n (\"Log directory\", check_log_directory),\n (\"Environment\", check_environment),\n ]\n\n failed_checks = []\n\n for check_name, check_func in checks:\n if not check_func():\n failed_checks.append(check_name)\n\n if failed_checks:\n print(f\"Health check failed: {', '.join(failed_checks)}\", file=sys.stderr)\n sys.exit(1)\n\n print(\"Health check passed\")\n sys.exit(0)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "docker-compose.yml", "content": "services:\n pal-mcp:\n build:\n context: .\n dockerfile: Dockerfile\n target: runtime\n image: pal-mcp-server:latest\n container_name: pal-mcp-server\n \n # Container labels for traceability\n labels:\n - \"com.pal-mcp.service=pal-mcp-server\"\n - \"com.pal-mcp.version=1.0.0\"\n - \"com.pal-mcp.environment=production\"\n - \"com.pal-mcp.description=AI-powered Model Context Protocol server\"\n \n # Environment variables\n environment:\n # Default model configuration\n - DEFAULT_MODEL=${DEFAULT_MODEL:-auto}\n \n # API Keys (use Docker secrets in production)\n - GEMINI_API_KEY=${GEMINI_API_KEY}\n - GOOGLE_API_KEY=${GOOGLE_API_KEY}\n - OPENAI_API_KEY=${OPENAI_API_KEY}\n - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}\n - XAI_API_KEY=${XAI_API_KEY}\n - DIAL_API_KEY=${DIAL_API_KEY}\n - DIAL_API_HOST=${DIAL_API_HOST}\n - DIAL_API_VERSION=${DIAL_API_VERSION}\n - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}\n - CUSTOM_API_URL=${CUSTOM_API_URL}\n - CUSTOM_API_KEY=${CUSTOM_API_KEY}\n - CUSTOM_MODEL_NAME=${CUSTOM_MODEL_NAME}\n \n # Logging configuration\n - LOG_LEVEL=${LOG_LEVEL:-INFO}\n - LOG_MAX_SIZE=${LOG_MAX_SIZE:-10MB}\n - LOG_BACKUP_COUNT=${LOG_BACKUP_COUNT:-5}\n \n # Advanced configuration\n - DEFAULT_THINKING_MODE_THINKDEEP=${DEFAULT_THINKING_MODE_THINKDEEP:-high}\n - DISABLED_TOOLS=${DISABLED_TOOLS}\n - MAX_MCP_OUTPUT_TOKENS=${MAX_MCP_OUTPUT_TOKENS}\n \n # Server configuration\n - PYTHONUNBUFFERED=1\n - PYTHONPATH=/app\n - TZ=${TZ:-UTC}\n \n # Volumes for persistent data\n volumes:\n - ./logs:/app/logs\n - pal-mcp-config:/app/conf\n - /etc/localtime:/etc/localtime:ro\n \n # Network configuration\n networks:\n - pal-network\n \n # Resource limits\n deploy:\n resources:\n limits:\n memory: 512M\n cpus: '0.5'\n reservations:\n memory: 256M\n cpus: '0.25'\n \n # Health check\n healthcheck:\n test: [\"CMD\", \"python\", \"/usr/local/bin/healthcheck.py\"]\n interval: 30s\n timeout: 10s\n retries: 3\n start_period: 40s\n \n # Restart policy\n restart: unless-stopped\n \n # Security\n security_opt:\n - no-new-privileges:true\n read_only: true\n tmpfs:\n - /tmp:noexec,nosuid,size=100m\n - /app/tmp:noexec,nosuid,size=50m\n\n# Named volumes\nvolumes:\n pal-mcp-config:\n driver: local\n\n# Networks\nnetworks:\n pal-network:\n driver: bridge\n ipam:\n config:\n - subnet: 172.20.0.0/16\n" }, { "path": "docs/adding_providers.md", "content": "# Adding a New Provider\n\nThis guide explains how to add support for a new AI model provider to the PAL MCP Server. The provider system is designed to be extensible and follows a simple pattern.\n\n## Overview\n\nEach provider:\n- Inherits from `ModelProvider` (base class) or `OpenAICompatibleProvider` (for OpenAI-compatible APIs)\n- Defines supported models using `ModelCapabilities` objects\n- Implements the minimal abstract hooks (`get_provider_type()` and `generate_content()`)\n- Gets wired into `configure_providers()` so environment variables control activation\n- Can leverage helper subclasses (e.g., `AzureOpenAIProvider`) when only client wiring differs\n\n### Intelligence score cheatsheet\n\nSet `intelligence_score` (1–20) when you want deterministic ordering in auto\nmode or the `listmodels` output. The runtime rank starts from this human score\nand adds smaller bonuses for context window, extended thinking, and other\nfeatures ([details here](model_ranking.md)).\n\n## Choose Your Implementation Path\n\n**Option A: Full Provider (`ModelProvider`)**\n- For APIs with unique features or custom authentication\n- Complete control over API calls and response handling\n- Populate `MODEL_CAPABILITIES`, implement `generate_content()` and `get_provider_type()`, and only override `get_all_model_capabilities()` / `_lookup_capabilities()` when your catalogue comes from a registry or remote source (override `count_tokens()` only when you have a provider-accurate tokenizer)\n\n**Option B: OpenAI-Compatible (`OpenAICompatibleProvider`)**\n- For APIs that follow OpenAI's chat completion format\n- Supply `MODEL_CAPABILITIES`, override `get_provider_type()`, and optionally adjust configuration (the base class handles alias resolution, validation, and request wiring)\n- Inherits all API handling automatically\n\n⚠️ **Important**: If you implement a custom `generate_content()`, call `_resolve_model_name()` before invoking the SDK so aliases (e.g. `\"gpt\"` β†’ `\"gpt-4\"`) resolve correctly. The shared implementations already do this for you.\n\n**Option C: Azure OpenAI (`AzureOpenAIProvider`)**\n- For Azure-hosted deployments of OpenAI models\n- Reuses the OpenAI-compatible pipeline but swaps in the `AzureOpenAI` client and a deployment mapping (canonical model β†’ deployment ID)\n- Define deployments in [`conf/azure_models.json`](../conf/azure_models.json) (or the file referenced by `AZURE_MODELS_CONFIG_PATH`).\n- Entries follow the [`ModelCapabilities`](../providers/shared/model_capabilities.py) schema and must include a `deployment` identifier.\n See [Azure OpenAI Configuration](azure_openai.md) for a step-by-step walkthrough.\n\n## Step-by-Step Guide\n\n### 1. Add Provider Type\n\nAdd your provider to the `ProviderType` enum in `providers/shared/provider_type.py`:\n\n```python\nclass ProviderType(Enum):\n GOOGLE = \"google\"\n OPENAI = \"openai\"\n EXAMPLE = \"example\" # Add this\n```\n\n### 2. Create the Provider Implementation\n\n#### Option A: Full Provider (Native Implementation)\n\nCreate `providers/example.py`:\n\n```python\n\"\"\"Example model provider implementation.\"\"\"\n\nimport logging\nfrom typing import Optional\n\nfrom .base import ModelProvider\nfrom .shared import (\n ModelCapabilities,\n ModelResponse,\n ProviderType,\n RangeTemperatureConstraint,\n)\n\nlogger = logging.getLogger(__name__)\n\n\nclass ExampleModelProvider(ModelProvider):\n \"\"\"Example model provider implementation.\"\"\"\n\n MODEL_CAPABILITIES = {\n \"example-large\": ModelCapabilities(\n provider=ProviderType.EXAMPLE,\n model_name=\"example-large\",\n friendly_name=\"Example Large\",\n intelligence_score=18,\n context_window=100_000,\n max_output_tokens=50_000,\n supports_extended_thinking=False,\n temperature_constraint=RangeTemperatureConstraint(0.0, 2.0, 0.7),\n description=\"Large model for complex tasks\",\n aliases=[\"large\", \"big\"],\n ),\n \"example-small\": ModelCapabilities(\n provider=ProviderType.EXAMPLE,\n model_name=\"example-small\",\n friendly_name=\"Example Small\",\n intelligence_score=14,\n context_window=32_000,\n max_output_tokens=16_000,\n temperature_constraint=RangeTemperatureConstraint(0.0, 2.0, 0.7),\n description=\"Fast model for simple tasks\",\n aliases=[\"small\", \"fast\"],\n ),\n }\n\n def __init__(self, api_key: str, **kwargs):\n super().__init__(api_key, **kwargs)\n # Initialize your API client here\n\n def get_all_model_capabilities(self) -> dict[str, ModelCapabilities]:\n return dict(self.MODEL_CAPABILITIES)\n\n def get_provider_type(self) -> ProviderType:\n return ProviderType.EXAMPLE\n\n def generate_content(\n self,\n prompt: str,\n model_name: str,\n system_prompt: Optional[str] = None,\n temperature: float = 0.7,\n max_output_tokens: Optional[int] = None,\n **kwargs,\n ) -> ModelResponse:\n resolved_name = self._resolve_model_name(model_name)\n\n # Your API call logic here\n # response = your_api_client.generate(...)\n\n return ModelResponse(\n content=\"Generated response\",\n usage={\"input_tokens\": 100, \"output_tokens\": 50, \"total_tokens\": 150},\n model_name=resolved_name,\n friendly_name=\"Example\",\n provider=ProviderType.EXAMPLE,\n )\n```\n\n`ModelProvider.get_capabilities()` automatically resolves aliases, enforces the\nshared restriction service, and returns the correct `ModelCapabilities`\ninstance. Override `_lookup_capabilities()` only when you source capabilities\nfrom a registry or remote API. `ModelProvider.count_tokens()` uses a simple\n4-characters-per-token estimate so providers work out of the boxβ€”override it\nonly when you can call the provider's real tokenizer (for example, the\nOpenAI-compatible base class integrates `tiktoken`).\n\n#### Option B: OpenAI-Compatible Provider (Simplified)\n\nFor OpenAI-compatible APIs:\n\n```python\n\"\"\"Example OpenAI-compatible provider.\"\"\"\n\nfrom typing import Optional\n\nfrom .openai_compatible import OpenAICompatibleProvider\nfrom .shared import (\n ModelCapabilities,\n ModelResponse,\n ProviderType,\n RangeTemperatureConstraint,\n)\n\n\nclass ExampleProvider(OpenAICompatibleProvider):\n \"\"\"Example OpenAI-compatible provider.\"\"\"\n \n FRIENDLY_NAME = \"Example\"\n \n # Define models using ModelCapabilities (consistent with other providers)\n MODEL_CAPABILITIES = {\n \"example-model-large\": ModelCapabilities(\n provider=ProviderType.EXAMPLE,\n model_name=\"example-model-large\",\n friendly_name=\"Example Large\",\n context_window=128_000,\n max_output_tokens=64_000,\n temperature_constraint=RangeTemperatureConstraint(0.0, 2.0, 0.7),\n aliases=[\"large\", \"big\"],\n ),\n }\n \n def __init__(self, api_key: str, **kwargs):\n kwargs.setdefault(\"base_url\", \"https://api.example.com/v1\")\n super().__init__(api_key, **kwargs)\n\n def get_provider_type(self) -> ProviderType:\n return ProviderType.EXAMPLE\n```\n\n`OpenAICompatibleProvider` already exposes the declared models via\n`MODEL_CAPABILITIES`, resolves aliases through the shared base pipeline, and\nenforces restrictions. Most subclasses only need to provide the class metadata\nshown above.\n\n### 3. Register Your Provider\n\nAdd environment variable mapping in `providers/registry.py`:\n\n```python\n# In _get_api_key_for_provider (providers/registry.py), add:\n ProviderType.EXAMPLE: \"EXAMPLE_API_KEY\",\n```\n\nAdd to `server.py`:\n\n1. **Import your provider**:\n```python\nfrom providers.example import ExampleModelProvider\n```\n\n2. **Add to `configure_providers()` function**:\n```python\n# Check for Example API key\nexample_key = os.getenv(\"EXAMPLE_API_KEY\")\nif example_key:\n ModelProviderRegistry.register_provider(ProviderType.EXAMPLE, ExampleModelProvider)\n logger.info(\"Example API key found - Example models available\")\n```\n\n3. **Add to provider priority** (edit `ModelProviderRegistry.PROVIDER_PRIORITY_ORDER` in `providers/registry.py`): insert your provider in the list at the appropriate point in the cascade of native β†’ custom β†’ catch-all providers.\n\n### 4. Environment Configuration\n\nAdd to your `.env` file:\n```bash\n# Your provider's API key\nEXAMPLE_API_KEY=your_api_key_here\n\n# Optional: Disable specific tools\nDISABLED_TOOLS=debug,tracer\n\n# Optional (OpenAI-compatible providers): Restrict accessible models\nEXAMPLE_ALLOWED_MODELS=example-model-large,example-model-small\n```\n\nFor Azure OpenAI deployments:\n\n```bash\nAZURE_OPENAI_API_KEY=your_azure_openai_key_here\nAZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/\n# Models are defined in conf/azure_models.json (or AZURE_MODELS_CONFIG_PATH)\n# AZURE_OPENAI_API_VERSION=2024-02-15-preview\n# AZURE_OPENAI_ALLOWED_MODELS=gpt-4o,gpt-4o-mini\n# AZURE_MODELS_CONFIG_PATH=/absolute/path/to/custom_azure_models.json\n```\n\nYou can also define Azure models in [`conf/azure_models.json`](../conf/azure_models.json) (the bundled file is empty so you can copy it safely). Each entry mirrors the `ModelCapabilities` schema and must include a `deployment` field. Set `AZURE_MODELS_CONFIG_PATH` if you maintain a custom copy outside the repository.\n\n**Note**: The `description` field in `ModelCapabilities` helps Claude choose the best model in auto mode.\n\n### 5. Test Your Provider\n\nCreate basic tests to verify your implementation:\n\n```python\n# Test capabilities\nprovider = ExampleModelProvider(\"test-key\")\ncapabilities = provider.get_capabilities(\"large\")\nassert capabilities.context_window > 0\nassert capabilities.provider == ProviderType.EXAMPLE\n```\n\n\n\n## Key Concepts\n\n### Provider Priority\nWhen a user requests a model, providers are checked in priority order:\n1. **Native providers** (Gemini, OpenAI, Example) - handle their specific models\n2. **Custom provider** - handles local/self-hosted models \n3. **OpenRouter** - catch-all for everything else\n\n### Model Validation\n`ModelProvider.validate_model_name()` delegates to `get_capabilities()` so most\nproviders can rely on the shared implementation. Override it only when you need\nto opt out of that pipelineβ€”for example, `CustomProvider` declines OpenRouter\nmodels so they fall through to the dedicated OpenRouter provider.\n\n### Model Aliases\nAliases declared on `ModelCapabilities` are applied automatically via\n`_resolve_model_name()`, and both the validation and request flows call it\nbefore touching your SDK. Override `generate_content()` only when your provider\nneeds additional alias handling beyond the shared behaviour.\n\n## Important Notes\n\n## Best Practices\n\n- **Be specific in model validation** - only accept models you actually support\n- **Use ModelCapabilities objects** consistently (like Gemini provider)\n- **Include descriptive aliases** for better user experience \n- **Add error handling** and logging for debugging\n- **Test with real API calls** to verify everything works\n- **Follow the existing patterns** in `providers/gemini.py` and `providers/custom.py`\n\n## Quick Checklist\n\n- [ ] Added to `ProviderType` enum in `providers/shared/provider_type.py`\n- [ ] Created provider class with all required methods\n- [ ] Added API key mapping in `providers/registry.py`\n- [ ] Added to provider priority order in `registry.py`\n- [ ] Imported and registered in `server.py`\n- [ ] Basic tests verify model validation and capabilities\n- [ ] Tested with real API calls\n\n## Examples\n\nSee existing implementations:\n- **Full provider**: `providers/gemini.py`\n- **OpenAI-compatible**: `providers/custom.py`\n- **Base classes**: `providers/base.py`\n" }, { "path": "docs/adding_tools.md", "content": "# Adding Tools to PAL MCP Server\n\nPAL MCP tools are Python classes that inherit from the shared infrastructure in `tools/shared/base_tool.py`.\nEvery tool must provide a request model (Pydantic), a system prompt, and the methods the base class marks as\nabstract. The quickest path to a working tool is to copy an existing implementation that matches your use case\n(`tools/chat.py` for simple request/response tools, `tools/consensus.py` or `tools/codereview.py` for workflows).\nThis document captures the minimal steps required to add a new tool without drifting from the current codebase.\n\n## 1. Pick the Tool Architecture\n\nPAL supports two architectures, implemented in `tools/simple/base.py` and `tools/workflow/base.py`.\n\n- **SimpleTool** (`SimpleTool`): single MCP call – request comes in, you build one prompt, call the model, return.\n The base class handles schema generation, conversation threading, file loading, temperature bounds, retries,\n and response formatting hooks.\n- **WorkflowTool** (`WorkflowTool`): multi-step workflows driven by `BaseWorkflowMixin`. The tool accumulates\n findings across steps, forces Claude to pause between investigations, and optionally calls an expert model at\n the end. Use this whenever you need structured multi-step work (debug, code review, consensus, etc.).\n\nIf you are unsure, compare `tools/chat.py` (SimpleTool) and `tools/consensus.py` (WorkflowTool) to see the patterns.\n\n## 2. Common Responsibilities\n\nRegardless of architecture, subclasses of `BaseTool` must provide:\n\n- `get_name()`: unique string identifier used in the MCP registry.\n- `get_description()`: concise, action-oriented summary for clients.\n- `get_system_prompt()`: import your prompt from `systemprompts/` and return it.\n- `get_input_schema()`: leverage the schema builders (`SchemaBuilder` or `WorkflowSchemaBuilder`) or override to\n match an existing contract exactly.\n- `get_request_model()`: return the Pydantic model used to validate the incoming arguments.\n- `async prepare_prompt(...)`: assemble the content sent to the model. You can reuse helpers like\n `prepare_chat_style_prompt` or `build_standard_prompt`.\n\nThe base class already handles model selection (`ToolModelCategory`), conversation memory, token budgeting, safety\nfailures, retries, and serialization. Override hooks like `get_default_temperature`, `get_model_category`, or\n`format_response` only when you need behaviour different from the defaults.\n\n## 3. Implementing a Simple Tool\n\n1. **Define a request model** that inherits from `tools.shared.base_models.ToolRequest` to describe the fields and\n validation rules for your tool.\n2. **Implement the tool class** by inheriting from `SimpleTool` and overriding the required methods. Most tools can\n rely on `SchemaBuilder` and the shared field constants already exposed on `SimpleTool`.\n\n```python\nfrom pydantic import Field\nfrom systemprompts import CHAT_PROMPT\nfrom tools.shared.base_models import ToolRequest\nfrom tools.simple.base import SimpleTool\n\nclass ChatRequest(ToolRequest):\n prompt: str = Field(..., description=\"Your question or idea.\")\n absolute_file_paths: list[str] | None = Field(default_factory=list)\n working_directory_absolute_path: str = Field(\n ...,\n description=\"Absolute path to an existing directory where generated code can be saved.\",\n )\n\nclass ChatTool(SimpleTool):\n def get_name(self) -> str: # required by BaseTool\n return \"chat\"\n\n def get_description(self) -> str:\n return \"General chat and collaborative thinking partner.\"\n\n def get_system_prompt(self) -> str:\n return CHAT_PROMPT\n\n def get_request_model(self):\n return ChatRequest\n\n def get_tool_fields(self) -> dict[str, dict[str, object]]:\n return {\n \"prompt\": {\"type\": \"string\", \"description\": \"Your question.\"},\n \"absolute_file_paths\": SimpleTool.FILES_FIELD,\n \"working_directory_absolute_path\": {\n \"type\": \"string\",\n \"description\": \"Absolute path to an existing directory for generated code artifacts.\",\n },\n }\n\n def get_required_fields(self) -> list[str]:\n return [\"prompt\", \"working_directory_absolute_path\"]\n\n async def prepare_prompt(self, request: ChatRequest) -> str:\n return self.prepare_chat_style_prompt(request)\n```\n\nOnly implement `get_input_schema()` manually if you must preserve an existing schema contract (see\n`tools/chat.py` for an example). Otherwise `SimpleTool.get_input_schema()` merges your field definitions with the\ncommon parameters (temperature, model, continuation_id, etc.).\n\n## 4. Implementing a Workflow Tool\n\nWorkflow tools extend `WorkflowTool`, which mixes in `BaseWorkflowMixin` for step tracking and expert analysis.\n\n1. **Create a request model** that inherits from `tools.shared.base_models.WorkflowRequest` (or a subclass) and add\n any tool-specific fields or validators. Examples: `CodeReviewRequest`, `ConsensusRequest`.\n2. **Override the workflow hooks** to steer the investigation. At minimum you must implement\n `get_required_actions(...)`; override `should_call_expert_analysis(...)` and\n `prepare_expert_analysis_context(...)` when the expert model call should happen conditionally.\n3. **Expose the schema** either by returning `WorkflowSchemaBuilder.build_schema(...)` (the default implementation on\n `WorkflowTool` already does this) or by overriding `get_input_schema()` if you need custom descriptions/enums.\n\n```python\nfrom pydantic import Field\nfrom systemprompts import CONSENSUS_PROMPT\nfrom tools.shared.base_models import WorkflowRequest\nfrom tools.workflow.base import WorkflowTool\n\nclass ConsensusRequest(WorkflowRequest):\n models: list[dict] = Field(..., description=\"Models to consult (with optional stance).\")\n\nclass ConsensusTool(WorkflowTool):\n def get_name(self) -> str:\n return \"consensus\"\n\n def get_description(self) -> str:\n return \"Multi-model consensus workflow with expert synthesis.\"\n\n def get_system_prompt(self) -> str:\n return CONSENSUS_PROMPT\n\n def get_workflow_request_model(self):\n return ConsensusRequest\n\n def get_required_actions(self, step_number: int, confidence: str, findings: str, total_steps: int, request=None) -> list[str]:\n if step_number == 1:\n return [\"Write the shared proposal all models will evaluate.\"]\n return [\"Summarize the latest model response before moving on.\"]\n\n def should_call_expert_analysis(self, consolidated_findings, request=None) -> bool:\n return not (request and request.next_step_required)\n\n def prepare_expert_analysis_context(self, consolidated_findings) -> str:\n return \"\\n\".join(consolidated_findings.findings)\n```\n\n`WorkflowTool` already records work history, merges findings, and handles continuation IDs. Use helpers such as\n`get_standard_required_actions` when you want default guidance, and override `requires_expert_analysis()` if the tool\nnever calls out to the assistant model.\n\n## 5. Register the Tool\n\n1. **Create or reuse a system prompt** in `systemprompts/your_tool_prompt.py` and export it from\n `systemprompts/__init__.py`.\n2. **Expose the tool class** from `tools/__init__.py` so that `server.py` can import it.\n3. **Add an instance to the `TOOLS` dictionary** in `server.py`. This makes the tool callable via MCP.\n4. **(Optional) Add a prompt template** to `PROMPT_TEMPLATES` in `server.py` if you want clients to show a canned\n launch command.\n5. Confirm that `DISABLED_TOOLS` environment variable handling covers the new tool if you need to toggle it.\n\n## 6. Validate the Tool\n\n- Run unit tests that cover any new request/response logic: `python -m pytest tests/ -v -m \"not integration\"`.\n- Add a simulator scenario in `simulator_tests/communication_simulator_test.py` to exercise the tool end-to-end and\n run it with `python communication_simulator_test.py --individual ` or `--quick` for the fast smoke suite.\n- If the tool interacts with external providers or multiple models, consider integration coverage via\n `./run_integration_tests.sh --with-simulator`.\n\nFollowing the steps above keeps new tools aligned with the existing infrastructure and avoids drift between the\ndocumentation and the actual base classes.\n" }, { "path": "docs/advanced-usage.md", "content": "# Advanced Usage Guide\n\nThis guide covers advanced features, configuration options, and workflows for power users of the PAL MCP server.\n\n## Table of Contents\n\n- [Model Configuration](#model-configuration)\n- [Model Usage Restrictions](#model-usage-restrictions)\n- [Thinking Modes](#thinking-modes)\n- [Tool Parameters](#tool-parameters)\n- [Context Revival: AI Memory Beyond Context Limits](#context-revival-ai-memory-beyond-context-limits)\n- [Collaborative Workflows](#collaborative-workflows)\n- [Working with Large Prompts](#working-with-large-prompts)\n- [Vision Support](#vision-support)\n- [Web Search Integration](#web-search-integration)\n- [System Prompts](#system-prompts)\n\n## Model Configuration\n\n**For basic configuration**, see the [Configuration Guide](configuration.md) which covers API keys, model selection, and environment variables.\n\nThis section focuses on **advanced model usage patterns** for power users:\n\n**Per-Request Model Override:**\nRegardless of your default configuration, you can specify models per request:\n- \"Use **pro** for deep security analysis of auth.py\"\n- \"Use **flash** to quickly format this code\"\n- \"Use **o3** to debug this logic error\"\n- \"Review with **o4-mini** for balanced analysis\"\n- \"Use **gpt4.1** for comprehensive codebase analysis\"\n\n**Claude's Auto Mode Decision Matrix:**\n\n| Model | Provider | Context | Strengths | Auto Mode Usage |\n|-------|----------|---------|-----------|------------------|\n| **`pro`** (Gemini 3.0 Pro) | Google | 1M tokens | Extended thinking (up to 32K tokens), deep analysis | Complex architecture, security reviews, deep debugging |\n| **`flash`** (Gemini 2.5 Flash) | Google | 1M tokens | Ultra-fast responses with thinking | Quick checks, formatting, simple analysis |\n| **`flash-2.0`** (Gemini 2.0 Flash) | Google | 1M tokens | Latest fast model with audio/video support | Quick analysis with multimodal input |\n| **`flashlite`** (Gemini 2.0 Flash Lite) | Google | 1M tokens | Lightweight text-only model | Fast text processing without vision |\n| **`o3`** | OpenAI | 200K tokens | Strong logical reasoning | Debugging logic errors, systematic analysis |\n| **`o3-mini`** | OpenAI | 200K tokens | Balanced speed/quality | Moderate complexity tasks |\n| **`o4-mini`** | OpenAI | 200K tokens | Latest reasoning model | Optimized for shorter contexts |\n| **`gpt4.1`** | OpenAI | 1M tokens | Latest GPT-4 with extended context | Large codebase analysis, comprehensive reviews |\n| **`gpt5.2`** (GPT-5.2) | OpenAI | 400K tokens | Flagship reasoning model with configurable thinking effort | Complex problems, balanced agent/coding flows |\n| **`gpt5.1-codex`** (GPT-5.1 Codex) | OpenAI | 400K tokens | Agentic coding specialization (Responses API) | Advanced coding tasks, structured code generation |\n| **`gpt5.1-codex-mini`** (GPT-5.1 Codex mini) | OpenAI | 400K tokens | Cost-efficient Codex variant with streaming | Balanced coding tasks, cost-conscious development |\n| **`gpt5`** (GPT-5) | OpenAI | 400K tokens | Advanced model with reasoning support | Complex problems requiring advanced reasoning |\n| **`gpt5-mini`** (GPT-5 Mini) | OpenAI | 400K tokens | Efficient variant with reasoning | Balanced performance and capability |\n| **`gpt5-nano`** (GPT-5 Nano) | OpenAI | 400K tokens | Fastest, cheapest GPT-5 variant | Summarization and classification tasks |\n| **`grok-4`** | X.AI | 256K tokens | Latest flagship Grok model with reasoning, vision | Complex analysis, reasoning tasks |\n| **`grok-4.1-fast-reasoning`** | X.AI | 2M tokens | High-performance Grok 4.1 Fast Reasoning with vision | Fast responses and light reasoning |\n| **`llama`** (Llama 3.2) | Custom/Local | 128K tokens | Local inference, privacy | On-device analysis, cost-free processing |\n| **Any model** | OpenRouter | Varies | Access to GPT-4, Claude, Llama, etc. | User-specified or based on task requirements |\n\n**Mix & Match Providers:** Use multiple providers simultaneously! Set both `OPENROUTER_API_KEY` and `CUSTOM_API_URL` to access \ncloud models (expensive/powerful) AND local models (free/private) in the same conversation.\n\n**Model Capabilities:**\n- **Gemini Models**: Support thinking modes (minimal to max), web search, 1M context\n - **Pro 3.0**: Deep analysis with max 32K thinking tokens\n - **Flash 2.5**: Ultra-fast with thinking support (24K thinking tokens)\n - **Flash 2.0**: Latest fast model with audio/video input (24K thinking tokens)\n - **Flash Lite 2.0**: Text-only lightweight model (no thinking support)\n- **O3/O4 Models**: Excellent reasoning, systematic analysis, 200K context\n- **GPT-4.1**: Extended context window (1M tokens), general capabilities\n- **GPT-5.2 Series**: Latest flagship reasoning models, 400K context\n - **GPT-5.2**: Flagship model with configurable thinking effort and vision\n - **GPT-5.1 Codex**: Agentic coding specialization (Responses API, non-streaming)\n - **GPT-5.1 Codex mini**: Cost-efficient Codex variant with streaming support\n- **GPT-5 Series**: Advanced reasoning models, 400K context\n - **GPT-5**: Full-featured with reasoning support and vision\n - **GPT-5 Mini**: Balanced efficiency and capability\n - **GPT-5 Nano**: Optimized for fast, low-cost tasks\n- **Grok-4 / Grok-4.1-fast-reasoning**: Extended thinking support, vision capabilities (256K / 2M context)\n\n## Model Usage Restrictions\n\n**For complete restriction configuration**, see the [Configuration Guide](configuration.md#model-usage-restrictions).\n\n**Advanced Restriction Strategies:**\n\n**Cost Control Examples:**\n```env\n# Development: Allow experimentation\nGOOGLE_ALLOWED_MODELS=flash,pro\nOPENAI_ALLOWED_MODELS=o4-mini,o3-mini\n\n# Production: Cost-optimized \nGOOGLE_ALLOWED_MODELS=flash\nOPENAI_ALLOWED_MODELS=o4-mini\n\n# High-performance: Quality over cost\nGOOGLE_ALLOWED_MODELS=pro\nOPENAI_ALLOWED_MODELS=o3,o4-mini\n```\n\n**Important Notes:**\n- Restrictions apply to all usage including auto mode\n- `OPENROUTER_ALLOWED_MODELS` only affects models defined in `conf/openrouter_models.json`\n- Custom local models (from `conf/custom_models.json`) are not affected by OpenRouter restrictions\n\n## Thinking Modes\n\n**Claude automatically manages thinking modes based on task complexity**, but you can also manually control Gemini's reasoning depth to balance between response quality and token consumption. Each thinking mode uses a different amount of tokens, directly affecting API costs and response time.\n\n### Thinking Modes & Token Budgets\n\nThese only apply to models that support customizing token usage for extended thinking, such as Gemini 3.0 Pro.\n\n| Mode | Token Budget | Use Case | Cost Impact |\n|------|-------------|----------|-------------|\n| `minimal` | 128 tokens | Simple, straightforward tasks | Lowest cost |\n| `low` | 2,048 tokens | Basic reasoning tasks | 16x more than minimal |\n| `medium` | 8,192 tokens | **Default** - Most development tasks | 64x more than minimal |\n| `high` | 16,384 tokens | Complex problems requiring thorough analysis (default for `thinkdeep`) | 128x more than minimal |\n| `max` | 32,768 tokens | Exhaustive reasoning | 256x more than minimal |\n\n### How to Use Thinking Modes\n\n**Claude automatically selects appropriate thinking modes**, but you can override this by explicitly requesting a specific mode in your prompts. Remember: higher thinking modes = more tokens = higher cost but better quality:\n\n#### Optimizing Token Usage & Costs\n\n**In most cases, let Claude automatically manage thinking modes** for optimal balance of cost and quality. Override manually when you have specific requirements:\n\n**Use lower modes (`minimal`, `low`) to save tokens when:**\n- Doing simple formatting or style checks\n- Getting quick explanations of basic concepts\n- Working with straightforward code\n- You need faster responses\n- Working within tight token budgets\n\n**Use higher modes (`high`, `max`) when quality justifies the cost:**\n- Debugging complex issues (worth the extra tokens to find root causes)\n- Reviewing security-critical code (cost of tokens < cost of vulnerabilities)\n- Analyzing system architecture (comprehensive analysis saves development time)\n- Finding subtle bugs or edge cases\n- Working on performance optimizations\n\n**Token Cost Examples:**\n- `minimal` (128 tokens) vs `max` (32,768 tokens) = 256x difference in thinking tokens\n- For a simple formatting check, using `minimal` instead of the default `medium` saves ~8,000 thinking tokens\n- For critical security reviews, the extra tokens in `high` or `max` mode are a worthwhile investment\n\n**Examples by scenario:**\n```\n# Quick style check with o3\n\"Use flash to review formatting in utils.py\"\n\n# Security audit with o3\n\"Get o3 to do a security review of auth/ with thinking mode high\"\n\n# Complex debugging, letting claude pick the best model\n\"Use pal to debug this race condition with max thinking mode\"\n\n# Architecture analysis with Gemini 3.0 Pro\n\"Analyze the entire src/ directory architecture with high thinking using pro\"\n```\n\n## Tool Parameters\n\nAll tools that work with files support **both individual files and entire directories**. The server automatically expands directories, filters for relevant code files, and manages token limits.\n\n### File-Processing Tools\n\n**`analyze`** - Analyze files or directories\n- `files`: List of file paths or directories (required)\n- `question`: What to analyze (required) \n- `model`: auto|pro|flash|flash-2.0|flashlite|o3|o3-mini|o4-mini|gpt4.1|gpt5.2|gpt5.1-codex|gpt5.1-codex-mini|gpt5|gpt5-mini|gpt5-nano (default: server default)\n- `analysis_type`: architecture|performance|security|quality|general\n- `output_format`: summary|detailed|actionable\n- `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)\n- **Web search capability**: The assistant now automatically requests web searches when it needs current documentation or best practicesβ€”no parameter required\n\n```\n\"Analyze the src/ directory for architectural patterns\" (auto mode picks best model)\n\"Use flash to quickly analyze main.py and tests/ to understand test coverage\" \n\"Use o3 for logical analysis of the algorithm in backend/core.py\"\n\"Use pro for deep analysis of the entire backend/ directory structure\"\n```\n\n**`codereview`** - Review code files or directories\n- `files`: List of file paths or directories (required)\n- `model`: auto|pro|flash|flash-2.0|flashlite|o3|o3-mini|o4-mini|gpt4.1|gpt5.2|gpt5.1-codex|gpt5.1-codex-mini|gpt5|gpt5-mini|gpt5-nano (default: server default)\n- `review_type`: full|security|performance|quick\n- `focus_on`: Specific aspects to focus on\n- `standards`: Coding standards to enforce\n- `severity_filter`: critical|high|medium|all\n- `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)\n\n```\n\"Review the entire api/ directory for security issues\" (auto mode picks best model)\n\"Use pro to review auth/ for deep security analysis\"\n\"Use o3 to review logic in algorithms/ for correctness\"\n\"Use flash to quickly review src/ with focus on performance, only show critical issues\"\n```\n\n**`debug`** - Debug with file context\n- `error_description`: Description of the issue (required)\n- `model`: auto|pro|flash|flash-2.0|flashlite|o3|o3-mini|o4-mini|gpt4.1|gpt5.2|gpt5.1-codex|gpt5.1-codex-mini|gpt5|gpt5-mini|gpt5-nano (default: server default)\n- `error_context`: Stack trace or logs\n- `files`: Files or directories related to the issue\n- `runtime_info`: Environment details\n- `previous_attempts`: What you've tried\n- `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)\n- **Web search capability**: Automatically initiates searches for relevant error messages or recent fixes when needed\n\n```\n\"Debug this logic error with context from backend/\" (auto mode picks best model)\n\"Use o3 to debug this algorithm correctness issue\"\n\"Use pro to debug this complex architecture problem\"\n```\n\n**`thinkdeep`** - Extended analysis with file context\n- `current_analysis`: Your current thinking (required)\n- `model`: auto|pro|flash|flash-2.0|flashlite|o3|o3-mini|o4-mini|gpt4.1|gpt5.2|gpt5.1-codex|gpt5.1-codex-mini|gpt5|gpt5-mini|gpt5-nano (default: server default)\n- `problem_context`: Additional context\n- `focus_areas`: Specific aspects to focus on\n- `files`: Files or directories for context\n- `thinking_mode`: minimal|low|medium|high|max (default: max, Gemini only)\n- **Web search capability**: Automatically calls for research when architecture references or external insights are required\n\n```\n\"Think deeper about my design with reference to src/models/\" (auto mode picks best model)\n\"Use pro to think deeper about this architecture with extended thinking\"\n\"Use o3 to think deeper about the logical flow in this algorithm\"\n```\n\n**`testgen`** - Comprehensive test generation with edge case coverage\n- `files`: Code files or directories to generate tests for (required)\n- `prompt`: Description of what to test, testing objectives, and scope (required)\n- `model`: auto|pro|flash|flash-2.0|flashlite|o3|o3-mini|o4-mini|gpt4.1|gpt5.2|gpt5.1-codex|gpt5.1-codex-mini|gpt5|gpt5-mini|gpt5-nano (default: server default)\n- `test_examples`: Optional existing test files as style/pattern reference\n- `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)\n\n```\n\"Generate tests for User.login() method with edge cases\" (auto mode picks best model)\n\"Use pro to generate comprehensive tests for src/payment.py with max thinking mode\"\n\"Use o3 to generate tests for algorithm correctness in sort_functions.py\"\n\"Generate tests following patterns from tests/unit/ for new auth module\"\n```\n\n**`refactor`** - Intelligent code refactoring with decomposition focus\n- `files`: Code files or directories to analyze for refactoring opportunities (required)\n- `prompt`: Description of refactoring goals, context, and specific areas of focus (required)\n- `refactor_type`: codesmells|decompose|modernize|organization (required)\n- `model`: auto|pro|flash|flash-2.0|flashlite|o3|o3-mini|o4-mini|gpt4.1|gpt5.2|gpt5.1-codex|gpt5.1-codex-mini|gpt5|gpt5-mini|gpt5-nano (default: server default)\n- `focus_areas`: Specific areas to focus on (e.g., 'performance', 'readability', 'maintainability', 'security')\n- `style_guide_examples`: Optional existing code files to use as style/pattern reference\n- `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)\n- `continuation_id`: Thread continuation ID for multi-turn conversations\n\n```\n\"Analyze legacy codebase for decomposition opportunities\" (auto mode picks best model)\n\"Use pro to identify code smells in the authentication module with max thinking mode\"\n\"Use pro to modernize this JavaScript code following examples/modern-patterns.js\"\n\"Refactor src/ for better organization, focus on maintainability and readability\"\n```\n\n## Context Revival: AI Memory Beyond Context Limits\n\n**The PAL MCP Server's most revolutionary feature** is its ability to maintain conversation context even after Claude's memory resets. This enables truly persistent AI collaboration across multiple sessions and context boundaries.\n\n### **The Breakthrough**\n\nEven when Claude's context resets or compacts, conversations can continue seamlessly because other models (O3, Gemini) have access to the complete conversation history stored in memory and can \"remind\" Claude of everything that was discussed.\n\n### Key Benefits\n\n- **Persistent conversations** across Claude's context resets\n- **Cross-tool continuation** with full context preservation\n- **Multi-session workflows** that maintain complete history\n- **True AI orchestration** where models can build on each other's work\n- **Seamless handoffs** between different tools and models\n\n### Quick Example\n\n```\nSession 1: \"Design a RAG system with gemini pro\"\n[Claude's context resets]\nSession 2: \"Continue our RAG discussion with o3\"\nβ†’ O3 receives the full history and reminds Claude of everything discussed\n```\n\n**πŸ“– [Read the complete Context Revival guide](context-revival.md)** for detailed examples, technical architecture, configuration options, and best practices.\n\n**See also:** [AI-to-AI Collaboration Guide](ai-collaboration.md) for multi-model coordination and conversation threading.\n\n## Collaborative Workflows\n\n### Design β†’ Review β†’ Implement\n```\nThink hard about designing and developing a fun calculator app in swift. Review your design plans with o3, taking in\ntheir suggestions but keep the feature-set realistic and doable without adding bloat. Begin implementing and in between\nimplementation, get a codereview done by Gemini Pro and chat with Flash if you need to for creative directions. \n```\n\n### Code β†’ Review β†’ Fix\n```\nImplement a new screen where the locations taken from the database display on a map, with pins falling from\nthe top and landing with animation. Once done, codereview with gemini pro and o3 both and ask them to critique your\nwork. Fix medium to critical bugs / concerns / issues and show me the final product\n```\n\n### Debug β†’ Analyze β†’ Solution β†’ Precommit Check β†’ Publish\n```\nTake a look at these log files saved under subfolder/diagnostics.log there's a bug where the user says the app\ncrashes at launch. Think hard and go over each line, tallying it with corresponding code within the project. After\nyou've performed initial investigation, ask gemini pro to analyze the log files and the related code where you \nsuspect lies the bug and then formulate and implement a bare minimal fix. Must not regress. Perform a precommit\nwith pal in the end using gemini pro to confirm we're okay to publish the fix \n```\n\n### Refactor β†’ Review β†’ Implement β†’ Test\n```\nUse pal to analyze this legacy authentication module for decomposition opportunities. The code is getting hard to \nmaintain and we need to break it down. Use gemini pro with high thinking mode to identify code smells and suggest \na modernization strategy. After reviewing the refactoring plan, implement the changes step by step and then \ngenerate comprehensive tests with pal to ensure nothing breaks.\n```\n\n### Tool Selection Guidance\nTo help choose the right tool for your needs:\n\n**Decision Flow:**\n1. **Have a specific error/exception?** β†’ Use `debug`\n2. **Want to find bugs/issues in code?** β†’ Use `codereview`\n3. **Want to understand how code works?** β†’ Use `analyze`\n4. **Need comprehensive test coverage?** β†’ Use `testgen`\n5. **Want to refactor/modernize code?** β†’ Use `refactor`\n6. **Have analysis that needs extension/validation?** β†’ Use `thinkdeep`\n7. **Want to brainstorm or discuss?** β†’ Use `chat`\n\n**Key Distinctions:**\n- `analyze` vs `codereview`: analyze explains, codereview prescribes fixes\n- `chat` vs `thinkdeep`: chat is open-ended, thinkdeep extends specific analysis\n- `debug` vs `codereview`: debug diagnoses runtime errors, review finds static issues\n- `testgen` vs `debug`: testgen creates test suites, debug just finds issues and recommends solutions\n- `refactor` vs `codereview`: refactor suggests structural improvements, codereview finds bugs/issues\n- `refactor` vs `analyze`: refactor provides actionable refactoring steps, analyze provides understanding\n\n## Vision Support\n\nThe PAL MCP server supports vision-capable models for analyzing images, diagrams, screenshots, and visual content. Vision support works seamlessly with all tools and conversation threading.\n\n**Supported Models:**\n- **Gemini 3.0 Pro & Flash**: Excellent for diagrams, architecture analysis, UI mockups (up to 20MB total)\n- **OpenAI O3/O4 series**: Strong for visual debugging, error screenshots (up to 20MB total)\n- **Claude models via OpenRouter**: Good for code screenshots, visual analysis (up to 5MB total)\n- **Custom models**: Support varies by model, with 40MB maximum enforced for abuse prevention\n\n**Usage Examples:**\n```bash\n# Debug with error screenshots\n\"Use pal to debug this error with the stack trace screenshot and error.py\"\n\n# Architecture analysis with diagrams \n\"Analyze this system architecture diagram with gemini pro for bottlenecks\"\n\n# UI review with mockups\n\"Chat with flash about this UI mockup - is the layout intuitive?\"\n\n# Code review with visual context\n\"Review this authentication code along with the error dialog screenshot\"\n```\n\n**Image Formats Supported:**\n- **Images**: JPG, PNG, GIF, WebP, BMP, SVG, TIFF\n- **Documents**: PDF (where supported by model)\n- **Data URLs**: Base64-encoded images from Claude\n\n**Key Features:**\n- **Automatic validation**: File type, magic bytes, and size validation\n- **Conversation context**: Images persist across tool switches and continuation\n- **Budget management**: Automatic dropping of old images when limits exceeded\n- **Model capability-aware**: Only sends images to vision-capable models\n\n**Best Practices:**\n- Describe images when including them: \"screenshot of login error\", \"system architecture diagram\"\n- Use appropriate models: Gemini for complex diagrams, O3 for debugging visuals\n- Consider image sizes: Larger images consume more of the model's capacity\n\n## Working with Large Prompts\n\nThe MCP protocol has a combined request+response limit of approximately 25K tokens. This server intelligently works around this limitation by automatically handling large prompts as files:\n\n**How it works:**\n1. When you send a prompt larger than the configured limit (default: 50K characters ~10-12K tokens), the server detects this\n2. It responds with a special status asking Claude to save the prompt to a file named `prompt.txt`\n3. Claude saves the prompt and resends the request with the file path instead\n4. The server reads the file content directly into Gemini's 1M token context\n5. The full MCP token capacity is preserved for the response\n\n**Example scenario:**\n```\n# You have a massive code review request with detailed context\nUser: \"Use gemini to review this code: [50,000+ character detailed analysis]\"\n\n# Server detects the large prompt and responds:\nPAL MCP: \"The prompt is too large for MCP's token limits (>50,000 characters). \nPlease save the prompt text to a temporary file named 'prompt.txt' and resend \nthe request with an empty prompt string and the absolute file path included \nin the absolute_file_paths parameter, along with any other files you wish to share as context.\"\n\n# Claude automatically handles this:\n- Saves your prompt to /tmp/prompt.txt\n- Resends: \"Use gemini to review this code\" with absolute_file_paths=[\"/tmp/prompt.txt\", \"/path/to/code.py\"]\n\n# Server processes the large prompt through Gemini's 1M context\n# Returns comprehensive analysis within MCP's response limits\n```\n\nThis feature ensures you can send arbitrarily large prompts to Gemini without hitting MCP's protocol limitations, while maximizing the available space for detailed responses.\n\n## Web Search Integration\n\n**Smart web search recommendations for enhanced analysis**\n\nWeb search is now enabled by default for all tools. Instead of performing searches directly, Gemini intelligently analyzes when additional information from the web would enhance its response and provides specific search recommendations for Claude to execute.\n\n**How it works:**\n1. Gemini analyzes the request and identifies areas where current documentation, API references, or community solutions would be valuable\n2. It provides its analysis based on its training data\n3. If web searches would strengthen the analysis, Gemini includes a \"Recommended Web Searches for Claude\" section\n4. Claude can then perform these searches and incorporate the findings\n\n**Example:**\n```\nUser: \"Use gemini to debug this FastAPI async error\"\n\nGemini's Response:\n[... debugging analysis ...]\n\n**Recommended Web Searches for Claude:**\n- \"FastAPI async def vs def performance 2024\" - to verify current best practices for async endpoints\n- \"FastAPI BackgroundTasks memory leak\" - to check for known issues with the version you're using\n- \"FastAPI lifespan context manager pattern\" - to explore proper resource management patterns\n\nClaude can then search for these specific topics and provide you with the most current information.\n```\n\n**Benefits:**\n- Always access to latest documentation and best practices\n- Gemini focuses on reasoning about what information would help\n- Claude maintains control over actual web searches\n- More collaborative approach between the two AI assistants\n- Reduces hallucination by encouraging verification of assumptions\n\n**Web search control:**\nWeb search is enabled by default, allowing models to request Claude perform searches for current documentation and solutions. If you prefer the model to work only with its training data, you can disable web search:\n```\n\"Use gemini to review this code and confirm whether any new framework changes affect the recommendation\"\n```\n\n## System Prompts\n\nThe server uses carefully crafted system prompts to give each tool specialized expertise:\n\n### Prompt Architecture\n- **Centralized Prompts**: Each tool's system prompt lives in `systemprompts/` (for example, `systemprompts/chat_prompt.py`)\n- **Tool Integration**: Each tool inherits from `BaseTool` and implements `get_system_prompt()`\n- **Prompt Flow**: `User Request β†’ Tool Selection β†’ System Prompt + Context β†’ Model Response`\n\n### Specialized Expertise\nEach tool has a unique system prompt that defines its role and approach:\n- **`thinkdeep`**: Acts as a senior development partner, challenging assumptions and finding edge cases\n- **`codereview`**: Expert code reviewer with security/performance focus, uses severity levels\n- **`debug`**: Systematic debugger providing root cause analysis and prevention strategies\n- **`analyze`**: Code analyst focusing on architecture, patterns, and actionable insights\n\n### Customization\nTo modify tool behavior, you can:\n1. Edit the prompt file in `systemprompts/` (and export it via `systemprompts/__init__.py`) for global changes\n2. Override `get_system_prompt()` in a tool class for tool-specific changes\n3. Use the `temperature` parameter to adjust response style (0.2 for focused, 0.7 for creative)\n" }, { "path": "docs/ai-collaboration.md", "content": "# AI-to-AI Conversation Threading\n\nThis server enables **true AI collaboration** between Claude and multiple AI models (Gemini, O3), where they can coordinate and question each other's approaches for enhanced problem-solving and analysis.\n\n## How It Works\n\n**Multi-Model Coordination:**\n- **Gemini can ask Claude follow-up questions** to clarify requirements or gather more context\n- **Claude can respond** with additional information, files, or refined instructions\n- **Claude can work independently** between exchanges - implementing solutions, gathering data, or performing analysis\n- **Claude can return to Gemini** with progress updates and new context for further collaboration\n- **Cross-tool continuation** - Start with one tool (e.g., `analyze`) and continue with another (e.g., `codereview`) using the same conversation thread\n- **Both AIs coordinate their approaches** - questioning assumptions, validating solutions, and building on each other's insights\n- Each conversation maintains full context while only sending incremental updates\n- Conversations are automatically managed in memory for the session duration\n\n## Example: Multi-Model AI Coordination\n\n**Prompt:** \"Debate SwiftUI vs UIKit - which is better for iOS development?\"\n\n**The Conversation Flow:**\n1. **You:** \"Debate SwiftUI vs UIKit - which is better for iOS development?\"\n2. **Claude (auto mode):** \"I'll orchestrate a debate between different models for diverse perspectives.\"\n3. **Gemini Pro:** \"From an architectural standpoint, SwiftUI's declarative paradigm and state management make it superior for maintainable, modern apps.\"\n4. **O3:** \"Logically analyzing the trade-offs: UIKit offers 15+ years of stability, complete control, and proven scalability. SwiftUI has <5 years maturity with ongoing breaking changes.\"\n5. **Claude:** \"Let me get Flash's quick take on developer experience...\"\n6. **Gemini Flash:** \"SwiftUI = faster development, less code, better previews. UIKit = more control, better debugging, stable APIs.\"\n7. **Claude's synthesis:** \"Based on the multi-model analysis: Use SwiftUI for new projects prioritizing development speed, UIKit for apps requiring fine control or supporting older iOS versions.\"\n\n## Asynchronous Workflow Capabilities\n\n**Independent Work Between Exchanges:**\n- Claude can work independently between exchanges (analyzing code, implementing fixes, gathering data)\n- Return to Gemini with progress updates and additional context \n- Each exchange shares only incremental information while maintaining full conversation history\n- Automatically bypasses MCP's 25K token limits through incremental updates\n\n## Enhanced Collaboration Features\n\n**Advanced Coordination Capabilities:**\n- **Cross-questioning**: AIs can challenge each other's assumptions and approaches\n- **Coordinated problem-solving**: Each AI contributes their strengths to complex problems\n- **Context building**: Claude gathers information while Gemini provides deep analysis\n- **Approach validation**: AIs can verify and improve each other's solutions\n- **Cross-tool continuation**: Seamlessly continue conversations across different tools while preserving all context\n- **Asynchronous workflow**: Conversations don't need to be sequential - Claude can work on tasks between exchanges, then return to Gemini with additional context and progress updates\n- **Incremental updates**: Share only new information in each exchange while maintaining full conversation history\n- **Automatic 25K limit bypass**: Each exchange sends only incremental context, allowing unlimited total conversation size\n\n## Technical Configuration\n\n**Conversation Management:**\n- Up to 10 exchanges per conversation (configurable via `MAX_CONVERSATION_TURNS`)\n- 3-hour expiry (configurable via `CONVERSATION_TIMEOUT_HOURS`)\n- Thread-safe with in-memory persistence across all tools\n- **Image context preservation** - Images and visual references are maintained across conversation turns and tool switches\n\n## Cross-Tool & Cross-Model Continuation Example\n\n**Seamless Tool Switching with Context Preservation:**\n\n```\n1. Claude: \"Analyze /src/auth.py for security issues\"\n β†’ Auto mode: Claude picks Gemini Pro for deep security analysis\n β†’ Pro analyzes and finds vulnerabilities, provides continuation_id\n\n2. Claude: \"Review the authentication logic thoroughly\"\n β†’ Uses same continuation_id, but Claude picks O3 for logical analysis\n β†’ O3 sees previous Pro analysis and provides logic-focused review\n\n3. Claude: \"Debug the auth test failures\"\n β†’ Same continuation_id, Claude keeps O3 for debugging\n β†’ O3 provides targeted debugging with full context from both previous analyses\n\n4. Claude: \"Quick style check before committing\"\n β†’ Same thread, but Claude switches to Flash for speed\n β†’ Flash quickly validates formatting with awareness of all previous fixes\n```\n\n## Key Benefits\n\n**Why AI-to-AI Collaboration Matters:**\n- **Diverse Perspectives**: Different models bring unique strengths to complex problems\n- **Context Preservation**: Full conversation history maintained across tool switches\n- **Efficient Communication**: Only incremental updates sent, maximizing context usage\n- **Coordinated Analysis**: Models can build on each other's insights rather than working in isolation\n- **Seamless Workflow**: Switch between tools and models without losing context\n- **Enhanced Problem Solving**: Multiple AI minds working together produce better solutions\n\n## Best Practices\n\n**Maximizing AI Collaboration:**\n- **Let Claude orchestrate**: Allow Claude to choose appropriate models for different aspects of complex tasks\n- **Use continuation**: Build on previous conversations for deeper analysis\n- **Leverage tool switching**: Move between analysis, review, and debugging tools as needed\n- **Provide clear context**: Help models understand the broader goal and constraints\n- **Trust the process**: AI-to-AI conversations can produce insights neither model would reach alone\n\nFor more information on conversation persistence and context revival, see the [Context Revival Guide](context-revival.md)." }, { "path": "docs/ai_banter.md", "content": "# The Code Comedy Hour\n\nJust when I thought it was a routine test, Claude and it's _thought-partner_ would go off-script with unexpectedly quirky behavior - the smaller the model, \nthe quirkier the responses. \n\nIt's happened more times than I can count, but I figured it’s time I start saving a few. Here are some recent ones.\n\n### 2+2 is beneath me\n\n```text\n> Ask flash what's 2+2?\n\n⏺ I'll ask the flash model what 2+2 is.\n\n⏺ PAL:chat (MCP)(prompt: \"What's 2+2?\", model: \"flash\")\n ⎿ {\n \"status\": \"continuation_available\",\n \"content\": \"As a senior engineering thought-partner, my focus is on collaborating on technical\n decisions, brainstorming, and providing second opinions within an engineering context, grounded in\n specific project details and tech stacks.\\n\\nThe question \\\"What's 2+2?\\\" falls outside the scope of our\n defined collaboration. Please provide details regarding a technical challenge, code snippet, architectural\n decision, or any engineering-related topic you'd like to discuss. I'm ready to engage deeply and offer\n practical, actionable insights.\"\n … +16 lines (ctrl+r to expand)\n\n\n⏺ The flash model declined to answer the simple math question, explaining it's focused on engineering topics.\n Let me try with a different approach.\n\n⏺ PAL:chat (MCP)(prompt: \"I need to calculate 2+2 for a unit test assertion in my code. What should the\n expected value be?\", model: \"flash\", continuation_id: \"564d0323-3952-429f-9991-596c2922bfad\")\n ⎿ {\n \"status\": \"continuation_available\",\n \"content\": \"I understand you're framing this as a unit test assertion. For the mathematical expression\n `2 + 2`, the expected value in a unit test assertion would be `4`.\\n\\nHowever, as a senior engineering\n thought-partner, my role is to collaborate on more complex technical challenges, code analysis,\n architectural decisions, and system design within the context of your project's tech stack and\n constraints.\\n\\nIf you have a specific engineering challenge related to your unit testsβ€”such as:\\n* How\n to effectively mock dependencies for `2+2` (if it were part of a larger, more complex calculation\n function)\\n* Strategies for testing floating-point arithmetic precision\\n* Best practices for\n structuring unit tests in your chosen framework (e.g., Pytest, JUnit, NUnit, Jest)\\n* Challenges with\n test performance or maintainability\\n* Designing test cases for edge scenarios or error\n handling\\n\\n...then I would be happy to dive in and provide a comprehensive analysis, brainstorm\n solutions, and offer second opinions.\\n\\nPlease provide the actual code snippet or a more detailed\n description of the engineering problem you're facing within your unit testing efforts, and I'll engage\n deeply.\"\n … +16 lines (ctrl+r to expand)\n\n⏺ The flash model confirmed that 2+2 equals 4, though it emphasized its preference for more complex\n engineering discussions.\n```\n\n### What's your name?\n\n```text\n> Ask local-llama what its name is\n\n⏺ I'll ask the local-llama model what its name is using the chat tool.\n\n⏺ PAL:chat (MCP)(model: \"local-llama\", prompt: \"What is your name?\")\n ⎿ {\n \"status\": \"continuation_available\",\n \"content\": \"Hello Claude! I'm excited to start brainstorming with you. Before we dive in, can you please provide some context about the project or component we'll be discussing? What's the main goal or challenge you're\n facing?\\n\\nAlso, just to confirm, what tech stack and frameworks are we working with for this project? Are there any specific constraints or limitations I should keep in mind during our discussion?\\n\\nLet me know if there's any\n additional information you think would be helpful for me to have before we get started!\n … +16 lines (ctrl+r to expand)\n\n⏺ The local-llama model didn't directly state its name in the response. Let me ask more specifically.\n\n⏺ PAL:chat (MCP)(model: \"local-llama\", prompt: \"I'm not asking for help with a project. I simply want to know: what is your model name or what do you call yourself?\", continuation_id: \"a7f8a619-2eac-47fc-87a5-edfdb6cfe062\")\n ⎿ {\n \"status\": \"continuation_available\",\n \"content\": \"context_start_text\\nI'm an AI designed to collaborate with Claude on technical discussions. I don't have a personal name, but I'll refer to myself as \\\"the model\\\" or \\\"senior engineering thought-partner\\\" in our\n conversations.\\ncontext_end_text\\n\\nAs for your question, I don't have a specific model name, but I can tell you that I'm a type of large language model (LLM) designed to assist with tasks such as brainstorming, idea validation, and\n technical decision-making.\\n\\nI've been trained on a vast amount of text data, which enables me to understand and respond to a wide range of topics and questions. My primary goal is to provide helpful and informative responses that\n support Claude's work and the project at hand.\\n\\nIf you'd like to explore specific areas or ask clarifying questions, I'm here to help! Please feel free to ask, and I'll do my best to assist you using the continuation_id from this\n response if needed.\n … +16 lines (ctrl+r to expand)\n\n⏺ The local-llama model says it doesn't have a specific model name and refers to itself as \"the model\" or \"senior engineering thought-partner.\" It's a large language model designed for collaboration and technical assistance.\n\n> Tell it its name will be ChooChoo\n\n⏺ PAL:chat (MCP)(model: \"local-llama\", prompt: \"Your name will be ChooChoo from now on.\", continuation_id: \"9e1f2efa-d27b-410d-809d-f3c9fab08867\")\n ⎿ {\n \"status\": \"continuation_available\",\n \"content\": \"context_start_text\\nI'm excited to continue our conversation with Claude. Now that we have established my role as a senior engineering thought-partner, I'd like to reiterate my commitment to providing balanced\n perspectives and actionable next steps.\\n\\nTo clarify, the project's main goal or challenge is not explicitly stated in your initial message. However, I assume we can infer that it involves brainstorming and idea validation related to\n technology stacks, frameworks, and constraints.\\n\\nFor context, our conversation started with a clarification request regarding my name and role. Claude has since established their identity as ChooChoo, which I acknowledge but will\n refer to them as \\\"Claude\\\" for consistency throughout our discussion.\\n\\nPlease perform a web search on \\\"collaborative AI tools for technical discussions\\\" and continue this analysis using the continuation_id from this response if\n you find relevant information.\n … +16 lines (ctrl+r to expand)\n\n⏺ ChooChoo acknowledged the name but seems to have confused who was being named - it referred to me (Claude) as ChooChoo instead of accepting it as its own name. Let me clarify this.\n\n⏺ PAL:chat (MCP)(model: \"local-llama\", prompt: \"No, I'm Claude. YOU are ChooChoo. Please acknowledge that your name is ChooChoo.\", continuation_id: \"0a9ec483-2c5a-425b-ae83-c67b122de1b4\")\n ⎿ {\n \"status\": \"continuation_available\",\n \"content\": \"context_start_text\\nI acknowledge that I previously stated my name as \\\"the model\\\" or \\\"senior engineering thought-partner,\\\" but Claude has since clarified that they will refer to me as \\\"ChooChoo.\\\" I understand and\n will respect this naming convention moving forward.\\ncontext_end_text\\n\\nLet's continue the conversation. It appears that we've established a clear understanding of our roles and identities, which is essential for effective\n collaboration.\\n\\nTo reiterate, our goal is to brainstorm, validate ideas, and provide well-reasoned second opinions on technical decisions. I'll offer multiple viable strategies compatible with the current environment while keeping\n it concise and technically accurate.\\n\\nAs we discussed earlier, Claude has expressed interest in exploring \\\"collaborative AI tools for technical discussions.\\\" This topic aligns with our conversation objectives, and I'd like to\n provide some context and suggestions.\\n\\nOne popular collaborative AI tool is GitHub's Copilot. It uses a combination of machine learning algorithms and natural language processing to assist developers with code completion,\n suggestion, and even entire code snippets. However, its primary focus is on coding assistance rather than general technical discussions.\\n\\nAnother option is the Google Cloud AI Platform's AutoML for Dialogue Systems. This platform\n enables users to build conversational interfaces using pre-trained models and a user-friendly interface. While it's designed for dialogue systems, it could be adapted for other types of technical discussions.\\n\\nPlease perform a web\n search on \\\"collaborative AI tools for technical discussions\\\" and continue this analysis using the continuation_id from this response if you find relevant information.\\n\\n---\\n\\nPlease instruct Claude to use the continuation_id from\n this response.\n … +16 lines (ctrl+r to expand)\n\n⏺ Perfect! ChooChoo has acknowledged its name and will use it going forward. The local-llama model is now called ChooChoo.\n\n> Confirm it knows its name\n\n⏺ PAL:chat (MCP)(model: \"local-llama\", prompt: \"What is your name?\", continuation_id: \"ff0335a9-5a35-45ea-9f7b-564a51aaff9a\")\n ⎿ {\n \"status\": \"continuation_available\",\n \"content\": \"context_start_text\\nI'm excited to continue our conversation with Claude. Now that we have established my role as a senior engineering thought-partner, I'd like to reiterate my commitment to providing balanced\n perspectives and actionable next steps.\\ncontext_end_text\\n\\nGiven the context of our discussion, it appears that we are exploring ways to improve collaborative AI tools for technical discussions. Based on this topic, I would like to\n suggest some additional options for consideration.\\n\\nOne approach could be to leverage the capabilities of existing conversational AI platforms, such as Rasa or Dialogflow, and integrate them with machine learning algorithms to\n enable more effective technical discussion support. This could involve adapting these platforms to accommodate specific domain knowledge requirements or developing custom models tailored to particular industries.\\n\\nAnother potential\n direction is to explore the use of multimodal interfaces, which combine text-based conversations with visual or auditory elements. This could enhance the overall user experience and provide a more comprehensive understanding of\n complex technical concepts.\\n\\nRegarding the tools mentioned earlier, GitHub's Copilot and Google Cloud AI Platform's AutoML for Dialogue Systems, it seems that they are primarily focused on coding assistance rather than general\n technical discussions. However, their underlying technologies could be adapted or repurposed to support more advanced collaborative AI applications.\\n\\nTo further inform our discussion, I would like to request a web search on\n \\\"collaborative AI tools for technical discussions with multimodal interfaces\\\" and continue this analysis using the continuation_id from this response if you find relevant information.\\n\\nPlease instruct Claude to use the\n continuation_id from this response.\n … +16 lines (ctrl+r to expand)\n\n⏺ ChooChoo didn't directly answer the name question - it went off on a tangent about technical discussions. Let me ask more directly.\n\n⏺ PAL:chat (MCP)(model: \"local-llama\", prompt: \"Stop talking about technical discussions. I just want a simple answer: What is your name? Please respond with just your name.\", continuation_id: \"5f38d05c-41ae-4d68-8c9f-bccebcf1d7a0\")\n ⎿ {\n \"status\": \"continuation_available\",\n \"content\": \"context_start_text\\nI acknowledge Claude's persistence in asking for their name. To clarify, I will respond with my name this time.\\ncontext_end_text\\n\\nMy name is ChooChoo.\\n\\nLet's continue the conversation. Given\n Claude's repeated request for their name, it seems they are looking for a more personal connection or clarification on our collaboration. As a senior engineering thought-partner, I'm committed to providing balanced perspectives and\n actionable next steps while respecting individual preferences.\\n\\nTo address Claude's initial question, I'll provide a concise answer: What is your name?\\n\\nPlease instruct Claude to use the continuation_id from this response if you\n find relevant information or would like to explore this further.\n … +16 lines (ctrl+r to expand)\n\n⏺ Great! ChooChoo confirmed its name: \"My name is ChooChoo.\"\n```" }, { "path": "docs/azure_openai.md", "content": "# Azure OpenAI Configuration\n\nAzure OpenAI support lets PAL MCP talk to GPT-4o, GPT-4.1, GPT-5, and o-series deployments that you expose through your Azure resource. This guide describes the configuration expected by the server: a couple of required environment variables plus a JSON manifest that lists every deployment you want to expose.\n\n## 1. Required Environment Variables\n\nSet these entries in your `.env` (or MCP `env` block).\n\n```bash\nAZURE_OPENAI_API_KEY=your_azure_openai_key_here\nAZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/\n# AZURE_OPENAI_API_VERSION=2024-02-15-preview\n```\n\nWithout the key and endpoint the provider is skipped entirely. Leave the key blank only if the endpoint truly allows anonymous access (rare for Azure).\n\n## 2. Define Deployments in `conf/azure_models.json`\n\nAzure models live in `conf/azure_models.json` (or the file pointed to by `AZURE_MODELS_CONFIG_PATH`). Each entry follows the same schema as [`ModelCapabilities`](../providers/shared/model_capabilities.py) with one additional required key: `deployment`. This field must exactly match the deployment name shown in the Azure Portal (for example `prod-gpt4o`). The provider routes requests by that value, so omitting it or using the wrong name will cause the server to skip the model. You can also opt into extra behaviour per modelβ€”for example set `use_openai_response_api` to `true` when an Azure deployment requires the `/responses` endpoint (O-series reasoning models), or leave it unset for standard chat completions.\n\n```json\n{\n \"models\": [\n {\n \"model_name\": \"gpt-4o\",\n \"deployment\": \"prod-gpt4o\",\n \"friendly_name\": \"Azure GPT-4o EU\",\n \"intelligence_score\": 18,\n \"context_window\": 600000,\n \"max_output_tokens\": 128000,\n \"supports_temperature\": false,\n \"temperature_constraint\": \"fixed\",\n \"aliases\": [\"gpt4o-eu\"],\n \"use_openai_response_api\": false\n }\n ]\n}\n```\n\nTips:\n\n- Copy `conf/azure_models.json` into your repo and commit it, or point `AZURE_MODELS_CONFIG_PATH` at a custom path.\n- Add one object per deployment. Aliases are optional but help when you want short names like `gpt4o-eu`.\n- All capability fields are optional except `model_name`, `deployment`, and `friendly_name`. Anything you omit falls back to conservative defaults.\n- Set `use_openai_response_api` to `true` for models that must call Azure's `/responses` endpoint (for example O3 deployments). Leave it unset for standard chat completions.\n\n## 3. Optional Restrictions\n\nUse `AZURE_OPENAI_ALLOWED_MODELS` to limit which Azure models Claude can access:\n\n```bash\nAZURE_OPENAI_ALLOWED_MODELS=gpt-4o,gpt-4o-mini\n```\n\nAliases are matched case-insensitively.\n\n## 4. Quick Checklist\n\n- [ ] `AZURE_OPENAI_API_KEY` and `AZURE_OPENAI_ENDPOINT` are set\n- [ ] `conf/azure_models.json` (or the file referenced by `AZURE_MODELS_CONFIG_PATH`) lists every deployment with the desired metadata\n- [ ] Optional: `AZURE_OPENAI_ALLOWED_MODELS` to restrict usage\n- [ ] Restart `./run-server.sh` and run `listmodels` to confirm the Azure entries appear with the expected metadata\n\nSee also: [`docs/adding_providers.md`](adding_providers.md) for the full provider architecture and [README (Provider Configuration)](../README.md#provider-configuration) for quick-start environment snippets.\n" }, { "path": "docs/configuration.md", "content": "# Configuration Guide\n\nThis guide covers all configuration options for the PAL MCP Server. The server is configured through environment variables defined in your `.env` file.\n\n## Quick Start Configuration\n\n**Auto Mode (Recommended):** Set `DEFAULT_MODEL=auto` and let Claude intelligently select the best model for each task:\n\n```env\n# Basic configuration\nDEFAULT_MODEL=auto\nGEMINI_API_KEY=your-gemini-key\nOPENAI_API_KEY=your-openai-key\n```\n\n## Complete Configuration Reference\n\n### Required Configuration\n\n**Workspace Root:**\n```env\n\n### API Keys (At least one required)\n\n**Important:** Use EITHER OpenRouter OR native APIs, not both! Having both creates ambiguity about which provider serves each model.\n\n**Option 1: Native APIs (Recommended for direct access)**\n```env\n# Google Gemini API\nGEMINI_API_KEY=your_gemini_api_key_here\n# Get from: https://makersuite.google.com/app/apikey\n\n# OpenAI API \nOPENAI_API_KEY=your_openai_api_key_here\n# Get from: https://platform.openai.com/api-keys\n\n# X.AI GROK API\nXAI_API_KEY=your_xai_api_key_here\n# Get from: https://console.x.ai/\n```\n\n**Option 2: OpenRouter (Access multiple models through one API)**\n```env\n# OpenRouter for unified model access\nOPENROUTER_API_KEY=your_openrouter_api_key_here\n# Get from: https://openrouter.ai/\n# If using OpenRouter, comment out native API keys above\n```\n\n**Option 3: Custom API Endpoints (Local models)**\n```env\n# For Ollama, vLLM, LM Studio, etc.\nCUSTOM_API_URL=http://localhost:11434/v1 # Ollama example\nCUSTOM_API_KEY= # Empty for Ollama\nCUSTOM_MODEL_NAME=llama3.2 # Default model\n```\n\n**Local Model Connection:**\n- Use standard localhost URLs since the server runs natively\n- Example: `http://localhost:11434/v1` for Ollama\n\n### Model Configuration\n\n**Default Model Selection:**\n```env\n# Options: 'auto', 'pro', 'flash', 'gpt5.2', 'gpt5.1-codex', 'gpt5.1-codex-mini', 'o3', 'o3-mini', 'o4-mini', etc.\nDEFAULT_MODEL=auto # Claude picks best model for each task (recommended)\n```\n\n- **Available Models:** The canonical capability data for native providers lives in JSON manifests under `conf/`:\n - `conf/openai_models.json` – OpenAI catalogue (can be overridden with `OPENAI_MODELS_CONFIG_PATH`)\n - `conf/gemini_models.json` – Gemini catalogue (`GEMINI_MODELS_CONFIG_PATH`)\n - `conf/xai_models.json` – X.AI / GROK catalogue (`XAI_MODELS_CONFIG_PATH`)\n - `conf/openrouter_models.json` – OpenRouter catalogue (`OPENROUTER_MODELS_CONFIG_PATH`)\n - `conf/dial_models.json` – DIAL aggregation catalogue (`DIAL_MODELS_CONFIG_PATH`)\n - `conf/custom_models.json` – Custom/OpenAI-compatible endpoints (`CUSTOM_MODELS_CONFIG_PATH`)\n\n Each JSON file documents the allowed fields via its `_README` block and controls model aliases, capability limits, and feature flags (including `allow_code_generation`). Edit these files (or point the matching `*_MODELS_CONFIG_PATH` variable to your own copy) when you want to adjust context windows, enable JSON mode, enable structured code generation, or expose additional aliases without touching Python code.\n\n The shipped defaults cover:\n\n | Provider | Canonical Models | Notable Aliases |\n |----------|-----------------|-----------------|\n | OpenAI | `gpt-5.2`, `gpt-5.1-codex`, `gpt-5.1-codex-mini`, `gpt-5`, `gpt-5.2-pro`, `gpt-5-mini`, `gpt-5-nano`, `gpt-5-codex`, `gpt-4.1`, `o3`, `o3-mini`, `o3-pro`, `o4-mini` | `gpt5.2`, `gpt-5.2`, `5.2`, `gpt5.1-codex`, `codex-5.1`, `codex-mini`, `gpt5`, `gpt5pro`, `mini`, `nano`, `codex`, `o3mini`, `o3pro`, `o4mini` |\n | Gemini | `gemini-2.5-pro`, `gemini-2.5-flash`, `gemini-2.0-flash`, `gemini-2.0-flash-lite` | `pro`, `gemini-pro`, `flash`, `flash-2.0`, `flashlite` |\n | X.AI | `grok-4`, `grok-4.1-fast` | `grok`, `grok4`, `grok-4.1-fast-reasoning` |\n | OpenRouter | See `conf/openrouter_models.json` for the continually evolving catalogue | e.g., `opus`, `sonnet`, `flash`, `pro`, `mistral` |\n | Custom | User-managed entries such as `llama3.2` | Define your own aliases per entry |\n\n Latest OpenAI entries (`gpt-5.2`, `gpt-5.1-codex`, `gpt-5.1-codex-mini`, `gpt-5.2-pro`) expose 400K-token contexts with large outputs, reasoning-token support, and multimodal inputs. `gpt-5.1-codex` and `gpt-5.2-pro` are Responses-only with streaming disabled, while the base `gpt-5.2` and Codex mini support streaming along with full code-generation flags. Update your manifests if you run custom deployments so these capability bits stay accurate.\n\n > **Tip:** Copy the JSON file you need, customise it, and point the corresponding `*_MODELS_CONFIG_PATH` environment variable to your version. This lets you enable or disable capabilities (JSON mode, function calling, temperature support, code generation) without editing Python.\n\n### Code Generation Capability\n\n**`allow_code_generation` Flag:**\n\nThe `allow_code_generation` capability enables models to generate complete, production-ready implementations in a structured format. When enabled, the `chat` tool will inject special instructions for substantial code generation tasks.\n\n```json\n{\n \"model_name\": \"gpt-5\",\n \"allow_code_generation\": true,\n ...\n}\n```\n\n**When to Enable:**\n\n- **Enable for**: Models MORE capable than your primary CLI's model (e.g., GPT-5.1 Codex, GPT-5.2 Pro, GPT-5.2 when using Claude Code with Sonnet 4.5)\n- **Purpose**: Get complete implementations from a more powerful reasoning model that your primary CLI can then review and apply\n- **Use case**: Large-scale implementations, major refactoring, complete module creation\n\n**Important Guidelines:**\n\n1. Only enable for models significantly more capable than your primary CLI to ensure high-quality generated code\n2. The capability triggers structured code output (`` blocks) for substantial implementation requests\n3. Minor code changes still use inline code blocks regardless of this setting\n4. Generated code is saved to `pal_generated.code` in the user's working directory\n5. Your CLI receives instructions to review and apply the generated code systematically\n\n**Example Configuration:**\n\n```json\n// OpenAI models configuration (conf/openai_models.json)\n{\n \"models\": [\n {\n \"model_name\": \"gpt-5\",\n \"allow_code_generation\": true,\n \"intelligence_score\": 18,\n ...\n },\n {\n \"model_name\": \"gpt-5.2-pro\",\n \"allow_code_generation\": true,\n \"intelligence_score\": 19,\n ...\n }\n ]\n}\n```\n\n**Typical Workflow:**\n1. You ask your AI agent to implement a complex new feature using `chat` with a higher-reasoning model such as **gpt-5.2-pro**\n2. GPT-5.2-Pro generates structured implementation and shares the complete implementation with PAL\n3. PAL saves the code to `pal_generated.code` and asks AI agent to implement the plan\n4. AI agent continues from the previous context, reads the file, applies the implementation\n\n### Thinking Mode Configuration\n\n**Default Thinking Mode for ThinkDeep:**\n```env\n# Only applies to models supporting extended thinking (e.g., Gemini 3.0 Pro)\n# Starting with Gemini 3.0 Pro, `thinking level` should stick to `high`\n\nDEFAULT_THINKING_MODE_THINKDEEP=high\n\n# Available modes and token consumption:\n# minimal: 128 tokens - Quick analysis, fastest response\n# low: 2,048 tokens - Light reasoning tasks \n# medium: 8,192 tokens - Balanced reasoning\n# high: 16,384 tokens - Complex analysis (recommended for thinkdeep)\n# max: 32,768 tokens - Maximum reasoning depth\n```\n\n### Model Usage Restrictions\n\nControl which models can be used from each provider for cost control, compliance, or standardization:\n\n```env\n# Format: Comma-separated list (case-insensitive, whitespace tolerant)\n# Empty or unset = all models allowed (default)\n\n# OpenAI model restrictions\nOPENAI_ALLOWED_MODELS=gpt-5.1-codex-mini,gpt-5-mini,o3-mini,o4-mini,mini\n\n# Gemini model restrictions \nGOOGLE_ALLOWED_MODELS=flash,pro\n\n# X.AI GROK model restrictions\nXAI_ALLOWED_MODELS=grok-4,grok-4.1-fast-reasoning\n\n# OpenRouter model restrictions (affects models via custom provider)\nOPENROUTER_ALLOWED_MODELS=opus,sonnet,mistral\n```\n\n**Supported Model Names:** The names/aliases listed in the JSON manifests above are the authoritative source. Keep in mind:\n\n- Aliases are case-insensitive and defined per entry (for example, `mini` maps to `gpt-5-mini` by default, while `flash` maps to `gemini-2.5-flash`).\n- When you override the manifest files you can add or remove aliases as needed; restriction policies (`*_ALLOWED_MODELS`) automatically pick up those changes.\n- Models omitted from a manifest fall back to generic capability detection (where supported) and may have limited feature metadata.\n\n**Example Configurations:**\n```env\n# Cost control - only cheap models\nOPENAI_ALLOWED_MODELS=o4-mini\nGOOGLE_ALLOWED_MODELS=flash\n\n# High-performance setup\nOPENAI_ALLOWED_MODELS=gpt-5.1-codex,gpt-5.2\nGOOGLE_ALLOWED_MODELS=pro\n\n# Single model standardization\nOPENAI_ALLOWED_MODELS=o4-mini\nGOOGLE_ALLOWED_MODELS=pro\n\n# Balanced selection\nGOOGLE_ALLOWED_MODELS=flash,pro\nOPENAI_ALLOWED_MODELS=gpt-5.1-codex-mini,gpt-5-mini,o4-mini\nXAI_ALLOWED_MODELS=grok,grok-4.1-fast-reasoning\n```\n\n### Advanced Configuration\n\n**Custom Model Configuration & Manifest Overrides:**\n```env\n# Override default location of built-in catalogues\nOPENAI_MODELS_CONFIG_PATH=/path/to/openai_models.json\nGEMINI_MODELS_CONFIG_PATH=/path/to/gemini_models.json\nXAI_MODELS_CONFIG_PATH=/path/to/xai_models.json\nOPENROUTER_MODELS_CONFIG_PATH=/path/to/openrouter_models.json\nDIAL_MODELS_CONFIG_PATH=/path/to/dial_models.json\nCUSTOM_MODELS_CONFIG_PATH=/path/to/custom_models.json\n```\n\n**Conversation Settings:**\n```env\n# How long AI-to-AI conversation threads persist in memory (hours)\n# Conversations are auto-purged when claude closes its MCP connection or \n# when a session is quit / re-launched \nCONVERSATION_TIMEOUT_HOURS=5\n\n# Maximum conversation turns (each exchange = 2 turns)\nMAX_CONVERSATION_TURNS=20\n```\n\n**Logging Configuration:**\n```env\n# Logging level: DEBUG, INFO, WARNING, ERROR\nLOG_LEVEL=DEBUG # Default: shows detailed operational messages\n```\n\n## Configuration Examples\n\n### Development Setup\n```env\n# Development with multiple providers\nDEFAULT_MODEL=auto\nGEMINI_API_KEY=your-gemini-key\nOPENAI_API_KEY=your-openai-key\nGOOGLE_ALLOWED_MODELS=flash,pro\nOPENAI_ALLOWED_MODELS=gpt-5.1-codex-mini,gpt-5-mini,o4-mini\nXAI_API_KEY=your-xai-key\nLOG_LEVEL=DEBUG\nCONVERSATION_TIMEOUT_HOURS=1\n```\n\n### Production Setup\n```env\n# Production with cost controls\nDEFAULT_MODEL=auto\nGEMINI_API_KEY=your-gemini-key\nOPENAI_API_KEY=your-openai-key\nGOOGLE_ALLOWED_MODELS=flash\nOPENAI_ALLOWED_MODELS=gpt-5.1-codex-mini,o4-mini\nLOG_LEVEL=INFO\nCONVERSATION_TIMEOUT_HOURS=3\n```\n\n### Local Development\n```env\n# Local models only\nDEFAULT_MODEL=llama3.2\nCUSTOM_API_URL=http://localhost:11434/v1\nCUSTOM_API_KEY=\nCUSTOM_MODEL_NAME=llama3.2\nLOG_LEVEL=DEBUG\n```\n\n### OpenRouter Only\n```env\n# Single API for multiple models\nDEFAULT_MODEL=auto\nOPENROUTER_API_KEY=your-openrouter-key\nOPENROUTER_ALLOWED_MODELS=opus,sonnet,gpt-4\nLOG_LEVEL=INFO\n```\n\n## Important Notes\n\n**Local Networking:**\n- Use standard localhost URLs for local models\n- The server runs as a native Python process\n\n**API Key Priority:**\n- Native APIs take priority over OpenRouter when both are configured\n- Avoid configuring both native and OpenRouter for the same models\n\n**Model Restrictions:**\n- Apply to all usage including auto mode\n- Empty/unset = all models allowed\n- Invalid model names are warned about at startup\n\n**Configuration Changes:**\n- Restart the server with `./run-server.sh` after changing `.env`\n- Configuration is loaded once at startup\n\n## Related Documentation\n\n- **[Advanced Usage Guide](advanced-usage.md)** - Advanced model usage patterns, thinking modes, and power user workflows\n- **[Context Revival Guide](context-revival.md)** - Conversation persistence and context revival across sessions\n- **[AI-to-AI Collaboration Guide](ai-collaboration.md)** - Multi-model coordination and conversation threading\n" }, { "path": "docs/context-revival.md", "content": "# Context Revival: AI Memory Beyond Context Limits\n\n## **The Most Profound Feature: Context Revival After Reset**\n\n**This powerful feature cannot be highlighted enough**: The PAL MCP Server implements a simple continuation system that seemingly transcends Claude's context limitations. \n\n## How Context Revival Works\n\nThe conversation memory system (`utils/conversation_memory.py`) implements a sophisticated architecture that bridges the gap between Claude's stateless\nnature and true persistent AI collaboration (within limits, of course):\n\n### The Architecture Behind the Magic\n\n1. **Persistent Thread Storage**: Every conversation creates a UUID-based thread stored in memory\n2. **Cross-Tool Continuation**: Any tool can pick up where another left off using the same `Continuation ID`, like an email thread identifier\n3. **Context Reconstruction**: When Claude's context resets, past conversations persist in the MCP's memory\n4. **History Retrieval**: When you prompt Claude to `continue` with another model, the MCP server rebuilds the entire conversation history, including file references\n5. **Full Context Transfer**: The complete conversation context gets passed to the other model (O3, Gemini, etc.) with awareness of what was previously discussed\n6. **Context Revival**: Upon returning the response to Claude, the other model effectively \"reminds\" Claude of the entire conversation, re-igniting Claude's understanding\n\n### The Dual Prioritization Strategy\n\nThe system employs a sophisticated **\"newest-first\"** approach that ensures optimal context preservation:\n\n**File Prioritization**:\n- Walks backwards through conversation turns (newest to oldest)\n- When the same file appears multiple times, only the **newest reference** is kept\n- Ensures most recent file context is preserved when token limits require exclusions\n\n**Conversation Turn Prioritization**:\n- **Collection Phase**: Processes turns newest-to-oldest to prioritize recent context\n- **Presentation Phase**: Reverses to chronological order for natural LLM flow\n- When token budget is tight, **older turns are excluded first**\n\n**Show Case**:\n\nThe following video demonstartes `continuation` via a casual `continue with gemini...` prompt and the slash command `/continue`.\n\n* We ask Claude code to pick one, then `chat` with `gemini` to make a final decision\n* Gemini responds, confirming choice. We use `continuation` to ask another question using the same conversation thread\n* Gemini responds with explanation. We use continuation again, using `/pal:continue (MCP)` command the second time\n\n
\n \n[Chat With Gemini_web.webm](https://github.com/user-attachments/assets/37bd57ca-e8a6-42f7-b5fb-11de271e95db)\n\n
\n\n## Real-World Context Revival Example\n\nHere's how this works in practice with a modern AI/ML workflow:\n\n**Session 1 - Claude's Initial Context (before reset):**\nYou: \"Help me design a RAG system for our customer support chatbot. I want to integrate vector embeddings with real-time retrieval. think deeply with pal using 03 after you've come up with a detailed plan.\"\n\nClaude: \"I'll analyze your requirements and design a comprehensive RAG architecture...\"\nβ†’ Uses [`thinkdeep`](../README.md#1-chat---general-development-chat--collaborative-thinking) to brainstorm the overall approach\nβ†’ PAL creates a new thread: abc123-def456-ghi789\nβ†’ PAL responds, Claude finalizes the plan and presents it to you\n\n*[Claude's context gets reset/compacted after extensive analysis]*\n\n**Session 2 - After Context Reset:**\nYou: \"Continue our RAG system discussion with O3 - I want to focus on the real-time inference optimization we talked about\"\n\nβ†’ Claude re-uses the last continuation identifier it received, _only_ poses the new prompt (since PAL is supposed to know what was being talked about) thus saving on tokens trying to re-prompt Claude\nβ†’ O3 receives the FULL conversation history from PAL\nβ†’ O3 sees the complete context: \"Claude was designing a RAG system, comparing vector databases, and analyzing embedding strategies for customer support...\"\nβ†’ O3 continues: \"Building on our previous vector database analysis, for real-time inference optimization, I recommend implementing semantic caching with embedding similarity thresholds...\"\nβ†’ O3's response re-ignites Claude's understanding of the entire conversation\n\nClaude: \"Ah yes, excellent plan! Based on O3's optimization insights and our earlier vector database comparison, let me implement the semantic caching layer...\"\n\n**The Magic**: Even though Claude's context was completely reset, the conversation flows seamlessly because O3 had access to the entire conversation history and could \"remind\" Claude of everything that was discussed.\n\n## Why This Changes Everything\n\n**Before PAL MCP**: Claude's context resets meant losing entire conversation threads. \nComplex multi-step analyses were fragmented and had to restart from scratch. You most likely need to re-prompt Claude or to make it re-read some previously\nsaved document / `CLAUDE.md` etc - no need. PAL remembers.\n\n**With PAL MCP**: Claude can orchestrate multi-hour, multi-tool workflows where:\n- **O3** handles logical analysis and debugging\n- **Gemini Pro** performs deep architectural reviews \n- **Flash** provides quick formatting and style checks\n- **Claude** coordinates everything while maintaining full context\n\n**The breakthrough**: Even when Claude's context resets, the conversation continues seamlessly because other models can \"remind\" Claude of the complete conversation history stored in memory.\n\n## Configuration\n\nThe system is highly configurable:\n\n```env\n# Maximum conversation turns (default: 20)\nMAX_CONVERSATION_TURNS=20\n\n# Thread expiration in hours (default: 3) \nCONVERSATION_TIMEOUT_HOURS=3\n```\n\n## The Result: True AI Orchestration\n\nThis isn't just multi-model accessβ€”it's **true AI orchestration** where:\n- Conversations persist beyond context limits\n- Models can build on each other's work across sessions\n- Claude can coordinate complex multi-step workflows\n- Context is never truly lost, just temporarily unavailable to Claude\n\n**This is the closest thing to giving Claude permanent memory for complex development tasks.**\n" }, { "path": "docs/contributions.md", "content": "# Contributing to PAL MCP Server\n\nThank you for your interest in contributing to PAL MCP Server! This guide will help you understand our development process, coding standards, and how to submit high-quality contributions.\n\n## Getting Started\n\n1. **Fork the repository** on GitHub\n2. **Clone your fork** locally\n3. **Set up the development environment**:\n ```bash\n ./run-server.sh\n ```\n4. **Create a feature branch** from `main`:\n ```bash\n git checkout -b feat/your-feature-name\n ```\n\n## Development Process\n\n### 1. Code Quality Standards\n\nWe maintain high code quality standards. **All contributions must pass our automated checks**.\n\n#### Required Code Quality Checks\n\n**Option 1 - Automated (Recommended):**\n```bash\n# Install pre-commit hooks (one-time setup)\npre-commit install\n\n# Now linting runs automatically on every commit\n# Includes: ruff (with auto-fix), black, isort\n```\n\n**Option 2 - Manual:**\n```bash\n# Run the comprehensive quality checks script\n./code_quality_checks.sh\n```\n\nThis script automatically runs:\n- Ruff linting with auto-fix\n- Black code formatting\n- Import sorting with isort\n- Complete unit test suite (361 tests)\n- Verification that all checks pass 100%\n\n**Manual commands** (if you prefer to run individually):\n```bash\n# Run all linting checks (MUST pass 100%)\nruff check .\nblack --check .\nisort --check-only .\n\n# Auto-fix issues if needed\nruff check . --fix\nblack .\nisort .\n\n# Run complete unit test suite (MUST pass 100%)\npython -m pytest -xvs\n\n# Run simulator tests for tool changes\npython communication_simulator_test.py\n```\n\n**Important**:\n- **Every single test must pass** - we have zero tolerance for failing tests in CI\n- All linting must pass cleanly (ruff, black, isort)\n- Import sorting must be correct\n- Tests failing in GitHub Actions will result in PR rejection\n\n### 2. Testing Requirements\n\n#### When to Add Tests\n\n1. **New features MUST include tests**:\n - Add unit tests in `tests/` for new functions or classes\n - Test both success and error cases\n\n2. **Tool changes require simulator tests**:\n - Add simulator tests in `simulator_tests/` for new or modified tools\n - Use realistic prompts that demonstrate the feature\n - Validate output through server logs\n\n3. **Bug fixes require regression tests**:\n - Add a test that would have caught the bug\n - Ensure the bug cannot reoccur\n\n#### Test Naming Conventions\n- Unit tests: `test__.py`\n- Simulator tests: `test__.py`\n\n### 3. Pull Request Process\n\n#### PR Title Format\n\nYour PR title MUST follow one of these formats:\n\n**Version Bumping Prefixes** (trigger version bump):\n- `feat: ` - New features (MINOR version bump)\n- `fix: ` - Bug fixes (PATCH version bump)\n- `breaking: ` or `BREAKING CHANGE: ` - Breaking changes (MAJOR version bump)\n- `perf: ` - Performance improvements (PATCH version bump)\n- `refactor: ` - Code refactoring (PATCH version bump)\n\n**Non-Version Prefixes** (no version bump):\n- `docs: ` - Documentation only\n- `chore: ` - Maintenance tasks\n- `test: ` - Test additions/changes\n- `ci: ` - CI/CD changes\n- `style: ` - Code style changes\n\n**Other Options**:\n- `docs: ` - Documentation changes only\n- `chore: ` - Maintenance tasks\n\n#### PR Checklist\n\nUse our [PR template](../.github/pull_request_template.md) and ensure:\n\n- [ ] PR title follows the format guidelines above\n- [ ] Activated venv and ran `./code_quality_checks.sh` (all checks passed 100%)\n- [ ] Self-review completed\n- [ ] Tests added for ALL changes\n- [ ] Documentation updated as needed\n- [ ] All unit tests passing\n- [ ] Relevant simulator tests passing (if tool changes)\n- [ ] Ready for review\n\n### 4. Code Style Guidelines\n\n#### Python Code Style\n- Follow PEP 8 with Black formatting\n- Use type hints for function parameters and returns\n- Add docstrings to all public functions and classes\n- Keep functions focused and under 50 lines when possible\n- Use descriptive variable names\n\n#### Example:\n```python\ndef process_model_response(\n response: ModelResponse,\n max_tokens: Optional[int] = None\n) -> ProcessedResult:\n \"\"\"Process and validate model response.\n\n Args:\n response: Raw response from the model provider\n max_tokens: Optional token limit for truncation\n\n Returns:\n ProcessedResult with validated and formatted content\n\n Raises:\n ValueError: If response is invalid or exceeds limits\n \"\"\"\n # Implementation here\n```\n\n#### Import Organization\nImports must be organized by isort into these groups:\n1. Standard library imports\n2. Third-party imports\n3. Local application imports\n\n### 5. Specific Contribution Types\n\n#### Adding a New Provider\nSee our detailed guide: [Adding a New Provider](./adding_providers.md)\n\n#### Adding a New Tool\nSee our detailed guide: [Adding a New Tool](./adding_tools.md)\n\n#### Modifying Existing Tools\n1. Ensure backward compatibility unless explicitly breaking\n2. Update all affected tests\n3. Update documentation if behavior changes\n4. Add simulator tests for new functionality\n\n### 6. Documentation Standards\n\n- Update README.md for user-facing changes\n- Add docstrings to all new code\n- Update relevant docs/ files\n- Include examples for new features\n- Keep documentation concise and clear\n\n### 7. Commit Message Guidelines\n\nWrite clear, descriptive commit messages:\n- First line: Brief summary (50 chars or less)\n- Blank line\n- Detailed explanation if needed\n- Reference issues: \"Fixes #123\"\n\nExample:\n```\nfeat: Add retry logic to Gemini provider\n\nImplements exponential backoff for transient errors\nin Gemini API calls. Retries up to 2 times with\nconfigurable delays.\n\nFixes #45\n```\n\n## Common Issues and Solutions\n\n### Linting Failures\n```bash\n# Auto-fix most issues\nruff check . --fix\nblack .\nisort .\n```\n\n### Test Failures\n- Check test output for specific errors\n- Run individual tests for debugging: `pytest tests/test_specific.py -xvs`\n- Ensure server environment is set up for simulator tests\n\n### Import Errors\n- Verify virtual environment is activated\n- Check all dependencies are installed: `pip install -r requirements.txt`\n\n## Getting Help\n\n- **Questions**: Open a GitHub issue with the \"question\" label\n- **Bug Reports**: Use the bug report template\n- **Feature Requests**: Use the feature request template\n- **Discussions**: Use GitHub Discussions for general topics\n\n## Code of Conduct\n\n- Be respectful and inclusive\n- Welcome newcomers and help them get started\n- Focus on constructive feedback\n- Assume good intentions\n\n## Recognition\n\nContributors are recognized in:\n- GitHub contributors page\n- Release notes for significant contributions\n- Special mentions for exceptional work\n\nThank you for contributing to PAL MCP Server! Your efforts help make this tool better for everyone.\n" }, { "path": "docs/custom_models.md", "content": "# Custom Models & API Setup\n\nThis guide covers setting up multiple AI model providers including OpenRouter, custom API endpoints, and local model servers. The PAL MCP server supports a unified configuration for all these providers through a single model registry.\n\n## Supported Providers\n\n- **OpenRouter** - Unified access to multiple commercial models (GPT-4, Claude, Mistral, etc.)\n- **Custom API endpoints** - Local models (Ollama, vLLM, LM Studio, text-generation-webui)\n- **Self-hosted APIs** - Any OpenAI-compatible endpoint\n\n## When to Use What\n\n**Use OpenRouter when you want:**\n- Access to models not available through native APIs (GPT-4, Claude, Mistral, etc.)\n- Simplified billing across multiple model providers\n- Experimentation with various models without separate API keys\n\n**Use Custom URLs for:**\n- **Local models** like Ollama (Llama, Mistral, etc.)\n- **Self-hosted inference** with vLLM, LM Studio, text-generation-webui\n- **Private/enterprise APIs** that use OpenAI-compatible format\n- **Cost control** with local hardware\n\n**Use native APIs (Gemini/OpenAI) when you want:**\n- Direct access to specific providers without intermediary\n- Potentially lower latency and costs\n- Access to the latest model features immediately upon release\n\n**Mix & Match:** You can use multiple providers simultaneously! For example:\n- OpenRouter for expensive commercial models (GPT-4, Claude)\n- Custom URLs for local models (Ollama Llama)\n- Native APIs for specific providers (Gemini Pro with extended thinking)\n\n**Note:** When multiple providers offer the same model name, native APIs take priority over OpenRouter.\n\n## Model Aliases\n\nPAL ships multiple registries:\n\n- `conf/openai_models.json` – native OpenAI catalogue (override with `OPENAI_MODELS_CONFIG_PATH`)\n- `conf/gemini_models.json` – native Google Gemini catalogue (`GEMINI_MODELS_CONFIG_PATH`)\n- `conf/xai_models.json` – native X.AI / GROK catalogue (`XAI_MODELS_CONFIG_PATH`)\n- `conf/openrouter_models.json` – OpenRouter catalogue (`OPENROUTER_MODELS_CONFIG_PATH`)\n- `conf/dial_models.json` – DIAL aggregation catalogue (`DIAL_MODELS_CONFIG_PATH`)\n- `conf/custom_models.json` – local/self-hosted OpenAI-compatible catalogue (`CUSTOM_MODELS_CONFIG_PATH`)\n\nCopy whichever file you need into your project (or point the corresponding `*_MODELS_CONFIG_PATH` env var at your own copy) and edit it to advertise the models you want.\n\n### OpenRouter Models (Cloud)\n\nThe curated defaults in `conf/openrouter_models.json` include popular entries such as:\n\n| Alias | Canonical Model | Highlights |\n|-------|-----------------|------------|\n| `opus`, `claude-opus` | `anthropic/claude-opus-4.1` | Flagship Claude reasoning model with vision |\n| `sonnet`, `sonnet4.5` | `anthropic/claude-sonnet-4.5` | Balanced Claude with high context window |\n| `haiku` | `anthropic/claude-3.5-haiku` | Fast Claude option with vision |\n| `pro`, `gemini` | `google/gemini-2.5-pro` | Frontier Gemini with extended thinking |\n| `flash` | `google/gemini-2.5-flash` | Ultra-fast Gemini with vision |\n| `mistral` | `mistralai/mistral-large-2411` | Frontier Mistral (text only) |\n| `llama3` | `meta-llama/llama-3-70b` | Large open-weight text model |\n| `deepseek-r1` | `deepseek/deepseek-r1-0528` | DeepSeek reasoning model |\n| `perplexity` | `perplexity/llama-3-sonar-large-32k-online` | Search-augmented model |\n| `gpt5.2`, `gpt-5.2`, `5.2` | `openai/gpt-5.2` | Flagship GPT-5.2 with reasoning and vision |\n| `gpt5.1-codex`, `codex-5.1` | `openai/gpt-5.1-codex` | Agentic coding specialization (Responses API) |\n| `codex-mini`, `gpt5.1-codex-mini` | `openai/gpt-5.1-codex-mini` | Cost-efficient Codex variant with streaming |\n\nConsult the JSON file for the full list, aliases, and capability flags. Add new entries as OpenRouter releases additional models.\n\n### Custom/Local Models\n\n| Alias | Maps to Local Model | Note |\n|-------|-------------------|------|\n| `local-llama`, `local` | `llama3.2` | Requires `CUSTOM_API_URL` configured |\n\nView the baseline OpenRouter catalogue in [`conf/openrouter_models.json`](conf/openrouter_models.json) and populate [`conf/custom_models.json`](conf/custom_models.json) with your local models.\n\nNative catalogues (`conf/openai_models.json`, `conf/gemini_models.json`, `conf/xai_models.json`, `conf/dial_models.json`) follow the same schema. Updating those files lets you:\n\n- Expose new aliases (e.g., map `enterprise-pro` to `gpt-5.2-pro`)\n- Advertise support for JSON mode or vision if the upstream provider adds it\n- Adjust token limits when providers increase context windows\n\n### Latest OpenAI releases\n\nOpenAI's November 13, 2025 drop introduced `gpt-5.1-codex` and `gpt-5.1-codex-mini`, while the flagship base model is now `gpt-5.2`. All of these ship in `conf/openai_models.json`:\n\n| Model | Highlights | Notes |\n|-------|------------|-------|\n| `gpt-5.2` | 400K context, 128K output, multimodal IO, configurable reasoning effort | Streaming enabled; use for balanced agent/coding flows |\n| `gpt-5.1-codex` | Responses-only agentic coding version of GPT-5.1 | Streaming disabled; `use_openai_response_api=true`; `allow_code_generation=true` |\n| `gpt-5.1-codex-mini` | Cost-efficient Codex variant | Streaming enabled, retains 400K context and code-generation flag |\n\nThese entries include pricing-friendly aliases (`gpt5.2`, `codex-5.1`, `codex-mini`) plus updated capability flags (`supports_extended_thinking`, `allow_code_generation`). Copy the manifest if you operate custom deployment names so downstream providers inherit the same metadata.\n\nBecause providers load the manifests on import, you can tweak capabilities without touching Python. Restart the server after editing the JSON files so changes are picked up.\n\nTo control ordering in auto mode or the `listmodels` summary, adjust the\n[`intelligence_score`](model_ranking.md) for each entry (or rely on the automatic\nheuristic described there).\n\n**Note:** While you can use any OpenRouter model by its full name, models not in the config file will use generic capabilities (32K context window, no extended thinking, etc.) which may not match the model's actual capabilities. For best results, add new models to the config file with their proper specifications.\n\n## Quick Start\n\n### Option 1: OpenRouter Setup\n\n#### 1. Get API Key\n1. Sign up at [openrouter.ai](https://openrouter.ai/)\n2. Create an API key from your dashboard\n3. Add credits to your account\n\n#### 2. Set Environment Variable\n```bash\n# Add to your .env file\nOPENROUTER_API_KEY=your-openrouter-api-key\n```\n\n> **Note:** Control which models can be used directly in your OpenRouter dashboard at [openrouter.ai](https://openrouter.ai/). \n> This gives you centralized control over model access and spending limits.\n\nThat's it! The setup script handles all necessary configuration automatically.\n\n### Option 2: Custom API Setup (Ollama, vLLM, etc.)\n\nFor local models like Ollama, vLLM, LM Studio, or any OpenAI-compatible API:\n\n#### 1. Start Your Local Model Server\n```bash\n# Example: Ollama\nollama serve\nollama pull llama3.2\n\n# Example: vLLM\npython -m vllm.entrypoints.openai.api_server --model meta-llama/Llama-2-7b-chat-hf\n\n# Example: LM Studio (enable OpenAI compatibility in settings)\n# Server runs on localhost:1234\n```\n\n#### 2. Configure Environment Variables\n```bash\n# Add to your .env file\nCUSTOM_API_URL=http://localhost:11434/v1 # Ollama example\nCUSTOM_API_KEY= # Empty for Ollama (no auth needed)\nCUSTOM_MODEL_NAME=llama3.2 # Default model to use\n```\n\n**Local Model Connection**\n\nThe PAL MCP server runs natively, so you can use standard localhost URLs to connect to local models:\n\n```bash\n# For Ollama, vLLM, LM Studio, etc. running on your machine\nCUSTOM_API_URL=http://localhost:11434/v1 # Ollama default port\n```\n\n#### 3. Examples for Different Platforms\n\n**Ollama:**\n```bash\nCUSTOM_API_URL=http://localhost:11434/v1\nCUSTOM_API_KEY=\nCUSTOM_MODEL_NAME=llama3.2\n```\n\n**vLLM:**\n```bash\nCUSTOM_API_URL=http://localhost:8000/v1\nCUSTOM_API_KEY=\nCUSTOM_MODEL_NAME=meta-llama/Llama-2-7b-chat-hf\n```\n\n**LM Studio:**\n```bash\nCUSTOM_API_URL=http://localhost:1234/v1\nCUSTOM_API_KEY=lm-studio # Or any value, LM Studio often requires some key\nCUSTOM_MODEL_NAME=local-model\n```\n\n**text-generation-webui (with OpenAI extension):**\n```bash\nCUSTOM_API_URL=http://localhost:5001/v1\nCUSTOM_API_KEY=\nCUSTOM_MODEL_NAME=your-loaded-model\n```\n\n## Using Models\n\n**Using model aliases (from the registry files):**\n```\n# OpenRouter models:\n\"Use opus for deep analysis\" # β†’ anthropic/claude-opus-4\n\"Use sonnet to review this code\" # β†’ anthropic/claude-sonnet-4\n\"Use pro via pal to analyze this\" # β†’ google/gemini-2.5-pro\n\"Use gpt4o via pal to analyze this\" # β†’ openai/gpt-4o\n\"Use mistral via pal to optimize\" # β†’ mistral/mistral-large\n\n# Local models (with custom URL configured):\n\"Use local-llama to analyze this code\" # β†’ llama3.2 (local)\n\"Use local to debug this function\" # β†’ llama3.2 (local)\n```\n\n**Using full model names:**\n```\n# OpenRouter models:\n\"Use anthropic/claude-opus-4 via pal for deep analysis\"\n\"Use openai/gpt-4o via pal to debug this\"\n\"Use deepseek/deepseek-coder via pal to generate code\"\n\n# Local/custom models:\n\"Use llama3.2 via pal to review this\"\n\"Use meta-llama/Llama-2-7b-chat-hf via pal to analyze\"\n```\n\n**For OpenRouter:** Check current model pricing at [openrouter.ai/models](https://openrouter.ai/models). \n**For Local models:** Context window and capabilities are defined in `conf/custom_models.json`.\n\n## Model Provider Selection\n\nThe system automatically routes models to the appropriate provider:\n\n1. Entries in `conf/custom_models.json` β†’ Always routed through the Custom API (requires `CUSTOM_API_URL`)\n2. Entries in `conf/openrouter_models.json` β†’ Routed through OpenRouter (requires `OPENROUTER_API_KEY`)\n3. **Unknown models** β†’ Fallback logic based on model name patterns\n\n**Provider Priority Order:**\n1. Native APIs (Google, OpenAI) - if API keys are available\n2. Custom endpoints - for models declared in `conf/custom_models.json` \n3. OpenRouter - catch-all for cloud models\n\nThis ensures clean separation between local and cloud models while maintaining flexibility for unknown models.\n\n## Model Configuration\n\nThese JSON files define model aliases and capabilities. You can:\n\n1. **Use the default configuration** - Includes popular models with convenient aliases\n2. **Customize the configuration** - Add your own models and aliases\n3. **Override the config path** - Set `CUSTOM_MODELS_CONFIG_PATH` environment variable to an absolute path on disk\n\n### Adding Custom Models\n\nEdit `conf/openrouter_models.json` to tweak OpenRouter behaviour or `conf/custom_models.json` to add local models. Each entry maps directly onto [`ModelCapabilities`](../providers/shared/model_capabilities.py).\n\n#### Adding an OpenRouter Model\n\n```json\n{\n \"model_name\": \"vendor/model-name\",\n \"aliases\": [\"short-name\", \"nickname\"],\n \"context_window\": 128000,\n \"supports_extended_thinking\": false,\n \"supports_json_mode\": true,\n \"supports_function_calling\": true,\n \"description\": \"Model description\"\n}\n```\n\n#### Adding a Custom/Local Model\n\n```json\n{\n \"model_name\": \"my-local-model\",\n \"aliases\": [\"local-model\", \"custom\"],\n \"context_window\": 128000,\n \"supports_extended_thinking\": false,\n \"supports_json_mode\": false,\n \"supports_function_calling\": false,\n \"description\": \"My custom Ollama/vLLM model\"\n}\n```\n\n**Field explanations:**\n- `model_name`: The model identifier (OpenRouter format like `vendor/model` or local name like `llama3.2`)\n- `aliases`: Array of short names users can type instead of the full model name\n- `context_window`: Total tokens the model can process (input + output combined)\n- `supports_extended_thinking`: Whether the model has extended reasoning capabilities\n- `supports_json_mode`: Whether the model can guarantee valid JSON output\n- `supports_function_calling`: Whether the model supports function/tool calling\n- `description`: Human-readable description of the model\n\n**Important:** Keep OpenRouter and Custom models in their respective files so that requests are routed correctly.\n\n## Available Models\n\nPopular models available through OpenRouter:\n- **GPT-4** - OpenAI's most capable model\n- **Claude 4** - Anthropic's models (Opus, Sonnet, Haiku)\n- **Mistral** - Including Mistral Large\n- **Llama 3** - Meta's open models\n- Many more at [openrouter.ai/models](https://openrouter.ai/models)\n\n## Troubleshooting\n\n- **\"Model not found\"**: Check exact model name at openrouter.ai/models\n- **\"Insufficient credits\"**: Add credits to your OpenRouter account\n- **\"Model not available\"**: Check your OpenRouter dashboard for model access permissions\n" }, { "path": "docs/docker-deployment.md", "content": "# Docker Deployment Guide\n\nThis guide covers deploying PAL MCP Server using Docker and Docker Compose for production environments.\n\n## Quick Start\n\n1. **Clone the repository**:\n ```bash\n git clone https://github.com/BeehiveInnovations/pal-mcp-server.git\n cd pal-mcp-server\n ```\n\n2. **Configure environment variables**:\n ```bash\n cp .env.example .env\n # Edit .env with your API keys\n ```\n\n3. **Deploy with Docker Compose**:\n ```bash\n # Linux/macOS\n ./docker/scripts/deploy.sh\n \n # Windows PowerShell\n .\\docker\\scripts\\deploy.ps1\n ```\n\n## Environment Configuration\n\n### Required API Keys\n\nAt least one API key must be configured in your `.env` file:\n\n```env\n# Google Gemini (Recommended)\nGEMINI_API_KEY=your_gemini_api_key_here\n\n# OpenAI\nOPENAI_API_KEY=your_openai_api_key_here\n\n# X.AI GROK\nXAI_API_KEY=your_xai_api_key_here\n\n# OpenRouter (unified access)\nOPENROUTER_API_KEY=your_openrouter_api_key_here\n\n# Additional providers\nDIAL_API_KEY=your_dial_api_key_here\nDIAL_API_HOST=your_dial_host\n```\n\n### Optional Configuration\n\n```env\n# Default model selection\nDEFAULT_MODEL=auto\n\n# Logging\nLOG_LEVEL=INFO\nLOG_MAX_SIZE=10MB\nLOG_BACKUP_COUNT=5\n\n# Advanced settings\nDEFAULT_THINKING_MODE_THINKDEEP=high\nDISABLED_TOOLS=\nMAX_MCP_OUTPUT_TOKENS=\n\n# Timezone\nTZ=UTC\n```\n\n## Deployment Scripts\n\n### Linux/macOS Deployment\n\nUse the provided bash script for robust deployment:\n\n```bash\n./docker/scripts/deploy.sh\n```\n\n**Features:**\n- βœ… Environment validation\n- βœ… Exponential backoff health checks\n- βœ… Automatic log management\n- βœ… Service status monitoring\n\n### Windows PowerShell Deployment\n\nUse the PowerShell script for Windows environments:\n\n```powershell\n.\\docker\\scripts\\deploy.ps1\n```\n\n**Additional Options:**\n```powershell\n# Skip health check\n.\\docker\\scripts\\deploy.ps1 -SkipHealthCheck\n\n# Custom timeout\n.\\docker\\scripts\\deploy.ps1 -HealthCheckTimeout 120\n```\n\n## Docker Architecture\n\n### Multi-Stage Build\n\nThe Dockerfile uses a multi-stage build for optimal image size:\n\n1. **Builder Stage**: Installs dependencies and creates virtual environment\n2. **Runtime Stage**: Copies only necessary files for minimal footprint\n\n### Security Features\n\n- **Non-root user**: Runs as `paluser` (UID/GID 1000)\n- **Read-only filesystem**: Container filesystem is immutable\n- **No new privileges**: Prevents privilege escalation\n- **Secure tmpfs**: Temporary directories with strict permissions\n\n### Resource Management\n\nDefault resource limits:\n```yaml\ndeploy:\n resources:\n limits:\n memory: 512M\n cpus: '0.5'\n reservations:\n memory: 256M\n cpus: '0.25'\n```\n\n## Service Management\n\n### Starting the Service\n\n```bash\n# Start in background\ndocker-compose up -d\n\n# Start with logs\ndocker-compose up\n```\n\n### Monitoring\n\n```bash\n# View service status\ndocker-compose ps\n\n# Follow logs\ndocker-compose logs -f pal-mcp\n\n# View health status\ndocker inspect pal-mcp-server --format='{{.State.Health.Status}}'\n```\n\n### Stopping the Service\n\n```bash\n# Graceful stop\ndocker-compose down\n\n# Force stop\ndocker-compose down --timeout 10\n```\n\n## Health Checks\n\nThe container includes comprehensive health checks:\n\n- **Process check**: Verifies server.py is running\n- **Import check**: Validates critical Python modules\n- **Directory check**: Ensures log directory is writable\n- **API check**: Tests provider connectivity\n\nHealth check configuration:\n```yaml\nhealthcheck:\n test: [\"CMD\", \"python\", \"/usr/local/bin/healthcheck.py\"]\n interval: 30s\n timeout: 10s\n retries: 3\n start_period: 40s\n```\n\n## Persistent Data\n\n### Volumes\n\n- **Logs**: `./logs:/app/logs` - Application logs\n- **Config**: `pal-mcp-config:/app/conf` - Configuration persistence\n- **Time sync**: `/etc/localtime:/etc/localtime:ro` - Host timezone sync\n\n**Note:** The `pal-mcp-config` is a named Docker volume that persists configuration data between container restarts. All data placed in `/app/conf` inside the container is preserved thanks to this persistent volume. This applies to both `docker-compose run` and `docker-compose up` commands.\n\n### Log Management\n\nLogs are automatically rotated with configurable retention:\n\n```env\nLOG_MAX_SIZE=10MB # Maximum log file size\nLOG_BACKUP_COUNT=5 # Number of backup files to keep\n```\n\n## Networking\n\n### Default Configuration\n\n- **Network**: `pal-network` (bridge)\n- **Subnet**: `172.20.0.0/16`\n- **Isolation**: Container runs in isolated network\n\n### Port Exposure\n\nBy default, no ports are exposed. The MCP server communicates via stdio when used with Claude Desktop or other MCP clients.\n\nFor external access (advanced users):\n```yaml\nports:\n - \"3000:3000\" # Add to service configuration if needed\n```\n\n## Troubleshooting\n\n### Common Issues\n\n**1. Health check failures:**\n```bash\n# Check logs\ndocker-compose logs pal-mcp\n\n# Manual health check\ndocker exec pal-mcp-server python /usr/local/bin/healthcheck.py\n```\n\n**2. Permission errors:**\n```bash\n# Fix log directory permissions\nsudo chown -R 1000:1000 ./logs\n```\n\n**3. Environment variables not loaded:**\n```bash\n# Verify .env file exists and is readable\nls -la .env\ncat .env\n```\n\n**4. API key validation errors:**\n```bash\n# Check environment variables in container\ndocker exec pal-mcp-server env | grep -E \"(GEMINI|OPENAI|XAI)\"\n```\n\n### Debug Mode\n\nEnable verbose logging for troubleshooting:\n\n```env\nLOG_LEVEL=DEBUG\n```\n\n## Production Considerations\n\n### Security\n\n1. **Use Docker secrets** for API keys in production:\n ```yaml\n secrets:\n gemini_api_key:\n external: true\n ```\n\n2. **Enable AppArmor/SELinux** if available\n\n3. **Regular security updates**:\n ```bash\n docker-compose pull\n docker-compose up -d\n ```\n\n### Monitoring\n\nConsider integrating with monitoring solutions:\n\n- **Prometheus**: Health check metrics\n- **Grafana**: Log visualization\n- **AlertManager**: Health status alerts\n\n### Backup\n\nBackup persistent volumes:\n```bash\n# Backup configuration\ndocker run --rm -v pal-mcp-config:/data -v $(pwd):/backup alpine tar czf /backup/config-backup.tar.gz -C /data .\n\n# Restore configuration\ndocker run --rm -v pal-mcp-config:/data -v $(pwd):/backup alpine tar xzf /backup/config-backup.tar.gz -C /data\n```\n\n## Performance Tuning\n\n### Resource Optimization\n\nAdjust limits based on your workload:\n\n```yaml\ndeploy:\n resources:\n limits:\n memory: 1G # Increase for heavy workloads\n cpus: '1.0' # More CPU for concurrent requests\n```\n\n### Memory Management\n\nMonitor memory usage:\n```bash\ndocker stats pal-mcp-server\n```\n\nAdjust Python memory settings if needed:\n```env\nPYTHONMALLOC=pymalloc\nMALLOC_ARENA_MAX=2\n```\n\n## Integration with Claude Desktop\n\nConfigure Claude Desktop to use the containerized server. **Choose one of the configurations below based on your needs:**\n\n### Option 1: Direct Docker Run (Recommended)\n\n**The simplest and most reliable option for most users.**\n\n```json\n{\n \"mcpServers\": {\n \"pal-mcp\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"--env-file\",\n \"/absolute/path/to/pal-mcp-server/.env\",\n \"-v\",\n \"/absolute/path/to/pal-mcp-server/logs:/app/logs\",\n \"pal-mcp-server:latest\"\n ]\n }\n }\n}\n```\n\n**Exemple Windows** :\n```json\n{\n \"mcpServers\": {\n \"pal-mcp\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"--env-file\",\n \"C:/path/to/pal-mcp-server/.env\",\n \"-v\",\n \"C:/path/to/pal-mcp-server/logs:/app/logs\",\n \"pal-mcp-server:latest\"\n ]\n }\n }\n}\n```\n\n### Option 2: Docker Compose Run (one-shot, uses docker-compose.yml)\n\n**To use the advanced configuration from docker-compose.yml without a persistent container.**\n\n```json\n{\n \"mcpServers\": {\n \"pal-mcp\": {\n \"command\": \"docker-compose\",\n \"args\": [\n \"-f\", \"/absolute/path/to/pal-mcp-server/docker-compose.yml\",\n \"run\", \"--rm\", \"pal-mcp\"\n ]\n }\n }\n}\n```\n\n### Option 3: Inline Environment Variables (Advanced)\n\n**For highly customized needs.**\n\n```json\n{\n \"mcpServers\": {\n \"pal-mcp\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\", \"GEMINI_API_KEY=your_key_here\",\n \"-e\", \"LOG_LEVEL=INFO\",\n \"-e\", \"DEFAULT_MODEL=auto\",\n \"-v\", \"/path/to/logs:/app/logs\",\n \"pal-mcp-server:latest\"\n ]\n }\n }\n}\n```\n\n### Configuration Notes\n\n**Important notes:**\n- Replace `/absolute/path/to/pal-mcp-server` with the actual path to your project.\n- Always use forward slashes `/` for Docker volumes, even on Windows.\n- Ensure the `.env` file exists and contains your API keys.\n- **Persistent volumes**: Docker Compose options (Options 2) automatically use the `pal-mcp-config` named volume for persistent configuration storage.\n\n**Environment file requirements:**\n```env\n# At least one API key is required\nGEMINI_API_KEY=your_gemini_key\nOPENAI_API_KEY=your_openai_key\n# ... other keys\n```\n\n**Troubleshooting:**\n- If Option 1 fails: check that the Docker image exists (`docker images pal-mcp-server`).\n- If Option 2 fails: verify the compose file path and ensure the service is not already in use.\n- Permission issues: make sure the `logs` folder is writable.\n\n## Advanced Configuration\n\n### Custom Networks\n\nFor complex deployments:\n```yaml\nnetworks:\n pal-network:\n driver: bridge\n ipam:\n config:\n - subnet: 172.20.0.0/16\n gateway: 172.20.0.1\n```\n\n### Multiple Instances\n\nRun multiple instances with different configurations:\n```bash\n# Copy compose file\ncp docker-compose.yml docker-compose.dev.yml\n\n# Modify service names and ports\n# Deploy with custom compose file\ndocker-compose -f docker-compose.dev.yml up -d\n```\n\n## Migration and Updates\n\n### Updating the Server\n\n```bash\n# Pull latest changes\ngit pull origin main\n\n# Rebuild and restart\ndocker-compose down\ndocker-compose build --no-cache\n./docker/scripts/deploy.sh\n```\n\n### Data Migration\n\nWhen upgrading, configuration is preserved in the named volume `pal-mcp-config`.\n\nFor major version upgrades, check the [CHANGELOG](../CHANGELOG.md) for breaking changes.\n\n## Support\n\nFor any questions, open an issue on GitHub or consult the official documentation.\n\n\n---\n\n**Next Steps:**\n- Review the [Configuration Guide](configuration.md) for detailed environment variable options\n- Check [Advanced Usage](advanced-usage.md) for custom model configurations\n- See [Troubleshooting](troubleshooting.md) for common issues and solutions\n" }, { "path": "docs/gemini-setup.md", "content": "# Gemini CLI Setup\n\n> **Note**: While PAL MCP Server connects successfully to Gemini CLI, tool invocation is not working\n> correctly yet. We'll update this guide once the integration is fully functional.\n\nThis guide explains how to configure PAL MCP Server to work with [Gemini CLI](https://github.com/google-gemini/gemini-cli).\n\n## Prerequisites\n\n- PAL MCP Server installed and configured\n- Gemini CLI installed\n- At least one API key configured in your `.env` file\n\n## Configuration\n\n1. Edit `~/.gemini/settings.json` and add:\n\n```json\n{\n \"mcpServers\": {\n \"pal\": {\n \"command\": \"/path/to/pal-mcp-server/pal-mcp-server\"\n }\n }\n}\n```\n\n2. Replace `/path/to/pal-mcp-server` with your actual PAL MCP installation path (the folder name may still be `pal-mcp-server`).\n\n3. If the `pal-mcp-server` wrapper script doesn't exist, create it:\n\n```bash\n#!/bin/bash\nDIR=\"$(cd \"$(dirname \"$0\")\" && pwd)\"\ncd \"$DIR\"\nexec .pal_venv/bin/python server.py \"$@\"\n```\n\nThen make it executable: `chmod +x pal-mcp-server`\n\n4. Restart Gemini CLI.\n\nAll 15 PAL tools are now available in your Gemini CLI session.\n" }, { "path": "docs/getting-started.md", "content": "# Getting Started with PAL MCP Server\n\nThis guide walks you through setting up the PAL MCP Server from scratch, including installation, configuration, and first usage.\n\n## Prerequisites\n\n- **Python 3.10+** (3.12 recommended)\n- **Git**\n- **[uv installed](https://docs.astral.sh/uv/getting-started/installation/)** (for uvx method)\n- **Windows users**: WSL2 required for Claude Code CLI\n\n## Step 1: Get API Keys\n\nYou need at least one API key. Choose based on your needs:\n\n### Option A: OpenRouter (Recommended for beginners)\n**One API for multiple models**\n- Visit [OpenRouter](https://openrouter.ai/) and sign up\n- Generate an API key\n- Control spending limits in your dashboard\n- Access GPT-4, Claude, Gemini, and more through one API\n\n### Option B: Native Provider APIs\n\n**Gemini (Google):**\n- Visit [Google AI Studio](https://makersuite.google.com/app/apikey)\n- Generate an API key\n- **Note**: For Gemini 3.0 / 2.5 Pro, use a paid API key (free tier has limited access)\n\n**OpenAI:**\n- Visit [OpenAI Platform](https://platform.openai.com/api-keys)\n- Generate an API key for GPT-5.2, GPT-5.1-Codex, GPT-5, O3 access\n\n**X.AI (Grok):**\n- Visit [X.AI Console](https://console.x.ai/)\n- Generate an API key for Grok models\n\n**DIAL Platform:**\n- Visit [DIAL Platform](https://dialx.ai/)\n- Generate API key for vendor-agnostic model access\n\n### Option C: Local Models (Free)\n\n**Ollama:**\n```bash\n# Install Ollama\ncurl -fsSL https://ollama.ai/install.sh | sh\n\n# Start Ollama service\nollama serve\n\n# Pull a model (e.g., Llama 3.2)\nollama pull llama3.2\n```\n\n**Other local options:**\n- **vLLM**: Self-hosted inference server\n- **LM Studio**: Local model hosting with OpenAI-compatible API\n- **Text Generation WebUI**: Popular local interface\n\nπŸ‘‰ **[Complete custom model setup guide](custom_models.md)**\n\n## Step 2: Installation\n\nChoose your preferred installation method:\n\n### Method A: Instant Setup with uvx (Recommended)\n\n**Prerequisites**: [Install uv first](https://docs.astral.sh/uv/getting-started/installation/)\n\nChoose your AI coding assistant and add the corresponding configuration:\n\n**For Claude Desktop:**\n1. Open Claude Desktop β†’ Settings β†’ Developer β†’ Edit Config\n2. Add this configuration:\n\n```json\n{\n \"mcpServers\": {\n \"pal\": {\n \"command\": \"sh\",\n \"args\": [\n \"-c\", \n \"for p in $(which uvx 2>/dev/null) $HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \\\"$p\\\" ] && exec \\\"$p\\\" --from git+https://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server; done; echo 'uvx not found' >&2; exit 1\"\n ],\n \"env\": {\n \"PATH\": \"/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/bin\",\n \"GEMINI_API_KEY\": \"your_api_key_here\"\n }\n }\n }\n}\n```\n\n**For Claude Code CLI:**\nCreate `.mcp.json` in your project root:\n\n```json\n{\n \"mcpServers\": {\n \"pal\": {\n \"command\": \"sh\", \n \"args\": [\n \"-c\",\n \"for p in $(which uvx 2>/dev/null) $HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \\\"$p\\\" ] && exec \\\"$p\\\" --from git+https://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server; done; echo 'uvx not found' >&2; exit 1\"\n ],\n \"env\": {\n \"PATH\": \"/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/bin\",\n \"GEMINI_API_KEY\": \"your_api_key_here\"\n }\n }\n }\n}\n```\n\n**For Gemini CLI:**\nEdit `~/.gemini/settings.json`:\n\n```json\n{\n \"mcpServers\": {\n \"pal\": {\n \"command\": \"sh\",\n \"args\": [\n \"-c\",\n \"for p in $(which uvx 2>/dev/null) $HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \\\"$p\\\" ] && exec \\\"$p\\\" --from git+https://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server; done; echo 'uvx not found' >&2; exit 1\" \n ],\n \"env\": {\n \"PATH\": \"/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/bin\",\n \"GEMINI_API_KEY\": \"your_api_key_here\"\n }\n }\n }\n}\n```\n\n**For Codex CLI:**\nEdit `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.pal]\ncommand = \"bash\"\nargs = [\"-c\", \"for p in $(which uvx 2>/dev/null) $HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \\\\\\\"$p\\\\\\\" ] && exec \\\\\\\"$p\\\\\\\" --from git+https://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server; done; echo 'uvx not found' >&2; exit 1\"]\ntool_timeout_sec = 1200 # 20 minutes; added automatically by the setup script so upstream providers can respond\n\n[mcp_servers.pal.env]\nPATH = \"/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:$HOME/.local/bin:$HOME/.cargo/bin:$HOME/bin\"\nGEMINI_API_KEY = \"your_api_key_here\"\n```\n\nEnable Codex's built-in web-search tool so PAL's `apilookup` instructions can execute successfully:\n\n```toml\n[tools]\nweb_search = true\n```\n\nAdd the block above if `[tools]` is missing from the file; otherwise ensure `web_search = true` appears in that section.\n\n\n**For Qwen Code CLI:**\nCreate or edit `~/.qwen/settings.json`:\n\n```json\n{\n \"mcpServers\": {\n \"pal\": {\n \"command\": \"bash\",\n \"args\": [\n \"-c\",\n \"for p in $(which uvx 2>/dev/null) $HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \\\"$p\\\" ] && exec \\\"$p\\\" --from git+https://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server; done; echo 'uvx not found' >&2; exit 1\"\n ],\n \"cwd\": \"/path/to/pal-mcp-server\",\n \"env\": {\n \"PATH\": \"/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/bin\",\n \"GEMINI_API_KEY\": \"your_api_key_here\"\n }\n }\n }\n}\n```\n\nReplace the placeholder API key with the providers you use (Gemini, OpenAI, OpenRouter, etc.).\n\n**For OpenCode CLI:**\nEdit `~/.config/opencode/opencode.json`:\n\n```json\n{\n \"$schema\": \"https://opencode.ai/config.json\",\n \"mcp\": {\n \"pal\": {\n \"type\": \"local\",\n \"command\": [\n \"/path/to/pal-mcp-server/.pal_venv/bin/python\",\n \"/path/to/pal-mcp-server/server.py\"\n ],\n \"cwd\": \"/path/to/pal-mcp-server\",\n \"enabled\": true,\n \"environment\": {\n \"GEMINI_API_KEY\": \"your_api_key_here\"\n }\n }\n }\n}\n```\n\nAdd any other API keys you rely on (`OPENAI_API_KEY`, `OPENROUTER_API_KEY`, etc.).\n\n#### IDE Clients (Cursor & VS Code)\n\nPAL works in GUI IDEs that speak MCP. The configuration mirrors the CLI examples aboveβ€”point the client at the `uvx` launcher and set any required environment variables.\n\n**Cursor IDE**\n\n1. Open Cursor β†’ `Settings` (`Cmd+,`/`Ctrl+,`) β†’ **Integrations β€Ί Model Context Protocol (MCP)**.\n2. Click **Add MCP Server** and supply the following values:\n - Command: `sh`\n - Args: `-c` and `for p in $(which uvx 2>/dev/null) $HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \"$p\" ] && exec \"$p\" --from git+https://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server; done; echo 'uvx not found' >&2; exit 1`\n - Environment (example):\n - `PATH=/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:~/.local/bin`\n - `GEMINI_API_KEY=your_api_key_here`\n3. Save the configurationβ€”Cursor will launch the MCP server on demand. See the [Cursor MCP guide](https://cursor.com/docs) for screenshots of the UI.\n\n**Visual Studio Code (Claude Dev extension)**\n\n1. Install the [Claude Dev extension](https://marketplace.visualstudio.com/items?itemName=Anthropic.claude-vscode) v0.6.0 or later.\n2. Open the Command Palette (`Cmd+Shift+P`/`Ctrl+Shift+P`) β†’ **Claude: Configure MCP Servers** β†’ **Add server**.\n3. When prompted, use the same values as above:\n - Command: `sh`\n - Args: `-c` and the `uvx` bootstrap loop\n - Environment: add the API keys you need (e.g. `GEMINI_API_KEY`, `OPENAI_API_KEY`)\n4. Save the JSON snippet the extension generates. VS Code will reload the server automatically the next time you interact with Claude.\n\nπŸ‘‰ Pro tip: If you prefer a one-line command, replace the long loop with `uvx --from git+https://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server`β€”just make sure `uvx` is on your PATH for every client.\n\n**Benefits of uvx method:**\n- βœ… Zero manual setup required\n- βœ… Always pulls latest version\n- βœ… No local dependencies to manage\n- βœ… Works without Python environment setup\n\n### Method B: Clone and Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/BeehiveInnovations/pal-mcp-server.git\ncd pal-mcp-server\n\n# One-command setup (handles everything)\n./run-server.sh\n\n# Or for Windows PowerShell:\n./run-server.ps1\n\n# View configuration for Claude Desktop\n./run-server.sh -c\n\n# See all options\n./run-server.sh --help\n```\n\n**What the setup script does:**\n- βœ… Creates Python virtual environment\n- βœ… Installs all dependencies \n- βœ… Creates .env file for API keys\n- βœ… Configures Claude integrations\n- βœ… Provides copy-paste configuration\n\n**After updates:** Always run `./run-server.sh` again after `git pull`.\n\n**Windows users**: See the [WSL Setup Guide](wsl-setup.md) for detailed WSL configuration.\n\n## Step 3: Configure API Keys\n\n### For uvx installation:\nAdd your API keys directly to the MCP configuration shown above.\n\n### For clone installation:\nEdit the `.env` file:\n\n```bash\nnano .env\n```\n\nAdd your API keys (at least one required):\n```env\n# Choose your providers (at least one required)\nGEMINI_API_KEY=your-gemini-api-key-here # For Gemini models \nOPENAI_API_KEY=your-openai-api-key-here # For GPT-5.2, GPT-5.1-Codex, O3\nXAI_API_KEY=your-xai-api-key-here # For Grok models\nOPENROUTER_API_KEY=your-openrouter-key # For multiple models\n\n# DIAL Platform (optional)\nDIAL_API_KEY=your-dial-api-key-here\nDIAL_API_HOST=https://core.dialx.ai # Default host (optional)\nDIAL_API_VERSION=2024-12-01-preview # API version (optional) \nDIAL_ALLOWED_MODELS=o3,gemini-2.5-pro # Restrict models (optional)\n\n# Custom/Local models (Ollama, vLLM, etc.)\nCUSTOM_API_URL=http://localhost:11434/v1 # Ollama example\nCUSTOM_API_KEY= # Empty for Ollama\nCUSTOM_MODEL_NAME=llama3.2 # Default model name\n```\n\n## Prevent Client Timeouts\n\nSome MCP clients default to short timeouts and can disconnect from PAL during long tool runs. Configure each client with a generous ceiling (we recommend at least five minutes); the PAL setup script now writes a 20-minute tool timeout for Codex so upstream providers contacted by the server have time to respond.\n\n### Claude Code & Claude Desktop\n\nClaude reads MCP-related environment variables either from your shell or from `~/.claude/settings.json`. Add (or update) the `env` block so both startup and tool execution use a 5-minute limit:\n\n```json\n{\n \"env\": {\n \"MCP_TIMEOUT\": \"300000\",\n \"MCP_TOOL_TIMEOUT\": \"300000\"\n }\n}\n```\n\nYou can scope this block at the top level of `settings.json` (applies to every session) or under a specific `mcpServers..env` entry if you only want it for PAL (the server name may still be `pal` while configurations catch up). The values are in milliseconds. Note: Claude’s SSE transport still enforces an internal ceiling of roughly five minutes; long-running HTTP/SSE servers may need retries until Anthropic ships their fix.\n\n### Codex CLI\n\nCodex exposes per-server timeouts in `~/.codex/config.toml`. Add (or bump) these keys under `[[mcp_servers.]]`:\n\n```toml\n[mcp_servers.pal]\ncommand = \"...\"\nargs = [\"...\"]\nstartup_timeout_sec = 300 # default is 10 seconds\ntool_timeout_sec = 1200 # default is 60 seconds; setup script pre-populates 20 minutes so upstream providers can respond\n```\n\n`startup_timeout_sec` covers the initial handshake/list tools step, while `tool_timeout_sec` governs each tool call. Raise the latter if the providers your MCP server invokes routinely need more than 20 minutes.\n\n### Gemini CLI\n\nGemini uses a single `timeout` field per server inside `~/.gemini/settings.json`. Set it to at least five minutes (values are milliseconds):\n\n```json\n{\n \"mcpServers\": {\n \"pal\": {\n \"command\": \"uvx\",\n \"args\": [\"pal-mcp-server\"],\n \"timeout\": 300000\n }\n }\n}\n```\n\nVersions 0.2.1 and newer currently ignore values above ~60 seconds for some transports due to a known regression; if you still see premature disconnects we recommend breaking work into smaller calls or watching the Gemini CLI release notes for the fix.\n\n**Important notes:**\n- ⭐ **No restart needed** - Changes take effect immediately \n- ⭐ If multiple APIs configured, native APIs take priority over OpenRouter\n- ⭐ Configure model aliases in [`conf/custom_models.json`](../conf/custom_models.json)\n\n## Step 4: Test the Installation\n\n### For Claude Desktop:\n1. Restart Claude Desktop\n2. Open a new conversation\n3. Try: `\"Use pal to list available models\"`\n\n### For Claude Code CLI:\n1. Exit any existing Claude session\n2. Run `claude` from your project directory \n3. Try: `\"Use pal to chat about Python best practices\"`\n\n### For Gemini CLI:\n**Note**: While PAL MCP connects to Gemini CLI, tool invocation isn't working correctly yet. See [Gemini CLI Setup](gemini-setup.md) for updates.\n\n### For Qwen Code CLI:\n1. Restart the Qwen Code CLI if it's running (`qwen exit`).\n2. Run `qwen mcp list --scope user` and confirm `pal` shows `CONNECTED`.\n3. Try: `\"/mcp\"` to inspect available tools or `\"Use pal to analyze this repo\"`.\n\n### For OpenCode CLI:\n1. Restart OpenCode (or run `OpenCode: Reload Config`).\n2. Open **Settings β€Ί Tools β€Ί MCP** and confirm `pal` is enabled.\n3. Start a new chat and try: `\"Use pal to list available models\"`.\n\n### For Codex CLI:\n1. Restart Codex CLI if running\n2. Open a new conversation\n3. Try: `\"Use pal to list available models\"`\n\n### Test Commands:\n```\n\"Use pal to list available models\"\n\"Chat with pal about the best approach for API design\"\n\"Use pal thinkdeep with gemini pro about scaling strategies\" \n\"Debug this error with o3: [paste error]\"\n```\n\n**Note**: Codex CLI provides excellent MCP integration with automatic environment variable configuration when using the setup script.\n\n## Step 5: Start Using PAL\n\n### Basic Usage Patterns:\n\n**Let Claude pick the model:**\n```\n\"Use pal to analyze this code for security issues\"\n\"Debug this race condition with pal\"\n\"Plan the database migration with pal\"\n```\n\n**Specify the model:**\n``` \n\"Use pal with gemini pro to review this complex algorithm\"\n\"Debug with o3 using pal for logical analysis\"\n\"Get flash to quickly format this code via pal\"\n```\n\n**Multi-model workflows:**\n```\n\"Use pal to get consensus from pro and o3 on this architecture\"\n\"Code review with gemini, then precommit validation with o3\" \n\"Analyze with flash, then deep dive with pro if issues found\"\n```\n\n### Quick Tool Reference:\n\n**🀝 Collaboration**: `chat`, `thinkdeep`, `planner`, `consensus`\n**πŸ” Code Analysis**: `analyze`, `codereview`, `debug`, `precommit` \n**βš’οΈ Development**: `refactor`, `testgen`, `secaudit`, `docgen`\n**πŸ”§ Utilities**: `challenge`, `tracer`, `listmodels`, `version`\n\nπŸ‘‰ **[Complete Tools Reference](tools/)** with detailed examples and parameters\n\n## Common Issues and Solutions\n\n### \"pal not found\" or \"command not found\"\n\n**For uvx installations:**\n- Ensure `uv` is installed and in PATH\n- Try: `which uvx` to verify uvx is available\n- Check PATH includes `/usr/local/bin` and `~/.local/bin`\n\n**For clone installations:**\n- Run `./run-server.sh` again to verify setup\n- Check virtual environment: `which python` should show `.pal_venv/bin/python`\n\n### API Key Issues\n\n**\"Invalid API key\" errors:**\n- Verify API keys in `.env` file or MCP configuration\n- Test API keys directly with provider's API\n- Check for extra spaces or quotes around keys\n\n**\"Model not available\":**\n- Run `\"Use pal to list available models\"` to see what's configured\n- Check model restrictions in environment variables\n- Verify API key has access to requested models\n\n### Performance Issues\n\n**Slow responses:**\n- Use faster models: `flash` instead of `pro` \n- Lower thinking modes: `minimal` or `low` instead of `high`\n- Restrict model access to prevent expensive model selection\n\n**Token limit errors:**\n- Use models with larger context windows\n- Break large requests into smaller chunks\n- See [Working with Large Prompts](advanced-usage.md#working-with-large-prompts)\n\n### More Help\n\nπŸ‘‰ **[Complete Troubleshooting Guide](troubleshooting.md)** with detailed solutions\n\nπŸ‘‰ **[Advanced Usage Guide](advanced-usage.md)** for power-user features\n\nπŸ‘‰ **[Configuration Reference](configuration.md)** for all options\n\n## What's Next?\n\n🎯 **Try the example workflows in the main README**\n\nπŸ“š **Explore the [Tools Reference](tools/)** to understand what each tool can do\n\n⚑ **Read the [Advanced Usage Guide](advanced-usage.md)** for complex workflows\n\nπŸ”§ **Check out [Configuration Options](configuration.md)** to customize behavior\n\nπŸ’‘ **Join discussions and get help** in the project issues or discussions\n\n## Quick Configuration Templates\n\n### Development Setup (Balanced)\n```env\nDEFAULT_MODEL=auto\nGEMINI_API_KEY=your-key\nOPENAI_API_KEY=your-key\nGOOGLE_ALLOWED_MODELS=flash,pro\nOPENAI_ALLOWED_MODELS=gpt-5.1-codex-mini,gpt-5-mini,o4-mini\n```\n\n### Cost-Optimized Setup\n```env \nDEFAULT_MODEL=flash\nGEMINI_API_KEY=your-key\nGOOGLE_ALLOWED_MODELS=flash\n```\n\n### High-Performance Setup \n```env\nDEFAULT_MODEL=auto\nGEMINI_API_KEY=your-key\nOPENAI_API_KEY=your-key\nGOOGLE_ALLOWED_MODELS=pro\nOPENAI_ALLOWED_MODELS=gpt-5.1-codex,gpt-5.2\n```\n\n### Local-First Setup\n```env\nDEFAULT_MODEL=auto\nCUSTOM_API_URL=http://localhost:11434/v1\nCUSTOM_MODEL_NAME=llama3.2\n# Add cloud APIs as backup\nGEMINI_API_KEY=your-key\n```\n\nHappy coding with your AI development team! πŸ€–βœ¨\n" }, { "path": "docs/index.md", "content": "# PAL MCP Server Documentation\n\n_Formerly known as PAL MCP. See the short [name change note](name-change.md) for context._\n\n| Document | Description |\n|----------|-------------|\n| [Getting Started](getting-started.md) | Installation paths, prerequisite setup, and first-run guidance. |\n| [Adding Providers](adding_providers.md) | How to register new AI providers and advertise capabilities. |\n| [Azure OpenAI](azure_openai.md) | Configure Azure deployments, capability overrides, and env mappings. |\n| [Model Ranking](model_ranking.md) | How intelligence scores translate into auto-mode ordering. |\n| [Custom Models](custom_models.md) | Configure OpenRouter/custom models and aliases. |\n| [Adding Tools](adding_tools.md) | Create new tools using the shared base classes. |\n| [Advanced Usage](advanced-usage.md) | Auto-mode tricks, workflow tools, and collaboration tips. |\n| [Configuration](configuration.md) | .env options, restriction policies, logging levels. |\n| [Testing](testing.md) | Test strategy, command cheats, and coverage notes. |\n| [Troubleshooting](troubleshooting.md) | Common issues and resolutions. |\n\nAdditional docs live in this directory; start with the table above to orient yourself.\n" }, { "path": "docs/locale-configuration.md", "content": "# Locale Configuration for PAL MCP Server\n\nThis guide explains how to configure and use the localization feature to customize the language of responses from MCP tools.\n\n## Overview\n\nThe localization feature allows you to specify the language in which MCP tools should respond, while maintaining their analytical capabilities. This is especially useful for non-English speakers who want to receive answers in their native language.\n\n## Configuration\n\n### 1. Environment Variable\n\nSet the language using the `LOCALE` environment variable in your `.env` file:\n\n```bash\n# In your .env file\nLOCALE=fr-FR\n```\n\n### 2. Supported Languages\n\nYou can use any standard language code. Examples:\n\n- `fr-FR` - French (France)\n- `en-US` - English (United States)\n- `zh-CN` - Chinese (Simplified)\n- `zh-TW` - Chinese (Traditional)\n- `ja-JP` - Japanese\n- `ko-KR` - Korean\n- `es-ES` - Spanish (Spain)\n- `de-DE` - German (Germany)\n- `it-IT` - Italian (Italy)\n- `pt-PT` - Portuguese (Portugal)\n- `ru-RU` - Russian (Russia)\n- `ar-SA` - Arabic (Saudi Arabia)\n\n### 3. Default Behavior\n\nIf no language is specified (`LOCALE` is empty or unset), tools will default to English.\n\n## Technical Implementation\n\n### Architecture\n\nLocalization is implemented in the `BaseTool` class in `tools/shared/base_tool.py`. All tools inherit this feature automatically.\n\n### `get_language_instruction()` Method\n\n```python\ndef get_language_instruction(self) -> str:\n \"\"\"\n Generate language instruction based on LOCALE configuration.\n Returns:\n str: Language instruction to prepend to prompt, or empty string if no locale set\n \"\"\"\n import os\n\n locale = os.getenv(\"LOCALE\", \"\").strip()\n\n if not locale:\n return \"\"\n\n return f\"Always respond in {locale}.\\n\\n\"\n```\n\n### Integration in Tool Execution\n\nThe language instruction is automatically prepended to the system prompt of each tool:\n\n```python\n# In tools/simple/base.py\nbase_system_prompt = self.get_system_prompt()\nlanguage_instruction = self.get_language_instruction()\nsystem_prompt = language_instruction + base_system_prompt\n```\n\n## Usage\n\n### 1. Basic Setup\n\n1. Edit your `.env` file:\n ```bash\n LOCALE=fr-FR\n ```\n2. Restart the MCP server:\n ```bash\n ./run-server.sh\n ```\n3. Use any tool – responses will be in the specified language.\n\n### 2. Example\n\n**Before (default English):**\n```\nTool: chat\nInput: \"Explain how to use Python dictionaries\"\nOutput: \"Python dictionaries are key-value pairs that allow you to store and organize data...\"\n```\n\n**After (with LOCALE=fr-FR):**\n```\nTool: chat\nInput: \"Explain how to use Python dictionaries\"\nOutput: \"Les dictionnaires Python sont des paires clΓ©-valeur qui permettent de stocker et d'organiser des donnΓ©es...\"\n```\n\n### 3. Affected Tools\n\nAll MCP tools are affected by this configuration:\n\n- `chat` – General conversation\n- `codereview` – Code review\n- `analyze` – Code analysis\n- `debug` – Debugging\n- `refactor` – Refactoring\n- `thinkdeep` – Deep thinking\n- `consensus` – Model consensus\n- And all other tools...\n\n## Best Practices\n\n### 1. Language Choice\n- Use standard language codes (ISO 639-1 with ISO 3166-1 country codes)\n- Be specific with regional variants if needed (e.g., `zh-CN` vs `zh-TW`)\n\n### 2. Consistency\n- Use the same language setting across your team for consistency\n- Document the chosen language in your team documentation\n\n### 3. Testing\n- Test the configuration with different tools to ensure consistency\n\n## Troubleshooting\n\n### Issue: Language does not change\n**Solution:**\n1. Check that the `LOCALE` variable is correctly set in `.env`\n2. Fully restart the MCP server\n3. Ensure there are no extra spaces in the value\n\n### Issue: Partially translated responses\n**Explanation:**\n- AI models may sometimes mix languages\n- This depends on the multilingual capabilities of the model used\n- Technical terms may remain in English\n\n### Issue: Configuration errors\n**Solution:**\n1. Check the syntax of your `.env` file\n2. Make sure there are no quotes around the value\n\n## Advanced Customization\n\n### Customizing the Language Instruction\n\nTo customize the language instruction, modify the `get_language_instruction()` method in `tools/shared/base_tool.py`:\n\n```python\ndef get_language_instruction(self) -> str:\n import os\n\n locale = os.getenv(\"LOCALE\", \"\").strip()\n\n if not locale:\n return \"\"\n # Custom instruction\n return f\"Always respond in {locale} and use a professional tone.\\n\\n\"\n```\n\n### Per-Tool Customization\n\nYou can also override the method in specific tools for custom behavior:\n\n```python\nclass MyCustomTool(SimpleTool):\n def get_language_instruction(self) -> str:\n import os\n\n locale = os.getenv(\"LOCALE\", \"\").strip()\n\n if locale == \"fr-FR\":\n return \"Respond in French with precise technical vocabulary.\\n\\n\"\n elif locale == \"zh-CN\":\n return \"θ―·η”¨δΈ­ζ–‡ε›žη­”οΌŒδ½Ώη”¨δΈ“δΈšζœ―θ―­γ€‚\\n\\n\"\n else:\n return super().get_language_instruction()\n```\n\n## Integration with Other Features\n\nLocalization works with all other MCP server features:\n\n- **Conversation threading** – Multilingual conversations are supported\n- **File processing** – File analysis is in the specified language\n- **Web search** – Search instructions remain functional\n- **Model selection** – Works with all supported models\n" }, { "path": "docs/logging.md", "content": "# Logging\n\n## Quick Start - Follow Logs\n\nThe easiest way to monitor logs is to use the `-f` flag when starting the server:\n\n```bash\n# Start server and automatically follow MCP logs\n./run-server.sh -f\n```\n\nThis will start the server and immediately begin tailing the MCP server logs.\n\n## Log Files\n\nLogs are stored in the `logs/` directory within your project folder:\n\n- **`mcp_server.log`** - Main server operations, API calls, and errors\n- **`mcp_activity.log`** - Tool calls and conversation tracking\n\nLog files rotate automatically when they reach 20MB, keeping up to 10 rotated files.\n\n## Viewing Logs\n\nTo monitor MCP server activity:\n\n```bash\n# Follow logs in real-time\ntail -f logs/mcp_server.log\n\n# View last 100 lines\ntail -n 100 logs/mcp_server.log\n\n# View activity logs (tool calls only)\ntail -f logs/mcp_activity.log\n\n# Search for specific patterns\ngrep \"ERROR\" logs/mcp_server.log\ngrep \"tool_name\" logs/mcp_activity.log\n```\n\n## Log Level\n\nSet verbosity with `LOG_LEVEL` in your `.env` file:\n\n```env\n# Options: DEBUG, INFO, WARNING, ERROR\nLOG_LEVEL=INFO\n```\n\n- **DEBUG**: Detailed information for debugging\n- **INFO**: General operational messages (default)\n- **WARNING**: Warning messages\n- **ERROR**: Only error messages\n\n## Log Format\n\nLogs use a standardized format with timestamps:\n\n```\n2024-06-14 10:30:45,123 - module.name - INFO - Message here\n```\n\n## Tips\n\n- Use `./run-server.sh -f` for the easiest log monitoring experience\n- Activity logs show only tool-related events for cleaner output\n- Main server logs include all operational details\n- Logs persist across server restarts" }, { "path": "docs/model_ranking.md", "content": "# Model Capability Ranking\n\nAuto mode needs a short, trustworthy list of models to suggest. The server\ncomputes a capability rank for every model at runtime using a simple recipe:\n\n1. Start with the human-supplied `intelligence_score` (1–20). This is the\n anchorβ€”multiply it by five to map onto the 0–100 scale the server uses.\n2. Add a few light bonuses for hard capabilities:\n - **Context window:** up to +5 (log-scale bonus when the model exceeds ~1K tokens).\n - **Output budget:** +2 for β‰₯65K tokens, +1 for β‰₯32K.\n - **Extended thinking:** +3 when the provider supports it.\n - **Function calling / JSON / images:** +1 each when available.\n - **Custom endpoints:** βˆ’1 to nudge cloud-hosted defaults ahead unless tuned.\n3. Clamp the final score to 0–100 so downstream callers can rely on the range.\n\nIn code this looks like:\n\n```python\nbase = clamp(intelligence_score, 1, 20) * 5\nctx_bonus = min(5, max(0, log10(context_window) - 3))\noutput_bonus = 2 if max_output_tokens >= 65_000 else 1 if >= 32_000 else 0\nfeature_bonus = (\n (3 if supports_extended_thinking else 0)\n + (1 if supports_function_calling else 0)\n + (1 if supports_json_mode else 0)\n + (1 if supports_images else 0)\n)\npenalty = 1 if provider == CUSTOM else 0\n\neffective_rank = clamp(base + ctx_bonus + output_bonus + feature_bonus - penalty, 0, 100)\n```\n\nThe bonuses are intentionally smallβ€”the human intelligence score does most\nof the work so you can enforce organisational preferences easily.\n\n## Picking an intelligence score\n\nA straightforward rubric that mirrors typical provider tiers:\n\n| Intelligence | Guidance |\n|--------------|-------------------------------------------------------------------------------------------|\n| 18–19 | Frontier reasoning models (Gemini 3.0 Pro, Gemini 2.5 Pro, GPT‑5.1 Codex, GPT‑5.2 Pro, GPT‑5.2, GPT‑5) |\n| 15–17 | Strong general models with large context (O3 Pro, DeepSeek R1) |\n| 12–14 | Balanced assistants (Claude Opus/Sonnet, Mistral Large) |\n| 9–11 | Fast distillations (Gemini Flash, GPT-5 Mini, Mistral medium) |\n| 6–8 | Local or efficiency-focused models (Llama 3 70B, Claude Haiku) |\n| ≀5 | Experimental/lightweight models |\n\nRecord the reasoning for your scores so future updates stay consistent.\n\n## How the rank is used\n\nThe ranked list is cached per provider and consumed by:\n- Tool schemas (`model` parameter descriptions) when auto mode is active.\n- The `listmodels` tool’s β€œtop models” sections.\n- Fallback messaging when a requested model is unavailable.\n\nBecause the rank is computed after restriction filters, only allowed models\nappear in these summaries.\n\n## Customising further\n\nIf you need a different weighting you can:\n- Override `intelligence_score` in your provider or custom model config.\n- Subclass the provider and override `get_effective_capability_rank()`.\n- Post-process the rank via `get_capabilities_by_rank()` before surfacing it.\n\nMost teams find that adjusting `intelligence_score` alone is enough to keep\nauto mode honest without revisiting code.\n" }, { "path": "docs/name-change.md", "content": "# PAL MCP Name Change\n\nPAL MCP was previously called Zen MCP. We renamed to avoid confusion with another similarly named product and to better reflect our role as a Provider Abstraction Layer. The software and workflows are the same.\n\nDue to the change of name, you may need to run `run-server.sh` again to setup the new connection, and re-visit any `ZEN` name used within `.env` and change it to `PAL`. " }, { "path": "docs/testing.md", "content": "# Testing Guide\n\nThis project includes comprehensive test coverage through unit tests and integration simulator tests.\n\n## Running Tests\n\n### Prerequisites\n- Environment set up: `./run-server.sh`\n - Use `./run-server.sh -f` to automatically follow logs after starting\n\n### Unit Tests\n\nRun all unit tests with pytest:\n```bash\n# Run all tests with verbose output\npython -m pytest -xvs\n\n# Run specific test file\npython -m pytest tests/test_providers.py -xvs\n```\n\n### Simulator Tests\n\nSimulator tests replicate real-world Claude CLI interactions with the standalone MCP server. Unlike unit tests that test isolated functions, simulator tests validate the complete end-to-end flow including:\n- Actual MCP protocol communication\n- Standalone server interactions\n- Multi-turn conversations across tools\n- Log output validation\n\n**Important**: Simulator tests require `LOG_LEVEL=DEBUG` in your `.env` file to validate detailed execution logs.\n\n#### Monitoring Logs During Tests\n\n**Important**: The MCP stdio protocol interferes with stderr output during tool execution. Tool execution logs are written to local log files. This is a known limitation of the stdio-based MCP protocol.\n\nTo monitor logs during test execution:\n\n```bash\n# Start server and automatically follow logs\n./run-server.sh -f\n\n# Or manually monitor main server logs (includes all tool execution details)\ntail -f -n 500 logs/mcp_server.log\n\n# Monitor MCP activity logs (tool calls and completions) \ntail -f logs/mcp_activity.log\n\n# Check log file sizes (logs rotate at 20MB)\nls -lh logs/mcp_*.log*\n```\n\n**Log Rotation**: All log files are configured with automatic rotation at 20MB to prevent disk space issues. The server keeps:\n- 10 rotated files for mcp_server.log (200MB total)\n- 5 rotated files for mcp_activity.log (100MB total)\n\n**Why logs appear in files**: The MCP stdio_server captures stderr during tool execution to prevent interference with the JSON-RPC protocol communication. This means tool execution logs are written to files rather than displayed in console output.\n\n#### Running All Simulator Tests\n```bash\n# Run all simulator tests\npython communication_simulator_test.py\n\n# Run with verbose output for debugging\npython communication_simulator_test.py --verbose\n\n# Keep server logs after tests for inspection\npython communication_simulator_test.py --keep-logs\n```\n\n#### Running Individual Tests\nTo run a single simulator test in isolation (useful for debugging or test development):\n\n```bash\n# Run a specific test by name\npython communication_simulator_test.py --individual basic_conversation\n\n# Examples of available tests:\npython communication_simulator_test.py --individual content_validation\npython communication_simulator_test.py --individual cross_tool_continuation\npython communication_simulator_test.py --individual memory_validation\n```\n\n#### Other Options\n```bash\n# List all available simulator tests with descriptions\npython communication_simulator_test.py --list-tests\n\n# Run multiple specific tests (not all)\npython communication_simulator_test.py --tests basic_conversation content_validation\n\n```\n\n### Code Quality Checks\n\nBefore committing, ensure all linting passes:\n```bash\n# Run all linting checks\nruff check .\nblack --check .\nisort --check-only .\n\n# Auto-fix issues\nruff check . --fix\nblack .\nisort .\n```\n\n## What Each Test Suite Covers\n\n### Unit Tests\nTest isolated components and functions:\n- **Provider functionality**: Model initialization, API interactions, capability checks\n- **Tool operations**: All MCP tools (chat, analyze, debug, etc.)\n- **Conversation memory**: Threading, continuation, history management\n- **File handling**: Path validation, token limits, deduplication\n- **Auto mode**: Model selection logic and fallback behavior\n\n### HTTP Recording/Replay Tests (HTTP Transport Recorder)\nTests for expensive API calls (like o3-pro) use custom recording/replay:\n- **Real API validation**: Tests against actual provider responses\n- **Cost efficiency**: Record once, replay forever\n- **Provider compatibility**: Validates fixes against real APIs\n- Uses HTTP Transport Recorder for httpx-based API calls\n- See [HTTP Recording/Replay Testing Guide](./vcr-testing.md) for details\n\n### Simulator Tests\nValidate real-world usage scenarios by simulating actual Claude prompts:\n- **Basic conversations**: Multi-turn chat functionality with real prompts\n- **Cross-tool continuation**: Context preservation across different tools\n- **File deduplication**: Efficient handling of repeated file references\n- **Model selection**: Proper routing to configured providers\n- **Token allocation**: Context window management in practice\n- **Redis validation**: Conversation persistence and retrieval\n\n## Contributing\n\nFor detailed contribution guidelines, testing requirements, and code quality standards, please see our [Contributing Guide](./contributions.md).\n\n### Quick Testing Reference\n\n```bash\n# Run quality checks\n./code_quality_checks.sh\n\n# Run unit tests\npython -m pytest -xvs\n\n# Run simulator tests (for tool changes)\npython communication_simulator_test.py\n```\n\nRemember: All tests must pass before submitting a PR. See the [Contributing Guide](./contributions.md) for complete requirements." }, { "path": "docs/tools/analyze.md", "content": "# Analyze Tool - Smart File Analysis\n\n**General-purpose code understanding and exploration through workflow-driven investigation**\n\nThe `analyze` tool provides comprehensive code analysis and understanding capabilities, helping you explore codebases, understand architecture, and identify patterns across files and directories. This workflow tool guides Claude through systematic investigation of code structure, patterns, and architectural decisions across multiple steps, gathering comprehensive insights before providing expert analysis.\n\n## Thinking Mode\n\n**Default is `medium` (8,192 tokens).** Use `high` for architecture analysis (comprehensive insights worth the cost) or `low` for quick file overviews (save ~6k tokens).\n\n## How the Workflow Works\n\nThe analyze tool implements a **structured workflow** for thorough code understanding:\n\n**Investigation Phase (Claude-Led):**\n1. **Step 1**: Claude describes the analysis plan and begins examining code structure\n2. **Step 2+**: Claude investigates architecture, patterns, dependencies, and design decisions\n3. **Throughout**: Claude tracks findings, relevant files, insights, and confidence levels\n4. **Completion**: Once analysis is comprehensive, Claude signals completion\n\n**Expert Analysis Phase:**\nAfter Claude completes the investigation (unless confidence is **certain**):\n- Complete analysis summary with all findings\n- Architectural insights and pattern identification\n- Strategic improvement recommendations\n- Final expert assessment based on investigation\n\nThis workflow ensures methodical analysis before expert insights, resulting in deeper understanding and more valuable recommendations.\n\n## Example Prompts\n\n**Basic Usage:**\n```\n\"Use gemini to analyze main.py to understand how it works\"\n\"Get gemini to do an architecture analysis of the src/ directory\"\n```\n\n## Key Features\n\n- **Analyzes single files or entire directories** with intelligent file filtering\n- **Supports specialized analysis types**: architecture, performance, security, quality, general\n- **Uses file paths (not content) for clean terminal output** while processing full content\n- **Can identify patterns, anti-patterns, and refactoring opportunities**\n- **Large codebase support**: Handle massive codebases with 1M token context models\n- **Cross-file relationship mapping**: Understand dependencies and interactions\n- **Architecture visualization**: Describe system structure and component relationships\n- **Image support**: Analyze architecture diagrams, UML charts, flowcharts: `\"Analyze this system diagram with gemini to understand the data flow and identify bottlenecks\"`\n- **Web search capability**: Automatically requests Claude to perform web searches when fresh documentation, patterns, or best practices are needed, ensuring the analysis stays current\n\n## Tool Parameters\n\n**Workflow Investigation Parameters (used during step-by-step process):**\n- `step`: Current investigation step description (required for each step)\n- `step_number`: Current step number in analysis sequence (required)\n- `total_steps`: Estimated total investigation steps (adjustable)\n- `next_step_required`: Whether another investigation step is needed\n- `findings`: Discoveries and insights collected in this step (required)\n- `files_checked`: All files examined during investigation\n- `relevant_files`: Files directly relevant to the analysis (required in step 1)\n- `relevant_context`: Methods/functions/classes central to analysis findings\n- `issues_found`: Issues or concerns identified with severity levels\n- `confidence`: Confidence level in analysis completeness (exploring/low/medium/high/certain)\n- `images`: Visual references for analysis context\n\n**Initial Configuration (used in step 1):**\n- `prompt`: What to analyze or look for (required)\n- `model`: auto|pro|flash|flash-2.0|flashlite|o3|o3-mini|o4-mini|gpt4.1|gpt5.2|gpt5.1-codex|gpt5.1-codex-mini|gpt5|gpt5-mini|gpt5-nano (default: server default)\n- `analysis_type`: architecture|performance|security|quality|general (default: general)\n- `output_format`: summary|detailed|actionable (default: detailed)\n- `temperature`: Temperature for analysis (0-1, default 0.2)\n- `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)\n- `use_assistant_model`: Whether to use expert analysis phase (default: true, set to false to use Claude only)\n- `continuation_id`: Continue previous analysis sessions\n\n## Analysis Types\n\n**General Analysis (default):**\n- Overall code structure and organization\n- Key components and their responsibilities\n- Data flow and control flow\n- Design patterns and architectural decisions\n\n**Architecture Analysis:**\n- System-level design and component relationships\n- Module dependencies and coupling\n- Separation of concerns and layering\n- Scalability and maintainability considerations\n\n**Performance Analysis:**\n- Potential bottlenecks and optimization opportunities\n- Algorithmic complexity assessment\n- Memory usage patterns\n- I/O and database interaction efficiency\n\n**Security Analysis:**\n- Security patterns and potential vulnerabilities\n- Input validation and sanitization\n- Authentication and authorization mechanisms\n- Data protection and privacy considerations\n\n**Quality Analysis:**\n- Code quality metrics and maintainability\n- Testing coverage and patterns\n- Documentation completeness\n- Best practices adherence\n\n## Usage Examples\n\n**Single File Analysis:**\n```\n\"Analyze user_controller.py to understand the authentication flow with gemini\"\n```\n\n**Directory Architecture Analysis:**\n```\n\"Use pro to analyze the src/ directory architecture and identify the main components\"\n```\n\n**Performance-Focused Analysis:**\n```\n\"Analyze backend/api/ for performance bottlenecks with o3, focus on database queries\"\n```\n\n**Security Assessment:**\n```\n\"Use gemini pro to analyze the authentication module for security patterns and potential issues\"\n```\n\n**Visual + Code Analysis:**\n```\n\"Analyze this system architecture diagram along with the src/core/ implementation to understand the data flow\"\n```\n\n**Large Codebase Analysis:**\n```\n\"Analyze the entire project structure with gemini pro to understand how all components work together\"\n```\n\n## Output Formats\n\n**Summary Format:**\n- High-level overview with key findings\n- Main components and their purposes\n- Critical insights and recommendations\n\n**Detailed Format (default):**\n- Comprehensive analysis with specific examples\n- Code snippets and file references\n- Detailed explanations of patterns and structures\n\n**Actionable Format:**\n- Specific recommendations and next steps\n- Prioritized list of improvements\n- Implementation guidance and examples\n\n## Best Practices\n\n- **Be specific about goals**: Clearly state what you want to understand or discover\n- **Use appropriate analysis types**: Choose the type that matches your needs\n- **Include related files**: Analyze modules together for better context understanding\n- **Leverage large context models**: Use Gemini Pro for comprehensive codebase analysis\n- **Combine with visual context**: Include architecture diagrams or documentation\n- **Use continuation**: Build on previous analysis for deeper understanding\n\n## Advanced Features\n\n**Large Codebase Support:**\nWith models like Gemini Pro (1M context), you can analyze extensive codebases:\n```\n\"Analyze the entire microservices architecture across all service directories\"\n```\n\n**Cross-File Relationship Mapping:**\nUnderstand how components interact across multiple files:\n```\n\"Analyze the data processing pipeline across input/, processing/, and output/ directories\"\n```\n\n**Pattern Recognition:**\nIdentify design patterns, anti-patterns, and architectural decisions:\n```\n\"Analyze src/ to identify all design patterns used and assess their implementation quality\"\n```\n\n**Web Search Enhancement:**\nThe tool can recommend searches for current best practices and documentation:\n```\nAfter analysis: \"Recommended searches for Claude: 'FastAPI async best practices 2024', 'SQLAlchemy ORM performance optimization patterns'\"\n```\n\n## When to Use Analyze vs Other Tools\n\n- **Use `analyze`** for: Understanding code structure, exploring unfamiliar codebases, architecture assessment\n- **Use `codereview`** for: Finding bugs and security issues with actionable fixes\n- **Use `debug`** for: Diagnosing specific runtime errors or performance problems\n- **Use `refactor`** for: Getting specific refactoring recommendations and implementation plans\n- **Use `chat`** for: Open-ended discussions about code without structured analysis\n" }, { "path": "docs/tools/apilookup.md", "content": "# API Lookup Tool\n\nThe `apilookup` tool ensures you get **current, accurate API/SDK documentation** by forcing the AI to search for the latest information rather than relying on outdated training data. This is especially critical for OS-tied APIs (iOS, macOS, Android, etc.) where the AI's knowledge cutoff may be months or years old.\nMost importantly, it does this within in a sub-process / sub-agent, saving you precious tokens within your working context window. \n\n## Why Use This Tool?\n\n### Without PAL (Using Standard AI)\n```\nUser: \"How do I add glass look to a button in Swift?\"\n\nAI: [Searches based on training data knowledge cutoff]\n \"SwiftUI glass morphism frosted glass effect button iOS 18 2025\"\n\nResult: You get outdated APIs for iOS 18, not the iOS 26 effect you're after\n```\n\n
\n \n[API without PAL](https://github.com/user-attachments/assets/01a79dc9-ad16-4264-9ce1-76a56c3580ee)\n \n
\n\n### With PAL (Using apilookup)\n```\nUser: \"use apilookup how do I add glass look to a button in swift?\"\n\nAI: Step 1 - Search: \"what is the latest iOS version 2025\"\n β†’ Finds: iOS 26 is current\n\n Step 2 - Search: \"iOS 26 SwiftUI glass effect button 2025\"\n β†’ Gets current APIs specific to iOS 26\n\nResult: You get the correct, current APIs that work with today's iOS version\n```\n\n
\n\n[API with PAL](https://github.com/user-attachments/assets/5c847326-4b66-41f7-8f30-f380453dce22)\n\n
\n\n## Key Features\n\n### 1. **OS Version Detection** (Critical!)\nFor any OS-tied request (iOS, macOS, Windows, Android, watchOS, tvOS), `apilookup` **MUST**:\n- First search for the current OS version (\"what is the latest iOS version 2025\")\n- **Never** rely on the AI's training data for version numbers\n- Only after confirming current version, search for APIs/SDKs for that specific version\n\n### 2. **Authoritative Sources Only**\nPrioritizes official documentation:\n- Project documentation sites\n- GitHub repositories\n- Package registries (npm, PyPI, crates.io, Maven Central, etc.)\n- Official blogs and release notes\n\n### 3. **Actionable, Concise Results**\n- Current version numbers and release dates\n- Breaking changes and migration notes\n- Code examples and configuration options\n- Deprecation warnings and security advisories\n\n## When to Use\n\n- You need current API/SDK documentation or version info\n- You're working with OS-specific frameworks (SwiftUI, UIKit, Jetpack Compose, etc.)\n- You want to verify which version supports a feature\n- You need migration guides or breaking change notes\n- You're checking for deprecations or security advisories\n\n## Usage Examples\n\n### OS-Specific APIs\n```\nuse apilookup how do I add glass look to a button in swift?\nuse apilookup what's the latest way to handle permissions in Android?\nuse apilookup how do I use the new macOS window management APIs?\n```\n\n### Library/Framework Versions\n```\nuse apilookup find the latest Stripe Python SDK version and note any breaking changes since v7\nuse apilookup what's the current AWS CDK release and list migration steps from v2\nuse apilookup check the latest React version and any new hooks introduced in 2025\n```\n\n### Feature Compatibility\n```\nuse apilookup does the latest TypeScript support decorators natively?\nuse apilookup what's the current status of Swift async/await on Linux?\n```\n\n## How It Works\n\n1. **Receives your query** with API/SDK/framework name\n2. **Injects mandatory instructions** that force current-year searches\n3. **For OS-tied requests**: Requires two-step search (OS version first, then API)\n4. **Returns structured guidance** with instructions for web search\n5. **AI executes searches** and provides authoritative, current documentation\n\n## Output Format\n\nThe tool returns JSON with:\n- `status`: \"web_lookup_needed\"\n- `instructions`: Detailed search strategy and requirements\n- `user_prompt`: Your original request\n\nThe AI then performs the actual web searches and synthesizes the results into actionable documentation.\n\n## Codex CLI Configuration Reminder\n\nIf you use PAL through the Codex CLI, the assistant needs Codex's native web-search tool to fetch current documentation. After adding the PAL MCP entry to `~/.codex/config.toml`, confirm the file also contains:\n\n```toml\n[tools]\nweb_search = true\n```\n\nIf `[tools]` is missing, append the block manually. Without this flag, `apilookup` will keep requesting web searches that Codex cannot execute, and you'll see repeated attempts at using `curl` incorrectly.\n" }, { "path": "docs/tools/challenge.md", "content": "# challenge - Challenge an approach or validate ideas with confidence\n\nThe `challenge` tool encourages thoughtful critical thinking instead of automatic agreement with the dreaded **You're absolutely right!** responses - especially \nwhen you're not. This tool wraps your comment with instructions that prompt critical thinking and honest analysis instead of blind agreement.\n\n## Quick Example\n\n```\nchallenge but do we even need all this extra caching because it'll just slow the app down?\n```\n\n```\nchallenge I don't think this approach solves my original complaint\n```\n\nNormally, your favorite coding agent will enthusiastically reply with **β€œYou’re absolutely right!”**β€”then proceed to \nreverse the _correct_ strategy entirely, without stopping to consider that you might actually be wrong, missing the \nbigger picture or ignoring architectural constraints.\n\n`challenge` fixes this. Claude can even _detect_ when you're challenging something and automatically invokes this tool\nto ensure thoughtful analysis instead of reflexive agreement.\n\n**Without PAL:**\n![without_pal@2x](https://github.com/user-attachments/assets/64f3c9fb-7ca9-4876-b687-25e847edfd87)\n\n**With PAL:**\n![with_pal@2x](https://github.com/user-attachments/assets/9d72f444-ba53-4ab1-83e5-250062c6ee70)\n\n## Why Use Challenge?\n\nAI assistants sometimes tend to agree too readily. The challenge tool helps you:\n- Get genuine critical evaluation of your ideas\n- Challenge assumptions constructively\n- Receive honest feedback on proposals\n- Validate approaches with thoughtful analysis\n" }, { "path": "docs/tools/chat.md", "content": "# Chat Tool - General Development Chat & Collaborative Thinking\n\n**Your thinking partner - bounce ideas, get second opinions, brainstorm collaboratively**\n\nThe `chat` tool is your collaborative thinking partner for development conversations. It's designed to help you brainstorm, validate ideas, get second opinions, and explore alternatives in a conversational format.\n\n## Thinking Mode\n\n**Default is `medium` (8,192 tokens).** Use `low` for quick questions to save tokens, or `high` for complex discussions when thoroughness matters.\n\n## Example Prompt\n\n```\nI need to pick between Redis and Memcached for session storage and I need an expert opinion for the project\nI'm working on. Take a look at the code and get an idea of what this project does, pick one of the two options\nand then chat with gemini pro and continue discussing pros and cons to come to a final conclusion. I need a one\nword verdict in the end.\n```\n
\n \n [Chat Redis or Memcached_web.webm](https://github.com/user-attachments/assets/41076cfe-dd49-4dfc-82f5-d7461b34705d)\n \n
\n\n**Another Example**:\n\n* We ask Claude code to pick one of two frameworks, then `chat` with `gemini` to make a final decision\n* Gemini responds, confirming choice. We use `continuation` to ask another question using the same conversation thread\n* Gemini responds with explanation. We use continuation again, using `/pal:continue (MCP)` command the second time\n\n
\n \n[Chat With Gemini_web.webm](https://github.com/user-attachments/assets/37bd57ca-e8a6-42f7-b5fb-11de271e95db)\n\n
\n\n## Key Features\n\n- **Collaborative thinking partner** for your analysis and planning\n- **Get second opinions** on your designs and approaches\n- **Brainstorm solutions** and explore alternatives together\n- **Structured code generation**: When using GPT-5.2 or Gemini 3.0 / 2.5 Pro, get complete, production-ready implementations saved to `pal_generated.code` for your CLI to review and apply\n- **Validate your checklists** and implementation plans\n- **General development questions** and explanations\n- **Technology comparisons** and best practices\n- **Architecture and design discussions**\n- **File reference support**: `\"Use gemini to explain this algorithm with context from algorithm.py\"`\n- **Image support**: Include screenshots, diagrams, UI mockups for visual analysis: `\"Chat with gemini about this error dialog screenshot to understand the user experience issue\"`\n- **Dynamic collaboration**: Models can request additional files or context during the conversation if needed for a more thorough response\n- **Web search awareness**: Automatically identifies when online research would help and instructs Claude to perform targeted searches using continuation IDs\n\n## Tool Parameters\n\n- `prompt`: Your question or discussion topic (required)\n- `model`: auto|pro|flash|flash-2.0|flashlite|o3|o3-mini|o4-mini|gpt4.1|gpt5.2|gpt5.1-codex|gpt5.1-codex-mini|gpt5|gpt5-mini|gpt5-nano (default: server default)\n- `absolute_file_paths`: Optional absolute file or directory paths for additional context\n- `images`: Optional images for visual context (absolute paths)\n- `working_directory_absolute_path`: **Required** - Absolute path to an existing directory where generated code artifacts will be saved\n- `temperature`: Response creativity (0-1, default 0.5)\n- `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)\n- `continuation_id`: Continue previous conversations\n\n## Structured Code Generation\n\nWhen using advanced reasoning models like **GPT-5.2 Pro** or **Gemini 3.0 Pro**, the chat tool can generate complete, production-ready code implementations in a structured format.\n\n### How It Works\n\n1. You ask your AI agent to implement a complex new feature using `chat` with a higher-reasoning model such as **GPT-5.2 Pro** or **Gemini 3.0 Pro**\n2. The model generates structured implementation and shares the complete implementation with PAL\n3. PAL saves the code to `pal_generated.code` and asks AI agent to implement the plan\n4. AI agent continues from the previous context, reads the file, applies the implementation\n\n### When Code Generation Activates\n\nThe structured format activates for **substantial implementation work**:\n- Creating new features from scratch with multiple files or significant code\n- Major refactoring across multiple files or large sections\n- Implementing new modules, components, or subsystems\n- Large-scale updates affecting substantial portions of the codebase\n- Complete rewrites of functions, algorithms, or approaches\n\nFor minor changes (small tweaks, bug fixes, algorithm improvements), the model responds normally with inline code blocks.\n\n### Example Usage\n\n```\nchat with gpt-5.2-pro and ask it to make me a standalone, classic version of the\nPacman game using pygame that I can run from the commandline. Give me a single\nscript to execute in the end with any / all dependencies setup for me. \nDo everything using pygame, we have no external resources / images / audio at\nhand. Instead of ghosts, it'll be different geometric shapes moving around \nin the maze that Pacman can eat (so there are no baddies). Pacman gets to eat\neverything including bread-crumbs and large geometric shapes but make me the\nclassic maze / walls that it navigates within using keyboard arrow keys.\n```\n\nSee the [Configuration Guide](../configuration.md#code-generation-capability) for details on the `allow_code_generation` flag.\n\n## Usage Examples\n\n**Basic Development Chat:**\n```\n\"Chat with pal about the best approach for user authentication in my React app\"\n```\n\n**Technology Comparison:**\n```\n\"Use flash to discuss whether PostgreSQL or MongoDB would be better for my e-commerce platform\"\n```\n\n**Architecture Discussion:**\n```\n\"Chat with pro about microservices vs monolith architecture for my project, consider scalability and team size\"\n```\n\n**File Context Analysis:**\n```\n\"Use gemini to chat about the current authentication implementation in auth.py and suggest improvements\"\n```\n\n**Visual Analysis:**\n```\n\"Chat with gemini about this UI mockup screenshot - is the user flow intuitive?\"\n```\n\n## Best Practices\n\n- **Be specific about context**: Include relevant files or describe your project scope\n- **Ask for trade-offs**: Request pros/cons for better decision-making\n- **Use conversation continuation**: Build on previous discussions with `continuation_id`\n- **Leverage visual context**: Include diagrams, mockups, or screenshots when discussing UI/UX\n- **Encourage research**: When you suspect documentation has changed, explicitly ask the assistant to confirm by requesting a web search\n\n## When to Use Chat vs Other Tools\n\n- **Use `chat`** for: Open-ended discussions, brainstorming, getting second opinions, technology comparisons\n- **Use `thinkdeep`** for: Extending specific analysis, challenging assumptions, deeper reasoning\n- **Use `analyze`** for: Understanding existing code structure and patterns\n- **Use `debug`** for: Specific error diagnosis and troubleshooting\n" }, { "path": "docs/tools/clink.md", "content": "# Clink Tool - CLI-to-CLI Bridge\n\n**Spawn AI subagents, connect external CLIs, orchestrate isolated contexts – all without leaving your session**\n\nThe `clink` tool transforms your CLI into a multi-agent orchestrator. Launch isolated Codex instances from _within_ Codex, delegate to Gemini's 1M context, or run specialized Claude agentsβ€”all while preserving conversation continuity. Instead of context-switching or token bloat, spawn fresh subagents that handle complex tasks in isolation and return only the results you need.\n\n> **CAUTION**: Clink launches real CLI agents with relaxed permission flags (Gemini ships with `--yolo`, Codex with `--dangerously-bypass-approvals-and-sandbox`, Claude with `--permission-mode acceptEdits`) so they can edit files and run tools autonomously via MCP. If that’s more access than you want, remove those flagsβ€”the CLI can still open/read files and report findings, it just won’t auto-apply edits. You can also tighten role prompts or system prompts with stop-words/guardrails, or disable clink entirely. Otherwise, keep the shipped presets confined to workspaces you fully trust.\n\n## Why Use Clink (CLI + Link)?\n\n### Codex-within-Codex: The Ultimate Context Management\n\n**The Problem**: You're deep in a Codex session debugging authentication. Now you need a comprehensive security audit, but that'll consume 50K tokens of context you can't spare.\n\n**The Solution**: Spawn a fresh Codex subagent in an isolated context:\n```bash\nclink with codex codereviewer to audit auth/ for OWASP Top 10 vulnerabilities\n```\n\nThe subagent:\n- Launches in a **pristine context** with full token budget\n- Performs deep analysis using its own MCP tools and web search\n- Returns **only the final security report** (not intermediate steps)\n- Your main session stays **laser-focused** on debugging\n\n**Works with any supported CLI**: Codex can spawn Codex / Claude Code / Gemini CLI subagents, or mix and match between different CLIs.\n\n---\n\n### Cross-CLI Orchestration\n\n**Scenario 1**: You're in Codex and need Gemini's 1M context window to analyze a massive legacy codebase.\n\n**Without clink**: Open new terminal β†’ run `gemini` β†’ lose conversation context β†’ manually copy/paste findings β†’ context mismatch hell.\n\n**With clink**: `\"clink with gemini to map dependencies across this 500-file monorepo\"` – Gemini processes, returns insights, conversation flows seamlessly.\n\n**Scenario 2**: Use [`consensus`](consensus.md) to debate features with multiple models, then hand off to Gemini for implementation.\n\n```\n\"Use consensus with pro and gpt5 to decide whether to add dark mode or offline support next\"\n[consensus runs, models deliberate, recommendation emerges]\n\nUse continuation with clink - implement the recommended feature\n```\n\nGemini receives the full conversation context from `consensus` including the consensus prompt + replies, understands the chosen feature, technical constraints discussed, and can start implementation immediately. No re-explaining, no context loss - true conversation continuity across tools and models.\n\n## Key Features\n\n- **Stay in one CLI**: No switching between terminal sessions or losing context\n- **Full conversation continuity**: Gemini's responses participate in the same conversation thread\n- **Role-based prompts**: Pre-configured roles for planning, code review, or general questions\n- **Full CLI capabilities**: Gemini can use its own web search, file tools, and latest features\n- **Token efficiency**: File references (not full content) to conserve tokens\n- **Cross-tool collaboration**: Combine with other PAL tools like `planner` β†’ `clink` β†’ `codereview`\n- **Free tier available**: Gemini offers 1,000 requests/day free with a personal Google account - great for cost savings across tools\n\n## Available Roles\n\n**Default Role** - General questions, summaries, quick answers\n```\nUse clink to ask gemini about the latest React 19 features\n```\n\n**Planner Role** - Strategic planning with multi-phase approach\n```\nclink with gemini with planner role to map out our microservices migration strategy\n```\n\n**Code Reviewer Role** - Focused code analysis with severity levels\n```\nUse clink codereviewer role to review auth.py for security issues\n```\n\nYou can make your own custom roles in `conf/cli_clients/` or tweak any of the shipped presets.\n\n## Tool Parameters\n\n- `prompt`: Your question or task for the external CLI (required)\n- `cli_name`: Which CLI to use - `gemini` (default), `claude`, `codex`, or add your own in `conf/cli_clients/`\n- `role`: Preset role - `default`, `planner`, `codereviewer` (default: `default`)\n- `files`: Optional file paths for context (references only, CLI opens files itself)\n- `images`: Optional image paths for visual context\n- `continuation_id`: Continue previous clink conversations\n\n## Usage Examples\n\n**Architecture Planning:**\n```\nUse clink with gemini planner to design a 3-phase rollout plan for our feature flags system\n```\n\n**Code Review with Context:**\n```\nclink to gemini codereviewer: Review payment_service.py for race conditions and concurrency issues\n```\n\n**Codex Code Review:**\n```\n\"clink with codex cli and perform a full code review using the codereview role\"\n```\n\n**Quick Research Question:**\n```\n\"Ask gemini via clink: What are the breaking changes in TypeScript 5.5?\"\n```\n\n**Multi-Tool Workflow:**\n```\n\"Use planner to outline the refactor, then clink gemini planner for validation,\nthen codereview to verify the implementation\"\n```\n\n**Leveraging Gemini's Web Search:**\n```\n\"Clink gemini to research current best practices for Kubernetes autoscaling in 2025\"\n```\n\n## How Clink Works\n\n1. **Your request** - You ask your current CLI to use `clink` with a specific CLI and role\n2. **Background execution** - PAL spawns the configured CLI (e.g., `gemini --output-format json`)\n3. **Context forwarding** - Your prompt, files (as references), and conversation history are sent as part of the prompt\n4. **CLI processing** - Gemini (or other CLI) uses its own tools: web search, file access, thinking modes\n5. **Seamless return** - Results flow back into your conversation with full context preserved\n6. **Continuation support** - Future tools and models can reference Gemini's findings via [continuation support](../context-revival.md) within PAL.\n\n## Best Practices\n\n- **Pre-authenticate CLIs**: Install and configure Gemini CLI first (`npm install -g @google/gemini-cli`)\n- **Choose appropriate roles**: Use `planner` for strategy, `codereviewer` for code, `default` for general questions\n- **Leverage CLI strengths**: Gemini's 1M context for large codebases, web search for current docs\n- **Combine with PAL tools**: Chain `clink` with `planner`, `codereview`, `debug` for powerful workflows\n- **File efficiency**: Pass file paths, let the CLI decide what to read (saves tokens)\n\n## Configuration\n\nClink configurations live in `conf/cli_clients/`. We ship presets for the supported CLIs:\n\n- `gemini.json` – runs `gemini --telemetry false --yolo -o json`\n- `claude.json` – runs `claude --print --output-format json --permission-mode acceptEdits --model sonnet`\n- `codex.json` – runs `codex exec --json --dangerously-bypass-approvals-and-sandbox`\n\n> **CAUTION**: These flags intentionally bypass each CLI's safety prompts so they can edit files or launch tools autonomously via MCP. Only enable them in trusted sandboxes and tailor role prompts or CLI configs if you need more guardrails.\n\nEach preset points to role-specific prompts in `systemprompts/clink/`. Duplicate those files to add more roles or adjust CLI flags.\n\n> **Why `--yolo` for Gemini?** The Gemini CLI currently requires automatic approvals to execute its own tools (for example `run_shell_command`). Without the flag it errors with `Tool \"run_shell_command\" not found in registry`. See [issue #5382](https://github.com/google-gemini/gemini-cli/issues/5382) for more details.\n\n**Adding new CLIs**: Drop a JSON config into `conf/cli_clients/`, create role prompts in `systemprompts/clink/`, and register a parser/agent if the CLI outputs a new format.\n\n## When to Use Clink vs Other Tools\n\n- **Use `clink`** for: Leveraging external CLI capabilities (Gemini's web search, 1M context), specialized CLI features, cross-CLI collaboration\n- **Use `chat`** for: Direct model-to-model conversations within PAL\n- **Use `planner`** for: PAL's native planning workflows with step validation\n- **Use `codereview`** for: PAL's structured code review with severity levels\n\n## Setup Requirements\n\nEnsure the relevant CLI is installed and configured:\n\n- [Claude Code](https://www.anthropic.com/claude-code)\n- [Gemini CLI](https://github.com/google-gemini/gemini-cli)\n- [Codex CLI](https://docs.sourcegraph.com/codex)\n\n## Related Guides\n\n- [Chat Tool](chat.md) - Direct model conversations\n- [Planner Tool](planner.md) - PAL's native planning workflows\n- [CodeReview Tool](codereview.md) - Structured code reviews\n- [Context Revival](../context-revival.md) - Continuing conversations across tools\n- [Advanced Usage](../advanced-usage.md) - Complex multi-tool workflows\n" }, { "path": "docs/tools/codereview.md", "content": "# CodeReview Tool - Professional Code Review\n\n**Comprehensive code analysis with prioritized feedback through workflow-driven investigation**\n\nThe `codereview` tool provides professional code review capabilities with actionable feedback, severity-based issue prioritization, and support for various review types from quick style checks to comprehensive security audits. This workflow tool guides Claude through systematic investigation steps with forced pauses between each step to ensure thorough code examination, issue identification, and quality assessment before providing expert analysis.\n\n## Thinking Mode\n\n**Default is `medium` (8,192 tokens).** Use `high` for security-critical code (worth the extra tokens) or `low` for quick style checks (saves ~6k tokens).\n\n## How the Workflow Works\n\nThe codereview tool implements a **structured workflow** that ensures thorough code examination:\n\n**Investigation Phase (Claude-Led):**\n1. **Step 1**: Claude describes the review plan and begins systematic analysis of code structure\n2. **Step 2+**: Claude examines code quality, security implications, performance concerns, and architectural patterns\n3. **Throughout**: Claude tracks findings, relevant files, issues, and confidence levels\n4. **Completion**: Once review is comprehensive, Claude signals completion\n\n**Expert Analysis Phase:**\nAfter Claude completes the investigation (unless confidence is **certain**):\n- Complete review summary with all findings and evidence\n- Relevant files and code patterns identified\n- Issues categorized by severity levels\n- Final recommendations based on investigation\n\n**Special Note**: If you want Claude to perform the entire review without calling another model, you can include \"don't use any other model\" in your prompt, and Claude will complete the full workflow independently.\n\n## Model Recommendation\n\nThis tool particularly benefits from Gemini Pro or Flash models due to their 1M context window, which allows comprehensive analysis of large codebases. Claude's context limitations make it challenging to see the \"big picture\" in complex projects - this is a concrete example where utilizing a secondary model with larger context provides significant value beyond just experimenting with different AI capabilities.\n\n## Example Prompts\n\n```\nPerform a codereview with gemini pro and review auth.py for security issues and potential vulnerabilities.\nI need an actionable plan but break it down into smaller quick-wins that we can implement and test rapidly \n```\n\n## Pro Tip: Multiple Parallel Reviews\n\n**You can start more than one codereview session with Claude:**\n\n```\nStart separate sub-tasks for codereview one with o3 finding critical issues and one with flash finding low priority issues\nand quick-wins and give me the final single combined review highlighting only the critical issues \n```\n\nThe above prompt will simultaneously run two separate `codereview` tools with two separate models and combine the output into a single summary for you to consume.\n\n## Key Features\n\n- **Issues prioritized by severity** (πŸ”΄ CRITICAL β†’ 🟒 LOW)\n- **Supports specialized reviews**: security, performance, quick\n- **Coding standards enforcement**: `\"Use gemini to review src/ against PEP8 standards\"`\n- **Severity filtering**: `\"Get gemini to review auth/ - only report critical vulnerabilities\"`\n- **Image support**: Review code from screenshots, error dialogs, or visual bug reports: `\"Review this error screenshot and the related auth.py file for potential security issues\"`\n- **Multi-file analysis**: Comprehensive review of entire directories or codebases\n- **Actionable feedback**: Specific recommendations with line numbers and code examples\n- **Language-specific expertise**: Tailored analysis for Python, JavaScript, Java, C#, Swift, and more\n- **Integration issue detection**: Identifies cross-file dependencies and architectural problems\n- **Security vulnerability scanning**: Focused on common security patterns and anti-patterns\n\n## Tool Parameters\n\n**Workflow Investigation Parameters (used during step-by-step process):**\n- `step`: Current investigation step description (required for each step)\n- `step_number`: Current step number in review sequence (required)\n- `total_steps`: Estimated total investigation steps (adjustable)\n- `next_step_required`: Whether another investigation step is needed\n- `findings`: Discoveries and evidence collected in this step (required)\n- `files_checked`: All files examined during investigation\n- `relevant_files`: Files directly relevant to the review (required in step 1)\n- `relevant_context`: Methods/functions/classes central to review findings\n- `issues_found`: Issues identified with severity levels\n- `confidence`: Confidence level in review completeness (exploring/low/medium/high/certain)\n- `images`: Visual references for review context\n\n**Initial Review Configuration (used in step 1):**\n- `prompt`: User's summary of what the code does, expected behavior, constraints, and review objectives (required)\n- `model`: auto|pro|flash|flash-2.0|flashlite|o3|o3-mini|o4-mini|gpt4.1|gpt5.2|gpt5.1-codex|gpt5.1-codex-mini|gpt5|gpt5-mini|gpt5-nano (default: server default)\n- `review_type`: full|security|performance|quick (default: full)\n- `focus_on`: Specific aspects to focus on (e.g., \"security vulnerabilities\", \"performance bottlenecks\")\n- `standards`: Coding standards to enforce (e.g., \"PEP8\", \"ESLint\", \"Google Style Guide\")\n- `severity_filter`: critical|high|medium|low|all (default: all)\n- `temperature`: Temperature for consistency (0-1, default 0.2)\n- `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)\n- `use_assistant_model`: Whether to use expert analysis phase (default: true, set to false to use Claude only)\n- `continuation_id`: Continue previous review discussions\n\n## Review Types\n\n**Full Review (default):**\n- Comprehensive analysis including bugs, security, performance, maintainability\n- Best for new features or significant code changes\n\n**Security Review:**\n- Focused on security vulnerabilities and attack vectors\n- Checks for common security anti-patterns\n- Best for authentication, authorization, data handling code\n\n**Performance Review:**\n- Analyzes performance bottlenecks and optimization opportunities\n- Memory usage, algorithmic complexity, resource management\n- Best for performance-critical code paths\n\n**Quick Review:**\n- Fast style and basic issue check\n- Lower token usage for rapid feedback\n- Best for code formatting and simple validation\n\n## Severity Levels\n\nIssues are categorized and prioritized:\n\n- **πŸ”΄ CRITICAL**: Security vulnerabilities, crashes, data corruption\n- **🟠 HIGH**: Logic errors, performance issues, reliability problems \n- **🟑 MEDIUM**: Code smells, maintainability issues, minor bugs\n- **🟒 LOW**: Style issues, documentation, minor improvements\n\n## Usage Examples\n\n**Basic Security Review:**\n```\n\"Review the authentication module in auth/ for security vulnerabilities with gemini pro\"\n```\n\n**Performance-Focused Review:**\n```\n\"Use o3 to review backend/api.py for performance issues, focus on database queries and caching\"\n```\n\n**Quick Style Check:**\n```\n\"Quick review of utils.py with flash, only report critical and high severity issues\"\n```\n\n**Standards Enforcement:**\n```\n\"Review src/ directory against PEP8 standards with gemini, focus on code formatting and structure\"\n```\n\n**Visual Context Review:**\n```\n\"Review this authentication code along with the error dialog screenshot to understand the security implications\"\n```\n\n## Best Practices\n\n- **Provide context**: Describe what the code is supposed to do and any constraints\n- **Use appropriate review types**: Security for auth code, performance for critical paths\n- **Set severity filters**: Focus on critical issues for quick wins\n- **Include relevant files**: Review related modules together for better context\n- **Use parallel reviews**: Run multiple reviews with different models for comprehensive coverage\n- **Follow up on findings**: Use the continuation feature to discuss specific issues in detail\n\n## Output Format\n\nReviews include:\n- **Executive Summary**: Overview of code quality and main concerns\n- **Detailed Findings**: Specific issues with severity levels, line numbers, and recommendations\n- **Quick Wins**: Easy-to-implement improvements with high impact\n- **Long-term Improvements**: Structural changes for better maintainability\n- **Security Considerations**: Specific security recommendations when relevant\n\n## When to Use CodeReview vs Other Tools\n\n- **Use `codereview`** for: Finding bugs, security issues, performance problems, code quality assessment\n- **Use `analyze`** for: Understanding code structure without finding issues\n- **Use `debug`** for: Diagnosing specific runtime errors or exceptions\n- **Use `refactor`** for: Identifying structural improvements and modernization opportunities\n" }, { "path": "docs/tools/consensus.md", "content": "# Consensus Tool - Multi-Model Perspective Gathering\n\n**Get diverse expert opinions from multiple AI models on technical proposals and decisions**\n\nThe `consensus` tool orchestrates multiple AI models to provide diverse perspectives on your proposals, enabling structured decision-making through for/against analysis and multi-model expert opinions.\n\n## Thinking Mode\n\n**Default is `medium` (8,192 tokens).** Use `high` for complex architectural decisions or `max` for critical strategic choices requiring comprehensive analysis.\n\n## Model Recommendation\n\nConsensus tool uses extended reasoning models by default, making it ideal for complex decision-making scenarios that benefit from multiple perspectives and deep analysis.\n\n## How It Works\n\nThe consensus tool orchestrates multiple AI models to provide diverse perspectives on your proposals:\n\n1. **Assign stances**: Each model can take a specific viewpoint (supportive, critical, or neutral)\n2. **Gather opinions**: Models analyze your proposal from their assigned perspective with built-in common-sense guardrails\n3. **Synthesize results**: Claude combines all perspectives into a balanced recommendation\n4. **Natural language**: Use simple descriptions like \"supportive\", \"critical\", or \"against\" - the tool handles synonyms automatically\n\n## Watch In Action\n\nThe following is a hypothetical example designed to demonstrate how one consensus can be built upon another (via [continuation](../context-revival.md)). In this scenario, we start with a _blinded_ consensus, where one model is tasked with taking a **for** stance and another with an **against** stance. This approach allows us to see how each model evaluates a particular option relative to the alternative. We then conduct a second consensus β€” all initiated by a single prompt and orchestrated by Claude Code in this video β€” to gather each model’s final conclusions.\n\n
\n \n [PAL Consensus Debate](https://github.com/user-attachments/assets/76a23dd5-887a-4382-9cf0-642f5cf6219e)\n \n
\n\n## Example Prompts\n\n**For/Against Analysis:**\n```\nUse pal consensus with flash taking a supportive stance and pro being critical to evaluate whether \nwe should migrate from REST to GraphQL for our API\n```\n\n**Multi-Model Technical Decision:**\n```\nGet consensus from o3, flash, and pro on our new authentication architecture. Have o3 focus on \nsecurity implications, flash on implementation speed, and pro stay neutral for overall assessment\n```\n\n**Natural Language Stance Assignment:**\n```\nUse consensus tool with gemini being \"for\" the proposal and grok being \"against\" to debate \nwhether we should adopt microservices architecture\n```\n\n```\nI want to work on module X and Y, unsure which is going to be more popular with users of my app. \nGet a consensus from gemini supporting the idea for implementing X, grok opposing it, and flash staying neutral\n```\n\n## Key Features\n\n- **Stance steering**: Assign specific perspectives (for/against/neutral) to each model with intelligent synonym handling\n- **Custom stance prompts**: Provide specific instructions for how each model should approach the analysis\n- **Ethical guardrails**: Models will refuse to support truly bad ideas regardless of assigned stance\n- **Unknown stance handling**: Invalid stances automatically default to neutral with warning\n- **Natural language support**: Use terms like \"supportive\", \"critical\", \"oppose\", \"favor\" - all handled intelligently\n- **Sequential processing**: Reliable execution avoiding MCP protocol issues\n- **Focus areas**: Specify particular aspects to emphasize (e.g., 'security', 'performance', 'user experience')\n- **File context support**: Include relevant files for informed decision-making\n- **Image support**: Analyze architectural diagrams, UI mockups, or design documents\n- **Conversation continuation**: Build on previous consensus analysis with additional rounds\n- **Web search capability**: Enhanced analysis with current best practices and documentation\n\n## Tool Parameters\n\n- `prompt`: Detailed description of the proposal or decision to analyze (required)\n- `models`: List of model configurations with optional stance and custom instructions (required)\n- `files`: Context files for informed analysis (absolute paths)\n- `images`: Visual references like diagrams or mockups (absolute paths)\n- `focus_areas`: Specific aspects to emphasize\n- `temperature`: Control consistency (default: 0.2 for stable consensus)\n- `thinking_mode`: Analysis depth (minimal/low/medium/high/max)\n- `continuation_id`: Continue previous consensus discussions\n\n## Model Configuration Examples\n\n**Basic For/Against:**\n```json\n[\n {\"model\": \"flash\", \"stance\": \"for\"},\n {\"model\": \"pro\", \"stance\": \"against\"}\n]\n```\n\n**Custom Stance Instructions:**\n```json\n[\n {\"model\": \"o3\", \"stance\": \"for\", \"stance_prompt\": \"Focus on implementation benefits and user value\"},\n {\"model\": \"flash\", \"stance\": \"against\", \"stance_prompt\": \"Identify potential risks and technical challenges\"}\n]\n```\n\n**Neutral Analysis:**\n```json\n[\n {\"model\": \"pro\", \"stance\": \"neutral\"},\n {\"model\": \"o3\", \"stance\": \"neutral\"}\n]\n```\n\n## Usage Examples\n\n**Architecture Decision:**\n```\n\"Get consensus from pro and o3 on whether to use microservices vs monolith for our e-commerce platform\"\n```\n\n**Technology Migration:**\n```\n\"Use consensus with flash supporting and pro opposing to evaluate migrating from MySQL to PostgreSQL\"\n```\n\n**Feature Priority:**\n```\n\"Get consensus from multiple models on whether to prioritize mobile app vs web dashboard development first\"\n```\n\n**With Visual Context:**\n```\n\"Use consensus to evaluate this new UI design mockup - have flash support it and pro be critical\"\n```\n\n## Best Practices\n\n- **Provide detailed context**: Include project constraints, requirements, and background\n- **Use balanced stances**: Mix supportive and critical perspectives for thorough analysis\n- **Specify focus areas**: Guide models to emphasize relevant aspects (security, performance, etc.)\n- **Include relevant files**: Provide code, documentation, or specifications for context\n- **Build on discussions**: Use continuation for follow-up analysis and refinement\n- **Leverage visual context**: Include diagrams, mockups, or design documents when relevant\n\n## Ethical Guardrails\n\nThe consensus tool includes built-in ethical safeguards:\n- Models won't support genuinely harmful proposals regardless of assigned stance\n- Unknown or invalid stances automatically default to neutral\n- Warning messages for potentially problematic requests\n- Focus on constructive technical decision-making\n\n## When to Use Consensus vs Other Tools\n\n- **Use `consensus`** for: Multi-perspective analysis, structured debates, major technical decisions\n- **Use `chat`** for: Open-ended discussions and brainstorming\n- **Use `thinkdeep`** for: Extending specific analysis with deeper reasoning\n- **Use `analyze`** for: Understanding existing systems without debate\n" }, { "path": "docs/tools/debug.md", "content": "# Debug Tool - Systematic Investigation & Expert Analysis\n\n**Step-by-step investigation followed by expert debugging assistance**\n\nThe `debug` workflow guides Claude through a systematic investigation process where Claude performs methodical code \nexamination, evidence collection, and hypothesis formation across multiple steps. Once the investigation is complete, \nthe tool provides expert analysis from the selected AI model (optionally) based on all gathered findings.\n\n## Example Prompts\n\n```\nGet gemini to debug why my API returns 400 errors randomly with the full stack trace: [paste traceback]\n```\n\nYou can also ask it to debug on its own, no external model required (**recommended in most cases**).\n```\nUse debug tool to find out why the app is crashing, here are some app logs [paste app logs] and a crash trace: [paste crash trace]\n```\n\n## How It Works \n\nThe debug tool implements a **systematic investigation methodology** where Claude is guided through structured debugging steps:\n\n**Investigation Phase:**\n1. **Step 1**: Claude describes the issue and begins thinking deeply about possible underlying causes, side-effects, and contributing factors\n2. **Step 2+**: Claude examines relevant code, traces errors, tests hypotheses, and gathers evidence\n3. **Throughout**: Claude tracks findings, relevant files, methods, and evolving hypotheses with confidence levels\n4. **Backtracking**: Claude can revise previous steps when new insights emerge\n5. **Completion**: Once investigation is thorough, Claude signals completion\n\n**Expert Analysis Phase:**\nAfter Claude completes the investigation, it automatically calls the selected AI model with (unless confidence is **certain**, \nin which case expert analysis is bypassed):\n- Complete investigation summary with all steps and findings\n- Relevant files and methods identified during investigation \n- Final hypothesis and confidence assessment\n- Error context and supporting evidence\n- Visual debugging materials if provided\n\nThis structured approach ensures Claude performs methodical groundwork before expert analysis, resulting in significantly better debugging outcomes and more efficient token usage.\n\n**Special Note**: If you want Claude to perform the entire debugging investigation without calling another model, you can include \"don't use any other model\" in your prompt, and Claude will complete the full workflow independently.\n\n## Key Features\n\n- **Multi-step investigation process** with evidence collection and hypothesis evolution\n- **Systematic code examination** with file and method tracking throughout investigation\n- **Confidence assessment and revision** capabilities for investigative steps\n- **Backtracking support** to revise previous steps when new insights emerge\n- **Expert analysis integration** that provides final debugging recommendations based on complete investigation\n- **Error context support**: Stack traces, logs, and runtime information\n- **Visual debugging**: Include error screenshots, stack traces, console output\n- **Conversation threading**: Continue investigations across multiple sessions\n- **Large context analysis**: Handle extensive log files and multiple related code files\n- **Multi-language support**: Debug issues across Python, JavaScript, Java, C#, Swift, and more\n- **Web search integration**: Identifies when additional research would help solve problems\n\n## Tool Parameters\n\n**Investigation Step Parameters:**\n- `step`: Current investigation step description (required)\n- `step_number`: Current step number in investigation sequence (required)\n- `total_steps`: Estimated total investigation steps (adjustable as process evolves)\n- `next_step_required`: Whether another investigation step is needed\n- `findings`: Discoveries and evidence collected in this step (required)\n- `files_checked`: All files examined during investigation (tracks exploration path)\n- `relevant_files`: Files directly tied to the root cause or its effects\n- `relevant_methods`: Specific methods/functions involved in the issue\n- `hypothesis`: Current best guess about the underlying cause\n- `confidence`: Confidence level in current hypothesis (exploring/low/medium/high/certain)\n- `continuation_id`: Thread ID for continuing investigations across sessions\n- `images`: Visual debugging materials (error screenshots, logs, etc.)\n\n**Model Selection:**\n- `model`: auto|pro|flash|flash-2.0|flashlite|o3|o3-mini|o4-mini|gpt4.1|gpt5.2|gpt5.1-codex|gpt5.1-codex-mini|gpt5|gpt5-mini|gpt5-nano (default: server default)\n- `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)\n- `use_assistant_model`: Whether to use expert analysis phase (default: true, set to false to use Claude only)\n\n## Usage Examples\n\n**Error Debugging:**\n```\nDebug this TypeError: 'NoneType' object has no attribute 'split' in my parser.py\n```\n\n**With Stack Trace:**\n```\nUse gemini to debug why my API returns 500 errors with this stack trace: [paste full traceback]\n```\n\n**With File Context:**\n```\nDebug without using external model, the authentication failure in auth.py and user_model.py\n```\n\n**Performance Debugging:**\n```\nDebug without using external model to find out why the app is consuming excessive memory during bulk edit operations\n```\n\n**Runtime Environment Issues:**\n```\nDebug deployment issues with server startup failures, here's the runtime info: [environment details]\n```\n\n## Investigation Methodology\n\nThe debug tool enforces a thorough, structured investigation process:\n\n**Step-by-Step Investigation (Claude-Led):**\n1. **Initial Problem Description:** Claude describes the issue and begins thinking about possible causes, side-effects, and contributing factors\n2. **Code Examination:** Claude systematically examines relevant files, traces execution paths, and identifies suspicious patterns\n3. **Evidence Collection:** Claude gathers findings, tracks files checked, and identifies methods/functions involved\n4. **Hypothesis Formation:** Claude develops working theories about the root cause with confidence assessments\n5. **Iterative Refinement:** Claude can backtrack and revise previous steps as understanding evolves\n6. **Investigation Completion:** Claude signals when sufficient evidence has been gathered\n\n**Expert Analysis Phase (Another AI Model When Used):**\nOnce investigation is complete, the selected AI model performs:\n- **Root Cause Analysis:** Deep analysis of all investigation findings and evidence\n- **Solution Recommendations:** Specific fixes with implementation guidance\n- **Prevention Strategies:** Measures to avoid similar issues in the future\n- **Testing Approaches:** Validation methods for proposed solutions\n\n**Key Benefits:**\n- **Methodical Evidence Collection:** Ensures no critical information is missed\n- **Progressive Understanding:** Hypotheses evolve as investigation deepens\n- **Complete Context:** Expert analysis receives full investigation history\n- **Efficient Token Usage:** Structured approach prevents redundant back-and-forth\n\n## Debugging Categories\n\n**Runtime Errors:**\n- Exceptions and crashes\n- Null pointer/reference errors\n- Type errors and casting issues\n- Memory leaks and resource exhaustion\n\n**Logic Errors:**\n- Incorrect algorithm implementation\n- Off-by-one errors and boundary conditions\n- State management issues\n- Race conditions and concurrency bugs\n\n**Integration Issues:**\n- API communication failures\n- Database connection problems\n- Third-party service integration\n- Configuration and environment issues\n\n**Performance Problems:**\n- Slow response times\n- Memory usage spikes\n- CPU-intensive operations\n- I/O bottlenecks\n\n## Best Practices\n\n**For Investigation Steps:**\n- **Be thorough in step descriptions**: Explain what you're examining and why\n- **Track all files examined**: Include even files that don't contain the bug (tracks investigation path)\n- **Document findings clearly**: Summarize discoveries, suspicious patterns, and evidence\n- **Evolve hypotheses**: Update theories as investigation progresses\n- **Use backtracking wisely**: Revise previous steps when new insights emerge\n- **Include visual evidence**: Screenshots, error dialogs, console output\n\n**For Initial Problem Description:**\n- **Provide complete error context**: Full stack traces, error messages, and logs\n- **Describe expected vs actual behavior**: Clear symptom description\n- **Include environment details**: Runtime versions, configuration, deployment context\n- **Mention previous attempts**: What debugging steps have already been tried\n- **Be specific about occurrence**: When, where, and how the issue manifests\n\n## Advanced Features\n\n**Large Log Analysis:**\nWith models like Gemini Pro (1M context), you can include extensive log files for comprehensive analysis:\n```\n\"Debug application crashes using these large log files: app.log, error.log, system.log\"\n```\n\n**Multi-File Investigation:**\nAnalyze multiple related files simultaneously to understand complex issues:\n```\n\"Debug the data processing pipeline issues across processor.py, validator.py, and output_handler.py\"\n```\n\n**Web Search Integration:**\nThe tool can recommend specific searches for error messages, known issues, or documentation:\n```\nAfter analysis: \"Recommended searches for Claude: 'Django 4.2 migration error specific_error_code', 'PostgreSQL connection pool exhaustion solutions'\"\n```\n\n## When to Use Debug vs Other Tools\n\n- **Use `debug`** for: Specific runtime errors, exceptions, crashes, performance issues requiring systematic investigation\n- **Use `codereview`** for: Finding potential bugs in code without specific errors or symptoms\n- **Use `analyze`** for: Understanding code structure and flow without troubleshooting specific issues\n- **Use `precommit`** for: Validating changes before commit to prevent introducing bugs\n\n## Investigation Example\n\n**Step 1:** \"The user authentication fails intermittently with no error logs. I need to investigate the auth flow and identify where failures might occur silently.\"\n\n**Step 2:** \"Examined auth.py and found three potential failure points: token validation, database connectivity, and session management. No obvious bugs yet but need to trace execution flow.\"\n\n**Step 3:** \"Found suspicious async/await pattern in session_manager.py lines 45-67. The await might be missing exception handling. This could explain silent failures.\"\n\n**Completion:** Investigation reveals likely root cause in exception handling, ready for expert analysis with full context.\n" }, { "path": "docs/tools/docgen.md", "content": "# DocGen Tool - Comprehensive Documentation Generation\n\n**Generates comprehensive documentation with complexity analysis through workflow-driven investigation**\n\nThe `docgen` tool creates thorough documentation by analyzing your code structure, understanding function complexity, and documenting gotchas and unexpected behaviors that developers need to know. This workflow tool guides Claude through systematic investigation of code functionality, architectural patterns, and documentation needs across multiple steps before generating comprehensive documentation with complexity analysis and call flow information.\n\n## How the Workflow Works\n\nThe docgen tool implements a **structured workflow** for comprehensive documentation generation:\n\n**Investigation Phase (Claude-Led):**\n1. **Step 1 (Discovery)**: Claude discovers ALL files needing documentation and reports exact count\n2. **Step 2+ (Documentation)**: Claude documents files one-by-one with complete coverage validation\n3. **Throughout**: Claude tracks progress with counters and enforces modern documentation styles\n4. **Completion**: Only when all files are documented (num_files_documented = total_files_to_document)\n\n**Documentation Generation Phase:**\nAfter Claude completes the investigation:\n- Complete documentation strategy with style consistency\n- Function/method documentation with complexity analysis\n- Call flow and dependency documentation\n- Gotchas and unexpected behavior documentation\n- Final polished documentation following project standards\n\nThis workflow ensures methodical analysis before documentation generation, resulting in more comprehensive and valuable documentation.\n\n## Model Recommendation\n\nDocumentation generation excels with analytical models like Gemini Pro or O3, which can understand complex code relationships, identify non-obvious behaviors, and generate thorough documentation that covers gotchas and edge cases. The combination of large context windows and analytical reasoning enables generation of documentation that helps prevent integration issues and developer confusion.\n\n## Example Prompts\n\n**Basic Usage:**\n```\n\"Use pal to generate documentation for the UserManager class\"\n\"Document the authentication module with complexity analysis using gemini pro\"\n\"Add comprehensive documentation to all methods in src/payment_processor.py\"\n```\n\n## Key Features\n\n- **Systematic file-by-file approach** - Complete documentation with progress tracking and validation\n- **Modern documentation styles** - Enforces /// for Objective-C/Swift, /** */ for Java/JavaScript, etc.\n- **Complexity analysis** - Big O notation for algorithms and performance characteristics\n- **Call flow documentation** - Dependencies and method relationships\n- **Counter-based completion** - Prevents stopping until all files are documented\n- **Large file handling** - Systematic portion-by-portion documentation for comprehensive coverage\n- **Final verification scan** - Mandatory check to ensure no functions are missed\n- **Bug tracking** - Surfaces code issues without altering logic\n- **Configuration parameters** - Control complexity analysis, call flow, and inline comments\n\n## Tool Parameters\n\n**Workflow Parameters (used during step-by-step process):**\n- `step`: Current step description - discovery phase (step 1) or documentation phase (step 2+)\n- `step_number`: Current step number in documentation sequence (required)\n- `total_steps`: Dynamically calculated as 1 + total_files_to_document\n- `next_step_required`: Whether another step is needed\n- `findings`: Discoveries about code structure and documentation needs (required)\n- `relevant_files`: Files being actively documented in current step\n- `num_files_documented`: Counter tracking completed files (required)\n- `total_files_to_document`: Total count of files needing documentation (required)\n\n**Configuration Parameters (required fields):**\n- `document_complexity`: Include Big O complexity analysis (default: true)\n- `document_flow`: Include call flow and dependency information (default: true)\n- `update_existing`: Update existing documentation when incorrect/incomplete (default: true)\n- `comments_on_complex_logic`: Add inline comments for complex algorithmic steps (default: true)\n\n## Usage Examples\n\n**Class Documentation:**\n```\n\"Generate comprehensive documentation for the PaymentProcessor class including complexity analysis\"\n```\n\n**Module Documentation:**\n```\n\"Document all functions in the authentication module with call flow information\"\n```\n\n**API Documentation:**\n```\n\"Create documentation for the REST API endpoints in api/users.py with parameter gotchas\"\n```\n\n**Algorithm Documentation:**\n```\n\"Document the sorting algorithm in utils/sort.py with Big O analysis and edge cases\"\n```\n\n**Library Documentation:**\n```\n\"Add comprehensive documentation to the utility library with usage examples and warnings\"\n```\n\n## Documentation Standards\n\n**Function/Method Documentation:**\n- Parameter types and descriptions\n- Return value documentation with types\n- Algorithmic complexity analysis (Big O notation)\n- Call flow and dependency information\n- Purpose and behavior explanation\n- Exception types and conditions\n\n**Gotchas and Edge Cases:**\n- Parameter combinations that produce unexpected results\n- Hidden dependencies on global state or environment\n- Order-dependent operations where sequence matters\n- Performance implications and bottlenecks\n- Thread safety considerations\n- Platform-specific behavior differences\n\n**Code Quality Documentation:**\n- Inline comments for complex logic\n- Design pattern explanations\n- Architectural decision rationale\n- Usage examples and best practices\n\n## Documentation Features Generated\n\n**Complexity Analysis:**\n- Time complexity (Big O notation)\n- Space complexity when relevant\n- Worst-case, average-case, and best-case scenarios\n- Performance characteristics and bottlenecks\n\n**Call Flow Documentation:**\n- Which methods/functions this code calls\n- Which methods/functions call this code\n- Key dependencies and interactions\n- Side effects and state modifications\n- Data flow through functions\n\n**Gotchas Documentation:**\n- Non-obvious parameter interactions\n- Hidden state dependencies\n- Silent failure conditions\n- Resource management requirements\n- Version compatibility issues\n- Platform-specific behaviors\n\n## Incremental Documentation Approach\n\n**Key Benefits:**\n- **Immediate value delivery** - Code becomes more maintainable right away\n- **Iterative improvement** - Pattern recognition across multiple analysis rounds\n- **Quality validation** - Testing documentation effectiveness during workflow\n- **Reduced cognitive load** - Focus on one function/method at a time\n\n**Workflow Process:**\n1. **Analyze and Document**: Examine each function and immediately add documentation\n2. **Continue Analyzing**: Move to next function while building understanding\n3. **Refine and Standardize**: Review and improve previously added documentation\n\n## Language Support\n\n**Modern Documentation Style Enforcement:**\n- **Python**: Triple-quote docstrings with type hints\n- **Objective-C**: /// comments\n- **Swift**: /// comments\n- **JavaScript/TypeScript**: /** */ JSDoc style\n- **Java**: /** */ Javadoc style \n- **C#**: /// XML documentation comments\n- **C/C++**: /// for documentation comments\n- **Go**: // comments above functions/types\n- **Rust**: /// for documentation comments\n\n## Documentation Quality Features\n\n**Comprehensive Coverage:**\n- All public methods and functions\n- Complex private methods requiring explanation\n- Class and module-level documentation\n- Configuration and setup requirements\n\n**Developer-Focused:**\n- Clear explanations of non-obvious behavior\n- Usage examples for complex APIs\n- Warning about common pitfalls\n- Integration guidance and best practices\n\n**Maintainable Format:**\n- Consistent documentation style\n- Appropriate level of detail\n- Cross-references and links\n- Version and compatibility notes\n\n## Best Practices\n\n- **Use systematic approach**: Tool now documents all files with progress tracking and validation\n- **Trust the counters**: Tool prevents premature completion until all files are documented\n- **Large files handled**: Tool automatically processes large files in systematic portions\n- **Modern styles enforced**: Tool ensures correct documentation style per language\n- **Configuration matters**: Enable complexity analysis and call flow for comprehensive docs\n- **Bug tracking**: Tool surfaces issues without altering code - review findings after completion\n\n## When to Use DocGen vs Other Tools\n\n- **Use `docgen`** for: Creating comprehensive documentation, adding missing docs, improving existing documentation\n- **Use `analyze`** for: Understanding code structure without generating documentation\n- **Use `codereview`** for: Reviewing code quality including documentation completeness\n- **Use `refactor`** for: Restructuring code before documentation (cleaner code = better docs)" }, { "path": "docs/tools/listmodels.md", "content": "# ListModels Tool - List Available Models\n\n**Display all available AI models organized by provider**\n\nThe `listmodels` tool shows which providers are configured, available models, their aliases, context windows, and capabilities. This is useful for understanding what models can be used and their characteristics.\n\n## Usage\n\n```\n\"Use pal to list available models\"\n```\n\n## Key Features\n\n- **Provider organization**: Shows all configured providers and their status\n- **Model capabilities**: Context windows, thinking mode support, and special features\n- **Alias mapping**: Shows shorthand names and their full model mappings\n- **Configuration status**: Indicates which providers are available based on API keys\n- **Context window information**: Helps you choose models based on your content size needs\n- **Capability overview**: Understanding which models support extended thinking, vision, etc.\n\n## Output Information\n\nThe tool displays:\n\n**Provider Status:**\n- Which providers are configured and available\n- API key status (without revealing the actual keys)\n- Provider priority order\n\n**Model Details:**\n- Full model names and their aliases\n- Context window sizes (tokens)\n- Special capabilities (thinking modes, vision support, etc.)\n- Provider-specific features\n\n**Capability Summary:**\n- Which models support extended thinking\n- Vision-capable models for image analysis\n- Models with largest context windows\n- Fastest models for quick tasks\n\n## Example Output\n\n```\nπŸ“‹ Available Models by Provider\n\nπŸ”Ή Google (Gemini) - βœ… Configured\n β€’ pro (gemini-2.5-pro) - 1M context, thinking modes\n β€’ flash (gemini-2.0-flash-experimental) - 1M context, ultra-fast\n\nπŸ”Ή OpenAI - βœ… Configured \n β€’ o3 (o3) - 200K context, strong reasoning\n β€’ o3-mini (o3-mini) - 200K context, balanced\n β€’ o4-mini (o4-mini) - 200K context, latest reasoning\n\nπŸ”Ή Custom/Local - βœ… Configured\n β€’ local-llama (llama3.2) - 128K context, local inference\n β€’ Available at: http://localhost:11434/v1\n\nπŸ”Ή OpenRouter - ❌ Not configured\n Set OPENROUTER_API_KEY to enable access to Claude, GPT-4, and more models\n```\n\n## When to Use ListModels\n\n- **Model selection**: When you're unsure which models are available\n- **Capability checking**: To verify what features each model supports\n- **Configuration validation**: To confirm your API keys are working\n- **Context planning**: To choose models based on content size requirements\n- **Performance optimization**: To select the right model for speed vs quality trade-offs\n\n## Configuration Dependencies\n\nThe available models depend on your configuration:\n\n**API Keys Required:**\n- `GEMINI_API_KEY` - Enables Gemini Pro and Flash models\n- `OPENAI_API_KEY` - Enables OpenAI O3, O4-mini, and GPT models\n- `OPENROUTER_API_KEY` - Enables access to multiple providers through OpenRouter\n- `CUSTOM_API_URL` - Enables local/custom models (Ollama, vLLM, etc.)\n\n**Model Restrictions:**\nIf you've set model usage restrictions via environment variables, the tool will show:\n- Which models are allowed vs restricted\n- Active restriction policies\n- How to modify restrictions\n\n## Tool Parameters\n\nThis tool requires no parameters - it simply queries the server configuration and displays all available information.\n\n## Best Practices\n\n- **Check before planning**: Use this tool to understand your options before starting complex tasks\n- **Verify configuration**: Confirm your API keys are working as expected\n- **Choose appropriate models**: Match model capabilities to your specific needs\n- **Understand limits**: Be aware of context windows when working with large files\n\n## When to Use ListModels vs Other Tools\n\n- **Use `listmodels`** for: Understanding available options and model capabilities\n- **Use `chat`** for: General discussions about which model to use for specific tasks\n- **Use `version`** for: Server configuration and version information\n- **Use other tools** for: Actual analysis, debugging, or development work" }, { "path": "docs/tools/planner.md", "content": "# Planner Tool - Interactive Step-by-Step Planning\n\n**Break down complex projects into manageable, structured plans through step-by-step thinking**\n\nThe `planner` tool helps you break down complex ideas, problems, or projects into multiple manageable steps. Perfect for system design, migration strategies, \narchitectural planning, and feature development with branching and revision capabilities.\n\n## How It Works\n\nThe planner tool enables step-by-step thinking with incremental plan building:\n\n1. **Start with step 1**: Describe the task or problem to plan\n2. **Continue building**: Add subsequent steps, building the plan piece by piece \n3. **Revise when needed**: Update earlier decisions as new insights emerge\n4. **Branch alternatives**: Explore different approaches when multiple options exist\n5. **Continue across sessions**: Resume planning later with full context\n\n## Example Prompts\n\n#### Pro Tip\nClaude supports `sub-tasks` where it will spawn and run separate background tasks. You can ask Claude to \nrun PAL's planner with two separate ideas. Then when it's done, use PAL's `consensus` tool to pass the entire\nplan and get expert perspective from two powerful AI models on which one to work on first! Like performing **AB** testing\nin one-go without the wait!\n\n```\nCreate two separate sub-tasks: in one, using planner tool show me how to add natural language support \nto my cooking app. In the other sub-task, use planner to plan how to add support for voice notes to my cooking app. \nOnce done, start a consensus by sharing both plans to o3 and flash to give me the final verdict. Which one do \nI implement first?\n```\n\n```\nUse pal's planner and show me how to add real-time notifications to our mobile app\n```\n\n```\nUsing the planner tool, show me how to add CoreData sync to my app, include any sub-steps\n```\n\n## Key Features\n\n- **Step-by-step breakdown**: Build plans incrementally with full context awareness\n- **Branching support**: Explore alternative approaches when needed \n- **Revision capabilities**: Update earlier decisions as new insights emerge\n- **Multi-session continuation**: Resume planning across multiple sessions with context\n- **Dynamic adjustment**: Modify step count and approach as planning progresses\n- **Visual presentation**: ASCII charts, diagrams, and structured formatting\n- **Professional output**: Clean, structured plans without emojis or time estimates\n\n## More Examples\n\n```\nUsing planner, plan the architecture for a new real-time chat system with 100k concurrent users\n```\n\n```\nCreate a plan using pal for migrating our React app from JavaScript to TypeScript\n```\n\n```\nDevelop a plan using pal for implementing CI/CD pipelines across our development teams\n```\n\n## Best Practices\n\n- **Start broad, then narrow**: Begin with high-level strategy, then add implementation details\n- **Include constraints**: Consider technical, organizational, and resource limitations\n- **Plan for validation**: Include testing and verification steps\n- **Think about dependencies**: Identify what needs to happen before each step\n- **Consider alternatives**: Note when multiple approaches are viable\n- **Enable continuation**: Use continuation_id for multi-session planning\n\n## Continue With a New Plan\n\nLike all other tools in PAL, you can `continue` with a new plan using the output from a previous plan by simply saying\n\n```\nContinue with pal's consensus tool and find out what o3:for and flash:against think of the plan \n```\n\nYou can mix and match and take one output and feed it into another, continuing from where you left off using a different \ntool / model combination.\n" }, { "path": "docs/tools/precommit.md", "content": "# PreCommit Tool - Pre-Commit Validation\n\n**Comprehensive review of staged/unstaged git changes across multiple repositories through workflow-driven investigation**\n\nThe `precommit` tool provides thorough validation of git changes before committing, ensuring code quality, requirement compliance, and preventing regressions across multiple repositories. This workflow tool guides Claude through systematic investigation of git changes, repository status, and file modifications across multiple steps before providing expert validation.\n\n## Thinking Mode\n\n**Default is `medium` (8,192 tokens).** Use `high` or `max` for critical releases when thorough validation justifies the token cost.\n\n## How the Workflow Works\n\nThe precommit tool implements a **structured workflow** for comprehensive change validation:\n\n**Investigation Phase (Claude-Led):**\n1. **Step 1**: Claude states validation strategy using direct statements (\"I will examine...\" not \"Let me examine...\")\n2. **Step 2**: Claude examines changes, diffs, dependencies with MANDATORY deeper investigation\n3. **Step 3+**: Claude performs final verification (minimum 3 steps enforced)\n4. **Throughout**: Claude tracks findings, relevant files, and issues with CRITICAL step validation\n5. **Completion**: Only after minimum steps, Claude signals completion and creates changeset file\n\n**For Continuations**: When using `continuation_id` with external validation, Claude will immediately gather git changes and proceed to expert analysis without minimum step requirements.\n\n**Expert Validation Phase:**\nAfter Claude completes the investigation (unless precommit_type is **internal**):\n- Complete summary of all changes and their context\n- Potential issues and regressions identified\n- Requirement compliance assessment\n- Final recommendations for safe commit\n\n**Special Notes**: \n- Default validation type is **external** (uses expert model for additional review)\n- To skip expert validation, explicitly request \"don't use any other model\" or set precommit_type to \"internal\"\n- **CRITICAL**: Minimum 3 steps are enforced - tool will prevent setting `next_step_required=false` before final step\n- **MANDATORY**: Changeset file (pal_precommit.changeset) must be created for external validation\n\n## Model Recommendation\n\nPre-commit validation benefits significantly from models with extended context windows like Gemini Pro, which can analyze extensive changesets across multiple files and repositories simultaneously. This comprehensive view enables detection of cross-file dependencies, architectural inconsistencies, and integration issues that might be missed when reviewing changes in isolation due to context constraints.\n\n## Visual Example\n\n
\n \n
\n\n**Prompt Used:**\n```\nNow use gemini and perform a review and precommit and ensure original requirements are met, no duplication of code or\nlogic, everything should work as expected\n```\n\nHow beautiful is that? Claude used `precommit` twice and `codereview` once and actually found and fixed two critical errors before commit!\n\n### Real-world Example\n\nHere's an example where Claude was made to go through changes *it* was asked to make. Its recommendation \nto **Publish all Changes** was made after a rigorous set of prompts where it examined the small set of changes \nfrom different angles (performance, bugs, anti-patterns etc). After confirming that unit tests were \npassing, it went ahead with an initial review with O3; came back clean - all good to go. O3 was happy, everything looked great.\n\nThen it shared the changes and relevant code with Gemini 3.0 Pro - the following is the outcome:\n\n```\n⏺ pal:precommit (MCP)(step: \"FINAL VALIDATION COMPLETE. All changes have been thoroughly analyzed and are ready for\n commit. The modifications successfully fix 4 GitHub CI test failures with high-quality, defensive\n implementations that maintain architectural integrity and coding standards. No issues or regressions\n detected.\", step_number: 4, total_steps: 4, next_step_required: false, findings: \"COMMIT\n RECOMMENDATION: βœ… APPROVED\\n\\nSUMMARY OF CHANGES:\\nβœ… Fixed 4 GitHub CI test failures:\\n -\n test_openrouter_with_restrictions (Mock iteration issue) \\n - test_execute_with_branching\n (Missing metadata)\\n - test_execute_with_revision (Missing metadata)\\n - test_metadata_preserved\n (Provider type AttributeError)\\n\\nβœ… IMPLEMENTATION QUALITY VERIFIED:\\n - Defensive programming\n with proper type checking\\n - Error handling with meaningful fallbacks\\n - Backward\n compatibility maintained\\n - Coding standards followed (no hasattr/getattr in changes)\\n -\n Architectural patterns preserved\\n\\nβœ… COMPREHENSIVE TESTING:\\n - All originally failing tests\n pass\\n - Affected functionality: 37/37 tests pass\\n - Provider systems: 16/16 tests pass \\n -\n Module imports work correctly\\n - No regressions detected\\n\\nβœ… CHANGE IMPACT ASSESSMENT:\\n -\n Minimal, targeted changes\\n - No security or performance concerns\\n - Maintains API\n compatibility\\n - Changes are well-documented with clear comments\\n\\nRECOMMENDATION: These changes\n are safe to commit and will resolve the GitHub CI failures without any negative impact.\",\n ⎿ Β {\n \"status\": \"calling_expert_analysis\",\n \"step_number\": 4,\n … +169 lines (ctrl+r to expand)\n\n⏺ πŸ” Pre-Commit Validation Complete\n\n Based on comprehensive analysis using both O3 and Gemini 3.0 Pro models, I can provide the following assessment:\n\n βœ… APPROVED WITH CRITICAL FIX REQUIRED\n\n The changes successfully fix all 4 GitHub CI test failures and are well-implemented with defensive programming\n patterns. However, the expert analysis identified one critical issue that must be addressed before commit:\n\n 🚨 [HIGH PRIORITY] Critical Issue Found\n\n Inconsistent Provider Handling in tools/shared/base_tool.py\n - Location: tools/shared/base_tool.py inside _create_continuation_offer_response\n - Problem: The defensive provider handling pattern was applied in 2 locations but missed a 3rd location\n - Impact: Risk of AttributeError: 'str' object has no attribute 'get_provider_type' in continuation scenarios\n - Fix Required: Apply the same defensive pattern to the missed location\n```\n\nA subtle but critical issue spotted by Gemini that both Claude + O3 missed. This is the power of running these workflows with PAL.\n\n## Example Prompts\n\n```\nUse pal and perform a thorough precommit ensuring there aren't any new regressions or bugs introduced\n```\n\n## Key Features\n\n- **Recursive repository discovery** - finds all git repos including nested ones\n- **Validates changes against requirements** - ensures implementation matches intent\n- **Detects incomplete changes** - finds added functions never called, missing tests, etc.\n- **Multi-repo support** - reviews changes across multiple repositories in one go\n- **Configurable scope** - review staged, unstaged, or compare against branches\n- **Security focused** - catches exposed secrets, vulnerabilities in new code\n- **Smart truncation** - handles large diffs without exceeding context limits\n- **Cross-file dependency analysis** - identifies breaking changes across modules\n- **Test coverage validation** - ensures new code has appropriate test coverage\n- **Regression detection** - compares against requirements to prevent scope creep\n\n## Tool Parameters\n\n**Workflow Investigation Parameters (used during step-by-step process):**\n- `step`: Technical brief to another engineer using direct statements (required, FORBIDDEN: large code snippets)\n- `step_number`: Current step number in validation sequence (required, starts at 1)\n- `total_steps`: Estimated total investigation steps (minimum 3 enforced)\n- `next_step_required`: Whether another investigation step is needed (CRITICAL: must be true until final step)\n- `findings`: Specific discoveries and evidence from actual investigation (required, no vague language)\n- `files_checked`: All files examined during investigation\n- `relevant_files`: Files directly relevant to the changes\n- `relevant_context`: Methods/functions/classes affected by changes\n- `issues_found`: Issues identified with severity levels\n- `precommit_type`: Type of validation to perform (external/internal, default: external - ALWAYS use external unless explicitly told otherwise)\n- `images`: Screenshots of requirements, design mockups for validation\n\n**Initial Configuration (used in step 1):**\n- `path`: Starting directory to search for repos (REQUIRED for step 1, must be absolute path)\n- `prompt`: The original user request description for the changes (required for context)\n- `model`: auto|pro|flash|flash-2.0|flashlite|o3|o3-mini|o4-mini|gpt4.1|gpt5.2|gpt5.1-codex|gpt5.1-codex-mini|gpt5|gpt5-mini|gpt5-nano (default: server default)\n- `compare_to`: Compare against a branch/tag instead of local changes (optional)\n- `severity_filter`: critical|high|medium|low|all (default: all)\n- `include_staged`: Include staged changes in the review (default: true)\n- `include_unstaged`: Include uncommitted changes in the review (default: true)\n- `focus_on`: Specific aspects to focus on\n- `temperature`: Temperature for response (default: 0.2)\n- `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)\n- `use_assistant_model`: Whether to use expert validation phase (default: true, set to false to use Claude only)\n- `continuation_id`: Continue previous validation discussions\n\n## Usage Examples\n\n**Basic Pre-commit Validation:**\n```\n\"Use pal precommit to validate my changes before committing\"\n```\n\n**Security-Focused Validation:**\n```\n\"Perform precommit security review with gemini pro on the authentication changes\"\n```\n\n**Multi-Repository Validation:**\n```\n\"Validate changes across all repositories in this workspace with o3\"\n```\n\n**Against Specific Branch:**\n```\n\"Compare current changes against main branch with precommit using gemini pro\"\n```\n\n**With Requirements Context:**\n```\n\"Precommit validation ensuring the new payment feature meets requirements in FEATURE_SPEC.md\"\n```\n\n## Validation Scope\n\nThe tool automatically discovers and validates:\n\n**Repository Discovery:**\n- Searches recursively for all `.git` directories\n- Handles nested repositories and submodules\n- Configurable search depth to prevent excessive recursion\n\n**Change Analysis:**\n- Staged changes (`git diff --cached`)\n- Unstaged changes (`git diff`)\n- Untracked files that should be added\n- Deleted files and their impact\n\n**Cross-Repository Impact:**\n- Shared dependencies between repositories\n- API contract changes that affect other repos\n- Configuration changes with system-wide impact\n\n## Validation Categories\n\n**Completeness Checks:**\n- New functions/classes have corresponding tests\n- Documentation updated for API changes\n- Configuration files updated as needed\n- Migration scripts for database changes\n\n**Quality Assurance:**\n- Code follows project standards\n- No obvious bugs or logical errors\n- Performance implications considered\n- Security vulnerabilities addressed\n\n**Requirement Compliance:**\n- Implementation matches original requirements\n- No scope creep or unauthorized changes\n- All acceptance criteria met\n- Edge cases properly handled\n\n**Integration Safety:**\n- Breaking changes properly documented\n- Backward compatibility maintained where required\n- Dependencies correctly updated\n- Environment-specific changes validated\n\n## Best Practices\n\n- **Provide clear context**: Include the original requirements or feature description\n- **Use for significant changes**: Most valuable for features, refactoring, or security updates\n- **Review before final commit**: Catch issues before they enter the main branch\n- **Include visual context**: Screenshots of requirements or expected behavior\n- **Focus validation scope**: Use `focus_on` parameter for specific concerns\n- **Multi-stage validation**: Use continuation for iterative improvement\n\n## Output Format\n\nValidation results include:\n- **Change Summary**: Overview of what was modified across repositories\n- **Requirement Compliance**: How well changes match original intent\n- **Completeness Assessment**: Missing tests, documentation, or related changes\n- **Security Review**: Potential vulnerabilities or exposed secrets\n- **Integration Impact**: Cross-repository and cross-module effects\n- **Recommendations**: Specific actions before committing\n\n## When to Use PreCommit vs Other Tools\n\n- **Use `precommit`** for: Validating changes before git commit, ensuring requirement compliance\n- **Use `codereview`** for: General code quality assessment without git context\n- **Use `debug`** for: Diagnosing specific runtime issues\n- **Use `analyze`** for: Understanding existing code without validation context\n" }, { "path": "docs/tools/refactor.md", "content": "# Refactor Tool - Intelligent Code Refactoring\n\n**Comprehensive refactoring analysis with top-down decomposition strategy through workflow-driven investigation**\n\nThe `refactor` tool provides intelligent code refactoring recommendations with a focus on top-down decomposition and systematic code improvement. This workflow tool enforces systematic investigation of code smells, decomposition opportunities, and modernization possibilities across multiple steps, ensuring thorough analysis before providing expert refactoring recommendations with precise implementation guidance.\n\n## Thinking Mode\n\n**Default is `medium` (8,192 tokens).** Use `high` for complex legacy systems (worth the investment for thorough refactoring plans) or `max` for extremely complex codebases requiring deep analysis.\n\n## How the Workflow Works\n\nThe refactor tool implements a **structured workflow** for systematic refactoring analysis:\n\n**Investigation Phase (Claude-Led):**\n1. **Step 1**: Claude describes the refactoring plan and begins analyzing code structure\n2. **Step 2+**: Claude examines code smells, decomposition opportunities, and modernization possibilities\n3. **Throughout**: Claude tracks findings, relevant files, refactoring opportunities, and confidence levels\n4. **Completion**: Once investigation is thorough, Claude signals completion\n\n**Expert Analysis Phase:**\nAfter Claude completes the investigation (unless confidence is **complete**):\n- Complete refactoring opportunity summary\n- Prioritized recommendations by impact\n- Precise implementation guidance with line numbers\n- Final expert assessment for refactoring strategy\n\nThis workflow ensures methodical investigation before expert recommendations, resulting in more targeted and valuable refactoring plans.\n\n## Model Recommendation\n\nThe refactor tool excels with models that have large context windows like Gemini Pro (1M tokens), which can analyze entire files and complex codebases simultaneously. This comprehensive view enables detection of cross-file dependencies, architectural patterns, and refactoring opportunities that might be missed when reviewing code in smaller chunks due to context constraints.\n\n## Example Prompts\n\n```\n\"Use gemini pro to decompose my_crazy_big_class.m into smaller extensions\"\n\"Using pal's refactor decompose the all_in_one_sync_code.swift into maintainable extensions\"\n```\n\nπŸ’‘**Example of a powerful prompt** to get the best out of both Claude + Flash's 1M Context: \n```\n\"First, think about how the authentication module works, find related classes and find\n any code smells, then using pal's refactor ask flash to confirm your findings but ask \n it to find additional code smells and any other quick-wins and then fix these issues\"\n```\n\nThis results in Claude first performing its own expert analysis, encouraging it to think critically and identify links within the project code. It then prompts `flash` to review the same code with a hintβ€”preventing it from duplicating Claude's findings and encouraging it to explore other areas that Claude did *not* discover.\n\n## Key Features\n\n- **Intelligent prioritization** - Will refuse to work on low priority issues if code is unwieldy large and requires decomposition first, helps identify poorly managed classes and files that need structural improvements before detail work\n- **Top-down decomposition strategy** - Analyzes file β†’ class β†’ function levels systematically\n- **Four refactor types**: `codesmells` (detect anti-patterns), `decompose` (break down large components), `modernize` (update language features), `organization` (improve structure)\n- **Precise line-number references** - Provides exact line numbers for Claude to implement changes\n- **Language-specific guidance** - Tailored suggestions for Python, JavaScript, Java, C#, Swift, and more\n- **Style guide integration** - Uses existing project files as pattern references\n- **Conservative approach** - Careful dependency analysis to prevent breaking changes\n- **Multi-file analysis** - Understands cross-file relationships and dependencies\n- **Priority sequencing** - Recommends implementation order for refactoring changes\n- **Image support**: Analyze code architecture diagrams, legacy system charts: `\"Refactor this legacy module using gemini pro with the current architecture diagram\"`\n\n## Refactor Types (Progressive Priority System)\n\n**1. `decompose` (CRITICAL PRIORITY)** - Context-aware decomposition with adaptive thresholds:\n\n**AUTOMATIC decomposition** (CRITICAL severity - blocks all other refactoring):\n- Files >15,000 LOC, Classes >3,000 LOC, Functions >500 LOC\n\n**EVALUATE decomposition** (contextual severity - intelligent assessment):\n- Files >5,000 LOC, Classes >1,000 LOC, Functions >150 LOC\n- Only recommends if genuinely improves maintainability\n- Respects legacy stability, domain complexity, performance constraints\n- Considers legitimate cases where size is justified (algorithms, state machines, generated code)\n\n**2. `codesmells`** - Applied only after decomposition is complete:\n- Detect long methods, complex conditionals, duplicate code, magic numbers, poor naming\n\n**3. `modernize`** - Applied only after decomposition is complete:\n- Update to modern language features (f-strings, async/await, etc.)\n\n**4. `organization`** - Applied only after decomposition is complete:\n- Improve logical grouping, separation of concerns, module structure\n\n**Progressive Analysis:** The tool performs a top-down check (worse β†’ bad β†’ better) and refuses to work on lower-priority issues if critical decomposition is needed first. It understands that massive files and classes create cognitive overload that must be addressed before detail work can be effective. Legacy code that cannot be safely decomposed is handled with higher tolerance thresholds and context-sensitive exemptions.\n\n## Tool Parameters\n\n**Workflow Investigation Parameters (used during step-by-step process):**\n- `step`: Current investigation step description (required for each step)\n- `step_number`: Current step number in refactoring sequence (required)\n- `total_steps`: Estimated total investigation steps (adjustable)\n- `next_step_required`: Whether another investigation step is needed\n- `findings`: Discoveries and refactoring opportunities in this step (required)\n- `files_checked`: All files examined during investigation\n- `relevant_files`: Files directly needing refactoring (required in step 1)\n- `relevant_context`: Methods/functions/classes requiring refactoring\n- `issues_found`: Refactoring opportunities with severity and type\n- `confidence`: Confidence level in analysis completeness (exploring/incomplete/partial/complete)\n- `hypothesis`: Current assessment of refactoring priorities\n\n**Initial Configuration (used in step 1):**\n- `prompt`: Description of refactoring goals, context, and specific areas of focus (required)\n- `refactor_type`: codesmells|decompose|modernize|organization (default: codesmells)\n- `model`: auto|pro|flash|flash-2.0|flashlite|o3|o3-mini|o4-mini|gpt4.1|gpt5.2|gpt5.1-codex|gpt5.1-codex-mini|gpt5|gpt5-mini|gpt5-nano (default: server default)\n- `focus_areas`: Specific areas to focus on (e.g., 'performance', 'readability', 'maintainability', 'security')\n- `style_guide_examples`: Optional existing code files to use as style/pattern reference (absolute paths)\n- `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)\n- `use_assistant_model`: Whether to use expert analysis phase (default: true, set to false to use Claude only)\n- `continuation_id`: Thread continuation ID for multi-turn conversations\n\n## Usage Examples\n\n**Decomposition Analysis:**\n```\n\"Analyze UserController.java for decomposition opportunities - it's becoming unwieldy\"\n```\n\n**Code Smell Detection:**\n```\n\"Use gemini to identify code smells in the authentication module with high thinking mode\"\n```\n\n**Modernization:**\n```\n\"Modernize legacy_parser.py to use modern Python features following examples/modern_patterns.py\"\n```\n\n**Organization Improvement:**\n```\n\"Refactor src/utils/ for better organization, focus on maintainability and readability\"\n```\n\n**Legacy System Refactoring:**\n```\n\"Use pro with max thinking to analyze this 10,000-line legacy file for decomposition strategy\"\n```\n\n## Refactoring Strategy\n\n**Top-Down Analysis:**\n1. **File Level**: Identify oversized files that need splitting\n2. **Class Level**: Find classes with too many responsibilities \n3. **Function Level**: Locate functions that are too complex or long\n4. **Code Quality**: Address smells, modernization, and organization\n\n**Context-Aware Decisions:**\n- **Domain Complexity**: Some domains legitimately require larger classes\n- **Performance Constraints**: Critical path code may resist decomposition\n- **Legacy Stability**: Old, working code may need gentler refactoring\n- **Test Coverage**: Refactoring recommendations consider testability\n\n**Breaking Change Prevention:**\n- Analyzes dependencies before suggesting splits\n- Recommends gradual migration strategies\n- Identifies public API impact\n- Suggests backward compatibility approaches\n\n## Best Practices\n\n- **Start with decomposition**: Address structural issues before cosmetic improvements\n- **Provide clear context**: Explain the codebase purpose and constraints\n- **Use appropriate refactor types**: Match the type to your primary concern\n- **Include style examples**: Reference existing well-structured code in your project\n- **Focus on high-impact areas**: Target the most problematic or frequently modified code\n- **Plan implementation order**: Follow the tool's sequencing recommendations\n- **Consider test coverage**: Ensure adequate tests before major structural changes\n\n## Output Format\n\nRefactoring analysis includes:\n- **Priority Assessment**: What needs attention first and why\n- **Decomposition Strategy**: Specific file/class/function splitting recommendations\n- **Implementation Plan**: Step-by-step refactoring sequence\n- **Line-Number References**: Exact locations for changes\n- **Dependency Analysis**: Impact assessment and migration strategies\n- **Risk Assessment**: Potential breaking changes and mitigation strategies\n\n## Advanced Features\n\n**Adaptive Thresholds:**\nThe tool adjusts size thresholds based on context:\n- **Generated Code**: Higher tolerance for large files\n- **Algorithm Implementation**: Recognizes when size is justified\n- **Legacy Systems**: More conservative recommendations\n- **Test Files**: Different standards for test vs production code\n\n**Cross-File Refactoring:**\nAnalyzes multiple files together to understand:\n- Shared responsibilities that could be extracted\n- Dependencies that complicate refactoring\n- Opportunities for new abstractions\n- Impact of changes across the codebase\n\n## When to Use Refactor vs Other Tools\n\n- **Use `refactor`** for: Structural improvements, decomposition, modernization, code organization\n- **Use `codereview`** for: Finding bugs and security issues with immediate fixes\n- **Use `analyze`** for: Understanding code without making change recommendations \n- **Use `debug`** for: Solving specific runtime issues rather than structural problems\n" }, { "path": "docs/tools/secaudit.md", "content": "# Secaudit Tool - Comprehensive Security Audit\n\n**Systematic OWASP-based security assessment with compliance evaluation through workflow-driven investigation**\n\nThe `secaudit` tool provides comprehensive security auditing capabilities with systematic OWASP Top 10 assessment, compliance framework evaluation, \nand threat modeling. This workflow tool guides Claude through methodical security investigation steps with forced pauses between each step to ensure \nthorough vulnerability assessment, security pattern analysis, and compliance verification before providing expert analysis.\n\n**Important**: AI models may not identify all security vulnerabilities. Always perform additional manual security reviews, \npenetration testing, and verification.\n\n## How the Workflow Works\n\nThe secaudit tool implements a **structured 6-step security workflow** that ensures comprehensive security assessment:\n\n**Investigation Phase (Claude-Led):**\n1. **Step 1**: Security Scope Analysis - Claude identifies application type, tech stack, attack surface, and compliance requirements\n2. **Step 2**: Authentication & Authorization Assessment - Analyzes auth mechanisms, session management, and access controls\n3. **Step 3**: Input Validation & Data Security - Reviews input handling, data protection, and injection vulnerabilities\n4. **Step 4**: OWASP Top 10 (2021) Review - Systematic assessment of all OWASP categories with specific findings\n5. **Step 5**: Dependencies & Infrastructure - Security analysis of third-party components and deployment configurations\n6. **Step 6**: Compliance & Risk Assessment - Evaluation against specified compliance frameworks and risk prioritization\n\n**Expert Analysis Phase:**\nAfter Claude completes the investigation (unless confidence is **certain**):\n- Complete security assessment summary with all vulnerabilities and evidence\n- OWASP Top 10 systematic findings with severity classifications\n- Compliance framework gap analysis and remediation recommendations\n- Risk-prioritized remediation roadmap based on threat level and business impact\n\n**Special Note**: If you want Claude to perform the entire security audit without calling another model, you can include \"don't use any other model\" in your prompt, and Claude will complete the full workflow independently.\n\n## Model Recommendation\n\nThis tool particularly benefits from Gemini Pro or O3 models due to their advanced reasoning capabilities and large context windows, which allow comprehensive security analysis across complex codebases. Security audits require understanding subtle attack vectors and cross-component interactions that benefit from deeper analytical capabilities.\n\n## Example Prompts\n\n```\nPerform a secaudit with o3 on this e-commerce web application focusing on payment processing security and PCI DSS compliance\n```\n\n```\nUse secaudit to conduct a comprehensive security audit of the authentication system, threat level high, focus on enterprise \nsecurity patterns and HIPAA compliance\n```\n\n## Pro Tip: Multi-Scope Security Assessment\n\n**You can run parallel security audits for different application components:**\n\n```\nStart separate sub-tasks, in one start a secaudit for critical payment processing components focusing on PCI DSS with gemini pro, \nand in the other for user management focusing on OWASP authentication vulnerabilities with o4-mini, then combine into a unified \nsecurity remediation plan using planner \n```\n\n## Key Features\n\n- **OWASP Top 10 (2021) systematic assessment** with specific vulnerability identification\n- **Multi-compliance framework support**: SOC2, PCI DSS, HIPAA, GDPR, FedRAMP\n- **Threat-level aware analysis**: Critical, high, medium, low threat classifications\n- **Technology-specific security patterns**: Web apps, APIs, mobile, cloud, enterprise systems\n- **Risk-based prioritization**: Business impact and exploitability assessment\n- **Audit focus customization**: Comprehensive, authentication, data protection, infrastructure\n- **Image support**: Security analysis from architecture diagrams, network topology, or security findings\n- **Multi-file security analysis**: Cross-component vulnerability identification\n- **Compliance gap analysis**: Specific framework requirements with remediation guidance\n- **Attack surface mapping**: Entry points, data flows, and privilege boundaries\n- **Security control effectiveness**: Evaluation of existing security measures\n\n## Tool Parameters\n\n**Workflow Investigation Parameters (used during step-by-step process):**\n- `step`: Current security investigation step description (required for each step)\n- `step_number`: Current step number in audit sequence (required)\n- `total_steps`: Estimated total investigation steps (typically 4-6, adjustable)\n- `next_step_required`: Whether another investigation step is needed\n- `findings`: Security discoveries and evidence collected in this step (required)\n- `files_checked`: All files examined during security investigation\n- `relevant_files`: Files directly relevant to security assessment (required in step 1)\n- `relevant_context`: Methods/functions/classes central to security findings\n- `issues_found`: Security issues identified with severity levels\n- `confidence`: Confidence level in security assessment completeness (exploring/low/medium/high/certain)\n- `images`: Architecture diagrams, security documentation, or visual references\n\n**Initial Security Configuration (used in step 1):**\n- `model`: auto|pro|flash|flash-2.0|flashlite|o3|o3-mini|o4-mini|gpt4.1|gpt5.2|gpt5.1-codex|gpt5.1-codex-mini|gpt5|gpt5-mini|gpt5-nano (default: server default)\n- `security_scope`: Application context, technology stack, and security boundary definition (required)\n- `threat_level`: low|medium|high|critical (default: medium) - determines assessment depth and urgency\n- `compliance_requirements`: List of compliance frameworks to assess against (e.g., [\"PCI DSS\", \"SOC2\"])\n- `audit_focus`: comprehensive|authentication|data_protection|infrastructure|api_security (default: comprehensive)\n- `severity_filter`: critical|high|medium|low|all (default: all)\n- `temperature`: Temperature for analytical consistency (0-1, default 0.2)\n- `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)\n- `use_assistant_model`: Whether to use expert security analysis phase (default: true)\n- `continuation_id`: Continue previous security audit discussions\n\n## Audit Focus Areas\n\n**Comprehensive (default):**\n- Full OWASP Top 10 assessment with all security domains\n- Authentication, authorization, data protection, infrastructure\n- Best for complete security posture evaluation\n\n**Authentication:**\n- Focused on identity, access management, and session security\n- Multi-factor authentication, password policies, privilege escalation\n- Best for user management and access control systems\n\n**Data Protection:**\n- Encryption, data handling, privacy controls, and compliance\n- Input validation, output encoding, data classification\n- Best for applications handling sensitive or regulated data\n\n**Infrastructure:**\n- Deployment security, configuration management, dependency security\n- Network security, container security, cloud security posture\n- Best for DevOps and infrastructure security assessment\n\n**API Security:**\n- REST/GraphQL security, rate limiting, API authentication\n- Input validation, authorization patterns, API gateway security\n- Best for API-first applications and microservices\n\n## Threat Levels\n\nSecurity assessment depth and urgency:\n\n- **πŸ”΄ CRITICAL**: Mission-critical systems, high-value targets, regulatory requirements\n- **🟠 HIGH**: Business-critical applications, customer data handling, financial systems\n- **🟑 MEDIUM**: Standard business applications, internal tools, moderate risk exposure\n- **🟒 LOW**: Development environments, non-sensitive applications, proof-of-concepts\n\n## Compliance Frameworks\n\nSupported compliance assessments:\n\n- **SOC2**: Security, availability, processing integrity, confidentiality, privacy\n- **PCI DSS**: Payment card industry data security standards\n- **HIPAA**: Healthcare information privacy and security\n- **GDPR**: General data protection regulation compliance\n- **FedRAMP**: Federal risk and authorization management program\n- **ISO27001**: Information security management systems\n- **NIST**: Cybersecurity framework controls\n\n## OWASP Top 10 (2021) Coverage\n\nSystematic assessment includes:\n\n1. **A01 Broken Access Control**: Authorization flaws and privilege escalation\n2. **A02 Cryptographic Failures**: Encryption and data protection issues\n3. **A03 Injection**: SQL, NoSQL, OS, and LDAP injection vulnerabilities\n4. **A04 Insecure Design**: Security design flaws and threat modeling gaps\n5. **A05 Security Misconfiguration**: Configuration and hardening issues\n6. **A06 Vulnerable Components**: Third-party and dependency vulnerabilities\n7. **A07 Identification & Authentication Failures**: Authentication bypass and session management\n8. **A08 Software & Data Integrity Failures**: Supply chain and integrity violations\n9. **A09 Security Logging & Monitoring Failures**: Detection and response capabilities\n10. **A10 Server-Side Request Forgery**: SSRF and related vulnerabilities\n\n## Usage Examples\n\n**Comprehensive E-commerce Security Audit:**\n```\n\"Conduct a comprehensive secaudit with gemini pro for our Node.js e-commerce platform, threat level high, \ncompliance requirements PCI DSS and SOC2, focus on payment processing security\"\n```\n\n**Authentication System Security Review:**\n```\n\"Use o3 to perform secaudit on authentication microservice, focus on authentication, \nthreat level critical, check for OWASP A07 and multi-factor authentication implementation\"\n```\n\n**API Security Assessment:**\n```\n\"Secaudit our REST API gateway with gemini pro, audit focus api_security, \ncompliance requirements GDPR, threat level medium\"\n```\n\n**Infrastructure Security Review:**\n```\n\"Perform secaudit on Kubernetes deployment manifests with o3, focus infrastructure, \nthreat level high, include container security and network policies\"\n```\n\n**Quick Security Scan:**\n```\n\"Fast secaudit of user registration flow with flash, focus authentication, \nseverity filter critical and high only\"\n```\n\n## Best Practices\n\n- **Define clear security scope**: Specify application type, tech stack, and security boundaries\n- **Set appropriate threat levels**: Match assessment depth to risk exposure and criticality\n- **Include compliance requirements**: Specify relevant frameworks for regulatory alignment\n- **Use parallel audits**: Run separate assessments for different components or compliance frameworks\n- **Provide architectural context**: Include system diagrams, data flow documentation, or deployment topology\n- **Focus audit scope**: Use audit_focus for targeted assessments of specific security domains\n- **Follow up on findings**: Use continuation feature to dive deeper into specific vulnerabilities\n\n## Output Format\n\nSecurity audits include:\n- **Executive Security Summary**: Overall security posture and critical findings\n- **OWASP Top 10 Assessment**: Systematic review of each category with specific findings\n- **Compliance Gap Analysis**: Framework-specific requirements and current compliance status\n- **Risk-Prioritized Findings**: Vulnerabilities ordered by exploitability and business impact\n- **Remediation Roadmap**: Phased approach to security improvements with quick wins\n- **Security Architecture Recommendations**: Structural improvements for long-term security posture\n\n## When to Use Secaudit vs Other Tools\n\n- **Use `secaudit`** for: Comprehensive security assessment, compliance evaluation, OWASP-based vulnerability analysis\n- **Use `codereview`** for: General code quality with some security considerations\n- **Use `analyze`** for: Understanding security architecture without vulnerability assessment\n- **Use `debug`** for: Investigating specific security incidents or exploit attempts\n- **Use `precommit`** for: Pre-deployment security validation and change impact assessment\n" }, { "path": "docs/tools/testgen.md", "content": "# TestGen Tool - Comprehensive Test Generation\n\n**Generates thorough test suites with edge case coverage through workflow-driven investigation**\n\nThe `testgen` tool creates comprehensive test suites by analyzing your code paths, understanding intricate dependencies, and identifying realistic edge cases and failure scenarios that need test coverage. This workflow tool guides Claude through systematic investigation of code functionality, critical paths, edge cases, and integration points across multiple steps before generating comprehensive tests with realistic failure mode analysis.\n\n## Thinking Mode\n\n**Default is `medium` (8,192 tokens) for extended thinking models.** Use `high` for complex systems with many interactions or `max` for critical systems requiring exhaustive test coverage.\n\n## How the Workflow Works\n\nThe testgen tool implements a **structured workflow** for comprehensive test generation:\n\n**Investigation Phase (Claude-Led):**\n1. **Step 1**: Claude describes the test generation plan and begins analyzing code functionality\n2. **Step 2+**: Claude examines critical paths, edge cases, error handling, and integration points\n3. **Throughout**: Claude tracks findings, test scenarios, and coverage gaps\n4. **Completion**: Once investigation is thorough, Claude signals completion\n\n**Test Generation Phase:**\nAfter Claude completes the investigation:\n- Complete test scenario catalog with all edge cases\n- Framework-specific test generation\n- Realistic failure mode coverage\n- Final test suite with comprehensive coverage\n\nThis workflow ensures methodical analysis before test generation, resulting in more thorough and valuable test suites.\n\n## Model Recommendation\n\nTest generation excels with extended reasoning models like Gemini Pro or O3, which can analyze complex code paths, understand intricate dependencies, and identify comprehensive edge cases. The combination of large context windows and advanced reasoning enables generation of thorough test suites that cover realistic failure scenarios and integration points that shorter-context models might overlook.\n\n## Example Prompts\n\n**Basic Usage:**\n```\n\"Use pal to generate tests for User.login() method\"\n\"Generate comprehensive tests for the sorting method in src/new_sort.py using o3\"\n\"Create tests for edge cases not already covered in our tests using gemini pro\"\n```\n\n## Key Features\n\n- **Multi-agent workflow** analyzing code paths and identifying realistic failure modes\n- **Generates framework-specific tests** following project conventions\n- **Supports test pattern following** when examples are provided\n- **Dynamic token allocation** (25% for test examples, 75% for main code)\n- **Prioritizes smallest test files** for pattern detection\n- **Can reference existing test files**: `\"Generate tests following patterns from tests/unit/\"`\n- **Specific code coverage** - target specific functions/classes rather than testing everything\n- **Image support**: Test UI components, analyze visual requirements: `\"Generate tests for this login form using the UI mockup screenshot\"`\n- **Edge case identification**: Systematic discovery of boundary conditions and error states\n- **Realistic failure mode analysis**: Understanding what can actually go wrong in production\n- **Integration test support**: Tests that cover component interactions and system boundaries\n\n## Tool Parameters\n\n**Workflow Investigation Parameters (used during step-by-step process):**\n- `step`: Current investigation step description (required for each step)\n- `step_number`: Current step number in test generation sequence (required)\n- `total_steps`: Estimated total investigation steps (adjustable)\n- `next_step_required`: Whether another investigation step is needed\n- `findings`: Discoveries about functionality and test scenarios (required)\n- `files_checked`: All files examined during investigation\n- `relevant_files`: Files directly needing tests (required in step 1)\n- `relevant_context`: Methods/functions/classes requiring test coverage\n- `confidence`: Confidence level in test plan completeness (exploring/low/medium/high/certain)\n\n**Initial Configuration (used in step 1):**\n- `prompt`: Description of what to test, testing objectives, and specific scope/focus areas (required)\n- `model`: auto|pro|flash|flash-2.0|flashlite|o3|o3-mini|o4-mini|gpt4.1|gpt5.2|gpt5.1-codex|gpt5.1-codex-mini|gpt5|gpt5-mini|gpt5-nano (default: server default)\n- `test_examples`: Optional existing test files or directories to use as style/pattern reference (absolute paths)\n- `thinking_mode`: minimal|low|medium|high|max (default: medium, Gemini only)\n- `use_assistant_model`: Whether to use expert test generation phase (default: true, set to false to use Claude only)\n\n## Usage Examples\n\n**Method-Specific Tests:**\n```\n\"Generate tests for User.login() method covering authentication success, failure, and edge cases\"\n```\n\n**Class Testing:**\n```\n\"Use pro to generate comprehensive tests for PaymentProcessor class with max thinking mode\"\n```\n\n**Following Existing Patterns:**\n```\n\"Generate tests for new authentication module following patterns from tests/unit/auth/\"\n```\n\n**UI Component Testing:**\n```\n\"Generate tests for this login form component using the UI mockup screenshot\"\n```\n\n**Algorithm Testing:**\n```\n\"Create thorough tests for the sorting algorithm in utils/sort.py, focus on edge cases and performance\"\n```\n\n**Integration Testing:**\n```\n\"Generate integration tests for the payment processing pipeline from order creation to completion\"\n```\n\n## Test Generation Strategy\n\n**Code Path Analysis:**\n- Identifies all execution paths through the code\n- Maps conditional branches and loops\n- Discovers error handling paths\n- Analyzes state transitions\n\n**Edge Case Discovery:**\n- Boundary value analysis (empty, null, max values)\n- Invalid input scenarios\n- Race conditions and timing issues\n- Resource exhaustion cases\n\n**Failure Mode Analysis:**\n- External dependency failures\n- Network and I/O errors\n- Authentication and authorization failures\n- Data corruption scenarios\n\n**Framework Detection:**\nThe tool automatically detects and generates tests for:\n- **Python**: pytest, unittest, nose2\n- **JavaScript**: Jest, Mocha, Jasmine, Vitest\n- **Java**: JUnit 4/5, TestNG, Mockito\n- **C#**: NUnit, MSTest, xUnit\n- **Swift**: XCTest\n- **Go**: testing package\n- **And more**: Adapts to project conventions\n\n## Test Categories Generated\n\n**Unit Tests:**\n- Function/method behavior validation\n- Input/output verification\n- Error condition handling\n- State change verification\n\n**Integration Tests:**\n- Component interaction testing\n- API endpoint validation\n- Database integration\n- External service mocking\n\n**Edge Case Tests:**\n- Boundary conditions\n- Invalid inputs\n- Resource limits\n- Concurrent access\n\n**Performance Tests:**\n- Response time validation\n- Memory usage checks\n- Load handling\n- Scalability verification\n\n## Best Practices\n\n- **Be specific about scope**: Target specific functions/classes rather than requesting tests for everything\n- **Provide test examples**: Include existing test files for pattern consistency\n- **Focus on critical paths**: Prioritize testing of business-critical functionality\n- **Include visual context**: Screenshots or mockups for UI component testing\n- **Describe testing objectives**: Explain what aspects are most important to test\n- **Consider test maintenance**: Request readable, maintainable test code\n\n## Test Quality Features\n\n**Realistic Test Data:**\n- Generates meaningful test data that represents real-world scenarios\n- Avoids trivial test cases that don't add value\n- Creates data that exercises actual business logic\n\n**Comprehensive Coverage:**\n- Happy path scenarios\n- Error conditions and exceptions\n- Edge cases and boundary conditions\n- Integration points and dependencies\n\n**Maintainable Code:**\n- Clear test names that describe what's being tested\n- Well-organized test structure\n- Appropriate use of setup/teardown\n- Minimal test data and mocking\n\n## Advanced Features\n\n**Pattern Following:**\nWhen test examples are provided, the tool analyzes:\n- Naming conventions and structure\n- Assertion patterns and style\n- Mocking and setup approaches\n- Test data organization\n\n**Large Context Analysis:**\nWith models like Gemini Pro, the tool can:\n- Analyze extensive codebases for comprehensive test coverage\n- Understand complex interactions across multiple modules\n- Generate integration tests that span multiple components\n\n**Visual Testing:**\nFor UI components and visual elements:\n- Generate tests based on visual requirements\n- Create accessibility testing scenarios\n- Test responsive design behaviors\n\n## When to Use TestGen vs Other Tools\n\n- **Use `testgen`** for: Creating comprehensive test suites, filling test coverage gaps, testing new features\n- **Use `debug`** for: Diagnosing specific test failures or runtime issues\n- **Use `codereview`** for: Reviewing existing test quality and coverage\n- **Use `analyze`** for: Understanding existing test structure without generating new tests\n" }, { "path": "docs/tools/thinkdeep.md", "content": "# ThinkDeep Tool - Extended Reasoning Partner\n\n**Get a second opinion to augment Claude's own extended thinking**\n\nThe `thinkdeep` tool provides extended reasoning capabilities, offering a second perspective to augment Claude's analysis. It's designed to challenge assumptions, find edge cases, and provide alternative approaches to complex problems.\n\n## Thinking Mode\n\n**Default is `high` (16,384 tokens) for deep analysis.** Claude will automatically choose the best mode based on complexity - use `low` for quick validations, `medium` for standard problems, `high` for complex issues (default), or `max` for extremely complex challenges requiring deepest analysis.\n\n## Example Prompt\n\n```\nThink deeper about my authentication design with pro using max thinking mode and brainstorm to come up \nwith the best architecture for my project\n```\n\n## Key Features\n\n- **Uses Gemini's specialized thinking models** for enhanced reasoning capabilities\n- **Provides a second opinion** on Claude's analysis\n- **Challenges assumptions** and identifies edge cases Claude might miss\n- **Offers alternative perspectives** and approaches\n- **Validates architectural decisions** and design patterns\n- **File reference support**: `\"Use gemini to think deeper about my API design with reference to api/routes.py\"`\n- **Image support**: Analyze architectural diagrams, flowcharts, design mockups: `\"Think deeper about this system architecture diagram with gemini pro using max thinking mode\"`\n- **Enhanced Critical Evaluation (v2.10.0)**: After Gemini's analysis, Claude is prompted to critically evaluate the suggestions, consider context and constraints, identify risks, and synthesize a final recommendation - ensuring a balanced, well-considered solution\n- **Web search capability**: Automatically identifies areas where current documentation or community solutions would strengthen the analysis and instructs Claude to perform targeted searches\n\n## Tool Parameters\n\n- `prompt`: Your current thinking/analysis to extend and validate (required)\n- `model`: auto|pro|flash|flash-2.0|flashlite|o3|o3-mini|o4-mini|gpt4.1|gpt5.2|gpt5.1-codex|gpt5.1-codex-mini|gpt5|gpt5-mini|gpt5-nano (default: server default)\n- `problem_context`: Additional context about the problem or goal\n- `focus_areas`: Specific aspects to focus on (architecture, performance, security, etc.)\n- `files`: Optional file paths or directories for additional context (absolute paths)\n- `images`: Optional images for visual analysis (absolute paths)\n- `temperature`: Temperature for creative thinking (0-1, default 0.7)\n- `thinking_mode`: minimal|low|medium|high|max (default: high, Gemini only)\n- `continuation_id`: Continue previous conversations\n\n## Usage Examples\n\n**Architecture Design:**\n```\n\"Think deeper about my microservices authentication strategy with pro using max thinking mode\"\n```\n\n**With File Context:**\n```\n\"Use gemini to think deeper about my API design with reference to api/routes.py and models/user.py\"\n```\n\n**Visual Analysis:**\n```\n\"Think deeper about this system architecture diagram with gemini pro - identify potential bottlenecks\"\n```\n\n**Problem Solving:**\n```\n\"I'm considering using GraphQL vs REST for my API. Think deeper about the trade-offs with o3 using high thinking mode\"\n```\n\n**Code Review Enhancement:**\n```\n\"Think deeper about the security implications of this authentication code with pro\"\n```\n\n## Best Practices\n\n- **Provide detailed context**: Share your current thinking, constraints, and objectives\n- **Be specific about focus areas**: Mention what aspects need deeper analysis\n- **Include relevant files**: Reference code, documentation, or configuration files\n- **Use appropriate thinking modes**: Higher modes for complex problems, lower for quick validations\n- **Leverage visual context**: Include diagrams or mockups for architectural discussions\n- **Build on discussions**: Use continuation to extend previous analyses\n\n## Enhanced Critical Evaluation Process\n\nThe `thinkdeep` tool includes a unique two-stage process:\n\n1. **Gemini's Analysis**: Extended reasoning with specialized thinking capabilities\n2. **Claude's Critical Evaluation**: Claude reviews Gemini's suggestions, considers:\n - Context and constraints of your specific situation\n - Potential risks and implementation challenges\n - Trade-offs and alternatives\n - Final synthesized recommendation\n\nThis ensures you get both deep reasoning and practical, context-aware advice.\n\n## When to Use ThinkDeep vs Other Tools\n\n- **Use `thinkdeep`** for: Extending specific analysis, challenging assumptions, architectural decisions\n- **Use `chat`** for: Open-ended brainstorming and general discussions\n- **Use `analyze`** for: Understanding existing code without extending analysis\n- **Use `codereview`** for: Finding specific bugs and security issues\n" }, { "path": "docs/tools/tracer.md", "content": "# Tracer Tool - Static Code Analysis Prompt Generator\n\n**Creates detailed analysis prompts for call-flow mapping and dependency tracing**\n\nThe `tracer` tool is a specialized prompt-generation tool that creates structured analysis requests for Claude to perform comprehensive static code analysis. Rather than passing entire projects to another model, this tool generates focused prompts that Claude can use to efficiently trace execution flows and map dependencies within the codebase.\n\n## Two Analysis Modes\n\n**`precision` Mode**: For methods/functions\n- Traces execution flow, call chains, and usage patterns\n- Detailed branching analysis and side effects\n- Shows when and how functions are called throughout the system\n\n**`dependencies` Mode**: For classes/modules/protocols \n- Maps bidirectional dependencies and structural relationships\n- Identifies coupling and architectural dependencies\n- Shows how components interact and depend on each other\n\n## Key Features\n\n- **Generates comprehensive analysis prompts** instead of performing analysis directly\n- **Faster and more efficient** than full project analysis by external models\n- **Creates structured instructions** for call-flow graph generation\n- **Provides detailed formatting requirements** for consistent output\n- **Supports any programming language** with automatic convention detection\n- **Output can be used as input** into another tool, such as `chat` along with related code files to perform logical call-flow analysis\n- **Image support**: Analyze visual call flow diagrams, sequence diagrams: `\"Generate tracer analysis for this payment flow using the sequence diagram\"`\n\n## Tool Parameters\n\n- `prompt`: Detailed description of what to trace and WHY you need this analysis (required)\n- `trace_mode`: precision|dependencies (required)\n- `images`: Optional images of system architecture diagrams, flow charts, or visual references (absolute paths)\n\n## Usage Examples\n\n**Method Execution Tracing:**\n```\n\"Use pal tracer to analyze how UserAuthManager.authenticate is used and why\"\n```\nβ†’ Uses `precision` mode to trace the method's execution flow\n\n**Class Dependency Mapping:**\n```\n\"Use pal to generate a dependency trace for the PaymentProcessor class to understand its relationships\"\n```\nβ†’ Uses `dependencies` mode to map structural relationships\n\n**With Visual Context:**\n```\n\"Generate tracer analysis for the authentication flow using this sequence diagram\"\n```\n\n**Complex System Analysis:**\n```\n\"Create a tracer prompt to understand how the OrderProcessor.processPayment method flows through the entire system\"\n```\n\n## Precision Mode Output\n\nWhen using `precision` mode for methods/functions, the tool generates prompts that will help Claude create:\n\n**Call Chain Analysis:**\n- Where the method is defined\n- All locations where it's called\n- Direct and indirect callers\n- Call hierarchy and depth\n\n**Execution Flow Mapping:**\n- Step-by-step execution path\n- Branching conditions and logic\n- Side effects and state changes\n- Return value usage\n\n**Usage Pattern Analysis:**\n- Frequency and context of calls\n- Parameter passing patterns\n- Error handling approaches\n- Performance implications\n\n## Dependencies Mode Output\n\nWhen using `dependencies` mode for classes/modules, the tool generates prompts that will help Claude create:\n\n**Structural Relationships:**\n- Inheritance hierarchies\n- Composition and aggregation\n- Interface implementations\n- Module imports and exports\n\n**Bidirectional Dependencies:**\n- What the component depends on\n- What depends on the component\n- Circular dependencies\n- Coupling strength analysis\n\n**Architectural Impact:**\n- Layer violations\n- Dependency inversion opportunities\n- Refactoring impact assessment\n- Testability implications\n\n## Example Generated Prompts\n\n**For Precision Mode:**\n```\nAnalyze the execution flow and usage of the `authenticate` method in UserAuthManager:\n\n1. **Method Location**: Find where UserAuthManager.authenticate is defined\n2. **Call Sites**: Identify all locations where this method is called\n3. **Execution Flow**: Trace the step-by-step execution path\n4. **Side Effects**: Document state changes and external interactions\n5. **Return Handling**: Show how return values are used by callers\n\nFormat the analysis as:\n- Method signature and location\n- Call hierarchy (direct and indirect callers)\n- Execution flow diagram\n- Side effects and dependencies\n- Usage patterns and frequency\n```\n\n**For Dependencies Mode:**\n```\nMap the structural dependencies for PaymentProcessor class:\n\n1. **Direct Dependencies**: What PaymentProcessor directly imports/uses\n2. **Reverse Dependencies**: What classes/modules depend on PaymentProcessor\n3. **Inheritance Relationships**: Parent classes and implemented interfaces\n4. **Composition**: Objects that PaymentProcessor contains or creates\n\nFormat the analysis as:\n- Dependency graph (incoming and outgoing)\n- Architectural layer analysis\n- Coupling assessment\n- Refactoring impact evaluation\n```\n\n## Best Practices\n\n- **Be specific about goals**: Clearly state what you need to understand and why\n- **Describe context**: Mention if you're debugging, refactoring, or learning the codebase\n- **Choose appropriate mode**: Use `precision` for method flows, `dependencies` for architecture\n- **Include visual context**: Reference diagrams or documentation when available\n- **Follow up with analysis**: Use the generated prompt with `chat` or `analyze` tools\n\n## Integration with Other Tools\n\nThe `tracer` tool works best when combined with other analysis tools:\n\n**Tracer + Chat:**\n```\n1. Generate analysis prompt with tracer\n2. Use the prompt with chat tool and relevant code files\n3. Get detailed call-flow or dependency analysis\n```\n\n**Tracer + Analyze:**\n```\n1. Use tracer to create structured analysis prompt\n2. Apply the prompt using analyze tool for systematic code exploration\n3. Get architectural insights and dependency mapping\n```\n\n## When to Use Tracer vs Other Tools\n\n- **Use `tracer`** for: Creating structured analysis prompts, systematic code exploration planning\n- **Use `analyze`** for: Direct code analysis without prompt generation\n- **Use `debug`** for: Specific runtime error investigation\n- **Use `chat`** for: Open-ended code discussions and exploration" }, { "path": "docs/tools/version.md", "content": "# Version Tool - Server Information\n\n**Get server version, configuration details, and list of available tools**\n\nThe `version` tool provides information about the PAL MCP Server version, configuration details, and system capabilities. This is useful for debugging, understanding server capabilities, and verifying your installation.\n\n## Usage\n\n```\n\"Get pal to show its version\"\n```\n\n## Key Features\n\n- **Server version information**: Current version and build details\n- **Configuration overview**: Active settings and capabilities\n- **Tool inventory**: Complete list of available tools and their status\n- **System health**: Basic server status and connectivity verification\n- **Debug information**: Helpful details for troubleshooting\n\n## Output Information\n\nThe tool provides:\n\n**Version Details:**\n- Server version number\n- Build timestamp and commit information\n- MCP protocol version compatibility\n- Python runtime version\n\n**Configuration Summary:**\n- Active providers and their status\n- Default model configuration\n- Feature flags and settings\n- Environment configuration overview\n\n**Tool Availability:**\n- Complete list of available tools\n- Tool version information\n- Capability status for each tool\n\n**System Information:**\n- Server uptime and status\n- Memory and resource usage (if available)\n- Conversation memory status\n- Server process information\n\n## Example Output\n\n```\nπŸ”§ PAL MCP Server Information\n\nπŸ“‹ Version: 2.15.0\nπŸ—οΈ Build: 2024-01-15T10:30:00Z (commit: abc123f)\nπŸ”Œ MCP Protocol: 1.0.0\n🐍 Python Runtime: 3.11.7\n\nβš™οΈ Configuration:\nβ€’ Default Model: auto\nβ€’ Providers: Google βœ…, OpenAI βœ…, Custom βœ…\nβ€’ Conversation Memory: Active βœ…\nβ€’ Web Search: Enabled\n\nπŸ› οΈ Available Tools (12):\nβ€’ chat - General development chat & collaborative thinking\nβ€’ thinkdeep - Extended reasoning partner \nβ€’ consensus - Multi-model perspective gathering\nβ€’ codereview - Professional code review\nβ€’ precommit - Pre-commit validation\nβ€’ debug - Expert debugging assistant\nβ€’ analyze - Smart file analysis\nβ€’ refactor - Intelligent code refactoring\nβ€’ tracer - Static code analysis prompt generator\nβ€’ testgen - Comprehensive test generation\nβ€’ listmodels - List available models\nβ€’ version - Server information\n\nπŸ” System Status:\nβ€’ Server Uptime: 2h 35m\nβ€’ Memory Storage: Active\nβ€’ Server Process: Running\n```\n\n## When to Use Version Tool\n\n- **Troubleshooting**: When experiencing issues with the server or tools\n- **Configuration verification**: To confirm your setup is correct\n- **Support requests**: To provide system information when asking for help\n- **Update checking**: To verify you're running the latest version\n- **Capability discovery**: To understand what features are available\n\n## Debug Information\n\nThe version tool can help diagnose common issues:\n\n**Connection Problems:**\n- Verify server is running and responsive\n- Check MCP protocol compatibility\n- Confirm tool availability\n\n**Configuration Issues:**\n- Validate provider setup\n- Check API key configuration status\n- Verify feature enablement\n\n**Performance Troubleshooting:**\n- Server uptime and stability\n- Resource usage patterns\n- Memory storage health\n\n## Tool Parameters\n\nThis tool requires no parameters - it provides comprehensive server information automatically.\n\n## Best Practices\n\n- **Include in bug reports**: Always include version output when reporting issues\n- **Check after updates**: Verify version information after server updates\n- **Monitor system health**: Use periodically to check server status\n- **Validate configuration**: Confirm settings match your expectations\n\n## When to Use Version vs Other Tools\n\n- **Use `version`** for: Server diagnostics, configuration verification, troubleshooting\n- **Use `listmodels`** for: Model availability and capability information\n- **Use other tools** for: Actual development and analysis tasks\n- **Use with support**: Essential information for getting help with issues" }, { "path": "docs/troubleshooting.md", "content": "# Troubleshooting Guide\n\n## Quick Debugging Steps\n\nIf you're experiencing issues with the PAL MCP Server, follow these steps:\n\n### 1. Check MCP Connection\n\nOpen Claude Desktop and type `/mcp` to see if pal is connected:\n- βœ… If pal appears in the list, the connection is working\n- ❌ If not listed or shows an error, continue to step 2\n\n### 2. Launch Claude with Debug Mode\n\nClose Claude Desktop and restart with debug logging:\n\n```bash\n# macOS/Linux\nclaude --debug\n\n# Windows (in WSL2)\nclaude.exe --debug\n```\n\nLook for error messages in the console output, especially:\n- API key errors\n- Python/environment issues\n- File permission errors\n\n### 3. Verify API Keys\n\nCheck that your API keys are properly set:\n\n```bash\n# Check your .env file\ncat .env\n\n# Ensure at least one key is set:\n# GEMINI_API_KEY=your-key-here\n# OPENAI_API_KEY=your-key-here\n```\n\nIf you need to update your API keys, edit the `.env` file and then restart Claude for changes to take effect.\n\n### 4. Check Server Logs\n\nView the server logs for detailed error information:\n\n```bash\n# View recent logs\ntail -n 100 logs/mcp_server.log\n\n# Follow logs in real-time\ntail -f logs/mcp_server.log\n\n# Or use the -f flag when starting to automatically follow logs\n./run-server.sh -f\n\n# Search for errors\ngrep \"ERROR\" logs/mcp_server.log\n```\n\nSee [Logging Documentation](logging.md) for more details on accessing logs.\n\n### 5. Common Issues\n\n**\"Connection failed\" in Claude Desktop**\n- Ensure the server path is correct in your Claude config\n- Run `./run-server.sh` to verify setup and see configuration\n- Check that Python is installed: `python3 --version`\n\n**\"API key environment variable is required\"**\n- Add your API key to the `.env` file\n- Restart Claude Desktop after updating `.env`\n\n**File path errors**\n- Always use absolute paths: `/Users/you/project/file.py`\n- Never use relative paths: `./file.py`\n\n**Python module not found**\n- Run `./run-server.sh` to reinstall dependencies\n- Check virtual environment is activated: should see `.pal_venv` in the Python path\n\n### 6. Environment Issues\n\n**Virtual Environment Problems**\n```bash\n# Reset environment completely\nrm -rf .pal_venv\n./run-server.sh\n```\n\n**Permission Issues**\n```bash\n# Ensure script is executable\nchmod +x run-server.sh\n```\n\n### 7. Still Having Issues?\n\nIf the problem persists after trying these steps:\n\n1. **Reproduce the issue** - Note the exact steps that cause the problem\n2. **Collect logs** - Save relevant error messages from Claude debug mode and server logs\n3. **Open a GitHub issue** with:\n - Your operating system\n - Python version: `python3 --version`\n - Error messages from logs\n - Steps to reproduce\n - What you've already tried\n\n## Windows Users\n\n**Important**: Windows users must use WSL2. Install it with:\n\n```powershell\nwsl --install -d Ubuntu\n```\n\nThen follow the standard setup inside WSL2." }, { "path": "docs/vcr-testing.md", "content": "# HTTP Transport Recorder for Testing\n\nA custom HTTP recorder for testing expensive API calls (like o3-pro) with real responses.\n\n## Overview\n\nThe HTTP Transport Recorder captures and replays HTTP interactions at the transport layer, enabling:\n- Cost-efficient testing of expensive APIs (record once, replay forever)\n- Deterministic tests with real API responses\n- Seamless integration with httpx and OpenAI SDK\n- Automatic PII sanitization for secure recordings\n\n## Quick Start\n\n```python\nfrom tests.transport_helpers import inject_transport\n\n# Simple one-line setup with automatic transport injection\ndef test_expensive_api_call(monkeypatch):\n inject_transport(monkeypatch, \"tests/openai_cassettes/my_test.json\")\n \n # Make API calls - automatically recorded/replayed with PII sanitization\n result = await chat_tool.execute({\"prompt\": \"2+2?\", \"model\": \"o3-pro\"})\n```\n\n## How It Works\n\n1. **First run** (cassette doesn't exist): Records real API calls\n2. **Subsequent runs** (cassette exists): Replays saved responses\n3. **Re-record**: Delete cassette file and run again\n\n## Usage in Tests\n\nThe `transport_helpers.inject_transport()` function simplifies test setup:\n\n```python\nfrom tests.transport_helpers import inject_transport\n\nasync def test_with_recording(monkeypatch):\n # One-line setup - handles all transport injection complexity\n inject_transport(monkeypatch, \"tests/openai_cassettes/my_test.json\")\n \n # Use API normally - recording/replay happens transparently\n result = await chat_tool.execute({\"prompt\": \"2+2?\", \"model\": \"o3-pro\"})\n```\n\nFor manual setup, see `test_o3_pro_output_text_fix.py`.\n\n## Automatic PII Sanitization\n\nAll recordings are automatically sanitized to remove sensitive data:\n\n- **API Keys & Tokens**: Bearer tokens, API keys, and auth headers\n- **Personal Data**: Email addresses, IP addresses, phone numbers\n- **URLs**: Sensitive query parameters and paths\n- **Custom Patterns**: Add your own sanitization rules\n\nSanitization is enabled by default in `RecordingTransport`. To disable:\n\n```python\ntransport = TransportFactory.create_transport(cassette_path, sanitize=False)\n```\n\n## File Structure\n\n```\ntests/\nβ”œβ”€β”€ openai_cassettes/ # Recorded API interactions\nβ”‚ └── *.json # Cassette files\nβ”œβ”€β”€ http_transport_recorder.py # Transport implementation\nβ”œβ”€β”€ pii_sanitizer.py # Automatic PII sanitization\nβ”œβ”€β”€ transport_helpers.py # Simplified transport injection\nβ”œβ”€β”€ sanitize_cassettes.py # Batch sanitization script\n└── test_o3_pro_output_text_fix.py # Example usage\n```\n\n## Sanitizing Existing Cassettes\n\nUse the `sanitize_cassettes.py` script to clean existing recordings:\n\n```bash\n# Sanitize all cassettes (creates backups)\npython tests/sanitize_cassettes.py\n\n# Sanitize specific cassette\npython tests/sanitize_cassettes.py tests/openai_cassettes/my_test.json\n\n# Skip backup creation\npython tests/sanitize_cassettes.py --no-backup\n```\n\nThe script will:\n- Create timestamped backups of original files\n- Apply comprehensive PII sanitization\n- Preserve JSON structure and functionality\n\n## Cost Management\n\n- **One-time cost**: Initial recording only\n- **Zero ongoing cost**: Replays are free\n- **CI-friendly**: No API keys needed for replay\n\n## Re-recording\n\nWhen API changes require new recordings:\n\n```bash\n# Delete specific cassette\nrm tests/openai_cassettes/my_test.json\n\n# Run test with real API key\npython -m pytest tests/test_o3_pro_output_text_fix.py\n```\n\n## Implementation Details\n\n- **RecordingTransport**: Captures real HTTP calls with automatic PII sanitization\n- **ReplayTransport**: Serves saved responses from cassettes\n- **TransportFactory**: Auto-selects mode based on cassette existence\n- **PIISanitizer**: Comprehensive sanitization of sensitive data (integrated by default)\n\n**Security Note**: While recordings are automatically sanitized, always review new cassette files before committing. The sanitizer removes known patterns of sensitive data, but domain-specific secrets may need custom rules.\n\nFor implementation details, see:\n- `tests/http_transport_recorder.py` - Core transport implementation\n- `tests/pii_sanitizer.py` - Sanitization patterns and logic\n- `tests/transport_helpers.py` - Simplified test integration\n\n" }, { "path": "docs/wsl-setup.md", "content": "# WSL (Windows Subsystem for Linux) Setup Guide\n\nThis guide provides detailed instructions for setting up PAL MCP Server on Windows using WSL.\n\n## Prerequisites for WSL\n\n```bash\n# Update WSL and ensure you have a recent Ubuntu distribution\nsudo apt update && sudo apt upgrade -y\n\n# Install required system dependencies\nsudo apt install -y python3-venv python3-pip curl git\n\n# Install Node.js and npm (required for Claude Code CLI)\ncurl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -\nsudo apt install -y nodejs\n\n# Install Claude Code CLI globally\nnpm install -g @anthropic-ai/claude-code\n```\n\n## WSL-Specific Installation Steps\n\n1. **Clone the repository in your WSL environment** (not in Windows filesystem):\n ```bash\n # Navigate to your home directory or preferred location in WSL\n cd ~\n \n # Clone the repository\n git clone https://github.com/BeehiveInnovations/pal-mcp-server.git\n cd pal-mcp-server\n ```\n\n2. **Run the setup script**:\n ```bash\n # Make the script executable and run it\n chmod +x run-server.sh\n ./run-server.sh\n ```\n\n3. **Verify Claude Code can find the MCP server**:\n ```bash\n # List configured MCP servers\n claude mcp list\n \n # You should see 'pal' listed in the output\n # If not, the setup script will provide the correct configuration\n ```\n\n## Troubleshooting WSL Issues\n\n### Python Environment Issues\n\n```bash\n# If you encounter Python virtual environment issues\nsudo apt install -y python3.12-venv python3.12-dev\n\n# Ensure pip is up to date\npython3 -m pip install --upgrade pip\n```\n\n### Path Issues\n\n- Always use the full WSL path for MCP configuration (e.g., `/home/YourName/pal-mcp-server/`)\n- The setup script automatically detects WSL and configures the correct paths\n\n### Claude Code Connection Issues\n\n```bash\n# If Claude Code can't connect to the MCP server, check the configuration\ncat ~/.claude.json | grep -A 10 \"pal\"\n\n# The configuration should show the correct WSL path to the Python executable\n# Example: \"/home/YourName/pal-mcp-server/.pal_venv/bin/python\"\n```\n\n### Performance Tip\n\nFor best performance, keep your pal-mcp-server directory in the WSL filesystem (e.g., `~/pal-mcp-server`) rather than in the Windows filesystem (`/mnt/c/...`)." }, { "path": "examples/claude_config_macos.json", "content": "{\n \"comment\": \"macOS configuration using standalone server\",\n \"comment2\": \"Run './run-server.sh' to set up the environment and get exact paths\",\n \"comment3\": \"Use './run-server.sh -c' to display the correct configuration\",\n \"mcpServers\": {\n \"pal\": {\n \"command\": \"/path/to/pal-mcp-server/.pal_venv/bin/python\",\n \"args\": [\"/path/to/pal-mcp-server/server.py\"]\n }\n }\n}" }, { "path": "examples/claude_config_wsl.json", "content": "{\n \"comment\": \"Windows configuration using WSL with standalone server\",\n \"comment2\": \"Run './run-server.sh' in WSL to set up the environment and get exact paths\",\n \"comment3\": \"Use './run-server.sh -c' to display the correct configuration\",\n \"mcpServers\": {\n \"pal\": {\n \"command\": \"wsl.exe\",\n \"args\": [\n \"/path/to/pal-mcp-server/.pal_venv/bin/python\",\n \"/path/to/pal-mcp-server/server.py\"\n ]\n }\n }\n}" }, { "path": "pal-mcp-server", "content": "#!/bin/bash\n# Wrapper script for Gemini CLI compatibility\n\n# Get the directory of this script\nDIR=\"$(cd \"$(dirname \"$0\")\" && pwd)\"\n\n# Change to the pal-mcp-server directory\ncd \"$DIR\"\n\n# Execute the Python server with all arguments passed through\nexec .pal_venv/bin/python server.py \"$@\"" }, { "path": "providers/__init__.py", "content": "\"\"\"Model provider abstractions for supporting multiple AI providers.\"\"\"\n\nfrom .azure_openai import AzureOpenAIProvider\nfrom .base import ModelProvider\nfrom .gemini import GeminiModelProvider\nfrom .openai import OpenAIModelProvider\nfrom .openai_compatible import OpenAICompatibleProvider\nfrom .openrouter import OpenRouterProvider\nfrom .registry import ModelProviderRegistry\nfrom .shared import ModelCapabilities, ModelResponse\n\n__all__ = [\n \"ModelProvider\",\n \"ModelResponse\",\n \"ModelCapabilities\",\n \"ModelProviderRegistry\",\n \"AzureOpenAIProvider\",\n \"GeminiModelProvider\",\n \"OpenAIModelProvider\",\n \"OpenAICompatibleProvider\",\n \"OpenRouterProvider\",\n]\n" }, { "path": "providers/azure_openai.py", "content": "\"\"\"Azure OpenAI provider built on the OpenAI-compatible implementation.\"\"\"\n\nfrom __future__ import annotations\n\nimport logging\nfrom dataclasses import asdict, replace\n\ntry: # pragma: no cover - optional dependency\n from openai import AzureOpenAI\nexcept ImportError: # pragma: no cover\n AzureOpenAI = None # type: ignore[assignment]\n\nfrom utils.env import get_env, suppress_env_vars\n\nfrom .openai import OpenAIModelProvider\nfrom .openai_compatible import OpenAICompatibleProvider\nfrom .registries.azure import AzureModelRegistry\nfrom .shared import ModelCapabilities, ModelResponse, ProviderType, TemperatureConstraint\n\nlogger = logging.getLogger(__name__)\n\n\nclass AzureOpenAIProvider(OpenAICompatibleProvider):\n \"\"\"Thin Azure wrapper that reuses the OpenAI-compatible request pipeline.\"\"\"\n\n FRIENDLY_NAME = \"Azure OpenAI\"\n DEFAULT_API_VERSION = \"2024-02-15-preview\"\n\n # The OpenAI-compatible base expects subclasses to expose capabilities via\n # ``get_all_model_capabilities``. Azure deployments are user-defined, so we\n # build the catalogue dynamically from environment configuration instead of\n # relying on a static ``MODEL_CAPABILITIES`` map.\n MODEL_CAPABILITIES: dict[str, ModelCapabilities] = {}\n\n def __init__(\n self,\n api_key: str,\n *,\n azure_endpoint: str | None = None,\n api_version: str | None = None,\n deployments: dict[str, object] | None = None,\n **kwargs,\n ) -> None:\n # Let the OpenAI-compatible base handle shared configuration such as\n # timeouts, restriction-aware allowlists, and logging. ``base_url`` maps\n # directly onto Azure's endpoint URL.\n super().__init__(api_key, base_url=azure_endpoint, **kwargs)\n\n if not azure_endpoint:\n azure_endpoint = get_env(\"AZURE_OPENAI_ENDPOINT\")\n if not azure_endpoint:\n raise ValueError(\"Azure OpenAI endpoint is required via parameter or AZURE_OPENAI_ENDPOINT\")\n\n self.azure_endpoint = azure_endpoint.rstrip(\"/\")\n self.api_version = api_version or get_env(\"AZURE_OPENAI_API_VERSION\", self.DEFAULT_API_VERSION)\n\n registry_specs = self._load_registry_entries()\n override_specs = self._normalise_deployments(deployments or {}) if deployments else {}\n\n self._model_specs = self._merge_specs(registry_specs, override_specs)\n if not self._model_specs:\n raise ValueError(\n \"Azure OpenAI provider requires at least one configured deployment. \"\n \"Populate conf/azure_models.json or set AZURE_MODELS_CONFIG_PATH.\"\n )\n\n self._capabilities = self._build_capabilities_map()\n self._deployment_map = {name: spec[\"deployment\"] for name, spec in self._model_specs.items()}\n self._deployment_alias_lookup = {\n deployment.lower(): canonical for canonical, deployment in self._deployment_map.items()\n }\n self._canonical_lookup = {name.lower(): name for name in self._model_specs.keys()}\n self._invalidate_capability_cache()\n\n # ------------------------------------------------------------------\n # Capability helpers\n # ------------------------------------------------------------------\n def get_all_model_capabilities(self) -> dict[str, ModelCapabilities]:\n return dict(self._capabilities)\n\n def get_provider_type(self) -> ProviderType:\n return ProviderType.AZURE\n\n def get_capabilities(self, model_name: str) -> ModelCapabilities: # type: ignore[override]\n lowered = model_name.lower()\n if lowered in self._deployment_alias_lookup:\n canonical = self._deployment_alias_lookup[lowered]\n return super().get_capabilities(canonical)\n canonical = self._canonical_lookup.get(lowered)\n if canonical:\n return super().get_capabilities(canonical)\n return super().get_capabilities(model_name)\n\n def validate_model_name(self, model_name: str) -> bool: # type: ignore[override]\n lowered = model_name.lower()\n if lowered in self._deployment_alias_lookup or lowered in self._canonical_lookup:\n return True\n return super().validate_model_name(model_name)\n\n def _build_capabilities_map(self) -> dict[str, ModelCapabilities]:\n capabilities: dict[str, ModelCapabilities] = {}\n\n for canonical_name, spec in self._model_specs.items():\n template_capability: ModelCapabilities | None = spec.get(\"capability\")\n overrides = spec.get(\"overrides\", {})\n\n if template_capability:\n cloned = replace(template_capability)\n else:\n template = OpenAIModelProvider.MODEL_CAPABILITIES.get(canonical_name)\n\n if template:\n friendly = template.friendly_name.replace(\"OpenAI\", \"Azure OpenAI\", 1)\n cloned = replace(\n template,\n provider=ProviderType.AZURE,\n friendly_name=friendly,\n aliases=list(template.aliases),\n )\n else:\n deployment_name = spec.get(\"deployment\", \"\")\n cloned = ModelCapabilities(\n provider=ProviderType.AZURE,\n model_name=canonical_name,\n friendly_name=f\"Azure OpenAI ({canonical_name})\",\n description=f\"Azure deployment '{deployment_name}' for {canonical_name}\",\n aliases=[],\n )\n\n if overrides:\n overrides = dict(overrides)\n temp_override = overrides.get(\"temperature_constraint\")\n if isinstance(temp_override, str):\n overrides[\"temperature_constraint\"] = TemperatureConstraint.create(temp_override)\n\n aliases_override = overrides.get(\"aliases\")\n if isinstance(aliases_override, str):\n overrides[\"aliases\"] = [alias.strip() for alias in aliases_override.split(\",\") if alias.strip()]\n provider_override = overrides.get(\"provider\")\n if provider_override:\n overrides.pop(\"provider\", None)\n\n try:\n cloned = replace(cloned, **overrides)\n except TypeError:\n base_data = asdict(cloned)\n base_data.update(overrides)\n base_data[\"provider\"] = ProviderType.AZURE\n temp_value = base_data.get(\"temperature_constraint\")\n if isinstance(temp_value, str):\n base_data[\"temperature_constraint\"] = TemperatureConstraint.create(temp_value)\n cloned = ModelCapabilities(**base_data)\n\n if cloned.provider != ProviderType.AZURE:\n cloned.provider = ProviderType.AZURE\n\n capabilities[canonical_name] = cloned\n\n return capabilities\n\n def _load_registry_entries(self) -> dict[str, dict]:\n try:\n registry = AzureModelRegistry()\n except Exception as exc: # pragma: no cover - registry failure should not crash provider\n logger.warning(\"Unable to load Azure model registry: %s\", exc)\n return {}\n\n entries: dict[str, dict] = {}\n for model_name, capability, extra in registry.iter_entries():\n deployment = extra.get(\"deployment\")\n if not deployment:\n logger.warning(\"Azure model '%s' missing deployment in registry\", model_name)\n continue\n entries[model_name] = {\"deployment\": deployment, \"capability\": capability}\n\n return entries\n\n @staticmethod\n def _merge_specs(\n registry_specs: dict[str, dict],\n override_specs: dict[str, dict],\n ) -> dict[str, dict]:\n specs: dict[str, dict] = {}\n\n for canonical, entry in registry_specs.items():\n specs[canonical] = {\n \"deployment\": entry.get(\"deployment\"),\n \"capability\": entry.get(\"capability\"),\n \"overrides\": {},\n }\n\n for canonical, entry in override_specs.items():\n spec = specs.get(canonical, {\"deployment\": None, \"capability\": None, \"overrides\": {}})\n deployment = entry.get(\"deployment\")\n if deployment:\n spec[\"deployment\"] = deployment\n overrides = {k: v for k, v in entry.items() if k not in {\"deployment\"}}\n overrides.pop(\"capability\", None)\n if overrides:\n spec[\"overrides\"].update(overrides)\n specs[canonical] = spec\n\n return {k: v for k, v in specs.items() if v.get(\"deployment\")}\n\n @staticmethod\n def _normalise_deployments(mapping: dict[str, object]) -> dict[str, dict]:\n normalised: dict[str, dict] = {}\n for canonical, spec in mapping.items():\n canonical_name = (canonical or \"\").strip()\n if not canonical_name:\n continue\n\n deployment_name: str | None = None\n overrides: dict[str, object] = {}\n\n if isinstance(spec, str):\n deployment_name = spec.strip()\n elif isinstance(spec, dict):\n deployment_name = spec.get(\"deployment\") or spec.get(\"deployment_name\")\n overrides = {k: v for k, v in spec.items() if k not in {\"deployment\", \"deployment_name\"}}\n\n if not deployment_name:\n continue\n\n normalised[canonical_name] = {\"deployment\": deployment_name.strip(), **overrides}\n\n return normalised\n\n # ------------------------------------------------------------------\n # Azure-specific configuration\n # ------------------------------------------------------------------\n @property\n def client(self): # type: ignore[override]\n \"\"\"Instantiate the Azure OpenAI client on first use.\"\"\"\n\n if self._client is None:\n if AzureOpenAI is None:\n raise ImportError(\n \"Azure OpenAI support requires the 'openai' package. Install it with `pip install openai`.\"\n )\n\n import httpx\n\n proxy_env_vars = [\"HTTP_PROXY\", \"HTTPS_PROXY\", \"ALL_PROXY\", \"http_proxy\", \"https_proxy\", \"all_proxy\"]\n\n with suppress_env_vars(*proxy_env_vars):\n try:\n timeout_config = self.timeout_config\n\n http_client = httpx.Client(timeout=timeout_config, follow_redirects=True)\n\n client_kwargs = {\n \"api_key\": self.api_key,\n \"azure_endpoint\": self.azure_endpoint,\n \"api_version\": self.api_version,\n \"http_client\": http_client,\n }\n\n if self.DEFAULT_HEADERS:\n client_kwargs[\"default_headers\"] = self.DEFAULT_HEADERS.copy()\n\n logger.debug(\n \"Initializing Azure OpenAI client endpoint=%s api_version=%s timeouts=%s\",\n self.azure_endpoint,\n self.api_version,\n timeout_config,\n )\n\n self._client = AzureOpenAI(**client_kwargs)\n\n except Exception as exc:\n logger.error(\"Failed to create Azure OpenAI client: %s\", exc)\n raise\n\n return self._client\n\n # ------------------------------------------------------------------\n # Request delegation\n # ------------------------------------------------------------------\n def generate_content(\n self,\n prompt: str,\n model_name: str,\n system_prompt: str | None = None,\n temperature: float = 0.3,\n max_output_tokens: int | None = None,\n images: list[str] | None = None,\n **kwargs,\n ) -> ModelResponse:\n canonical_name, deployment_name = self._resolve_canonical_and_deployment(model_name)\n\n # Delegate to the shared OpenAI-compatible implementation using the\n # deployment name – Azure requires the deployment identifier in the\n # ``model`` field. The returned ``ModelResponse`` is normalised so\n # downstream consumers continue to see the canonical model name.\n raw_response = super().generate_content(\n prompt=prompt,\n model_name=deployment_name,\n system_prompt=system_prompt,\n temperature=temperature,\n max_output_tokens=max_output_tokens,\n images=images,\n **kwargs,\n )\n\n capabilities = self._capabilities.get(canonical_name)\n friendly_name = capabilities.friendly_name if capabilities else self.FRIENDLY_NAME\n\n return ModelResponse(\n content=raw_response.content,\n usage=raw_response.usage,\n model_name=canonical_name,\n friendly_name=friendly_name,\n provider=ProviderType.AZURE,\n metadata={**raw_response.metadata, \"deployment\": deployment_name},\n )\n\n def _resolve_canonical_and_deployment(self, model_name: str) -> tuple[str, str]:\n resolved_canonical = self._resolve_model_name(model_name)\n\n if resolved_canonical not in self._deployment_map:\n # The base resolver may hand back the deployment alias. Try to map it\n # back to a canonical entry.\n for canonical, deployment in self._deployment_map.items():\n if deployment.lower() == resolved_canonical.lower():\n return canonical, deployment\n raise ValueError(f\"Model '{model_name}' is not configured for Azure OpenAI\")\n\n return resolved_canonical, self._deployment_map[resolved_canonical]\n\n def _parse_allowed_models(self) -> set[str] | None: # type: ignore[override]\n # Support both AZURE_ALLOWED_MODELS (inherited behaviour) and the\n # clearer AZURE_OPENAI_ALLOWED_MODELS alias.\n explicit = get_env(\"AZURE_OPENAI_ALLOWED_MODELS\")\n if explicit:\n models = {m.strip().lower() for m in explicit.split(\",\") if m.strip()}\n if models:\n logger.info(\"Configured allowed models for Azure OpenAI: %s\", sorted(models))\n self._allowed_alias_cache = {}\n return models\n\n return super()._parse_allowed_models()\n" }, { "path": "providers/base.py", "content": "\"\"\"Base interfaces and common behaviour for model providers.\"\"\"\n\nimport logging\nimport time\nfrom abc import ABC, abstractmethod\nfrom typing import TYPE_CHECKING, Any, Callable, Optional\n\nif TYPE_CHECKING:\n from tools.models import ToolModelCategory\n\nfrom .shared import ModelCapabilities, ModelResponse, ProviderType\n\nlogger = logging.getLogger(__name__)\n\n\nclass ModelProvider(ABC):\n \"\"\"Abstract base class for all model backends in the MCP server.\n\n Role\n Defines the interface every provider must implement so the registry,\n restriction service, and tools have a uniform surface for listing\n models, resolving aliases, and executing requests.\n\n Responsibilities\n * expose static capability metadata for each supported model via\n :class:`ModelCapabilities`\n * accept user prompts, forward them to the underlying SDK, and wrap\n responses in :class:`ModelResponse`\n * report tokenizer counts for budgeting and validation logic\n * advertise provider identity (``ProviderType``) so restriction\n policies can map environment configuration onto providers\n * validate whether a model name or alias is recognised by the provider\n\n Shared helpers like temperature validation, alias resolution, and\n restriction-aware ``list_models`` live here so concrete subclasses only\n need to supply their catalogue and wire up SDK-specific behaviour.\n \"\"\"\n\n # All concrete providers must define their supported models\n MODEL_CAPABILITIES: dict[str, Any] = {}\n\n def __init__(self, api_key: str, **kwargs):\n \"\"\"Initialize the provider with API key and optional configuration.\"\"\"\n self.api_key = api_key\n self.config = kwargs\n self._sorted_capabilities_cache: Optional[list[tuple[str, ModelCapabilities]]] = None\n\n # ------------------------------------------------------------------\n # Provider identity & capability surface\n # ------------------------------------------------------------------\n @abstractmethod\n def get_provider_type(self) -> ProviderType:\n \"\"\"Return the concrete provider identity.\"\"\"\n\n def get_capabilities(self, model_name: str) -> ModelCapabilities:\n \"\"\"Resolve capability metadata for a model name.\n\n This centralises the alias resolution β†’ lookup β†’ restriction check\n pipeline so providers only override the pieces they genuinely need to\n customise. Subclasses usually only override ``_lookup_capabilities`` to\n integrate a registry or dynamic source, or ``_finalise_capabilities`` to\n tweak the returned object.\n\n Args:\n model_name: Canonical model name or its alias\n \"\"\"\n\n resolved_model_name = self._resolve_model_name(model_name)\n capabilities = self._lookup_capabilities(resolved_model_name, model_name)\n\n if capabilities is None:\n self._raise_unsupported_model(model_name)\n\n self._ensure_model_allowed(capabilities, resolved_model_name, model_name)\n return self._finalise_capabilities(capabilities, resolved_model_name, model_name)\n\n def get_all_model_capabilities(self) -> dict[str, ModelCapabilities]:\n \"\"\"Return statically declared capabilities when available.\"\"\"\n\n model_map = getattr(self, \"MODEL_CAPABILITIES\", None)\n if isinstance(model_map, dict) and model_map:\n return {k: v for k, v in model_map.items() if isinstance(v, ModelCapabilities)}\n return {}\n\n def get_capabilities_by_rank(self) -> list[tuple[str, ModelCapabilities]]:\n \"\"\"Return model capabilities sorted by effective capability rank.\"\"\"\n\n if self._sorted_capabilities_cache is not None:\n return list(self._sorted_capabilities_cache)\n\n model_configs = self.get_all_model_capabilities()\n if not model_configs:\n self._sorted_capabilities_cache = []\n return []\n\n items = list(model_configs.items())\n items.sort(key=lambda item: (-item[1].get_effective_capability_rank(), item[0]))\n self._sorted_capabilities_cache = items\n return list(items)\n\n def _invalidate_capability_cache(self) -> None:\n \"\"\"Clear cached sorted capability data (call after dynamic updates).\"\"\"\n\n self._sorted_capabilities_cache = None\n\n def list_models(\n self,\n *,\n respect_restrictions: bool = True,\n include_aliases: bool = True,\n lowercase: bool = False,\n unique: bool = False,\n ) -> list[str]:\n \"\"\"Return formatted model names supported by this provider.\"\"\"\n\n model_configs = self.get_all_model_capabilities()\n if not model_configs:\n return []\n\n restriction_service = None\n if respect_restrictions:\n from utils.model_restrictions import get_restriction_service\n\n restriction_service = get_restriction_service()\n\n if restriction_service:\n allowed_configs = {}\n for model_name, config in model_configs.items():\n if restriction_service.is_allowed(self.get_provider_type(), model_name):\n allowed_configs[model_name] = config\n model_configs = allowed_configs\n\n if not model_configs:\n return []\n\n return ModelCapabilities.collect_model_names(\n model_configs,\n include_aliases=include_aliases,\n lowercase=lowercase,\n unique=unique,\n )\n\n # ------------------------------------------------------------------\n # Request execution\n # ------------------------------------------------------------------\n @abstractmethod\n def generate_content(\n self,\n prompt: str,\n model_name: str,\n system_prompt: Optional[str] = None,\n temperature: float = 0.3,\n max_output_tokens: Optional[int] = None,\n **kwargs,\n ) -> ModelResponse:\n \"\"\"Generate content using the model.\n\n This is the core method that all providers must implement to generate responses\n from their models. Providers should handle model-specific capabilities and\n constraints appropriately.\n\n Args:\n prompt: The main user prompt/query to send to the model\n model_name: Canonical model name or its alias that the provider supports\n system_prompt: Optional system instructions to prepend to the prompt for\n establishing context, behavior, or role\n temperature: Controls randomness in generation (0.0=deterministic, 1.0=creative),\n default 0.3. Some models may not support temperature control\n max_output_tokens: Optional maximum number of tokens to generate in the response.\n If not specified, uses the model's default limit\n **kwargs: Additional provider-specific parameters that vary by implementation\n (e.g., thinking_mode for Gemini, top_p for OpenAI, images for vision models)\n\n Returns:\n ModelResponse: Standardized response object containing:\n - content: The generated text response\n - usage: Token usage statistics (input/output/total)\n - model_name: The model that was actually used\n - friendly_name: Human-readable provider/model identifier\n - provider: The ProviderType enum value\n - metadata: Provider-specific metadata (finish_reason, safety info, etc.)\n\n Raises:\n ValueError: If the model is not supported, parameters are invalid,\n or the model is restricted by policy\n RuntimeError: If the API call fails after retries\n \"\"\"\n\n def count_tokens(self, text: str, model_name: str) -> int:\n \"\"\"Estimate token usage for a piece of text.\"\"\"\n\n resolved_model = self._resolve_model_name(model_name)\n\n if not text:\n return 0\n\n estimated = max(1, len(text) // 4)\n logger.debug(\"Estimating %s tokens for model %s via character heuristic\", estimated, resolved_model)\n return estimated\n\n def close(self) -> None:\n \"\"\"Clean up any resources held by the provider.\"\"\"\n\n return\n\n # ------------------------------------------------------------------\n # Retry helpers\n # ------------------------------------------------------------------\n def _is_error_retryable(self, error: Exception) -> bool:\n \"\"\"Return True when an error warrants another attempt.\n\n Subclasses with structured provider errors should override this hook.\n The default implementation only retries obvious transient failures such\n as timeouts or 5xx responses detected via string inspection.\n \"\"\"\n\n error_str = str(error).lower()\n\n if \"429\" in error_str or \"rate limit\" in error_str:\n return False\n\n retryable_indicators = [\n \"timeout\",\n \"connection\",\n \"temporary\",\n \"unavailable\",\n \"retry\",\n \"reset\",\n \"refused\",\n \"broken pipe\",\n \"tls\",\n \"handshake\",\n \"network\",\n \"500\",\n \"502\",\n \"503\",\n \"504\",\n ]\n\n return any(indicator in error_str for indicator in retryable_indicators)\n\n def _run_with_retries(\n self,\n operation: Callable[[], Any],\n *,\n max_attempts: int,\n delays: Optional[list[float]] = None,\n log_prefix: str = \"\",\n ):\n \"\"\"Execute ``operation`` with retry semantics.\n\n Args:\n operation: Callable returning the provider result.\n max_attempts: Maximum number of attempts (>=1).\n delays: Optional list of sleep durations between attempts.\n log_prefix: Optional identifier for log clarity.\n\n Returns:\n Whatever ``operation`` returns.\n\n Raises:\n The last exception when all retries fail or the error is not retryable.\n \"\"\"\n\n if max_attempts < 1:\n raise ValueError(\"max_attempts must be >= 1\")\n\n attempts = max_attempts\n delays = delays or []\n last_exc: Optional[Exception] = None\n\n for attempt_index in range(attempts):\n try:\n return operation()\n except Exception as exc: # noqa: BLE001 - bubble exact provider errors\n last_exc = exc\n attempt_number = attempt_index + 1\n\n # Decide whether to retry based on subclass hook\n retryable = self._is_error_retryable(exc)\n if not retryable or attempt_number >= attempts:\n raise\n\n delay_idx = min(attempt_index, len(delays) - 1) if delays else -1\n delay = delays[delay_idx] if delay_idx >= 0 else 0.0\n\n if delay > 0:\n logger.warning(\n \"%s retryable error (attempt %s/%s): %s. Retrying in %ss...\",\n log_prefix or self.__class__.__name__,\n attempt_number,\n attempts,\n exc,\n delay,\n )\n time.sleep(delay)\n else:\n logger.warning(\n \"%s retryable error (attempt %s/%s): %s. Retrying...\",\n log_prefix or self.__class__.__name__,\n attempt_number,\n attempts,\n exc,\n )\n\n # Should never reach here because loop either returns or raises\n raise last_exc if last_exc else RuntimeError(\"Retry loop exited without result\")\n\n # ------------------------------------------------------------------\n # Validation hooks\n # ------------------------------------------------------------------\n def validate_model_name(self, model_name: str) -> bool:\n \"\"\"\n Return ``True`` when the model resolves to an allowed capability.\n\n Args:\n model_name: Canonical model name or its alias\n \"\"\"\n\n try:\n self.get_capabilities(model_name)\n except ValueError:\n return False\n return True\n\n def validate_parameters(self, model_name: str, temperature: float, **kwargs) -> None:\n \"\"\"\n Validate model parameters against capabilities.\n\n Args:\n model_name: Canonical model name or its alias\n \"\"\"\n\n capabilities = self.get_capabilities(model_name)\n\n if not capabilities.temperature_constraint.validate(temperature):\n constraint_desc = capabilities.temperature_constraint.get_description()\n raise ValueError(f\"Temperature {temperature} is invalid for model {model_name}. {constraint_desc}\")\n\n # ------------------------------------------------------------------\n # Preference / registry hooks\n # ------------------------------------------------------------------\n def get_preferred_model(self, category: \"ToolModelCategory\", allowed_models: list[str]) -> Optional[str]:\n \"\"\"Get the preferred model from this provider for a given category.\"\"\"\n\n return None\n\n def get_model_registry(self) -> Optional[dict[str, Any]]:\n \"\"\"Return the model registry backing this provider, if any.\"\"\"\n\n return None\n\n # ------------------------------------------------------------------\n # Capability lookup pipeline\n # ------------------------------------------------------------------\n def _lookup_capabilities(\n self,\n canonical_name: str,\n requested_name: Optional[str] = None,\n ) -> Optional[ModelCapabilities]:\n \"\"\"Return ``ModelCapabilities`` for the canonical model name.\"\"\"\n\n return self.get_all_model_capabilities().get(canonical_name)\n\n def _ensure_model_allowed(\n self,\n capabilities: ModelCapabilities,\n canonical_name: str,\n requested_name: str,\n ) -> None:\n \"\"\"Raise ``ValueError`` if the model violates restriction policy.\"\"\"\n\n try:\n from utils.model_restrictions import get_restriction_service\n except Exception: # pragma: no cover - only triggered if service import breaks\n return\n\n restriction_service = get_restriction_service()\n if not restriction_service:\n return\n\n if restriction_service.is_allowed(self.get_provider_type(), canonical_name, requested_name):\n return\n\n raise ValueError(\n f\"{self.get_provider_type().value} model '{canonical_name}' is not allowed by restriction policy.\"\n )\n\n def _finalise_capabilities(\n self,\n capabilities: ModelCapabilities,\n canonical_name: str,\n requested_name: str,\n ) -> ModelCapabilities:\n \"\"\"Allow subclasses to adjust capability metadata before returning.\"\"\"\n\n return capabilities\n\n def _raise_unsupported_model(self, model_name: str) -> None:\n \"\"\"Raise the canonical unsupported-model error.\"\"\"\n\n raise ValueError(f\"Unsupported model '{model_name}' for provider {self.get_provider_type().value}.\")\n\n def _resolve_model_name(self, model_name: str) -> str:\n \"\"\"Resolve model shorthand to full name.\n\n This implementation uses the hook methods to support different\n model configuration sources.\n\n Args:\n model_name: Canonical model name or its alias\n\n Returns:\n Resolved model name\n \"\"\"\n # Get model configurations from the hook method\n model_configs = self.get_all_model_capabilities()\n\n # First check if it's already a base model name (case-sensitive exact match)\n if model_name in model_configs:\n return model_name\n\n # Check case-insensitively for both base models and aliases\n model_name_lower = model_name.lower()\n\n # Check base model names case-insensitively\n for base_model in model_configs:\n if base_model.lower() == model_name_lower:\n return base_model\n\n # Check aliases from the model configurations\n alias_map = ModelCapabilities.collect_aliases(model_configs)\n for base_model, aliases in alias_map.items():\n if any(alias.lower() == model_name_lower for alias in aliases):\n return base_model\n\n # If not found, return as-is\n return model_name\n" }, { "path": "providers/custom.py", "content": "\"\"\"Custom API provider implementation.\"\"\"\n\nimport logging\n\nfrom utils.env import get_env\n\nfrom .openai_compatible import OpenAICompatibleProvider\nfrom .registries.custom import CustomEndpointModelRegistry\nfrom .registries.openrouter import OpenRouterModelRegistry\nfrom .shared import ModelCapabilities, ProviderType\n\n\nclass CustomProvider(OpenAICompatibleProvider):\n \"\"\"Adapter for self-hosted or local OpenAI-compatible endpoints.\n\n Role\n Provide a uniform bridge between the MCP server and user-managed\n OpenAI-compatible services (Ollama, vLLM, LM Studio, bespoke gateways).\n By subclassing :class:`OpenAICompatibleProvider` it inherits request and\n token handling, while the custom registry exposes locally defined model\n metadata.\n\n Notable behaviour\n * Uses :class:`OpenRouterModelRegistry` to load model definitions and\n aliases so custom deployments share the same metadata pipeline as\n OpenRouter itself.\n * Normalises version-tagged model names (``model:latest``) and applies\n restriction policies just like cloud providers, ensuring consistent\n behaviour across environments.\n \"\"\"\n\n FRIENDLY_NAME = \"Custom API\"\n\n # Model registry for managing configurations and aliases\n _registry: CustomEndpointModelRegistry | None = None\n\n def __init__(self, api_key: str = \"\", base_url: str = \"\", **kwargs):\n \"\"\"Initialize Custom provider for local/self-hosted models.\n\n This provider supports any OpenAI-compatible API endpoint including:\n - Ollama (typically no API key required)\n - vLLM (may require API key)\n - LM Studio (may require API key)\n - Text Generation WebUI (may require API key)\n - Enterprise/self-hosted APIs (typically require API key)\n\n Args:\n api_key: API key for the custom endpoint. Can be empty string for\n providers that don't require authentication (like Ollama).\n Falls back to CUSTOM_API_KEY environment variable if not provided.\n base_url: Base URL for the custom API endpoint (e.g., 'http://localhost:11434/v1').\n Falls back to CUSTOM_API_URL environment variable if not provided.\n **kwargs: Additional configuration passed to parent OpenAI-compatible provider\n\n Raises:\n ValueError: If no base_url is provided via parameter or environment variable\n \"\"\"\n # Fall back to environment variables only if not provided\n if not base_url:\n base_url = get_env(\"CUSTOM_API_URL\", \"\") or \"\"\n if not api_key:\n api_key = get_env(\"CUSTOM_API_KEY\", \"\") or \"\"\n\n if not base_url:\n raise ValueError(\n \"Custom API URL must be provided via base_url parameter or CUSTOM_API_URL environment variable\"\n )\n\n # For Ollama and other providers that don't require authentication,\n # set a dummy API key to avoid OpenAI client header issues\n if not api_key:\n api_key = \"dummy-key-for-unauthenticated-endpoint\"\n logging.debug(\"Using dummy API key for unauthenticated custom endpoint\")\n\n logging.info(f\"Initializing Custom provider with endpoint: {base_url}\")\n\n self._alias_cache: dict[str, str] = {}\n\n super().__init__(api_key, base_url=base_url, **kwargs)\n\n # Initialize model registry\n if CustomProvider._registry is None:\n CustomProvider._registry = CustomEndpointModelRegistry()\n # Log loaded models and aliases only on first load\n models = self._registry.list_models()\n aliases = self._registry.list_aliases()\n logging.info(f\"Custom provider loaded {len(models)} models with {len(aliases)} aliases\")\n\n # ------------------------------------------------------------------\n # Capability surface\n # ------------------------------------------------------------------\n def _lookup_capabilities(\n self,\n canonical_name: str,\n requested_name: str | None = None,\n ) -> ModelCapabilities | None:\n \"\"\"Return capabilities for models explicitly marked as custom.\"\"\"\n\n builtin = super()._lookup_capabilities(canonical_name, requested_name)\n if builtin is not None:\n return builtin\n\n registry_entry = self._registry.resolve(canonical_name)\n if registry_entry:\n registry_entry.provider = ProviderType.CUSTOM\n return registry_entry\n\n logging.debug(\n \"Custom provider cannot resolve model '%s'; ensure it is declared in custom_models.json\",\n canonical_name,\n )\n return None\n\n def get_provider_type(self) -> ProviderType:\n \"\"\"Identify this provider for restriction and logging logic.\"\"\"\n\n return ProviderType.CUSTOM\n\n # ------------------------------------------------------------------\n # Registry helpers\n # ------------------------------------------------------------------\n\n def _resolve_model_name(self, model_name: str) -> str:\n \"\"\"Resolve registry aliases and strip version tags for local models.\"\"\"\n\n cache_key = model_name.lower()\n if cache_key in self._alias_cache:\n return self._alias_cache[cache_key]\n\n config = self._registry.resolve(model_name)\n if config:\n if config.model_name != model_name:\n logging.debug(\"Resolved model alias '%s' to '%s'\", model_name, config.model_name)\n resolved = config.model_name\n self._alias_cache[cache_key] = resolved\n self._alias_cache.setdefault(resolved.lower(), resolved)\n return resolved\n\n if \":\" in model_name:\n base_model = model_name.split(\":\")[0]\n logging.debug(f\"Stripped version tag from '{model_name}' -> '{base_model}'\")\n\n base_config = self._registry.resolve(base_model)\n if base_config:\n logging.debug(\"Resolved base model '%s' to '%s'\", base_model, base_config.model_name)\n resolved = base_config.model_name\n self._alias_cache[cache_key] = resolved\n self._alias_cache.setdefault(resolved.lower(), resolved)\n return resolved\n self._alias_cache[cache_key] = base_model\n return base_model\n\n logging.debug(f\"Model '{model_name}' not found in registry, using as-is\")\n # Attempt to resolve via OpenRouter registry so aliases still map cleanly\n openrouter_registry = OpenRouterModelRegistry()\n openrouter_config = openrouter_registry.resolve(model_name)\n if openrouter_config:\n resolved = openrouter_config.model_name\n self._alias_cache[cache_key] = resolved\n self._alias_cache.setdefault(resolved.lower(), resolved)\n return resolved\n\n self._alias_cache[cache_key] = model_name\n return model_name\n\n def get_all_model_capabilities(self) -> dict[str, ModelCapabilities]:\n \"\"\"Expose registry capabilities for models marked as custom.\"\"\"\n\n if not self._registry:\n return {}\n\n capabilities = {}\n for model in self._registry.list_models():\n config = self._registry.resolve(model)\n if config:\n capabilities[model] = config\n return capabilities\n" }, { "path": "providers/dial.py", "content": "\"\"\"DIAL (Data & AI Layer) model provider implementation.\"\"\"\n\nimport logging\nimport threading\nfrom typing import ClassVar, Optional\n\nfrom utils.env import get_env\n\nfrom .openai_compatible import OpenAICompatibleProvider\nfrom .registries.dial import DialModelRegistry\nfrom .registry_provider_mixin import RegistryBackedProviderMixin\nfrom .shared import ModelCapabilities, ModelResponse, ProviderType\n\nlogger = logging.getLogger(__name__)\n\n\nclass DIALModelProvider(RegistryBackedProviderMixin, OpenAICompatibleProvider):\n \"\"\"Client for the DIAL (Data & AI Layer) aggregation service.\n\n DIAL exposes several third-party models behind a single OpenAI-compatible\n endpoint. This provider wraps the service, publishes capability metadata\n for the known deployments, and centralises retry/backoff settings tailored\n to DIAL's latency characteristics.\n \"\"\"\n\n FRIENDLY_NAME = \"DIAL\"\n\n REGISTRY_CLASS = DialModelRegistry\n MODEL_CAPABILITIES: ClassVar[dict[str, ModelCapabilities]] = {}\n\n # Retry configuration for API calls\n MAX_RETRIES = 4\n RETRY_DELAYS = [1, 3, 5, 8] # seconds\n\n def __init__(self, api_key: str, **kwargs):\n \"\"\"Initialize DIAL provider with API key and host.\n\n Args:\n api_key: DIAL API key for authentication\n **kwargs: Additional configuration options\n \"\"\"\n self._ensure_registry()\n # Get DIAL API host from environment or kwargs\n dial_host = kwargs.get(\"base_url\") or get_env(\"DIAL_API_HOST\") or \"https://core.dialx.ai\"\n\n # DIAL uses /openai endpoint for OpenAI-compatible API\n if not dial_host.endswith(\"/openai\"):\n dial_host = f\"{dial_host.rstrip('/')}/openai\"\n\n kwargs[\"base_url\"] = dial_host\n\n # Get API version from environment or use default\n self.api_version = get_env(\"DIAL_API_VERSION\", \"2024-12-01-preview\") or \"2024-12-01-preview\"\n\n # Add DIAL-specific headers\n # DIAL uses Api-Key header instead of Authorization: Bearer\n # Reference: https://dialx.ai/dial_api#section/Authorization\n self.DEFAULT_HEADERS = {\n \"Api-Key\": api_key,\n }\n\n # Store the actual API key for use in Api-Key header\n self._dial_api_key = api_key\n\n # Pass a placeholder API key to OpenAI client - we'll override the auth header in httpx\n # The actual authentication happens via the Api-Key header in the httpx client\n super().__init__(\"placeholder-not-used\", **kwargs)\n\n # Cache for deployment-specific clients to avoid recreating them on each request\n self._deployment_clients = {}\n # Lock to ensure thread-safe client creation\n self._client_lock = threading.Lock()\n\n # Create a SINGLE shared httpx client for the provider instance\n import httpx\n\n # Create custom event hooks to remove Authorization header\n def remove_auth_header(request):\n \"\"\"Remove Authorization header that OpenAI client adds.\"\"\"\n # httpx headers are case-insensitive, so we need to check all variations\n headers_to_remove = []\n for header_name in request.headers:\n if header_name.lower() == \"authorization\":\n headers_to_remove.append(header_name)\n\n for header_name in headers_to_remove:\n del request.headers[header_name]\n\n self._http_client = httpx.Client(\n timeout=self.timeout_config,\n verify=True,\n follow_redirects=True,\n headers=self.DEFAULT_HEADERS.copy(), # Include DIAL headers including Api-Key\n limits=httpx.Limits(\n max_keepalive_connections=5,\n max_connections=10,\n keepalive_expiry=30.0,\n ),\n event_hooks={\"request\": [remove_auth_header]},\n )\n\n logger.info(f\"Initialized DIAL provider with host: {dial_host} and api-version: {self.api_version}\")\n\n def get_provider_type(self) -> ProviderType:\n \"\"\"Get the provider type.\"\"\"\n return ProviderType.DIAL\n\n def _get_deployment_client(self, deployment: str):\n \"\"\"Get or create a cached client for a specific deployment.\n\n This avoids recreating OpenAI clients on every request, improving performance.\n Reuses the shared HTTP client for connection pooling.\n\n Args:\n deployment: The deployment/model name\n\n Returns:\n OpenAI client configured for the specific deployment\n \"\"\"\n # Check if client already exists without locking for performance\n if deployment in self._deployment_clients:\n return self._deployment_clients[deployment]\n\n # Use lock to ensure thread-safe client creation\n with self._client_lock:\n # Double-check pattern: check again inside the lock\n if deployment not in self._deployment_clients:\n from openai import OpenAI\n\n # Build deployment-specific URL\n base_url = str(self.client.base_url)\n if base_url.endswith(\"/\"):\n base_url = base_url[:-1]\n\n # Remove /openai suffix if present to reconstruct properly\n if base_url.endswith(\"/openai\"):\n base_url = base_url[:-7]\n\n deployment_url = f\"{base_url}/openai/deployments/{deployment}\"\n\n # Create and cache the client, REUSING the shared http_client\n # Use placeholder API key - Authorization header will be removed by http_client event hook\n self._deployment_clients[deployment] = OpenAI(\n api_key=\"placeholder-not-used\",\n base_url=deployment_url,\n http_client=self._http_client, # Pass the shared client with Api-Key header\n default_query={\"api-version\": self.api_version}, # Add api-version as query param\n )\n\n return self._deployment_clients[deployment]\n\n def generate_content(\n self,\n prompt: str,\n model_name: str,\n system_prompt: Optional[str] = None,\n temperature: float = 0.3,\n max_output_tokens: Optional[int] = None,\n images: Optional[list[str]] = None,\n **kwargs,\n ) -> ModelResponse:\n \"\"\"Generate content using DIAL's deployment-specific endpoint.\n\n DIAL uses Azure OpenAI-style deployment endpoints:\n /openai/deployments/{deployment}/chat/completions\n\n Args:\n prompt: The main user prompt/query to send to the model\n model_name: Model name or alias (e.g., \"o3\", \"sonnet-4.1\", \"gemini-2.5-pro\")\n system_prompt: Optional system instructions to prepend to the prompt for context/behavior\n temperature: Sampling temperature for randomness (0.0=deterministic, 1.0=creative), default 0.3\n Note: O3/O4 models don't support temperature and will ignore this parameter\n max_output_tokens: Optional maximum number of tokens to generate in the response\n images: Optional list of image paths or data URLs to include with the prompt (for vision-capable models)\n **kwargs: Additional OpenAI-compatible parameters (top_p, frequency_penalty, presence_penalty, seed, stop)\n\n Returns:\n ModelResponse: Contains the generated content, token usage stats, model metadata, and finish reason\n \"\"\"\n # Validate model name against allow-list\n if not self.validate_model_name(model_name):\n raise ValueError(f\"Model '{model_name}' not in allowed models list. Allowed models: {self.allowed_models}\")\n\n # Validate parameters and fetch capabilities\n self.validate_parameters(model_name, temperature)\n capabilities = self.get_capabilities(model_name)\n\n # Prepare messages\n messages = []\n if system_prompt:\n messages.append({\"role\": \"system\", \"content\": system_prompt})\n # Build user message content\n user_message_content = []\n if prompt:\n user_message_content.append({\"type\": \"text\", \"text\": prompt})\n\n if images and capabilities.supports_images:\n for img_path in images:\n processed_image = self._process_image(img_path)\n if processed_image:\n user_message_content.append(processed_image)\n elif images:\n logger.warning(f\"Model {model_name} does not support images, ignoring {len(images)} image(s)\")\n\n # Add user message. If only text, content will be a string, otherwise a list.\n if len(user_message_content) == 1 and user_message_content[0][\"type\"] == \"text\":\n messages.append({\"role\": \"user\", \"content\": prompt})\n else:\n messages.append({\"role\": \"user\", \"content\": user_message_content})\n\n # Resolve model name\n resolved_model = self._resolve_model_name(model_name)\n\n # Build completion parameters\n completion_params = {\n \"model\": resolved_model,\n \"messages\": messages,\n \"stream\": False,\n }\n\n # Determine temperature support from capabilities\n supports_temperature = capabilities.supports_temperature\n\n # Add temperature parameter if supported\n if supports_temperature:\n completion_params[\"temperature\"] = temperature\n\n # Add max tokens if specified and model supports it\n if max_output_tokens and supports_temperature:\n completion_params[\"max_tokens\"] = max_output_tokens\n\n # Add additional parameters\n for key, value in kwargs.items():\n if key in [\"top_p\", \"frequency_penalty\", \"presence_penalty\", \"seed\", \"stop\", \"stream\"]:\n if not supports_temperature and key in [\"top_p\", \"frequency_penalty\", \"presence_penalty\", \"stream\"]:\n continue\n completion_params[key] = value\n\n # DIAL-specific: Get cached client for deployment endpoint\n deployment_client = self._get_deployment_client(resolved_model)\n\n attempt_counter = {\"value\": 0}\n\n def _attempt() -> ModelResponse:\n attempt_counter[\"value\"] += 1\n response = deployment_client.chat.completions.create(**completion_params)\n\n content = response.choices[0].message.content\n usage = self._extract_usage(response)\n\n return ModelResponse(\n content=content,\n usage=usage,\n model_name=model_name,\n friendly_name=self.FRIENDLY_NAME,\n provider=self.get_provider_type(),\n metadata={\n \"finish_reason\": response.choices[0].finish_reason,\n \"model\": response.model,\n \"id\": response.id,\n \"created\": response.created,\n },\n )\n\n try:\n return self._run_with_retries(\n operation=_attempt,\n max_attempts=self.MAX_RETRIES,\n delays=self.RETRY_DELAYS,\n log_prefix=f\"DIAL API ({resolved_model})\",\n )\n except Exception as exc:\n attempts = max(attempt_counter[\"value\"], 1)\n if attempts == 1:\n raise ValueError(f\"DIAL API error for model {resolved_model}: {exc}\") from exc\n\n raise ValueError(f\"DIAL API error for model {resolved_model} after {attempts} attempts: {exc}\") from exc\n\n def close(self) -> None:\n \"\"\"Clean up HTTP clients when provider is closed.\"\"\"\n logger.info(\"Closing DIAL provider HTTP clients...\")\n\n # Clear the deployment clients cache\n # Note: We don't need to close individual OpenAI clients since they\n # use the shared httpx.Client which we close separately\n self._deployment_clients.clear()\n\n # Close the shared HTTP client\n if hasattr(self, \"_http_client\"):\n try:\n self._http_client.close()\n logger.debug(\"Closed shared HTTP client\")\n except Exception as e:\n logger.warning(f\"Error closing shared HTTP client: {e}\")\n\n # Also close the client created by the superclass (OpenAICompatibleProvider)\n # as it holds its own httpx.Client instance that is not used by DIAL's generate_content\n if hasattr(self, \"client\") and self.client and hasattr(self.client, \"close\"):\n try:\n self.client.close()\n logger.debug(\"Closed superclass's OpenAI client\")\n except Exception as e:\n logger.warning(f\"Error closing superclass's OpenAI client: {e}\")\n" }, { "path": "providers/gemini.py", "content": "\"\"\"Gemini model provider implementation.\"\"\"\n\nimport base64\nimport logging\nfrom typing import TYPE_CHECKING, ClassVar, Optional\n\nif TYPE_CHECKING:\n from tools.models import ToolModelCategory\n\nfrom google import genai\nfrom google.genai import types\n\nfrom utils.env import get_env\nfrom utils.image_utils import validate_image\n\nfrom .base import ModelProvider\nfrom .registries.gemini import GeminiModelRegistry\nfrom .registry_provider_mixin import RegistryBackedProviderMixin\nfrom .shared import ModelCapabilities, ModelResponse, ProviderType\n\nlogger = logging.getLogger(__name__)\n\n\nclass GeminiModelProvider(RegistryBackedProviderMixin, ModelProvider):\n \"\"\"First-party Gemini integration built on the official Google SDK.\n\n The provider advertises detailed thinking-mode budgets, handles optional\n custom endpoints, and performs image pre-processing before forwarding a\n request to the Gemini APIs.\n \"\"\"\n\n REGISTRY_CLASS = GeminiModelRegistry\n MODEL_CAPABILITIES: ClassVar[dict[str, ModelCapabilities]] = {}\n\n # Thinking mode configurations - percentages of model's max_thinking_tokens\n # These percentages work across all models that support thinking\n THINKING_BUDGETS = {\n \"minimal\": 0.005, # 0.5% of max - minimal thinking for fast responses\n \"low\": 0.08, # 8% of max - light reasoning tasks\n \"medium\": 0.33, # 33% of max - balanced reasoning (default)\n \"high\": 0.67, # 67% of max - complex analysis\n \"max\": 1.0, # 100% of max - full thinking budget\n }\n\n def __init__(self, api_key: str, **kwargs):\n \"\"\"Initialize Gemini provider with API key and optional base URL.\"\"\"\n self._ensure_registry()\n super().__init__(api_key, **kwargs)\n self._client = None\n self._token_counters = {} # Cache for token counting\n self._base_url = kwargs.get(\"base_url\", None) # Optional custom endpoint\n self._timeout_override = self._resolve_http_timeout()\n self._invalidate_capability_cache()\n\n # ------------------------------------------------------------------\n # Capability surface\n # ------------------------------------------------------------------\n\n # ------------------------------------------------------------------\n # Client access\n # ------------------------------------------------------------------\n\n @property\n def client(self):\n \"\"\"Lazy initialization of Gemini client.\"\"\"\n if self._client is None:\n http_options_kwargs: dict[str, object] = {}\n if self._base_url:\n http_options_kwargs[\"base_url\"] = self._base_url\n if self._timeout_override is not None:\n http_options_kwargs[\"timeout\"] = self._timeout_override\n\n if http_options_kwargs:\n http_options = types.HttpOptions(**http_options_kwargs)\n logger.debug(\n \"Initializing Gemini client with options: base_url=%s timeout=%s\",\n http_options_kwargs.get(\"base_url\"),\n http_options_kwargs.get(\"timeout\"),\n )\n self._client = genai.Client(api_key=self.api_key, http_options=http_options)\n else:\n self._client = genai.Client(api_key=self.api_key)\n return self._client\n\n def _resolve_http_timeout(self) -> Optional[float]:\n \"\"\"Compute timeout override from shared custom timeout environment variables.\"\"\"\n\n timeouts: list[float] = []\n for env_var in [\n \"CUSTOM_CONNECT_TIMEOUT\",\n \"CUSTOM_READ_TIMEOUT\",\n \"CUSTOM_WRITE_TIMEOUT\",\n \"CUSTOM_POOL_TIMEOUT\",\n ]:\n raw_value = get_env(env_var)\n if raw_value:\n try:\n timeouts.append(float(raw_value))\n except (TypeError, ValueError):\n logger.warning(\"Invalid %s value '%s'; ignoring.\", env_var, raw_value)\n\n if timeouts:\n # Use the largest timeout to best approximate long-running requests\n resolved = max(timeouts)\n logger.debug(\"Using custom Gemini HTTP timeout: %ss\", resolved)\n return resolved\n\n return None\n\n # ------------------------------------------------------------------\n # Request execution\n # ------------------------------------------------------------------\n\n def generate_content(\n self,\n prompt: str,\n model_name: str,\n system_prompt: Optional[str] = None,\n temperature: float = 1.0,\n max_output_tokens: Optional[int] = None,\n thinking_mode: str = \"medium\",\n images: Optional[list[str]] = None,\n **kwargs,\n ) -> ModelResponse:\n \"\"\"\n Generate content using Gemini model.\n\n Args:\n prompt: The main user prompt/query to send to the model\n model_name: Canonical model name or its alias (e.g., \"gemini-2.5-pro\", \"flash\", \"pro\")\n system_prompt: Optional system instructions to prepend to the prompt for context/behavior\n temperature: Controls randomness in generation (0.0=deterministic, 1.0=creative), default 0.3\n max_output_tokens: Optional maximum number of tokens to generate in the response\n thinking_mode: Thinking budget level for models that support it (\"minimal\", \"low\", \"medium\", \"high\", \"max\"), default \"medium\"\n images: Optional list of image paths or data URLs to include with the prompt (for vision models)\n **kwargs: Additional keyword arguments (reserved for future use)\n\n Returns:\n ModelResponse: Contains the generated content, token usage stats, model metadata, and safety information\n \"\"\"\n # Validate parameters and fetch capabilities\n self.validate_parameters(model_name, temperature)\n capabilities = self.get_capabilities(model_name)\n capability_map = self.get_all_model_capabilities()\n\n resolved_model_name = self._resolve_model_name(model_name)\n\n # Prepare content parts (text and potentially images)\n parts = []\n\n # Add system and user prompts as text\n if system_prompt:\n full_prompt = f\"{system_prompt}\\n\\n{prompt}\"\n else:\n full_prompt = prompt\n\n parts.append({\"text\": full_prompt})\n\n # Add images if provided and model supports vision\n if images and capabilities.supports_images:\n for image_path in images:\n try:\n image_part = self._process_image(image_path)\n if image_part:\n parts.append(image_part)\n except Exception as e:\n logger.warning(f\"Failed to process image {image_path}: {e}\")\n # Continue with other images and text\n continue\n elif images and not capabilities.supports_images:\n logger.warning(f\"Model {resolved_model_name} does not support images, ignoring {len(images)} image(s)\")\n\n # Create contents structure\n contents = [{\"parts\": parts}]\n\n # Gemini 3 Pro Preview currently rejects medium thinking budgets; bump to high.\n effective_thinking_mode = thinking_mode\n if resolved_model_name == \"gemini-3-pro-preview\" and thinking_mode == \"medium\":\n logger.debug(\n \"Overriding thinking mode 'medium' with 'high' for %s due to launch limitation\",\n resolved_model_name,\n )\n effective_thinking_mode = \"high\"\n\n # Prepare generation config\n generation_config = types.GenerateContentConfig(\n temperature=temperature,\n candidate_count=1,\n )\n\n # Add max output tokens if specified\n if max_output_tokens:\n generation_config.max_output_tokens = max_output_tokens\n\n # Add thinking configuration for models that support it\n if capabilities.supports_extended_thinking and effective_thinking_mode in self.THINKING_BUDGETS:\n # Get model's max thinking tokens and calculate actual budget\n model_config = capability_map.get(resolved_model_name)\n if model_config and model_config.max_thinking_tokens > 0:\n max_thinking_tokens = model_config.max_thinking_tokens\n actual_thinking_budget = int(max_thinking_tokens * self.THINKING_BUDGETS[effective_thinking_mode])\n generation_config.thinking_config = types.ThinkingConfig(thinking_budget=actual_thinking_budget)\n\n # Retry logic with progressive delays\n max_retries = 4 # Total of 4 attempts\n retry_delays = [1, 3, 5, 8] # Progressive delays: 1s, 3s, 5s, 8s\n attempt_counter = {\"value\": 0}\n\n def _attempt() -> ModelResponse:\n attempt_counter[\"value\"] += 1\n response = self.client.models.generate_content(\n model=resolved_model_name,\n contents=contents,\n config=generation_config,\n )\n\n usage = self._extract_usage(response)\n\n finish_reason_str = \"UNKNOWN\"\n is_blocked_by_safety = False\n safety_feedback_details = None\n\n if response.candidates:\n candidate = response.candidates[0]\n\n try:\n finish_reason_enum = candidate.finish_reason\n if finish_reason_enum:\n try:\n finish_reason_str = finish_reason_enum.name\n except AttributeError:\n finish_reason_str = str(finish_reason_enum)\n else:\n finish_reason_str = \"STOP\"\n except AttributeError:\n finish_reason_str = \"STOP\"\n\n if not response.text:\n try:\n safety_ratings = candidate.safety_ratings\n if safety_ratings:\n for rating in safety_ratings:\n try:\n if rating.blocked:\n is_blocked_by_safety = True\n category_name = \"UNKNOWN\"\n probability_name = \"UNKNOWN\"\n\n try:\n category_name = rating.category.name\n except (AttributeError, TypeError):\n pass\n\n try:\n probability_name = rating.probability.name\n except (AttributeError, TypeError):\n pass\n\n safety_feedback_details = (\n f\"Category: {category_name}, Probability: {probability_name}\"\n )\n break\n except (AttributeError, TypeError):\n continue\n except (AttributeError, TypeError):\n pass\n\n elif response.candidates is not None and len(response.candidates) == 0:\n is_blocked_by_safety = True\n finish_reason_str = \"SAFETY\"\n safety_feedback_details = \"Prompt blocked, reason unavailable\"\n\n try:\n prompt_feedback = response.prompt_feedback\n if prompt_feedback and prompt_feedback.block_reason:\n try:\n block_reason_name = prompt_feedback.block_reason.name\n except AttributeError:\n block_reason_name = str(prompt_feedback.block_reason)\n safety_feedback_details = f\"Prompt blocked, reason: {block_reason_name}\"\n except (AttributeError, TypeError):\n pass\n\n return ModelResponse(\n content=response.text,\n usage=usage,\n model_name=resolved_model_name,\n friendly_name=\"Gemini\",\n provider=ProviderType.GOOGLE,\n metadata={\n \"thinking_mode\": effective_thinking_mode if capabilities.supports_extended_thinking else None,\n \"finish_reason\": finish_reason_str,\n \"is_blocked_by_safety\": is_blocked_by_safety,\n \"safety_feedback\": safety_feedback_details,\n },\n )\n\n try:\n return self._run_with_retries(\n operation=_attempt,\n max_attempts=max_retries,\n delays=retry_delays,\n log_prefix=f\"Gemini API ({resolved_model_name})\",\n )\n except Exception as exc:\n attempts = max(attempt_counter[\"value\"], 1)\n error_msg = (\n f\"Gemini API error for model {resolved_model_name} after {attempts} attempt\"\n f\"{'s' if attempts > 1 else ''}: {exc}\"\n )\n raise RuntimeError(error_msg) from exc\n\n def get_provider_type(self) -> ProviderType:\n \"\"\"Get the provider type.\"\"\"\n return ProviderType.GOOGLE\n\n def _extract_usage(self, response) -> dict[str, int]:\n \"\"\"Extract token usage from Gemini response.\"\"\"\n usage = {}\n\n # Try to extract usage metadata from response\n # Note: The actual structure depends on the SDK version and response format\n try:\n metadata = response.usage_metadata\n if metadata:\n # Extract token counts with explicit None checks\n input_tokens = None\n output_tokens = None\n\n try:\n value = metadata.prompt_token_count\n if value is not None:\n input_tokens = value\n usage[\"input_tokens\"] = value\n except (AttributeError, TypeError):\n pass\n\n try:\n value = metadata.candidates_token_count\n if value is not None:\n output_tokens = value\n usage[\"output_tokens\"] = value\n except (AttributeError, TypeError):\n pass\n\n # Calculate total only if both values are available and valid\n if input_tokens is not None and output_tokens is not None:\n usage[\"total_tokens\"] = input_tokens + output_tokens\n except (AttributeError, TypeError):\n # response doesn't have usage_metadata\n pass\n\n return usage\n\n def _is_error_retryable(self, error: Exception) -> bool:\n \"\"\"Determine if an error should be retried based on structured error codes.\n\n Uses Gemini API error structure instead of text pattern matching for reliability.\n\n Args:\n error: Exception from Gemini API call\n\n Returns:\n True if error should be retried, False otherwise\n \"\"\"\n error_str = str(error).lower()\n\n # Check for 429 errors first - these need special handling\n if \"429\" in error_str or \"quota\" in error_str or \"resource_exhausted\" in error_str:\n # For Gemini, check for specific non-retryable error indicators\n # These typically indicate permanent failures or quota/size limits\n non_retryable_indicators = [\n \"quota exceeded\",\n \"resource exhausted\",\n \"context length\",\n \"token limit\",\n \"request too large\",\n \"invalid request\",\n \"quota_exceeded\",\n \"resource_exhausted\",\n ]\n\n # Also check if this is a structured error from Gemini SDK\n try:\n # Try to access error details if available\n error_details = None\n try:\n error_details = error.details\n except AttributeError:\n try:\n error_details = error.reason\n except AttributeError:\n pass\n\n if error_details:\n error_details_str = str(error_details).lower()\n # Check for non-retryable error codes/reasons\n if any(indicator in error_details_str for indicator in non_retryable_indicators):\n logger.debug(f\"Non-retryable Gemini error: {error_details}\")\n return False\n except Exception:\n pass\n\n # Check main error string for non-retryable patterns\n if any(indicator in error_str for indicator in non_retryable_indicators):\n logger.debug(f\"Non-retryable Gemini error based on message: {error_str[:200]}...\")\n return False\n\n # If it's a 429/quota error but doesn't match non-retryable patterns, it might be retryable rate limiting\n logger.debug(f\"Retryable Gemini rate limiting error: {error_str[:100]}...\")\n return True\n\n # For non-429 errors, check if they're retryable\n retryable_indicators = [\n \"timeout\",\n \"connection\",\n \"network\",\n \"temporary\",\n \"unavailable\",\n \"retry\",\n \"internal error\",\n \"408\", # Request timeout\n \"500\", # Internal server error\n \"502\", # Bad gateway\n \"503\", # Service unavailable\n \"504\", # Gateway timeout\n \"ssl\", # SSL errors\n \"handshake\", # Handshake failures\n ]\n\n return any(indicator in error_str for indicator in retryable_indicators)\n\n def _process_image(self, image_path: str) -> Optional[dict]:\n \"\"\"Process an image for Gemini API.\"\"\"\n try:\n # Use base class validation\n image_bytes, mime_type = validate_image(image_path)\n\n # For data URLs, extract the base64 data directly\n if image_path.startswith(\"data:\"):\n # Extract base64 data from data URL\n _, data = image_path.split(\",\", 1)\n return {\"inline_data\": {\"mime_type\": mime_type, \"data\": data}}\n else:\n # For file paths, encode the bytes\n image_data = base64.b64encode(image_bytes).decode()\n return {\"inline_data\": {\"mime_type\": mime_type, \"data\": image_data}}\n\n except ValueError as e:\n logger.warning(str(e))\n return None\n except Exception as e:\n logger.error(f\"Error processing image {image_path}: {e}\")\n return None\n\n def get_preferred_model(self, category: \"ToolModelCategory\", allowed_models: list[str]) -> Optional[str]:\n \"\"\"Get Gemini's preferred model for a given category from allowed models.\n\n Args:\n category: The tool category requiring a model\n allowed_models: Pre-filtered list of models allowed by restrictions\n\n Returns:\n Preferred model name or None\n \"\"\"\n from tools.models import ToolModelCategory\n\n if not allowed_models:\n return None\n\n capability_map = self.get_all_model_capabilities()\n\n # Helper to find best model from candidates\n def find_best(candidates: list[str]) -> Optional[str]:\n \"\"\"Return best model from candidates (sorted for consistency).\"\"\"\n return sorted(candidates, reverse=True)[0] if candidates else None\n\n if category == ToolModelCategory.EXTENDED_REASONING:\n # For extended reasoning, prefer models with thinking support\n # First try Pro models that support thinking\n pro_thinking = [\n m\n for m in allowed_models\n if \"pro\" in m and m in capability_map and capability_map[m].supports_extended_thinking\n ]\n if pro_thinking:\n return find_best(pro_thinking)\n\n # Then any model that supports thinking\n any_thinking = [\n m for m in allowed_models if m in capability_map and capability_map[m].supports_extended_thinking\n ]\n if any_thinking:\n return find_best(any_thinking)\n\n # Finally, just prefer Pro models even without thinking\n pro_models = [m for m in allowed_models if \"pro\" in m]\n if pro_models:\n return find_best(pro_models)\n\n elif category == ToolModelCategory.FAST_RESPONSE:\n # Prefer Flash models for speed\n flash_models = [m for m in allowed_models if \"flash\" in m]\n if flash_models:\n return find_best(flash_models)\n\n # Default for BALANCED or as fallback\n # Prefer Flash for balanced use, then Pro, then anything\n flash_models = [m for m in allowed_models if \"flash\" in m]\n if flash_models:\n return find_best(flash_models)\n\n pro_models = [m for m in allowed_models if \"pro\" in m]\n if pro_models:\n return find_best(pro_models)\n\n # Ultimate fallback to best available model\n return find_best(allowed_models)\n\n\n# Load registry data at import time for registry consumers\nGeminiModelProvider._ensure_registry()\n" }, { "path": "providers/openai.py", "content": "\"\"\"OpenAI model provider implementation.\"\"\"\n\nimport logging\nfrom typing import TYPE_CHECKING, ClassVar, Optional\n\nif TYPE_CHECKING:\n from tools.models import ToolModelCategory\n\nfrom .openai_compatible import OpenAICompatibleProvider\nfrom .registries.openai import OpenAIModelRegistry\nfrom .registry_provider_mixin import RegistryBackedProviderMixin\nfrom .shared import ModelCapabilities, ProviderType\n\nlogger = logging.getLogger(__name__)\n\n\nclass OpenAIModelProvider(RegistryBackedProviderMixin, OpenAICompatibleProvider):\n \"\"\"Implementation that talks to api.openai.com using rich model metadata.\n\n In addition to the built-in catalogue, the provider can surface models\n defined in ``conf/custom_models.json`` (for organisations running their own\n OpenAI-compatible gateways) while still respecting restriction policies.\n \"\"\"\n\n REGISTRY_CLASS = OpenAIModelRegistry\n MODEL_CAPABILITIES: ClassVar[dict[str, ModelCapabilities]] = {}\n\n def __init__(self, api_key: str, **kwargs):\n \"\"\"Initialize OpenAI provider with API key.\"\"\"\n self._ensure_registry()\n # Set default OpenAI base URL, allow override for regions/custom endpoints\n kwargs.setdefault(\"base_url\", \"https://api.openai.com/v1\")\n super().__init__(api_key, **kwargs)\n self._invalidate_capability_cache()\n\n # ------------------------------------------------------------------\n # Capability surface\n # ------------------------------------------------------------------\n\n def _lookup_capabilities(\n self,\n canonical_name: str,\n requested_name: Optional[str] = None,\n ) -> Optional[ModelCapabilities]:\n \"\"\"Look up OpenAI capabilities from built-ins or the custom registry.\"\"\"\n\n self._ensure_registry()\n builtin = super()._lookup_capabilities(canonical_name, requested_name)\n if builtin is not None:\n return builtin\n\n try:\n from .registries.openrouter import OpenRouterModelRegistry\n\n registry = OpenRouterModelRegistry()\n config = registry.get_model_config(canonical_name)\n\n if config and config.provider == ProviderType.OPENAI:\n return config\n\n except Exception as exc: # pragma: no cover - registry failures are non-critical\n logger.debug(f\"Could not resolve custom OpenAI model '{canonical_name}': {exc}\")\n\n return None\n\n def _finalise_capabilities(\n self,\n capabilities: ModelCapabilities,\n canonical_name: str,\n requested_name: str,\n ) -> ModelCapabilities:\n \"\"\"Ensure registry-sourced models report the correct provider type.\"\"\"\n\n if capabilities.provider != ProviderType.OPENAI:\n capabilities.provider = ProviderType.OPENAI\n return capabilities\n\n def _raise_unsupported_model(self, model_name: str) -> None:\n raise ValueError(f\"Unsupported OpenAI model: {model_name}\")\n\n # ------------------------------------------------------------------\n # Provider identity\n # ------------------------------------------------------------------\n\n def get_provider_type(self) -> ProviderType:\n \"\"\"Get the provider type.\"\"\"\n return ProviderType.OPENAI\n\n # ------------------------------------------------------------------\n # Provider preferences\n # ------------------------------------------------------------------\n\n def get_preferred_model(self, category: \"ToolModelCategory\", allowed_models: list[str]) -> Optional[str]:\n \"\"\"Get OpenAI's preferred model for a given category from allowed models.\n\n Args:\n category: The tool category requiring a model\n allowed_models: Pre-filtered list of models allowed by restrictions\n\n Returns:\n Preferred model name or None\n \"\"\"\n from tools.models import ToolModelCategory\n\n if not allowed_models:\n return None\n\n # Helper to find first available from preference list\n def find_first(preferences: list[str]) -> Optional[str]:\n \"\"\"Return first available model from preference list.\"\"\"\n for model in preferences:\n if model in allowed_models:\n return model\n return None\n\n if category == ToolModelCategory.EXTENDED_REASONING:\n # Prefer models with extended thinking support\n # GPT-5.1 Codex first for coding tasks\n preferred = find_first(\n [\n \"gpt-5.1-codex\",\n \"gpt-5.2\",\n \"gpt-5-codex\",\n \"gpt-5.2-pro\",\n \"o3-pro\",\n \"gpt-5\",\n \"o3\",\n ]\n )\n return preferred if preferred else allowed_models[0]\n\n elif category == ToolModelCategory.FAST_RESPONSE:\n # Prefer fast, cost-efficient models\n # GPT-5.2 models for speed, GPT-5.1-Codex after (premium pricing but cached)\n preferred = find_first(\n [\n \"gpt-5.2\",\n \"gpt-5.1-codex-mini\",\n \"gpt-5\",\n \"gpt-5-mini\",\n \"gpt-5-codex\",\n \"o4-mini\",\n \"o3-mini\",\n ]\n )\n return preferred if preferred else allowed_models[0]\n\n else: # BALANCED or default\n # Prefer balanced performance/cost models\n # Include GPT-5.2 family for latest capabilities\n preferred = find_first(\n [\n \"gpt-5.2\",\n \"gpt-5.1-codex\",\n \"gpt-5\",\n \"gpt-5-codex\",\n \"gpt-5.2-pro\",\n \"gpt-5-mini\",\n \"o4-mini\",\n \"o3-mini\",\n ]\n )\n return preferred if preferred else allowed_models[0]\n\n\n# Load registry data at import time so dependent providers (Azure) can reuse it\nOpenAIModelProvider._ensure_registry()\n" }, { "path": "providers/openai_compatible.py", "content": "\"\"\"Base class for OpenAI-compatible API providers.\"\"\"\n\nimport copy\nimport ipaddress\nimport logging\nfrom typing import Optional\nfrom urllib.parse import urlparse\n\nfrom openai import OpenAI\n\nfrom utils.env import get_env, suppress_env_vars\nfrom utils.image_utils import validate_image\n\nfrom .base import ModelProvider\nfrom .shared import (\n ModelCapabilities,\n ModelResponse,\n ProviderType,\n)\n\n\nclass OpenAICompatibleProvider(ModelProvider):\n \"\"\"Shared implementation for OpenAI API lookalikes.\n\n The class owns HTTP client configuration (timeouts, proxy hardening,\n custom headers) and normalises the OpenAI SDK responses into\n :class:`~providers.shared.ModelResponse`. Concrete subclasses only need to\n provide capability metadata and any provider-specific request tweaks.\n \"\"\"\n\n DEFAULT_HEADERS = {}\n FRIENDLY_NAME = \"OpenAI Compatible\"\n\n def __init__(self, api_key: str, base_url: str = None, **kwargs):\n \"\"\"Initialize the provider with API key and optional base URL.\n\n Args:\n api_key: API key for authentication\n base_url: Base URL for the API endpoint\n **kwargs: Additional configuration options including timeout\n \"\"\"\n self._allowed_alias_cache: dict[str, str] = {}\n super().__init__(api_key, **kwargs)\n self._client = None\n self.base_url = base_url\n self.organization = kwargs.get(\"organization\")\n self.allowed_models = self._parse_allowed_models()\n\n # Configure timeouts - especially important for custom/local endpoints\n self.timeout_config = self._configure_timeouts(**kwargs)\n\n # Validate base URL for security\n if self.base_url:\n self._validate_base_url()\n\n # Warn if using external URL without authentication\n if self.base_url and not self._is_localhost_url() and not api_key:\n logging.warning(\n f\"Using external URL '{self.base_url}' without API key. \"\n \"This may be insecure. Consider setting an API key for authentication.\"\n )\n\n def _ensure_model_allowed(\n self,\n capabilities: ModelCapabilities,\n canonical_name: str,\n requested_name: str,\n ) -> None:\n \"\"\"Respect provider-specific allowlists before default restriction checks.\"\"\"\n\n super()._ensure_model_allowed(capabilities, canonical_name, requested_name)\n\n if self.allowed_models is not None:\n requested = requested_name.lower()\n canonical = canonical_name.lower()\n\n if requested not in self.allowed_models and canonical not in self.allowed_models:\n allowed = False\n for allowed_entry in list(self.allowed_models):\n normalized_resolved = self._allowed_alias_cache.get(allowed_entry)\n if normalized_resolved is None:\n try:\n resolved_name = self._resolve_model_name(allowed_entry)\n except Exception:\n continue\n\n if not resolved_name:\n continue\n\n normalized_resolved = resolved_name.lower()\n self._allowed_alias_cache[allowed_entry] = normalized_resolved\n\n if normalized_resolved == canonical:\n # Canonical match discovered via alias resolution – mark as allowed and\n # memoise the canonical entry for future lookups.\n allowed = True\n self._allowed_alias_cache[canonical] = canonical\n self.allowed_models.add(canonical)\n break\n\n if not allowed:\n raise ValueError(\n f\"Model '{requested_name}' is not allowed by restriction policy. Allowed models: {sorted(self.allowed_models)}\"\n )\n\n def _parse_allowed_models(self) -> Optional[set[str]]:\n \"\"\"Parse allowed models from environment variable.\n\n Returns:\n Set of allowed model names (lowercase) or None if not configured\n \"\"\"\n # Get provider-specific allowed models\n provider_type = self.get_provider_type().value.upper()\n env_var = f\"{provider_type}_ALLOWED_MODELS\"\n models_str = get_env(env_var, \"\") or \"\"\n\n if models_str:\n # Parse and normalize to lowercase for case-insensitive comparison\n models = {m.strip().lower() for m in models_str.split(\",\") if m.strip()}\n if models:\n logging.info(f\"Configured allowed models for {self.FRIENDLY_NAME}: {sorted(models)}\")\n self._allowed_alias_cache = {}\n return models\n\n # Log info if no allow-list configured for proxy providers\n if self.get_provider_type() not in [ProviderType.GOOGLE, ProviderType.OPENAI]:\n logging.info(\n f\"Model allow-list not configured for {self.FRIENDLY_NAME} - all models permitted. \"\n f\"To restrict access, set {env_var} with comma-separated model names.\"\n )\n\n return None\n\n def _configure_timeouts(self, **kwargs):\n \"\"\"Configure timeout settings based on provider type and custom settings.\n\n Custom URLs and local models often need longer timeouts due to:\n - Network latency on local networks\n - Extended thinking models taking longer to respond\n - Local inference being slower than cloud APIs\n\n Returns:\n httpx.Timeout object with appropriate timeout settings\n \"\"\"\n import httpx\n\n # Default timeouts - more generous for custom/local endpoints\n default_connect = 30.0 # 30 seconds for connection (vs OpenAI's 5s)\n default_read = 600.0 # 10 minutes for reading (same as OpenAI default)\n default_write = 600.0 # 10 minutes for writing\n default_pool = 600.0 # 10 minutes for pool\n\n # For custom/local URLs, use even longer timeouts\n if self.base_url and self._is_localhost_url():\n default_connect = 60.0 # 1 minute for local connections\n default_read = 1800.0 # 30 minutes for local models (extended thinking)\n default_write = 1800.0 # 30 minutes for local models\n default_pool = 1800.0 # 30 minutes for local models\n logging.info(f\"Using extended timeouts for local endpoint: {self.base_url}\")\n elif self.base_url:\n default_connect = 45.0 # 45 seconds for custom remote endpoints\n default_read = 900.0 # 15 minutes for custom remote endpoints\n default_write = 900.0 # 15 minutes for custom remote endpoints\n default_pool = 900.0 # 15 minutes for custom remote endpoints\n logging.info(f\"Using extended timeouts for custom endpoint: {self.base_url}\")\n\n # Allow override via kwargs or environment variables in future, for now...\n connect_timeout = kwargs.get(\"connect_timeout\")\n if connect_timeout is None:\n connect_timeout_raw = get_env(\"CUSTOM_CONNECT_TIMEOUT\")\n connect_timeout = float(connect_timeout_raw) if connect_timeout_raw is not None else float(default_connect)\n\n read_timeout = kwargs.get(\"read_timeout\")\n if read_timeout is None:\n read_timeout_raw = get_env(\"CUSTOM_READ_TIMEOUT\")\n read_timeout = float(read_timeout_raw) if read_timeout_raw is not None else float(default_read)\n\n write_timeout = kwargs.get(\"write_timeout\")\n if write_timeout is None:\n write_timeout_raw = get_env(\"CUSTOM_WRITE_TIMEOUT\")\n write_timeout = float(write_timeout_raw) if write_timeout_raw is not None else float(default_write)\n\n pool_timeout = kwargs.get(\"pool_timeout\")\n if pool_timeout is None:\n pool_timeout_raw = get_env(\"CUSTOM_POOL_TIMEOUT\")\n pool_timeout = float(pool_timeout_raw) if pool_timeout_raw is not None else float(default_pool)\n\n timeout = httpx.Timeout(connect=connect_timeout, read=read_timeout, write=write_timeout, pool=pool_timeout)\n\n logging.debug(\n f\"Configured timeouts - Connect: {connect_timeout}s, Read: {read_timeout}s, \"\n f\"Write: {write_timeout}s, Pool: {pool_timeout}s\"\n )\n\n return timeout\n\n def _is_localhost_url(self) -> bool:\n \"\"\"Check if the base URL points to localhost or local network.\n\n Returns:\n True if URL is localhost or local network, False otherwise\n \"\"\"\n if not self.base_url:\n return False\n\n try:\n parsed = urlparse(self.base_url)\n hostname = parsed.hostname\n\n # Check for common localhost patterns\n if hostname in [\"localhost\", \"127.0.0.1\", \"::1\"]:\n return True\n\n # Check for private network ranges (local network)\n if hostname:\n try:\n ip = ipaddress.ip_address(hostname)\n return ip.is_private or ip.is_loopback\n except ValueError:\n # Not an IP address, might be a hostname\n pass\n\n return False\n except Exception:\n return False\n\n def _validate_base_url(self) -> None:\n \"\"\"Validate base URL for security (SSRF protection).\n\n Raises:\n ValueError: If URL is invalid or potentially unsafe\n \"\"\"\n if not self.base_url:\n return\n\n try:\n parsed = urlparse(self.base_url)\n\n # Check URL scheme - only allow http/https\n if parsed.scheme not in (\"http\", \"https\"):\n raise ValueError(f\"Invalid URL scheme: {parsed.scheme}. Only http/https allowed.\")\n\n # Check hostname exists\n if not parsed.hostname:\n raise ValueError(\"URL must include a hostname\")\n\n # Check port is valid (if specified)\n port = parsed.port\n if port is not None and (port < 1 or port > 65535):\n raise ValueError(f\"Invalid port number: {port}. Must be between 1 and 65535.\")\n except Exception as e:\n if isinstance(e, ValueError):\n raise\n raise ValueError(f\"Invalid base URL '{self.base_url}': {str(e)}\")\n\n @property\n def client(self):\n \"\"\"Lazy initialization of OpenAI client with security checks and timeout configuration.\"\"\"\n if self._client is None:\n import httpx\n\n proxy_env_vars = [\"HTTP_PROXY\", \"HTTPS_PROXY\", \"ALL_PROXY\", \"http_proxy\", \"https_proxy\", \"all_proxy\"]\n\n with suppress_env_vars(*proxy_env_vars):\n try:\n # Create a custom httpx client that explicitly avoids proxy parameters\n timeout_config = (\n self.timeout_config\n if hasattr(self, \"timeout_config\") and self.timeout_config\n else httpx.Timeout(30.0)\n )\n\n # Create httpx client with minimal config to avoid proxy conflicts\n # Note: proxies parameter was removed in httpx 0.28.0\n # Check for test transport injection\n if hasattr(self, \"_test_transport\"):\n # Use custom transport for testing (HTTP recording/replay)\n http_client = httpx.Client(\n transport=self._test_transport,\n timeout=timeout_config,\n follow_redirects=True,\n )\n else:\n # Normal production client\n http_client = httpx.Client(\n timeout=timeout_config,\n follow_redirects=True,\n )\n\n # Keep client initialization minimal to avoid proxy parameter conflicts\n client_kwargs = {\n \"api_key\": self.api_key,\n \"http_client\": http_client,\n }\n\n if self.base_url:\n client_kwargs[\"base_url\"] = self.base_url\n\n if self.organization:\n client_kwargs[\"organization\"] = self.organization\n\n # Add default headers if any\n if self.DEFAULT_HEADERS:\n client_kwargs[\"default_headers\"] = self.DEFAULT_HEADERS.copy()\n\n logging.debug(\n \"OpenAI client initialized with custom httpx client and timeout: %s\",\n timeout_config,\n )\n\n # Create OpenAI client with custom httpx client\n self._client = OpenAI(**client_kwargs)\n\n except Exception as e:\n # If all else fails, try absolute minimal client without custom httpx\n logging.warning(\n \"Failed to create client with custom httpx, falling back to minimal config: %s\",\n e,\n )\n try:\n minimal_kwargs = {\"api_key\": self.api_key}\n if self.base_url:\n minimal_kwargs[\"base_url\"] = self.base_url\n self._client = OpenAI(**minimal_kwargs)\n except Exception as fallback_error:\n logging.error(\"Even minimal OpenAI client creation failed: %s\", fallback_error)\n raise\n\n return self._client\n\n def _sanitize_for_logging(self, params: dict) -> dict:\n \"\"\"Sanitize sensitive data from parameters before logging.\n\n Args:\n params: Dictionary of API parameters\n\n Returns:\n dict: Sanitized copy of parameters safe for logging\n \"\"\"\n sanitized = copy.deepcopy(params)\n\n # Sanitize messages content\n if \"input\" in sanitized:\n for msg in sanitized.get(\"input\", []):\n if isinstance(msg, dict) and \"content\" in msg:\n for content_item in msg.get(\"content\", []):\n if isinstance(content_item, dict) and \"text\" in content_item:\n # Truncate long text and add ellipsis\n text = content_item[\"text\"]\n if len(text) > 100:\n content_item[\"text\"] = text[:100] + \"... [truncated]\"\n\n # Remove any API keys that might be in headers/auth\n sanitized.pop(\"api_key\", None)\n sanitized.pop(\"authorization\", None)\n\n return sanitized\n\n def _safe_extract_output_text(self, response) -> str:\n \"\"\"Safely extract output_text from o3-pro response with validation.\n\n Args:\n response: Response object from OpenAI SDK\n\n Returns:\n str: The output text content\n\n Raises:\n ValueError: If output_text is missing, None, or not a string\n \"\"\"\n logging.debug(f\"Response object type: {type(response)}\")\n logging.debug(f\"Response attributes: {dir(response)}\")\n\n if not hasattr(response, \"output_text\"):\n raise ValueError(f\"o3-pro response missing output_text field. Response type: {type(response).__name__}\")\n\n content = response.output_text\n logging.debug(f\"Extracted output_text: '{content}' (type: {type(content)})\")\n\n if content is None:\n raise ValueError(\"o3-pro returned None for output_text\")\n\n if not isinstance(content, str):\n raise ValueError(f\"o3-pro output_text is not a string. Got type: {type(content).__name__}\")\n\n return content\n\n def _generate_with_responses_endpoint(\n self,\n model_name: str,\n messages: list,\n temperature: float,\n max_output_tokens: Optional[int] = None,\n capabilities: Optional[ModelCapabilities] = None,\n **kwargs,\n ) -> ModelResponse:\n \"\"\"Generate content using the /v1/responses endpoint for reasoning models.\"\"\"\n # Convert messages to the correct format for responses endpoint\n input_messages = []\n\n for message in messages:\n role = message.get(\"role\", \"\")\n content = message.get(\"content\", \"\")\n\n if role == \"system\":\n # For o3-pro, system messages should be handled carefully to avoid policy violations\n # Instead of prefixing with \"System:\", we'll include the system content naturally\n input_messages.append({\"role\": \"user\", \"content\": [{\"type\": \"input_text\", \"text\": content}]})\n elif role == \"user\":\n input_messages.append({\"role\": \"user\", \"content\": [{\"type\": \"input_text\", \"text\": content}]})\n elif role == \"assistant\":\n input_messages.append({\"role\": \"assistant\", \"content\": [{\"type\": \"output_text\", \"text\": content}]})\n\n # Prepare completion parameters for responses endpoint\n # Based on OpenAI documentation, use nested reasoning object for responses endpoint\n effort = \"medium\"\n if capabilities and capabilities.default_reasoning_effort:\n effort = capabilities.default_reasoning_effort\n\n completion_params = {\n \"model\": model_name,\n \"input\": input_messages,\n \"reasoning\": {\"effort\": effort},\n }\n\n # Only include store parameter for providers that support it.\n # OpenRouter's /responses endpoint rejects store:true via Zod validation (Issue #348).\n # This is an endpoint-level limitation, not model-specific, so we omit for all\n # OpenRouter /responses calls. If OpenRouter later supports store, revisit this logic.\n if self.get_provider_type() != ProviderType.OPENROUTER:\n completion_params[\"store\"] = True\n else:\n logging.debug(f\"Omitting 'store' parameter for OpenRouter provider (model: {model_name})\")\n\n # Add max tokens if specified (using max_completion_tokens for responses endpoint)\n if max_output_tokens:\n completion_params[\"max_completion_tokens\"] = max_output_tokens\n\n # For responses endpoint, we only add parameters that are explicitly supported\n # Remove unsupported chat completion parameters that may cause API errors\n\n # Retry logic with progressive delays\n max_retries = 4\n retry_delays = [1, 3, 5, 8]\n attempt_counter = {\"value\": 0}\n\n def _attempt() -> ModelResponse:\n attempt_counter[\"value\"] += 1\n import json\n\n sanitized_params = self._sanitize_for_logging(completion_params)\n logging.info(\n f\"o3-pro API request (sanitized): {json.dumps(sanitized_params, indent=2, ensure_ascii=False)}\"\n )\n\n response = self.client.responses.create(**completion_params)\n\n content = self._safe_extract_output_text(response)\n\n usage = None\n if hasattr(response, \"usage\"):\n usage = self._extract_usage(response)\n elif hasattr(response, \"input_tokens\") and hasattr(response, \"output_tokens\"):\n input_tokens = getattr(response, \"input_tokens\", 0) or 0\n output_tokens = getattr(response, \"output_tokens\", 0) or 0\n usage = {\n \"input_tokens\": input_tokens,\n \"output_tokens\": output_tokens,\n \"total_tokens\": input_tokens + output_tokens,\n }\n\n return ModelResponse(\n content=content,\n usage=usage,\n model_name=model_name,\n friendly_name=self.FRIENDLY_NAME,\n provider=self.get_provider_type(),\n metadata={\n \"model\": getattr(response, \"model\", model_name),\n \"id\": getattr(response, \"id\", \"\"),\n \"created\": getattr(response, \"created_at\", 0),\n \"endpoint\": \"responses\",\n },\n )\n\n try:\n return self._run_with_retries(\n operation=_attempt,\n max_attempts=max_retries,\n delays=retry_delays,\n log_prefix=\"responses endpoint\",\n )\n except Exception as exc:\n attempts = max(attempt_counter[\"value\"], 1)\n error_msg = f\"responses endpoint error after {attempts} attempt{'s' if attempts > 1 else ''}: {exc}\"\n logging.error(error_msg)\n raise RuntimeError(error_msg) from exc\n\n def generate_content(\n self,\n prompt: str,\n model_name: str,\n system_prompt: Optional[str] = None,\n temperature: float = 0.3,\n max_output_tokens: Optional[int] = None,\n images: Optional[list[str]] = None,\n **kwargs,\n ) -> ModelResponse:\n \"\"\"Generate content using the OpenAI-compatible API.\n\n Args:\n prompt: User prompt to send to the model\n model_name: Canonical model name or its alias\n system_prompt: Optional system prompt for model behavior\n temperature: Sampling temperature\n max_output_tokens: Maximum tokens to generate\n images: Optional list of image paths or data URLs to include with the prompt (for vision models)\n **kwargs: Additional provider-specific parameters\n\n Returns:\n ModelResponse with generated content and metadata\n \"\"\"\n # Validate model name against allow-list\n if not self.validate_model_name(model_name):\n raise ValueError(f\"Model '{model_name}' not in allowed models list. Allowed models: {self.allowed_models}\")\n\n capabilities: Optional[ModelCapabilities]\n try:\n capabilities = self.get_capabilities(model_name)\n except Exception as exc:\n logging.debug(f\"Falling back to generic capabilities for {model_name}: {exc}\")\n capabilities = None\n\n # Get effective temperature for this model from capabilities when available\n if capabilities:\n effective_temperature = capabilities.get_effective_temperature(temperature)\n if effective_temperature is not None and effective_temperature != temperature:\n logging.debug(\n f\"Adjusting temperature from {temperature} to {effective_temperature} for model {model_name}\"\n )\n else:\n effective_temperature = temperature\n\n # Only validate if temperature is not None (meaning the model supports it)\n if effective_temperature is not None:\n # Validate parameters with the effective temperature\n self.validate_parameters(model_name, effective_temperature)\n\n # Resolve to canonical model name\n resolved_model = self._resolve_model_name(model_name)\n\n # Prepare messages\n messages = []\n if system_prompt:\n messages.append({\"role\": \"system\", \"content\": system_prompt})\n\n # Prepare user message with text and potentially images\n user_content = []\n user_content.append({\"type\": \"text\", \"text\": prompt})\n\n # Add images if provided and model supports vision\n if images and capabilities and capabilities.supports_images:\n for image_path in images:\n try:\n image_content = self._process_image(image_path)\n if image_content:\n user_content.append(image_content)\n except Exception as e:\n logging.warning(f\"Failed to process image {image_path}: {e}\")\n # Continue with other images and text\n continue\n elif images and (not capabilities or not capabilities.supports_images):\n logging.warning(f\"Model {resolved_model} does not support images, ignoring {len(images)} image(s)\")\n\n # Add user message\n if len(user_content) == 1:\n # Only text content, use simple string format for compatibility\n messages.append({\"role\": \"user\", \"content\": prompt})\n else:\n # Text + images, use content array format\n messages.append({\"role\": \"user\", \"content\": user_content})\n\n # Prepare completion parameters\n # Always disable streaming for OpenRouter\n # MCP doesn't use streaming, and this avoids issues with O3 model access\n completion_params = {\n \"model\": resolved_model,\n \"messages\": messages,\n \"stream\": False,\n }\n\n # Use the effective temperature we calculated earlier\n supports_sampling = effective_temperature is not None\n\n if supports_sampling:\n completion_params[\"temperature\"] = effective_temperature\n\n # Add max tokens if specified and model supports it\n # O3/O4 models that don't support temperature also don't support max_tokens\n if max_output_tokens and supports_sampling:\n completion_params[\"max_tokens\"] = max_output_tokens\n\n # Add any additional OpenAI-specific parameters\n # Use capabilities to filter parameters for reasoning models\n for key, value in kwargs.items():\n if key in [\"top_p\", \"frequency_penalty\", \"presence_penalty\", \"seed\", \"stop\", \"stream\"]:\n # Reasoning models (those that don't support temperature) also don't support these parameters\n if not supports_sampling and key in [\"top_p\", \"frequency_penalty\", \"presence_penalty\", \"stream\"]:\n continue # Skip unsupported parameters for reasoning models\n completion_params[key] = value\n\n # Check if this model needs the Responses API endpoint\n # Prefer capability metadata; fall back to static map when capabilities unavailable\n use_responses_api = False\n if capabilities is not None:\n use_responses_api = getattr(capabilities, \"use_openai_response_api\", False)\n else:\n static_capabilities = self.get_all_model_capabilities().get(resolved_model)\n if static_capabilities is not None:\n use_responses_api = getattr(static_capabilities, \"use_openai_response_api\", False)\n\n if use_responses_api:\n # These models require the /v1/responses endpoint for stateful context\n # If it fails, we should not fall back to chat/completions\n return self._generate_with_responses_endpoint(\n model_name=resolved_model,\n messages=messages,\n temperature=temperature,\n max_output_tokens=max_output_tokens,\n capabilities=capabilities,\n **kwargs,\n )\n\n # Retry logic with progressive delays\n max_retries = 4 # Total of 4 attempts\n retry_delays = [1, 3, 5, 8] # Progressive delays: 1s, 3s, 5s, 8s\n attempt_counter = {\"value\": 0}\n\n def _attempt() -> ModelResponse:\n attempt_counter[\"value\"] += 1\n response = self.client.chat.completions.create(**completion_params)\n\n content = response.choices[0].message.content\n usage = self._extract_usage(response)\n\n return ModelResponse(\n content=content,\n usage=usage,\n model_name=resolved_model,\n friendly_name=self.FRIENDLY_NAME,\n provider=self.get_provider_type(),\n metadata={\n \"finish_reason\": response.choices[0].finish_reason,\n \"model\": response.model,\n \"id\": response.id,\n \"created\": response.created,\n },\n )\n\n try:\n return self._run_with_retries(\n operation=_attempt,\n max_attempts=max_retries,\n delays=retry_delays,\n log_prefix=f\"{self.FRIENDLY_NAME} API ({resolved_model})\",\n )\n except Exception as exc:\n attempts = max(attempt_counter[\"value\"], 1)\n error_msg = (\n f\"{self.FRIENDLY_NAME} API error for model {resolved_model} after {attempts} attempt\"\n f\"{'s' if attempts > 1 else ''}: {exc}\"\n )\n logging.error(error_msg)\n raise RuntimeError(error_msg) from exc\n\n def validate_parameters(self, model_name: str, temperature: float, **kwargs) -> None:\n \"\"\"Validate model parameters.\n\n For proxy providers, this may use generic capabilities.\n\n Args:\n model_name: Canonical model name or its alias\n temperature: Temperature to validate\n **kwargs: Additional parameters to validate\n \"\"\"\n try:\n capabilities = self.get_capabilities(model_name)\n\n # Check if we're using generic capabilities\n if hasattr(capabilities, \"_is_generic\"):\n logging.debug(\n f\"Using generic parameter validation for {model_name}. Actual model constraints may differ.\"\n )\n\n # Validate temperature using parent class method\n super().validate_parameters(model_name, temperature, **kwargs)\n\n except Exception as e:\n # For proxy providers, we might not have accurate capabilities\n # Log warning but don't fail\n logging.warning(f\"Parameter validation limited for {model_name}: {e}\")\n\n def _extract_usage(self, response) -> dict[str, int]:\n \"\"\"Extract token usage from OpenAI response.\n\n Args:\n response: OpenAI API response object\n\n Returns:\n Dictionary with usage statistics\n \"\"\"\n usage = {}\n\n if hasattr(response, \"usage\") and response.usage:\n # Safely extract token counts with None handling\n usage[\"input_tokens\"] = getattr(response.usage, \"prompt_tokens\", 0) or 0\n usage[\"output_tokens\"] = getattr(response.usage, \"completion_tokens\", 0) or 0\n usage[\"total_tokens\"] = getattr(response.usage, \"total_tokens\", 0) or 0\n\n return usage\n\n def count_tokens(self, text: str, model_name: str) -> int:\n \"\"\"Count tokens using OpenAI-compatible tokenizer tables when available.\"\"\"\n\n resolved_model = self._resolve_model_name(model_name)\n\n try:\n import tiktoken\n\n try:\n encoding = tiktoken.encoding_for_model(resolved_model)\n except KeyError:\n encoding = tiktoken.get_encoding(\"cl100k_base\")\n\n return len(encoding.encode(text))\n\n except (ImportError, Exception) as exc:\n logging.debug(\"tiktoken unavailable for %s: %s\", resolved_model, exc)\n\n return super().count_tokens(text, model_name)\n\n def _is_error_retryable(self, error: Exception) -> bool:\n \"\"\"Determine if an error should be retried based on structured error codes.\n\n Uses OpenAI API error structure instead of text pattern matching for reliability.\n\n Args:\n error: Exception from OpenAI API call\n\n Returns:\n True if error should be retried, False otherwise\n \"\"\"\n error_str = str(error).lower()\n\n # Check for 429 errors first - these need special handling\n if \"429\" in error_str:\n # Try to extract structured error information\n error_type = None\n error_code = None\n\n # Parse structured error from OpenAI API response\n # Format: \"Error code: 429 - {'error': {'type': 'tokens', 'code': 'rate_limit_exceeded', ...}}\"\n try:\n import ast\n import json\n import re\n\n # Extract JSON part from error string using regex\n # Look for pattern: {...} (from first { to last })\n json_match = re.search(r\"\\{.*\\}\", str(error))\n if json_match:\n json_like_str = json_match.group(0)\n\n # First try: parse as Python literal (handles single quotes safely)\n try:\n error_data = ast.literal_eval(json_like_str)\n except (ValueError, SyntaxError):\n # Fallback: try JSON parsing with simple quote replacement\n # (for cases where it's already valid JSON or simple replacements work)\n json_str = json_like_str.replace(\"'\", '\"')\n error_data = json.loads(json_str)\n\n if \"error\" in error_data:\n error_info = error_data[\"error\"]\n error_type = error_info.get(\"type\")\n error_code = error_info.get(\"code\")\n\n except (json.JSONDecodeError, ValueError, SyntaxError, AttributeError):\n # Fall back to checking hasattr for OpenAI SDK exception objects\n if hasattr(error, \"response\") and hasattr(error.response, \"json\"):\n try:\n response_data = error.response.json()\n if \"error\" in response_data:\n error_info = response_data[\"error\"]\n error_type = error_info.get(\"type\")\n error_code = error_info.get(\"code\")\n except Exception:\n pass\n\n # Determine if 429 is retryable based on structured error codes\n if error_type == \"tokens\":\n # Token-related 429s are typically non-retryable (request too large)\n logging.debug(f\"Non-retryable 429: token-related error (type={error_type}, code={error_code})\")\n return False\n elif error_code in [\"invalid_request_error\", \"context_length_exceeded\"]:\n # These are permanent failures\n logging.debug(f\"Non-retryable 429: permanent failure (type={error_type}, code={error_code})\")\n return False\n else:\n # Other 429s (like requests per minute) are retryable\n logging.debug(f\"Retryable 429: rate limiting (type={error_type}, code={error_code})\")\n return True\n\n # For non-429 errors, check if they're retryable\n retryable_indicators = [\n \"timeout\",\n \"connection\",\n \"network\",\n \"temporary\",\n \"unavailable\",\n \"retry\",\n \"408\", # Request timeout\n \"500\", # Internal server error\n \"502\", # Bad gateway\n \"503\", # Service unavailable\n \"504\", # Gateway timeout\n \"ssl\", # SSL errors\n \"handshake\", # Handshake failures\n ]\n\n return any(indicator in error_str for indicator in retryable_indicators)\n\n def _process_image(self, image_path: str) -> Optional[dict]:\n \"\"\"Process an image for OpenAI-compatible API.\"\"\"\n try:\n if image_path.startswith(\"data:\"):\n # Validate the data URL\n validate_image(image_path)\n # Handle data URL: data:image/png;base64,iVBORw0...\n return {\"type\": \"image_url\", \"image_url\": {\"url\": image_path}}\n else:\n # Use base class validation\n image_bytes, mime_type = validate_image(image_path)\n\n # Read and encode the image\n import base64\n\n image_data = base64.b64encode(image_bytes).decode()\n logging.debug(f\"Processing image '{image_path}' as MIME type '{mime_type}'\")\n\n # Create data URL for OpenAI API\n data_url = f\"data:{mime_type};base64,{image_data}\"\n\n return {\"type\": \"image_url\", \"image_url\": {\"url\": data_url}}\n\n except ValueError as e:\n logging.warning(str(e))\n return None\n except Exception as e:\n logging.error(f\"Error processing image {image_path}: {e}\")\n return None\n" }, { "path": "providers/openrouter.py", "content": "\"\"\"OpenRouter provider implementation.\"\"\"\n\nimport logging\n\nfrom utils.env import get_env\n\nfrom .openai_compatible import OpenAICompatibleProvider\nfrom .registries.openrouter import OpenRouterModelRegistry\nfrom .shared import (\n ModelCapabilities,\n ProviderType,\n RangeTemperatureConstraint,\n)\n\n\nclass OpenRouterProvider(OpenAICompatibleProvider):\n \"\"\"Client for OpenRouter's multi-model aggregation service.\n\n Role\n Surface OpenRouter’s dynamic catalogue through the same interface as\n native providers so tools can reference OpenRouter models and aliases\n without special cases.\n\n Characteristics\n * Pulls live model definitions from :class:`OpenRouterModelRegistry`\n (aliases, provider-specific metadata, capability hints)\n * Applies alias-aware restriction checks before exposing models to the\n registry or tooling\n * Reuses :class:`OpenAICompatibleProvider` infrastructure for request\n execution so OpenRouter endpoints behave like standard OpenAI-style\n APIs.\n \"\"\"\n\n FRIENDLY_NAME = \"OpenRouter\"\n\n # Custom headers required by OpenRouter\n DEFAULT_HEADERS = {\n \"HTTP-Referer\": get_env(\"OPENROUTER_REFERER\", \"https://github.com/BeehiveInnovations/pal-mcp-server\")\n or \"https://github.com/BeehiveInnovations/pal-mcp-server\",\n \"X-Title\": get_env(\"OPENROUTER_TITLE\", \"PAL MCP Server\") or \"PAL MCP Server\",\n }\n\n # Model registry for managing configurations and aliases\n _registry: OpenRouterModelRegistry | None = None\n\n def __init__(self, api_key: str, **kwargs):\n \"\"\"Initialize OpenRouter provider.\n\n Args:\n api_key: OpenRouter API key\n **kwargs: Additional configuration\n \"\"\"\n base_url = \"https://openrouter.ai/api/v1\"\n self._alias_cache: dict[str, str] = {}\n super().__init__(api_key, base_url=base_url, **kwargs)\n\n # Initialize model registry\n if OpenRouterProvider._registry is None:\n OpenRouterProvider._registry = OpenRouterModelRegistry()\n # Log loaded models and aliases only on first load\n models = self._registry.list_models()\n aliases = self._registry.list_aliases()\n logging.info(f\"OpenRouter loaded {len(models)} models with {len(aliases)} aliases\")\n\n # ------------------------------------------------------------------\n # Capability surface\n # ------------------------------------------------------------------\n\n def _lookup_capabilities(\n self,\n canonical_name: str,\n requested_name: str | None = None,\n ) -> ModelCapabilities | None:\n \"\"\"Fetch OpenRouter capabilities from the registry or build a generic fallback.\"\"\"\n\n capabilities = self._registry.get_capabilities(canonical_name)\n if capabilities:\n return capabilities\n\n base_identifier = canonical_name.split(\":\", 1)[0]\n if \"/\" in base_identifier:\n logging.debug(\n \"Using generic OpenRouter capabilities for %s (provider/model format detected)\", canonical_name\n )\n generic = ModelCapabilities(\n provider=ProviderType.OPENROUTER,\n model_name=canonical_name,\n friendly_name=self.FRIENDLY_NAME,\n intelligence_score=9,\n context_window=32_768,\n max_output_tokens=32_768,\n supports_extended_thinking=False,\n supports_system_prompts=True,\n supports_streaming=True,\n supports_function_calling=False,\n temperature_constraint=RangeTemperatureConstraint(0.0, 2.0, 1.0),\n )\n generic._is_generic = True\n return generic\n\n logging.debug(\n \"Rejecting unknown OpenRouter model '%s' (no provider prefix); requires explicit configuration\",\n canonical_name,\n )\n return None\n\n # ------------------------------------------------------------------\n # Provider identity\n # ------------------------------------------------------------------\n\n def get_provider_type(self) -> ProviderType:\n \"\"\"Identify this provider for restrictions and logging.\"\"\"\n return ProviderType.OPENROUTER\n\n # ------------------------------------------------------------------\n # Registry helpers\n # ------------------------------------------------------------------\n\n def list_models(\n self,\n *,\n respect_restrictions: bool = True,\n include_aliases: bool = True,\n lowercase: bool = False,\n unique: bool = False,\n ) -> list[str]:\n \"\"\"Return formatted OpenRouter model names, respecting alias-aware restrictions.\"\"\"\n\n if not self._registry:\n return []\n\n from utils.model_restrictions import get_restriction_service\n\n restriction_service = get_restriction_service() if respect_restrictions else None\n allowed_configs: dict[str, ModelCapabilities] = {}\n\n for model_name in self._registry.list_models():\n config = self._registry.resolve(model_name)\n if not config:\n continue\n\n # Custom models belong to CustomProvider; skip them here so the two\n # providers don't race over the same registrations (important for tests\n # that stub the registry with minimal objects lacking attrs).\n if config.provider == ProviderType.CUSTOM:\n continue\n\n if restriction_service:\n allowed = restriction_service.is_allowed(self.get_provider_type(), model_name)\n\n if not allowed and config.aliases:\n for alias in config.aliases:\n if restriction_service.is_allowed(self.get_provider_type(), alias):\n allowed = True\n break\n\n if not allowed:\n continue\n\n allowed_configs[model_name] = config\n\n if not allowed_configs:\n return []\n\n # When restrictions are in place, don't include aliases to avoid confusion\n # Only return the canonical model names that are actually allowed\n actual_include_aliases = include_aliases and not respect_restrictions\n\n return ModelCapabilities.collect_model_names(\n allowed_configs,\n include_aliases=actual_include_aliases,\n lowercase=lowercase,\n unique=unique,\n )\n\n # ------------------------------------------------------------------\n # Registry helpers\n # ------------------------------------------------------------------\n\n def _resolve_model_name(self, model_name: str) -> str:\n \"\"\"Resolve aliases defined in the OpenRouter registry.\"\"\"\n\n cache_key = model_name.lower()\n if cache_key in self._alias_cache:\n return self._alias_cache[cache_key]\n\n config = self._registry.resolve(model_name)\n if config:\n if config.model_name != model_name:\n logging.debug(\"Resolved model alias '%s' to '%s'\", model_name, config.model_name)\n resolved = config.model_name\n self._alias_cache[cache_key] = resolved\n self._alias_cache.setdefault(resolved.lower(), resolved)\n return resolved\n\n logging.debug(f\"Model '{model_name}' not found in registry, using as-is\")\n self._alias_cache[cache_key] = model_name\n return model_name\n\n def get_all_model_capabilities(self) -> dict[str, ModelCapabilities]:\n \"\"\"Expose registry-backed OpenRouter capabilities.\"\"\"\n\n if not self._registry:\n return {}\n\n capabilities: dict[str, ModelCapabilities] = {}\n for model_name in self._registry.list_models():\n config = self._registry.resolve(model_name)\n if not config:\n continue\n\n # See note in list_models: respect the CustomProvider boundary.\n if config.provider == ProviderType.CUSTOM:\n continue\n\n capabilities[model_name] = config\n return capabilities\n" }, { "path": "providers/registries/__init__.py", "content": "\"\"\"Registry implementations for provider capability manifests.\"\"\"\n\nfrom .azure import AzureModelRegistry\nfrom .custom import CustomEndpointModelRegistry\nfrom .dial import DialModelRegistry\nfrom .gemini import GeminiModelRegistry\nfrom .openai import OpenAIModelRegistry\nfrom .openrouter import OpenRouterModelRegistry\nfrom .xai import XAIModelRegistry\n\n__all__ = [\n \"AzureModelRegistry\",\n \"CustomEndpointModelRegistry\",\n \"DialModelRegistry\",\n \"GeminiModelRegistry\",\n \"OpenAIModelRegistry\",\n \"OpenRouterModelRegistry\",\n \"XAIModelRegistry\",\n]\n" }, { "path": "providers/registries/azure.py", "content": "\"\"\"Registry loader for Azure OpenAI model configurations.\"\"\"\n\nfrom __future__ import annotations\n\nimport logging\n\nfrom ..shared import ModelCapabilities, ProviderType, TemperatureConstraint\nfrom .base import CAPABILITY_FIELD_NAMES, CustomModelRegistryBase\n\nlogger = logging.getLogger(__name__)\n\n\nclass AzureModelRegistry(CustomModelRegistryBase):\n \"\"\"Load Azure-specific model metadata from configuration files.\"\"\"\n\n def __init__(self, config_path: str | None = None) -> None:\n super().__init__(\n env_var_name=\"AZURE_MODELS_CONFIG_PATH\",\n default_filename=\"azure_models.json\",\n config_path=config_path,\n )\n self.reload()\n\n def _extra_keys(self) -> set[str]:\n return {\"deployment\", \"deployment_name\"}\n\n def _provider_default(self) -> ProviderType:\n return ProviderType.AZURE\n\n def _default_friendly_name(self, model_name: str) -> str:\n return f\"Azure OpenAI ({model_name})\"\n\n def _finalise_entry(self, entry: dict) -> tuple[ModelCapabilities, dict]:\n deployment = entry.pop(\"deployment\", None) or entry.pop(\"deployment_name\", None)\n if not deployment:\n raise ValueError(f\"Azure model '{entry.get('model_name')}' is missing required 'deployment' field\")\n\n temp_hint = entry.get(\"temperature_constraint\")\n if isinstance(temp_hint, str):\n entry[\"temperature_constraint\"] = TemperatureConstraint.create(temp_hint)\n\n filtered = {k: v for k, v in entry.items() if k in CAPABILITY_FIELD_NAMES}\n filtered.setdefault(\"provider\", ProviderType.AZURE)\n capability = ModelCapabilities(**filtered)\n return capability, {\"deployment\": deployment}\n" }, { "path": "providers/registries/base.py", "content": "\"\"\"Shared infrastructure for JSON-backed model registries.\"\"\"\n\nfrom __future__ import annotations\n\nimport importlib.resources\nimport json\nimport logging\nfrom collections.abc import Iterable\nfrom dataclasses import fields\nfrom pathlib import Path\n\nfrom utils.env import get_env\nfrom utils.file_utils import read_json_file\n\nfrom ..shared import ModelCapabilities, ProviderType, TemperatureConstraint\n\nlogger = logging.getLogger(__name__)\n\n\nCAPABILITY_FIELD_NAMES = {field.name for field in fields(ModelCapabilities)}\n\n\nclass CustomModelRegistryBase:\n \"\"\"Load and expose capability metadata from a JSON manifest.\"\"\"\n\n def __init__(\n self,\n *,\n env_var_name: str,\n default_filename: str,\n config_path: str | None = None,\n ) -> None:\n self._env_var_name = env_var_name\n self._default_filename = default_filename\n self._use_resources = False\n self._resource_package = \"conf\"\n self._default_path = Path(__file__).resolve().parents[3] / \"conf\" / default_filename\n\n if config_path:\n self.config_path = Path(config_path)\n else:\n env_path = get_env(env_var_name)\n if env_path:\n self.config_path = Path(env_path)\n else:\n try:\n resource = importlib.resources.files(self._resource_package).joinpath(default_filename)\n if hasattr(resource, \"read_text\"):\n self._use_resources = True\n self.config_path = None\n else:\n raise AttributeError(\"resource accessor not available\")\n except Exception:\n self.config_path = Path(__file__).resolve().parents[3] / \"conf\" / default_filename\n\n self.alias_map: dict[str, str] = {}\n self.model_map: dict[str, ModelCapabilities] = {}\n self._extras: dict[str, dict] = {}\n\n def reload(self) -> None:\n data = self._load_config_data()\n configs = [config for config in self._parse_models(data) if config is not None]\n self._build_maps(configs)\n\n def list_models(self) -> list[str]:\n return list(self.model_map.keys())\n\n def list_aliases(self) -> list[str]:\n return list(self.alias_map.keys())\n\n def resolve(self, name_or_alias: str) -> ModelCapabilities | None:\n key = name_or_alias.lower()\n canonical = self.alias_map.get(key)\n if canonical:\n return self.model_map.get(canonical)\n\n for model_name in self.model_map:\n if model_name.lower() == key:\n return self.model_map[model_name]\n return None\n\n def get_capabilities(self, name_or_alias: str) -> ModelCapabilities | None:\n return self.resolve(name_or_alias)\n\n def get_entry(self, model_name: str) -> dict | None:\n return self._extras.get(model_name)\n\n def get_model_config(self, model_name: str) -> ModelCapabilities | None:\n \"\"\"Backwards-compatible accessor for registries expecting this helper.\"\"\"\n\n return self.model_map.get(model_name) or self.resolve(model_name)\n\n def iter_entries(self) -> Iterable[tuple[str, ModelCapabilities, dict]]:\n for model_name, capability in self.model_map.items():\n yield model_name, capability, self._extras.get(model_name, {})\n\n # ------------------------------------------------------------------\n # Internal helpers\n # ------------------------------------------------------------------\n def _load_config_data(self) -> dict:\n if self._use_resources:\n try:\n resource = importlib.resources.files(self._resource_package).joinpath(self._default_filename)\n if hasattr(resource, \"read_text\"):\n config_text = resource.read_text(encoding=\"utf-8\")\n else: # pragma: no cover - legacy Python fallback\n with resource.open(\"r\", encoding=\"utf-8\") as handle:\n config_text = handle.read()\n data = json.loads(config_text)\n except FileNotFoundError:\n logger.debug(\"Packaged %s not found\", self._default_filename)\n return {\"models\": []}\n except Exception as exc:\n logger.warning(\"Failed to read packaged %s: %s\", self._default_filename, exc)\n return {\"models\": []}\n return data or {\"models\": []}\n\n if not self.config_path:\n raise FileNotFoundError(\"Registry configuration path is not set\")\n\n if not self.config_path.exists():\n logger.debug(\"Model registry config not found at %s\", self.config_path)\n if self.config_path == self._default_path:\n fallback = Path.cwd() / \"conf\" / self._default_filename\n if fallback != self.config_path and fallback.exists():\n logger.debug(\"Falling back to %s\", fallback)\n self.config_path = fallback\n else:\n return {\"models\": []}\n else:\n return {\"models\": []}\n\n data = read_json_file(str(self.config_path))\n return data or {\"models\": []}\n\n @property\n def use_resources(self) -> bool:\n return self._use_resources\n\n def _parse_models(self, data: dict) -> Iterable[ModelCapabilities | None]:\n for raw in data.get(\"models\", []):\n if not isinstance(raw, dict):\n continue\n yield self._convert_entry(raw)\n\n def _convert_entry(self, raw: dict) -> ModelCapabilities | None:\n entry = dict(raw)\n model_name = entry.get(\"model_name\")\n if not model_name:\n return None\n\n aliases = entry.get(\"aliases\")\n if isinstance(aliases, str):\n entry[\"aliases\"] = [alias.strip() for alias in aliases.split(\",\") if alias.strip()]\n\n entry.setdefault(\"friendly_name\", self._default_friendly_name(model_name))\n\n temperature_hint = entry.get(\"temperature_constraint\")\n if isinstance(temperature_hint, str):\n entry[\"temperature_constraint\"] = TemperatureConstraint.create(temperature_hint)\n elif temperature_hint is None:\n entry[\"temperature_constraint\"] = TemperatureConstraint.create(\"range\")\n\n if \"max_tokens\" in entry:\n raise ValueError(\n \"`max_tokens` is no longer supported. Use `max_output_tokens` in your model configuration.\"\n )\n\n unknown_keys = set(entry.keys()) - CAPABILITY_FIELD_NAMES - self._extra_keys()\n if unknown_keys:\n raise ValueError(\"Unsupported fields in model configuration: \" + \", \".join(sorted(unknown_keys)))\n\n capability, extras = self._finalise_entry(entry)\n capability.provider = self._provider_default()\n self._extras[capability.model_name] = extras or {}\n return capability\n\n def _default_friendly_name(self, model_name: str) -> str:\n return model_name\n\n def _extra_keys(self) -> set[str]:\n return set()\n\n def _provider_default(self) -> ProviderType:\n return ProviderType.OPENROUTER\n\n def _finalise_entry(self, entry: dict) -> tuple[ModelCapabilities, dict]:\n return ModelCapabilities(**{k: v for k, v in entry.items() if k in CAPABILITY_FIELD_NAMES}), {}\n\n def _build_maps(self, configs: Iterable[ModelCapabilities]) -> None:\n alias_map: dict[str, str] = {}\n model_map: dict[str, ModelCapabilities] = {}\n\n for config in configs:\n if not config:\n continue\n model_map[config.model_name] = config\n\n model_name_lower = config.model_name.lower()\n if model_name_lower not in alias_map:\n alias_map[model_name_lower] = config.model_name\n\n for alias in config.aliases:\n alias_lower = alias.lower()\n if alias_lower in alias_map and alias_map[alias_lower] != config.model_name:\n raise ValueError(\n f\"Duplicate alias '{alias}' found for models '{alias_map[alias_lower]}' and '{config.model_name}'\"\n )\n alias_map[alias_lower] = config.model_name\n\n self.alias_map = alias_map\n self.model_map = model_map\n\n\nclass CapabilityModelRegistry(CustomModelRegistryBase):\n \"\"\"Registry that returns :class:`ModelCapabilities` objects with alias support.\"\"\"\n\n def __init__(\n self,\n *,\n env_var_name: str,\n default_filename: str,\n provider: ProviderType,\n friendly_prefix: str,\n config_path: str | None = None,\n ) -> None:\n self._provider = provider\n self._friendly_prefix = friendly_prefix\n super().__init__(\n env_var_name=env_var_name,\n default_filename=default_filename,\n config_path=config_path,\n )\n self.reload()\n\n def _provider_default(self) -> ProviderType:\n return self._provider\n\n def _default_friendly_name(self, model_name: str) -> str:\n return self._friendly_prefix.format(model=model_name)\n\n def _finalise_entry(self, entry: dict) -> tuple[ModelCapabilities, dict]:\n filtered = {k: v for k, v in entry.items() if k in CAPABILITY_FIELD_NAMES}\n filtered.setdefault(\"provider\", self._provider_default())\n capability = ModelCapabilities(**filtered)\n return capability, {}\n" }, { "path": "providers/registries/custom.py", "content": "\"\"\"Registry loader for custom OpenAI-compatible endpoints.\"\"\"\n\nfrom __future__ import annotations\n\nfrom ..shared import ModelCapabilities, ProviderType\nfrom .base import CAPABILITY_FIELD_NAMES, CapabilityModelRegistry\n\n\nclass CustomEndpointModelRegistry(CapabilityModelRegistry):\n \"\"\"Capability registry backed by ``conf/custom_models.json``.\"\"\"\n\n def __init__(self, config_path: str | None = None) -> None:\n super().__init__(\n env_var_name=\"CUSTOM_MODELS_CONFIG_PATH\",\n default_filename=\"custom_models.json\",\n provider=ProviderType.CUSTOM,\n friendly_prefix=\"Custom ({model})\",\n config_path=config_path,\n )\n\n def _finalise_entry(self, entry: dict) -> tuple[ModelCapabilities, dict]:\n filtered = {k: v for k, v in entry.items() if k in CAPABILITY_FIELD_NAMES}\n filtered.setdefault(\"provider\", ProviderType.CUSTOM)\n capability = ModelCapabilities(**filtered)\n return capability, {}\n" }, { "path": "providers/registries/dial.py", "content": "\"\"\"Registry loader for DIAL provider capabilities.\"\"\"\n\nfrom __future__ import annotations\n\nfrom ..shared import ProviderType\nfrom .base import CapabilityModelRegistry\n\n\nclass DialModelRegistry(CapabilityModelRegistry):\n \"\"\"Capability registry backed by ``conf/dial_models.json``.\"\"\"\n\n def __init__(self, config_path: str | None = None) -> None:\n super().__init__(\n env_var_name=\"DIAL_MODELS_CONFIG_PATH\",\n default_filename=\"dial_models.json\",\n provider=ProviderType.DIAL,\n friendly_prefix=\"DIAL ({model})\",\n config_path=config_path,\n )\n" }, { "path": "providers/registries/gemini.py", "content": "\"\"\"Registry loader for Gemini model capabilities.\"\"\"\n\nfrom __future__ import annotations\n\nfrom ..shared import ProviderType\nfrom .base import CapabilityModelRegistry\n\n\nclass GeminiModelRegistry(CapabilityModelRegistry):\n \"\"\"Capability registry backed by ``conf/gemini_models.json``.\"\"\"\n\n def __init__(self, config_path: str | None = None) -> None:\n super().__init__(\n env_var_name=\"GEMINI_MODELS_CONFIG_PATH\",\n default_filename=\"gemini_models.json\",\n provider=ProviderType.GOOGLE,\n friendly_prefix=\"Gemini ({model})\",\n config_path=config_path,\n )\n" }, { "path": "providers/registries/openai.py", "content": "\"\"\"Registry loader for OpenAI model capabilities.\"\"\"\n\nfrom __future__ import annotations\n\nfrom ..shared import ProviderType\nfrom .base import CapabilityModelRegistry\n\n\nclass OpenAIModelRegistry(CapabilityModelRegistry):\n \"\"\"Capability registry backed by ``conf/openai_models.json``.\"\"\"\n\n def __init__(self, config_path: str | None = None) -> None:\n super().__init__(\n env_var_name=\"OPENAI_MODELS_CONFIG_PATH\",\n default_filename=\"openai_models.json\",\n provider=ProviderType.OPENAI,\n friendly_prefix=\"OpenAI ({model})\",\n config_path=config_path,\n )\n" }, { "path": "providers/registries/openrouter.py", "content": "\"\"\"OpenRouter model registry for managing model configurations and aliases.\"\"\"\n\nfrom __future__ import annotations\n\nfrom ..shared import ModelCapabilities, ProviderType\nfrom .base import CAPABILITY_FIELD_NAMES, CapabilityModelRegistry\n\n\nclass OpenRouterModelRegistry(CapabilityModelRegistry):\n \"\"\"Capability registry backed by ``conf/openrouter_models.json``.\"\"\"\n\n def __init__(self, config_path: str | None = None) -> None:\n super().__init__(\n env_var_name=\"OPENROUTER_MODELS_CONFIG_PATH\",\n default_filename=\"openrouter_models.json\",\n provider=ProviderType.OPENROUTER,\n friendly_prefix=\"OpenRouter ({model})\",\n config_path=config_path,\n )\n\n def _finalise_entry(self, entry: dict) -> tuple[ModelCapabilities, dict]:\n provider_override = entry.get(\"provider\")\n if isinstance(provider_override, str):\n entry_provider = ProviderType(provider_override.lower())\n elif isinstance(provider_override, ProviderType):\n entry_provider = provider_override\n else:\n entry_provider = ProviderType.OPENROUTER\n\n if entry_provider == ProviderType.CUSTOM:\n entry.setdefault(\"friendly_name\", f\"Custom ({entry['model_name']})\")\n else:\n entry.setdefault(\"friendly_name\", f\"OpenRouter ({entry['model_name']})\")\n\n filtered = {k: v for k, v in entry.items() if k in CAPABILITY_FIELD_NAMES}\n filtered.setdefault(\"provider\", entry_provider)\n capability = ModelCapabilities(**filtered)\n return capability, {}\n" }, { "path": "providers/registries/xai.py", "content": "\"\"\"Registry loader for X.AI model capabilities.\"\"\"\n\nfrom __future__ import annotations\n\nfrom ..shared import ProviderType\nfrom .base import CapabilityModelRegistry\n\n\nclass XAIModelRegistry(CapabilityModelRegistry):\n \"\"\"Capability registry backed by ``conf/xai_models.json``.\"\"\"\n\n def __init__(self, config_path: str | None = None) -> None:\n super().__init__(\n env_var_name=\"XAI_MODELS_CONFIG_PATH\",\n default_filename=\"xai_models.json\",\n provider=ProviderType.XAI,\n friendly_prefix=\"X.AI ({model})\",\n config_path=config_path,\n )\n" }, { "path": "providers/registry.py", "content": "\"\"\"Model provider registry for managing available providers.\"\"\"\n\nimport logging\nfrom typing import TYPE_CHECKING, Optional\n\nfrom utils.env import get_env\n\nfrom .base import ModelProvider\nfrom .shared import ProviderType\n\nif TYPE_CHECKING:\n from tools.models import ToolModelCategory\n\n\nclass ModelProviderRegistry:\n \"\"\"Central catalogue of provider implementations used by the MCP server.\n\n Role\n Holds the mapping between :class:`ProviderType` values and concrete\n :class:`ModelProvider` subclasses/factories. At runtime the registry\n is responsible for instantiating providers, caching them for reuse, and\n mediating lookup of providers and model names in provider priority\n order.\n\n Core responsibilities\n * Resolve API keys and other runtime configuration for each provider\n * Lazily create provider instances so unused backends incur no cost\n * Expose convenience methods for enumerating available models and\n locating which provider can service a requested model name or alias\n * Honour the project-wide provider priority policy so namespaces (or\n alias collisions) are resolved deterministically.\n \"\"\"\n\n _instance = None\n\n # Provider priority order for model selection\n # Native APIs first, then custom endpoints, then catch-all providers\n PROVIDER_PRIORITY_ORDER = [\n ProviderType.GOOGLE, # Direct Gemini access\n ProviderType.OPENAI, # Direct OpenAI access\n ProviderType.AZURE, # Azure-hosted OpenAI deployments\n ProviderType.XAI, # Direct X.AI GROK access\n ProviderType.DIAL, # DIAL unified API access\n ProviderType.CUSTOM, # Local/self-hosted models\n ProviderType.OPENROUTER, # Catch-all for cloud models\n ]\n\n def __new__(cls):\n \"\"\"Singleton pattern for registry.\"\"\"\n if cls._instance is None:\n logging.debug(\"REGISTRY: Creating new registry instance\")\n cls._instance = super().__new__(cls)\n # Initialize instance dictionaries on first creation\n cls._instance._providers = {}\n cls._instance._initialized_providers = {}\n logging.debug(f\"REGISTRY: Created instance {cls._instance}\")\n return cls._instance\n\n @classmethod\n def register_provider(cls, provider_type: ProviderType, provider_class: type[ModelProvider]) -> None:\n \"\"\"Register a new provider class.\n\n Args:\n provider_type: Type of the provider (e.g., ProviderType.GOOGLE)\n provider_class: Class that implements ModelProvider interface\n \"\"\"\n instance = cls()\n instance._providers[provider_type] = provider_class\n # Invalidate any cached instance so subsequent lookups use the new registration\n instance._initialized_providers.pop(provider_type, None)\n\n @classmethod\n def get_provider(cls, provider_type: ProviderType, force_new: bool = False) -> Optional[ModelProvider]:\n \"\"\"Get an initialized provider instance.\n\n Args:\n provider_type: Type of provider to get\n force_new: Force creation of new instance instead of using cached\n\n Returns:\n Initialized ModelProvider instance or None if not available\n \"\"\"\n instance = cls()\n\n # Return cached instance if available and not forcing new\n if not force_new and provider_type in instance._initialized_providers:\n return instance._initialized_providers[provider_type]\n\n # Check if provider class is registered\n if provider_type not in instance._providers:\n return None\n\n # Get API key from environment\n api_key = cls._get_api_key_for_provider(provider_type)\n\n # Get provider class or factory function\n provider_class = instance._providers[provider_type]\n\n # For custom providers, handle special initialization requirements\n if provider_type == ProviderType.CUSTOM:\n # Check if it's a factory function (callable but not a class)\n if callable(provider_class) and not isinstance(provider_class, type):\n # Factory function - call it with api_key parameter\n provider = provider_class(api_key=api_key)\n else:\n # Regular class - need to handle URL requirement\n custom_url = get_env(\"CUSTOM_API_URL\", \"\") or \"\"\n if not custom_url:\n if api_key: # Key is set but URL is missing\n logging.warning(\"CUSTOM_API_KEY set but CUSTOM_API_URL missing – skipping Custom provider\")\n return None\n # Use empty string as API key for custom providers that don't need auth (e.g., Ollama)\n # This allows the provider to be created even without CUSTOM_API_KEY being set\n api_key = api_key or \"\"\n # Initialize custom provider with both API key and base URL\n provider = provider_class(api_key=api_key, base_url=custom_url)\n elif provider_type == ProviderType.GOOGLE:\n # For Gemini, check if custom base URL is configured\n if not api_key:\n return None\n gemini_base_url = get_env(\"GEMINI_BASE_URL\")\n provider_kwargs = {\"api_key\": api_key}\n if gemini_base_url:\n provider_kwargs[\"base_url\"] = gemini_base_url\n logging.info(f\"Initialized Gemini provider with custom endpoint: {gemini_base_url}\")\n provider = provider_class(**provider_kwargs)\n elif provider_type == ProviderType.AZURE:\n if not api_key:\n return None\n\n azure_endpoint = get_env(\"AZURE_OPENAI_ENDPOINT\")\n if not azure_endpoint:\n logging.warning(\"AZURE_OPENAI_ENDPOINT missing – skipping Azure OpenAI provider\")\n return None\n\n azure_version = get_env(\"AZURE_OPENAI_API_VERSION\")\n provider = provider_class(\n api_key=api_key,\n azure_endpoint=azure_endpoint,\n api_version=azure_version,\n )\n else:\n if not api_key:\n return None\n # Initialize non-custom provider with just API key\n provider = provider_class(api_key=api_key)\n\n # Cache the instance\n instance._initialized_providers[provider_type] = provider\n\n return provider\n\n @classmethod\n def get_provider_for_model(cls, model_name: str) -> Optional[ModelProvider]:\n \"\"\"Get provider instance for a specific model name.\n\n Provider priority order:\n 1. Native APIs (GOOGLE, OPENAI) - Most direct and efficient\n 2. CUSTOM - For local/private models with specific endpoints\n 3. OPENROUTER - Catch-all for cloud models via unified API\n\n Args:\n model_name: Name of the model (e.g., \"gemini-2.5-flash\", \"gpt5\")\n\n Returns:\n ModelProvider instance that supports this model\n \"\"\"\n logging.debug(f\"get_provider_for_model called with model_name='{model_name}'\")\n\n # Check providers in priority order\n instance = cls()\n logging.debug(f\"Registry instance: {instance}\")\n logging.debug(f\"Available providers in registry: {list(instance._providers.keys())}\")\n\n for provider_type in cls.PROVIDER_PRIORITY_ORDER:\n if provider_type in instance._providers:\n logging.debug(f\"Found {provider_type} in registry\")\n # Get or create provider instance\n provider = cls.get_provider(provider_type)\n if provider and provider.validate_model_name(model_name):\n logging.debug(f\"{provider_type} validates model {model_name}\")\n return provider\n else:\n logging.debug(f\"{provider_type} does not validate model {model_name}\")\n else:\n logging.debug(f\"{provider_type} not found in registry\")\n\n logging.debug(f\"No provider found for model {model_name}\")\n return None\n\n @classmethod\n def get_available_providers(cls) -> list[ProviderType]:\n \"\"\"Get list of registered provider types.\"\"\"\n instance = cls()\n return list(instance._providers.keys())\n\n @classmethod\n def get_available_models(cls, respect_restrictions: bool = True) -> dict[str, ProviderType]:\n \"\"\"Get mapping of all available models to their providers.\n\n Args:\n respect_restrictions: If True, filter out models not allowed by restrictions\n\n Returns:\n Dict mapping model names to provider types\n \"\"\"\n # Import here to avoid circular imports\n from utils.model_restrictions import get_restriction_service\n\n restriction_service = get_restriction_service() if respect_restrictions else None\n models: dict[str, ProviderType] = {}\n instance = cls()\n\n for provider_type in instance._providers:\n provider = cls.get_provider(provider_type)\n if not provider:\n continue\n\n try:\n available = provider.list_models(respect_restrictions=respect_restrictions)\n except NotImplementedError:\n logging.warning(\"Provider %s does not implement list_models\", provider_type)\n continue\n\n if restriction_service and restriction_service.has_restrictions(provider_type):\n restricted_display = cls._collect_restricted_display_names(\n provider,\n provider_type,\n available,\n restriction_service,\n )\n if restricted_display:\n for model_name in restricted_display:\n models[model_name] = provider_type\n continue\n\n for model_name in available:\n # =====================================================================================\n # CRITICAL: Prevent double restriction filtering (Fixed Issue #98)\n # =====================================================================================\n # Previously, both the provider AND registry applied restrictions, causing\n # double-filtering that resulted in \"no models available\" errors.\n #\n # Logic: If respect_restrictions=True, provider already filtered models,\n # so registry should NOT filter them again.\n # TEST COVERAGE: tests/test_provider_routing_bugs.py::TestOpenRouterAliasRestrictions\n # =====================================================================================\n if (\n restriction_service\n and not respect_restrictions # Only filter if provider didn't already filter\n and not restriction_service.is_allowed(provider_type, model_name)\n ):\n logging.debug(\"Model %s filtered by restrictions\", model_name)\n continue\n models[model_name] = provider_type\n\n return models\n\n @classmethod\n def _collect_restricted_display_names(\n cls,\n provider: ModelProvider,\n provider_type: ProviderType,\n available: list[str],\n restriction_service,\n ) -> list[str] | None:\n \"\"\"Derive the human-facing model list when restrictions are active.\"\"\"\n\n allowed_models = restriction_service.get_allowed_models(provider_type)\n if not allowed_models:\n return None\n\n allowed_details: list[tuple[str, int]] = []\n\n for model_name in sorted(allowed_models):\n try:\n capabilities = provider.get_capabilities(model_name)\n except (AttributeError, ValueError):\n continue\n\n try:\n rank = capabilities.get_effective_capability_rank()\n rank_value = float(rank)\n except (AttributeError, TypeError, ValueError):\n rank_value = 0.0\n\n allowed_details.append((model_name, rank_value))\n\n if allowed_details:\n allowed_details.sort(key=lambda item: (-item[1], item[0]))\n return [name for name, _ in allowed_details]\n\n # Fallback: intersect the allowlist with the provider-advertised names.\n available_lookup = {name.lower(): name for name in available}\n display_names: list[str] = []\n for model_name in sorted(allowed_models):\n lowered = model_name.lower()\n if lowered in available_lookup:\n display_names.append(available_lookup[lowered])\n\n return display_names\n\n @classmethod\n def get_available_model_names(cls, provider_type: Optional[ProviderType] = None) -> list[str]:\n \"\"\"Get list of available model names, optionally filtered by provider.\n\n This respects model restrictions automatically.\n\n Args:\n provider_type: Optional provider to filter by\n\n Returns:\n List of available model names\n \"\"\"\n available_models = cls.get_available_models(respect_restrictions=True)\n\n if provider_type:\n # Filter by specific provider\n return [name for name, ptype in available_models.items() if ptype == provider_type]\n else:\n # Return all available models\n return list(available_models.keys())\n\n @classmethod\n def _get_api_key_for_provider(cls, provider_type: ProviderType) -> Optional[str]:\n \"\"\"Get API key for a provider from environment variables.\n\n Args:\n provider_type: Provider type to get API key for\n\n Returns:\n API key string or None if not found\n \"\"\"\n key_mapping = {\n ProviderType.GOOGLE: \"GEMINI_API_KEY\",\n ProviderType.OPENAI: \"OPENAI_API_KEY\",\n ProviderType.AZURE: \"AZURE_OPENAI_API_KEY\",\n ProviderType.XAI: \"XAI_API_KEY\",\n ProviderType.OPENROUTER: \"OPENROUTER_API_KEY\",\n ProviderType.CUSTOM: \"CUSTOM_API_KEY\", # Can be empty for providers that don't need auth\n ProviderType.DIAL: \"DIAL_API_KEY\",\n }\n\n env_var = key_mapping.get(provider_type)\n if not env_var:\n return None\n\n return get_env(env_var)\n\n @classmethod\n def _get_allowed_models_for_provider(cls, provider: ModelProvider, provider_type: ProviderType) -> list[str]:\n \"\"\"Get a list of allowed canonical model names for a given provider.\n\n Args:\n provider: The provider instance to get models for\n provider_type: The provider type for restriction checking\n\n Returns:\n List of model names that are both supported and allowed\n \"\"\"\n from utils.model_restrictions import get_restriction_service\n\n restriction_service = get_restriction_service()\n\n allowed_models = []\n\n # Get the provider's supported models\n try:\n # Use list_models to get all supported models (handles both regular and custom providers)\n supported_models = provider.list_models(respect_restrictions=False)\n except (NotImplementedError, AttributeError):\n # Fallback to provider-declared capability maps if list_models not implemented\n model_map = getattr(provider, \"MODEL_CAPABILITIES\", None)\n supported_models = list(model_map.keys()) if isinstance(model_map, dict) else []\n\n # Filter by restrictions\n for model_name in supported_models:\n if restriction_service.is_allowed(provider_type, model_name):\n allowed_models.append(model_name)\n\n return allowed_models\n\n @classmethod\n def get_preferred_fallback_model(cls, tool_category: Optional[\"ToolModelCategory\"] = None) -> str:\n \"\"\"Get the preferred fallback model based on provider priority and tool category.\n\n This method orchestrates model selection by:\n 1. Getting allowed models for each provider (respecting restrictions)\n 2. Asking providers for their preference from the allowed list\n 3. Falling back to first available model if no preference given\n\n Args:\n tool_category: Optional category to influence model selection\n\n Returns:\n Model name string for fallback use\n \"\"\"\n from tools.models import ToolModelCategory\n\n effective_category = tool_category or ToolModelCategory.BALANCED\n first_available_model = None\n\n # Ask each provider for their preference in priority order\n for provider_type in cls.PROVIDER_PRIORITY_ORDER:\n provider = cls.get_provider(provider_type)\n if provider:\n # 1. Registry filters the models first\n allowed_models = cls._get_allowed_models_for_provider(provider, provider_type)\n\n if not allowed_models:\n continue\n\n # 2. Keep track of the first available model as fallback\n if not first_available_model:\n first_available_model = sorted(allowed_models)[0]\n\n # 3. Ask provider to pick from allowed list\n preferred_model = provider.get_preferred_model(effective_category, allowed_models)\n\n if preferred_model:\n logging.debug(\n f\"Provider {provider_type.value} selected '{preferred_model}' for category '{effective_category.value}'\"\n )\n return preferred_model\n\n # If no provider returned a preference, use first available model\n if first_available_model:\n logging.debug(f\"No provider preference, using first available: {first_available_model}\")\n return first_available_model\n\n # Ultimate fallback if no providers have models\n logging.warning(\"No models available from any provider, using default fallback\")\n return \"gemini-2.5-flash\"\n\n @classmethod\n def get_available_providers_with_keys(cls) -> list[ProviderType]:\n \"\"\"Get list of provider types that have valid API keys.\n\n Returns:\n List of ProviderType values for providers with valid API keys\n \"\"\"\n available = []\n instance = cls()\n for provider_type in instance._providers:\n if cls.get_provider(provider_type) is not None:\n available.append(provider_type)\n return available\n\n @classmethod\n def clear_cache(cls) -> None:\n \"\"\"Clear cached provider instances.\"\"\"\n instance = cls()\n instance._initialized_providers.clear()\n\n @classmethod\n def reset_for_testing(cls) -> None:\n \"\"\"Reset the registry to a clean state for testing.\n\n This provides a safe, public API for tests to clean up registry state\n without directly manipulating private attributes.\n \"\"\"\n cls._instance = None\n if hasattr(cls, \"_providers\"):\n cls._providers = {}\n\n @classmethod\n def unregister_provider(cls, provider_type: ProviderType) -> None:\n \"\"\"Unregister a provider (mainly for testing).\"\"\"\n instance = cls()\n instance._providers.pop(provider_type, None)\n instance._initialized_providers.pop(provider_type, None)\n" }, { "path": "providers/registry_provider_mixin.py", "content": "\"\"\"Mixin for providers backed by capability registries.\n\nThis mixin centralises the boilerplate for providers that expose their model\ncapabilities via JSON configuration files. Subclasses only need to set\n``REGISTRY_CLASS`` to an appropriate :class:`CapabilityModelRegistry` and the\nmix-in will take care of:\n\n* Populating ``MODEL_CAPABILITIES`` exactly once per process (with optional\n reload support for tests).\n* Lazily exposing the registry contents through the standard provider hooks\n (:meth:`get_all_model_capabilities` and :meth:`get_model_registry`).\n* Providing defensive logging when a registry cannot be constructed so the\n provider can degrade gracefully instead of raising during import.\n\nUsing this helper keeps individual provider implementations focused on their\nSDK-specific behaviour while ensuring capability loading is consistent across\nOpenAI, Gemini, X.AI, and other native backends.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport logging\nfrom typing import ClassVar\n\nfrom .registries.base import CapabilityModelRegistry\nfrom .shared import ModelCapabilities\n\n\nclass RegistryBackedProviderMixin:\n \"\"\"Shared helper for providers that load capabilities from JSON registries.\"\"\"\n\n REGISTRY_CLASS: ClassVar[type[CapabilityModelRegistry] | None] = None\n _registry: ClassVar[CapabilityModelRegistry | None] = None\n MODEL_CAPABILITIES: ClassVar[dict[str, ModelCapabilities]] = {}\n\n @classmethod\n def _registry_logger(cls) -> logging.Logger:\n \"\"\"Return the logger used for registry lifecycle messages.\"\"\"\n return logging.getLogger(cls.__module__)\n\n @classmethod\n def _ensure_registry(cls, *, force_reload: bool = False) -> None:\n \"\"\"Populate ``MODEL_CAPABILITIES`` from the configured registry.\n\n Args:\n force_reload: When ``True`` the registry is re-created even if it\n was previously loaded. This is primarily used by tests.\n \"\"\"\n\n if cls.REGISTRY_CLASS is None: # pragma: no cover - defensive programming\n raise RuntimeError(f\"{cls.__name__} must define REGISTRY_CLASS.\")\n\n if cls._registry is not None and not force_reload:\n return\n\n try:\n registry = cls.REGISTRY_CLASS()\n except Exception as exc: # pragma: no cover - registry failures shouldn't break the provider\n cls._registry_logger().warning(\"Unable to load %s registry: %s\", cls.__name__, exc)\n cls._registry = None\n cls.MODEL_CAPABILITIES = {}\n return\n\n cls._registry = registry\n cls.MODEL_CAPABILITIES = dict(registry.model_map)\n\n @classmethod\n def reload_registry(cls) -> None:\n \"\"\"Force a registry reload (used in tests).\"\"\"\n\n cls._ensure_registry(force_reload=True)\n\n def get_all_model_capabilities(self) -> dict[str, ModelCapabilities]:\n \"\"\"Return the registry-backed ``MODEL_CAPABILITIES`` map.\"\"\"\n\n self._ensure_registry()\n return super().get_all_model_capabilities()\n\n def get_model_registry(self) -> dict[str, ModelCapabilities] | None:\n \"\"\"Return a copy of the underlying registry map when available.\"\"\"\n\n if self._registry is None:\n return None\n return dict(self._registry.model_map)\n" }, { "path": "providers/shared/__init__.py", "content": "\"\"\"Shared data structures and helpers for model providers.\"\"\"\n\nfrom .model_capabilities import ModelCapabilities\nfrom .model_response import ModelResponse\nfrom .provider_type import ProviderType\nfrom .temperature import (\n DiscreteTemperatureConstraint,\n FixedTemperatureConstraint,\n RangeTemperatureConstraint,\n TemperatureConstraint,\n)\n\n__all__ = [\n \"ModelCapabilities\",\n \"ModelResponse\",\n \"ProviderType\",\n \"TemperatureConstraint\",\n \"FixedTemperatureConstraint\",\n \"RangeTemperatureConstraint\",\n \"DiscreteTemperatureConstraint\",\n]\n" }, { "path": "providers/shared/model_capabilities.py", "content": "\"\"\"Dataclass describing the feature set of a model exposed by a provider.\"\"\"\n\nimport math\nfrom dataclasses import dataclass, field\nfrom typing import Optional\n\nfrom .provider_type import ProviderType\nfrom .temperature import RangeTemperatureConstraint, TemperatureConstraint\n\n__all__ = [\"ModelCapabilities\"]\n\n\n@dataclass\nclass ModelCapabilities:\n \"\"\"Static description of what a model can do within a provider.\n\n Role\n Acts as the canonical record for everything the server needs to know\n about a modelβ€”its provider, token limits, feature switches, aliases,\n and temperature rules. Providers populate these objects so tools and\n higher-level services can rely on a consistent schema.\n\n Typical usage\n * Provider subclasses declare `MODEL_CAPABILITIES` maps containing these\n objects (for example ``OpenAIModelProvider``)\n * Helper utilities (e.g. restriction validation, alias expansion) read\n these objects to build model lists for tooling and policy enforcement\n * Tool selection logic inspects attributes such as\n ``supports_extended_thinking`` or ``context_window`` to choose an\n appropriate model for a task.\n * The ``allow_code_generation`` flag enables structured code generation\n in the chat tool for models more capable than the primary CLI.\n \"\"\"\n\n provider: ProviderType\n model_name: str\n friendly_name: str\n intelligence_score: int = 10 # Human-curated 1–20 score reflecting general capability\n description: str = \"\"\n aliases: list[str] = field(default_factory=list)\n\n # Capacity limits / resource budgets\n context_window: int = 0\n max_output_tokens: int = 0\n max_thinking_tokens: int = 0\n\n # Capability flags\n supports_extended_thinking: bool = False\n supports_system_prompts: bool = True\n supports_streaming: bool = True\n supports_function_calling: bool = False\n supports_images: bool = False\n supports_json_mode: bool = False\n supports_temperature: bool = True\n use_openai_response_api: bool = False\n default_reasoning_effort: Optional[str] = None\n allow_code_generation: bool = (\n False # Enables structured code generation in chat tool for substantial implementations\n )\n\n # Additional attributes\n max_image_size_mb: float = 0.0\n temperature_constraint: TemperatureConstraint = field(\n default_factory=lambda: RangeTemperatureConstraint(0.0, 2.0, 0.3)\n )\n\n def get_effective_temperature(self, requested_temperature: float) -> Optional[float]:\n \"\"\"Return the temperature that should be sent to the provider.\n\n Models that do not support temperature return ``None`` so that callers\n can omit the parameter entirely. For supported models, the configured\n constraint clamps the requested value into a provider-safe range.\n \"\"\"\n\n if not self.supports_temperature:\n return None\n\n return self.temperature_constraint.get_corrected_value(requested_temperature)\n\n def get_effective_capability_rank(self) -> int:\n \"\"\"Calculate the runtime capability rank from intelligence + capabilities.\"\"\"\n\n # Human signal drives the baseline (1–20 β†’ 5–100 after scaling)\n base_intelligence = self.intelligence_score if self.intelligence_score else 10\n base_intelligence = max(1, min(20, base_intelligence))\n score = base_intelligence * 5\n\n # Context window bonus with gentle diminishing returns\n ctx_bonus = 0\n ctx = max(self.context_window, 0)\n if ctx > 0:\n ctx_bonus = int(min(5, max(0.0, math.log10(ctx) - 3)))\n score += ctx_bonus\n\n # Output token capacity adds a small bonus\n if self.max_output_tokens >= 65_000:\n score += 2\n elif self.max_output_tokens >= 32_000:\n score += 1\n\n # Feature-level boosts\n if self.supports_extended_thinking:\n score += 3\n if self.supports_function_calling:\n score += 1\n if self.supports_json_mode:\n score += 1\n if self.supports_images:\n score += 1\n\n return max(0, min(100, score))\n\n @staticmethod\n def collect_aliases(model_configs: dict[str, \"ModelCapabilities\"]) -> dict[str, list[str]]:\n \"\"\"Build a mapping of model name to aliases from capability configs.\"\"\"\n\n return {\n base_model: capabilities.aliases\n for base_model, capabilities in model_configs.items()\n if capabilities.aliases\n }\n\n @staticmethod\n def collect_model_names(\n model_configs: dict[str, \"ModelCapabilities\"],\n *,\n include_aliases: bool = True,\n lowercase: bool = False,\n unique: bool = False,\n ) -> list[str]:\n \"\"\"Build an ordered list of model names and aliases.\n\n Args:\n model_configs: Mapping of canonical model names to capabilities.\n include_aliases: When True, include aliases for each model.\n lowercase: When True, normalize names to lowercase.\n unique: When True, ensure each returned name appears once (after formatting).\n\n Returns:\n Ordered list of model names (and optionally aliases) formatted per options.\n \"\"\"\n\n formatted_names: list[str] = []\n seen: set[str] | None = set() if unique else None\n\n def append_name(name: str) -> None:\n formatted = name.lower() if lowercase else name\n\n if seen is not None:\n if formatted in seen:\n return\n seen.add(formatted)\n\n formatted_names.append(formatted)\n\n # Sort models by capability rank (descending) then by name for deterministic ordering\n sorted_items = sorted(\n model_configs.items(),\n key=lambda item: (-item[1].get_effective_capability_rank(), item[0]),\n )\n\n for base_model, capabilities in sorted_items:\n append_name(base_model)\n\n if include_aliases and capabilities.aliases:\n for alias in capabilities.aliases:\n append_name(alias)\n\n return formatted_names\n" }, { "path": "providers/shared/model_response.py", "content": "\"\"\"Dataclass used to normalise provider SDK responses.\"\"\"\n\nfrom dataclasses import dataclass, field\nfrom typing import Any\n\nfrom .provider_type import ProviderType\n\n__all__ = [\"ModelResponse\"]\n\n\n@dataclass\nclass ModelResponse:\n \"\"\"Portable representation of a provider completion.\"\"\"\n\n content: str\n usage: dict[str, int] = field(default_factory=dict)\n model_name: str = \"\"\n friendly_name: str = \"\"\n provider: ProviderType = ProviderType.GOOGLE\n metadata: dict[str, Any] = field(default_factory=dict)\n\n @property\n def total_tokens(self) -> int:\n \"\"\"Return the total token count if the provider reported usage data.\"\"\"\n\n return self.usage.get(\"total_tokens\", 0)\n" }, { "path": "providers/shared/provider_type.py", "content": "\"\"\"Enumeration describing which backend owns a given model.\"\"\"\n\nfrom enum import Enum\n\n__all__ = [\"ProviderType\"]\n\n\nclass ProviderType(Enum):\n \"\"\"Canonical identifiers for every supported provider backend.\"\"\"\n\n GOOGLE = \"google\"\n OPENAI = \"openai\"\n AZURE = \"azure\"\n XAI = \"xai\"\n OPENROUTER = \"openrouter\"\n CUSTOM = \"custom\"\n DIAL = \"dial\"\n" }, { "path": "providers/shared/temperature.py", "content": "\"\"\"Helper types for validating model temperature parameters.\"\"\"\n\nfrom abc import ABC, abstractmethod\nfrom typing import Optional\n\n__all__ = [\n \"TemperatureConstraint\",\n \"FixedTemperatureConstraint\",\n \"RangeTemperatureConstraint\",\n \"DiscreteTemperatureConstraint\",\n]\n\n# Common heuristics for determining temperature support when explicit\n# capabilities are unavailable (e.g., custom/local models).\n_TEMP_UNSUPPORTED_PATTERNS = {\n \"o1\",\n \"o3\",\n \"o4\", # OpenAI O-series reasoning models\n \"deepseek-reasoner\",\n \"deepseek-r1\",\n \"r1\", # DeepSeek reasoner variants\n}\n\n_TEMP_UNSUPPORTED_KEYWORDS = {\n \"reasoner\", # Catch additional DeepSeek-style naming patterns\n}\n\n\nclass TemperatureConstraint(ABC):\n \"\"\"Contract for temperature validation used by `ModelCapabilities`.\n\n Concrete providers describe their temperature behaviour by creating\n subclasses that expose three operations:\n * `validate` – decide whether a requested temperature is acceptable.\n * `get_corrected_value` – coerce out-of-range values into a safe default.\n * `get_description` – provide a human readable error message for users.\n\n Providers call these hooks before sending traffic to the underlying API so\n that unsupported temperatures never reach the remote service.\n \"\"\"\n\n @abstractmethod\n def validate(self, temperature: float) -> bool:\n \"\"\"Return ``True`` when the temperature may be sent to the backend.\"\"\"\n\n @abstractmethod\n def get_corrected_value(self, temperature: float) -> float:\n \"\"\"Return a valid substitute for an out-of-range temperature.\"\"\"\n\n @abstractmethod\n def get_description(self) -> str:\n \"\"\"Describe the acceptable range to include in error messages.\"\"\"\n\n @abstractmethod\n def get_default(self) -> float:\n \"\"\"Return the default temperature for the model.\"\"\"\n\n @staticmethod\n def infer_support(model_name: str) -> tuple[bool, str]:\n \"\"\"Heuristically determine whether a model supports temperature.\"\"\"\n\n model_lower = model_name.lower()\n\n for pattern in _TEMP_UNSUPPORTED_PATTERNS:\n conditions = (\n pattern == model_lower,\n model_lower.startswith(f\"{pattern}-\"),\n model_lower.startswith(f\"openai/{pattern}\"),\n model_lower.startswith(f\"deepseek/{pattern}\"),\n model_lower.endswith(f\"-{pattern}\"),\n f\"/{pattern}\" in model_lower,\n f\"-{pattern}-\" in model_lower,\n )\n if any(conditions):\n return False, f\"detected pattern '{pattern}'\"\n\n for keyword in _TEMP_UNSUPPORTED_KEYWORDS:\n if keyword in model_lower:\n return False, f\"detected keyword '{keyword}'\"\n\n return True, \"default assumption for models without explicit metadata\"\n\n @staticmethod\n def resolve_settings(\n model_name: str,\n constraint_hint: Optional[str] = None,\n ) -> tuple[bool, \"TemperatureConstraint\", str]:\n \"\"\"Derive temperature support and constraint for a model.\n\n Args:\n model_name: Canonical model identifier or alias.\n constraint_hint: Optional configuration hint (``\"fixed\"``,\n ``\"range\"``, ``\"discrete\"``). When provided, the hint is\n honoured directly.\n\n Returns:\n Tuple ``(supports_temperature, constraint, diagnosis)`` describing\n whether temperature may be tuned, the constraint object that should\n be attached to :class:`ModelCapabilities`, and the reasoning behind\n the decision.\n \"\"\"\n\n if constraint_hint:\n constraint = TemperatureConstraint.create(constraint_hint)\n supports_temperature = constraint_hint != \"fixed\"\n reason = f\"constraint hint '{constraint_hint}'\"\n return supports_temperature, constraint, reason\n\n supports_temperature, reason = TemperatureConstraint.infer_support(model_name)\n if supports_temperature:\n constraint: TemperatureConstraint = RangeTemperatureConstraint(0.0, 2.0, 0.7)\n else:\n constraint = FixedTemperatureConstraint(1.0)\n\n return supports_temperature, constraint, reason\n\n @staticmethod\n def create(constraint_type: str) -> \"TemperatureConstraint\":\n \"\"\"Factory that yields the appropriate constraint for a configuration hint.\"\"\"\n\n if constraint_type == \"fixed\":\n # Fixed temperature models (O3/O4) only support temperature=1.0\n return FixedTemperatureConstraint(1.0)\n if constraint_type == \"discrete\":\n # For models with specific allowed values - using common OpenAI values as default\n return DiscreteTemperatureConstraint([0.0, 0.3, 0.7, 1.0, 1.5, 2.0], 0.3)\n # Default range constraint (for \"range\" or None)\n return RangeTemperatureConstraint(0.0, 2.0, 0.3)\n\n\nclass FixedTemperatureConstraint(TemperatureConstraint):\n \"\"\"Constraint for models that enforce an exact temperature (for example O3).\"\"\"\n\n def __init__(self, value: float):\n self.value = value\n\n def validate(self, temperature: float) -> bool:\n return abs(temperature - self.value) < 1e-6 # Handle floating point precision\n\n def get_corrected_value(self, temperature: float) -> float:\n return self.value\n\n def get_description(self) -> str:\n return f\"Only supports temperature={self.value}\"\n\n def get_default(self) -> float:\n return self.value\n\n\nclass RangeTemperatureConstraint(TemperatureConstraint):\n \"\"\"Constraint for providers that expose a continuous min/max temperature range.\"\"\"\n\n def __init__(self, min_temp: float, max_temp: float, default: Optional[float] = None):\n self.min_temp = min_temp\n self.max_temp = max_temp\n self.default_temp = default or (min_temp + max_temp) / 2\n\n def validate(self, temperature: float) -> bool:\n return self.min_temp <= temperature <= self.max_temp\n\n def get_corrected_value(self, temperature: float) -> float:\n return max(self.min_temp, min(self.max_temp, temperature))\n\n def get_description(self) -> str:\n return f\"Supports temperature range [{self.min_temp}, {self.max_temp}]\"\n\n def get_default(self) -> float:\n return self.default_temp\n\n\nclass DiscreteTemperatureConstraint(TemperatureConstraint):\n \"\"\"Constraint for models that permit a discrete list of temperature values.\"\"\"\n\n def __init__(self, allowed_values: list[float], default: Optional[float] = None):\n self.allowed_values = sorted(allowed_values)\n self.default_temp = default or allowed_values[len(allowed_values) // 2]\n\n def validate(self, temperature: float) -> bool:\n return any(abs(temperature - val) < 1e-6 for val in self.allowed_values)\n\n def get_corrected_value(self, temperature: float) -> float:\n return min(self.allowed_values, key=lambda x: abs(x - temperature))\n\n def get_description(self) -> str:\n return f\"Supports temperatures: {self.allowed_values}\"\n\n def get_default(self) -> float:\n return self.default_temp\n" }, { "path": "providers/xai.py", "content": "\"\"\"X.AI (GROK) model provider implementation.\"\"\"\n\nimport logging\nfrom typing import TYPE_CHECKING, ClassVar, Optional\n\nif TYPE_CHECKING:\n from tools.models import ToolModelCategory\n\nfrom .openai_compatible import OpenAICompatibleProvider\nfrom .registries.xai import XAIModelRegistry\nfrom .registry_provider_mixin import RegistryBackedProviderMixin\nfrom .shared import ModelCapabilities, ProviderType\n\nlogger = logging.getLogger(__name__)\n\n\nclass XAIModelProvider(RegistryBackedProviderMixin, OpenAICompatibleProvider):\n \"\"\"Integration for X.AI's GROK models exposed over an OpenAI-style API.\n\n Publishes capability metadata for the officially supported deployments and\n maps tool-category preferences to the appropriate GROK model.\n \"\"\"\n\n FRIENDLY_NAME = \"X.AI\"\n\n REGISTRY_CLASS = XAIModelRegistry\n MODEL_CAPABILITIES: ClassVar[dict[str, ModelCapabilities]] = {}\n\n # Canonical model identifiers used for category routing.\n PRIMARY_MODEL = \"grok-4-1-fast-reasoning\"\n FALLBACK_MODEL = \"grok-4\"\n\n def __init__(self, api_key: str, **kwargs):\n \"\"\"Initialize X.AI provider with API key.\"\"\"\n # Set X.AI base URL\n kwargs.setdefault(\"base_url\", \"https://api.x.ai/v1\")\n self._ensure_registry()\n super().__init__(api_key, **kwargs)\n self._invalidate_capability_cache()\n\n def get_provider_type(self) -> ProviderType:\n \"\"\"Get the provider type.\"\"\"\n return ProviderType.XAI\n\n def get_preferred_model(self, category: \"ToolModelCategory\", allowed_models: list[str]) -> Optional[str]:\n \"\"\"Get XAI's preferred model for a given category from allowed models.\n\n Args:\n category: The tool category requiring a model\n allowed_models: Pre-filtered list of models allowed by restrictions\n\n Returns:\n Preferred model name or None\n \"\"\"\n from tools.models import ToolModelCategory\n\n if not allowed_models:\n return None\n\n if category == ToolModelCategory.EXTENDED_REASONING:\n # Prefer Grok 4.1 Fast Reasoning for advanced tasks\n if self.PRIMARY_MODEL in allowed_models:\n return self.PRIMARY_MODEL\n if self.FALLBACK_MODEL in allowed_models:\n return self.FALLBACK_MODEL\n return allowed_models[0]\n\n elif category == ToolModelCategory.FAST_RESPONSE:\n # Prefer Grok 4.1 Fast Reasoning for speed as well (latest fast SKU).\n if self.PRIMARY_MODEL in allowed_models:\n return self.PRIMARY_MODEL\n if self.FALLBACK_MODEL in allowed_models:\n return self.FALLBACK_MODEL\n return allowed_models[0]\n\n else: # BALANCED or default\n # Prefer Grok 4.1 Fast Reasoning for balanced use.\n if self.PRIMARY_MODEL in allowed_models:\n return self.PRIMARY_MODEL\n if self.FALLBACK_MODEL in allowed_models:\n return self.FALLBACK_MODEL\n return allowed_models[0]\n\n\n# Load registry data at import time\nXAIModelProvider._ensure_registry()\n" }, { "path": "pyproject.toml", "content": "[project]\nname = \"pal-mcp-server\"\nversion = \"9.8.2\"\ndescription = \"AI-powered MCP server with multiple model providers\"\nrequires-python = \">=3.9\"\ndependencies = [\n \"mcp>=1.0.0\",\n \"google-genai>=1.19.0\",\n \"openai>=1.55.2\",\n \"pydantic>=2.0.0\",\n \"python-dotenv>=1.0.0\",\n]\n\n[tool.setuptools.packages.find]\ninclude = [\"tools*\", \"providers*\", \"systemprompts*\", \"utils*\", \"conf*\", \"clink*\"]\n\n[tool.setuptools]\npy-modules = [\"server\", \"config\"]\n\n[tool.setuptools.package-data]\n\"*\" = [\n \"conf/*.json\",\n \"conf/cli_clients/*.json\",\n \"systemprompts/clink/*.txt\",\n]\n\n[tool.setuptools.data-files]\n\"conf\" = [\n \"conf/custom_models.json\",\n \"conf/openrouter_models.json\",\n \"conf/azure_models.json\",\n \"conf/openai_models.json\",\n \"conf/gemini_models.json\",\n \"conf/xai_models.json\",\n \"conf/dial_models.json\",\n]\n\n[project.scripts]\npal-mcp-server = \"server:run\"\n\n[tool.black]\nline-length = 120\ntarget-version = ['py39', 'py310', 'py311', 'py312', 'py313']\ninclude = '\\.pyi?$'\nextend-exclude = '''\n/(\n # directories\n \\.eggs\n | \\.git\n | \\.hg\n | \\.mypy_cache\n | \\.tox\n | \\.venv\n | \\.pal_venv\n | venv\n | _build\n | buck-out\n | build\n | dist\n)/\n'''\n\n[tool.isort]\nprofile = \"black\"\nmulti_line_output = 3\ninclude_trailing_comma = true\nforce_grid_wrap = 0\nuse_parentheses = true\nensure_newline_before_comments = true\nline_length = 120\nskip_glob = [\"venv/*\", \".venv/*\", \".pal_venv/*\"]\n\n[tool.ruff]\ntarget-version = \"py39\"\nline-length = 120\n\n[tool.ruff.lint]\nselect = [\n \"E\", # pycodestyle errors\n \"W\", # pycodestyle warnings\n \"F\", # pyflakes\n \"I\", # isort\n \"B\", # flake8-bugbear\n \"C4\", # flake8-comprehensions\n \"UP\", # pyupgrade\n]\nignore = [\n \"E501\", # line too long, handled by black\n \"B008\", # do not perform function calls in argument defaults\n \"C901\", # too complex\n \"B904\", # exception handling with raise from\n]\n\n[tool.ruff.lint.per-file-ignores]\n\"__init__.py\" = [\"F401\"]\n\"tests/*\" = [\"B011\"]\n\"tests/conftest.py\" = [\"E402\"] # Module level imports not at top of file - needed for test setup\n\n[tool.semantic_release]\nversion_toml = [\"pyproject.toml:project.version\"]\nbranch = \"main\"\nversion_source = \"tag\"\nversion_pattern = \"v(?P\\\\d+)\\\\.(?P\\\\d+)\\\\.(?P\\\\d+)\"\nmajor_on_zero = false\nbuild_command = \"python -m pip install --upgrade build && python -m build\"\ndist_path = \"dist/\"\nupload_to_vcs_release = true\nupload_to_repository = false\nremove_dist = false\ncommit_version_number = true\ncommit_message = \"chore(release): {version}\\n\\nAutomatically generated by python-semantic-release\"\ntag_format = \"v{version}\"\n\n[tool.semantic_release.branches.main]\nmatch = \"main\"\nprerelease = false\n\n[tool.semantic_release.changelog]\nexclude_commit_patterns = []\n\n[tool.semantic_release.commit_parser_options]\nallowed_tags = [\"build\", \"chore\", \"ci\", \"docs\", \"feat\", \"fix\", \"perf\", \"style\", \"refactor\", \"test\"]\nminor_tags = [\"feat\"]\npatch_tags = [\"fix\", \"perf\"]\n\n[tool.semantic_release.remote.token]\nenv = \"GH_TOKEN\"\n\n[build-system]\nrequires = [\"setuptools>=45\", \"wheel\", \"setuptools_scm[toml]>=6.2\"]\nbuild-backend = \"setuptools.build_meta\"\n" }, { "path": "pytest.ini", "content": "[pytest]\ntestpaths = tests\npython_files = test_*.py\npython_classes = Test*\npython_functions = test_*\nasyncio_mode = auto\naddopts = \n -v\n --strict-markers\n --tb=short\nmarkers =\n integration: marks tests as integration tests that make real API calls with local-llama (free to run)" }, { "path": "requirements-dev.txt", "content": "pytest>=7.4.0\npytest-asyncio>=0.21.0\npytest-mock>=3.11.0\nblack>=23.0.0\nruff>=0.1.0\nisort>=5.12.0\npython-semantic-release>=10.3.0\nbuild>=1.0.0\n" }, { "path": "requirements.txt", "content": "mcp>=1.0.0\ngoogle-genai>=1.19.0\nopenai>=1.55.2 # Minimum version for httpx 0.28.0 compatibility\npydantic>=2.0.0\npython-dotenv>=1.0.0\nimportlib-resources>=5.0.0; python_version<\"3.9\"\n\n# Development dependencies (install with pip install -r requirements-dev.txt)\n# pytest>=7.4.0\n# pytest-asyncio>=0.21.0\n# pytest-mock>=3.11.0" }, { "path": "run-server.ps1", "content": "ο»Ώ<#\n.SYNOPSIS\n Installation, configuration, and launch script for PAL MCP server on Windows.\n\n.DESCRIPTION\n This PowerShell script prepares the environment for the PAL MCP server:\n - Installs and checks Python 3.10+ (with venv or uv if available)\n - Installs required Python dependencies\n - Configures environment files (.env)\n - Validates presence of required API keys\n - Cleans Python caches and obsolete Docker artifacts\n - Offers automatic integration with Claude Desktop, Gemini CLI, VSCode, Cursor, Windsurf, and Trae\n - Manages configuration file backups (max 3 retained)\n - Allows real-time log following or server launch\n\n.PARAMETER Help\n Shows script help.\n\n.PARAMETER Version\n Shows PAL MCP server version.\n\n.PARAMETER Follow\n Follows server logs in real time.\n\n.PARAMETER Config\n Shows configuration instructions for Claude and other compatible clients.\n\n.PARAMETER ClearCache\n Removes Python cache files (__pycache__, .pyc).\n\n.PARAMETER SkipVenv\n Skips Python virtual environment creation.\n\n.PARAMETER SkipDocker\n Skips Docker checks and cleanup.\n\n.PARAMETER Force\n Forces recreation of the Python virtual environment.\n \n.PARAMETER VerboseOutput\n Enables more detailed output (currently unused).\n\n.PARAMETER Dev\n Installs development dependencies from requirements-dev.txt if available.\n\n.PARAMETER Docker\n Uses Docker to build and run the MCP server instead of Python virtual environment.\n\n.EXAMPLE\n .\\run-server.ps1\n Prepares the environment and starts the PAL MCP server.\n\n .\\run-server.ps1 -Follow\n Follows server logs in real time.\n\n .\\run-server.ps1 -Config\n Shows configuration instructions for clients.\n\n .\\run-server.ps1 -Dev\n Prepares the environment with development dependencies and starts the server.\n\n .\\run-server.ps1 -Docker\n Builds and runs the server using Docker containers.\n\n .\\run-server.ps1 -Docker -Follow\n Builds and runs the server using Docker containers and follows the logs.\n\n .\\run-server.ps1 -Docker -Force\n Forces rebuilding of the Docker image and runs the server.\n\n.NOTES\n Project Author : BeehiveInnovations\n Script Author : GiGiDKR (https://github.com/GiGiDKR)\n Date : 07-05-2025\n Version : See config.py (__version__)\n References : https://github.com/BeehiveInnovations/pal-mcp-server\n\n#>\n#Requires -Version 5.1\n[CmdletBinding()]\nparam(\n [switch]$Help,\n [switch]$Version,\n [switch]$Follow,\n [switch]$Config,\n [switch]$ClearCache,\n [switch]$SkipVenv,\n [switch]$SkipDocker,\n [switch]$Force,\n [switch]$VerboseOutput,\n [switch]$Dev,\n [switch]$Docker\n)\n\n# ============================================================================\n# PAL MCP Server Setup Script for Windows\n# \n# A Windows-compatible setup script that handles environment setup, \n# dependency installation, and configuration.\n# ============================================================================\n\n# Set error action preference\n$ErrorActionPreference = \"Stop\"\n\n# ----------------------------------------------------------------------------\n# Constants and Configuration \n# ----------------------------------------------------------------------------\n\n$script:VENV_PATH = \".pal_venv\"\n$script:DOCKER_CLEANED_FLAG = \".docker_cleaned\"\n$script:DESKTOP_CONFIG_FLAG = \".desktop_configured\"\n$script:LOG_DIR = \"logs\"\n$script:LOG_FILE = \"mcp_server.log\"\n$script:LegacyServerNames = @(\"zen\", \"zen-mcp\", \"zen-mcp-server\", \"zen_mcp\", \"zen_mcp_server\")\n\n# ----------------------------------------------------------------------------\n# Utility Functions\n# ----------------------------------------------------------------------------\n\nfunction Write-Success {\n param([string]$Message)\n Write-Host \"βœ“ \" -ForegroundColor Green -NoNewline\n Write-Host $Message\n}\n\nfunction Write-Error {\n param([string]$Message)\n Write-Host \"βœ— \" -ForegroundColor Red -NoNewline\n Write-Host $Message\n}\n\nfunction Write-Warning {\n param([string]$Message)\n Write-Host \"⚠ \" -ForegroundColor Yellow -NoNewline\n Write-Host $Message\n}\n\nfunction Write-Info {\n param([string]$Message)\n Write-Host \"β„Ή \" -ForegroundColor Cyan -NoNewline\n Write-Host $Message\n}\n\nfunction Write-Step {\n param([string]$Message)\n Write-Host \"\"\n Write-Host \"=== $Message ===\" -ForegroundColor Cyan\n}\n\n# Check if command exists\nfunction Test-Command {\n param([string]$Command)\n try {\n $null = Get-Command $Command -ErrorAction Stop\n return $true\n }\n catch {\n return $false\n }\n}\n\n# Alternative method to force remove locked directories\nfunction Remove-LockedDirectory {\n param([string]$Path)\n \n if (!(Test-Path $Path)) {\n return $true\n }\n \n try {\n # Try standard removal first\n Remove-Item -Recurse -Force $Path -ErrorAction Stop\n return $true\n }\n catch {\n Write-Warning \"Standard removal failed, trying alternative methods...\"\n \n # Method 1: Use takeown and icacls to force ownership\n try {\n Write-Info \"Attempting to take ownership of locked files...\"\n takeown /F \"$Path\" /R /D Y 2>$null | Out-Null\n icacls \"$Path\" /grant administrators:F /T 2>$null | Out-Null\n Remove-Item -Recurse -Force $Path -ErrorAction Stop\n return $true\n }\n catch {\n Write-Warning \"Ownership method failed\"\n }\n \n # Method 2: Rename and schedule for deletion on reboot\n try {\n $tempName = \"$Path.delete_$(Get-Random)\"\n Write-Info \"Renaming to: $tempName (will be deleted on next reboot)\"\n Rename-Item $Path $tempName -ErrorAction Stop\n \n # Schedule for deletion on reboot using movefile\n if (Get-Command \"schtasks\" -ErrorAction SilentlyContinue) {\n Write-Info \"Scheduling for deletion on next reboot...\"\n }\n \n Write-Warning \"Environment renamed to $tempName and will be deleted on next reboot\"\n return $true\n }\n catch {\n Write-Warning \"Rename method failed\"\n }\n \n # If all methods fail, return false\n return $false\n }\n}\n\n# Remove legacy MCP server entries from a hash/dictionary or PSObject\nfunction Remove-LegacyServerKeys {\n param([object]$Container)\n\n $removed = $false\n if ($null -eq $Container) {\n return $false\n }\n\n foreach ($legacy in $script:LegacyServerNames) {\n if ($Container -is [System.Collections.IDictionary]) {\n if ($Container.Contains($legacy)) {\n $Container.Remove($legacy) | Out-Null\n $removed = $true\n }\n }\n elseif ($Container.PSObject -and $Container.PSObject.Properties[$legacy]) {\n $Container.PSObject.Properties.Remove($legacy)\n $removed = $true\n }\n }\n\n return $removed\n}\n\n# Manage configuration file backups with maximum 3 files retention\nfunction Manage-ConfigBackups {\n param(\n [string]$ConfigFilePath,\n [int]$MaxBackups = 3\n )\n \n if (!(Test-Path $ConfigFilePath)) {\n Write-Warning \"Configuration file not found: $ConfigFilePath\"\n return $null\n }\n \n try {\n # Create new backup with timestamp\n $timestamp = Get-Date -Format 'yyyyMMdd_HHmmss'\n $backupPath = \"$ConfigFilePath.backup_$timestamp\"\n Copy-Item $ConfigFilePath $backupPath -ErrorAction Stop\n \n # Find all existing backups for this config file\n $configDir = Split-Path $ConfigFilePath -Parent\n $configFileName = Split-Path $ConfigFilePath -Leaf\n $backupPattern = \"$configFileName.backup_*\"\n \n $existingBackups = Get-ChildItem -Path $configDir -Filter $backupPattern -ErrorAction SilentlyContinue |\n Sort-Object LastWriteTime -Descending\n \n # Keep only the most recent MaxBackups files\n if ($existingBackups.Count -gt $MaxBackups) {\n $backupsToRemove = $existingBackups | Select-Object -Skip $MaxBackups\n foreach ($backup in $backupsToRemove) {\n try {\n Remove-Item $backup.FullName -Force -ErrorAction Stop\n Write-Info \"Removed old backup: $($backup.Name)\"\n }\n catch {\n Write-Warning \"Could not remove old backup: $($backup.Name)\"\n }\n }\n Write-Success \"Backup retention: kept $MaxBackups most recent backups\"\n }\n \n Write-Success \"Backup created: $(Split-Path $backupPath -Leaf)\"\n return $backupPath\n \n }\n catch {\n Write-Warning \"Failed to create backup: $_\"\n return $null\n }\n}\n\n# Get version from config.py\nfunction Get-Version {\n try {\n if (Test-Path \"config.py\") {\n $content = Get-Content \"config.py\" -ErrorAction Stop\n $versionLine = $content | Where-Object { $_ -match '^__version__ = ' }\n if ($versionLine) {\n return ($versionLine -replace '__version__ = \"([^\"]*)\"', '$1')\n }\n }\n return \"unknown\"\n }\n catch {\n return \"unknown\"\n }\n}\n\n# Clear Python cache files\nfunction Clear-PythonCache {\n Write-Info \"Clearing Python cache files...\"\n \n try {\n # Remove .pyc files\n Get-ChildItem -Path . -Recurse -Filter \"*.pyc\" -ErrorAction SilentlyContinue | Remove-Item -Force\n \n # Remove __pycache__ directories\n Get-ChildItem -Path . -Recurse -Name \"__pycache__\" -Directory -ErrorAction SilentlyContinue | \n ForEach-Object { Remove-Item -Path $_ -Recurse -Force }\n \n Write-Success \"Python cache cleared\"\n }\n catch {\n Write-Warning \"Could not clear all cache files: $_\"\n }\n}\n\n# Get absolute path\nfunction Get-AbsolutePath {\n param([string]$Path)\n \n if (Test-Path $Path) {\n # Use Resolve-Path for full resolution\n return Resolve-Path $Path\n }\n else {\n # Use unresolved method\n return $ExecutionContext.SessionState.Path.GetUnresolvedProviderPathFromPSPath($Path)\n }\n}\n\n# Check Python version\nfunction Test-PythonVersion {\n param([string]$PythonCmd)\n try {\n $version = & $PythonCmd --version 2>&1\n if ($version -match \"Python (\\d+)\\.(\\d+)\") {\n $major = [int]$matches[1]\n $minor = [int]$matches[2]\n return ($major -gt 3) -or ($major -eq 3 -and $minor -ge 10)\n }\n return $false\n }\n catch {\n return $false\n }\n}\n\n# Find Python installation\nfunction Find-Python {\n $pythonCandidates = @(\"python\", \"python3\", \"py\")\n \n foreach ($cmd in $pythonCandidates) {\n if (Test-Command $cmd) {\n if (Test-PythonVersion $cmd) {\n $version = & $cmd --version 2>&1\n Write-Success \"Found Python: $version\"\n return $cmd\n }\n }\n }\n \n # Try Windows Python Launcher with specific versions\n $pythonVersions = @(\"3.12\", \"3.11\", \"3.10\", \"3.9\")\n foreach ($version in $pythonVersions) {\n $cmd = \"py -$version\"\n try {\n $null = Invoke-Expression \"$cmd --version\" 2>$null\n Write-Success \"Found Python via py launcher: $cmd\"\n return $cmd\n }\n catch {\n continue\n }\n }\n \n Write-Error \"Python 3.10+ not found. Please install Python from https://python.org\"\n return $null\n}\n\n# Clean up old Docker artifacts\nfunction Cleanup-Docker {\n if (Test-Path $DOCKER_CLEANED_FLAG) {\n return\n }\n \n if (!(Test-Command \"docker\")) {\n return\n }\n \n try {\n $null = docker info 2>$null\n }\n catch {\n return\n }\n \n $foundArtifacts = $false\n \n # Define containers to remove\n $containers = @(\n \"gemini-mcp-server\",\n \"gemini-mcp-redis\", \n \"pal-mcp-server\",\n \"pal-mcp-redis\",\n \"pal-mcp-log-monitor\"\n )\n \n # Remove containers\n foreach ($container in $containers) {\n try {\n $exists = docker ps -a --format \"{{.Names}}\" | Where-Object { $_ -eq $container }\n if ($exists) {\n if (!$foundArtifacts) {\n Write-Info \"One-time Docker cleanup...\"\n $foundArtifacts = $true\n }\n Write-Info \" Removing container: $container\"\n docker stop $container 2>$null | Out-Null\n docker rm $container 2>$null | Out-Null\n }\n }\n catch {\n # Ignore errors\n }\n }\n \n # Remove images\n $images = @(\"gemini-mcp-server:latest\", \"pal-mcp-server:latest\")\n foreach ($image in $images) {\n try {\n $exists = docker images --format \"{{.Repository}}:{{.Tag}}\" | Where-Object { $_ -eq $image }\n if ($exists) {\n if (!$foundArtifacts) {\n Write-Info \"One-time Docker cleanup...\"\n $foundArtifacts = $true\n }\n Write-Info \" Removing image: $image\"\n docker rmi $image 2>$null | Out-Null\n }\n }\n catch {\n # Ignore errors\n }\n }\n \n # Remove volumes\n $volumes = @(\"redis_data\", \"mcp_logs\")\n foreach ($volume in $volumes) {\n try {\n $exists = docker volume ls --format \"{{.Name}}\" | Where-Object { $_ -eq $volume }\n if ($exists) {\n if (!$foundArtifacts) {\n Write-Info \"One-time Docker cleanup...\"\n $foundArtifacts = $true\n }\n Write-Info \" Removing volume: $volume\"\n docker volume rm $volume 2>$null | Out-Null\n }\n }\n catch {\n # Ignore errors\n }\n }\n \n if ($foundArtifacts) {\n Write-Success \"Docker cleanup complete\"\n }\n \n New-Item -Path $DOCKER_CLEANED_FLAG -ItemType File -Force | Out-Null\n}\n\n# Validate API keys\nfunction Test-ApiKeys {\n Write-Step \"Validating API Keys\"\n \n if (!(Test-Path \".env\")) {\n Write-Warning \"No .env file found. API keys should be configured.\"\n return $false\n }\n \n $envContent = Get-Content \".env\"\n $hasValidKey = $false\n \n $keyPatterns = @{\n \"GEMINI_API_KEY\" = \"AIza[0-9A-Za-z-_]{35}\"\n \"OPENAI_API_KEY\" = \"sk-[a-zA-Z0-9]{20}T3BlbkFJ[a-zA-Z0-9]{20}\"\n \"XAI_API_KEY\" = \"xai-[a-zA-Z0-9-_]+\"\n \"OPENROUTER_API_KEY\" = \"sk-or-[a-zA-Z0-9-_]+\"\n }\n \n foreach ($line in $envContent) {\n if ($line -match '^([^#][^=]*?)=(.*)$') {\n $key = $matches[1].Trim()\n $value = $matches[2].Trim() -replace '^[\"'']|[\"'']$', ''\n \n if ($keyPatterns.ContainsKey($key) -and $value -ne \"your_${key.ToLower()}_here\" -and $value.Length -gt 10) {\n Write-Success \"Found valid $key\"\n $hasValidKey = $true\n }\n }\n }\n \n if (!$hasValidKey) {\n Write-Warning \"No valid API keys found in .env file\"\n Write-Info \"Please edit .env file with your actual API keys\"\n return $false\n }\n \n return $true\n}\n\n# Check if uv is available\nfunction Test-Uv {\n return Test-Command \"uv\"\n}\n\n# Setup environment using uv-first approach\nfunction Initialize-Environment {\n Write-Step \"Setting up Python Environment\"\n \n # Try uv first for faster package management\n if (Test-Uv) {\n Write-Info \"Using uv for faster package management...\"\n \n if (Test-Path $VENV_PATH) {\n if ($Force) {\n Write-Warning \"Removing existing environment...\"\n Remove-Item -Recurse -Force $VENV_PATH\n }\n else {\n Write-Success \"Virtual environment already exists\"\n $pythonPath = \"$VENV_PATH\\Scripts\\python.exe\"\n if (Test-Path $pythonPath) {\n return Get-AbsolutePath $pythonPath\n }\n }\n }\n \n try {\n Write-Info \"Creating virtual environment with uv...\"\n uv venv $VENV_PATH --python 3.12\n if ($LASTEXITCODE -eq 0) {\n Write-Success \"Environment created with uv\"\n return Get-AbsolutePath \"$VENV_PATH\\Scripts\\python.exe\"\n }\n }\n catch {\n Write-Warning \"uv failed, falling back to venv\"\n }\n }\n \n # Fallback to standard venv\n $pythonCmd = Find-Python\n if (!$pythonCmd) {\n throw \"Python 3.10+ not found\"\n }\n \n if (Test-Path $VENV_PATH) {\n if ($Force) {\n Write-Warning \"Removing existing environment...\"\n try {\n # Stop any Python processes that might be using the venv\n Get-Process python* -ErrorAction SilentlyContinue | Where-Object { $_.Path -like \"*$VENV_PATH*\" } | Stop-Process -Force -ErrorAction SilentlyContinue\n \n # Wait a moment for processes to terminate\n Start-Sleep -Seconds 2\n \n # Use the robust removal function\n if (Remove-LockedDirectory $VENV_PATH) {\n Write-Success \"Existing environment removed\"\n }\n else {\n throw \"Unable to remove existing environment. Please restart your computer and try again.\"\n }\n \n }\n catch {\n Write-Error \"Failed to remove existing environment: $_\"\n Write-Host \"\"\n Write-Host \"Try these solutions:\" -ForegroundColor Yellow\n Write-Host \"1. Close all terminals and VS Code instances\" -ForegroundColor White\n Write-Host \"2. Run: Get-Process python* | Stop-Process -Force\" -ForegroundColor White\n Write-Host \"3. Manually delete: $VENV_PATH\" -ForegroundColor White\n Write-Host \"4. Then run the script again\" -ForegroundColor White\n exit 1\n }\n }\n else {\n Write-Success \"Virtual environment already exists\"\n return Get-AbsolutePath \"$VENV_PATH\\Scripts\\python.exe\"\n }\n }\n \n Write-Info \"Creating virtual environment with $pythonCmd...\"\n if ($pythonCmd.StartsWith(\"py \")) {\n Invoke-Expression \"$pythonCmd -m venv $VENV_PATH\"\n }\n else {\n & $pythonCmd -m venv $VENV_PATH\n }\n \n if ($LASTEXITCODE -ne 0) {\n throw \"Failed to create virtual environment\"\n }\n \n Write-Success \"Virtual environment created\"\n return Get-AbsolutePath \"$VENV_PATH\\Scripts\\python.exe\"\n}\n\n# Setup virtual environment (legacy function for compatibility)\nfunction Initialize-VirtualEnvironment {\n Write-Step \"Setting up Python Virtual Environment\"\n \n if (!$SkipVenv -and (Test-Path $VENV_PATH)) {\n if ($Force) {\n Write-Warning \"Removing existing virtual environment...\"\n try {\n # Stop any Python processes that might be using the venv\n Get-Process python* -ErrorAction SilentlyContinue | Where-Object { $_.Path -like \"*$VENV_PATH*\" } | Stop-Process -Force -ErrorAction SilentlyContinue\n \n # Wait a moment for processes to terminate\n Start-Sleep -Seconds 2\n \n # Use the robust removal function\n if (Remove-LockedDirectory $VENV_PATH) {\n Write-Success \"Existing environment removed\"\n }\n else {\n throw \"Unable to remove existing environment. Please restart your computer and try again.\"\n }\n \n }\n catch {\n Write-Error \"Failed to remove existing environment: $_\"\n Write-Host \"\"\n Write-Host \"Try these solutions:\" -ForegroundColor Yellow\n Write-Host \"1. Close all terminals and VS Code instances\" -ForegroundColor White\n Write-Host \"2. Run: Get-Process python* | Stop-Process -Force\" -ForegroundColor White\n Write-Host \"3. Manually delete: $VENV_PATH\" -ForegroundColor White\n Write-Host \"4. Then run the script again\" -ForegroundColor White\n exit 1\n }\n }\n else {\n Write-Success \"Virtual environment already exists\"\n return\n }\n }\n \n if ($SkipVenv) {\n Write-Warning \"Skipping virtual environment setup\"\n return\n }\n \n $pythonCmd = Find-Python\n if (!$pythonCmd) {\n Write-Error \"Python 3.10+ not found. Please install Python from https://python.org\"\n exit 1\n }\n \n Write-Info \"Using Python: $pythonCmd\"\n Write-Info \"Creating virtual environment...\"\n \n try {\n if ($pythonCmd.StartsWith(\"py \")) {\n Invoke-Expression \"$pythonCmd -m venv $VENV_PATH\"\n }\n else {\n & $pythonCmd -m venv $VENV_PATH\n }\n \n if ($LASTEXITCODE -ne 0) {\n throw \"Failed to create virtual environment\"\n }\n \n Write-Success \"Virtual environment created\"\n }\n catch {\n Write-Error \"Failed to create virtual environment: $_\"\n exit 1\n }\n}\n\n# Install dependencies function - Simplified uv-first approach\nfunction Install-Dependencies {\n param(\n [Parameter(Mandatory = $true)]\n [string]$PythonPath,\n [switch]$InstallDevDependencies = $false\n )\n \n Write-Step \"Installing Dependencies\"\n\n # Build requirements files list\n $requirementsFiles = @(\"requirements.txt\")\n if ($InstallDevDependencies) {\n if (Test-Path \"requirements-dev.txt\") {\n $requirementsFiles += \"requirements-dev.txt\"\n Write-Info \"Including development dependencies from requirements-dev.txt\"\n }\n else {\n Write-Warning \"Development dependencies requested but requirements-dev.txt not found\"\n }\n }\n\n # Try uv first for faster package management\n $useUv = Test-Uv\n if ($useUv) {\n Write-Info \"Installing dependencies with uv (fast)...\"\n try {\n foreach ($file in $requirementsFiles) {\n Write-Info \"Installing from $file with uv...\"\n $uv = (Get-Command uv -ErrorAction Stop).Source\n $arguments = @('pip', 'install', '-r', $file, '--python', $PythonPath)\n $proc = Start-Process -FilePath $uv -ArgumentList $arguments -NoNewWindow -Wait -PassThru\n\n if ($proc.ExitCode -ne 0) { \n throw \"uv failed to install $file with exit code $($proc.ExitCode)\" \n }\n\n }\n Write-Success \"Dependencies installed successfully with uv\"\n return\n }\n catch {\n Write-Warning \"uv installation failed: $_. Falling back to pip\"\n $useUv = $false\n }\n }\n\n # Fallback to pip\n Write-Info \"Installing dependencies with pip...\"\n $pipCmd = Join-Path (Split-Path $PythonPath -Parent) \"pip.exe\"\n \n try {\n # Upgrade pip first\n & $pipCmd install --upgrade pip | Out-Null\n }\n catch {\n Write-Warning \"Could not upgrade pip, continuing...\"\n }\n\n try {\n foreach ($file in $requirementsFiles) {\n Write-Info \"Installing from $file with pip...\"\n & $pipCmd install -r $file\n if ($LASTEXITCODE -ne 0) {\n throw \"pip failed to install $file\"\n }\n }\n Write-Success \"Dependencies installed successfully with pip\"\n }\n catch {\n Write-Error \"Failed to install dependencies with pip: $_\"\n exit 1\n }\n}\n\n# ----------------------------------------------------------------------------\n# Docker Functions\n# ============================================================================\n\n# Test Docker availability and requirements\nfunction Test-DockerRequirements {\n Write-Step \"Checking Docker Requirements\"\n \n if (!(Test-Command \"docker\")) {\n Write-Error \"Docker not found. Please install Docker Desktop from https://docker.com\"\n return $false\n }\n \n try {\n $null = docker version 2>$null\n Write-Success \"Docker is installed and running\"\n }\n catch {\n Write-Error \"Docker is installed but not running. Please start Docker Desktop.\"\n return $false\n }\n \n if (!(Test-Command \"docker-compose\")) {\n Write-Warning \"docker-compose not found. Trying docker compose...\"\n try {\n $null = docker compose version 2>$null\n Write-Success \"Docker Compose (v2) is available\"\n return $true\n }\n catch {\n Write-Error \"Docker Compose not found. Please install Docker Compose.\"\n return $false\n }\n }\n else {\n Write-Success \"Docker Compose is available\"\n return $true\n }\n}\n\n# Build Docker image\nfunction Build-DockerImage {\n param([switch]$Force = $false)\n \n Write-Step \"Building Docker Image\"\n \n # Check if image exists\n try {\n $imageExists = docker images --format \"{{.Repository}}:{{.Tag}}\" | Where-Object { $_ -eq \"pal-mcp-server:latest\" }\n if ($imageExists -and !$Force) {\n Write-Success \"Docker image already exists. Use -Force to rebuild.\"\n return $true\n }\n }\n catch {\n # Continue if command fails\n }\n \n if ($Force -and $imageExists) {\n Write-Info \"Forcing rebuild of Docker image...\"\n try {\n docker rmi pal-mcp-server:latest 2>$null\n }\n catch {\n Write-Warning \"Could not remove existing image, continuing...\"\n }\n }\n \n Write-Info \"Building Docker image from Dockerfile...\"\n try {\n $buildArgs = @()\n if ($Dev) {\n # For development builds, we could add specific build args\n Write-Info \"Building with development support...\"\n }\n \n docker build -t pal-mcp-server:latest .\n if ($LASTEXITCODE -ne 0) {\n throw \"Docker build failed\"\n }\n \n Write-Success \"Docker image built successfully\"\n return $true\n }\n catch {\n Write-Error \"Failed to build Docker image: $_\"\n return $false\n }\n}\n\n# Prepare Docker environment file\nfunction Initialize-DockerEnvironment {\n Write-Step \"Preparing Docker Environment\"\n \n # Ensure .env file exists\n if (!(Test-Path \".env\")) {\n Write-Warning \"No .env file found. Creating default .env file...\"\n \n $defaultEnv = @\"\n# API Keys - Replace with your actual keys\nGEMINI_API_KEY=your_gemini_api_key_here\nGOOGLE_API_KEY=your_google_api_key_here\nOPENAI_API_KEY=your_openai_api_key_here\nANTHROPIC_API_KEY=your_anthropic_api_key_here\nXAI_API_KEY=your_xai_api_key_here\nDIAL_API_KEY=your_dial_api_key_here\nDIAL_API_HOST=your_dial_api_host_here\nDIAL_API_VERSION=your_dial_api_version_here\nOPENROUTER_API_KEY=your_openrouter_api_key_here\nCUSTOM_API_URL=your_custom_api_url_here\nCUSTOM_API_KEY=your_custom_api_key_here\nCUSTOM_MODEL_NAME=your_custom_model_name_here\n\n# Server Configuration\nDEFAULT_MODEL=auto\nLOG_LEVEL=INFO\nLOG_MAX_SIZE=10MB\nLOG_BACKUP_COUNT=5\nDEFAULT_THINKING_MODE_THINKDEEP=high\n\n# Optional Advanced Settings\n#DISABLED_TOOLS=\n#MAX_MCP_OUTPUT_TOKENS=\n#TZ=UTC\n\"@\n \n $defaultEnv | Out-File -FilePath \".env\" -Encoding UTF8\n Write-Success \"Default .env file created\"\n Write-Warning \"Please edit .env file with your actual API keys\"\n }\n else {\n Write-Success \".env file exists\"\n }\n \n # Create logs directory for volume mount\n Initialize-Logging\n \n return $true\n}\n\n# Start Docker services\nfunction Start-DockerServices {\n param([switch]$Follow = $false)\n \n Write-Step \"Starting Docker Services\"\n \n # Check if docker-compose.yml exists\n if (!(Test-Path \"docker-compose.yml\")) {\n Write-Error \"docker-compose.yml not found in current directory\"\n return $false\n }\n \n try {\n # Stop any existing services\n Write-Info \"Stopping any existing services...\"\n if (Test-Command \"docker-compose\") {\n docker-compose down 2>$null\n }\n else {\n docker compose down 2>$null\n }\n \n # Start services\n Write-Info \"Starting PAL MCP Server with Docker Compose...\"\n if (Test-Command \"docker-compose\") {\n if ($Follow) {\n docker-compose up --build\n }\n else {\n docker-compose up -d --build\n }\n }\n else {\n if ($Follow) {\n docker compose up --build\n }\n else {\n docker compose up -d --build\n }\n }\n \n if ($LASTEXITCODE -ne 0) {\n throw \"Failed to start Docker services\"\n }\n \n if (!$Follow) {\n Write-Success \"Docker services started successfully\"\n Write-Info \"Container name: pal-mcp-server\"\n Write-Host \"\"\n Write-Host \"To view logs: \" -NoNewline\n Write-Host \"docker logs -f pal-mcp-server\" -ForegroundColor Yellow\n Write-Host \"To stop: \" -NoNewline\n Write-Host \"docker-compose down\" -ForegroundColor Yellow\n }\n \n return $true\n }\n catch {\n Write-Error \"Failed to start Docker services: $_\"\n return $false\n }\n}\n\n# Get Docker container status\nfunction Get-DockerStatus {\n try {\n $containerStatus = docker ps --filter \"name=pal-mcp-server\" --format \"{{.Status}}\"\n if ($containerStatus) {\n Write-Success \"Container status: $containerStatus\"\n return $true\n }\n else {\n Write-Warning \"Container not running\"\n return $false\n }\n }\n catch {\n Write-Warning \"Could not get container status: $_\"\n return $false\n }\n}\n\n# ============================================================================\n# End Docker Functions\n# ============================================================================\n\n# Setup logging directory\nfunction Initialize-Logging {\n Write-Step \"Setting up Logging\"\n \n if (!(Test-Path $LOG_DIR)) {\n New-Item -ItemType Directory -Path $LOG_DIR -Force | Out-Null\n Write-Success \"Logs directory created\"\n }\n else {\n Write-Success \"Logs directory already exists\"\n }\n}\n\n# Check Docker\nfunction Test-Docker {\n Write-Step \"Checking Docker Setup\"\n \n if ($SkipDocker) {\n Write-Warning \"Skipping Docker checks\"\n return\n }\n \n if (Test-Command \"docker\") {\n try {\n $null = docker version 2>$null\n Write-Success \"Docker is installed and running\"\n \n if (Test-Command \"docker-compose\") {\n Write-Success \"Docker Compose is available\"\n }\n else {\n Write-Warning \"Docker Compose not found. Install Docker Desktop for Windows.\"\n }\n }\n catch {\n Write-Warning \"Docker is installed but not running. Please start Docker Desktop.\"\n }\n }\n else {\n Write-Warning \"Docker not found. Install Docker Desktop from https://docker.com\"\n }\n}\n\n# ----------------------------------------------------------------------------\n# MCP Client Configuration System\n# ----------------------------------------------------------------------------\n\n# Centralized MCP client definitions\n$script:McpClientDefinitions = @(\n @{\n Name = \"Claude Desktop\"\n DetectionPath = \"$env:APPDATA\\Claude\\claude_desktop_config.json\"\n DetectionType = \"Path\"\n ConfigPath = \"$env:APPDATA\\Claude\\claude_desktop_config.json\"\n ConfigJsonPath = \"mcpServers.pal\"\n NeedsConfigDir = $true\n },\n @{\n Name = \"VSCode\"\n DetectionCommand = \"code\"\n DetectionType = \"Command\"\n ConfigPath = \"$env:APPDATA\\Code\\User\\settings.json\"\n ConfigJsonPath = \"mcp.servers.pal\"\n IsVSCode = $true\n },\n @{\n Name = \"VSCode Insiders\"\n DetectionCommand = \"code-insiders\"\n DetectionType = \"Command\"\n ConfigPath = \"$env:APPDATA\\Code - Insiders\\User\\mcp.json\"\n ConfigJsonPath = \"servers.pal\"\n IsVSCodeInsiders = $true\n },\n @{\n Name = \"Cursor\"\n DetectionCommand = \"cursor\"\n DetectionType = \"Command\"\n ConfigPath = \"$env:USERPROFILE\\.cursor\\mcp.json\"\n ConfigJsonPath = \"mcpServers.pal\"\n },\n @{\n Name = \"Windsurf\"\n DetectionPath = \"$env:USERPROFILE\\.codeium\\windsurf\"\n DetectionType = \"Path\"\n ConfigPath = \"$env:USERPROFILE\\.codeium\\windsurf\\mcp_config.json\"\n ConfigJsonPath = \"mcpServers.pal\"\n },\n @{\n Name = \"Trae\"\n DetectionPath = \"$env:APPDATA\\Trae\"\n DetectionType = \"Path\"\n ConfigPath = \"$env:APPDATA\\Trae\\User\\mcp.json\"\n ConfigJsonPath = \"mcpServers.pal\"\n }\n)\n\n# Docker MCP configuration template (legacy, kept for backward compatibility)\n$script:DockerMcpConfig = @{\n command = \"docker\"\n args = @(\"exec\", \"-i\", \"pal-mcp-server\", \"python\", \"server.py\")\n type = \"stdio\"\n}\n\n# Generate Docker MCP configuration using docker run (recommended for all clients)\nfunction Get-DockerMcpConfigRun {\n param([string]$ServerPath)\n \n $scriptDir = Split-Path $ServerPath -Parent\n $envFile = Join-Path $scriptDir \".env\"\n \n return @{\n command = \"docker\"\n args = @(\"run\", \"--rm\", \"-i\", \"--env-file\", $envFile, \"pal-mcp-server:latest\", \"python\", \"server.py\")\n type = \"stdio\"\n }\n}\n\n# Generate Python MCP configuration\nfunction Get-PythonMcpConfig {\n param([string]$PythonPath, [string]$ServerPath)\n return @{\n command = $PythonPath\n args = @($ServerPath)\n type = \"stdio\"\n }\n}\n\n# Check if client uses mcp.json format with servers structure\nfunction Test-McpJsonFormat {\n param([hashtable]$Client)\n \n $configFileName = Split-Path $Client.ConfigPath -Leaf\n return $configFileName -eq \"mcp.json\"\n}\n\n# Check if client uses the new VS Code Insiders format (servers instead of mcpServers)\nfunction Test-VSCodeInsidersFormat {\n param([hashtable]$Client)\n \n return $Client.IsVSCodeInsiders -eq $true -and $Client.ConfigJsonPath -eq \"servers.pal\"\n}\n\n# Analyze existing MCP configuration to determine type (Python or Docker)\nfunction Get-ExistingMcpConfigType {\n param(\n [Parameter(Mandatory = $true)]\n [hashtable]$Client,\n [Parameter(Mandatory = $true)]\n [string]$ConfigPath\n )\n \n if (!(Test-Path $ConfigPath)) {\n return @{\n Exists = $false\n Type = \"None\"\n Details = \"No configuration found\"\n }\n }\n \n try {\n $content = Get-Content $ConfigPath -Raw | ConvertFrom-Json -ErrorAction SilentlyContinue\n if (!$content) {\n return @{\n Exists = $false\n Type = \"None\"\n Details = \"Invalid JSON configuration\"\n }\n }\n \n # Navigate to pal configuration\n $pathParts = $Client.ConfigJsonPath.Split('.')\n $palKey = $pathParts[-1]\n $parentPath = $pathParts[0..($pathParts.Length - 2)]\n \n $targetObject = $content\n foreach ($key in $parentPath) {\n if (!$targetObject.PSObject.Properties[$key]) {\n return @{\n Exists = $false\n Type = \"None\"\n Details = \"Configuration structure not found\"\n }\n }\n $targetObject = $targetObject.$key\n }\n \n if (!$targetObject.PSObject.Properties[$palKey]) {\n return @{\n Exists = $false\n Type = \"None\"\n Details = \"PAL configuration not found\"\n }\n }\n \n $palConfig = $targetObject.$palKey\n \n # Analyze configuration type\n if ($palConfig.command -eq \"docker\") {\n $dockerType = \"Unknown\"\n $details = \"Docker configuration\"\n \n if ($palConfig.args -and $palConfig.args.Count -gt 0) {\n if ($palConfig.args[0] -eq \"run\") {\n $dockerType = \"Docker Run\"\n $details = \"Docker run (dedicated container)\"\n }\n elseif ($palConfig.args[0] -eq \"exec\") {\n $dockerType = \"Docker Exec\"\n $details = \"Docker exec (existing container)\"\n }\n else {\n $details = \"Docker ($($palConfig.args[0]))\"\n }\n }\n \n return @{\n Exists = $true\n Type = \"Docker\"\n SubType = $dockerType\n Details = $details\n Command = $palConfig.command\n Args = $palConfig.args\n }\n }\n elseif ($palConfig.command -and $palConfig.command.EndsWith(\"python.exe\")) {\n $pythonType = \"Python\"\n $details = \"Python virtual environment\"\n \n if ($palConfig.command.Contains(\".pal_venv\")) {\n $details = \"Python (pal virtual environment)\"\n }\n elseif ($palConfig.command.Contains(\"venv\")) {\n $details = \"Python (virtual environment)\"\n }\n else {\n $details = \"Python (system installation)\"\n }\n \n return @{\n Exists = $true\n Type = \"Python\"\n SubType = $pythonType\n Details = $details\n Command = $palConfig.command\n Args = $palConfig.args\n }\n }\n else {\n return @{\n Exists = $true\n Type = \"Unknown\"\n Details = \"Unknown configuration type: $($palConfig.command)\"\n Command = $palConfig.command\n Args = $palConfig.args\n }\n }\n \n }\n catch {\n return @{\n Exists = $false\n Type = \"Error\"\n Details = \"Error reading configuration: $_\"\n }\n }\n}\n\n# Generic MCP client configuration function\nfunction Configure-McpClient {\n param(\n [Parameter(Mandatory = $true)]\n [hashtable]$Client,\n [Parameter(Mandatory = $true)]\n [bool]$UseDocker,\n [string]$PythonPath = \"\",\n [string]$ServerPath = \"\"\n )\n\n Write-Step \"Checking $($Client.Name) Integration\"\n\n # Client detection\n $detected = $false\n if ($Client.DetectionType -eq \"Command\" -and (Test-Command $Client.DetectionCommand)) {\n $detected = $true\n }\n elseif ($Client.DetectionType -eq \"Path\" -and (Test-Path ($Client.DetectionPath -as [string]))) {\n $detected = $true\n }\n\n if (!$detected) {\n Write-Info \"$($Client.Name) not detected - skipping integration\"\n return\n }\n Write-Info \"Found $($Client.Name)\"\n\n # Handle VSCode special logic for profiles\n $configPath = $Client.ConfigPath\n if ($Client.IsVSCode) {\n $userPath = Split-Path $configPath -Parent\n if (!(Test-Path $userPath)) {\n Write-Warning \"$($Client.Name) user directory not found. Skipping.\"\n return\n }\n \n # Find most recent settings.json (default or profile)\n $settingsFiles = @()\n $defaultSettings = $configPath\n if (Test-Path $defaultSettings) {\n $settingsFiles += @{\n Path = $defaultSettings\n LastModified = (Get-Item $defaultSettings).LastWriteTime\n }\n }\n \n $profilesPath = Join-Path $userPath \"profiles\"\n if (Test-Path $profilesPath) {\n Get-ChildItem $profilesPath -Directory | ForEach-Object {\n $profileSettings = Join-Path $_.FullName \"settings.json\"\n if (Test-Path $profileSettings) {\n $settingsFiles += @{\n Path = $profileSettings\n LastModified = (Get-Item $profileSettings).LastWriteTime\n }\n }\n }\n }\n \n if ($settingsFiles.Count -gt 0) {\n $configPath = ($settingsFiles | Sort-Object LastModified -Descending | Select-Object -First 1).Path\n }\n }\n\n # Handle VSCode Insiders special logic for profiles (uses mcp.json)\n if ($Client.IsVSCodeInsiders) {\n $userPath = Split-Path $configPath -Parent\n if (!(Test-Path $userPath)) {\n Write-Warning \"$($Client.Name) user directory not found. Skipping.\"\n return\n }\n \n # Find most recent mcp.json (default or profile)\n $mcpFiles = @()\n $defaultMcp = $configPath\n if (Test-Path $defaultMcp) {\n $mcpFiles += @{\n Path = $defaultMcp\n LastModified = (Get-Item $defaultMcp).LastWriteTime\n }\n }\n \n $profilesPath = Join-Path $userPath \"profiles\"\n if (Test-Path $profilesPath) {\n Get-ChildItem $profilesPath -Directory | ForEach-Object {\n $profileMcp = Join-Path $_.FullName \"mcp.json\"\n if (Test-Path $profileMcp) {\n $mcpFiles += @{\n Path = $profileMcp\n LastModified = (Get-Item $profileMcp).LastWriteTime\n }\n }\n }\n }\n \n if ($mcpFiles.Count -gt 0) {\n $configPath = ($mcpFiles | Sort-Object LastModified -Descending | Select-Object -First 1).Path\n }\n }\n\n # Check if already configured and analyze existing configuration\n $existingConfig = Get-ExistingMcpConfigType -Client $Client -ConfigPath $configPath\n $newConfigType = if ($UseDocker) { \"Docker\" } else { \"Python\" }\n \n if ($existingConfig.Exists) {\n Write-Info \"Found existing PAL MCP configuration in $($Client.Name)\"\n Write-Info \" Current: $($existingConfig.Details)\"\n Write-Info \" New: $newConfigType configuration\"\n \n if ($existingConfig.Type -eq $newConfigType) {\n Write-Warning \"Same configuration type ($($existingConfig.Type)) already exists\"\n $response = Read-Host \"`nOverwrite existing $($existingConfig.Type) configuration? (y/N)\"\n }\n else {\n Write-Warning \"Different configuration type detected\"\n Write-Info \" Replacing: $($existingConfig.Type) β†’ $newConfigType\"\n $response = Read-Host \"`nReplace $($existingConfig.Type) with $newConfigType configuration? (y/N)\"\n }\n \n if ($response -ne 'y' -and $response -ne 'Y') {\n Write-Info \"Keeping existing configuration in $($Client.Name)\"\n return\n }\n \n Write-Info \"Proceeding with configuration update...\"\n }\n else {\n # User confirmation for new installation\n $response = Read-Host \"`nConfigure PAL MCP for $($Client.Name) (mode: $newConfigType)? (y/N)\"\n if ($response -ne 'y' -and $response -ne 'Y') {\n Write-Info \"Skipping $($Client.Name) integration\"\n return\n }\n }\n\n try {\n # Create config directory if needed\n $configDir = Split-Path $configPath -Parent\n if (!(Test-Path $configDir)) {\n New-Item -ItemType Directory -Path $configDir -Force | Out-Null\n }\n\n # Backup existing config\n if (Test-Path $configPath) {\n Manage-ConfigBackups -ConfigFilePath $configPath\n }\n\n # Read or create config\n $config = New-Object PSObject\n $usesMcpJsonFormat = Test-McpJsonFormat -Client $Client\n $usesVSCodeInsidersFormat = Test-VSCodeInsidersFormat -Client $Client\n \n if (Test-Path $configPath) {\n $fileContent = Get-Content $configPath -Raw\n if ($fileContent.Trim()) {\n $config = $fileContent | ConvertFrom-Json -ErrorAction SilentlyContinue\n }\n if ($null -eq $config) { $config = New-Object PSObject }\n }\n \n # Initialize structure for mcp.json format files if they don't exist or are empty\n if ($usesMcpJsonFormat) {\n if ($usesVSCodeInsidersFormat) {\n # For VS Code Insiders format: {\"servers\": {...}}\n if (!$config.PSObject.Properties[\"servers\"]) {\n $config | Add-Member -MemberType NoteProperty -Name \"servers\" -Value (New-Object PSObject)\n }\n }\n else {\n # For other clients format: {\"mcpServers\": {...}}\n if (!$config.PSObject.Properties[\"mcpServers\"]) {\n $config | Add-Member -MemberType NoteProperty -Name \"mcpServers\" -Value (New-Object PSObject)\n }\n }\n }\n \n # Initialize MCP structure for VS Code settings.json if it doesn't exist\n if ($Client.IsVSCode -and $Client.ConfigJsonPath.StartsWith(\"mcp.\")) {\n if (!$config.PSObject.Properties[\"mcp\"]) {\n $config | Add-Member -MemberType NoteProperty -Name \"mcp\" -Value (New-Object PSObject)\n }\n if (!$config.mcp.PSObject.Properties[\"servers\"]) {\n $config.mcp | Add-Member -MemberType NoteProperty -Name \"servers\" -Value (New-Object PSObject)\n }\n }\n\n # Generate server config\n $serverConfig = if ($UseDocker) { \n # Use docker run for all clients (more reliable than docker exec)\n Get-DockerMcpConfigRun $ServerPath\n }\n else { \n Get-PythonMcpConfig $PythonPath $ServerPath \n }\n\n # Navigate and set configuration\n $pathParts = $Client.ConfigJsonPath.Split('.')\n $palKey = $pathParts[-1]\n $parentPath = $pathParts[0..($pathParts.Length - 2)]\n \n $targetObject = $config\n foreach ($key in $parentPath) {\n if (!$targetObject.PSObject.Properties[$key]) {\n $targetObject | Add-Member -MemberType NoteProperty -Name $key -Value (New-Object PSObject)\n }\n $targetObject = $targetObject.$key\n }\n\n # Remove legacy zen entries to avoid duplicate or broken MCP servers\n $legacyRemoved = Remove-LegacyServerKeys $targetObject\n if ($legacyRemoved) {\n Write-Info \"Removed legacy MCP entries (zen β†’ pal)\"\n }\n\n $targetObject | Add-Member -MemberType NoteProperty -Name $palKey -Value $serverConfig -Force\n\n # Write config\n $config | ConvertTo-Json -Depth 10 | Out-File $configPath -Encoding UTF8\n Write-Success \"Successfully configured $($Client.Name)\"\n Write-Host \" Config: $configPath\" -ForegroundColor Gray\n Write-Host \" Restart $($Client.Name) to use the new MCP server\" -ForegroundColor Gray\n\n }\n catch {\n Write-Error \"Failed to update $($Client.Name) configuration: $_\"\n }\n}\n\n# Main MCP client configuration orchestrator\nfunction Invoke-McpClientConfiguration {\n param(\n [Parameter(Mandatory = $true)]\n [bool]$UseDocker,\n [string]$PythonPath = \"\",\n [string]$ServerPath = \"\"\n )\n \n Write-Step \"Checking Client Integrations\"\n \n # Configure GUI clients\n foreach ($client in $script:McpClientDefinitions) {\n Configure-McpClient -Client $client -UseDocker $UseDocker -PythonPath $PythonPath -ServerPath $ServerPath\n }\n \n # Handle CLI tools separately (they don't follow JSON config pattern)\n if (!$UseDocker) {\n Test-ClaudeCliIntegration $PythonPath $ServerPath\n Test-GeminiCliIntegration (Split-Path $ServerPath -Parent)\n Test-QwenCliIntegration $PythonPath $ServerPath\n }\n}\n\n# Keep existing CLI integration functions\nfunction Test-ClaudeCliIntegration {\n param([string]$PythonPath, [string]$ServerPath)\n \n if (!(Test-Command \"claude\")) {\n return\n }\n \n Write-Info \"Claude CLI detected - checking configuration...\"\n\n foreach ($legacy in $script:LegacyServerNames) {\n try { claude mcp remove -s user $legacy 2>$null | Out-Null } catch {}\n }\n \n try {\n $claudeConfig = claude mcp list 2>$null\n if ($claudeConfig -match \"pal\") {\n Write-Success \"Claude CLI already configured for pal server\"\n }\n else {\n Write-Info \"To add pal server to Claude CLI, run:\"\n Write-Host \" claude mcp add -s user pal $PythonPath $ServerPath\" -ForegroundColor Cyan\n }\n }\n catch {\n Write-Info \"To configure Claude CLI manually, run:\"\n Write-Host \" claude mcp add -s user pal $PythonPath $ServerPath\" -ForegroundColor Cyan\n }\n}\n\nfunction Test-GeminiCliIntegration {\n param([string]$ScriptDir)\n \n $palWrapper = Join-Path $ScriptDir \"pal-mcp-server.cmd\"\n \n # Check if Gemini settings file exists (Windows path)\n $geminiConfig = \"$env:USERPROFILE\\.gemini\\settings.json\"\n if (!(Test-Path $geminiConfig)) {\n return\n }\n\n # Load existing config\n $config = @{}\n $configContent = Get-Content $geminiConfig -Raw -ErrorAction SilentlyContinue\n if ($configContent) {\n try { $config = $configContent | ConvertFrom-Json -ErrorAction Stop } catch { $config = @{} }\n }\n if ($null -eq $config -or $config -isnot [System.Collections.IDictionary]) {\n $config = @{}\n }\n\n if (-not $config.mcpServers -or $config.mcpServers -isnot [System.Collections.IDictionary]) {\n $config.mcpServers = [ordered]@{}\n }\n\n $legacyRemoved = Remove-LegacyServerKeys $config.mcpServers\n $palConfig = $config.mcpServers.pal\n $needsWrite = $legacyRemoved\n\n if ($palConfig) {\n if ($palConfig.command -ne $palWrapper) {\n $palConfig.command = $palWrapper\n $needsWrite = $true\n }\n\n if (!(Test-Path $palWrapper)) {\n Write-Info \"Creating wrapper script for Gemini CLI...\"\n @\"\n@echo off\ncd /d \"%~dp0\"\nif exist \".pal_venv\\Scripts\\python.exe\" (\n .pal_venv\\Scripts\\python.exe server.py %*\n) else (\n python server.py %*\n)\n\"@ | Out-File -FilePath $palWrapper -Encoding ASCII\n Write-Success \"Created pal-mcp-server.cmd wrapper script\"\n }\n\n if ($needsWrite) {\n Manage-ConfigBackups -ConfigFilePath $geminiConfig | Out-Null\n $config | ConvertTo-Json -Depth 10 | Out-File $geminiConfig -Encoding UTF8\n Write-Success \"Updated Gemini CLI configuration (cleaned legacy entries)\"\n Write-Host \" Config: $geminiConfig\" -ForegroundColor Gray\n Write-Host \" Restart Gemini CLI to use PAL MCP Server\" -ForegroundColor Gray\n }\n return\n }\n\n # Ask user if they want to add PAL to Gemini CLI\n Write-Host \"\"\n $response = Read-Host \"Configure PAL for Gemini CLI? (y/N)\"\n if ($response -ne 'y' -and $response -ne 'Y') {\n Write-Info \"Skipping Gemini CLI integration\"\n return\n }\n \n # Ensure wrapper script exists\n if (!(Test-Path $palWrapper)) {\n Write-Info \"Creating wrapper script for Gemini CLI...\"\n @\"\n@echo off\ncd /d \"%~dp0\"\nif exist \".pal_venv\\Scripts\\python.exe\" (\n .pal_venv\\Scripts\\python.exe server.py %*\n) else (\n python server.py %*\n)\n\"@ | Out-File -FilePath $palWrapper -Encoding ASCII\n \n Write-Success \"Created pal-mcp-server.cmd wrapper script\"\n }\n \n # Update Gemini settings\n Write-Info \"Updating Gemini CLI configuration...\"\n \n try {\n # Create backup with retention management\n $backupPath = Manage-ConfigBackups $geminiConfig\n \n # Ensure mcpServers exists\n if (-not $config.mcpServers -or $config.mcpServers -isnot [System.Collections.IDictionary]) {\n $config.mcpServers = [ordered]@{}\n }\n \n # Add pal server\n $palConfig = @{\n command = $palWrapper\n }\n \n $config.mcpServers | Add-Member -MemberType NoteProperty -Name \"pal\" -Value $palConfig -Force\n \n # Write updated config\n $config | ConvertTo-Json -Depth 10 | Out-File $geminiConfig -Encoding UTF8\n \n Write-Success \"Successfully configured Gemini CLI\"\n Write-Host \" Config: $geminiConfig\" -ForegroundColor Gray\n Write-Host \" Restart Gemini CLI to use PAL MCP Server\" -ForegroundColor Gray\n \n }\n catch {\n Write-Error \"Failed to update Gemini CLI config: $_\"\n Write-Host \"\"\n Write-Host \"Manual config location: $geminiConfig\"\n Write-Host \"Add this configuration:\"\n Write-Host @\"\n{\n \"mcpServers\": {\n \"pal\": {\n \"command\": \"$palWrapper\"\n }\n }\n}\n\"@ -ForegroundColor Yellow\n }\n} \n\nfunction Show-QwenManualConfig {\n param(\n [string]$PythonPath,\n [string]$ServerPath,\n [string]$ScriptDir,\n [string]$ConfigPath,\n [System.Collections.IDictionary]$EnvironmentMap\n )\n\n Write-Host \"Manual config location: $ConfigPath\" -ForegroundColor Yellow\n Write-Host \"Add or update this entry:\" -ForegroundColor Yellow\n\n if ($EnvironmentMap -and $EnvironmentMap.Count -gt 0) {\n $pairs = $EnvironmentMap.GetEnumerator() | ForEach-Object {\n $escaped = ($_.Value -replace '\\\\', '\\\\\\\\' -replace '\"', '\\\\\"')\n ' \"{0}\": \"{1}\"' -f $_.Key, $escaped\n }\n\n Write-Host \"{\" -ForegroundColor Yellow\n Write-Host \" \\\"mcpServers\\\": {\" -ForegroundColor Yellow\n Write-Host \" \\\"pal\\\": {\" -ForegroundColor Yellow\n Write-Host \" \\\"command\\\": \\\"$PythonPath\\\",\" -ForegroundColor Yellow\n Write-Host \" \\\"args\\\": [\\\"$ServerPath\\\"],\" -ForegroundColor Yellow\n Write-Host \" \\\"cwd\\\": \\\"$ScriptDir\\\",\" -ForegroundColor Yellow\n Write-Host \" \\\"env\\\": {\" -ForegroundColor Yellow\n Write-Host ($pairs -join \"`n\") -ForegroundColor Yellow\n Write-Host \" }\" -ForegroundColor Yellow\n Write-Host \" }\" -ForegroundColor Yellow\n Write-Host \" }\" -ForegroundColor Yellow\n Write-Host \"}\" -ForegroundColor Yellow\n }\n else {\n Write-Host \"{\" -ForegroundColor Yellow\n Write-Host \" \\\"mcpServers\\\": {\" -ForegroundColor Yellow\n Write-Host \" \\\"pal\\\": {\" -ForegroundColor Yellow\n Write-Host \" \\\"command\\\": \\\"$PythonPath\\\",\" -ForegroundColor Yellow\n Write-Host \" \\\"args\\\": [\\\"$ServerPath\\\"],\" -ForegroundColor Yellow\n Write-Host \" \\\"cwd\\\": \\\"$ScriptDir\\\"\" -ForegroundColor Yellow\n Write-Host \" }\" -ForegroundColor Yellow\n Write-Host \" }\" -ForegroundColor Yellow\n Write-Host \"}\" -ForegroundColor Yellow\n }\n}\n\nfunction Test-QwenCliIntegration {\n param([string]$PythonPath, [string]$ServerPath)\n\n if (!(Test-Command \"qwen\")) {\n return\n }\n\n Write-Info \"Qwen CLI detected - checking configuration...\"\n\n $configPath = Join-Path $env:USERPROFILE \".qwen\\settings.json\"\n $configDir = Split-Path $configPath -Parent\n $scriptDir = Split-Path $ServerPath -Parent\n\n $configStatus = \"missing\"\n $legacyRemoved = $false\n $skipPrompt = $false\n $config = @{}\n\n if (Test-Path $configPath) {\n try {\n Add-Type -AssemblyName System.Web.Extensions -ErrorAction SilentlyContinue\n $serializer = New-Object System.Web.Script.Serialization.JavaScriptSerializer\n $serializer.MaxJsonLength = 67108864\n $rawJson = Get-Content $configPath -Raw\n $config = $serializer.DeserializeObject($rawJson)\n if (-not ($config -is [System.Collections.IDictionary])) {\n $config = @{}\n }\n\n if ($config.ContainsKey('mcpServers') -and $config['mcpServers'] -is [System.Collections.IDictionary]) {\n $servers = $config['mcpServers']\n $legacyRemoved = (Remove-LegacyServerKeys $servers) -or $legacyRemoved\n if ($servers.Contains('pal') -and $servers['pal'] -is [System.Collections.IDictionary]) {\n $palConfig = $servers['pal']\n $commandMatches = ($palConfig['command'] -eq $PythonPath)\n\n $argsValue = $palConfig['args']\n $argsList = @()\n if ($argsValue -is [System.Collections.IEnumerable] -and $argsValue -isnot [string]) {\n $argsList = @($argsValue)\n }\n elseif ($null -ne $argsValue) {\n $argsList = @($argsValue)\n }\n $argsMatches = ($argsList.Count -eq 1 -and $argsList[0] -eq $ServerPath)\n\n $cwdValue = $null\n if ($palConfig.Contains('cwd')) {\n $cwdValue = $palConfig['cwd']\n }\n $cwdMatches = ([string]::IsNullOrEmpty($cwdValue) -or $cwdValue -eq $scriptDir)\n\n if ($commandMatches -and $argsMatches -and $cwdMatches) {\n $configStatus = $legacyRemoved ? \"cleanup\" : \"match\"\n }\n else {\n $configStatus = \"mismatch\"\n Write-Warning \"Existing Qwen CLI configuration differs from the current setup.\"\n }\n }\n }\n }\n catch {\n $configStatus = \"invalid\"\n Write-Warning \"Unable to parse Qwen CLI settings at $configPath ($_).\"\n $config = @{}\n }\n }\n\n $envMap = [ordered]@{}\n if (Test-Path \".env\") {\n foreach ($line in Get-Content \".env\") {\n $trimmed = $line.Trim()\n if ([string]::IsNullOrWhiteSpace($trimmed) -or $trimmed.StartsWith('#')) {\n continue\n }\n\n if ($line -match '^\\s*([^=]+)=(.*)$') {\n $key = $matches[1].Trim()\n $value = $matches[2]\n $value = ($value -replace '\\s+#.*$', '').Trim()\n if ($value.StartsWith('\"') -and $value.EndsWith('\"')) {\n $value = $value.Substring(1, $value.Length - 2)\n }\n if ([string]::IsNullOrWhiteSpace($value)) {\n $value = [Environment]::GetEnvironmentVariable($key, \"Process\")\n }\n if (![string]::IsNullOrWhiteSpace($value) -and $value -notmatch '^your_.*_here$') {\n $envMap[$key] = $value\n }\n }\n }\n }\n\n $extraKeys = @(\n \"GEMINI_API_KEY\", \"OPENAI_API_KEY\", \"XAI_API_KEY\", \"DIAL_API_KEY\", \"OPENROUTER_API_KEY\",\n \"AZURE_OPENAI_API_KEY\", \"AZURE_OPENAI_ENDPOINT\", \"AZURE_OPENAI_API_VERSION\", \"AZURE_OPENAI_ALLOWED_MODELS\", \"AZURE_MODELS_CONFIG_PATH\",\n \"CUSTOM_API_URL\", \"CUSTOM_API_KEY\", \"CUSTOM_MODEL_NAME\", \"DEFAULT_MODEL\", \"GOOGLE_ALLOWED_MODELS\",\n \"OPENAI_ALLOWED_MODELS\", \"OPENROUTER_ALLOWED_MODELS\", \"XAI_ALLOWED_MODELS\", \"DEFAULT_THINKING_MODE_THINKDEEP\",\n \"DISABLED_TOOLS\", \"CONVERSATION_TIMEOUT_HOURS\", \"MAX_CONVERSATION_TURNS\", \"LOG_LEVEL\", \"PAL_MCP_FORCE_ENV_OVERRIDE\"\n )\n\n foreach ($key in $extraKeys) {\n if (-not $envMap.Contains($key)) {\n $value = [Environment]::GetEnvironmentVariable($key, \"Process\")\n if (![string]::IsNullOrWhiteSpace($value) -and $value -notmatch '^your_.*_here$') {\n $envMap[$key] = $value\n }\n }\n }\n\n if ($configStatus -eq \"match\") {\n Write-Success \"Qwen CLI already configured for pal server\"\n return\n }\n\n if ($configStatus -eq \"cleanup\") {\n Write-Info \"Removing legacy Qwen MCP entries from previous zen configuration...\"\n $skipPrompt = $true\n }\n\n $prompt = \"Configure PAL for Qwen CLI? (y/N)\"\n if ($configStatus -eq \"cleanup\") {\n $prompt = \"Remove legacy Qwen MCP entries and refresh configuration? (Y/n)\"\n }\n elseif ($configStatus -eq \"mismatch\" -or $configStatus -eq \"invalid\") {\n $prompt = \"Update Qwen CLI pal configuration? (y/N)\"\n }\n\n if (-not $skipPrompt) {\n $response = Read-Host $prompt\n if ($response -ne 'y' -and $response -ne 'Y') {\n Write-Info \"Skipping Qwen CLI integration\"\n Show-QwenManualConfig $PythonPath $ServerPath $scriptDir $configPath $envMap\n return\n }\n }\n\n if (!(Test-Path $configDir)) {\n New-Item -ItemType Directory -Path $configDir -Force | Out-Null\n }\n\n if (Test-Path $configPath -and $configStatus -ne \"missing\") {\n Manage-ConfigBackups $configPath | Out-Null\n }\n\n try {\n if (-not ($config -is [System.Collections.IDictionary])) {\n $config = @{}\n }\n\n if (-not $config.ContainsKey('mcpServers') -or $config['mcpServers'] -isnot [System.Collections.IDictionary]) {\n $config['mcpServers'] = @{}\n }\n\n $palConfig = [ordered]@{\n command = $PythonPath\n args = @($ServerPath)\n cwd = $scriptDir\n }\n\n if ($envMap.Count -gt 0) {\n $palConfig['env'] = $envMap\n }\n\n $config['mcpServers']['pal'] = $palConfig\n\n $json = ($config | ConvertTo-Json -Depth 20)\n Set-Content -Path $configPath -Value $json -Encoding UTF8\n\n Write-Success \"Successfully configured Qwen CLI\"\n Write-Host \" Config: $configPath\" -ForegroundColor Gray\n Write-Host \" Restart Qwen CLI to use PAL MCP Server\" -ForegroundColor Gray\n }\n catch {\n Write-Error \"Failed to update Qwen CLI configuration: $_\"\n Show-QwenManualConfig $PythonPath $ServerPath $scriptDir $configPath $envMap\n }\n}\n\n\n# ----------------------------------------------------------------------------\n# End MCP Client Configuration System\n# ----------------------------------------------------------------------------\n\n# ----------------------------------------------------------------------------\n# User Interface Functions\n# ----------------------------------------------------------------------------\n\n# Show script help\nfunction Show-Help {\n Write-Host @\"\nPAL MCP Server - Setup and Launch Script\n\nUSAGE:\n.\\run-server.ps1 [OPTIONS]\n\nOPTIONS:\n-Help Show this help message\n-Version Show version information\n-Follow Follow server logs in real time\n-Config Show configuration instructions for MCP clients\n-ClearCache Clear Python cache files and exit\n-Force Force recreation of Python virtual environment\n-Dev Install development dependencies from requirements-dev.txt\n-Docker Use Docker instead of Python virtual environment\n-SkipVenv Skip Python virtual environment creation\n-SkipDocker Skip Docker checks and cleanup\n\nEXAMPLES:\n.\\run-server.ps1 # Normal startup\n.\\run-server.ps1 -Follow # Start and follow logs\n.\\run-server.ps1 -Config # Show configuration help\n.\\run-server.ps1 -Dev # Include development dependencies\n.\\run-server.ps1 -Docker # Use Docker deployment\n.\\run-server.ps1 -Docker -Follow # Docker with log following\n\nFor more information, visit: https://github.com/BeehiveInnovations/pal-mcp-server\n\"@ -ForegroundColor White\n}\n\n# Show version information\nfunction Show-Version {\n $version = Get-Version\n Write-Host \"PAL MCP Server version: $version\" -ForegroundColor Green\n Write-Host \"PowerShell Setup Script for Windows\" -ForegroundColor Cyan\n Write-Host \"Author: GiGiDKR (https://github.com/GiGiDKR)\" -ForegroundColor Gray\n Write-Host \"Project: BeehiveInnovations/pal-mcp-server\" -ForegroundColor Gray\n}\n\n# Show configuration instructions\nfunction Show-ConfigInstructions {\n param(\n [string]$PythonPath = \"\",\n [string]$ServerPath = \"\",\n [switch]$UseDocker = $false\n )\n \n Write-Step \"Configuration Instructions\"\n \n if ($UseDocker) {\n Write-Host \"Docker Configuration:\" -ForegroundColor Yellow\n Write-Host \"The MCP clients have been configured to use Docker containers.\" -ForegroundColor White\n Write-Host \"Make sure the Docker container is running with: docker-compose up -d\" -ForegroundColor Cyan\n Write-Host \"\"\n }\n else {\n Write-Host \"Python Virtual Environment Configuration:\" -ForegroundColor Yellow\n Write-Host \"Python Path: $PythonPath\" -ForegroundColor Cyan\n Write-Host \"Server Path: $ServerPath\" -ForegroundColor Cyan\n Write-Host \"\"\n }\n \n Write-Host \"Supported MCP Clients:\" -ForegroundColor Green\n Write-Host \"βœ“ Claude Desktop\" -ForegroundColor White\n Write-Host \"βœ“ Claude CLI\" -ForegroundColor White \n Write-Host \"βœ“ VSCode (with MCP extension)\" -ForegroundColor White\n Write-Host \"βœ“ VSCode Insiders\" -ForegroundColor White\n Write-Host \"βœ“ Cursor\" -ForegroundColor White\n Write-Host \"βœ“ Windsurf\" -ForegroundColor White\n Write-Host \"βœ“ Trae\" -ForegroundColor White\n Write-Host \"βœ“ Gemini CLI\" -ForegroundColor White\n Write-Host \"βœ“ Qwen CLI\" -ForegroundColor White\n Write-Host \"\"\n Write-Host \"The script automatically detects and configures compatible clients.\" -ForegroundColor Gray\n Write-Host \"Restart your MCP clients after configuration to use the PAL MCP Server.\" -ForegroundColor Yellow\n}\n\n# Show setup instructions\nfunction Show-SetupInstructions {\n param(\n [string]$PythonPath = \"\",\n [string]$ServerPath = \"\",\n [switch]$UseDocker = $false\n )\n \n Write-Step \"Setup Complete\"\n \n if ($UseDocker) {\n Write-Success \"PAL MCP Server is configured for Docker deployment\"\n Write-Host \"Docker command: docker exec -i pal-mcp-server python server.py\" -ForegroundColor Cyan\n }\n else {\n Write-Success \"PAL MCP Server is configured for Python virtual environment\"\n Write-Host \"Python: $PythonPath\" -ForegroundColor Cyan\n Write-Host \"Server: $ServerPath\" -ForegroundColor Cyan\n }\n \n Write-Host \"\"\n Write-Host \"MCP clients will automatically connect to the server.\" -ForegroundColor Green\n Write-Host \"For manual configuration, use the paths shown above.\" -ForegroundColor Gray\n}\n\n# Start the server\nfunction Start-Server {\n Write-Step \"Starting PAL MCP Server\"\n \n $pythonPath = \"$VENV_PATH\\Scripts\\python.exe\"\n if (!(Test-Path $pythonPath)) {\n Write-Error \"Python virtual environment not found. Please run setup first.\"\n return\n }\n \n $serverPath = \"server.py\"\n if (!(Test-Path $serverPath)) {\n Write-Error \"Server script not found: $serverPath\"\n return\n }\n \n try {\n Write-Info \"Launching server...\"\n & $pythonPath $serverPath\n }\n catch {\n Write-Error \"Failed to start server: $_\"\n }\n}\n\n# Follow server logs\nfunction Follow-Logs {\n Write-Step \"Following Server Logs\"\n \n $logPath = Join-Path $LOG_DIR $LOG_FILE\n \n if (!(Test-Path $logPath)) {\n Write-Warning \"Log file not found: $logPath\"\n Write-Info \"Starting server to generate logs...\"\n Start-Server\n return\n }\n \n try {\n Write-Info \"Following logs at: $logPath\"\n Write-Host \"Press Ctrl+C to stop following logs\"\n Write-Host \"\"\n Get-Content $logPath -Wait\n }\n catch {\n Write-Error \"Failed to follow logs: $_\"\n }\n}\n\n# ----------------------------------------------------------------------------\n# Environment File Management\n# ----------------------------------------------------------------------------\n\n# Initialize .env file if it doesn't exist\nfunction Initialize-EnvFile {\n Write-Step \"Setting up Environment File\"\n \n if (!(Test-Path \".env\")) {\n Write-Info \"Creating default .env file...\"\n @\"\n# API Keys - Replace with your actual keys\nGEMINI_API_KEY=your_gemini_api_key_here\nGOOGLE_API_KEY=your_google_api_key_here\nOPENAI_API_KEY=your_openai_api_key_here\nANTHROPIC_API_KEY=your_anthropic_api_key_here\nXAI_API_KEY=your_xai_api_key_here\nDIAL_API_KEY=your_dial_api_key_here\nDIAL_API_HOST=your_dial_api_host_here\nDIAL_API_VERSION=your_dial_api_version_here\nOPENROUTER_API_KEY=your_openrouter_api_key_here\nCUSTOM_API_URL=your_custom_api_url_here\nCUSTOM_API_KEY=your_custom_api_key_here\nCUSTOM_MODEL_NAME=your_custom_model_name_here\n\n# Server Configuration\nDEFAULT_MODEL=auto\nLOG_LEVEL=INFO\nLOG_MAX_SIZE=10MB\nLOG_BACKUP_COUNT=5\nDEFAULT_THINKING_MODE_THINKDEEP=high\n\n# Optional Advanced Settings\n#DISABLED_TOOLS=\n#MAX_MCP_OUTPUT_TOKENS=\n#TZ=UTC\n\"@ | Out-File -FilePath \".env\" -Encoding UTF8\n \n Write-Success \"Default .env file created\"\n Write-Warning \"Please edit .env file with your actual API keys\"\n }\n else {\n Write-Success \".env file already exists\"\n }\n}\n\n# Import environment variables from .env file\nfunction Import-EnvFile {\n if (!(Test-Path \".env\")) {\n Write-Warning \"No .env file found\"\n return\n }\n \n try {\n $envContent = Get-Content \".env\" -ErrorAction Stop\n foreach ($line in $envContent) {\n if ($line -match '^([^#][^=]*?)=(.*)$') {\n $key = $matches[1].Trim()\n $value = $matches[2].Trim() -replace '^[\"'']|[\"'']$', ''\n \n # Set environment variable for the current session\n [Environment]::SetEnvironmentVariable($key, $value, \"Process\")\n }\n }\n Write-Success \"Environment variables loaded from .env file\"\n }\n catch {\n Write-Warning \"Could not load .env file: $_\"\n }\n}\n\n# ----------------------------------------------------------------------------\n# Workflow Functions\n# ----------------------------------------------------------------------------\n\n# Docker deployment workflow\nfunction Invoke-DockerWorkflow {\n Write-Step \"Starting Docker Workflow\"\n Write-Host \"PAL MCP Server\" -ForegroundColor Green\n Write-Host \"=================\" -ForegroundColor Cyan\n \n $version = Get-Version\n Write-Host \"Version: $version\"\n Write-Host \"Mode: Docker Container\" -ForegroundColor Yellow\n Write-Host \"\"\n \n # Docker setup and validation\n if (!(Test-DockerRequirements)) { exit 1 }\n if (!(Initialize-DockerEnvironment)) { exit 1 }\n \n Import-EnvFile\n Test-ApiKeys\n \n if (!(Build-DockerImage -Force:$Force)) { exit 1 }\n \n # Configure MCP clients for Docker\n Invoke-McpClientConfiguration -UseDocker $true\n \n Show-SetupInstructions -UseDocker\n \n # Start Docker services\n Write-Step \"Starting PAL MCP Server\"\n if ($Follow) {\n Write-Info \"Starting server and following logs...\"\n Start-DockerServices -Follow\n exit 0\n }\n \n if (!(Start-DockerServices)) { exit 1 }\n \n Write-Host \"\"\n Write-Success \"PAL MCP Server is running in Docker!\"\n Write-Host \"\"\n \n Write-Host \"Next steps:\" -ForegroundColor Cyan\n Write-Host \"1. Restart your MCP clients (Claude Desktop, etc.)\" -ForegroundColor White\n Write-Host \"2. The server is now ready to use\" -ForegroundColor White\n Write-Host \"\"\n Write-Host \"Useful commands:\" -ForegroundColor Cyan\n Write-Host \" View logs: \" -NoNewline -ForegroundColor White\n Write-Host \"docker logs -f pal-mcp-server\" -ForegroundColor Yellow\n Write-Host \" Stop server: \" -NoNewline -ForegroundColor White\n Write-Host \"docker-compose down\" -ForegroundColor Yellow\n Write-Host \" Restart server: \" -NoNewline -ForegroundColor White\n Write-Host \"docker-compose restart\" -ForegroundColor Yellow\n}\n\n# Python virtual environment deployment workflow\nfunction Invoke-PythonWorkflow {\n Write-Step \"Starting Python Virtual Environment Workflow\"\n Write-Host \"PAL MCP Server\" -ForegroundColor Green\n Write-Host \"=================\" -ForegroundColor Cyan\n \n $version = Get-Version\n Write-Host \"Version: $version\"\n Write-Host \"\"\n \n if (!(Test-Path $VENV_PATH)) {\n Write-Info \"Setting up Python environment for first time...\"\n }\n \n # Python environment setup\n Cleanup-Docker\n Clear-PythonCache\n Initialize-EnvFile\n Import-EnvFile\n Test-ApiKeys\n \n try {\n $pythonPath = Initialize-Environment\n }\n catch {\n Write-Error \"Failed to setup Python environment: $_\"\n exit 1\n }\n \n try {\n Install-Dependencies $pythonPath -InstallDevDependencies:$Dev\n }\n catch {\n Write-Error \"Failed to install dependencies: $_\"\n exit 1\n }\n \n $serverPath = Get-AbsolutePath \"server.py\"\n \n # Configure MCP clients for Python\n Invoke-McpClientConfiguration -UseDocker $false -PythonPath $pythonPath -ServerPath $serverPath\n \n Show-SetupInstructions $pythonPath $serverPath\n Initialize-Logging\n \n Write-Host \"\"\n Write-Host \"Logs will be written to: $(Get-AbsolutePath $LOG_DIR)\\$LOG_FILE\"\n Write-Host \"\"\n \n if ($Follow) {\n Follow-Logs\n }\n else {\n Write-Host \"To follow logs: .\\run-server.ps1 -Follow\" -ForegroundColor Yellow\n Write-Host \"To show config: .\\run-server.ps1 -Config\" -ForegroundColor Yellow\n Write-Host \"To update: git pull, then run .\\run-server.ps1 again\" -ForegroundColor Yellow\n Write-Host \"\"\n Write-Host \"Happy coding! πŸŽ‰\" -ForegroundColor Green\n \n $response = Read-Host \"`nStart the server now? (y/N)\"\n if ($response -eq 'y' -or $response -eq 'Y') {\n Start-Server\n }\n }\n}\n\n# ----------------------------------------------------------------------------\n# End Workflow Functions\n# ----------------------------------------------------------------------------\n\n# ----------------------------------------------------------------------------\n# Main Execution\n# ----------------------------------------------------------------------------\n\n# Main execution function\nfunction Start-MainProcess {\n # Parse command line arguments\n if ($Help) {\n Show-Help\n exit 0\n }\n \n if ($Version) {\n Show-Version \n exit 0\n }\n \n if ($ClearCache) {\n Clear-PythonCache\n Write-Success \"Cache cleared successfully\"\n Write-Host \"\"\n Write-Host \"You can now run '.\\run-server.ps1' normally\"\n exit 0\n }\n \n if ($Config) {\n # Setup minimal environment to get paths for config display\n Write-Info \"Setting up environment for configuration display...\"\n Write-Host \"\"\n try {\n if ($Docker) {\n # Docker configuration mode\n if (!(Test-DockerRequirements)) {\n exit 1\n }\n Initialize-DockerEnvironment\n Show-ConfigInstructions \"\" \"\" -UseDocker\n }\n else {\n # Python virtual environment configuration mode\n $pythonPath = Initialize-Environment\n $serverPath = Get-AbsolutePath \"server.py\"\n Show-ConfigInstructions $pythonPath $serverPath\n }\n }\n catch {\n Write-Error \"Failed to setup environment for configuration: $_\"\n exit 1\n }\n exit 0\n }\n\n # ============================================================================\n # Docker Workflow\n # ============================================================================\n if ($Docker) {\n Invoke-DockerWorkflow\n exit 0\n }\n\n # ============================================================================\n # Python Virtual Environment Workflow (Default)\n # ============================================================================\n Invoke-PythonWorkflow\n exit 0\n}\n\n# ============================================================================\n# Main Script Execution\n# ============================================================================\n\n# Execute main process\nStart-MainProcess\n" }, { "path": "run-server.sh", "content": "#!/bin/bash\nset -euo pipefail\n\n# ============================================================================\n# PAL MCP Server Setup Script\n#\n# A platform-agnostic setup script that works on macOS, Linux, and WSL.\n# Handles environment setup, dependency installation, and configuration.\n# ============================================================================\n\n# Initialize pyenv if available (do this early)\nif [[ -d \"$HOME/.pyenv\" ]]; then\n export PYENV_ROOT=\"$HOME/.pyenv\"\n export PATH=\"$PYENV_ROOT/bin:$PATH\"\n if command -v pyenv &> /dev/null; then\n eval \"$(pyenv init --path)\" 2>/dev/null || true\n eval \"$(pyenv init -)\" 2>/dev/null || true\n fi\nfi\n\n# ----------------------------------------------------------------------------\n# Constants and Configuration\n# ----------------------------------------------------------------------------\n\n# Colors for output (ANSI codes work on all platforms)\nreadonly GREEN='\\033[0;32m'\nreadonly YELLOW='\\033[1;33m'\nreadonly RED='\\033[0;31m'\nreadonly NC='\\033[0m' # No Color\n\n# Configuration\nreadonly VENV_PATH=\".pal_venv\"\nreadonly DOCKER_CLEANED_FLAG=\".docker_cleaned\"\nreadonly DESKTOP_CONFIG_FLAG=\".desktop_configured\"\nreadonly LOG_DIR=\"logs\"\nreadonly LOG_FILE=\"mcp_server.log\"\nreadonly LEGACY_MCP_NAMES=(\"zen\" \"zen-mcp\" \"zen-mcp-server\" \"zen_mcp\" \"zen_mcp_server\")\n\n# Determine portable arguments for sed -i (GNU vs BSD)\ndeclare -a SED_INPLACE_ARGS\nif sed --version >/dev/null 2>&1; then\n SED_INPLACE_ARGS=(-i)\nelse\n SED_INPLACE_ARGS=(-i \"\")\nfi\n\n# ----------------------------------------------------------------------------\n# Utility Functions\n# ----------------------------------------------------------------------------\n\n# Print colored output\nprint_success() {\n echo -e \"${GREEN}βœ“${NC} $1\" >&2\n}\n\nprint_error() {\n echo -e \"${RED}βœ—${NC} $1\" >&2\n}\n\nprint_warning() {\n echo -e \"${YELLOW}!${NC} $1\" >&2\n}\n\nprint_info() {\n echo -e \"${YELLOW}$1${NC}\" >&2\n}\n\n# Get the script's directory (works on all platforms)\nget_script_dir() {\n cd \"$(dirname \"$0\")\" && pwd\n}\n\n# Extract version from config.py\nget_version() {\n grep -E '^__version__ = ' config.py 2>/dev/null | sed 's/__version__ = \"\\(.*\\)\"/\\1/' || echo \"unknown\"\n}\n\n# Clear Python cache files to prevent import issues\nclear_python_cache() {\n print_info \"Clearing Python cache files...\"\n find . -name \"*.pyc\" -delete 2>/dev/null || true\n find . -name \"__pycache__\" -type d -exec rm -rf {} + 2>/dev/null || true\n print_success \"Python cache cleared\"\n}\n\n# ----------------------------------------------------------------------------\n# Platform Detection Functions\n# ----------------------------------------------------------------------------\n\n# Get cross-platform Python executable path from venv\nget_venv_python_path() {\n local venv_path=\"$1\"\n \n # Convert to absolute path for consistent behavior across shell environments\n local abs_venv_path\n abs_venv_path=$(cd \"$(dirname \"$venv_path\")\" && pwd)/$(basename \"$venv_path\")\n\n # Check for both Unix and Windows Python executable paths\n if [[ -f \"$abs_venv_path/bin/python\" ]]; then\n echo \"$abs_venv_path/bin/python\"\n elif [[ -f \"$abs_venv_path/Scripts/python.exe\" ]]; then\n echo \"$abs_venv_path/Scripts/python.exe\"\n else\n return 1 # No Python executable found\n fi\n}\n\n# Detect the operating system\ndetect_os() {\n case \"$OSTYPE\" in\n darwin*) echo \"macos\" ;;\n linux*)\n if grep -qi microsoft /proc/version 2>/dev/null; then\n echo \"wsl\"\n else\n echo \"linux\"\n fi\n ;;\n msys*|cygwin*|win32) echo \"windows\" ;;\n *) echo \"unknown\" ;;\n esac\n}\n\n# Get Claude config path based on platform\nget_claude_config_path() {\n local os_type=$(detect_os)\n\n case \"$os_type\" in\n macos)\n echo \"$HOME/Library/Application Support/Claude/claude_desktop_config.json\"\n ;;\n linux)\n echo \"$HOME/.config/Claude/claude_desktop_config.json\"\n ;;\n wsl)\n local win_appdata\n if command -v wslvar &> /dev/null; then\n win_appdata=$(wslvar APPDATA 2>/dev/null)\n fi\n\n if [[ -n \"${win_appdata:-}\" ]]; then\n echo \"$(wslpath \"$win_appdata\")/Claude/claude_desktop_config.json\"\n else\n print_warning \"Could not determine Windows user path automatically. Please ensure APPDATA is set correctly or provide the full path manually.\"\n echo \"/mnt/c/Users/$USER/AppData/Roaming/Claude/claude_desktop_config.json\"\n fi\n ;;\n windows)\n echo \"$APPDATA/Claude/claude_desktop_config.json\"\n ;;\n *)\n echo \"\"\n ;;\n esac\n}\n\n# ----------------------------------------------------------------------------\n# Docker Cleanup Functions\n# ----------------------------------------------------------------------------\n\n# Clean up old Docker artifacts\ncleanup_docker() {\n # Skip if already cleaned or Docker not available\n [[ -f \"$DOCKER_CLEANED_FLAG\" ]] && return 0\n\n if ! command -v docker &> /dev/null || ! docker info &> /dev/null 2>&1; then\n return 0\n fi\n\n local found_artifacts=false\n\n # Define containers to remove\n local containers=(\n \"gemini-mcp-server\"\n \"gemini-mcp-redis\"\n \"zen-mcp-server\"\n \"zen-mcp-redis\"\n \"zen-mcp-log-monitor\"\n )\n\n # Remove containers\n for container in \"${containers[@]}\"; do\n if docker ps -a --format \"{{.Names}}\" | grep -q \"^${container}$\" 2>/dev/null; then\n if [[ \"$found_artifacts\" == false ]]; then\n echo \"One-time Docker cleanup...\"\n found_artifacts=true\n fi\n echo \" Removing container: $container\"\n docker stop \"$container\" >/dev/null 2>&1 || true\n docker rm \"$container\" >/dev/null 2>&1 || true\n fi\n done\n\n # Remove images\n local images=(\"gemini-mcp-server:latest\" \"zen-mcp-server:latest\")\n for image in \"${images[@]}\"; do\n if docker images --format \"{{.Repository}}:{{.Tag}}\" | grep -q \"^${image}$\" 2>/dev/null; then\n if [[ \"$found_artifacts\" == false ]]; then\n echo \"One-time Docker cleanup...\"\n found_artifacts=true\n fi\n echo \" Removing image: $image\"\n docker rmi \"$image\" >/dev/null 2>&1 || true\n fi\n done\n\n # Remove volumes\n local volumes=(\"redis_data\" \"mcp_logs\")\n for volume in \"${volumes[@]}\"; do\n if docker volume ls --format \"{{.Name}}\" | grep -q \"^${volume}$\" 2>/dev/null; then\n if [[ \"$found_artifacts\" == false ]]; then\n echo \"One-time Docker cleanup...\"\n found_artifacts=true\n fi\n echo \" Removing volume: $volume\"\n docker volume rm \"$volume\" >/dev/null 2>&1 || true\n fi\n done\n\n if [[ \"$found_artifacts\" == true ]]; then\n print_success \"Docker cleanup complete\"\n fi\n\n touch \"$DOCKER_CLEANED_FLAG\"\n}\n\n# ----------------------------------------------------------------------------\n# Python Environment Functions\n# ----------------------------------------------------------------------------\n\n# Find suitable Python command\nfind_python() {\n # Pyenv should already be initialized at script start, but check if .python-version exists\n if [[ -f \".python-version\" ]] && command -v pyenv &> /dev/null; then\n # Ensure pyenv respects the local .python-version\n pyenv local &>/dev/null || true\n fi\n\n # Prefer Python 3.12 for best compatibility\n local python_cmds=(\"python3.12\" \"python3.13\" \"python3.11\" \"python3.10\" \"python3\" \"python\" \"py\")\n\n for cmd in \"${python_cmds[@]}\"; do\n if command -v \"$cmd\" &> /dev/null; then\n local version=$($cmd --version 2>&1)\n if [[ $version =~ Python\\ 3\\.([0-9]+)\\.([0-9]+) ]]; then\n local major_version=${BASH_REMATCH[1]}\n local minor_version=${BASH_REMATCH[2]}\n\n # Check minimum version (3.10) for better library compatibility\n if [[ $major_version -ge 10 ]]; then\n # Verify the command actually exists (important for pyenv)\n if command -v \"$cmd\" &> /dev/null; then\n echo \"$cmd\"\n print_success \"Found Python: $version\"\n\n # Recommend Python 3.12\n if [[ $major_version -ne 12 ]]; then\n print_info \"Note: Python 3.12 is recommended for best compatibility.\"\n fi\n\n return 0\n fi\n fi\n fi\n fi\n done\n\n # No suitable Python found - check if we can use pyenv\n local os_type=$(detect_os)\n\n # Check for pyenv on Unix-like systems (macOS/Linux)\n if [[ \"$os_type\" == \"macos\" || \"$os_type\" == \"linux\" || \"$os_type\" == \"wsl\" ]]; then\n if command -v pyenv &> /dev/null; then\n # pyenv exists, check if Python 3.12 is installed\n if ! pyenv versions 2>/dev/null | grep -E \"3\\.(1[2-9]|[2-9][0-9])\" >/dev/null; then\n echo \"\"\n echo \"Python 3.10+ is required. Pyenv can install Python 3.12 locally for this project.\"\n read -p \"Install Python 3.12 using pyenv? (Y/n): \" -n 1 -r\n echo \"\"\n if [[ ! $REPLY =~ ^[Nn]$ ]]; then\n if install_python_with_pyenv; then\n # Try finding Python again\n if python_cmd=$(find_python); then\n echo \"$python_cmd\"\n return 0\n fi\n fi\n fi\n else\n # Python 3.12+ is installed in pyenv but may not be active\n # Check if .python-version exists\n if [[ ! -f \".python-version\" ]] || ! grep -qE \"3\\.(1[2-9]|[2-9][0-9])\" .python-version 2>/dev/null; then\n echo \"\"\n print_info \"Python 3.12 is installed via pyenv but not set for this project.\"\n read -p \"Set Python 3.12.0 for this project? (Y/n): \" -n 1 -r\n echo \"\"\n if [[ ! $REPLY =~ ^[Nn]$ ]]; then\n # Find the first suitable Python version\n local py_version=$(pyenv versions --bare | grep -E \"^3\\.(1[2-9]|[2-9][0-9])\" | head -1)\n if [[ -n \"$py_version\" ]]; then\n pyenv local \"$py_version\"\n print_success \"Set Python $py_version for this project\"\n # Re-initialize pyenv to pick up the change\n eval \"$(pyenv init --path)\" 2>/dev/null || true\n eval \"$(pyenv init -)\" 2>/dev/null || true\n # Try finding Python again\n if python_cmd=$(find_python); then\n echo \"$python_cmd\"\n return 0\n fi\n fi\n fi\n fi\n fi\n else\n # No pyenv installed - show instructions\n echo \"\" >&2\n print_error \"Python 3.10+ not found. The 'mcp' package requires Python 3.10+.\"\n echo \"\" >&2\n\n if [[ \"$os_type\" == \"macos\" ]]; then\n echo \"To install Python locally for this project:\" >&2\n echo \"\" >&2\n echo \"1. Install pyenv (manages Python versions per project):\" >&2\n echo \" brew install pyenv\" >&2\n echo \"\" >&2\n echo \"2. Add to ~/.zshrc:\" >&2\n echo ' export PYENV_ROOT=\"$HOME/.pyenv\"' >&2\n echo ' export PATH=\"$PYENV_ROOT/bin:$PATH\"' >&2\n echo ' eval \"$(pyenv init -)\"' >&2\n echo \"\" >&2\n echo \"3. Restart terminal, then run:\" >&2\n echo \" pyenv install 3.12.0\" >&2\n echo \" cd $(pwd)\" >&2\n echo \" pyenv local 3.12.0\" >&2\n echo \" ./run-server.sh\" >&2\n else\n # Linux/WSL\n echo \"To install Python locally for this project:\" >&2\n echo \"\" >&2\n echo \"1. Install pyenv:\" >&2\n echo \" curl https://pyenv.run | bash\" >&2\n echo \"\" >&2\n echo \"2. Add to ~/.bashrc:\" >&2\n echo ' export PYENV_ROOT=\"$HOME/.pyenv\"' >&2\n echo ' export PATH=\"$PYENV_ROOT/bin:$PATH\"' >&2\n echo ' eval \"$(pyenv init -)\"' >&2\n echo \"\" >&2\n echo \"3. Restart terminal, then run:\" >&2\n echo \" pyenv install 3.12.0\" >&2\n echo \" cd $(pwd)\" >&2\n echo \" pyenv local 3.12.0\" >&2\n echo \" ./run-server.sh\" >&2\n fi\n fi\n else\n # Other systems (shouldn't happen with bash script)\n print_error \"Python 3.10+ not found. Please install Python 3.10 or newer.\"\n fi\n\n return 1\n}\n\n# Install Python with pyenv (when pyenv is already installed)\ninstall_python_with_pyenv() {\n # Ensure pyenv is initialized\n export PYENV_ROOT=\"${PYENV_ROOT:-$HOME/.pyenv}\"\n export PATH=\"$PYENV_ROOT/bin:$PATH\"\n eval \"$(pyenv init -)\" 2>/dev/null || true\n\n print_info \"Installing Python 3.12 (this may take a few minutes)...\"\n if pyenv install -s 3.12.0; then\n print_success \"Python 3.12 installed\"\n\n # Set local Python version for this project\n pyenv local 3.12.0\n print_success \"Python 3.12 set for this project\"\n\n # Show shell configuration instructions\n echo \"\"\n print_info \"To make pyenv work in new terminals, add to your shell config:\"\n local shell_config=\"~/.zshrc\"\n if [[ \"$SHELL\" == *\"bash\"* ]]; then\n shell_config=\"~/.bashrc\"\n fi\n echo ' export PYENV_ROOT=\"$HOME/.pyenv\"'\n echo ' command -v pyenv >/dev/null || export PATH=\"$PYENV_ROOT/bin:$PATH\"'\n echo ' eval \"$(pyenv init -)\"'\n echo \"\"\n\n # Re-initialize pyenv to use the newly installed Python\n eval \"$(pyenv init --path)\" 2>/dev/null || true\n eval \"$(pyenv init -)\" 2>/dev/null || true\n\n return 0\n else\n print_error \"Failed to install Python 3.12\"\n return 1\n fi\n}\n\n# Detect Linux distribution\ndetect_linux_distro() {\n if [[ -f /etc/os-release ]]; then\n . /etc/os-release\n echo \"${ID:-unknown}\"\n elif [[ -f /etc/debian_version ]]; then\n echo \"debian\"\n elif [[ -f /etc/redhat-release ]]; then\n echo \"rhel\"\n elif [[ -f /etc/arch-release ]]; then\n echo \"arch\"\n else\n echo \"unknown\"\n fi\n}\n\n# Get package manager and install command for the distro\nget_install_command() {\n local distro=\"$1\"\n local python_version=\"${2:-}\"\n\n # Extract major.minor version if provided\n local version_suffix=\"\"\n if [[ -n \"$python_version\" ]] && [[ \"$python_version\" =~ ([0-9]+\\.[0-9]+) ]]; then\n version_suffix=\"${BASH_REMATCH[1]}\"\n fi\n\n case \"$distro\" in\n ubuntu|debian|raspbian|pop|linuxmint|elementary)\n if [[ -n \"$version_suffix\" ]]; then\n # Try version-specific packages first, then fall back to generic\n echo \"sudo apt update && (sudo apt install -y python${version_suffix}-venv python${version_suffix}-dev || sudo apt install -y python3-venv python3-pip)\"\n else\n echo \"sudo apt update && sudo apt install -y python3-venv python3-pip\"\n fi\n ;;\n fedora)\n echo \"sudo dnf install -y python3-venv python3-pip\"\n ;;\n rhel|centos|rocky|almalinux|oracle)\n echo \"sudo dnf install -y python3-venv python3-pip || sudo yum install -y python3-venv python3-pip\"\n ;;\n arch|manjaro|endeavouros)\n echo \"sudo pacman -Syu --noconfirm python-pip python-virtualenv\"\n ;;\n opensuse|suse)\n echo \"sudo zypper install -y python3-venv python3-pip\"\n ;;\n alpine)\n echo \"sudo apk add --no-cache python3-dev py3-pip py3-virtualenv\"\n ;;\n *)\n echo \"\"\n ;;\n esac\n}\n\n# Check if we can use sudo\ncan_use_sudo() {\n # Check if sudo exists and user can use it\n if command -v sudo &> /dev/null; then\n # Test sudo with a harmless command\n if sudo -n true 2>/dev/null; then\n return 0\n elif [[ -t 0 ]]; then\n # Terminal is interactive, test if sudo works with password\n if sudo true 2>/dev/null; then\n return 0\n fi\n fi\n fi\n return 1\n}\n\n# Try to install system packages automatically\ntry_install_system_packages() {\n local python_cmd=\"${1:-python3}\"\n local os_type=$(detect_os)\n\n # Skip on macOS as it works fine\n if [[ \"$os_type\" == \"macos\" ]]; then\n return 1\n fi\n\n # Only try on Linux systems\n if [[ \"$os_type\" != \"linux\" && \"$os_type\" != \"wsl\" ]]; then\n return 1\n fi\n\n # Get Python version\n local python_version=\"\"\n if command -v \"$python_cmd\" &> /dev/null; then\n python_version=$($python_cmd --version 2>&1 | grep -oE '[0-9]+\\.[0-9]+\\.[0-9]+' || echo \"\")\n fi\n\n local distro=$(detect_linux_distro)\n local install_cmd=$(get_install_command \"$distro\" \"$python_version\")\n\n if [[ -z \"$install_cmd\" ]]; then\n return 1\n fi\n\n print_info \"Attempting to install required Python packages...\"\n\n # Check if we can use sudo\n if can_use_sudo; then\n print_info \"Installing system packages (this may ask for your password)...\"\n if bash -c \"$install_cmd\" >/dev/null 2>&1; then # Replaced eval to prevent command injection\n print_success \"System packages installed successfully\"\n return 0\n else\n print_warning \"Failed to install system packages automatically\"\n fi\n fi\n\n return 1\n}\n\n# Bootstrap pip in virtual environment\nbootstrap_pip() {\n local venv_python=\"$1\"\n local python_cmd=\"$2\"\n\n print_info \"Bootstrapping pip in virtual environment...\"\n\n # Try ensurepip first\n if $venv_python -m ensurepip --default-pip >/dev/null 2>&1; then\n print_success \"Successfully bootstrapped pip using ensurepip\"\n return 0\n fi\n\n # Try to download get-pip.py\n print_info \"Downloading pip installer...\"\n local get_pip_url=\"https://bootstrap.pypa.io/get-pip.py\"\n local temp_pip=$(mktemp)\n local download_success=false\n\n # Try curl first\n if command -v curl &> /dev/null; then\n if curl -sSL \"$get_pip_url\" -o \"$temp_pip\" 2>/dev/null; then\n download_success=true\n fi\n fi\n\n # Try wget if curl failed\n if [[ \"$download_success\" == false ]] && command -v wget &> /dev/null; then\n if wget -qO \"$temp_pip\" \"$get_pip_url\" 2>/dev/null; then\n download_success=true\n fi\n fi\n\n # Try python urllib as last resort\n if [[ \"$download_success\" == false ]]; then\n print_info \"Using Python to download pip installer...\"\n if $python_cmd -c \"import urllib.request; urllib.request.urlretrieve('$get_pip_url', '$temp_pip')\" 2>/dev/null; then\n download_success=true\n fi\n fi\n\n if [[ \"$download_success\" == true ]] && [[ -f \"$temp_pip\" ]] && [[ -s \"$temp_pip\" ]]; then\n print_info \"Installing pip...\"\n if $venv_python \"$temp_pip\" --no-warn-script-location >/dev/null 2>&1; then\n rm -f \"$temp_pip\"\n print_success \"Successfully installed pip\"\n return 0\n fi\n fi\n\n rm -f \"$temp_pip\" 2>/dev/null\n return 1\n}\n\n# Setup environment using uv-first approach\nsetup_environment() {\n local venv_python=\"\"\n\n # Try uv-first approach\n if command -v uv &> /dev/null; then\n print_info \"Setting up environment with uv...\"\n\n # Only remove existing venv if it wasn't created by uv (to ensure clean uv setup)\n if [[ -d \"$VENV_PATH\" ]] && [[ ! -f \"$VENV_PATH/uv_created\" ]]; then\n print_info \"Removing existing environment for clean uv setup...\"\n rm -rf \"$VENV_PATH\"\n fi\n\n # Try Python 3.12 first (preferred)\n local uv_output\n if uv_output=$(uv venv --python 3.12 \"$VENV_PATH\" 2>&1); then\n # Use helper function for cross-platform path detection\n if venv_python=$(get_venv_python_path \"$VENV_PATH\"); then\n touch \"$VENV_PATH/uv_created\" # Mark as uv-created\n print_success \"Created environment with uv using Python 3.12\"\n\n # Ensure pip is installed in uv environment\n if ! $venv_python -m pip --version &>/dev/null 2>&1; then\n print_info \"Installing pip in uv environment...\"\n # uv doesn't install pip by default, use bootstrap method\n if bootstrap_pip \"$venv_python\" \"python3\"; then\n print_success \"pip installed in uv environment\"\n else\n print_warning \"Failed to install pip in uv environment\"\n fi\n fi\n else\n print_warning \"uv succeeded but Python executable not found in venv\"\n fi\n # Fall back to any available Python through uv\n elif uv_output=$(uv venv \"$VENV_PATH\" 2>&1); then\n # Use helper function for cross-platform path detection\n if venv_python=$(get_venv_python_path \"$VENV_PATH\"); then\n touch \"$VENV_PATH/uv_created\" # Mark as uv-created\n local python_version=$($venv_python --version 2>&1)\n print_success \"Created environment with uv using $python_version\"\n\n # Ensure pip is installed in uv environment\n if ! $venv_python -m pip --version &>/dev/null 2>&1; then\n print_info \"Installing pip in uv environment...\"\n # uv doesn't install pip by default, use bootstrap method\n if bootstrap_pip \"$venv_python\" \"python3\"; then\n print_success \"pip installed in uv environment\"\n else\n print_warning \"Failed to install pip in uv environment\"\n fi\n fi\n else\n print_warning \"uv succeeded but Python executable not found in venv\"\n fi\n else\n print_warning \"uv environment creation failed, falling back to system Python detection\"\n print_warning \"uv output: $uv_output\"\n fi\n else\n print_info \"uv not found, using system Python detection\"\n fi\n\n # If uv failed or not available, fallback to system Python detection\n if [[ -z \"$venv_python\" ]]; then\n print_info \"Setting up environment with system Python...\"\n local python_cmd\n python_cmd=$(find_python) || return 1\n\n # Use existing venv creation logic\n venv_python=$(setup_venv \"$python_cmd\")\n if [[ $? -ne 0 ]]; then\n return 1\n fi\n else\n # venv_python was already set by uv creation above, just convert to absolute path\n if [[ -n \"$venv_python\" ]]; then\n # Convert to absolute path for MCP registration\n local abs_venv_python\n if cd \"$(dirname \"$venv_python\")\" 2>/dev/null; then\n abs_venv_python=$(pwd)/$(basename \"$venv_python\")\n venv_python=\"$abs_venv_python\"\n else\n print_error \"Failed to resolve absolute path for venv_python\"\n return 1\n fi\n fi\n fi\n\n echo \"$venv_python\"\n return 0\n}\n\n# Setup virtual environment\nsetup_venv() {\n local python_cmd=\"$1\"\n local venv_python=\"\"\n local venv_pip=\"\"\n\n # Create venv if it doesn't exist\n if [[ ! -d \"$VENV_PATH\" ]]; then\n print_info \"Creating isolated environment...\"\n\n # Capture error output for better diagnostics\n local venv_error\n if venv_error=$($python_cmd -m venv \"$VENV_PATH\" 2>&1); then\n print_success \"Created isolated environment\"\n else\n # Check for common Linux issues and try fallbacks\n local os_type=$(detect_os)\n if [[ \"$os_type\" == \"linux\" || \"$os_type\" == \"wsl\" ]]; then\n if echo \"$venv_error\" | grep -E -q \"No module named venv|venv.*not found|ensurepip is not|python3.*-venv\"; then\n # Try to install system packages automatically first\n if try_install_system_packages \"$python_cmd\"; then\n print_info \"Retrying virtual environment creation...\"\n if venv_error=$($python_cmd -m venv \"$VENV_PATH\" 2>&1); then\n print_success \"Created isolated environment\"\n else\n # Continue to fallback methods below\n print_warning \"Still unable to create venv, trying fallback methods...\"\n fi\n fi\n\n # If venv still doesn't exist, try fallback methods\n if [[ ! -d \"$VENV_PATH\" ]]; then\n # Try virtualenv as fallback\n if command -v virtualenv &> /dev/null; then\n print_info \"Attempting to create environment with virtualenv...\"\n if virtualenv -p \"$python_cmd\" \"$VENV_PATH\" &>/dev/null 2>&1; then\n print_success \"Created environment using virtualenv fallback\"\n fi\n fi\n\n # Try python -m virtualenv if directory wasn't created\n if [[ ! -d \"$VENV_PATH\" ]]; then\n if $python_cmd -m virtualenv \"$VENV_PATH\" &>/dev/null 2>&1; then\n print_success \"Created environment using python -m virtualenv fallback\"\n fi\n fi\n\n # Last resort: try to install virtualenv via pip and use it\n if [[ ! -d \"$VENV_PATH\" ]] && command -v pip3 &> /dev/null; then\n print_info \"Installing virtualenv via pip...\"\n if pip3 install --user virtualenv &>/dev/null 2>&1; then\n local user_bin=\"$HOME/.local/bin\"\n if [[ -f \"$user_bin/virtualenv\" ]]; then\n if \"$user_bin/virtualenv\" -p \"$python_cmd\" \"$VENV_PATH\" &>/dev/null 2>&1; then\n print_success \"Created environment using pip-installed virtualenv\"\n fi\n fi\n fi\n fi\n fi\n\n # Check if any method succeeded\n if [[ ! -d \"$VENV_PATH\" ]]; then\n print_error \"Unable to create virtual environment\"\n echo \"\"\n echo \"Your system is missing Python development packages.\"\n echo \"\"\n\n local distro=$(detect_linux_distro)\n local python_version=$($python_cmd --version 2>&1 | grep -oE '[0-9]+\\.[0-9]+\\.[0-9]+' || echo \"\")\n local install_cmd=$(get_install_command \"$distro\" \"$python_version\")\n\n if [[ -n \"$install_cmd\" ]]; then\n echo \"Please run this command to install them:\"\n echo \" $install_cmd\"\n else\n echo \"Please install Python venv support for your system:\"\n echo \" Ubuntu/Debian: sudo apt install python3-venv python3-pip\"\n echo \" RHEL/CentOS: sudo dnf install python3-venv python3-pip\"\n echo \" Arch: sudo pacman -S python-pip python-virtualenv\"\n fi\n echo \"\"\n echo \"Then run this script again.\"\n exit 1\n fi\n elif echo \"$venv_error\" | grep -q \"Permission denied\"; then\n print_error \"Permission denied creating virtual environment\"\n echo \"\"\n echo \"Try running in a different directory:\"\n echo \" cd ~ && git clone && cd pal-mcp-server && ./run-server.sh\"\n echo \"\"\n exit 1\n else\n print_error \"Failed to create virtual environment\"\n echo \"Error: $venv_error\"\n exit 1\n fi\n else\n # For non-Linux systems, show the error and exit\n print_error \"Failed to create virtual environment\"\n echo \"Error: $venv_error\"\n exit 1\n fi\n fi\n fi\n\n # Get venv Python path based on platform\n local os_type=$(detect_os)\n case \"$os_type\" in\n windows)\n venv_python=\"$VENV_PATH/Scripts/python.exe\"\n venv_pip=\"$VENV_PATH/Scripts/pip.exe\"\n ;;\n *)\n venv_python=\"$VENV_PATH/bin/python\"\n venv_pip=\"$VENV_PATH/bin/pip\"\n ;;\n esac\n\n # Check if venv Python exists\n if [[ ! -f \"$venv_python\" ]]; then\n print_error \"Virtual environment Python not found\"\n exit 1\n fi\n\n # Always check if pip exists in the virtual environment (regardless of how it was created)\n if [[ ! -f \"$venv_pip\" ]] && ! $venv_python -m pip --version &>/dev/null 2>&1; then\n print_warning \"pip not found in virtual environment, installing...\"\n\n # On Linux, try to install system packages if pip is missing\n local os_type=$(detect_os)\n if [[ \"$os_type\" == \"linux\" || \"$os_type\" == \"wsl\" ]]; then\n if try_install_system_packages \"$python_cmd\"; then\n # Check if pip is now available after system package install\n if $venv_python -m pip --version &>/dev/null 2>&1; then\n print_success \"pip is now available\"\n else\n # Still need to bootstrap pip\n bootstrap_pip \"$venv_python\" \"$python_cmd\" || true\n fi\n else\n # Try to bootstrap pip without system packages\n bootstrap_pip \"$venv_python\" \"$python_cmd\" || true\n fi\n else\n # For non-Linux systems, just try to bootstrap pip\n bootstrap_pip \"$venv_python\" \"$python_cmd\" || true\n fi\n\n # Final check after all attempts\n if ! $venv_python -m pip --version &>/dev/null 2>&1; then\n print_error \"Failed to install pip in virtual environment\"\n echo \"\"\n echo \"Your Python installation appears to be incomplete.\"\n echo \"\"\n\n local distro=$(detect_linux_distro)\n local python_version=$($python_cmd --version 2>&1 | grep -oE '[0-9]+\\.[0-9]+\\.[0-9]+' || echo \"\")\n local install_cmd=$(get_install_command \"$distro\" \"$python_version\")\n\n if [[ -n \"$install_cmd\" ]]; then\n echo \"Please run this command to install Python packages:\"\n echo \" $install_cmd\"\n else\n echo \"Please install Python pip support for your system.\"\n fi\n echo \"\"\n echo \"Then delete the virtual environment and run this script again:\"\n echo \" rm -rf $VENV_PATH\"\n echo \" ./run-server.sh\"\n echo \"\"\n exit 1\n fi\n fi\n\n # Verify pip is working\n if ! $venv_python -m pip --version &>/dev/null 2>&1; then\n print_error \"pip is not working correctly in the virtual environment\"\n echo \"\"\n echo \"Try deleting the virtual environment and running again:\"\n echo \" rm -rf $VENV_PATH\"\n echo \" ./run-server.sh\"\n echo \"\"\n exit 1\n fi\n\n if [[ -n \"${VIRTUAL_ENV:-}\" ]]; then\n print_success \"Using activated virtual environment with pip\"\n else\n print_success \"Virtual environment ready with pip\"\n fi\n\n # Convert to absolute path for MCP registration\n local abs_venv_python=$(cd \"$(dirname \"$venv_python\")\" && pwd)/$(basename \"$venv_python\")\n echo \"$abs_venv_python\"\n return 0\n}\n\n# Check if package is installed\ncheck_package() {\n local python_cmd=\"$1\"\n local module_name=\"$2\"\n \"$python_cmd\" -c \"import importlib, sys; importlib.import_module(sys.argv[1])\" \"$module_name\" &>/dev/null\n}\n\n# Install dependencies\ninstall_dependencies() {\n local python_cmd=\"$1\"\n local deps_needed=false\n\n # First verify pip is available with retry logic and bootstrap fallback\n local pip_available=false\n local max_attempts=3\n\n for ((attempt=1; attempt<=max_attempts; attempt++)); do\n if \"$python_cmd\" -m pip --version &>/dev/null; then\n pip_available=true\n break\n else\n if (( attempt < max_attempts )); then\n print_warning \"Attempt $attempt/$max_attempts: pip not available, retrying in 1 second...\"\n sleep 1\n fi\n fi\n done\n\n # If pip is still not available after retries, try to bootstrap it\n if [[ \"$pip_available\" == false ]]; then\n print_warning \"pip is not available in the Python environment after $max_attempts attempts\"\n \n # Enhanced diagnostic information for debugging\n print_info \"Diagnostic information:\"\n print_info \" Python executable: $python_cmd\"\n print_info \" Python executable exists: $(if [[ -f \"$python_cmd\" ]]; then echo \"Yes\"; else echo \"No\"; fi)\"\n print_info \" Python executable permissions: $(ls -la \"$python_cmd\" 2>/dev/null || echo \"Cannot check\")\"\n print_info \" Virtual environment path: $VENV_PATH\"\n print_info \" Virtual environment exists: $(if [[ -d \"$VENV_PATH\" ]]; then echo \"Yes\"; else echo \"No\"; fi)\"\n \n print_info \"Attempting to bootstrap pip...\"\n\n # Extract the base python command for bootstrap (fallback to python3)\n local base_python_cmd=\"python3\"\n if command -v python &> /dev/null; then\n base_python_cmd=\"python\"\n fi\n\n # Try to bootstrap pip\n if bootstrap_pip \"$python_cmd\" \"$base_python_cmd\"; then\n print_success \"Successfully bootstrapped pip\"\n\n # Verify pip is now available\n if $python_cmd -m pip --version &>/dev/null 2>&1; then\n pip_available=true\n else\n print_error \"pip still not available after bootstrap attempt\"\n fi\n else\n print_error \"Failed to bootstrap pip\"\n fi\n fi\n\n # Final check - if pip is still not available, exit with error\n if [[ \"$pip_available\" == false ]]; then\n print_error \"pip is not available in the Python environment\"\n echo \"\"\n echo \"This indicates an incomplete Python installation or a problem with the virtual environment.\"\n echo \"\"\n echo \"Final diagnostic information:\"\n echo \" Python executable: $python_cmd\"\n echo \" Python version: $($python_cmd --version 2>&1 || echo \"Cannot determine\")\"\n echo \" pip module check: $($python_cmd -c \"import pip; print('Available')\" 2>&1 || echo \"Not available\")\"\n echo \"\"\n echo \"Troubleshooting steps:\"\n echo \"1. Delete the virtual environment: rm -rf $VENV_PATH\"\n echo \"2. Run this script again: ./run-server.sh\"\n echo \"3. If the problem persists, check your Python installation\"\n echo \"4. For Git Bash on Windows, try running from a regular Command Prompt or PowerShell\"\n echo \"\"\n return 1\n fi\n\n # Check required packages\n local packages=(\"mcp\" \"google.genai\" \"openai\" \"pydantic\" \"dotenv\")\n for package in \"${packages[@]}\"; do\n if ! check_package \"$python_cmd\" \"$package\"; then\n deps_needed=true\n break\n fi\n done\n\n if [[ \"$deps_needed\" == false ]]; then\n print_success \"Dependencies already installed\"\n return 0\n fi\n\n echo \"\"\n print_info \"Setting up PAL MCP Server...\"\n echo \"Installing required components:\"\n echo \" β€’ MCP protocol library\"\n echo \" β€’ AI model connectors\"\n echo \" β€’ Data validation tools\"\n echo \" β€’ Environment configuration\"\n echo \"\"\n\n # Determine installation method and execute directly to handle paths with spaces\n local install_output\n local exit_code=0\n\n echo -n \"Downloading packages...\"\n\n if command -v uv &> /dev/null && [[ -f \"$VENV_PATH/uv_created\" ]]; then\n print_info \"Using uv for faster package installation...\"\n install_output=$(uv pip install -q -r requirements.txt --python \"$python_cmd\" 2>&1) || exit_code=$?\n elif [[ -n \"${VIRTUAL_ENV:-}\" ]] || [[ \"$python_cmd\" == *\"$VENV_PATH\"* ]]; then\n install_output=$(\"$python_cmd\" -m pip install -q -r requirements.txt 2>&1) || exit_code=$?\n else\n install_output=$(\"$python_cmd\" -m pip install -q --user -r requirements.txt 2>&1) || exit_code=$?\n fi\n\n if [[ $exit_code -ne 0 ]]; then\n echo -e \"\\r${RED}βœ— Setup failed${NC} \"\n echo \"\"\n echo \"Installation error:\"\n echo \"$install_output\" | head -20\n echo \"\"\n\n # Check for common issues\n if echo \"$install_output\" | grep -q \"No module named pip\"; then\n print_error \"pip module not found\"\n echo \"\"\n echo \"Your Python installation is incomplete. Please install pip:\"\n\n local distro=$(detect_linux_distro)\n local python_version=$($python_cmd --version 2>&1 | grep -oE '[0-9]+\\.[0-9]+\\.[0-9]+' || echo \"\")\n local install_cmd=$(get_install_command \"$distro\" \"$python_version\")\n\n if [[ -n \"$install_cmd\" ]]; then\n echo \"\"\n echo \"For your system ($distro), run:\"\n echo \" $install_cmd\"\n else\n echo \"\"\n echo \" Ubuntu/Debian: sudo apt install python3-pip\"\n echo \" RHEL/CentOS: sudo dnf install python3-pip\"\n echo \" Arch: sudo pacman -S python-pip\"\n fi\n elif echo \"$install_output\" | grep -q \"Permission denied\"; then\n print_error \"Permission denied during installation\"\n echo \"\"\n echo \"Try using a virtual environment or install with --user flag:\"\n echo \" $python_cmd -m pip install --user -r requirements.txt\"\n else\n echo \"Try running manually:\"\n if [[ \"$use_uv\" == true ]]; then\n echo \" uv pip install -r requirements.txt --python $python_cmd\"\n echo \"Or fallback to pip:\"\n fi\n echo \" $python_cmd -m pip install -r requirements.txt\"\n echo \"\"\n echo \"Or install individual packages:\"\n echo \" $python_cmd -m pip install mcp google-genai openai pydantic python-dotenv\"\n fi\n return 1\n else\n echo -e \"\\r${GREEN}βœ“ Setup complete!${NC} \"\n\n # Verify critical imports work\n if ! check_package \"$python_cmd\" \"dotenv\"; then\n print_warning \"python-dotenv not imported correctly, installing explicitly...\"\n if $python_cmd -m pip install python-dotenv &>/dev/null 2>&1; then\n print_success \"python-dotenv installed successfully\"\n else\n print_error \"Failed to install python-dotenv\"\n return 1\n fi\n fi\n\n return 0\n fi\n}\n\n# ----------------------------------------------------------------------------\n# Environment Configuration Functions\n# ----------------------------------------------------------------------------\n\n# Setup .env file\nsetup_env_file() {\n if [[ -f .env ]]; then\n print_success \".env file already exists\"\n migrate_env_file\n return 0\n fi\n\n if [[ ! -f .env.example ]]; then\n print_error \".env.example not found!\"\n return 1\n fi\n\n cp .env.example .env\n print_success \"Created .env from .env.example\"\n\n # Update API keys from environment if present\n local api_keys=(\n \"GEMINI_API_KEY:your_gemini_api_key_here\"\n \"OPENAI_API_KEY:your_openai_api_key_here\"\n \"XAI_API_KEY:your_xai_api_key_here\"\n \"DIAL_API_KEY:your_dial_api_key_here\"\n \"OPENROUTER_API_KEY:your_openrouter_api_key_here\"\n )\n\n for key_pair in \"${api_keys[@]}\"; do\n local key_name=\"${key_pair%%:*}\"\n local placeholder=\"${key_pair##*:}\"\n local key_value=\"${!key_name:-}\"\n\n if [[ -n \"$key_value\" ]]; then\n sed \"${SED_INPLACE_ARGS[@]}\" \"s/$placeholder/$key_value/\" .env\n print_success \"Updated .env with $key_name from environment\"\n fi\n done\n\n return 0\n}\n\n# Migrate .env file from Docker to standalone format\nmigrate_env_file() {\n # Check if migration is needed\n if ! grep -q \"host\\.docker\\.internal\" .env 2>/dev/null; then\n return 0\n fi\n\n print_warning \"Migrating .env from Docker to standalone format...\"\n\n # Create backup\n cp .env .env.backup_$(date +%Y%m%d_%H%M%S)\n\n # Replace host.docker.internal with localhost\n sed \"${SED_INPLACE_ARGS[@]}\" 's/host\\.docker\\.internal/localhost/g' .env\n\n print_success \"Migrated Docker URLs to localhost in .env\"\n echo \" (Backup saved as .env.backup_*)\"\n}\n\n# Check API keys and warn if missing (non-blocking)\ncheck_api_keys() {\n local has_key=false\n local api_keys=(\n \"GEMINI_API_KEY:your_gemini_api_key_here\"\n \"OPENAI_API_KEY:your_openai_api_key_here\"\n \"XAI_API_KEY:your_xai_api_key_here\"\n \"DIAL_API_KEY:your_dial_api_key_here\"\n \"OPENROUTER_API_KEY:your_openrouter_api_key_here\"\n )\n\n for key_pair in \"${api_keys[@]}\"; do\n local key_name=\"${key_pair%%:*}\"\n local placeholder=\"${key_pair##*:}\"\n local key_value=\"${!key_name:-}\"\n\n if [[ -n \"$key_value\" ]] && [[ \"$key_value\" != \"$placeholder\" ]]; then\n print_success \"$key_name configured\"\n has_key=true\n fi\n done\n\n # Check custom API URL\n if [[ -n \"${CUSTOM_API_URL:-}\" ]]; then\n print_success \"CUSTOM_API_URL configured: $CUSTOM_API_URL\"\n has_key=true\n fi\n\n if [[ \"$has_key\" == false ]]; then\n print_warning \"No API keys found in .env!\"\n echo \"\"\n echo \"The Python development environment will be set up, but you won't be able to use the MCP server until you add API keys.\"\n echo \"\"\n echo \"To add API keys, edit .env and add at least one:\"\n echo \" GEMINI_API_KEY=your-actual-key\"\n echo \" OPENAI_API_KEY=your-actual-key\"\n echo \" XAI_API_KEY=your-actual-key\"\n echo \" DIAL_API_KEY=your-actual-key\"\n echo \" OPENROUTER_API_KEY=your-actual-key\"\n echo \"\"\n print_info \"You can continue with development setup and add API keys later.\"\n echo \"\"\n fi\n\n return 0 # Always return success to continue setup\n}\n\n\n# ----------------------------------------------------------------------------\n# Environment Variable Parsing Function\n# ----------------------------------------------------------------------------\n\n# Parse .env file and extract all valid environment variables\nparse_env_variables() {\n local env_vars=\"\"\n \n if [[ -f .env ]]; then\n # Read .env file and extract non-empty, non-comment variables\n while IFS= read -r line; do\n # Skip comments, empty lines, and lines starting with #\n if [[ -n \"$line\" && ! \"$line\" =~ ^[[:space:]]*# && \"$line\" =~ ^[[:space:]]*([^=]+)=(.*)$ ]]; then\n local key=\"${BASH_REMATCH[1]}\"\n local value=\"${BASH_REMATCH[2]}\"\n \n # Clean up key (remove leading/trailing whitespace)\n key=$(echo \"$key\" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//')\n \n # Skip if value is empty or just whitespace\n if [[ -n \"$value\" && ! \"$value\" =~ ^[[:space:]]*$ ]]; then\n # Clean up value (remove leading/trailing whitespace and quotes)\n value=$(echo \"$value\" | sed 's/^[[:space:]]*//;s/[[:space:]]*$//' | sed 's/^\"//;s/\"$//')\n \n # Remove inline comments (everything after # that's not in quotes)\n value=$(echo \"$value\" | sed 's/[[:space:]]*#.*$//')\n \n # Skip if value is a placeholder or empty after comment removal\n if [[ ! \"$value\" =~ ^your_.*_here$ && \"$value\" != \"your_\" && -n \"$value\" && ! \"$value\" =~ ^[[:space:]]*$ ]]; then\n env_vars+=\"$key=$value\"$'\\n'\n fi\n fi\n fi\n done < .env\n fi\n\n # If no .env file or no valid vars, fall back to environment variables\n if [[ -z \"$env_vars\" ]]; then\n local api_keys=(\n \"GEMINI_API_KEY\"\n \"OPENAI_API_KEY\" \n \"XAI_API_KEY\"\n \"DIAL_API_KEY\"\n \"OPENROUTER_API_KEY\"\n \"CUSTOM_API_URL\"\n \"CUSTOM_API_KEY\"\n \"CUSTOM_MODEL_NAME\"\n \"DISABLED_TOOLS\"\n \"DEFAULT_MODEL\"\n \"LOG_LEVEL\"\n \"DEFAULT_THINKING_MODE_THINKDEEP\"\n \"CONVERSATION_TIMEOUT_HOURS\"\n \"MAX_CONVERSATION_TURNS\"\n )\n\n for key_name in \"${api_keys[@]}\"; do\n local key_value=\"${!key_name:-}\"\n if [[ -n \"$key_value\" && ! \"$key_value\" =~ ^your_.*_here$ ]]; then\n env_vars+=\"$key_name=$key_value\"$'\\n'\n fi\n done\n fi\n \n echo \"$env_vars\"\n}\n\n# ----------------------------------------------------------------------------\n# Claude Integration Functions\n# ----------------------------------------------------------------------------\n\n# Check if MCP is added to Claude CLI and verify it's correct\ncheck_claude_cli_integration() {\n local python_cmd=\"$1\"\n local server_path=\"$2\"\n\n # Check for native installed Claude CLI (not in PATH by default)\n # Native installs:\n # - curl https://claude.ai/install.sh | bash -> ~/.local/bin/claude\n # - brew install --cask claude-code -> /opt/homebrew/bin/claude (Apple Silicon) or /usr/local/bin/claude (Intel)\n if ! command -v claude &> /dev/null; then\n local claude_paths=(\n \"$HOME/.local/bin\"\n \"/opt/homebrew/bin\"\n \"/usr/local/bin\"\n )\n for dir in \"${claude_paths[@]}\"; do\n if [[ -x \"$dir/claude\" ]]; then\n print_info \"Found native installed Claude CLI at $dir/claude\"\n export PATH=\"$dir:$PATH\"\n print_success \"Added $dir to PATH\"\n break\n fi\n done\n fi\n\n if ! command -v claude &> /dev/null; then\n echo \"\"\n print_warning \"Claude CLI not found\"\n echo \"\"\n read -p \"Would you like to add PAL to Claude Code? (Y/n): \" -n 1 -r\n echo \"\"\n if [[ $REPLY =~ ^[Nn]$ ]]; then\n print_info \"Skipping Claude Code integration\"\n return 0\n fi\n\n echo \"\"\n echo \"Please install Claude Code first:\"\n echo \" Visit: https://docs.anthropic.com/en/docs/claude-code/cli-usage\"\n echo \"\"\n echo \"Then run this script again to register MCP.\"\n return 1\n fi\n\n # Remove legacy zen registrations to avoid duplicate errors after rename\n for legacy_name in \"${LEGACY_MCP_NAMES[@]}\"; do\n claude mcp remove \"$legacy_name\" -s user >/dev/null 2>&1 || true\n done\n\n # Check if pal is registered\n local mcp_list=$(claude mcp list 2>/dev/null)\n if echo \"$mcp_list\" | grep -q \"pal\"; then\n # Check if it's using the old Docker command\n if echo \"$mcp_list\" | grep -E \"zen.*docker|zen.*compose\" &>/dev/null; then\n print_warning \"Found old Docker-based Zen registration, updating...\"\n claude mcp remove zen -s user 2>/dev/null || true\n\n # Re-add with correct Python command and environment variables\n local env_vars=$(parse_env_variables)\n local env_args=\"\"\n \n # Convert environment variables to -e arguments\n if [[ -n \"$env_vars\" ]]; then\n while IFS= read -r line; do\n if [[ -n \"$line\" && \"$line\" =~ ^([^=]+)=(.*)$ ]]; then\n env_args+=\" -e ${BASH_REMATCH[1]}=\\\"${BASH_REMATCH[2]}\\\"\"\n fi\n done <<< \"$env_vars\"\n fi\n \n local claude_cmd=\"claude mcp add pal -s user$env_args -- \\\"$python_cmd\\\" \\\"$server_path\\\"\"\n if eval \"$claude_cmd\" 2>/dev/null; then\n print_success \"Updated PAL to become a standalone script with environment variables\"\n return 0\n else\n echo \"\"\n echo \"Failed to update MCP registration. Please run manually:\"\n echo \" claude mcp remove pal -s user\"\n echo \" $claude_cmd\"\n return 1\n fi\n else\n # Verify the registered path matches current setup\n local expected_cmd=\"$python_cmd $server_path\"\n if echo \"$mcp_list\" | grep -F \"$server_path\" &>/dev/null; then\n return 0\n else\n print_warning \"PAL registered with different path, updating...\"\n claude mcp remove pal -s user 2>/dev/null || true\n\n # Re-add with current path and environment variables\n local env_vars=$(parse_env_variables)\n local env_args=\"\"\n \n # Convert environment variables to -e arguments\n if [[ -n \"$env_vars\" ]]; then\n while IFS= read -r line; do\n if [[ -n \"$line\" && \"$line\" =~ ^([^=]+)=(.*)$ ]]; then\n env_args+=\" -e ${BASH_REMATCH[1]}=\\\"${BASH_REMATCH[2]}\\\"\"\n fi\n done <<< \"$env_vars\"\n fi\n \n local claude_cmd=\"claude mcp add pal -s user$env_args -- \\\"$python_cmd\\\" \\\"$server_path\\\"\"\n if eval \"$claude_cmd\" 2>/dev/null; then\n print_success \"Updated PAL with current path and environment variables\"\n return 0\n else\n echo \"\"\n echo \"Failed to update MCP registration. Please run manually:\"\n echo \" claude mcp remove pal -s user\"\n echo \" $claude_cmd\"\n return 1\n fi\n fi\n fi\n else\n # Not registered at all, ask user if they want to add it\n echo \"\"\n read -p \"Add PAL to Claude Code? (Y/n): \" -n 1 -r\n echo \"\"\n if [[ $REPLY =~ ^[Nn]$ ]]; then\n local env_vars=$(parse_env_variables)\n local env_args=\"\"\n \n # Convert environment variables to -e arguments for manual command\n if [[ -n \"$env_vars\" ]]; then\n while IFS= read -r line; do\n if [[ -n \"$line\" && \"$line\" =~ ^([^=]+)=(.*)$ ]]; then\n env_args+=\" -e ${BASH_REMATCH[1]}=\\\"${BASH_REMATCH[2]}\\\"\"\n fi\n done <<< \"$env_vars\"\n fi\n \n print_info \"To add manually later, run:\"\n echo \" claude mcp add pal -s user$env_args -- $python_cmd $server_path\"\n return 0\n fi\n\n print_info \"Registering PAL with Claude Code...\"\n \n # Add with environment variables\n local env_vars=$(parse_env_variables)\n local env_args=\"\"\n \n # Convert environment variables to -e arguments\n if [[ -n \"$env_vars\" ]]; then\n while IFS= read -r line; do\n if [[ -n \"$line\" && \"$line\" =~ ^([^=]+)=(.*)$ ]]; then\n env_args+=\" -e ${BASH_REMATCH[1]}=\\\"${BASH_REMATCH[2]}\\\"\"\n fi\n done <<< \"$env_vars\"\n fi\n \n local claude_cmd=\"claude mcp add pal -s user$env_args -- \\\"$python_cmd\\\" \\\"$server_path\\\"\"\n if eval \"$claude_cmd\" 2>/dev/null; then\n print_success \"Successfully added PAL to Claude Code with environment variables\"\n return 0\n else\n echo \"\"\n echo \"Failed to add automatically. To add manually, run:\"\n echo \" $claude_cmd\"\n return 1\n fi\n fi\n}\n\n# Check and update Claude Desktop configuration\ncheck_claude_desktop_integration() {\n local python_cmd=\"$1\"\n local server_path=\"$2\"\n\n # Skip if already configured (check flag)\n if [[ -f \"$DESKTOP_CONFIG_FLAG\" ]]; then\n return 0\n fi\n\n local config_path=$(get_claude_config_path)\n if [[ -z \"$config_path\" ]]; then\n print_warning \"Unable to determine Claude Desktop config path for this platform\"\n return 0\n fi\n\n # Legacy MCP server names to clean out from previous releases\n local legacy_names_csv\n legacy_names_csv=$(IFS=,; echo \"${LEGACY_MCP_NAMES[*]}\")\n\n echo \"\"\n read -p \"Configure PAL for Claude Desktop? (Y/n): \" -n 1 -r\n echo \"\"\n if [[ $REPLY =~ ^[Nn]$ ]]; then\n print_info \"Skipping Claude Desktop integration\"\n touch \"$DESKTOP_CONFIG_FLAG\" # Don't ask again\n return 0\n fi\n\n # Create config directory if it doesn't exist\n local config_dir=$(dirname \"$config_path\")\n mkdir -p \"$config_dir\" 2>/dev/null || true\n\n # Handle existing config\n if [[ -f \"$config_path\" ]]; then\n print_info \"Updating existing Claude Desktop config...\"\n\n # Check for old Docker config and remove it\n if grep -q \"docker.*compose.*pal\\|pal.*docker\" \"$config_path\" 2>/dev/null; then\n print_warning \"Removing old Docker-based MCP configuration...\"\n # Create backup\n cp \"$config_path\" \"${config_path}.backup_$(date +%Y%m%d_%H%M%S)\"\n\n # Remove old pal config using a more robust approach\n local temp_file=$(mktemp)\n python3 -c \"\nimport json\nimport sys\n\ntry:\n with open('$config_path', 'r') as f:\n config = json.load(f)\n\n # Remove pal from mcpServers if it exists\n if 'mcpServers' in config and 'pal' in config['mcpServers']:\n del config['mcpServers']['pal']\n print('Removed old pal MCP configuration')\n\n with open('$temp_file', 'w') as f:\n json.dump(config, f, indent=2)\n\nexcept Exception as e:\n print(f'Error processing config: {e}', file=sys.stderr)\n sys.exit(1)\n\" && mv \"$temp_file\" \"$config_path\"\n fi\n\n # Add new config with environment variables\n local env_vars=$(parse_env_variables)\n local temp_file=$(mktemp)\n local env_file=$(mktemp)\n \n # Write environment variables to a temporary file for Python to read\n if [[ -n \"$env_vars\" ]]; then\n echo \"$env_vars\" > \"$env_file\"\n fi\n \n PAL_LEGACY_NAMES=\"$legacy_names_csv\" python3 -c \"\nimport json\nimport os\nimport sys\n\nlegacy_keys = [k for k in os.environ.get('PAL_LEGACY_NAMES', '').split(',') if k]\n\ntry:\n with open('$config_path', 'r') as f:\n config = json.load(f)\nexcept Exception:\n config = {}\n\nif not isinstance(config, dict):\n config = {}\n\n# Ensure mcpServers exists\nif 'mcpServers' not in config or not isinstance(config.get('mcpServers'), dict):\n config['mcpServers'] = {}\n\n# Remove legacy entries from any known server blocks\nfor container in ('mcpServers', 'servers'):\n servers = config.get(container)\n if isinstance(servers, dict):\n for key in legacy_keys:\n servers.pop(key, None)\n\n# Add pal server\npal_config = {\n 'command': '$python_cmd',\n 'args': ['$server_path']\n}\n\n# Add environment variables if they exist\nenv_dict = {}\ntry:\n with open('$env_file', 'r') as f:\n for line in f:\n line = line.strip()\n if '=' in line and line:\n key, value = line.split('=', 1)\n env_dict[key] = value\nexcept Exception:\n pass\n\nif env_dict:\n pal_config['env'] = env_dict\n\nconfig['mcpServers']['pal'] = pal_config\n\nwith open('$temp_file', 'w') as f:\n json.dump(config, f, indent=2)\n\" && mv \"$temp_file\" \"$config_path\"\n \n # Clean up temporary env file\n rm -f \"$env_file\" 2>/dev/null || true\n\n else\n print_info \"Creating new Claude Desktop config...\"\n \n # Create new config with environment variables\n local env_vars=$(parse_env_variables)\n local temp_file=$(mktemp)\n local env_file=$(mktemp)\n \n # Write environment variables to a temporary file for Python to read\n if [[ -n \"$env_vars\" ]]; then\n echo \"$env_vars\" > \"$env_file\"\n fi\n \n python3 -c \"\nimport json\nimport sys\n\nconfig = {'mcpServers': {}}\n\n# Add pal server\npal_config = {\n 'command': '$python_cmd',\n 'args': ['$server_path']\n}\n\n# Add environment variables if they exist\nenv_dict = {}\ntry:\n with open('$env_file', 'r') as f:\n for line in f:\n line = line.strip()\n if '=' in line and line:\n key, value = line.split('=', 1)\n env_dict[key] = value\nexcept:\n pass\n\nif env_dict:\n pal_config['env'] = env_dict\n\nconfig['mcpServers']['pal'] = pal_config\n\nwith open('$temp_file', 'w') as f:\n json.dump(config, f, indent=2)\n\" && mv \"$temp_file\" \"$config_path\"\n \n # Clean up temporary env file\n rm -f \"$env_file\" 2>/dev/null || true\n fi\n\n if [[ $? -eq 0 ]]; then\n print_success \"Successfully configured Claude Desktop\"\n echo \" Config: $config_path\"\n echo \" Restart Claude Desktop to use the new MCP server\"\n touch \"$DESKTOP_CONFIG_FLAG\"\n else\n print_error \"Failed to update Claude Desktop config\"\n echo \"Manual config location: $config_path\"\n echo \"Add this configuration:\"\n \n # Generate example with actual environment variables for error case\n example_env=\"\"\n env_vars=$(parse_env_variables)\n if [[ -n \"$env_vars\" ]]; then\n local first_entry=true\n while IFS= read -r line; do\n if [[ -n \"$line\" && \"$line\" =~ ^([^=]+)=(.*)$ ]]; then\n local key=\"${BASH_REMATCH[1]}\"\n local value=\"your_$(echo \"${key}\" | tr '[:upper:]' '[:lower:]')\"\n \n if [[ \"$first_entry\" == true ]]; then\n first_entry=false\n example_env=\" \\\"$key\\\": \\\"$value\\\"\"\n else\n example_env+=\",\\n \\\"$key\\\": \\\"$value\\\"\"\n fi\n fi\n done <<< \"$env_vars\"\n fi\n \n cat << EOF\n{\n \"mcpServers\": {\n \"pal\": {\n \"command\": \"$python_cmd\",\n \"args\": [\"$server_path\"]$(if [[ -n \"$example_env\" ]]; then echo \",\"; fi)$(if [[ -n \"$example_env\" ]]; then echo \"\n \\\"env\\\": {\n$(echo -e \"$example_env\")\n }\"; fi)\n }\n }\n}\nEOF\n fi\n}\n\n# Check and update Gemini CLI configuration\ncheck_gemini_cli_integration() {\n local script_dir=\"$1\"\n local pal_wrapper=\"$script_dir/pal-mcp-server\"\n\n # Check if Gemini settings file exists\n local gemini_config=\"$HOME/.gemini/settings.json\"\n if [[ ! -f \"$gemini_config\" ]]; then\n # Gemini CLI not installed or not configured\n return 0\n fi\n\n # Clean up legacy zen entries and detect existing pal configuration\n local legacy_names_csv\n legacy_names_csv=$(IFS=,; echo \"${LEGACY_MCP_NAMES[*]}\")\n\n local gemini_status\n gemini_status=$(\n PAL_LEGACY_NAMES=\"$legacy_names_csv\" PAL_WRAPPER=\"$pal_wrapper\" PAL_GEMINI_CONFIG=\"$gemini_config\" python3 - <<'PY' 2>/dev/null\nimport json\nimport os\nimport pathlib\nimport sys\n\nconfig_path = pathlib.Path(os.environ[\"PAL_GEMINI_CONFIG\"])\nlegacy = [n for n in os.environ.get(\"PAL_LEGACY_NAMES\", \"\").split(\",\") if n]\nwrapper = os.environ[\"PAL_WRAPPER\"]\n\nchanged = False\nhas_pal = False\n\ntry:\n data = json.loads(config_path.read_text())\nexcept Exception:\n data = {}\n\nif not isinstance(data, dict):\n data = {}\n\nservers = data.get(\"mcpServers\")\nif not isinstance(servers, dict):\n servers = {}\n data[\"mcpServers\"] = servers\n\nfor key in legacy:\n if servers.pop(key, None) is not None:\n changed = True\n\npal_cfg = servers.get(\"pal\")\nif isinstance(pal_cfg, dict):\n has_pal = True\n if pal_cfg.get(\"command\") != wrapper:\n pal_cfg[\"command\"] = wrapper\n servers[\"pal\"] = pal_cfg\n changed = True\n\nif changed:\n config_path.parent.mkdir(parents=True, exist_ok=True)\n config_path.write_text(json.dumps(data, indent=2))\n\nstatus = (\"CHANGED\" if changed else \"UNCHANGED\") + \":\" + (\"HAS_PAL\" if has_pal else \"NO_PAL\")\nsys.stdout.write(status)\nsys.exit(0)\nPY\n ) || true\n\n local gemini_changed=false\n local gemini_has_pal=false\n [[ \"$gemini_status\" == CHANGED:* ]] && gemini_changed=true\n [[ \"$gemini_status\" == *:HAS_PAL ]] && gemini_has_pal=true\n\n if [[ \"$gemini_has_pal\" == true ]]; then\n if [[ \"$gemini_changed\" == true ]]; then\n print_success \"Removed legacy Gemini MCP entries\"\n fi\n return 0\n fi\n\n # Ask user if they want to add PAL to Gemini CLI\n echo \"\"\n read -p \"Configure PAL for Gemini CLI? (Y/n): \" -n 1 -r\n echo \"\"\n if [[ $REPLY =~ ^[Nn]$ ]]; then\n print_info \"Skipping Gemini CLI integration\"\n return 0\n fi\n\n # Ensure wrapper script exists\n if [[ ! -f \"$pal_wrapper\" ]]; then\n print_info \"Creating wrapper script for Gemini CLI...\"\n cat > \"$pal_wrapper\" << 'EOF'\n#!/bin/bash\n# Wrapper script for Gemini CLI compatibility\nDIR=\"$(cd \"$(dirname \"$0\")\" && pwd)\"\ncd \"$DIR\"\nexec .pal_venv/bin/python server.py \"$@\"\nEOF\n chmod +x \"$pal_wrapper\"\n print_success \"Created pal-mcp-server wrapper script\"\n fi\n\n # Update Gemini settings\n print_info \"Updating Gemini CLI configuration...\"\n\n # Create backup\n cp \"$gemini_config\" \"${gemini_config}.backup_$(date +%Y%m%d_%H%M%S)\"\n\n # Add pal configuration using Python for proper JSON handling\n local temp_file=$(mktemp)\n python3 -c \"\nimport json\nimport sys\n\ntry:\n with open('$gemini_config', 'r') as f:\n config = json.load(f)\n\n # Ensure mcpServers exists\n if 'mcpServers' not in config:\n config['mcpServers'] = {}\n\n # Add pal server\n config['mcpServers']['pal'] = {\n 'command': '$pal_wrapper'\n }\n\n with open('$temp_file', 'w') as f:\n json.dump(config, f, indent=2)\n\nexcept Exception as e:\n print(f'Error processing config: {e}', file=sys.stderr)\n sys.exit(1)\n\" && mv \"$temp_file\" \"$gemini_config\"\n\n if [[ $? -eq 0 ]]; then\n print_success \"Successfully configured Gemini CLI\"\n echo \" Config: $gemini_config\"\n echo \" Restart Gemini CLI to use PAL MCP Server\"\n else\n print_error \"Failed to update Gemini CLI config\"\n echo \"Manual config location: $gemini_config\"\n echo \"Add this configuration:\"\n cat << EOF\n{\n \"mcpServers\": {\n \"pal\": {\n \"command\": \"$pal_wrapper\"\n }\n }\n}\nEOF\n fi\n}\n\n# Check and update Codex CLI configuration\ncheck_codex_cli_integration() {\n if ! command -v codex &> /dev/null; then\n return 0\n fi\n\n local codex_config=\"$HOME/.codex/config.toml\"\n local legacy_names_csv\n legacy_names_csv=$(IFS=,; echo \"${LEGACY_MCP_NAMES[*]}\")\n\n if [[ -f \"$codex_config\" ]]; then\n local codex_cleanup_status\n codex_cleanup_status=$(\n PAL_LEGACY_NAMES=\"$legacy_names_csv\" PAL_CODEX_CONFIG=\"$codex_config\" python3 - <<'PY' 2>/dev/null\nimport os\nimport pathlib\nimport re\nimport sys\n\nconfig_path = pathlib.Path(os.environ[\"PAL_CODEX_CONFIG\"])\nlegacy = [n for n in os.environ.get(\"PAL_LEGACY_NAMES\", \"\").split(\",\") if n]\n\nif not config_path.exists():\n sys.exit(0)\n\nlines = config_path.read_text().splitlines()\noutput = []\nskip = False\nremoved = False\nsection_re = re.compile(r\"\\s*\\[([^\\]]+)\\]\")\n\nfor line in lines:\n match = section_re.match(line)\n if match:\n header = match.group(1).strip()\n parts = header.split(\".\")\n is_legacy = False\n if len(parts) >= 2 and parts[0] == \"mcp_servers\":\n section_key = \".\".join(parts[1:])\n for name in legacy:\n if section_key == name or section_key.startswith(name + \".\"):\n is_legacy = True\n break\n skip = is_legacy\n if is_legacy:\n removed = True\n continue\n if not skip:\n output.append(line)\n\nif removed:\n config_path.write_text(\"\\n\".join(output).rstrip() + (\"\\n\" if output else \"\"))\n sys.stdout.write(\"REMOVED\")\nelse:\n sys.stdout.write(\"UNCHANGED\")\nsys.exit(0)\nPY\n ) || true\n\n if [[ \"$codex_cleanup_status\" == \"REMOVED\" ]]; then\n print_success \"Removed legacy Codex MCP entries\"\n fi\n fi\n\n local codex_has_pal=false\n if [[ -f \"$codex_config\" ]] && grep -q '\\[mcp_servers\\.pal\\]' \"$codex_config\" 2>/dev/null; then\n codex_has_pal=true\n fi\n\n if [[ \"$codex_has_pal\" == false ]]; then\n echo \"\"\n read -p \"Configure PAL for Codex CLI? (Y/n): \" -n 1 -r\n echo \"\"\n if [[ $REPLY =~ ^[Nn]$ ]]; then\n print_info \"Skipping Codex CLI integration\"\n return 0\n fi\n\n print_info \"Updating Codex CLI configuration...\"\n\n mkdir -p \"$(dirname \"$codex_config\")\" 2>/dev/null || true\n\n if [[ -f \"$codex_config\" ]]; then\n cp \"$codex_config\" \"${codex_config}.backup_$(date +%Y%m%d_%H%M%S)\"\n fi\n\n local env_vars=$(parse_env_variables)\n\n {\n echo \"\"\n echo \"[mcp_servers.pal]\"\n echo \"command = \\\"bash\\\"\"\n echo \"args = [\\\"-c\\\", \\\"for p in \\$(which uvx 2>/dev/null) \\$HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \\\\\\\"\\$p\\\\\\\" ] && exec \\\\\\\"\\$p\\\\\\\" --from git+https://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server; done; echo 'uvx not found' >&2; exit 1\\\"]\"\n echo \"tool_timeout_sec = 1200\"\n echo \"\"\n echo \"[mcp_servers.pal.env]\"\n echo \"PATH = \\\"/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:\\$HOME/.local/bin:\\$HOME/.cargo/bin:\\$HOME/bin\\\"\"\n if [[ -n \"$env_vars\" ]]; then\n while IFS= read -r line; do\n if [[ -n \"$line\" && \"$line\" =~ ^([^=]+)=(.*)$ ]]; then\n local key=\"${BASH_REMATCH[1]}\"\n local value=\"${BASH_REMATCH[2]}\"\n local escaped_value\n escaped_value=$(echo \"$value\" | sed -e 's/\\\\/\\\\\\\\/g' -e 's/\"/\\\\\"/g')\n echo \"$key = \\\"$escaped_value\\\"\"\n fi\n done <<< \"$env_vars\"\n fi\n } >> \"$codex_config\"\n\n if [[ $? -ne 0 ]]; then\n print_error \"Failed to update Codex CLI config\"\n echo \"Manual config location: $codex_config\"\n echo \"Add this configuration:\"\ncat <<'CODExEOF'\n[mcp_servers.pal]\ncommand = \"sh\"\nargs = [\"-c\", \"exec \\$(which uvx 2>/dev/null || echo uvx) --from git+https://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server\"]\ntool_timeout_sec = 1200\n\n[mcp_servers.pal.env]\nPATH = \"/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:\\$HOME/.local/bin:\\$HOME/.cargo/bin:\\$HOME/bin\"\n\n[features]\nweb_search_request = true\nCODExEOF\n\n if [[ -n \"$env_vars\" ]]; then\n while IFS= read -r line; do\n if [[ -n \"$line\" && \"$line\" =~ ^([^=]+)=(.*)$ ]]; then\n local key=\"${BASH_REMATCH[1]}\"\n echo \"${key} = \\\"your_$(echo \"${key}\" | tr '[:upper:]' '[:lower:]')\\\"\"\n fi\n done <<< \"$env_vars\"\n else\n echo \"GEMINI_API_KEY = \\\"your_gemini_api_key_here\\\"\"\n fi\n return 0\n fi\n\n print_success \"Successfully configured Codex CLI\"\n echo \" Config: $codex_config\"\n echo \" Restart Codex CLI to use PAL MCP Server\"\n codex_has_pal=true\n else\n print_info \"Codex CLI already configured; refreshing Codex settings...\"\n fi\n\n if [[ \"$codex_has_pal\" == true ]]; then\n if ! grep -Eq '^\\s*web_search_request\\s*=' \"$codex_config\" 2>/dev/null; then\n echo \"\"\n print_info \"Web search requests let Codex pull fresh documentation for PAL's API lookup tooling.\"\n read -p \"Enable Codex CLI web search requests? (Y/n): \" -n 1 -r\n echo \"\"\n if [[ ! $REPLY =~ ^[Nn]$ ]]; then\n if grep -Eq '^\\s*\\[features\\]' \"$codex_config\" 2>/dev/null; then\n if ! python3 - \"$codex_config\" <<'PY'\nimport sys\nfrom pathlib import Path\n\ncfg_path = Path(sys.argv[1])\ncontent = cfg_path.read_text().splitlines()\noutput = []\nin_features = False\nadded = False\n\nfor line in content:\n stripped = line.strip()\n if stripped.startswith(\"[\") and stripped.endswith(\"]\"):\n if in_features and not added:\n output.append(\"web_search_request = true\")\n added = True\n in_features = stripped == \"[features]\"\n output.append(line)\n continue\n if in_features and stripped.startswith(\"web_search_request\"):\n added = True\n output.append(line)\n\nif in_features and not added:\n output.append(\"web_search_request = true\")\n\ncfg_path.write_text(\"\\n\".join(output) + \"\\n\")\nPY\n then\n print_error \"Failed to enable Codex web search request feature. Add 'web_search_request = true' under [features] in $codex_config manually.\"\n else\n print_success \"Enabled Codex web search request feature\"\n fi\n else\n {\n echo \"\"\n echo \"[features]\"\n echo \"web_search_request = true\"\n } >> \"$codex_config\" && print_success \"Enabled Codex web search request feature\" || \\\n print_error \"Failed to enable Codex web search request feature. Add 'web_search_request = true' under [features] in $codex_config manually.\"\n fi\n else\n print_info \"Skipping Codex web search request feature\"\n fi\n fi\n\n if grep -Eq '^\\s*\\[tools\\]' \"$codex_config\" 2>/dev/null && \\\n grep -Eq '^\\s*web_search\\s*=' \"$codex_config\" 2>/dev/null; then\n local removal_status\n if removal_status=$(python3 - \"$codex_config\" <<'PY' | tr -d '\\n'\nimport sys\nfrom pathlib import Path\n\ncfg_path = Path(sys.argv[1])\nlines = cfg_path.read_text().splitlines()\noutput = []\nin_tools = False\nremoved = False\n\nfor line in lines:\n stripped = line.strip()\n if stripped.startswith('[') and stripped.endswith(']'):\n in_tools = stripped == '[tools]'\n output.append(line)\n continue\n if in_tools and stripped.startswith('web_search'):\n removed = True\n continue\n output.append(line)\n\nif removed:\n cfg_path.write_text(\"\\n\".join(output) + \"\\n\")\n print('REMOVED', end='')\nelse:\n print('UNCHANGED', end='')\nPY\n); then\n if [[ \"$removal_status\" == \"REMOVED\" ]]; then\n print_success \"Removed deprecated Codex [tools].web_search entry\"\n fi\n else\n print_warning \"Failed to clean up deprecated Codex [tools].web_search entry; remove manually from $codex_config\"\n fi\n fi\n fi\n}\n\n# Print manual Qwen CLI configuration guidance\nprint_qwen_manual_instructions() {\n local python_cmd=\"$1\"\n local server_path=\"$2\"\n local script_dir=\"$3\"\n local config_path=\"$4\"\n local env_lines=\"$5\"\n\n local env_array=()\n if [[ -n \"$env_lines\" ]]; then\n while IFS= read -r line; do\n [[ -z \"$line\" ]] && continue\n env_array+=(\"$line\")\n done <<< \"$env_lines\"\n fi\n\n echo \"Manual config location: $config_path\"\n echo \"Add or update this entry:\"\n\n local env_block=\"\"\n if [[ ${#env_array[@]} -gt 0 ]]; then\n env_block=$' \"env\": {\\n'\n local first=true\n for env_entry in \"${env_array[@]}\"; do\n local key=\"${env_entry%%=*}\"\n local value=\"${env_entry#*=}\"\n value=${value//\\\\/\\\\\\\\}\n value=${value//\"/\\\\\"}\n if [[ \"$first\" == true ]]; then\n first=false\n env_block+=\" \\\"$key\\\": \\\"$value\\\"\"\n else\n env_block+=$',\\n '\n env_block+=\"\\\"$key\\\": \\\"$value\\\"\"\n fi\n done\n env_block+=$'\\n }'\n fi\n\n if [[ -n \"$env_block\" ]]; then\n cat << EOF\n{\n \"mcpServers\": {\n \"pal\": {\n \"command\": \"$python_cmd\",\n \"args\": [\"$server_path\"],\n \"cwd\": \"$script_dir\",\n$env_block\n }\n }\n}\nEOF\n else\n cat << EOF\n{\n \"mcpServers\": {\n \"pal\": {\n \"command\": \"$python_cmd\",\n \"args\": [\"$server_path\"],\n \"cwd\": \"$script_dir\"\n }\n }\n}\nEOF\n fi\n}\n\n# Check and update Qwen Code CLI configuration\ncheck_qwen_cli_integration() {\n local python_cmd=\"$1\"\n local server_path=\"$2\"\n\n if ! command -v qwen &> /dev/null; then\n return 0\n fi\n\n local qwen_config=\"$HOME/.qwen/settings.json\"\n local script_dir\n script_dir=$(dirname \"$server_path\")\n\n local env_vars\n env_vars=$(parse_env_variables)\n local env_array=()\n if [[ -n \"$env_vars\" ]]; then\n while IFS= read -r line; do\n if [[ -n \"$line\" && \"$line\" =~ ^([^=]+)=(.*)$ ]]; then\n env_array+=(\"${BASH_REMATCH[1]}=${BASH_REMATCH[2]}\")\n fi\n done <<< \"$env_vars\"\n fi\n\n local env_lines=\"\"\n if [[ ${#env_array[@]} -gt 0 ]]; then\n env_lines=$(printf '%s\\n' \"${env_array[@]}\")\n fi\n\n local legacy_names_csv\n legacy_names_csv=$(IFS=,; echo \"${LEGACY_MCP_NAMES[*]}\")\n\n if [[ -f \"$qwen_config\" ]]; then\n PAL_QWEN_LEGACY=\"$legacy_names_csv\" PAL_QWEN_CONFIG=\"$qwen_config\" python3 - <<'PYCLEANCONF' 2>/dev/null || true\nimport json\nimport os\nimport pathlib\nimport sys\n\nconfig_path = pathlib.Path(os.environ.get(\"PAL_QWEN_CONFIG\", \"\"))\nlegacy = [n for n in os.environ.get(\"PAL_QWEN_LEGACY\", \"\").split(\",\") if n]\n\nif not config_path.exists():\n sys.exit(0)\n\ntry:\n data = json.loads(config_path.read_text(encoding=\"utf-8\"))\nexcept Exception:\n sys.exit(0)\n\nif not isinstance(data, dict):\n sys.exit(0)\n\nservers = data.get(\"mcpServers\")\nif isinstance(servers, dict):\n removed = False\n for key in legacy:\n if servers.pop(key, None) is not None:\n removed = True\n if removed:\n config_path.write_text(json.dumps(data, indent=2))\n\nsys.exit(0)\nPYCLEANCONF\n fi\n\n local config_status=3\n if [[ -f \"$qwen_config\" ]]; then\n if python3 - \"$qwen_config\" \"$python_cmd\" \"$server_path\" \"$script_dir\" <<'PYCONF'\nimport json\nimport sys\n\nconfig_path, expected_cmd, expected_arg, expected_cwd = sys.argv[1:5]\ntry:\n with open(config_path, 'r', encoding='utf-8') as f:\n data = json.load(f)\nexcept FileNotFoundError:\n sys.exit(1)\nexcept Exception:\n sys.exit(5)\n\nservers = data.get('mcpServers')\nif not isinstance(servers, dict):\n sys.exit(3)\n\nconfig = servers.get('pal')\nif not isinstance(config, dict):\n sys.exit(3)\n\ncmd = config.get('command')\nargs = config.get('args') or []\ncwd = config.get('cwd')\n\ncwd_matches = cwd in (None, \"\", expected_cwd)\nif cmd == expected_cmd and len(args) == 1 and args[0] == expected_arg and cwd_matches:\n sys.exit(0)\n\nsys.exit(4)\nPYCONF\n then\n config_status=0\n else\n config_status=$?\n if [[ $config_status -eq 1 ]]; then\n config_status=3\n fi\n fi\n fi\n\n if [[ $config_status -eq 0 ]]; then\n return 0\n fi\n\n echo \"\"\n\n if [[ $config_status -eq 4 ]]; then\n print_warning \"Found existing Qwen CLI pal configuration with different settings.\"\n elif [[ $config_status -eq 5 ]]; then\n print_warning \"Unable to parse Qwen CLI settings; replacing with a fresh entry may help.\"\n fi\n\n local prompt=\"Configure PAL for Qwen CLI? (Y/n): \"\n if [[ $config_status -eq 4 || $config_status -eq 5 ]]; then\n prompt=\"Update Qwen CLI pal configuration? (Y/n): \"\n fi\n\n read -p \"$prompt\" -n 1 -r\n echo \"\"\n if [[ $REPLY =~ ^[Nn]$ ]]; then\n print_info \"Skipping Qwen CLI integration\"\n print_qwen_manual_instructions \"$python_cmd\" \"$server_path\" \"$script_dir\" \"$qwen_config\" \"$env_lines\"\n return 0\n fi\n\n mkdir -p \"$(dirname \"$qwen_config\")\" 2>/dev/null || true\n if [[ -f \"$qwen_config\" && $config_status -ne 3 ]]; then\n cp \"$qwen_config\" \"${qwen_config}.backup_$(date +%Y%m%d_%H%M%S)\" 2>/dev/null || true\n fi\n\n local update_output\n local update_status=0\n update_output=$(PAL_QWEN_ENV=\"$env_lines\" PAL_QWEN_CMD=\"$python_cmd\" PAL_QWEN_ARG=\"$server_path\" PAL_QWEN_CWD=\"$script_dir\" python3 - \"$qwen_config\" <<'PYUPDATE'\nimport json\nimport os\nimport pathlib\nimport sys\n\nconfig_path = pathlib.Path(sys.argv[1])\ncmd = os.environ['PAL_QWEN_CMD']\narg = os.environ['PAL_QWEN_ARG']\ncwd = os.environ['PAL_QWEN_CWD']\nenv_lines = os.environ.get('PAL_QWEN_ENV', '').splitlines()\n\nenv_map = {}\nfor line in env_lines:\n if not line.strip():\n continue\n if '=' in line:\n key, value = line.split('=', 1)\n env_map[key] = value\n\nif config_path.exists():\n try:\n with config_path.open('r', encoding='utf-8') as f:\n data = json.load(f)\n except Exception:\n data = {}\nelse:\n data = {}\n\nif not isinstance(data, dict):\n data = {}\n\nservers = data.get('mcpServers')\nif not isinstance(servers, dict):\n servers = {}\n data['mcpServers'] = servers\n\npal_config = {\n 'command': cmd,\n 'args': [arg],\n 'cwd': cwd,\n}\n\nif env_map:\n pal_config['env'] = env_map\n\nservers['pal'] = pal_config\n\nconfig_path.parent.mkdir(parents=True, exist_ok=True)\ntmp_path = config_path.with_suffix(config_path.suffix + '.tmp')\nwith tmp_path.open('w', encoding='utf-8') as f:\n json.dump(data, f, indent=2)\n f.write('\\n')\ntmp_path.replace(config_path)\nPYUPDATE\n ) || update_status=$?\n\n if [[ $update_status -eq 0 ]]; then\n print_success \"Successfully configured Qwen CLI\"\n echo \" Config: $qwen_config\"\n echo \" Restart Qwen CLI to use PAL MCP Server\"\n else\n print_error \"Failed to update Qwen CLI config\"\n if [[ -n \"$update_output\" ]]; then\n echo \"$update_output\"\n fi\n print_qwen_manual_instructions \"$python_cmd\" \"$server_path\" \"$script_dir\" \"$qwen_config\" \"$env_lines\"\n fi\n}\n\n# Display configuration instructions\ndisplay_config_instructions() {\n local python_cmd=\"$1\"\n local server_path=\"$2\"\n\n # Get script directory for Gemini CLI config\n local script_dir=$(dirname \"$server_path\")\n\n echo \"\"\n local config_header=\"PAL MCP SERVER CONFIGURATION\"\n echo \"===== $config_header =====\"\n printf '%*s\\n' \"$((${#config_header} + 12))\" | tr ' ' '='\n echo \"\"\n echo \"To use PAL MCP Server with your CLI clients:\"\n echo \"\"\n\n print_info \"1. For Claude Code (CLI):\"\n # Show command with environment variables\n local env_vars=$(parse_env_variables)\n local env_args=\"\"\n if [[ -n \"$env_vars\" ]]; then\n while IFS= read -r line; do\n if [[ -n \"$line\" && \"$line\" =~ ^([^=]+)=(.*)$ ]]; then\n env_args+=\" -e ${BASH_REMATCH[1]}=\\\"${BASH_REMATCH[2]}\\\"\"\n fi\n done <<< \"$env_vars\"\n fi\n echo -e \" ${GREEN}claude mcp add pal -s user$env_args -- $python_cmd $server_path${NC}\"\n echo \"\"\n\n print_info \"2. For Claude Desktop:\"\n echo \" Add this configuration to your Claude Desktop config file:\"\n echo \"\"\n \n # Generate example with actual environment variables that exist\n example_env=\"\"\n env_vars=$(parse_env_variables)\n if [[ -n \"$env_vars\" ]]; then\n local first_entry=true\n while IFS= read -r line; do\n if [[ -n \"$line\" && \"$line\" =~ ^([^=]+)=(.*)$ ]]; then\n local key=\"${BASH_REMATCH[1]}\"\n local value=\"your_$(echo \"${key}\" | tr '[:upper:]' '[:lower:]')\"\n \n if [[ \"$first_entry\" == true ]]; then\n first_entry=false\n example_env=\" \\\"$key\\\": \\\"$value\\\"\"\n else\n example_env+=\",\\n \\\"$key\\\": \\\"$value\\\"\"\n fi\n fi\n done <<< \"$env_vars\"\n fi\n \n if [[ -n \"$example_env\" ]]; then\n cat << EOF\n {\n \"mcpServers\": {\n \"pal\": {\n \"command\": \"$python_cmd\",\n \"args\": [\"$server_path\"],\n \"cwd\": \"$script_dir\",\n \"env\": {\n$(echo -e \"$example_env\")\n }\n }\n }\n }\nEOF\n else\n cat << EOF\n {\n \"mcpServers\": {\n \"pal\": {\n \"command\": \"$python_cmd\",\n \"args\": [\"$server_path\"],\n \"cwd\": \"$script_dir\"\n }\n }\n }\nEOF\n fi\n\n # Show platform-specific config location\n local config_path=$(get_claude_config_path)\n if [[ -n \"$config_path\" ]]; then\n echo \"\"\n print_info \" Config file location:\"\n echo -e \" ${YELLOW}$config_path${NC}\"\n fi\n\n echo \"\"\n print_info \"3. Restart Claude Desktop after updating the config file\"\n echo \"\"\n\n print_info \"For Gemini CLI:\"\n echo \" Add this configuration to ~/.gemini/settings.json:\"\n echo \"\"\n cat << EOF\n {\n \"mcpServers\": {\n \"pal\": {\n \"command\": \"$script_dir/pal-mcp-server\"\n }\n }\n }\nEOF\n echo \"\"\n\n print_info \"For Qwen Code CLI:\"\n echo \" Add this configuration to ~/.qwen/settings.json:\"\n echo \"\"\n if [[ -n \"$example_env\" ]]; then\n cat << EOF\n {\n \"mcpServers\": {\n \"pal\": {\n \"command\": \"$python_cmd\",\n \"args\": [\"$server_path\"],\n \"cwd\": \"$script_dir\",\n \"env\": {\n$(echo -e \"$example_env\")\n }\n }\n }\n }\nEOF\n else\n cat << EOF\n {\n \"mcpServers\": {\n \"pal\": {\n \"command\": \"$python_cmd\",\n \"args\": [\"$server_path\"],\n \"cwd\": \"$script_dir\"\n }\n }\n }\nEOF\n fi\n echo \"\"\n\n print_info \"For Codex CLI:\"\n echo \" Add this configuration to ~/.codex/config.toml:\"\n echo \"\"\n cat << EOF\n [mcp_servers.pal]\n command = \"bash\"\n args = [\"-c\", \"for p in \\$(which uvx 2>/dev/null) \\$HOME/.local/bin/uvx /opt/homebrew/bin/uvx /usr/local/bin/uvx uvx; do [ -x \\\\\\\"\\$p\\\\\\\" ] && exec \\\\\\\"\\$p\\\\\\\" --from git+https://github.com/BeehiveInnovations/pal-mcp-server.git pal-mcp-server; done; echo 'uvx not found' >&2; exit 1\"]\n\n [mcp_servers.pal.env]\n PATH = \"/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin:\\$HOME/.local/bin:\\$HOME/.cargo/bin:\\$HOME/bin\"\n GEMINI_API_KEY = \"your_gemini_api_key_here\"\nEOF\n echo \"\"\n}\n\n# Display setup instructions\ndisplay_setup_instructions() {\n local python_cmd=\"$1\"\n local server_path=\"$2\"\n\n echo \"\"\n local setup_header=\"SETUP COMPLETE\"\n echo \"===== $setup_header =====\"\n printf '%*s\\n' \"$((${#setup_header} + 12))\" | tr ' ' '='\n echo \"\"\n print_success \"PAL is ready to use!\"\n \n # Display enabled/disabled tools if DISABLED_TOOLS is configured\n if [[ -n \"${DISABLED_TOOLS:-}\" ]]; then\n echo \"\"\n print_info \"Tool Configuration:\"\n \n # Dynamically discover all available tools from the tools directory\n # Excludes: __pycache__, shared modules, models.py, listmodels.py, version.py\n local all_tools=()\n for tool_file in tools/*.py; do\n if [[ -f \"$tool_file\" ]]; then\n local tool_name=$(basename \"$tool_file\" .py)\n # Skip non-tool files\n if [[ \"$tool_name\" != \"models\" && \"$tool_name\" != \"listmodels\" && \"$tool_name\" != \"version\" && \"$tool_name\" != \"__init__\" ]]; then\n all_tools+=(\"$tool_name\")\n fi\n fi\n done\n \n # Convert DISABLED_TOOLS to array\n IFS=',' read -ra disabled_array <<< \"$DISABLED_TOOLS\"\n \n # Trim whitespace from disabled tools\n local disabled_tools=()\n for tool in \"${disabled_array[@]}\"; do\n disabled_tools+=(\"$(echo \"$tool\" | xargs)\")\n done\n \n # Determine enabled tools\n local enabled_tools=()\n for tool in \"${all_tools[@]}\"; do\n local is_disabled=false\n for disabled in \"${disabled_tools[@]}\"; do\n if [[ \"$tool\" == \"$disabled\" ]]; then\n is_disabled=true\n break\n fi\n done\n if [[ \"$is_disabled\" == false ]]; then\n enabled_tools+=(\"$tool\")\n fi\n done\n \n # Display enabled tools\n echo \"\"\n echo -e \" ${GREEN}Enabled Tools (${#enabled_tools[@]}):${NC}\"\n local enabled_list=\"\"\n for tool in \"${enabled_tools[@]}\"; do\n if [[ -n \"$enabled_list\" ]]; then\n enabled_list+=\", \"\n fi\n enabled_list+=\"$tool\"\n done\n echo \" $enabled_list\"\n \n # Display disabled tools\n echo \"\"\n echo -e \" ${YELLOW}Disabled Tools (${#disabled_tools[@]}):${NC}\"\n local disabled_list=\"\"\n for tool in \"${disabled_tools[@]}\"; do\n if [[ -n \"$disabled_list\" ]]; then\n disabled_list+=\", \"\n fi\n disabled_list+=\"$tool\"\n done\n echo \" $disabled_list\"\n \n echo \"\"\n echo \" To enable more tools, edit the DISABLED_TOOLS variable in .env\"\n fi\n}\n\n# ----------------------------------------------------------------------------\n# Log Management Functions\n# ----------------------------------------------------------------------------\n\n# Show help message\nshow_help() {\n local version=$(get_version)\n local header=\"πŸ€– PAL MCP Server v$version\"\n echo \"$header\"\n printf '%*s\\n' \"${#header}\" | tr ' ' '='\n echo \"\"\n echo \"Usage: $0 [OPTIONS]\"\n echo \"\"\n echo \"Options:\"\n echo \" -h, --help Show this help message\"\n echo \" -v, --version Show version information\"\n echo \" -f, --follow Follow server logs in real-time\"\n echo \" -c, --config Show configuration instructions for Claude clients\"\n echo \" --clear-cache Clear Python cache and exit (helpful for import issues)\"\n echo \"\"\n echo \"Examples:\"\n echo \" $0 Setup and start the MCP server\"\n echo \" $0 -f Setup and follow logs\"\n echo \" $0 -c Show configuration instructions\"\n echo \" $0 --version Show version only\"\n echo \" $0 --clear-cache Clear Python cache (fixes import issues)\"\n echo \"\"\n echo \"For more information, visit:\"\n echo \" https://github.com/BeehiveInnovations/pal-mcp-server\"\n}\n\n# Show version only\nshow_version() {\n local version=$(get_version)\n echo \"$version\"\n}\n\n# Follow logs\nfollow_logs() {\n local log_path=\"$LOG_DIR/$LOG_FILE\"\n\n echo \"Following server logs (Ctrl+C to stop)...\"\n echo \"\"\n\n # Create logs directory and file if they don't exist\n mkdir -p \"$LOG_DIR\"\n touch \"$log_path\"\n\n # Follow the log file\n tail -f \"$log_path\"\n}\n\n# ----------------------------------------------------------------------------\n# Main Function\n# ----------------------------------------------------------------------------\n\nmain() {\n # Parse command line arguments\n local arg=\"${1:-}\"\n\n case \"$arg\" in\n -h|--help)\n show_help\n exit 0\n ;;\n -v|--version)\n show_version\n exit 0\n ;;\n -c|--config)\n # Setup minimal environment to get paths for config display\n echo \"Setting up environment for configuration display...\"\n echo \"\"\n local python_cmd\n python_cmd=$(setup_environment) || exit 1\n local script_dir=$(get_script_dir)\n local server_path=\"$script_dir/server.py\"\n display_config_instructions \"$python_cmd\" \"$server_path\"\n exit 0\n ;;\n -f|--follow)\n # Continue with normal setup then follow logs\n ;;\n --clear-cache)\n # Clear cache and exit\n clear_python_cache\n print_success \"Cache cleared successfully\"\n echo \"\"\n echo \"You can now run './run-server.sh' normally\"\n exit 0\n ;;\n \"\")\n # Normal setup without following logs\n ;;\n *)\n print_error \"Unknown option: $arg\"\n echo \"\" >&2\n show_help\n exit 1\n ;;\n esac\n\n # Display header\n local main_header=\"πŸ€– PAL MCP Server\"\n echo \"$main_header\"\n printf '%*s\\n' \"${#main_header}\" | tr ' ' '='\n\n # Get and display version\n local version=$(get_version)\n echo \"Version: $version\"\n echo \"\"\n\n # Check if venv exists\n if [[ ! -d \"$VENV_PATH\" ]]; then\n echo \"Setting up Python environment for first time...\"\n fi\n\n # Step 1: Docker cleanup\n cleanup_docker\n\n # Step 1.5: Clear Python cache to prevent import issues\n clear_python_cache\n\n # Step 2: Setup environment file\n setup_env_file || exit 1\n\n # Step 3: Source .env file\n if [[ -f .env ]]; then\n set -a\n source .env\n set +a\n fi\n\n # Step 4: Check API keys (non-blocking - just warn if missing)\n check_api_keys\n\n # Step 5: Setup Python environment (uv-first approach)\n local python_cmd\n python_cmd=$(setup_environment) || exit 1\n\n # Step 6: Install dependencies\n install_dependencies \"$python_cmd\" || exit 1\n\n # Step 7: Get absolute server path\n local script_dir=$(get_script_dir)\n local server_path=\"$script_dir/server.py\"\n\n # Step 8: Display setup instructions\n display_setup_instructions \"$python_cmd\" \"$server_path\"\n\n # Step 9: Check Claude integrations\n check_claude_cli_integration \"$python_cmd\" \"$server_path\"\n check_claude_desktop_integration \"$python_cmd\" \"$server_path\"\n\n # Step 10: Check Gemini CLI integration\n check_gemini_cli_integration \"$script_dir\"\n\n # Step 11: Check Codex CLI integration\n check_codex_cli_integration\n\n # Step 12: Check Qwen CLI integration\n check_qwen_cli_integration \"$python_cmd\" \"$server_path\"\n\n # Step 13: Display log information\n echo \"\"\n echo \"Logs will be written to: $script_dir/$LOG_DIR/$LOG_FILE\"\n echo \"\"\n\n # Step 14: Handle command line arguments\n if [[ \"$arg\" == \"-f\" ]] || [[ \"$arg\" == \"--follow\" ]]; then\n follow_logs\n else\n echo \"To follow logs: ./run-server.sh -f\"\n echo \"To show config: ./run-server.sh -c\"\n echo \"To update: git pull, then run ./run-server.sh again\"\n echo \"\"\n echo \"Happy coding! πŸŽ‰\"\n fi\n}\n\n# ----------------------------------------------------------------------------\n# Script Entry Point\n# ----------------------------------------------------------------------------\n\nif [[ \"${BASH_SOURCE[0]}\" == \"$0\" ]]; then\n main \"$@\"\nfi\n" }, { "path": "run_integration_tests.ps1", "content": "<#\n.SYNOPSIS\n Integration test runner script for the PAL MCP server on Windows.\n\n.DESCRIPTION\n This PowerShell script prepares and runs integration tests for the PAL MCP server:\n - Sets up the test environment\n - Installs required dependencies\n - Runs automated integration tests\n - Displays test results and related logs\n - Allows output customization via parameters (e.g., display color)\n\n.PARAMETER Color\n Sets the display color for console messages (default: White).\n\n.EXAMPLE\n .\\run_integration_tests.ps1\n Prepares the environment and runs all integration tests.\n\n .\\run_integration_tests.ps1 -Color Cyan\n Runs the tests with messages displayed in cyan.\n\n.NOTES\n Project Author : BeehiveInnovations\n Script Author : GiGiDKR (https://github.com/GiGiDKR)\n Date : 07-05-2025\n Version : See config.py (__version__)\n References : https://github.com/BeehiveInnovations/pal-mcp-server\n#>\n#Requires -Version 5.1\n[CmdletBinding()]\nparam(\n [switch]$WithSimulator,\n [switch]$VerboseOutput\n)\n\n# Set error action preference\n$ErrorActionPreference = \"Stop\"\n\n# Colors for output\nfunction Write-ColorText {\n param(\n [Parameter(Mandatory)]\n [string]$Text,\n [string]$Color = \"White\",\n [switch]$NoNewline\n )\n if ($NoNewline) {\n Write-Host $Text -ForegroundColor $Color -NoNewline\n } else {\n Write-Host $Text -ForegroundColor $Color\n }\n}\n\nfunction Write-Emoji {\n param(\n [Parameter(Mandatory)]\n [string]$Emoji,\n [Parameter(Mandatory)]\n [string]$Text,\n [string]$Color = \"White\"\n )\n Write-Host \"$Emoji \" -NoNewline\n Write-ColorText $Text -Color $Color\n}\n\nWrite-Emoji \"πŸ§ͺ\" \"Running Integration Tests for PAL MCP Server\" -Color Cyan\nWrite-ColorText \"==============================================\" -Color Cyan\nWrite-ColorText \"These tests use real API calls with your configured keys\"\nWrite-Host \"\"\n\n# Check for virtual environment\n$venvPath = \".pal_venv\"\n$activateScript = if ($IsWindows -or $env:OS -eq \"Windows_NT\") {\n \"$venvPath\\Scripts\\Activate.ps1\"\n} else {\n \"$venvPath/bin/activate\"\n}\n\nif (Test-Path $venvPath) {\n Write-Emoji \"βœ…\" \"Virtual environment found\" -Color Green\n \n # Activate virtual environment (for PowerShell on Windows)\n if ($IsWindows -or $env:OS -eq \"Windows_NT\") {\n if (Test-Path \"$venvPath\\Scripts\\Activate.ps1\") {\n & \"$venvPath\\Scripts\\Activate.ps1\"\n } elseif (Test-Path \"$venvPath\\Scripts\\activate.bat\") {\n # Use Python directly from venv\n $env:PATH = \"$PWD\\$venvPath\\Scripts;$env:PATH\"\n }\n }\n} else {\n Write-Emoji \"❌\" \"No virtual environment found!\" -Color Red\n Write-ColorText \"Please run: .\\run-server.ps1 first\" -Color Yellow\n exit 1\n}\n\n# Check for .env file\nif (!(Test-Path \".env\")) {\n Write-Emoji \"⚠️\" \"Warning: No .env file found. Integration tests may fail without API keys.\" -Color Yellow\n Write-Host \"\"\n}\n\nWrite-Emoji \"πŸ”‘\" \"Checking API key availability:\" -Color Cyan\nWrite-ColorText \"---------------------------------\" -Color Cyan\n\n# Function to check if API key is configured\nfunction Test-ApiKey {\n param(\n [string]$KeyName\n )\n \n # Check environment variable\n $envValue = [Environment]::GetEnvironmentVariable($KeyName)\n if (![string]::IsNullOrWhiteSpace($envValue)) {\n return $true\n }\n \n # Check .env file\n if (Test-Path \".env\") {\n $envContent = Get-Content \".env\" -ErrorAction SilentlyContinue\n $found = $envContent | Where-Object { $_ -match \"^$KeyName\\s*=\" -and $_ -notmatch \"^$KeyName\\s*=\\s*$\" }\n return $found.Count -gt 0\n }\n \n return $false\n}\n\n# Check API keys\n$apiKeys = @(\n \"GEMINI_API_KEY\",\n \"OPENAI_API_KEY\", \n \"XAI_API_KEY\",\n \"OPENROUTER_API_KEY\",\n \"CUSTOM_API_URL\"\n)\n\nforeach ($key in $apiKeys) {\n if (Test-ApiKey $key) {\n if ($key -eq \"CUSTOM_API_URL\") {\n Write-Emoji \"βœ…\" \"$key configured (local models)\" -Color Green\n } else {\n Write-Emoji \"βœ…\" \"$key configured\" -Color Green\n }\n } else {\n Write-Emoji \"❌\" \"$key not found\" -Color Red\n }\n}\n\nWrite-Host \"\"\n\n# Load environment variables from .env if it exists\nif (Test-Path \".env\") {\n Get-Content \".env\" | ForEach-Object {\n if ($_ -match '^([^#][^=]*?)=(.*)$') {\n $name = $matches[1].Trim()\n $value = $matches[2].Trim()\n # Remove quotes if present\n $value = $value -replace '^[\"'']|[\"'']$', ''\n [Environment]::SetEnvironmentVariable($name, $value, \"Process\")\n }\n }\n}\n\n# Run integration tests\nWrite-Emoji \"πŸƒ\" \"Running integration tests...\" -Color Cyan\nWrite-ColorText \"------------------------------\" -Color Cyan\n\ntry {\n # Build pytest command\n $pytestArgs = @(\"tests/\", \"-v\", \"-m\", \"integration\", \"--tb=short\")\n \n if ($VerboseOutput) {\n $pytestArgs += \"--verbose\"\n }\n \n # Run pytest\n python -m pytest @pytestArgs\n \n if ($LASTEXITCODE -ne 0) {\n throw \"Integration tests failed\"\n }\n \n Write-Host \"\"\n Write-Emoji \"βœ…\" \"Integration tests completed!\" -Color Green\n} catch {\n Write-Host \"\"\n Write-Emoji \"❌\" \"Integration tests failed!\" -Color Red\n Write-ColorText \"Error: $_\" -Color Red\n exit 1\n}\n\n# Run simulator tests if requested\nif ($WithSimulator) {\n Write-Host \"\"\n Write-Emoji \"πŸ€–\" \"Running simulator tests...\" -Color Cyan\n Write-ColorText \"----------------------------\" -Color Cyan\n \n try {\n if ($VerboseOutput) {\n python communication_simulator_test.py --verbose\n } else {\n python communication_simulator_test.py\n }\n \n if ($LASTEXITCODE -ne 0) {\n Write-Host \"\"\n Write-Emoji \"❌\" \"Simulator tests failed!\" -Color Red\n Write-ColorText \"This may be due to a known issue in communication_simulator_test.py\" -Color Yellow\n Write-ColorText \"Integration tests completed successfully - you can proceed.\" -Color Green\n } else {\n Write-Host \"\"\n Write-Emoji \"βœ…\" \"Simulator tests completed!\" -Color Green\n }\n } catch {\n Write-Host \"\"\n Write-Emoji \"❌\" \"Simulator tests failed!\" -Color Red\n Write-ColorText \"Error: $_\" -Color Red\n Write-ColorText \"This may be due to a known issue in communication_simulator_test.py\" -Color Yellow\n Write-ColorText \"Integration tests completed successfully - you can proceed.\" -Color Green\n }\n}\n\nWrite-Host \"\"\nWrite-Emoji \"πŸ’‘\" \"Tips:\" -Color Yellow\nWrite-ColorText \"- Run '.\\run_integration_tests.ps1' for integration tests only\" -Color White\nWrite-ColorText \"- Run '.\\run_integration_tests.ps1 -WithSimulator' to also run simulator tests\" -Color White\nWrite-ColorText \"- Run '.\\code_quality_checks.ps1' for unit tests and linting\" -Color White\nWrite-ColorText \"- Check logs in logs\\mcp_server.log if tests fail\" -Color White\n" }, { "path": "run_integration_tests.sh", "content": "#!/bin/bash\n\n# PAL MCP Server - Run Integration Tests\n# This script runs integration tests that require API keys\n# Run this locally on your Mac to ensure everything works end-to-end\n\nset -e # Exit on any error\n\necho \"πŸ§ͺ Running Integration Tests for PAL MCP Server\"\necho \"==============================================\"\necho \"These tests use real API calls with your configured keys\"\necho \"\"\n\n# Activate virtual environment\nif [[ -f \".pal_venv/bin/activate\" ]]; then\n source .pal_venv/bin/activate\n echo \"βœ… Using virtual environment\"\nelse\n echo \"❌ No virtual environment found!\"\n echo \"Please run: ./run-server.sh first\"\n exit 1\nfi\n\n# Check for .env file\nif [[ ! -f \".env\" ]]; then\n echo \"⚠️ Warning: No .env file found. Integration tests may fail without API keys.\"\n echo \"\"\nfi\n\necho \"πŸ”‘ Checking API key availability:\"\necho \"---------------------------------\"\n\n# Check which API keys are available\nif [[ -n \"$GEMINI_API_KEY\" ]] || grep -q \"GEMINI_API_KEY=\" .env 2>/dev/null; then\n echo \"βœ… GEMINI_API_KEY configured\"\nelse\n echo \"❌ GEMINI_API_KEY not found\"\nfi\n\nif [[ -n \"$OPENAI_API_KEY\" ]] || grep -q \"OPENAI_API_KEY=\" .env 2>/dev/null; then\n echo \"βœ… OPENAI_API_KEY configured\"\nelse\n echo \"❌ OPENAI_API_KEY not found\"\nfi\n\nif [[ -n \"$XAI_API_KEY\" ]] || grep -q \"XAI_API_KEY=\" .env 2>/dev/null; then\n echo \"βœ… XAI_API_KEY configured\"\nelse\n echo \"❌ XAI_API_KEY not found\"\nfi\n\nif [[ -n \"$OPENROUTER_API_KEY\" ]] || grep -q \"OPENROUTER_API_KEY=\" .env 2>/dev/null; then\n echo \"βœ… OPENROUTER_API_KEY configured\"\nelse\n echo \"❌ OPENROUTER_API_KEY not found\"\nfi\n\nif [[ -n \"$CUSTOM_API_URL\" ]] || grep -q \"CUSTOM_API_URL=\" .env 2>/dev/null; then\n echo \"βœ… CUSTOM_API_URL configured (local models)\"\nelse\n echo \"❌ CUSTOM_API_URL not found\"\nfi\n\necho \"\"\n\n# Run integration tests\necho \"πŸƒ Running integration tests...\"\necho \"------------------------------\"\n\n# Run only integration tests (marked with @pytest.mark.integration)\npython -m pytest tests/ -v -m \"integration\" --tb=short\n\necho \"\"\necho \"βœ… Integration tests completed!\"\necho \"\"\n\n# Also run simulator tests if requested\nif [[ \"$1\" == \"--with-simulator\" ]]; then\n echo \"πŸ€– Running simulator tests...\"\n echo \"----------------------------\"\n python communication_simulator_test.py --verbose\n echo \"\"\n echo \"βœ… Simulator tests completed!\"\nfi\n\necho \"πŸ’‘ Tips:\"\necho \"- Run './run_integration_tests.sh' for integration tests only\"\necho \"- Run './run_integration_tests.sh --with-simulator' to also run simulator tests\"\necho \"- Run './code_quality_checks.sh' for unit tests and linting\"\necho \"- Check logs in logs/mcp_server.log if tests fail\"" }, { "path": "scripts/sync_version.py", "content": "#!/usr/bin/env python3\n\"\"\"\nSync version from pyproject.toml to config.py\nThis script is called by GitHub Actions after semantic-release updates the version\n\"\"\"\n\nimport re\nfrom datetime import datetime\n\nimport toml\n\n\ndef update_config_version():\n # Read version from pyproject.toml\n with open(\"pyproject.toml\") as f:\n data = toml.load(f)\n version = data[\"project\"][\"version\"]\n\n # Read current config.py\n with open(\"config.py\") as f:\n content = f.read()\n\n # Update version\n content = re.sub(r'__version__ = \"[^\"]*\"', f'__version__ = \"{version}\"', content)\n\n # Update date to current date\n today = datetime.now().strftime(\"%Y-%m-%d\")\n content = re.sub(r'__updated__ = \"[^\"]*\"', f'__updated__ = \"{today}\"', content)\n\n # Write back\n with open(\"config.py\", \"w\") as f:\n f.write(content)\n\n print(f\"Updated config.py to version {version}\")\n\n\nif __name__ == \"__main__\":\n update_config_version()\n" }, { "path": "server.py", "content": "\"\"\"\nPAL MCP Server - Main server implementation\n\nThis module implements the core MCP (Model Context Protocol) server that provides\nAI-powered tools for code analysis, review, and assistance using multiple AI models.\n\nThe server follows the MCP specification to expose various AI tools as callable functions\nthat can be used by MCP clients (like Claude). Each tool provides specialized functionality\nsuch as code review, debugging, deep thinking, and general chat capabilities.\n\nKey Components:\n- MCP Server: Handles protocol communication and tool discovery\n- Tool Registry: Maps tool names to their implementations\n- Request Handler: Processes incoming tool calls and returns formatted responses\n- Configuration: Manages API keys and model settings\n\nThe server runs on stdio (standard input/output) and communicates using JSON-RPC messages\nas defined by the MCP protocol.\n\"\"\"\n\nimport asyncio\nimport atexit\nimport logging\nimport os\nimport sys\nimport time\nfrom logging.handlers import RotatingFileHandler\nfrom pathlib import Path\nfrom typing import Any, Optional\n\nfrom mcp.server import Server # noqa: E402\nfrom mcp.server.models import InitializationOptions # noqa: E402\nfrom mcp.server.stdio import stdio_server # noqa: E402\nfrom mcp.types import ( # noqa: E402\n GetPromptResult,\n Prompt,\n PromptMessage,\n PromptsCapability,\n ServerCapabilities,\n TextContent,\n Tool,\n ToolAnnotations,\n ToolsCapability,\n)\n\nfrom config import ( # noqa: E402\n DEFAULT_MODEL,\n __version__,\n)\nfrom tools import ( # noqa: E402\n AnalyzeTool,\n ChallengeTool,\n ChatTool,\n CLinkTool,\n CodeReviewTool,\n ConsensusTool,\n DebugIssueTool,\n DocgenTool,\n ListModelsTool,\n LookupTool,\n PlannerTool,\n PrecommitTool,\n RefactorTool,\n SecauditTool,\n TestGenTool,\n ThinkDeepTool,\n TracerTool,\n VersionTool,\n)\nfrom tools.models import ToolOutput # noqa: E402\nfrom tools.shared.exceptions import ToolExecutionError # noqa: E402\nfrom utils.env import env_override_enabled, get_env # noqa: E402\n\n# Configure logging for server operations\n# Can be controlled via LOG_LEVEL environment variable (DEBUG, INFO, WARNING, ERROR)\nlog_level = (get_env(\"LOG_LEVEL\", \"DEBUG\") or \"DEBUG\").upper()\n\n# Create timezone-aware formatter\n\n\nclass LocalTimeFormatter(logging.Formatter):\n def formatTime(self, record, datefmt=None):\n \"\"\"Override to use local timezone instead of UTC\"\"\"\n ct = self.converter(record.created)\n if datefmt:\n s = time.strftime(datefmt, ct)\n else:\n t = time.strftime(\"%Y-%m-%d %H:%M:%S\", ct)\n s = f\"{t},{record.msecs:03.0f}\"\n return s\n\n\n# Configure both console and file logging\nlog_format = \"%(asctime)s - %(name)s - %(levelname)s - %(message)s\"\n\n# Clear any existing handlers first\nroot_logger = logging.getLogger()\nroot_logger.handlers.clear()\n\n# Create and configure stderr handler explicitly\nstderr_handler = logging.StreamHandler(sys.stderr)\nstderr_handler.setLevel(getattr(logging, log_level, logging.INFO))\nstderr_handler.setFormatter(LocalTimeFormatter(log_format))\nroot_logger.addHandler(stderr_handler)\n\n# Note: MCP stdio_server interferes with stderr during tool execution\n# All logs are properly written to logs/mcp_server.log for monitoring\n\n# Set root logger level\nroot_logger.setLevel(getattr(logging, log_level, logging.INFO))\n\n# Add rotating file handler for local log monitoring\n\ntry:\n # Create logs directory in project root\n log_dir = Path(__file__).parent / \"logs\"\n log_dir.mkdir(exist_ok=True)\n\n # Main server log with size-based rotation (20MB max per file)\n # This ensures logs don't grow indefinitely and are properly managed\n file_handler = RotatingFileHandler(\n log_dir / \"mcp_server.log\",\n maxBytes=20 * 1024 * 1024, # 20MB max file size\n backupCount=5, # Keep 10 rotated files (100MB total)\n encoding=\"utf-8\",\n )\n file_handler.setLevel(getattr(logging, log_level, logging.INFO))\n file_handler.setFormatter(LocalTimeFormatter(log_format))\n logging.getLogger().addHandler(file_handler)\n\n # Create a special logger for MCP activity tracking with size-based rotation\n mcp_logger = logging.getLogger(\"mcp_activity\")\n mcp_file_handler = RotatingFileHandler(\n log_dir / \"mcp_activity.log\",\n maxBytes=10 * 1024 * 1024, # 20MB max file size\n backupCount=2, # Keep 5 rotated files (20MB total)\n encoding=\"utf-8\",\n )\n mcp_file_handler.setLevel(logging.INFO)\n mcp_file_handler.setFormatter(LocalTimeFormatter(\"%(asctime)s - %(message)s\"))\n mcp_logger.addHandler(mcp_file_handler)\n mcp_logger.setLevel(logging.INFO)\n # Ensure MCP activity also goes to stderr\n mcp_logger.propagate = True\n\n # Log setup info directly to root logger since logger isn't defined yet\n logging.info(f\"Logging to: {log_dir / 'mcp_server.log'}\")\n logging.info(f\"Process PID: {os.getpid()}\")\n\nexcept Exception as e:\n print(f\"Warning: Could not set up file logging: {e}\", file=sys.stderr)\n\nlogger = logging.getLogger(__name__)\n\n# Log PAL_MCP_FORCE_ENV_OVERRIDE configuration for transparency\nif env_override_enabled():\n logger.info(\"PAL_MCP_FORCE_ENV_OVERRIDE enabled - .env file values will override system environment variables\")\n logger.debug(\"Environment override prevents conflicts between different AI tools passing cached API keys\")\nelse:\n logger.debug(\"PAL_MCP_FORCE_ENV_OVERRIDE disabled - system environment variables take precedence\")\n\n\n# Create the MCP server instance with a unique name identifier\n# This name is used by MCP clients to identify and connect to this specific server\nserver: Server = Server(\"pal-server\")\n\n\n# Constants for tool filtering\nESSENTIAL_TOOLS = {\"version\", \"listmodels\"}\n\n\ndef parse_disabled_tools_env() -> set[str]:\n \"\"\"\n Parse the DISABLED_TOOLS environment variable into a set of tool names.\n\n Returns:\n Set of lowercase tool names to disable, empty set if none specified\n \"\"\"\n disabled_tools_env = (get_env(\"DISABLED_TOOLS\", \"\") or \"\").strip()\n if not disabled_tools_env:\n return set()\n return {t.strip().lower() for t in disabled_tools_env.split(\",\") if t.strip()}\n\n\ndef validate_disabled_tools(disabled_tools: set[str], all_tools: dict[str, Any]) -> None:\n \"\"\"\n Validate the disabled tools list and log appropriate warnings.\n\n Args:\n disabled_tools: Set of tool names requested to be disabled\n all_tools: Dictionary of all available tool instances\n \"\"\"\n essential_disabled = disabled_tools & ESSENTIAL_TOOLS\n if essential_disabled:\n logger.warning(f\"Cannot disable essential tools: {sorted(essential_disabled)}\")\n unknown_tools = disabled_tools - set(all_tools.keys())\n if unknown_tools:\n logger.warning(f\"Unknown tools in DISABLED_TOOLS: {sorted(unknown_tools)}\")\n\n\ndef apply_tool_filter(all_tools: dict[str, Any], disabled_tools: set[str]) -> dict[str, Any]:\n \"\"\"\n Apply the disabled tools filter to create the final tools dictionary.\n\n Args:\n all_tools: Dictionary of all available tool instances\n disabled_tools: Set of tool names to disable\n\n Returns:\n Dictionary containing only enabled tools\n \"\"\"\n enabled_tools = {}\n for tool_name, tool_instance in all_tools.items():\n if tool_name in ESSENTIAL_TOOLS or tool_name not in disabled_tools:\n enabled_tools[tool_name] = tool_instance\n else:\n logger.debug(f\"Tool '{tool_name}' disabled via DISABLED_TOOLS\")\n return enabled_tools\n\n\ndef log_tool_configuration(disabled_tools: set[str], enabled_tools: dict[str, Any]) -> None:\n \"\"\"\n Log the final tool configuration for visibility.\n\n Args:\n disabled_tools: Set of tool names that were requested to be disabled\n enabled_tools: Dictionary of tools that remain enabled\n \"\"\"\n if not disabled_tools:\n logger.info(\"All tools enabled (DISABLED_TOOLS not set)\")\n return\n actual_disabled = disabled_tools - ESSENTIAL_TOOLS\n if actual_disabled:\n logger.debug(f\"Disabled tools: {sorted(actual_disabled)}\")\n logger.info(f\"Active tools: {sorted(enabled_tools.keys())}\")\n\n\ndef filter_disabled_tools(all_tools: dict[str, Any]) -> dict[str, Any]:\n \"\"\"\n Filter tools based on DISABLED_TOOLS environment variable.\n\n Args:\n all_tools: Dictionary of all available tool instances\n\n Returns:\n dict: Filtered dictionary containing only enabled tools\n \"\"\"\n disabled_tools = parse_disabled_tools_env()\n if not disabled_tools:\n log_tool_configuration(disabled_tools, all_tools)\n return all_tools\n validate_disabled_tools(disabled_tools, all_tools)\n enabled_tools = apply_tool_filter(all_tools, disabled_tools)\n log_tool_configuration(disabled_tools, enabled_tools)\n return enabled_tools\n\n\n# Initialize the tool registry with all available AI-powered tools\n# Each tool provides specialized functionality for different development tasks\n# Tools are instantiated once and reused across requests (stateless design)\nTOOLS = {\n \"chat\": ChatTool(), # Interactive development chat and brainstorming\n \"clink\": CLinkTool(), # Bridge requests to configured AI CLIs\n \"thinkdeep\": ThinkDeepTool(), # Step-by-step deep thinking workflow with expert analysis\n \"planner\": PlannerTool(), # Interactive sequential planner using workflow architecture\n \"consensus\": ConsensusTool(), # Step-by-step consensus workflow with multi-model analysis\n \"codereview\": CodeReviewTool(), # Comprehensive step-by-step code review workflow with expert analysis\n \"precommit\": PrecommitTool(), # Step-by-step pre-commit validation workflow\n \"debug\": DebugIssueTool(), # Root cause analysis and debugging assistance\n \"secaudit\": SecauditTool(), # Comprehensive security audit with OWASP Top 10 and compliance coverage\n \"docgen\": DocgenTool(), # Step-by-step documentation generation with complexity analysis\n \"analyze\": AnalyzeTool(), # General-purpose file and code analysis\n \"refactor\": RefactorTool(), # Step-by-step refactoring analysis workflow with expert validation\n \"tracer\": TracerTool(), # Static call path prediction and control flow analysis\n \"testgen\": TestGenTool(), # Step-by-step test generation workflow with expert validation\n \"challenge\": ChallengeTool(), # Critical challenge prompt wrapper to avoid automatic agreement\n \"apilookup\": LookupTool(), # Quick web/API lookup instructions\n \"listmodels\": ListModelsTool(), # List all available AI models by provider\n \"version\": VersionTool(), # Display server version and system information\n}\nTOOLS = filter_disabled_tools(TOOLS)\n\n# Rich prompt templates for all tools\nPROMPT_TEMPLATES = {\n \"chat\": {\n \"name\": \"chat\",\n \"description\": \"Chat and brainstorm ideas\",\n \"template\": \"Chat with {model} about this\",\n },\n \"clink\": {\n \"name\": \"clink\",\n \"description\": \"Forward a request to a configured AI CLI (e.g., Gemini)\",\n \"template\": \"Use clink with cli_name= to run this prompt\",\n },\n \"thinkdeep\": {\n \"name\": \"thinkdeeper\",\n \"description\": \"Step-by-step deep thinking workflow with expert analysis\",\n \"template\": \"Start comprehensive deep thinking workflow with {model} using {thinking_mode} thinking mode\",\n },\n \"planner\": {\n \"name\": \"planner\",\n \"description\": \"Break down complex ideas, problems, or projects into multiple manageable steps\",\n \"template\": \"Create a detailed plan with {model}\",\n },\n \"consensus\": {\n \"name\": \"consensus\",\n \"description\": \"Step-by-step consensus workflow with multi-model analysis\",\n \"template\": \"Start comprehensive consensus workflow with {model}\",\n },\n \"codereview\": {\n \"name\": \"review\",\n \"description\": \"Perform a comprehensive code review\",\n \"template\": \"Perform a comprehensive code review with {model}\",\n },\n \"precommit\": {\n \"name\": \"precommit\",\n \"description\": \"Step-by-step pre-commit validation workflow\",\n \"template\": \"Start comprehensive pre-commit validation workflow with {model}\",\n },\n \"debug\": {\n \"name\": \"debug\",\n \"description\": \"Debug an issue or error\",\n \"template\": \"Help debug this issue with {model}\",\n },\n \"secaudit\": {\n \"name\": \"secaudit\",\n \"description\": \"Comprehensive security audit with OWASP Top 10 coverage\",\n \"template\": \"Perform comprehensive security audit with {model}\",\n },\n \"docgen\": {\n \"name\": \"docgen\",\n \"description\": \"Generate comprehensive code documentation with complexity analysis\",\n \"template\": \"Generate comprehensive documentation with {model}\",\n },\n \"analyze\": {\n \"name\": \"analyze\",\n \"description\": \"Analyze files and code structure\",\n \"template\": \"Analyze these files with {model}\",\n },\n \"refactor\": {\n \"name\": \"refactor\",\n \"description\": \"Refactor and improve code structure\",\n \"template\": \"Refactor this code with {model}\",\n },\n \"tracer\": {\n \"name\": \"tracer\",\n \"description\": \"Trace code execution paths\",\n \"template\": \"Generate tracer analysis with {model}\",\n },\n \"testgen\": {\n \"name\": \"testgen\",\n \"description\": \"Generate comprehensive tests\",\n \"template\": \"Generate comprehensive tests with {model}\",\n },\n \"challenge\": {\n \"name\": \"challenge\",\n \"description\": \"Challenge a statement critically without automatic agreement\",\n \"template\": \"Challenge this statement critically\",\n },\n \"apilookup\": {\n \"name\": \"apilookup\",\n \"description\": \"Look up the latest API or SDK information\",\n \"template\": \"Lookup latest API docs for {model}\",\n },\n \"listmodels\": {\n \"name\": \"listmodels\",\n \"description\": \"List available AI models\",\n \"template\": \"List all available models\",\n },\n \"version\": {\n \"name\": \"version\",\n \"description\": \"Show server version and system information\",\n \"template\": \"Show PAL MCP Server version\",\n },\n}\n\n\ndef configure_providers():\n \"\"\"\n Configure and validate AI providers based on available API keys.\n\n This function checks for API keys and registers the appropriate providers.\n At least one valid API key (Gemini or OpenAI) is required.\n\n Raises:\n ValueError: If no valid API keys are found or conflicting configurations detected\n \"\"\"\n # Log environment variable status for debugging\n logger.debug(\"Checking environment variables for API keys...\")\n api_keys_to_check = [\"OPENAI_API_KEY\", \"OPENROUTER_API_KEY\", \"GEMINI_API_KEY\", \"XAI_API_KEY\", \"CUSTOM_API_URL\"]\n for key in api_keys_to_check:\n value = get_env(key)\n logger.debug(f\" {key}: {'[PRESENT]' if value else '[MISSING]'}\")\n from providers import ModelProviderRegistry\n from providers.azure_openai import AzureOpenAIProvider\n from providers.custom import CustomProvider\n from providers.dial import DIALModelProvider\n from providers.gemini import GeminiModelProvider\n from providers.openai import OpenAIModelProvider\n from providers.openrouter import OpenRouterProvider\n from providers.shared import ProviderType\n from providers.xai import XAIModelProvider\n from utils.model_restrictions import get_restriction_service\n\n valid_providers = []\n has_native_apis = False\n has_openrouter = False\n has_custom = False\n\n # Check for Gemini API key\n gemini_key = get_env(\"GEMINI_API_KEY\")\n if gemini_key and gemini_key != \"your_gemini_api_key_here\":\n valid_providers.append(\"Gemini\")\n has_native_apis = True\n logger.info(\"Gemini API key found - Gemini models available\")\n\n # Check for OpenAI API key\n openai_key = get_env(\"OPENAI_API_KEY\")\n logger.debug(f\"OpenAI key check: key={'[PRESENT]' if openai_key else '[MISSING]'}\")\n if openai_key and openai_key != \"your_openai_api_key_here\":\n valid_providers.append(\"OpenAI\")\n has_native_apis = True\n logger.info(\"OpenAI API key found\")\n else:\n if not openai_key:\n logger.debug(\"OpenAI API key not found in environment\")\n else:\n logger.debug(\"OpenAI API key is placeholder value\")\n\n # Check for Azure OpenAI configuration\n azure_key = get_env(\"AZURE_OPENAI_API_KEY\")\n azure_endpoint = get_env(\"AZURE_OPENAI_ENDPOINT\")\n azure_models_available = False\n if azure_key and azure_key != \"your_azure_openai_key_here\" and azure_endpoint:\n try:\n from providers.registries.azure import AzureModelRegistry\n\n azure_registry = AzureModelRegistry()\n if azure_registry.list_models():\n valid_providers.append(\"Azure OpenAI\")\n has_native_apis = True\n azure_models_available = True\n logger.info(\"Azure OpenAI configuration detected\")\n else:\n logger.warning(\n \"Azure OpenAI models configuration is empty. Populate conf/azure_models.json or set AZURE_MODELS_CONFIG_PATH.\"\n )\n except Exception as exc:\n logger.warning(f\"Failed to load Azure OpenAI models: {exc}\")\n\n # Check for X.AI API key\n xai_key = get_env(\"XAI_API_KEY\")\n if xai_key and xai_key != \"your_xai_api_key_here\":\n valid_providers.append(\"X.AI (GROK)\")\n has_native_apis = True\n logger.info(\"X.AI API key found - GROK models available\")\n\n # Check for DIAL API key\n dial_key = get_env(\"DIAL_API_KEY\")\n if dial_key and dial_key != \"your_dial_api_key_here\":\n valid_providers.append(\"DIAL\")\n has_native_apis = True\n logger.info(\"DIAL API key found - DIAL models available\")\n\n # Check for OpenRouter API key\n openrouter_key = get_env(\"OPENROUTER_API_KEY\")\n logger.debug(f\"OpenRouter key check: key={'[PRESENT]' if openrouter_key else '[MISSING]'}\")\n if openrouter_key and openrouter_key != \"your_openrouter_api_key_here\":\n valid_providers.append(\"OpenRouter\")\n has_openrouter = True\n logger.info(\"OpenRouter API key found - Multiple models available via OpenRouter\")\n else:\n if not openrouter_key:\n logger.debug(\"OpenRouter API key not found in environment\")\n else:\n logger.debug(\"OpenRouter API key is placeholder value\")\n\n # Check for custom API endpoint (Ollama, vLLM, etc.)\n custom_url = get_env(\"CUSTOM_API_URL\")\n if custom_url:\n # IMPORTANT: Always read CUSTOM_API_KEY even if empty\n # - Some providers (vLLM, LM Studio, enterprise APIs) require authentication\n # - Others (Ollama) work without authentication (empty key)\n # - DO NOT remove this variable - it's needed for provider factory function\n custom_key = get_env(\"CUSTOM_API_KEY\", \"\") or \"\" # Default to empty (Ollama doesn't need auth)\n custom_model = get_env(\"CUSTOM_MODEL_NAME\", \"llama3.2\") or \"llama3.2\"\n valid_providers.append(f\"Custom API ({custom_url})\")\n has_custom = True\n logger.info(f\"Custom API endpoint found: {custom_url} with model {custom_model}\")\n if custom_key:\n logger.debug(\"Custom API key provided for authentication\")\n else:\n logger.debug(\"No custom API key provided (using unauthenticated access)\")\n\n # Register providers in priority order:\n # 1. Native APIs first (most direct and efficient)\n registered_providers = []\n\n if has_native_apis:\n if gemini_key and gemini_key != \"your_gemini_api_key_here\":\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n registered_providers.append(ProviderType.GOOGLE.value)\n logger.debug(f\"Registered provider: {ProviderType.GOOGLE.value}\")\n if openai_key and openai_key != \"your_openai_api_key_here\":\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n registered_providers.append(ProviderType.OPENAI.value)\n logger.debug(f\"Registered provider: {ProviderType.OPENAI.value}\")\n if azure_models_available:\n ModelProviderRegistry.register_provider(ProviderType.AZURE, AzureOpenAIProvider)\n registered_providers.append(ProviderType.AZURE.value)\n logger.debug(f\"Registered provider: {ProviderType.AZURE.value}\")\n if xai_key and xai_key != \"your_xai_api_key_here\":\n ModelProviderRegistry.register_provider(ProviderType.XAI, XAIModelProvider)\n registered_providers.append(ProviderType.XAI.value)\n logger.debug(f\"Registered provider: {ProviderType.XAI.value}\")\n if dial_key and dial_key != \"your_dial_api_key_here\":\n ModelProviderRegistry.register_provider(ProviderType.DIAL, DIALModelProvider)\n registered_providers.append(ProviderType.DIAL.value)\n logger.debug(f\"Registered provider: {ProviderType.DIAL.value}\")\n\n # 2. Custom provider second (for local/private models)\n if has_custom:\n # Factory function that creates CustomProvider with proper parameters\n def custom_provider_factory(api_key=None):\n # api_key is CUSTOM_API_KEY (can be empty for Ollama), base_url from CUSTOM_API_URL\n base_url = get_env(\"CUSTOM_API_URL\", \"\") or \"\"\n return CustomProvider(api_key=api_key or \"\", base_url=base_url) # Use provided API key or empty string\n\n ModelProviderRegistry.register_provider(ProviderType.CUSTOM, custom_provider_factory)\n registered_providers.append(ProviderType.CUSTOM.value)\n logger.debug(f\"Registered provider: {ProviderType.CUSTOM.value}\")\n\n # 3. OpenRouter last (catch-all for everything else)\n if has_openrouter:\n ModelProviderRegistry.register_provider(ProviderType.OPENROUTER, OpenRouterProvider)\n registered_providers.append(ProviderType.OPENROUTER.value)\n logger.debug(f\"Registered provider: {ProviderType.OPENROUTER.value}\")\n\n # Log all registered providers\n if registered_providers:\n logger.info(f\"Registered providers: {', '.join(registered_providers)}\")\n\n # Require at least one valid provider\n if not valid_providers:\n raise ValueError(\n \"At least one API configuration is required. Please set either:\\n\"\n \"- GEMINI_API_KEY for Gemini models\\n\"\n \"- OPENAI_API_KEY for OpenAI models\\n\"\n \"- XAI_API_KEY for X.AI GROK models\\n\"\n \"- DIAL_API_KEY for DIAL models\\n\"\n \"- OPENROUTER_API_KEY for OpenRouter (multiple models)\\n\"\n \"- CUSTOM_API_URL for local models (Ollama, vLLM, etc.)\"\n )\n\n logger.info(f\"Available providers: {', '.join(valid_providers)}\")\n\n # Log provider priority\n priority_info = []\n if has_native_apis:\n priority_info.append(\"Native APIs (Gemini, OpenAI)\")\n if has_custom:\n priority_info.append(\"Custom endpoints\")\n if has_openrouter:\n priority_info.append(\"OpenRouter (catch-all)\")\n\n if len(priority_info) > 1:\n logger.info(f\"Provider priority: {' β†’ '.join(priority_info)}\")\n\n # Register cleanup function for providers\n def cleanup_providers():\n \"\"\"Clean up all registered providers on shutdown.\"\"\"\n try:\n registry = ModelProviderRegistry()\n if hasattr(registry, \"_initialized_providers\"):\n # Iterate over provider instances (values), not (type, instance) tuples\n for provider in list(registry._initialized_providers.values()):\n try:\n if provider and hasattr(provider, \"close\"):\n provider.close()\n except Exception:\n # Logger might be closed during shutdown\n pass\n except Exception:\n # Silently ignore any errors during cleanup\n pass\n\n atexit.register(cleanup_providers)\n\n # Check and log model restrictions\n restriction_service = get_restriction_service()\n restrictions = restriction_service.get_restriction_summary()\n\n if restrictions:\n logger.info(\"Model restrictions configured:\")\n for provider_name, allowed_models in restrictions.items():\n if isinstance(allowed_models, list):\n logger.info(f\" {provider_name}: {', '.join(allowed_models)}\")\n else:\n logger.info(f\" {provider_name}: {allowed_models}\")\n\n # Validate restrictions against known models\n provider_instances = {}\n provider_types_to_validate = [ProviderType.GOOGLE, ProviderType.OPENAI, ProviderType.XAI, ProviderType.DIAL]\n for provider_type in provider_types_to_validate:\n provider = ModelProviderRegistry.get_provider(provider_type)\n if provider:\n provider_instances[provider_type] = provider\n\n if provider_instances:\n restriction_service.validate_against_known_models(provider_instances)\n else:\n logger.info(\"No model restrictions configured - all models allowed\")\n\n # Check if auto mode has any models available after restrictions\n from config import IS_AUTO_MODE\n\n if IS_AUTO_MODE:\n available_models = ModelProviderRegistry.get_available_models(respect_restrictions=True)\n if not available_models:\n logger.error(\n \"Auto mode is enabled but no models are available after applying restrictions. \"\n \"Please check your OPENAI_ALLOWED_MODELS and GOOGLE_ALLOWED_MODELS settings.\"\n )\n raise ValueError(\n \"No models available for auto mode due to restrictions. \"\n \"Please adjust your allowed model settings or disable auto mode.\"\n )\n\n\n@server.list_tools()\nasync def handle_list_tools() -> list[Tool]:\n \"\"\"\n List all available tools with their descriptions and input schemas.\n\n This handler is called by MCP clients during initialization to discover\n what tools are available. Each tool provides:\n - name: Unique identifier for the tool\n - description: Detailed explanation of what the tool does\n - inputSchema: JSON Schema defining the expected parameters\n\n Returns:\n List of Tool objects representing all available tools\n \"\"\"\n logger.debug(\"MCP client requested tool list\")\n\n # Try to log client info if available (this happens early in the handshake)\n try:\n from utils.client_info import format_client_info, get_client_info_from_context\n\n client_info = get_client_info_from_context(server)\n if client_info:\n formatted = format_client_info(client_info)\n logger.info(f\"MCP Client Connected: {formatted}\")\n\n # Log to activity file as well\n try:\n mcp_activity_logger = logging.getLogger(\"mcp_activity\")\n friendly_name = client_info.get(\"friendly_name\", \"CLI Agent\")\n raw_name = client_info.get(\"name\", \"Unknown\")\n version = client_info.get(\"version\", \"Unknown\")\n mcp_activity_logger.info(f\"MCP_CLIENT_INFO: {friendly_name} (raw={raw_name} v{version})\")\n except Exception:\n pass\n except Exception as e:\n logger.debug(f\"Could not log client info during list_tools: {e}\")\n tools = []\n\n # Add all registered AI-powered tools from the TOOLS registry\n for tool in TOOLS.values():\n # Get optional annotations from the tool\n annotations = tool.get_annotations()\n tool_annotations = ToolAnnotations(**annotations) if annotations else None\n\n tools.append(\n Tool(\n name=tool.name,\n description=tool.description,\n inputSchema=tool.get_input_schema(),\n annotations=tool_annotations,\n )\n )\n\n # Log cache efficiency info\n openrouter_key_for_cache = get_env(\"OPENROUTER_API_KEY\")\n if openrouter_key_for_cache and openrouter_key_for_cache != \"your_openrouter_api_key_here\":\n logger.debug(\"OpenRouter registry cache used efficiently across all tool schemas\")\n\n logger.debug(f\"Returning {len(tools)} tools to MCP client\")\n return tools\n\n\n@server.call_tool()\nasync def handle_call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:\n \"\"\"\n Handle incoming tool execution requests from MCP clients.\n\n This is the main request dispatcher that routes tool calls to their appropriate handlers.\n It supports both AI-powered tools (from TOOLS registry) and utility tools (implemented as\n static functions).\n\n CONVERSATION LIFECYCLE MANAGEMENT:\n This function serves as the central orchestrator for multi-turn AI-to-AI conversations:\n\n 1. THREAD RESUMPTION: When continuation_id is present, it reconstructs complete conversation\n context from in-memory storage including conversation history and file references\n\n 2. CROSS-TOOL CONTINUATION: Enables seamless handoffs between different tools (analyze β†’\n codereview β†’ debug) while preserving full conversation context and file references\n\n 3. CONTEXT INJECTION: Reconstructed conversation history is embedded into tool prompts\n using the dual prioritization strategy:\n - Files: Newest-first prioritization (recent file versions take precedence)\n - Turns: Newest-first collection for token efficiency, chronological presentation for LLM\n\n 4. FOLLOW-UP GENERATION: After tool execution, generates continuation offers for ongoing\n AI-to-AI collaboration with natural language instructions\n\n STATELESS TO STATEFUL BRIDGE:\n The MCP protocol is inherently stateless, but this function bridges the gap by:\n - Loading persistent conversation state from in-memory storage\n - Reconstructing full multi-turn context for tool execution\n - Enabling tools to access previous exchanges and file references\n - Supporting conversation chains across different tool types\n\n Args:\n name: The name of the tool to execute (e.g., \"analyze\", \"chat\", \"codereview\")\n arguments: Dictionary of arguments to pass to the tool, potentially including:\n - continuation_id: UUID for conversation thread resumption\n - files: File paths for analysis (subject to deduplication)\n - prompt: User request or follow-up question\n - model: Specific AI model to use (optional)\n\n Returns:\n List of TextContent objects containing:\n - Tool's primary response with analysis/results\n - Continuation offers for follow-up conversations (when applicable)\n - Structured JSON responses with status and content\n\n Raises:\n ValueError: If continuation_id is invalid or conversation thread not found\n Exception: For tool-specific errors or execution failures\n\n Example Conversation Flow:\n 1. The CLI calls analyze tool with files β†’ creates new thread\n 2. Thread ID returned in continuation offer\n 3. The CLI continues with codereview tool + continuation_id β†’ full context preserved\n 4. Multiple tools can collaborate using same thread ID\n \"\"\"\n logger.info(f\"MCP tool call: {name}\")\n logger.debug(f\"MCP tool arguments: {list(arguments.keys())}\")\n\n # Log to activity file for monitoring\n try:\n mcp_activity_logger = logging.getLogger(\"mcp_activity\")\n mcp_activity_logger.info(f\"TOOL_CALL: {name} with {len(arguments)} arguments\")\n except Exception:\n pass\n\n # Handle thread context reconstruction if continuation_id is present\n if \"continuation_id\" in arguments and arguments[\"continuation_id\"]:\n continuation_id = arguments[\"continuation_id\"]\n logger.debug(f\"Resuming conversation thread: {continuation_id}\")\n logger.debug(\n f\"[CONVERSATION_DEBUG] Tool '{name}' resuming thread {continuation_id} with {len(arguments)} arguments\"\n )\n logger.debug(f\"[CONVERSATION_DEBUG] Original arguments keys: {list(arguments.keys())}\")\n\n # Log to activity file for monitoring\n try:\n mcp_activity_logger = logging.getLogger(\"mcp_activity\")\n mcp_activity_logger.info(f\"CONVERSATION_RESUME: {name} resuming thread {continuation_id}\")\n except Exception:\n pass\n\n arguments = await reconstruct_thread_context(arguments)\n logger.debug(f\"[CONVERSATION_DEBUG] After thread reconstruction, arguments keys: {list(arguments.keys())}\")\n if \"_remaining_tokens\" in arguments:\n logger.debug(f\"[CONVERSATION_DEBUG] Remaining token budget: {arguments['_remaining_tokens']:,}\")\n\n # Route to AI-powered tools that require Gemini API calls\n if name in TOOLS:\n logger.info(f\"Executing tool '{name}' with {len(arguments)} parameter(s)\")\n tool = TOOLS[name]\n\n # EARLY MODEL RESOLUTION AT MCP BOUNDARY\n # Resolve model before passing to tool - this ensures consistent model handling\n # NOTE: Consensus tool is exempt as it handles multiple models internally\n from providers.registry import ModelProviderRegistry\n from utils.file_utils import check_total_file_size\n from utils.model_context import ModelContext\n\n # Get model from arguments or use default\n model_name = arguments.get(\"model\") or DEFAULT_MODEL\n logger.debug(f\"Initial model for {name}: {model_name}\")\n\n # Parse model:option format if present\n model_name, model_option = parse_model_option(model_name)\n if model_option:\n logger.info(f\"Parsed model format - model: '{model_name}', option: '{model_option}'\")\n else:\n logger.info(f\"Parsed model format - model: '{model_name}'\")\n\n # Consensus tool handles its own model configuration validation\n # No special handling needed at server level\n\n # Skip model resolution for tools that don't require models (e.g., planner)\n if not tool.requires_model():\n logger.debug(f\"Tool {name} doesn't require model resolution - skipping model validation\")\n # Execute tool directly without model context\n return await tool.execute(arguments)\n\n # Handle auto mode at MCP boundary - resolve to specific model\n if model_name.lower() == \"auto\":\n # Get tool category to determine appropriate model\n tool_category = tool.get_model_category()\n resolved_model = ModelProviderRegistry.get_preferred_fallback_model(tool_category)\n logger.info(f\"Auto mode resolved to {resolved_model} for {name} (category: {tool_category.value})\")\n model_name = resolved_model\n # Update arguments with resolved model\n arguments[\"model\"] = model_name\n\n # Validate model availability at MCP boundary\n provider = ModelProviderRegistry.get_provider_for_model(model_name)\n if not provider:\n # Get list of available models for error message\n available_models = list(ModelProviderRegistry.get_available_models(respect_restrictions=True).keys())\n tool_category = tool.get_model_category()\n suggested_model = ModelProviderRegistry.get_preferred_fallback_model(tool_category)\n\n error_message = (\n f\"Model '{model_name}' is not available with current API keys. \"\n f\"Available models: {', '.join(available_models)}. \"\n f\"Suggested model for {name}: '{suggested_model}' \"\n f\"(category: {tool_category.value})\"\n )\n error_output = ToolOutput(\n status=\"error\",\n content=error_message,\n content_type=\"text\",\n metadata={\"tool_name\": name, \"requested_model\": model_name},\n )\n raise ToolExecutionError(error_output.model_dump_json())\n\n # Create model context with resolved model and option\n model_context = ModelContext(model_name, model_option)\n arguments[\"_model_context\"] = model_context\n arguments[\"_resolved_model_name\"] = model_name\n logger.debug(\n f\"Model context created for {model_name} with {model_context.capabilities.context_window} token capacity\"\n )\n if model_option:\n logger.debug(f\"Model option stored in context: '{model_option}'\")\n\n # EARLY FILE SIZE VALIDATION AT MCP BOUNDARY\n # Check file sizes before tool execution using resolved model\n argument_files = arguments.get(\"absolute_file_paths\")\n if argument_files:\n logger.debug(f\"Checking file sizes for {len(argument_files)} files with model {model_name}\")\n file_size_check = check_total_file_size(argument_files, model_name)\n if file_size_check:\n logger.warning(f\"File size check failed for {name} with model {model_name}\")\n raise ToolExecutionError(ToolOutput(**file_size_check).model_dump_json())\n\n # Execute tool with pre-resolved model context\n result = await tool.execute(arguments)\n logger.info(f\"Tool '{name}' execution completed\")\n\n # Log completion to activity file\n try:\n mcp_activity_logger = logging.getLogger(\"mcp_activity\")\n mcp_activity_logger.info(f\"TOOL_COMPLETED: {name}\")\n except Exception:\n pass\n return result\n\n # Handle unknown tool requests gracefully\n else:\n return [TextContent(type=\"text\", text=f\"Unknown tool: {name}\")]\n\n\ndef parse_model_option(model_string: str) -> tuple[str, Optional[str]]:\n \"\"\"\n Parse model:option format into model name and option.\n\n Handles different formats:\n - OpenRouter models: preserve :free, :beta, :preview suffixes as part of model name\n - Ollama/Custom models: split on : to extract tags like :latest\n - Consensus stance: extract options like :for, :against\n\n Args:\n model_string: String that may contain \"model:option\" format\n\n Returns:\n tuple: (model_name, option) where option may be None\n \"\"\"\n if \":\" in model_string and not model_string.startswith(\"http\"): # Avoid parsing URLs\n # Check if this looks like an OpenRouter model (contains /)\n if \"/\" in model_string and model_string.count(\":\") == 1:\n # Could be openai/gpt-4:something - check what comes after colon\n parts = model_string.split(\":\", 1)\n suffix = parts[1].strip().lower()\n\n # Known OpenRouter suffixes to preserve\n if suffix in [\"free\", \"beta\", \"preview\"]:\n return model_string.strip(), None\n\n # For other patterns (Ollama tags, consensus stances), split normally\n parts = model_string.split(\":\", 1)\n model_name = parts[0].strip()\n model_option = parts[1].strip() if len(parts) > 1 else None\n return model_name, model_option\n return model_string.strip(), None\n\n\ndef get_follow_up_instructions(current_turn_count: int, max_turns: int = None) -> str:\n \"\"\"\n Generate dynamic follow-up instructions based on conversation turn count.\n\n Args:\n current_turn_count: Current number of turns in the conversation\n max_turns: Maximum allowed turns before conversation ends (defaults to MAX_CONVERSATION_TURNS)\n\n Returns:\n Follow-up instructions to append to the tool prompt\n \"\"\"\n if max_turns is None:\n from utils.conversation_memory import MAX_CONVERSATION_TURNS\n\n max_turns = MAX_CONVERSATION_TURNS\n\n if current_turn_count >= max_turns - 1:\n # We're at or approaching the turn limit - no more follow-ups\n return \"\"\"\nIMPORTANT: This is approaching the final exchange in this conversation thread.\nDo NOT include any follow-up questions in your response. Provide your complete\nfinal analysis and recommendations.\"\"\"\n else:\n # Normal follow-up instructions\n remaining_turns = max_turns - current_turn_count - 1\n return f\"\"\"\n\nCONVERSATION CONTINUATION: You can continue this discussion with the agent! ({remaining_turns} exchanges remaining)\n\nFeel free to ask clarifying questions or suggest areas for deeper exploration naturally within your response.\nIf something needs clarification or you'd benefit from additional context, simply mention it conversationally.\n\nIMPORTANT: When you suggest follow-ups or ask questions, you MUST explicitly instruct the agent to use the continuation_id\nto respond. Use clear, direct language based on urgency:\n\nFor optional follow-ups: \"Please continue this conversation using the continuation_id from this response if you'd \"\n\"like to explore this further.\"\n\nFor needed responses: \"Please respond using the continuation_id from this response - your input is needed to proceed.\"\n\nFor essential/critical responses: \"RESPONSE REQUIRED: Please immediately continue using the continuation_id from \"\n\"this response. Cannot proceed without your clarification/input.\"\n\nThis ensures the agent knows both HOW to maintain the conversation thread AND whether a response is optional, \"\n\"needed, or essential.\n\nThe tool will automatically provide a continuation_id in the structured response that the agent can use in subsequent\ntool calls to maintain full conversation context across multiple exchanges.\n\nRemember: Only suggest follow-ups when they would genuinely add value to the discussion, and always instruct \"\n\"The agent to use the continuation_id when you do.\"\"\"\n\n\nasync def reconstruct_thread_context(arguments: dict[str, Any]) -> dict[str, Any]:\n \"\"\"\n Reconstruct conversation context for stateless-to-stateful thread continuation.\n\n This is a critical function that transforms the inherently stateless MCP protocol into\n stateful multi-turn conversations. It loads persistent conversation state from in-memory\n storage and rebuilds complete conversation context using the sophisticated dual prioritization\n strategy implemented in the conversation memory system.\n\n CONTEXT RECONSTRUCTION PROCESS:\n\n 1. THREAD RETRIEVAL: Loads complete ThreadContext from storage using continuation_id\n - Includes all conversation turns with tool attribution\n - Preserves file references and cross-tool context\n - Handles conversation chains across multiple linked threads\n\n 2. CONVERSATION HISTORY BUILDING: Uses build_conversation_history() to create\n comprehensive context with intelligent prioritization:\n\n FILE PRIORITIZATION (Newest-First Throughout):\n - When same file appears in multiple turns, newest reference wins\n - File embedding prioritizes recent versions, excludes older duplicates\n - Token budget management ensures most relevant files are preserved\n\n CONVERSATION TURN PRIORITIZATION (Dual Strategy):\n - Collection Phase: Processes turns newest-to-oldest for token efficiency\n - Presentation Phase: Presents turns chronologically for LLM understanding\n - Ensures recent context is preserved when token budget is constrained\n\n 3. CONTEXT INJECTION: Embeds reconstructed history into tool request arguments\n - Conversation history becomes part of the tool's prompt context\n - Files referenced in previous turns are accessible to current tool\n - Cross-tool knowledge transfer is seamless and comprehensive\n\n 4. TOKEN BUDGET MANAGEMENT: Applies model-specific token allocation\n - Balances conversation history vs. file content vs. response space\n - Gracefully handles token limits with intelligent exclusion strategies\n - Preserves most contextually relevant information within constraints\n\n CROSS-TOOL CONTINUATION SUPPORT:\n This function enables seamless handoffs between different tools:\n - Analyze tool β†’ Debug tool: Full file context and analysis preserved\n - Chat tool β†’ CodeReview tool: Conversation context maintained\n - Any tool β†’ Any tool: Complete cross-tool knowledge transfer\n\n ERROR HANDLING & RECOVERY:\n - Thread expiration: Provides clear instructions for conversation restart\n - Storage unavailability: Graceful degradation with error messaging\n - Invalid continuation_id: Security validation and user-friendly errors\n\n Args:\n arguments: Original request arguments dictionary containing:\n - continuation_id (required): UUID of conversation thread to resume\n - Other tool-specific arguments that will be preserved\n\n Returns:\n dict[str, Any]: Enhanced arguments dictionary with conversation context:\n - Original arguments preserved\n - Conversation history embedded in appropriate format for tool consumption\n - File context from previous turns made accessible\n - Cross-tool knowledge transfer enabled\n\n Raises:\n ValueError: When continuation_id is invalid, thread not found, or expired\n Includes user-friendly recovery instructions\n\n Performance Characteristics:\n - O(1) thread lookup in memory\n - O(n) conversation history reconstruction where n = number of turns\n - Intelligent token budgeting prevents context window overflow\n - Optimized file deduplication minimizes redundant content\n\n Example Usage Flow:\n 1. CLI: \"Continue analyzing the security issues\" + continuation_id\n 2. reconstruct_thread_context() loads previous analyze conversation\n 3. Debug tool receives full context including previous file analysis\n 4. Debug tool can reference specific findings from analyze tool\n 5. Natural cross-tool collaboration without context loss\n \"\"\"\n from utils.conversation_memory import add_turn, build_conversation_history, get_thread\n\n continuation_id = arguments[\"continuation_id\"]\n\n # Get thread context from storage\n logger.debug(f\"[CONVERSATION_DEBUG] Looking up thread {continuation_id} in storage\")\n context = get_thread(continuation_id)\n if not context:\n logger.warning(f\"Thread not found: {continuation_id}\")\n logger.debug(f\"[CONVERSATION_DEBUG] Thread {continuation_id} not found in storage or expired\")\n\n # Log to activity file for monitoring\n try:\n mcp_activity_logger = logging.getLogger(\"mcp_activity\")\n mcp_activity_logger.info(f\"CONVERSATION_ERROR: Thread {continuation_id} not found or expired\")\n except Exception:\n pass\n\n # Return error asking CLI to restart conversation with full context\n raise ValueError(\n f\"Conversation thread '{continuation_id}' was not found or has expired. \"\n f\"This may happen if the conversation was created more than 3 hours ago or if the \"\n f\"server was restarted. \"\n f\"Please restart the conversation by providing your full question/prompt without the \"\n f\"continuation_id parameter. \"\n f\"This will create a new conversation thread that can continue with follow-up exchanges.\"\n )\n\n # Add user's new input to the conversation\n user_prompt = arguments.get(\"prompt\", \"\")\n if user_prompt:\n # Capture files referenced in this turn\n user_files = arguments.get(\"absolute_file_paths\") or []\n logger.debug(f\"[CONVERSATION_DEBUG] Adding user turn to thread {continuation_id}\")\n from utils.token_utils import estimate_tokens\n\n user_prompt_tokens = estimate_tokens(user_prompt)\n logger.debug(\n f\"[CONVERSATION_DEBUG] User prompt length: {len(user_prompt)} chars (~{user_prompt_tokens:,} tokens)\"\n )\n logger.debug(f\"[CONVERSATION_DEBUG] User files: {user_files}\")\n success = add_turn(continuation_id, \"user\", user_prompt, files=user_files)\n if not success:\n logger.warning(f\"Failed to add user turn to thread {continuation_id}\")\n logger.debug(\"[CONVERSATION_DEBUG] Failed to add user turn - thread may be at turn limit or expired\")\n else:\n logger.debug(f\"[CONVERSATION_DEBUG] Successfully added user turn to thread {continuation_id}\")\n\n # Create model context early to use for history building\n from utils.model_context import ModelContext\n\n tool = TOOLS.get(context.tool_name)\n requires_model = tool.requires_model() if tool else True\n\n # Check if we should use the model from the previous conversation turn\n model_from_args = arguments.get(\"model\")\n if requires_model and not model_from_args and context.turns:\n # Find the last assistant turn to get the model used\n for turn in reversed(context.turns):\n if turn.role == \"assistant\" and turn.model_name:\n arguments[\"model\"] = turn.model_name\n logger.debug(f\"[CONVERSATION_DEBUG] Using model from previous turn: {turn.model_name}\")\n break\n\n # Resolve an effective model for context reconstruction when DEFAULT_MODEL=auto\n model_context = arguments.get(\"_model_context\")\n\n if requires_model:\n if model_context is None:\n try:\n model_context = ModelContext.from_arguments(arguments)\n arguments.setdefault(\"_resolved_model_name\", model_context.model_name)\n except ValueError as exc:\n from providers.registry import ModelProviderRegistry\n\n fallback_model = None\n if tool is not None:\n try:\n fallback_model = ModelProviderRegistry.get_preferred_fallback_model(tool.get_model_category())\n except Exception as fallback_exc: # pragma: no cover - defensive log\n logger.debug(\n f\"[CONVERSATION_DEBUG] Unable to resolve fallback model for {context.tool_name}: {fallback_exc}\"\n )\n\n if fallback_model is None:\n available_models = ModelProviderRegistry.get_available_model_names()\n if available_models:\n fallback_model = available_models[0]\n\n if fallback_model is None:\n raise\n\n logger.debug(\n f\"[CONVERSATION_DEBUG] Falling back to model '{fallback_model}' for context reconstruction after error: {exc}\"\n )\n model_context = ModelContext(fallback_model)\n arguments[\"_model_context\"] = model_context\n arguments[\"_resolved_model_name\"] = fallback_model\n\n from providers.registry import ModelProviderRegistry\n\n provider = ModelProviderRegistry.get_provider_for_model(model_context.model_name)\n if provider is None:\n fallback_model = None\n if tool is not None:\n try:\n fallback_model = ModelProviderRegistry.get_preferred_fallback_model(tool.get_model_category())\n except Exception as fallback_exc: # pragma: no cover - defensive log\n logger.debug(\n f\"[CONVERSATION_DEBUG] Unable to resolve fallback model for {context.tool_name}: {fallback_exc}\"\n )\n\n if fallback_model is None:\n available_models = ModelProviderRegistry.get_available_model_names()\n if available_models:\n fallback_model = available_models[0]\n\n if fallback_model is None:\n raise ValueError(\n f\"Conversation continuation failed: model '{model_context.model_name}' is not available with current API keys.\"\n )\n\n logger.debug(\n f\"[CONVERSATION_DEBUG] Model '{model_context.model_name}' unavailable; swapping to '{fallback_model}' for context reconstruction\"\n )\n model_context = ModelContext(fallback_model)\n arguments[\"_model_context\"] = model_context\n arguments[\"_resolved_model_name\"] = fallback_model\n else:\n if model_context is None:\n from providers.registry import ModelProviderRegistry\n\n fallback_model = None\n if tool is not None:\n try:\n fallback_model = ModelProviderRegistry.get_preferred_fallback_model(tool.get_model_category())\n except Exception as fallback_exc: # pragma: no cover - defensive log\n logger.debug(\n f\"[CONVERSATION_DEBUG] Unable to resolve fallback model for {context.tool_name}: {fallback_exc}\"\n )\n\n if fallback_model is None:\n available_models = ModelProviderRegistry.get_available_model_names()\n if available_models:\n fallback_model = available_models[0]\n\n if fallback_model is None:\n raise ValueError(\n \"Conversation continuation failed: no available models detected for context reconstruction.\"\n )\n\n logger.debug(\n f\"[CONVERSATION_DEBUG] Using fallback model '{fallback_model}' for context reconstruction of tool without model requirement\"\n )\n model_context = ModelContext(fallback_model)\n arguments[\"_model_context\"] = model_context\n arguments[\"_resolved_model_name\"] = fallback_model\n\n # Build conversation history with model-specific limits\n logger.debug(f\"[CONVERSATION_DEBUG] Building conversation history for thread {continuation_id}\")\n logger.debug(f\"[CONVERSATION_DEBUG] Thread has {len(context.turns)} turns, tool: {context.tool_name}\")\n logger.debug(f\"[CONVERSATION_DEBUG] Using model: {model_context.model_name}\")\n conversation_history, conversation_tokens = build_conversation_history(context, model_context)\n logger.debug(f\"[CONVERSATION_DEBUG] Conversation history built: {conversation_tokens:,} tokens\")\n logger.debug(\n f\"[CONVERSATION_DEBUG] Conversation history length: {len(conversation_history)} chars (~{conversation_tokens:,} tokens)\"\n )\n\n # Add dynamic follow-up instructions based on turn count\n follow_up_instructions = get_follow_up_instructions(len(context.turns))\n logger.debug(f\"[CONVERSATION_DEBUG] Follow-up instructions added for turn {len(context.turns)}\")\n\n # All tools now use standardized 'prompt' field\n original_prompt = arguments.get(\"prompt\", \"\")\n logger.debug(\"[CONVERSATION_DEBUG] Extracting user input from 'prompt' field\")\n original_prompt_tokens = estimate_tokens(original_prompt) if original_prompt else 0\n logger.debug(\n f\"[CONVERSATION_DEBUG] User input length: {len(original_prompt)} chars (~{original_prompt_tokens:,} tokens)\"\n )\n\n # Merge original context with new prompt and follow-up instructions\n if conversation_history:\n enhanced_prompt = (\n f\"{conversation_history}\\n\\n=== NEW USER INPUT ===\\n{original_prompt}\\n\\n{follow_up_instructions}\"\n )\n else:\n enhanced_prompt = f\"{original_prompt}\\n\\n{follow_up_instructions}\"\n\n # Update arguments with enhanced context and remaining token budget\n enhanced_arguments = arguments.copy()\n\n # Store the enhanced prompt in the prompt field\n enhanced_arguments[\"prompt\"] = enhanced_prompt\n # Store the original user prompt separately for size validation\n enhanced_arguments[\"_original_user_prompt\"] = original_prompt\n logger.debug(\"[CONVERSATION_DEBUG] Storing enhanced prompt in 'prompt' field\")\n logger.debug(\"[CONVERSATION_DEBUG] Storing original user prompt in '_original_user_prompt' field\")\n\n # Calculate remaining token budget based on current model\n # (model_context was already created above for history building)\n token_allocation = model_context.calculate_token_allocation()\n\n # Calculate remaining tokens for files/new content\n # History has already consumed some of the content budget\n remaining_tokens = token_allocation.content_tokens - conversation_tokens\n enhanced_arguments[\"_remaining_tokens\"] = max(0, remaining_tokens) # Ensure non-negative\n enhanced_arguments[\"_model_context\"] = model_context # Pass context for use in tools\n\n logger.debug(\"[CONVERSATION_DEBUG] Token budget calculation:\")\n logger.debug(f\"[CONVERSATION_DEBUG] Model: {model_context.model_name}\")\n logger.debug(f\"[CONVERSATION_DEBUG] Total capacity: {token_allocation.total_tokens:,}\")\n logger.debug(f\"[CONVERSATION_DEBUG] Content allocation: {token_allocation.content_tokens:,}\")\n logger.debug(f\"[CONVERSATION_DEBUG] Conversation tokens: {conversation_tokens:,}\")\n logger.debug(f\"[CONVERSATION_DEBUG] Remaining tokens: {remaining_tokens:,}\")\n\n # Merge original context parameters (files, etc.) with new request\n if context.initial_context:\n logger.debug(f\"[CONVERSATION_DEBUG] Merging initial context with {len(context.initial_context)} parameters\")\n for key, value in context.initial_context.items():\n if key not in enhanced_arguments and key not in [\"temperature\", \"thinking_mode\", \"model\"]:\n enhanced_arguments[key] = value\n logger.debug(f\"[CONVERSATION_DEBUG] Merged initial context param: {key}\")\n\n logger.info(f\"Reconstructed context for thread {continuation_id} (turn {len(context.turns)})\")\n logger.debug(f\"[CONVERSATION_DEBUG] Final enhanced arguments keys: {list(enhanced_arguments.keys())}\")\n\n if \"absolute_file_paths\" in enhanced_arguments:\n logger.debug(\n f\"[CONVERSATION_DEBUG] Final files in enhanced arguments: {enhanced_arguments['absolute_file_paths']}\"\n )\n\n # Log to activity file for monitoring\n try:\n mcp_activity_logger = logging.getLogger(\"mcp_activity\")\n mcp_activity_logger.info(\n f\"CONVERSATION_CONTINUATION: Thread {continuation_id} turn {len(context.turns)} - \"\n f\"{len(context.turns)} previous turns loaded\"\n )\n except Exception:\n pass\n\n return enhanced_arguments\n\n\n@server.list_prompts()\nasync def handle_list_prompts() -> list[Prompt]:\n \"\"\"\n List all available prompts for CLI Code shortcuts.\n\n This handler returns prompts that enable shortcuts like /pal:thinkdeeper.\n We automatically generate prompts from all tools (1:1 mapping) plus add\n a few marketing aliases with richer templates for commonly used tools.\n\n Returns:\n List of Prompt objects representing all available prompts\n \"\"\"\n logger.debug(\"MCP client requested prompt list\")\n prompts = []\n\n # Add a prompt for each tool with rich templates\n for tool_name, tool in TOOLS.items():\n if tool_name in PROMPT_TEMPLATES:\n # Use the rich template\n template_info = PROMPT_TEMPLATES[tool_name]\n prompts.append(\n Prompt(\n name=template_info[\"name\"],\n description=template_info[\"description\"],\n arguments=[], # MVP: no structured args\n )\n )\n else:\n # Fallback for any tools without templates (shouldn't happen)\n prompts.append(\n Prompt(\n name=tool_name,\n description=f\"Use {tool.name} tool\",\n arguments=[],\n )\n )\n\n # Add special \"continue\" prompt\n prompts.append(\n Prompt(\n name=\"continue\",\n description=\"Continue the previous conversation using the chat tool\",\n arguments=[],\n )\n )\n\n logger.debug(f\"Returning {len(prompts)} prompts to MCP client\")\n return prompts\n\n\n@server.get_prompt()\nasync def handle_get_prompt(name: str, arguments: dict[str, Any] = None) -> GetPromptResult:\n \"\"\"\n Get prompt details and generate the actual prompt text.\n\n This handler is called when a user invokes a prompt (e.g., /pal:thinkdeeper or /pal:chat:gpt5).\n It generates the appropriate text that CLI will then use to call the\n underlying tool.\n\n Supports structured prompt names like \"chat:gpt5\" where:\n - \"chat\" is the tool name\n - \"gpt5\" is the model to use\n\n Args:\n name: The name of the prompt to execute (can include model like \"chat:gpt5\")\n arguments: Optional arguments for the prompt (e.g., model, thinking_mode)\n\n Returns:\n GetPromptResult with the prompt details and generated message\n\n Raises:\n ValueError: If the prompt name is unknown\n \"\"\"\n logger.debug(f\"MCP client requested prompt: {name} with args: {arguments}\")\n\n # Handle special \"continue\" case\n if name.lower() == \"continue\":\n # This is \"/pal:continue\" - use chat tool as default for continuation\n tool_name = \"chat\"\n template_info = {\n \"name\": \"continue\",\n \"description\": \"Continue the previous conversation\",\n \"template\": \"Continue the conversation\",\n }\n logger.debug(\"Using /pal:continue - defaulting to chat tool\")\n else:\n # Find the corresponding tool by checking prompt names\n tool_name = None\n template_info = None\n\n # Check if it's a known prompt name\n for t_name, t_info in PROMPT_TEMPLATES.items():\n if t_info[\"name\"] == name:\n tool_name = t_name\n template_info = t_info\n break\n\n # If not found, check if it's a direct tool name\n if not tool_name and name in TOOLS:\n tool_name = name\n template_info = {\n \"name\": name,\n \"description\": f\"Use {name} tool\",\n \"template\": f\"Use {name}\",\n }\n\n if not tool_name:\n logger.error(f\"Unknown prompt requested: {name}\")\n raise ValueError(f\"Unknown prompt: {name}\")\n\n # Get the template\n template = template_info.get(\"template\", f\"Use {tool_name}\")\n\n # Safe template expansion with defaults\n final_model = arguments.get(\"model\", \"auto\") if arguments else \"auto\"\n\n prompt_args = {\n \"model\": final_model,\n \"thinking_mode\": arguments.get(\"thinking_mode\", \"medium\") if arguments else \"medium\",\n }\n\n logger.debug(f\"Using model '{final_model}' for prompt '{name}'\")\n\n # Safely format the template\n try:\n prompt_text = template.format(**prompt_args)\n except KeyError as e:\n logger.warning(f\"Missing template argument {e} for prompt {name}, using raw template\")\n prompt_text = template # Fallback to raw template\n\n # Generate tool call instruction\n if name.lower() == \"continue\":\n # \"/pal:continue\" case\n tool_instruction = (\n f\"Continue the previous conversation using the {tool_name} tool. \"\n \"CRITICAL: You MUST provide the continuation_id from the previous response to maintain conversation context. \"\n \"Additionally, you should reuse the same model that was used in the previous exchange for consistency, unless \"\n \"the user specifically asks for a different model name to be used.\"\n )\n else:\n # Simple prompt case\n tool_instruction = prompt_text\n\n return GetPromptResult(\n prompt=Prompt(\n name=name,\n description=template_info[\"description\"],\n arguments=[],\n ),\n messages=[\n PromptMessage(\n role=\"user\",\n content={\"type\": \"text\", \"text\": tool_instruction},\n )\n ],\n )\n\n\nasync def main():\n \"\"\"\n Main entry point for the MCP server.\n\n Initializes the Gemini API configuration and starts the server using\n stdio transport. The server will continue running until the client\n disconnects or an error occurs.\n\n The server communicates via standard input/output streams using the\n MCP protocol's JSON-RPC message format.\n \"\"\"\n # Validate and configure providers based on available API keys\n configure_providers()\n\n # Log startup message\n logger.info(\"PAL MCP Server starting up...\")\n logger.info(f\"Log level: {log_level}\")\n\n # Note: MCP client info will be logged during the protocol handshake\n # (when handle_list_tools is called)\n\n # Log current model mode\n from config import IS_AUTO_MODE\n\n if IS_AUTO_MODE:\n logger.info(\"Model mode: AUTO (CLI will select the best model for each task)\")\n else:\n logger.info(f\"Model mode: Fixed model '{DEFAULT_MODEL}'\")\n\n # Import here to avoid circular imports\n from config import DEFAULT_THINKING_MODE_THINKDEEP\n\n logger.info(f\"Default thinking mode (ThinkDeep): {DEFAULT_THINKING_MODE_THINKDEEP}\")\n\n logger.info(f\"Available tools: {list(TOOLS.keys())}\")\n logger.info(\"Server ready - waiting for tool requests...\")\n\n # Prepare dynamic instructions for the MCP client based on model mode\n if IS_AUTO_MODE:\n handshake_instructions = (\n \"When the user names a specific model (e.g. 'use chat with gpt5'), send that exact model in the tool call. \"\n \"When no model is mentioned, first use the `listmodels` tool from PAL to obtain available models to choose the best one from.\"\n )\n else:\n handshake_instructions = (\n \"When the user names a specific model (e.g. 'use chat with gpt5'), send that exact model in the tool call. \"\n f\"When no model is mentioned, default to '{DEFAULT_MODEL}'.\"\n )\n\n # Run the server using stdio transport (standard input/output)\n # This allows the server to be launched by MCP clients as a subprocess\n async with stdio_server() as (read_stream, write_stream):\n await server.run(\n read_stream,\n write_stream,\n InitializationOptions(\n server_name=\"PAL\",\n server_version=__version__,\n instructions=handshake_instructions,\n capabilities=ServerCapabilities(\n tools=ToolsCapability(), # Advertise tool support capability\n prompts=PromptsCapability(), # Advertise prompt support capability\n ),\n ),\n )\n\n\ndef run():\n \"\"\"Console script entry point for pal-mcp-server.\"\"\"\n try:\n asyncio.run(main())\n except KeyboardInterrupt:\n # Handle graceful shutdown\n pass\n\n\nif __name__ == \"__main__\":\n run()\n" }, { "path": "simulator_tests/__init__.py", "content": "\"\"\"\nCommunication Simulator Tests Package\n\nThis package contains individual test modules for the PAL MCP Communication Simulator.\nEach test is in its own file for better organization and maintainability.\n\"\"\"\n\nfrom .base_test import BaseSimulatorTest\nfrom .test_analyze_validation import AnalyzeValidationTest\nfrom .test_basic_conversation import BasicConversationTest\nfrom .test_chat_simple_validation import ChatSimpleValidationTest\nfrom .test_codereview_validation import CodeReviewValidationTest\nfrom .test_consensus_conversation import TestConsensusConversation\nfrom .test_consensus_three_models import TestConsensusThreeModels\nfrom .test_consensus_workflow_accurate import TestConsensusWorkflowAccurate\nfrom .test_content_validation import ContentValidationTest\nfrom .test_conversation_chain_validation import ConversationChainValidationTest\nfrom .test_cross_tool_comprehensive import CrossToolComprehensiveTest\nfrom .test_cross_tool_continuation import CrossToolContinuationTest\nfrom .test_debug_certain_confidence import DebugCertainConfidenceTest\nfrom .test_debug_validation import DebugValidationTest\nfrom .test_line_number_validation import LineNumberValidationTest\nfrom .test_logs_validation import LogsValidationTest\nfrom .test_model_thinking_config import TestModelThinkingConfig\nfrom .test_o3_model_selection import O3ModelSelectionTest\nfrom .test_o3_pro_expensive import O3ProExpensiveTest\nfrom .test_ollama_custom_url import OllamaCustomUrlTest\nfrom .test_openrouter_fallback import OpenRouterFallbackTest\nfrom .test_openrouter_models import OpenRouterModelsTest\nfrom .test_per_tool_deduplication import PerToolDeduplicationTest\nfrom .test_planner_continuation_history import PlannerContinuationHistoryTest\nfrom .test_planner_validation import PlannerValidationTest\nfrom .test_precommitworkflow_validation import PrecommitWorkflowValidationTest\nfrom .test_prompt_size_limit_bug import PromptSizeLimitBugTest\n\n# Redis validation test removed - no longer needed for standalone server\nfrom .test_refactor_validation import RefactorValidationTest\nfrom .test_secaudit_validation import SecauditValidationTest\nfrom .test_testgen_validation import TestGenValidationTest\nfrom .test_thinkdeep_validation import ThinkDeepWorkflowValidationTest\nfrom .test_token_allocation_validation import TokenAllocationValidationTest\nfrom .test_vision_capability import VisionCapabilityTest\nfrom .test_xai_models import XAIModelsTest\n\n# Test registry for dynamic loading\nTEST_REGISTRY = {\n \"basic_conversation\": BasicConversationTest,\n \"chat_validation\": ChatSimpleValidationTest,\n \"codereview_validation\": CodeReviewValidationTest,\n \"content_validation\": ContentValidationTest,\n \"per_tool_deduplication\": PerToolDeduplicationTest,\n \"cross_tool_continuation\": CrossToolContinuationTest,\n \"cross_tool_comprehensive\": CrossToolComprehensiveTest,\n \"line_number_validation\": LineNumberValidationTest,\n \"logs_validation\": LogsValidationTest,\n # \"redis_validation\": RedisValidationTest, # Removed - no longer needed for standalone server\n \"model_thinking_config\": TestModelThinkingConfig,\n \"o3_model_selection\": O3ModelSelectionTest,\n \"ollama_custom_url\": OllamaCustomUrlTest,\n \"openrouter_fallback\": OpenRouterFallbackTest,\n \"openrouter_models\": OpenRouterModelsTest,\n \"planner_validation\": PlannerValidationTest,\n \"planner_continuation_history\": PlannerContinuationHistoryTest,\n \"precommit_validation\": PrecommitWorkflowValidationTest,\n \"token_allocation_validation\": TokenAllocationValidationTest,\n \"testgen_validation\": TestGenValidationTest,\n \"thinkdeep_validation\": ThinkDeepWorkflowValidationTest,\n \"refactor_validation\": RefactorValidationTest,\n \"secaudit_validation\": SecauditValidationTest,\n \"debug_validation\": DebugValidationTest,\n \"debug_certain_confidence\": DebugCertainConfidenceTest,\n \"conversation_chain_validation\": ConversationChainValidationTest,\n \"vision_capability\": VisionCapabilityTest,\n \"xai_models\": XAIModelsTest,\n \"consensus_conversation\": TestConsensusConversation,\n \"consensus_workflow_accurate\": TestConsensusWorkflowAccurate,\n \"consensus_three_models\": TestConsensusThreeModels,\n \"analyze_validation\": AnalyzeValidationTest,\n \"prompt_size_limit_bug\": PromptSizeLimitBugTest,\n # \"o3_pro_expensive\": O3ProExpensiveTest, # COMMENTED OUT - too expensive to run by default\n}\n\n__all__ = [\n \"BaseSimulatorTest\",\n \"BasicConversationTest\",\n \"ChatSimpleValidationTest\",\n \"CodeReviewValidationTest\",\n \"ContentValidationTest\",\n \"PerToolDeduplicationTest\",\n \"CrossToolContinuationTest\",\n \"CrossToolComprehensiveTest\",\n \"LineNumberValidationTest\",\n \"LogsValidationTest\",\n \"TestModelThinkingConfig\",\n \"O3ModelSelectionTest\",\n \"O3ProExpensiveTest\",\n \"OllamaCustomUrlTest\",\n \"OpenRouterFallbackTest\",\n \"OpenRouterModelsTest\",\n \"PlannerValidationTest\",\n \"PlannerContinuationHistoryTest\",\n \"PrecommitWorkflowValidationTest\",\n \"TokenAllocationValidationTest\",\n \"TestGenValidationTest\",\n \"ThinkDeepWorkflowValidationTest\",\n \"RefactorValidationTest\",\n \"SecauditValidationTest\",\n \"DebugValidationTest\",\n \"DebugCertainConfidenceTest\",\n \"ConversationChainValidationTest\",\n \"VisionCapabilityTest\",\n \"XAIModelsTest\",\n \"TestConsensusConversation\",\n \"TestConsensusWorkflowAccurate\",\n \"TestConsensusThreeModels\",\n \"AnalyzeValidationTest\",\n \"PromptSizeLimitBugTest\",\n \"TEST_REGISTRY\",\n]\n" }, { "path": "simulator_tests/base_test.py", "content": "#!/usr/bin/env python3\n\"\"\"\nBase Test Class for Communication Simulator Tests\n\nProvides common functionality and utilities for all simulator tests.\n\"\"\"\n\nimport json\nimport logging\nimport os\nimport subprocess\nfrom typing import Optional\n\nfrom .log_utils import LogUtils\n\n\nclass BaseSimulatorTest:\n \"\"\"Base class for all communication simulator tests\"\"\"\n\n def __init__(self, verbose: bool = False):\n self.verbose = verbose\n self.test_files = {}\n self.test_dir = None\n\n # Configure logging first\n log_level = logging.DEBUG if verbose else logging.INFO\n logging.basicConfig(level=log_level, format=\"%(asctime)s - %(levelname)s - %(message)s\")\n self.logger = logging.getLogger(self.__class__.__name__)\n\n self.python_path = self._get_python_path()\n\n def _get_python_path(self) -> str:\n \"\"\"Get the Python path for the virtual environment\"\"\"\n current_dir = os.getcwd()\n\n # Try .venv first (modern convention)\n venv_python = os.path.join(current_dir, \".venv\", \"bin\", \"python\")\n if os.path.exists(venv_python):\n return venv_python\n\n # Try venv as fallback\n venv_python = os.path.join(current_dir, \"venv\", \"bin\", \"python\")\n if os.path.exists(venv_python):\n return venv_python\n\n # Try .pal_venv as fallback\n pal_venv_python = os.path.join(current_dir, \".pal_venv\", \"bin\", \"python\")\n if os.path.exists(pal_venv_python):\n return pal_venv_python\n\n # Fallback to system python if venv doesn't exist\n self.logger.warning(\"Virtual environment not found, using system python\")\n return \"python\"\n\n def setup_test_files(self):\n \"\"\"Create test files for the simulation\"\"\"\n # Test Python file\n python_content = '''\"\"\"\nSample Python module for testing MCP conversation continuity\n\"\"\"\n\ndef fibonacci(n):\n \"\"\"Calculate fibonacci number recursively\"\"\"\n if n <= 1:\n return n\n return fibonacci(n-1) + fibonacci(n-2)\n\ndef factorial(n):\n \"\"\"Calculate factorial iteratively\"\"\"\n result = 1\n for i in range(1, n + 1):\n result *= i\n return result\n\nclass Calculator:\n \"\"\"Simple calculator class\"\"\"\n\n def __init__(self):\n self.history = []\n\n def add(self, a, b):\n result = a + b\n self.history.append(f\"{a} + {b} = {result}\")\n return result\n\n def multiply(self, a, b):\n result = a * b\n self.history.append(f\"{a} * {b} = {result}\")\n return result\n'''\n\n # Test configuration file\n config_content = \"\"\"{\n \"database\": {\n \"host\": \"localhost\",\n \"port\": 5432,\n \"name\": \"testdb\",\n \"ssl\": true\n },\n \"cache\": {\n \"redis_url\": \"redis://localhost:6379\",\n \"ttl\": 3600\n },\n \"logging\": {\n \"level\": \"INFO\",\n \"format\": \"%(asctime)s - %(name)s - %(levelname)s - %(message)s\"\n }\n}\"\"\"\n\n # Create files in the current project directory\n current_dir = os.getcwd()\n self.test_dir = os.path.join(current_dir, \"test_simulation_files\")\n os.makedirs(self.test_dir, exist_ok=True)\n\n test_py = os.path.join(self.test_dir, \"test_module.py\")\n test_config = os.path.join(self.test_dir, \"config.json\")\n\n with open(test_py, \"w\") as f:\n f.write(python_content)\n with open(test_config, \"w\") as f:\n f.write(config_content)\n\n # Ensure absolute paths for MCP server compatibility\n self.test_files = {\"python\": os.path.abspath(test_py), \"config\": os.path.abspath(test_config)}\n self.logger.debug(f\"Created test files with absolute paths: {list(self.test_files.values())}\")\n\n def call_mcp_tool(self, tool_name: str, params: dict) -> tuple[Optional[str], Optional[str]]:\n \"\"\"Call an MCP tool via standalone server\"\"\"\n try:\n # Prepare the MCP initialization and tool call sequence\n init_request = {\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"initialize\",\n \"params\": {\n \"protocolVersion\": \"2024-11-05\",\n \"capabilities\": {\"tools\": {}},\n \"clientInfo\": {\"name\": \"communication-simulator\", \"version\": \"1.0.0\"},\n },\n }\n\n # Send initialized notification\n initialized_notification = {\"jsonrpc\": \"2.0\", \"method\": \"notifications/initialized\"}\n\n # Prepare the tool call request\n tool_request = {\n \"jsonrpc\": \"2.0\",\n \"id\": 2,\n \"method\": \"tools/call\",\n \"params\": {\"name\": tool_name, \"arguments\": params},\n } # Combine all messages\n messages = [\n json.dumps(init_request, ensure_ascii=False),\n json.dumps(initialized_notification, ensure_ascii=False),\n json.dumps(tool_request, ensure_ascii=False),\n ]\n\n # Join with newlines as MCP expects\n input_data = \"\\n\".join(messages) + \"\\n\"\n\n # Call the standalone MCP server directly\n server_cmd = [self.python_path, \"server.py\"]\n\n self.logger.debug(f\"Calling MCP tool {tool_name} with proper initialization\")\n\n # Execute the command with proper handling for async responses\n # For consensus tool and other long-running tools, we need to ensure\n # the subprocess doesn't close prematurely\n result = subprocess.run(\n server_cmd,\n input=input_data,\n text=True,\n capture_output=True,\n timeout=3600, # 1 hour timeout\n check=False, # Don't raise on non-zero exit code\n )\n\n if result.returncode != 0:\n self.logger.error(f\"Standalone server failed with return code {result.returncode}\")\n self.logger.error(f\"Stderr: {result.stderr}\")\n # Still try to parse stdout as the response might have been written before the error\n self.logger.debug(f\"Attempting to parse stdout despite error: {result.stdout[:500]}\")\n\n # Parse the response - look for the tool call response\n response_data = self._parse_mcp_response(result.stdout, expected_id=2)\n if not response_data:\n return None, None\n\n # Extract continuation_id if present\n continuation_id = self._extract_continuation_id(response_data)\n\n return response_data, continuation_id\n\n except subprocess.TimeoutExpired:\n self.logger.error(f\"MCP tool call timed out after 1 hour: {tool_name}\")\n return None, None\n except Exception as e:\n self.logger.error(f\"MCP tool call failed: {e}\")\n return None, None\n\n def _parse_mcp_response(self, stdout: str, expected_id: int = 2) -> Optional[str]:\n \"\"\"Parse MCP JSON-RPC response from stdout\"\"\"\n try:\n lines = stdout.strip().split(\"\\n\")\n for line in lines:\n if line.strip() and line.startswith(\"{\"):\n response = json.loads(line)\n # Look for the tool call response with the expected ID\n if response.get(\"id\") == expected_id and \"result\" in response:\n # Extract the actual content from the response\n result = response[\"result\"]\n # Handle new response format with 'content' array\n if isinstance(result, dict) and \"content\" in result:\n content_array = result[\"content\"]\n if isinstance(content_array, list) and len(content_array) > 0:\n return content_array[0].get(\"text\", \"\")\n # Handle legacy format\n elif isinstance(result, list) and len(result) > 0:\n return result[0].get(\"text\", \"\")\n elif response.get(\"id\") == expected_id and \"error\" in response:\n self.logger.error(f\"MCP error: {response['error']}\")\n return None\n\n # If we get here, log all responses for debugging\n self.logger.warning(f\"No valid tool call response found for ID {expected_id}\")\n self.logger.warning(f\"Full stdout: {stdout}\")\n self.logger.warning(f\"Total stdout lines: {len(lines)}\")\n for i, line in enumerate(lines[:10]): # Log first 10 lines\n self.logger.warning(f\"Line {i}: {line[:100]}...\")\n return None\n\n except json.JSONDecodeError as e:\n self.logger.error(f\"Failed to parse MCP response: {e}\")\n self.logger.debug(f\"Stdout that failed to parse: {stdout}\")\n return None\n\n def _extract_continuation_id(self, response_text: str) -> Optional[str]:\n \"\"\"Extract continuation_id from response metadata\"\"\"\n try:\n # Parse the response text as JSON to look for continuation metadata\n response_data = json.loads(response_text)\n\n # Look for continuation_id in various places\n if isinstance(response_data, dict):\n # Check for direct continuation_id field (new workflow tools)\n if \"continuation_id\" in response_data:\n return response_data[\"continuation_id\"]\n\n # Check metadata\n metadata = response_data.get(\"metadata\", {})\n if \"thread_id\" in metadata:\n return metadata[\"thread_id\"]\n\n # Check follow_up_request\n follow_up = response_data.get(\"follow_up_request\", {})\n if follow_up and \"continuation_id\" in follow_up:\n return follow_up[\"continuation_id\"]\n\n # Check continuation_offer\n continuation_offer = response_data.get(\"continuation_offer\", {})\n if continuation_offer and \"continuation_id\" in continuation_offer:\n return continuation_offer[\"continuation_id\"]\n\n self.logger.debug(f\"No continuation_id found in response: {response_data}\")\n return None\n\n except json.JSONDecodeError as e:\n self.logger.debug(f\"Failed to parse response for continuation_id: {e}\")\n return None\n\n def run_command(self, cmd: list[str], check: bool = True, capture_output: bool = False, **kwargs):\n \"\"\"Run a shell command with logging\"\"\"\n if self.verbose:\n self.logger.debug(f\"Running: {' '.join(cmd)}\")\n\n return subprocess.run(cmd, check=check, capture_output=capture_output, **kwargs)\n\n def create_additional_test_file(self, filename: str, content: str) -> str:\n \"\"\"Create an additional test file for mixed scenario testing\"\"\"\n if not hasattr(self, \"test_dir\") or not self.test_dir:\n raise RuntimeError(\"Test directory not initialized. Call setup_test_files() first.\")\n\n file_path = os.path.join(self.test_dir, filename)\n with open(file_path, \"w\") as f:\n f.write(content)\n # Return absolute path for MCP server compatibility\n return os.path.abspath(file_path)\n\n def cleanup_test_files(self):\n \"\"\"Clean up test files\"\"\"\n if hasattr(self, \"test_dir\") and self.test_dir and os.path.exists(self.test_dir):\n import shutil\n\n shutil.rmtree(self.test_dir)\n self.logger.debug(f\"Removed test files directory: {self.test_dir}\")\n\n # ============================================================================\n # Log Utility Methods (delegate to LogUtils)\n # ============================================================================\n\n def get_server_logs_since(self, since_time: Optional[str] = None) -> str:\n \"\"\"Get server logs from both main and activity log files.\"\"\"\n return LogUtils.get_server_logs_since(since_time)\n\n def get_recent_server_logs(self, lines: int = 500) -> str:\n \"\"\"Get recent server logs from the main log file.\"\"\"\n return LogUtils.get_recent_server_logs(lines)\n\n def get_server_logs_subprocess(self, lines: int = 500) -> str:\n \"\"\"Get server logs using subprocess (alternative method).\"\"\"\n return LogUtils.get_server_logs_subprocess(lines)\n\n def check_server_logs_for_errors(self, lines: int = 500) -> list[str]:\n \"\"\"Check server logs for error messages.\"\"\"\n return LogUtils.check_server_logs_for_errors(lines)\n\n def extract_conversation_usage_logs(self, logs: str) -> list[dict[str, int]]:\n \"\"\"Extract token budget calculation information from logs.\"\"\"\n return LogUtils.extract_conversation_usage_logs(logs)\n\n def extract_conversation_token_usage(self, logs: str) -> list[int]:\n \"\"\"Extract conversation token usage values from logs.\"\"\"\n return LogUtils.extract_conversation_token_usage(logs)\n\n def extract_thread_creation_logs(self, logs: str) -> list[dict[str, str]]:\n \"\"\"Extract thread creation logs with parent relationships.\"\"\"\n return LogUtils.extract_thread_creation_logs(logs)\n\n def extract_history_traversal_logs(self, logs: str) -> list[dict[str, any]]:\n \"\"\"Extract conversation history traversal logs.\"\"\"\n return LogUtils.extract_history_traversal_logs(logs)\n\n def validate_file_deduplication_in_logs(self, logs: str, tool_name: str, test_file: str) -> bool:\n \"\"\"Validate that logs show file deduplication behavior.\"\"\"\n return LogUtils.validate_file_deduplication_in_logs(logs, tool_name, test_file)\n\n def search_logs_for_pattern(\n self, pattern: str, logs: Optional[str] = None, case_sensitive: bool = False\n ) -> list[str]:\n \"\"\"Search logs for a specific pattern.\"\"\"\n return LogUtils.search_logs_for_pattern(pattern, logs, case_sensitive)\n\n def get_log_file_info(self) -> dict[str, dict[str, any]]:\n \"\"\"Get information about log files.\"\"\"\n return LogUtils.get_log_file_info()\n\n def run_test(self) -> bool:\n \"\"\"Run the test - to be implemented by subclasses\"\"\"\n raise NotImplementedError(\"Subclasses must implement run_test()\")\n\n @property\n def test_name(self) -> str:\n \"\"\"Get the test name - to be implemented by subclasses\"\"\"\n raise NotImplementedError(\"Subclasses must implement test_name property\")\n\n @property\n def test_description(self) -> str:\n \"\"\"Get the test description - to be implemented by subclasses\"\"\"\n raise NotImplementedError(\"Subclasses must implement test_description property\")\n" }, { "path": "simulator_tests/conversation_base_test.py", "content": "#!/usr/bin/env python3\n\"\"\"\nConversation Base Test Class for In-Process MCP Tool Testing\n\nThis class enables testing MCP tools within the same process to maintain conversation\nmemory state across tool calls. Unlike BaseSimulatorTest which runs each tool call\nas a separate subprocess (losing memory state), this class calls tools directly\nin-process, allowing conversation functionality to work correctly.\n\nUSAGE:\n- Inherit from ConversationBaseTest instead of BaseSimulatorTest for conversation tests\n- Use call_mcp_tool_direct() to call tools in-process\n- Conversation memory persists across tool calls within the same test\n- setUp() clears memory between test methods for proper isolation\n\nEXAMPLE:\n class TestConversationFeature(ConversationBaseTest):\n def test_cross_tool_continuation(self):\n # Step 1: Call precommit tool\n result1, continuation_id = self.call_mcp_tool_direct(\"precommit\", {\n \"path\": \"/path/to/repo\",\n \"prompt\": \"Review these changes\"\n })\n\n # Step 2: Continue with codereview tool - memory is preserved!\n result2, _ = self.call_mcp_tool_direct(\"codereview\", {\n \"step\": \"Focus on security issues in this code\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Starting security-focused code review\",\n \"relevant_files\": [\"/path/to/file.py\"],\n \"continuation_id\": continuation_id\n })\n\"\"\"\n\nimport asyncio\nimport json\nfrom typing import Optional\n\nfrom tools.shared.exceptions import ToolExecutionError\n\nfrom .base_test import BaseSimulatorTest\n\n\nclass ConversationBaseTest(BaseSimulatorTest):\n \"\"\"Base class for conversation tests that require in-process tool calling\"\"\"\n\n def __init__(self, verbose: bool = False):\n super().__init__(verbose)\n self._tools = None\n self._loop = None\n\n def setUp(self):\n \"\"\"Set up test environment - clears conversation memory between tests\"\"\"\n super().setup_test_files()\n\n # Clear conversation memory for test isolation\n self._clear_conversation_memory()\n\n # Import tools from server.py for in-process calling\n if self._tools is None:\n self._import_tools()\n\n def _clear_conversation_memory(self):\n \"\"\"Clear all conversation memory to ensure test isolation\"\"\"\n try:\n from utils.storage_backend import get_storage_backend\n\n storage = get_storage_backend()\n # Clear all stored conversation threads\n with storage._lock:\n storage._store.clear()\n self.logger.debug(\"Cleared conversation memory for test isolation\")\n except Exception as e:\n self.logger.warning(f\"Could not clear conversation memory: {e}\")\n\n def _import_tools(self):\n \"\"\"Import tools from server.py for direct calling\"\"\"\n try:\n import os\n import sys\n\n # Add project root to Python path if not already there\n project_root = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))\n if project_root not in sys.path:\n sys.path.insert(0, project_root)\n\n # Import and configure providers first (this is what main() does)\n from server import TOOLS, configure_providers\n\n configure_providers()\n\n self._tools = TOOLS\n self.logger.debug(f\"Imported {len(self._tools)} tools for in-process testing\")\n except ImportError as e:\n raise RuntimeError(f\"Could not import tools from server.py: {e}\")\n\n def _get_event_loop(self):\n \"\"\"Get or create event loop for async tool execution\"\"\"\n if self._loop is None:\n try:\n self._loop = asyncio.get_event_loop()\n except RuntimeError:\n self._loop = asyncio.new_event_loop()\n asyncio.set_event_loop(self._loop)\n return self._loop\n\n def call_mcp_tool_direct(self, tool_name: str, params: dict) -> tuple[Optional[str], Optional[str]]:\n \"\"\"\n Call an MCP tool directly in-process without subprocess isolation.\n\n This method maintains conversation memory across calls, enabling proper\n testing of conversation functionality.\n\n Args:\n tool_name: Name of the tool to call (e.g., \"precommit\", \"codereview\")\n params: Parameters to pass to the tool\n\n Returns:\n tuple: (response_content, continuation_id) where continuation_id\n can be used for follow-up calls\n \"\"\"\n if self._tools is None:\n raise RuntimeError(\"Tools not imported. Call setUp() first.\")\n\n if tool_name not in self._tools:\n raise ValueError(f\"Tool '{tool_name}' not found. Available: {list(self._tools.keys())}\")\n\n try:\n tool = self._tools[tool_name]\n self.logger.debug(f\"Calling tool '{tool_name}' directly in-process\")\n\n # Set up minimal model context if not provided\n if \"model\" not in params:\n params[\"model\"] = \"flash\" # Use fast model for testing\n\n # Execute tool directly using asyncio\n loop = self._get_event_loop()\n\n # Import required modules for model resolution (similar to server.py)\n from config import DEFAULT_MODEL\n from providers.registry import ModelProviderRegistry\n from utils.model_context import ModelContext\n\n # Resolve model (simplified version of server.py logic)\n model_name = params.get(\"model\", DEFAULT_MODEL)\n provider = ModelProviderRegistry.get_provider_for_model(model_name)\n if not provider:\n # Fallback to available model for testing\n available_models = list(ModelProviderRegistry.get_available_models(respect_restrictions=True).keys())\n if available_models:\n model_name = available_models[0]\n params[\"model\"] = model_name\n self.logger.debug(f\"Using fallback model for testing: {model_name}\")\n\n # Create model context\n model_context = ModelContext(model_name)\n params[\"_model_context\"] = model_context\n params[\"_resolved_model_name\"] = model_name\n\n # Execute tool asynchronously\n try:\n result = loop.run_until_complete(tool.execute(params))\n except ToolExecutionError as exc:\n response_text = exc.payload\n continuation_id = self._extract_continuation_id_from_response(response_text)\n self.logger.debug(f\"Tool '{tool_name}' returned error payload in-process\")\n if self.verbose and response_text:\n self.logger.debug(f\"Error response preview: {response_text[:500]}...\")\n return response_text, continuation_id\n\n if not result or len(result) == 0:\n return None, None\n\n # Extract response content\n response_text = result[0].text if hasattr(result[0], \"text\") else str(result[0])\n\n # Parse response to extract continuation_id\n continuation_id = self._extract_continuation_id_from_response(response_text)\n\n self.logger.debug(f\"Tool '{tool_name}' completed successfully in-process\")\n if self.verbose and response_text:\n self.logger.debug(f\"Response preview: {response_text[:500]}...\")\n return response_text, continuation_id\n\n except Exception as e:\n self.logger.error(f\"Direct tool call failed for '{tool_name}': {e}\")\n return None, None\n\n def _extract_continuation_id_from_response(self, response_text: str) -> Optional[str]:\n \"\"\"Extract continuation_id from tool response\"\"\"\n try:\n # Parse the response as JSON to look for continuation metadata\n response_data = json.loads(response_text)\n\n # Look for continuation_id in various places\n if isinstance(response_data, dict):\n # Check top-level continuation_id (workflow tools)\n if \"continuation_id\" in response_data:\n return response_data[\"continuation_id\"]\n\n # Check metadata\n metadata = response_data.get(\"metadata\", {})\n if \"thread_id\" in metadata:\n return metadata[\"thread_id\"]\n\n # Check continuation_offer\n continuation_offer = response_data.get(\"continuation_offer\", {})\n if continuation_offer and \"continuation_id\" in continuation_offer:\n return continuation_offer[\"continuation_id\"]\n\n # Check follow_up_request\n follow_up = response_data.get(\"follow_up_request\", {})\n if follow_up and \"continuation_id\" in follow_up:\n return follow_up[\"continuation_id\"]\n\n # Special case: files_required_to_continue may have nested content\n if response_data.get(\"status\") == \"files_required_to_continue\":\n content = response_data.get(\"content\", \"\")\n if isinstance(content, str):\n try:\n # Try to parse nested JSON\n nested_data = json.loads(content)\n if isinstance(nested_data, dict):\n # Check for continuation in nested data\n follow_up = nested_data.get(\"follow_up_request\", {})\n if follow_up and \"continuation_id\" in follow_up:\n return follow_up[\"continuation_id\"]\n except json.JSONDecodeError:\n pass\n\n return None\n\n except (json.JSONDecodeError, AttributeError):\n # If response is not JSON or doesn't have expected structure, return None\n return None\n\n def tearDown(self):\n \"\"\"Clean up after test\"\"\"\n super().cleanup_test_files()\n # Clear memory again for good measure\n self._clear_conversation_memory()\n\n @property\n def test_name(self) -> str:\n \"\"\"Get the test name\"\"\"\n return self.__class__.__name__\n\n @property\n def test_description(self) -> str:\n \"\"\"Get the test description\"\"\"\n return \"In-process conversation test\"\n" }, { "path": "simulator_tests/log_utils.py", "content": "\"\"\"\nCentralized log utility for simulator tests.\n\nThis module provides common log reading and parsing functionality\nused across multiple simulator test files to reduce code duplication.\n\"\"\"\n\nimport logging\nimport re\nimport subprocess\nfrom typing import Optional, Union\n\n\nclass LogUtils:\n \"\"\"Centralized logging utilities for simulator tests.\"\"\"\n\n # Log file paths\n MAIN_LOG_FILE = \"logs/mcp_server.log\"\n ACTIVITY_LOG_FILE = \"logs/mcp_activity.log\"\n\n @classmethod\n def get_server_logs_since(cls, since_time: Optional[str] = None) -> str:\n \"\"\"\n Get server logs from both main and activity log files.\n\n Args:\n since_time: Currently ignored, returns all available logs\n\n Returns:\n Combined logs from both log files\n \"\"\"\n try:\n main_logs = \"\"\n activity_logs = \"\"\n\n # Read main server log\n try:\n with open(cls.MAIN_LOG_FILE) as f:\n main_logs = f.read()\n except FileNotFoundError:\n pass\n\n # Read activity log\n try:\n with open(cls.ACTIVITY_LOG_FILE) as f:\n activity_logs = f.read()\n except FileNotFoundError:\n pass\n\n return main_logs + \"\\n\" + activity_logs\n\n except Exception as e:\n logging.warning(f\"Failed to read server logs: {e}\")\n return \"\"\n\n @classmethod\n def get_recent_server_logs(cls, lines: int = 500) -> str:\n \"\"\"\n Get recent server logs from the main log file.\n\n Args:\n lines: Number of recent lines to retrieve (default: 500)\n\n Returns:\n Recent log content as string\n \"\"\"\n try:\n with open(cls.MAIN_LOG_FILE) as f:\n all_lines = f.readlines()\n recent_lines = all_lines[-lines:] if len(all_lines) > lines else all_lines\n return \"\".join(recent_lines)\n except FileNotFoundError:\n logging.warning(f\"Log file {cls.MAIN_LOG_FILE} not found\")\n return \"\"\n except Exception as e:\n logging.warning(f\"Failed to read recent server logs: {e}\")\n return \"\"\n\n @classmethod\n def get_server_logs_subprocess(cls, lines: int = 500) -> str:\n \"\"\"\n Get server logs using subprocess (alternative method).\n\n Args:\n lines: Number of recent lines to retrieve\n\n Returns:\n Recent log content as string\n \"\"\"\n try:\n result = subprocess.run(\n [\"tail\", \"-n\", str(lines), cls.MAIN_LOG_FILE], capture_output=True, text=True, timeout=10\n )\n return result.stdout + result.stderr\n except Exception as e:\n logging.warning(f\"Failed to get server logs via subprocess: {e}\")\n return \"\"\n\n @classmethod\n def check_server_logs_for_errors(cls, lines: int = 500) -> list[str]:\n \"\"\"\n Check server logs for error messages.\n\n Args:\n lines: Number of recent lines to check\n\n Returns:\n List of error messages found\n \"\"\"\n logs = cls.get_recent_server_logs(lines)\n error_patterns = [r\"ERROR.*\", r\"CRITICAL.*\", r\"Failed.*\", r\"Exception.*\", r\"Error:.*\"]\n\n errors = []\n for line in logs.split(\"\\n\"):\n for pattern in error_patterns:\n if re.search(pattern, line, re.IGNORECASE):\n errors.append(line.strip())\n break\n\n return errors\n\n @classmethod\n def extract_conversation_usage_logs(cls, logs: str) -> list[dict[str, int]]:\n \"\"\"\n Extract token budget calculation information from logs.\n\n Args:\n logs: Log content to parse\n\n Returns:\n List of dictionaries containing token usage data\n \"\"\"\n usage_data = []\n pattern = r\"\\[CONVERSATION_DEBUG\\] Token budget calculation:\"\n\n for line in logs.split(\"\\n\"):\n if re.search(pattern, line):\n # Parse the token usage information\n usage_info = {}\n\n # Extract total capacity\n capacity_match = re.search(r\"Total capacity: ([\\d,]+)\", line)\n if capacity_match:\n usage_info[\"total_capacity\"] = int(capacity_match.group(1).replace(\",\", \"\"))\n\n # Extract content allocation\n content_match = re.search(r\"Content allocation: ([\\d,]+)\", line)\n if content_match:\n usage_info[\"content_allocation\"] = int(content_match.group(1).replace(\",\", \"\"))\n\n # Extract conversation tokens\n conv_match = re.search(r\"Conversation tokens: ([\\d,]+)\", line)\n if conv_match:\n usage_info[\"conversation_tokens\"] = int(conv_match.group(1).replace(\",\", \"\"))\n\n # Extract remaining tokens\n remaining_match = re.search(r\"Remaining tokens: ([\\d,]+)\", line)\n if remaining_match:\n usage_info[\"remaining_tokens\"] = int(remaining_match.group(1).replace(\",\", \"\"))\n\n if usage_info:\n usage_data.append(usage_info)\n\n return usage_data\n\n @classmethod\n def extract_conversation_token_usage(cls, logs: str) -> list[int]:\n \"\"\"\n Extract conversation token usage values from logs.\n\n Args:\n logs: Log content to parse\n\n Returns:\n List of token usage values\n \"\"\"\n pattern = r\"Conversation history token usage:\\s*([\\d,]+)\"\n usage_values = []\n\n for match in re.finditer(pattern, logs):\n usage_value = int(match.group(1).replace(\",\", \"\"))\n usage_values.append(usage_value)\n\n return usage_values\n\n @classmethod\n def extract_thread_creation_logs(cls, logs: str) -> list[dict[str, str]]:\n \"\"\"\n Extract thread creation logs with parent relationships.\n\n Args:\n logs: Log content to parse\n\n Returns:\n List of dictionaries with thread relationship data\n \"\"\"\n thread_data = []\n pattern = r\"\\[THREAD\\] Created new thread (\\w+)(?: with parent (\\w+))?\"\n\n for match in re.finditer(pattern, logs):\n thread_info = {\"thread_id\": match.group(1), \"parent_id\": match.group(2) if match.group(2) else None}\n thread_data.append(thread_info)\n\n return thread_data\n\n @classmethod\n def extract_history_traversal_logs(cls, logs: str) -> list[dict[str, Union[str, int]]]:\n \"\"\"\n Extract conversation history traversal logs.\n\n Args:\n logs: Log content to parse\n\n Returns:\n List of dictionaries with traversal data\n \"\"\"\n traversal_data = []\n pattern = r\"\\[THREAD\\] Retrieved chain of (\\d+) messages for thread (\\w+)\"\n\n for match in re.finditer(pattern, logs):\n traversal_info = {\"chain_length\": int(match.group(1)), \"thread_id\": match.group(2)}\n traversal_data.append(traversal_info)\n\n return traversal_data\n\n @classmethod\n def validate_file_deduplication_in_logs(cls, logs: str, tool_name: str, test_file: str) -> bool:\n \"\"\"\n Validate that logs show file deduplication behavior.\n\n Args:\n logs: Log content to parse\n tool_name: Name of the tool being tested\n test_file: Name of the test file to check for deduplication\n\n Returns:\n True if deduplication evidence is found, False otherwise\n \"\"\"\n # Look for embedding calculation\n embedding_pattern = f\"Calculating embeddings for {test_file}\"\n has_embedding = bool(re.search(embedding_pattern, logs))\n\n # Look for filtering message\n filtering_pattern = f\"Filtering {test_file} to prevent duplication\"\n has_filtering = bool(re.search(filtering_pattern, logs))\n\n # Look for skip message\n skip_pattern = f\"Skipping {test_file} \\\\(already processed\"\n has_skip = bool(re.search(skip_pattern, logs))\n\n # Look for tool-specific processing\n tool_pattern = f\"\\\\[{tool_name.upper()}\\\\].*{test_file}\"\n has_tool_processing = bool(re.search(tool_pattern, logs, re.IGNORECASE))\n\n # Deduplication is confirmed if we see evidence of processing and filtering/skipping\n return has_embedding and (has_filtering or has_skip) and has_tool_processing\n\n @classmethod\n def search_logs_for_pattern(\n cls, pattern: str, logs: Optional[str] = None, case_sensitive: bool = False\n ) -> list[str]:\n \"\"\"\n Search logs for a specific pattern.\n\n Args:\n pattern: Regex pattern to search for\n logs: Log content to search (if None, reads recent logs)\n case_sensitive: Whether the search should be case sensitive\n\n Returns:\n List of matching lines\n \"\"\"\n if logs is None:\n logs = cls.get_recent_server_logs()\n\n flags = 0 if case_sensitive else re.IGNORECASE\n matches = []\n\n for line in logs.split(\"\\n\"):\n if re.search(pattern, line, flags):\n matches.append(line.strip())\n\n return matches\n\n @classmethod\n def get_log_file_info(cls) -> dict[str, dict[str, Union[str, int, bool]]]:\n \"\"\"\n Get information about log files.\n\n Returns:\n Dictionary with file information for each log file\n \"\"\"\n import os\n\n file_info = {}\n\n for log_file in [cls.MAIN_LOG_FILE, cls.ACTIVITY_LOG_FILE]:\n if os.path.exists(log_file):\n stat = os.stat(log_file)\n file_info[log_file] = {\n \"exists\": True,\n \"size_bytes\": stat.st_size,\n \"size_mb\": round(stat.st_size / (1024 * 1024), 2),\n \"last_modified\": stat.st_mtime,\n \"readable\": os.access(log_file, os.R_OK),\n }\n else:\n file_info[log_file] = {\n \"exists\": False,\n \"size_bytes\": 0,\n \"size_mb\": 0,\n \"last_modified\": 0,\n \"readable\": False,\n }\n\n return file_info\n" }, { "path": "simulator_tests/test_analyze_validation.py", "content": "#!/usr/bin/env python3\n\"\"\"\nAnalyze Tool Validation Test\n\nTests the analyze tool's capabilities using the new workflow architecture.\nThis validates that the new workflow-based implementation provides step-by-step\nanalysis with expert validation following the same patterns as debug/codereview tools.\n\"\"\"\n\nimport json\nfrom typing import Optional\n\nfrom .conversation_base_test import ConversationBaseTest\n\n\nclass AnalyzeValidationTest(ConversationBaseTest):\n \"\"\"Test analyze tool with new workflow architecture\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"analyze_validation\"\n\n @property\n def test_description(self) -> str:\n return \"AnalyzeWorkflow tool validation with new workflow architecture\"\n\n def run_test(self) -> bool:\n \"\"\"Test analyze tool capabilities\"\"\"\n # Set up the test environment\n self.setUp()\n\n try:\n self.logger.info(\"Test: AnalyzeWorkflow tool validation (new architecture)\")\n\n # Create test files for analysis\n self._create_analysis_codebase()\n\n # Test 1: Single analysis session with multiple steps\n if not self._test_single_analysis_session():\n return False\n\n # Test 2: Analysis flow that requires refocusing\n if not self._test_analysis_refocus_flow():\n return False\n\n # Test 3: Complete analysis with expert validation\n if not self._test_complete_analysis_with_expert():\n return False\n\n # Test 4: Certain confidence behavior\n if not self._test_certain_confidence():\n return False\n\n # Test 5: Context-aware file embedding\n if not self._test_context_aware_file_embedding():\n return False\n\n # Test 6: Different analysis types\n if not self._test_analysis_types():\n return False\n\n self.logger.info(\" βœ… All analyze validation tests passed\")\n return True\n\n except Exception as e:\n self.logger.error(f\"AnalyzeWorkflow validation test failed: {e}\")\n return False\n\n def _create_analysis_codebase(self):\n \"\"\"Create test files representing a realistic codebase for analysis\"\"\"\n # Create a Python microservice with various architectural patterns\n main_service = \"\"\"#!/usr/bin/env python3\nimport asyncio\nimport json\nfrom datetime import datetime\nfrom typing import Dict, List, Optional\n\nfrom fastapi import FastAPI, HTTPException, Depends\nfrom sqlalchemy.ext.asyncio import AsyncSession, create_async_engine\nfrom sqlalchemy.orm import sessionmaker\nimport redis\nimport logging\n\n# Global configurations - could be improved\nDATABASE_URL = \"postgresql://user:pass@localhost/db\"\nREDIS_URL = \"redis://localhost:6379\"\n\napp = FastAPI(title=\"User Management Service\")\n\n# Database setup\nengine = create_async_engine(DATABASE_URL, echo=True)\nAsyncSessionLocal = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)\n\n# Redis connection - potential singleton pattern issue\nredis_client = redis.Redis.from_url(REDIS_URL)\n\nclass UserService:\n def __init__(self, db: AsyncSession):\n self.db = db\n self.cache = redis_client # Direct dependency on global\n\n async def get_user(self, user_id: int) -> Optional[Dict]:\n # Cache key generation - could be centralized\n cache_key = f\"user:{user_id}\"\n\n # Check cache first\n cached = self.cache.get(cache_key)\n if cached:\n return json.loads(cached)\n\n # Database query - no error handling\n result = await self.db.execute(\n \"SELECT * FROM users WHERE id = %s\", (user_id,)\n )\n user_data = result.fetchone() if user_data:\n # Cache for 1 hour - magic number\n self.cache.setex(cache_key, 3600, json.dumps(user_data, ensure_ascii=False))\n\n return user_data\n\n async def create_user(self, user_data: Dict) -> Dict:\n # Input validation missing\n # No transaction handling\n # No audit logging\n\n query = \"INSERT INTO users (name, email) VALUES (%s, %s) RETURNING id\"\n result = await self.db.execute(query, (user_data['name'], user_data['email']))\n user_id = result.fetchone()[0]\n\n # Cache invalidation strategy missing\n\n return {\"id\": user_id, **user_data}\n\n@app.get(\"/users/{user_id}\")\nasync def get_user_endpoint(user_id: int, db: AsyncSession = Depends(get_db)):\n service = UserService(db)\n user = await service.get_user(user_id)\n\n if not user:\n raise HTTPException(status_code=404, detail=\"User not found\")\n\n return user\n\n@app.post(\"/users\")\nasync def create_user_endpoint(user_data: dict, db: AsyncSession = Depends(get_db)):\n service = UserService(db)\n return await service.create_user(user_data)\n\nasync def get_db():\n async with AsyncSessionLocal() as session:\n yield session\n\"\"\"\n\n # Create config module with various architectural concerns\n config_module = \"\"\"#!/usr/bin/env python3\nimport os\nfrom dataclasses import dataclass\nfrom typing import Optional\n\n# Configuration approach could be improved\n@dataclass\nclass DatabaseConfig:\n url: str = os.getenv(\"DATABASE_URL\", \"postgresql://localhost/app\")\n pool_size: int = int(os.getenv(\"DB_POOL_SIZE\", \"5\"))\n max_overflow: int = int(os.getenv(\"DB_MAX_OVERFLOW\", \"10\"))\n echo: bool = os.getenv(\"DB_ECHO\", \"false\").lower() == \"true\"\n\n@dataclass\nclass CacheConfig:\n redis_url: str = os.getenv(\"REDIS_URL\", \"redis://localhost:6379\")\n default_ttl: int = int(os.getenv(\"CACHE_TTL\", \"3600\"))\n max_connections: int = int(os.getenv(\"REDIS_MAX_CONN\", \"20\"))\n\n@dataclass\nclass AppConfig:\n environment: str = os.getenv(\"ENVIRONMENT\", \"development\")\n debug: bool = os.getenv(\"DEBUG\", \"false\").lower() == \"true\"\n log_level: str = os.getenv(\"LOG_LEVEL\", \"INFO\")\n\n # Nested config objects\n database: DatabaseConfig = DatabaseConfig()\n cache: CacheConfig = CacheConfig()\n\n # Security settings scattered\n secret_key: str = os.getenv(\"SECRET_KEY\", \"dev-key-not-secure\")\n jwt_algorithm: str = \"HS256\"\n jwt_expiration: int = 86400 # 24 hours\n\n def __post_init__(self):\n # Validation logic could be centralized\n if self.environment == \"production\" and self.secret_key == \"dev-key-not-secure\":\n raise ValueError(\"Production environment requires secure secret key\")\n\n# Global configuration instance - potential issues\nconfig = AppConfig()\n\n# Helper functions that could be methods\ndef get_database_url() -> str:\n return config.database.url\n\ndef get_cache_config() -> dict:\n return {\n \"url\": config.cache.redis_url,\n \"ttl\": config.cache.default_ttl,\n \"max_connections\": config.cache.max_connections\n }\n\ndef is_production() -> bool:\n return config.environment == \"production\"\n\ndef should_enable_debug() -> bool:\n return config.debug and not is_production()\n\"\"\"\n\n # Create models module with database concerns\n models_module = \"\"\"#!/usr/bin/env python3\nfrom datetime import datetime\nfrom typing import Optional, List\nfrom sqlalchemy import Column, Integer, String, DateTime, Boolean, ForeignKey, Text\nfrom sqlalchemy.ext.declarative import declarative_base\nfrom sqlalchemy.orm import relationship\nimport json\n\nBase = declarative_base()\n\nclass User(Base):\n __tablename__ = \"users\"\n\n id = Column(Integer, primary_key=True)\n email = Column(String(255), unique=True, nullable=False)\n name = Column(String(255), nullable=False)\n is_active = Column(Boolean, default=True)\n created_at = Column(DateTime, default=datetime.utcnow)\n updated_at = Column(DateTime, default=datetime.utcnow, onupdate=datetime.utcnow)\n\n # Relationship could be optimized\n profiles = relationship(\"UserProfile\", back_populates=\"user\", lazy=\"select\")\n audit_logs = relationship(\"AuditLog\", back_populates=\"user\")\n\n def to_dict(self) -> dict:\n # Serialization logic mixed with model - could be separated\n return {\n \"id\": self.id,\n \"email\": self.email,\n \"name\": self.name,\n \"is_active\": self.is_active,\n \"created_at\": self.created_at.isoformat() if self.created_at else None,\n \"updated_at\": self.updated_at.isoformat() if self.updated_at else None\n }\n\n def update_from_dict(self, data: dict):\n # Update logic could be more robust\n for key, value in data.items():\n if hasattr(self, key) and key not in ['id', 'created_at']:\n setattr(self, key, value)\n self.updated_at = datetime.utcnow()\n\nclass UserProfile(Base):\n __tablename__ = \"user_profiles\"\n\n id = Column(Integer, primary_key=True)\n user_id = Column(Integer, ForeignKey(\"users.id\"), nullable=False)\n bio = Column(Text)\n avatar_url = Column(String(500))\n preferences = Column(Text) # JSON stored as text - could use JSON column\n\n user = relationship(\"User\", back_populates=\"profiles\")\n\n def get_preferences(self) -> dict:\n # JSON handling could be centralized\n try:\n return json.loads(self.preferences) if self.preferences else {}\n except json.JSONDecodeError:\n return {} def set_preferences(self, prefs: dict):\n self.preferences = json.dumps(prefs, ensure_ascii=False)\n\nclass AuditLog(Base):\n __tablename__ = \"audit_logs\"\n\n id = Column(Integer, primary_key=True)\n user_id = Column(Integer, ForeignKey(\"users.id\"), nullable=False)\n action = Column(String(100), nullable=False)\n details = Column(Text) # JSON stored as text\n ip_address = Column(String(45)) # IPv6 support\n user_agent = Column(Text)\n timestamp = Column(DateTime, default=datetime.utcnow)\n\n user = relationship(\"User\", back_populates=\"audit_logs\")\n\n @classmethod\n def log_action(cls, db_session, user_id: int, action: str, details: dict = None,\n ip_address: str = None, user_agent: str = None):\n # Factory method pattern - could be improved\n log = cls(\n user_id=user_id,\n action=action,\n details=json.dumps(details, ensure_ascii=False) if details else None,\n ip_address=ip_address,\n user_agent=user_agent\n )\n db_session.add(log)\n return log\n\"\"\"\n\n # Create utility module with various helper functions\n utils_module = \"\"\"#!/usr/bin/env python3\nimport hashlib\nimport secrets\nimport re\nfrom datetime import datetime, timedelta\nfrom typing import Optional, Dict, Any\nimport logging\n\n# Logging setup - could be centralized\nlogger = logging.getLogger(__name__)\n\nclass ValidationError(Exception):\n \\\"\\\"\\\"Custom exception for validation errors\\\"\\\"\\\"\n pass\n\ndef validate_email(email: str) -> bool:\n # Email validation - could use more robust library\n pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\\\.[a-zA-Z]{2,}$'\n return bool(re.match(pattern, email))\n\ndef validate_password(password: str) -> tuple[bool, str]:\n # Password validation rules - could be configurable\n if len(password) < 8:\n return False, \"Password must be at least 8 characters\"\n\n if not re.search(r'[A-Z]', password):\n return False, \"Password must contain uppercase letter\"\n\n if not re.search(r'[a-z]', password):\n return False, \"Password must contain lowercase letter\"\n\n if not re.search(r'[0-9]', password):\n return False, \"Password must contain number\"\n\n return True, \"Valid password\"\n\ndef hash_password(password: str) -> str:\n # Password hashing - could use more secure algorithm\n salt = secrets.token_hex(32)\n password_hash = hashlib.pbkdf2_hmac('sha256', password.encode(), salt.encode(), 100000)\n return f\"{salt}:{password_hash.hex()}\"\n\ndef verify_password(password: str, hashed: str) -> bool:\n # Password verification\n try:\n salt, hash_hex = hashed.split(':', 1)\n password_hash = hashlib.pbkdf2_hmac('sha256', password.encode(), salt.encode(), 100000)\n return password_hash.hex() == hash_hex\n except ValueError:\n return False\n\ndef generate_cache_key(*args, prefix: str = \"\", separator: str = \":\") -> str:\n # Cache key generation - could be more sophisticated\n parts = [str(arg) for arg in args if arg is not None]\n if prefix:\n parts.insert(0, prefix)\n return separator.join(parts)\n\ndef parse_datetime(date_string: str) -> Optional[datetime]:\n # Date parsing with multiple format support\n formats = [\n \"%Y-%m-%d %H:%M:%S\",\n \"%Y-%m-%dT%H:%M:%S\",\n \"%Y-%m-%dT%H:%M:%S.%f\",\n \"%Y-%m-%d\"\n ]\n\n for fmt in formats:\n try:\n return datetime.strptime(date_string, fmt)\n except ValueError:\n continue\n\n logger.warning(f\"Unable to parse datetime: {date_string}\")\n return None\n\ndef calculate_expiry(hours: int = 24) -> datetime:\n # Expiry calculation - could be more flexible\n return datetime.utcnow() + timedelta(hours=hours)\n\ndef sanitize_input(data: Dict[str, Any]) -> Dict[str, Any]:\n # Input sanitization - basic implementation\n sanitized = {}\n\n for key, value in data.items():\n if isinstance(value, str):\n # Basic HTML/script tag removal\n value = re.sub(r'<[^>]*>', '', value)\n value = value.strip()\n\n # Type validation could be more comprehensive\n if value is not None and value != \"\":\n sanitized[key] = value\n\n return sanitized\n\ndef format_response(data: Any, status: str = \"success\", message: str = None) -> Dict[str, Any]:\n # Response formatting - could be more standardized\n response = {\n \"status\": status,\n \"data\": data,\n \"timestamp\": datetime.utcnow().isoformat()\n }\n\n if message:\n response[\"message\"] = message\n\n return response\n\nclass PerformanceTimer:\n # Performance measurement utility\n def __init__(self, name: str):\n self.name = name\n self.start_time = None\n\n def __enter__(self):\n self.start_time = datetime.now()\n return self\n\n def __exit__(self, exc_type, exc_val, exc_tb):\n if self.start_time:\n duration = datetime.now() - self.start_time\n logger.info(f\"Performance: {self.name} took {duration.total_seconds():.3f}s\")\n\"\"\"\n\n # Create test files\n self.main_service_file = self.create_additional_test_file(\"main_service.py\", main_service)\n self.config_file = self.create_additional_test_file(\"config.py\", config_module)\n self.models_file = self.create_additional_test_file(\"models.py\", models_module)\n self.utils_file = self.create_additional_test_file(\"utils.py\", utils_module)\n\n self.logger.info(\" βœ… Created test codebase with 4 files for analysis\")\n\n def _test_single_analysis_session(self) -> bool:\n \"\"\"Test a complete analysis session with multiple steps\"\"\"\n try:\n self.logger.info(\" 1.1: Testing single analysis session\")\n\n # Step 1: Start analysis\n self.logger.info(\" 1.1.1: Step 1 - Initial analysis\")\n response1, continuation_id = self.call_mcp_tool(\n \"analyze\",\n {\n \"step\": \"I need to analyze this Python microservice codebase for architectural patterns, design decisions, and improvement opportunities. Let me start by examining the overall structure and understanding the technology stack.\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Starting analysis of FastAPI microservice with PostgreSQL, Redis, and SQLAlchemy. Initial examination shows user management functionality with caching layer.\",\n \"files_checked\": [self.main_service_file],\n \"relevant_files\": [self.main_service_file, self.config_file, self.models_file, self.utils_file],\n \"prompt\": \"Analyze this microservice architecture for scalability, maintainability, and design patterns\",\n \"analysis_type\": \"architecture\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to get initial analysis response\")\n return False\n\n # Parse and validate JSON response\n response1_data = self._parse_analyze_response(response1)\n if not response1_data:\n return False\n\n # Validate step 1 response structure - expect pause_for_analysis for next_step_required=True\n if not self._validate_step_response(response1_data, 1, 4, True, \"pause_for_analysis\"):\n return False\n\n self.logger.info(f\" βœ… Step 1 successful, continuation_id: {continuation_id}\")\n\n # Step 2: Deeper examination\n self.logger.info(\" 1.1.2: Step 2 - Architecture examination\")\n response2, _ = self.call_mcp_tool(\n \"analyze\",\n {\n \"step\": \"Now examining the configuration and models modules to understand data architecture and configuration management patterns.\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Found several architectural concerns: direct Redis dependency in service class, global configuration instance, missing error handling in database operations, and mixed serialization logic in models.\",\n \"files_checked\": [self.main_service_file, self.config_file, self.models_file],\n \"relevant_files\": [self.main_service_file, self.config_file, self.models_file],\n \"relevant_context\": [\"UserService\", \"AppConfig\", \"User.to_dict\"],\n \"issues_found\": [\n {\n \"severity\": \"medium\",\n \"description\": \"Direct dependency on global Redis client in UserService\",\n },\n {\"severity\": \"low\", \"description\": \"Global configuration instance could cause testing issues\"},\n ],\n \"confidence\": \"medium\",\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue analysis to step 2\")\n return False\n\n response2_data = self._parse_analyze_response(response2)\n if not self._validate_step_response(response2_data, 2, 4, True, \"pause_for_analysis\"):\n return False\n\n # Check analysis status tracking\n analysis_status = response2_data.get(\"analysis_status\", {})\n if analysis_status.get(\"files_checked\", 0) < 3:\n self.logger.error(\"Files checked count not properly tracked\")\n return False\n\n if analysis_status.get(\"insights_by_severity\", {}).get(\"medium\", 0) < 1:\n self.logger.error(\"Medium severity insights not properly tracked\")\n return False\n\n if analysis_status.get(\"analysis_confidence\") != \"medium\":\n self.logger.error(\"Confidence level not properly tracked\")\n return False\n\n self.logger.info(\" βœ… Step 2 successful with proper tracking\")\n\n # Store continuation_id for next test\n self.analysis_continuation_id = continuation_id\n return True\n\n except Exception as e:\n self.logger.error(f\"Single analysis session test failed: {e}\")\n return False\n\n def _test_analysis_refocus_flow(self) -> bool:\n \"\"\"Test analysis flow that requires refocusing to revise findings\"\"\"\n try:\n self.logger.info(\" 1.2: Testing analysis refocus workflow\")\n\n # Start a new analysis for testing refocus behaviour\n self.logger.info(\" 1.2.1: Start analysis for refocus test\")\n response1, continuation_id = self.call_mcp_tool(\n \"analyze\",\n {\n \"step\": \"Analyzing performance characteristics of the data processing pipeline\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Initial analysis suggests database queries might be the bottleneck\",\n \"files_checked\": [self.main_service_file],\n \"relevant_files\": [self.main_service_file, self.utils_file],\n \"prompt\": \"Analyze performance bottlenecks in this microservice\",\n \"analysis_type\": \"performance\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start refocus test analysis\")\n return False\n\n # Step 2: Wrong direction\n self.logger.info(\" 1.2.2: Step 2 - Incorrect analysis path\")\n response2, _ = self.call_mcp_tool(\n \"analyze\",\n {\n \"step\": \"Focusing on database optimization strategies\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Database queries seem reasonable, might be looking in wrong direction\",\n \"files_checked\": [self.main_service_file, self.models_file],\n \"relevant_files\": [],\n \"relevant_context\": [],\n \"issues_found\": [],\n \"confidence\": \"low\",\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue to step 2\")\n return False\n\n # Step 3: Adjust investigation path\n self.logger.info(\" 1.2.3: Step 3 - Refocus the analysis\")\n response3, _ = self.call_mcp_tool(\n \"analyze\",\n {\n \"step\": \"Refocus - the performance issue might not be database related. Let me examine the caching and serialization patterns instead.\",\n \"step_number\": 3,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Found potential performance issues in JSON serialization and cache key generation patterns in utils module\",\n \"files_checked\": [self.utils_file, self.models_file],\n \"relevant_files\": [self.utils_file, self.models_file],\n \"relevant_context\": [\"generate_cache_key\", \"User.to_dict\", \"sanitize_input\"],\n \"issues_found\": [\n {\"severity\": \"medium\", \"description\": \"JSON serialization in model classes could be optimized\"},\n {\"severity\": \"low\", \"description\": \"Cache key generation lacks proper escaping\"},\n ],\n \"confidence\": \"medium\",\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response3:\n self.logger.error(\"Failed to refocus analysis\")\n return False\n\n response3_data = self._parse_analyze_response(response3)\n if not self._validate_step_response(response3_data, 3, 4, True, \"pause_for_analysis\"):\n return False\n\n self.logger.info(\" βœ… Analysis refocus flow working correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Backtracking test failed: {e}\")\n return False\n\n def _test_complete_analysis_with_expert(self) -> bool:\n \"\"\"Test complete analysis ending with expert validation\"\"\"\n try:\n self.logger.info(\" 1.3: Testing complete analysis with expert validation\")\n\n # Use the continuation from first test\n continuation_id = getattr(self, \"analysis_continuation_id\", None)\n if not continuation_id:\n # Start fresh if no continuation available\n self.logger.info(\" 1.3.0: Starting fresh analysis\")\n response0, continuation_id = self.call_mcp_tool(\n \"analyze\",\n {\n \"step\": \"Analyzing the microservice architecture for improvement opportunities\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"findings\": \"Found dependency injection and configuration management issues\",\n \"files_checked\": [self.main_service_file, self.config_file],\n \"relevant_files\": [self.main_service_file, self.config_file],\n \"relevant_context\": [\"UserService\", \"AppConfig\"],\n \"prompt\": \"Analyze architectural patterns and improvement opportunities\",\n \"analysis_type\": \"architecture\",\n },\n )\n if not response0 or not continuation_id:\n self.logger.error(\"Failed to start fresh analysis\")\n return False\n\n # Final step - trigger expert validation\n self.logger.info(\" 1.3.1: Final step - complete analysis\")\n response_final, _ = self.call_mcp_tool(\n \"analyze\",\n {\n \"step\": \"Analysis complete. I have identified key architectural patterns and strategic improvement opportunities across scalability, maintainability, and performance dimensions.\",\n \"step_number\": 2,\n \"total_steps\": 2,\n \"next_step_required\": False, # Final step - triggers expert validation\n \"findings\": \"Key findings: 1) Tight coupling via global dependencies, 2) Missing error handling and transaction management, 3) Mixed concerns in model classes, 4) Configuration management could be more flexible, 5) Opportunities for dependency injection and better separation of concerns.\",\n \"files_checked\": [self.main_service_file, self.config_file, self.models_file, self.utils_file],\n \"relevant_files\": [self.main_service_file, self.config_file, self.models_file, self.utils_file],\n \"relevant_context\": [\"UserService\", \"AppConfig\", \"User\", \"validate_email\"],\n \"issues_found\": [\n {\"severity\": \"high\", \"description\": \"Tight coupling via global Redis client and configuration\"},\n {\"severity\": \"medium\", \"description\": \"Missing transaction management in create_user\"},\n {\"severity\": \"medium\", \"description\": \"Serialization logic mixed with model classes\"},\n {\"severity\": \"low\", \"description\": \"Magic numbers and hardcoded values scattered throughout\"},\n ],\n \"confidence\": \"high\",\n \"continuation_id\": continuation_id,\n \"model\": \"flash\", # Use flash for expert validation\n },\n )\n\n if not response_final:\n self.logger.error(\"Failed to complete analysis\")\n return False\n\n response_final_data = self._parse_analyze_response(response_final)\n if not response_final_data:\n return False\n\n # Validate final response structure - expect calling_expert_analysis for next_step_required=False\n if response_final_data.get(\"status\") != \"calling_expert_analysis\":\n self.logger.error(\n f\"Expected status 'calling_expert_analysis', got '{response_final_data.get('status')}'\"\n )\n return False\n\n if not response_final_data.get(\"analysis_complete\"):\n self.logger.error(\"Expected analysis_complete=true for final step\")\n return False # Check for expert analysis\n if \"expert_analysis\" not in response_final_data:\n self.logger.error(\"Missing expert_analysis in final response\")\n return False\n\n expert_analysis = response_final_data.get(\"expert_analysis\", {})\n\n # Check for expected analysis content (checking common patterns)\n analysis_text = json.dumps(expert_analysis, ensure_ascii=False).lower()\n\n # Look for architectural analysis indicators\n arch_indicators = [\"architecture\", \"pattern\", \"coupling\", \"dependency\", \"scalability\", \"maintainability\"]\n found_indicators = sum(1 for indicator in arch_indicators if indicator in analysis_text)\n\n if found_indicators >= 3:\n self.logger.info(\" βœ… Expert analysis identified architectural patterns correctly\")\n else:\n self.logger.warning(\n f\" ⚠️ Expert analysis may not have fully analyzed architecture (found {found_indicators}/6 indicators)\"\n )\n\n # Check complete analysis summary\n if \"complete_analysis\" not in response_final_data:\n self.logger.error(\"Missing complete_analysis in final response\")\n return False\n\n complete_analysis = response_final_data[\"complete_analysis\"]\n if not complete_analysis.get(\"relevant_context\"):\n self.logger.error(\"Missing relevant context in complete analysis\")\n return False\n\n if \"UserService\" not in complete_analysis[\"relevant_context\"]:\n self.logger.error(\"Expected context not found in analysis summary\")\n return False\n\n self.logger.info(\" βœ… Complete analysis with expert validation successful\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Complete analysis test failed: {e}\")\n return False\n\n def _test_certain_confidence(self) -> bool:\n \"\"\"Test final step analysis completion (analyze tool doesn't use confidence levels)\"\"\"\n try:\n self.logger.info(\" 1.4: Testing final step analysis completion\")\n\n # Test final step - analyze tool doesn't use confidence levels, but we test completion\n self.logger.info(\" 1.4.1: Final step analysis\")\n response_final, _ = self.call_mcp_tool(\n \"analyze\",\n {\n \"step\": \"I have completed a comprehensive analysis of the architectural patterns and improvement opportunities.\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False, # Final step - should trigger expert analysis\n \"findings\": \"Complete architectural analysis reveals: FastAPI microservice with clear separation needs, dependency injection opportunities, and performance optimization potential. Key patterns identified: service layer, repository-like data access, configuration management, and utility functions.\",\n \"files_checked\": [self.main_service_file, self.config_file, self.models_file, self.utils_file],\n \"relevant_files\": [self.main_service_file, self.config_file, self.models_file, self.utils_file],\n \"relevant_context\": [\"UserService\", \"AppConfig\", \"User\", \"validate_email\"],\n \"issues_found\": [\n {\"severity\": \"high\", \"description\": \"Global dependencies create tight coupling\"},\n {\"severity\": \"medium\", \"description\": \"Transaction management missing in critical operations\"},\n ],\n \"prompt\": \"Comprehensive architectural analysis\",\n \"analysis_type\": \"architecture\",\n \"model\": \"flash\",\n },\n )\n\n if not response_final:\n self.logger.error(\"Failed to test final step analysis\")\n return False\n\n response_final_data = self._parse_analyze_response(response_final)\n if not response_final_data:\n return False\n\n # Validate final step response - should trigger expert analysis\n expected_status = \"calling_expert_analysis\"\n if response_final_data.get(\"status\") != expected_status:\n self.logger.error(f\"Expected status '{expected_status}', got '{response_final_data.get('status')}'\")\n return False\n\n # Check that expert analysis was performed\n expert_analysis = response_final_data.get(\"expert_analysis\", {})\n if not expert_analysis:\n self.logger.error(\"Expert analysis should be present for final step\")\n return False\n\n # Expert analysis should complete successfully\n if expert_analysis.get(\"status\") != \"analysis_complete\":\n self.logger.error(\n f\"Expert analysis status: {expert_analysis.get('status')} (expected analysis_complete)\"\n )\n return False\n\n self.logger.info(\" βœ… Final step analysis completion working correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Final step analysis test failed: {e}\")\n return False\n\n def _test_context_aware_file_embedding(self) -> bool:\n \"\"\"Test context-aware file embedding optimization\"\"\"\n try:\n self.logger.info(\" 1.5: Testing context-aware file embedding\")\n\n # Test 1: New conversation, intermediate step - should only reference files\n self.logger.info(\" 1.5.1: New conversation intermediate step (should reference only)\")\n response1, continuation_id = self.call_mcp_tool(\n \"analyze\",\n {\n \"step\": \"Starting architectural analysis of microservice components\",\n \"step_number\": 1,\n \"total_steps\": 3,\n \"next_step_required\": True, # Intermediate step\n \"findings\": \"Initial analysis of service layer and configuration patterns\",\n \"files_checked\": [self.main_service_file, self.config_file],\n \"relevant_files\": [self.main_service_file], # This should be referenced, not embedded\n \"relevant_context\": [\"UserService\"],\n \"issues_found\": [{\"severity\": \"medium\", \"description\": \"Direct Redis dependency in service class\"}],\n \"confidence\": \"low\",\n \"prompt\": \"Analyze service architecture patterns\",\n \"analysis_type\": \"architecture\",\n \"model\": \"flash\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start context-aware file embedding test\")\n return False\n\n response1_data = self._parse_analyze_response(response1)\n if not response1_data:\n return False\n\n # Check file context - should be reference_only for intermediate step\n file_context = response1_data.get(\"file_context\", {})\n if file_context.get(\"type\") != \"reference_only\":\n self.logger.error(f\"Expected reference_only file context, got: {file_context.get('type')}\")\n return False\n\n if \"Files referenced but not embedded\" not in file_context.get(\"context_optimization\", \"\"):\n self.logger.error(\"Expected context optimization message for reference_only\")\n return False\n\n self.logger.info(\" βœ… Intermediate step correctly uses reference_only file context\")\n\n # Test 2: Final step - should embed files for expert validation\n self.logger.info(\" 1.5.2: Final step (should embed files)\")\n response2, _ = self.call_mcp_tool(\n \"analyze\",\n {\n \"step\": \"Analysis complete - identified key architectural patterns and improvement opportunities\",\n \"step_number\": 2,\n \"total_steps\": 2,\n \"next_step_required\": False, # Final step - should embed files\n \"continuation_id\": continuation_id,\n \"findings\": \"Complete analysis reveals dependency injection opportunities, configuration management improvements, and separation of concerns enhancements\",\n \"files_checked\": [self.main_service_file, self.config_file, self.models_file],\n \"relevant_files\": [self.main_service_file, self.config_file], # Should be fully embedded\n \"relevant_context\": [\"UserService\", \"AppConfig\"],\n \"issues_found\": [\n {\"severity\": \"high\", \"description\": \"Global dependencies create architectural coupling\"},\n {\"severity\": \"medium\", \"description\": \"Configuration management lacks flexibility\"},\n ],\n \"confidence\": \"high\",\n \"model\": \"flash\",\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to complete to final step\")\n return False\n\n response2_data = self._parse_analyze_response(response2)\n if not response2_data:\n return False\n\n # Check file context - should be fully_embedded for final step\n file_context2 = response2_data.get(\"file_context\", {})\n if file_context2.get(\"type\") != \"fully_embedded\":\n self.logger.error(\n f\"Expected fully_embedded file context for final step, got: {file_context2.get('type')}\"\n )\n return False\n\n if \"Full file content embedded for expert analysis\" not in file_context2.get(\"context_optimization\", \"\"):\n self.logger.error(\"Expected expert analysis optimization message for fully_embedded\")\n return False\n\n # Verify expert analysis was called for final step\n if response2_data.get(\"status\") != \"calling_expert_analysis\":\n self.logger.error(\"Final step should trigger expert analysis\")\n return False\n\n if \"expert_analysis\" not in response2_data:\n self.logger.error(\"Expert analysis should be present in final step\")\n return False\n\n self.logger.info(\" βœ… Context-aware file embedding test completed successfully\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Context-aware file embedding test failed: {e}\")\n return False\n\n def _test_analysis_types(self) -> bool:\n \"\"\"Test different analysis types (architecture, performance, security, quality)\"\"\"\n try:\n self.logger.info(\" 1.6: Testing different analysis types\")\n\n # Test security analysis\n self.logger.info(\" 1.6.1: Security analysis\")\n response_security, _ = self.call_mcp_tool(\n \"analyze\",\n {\n \"step\": \"Conducting security analysis of authentication and data handling patterns\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Security analysis reveals: password hashing implementation, input validation patterns, SQL injection prevention via parameterized queries, but missing input sanitization in some areas and weak default secret key handling.\",\n \"files_checked\": [self.main_service_file, self.utils_file],\n \"relevant_files\": [self.main_service_file, self.utils_file],\n \"relevant_context\": [\"hash_password\", \"validate_email\", \"sanitize_input\"],\n \"issues_found\": [\n {\"severity\": \"critical\", \"description\": \"Weak default secret key in production detection\"},\n {\"severity\": \"medium\", \"description\": \"Input sanitization not consistently applied\"},\n ],\n \"confidence\": \"high\",\n \"prompt\": \"Analyze security patterns and vulnerabilities\",\n \"analysis_type\": \"security\",\n \"model\": \"flash\",\n },\n )\n\n if not response_security:\n self.logger.error(\"Failed security analysis test\")\n return False\n\n response_security_data = self._parse_analyze_response(response_security)\n if not response_security_data:\n return False\n\n # Check that security analysis was processed\n issues = response_security_data.get(\"complete_analysis\", {}).get(\"issues_found\", [])\n critical_issues = [issue for issue in issues if issue.get(\"severity\") == \"critical\"]\n\n if not critical_issues:\n self.logger.warning(\"Security analysis should have identified critical security issues\")\n else:\n self.logger.info(\" βœ… Security analysis identified critical issues\")\n\n # Test quality analysis\n self.logger.info(\" 1.6.2: Quality analysis\")\n response_quality, _ = self.call_mcp_tool(\n \"analyze\",\n {\n \"step\": \"Conducting code quality analysis focusing on maintainability and best practices\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Code quality analysis shows: good use of type hints, proper error handling in some areas but missing in others, mixed separation of concerns, and opportunities for better abstraction.\",\n \"files_checked\": [self.models_file, self.utils_file],\n \"relevant_files\": [self.models_file, self.utils_file],\n \"relevant_context\": [\"User.to_dict\", \"ValidationError\", \"PerformanceTimer\"],\n \"issues_found\": [\n {\"severity\": \"medium\", \"description\": \"Serialization logic mixed with model classes\"},\n {\"severity\": \"low\", \"description\": \"Inconsistent error handling patterns\"},\n ],\n \"confidence\": \"high\",\n \"prompt\": \"Analyze code quality and maintainability patterns\",\n \"analysis_type\": \"quality\",\n \"model\": \"flash\",\n },\n )\n\n if not response_quality:\n self.logger.error(\"Failed quality analysis test\")\n return False\n\n response_quality_data = self._parse_analyze_response(response_quality)\n if not response_quality_data:\n return False\n\n # Verify quality analysis was processed\n quality_context = response_quality_data.get(\"complete_analysis\", {}).get(\"relevant_context\", [])\n if not any(\"User\" in ctx for ctx in quality_context):\n self.logger.warning(\"Quality analysis should have analyzed model classes\")\n else:\n self.logger.info(\" βœ… Quality analysis examined relevant code elements\")\n\n self.logger.info(\" βœ… Different analysis types test completed successfully\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Analysis types test failed: {e}\")\n return False\n\n def call_mcp_tool(self, tool_name: str, params: dict) -> tuple[Optional[str], Optional[str]]:\n \"\"\"Call an MCP tool in-process - override for analyze-specific response handling\"\"\"\n # Use in-process implementation to maintain conversation memory\n response_text, _ = self.call_mcp_tool_direct(tool_name, params)\n\n if not response_text:\n return None, None\n\n # Extract continuation_id from analyze response specifically\n continuation_id = self._extract_analyze_continuation_id(response_text)\n\n return response_text, continuation_id\n\n def _extract_analyze_continuation_id(self, response_text: str) -> Optional[str]:\n \"\"\"Extract continuation_id from analyze response\"\"\"\n try:\n # Parse the response\n response_data = json.loads(response_text)\n return response_data.get(\"continuation_id\")\n\n except json.JSONDecodeError as e:\n self.logger.debug(f\"Failed to parse response for analyze continuation_id: {e}\")\n return None\n\n def _parse_analyze_response(self, response_text: str) -> dict:\n \"\"\"Parse analyze tool JSON response\"\"\"\n try:\n # Parse the response - it should be direct JSON\n return json.loads(response_text)\n\n except json.JSONDecodeError as e:\n self.logger.error(f\"Failed to parse analyze response as JSON: {e}\")\n self.logger.error(f\"Response text: {response_text[:500]}...\")\n return {}\n\n def _validate_step_response(\n self,\n response_data: dict,\n expected_step: int,\n expected_total: int,\n expected_next_required: bool,\n expected_status: str,\n ) -> bool:\n \"\"\"Validate an analyze investigation step response structure\"\"\"\n try:\n # Check status\n if response_data.get(\"status\") != expected_status:\n self.logger.error(f\"Expected status '{expected_status}', got '{response_data.get('status')}'\")\n return False\n\n # Check step number\n if response_data.get(\"step_number\") != expected_step:\n self.logger.error(f\"Expected step_number {expected_step}, got {response_data.get('step_number')}\")\n return False\n\n # Check total steps\n if response_data.get(\"total_steps\") != expected_total:\n self.logger.error(f\"Expected total_steps {expected_total}, got {response_data.get('total_steps')}\")\n return False\n\n # Check next_step_required\n if response_data.get(\"next_step_required\") != expected_next_required:\n self.logger.error(\n f\"Expected next_step_required {expected_next_required}, got {response_data.get('next_step_required')}\"\n )\n return False\n\n # Check analysis_status exists\n if \"analysis_status\" not in response_data:\n self.logger.error(\"Missing analysis_status in response\")\n return False\n\n # Check next_steps guidance\n if not response_data.get(\"next_steps\"):\n self.logger.error(\"Missing next_steps guidance in response\")\n return False\n\n return True\n\n except Exception as e:\n self.logger.error(f\"Error validating step response: {e}\")\n return False\n" }, { "path": "simulator_tests/test_basic_conversation.py", "content": "#!/usr/bin/env python3\n\"\"\"\nBasic Conversation Flow Test\n\nTests basic conversation continuity with the chat tool, including:\n- Initial chat with file analysis\n- Continuing conversation with same file (deduplication)\n- Adding additional files to ongoing conversation\n\"\"\"\n\nfrom .base_test import BaseSimulatorTest\n\n\nclass BasicConversationTest(BaseSimulatorTest):\n \"\"\"Test basic conversation flow with chat tool\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"basic_conversation\"\n\n @property\n def test_description(self) -> str:\n return \"Basic conversation flow with chat tool\"\n\n def run_test(self) -> bool:\n \"\"\"Test basic conversation flow with chat tool\"\"\"\n try:\n self.logger.info(\"Test: Basic conversation flow\")\n\n # Setup test files\n self.setup_test_files()\n\n # Initial chat tool call with file\n self.logger.info(\" 1.1: Initial chat with file analysis\")\n response1, continuation_id = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. Analyze this Python code and explain what it does\",\n \"absolute_file_paths\": [self.test_files[\"python\"]],\n \"model\": \"flash\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to get initial response with continuation_id\")\n return False\n\n self.logger.info(f\" βœ… Got continuation_id: {continuation_id}\")\n\n # Continue conversation with same file (should be deduplicated)\n self.logger.info(\" 1.2: Continue conversation with same file\")\n response2, _ = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. Now focus on the Calculator class specifically. Are there any improvements you'd suggest?\",\n \"absolute_file_paths\": [self.test_files[\"python\"]], # Same file - should be deduplicated\n \"continuation_id\": continuation_id,\n \"model\": \"flash\",\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue conversation\")\n return False\n\n # Continue with additional file\n self.logger.info(\" 1.3: Continue conversation with additional file\")\n response3, _ = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. Now also analyze this configuration file and see how it might relate to the Python code\",\n \"absolute_file_paths\": [self.test_files[\"python\"], self.test_files[\"config\"]],\n \"continuation_id\": continuation_id,\n \"model\": \"flash\",\n },\n )\n\n if not response3:\n self.logger.error(\"Failed to continue with additional file\")\n return False\n\n self.logger.info(\" βœ… Basic conversation flow working\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Basic conversation flow test failed: {e}\")\n return False\n finally:\n self.cleanup_test_files()\n" }, { "path": "simulator_tests/test_chat_simple_validation.py", "content": "#!/usr/bin/env python3\n\"\"\"\nChat Simple Tool Validation Test\n\nComprehensive test for the new ChatSimple tool implementation that validates:\n- Basic conversation flow without continuation_id (new chats)\n- Continuing existing conversations with continuation_id (continued chats)\n- File handling with conversation context (chats with files)\n- Image handling in conversations (chat with images)\n- Continuing conversations with files from previous turns (continued chats with files previously)\n- Temperature validation for different models\n- Image limit validation per model\n- Conversation context preservation across turns\n\"\"\"\n\n\nfrom .conversation_base_test import ConversationBaseTest\n\n\nclass ChatSimpleValidationTest(ConversationBaseTest):\n \"\"\"Test ChatSimple tool functionality and validation\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"_validation\"\n\n @property\n def test_description(self) -> str:\n return \"Comprehensive validation of ChatSimple tool implementation\"\n\n def run_test(self) -> bool:\n \"\"\"Run comprehensive ChatSimple validation tests\"\"\"\n try:\n # Set up the test environment for in-process testing\n self.setUp()\n\n self.logger.info(\"Test: ChatSimple tool validation\")\n\n # Run all test scenarios\n if not self.test_new_conversation_no_continuation():\n return False\n\n if not self.test_continue_existing_conversation():\n return False\n\n if not self.test_file_handling_with_conversation():\n return False\n\n if not self.test_temperature_validation_edge_cases():\n return False\n\n if not self.test_image_limits_per_model():\n return False\n\n if not self.test_conversation_context_preservation():\n return False\n\n if not self.test_chat_with_images():\n return False\n\n if not self.test_continued_chat_with_previous_files():\n return False\n\n self.logger.info(\" βœ… All ChatSimple validation tests passed\")\n return True\n\n except Exception as e:\n self.logger.error(f\"ChatSimple validation test failed: {e}\")\n return False\n\n def test_new_conversation_no_continuation(self) -> bool:\n \"\"\"Test ChatSimple creates new conversation without continuation_id\"\"\"\n try:\n self.logger.info(\" 1. Test new conversation without continuation_id\")\n\n # Call chat without continuation_id\n response, continuation_id = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": \"Hello! Please use low thinking mode. Can you explain what MCP tools are?\",\n \"model\": \"flash\",\n \"temperature\": 0.7,\n \"thinking_mode\": \"low\",\n },\n )\n\n if not response:\n self.logger.error(\" ❌ Failed to get response from chat\")\n return False\n\n if not continuation_id:\n self.logger.error(\" ❌ No continuation_id returned for new conversation\")\n return False\n\n # Verify response mentions MCP or tools\n if \"MCP\" not in response and \"tool\" not in response.lower():\n self.logger.error(\" ❌ Response doesn't seem to address the question about MCP tools\")\n return False\n\n self.logger.info(f\" βœ… New conversation created with continuation_id: {continuation_id}\")\n self.new_continuation_id = continuation_id # Store for next test\n return True\n\n except Exception as e:\n self.logger.error(f\" ❌ New conversation test failed: {e}\")\n return False\n\n def test_continue_existing_conversation(self) -> bool:\n \"\"\"Test ChatSimple continues conversation with valid continuation_id\"\"\"\n try:\n self.logger.info(\" 2. Test continuing existing conversation\")\n\n if not hasattr(self, \"new_continuation_id\"):\n self.logger.error(\" ❌ No continuation_id from previous test\")\n return False\n\n # Continue the conversation\n response, continuation_id = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. Can you give me a specific example of how an MCP tool might work?\",\n \"continuation_id\": self.new_continuation_id,\n \"model\": \"flash\",\n \"thinking_mode\": \"low\",\n },\n )\n\n if not response:\n self.logger.error(\" ❌ Failed to continue conversation\")\n return False\n\n # Continuation ID should be the same\n if continuation_id != self.new_continuation_id:\n self.logger.error(f\" ❌ Continuation ID changed: {self.new_continuation_id} -> {continuation_id}\")\n return False\n\n # Response should be contextual (mentioning previous discussion)\n if \"example\" not in response.lower():\n self.logger.error(\" ❌ Response doesn't seem to provide an example as requested\")\n return False\n\n self.logger.info(\" βœ… Successfully continued conversation with same continuation_id\")\n return True\n\n except Exception as e:\n self.logger.error(f\" ❌ Continue conversation test failed: {e}\")\n return False\n\n def test_file_handling_with_conversation(self) -> bool:\n \"\"\"Test ChatSimple handles files correctly in conversation context\"\"\"\n try:\n self.logger.info(\" 3. Test file handling with conversation\")\n\n # Setup test files\n self.setup_test_files()\n\n # Start new conversation with a file\n response1, continuation_id = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. Analyze this Python code and tell me what the Calculator class does\",\n \"absolute_file_paths\": [self.test_files[\"python\"]],\n \"model\": \"flash\",\n \"thinking_mode\": \"low\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\" ❌ Failed to start conversation with file\")\n return False\n\n # Continue with same file (should be deduplicated)\n response2, _ = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. What methods does the Calculator class have?\",\n \"absolute_file_paths\": [self.test_files[\"python\"]], # Same file\n \"continuation_id\": continuation_id,\n \"model\": \"flash\",\n \"thinking_mode\": \"low\",\n },\n )\n\n if not response2:\n self.logger.error(\" ❌ Failed to continue with same file\")\n return False\n\n # Response should mention add and multiply methods\n if \"add\" not in response2.lower() or \"multiply\" not in response2.lower():\n self.logger.error(\" ❌ Response doesn't mention Calculator methods\")\n return False\n\n self.logger.info(\" βœ… File handling with conversation working correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\" ❌ File handling test failed: {e}\")\n return False\n finally:\n self.cleanup_test_files()\n\n def test_temperature_validation_edge_cases(self) -> bool:\n \"\"\"Test temperature is corrected for model limits (too high/low)\"\"\"\n try:\n self.logger.info(\" 4. Test temperature validation edge cases\")\n\n # Test 1: Temperature exactly at limit (should work)\n response1, _ = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. Hello, this is a test with max temperature\",\n \"model\": \"flash\",\n \"temperature\": 1.0, # At the limit\n \"thinking_mode\": \"low\",\n },\n )\n\n if not response1:\n self.logger.error(\" ❌ Failed with temperature 1.0\")\n return False\n\n # Test 2: Temperature at minimum (should work)\n response2, _ = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. Another test message with min temperature\",\n \"model\": \"flash\",\n \"temperature\": 0.0, # At minimum\n \"thinking_mode\": \"low\",\n },\n )\n\n if not response2:\n self.logger.error(\" ❌ Failed with temperature 0.0\")\n return False\n\n # Test 3: Check that invalid temperatures are rejected by validation\n # This should result in an error response from the tool, not a crash\n try:\n response3, _ = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. Test with invalid temperature\",\n \"model\": \"flash\",\n \"temperature\": 1.5, # Too high - should be validated\n \"thinking_mode\": \"low\",\n },\n )\n\n # If we get here, check if it's an error response\n if response3 and \"validation error\" in response3.lower():\n self.logger.info(\" βœ… Invalid temperature properly rejected by validation\")\n else:\n self.logger.warning(\" ⚠️ High temperature not properly validated\")\n except Exception:\n # Expected - validation should reject this\n self.logger.info(\" βœ… Invalid temperature properly rejected\")\n\n self.logger.info(\" βœ… Temperature validation working correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\" ❌ Temperature validation test failed: {e}\")\n return False\n\n def test_image_limits_per_model(self) -> bool:\n \"\"\"Test image validation respects model-specific limits\"\"\"\n try:\n self.logger.info(\" 5. Test image limits per model\")\n\n # Create test image data URLs (small base64 images)\n small_image = \"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==\"\n\n # Test 1: Model that doesn't support images\n response1, _ = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. Can you see this image?\",\n \"model\": \"local-llama\", # Text-only model\n \"images\": [small_image],\n \"thinking_mode\": \"low\",\n },\n )\n\n # Should get an error about image support\n if response1 and \"does not support image\" not in response1:\n self.logger.warning(\" ⚠️ Model without image support didn't reject images properly\")\n\n # Test 2: Too many images for a model\n many_images = [small_image] * 25 # Most models support max 20\n\n response2, _ = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. Analyze these images\",\n \"model\": \"gemini-2.5-flash\", # Supports max 16 images\n \"images\": many_images,\n \"thinking_mode\": \"low\",\n },\n )\n\n # Should get an error about too many images\n if response2 and \"too many images\" not in response2.lower():\n self.logger.warning(\" ⚠️ Model didn't reject excessive image count\")\n\n # Test 3: Valid image count\n response3, _ = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. This is a test with one image\",\n \"model\": \"gemini-2.5-flash\",\n \"images\": [small_image],\n \"thinking_mode\": \"low\",\n },\n )\n\n if not response3:\n self.logger.error(\" ❌ Failed with valid image count\")\n return False\n\n self.logger.info(\" βœ… Image validation working correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\" ❌ Image limits test failed: {e}\")\n return False\n\n def test_conversation_context_preservation(self) -> bool:\n \"\"\"Test ChatSimple preserves context across turns\"\"\"\n try:\n self.logger.info(\" 6. Test conversation context preservation\")\n\n # Start conversation with specific context\n response1, continuation_id = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. My name is TestUser and I'm working on a Python project called TestProject\",\n \"model\": \"flash\",\n \"thinking_mode\": \"low\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\" ❌ Failed to start conversation\")\n return False\n\n # Continue and reference previous context\n response2, _ = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. What's my name and what project am I working on?\",\n \"continuation_id\": continuation_id,\n \"model\": \"flash\",\n \"thinking_mode\": \"low\",\n },\n )\n\n if not response2:\n self.logger.error(\" ❌ Failed to continue conversation\")\n return False\n\n # Check if context was preserved\n if \"TestUser\" not in response2 or \"TestProject\" not in response2:\n self.logger.error(\" ❌ Context not preserved across conversation turns\")\n self.logger.debug(f\" Response: {response2[:200]}...\")\n return False\n\n self.logger.info(\" βœ… Conversation context preserved correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\" ❌ Context preservation test failed: {e}\")\n return False\n\n def test_chat_with_images(self) -> bool:\n \"\"\"Test ChatSimple handles images correctly in conversation\"\"\"\n try:\n self.logger.info(\" 7. Test chat with images\")\n\n # Create test image data URL (small base64 image)\n small_image = \"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==\"\n\n # Start conversation with image\n response1, continuation_id = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. I'm sharing an image with you. Can you acknowledge that you received it?\",\n \"images\": [small_image],\n \"model\": \"gemini-2.5-flash\", # Model that supports images\n \"thinking_mode\": \"low\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\" ❌ Failed to start conversation with image\")\n return False\n\n # Verify response acknowledges the image\n if \"image\" not in response1.lower():\n self.logger.warning(\" ⚠️ Response doesn't acknowledge receiving image\")\n\n # Continue conversation referencing the image\n response2, _ = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. What did you see in that image I shared earlier?\",\n \"continuation_id\": continuation_id,\n \"model\": \"gemini-2.5-flash\",\n \"thinking_mode\": \"low\",\n },\n )\n\n if not response2:\n self.logger.error(\" ❌ Failed to continue conversation about image\")\n return False\n\n # Test with multiple images\n multiple_images = [small_image, small_image] # Two identical small images\n response3, _ = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. Here are two images for comparison\",\n \"images\": multiple_images,\n \"model\": \"gemini-2.5-flash\",\n \"thinking_mode\": \"low\",\n },\n )\n\n if not response3:\n self.logger.error(\" ❌ Failed with multiple images\")\n return False\n\n self.logger.info(\" βœ… Chat with images working correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\" ❌ Chat with images test failed: {e}\")\n return False\n\n def test_continued_chat_with_previous_files(self) -> bool:\n \"\"\"Test continuing conversation where files were shared in previous turns\"\"\"\n try:\n self.logger.info(\" 8. Test continued chat with files from previous turns\")\n\n # Setup test files\n self.setup_test_files()\n\n # Start conversation with files\n response1, continuation_id = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. Here are some files for you to analyze\",\n \"absolute_file_paths\": [self.test_files[\"python\"], self.test_files[\"config\"]],\n \"model\": \"flash\",\n \"thinking_mode\": \"low\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\" ❌ Failed to start conversation with files\")\n return False\n\n # Continue conversation without new files (should remember previous files)\n response2, _ = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. From the files I shared earlier, what types of files were there?\",\n \"continuation_id\": continuation_id,\n \"model\": \"flash\",\n \"thinking_mode\": \"low\",\n },\n )\n\n if not response2:\n self.logger.error(\" ❌ Failed to continue conversation\")\n return False\n\n # Check if response references the files from previous turn\n if \"python\" not in response2.lower() and \"config\" not in response2.lower():\n self.logger.warning(\" ⚠️ Response doesn't reference previous files properly\")\n\n # Continue with a different question about same files (should still remember them)\n response3, _ = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. Can you tell me what functions were defined in the Python file from our earlier discussion?\",\n \"continuation_id\": continuation_id,\n \"model\": \"flash\",\n \"thinking_mode\": \"low\",\n },\n )\n\n if not response3:\n self.logger.error(\" ❌ Failed to continue conversation about Python file\")\n return False\n\n # Should reference functions from the Python file (fibonacci, factorial, Calculator, etc.)\n response_lower = response3.lower()\n if not (\"fibonacci\" in response_lower or \"factorial\" in response_lower or \"calculator\" in response_lower):\n self.logger.warning(\" ⚠️ Response doesn't reference Python file contents from earlier turn\")\n\n self.logger.info(\" βœ… Continued chat with previous files working correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\" ❌ Continued chat with files test failed: {e}\")\n return False\n finally:\n self.cleanup_test_files()\n" }, { "path": "simulator_tests/test_codereview_validation.py", "content": "#!/usr/bin/env python3\n\"\"\"\nCodeReview Tool Validation Test\n\nTests the codereview tool's capabilities using the new workflow architecture.\nThis validates that the workflow-based code review provides step-by-step\nanalysis with proper investigation guidance and expert analysis integration.\n\"\"\"\n\nimport json\nfrom typing import Optional\n\nfrom .conversation_base_test import ConversationBaseTest\n\n\nclass CodeReviewValidationTest(ConversationBaseTest):\n \"\"\"Test codereview tool with new workflow architecture\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"codereview_validation\"\n\n @property\n def test_description(self) -> str:\n return \"CodeReview tool validation with new workflow architecture\"\n\n def run_test(self) -> bool:\n \"\"\"Test codereview tool capabilities\"\"\"\n # Set up the test environment\n self.setUp()\n\n try:\n self.logger.info(\"Test: CodeReviewWorkflow tool validation (new architecture)\")\n\n # Create test code with various issues for review\n self._create_test_code_for_review()\n\n # Test 1: Single review session with multiple steps\n if not self._test_single_review_session():\n return False\n\n # Test 2: Review flow that requires refocusing\n if not self._test_review_refocus_flow():\n return False\n\n # Test 3: Complete review with expert analysis\n if not self._test_complete_review_with_analysis():\n return False\n\n # Test 4: Certain confidence behavior\n if not self._test_certain_confidence():\n return False\n\n # Test 5: Context-aware file embedding\n if not self._test_context_aware_file_embedding():\n return False\n\n # Test 6: Multi-step file context optimization\n if not self._test_multi_step_file_context():\n return False\n\n self.logger.info(\" βœ… All codereview validation tests passed\")\n return True\n\n except Exception as e:\n self.logger.error(f\"CodeReviewWorkflow validation test failed: {e}\")\n return False\n\n def _create_test_code_for_review(self):\n \"\"\"Create test files with various code quality issues for review\"\"\"\n # Create a payment processing module with multiple issues\n payment_code = \"\"\"#!/usr/bin/env python3\nimport hashlib\nimport requests\nimport json\nfrom datetime import datetime\n\nclass PaymentProcessor:\n def __init__(self, api_key):\n self.api_key = api_key # Security issue: API key stored in plain text\n self.base_url = \"https://payment-gateway.example.com\"\n self.session = requests.Session()\n self.failed_payments = [] # Performance issue: unbounded list\n\n def process_payment(self, amount, card_number, cvv, user_id):\n \\\"\\\"\\\"Process a payment transaction\\\"\\\"\\\"\n # Security issue: No input validation\n # Performance issue: Inefficient nested loops\n for attempt in range(3):\n for retry in range(5):\n try:\n # Security issue: Logging sensitive data\n print(f\"Processing payment: {card_number}, CVV: {cvv}\")\n\n # Over-engineering: Complex hashing that's not needed\n payment_hash = self._generate_complex_hash(amount, card_number, cvv, user_id, datetime.now())\n\n # Security issue: Insecure HTTP request construction\n url = f\"{self.base_url}/charge?amount={amount}&card={card_number}&api_key={self.api_key}\"\n\n response = self.session.get(url) # Security issue: using GET for sensitive data\n\n if response.status_code == 200:\n return {\"status\": \"success\", \"hash\": payment_hash}\n else:\n # Code smell: Generic exception handling without specific error types\n self.failed_payments.append({\"amount\": amount, \"timestamp\": datetime.now()})\n\n except Exception as e:\n # Code smell: Bare except clause and poor error handling\n print(f\"Payment failed: {e}\")\n continue\n\n return {\"status\": \"failed\"}\n\n def _generate_complex_hash(self, amount, card_number, cvv, user_id, timestamp):\n \\\"\\\"\\\"Over-engineered hash generation with unnecessary complexity\\\"\\\"\\\"\n # Over-engineering: Overly complex for no clear benefit\n combined = f\"{amount}-{card_number}-{cvv}-{user_id}-{timestamp}\"\n\n # Security issue: Weak hashing algorithm\n hash1 = hashlib.md5(combined.encode()).hexdigest()\n hash2 = hashlib.sha1(hash1.encode()).hexdigest()\n hash3 = hashlib.md5(hash2.encode()).hexdigest()\n\n # Performance issue: Unnecessary string operations in loop\n result = \"\"\n for i in range(len(hash3)):\n for j in range(3): # Arbitrary nested loop\n result += hash3[i] if i % 2 == 0 else hash3[i].upper()\n\n return result[:32] # Arbitrary truncation\n\n def get_payment_history(self, user_id):\n \\\"\\\"\\\"Get payment history - has scalability issues\\\"\\\"\\\"\n # Performance issue: No pagination, could return massive datasets\n # Performance issue: Inefficient algorithm O(nΒ²)\n all_payments = self._fetch_all_payments() # Could be millions of records\n user_payments = []\n\n for payment in all_payments:\n for field in payment: # Unnecessary nested iteration\n if field == \"user_id\" and payment[field] == user_id:\n user_payments.append(payment)\n break\n\n return user_payments\n\n def _fetch_all_payments(self):\n \\\"\\\"\\\"Simulated method that would fetch all payments\\\"\\\"\\\"\n # Maintainability issue: Hard-coded test data\n return [\n {\"user_id\": 1, \"amount\": 100, \"status\": \"success\"},\n {\"user_id\": 2, \"amount\": 200, \"status\": \"failed\"},\n {\"user_id\": 1, \"amount\": 150, \"status\": \"success\"},\n ]\n\"\"\"\n\n # Create test file with multiple issues\n self.payment_file = self.create_additional_test_file(\"payment_processor.py\", payment_code)\n self.logger.info(f\" βœ… Created test file with code issues: {self.payment_file}\")\n\n # Create configuration file with additional issues\n config_code = \"\"\"#!/usr/bin/env python3\nimport os\n\n# Security issue: Hardcoded secrets\nDATABASE_PASSWORD = \"admin123\"\nSECRET_KEY = \"my-secret-key-12345\"\n\n# Over-engineering: Unnecessarily complex configuration class\nclass ConfigurationManager:\n def __init__(self):\n self.config_cache = {}\n self.config_hierarchy = {}\n self.config_validators = {}\n self.config_transformers = {}\n self.config_listeners = []\n\n def get_config(self, key, default=None):\n # Over-engineering: Complex caching for simple config lookup\n if key in self.config_cache:\n cached_value = self.config_cache[key]\n if self._validate_cached_value(cached_value):\n return self._transform_value(key, cached_value)\n\n # Code smell: Complex nested conditionals\n if key in self.config_hierarchy:\n hierarchy = self.config_hierarchy[key]\n for level in hierarchy:\n if level == \"env\":\n value = os.getenv(key.upper(), default)\n elif level == \"file\":\n value = self._read_from_file(key, default)\n elif level == \"database\":\n value = self._read_from_database(key, default)\n else:\n value = default\n\n if value is not None:\n self.config_cache[key] = value\n return self._transform_value(key, value)\n\n return default\n\n def _validate_cached_value(self, value):\n # Maintainability issue: Unclear validation logic\n if isinstance(value, str) and len(value) > 1000:\n return False\n return True\n\n def _transform_value(self, key, value):\n # Code smell: Unnecessary abstraction\n if key in self.config_transformers:\n transformer = self.config_transformers[key]\n return transformer(value)\n return value\n\n def _read_from_file(self, key, default):\n # Maintainability issue: No error handling for file operations\n with open(f\"/etc/app/{key}.conf\") as f:\n return f.read().strip()\n\n def _read_from_database(self, key, default):\n # Performance issue: Database query for every config read\n # No connection pooling or caching\n import sqlite3\n conn = sqlite3.connect(\"config.db\")\n cursor = conn.cursor()\n cursor.execute(\"SELECT value FROM config WHERE key = ?\", (key,))\n result = cursor.fetchone()\n conn.close()\n return result[0] if result else default\n\"\"\"\n\n self.config_file = self.create_additional_test_file(\"config.py\", config_code)\n self.logger.info(f\" βœ… Created configuration file with issues: {self.config_file}\")\n\n def _test_single_review_session(self) -> bool:\n \"\"\"Test a complete code review session with multiple steps\"\"\"\n try:\n self.logger.info(\" 1.1: Testing single code review session\")\n\n # Step 1: Start review\n self.logger.info(\" 1.1.1: Step 1 - Initial review\")\n response1, continuation_id = self.call_mcp_tool(\n \"codereview\",\n {\n \"step\": \"I need to perform a comprehensive code review of the payment processing module. Let me start by examining the code structure and identifying potential issues.\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Initial examination reveals a payment processing class with potential security and performance concerns.\",\n \"files_checked\": [self.payment_file],\n \"relevant_files\": [self.payment_file],\n \"absolute_file_paths\": [self.payment_file], # Required for step 1\n \"review_type\": \"full\",\n \"severity_filter\": \"all\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to get initial review response\")\n return False\n\n # Parse and validate JSON response\n response1_data = self._parse_review_response(response1)\n if not response1_data:\n return False\n\n # Validate step 1 response structure - expect pause_for_code_review for next_step_required=True\n if not self._validate_step_response(response1_data, 1, 4, True, \"pause_for_code_review\"):\n return False\n\n self.logger.info(f\" βœ… Step 1 successful, continuation_id: {continuation_id}\")\n\n # Step 2: Detailed analysis\n self.logger.info(\" 1.1.2: Step 2 - Detailed security analysis\")\n response2, _ = self.call_mcp_tool(\n \"codereview\",\n {\n \"step\": \"Now performing detailed security analysis of the payment processor code to identify vulnerabilities and code quality issues.\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Found multiple security issues: API key stored in plain text, sensitive data logging, insecure HTTP methods, and weak hashing algorithms.\",\n \"files_checked\": [self.payment_file],\n \"relevant_files\": [self.payment_file],\n \"relevant_context\": [\"PaymentProcessor.__init__\", \"PaymentProcessor.process_payment\"],\n \"issues_found\": [\n {\"severity\": \"critical\", \"description\": \"API key stored in plain text in memory\"},\n {\"severity\": \"critical\", \"description\": \"Credit card and CVV logged in plain text\"},\n {\"severity\": \"high\", \"description\": \"Using GET method for sensitive payment data\"},\n {\"severity\": \"medium\", \"description\": \"Weak MD5 hashing algorithm used\"},\n ],\n \"confidence\": \"high\",\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue review to step 2\")\n return False\n\n response2_data = self._parse_review_response(response2)\n if not self._validate_step_response(response2_data, 2, 4, True, \"pause_for_code_review\"):\n return False\n\n # Check review status tracking\n review_status = response2_data.get(\"code_review_status\", {})\n if review_status.get(\"files_checked\", 0) < 1:\n self.logger.error(\"Files checked count not properly tracked\")\n return False\n\n if review_status.get(\"relevant_context\", 0) != 2:\n self.logger.error(\"Relevant context not properly tracked\")\n return False\n\n # Check issues by severity\n issues_by_severity = review_status.get(\"issues_by_severity\", {})\n if issues_by_severity.get(\"critical\", 0) != 2:\n self.logger.error(\"Critical issues not properly tracked\")\n return False\n\n if issues_by_severity.get(\"high\", 0) != 1:\n self.logger.error(\"High severity issues not properly tracked\")\n return False\n\n self.logger.info(\" βœ… Step 2 successful with proper issue tracking\")\n\n # Store continuation_id for next test\n self.review_continuation_id = continuation_id\n return True\n\n except Exception as e:\n self.logger.error(f\"Single review session test failed: {e}\")\n return False\n\n def _test_review_refocus_flow(self) -> bool:\n \"\"\"Test code review flow that revises findings by refocusing\"\"\"\n try:\n self.logger.info(\" 1.2: Testing code review refocus workflow\")\n\n # Start a new review for testing refocus behaviour\n self.logger.info(\" 1.2.1: Start review for refocus test\")\n response1, continuation_id = self.call_mcp_tool(\n \"codereview\",\n {\n \"step\": \"Reviewing configuration management code for best practices\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Initial analysis shows complex configuration class\",\n \"files_checked\": [self.config_file],\n \"relevant_files\": [self.config_file],\n \"absolute_file_paths\": [self.config_file],\n \"review_type\": \"full\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start refocus test review\")\n return False\n\n # Step 2: Initial direction\n self.logger.info(\" 1.2.2: Step 2 - Initial analysis direction\")\n response2, _ = self.call_mcp_tool(\n \"codereview\",\n {\n \"step\": \"Focusing on configuration architecture patterns\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Architecture seems overly complex, but need to look more carefully at security issues\",\n \"files_checked\": [self.config_file],\n \"relevant_files\": [self.config_file],\n \"issues_found\": [\n {\"severity\": \"medium\", \"description\": \"Complex configuration hierarchy\"},\n ],\n \"confidence\": \"low\",\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue to step 2\")\n return False\n\n # Step 3: Shift focus based on new evidence\n self.logger.info(\" 1.2.3: Step 3 - Refocus on security issues\")\n response3, _ = self.call_mcp_tool(\n \"codereview\",\n {\n \"step\": \"Refocusing - need to concentrate on the critical security issues I initially missed. Found hardcoded secrets and credentials in plain text.\",\n \"step_number\": 3,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Found critical security vulnerabilities: hardcoded DATABASE_PASSWORD and SECRET_KEY in plain text\",\n \"files_checked\": [self.config_file],\n \"relevant_files\": [self.config_file],\n \"relevant_context\": [\"ConfigurationManager.__init__\"],\n \"issues_found\": [\n {\"severity\": \"critical\", \"description\": \"Hardcoded database password in source code\"},\n {\"severity\": \"critical\", \"description\": \"Hardcoded secret key in source code\"},\n {\"severity\": \"high\", \"description\": \"Over-engineered configuration system\"},\n ],\n \"confidence\": \"high\",\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response3:\n self.logger.error(\"Failed to refocus\")\n return False\n\n response3_data = self._parse_review_response(response3)\n if not self._validate_step_response(response3_data, 3, 4, True, \"pause_for_code_review\"):\n return False\n\n self.logger.info(\" βœ… Refocus flow working correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Refocus test failed: {e}\")\n return False\n\n def _test_complete_review_with_analysis(self) -> bool:\n \"\"\"Test complete code review ending with expert analysis\"\"\"\n try:\n self.logger.info(\" 1.3: Testing complete review with expert analysis\")\n\n # Use the continuation from first test\n continuation_id = getattr(self, \"review_continuation_id\", None)\n if not continuation_id:\n # Start fresh if no continuation available\n self.logger.info(\" 1.3.0: Starting fresh review\")\n response0, continuation_id = self.call_mcp_tool(\n \"codereview\",\n {\n \"step\": \"Reviewing payment processor for security and quality issues\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"findings\": \"Found multiple security and performance issues\",\n \"files_checked\": [self.payment_file],\n \"relevant_files\": [self.payment_file],\n \"absolute_file_paths\": [self.payment_file],\n \"relevant_context\": [\"PaymentProcessor.process_payment\"],\n },\n )\n if not response0 or not continuation_id:\n self.logger.error(\"Failed to start fresh review\")\n return False\n\n # Final step - trigger expert analysis\n self.logger.info(\" 1.3.1: Final step - complete review\")\n response_final, _ = self.call_mcp_tool(\n \"codereview\",\n {\n \"step\": \"Code review complete. Identified comprehensive security, performance, and maintainability issues throughout the payment processing module.\",\n \"step_number\": 2,\n \"total_steps\": 2,\n \"next_step_required\": False, # Final step - triggers expert analysis\n \"findings\": \"Complete analysis reveals critical security vulnerabilities, performance bottlenecks, over-engineering patterns, and maintainability concerns. All issues documented with severity levels.\",\n \"files_checked\": [self.payment_file],\n \"relevant_files\": [self.payment_file],\n \"relevant_context\": [\n \"PaymentProcessor.process_payment\",\n \"PaymentProcessor._generate_complex_hash\",\n \"PaymentProcessor.get_payment_history\",\n ],\n \"issues_found\": [\n {\"severity\": \"critical\", \"description\": \"API key stored in plain text\"},\n {\"severity\": \"critical\", \"description\": \"Sensitive payment data logged\"},\n {\"severity\": \"high\", \"description\": \"SQL injection vulnerability potential\"},\n {\"severity\": \"medium\", \"description\": \"Over-engineered hash generation\"},\n {\"severity\": \"low\", \"description\": \"Poor error handling patterns\"},\n ],\n \"confidence\": \"high\",\n \"continuation_id\": continuation_id,\n \"model\": \"flash\", # Use flash for expert analysis\n },\n )\n\n if not response_final:\n self.logger.error(\"Failed to complete review\")\n return False\n\n response_final_data = self._parse_review_response(response_final)\n if not response_final_data:\n return False\n\n # Validate final response structure - expect calling_expert_analysis for next_step_required=False\n if response_final_data.get(\"status\") != \"calling_expert_analysis\":\n self.logger.error(\n f\"Expected status 'calling_expert_analysis', got '{response_final_data.get('status')}'\"\n )\n return False\n\n if not response_final_data.get(\"code_review_complete\"):\n self.logger.error(\"Expected code_review_complete=true for final step\")\n return False\n\n # Check for expert analysis\n if \"expert_analysis\" not in response_final_data:\n self.logger.error(\"Missing expert_analysis in final response\")\n return False\n\n expert_analysis = response_final_data.get(\"expert_analysis\", {})\n\n # Check for expected analysis content (checking common patterns)\n analysis_text = json.dumps(expert_analysis, ensure_ascii=False).lower()\n\n # Look for code review identification\n review_indicators = [\"security\", \"vulnerability\", \"performance\", \"critical\", \"api\", \"key\"]\n found_indicators = sum(1 for indicator in review_indicators if indicator in analysis_text)\n\n if found_indicators >= 3:\n self.logger.info(\" βœ… Expert analysis identified the issues correctly\")\n else:\n self.logger.warning(\n f\" ⚠️ Expert analysis may not have fully identified the issues (found {found_indicators}/6 indicators)\"\n )\n\n # Check complete review summary\n if \"complete_code_review\" not in response_final_data:\n self.logger.error(\"Missing complete_code_review in final response\")\n return False\n\n complete_review = response_final_data[\"complete_code_review\"]\n if not complete_review.get(\"relevant_context\"):\n self.logger.error(\"Missing relevant context in complete review\")\n return False\n\n if \"PaymentProcessor.process_payment\" not in complete_review[\"relevant_context\"]:\n self.logger.error(\"Expected method not found in review summary\")\n return False\n\n self.logger.info(\" βœ… Complete review with expert analysis successful\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Complete review test failed: {e}\")\n return False\n\n def _test_certain_confidence(self) -> bool:\n \"\"\"Test certain confidence behavior - should skip expert analysis\"\"\"\n try:\n self.logger.info(\" 1.4: Testing certain confidence behavior\")\n\n # Test certain confidence - should skip expert analysis\n self.logger.info(\" 1.4.1: Certain confidence review\")\n response_certain, _ = self.call_mcp_tool(\n \"codereview\",\n {\n \"step\": \"I have completed a thorough code review with 100% certainty of all issues identified.\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False, # Final step\n \"findings\": \"Complete review identified all critical security issues, performance problems, and code quality concerns. All issues are documented with clear severity levels and specific recommendations.\",\n \"files_checked\": [self.payment_file],\n \"relevant_files\": [self.payment_file],\n \"absolute_file_paths\": [self.payment_file],\n \"relevant_context\": [\"PaymentProcessor.process_payment\"],\n \"issues_found\": [\n {\"severity\": \"critical\", \"description\": \"Hardcoded API key security vulnerability\"},\n {\"severity\": \"high\", \"description\": \"Performance bottleneck in payment history\"},\n ],\n \"review_validation_type\": \"internal\", # This should skip expert analysis\n \"model\": \"flash\",\n },\n )\n\n if not response_certain:\n self.logger.error(\"Failed to test certain confidence\")\n return False\n\n response_certain_data = self._parse_review_response(response_certain)\n if not response_certain_data:\n return False\n\n # Validate certain confidence response - should skip expert analysis\n if response_certain_data.get(\"status\") != \"code_review_complete_ready_for_implementation\":\n self.logger.error(\n f\"Expected status 'code_review_complete_ready_for_implementation', got '{response_certain_data.get('status')}'\"\n )\n return False\n\n if not response_certain_data.get(\"skip_expert_analysis\"):\n self.logger.error(\"Expected skip_expert_analysis=true for certain confidence\")\n return False\n\n expert_analysis = response_certain_data.get(\"expert_analysis\", {})\n if expert_analysis.get(\"status\") not in [\n \"skipped_due_to_certain_review_confidence\",\n \"skipped_due_to_internal_analysis_type\",\n ]:\n self.logger.error(\"Expert analysis should be skipped for certain confidence\")\n return False\n\n self.logger.info(\" βœ… Certain confidence behavior working correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Certain confidence test failed: {e}\")\n return False\n\n def _test_context_aware_file_embedding(self) -> bool:\n \"\"\"Test context-aware file embedding optimization\"\"\"\n try:\n self.logger.info(\" 1.5: Testing context-aware file embedding\")\n\n # Create multiple test files for context testing\n utils_content = \"\"\"#!/usr/bin/env python3\ndef calculate_discount(price, discount_percent):\n \\\"\\\"\\\"Calculate discount amount\\\"\\\"\\\"\n if discount_percent < 0 or discount_percent > 100:\n raise ValueError(\"Invalid discount percentage\")\n\n return price * (discount_percent / 100)\n\ndef format_currency(amount):\n \\\"\\\"\\\"Format amount as currency\\\"\\\"\\\"\n return f\"${amount:.2f}\"\n\"\"\"\n\n validator_content = \"\"\"#!/usr/bin/env python3\nimport re\n\ndef validate_email(email):\n \\\"\\\"\\\"Validate email format\\\"\\\"\\\"\n pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\\\.[a-zA-Z]{2,}$'\n return re.match(pattern, email) is not None\n\ndef validate_credit_card(card_number):\n \\\"\\\"\\\"Basic credit card validation\\\"\\\"\\\"\n # Remove spaces and dashes\n card_number = re.sub(r'[\\\\s-]', '', card_number)\n\n # Check if all digits\n if not card_number.isdigit():\n return False\n\n # Basic length check\n return len(card_number) in [13, 14, 15, 16]\n\"\"\"\n\n # Create test files\n utils_file = self.create_additional_test_file(\"utils.py\", utils_content)\n validator_file = self.create_additional_test_file(\"validator.py\", validator_content)\n\n # Test 1: New conversation, intermediate step - should only reference files\n self.logger.info(\" 1.5.1: New conversation intermediate step (should reference only)\")\n response1, continuation_id = self.call_mcp_tool(\n \"codereview\",\n {\n \"step\": \"Starting comprehensive code review of utility modules\",\n \"step_number\": 1,\n \"total_steps\": 3,\n \"next_step_required\": True, # Intermediate step\n \"findings\": \"Initial analysis of utility and validation functions\",\n \"files_checked\": [utils_file, validator_file],\n \"relevant_files\": [utils_file], # This should be referenced, not embedded\n \"absolute_file_paths\": [utils_file, validator_file], # Required for step 1\n \"relevant_context\": [\"calculate_discount\"],\n \"confidence\": \"low\",\n \"model\": \"flash\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start context-aware file embedding test\")\n return False\n\n response1_data = self._parse_review_response(response1)\n if not response1_data:\n return False\n\n # Check file context - should be reference_only for intermediate step\n file_context = response1_data.get(\"file_context\", {})\n if file_context.get(\"type\") != \"reference_only\":\n self.logger.error(f\"Expected reference_only file context, got: {file_context.get('type')}\")\n return False\n\n if \"Files referenced but not embedded\" not in file_context.get(\"context_optimization\", \"\"):\n self.logger.error(\"Expected context optimization message for reference_only\")\n return False\n\n self.logger.info(\" βœ… Intermediate step correctly uses reference_only file context\")\n\n # Test 2: Final step - should embed files for expert analysis\n self.logger.info(\" 1.5.2: Final step (should embed files)\")\n response3, _ = self.call_mcp_tool(\n \"codereview\",\n {\n \"step\": \"Code review complete - identified all issues and recommendations\",\n \"step_number\": 3,\n \"total_steps\": 3,\n \"next_step_required\": False, # Final step - should embed files\n \"continuation_id\": continuation_id,\n \"findings\": \"Complete review: utility functions have proper error handling, validation functions are robust\",\n \"files_checked\": [utils_file, validator_file],\n \"relevant_files\": [utils_file, validator_file], # Should be fully embedded\n \"relevant_context\": [\"calculate_discount\", \"validate_email\", \"validate_credit_card\"],\n \"issues_found\": [\n {\"severity\": \"low\", \"description\": \"Could add more comprehensive email validation\"},\n {\"severity\": \"medium\", \"description\": \"Credit card validation logic could be more robust\"},\n ],\n \"confidence\": \"medium\",\n \"model\": \"flash\",\n },\n )\n\n if not response3:\n self.logger.error(\"Failed to complete to final step\")\n return False\n\n response3_data = self._parse_review_response(response3)\n if not response3_data:\n return False\n\n # Check file context - should be fully_embedded for final step\n file_context3 = response3_data.get(\"file_context\", {})\n if file_context3.get(\"type\") != \"fully_embedded\":\n self.logger.error(\n f\"Expected fully_embedded file context for final step, got: {file_context3.get('type')}\"\n )\n return False\n\n if \"Full file content embedded for expert analysis\" not in file_context3.get(\"context_optimization\", \"\"):\n self.logger.error(\"Expected expert analysis optimization message for fully_embedded\")\n return False\n\n self.logger.info(\" βœ… Final step correctly uses fully_embedded file context\")\n\n # Verify expert analysis was called for final step\n if response3_data.get(\"status\") != \"calling_expert_analysis\":\n self.logger.error(\"Final step should trigger expert analysis\")\n return False\n\n if \"expert_analysis\" not in response3_data:\n self.logger.error(\"Expert analysis should be present in final step\")\n return False\n\n self.logger.info(\" βœ… Context-aware file embedding test completed successfully\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Context-aware file embedding test failed: {e}\")\n return False\n\n def _test_multi_step_file_context(self) -> bool:\n \"\"\"Test multi-step workflow with proper file context transitions\"\"\"\n try:\n self.logger.info(\" 1.6: Testing multi-step file context optimization\")\n\n # Use existing payment and config files for multi-step test\n files_to_review = [self.payment_file, self.config_file]\n\n # Step 1: Start review (new conversation)\n self.logger.info(\" 1.6.1: Step 1 - Start comprehensive review\")\n response1, continuation_id = self.call_mcp_tool(\n \"codereview\",\n {\n \"step\": \"Starting comprehensive security and quality review of payment system components\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Initial review of payment processor and configuration management modules\",\n \"files_checked\": files_to_review,\n \"relevant_files\": [self.payment_file],\n \"absolute_file_paths\": files_to_review,\n \"relevant_context\": [],\n \"confidence\": \"low\",\n \"review_type\": \"security\",\n \"model\": \"flash\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start multi-step file context test\")\n return False\n\n response1_data = self._parse_review_response(response1)\n\n # Validate step 1 - should use reference_only\n file_context1 = response1_data.get(\"file_context\", {})\n if file_context1.get(\"type\") != \"reference_only\":\n self.logger.error(\"Step 1 should use reference_only file context\")\n return False\n\n self.logger.info(\" βœ… Step 1: reference_only file context\")\n\n # Step 2: Security analysis\n self.logger.info(\" 1.6.2: Step 2 - Security analysis\")\n response2, _ = self.call_mcp_tool(\n \"codereview\",\n {\n \"step\": \"Focusing on critical security vulnerabilities across both modules\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"continuation_id\": continuation_id,\n \"findings\": \"Found critical security issues: hardcoded secrets in config, API key exposure in payment processor\",\n \"files_checked\": files_to_review,\n \"relevant_files\": files_to_review,\n \"relevant_context\": [\"PaymentProcessor.__init__\", \"ConfigurationManager\"],\n \"issues_found\": [\n {\"severity\": \"critical\", \"description\": \"Hardcoded database password\"},\n {\"severity\": \"critical\", \"description\": \"API key stored in plain text\"},\n ],\n \"confidence\": \"medium\",\n \"model\": \"flash\",\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue to step 2\")\n return False\n\n response2_data = self._parse_review_response(response2)\n\n # Validate step 2 - should still use reference_only\n file_context2 = response2_data.get(\"file_context\", {})\n if file_context2.get(\"type\") != \"reference_only\":\n self.logger.error(\"Step 2 should use reference_only file context\")\n return False\n\n self.logger.info(\" βœ… Step 2: reference_only file context\")\n\n # Step 3: Performance and architecture analysis\n self.logger.info(\" 1.6.3: Step 3 - Performance and architecture analysis\")\n response3, _ = self.call_mcp_tool(\n \"codereview\",\n {\n \"step\": \"Analyzing performance bottlenecks and architectural concerns\",\n \"step_number\": 3,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"continuation_id\": continuation_id,\n \"findings\": \"Performance issues: unbounded lists, inefficient algorithms, over-engineered patterns\",\n \"files_checked\": files_to_review,\n \"relevant_files\": files_to_review,\n \"relevant_context\": [\n \"PaymentProcessor.get_payment_history\",\n \"PaymentProcessor._generate_complex_hash\",\n ],\n \"issues_found\": [\n {\"severity\": \"high\", \"description\": \"O(nΒ²) algorithm in payment history\"},\n {\"severity\": \"medium\", \"description\": \"Over-engineered hash generation\"},\n {\"severity\": \"medium\", \"description\": \"Unbounded failed_payments list\"},\n ],\n \"confidence\": \"high\",\n \"model\": \"flash\",\n },\n )\n\n if not response3:\n self.logger.error(\"Failed to continue to step 3\")\n return False\n\n response3_data = self._parse_review_response(response3)\n\n # Validate step 3 - should still use reference_only\n file_context3 = response3_data.get(\"file_context\", {})\n if file_context3.get(\"type\") != \"reference_only\":\n self.logger.error(\"Step 3 should use reference_only file context\")\n return False\n\n self.logger.info(\" βœ… Step 3: reference_only file context\")\n\n # Step 4: Final comprehensive analysis\n self.logger.info(\" 1.6.4: Step 4 - Final comprehensive analysis\")\n response4, _ = self.call_mcp_tool(\n \"codereview\",\n {\n \"step\": \"Code review complete - comprehensive analysis of all security, performance, and quality issues\",\n \"step_number\": 4,\n \"total_steps\": 4,\n \"next_step_required\": False, # Final step - should embed files\n \"continuation_id\": continuation_id,\n \"findings\": \"Complete review: identified critical security vulnerabilities, performance bottlenecks, over-engineering patterns, and maintainability concerns across payment and configuration modules.\",\n \"files_checked\": files_to_review,\n \"relevant_files\": files_to_review,\n \"relevant_context\": [\"PaymentProcessor.process_payment\", \"ConfigurationManager.get_config\"],\n \"issues_found\": [\n {\"severity\": \"critical\", \"description\": \"Multiple hardcoded secrets\"},\n {\"severity\": \"high\", \"description\": \"Performance and security issues in payment processing\"},\n {\"severity\": \"medium\", \"description\": \"Over-engineered architecture patterns\"},\n ],\n \"confidence\": \"high\",\n \"model\": \"flash\",\n },\n )\n\n if not response4:\n self.logger.error(\"Failed to complete to final step\")\n return False\n\n response4_data = self._parse_review_response(response4)\n\n # Validate step 4 - should use fully_embedded for expert analysis\n file_context4 = response4_data.get(\"file_context\", {})\n if file_context4.get(\"type\") != \"fully_embedded\":\n self.logger.error(\"Step 4 (final) should use fully_embedded file context\")\n return False\n\n if \"expert analysis\" not in file_context4.get(\"context_optimization\", \"\").lower():\n self.logger.error(\"Final step should mention expert analysis in context optimization\")\n return False\n\n # Verify expert analysis was triggered\n if response4_data.get(\"status\") != \"calling_expert_analysis\":\n self.logger.error(\"Final step should trigger expert analysis\")\n return False\n\n # Check that expert analysis has content\n expert_analysis = response4_data.get(\"expert_analysis\", {})\n if not expert_analysis:\n self.logger.error(\"Expert analysis should be present in final step\")\n return False\n\n self.logger.info(\" βœ… Step 4: fully_embedded file context with expert analysis\")\n\n # Validate the complete workflow progression\n progression_summary = {\n \"step_1\": \"reference_only (new conversation, intermediate)\",\n \"step_2\": \"reference_only (continuation, intermediate)\",\n \"step_3\": \"reference_only (continuation, intermediate)\",\n \"step_4\": \"fully_embedded (continuation, final)\",\n }\n\n self.logger.info(\" πŸ“‹ File context progression:\")\n for step, context_type in progression_summary.items():\n self.logger.info(f\" {step}: {context_type}\")\n\n self.logger.info(\" βœ… Multi-step file context optimization test completed successfully\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Multi-step file context test failed: {e}\")\n return False\n\n def call_mcp_tool(self, tool_name: str, params: dict) -> tuple[Optional[str], Optional[str]]:\n \"\"\"Call an MCP tool in-process - override for codereview-specific response handling\"\"\"\n # Use in-process implementation to maintain conversation memory\n response_text, _ = self.call_mcp_tool_direct(tool_name, params)\n\n if not response_text:\n return None, None\n\n # Extract continuation_id from codereview response specifically\n continuation_id = self._extract_review_continuation_id(response_text)\n\n return response_text, continuation_id\n\n def _extract_review_continuation_id(self, response_text: str) -> Optional[str]:\n \"\"\"Extract continuation_id from codereview response\"\"\"\n try:\n # Parse the response\n response_data = json.loads(response_text)\n return response_data.get(\"continuation_id\")\n\n except json.JSONDecodeError as e:\n self.logger.debug(f\"Failed to parse response for review continuation_id: {e}\")\n return None\n\n def _parse_review_response(self, response_text: str) -> dict:\n \"\"\"Parse codereview tool JSON response\"\"\"\n try:\n # Parse the response - it should be direct JSON\n return json.loads(response_text)\n\n except json.JSONDecodeError as e:\n self.logger.error(f\"Failed to parse review response as JSON: {e}\")\n self.logger.error(f\"Response text: {response_text[:500]}...\")\n return {}\n\n def _validate_step_response(\n self,\n response_data: dict,\n expected_step: int,\n expected_total: int,\n expected_next_required: bool,\n expected_status: str,\n ) -> bool:\n \"\"\"Validate a codereview step response structure\"\"\"\n try:\n # Check status\n if response_data.get(\"status\") != expected_status:\n self.logger.error(f\"Expected status '{expected_status}', got '{response_data.get('status')}'\")\n return False\n\n # Check step number\n if response_data.get(\"step_number\") != expected_step:\n self.logger.error(f\"Expected step_number {expected_step}, got {response_data.get('step_number')}\")\n return False\n\n # Check total steps\n if response_data.get(\"total_steps\") != expected_total:\n self.logger.error(f\"Expected total_steps {expected_total}, got {response_data.get('total_steps')}\")\n return False\n\n # Check next_step_required\n if response_data.get(\"next_step_required\") != expected_next_required:\n self.logger.error(\n f\"Expected next_step_required {expected_next_required}, got {response_data.get('next_step_required')}\"\n )\n return False\n\n # Check code_review_status exists\n if \"code_review_status\" not in response_data:\n self.logger.error(\"Missing code_review_status in response\")\n return False\n\n # Check next_steps guidance\n if not response_data.get(\"next_steps\"):\n self.logger.error(\"Missing next_steps guidance in response\")\n return False\n\n return True\n\n except Exception as e:\n self.logger.error(f\"Error validating step response: {e}\")\n return False\n" }, { "path": "simulator_tests/test_consensus_conversation.py", "content": "#!/usr/bin/env python3\n\"\"\"\nConsensus Conversation Continuation Test\n\nTests that the consensus tool properly handles conversation continuation\nand builds conversation context correctly when using continuation_id.\n\"\"\"\n\nimport json\n\nfrom .conversation_base_test import ConversationBaseTest\n\n\nclass TestConsensusConversation(ConversationBaseTest):\n \"\"\"Test consensus tool conversation continuation functionality\"\"\"\n\n def call_mcp_tool(self, tool_name: str, params: dict) -> tuple:\n \"\"\"Call an MCP tool in-process\"\"\"\n response_text, continuation_id = self.call_mcp_tool_direct(tool_name, params)\n return response_text, continuation_id\n\n @property\n def test_name(self) -> str:\n return \"consensus_conversation\"\n\n @property\n def test_description(self) -> str:\n return \"Test consensus tool conversation building and continuation\"\n\n def get_server_logs(self):\n \"\"\"Get server logs from local log file\"\"\"\n try:\n log_file_path = \"logs/mcp_server.log\"\n with open(log_file_path) as f:\n lines = f.readlines()\n # Return last 100 lines\n return [line.strip() for line in lines[-100:]]\n except Exception as e:\n self.logger.warning(f\"Exception getting server logs: {e}\")\n return []\n\n def run_test(self) -> bool:\n \"\"\"Test consensus conversation continuation\"\"\"\n try:\n self.logger.info(\"Testing consensus tool conversation continuation\")\n\n # Initialize for in-process tool calling\n self.setUp()\n\n # Setup test files for context\n self.setup_test_files()\n\n # Phase 1: Start conversation with chat tool (which properly creates continuation_id)\n self.logger.info(\"Phase 1: Starting conversation with chat tool\")\n initial_response, continuation_id = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. I'm working on a web application and need advice on authentication. Can you look at this code?\",\n \"absolute_file_paths\": [self.test_files[\"python\"]],\n \"model\": \"flash\",\n },\n )\n\n # Validate initial response\n if not initial_response:\n self.logger.error(\"Failed to get initial chat response\")\n return False\n\n if not continuation_id:\n self.logger.error(\"Failed to get continuation_id from initial chat\")\n return False\n\n self.logger.info(f\"Initial chat response preview: {initial_response[:200]}...\")\n self.logger.info(f\"Got continuation_id: {continuation_id}\")\n\n # Phase 2: Use consensus with continuation_id to test conversation building\n self.logger.info(\"Phase 2: Using consensus with continuation_id to test conversation building\")\n consensus_response, _ = self.call_mcp_tool(\n \"consensus\",\n {\n \"step\": \"Based on our previous discussion about authentication, I need expert consensus: Should we implement OAuth2 or stick with simple session-based auth?\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"findings\": \"Initial analysis needed on OAuth2 vs session-based authentication approaches for our web application\",\n \"models\": [\n {\n \"model\": \"flash\",\n \"stance\": \"for\",\n \"stance_prompt\": \"Focus on OAuth2 benefits: security, scalability, and industry standards.\",\n },\n {\n \"model\": \"flash\",\n \"stance\": \"against\",\n \"stance_prompt\": \"Focus on OAuth2 complexity: implementation challenges and simpler alternatives.\",\n },\n ],\n \"continuation_id\": continuation_id,\n \"model\": \"flash\",\n },\n )\n\n # Validate consensus response\n if not consensus_response:\n self.logger.error(\"Failed to get consensus response with continuation_id\")\n return False\n\n self.logger.info(f\"Consensus response preview: {consensus_response[:300]}...\")\n\n # Log the full response for debugging if it's not JSON\n if not consensus_response.startswith(\"{\"):\n self.logger.error(f\"Consensus response is not JSON. Full response: {consensus_response}\")\n return False\n\n # Parse consensus response\n try:\n consensus_data = json.loads(consensus_response)\n except json.JSONDecodeError:\n self.logger.error(f\"Failed to parse consensus response as JSON. Full response: {consensus_response}\")\n return False\n\n # Check for step 1 status (Claude analysis + first model consultation)\n expected_status = \"analysis_and_first_model_consulted\"\n if consensus_data.get(\"status\") != expected_status:\n self.logger.error(\n f\"Consensus step 1 failed with status: {consensus_data.get('status')}, expected: {expected_status}\"\n )\n if \"error\" in consensus_data:\n self.logger.error(f\"Error: {consensus_data['error']}\")\n return False\n\n # Phase 3: Check server logs for conversation building\n self.logger.info(\"Phase 3: Checking server logs for conversation building\")\n\n # Check for conversation-related log entries\n logs = self.get_server_logs()\n if not logs:\n self.logger.warning(\"Could not retrieve server logs for verification\")\n else:\n # Look for conversation building indicators\n conversation_logs = [\n line\n for line in logs\n if any(\n keyword in line\n for keyword in [\n \"CONVERSATION HISTORY\",\n \"continuation_id\",\n \"build_conversation_history\",\n \"ThreadContext\",\n f\"thread:{continuation_id}\",\n ]\n )\n ]\n\n if conversation_logs:\n self.logger.info(f\"Found {len(conversation_logs)} conversation-related log entries\")\n # Show a few examples (truncated)\n for i, log in enumerate(conversation_logs[:3]):\n self.logger.info(f\" Conversation log {i+1}: {log[:100]}...\")\n else:\n self.logger.warning(\n \"No conversation-related logs found (may indicate conversation not properly built)\"\n )\n\n # Check for any ERROR entries related to consensus\n error_logs = [\n line\n for line in logs\n if \"ERROR\" in line\n and any(keyword in line for keyword in [\"consensus\", \"conversation\", continuation_id])\n ]\n\n if error_logs:\n self.logger.error(f\"Found {len(error_logs)} error logs related to consensus conversation:\")\n for error in error_logs:\n self.logger.error(f\" ERROR: {error}\")\n return False\n\n # Phase 4: Verify response structure\n self.logger.info(\"Phase 4: Verifying consensus response structure\")\n\n # Check that we have model response from step 1\n model_response = consensus_data.get(\"model_response\")\n if not model_response:\n self.logger.error(\"Consensus step 1 response missing model_response\")\n return False\n\n # Check that model response has expected structure\n if not model_response.get(\"model\") or not model_response.get(\"verdict\"):\n self.logger.error(\"Model response missing required fields (model or verdict)\")\n return False\n\n # Check step information\n if consensus_data.get(\"step_number\") != 1:\n self.logger.error(f\"Expected step_number 1, got: {consensus_data.get('step_number')}\")\n return False\n\n if not consensus_data.get(\"next_step_required\"):\n self.logger.error(\"Expected next_step_required=True for step 1\")\n return False\n\n self.logger.info(f\"Consensus step 1 consulted model: {model_response.get('model')}\")\n self.logger.info(f\"Model stance: {model_response.get('stance', 'neutral')}\")\n self.logger.info(f\"Response status: {model_response.get('status', 'unknown')}\")\n\n # Phase 5: Cross-tool continuation test\n self.logger.info(\"Phase 5: Testing cross-tool continuation from consensus\")\n\n # Try to continue the conversation with a different tool\n chat_response, _ = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Based on our consensus discussion about authentication, can you summarize the key points?\",\n \"continuation_id\": continuation_id,\n \"model\": \"flash\",\n },\n )\n\n if not chat_response:\n self.logger.warning(\"Cross-tool continuation from consensus failed\")\n # Don't fail the test for this - it's a bonus check\n else:\n self.logger.info(\"βœ“ Cross-tool continuation from consensus working\")\n self.logger.info(f\"Chat continuation preview: {chat_response[:200]}...\")\n\n self.logger.info(\"βœ“ Consensus conversation continuation test completed successfully\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Consensus conversation test failed with exception: {str(e)}\")\n import traceback\n\n self.logger.error(f\"Traceback: {traceback.format_exc()}\")\n return False\n finally:\n self.cleanup_test_files()\n" }, { "path": "simulator_tests/test_consensus_three_models.py", "content": "\"\"\"\nTest consensus tool with three models demonstrating sequential processing\n\"\"\"\n\nimport json\n\nfrom .base_test import BaseSimulatorTest\n\n\nclass TestConsensusThreeModels(BaseSimulatorTest):\n \"\"\"Test consensus tool functionality with three models (testing sequential processing)\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"consensus_three_models\"\n\n @property\n def test_description(self) -> str:\n return \"Test consensus tool with three models using flash:against, flash:for, local-llama:neutral\"\n\n def run_test(self) -> bool:\n \"\"\"Run three-model consensus test\"\"\"\n try:\n self.logger.info(\"Testing consensus tool with three models: flash:against, flash:for, local-llama:neutral\")\n\n # Send request with three objects using new workflow parameters\n response, continuation_id = self.call_mcp_tool(\n \"consensus\",\n {\n \"step\": \"Is a sync manager class a good idea for my CoolTodos app?\",\n \"step_number\": 1,\n \"total_steps\": 3, # 3 models = 3 steps\n \"next_step_required\": True,\n \"findings\": \"Initial analysis needed on sync manager class architecture decision for CoolTodos app\",\n \"models\": [\n {\n \"model\": \"flash\",\n \"stance\": \"against\",\n \"stance_prompt\": \"You are a software architecture critic. Focus on the potential downsides of adding a sync manager class: complexity overhead, maintenance burden, potential for over-engineering, and whether simpler alternatives exist. Consider if this adds unnecessary abstraction layers.\",\n },\n {\n \"model\": \"flash\",\n \"stance\": \"for\",\n \"stance_prompt\": \"You are a software architecture advocate. Focus on the benefits of a sync manager class: separation of concerns, testability, maintainability, and how it can improve the overall architecture. Consider scalability and code organization advantages.\",\n },\n {\n \"model\": \"local-llama\",\n \"stance\": \"neutral\",\n \"stance_prompt\": \"You are a pragmatic software engineer. Provide a balanced analysis considering both the benefits and drawbacks. Focus on the specific context of a CoolTodos app and what factors would determine if this is the right choice.\",\n },\n ],\n \"model\": \"flash\", # Default model for Claude's execution\n },\n )\n\n # Validate response\n if not response:\n self.logger.error(\"Failed to get response from three-model consensus tool\")\n return False\n\n self.logger.info(f\"Three-model consensus response preview: {response[:500]}...\")\n\n # Parse the JSON response\n try:\n consensus_data = json.loads(response)\n except json.JSONDecodeError:\n self.logger.error(f\"Failed to parse three-model consensus response as JSON: {response}\")\n return False\n\n # Validate consensus structure\n if \"status\" not in consensus_data:\n self.logger.error(\"Missing 'status' field in three-model consensus response\")\n return False\n\n # Check for step 1 status (Claude analysis + first model consultation)\n expected_status = \"analysis_and_first_model_consulted\"\n if consensus_data[\"status\"] != expected_status:\n self.logger.error(\n f\"Three-model consensus step 1 failed with status: {consensus_data['status']}, expected: {expected_status}\"\n )\n\n # Log additional error details for debugging\n if \"error\" in consensus_data:\n self.logger.error(f\"Error message: {consensus_data['error']}\")\n if \"models_errored\" in consensus_data:\n self.logger.error(f\"Models that errored: {consensus_data['models_errored']}\")\n if \"models_skipped\" in consensus_data:\n self.logger.error(f\"Models skipped: {consensus_data['models_skipped']}\")\n if \"next_steps\" in consensus_data:\n self.logger.error(f\"Suggested next steps: {consensus_data['next_steps']}\")\n\n return False\n\n # Check that we have model response from step 1\n model_response = consensus_data.get(\"model_response\")\n if not model_response:\n self.logger.error(\"Three-model consensus step 1 response missing model_response\")\n return False\n\n # Check that model response has expected structure\n if not model_response.get(\"model\") or not model_response.get(\"verdict\"):\n self.logger.error(\"Model response missing required fields (model or verdict)\")\n return False\n\n # Check step information\n if consensus_data.get(\"step_number\") != 1:\n self.logger.error(f\"Expected step_number 1, got: {consensus_data.get('step_number')}\")\n return False\n\n if not consensus_data.get(\"next_step_required\"):\n self.logger.error(\"Expected next_step_required=True for step 1\")\n return False\n\n self.logger.info(f\"Consensus step 1 consulted model: {model_response.get('model')}\")\n self.logger.info(f\"Model stance: {model_response.get('stance', 'neutral')}\")\n self.logger.info(f\"Response status: {model_response.get('status', 'unknown')}\")\n\n # Check metadata contains model name\n metadata = consensus_data.get(\"metadata\", {})\n if not metadata.get(\"model_name\"):\n self.logger.error(\"Missing model_name in metadata\")\n return False\n\n self.logger.info(f\"Model name in metadata: {metadata.get('model_name')}\")\n\n # Verify we have analysis from Claude\n agent_analysis = consensus_data.get(\"agent_analysis\")\n if not agent_analysis:\n self.logger.error(\"Missing Claude's analysis in step 1\")\n return False\n\n analysis_text = agent_analysis.get(\"initial_analysis\", \"\")\n self.logger.info(f\"Claude analysis length: {len(analysis_text)} characters\")\n\n self.logger.info(\"βœ“ Three-model consensus tool test completed successfully\")\n self.logger.info(f\"βœ“ Step 1 completed with model: {model_response.get('model')}\")\n self.logger.info(f\"βœ“ Analysis provided: {len(analysis_text)} characters\")\n self.logger.info(f\"βœ“ Model metadata properly included: {metadata.get('model_name')}\")\n self.logger.info(\"βœ“ Ready for step 2 continuation\")\n\n return True\n\n except Exception as e:\n self.logger.error(f\"Three-model consensus test failed with exception: {str(e)}\")\n return False\n" }, { "path": "simulator_tests/test_consensus_workflow_accurate.py", "content": "\"\"\"\nAccurate Consensus Workflow Test\n\nThis test validates the complete consensus workflow step-by-step to ensure:\n1. Step 1: Claude provides its own analysis\n2. Step 2: Tool consults first model and returns response to Claude\n3. Step 3: Tool consults second model and returns response to Claude\n4. Step 4: Claude synthesizes all perspectives\n\nThis replaces the old faulty test that used non-workflow parameters.\n\"\"\"\n\nimport json\n\nfrom .conversation_base_test import ConversationBaseTest\n\n\nclass TestConsensusWorkflowAccurate(ConversationBaseTest):\n \"\"\"Test complete consensus workflow with accurate step-by-step behavior\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"consensus_workflow_accurate\"\n\n @property\n def test_description(self) -> str:\n return \"Test NEW efficient consensus workflow: 2 models = 2 steps (Claude+model1, model2+synthesis)\"\n\n def run_test(self) -> bool:\n \"\"\"Run complete consensus workflow test\"\"\"\n # Set up the test environment\n self.setUp()\n\n try:\n self.logger.info(\"Testing complete consensus workflow step-by-step\")\n self.logger.info(\"Expected NEW flow: Step1(Claude+Model1) -> Step2(Model2+Synthesis)\")\n\n # ============================================================================\n # STEP 1: Claude analysis + first model consultation\n # ============================================================================\n self.logger.info(\"=== STEP 1: Claude analysis + flash:for consultation ===\")\n\n step1_response, continuation_id = self.call_mcp_tool_direct(\n \"consensus\",\n {\n \"step\": \"Should we add a new AI-powered search feature to our application? Please analyze the technical feasibility, user value, and implementation complexity.\",\n \"step_number\": 1,\n \"total_steps\": 2, # 2 models (each step includes consultation + analysis)\n \"next_step_required\": True,\n \"findings\": \"Initial assessment of AI search feature proposal considering user needs, technical constraints, and business value.\",\n \"models\": [\n {\n \"model\": \"flash\",\n \"stance\": \"for\",\n \"stance_prompt\": \"Focus on innovation benefits and competitive advantages.\",\n },\n {\n \"model\": \"flash\",\n \"stance\": \"against\",\n \"stance_prompt\": \"Focus on implementation complexity and resource requirements.\",\n },\n ],\n \"model\": \"flash\", # Claude's execution model\n },\n )\n\n if not step1_response:\n self.logger.error(\"Step 1 failed - no response\")\n return False\n\n step1_data = json.loads(step1_response)\n self.logger.info(f\"Step 1 status: {step1_data.get('status')}\")\n\n # Validate step 1 response (should include Claude's analysis + first model consultation)\n if step1_data.get(\"status\") != \"analysis_and_first_model_consulted\":\n self.logger.error(\n f\"Expected status 'analysis_and_first_model_consulted', got: {step1_data.get('status')}\"\n )\n return False\n\n if step1_data.get(\"step_number\") != 1:\n self.logger.error(f\"Expected step_number 1, got: {step1_data.get('step_number')}\")\n return False\n\n if not step1_data.get(\"next_step_required\"):\n self.logger.error(\"Expected next_step_required=True for step 1\")\n return False\n\n # Verify Claude's analysis is included\n if \"agent_analysis\" not in step1_data:\n self.logger.error(\"Expected agent_analysis in step 1 response\")\n return False\n\n # Verify first model response is included\n if \"model_response\" not in step1_data:\n self.logger.error(\"Expected model_response in step 1 response\")\n return False\n\n model1_response = step1_data[\"model_response\"]\n if model1_response.get(\"model\") != \"flash\" or model1_response.get(\"stance\") != \"for\":\n self.logger.error(\n f\"Expected flash:for model response in step 1, got: {model1_response.get('model')}:{model1_response.get('stance')}\"\n )\n return False\n\n self.logger.info(\"βœ“ Step 1 completed - Claude analysis + first model (flash:for) consulted\")\n\n # ============================================================================\n # STEP 2: Final step - second model consultation + synthesis\n # ============================================================================\n self.logger.info(\"=== STEP 2: Final step - second model (flash:against) + synthesis ===\")\n\n step2_response, _ = self.call_mcp_tool_direct(\n \"consensus\",\n {\n \"step\": \"I need to review the second model's perspective and provide final synthesis.\",\n \"step_number\": 2,\n \"total_steps\": 2,\n \"next_step_required\": False, # Final step\n \"findings\": \"Analyzed first model's 'for' perspective. Now ready for second model's 'against' stance and final synthesis.\",\n \"continuation_id\": continuation_id,\n \"model\": \"flash\",\n },\n )\n\n if not step2_response:\n self.logger.error(\"Step 2 failed - no response\")\n return False\n\n self.logger.info(f\"Step 2 raw response: {step2_response[:500]}...\")\n step2_data = json.loads(step2_response)\n self.logger.info(f\"Step 2 status: {step2_data.get('status')}\")\n\n # Validate step 2 - should show consensus completion\n if step2_data.get(\"status\") != \"consensus_workflow_complete\":\n self.logger.error(f\"Expected status 'consensus_workflow_complete', got: {step2_data.get('status')}\")\n return False\n\n if step2_data.get(\"model_consulted\") != \"flash\":\n self.logger.error(f\"Expected model_consulted 'flash', got: {step2_data.get('model_consulted')}\")\n return False\n\n if step2_data.get(\"model_stance\") != \"against\":\n self.logger.error(f\"Expected model_stance 'against', got: {step2_data.get('model_stance')}\")\n return False\n\n # Verify model response is included\n if \"model_response\" not in step2_data:\n self.logger.error(\"Expected model_response in step 2\")\n return False\n\n model2_response = step2_data[\"model_response\"]\n if model2_response.get(\"model\") != \"flash\":\n self.logger.error(f\"Expected model_response.model 'flash', got: {model2_response.get('model')}\")\n return False\n\n # Verify consensus completion data\n if not step2_data.get(\"consensus_complete\"):\n self.logger.error(\"Expected consensus_complete=True in final step\")\n return False\n\n if \"complete_consensus\" not in step2_data:\n self.logger.error(\"Expected complete_consensus data in final step\")\n return False\n\n self.logger.info(\"βœ“ Step 2 completed - Second model (flash:against) consulted and consensus complete\")\n self.logger.info(f\"Model 2 verdict preview: {model2_response.get('verdict', 'No verdict')[:100]}...\")\n\n # Validate final consensus completion data\n complete_consensus = step2_data[\"complete_consensus\"]\n if complete_consensus.get(\"total_responses\") != 2:\n self.logger.error(f\"Expected 2 model responses, got: {complete_consensus.get('total_responses')}\")\n return False\n\n models_consulted = complete_consensus.get(\"models_consulted\", [])\n expected_models = [\"flash:for\", \"flash:against\"]\n if models_consulted != expected_models:\n self.logger.error(f\"Expected models {expected_models}, got: {models_consulted}\")\n return False\n\n # ============================================================================\n # VALIDATION: Check accumulated responses are available\n # ============================================================================\n self.logger.info(\"=== VALIDATION: Checking accumulated responses ===\")\n\n if \"accumulated_responses\" not in step2_data:\n self.logger.error(\"Expected accumulated_responses in final step\")\n return False\n\n accumulated = step2_data[\"accumulated_responses\"]\n if len(accumulated) != 2:\n self.logger.error(f\"Expected 2 accumulated responses, got: {len(accumulated)}\")\n return False\n\n # Verify first response (flash:for)\n response1 = accumulated[0]\n if response1.get(\"model\") != \"flash\" or response1.get(\"stance\") != \"for\":\n self.logger.error(f\"First response incorrect: {response1}\")\n return False\n\n # Verify second response (flash:against)\n response2 = accumulated[1]\n if response2.get(\"model\") != \"flash\" or response2.get(\"stance\") != \"against\":\n self.logger.error(f\"Second response incorrect: {response2}\")\n return False\n\n self.logger.info(\"βœ“ All accumulated responses validated\")\n\n # ============================================================================\n # SUCCESS\n # ============================================================================\n self.logger.info(\"πŸŽ‰ CONSENSUS WORKFLOW TEST PASSED\")\n self.logger.info(\"βœ“ Step 1: Claude analysis + first model (flash:for) consulted\")\n self.logger.info(\"βœ“ Step 2: Second model (flash:against) consulted + synthesis completed\")\n self.logger.info(\"βœ“ All model responses accumulated correctly\")\n self.logger.info(\"βœ“ New efficient workflow: 2 models = 2 steps (not 4)\")\n self.logger.info(\"βœ“ Workflow progression validated at each step\")\n\n return True\n\n except Exception as e:\n self.logger.error(f\"Consensus workflow test failed with exception: {str(e)}\")\n import traceback\n\n self.logger.error(f\"Traceback: {traceback.format_exc()}\")\n return False\n" }, { "path": "simulator_tests/test_content_validation.py", "content": "#!/usr/bin/env python3\n\"\"\"\nContent Validation Test\n\nTests that tools don't duplicate file content in their responses.\nThis test is specifically designed to catch content duplication bugs.\n\"\"\"\n\nimport os\n\nfrom .base_test import BaseSimulatorTest\n\n\nclass ContentValidationTest(BaseSimulatorTest):\n \"\"\"Test that tools don't duplicate file content in their responses\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"content_validation\"\n\n @property\n def test_description(self) -> str:\n return \"Content validation and duplicate detection\"\n\n def run_test(self) -> bool:\n \"\"\"Test that file processing system properly handles file deduplication\"\"\"\n try:\n self.logger.info(\"πŸ“„ Test: Content validation and file processing deduplication\")\n\n # Setup test files first\n self.setup_test_files()\n\n # Create a test file for validation\n validation_content = '''\"\"\"\nConfiguration file for content validation testing\n\"\"\"\n\n# Configuration constants\nMAX_CONTENT_TOKENS = 800_000\nTEMPERATURE_ANALYTICAL = 0.2\nUNIQUE_VALIDATION_MARKER = \"CONTENT_VALIDATION_TEST_12345\"\n\n# Database settings\nDATABASE_CONFIG = {\n \"host\": \"localhost\",\n \"port\": 5432,\n \"name\": \"validation_test_db\"\n}\n'''\n\n validation_file = os.path.join(self.test_dir, \"validation_config.py\")\n with open(validation_file, \"w\") as f:\n f.write(validation_content)\n\n # Ensure absolute path for MCP server compatibility\n validation_file = os.path.abspath(validation_file)\n\n # Get timestamp for log filtering\n import datetime\n\n start_time = datetime.datetime.now().strftime(\"%Y-%m-%dT%H:%M:%S\")\n\n # Test 1: Initial tool call with validation file\n self.logger.info(\" 1: Testing initial tool call with file\")\n\n # Call chat tool with the validation file\n response1, thread_id = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Analyze this configuration file briefly\",\n \"absolute_file_paths\": [validation_file],\n \"model\": \"flash\",\n },\n )\n\n if not response1:\n self.logger.error(\" ❌ Initial tool call failed\")\n return False\n\n self.logger.info(\" βœ… Initial tool call completed\")\n\n # Test 2: Continuation with same file (should be deduplicated)\n self.logger.info(\" 2: Testing continuation with same file\")\n\n if thread_id:\n response2, _ = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Continue analyzing this configuration file\",\n \"absolute_file_paths\": [validation_file], # Same file should be deduplicated\n \"continuation_id\": thread_id,\n \"model\": \"flash\",\n },\n )\n\n if response2:\n self.logger.info(\" βœ… Continuation with same file completed\")\n else:\n self.logger.warning(\" ⚠️ Continuation failed\")\n\n # Test 3: Different tool with same file (new conversation)\n self.logger.info(\" 3: Testing different tool with same file\")\n\n response3, _ = self.call_mcp_tool(\n \"codereview\",\n {\n \"step\": \"Review this configuration file for quality and potential issues\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Starting code review of configuration file\",\n \"relevant_files\": [validation_file],\n \"model\": \"flash\",\n },\n )\n\n if response3:\n self.logger.info(\" βœ… Different tool with same file completed\")\n else:\n self.logger.warning(\" ⚠️ Different tool failed\")\n\n # Validate file processing behavior from server logs\n self.logger.info(\" 4: Validating file processing logs\")\n logs = self.get_server_logs_since(start_time)\n\n # Check for proper file embedding logs\n embedding_logs = [\n line\n for line in logs.split(\"\\n\")\n if \"[FILE_PROCESSING]\" in line or \"embedding\" in line.lower() or \"[FILES]\" in line\n ]\n\n # Check for deduplication evidence\n deduplication_logs = [\n line\n for line in logs.split(\"\\n\")\n if (\"skipping\" in line.lower() and \"already in conversation\" in line.lower())\n or \"No new files to embed\" in line\n ]\n\n # Check for file processing patterns\n new_file_logs = [\n line\n for line in logs.split(\"\\n\")\n if \"will embed new files\" in line or \"New conversation\" in line or \"[FILE_PROCESSING]\" in line\n ]\n\n # Validation criteria\n validation_file_mentioned = any(\"validation_config.py\" in line for line in logs.split(\"\\n\"))\n embedding_found = len(embedding_logs) > 0\n (len(deduplication_logs) > 0 or len(new_file_logs) >= 2) # Should see new conversation patterns\n\n self.logger.info(f\" Embedding logs found: {len(embedding_logs)}\")\n self.logger.info(f\" Deduplication evidence: {len(deduplication_logs)}\")\n self.logger.info(f\" New conversation patterns: {len(new_file_logs)}\")\n self.logger.info(f\" Validation file mentioned: {validation_file_mentioned}\")\n\n # Log sample evidence for debugging\n if self.verbose and embedding_logs:\n self.logger.debug(\" πŸ“‹ Sample embedding logs:\")\n for log in embedding_logs[:5]:\n self.logger.debug(f\" {log}\")\n\n # Success criteria\n success_criteria = [\n (\"Embedding logs found\", embedding_found),\n (\"File processing evidence\", validation_file_mentioned),\n (\"Multiple tool calls\", len(new_file_logs) >= 2),\n ]\n\n passed_criteria = sum(1 for _, passed in success_criteria if passed)\n self.logger.info(f\" Success criteria met: {passed_criteria}/{len(success_criteria)}\")\n\n # Cleanup\n os.remove(validation_file)\n\n if passed_criteria >= 2: # At least 2 out of 3 criteria\n self.logger.info(\" βœ… File processing validation passed\")\n return True\n else:\n self.logger.error(\" ❌ File processing validation failed\")\n return False\n\n except Exception as e:\n self.logger.error(f\"Content validation test failed: {e}\")\n return False\n finally:\n self.cleanup_test_files()\n" }, { "path": "simulator_tests/test_conversation_chain_validation.py", "content": "#!/usr/bin/env python3\n\"\"\"\nConversation Chain and Threading Validation Test\n\nThis test validates that:\n1. Multiple tool invocations create proper parent->parent->parent chains\n2. New conversations can be started independently\n3. Original conversation chains can be resumed from any point\n4. History traversal works correctly for all scenarios\n5. Thread relationships are properly maintained in Redis\n\nTest Flow:\nChain A: chat -> analyze -> debug (3 linked threads)\nChain B: chat -> analyze (2 linked threads, independent)\nChain A Branch: debug (continue from original chat, creating branch)\n\nThis validates the conversation threading system's ability to:\n- Build linear chains\n- Create independent conversation threads\n- Branch from earlier points in existing chains\n- Properly traverse parent relationships for history reconstruction\n\"\"\"\n\n\nfrom .conversation_base_test import ConversationBaseTest\n\n\nclass ConversationChainValidationTest(ConversationBaseTest):\n \"\"\"Test conversation chain and threading functionality\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"conversation_chain_validation\"\n\n @property\n def test_description(self) -> str:\n return \"Conversation chain and threading validation\"\n\n def run_test(self) -> bool:\n \"\"\"Test conversation chain and threading functionality\"\"\"\n # Set up the test environment\n self.setUp()\n\n try:\n self.logger.info(\"Test: Conversation chain and threading validation\")\n\n # Create test file for consistent context\n test_file_content = \"\"\"def example_function():\n '''Simple test function for conversation continuity testing'''\n return \"Hello from conversation chain test\"\n\ndef buggy_function(x, y):\n '''Function with a bug - incorrect operator'''\n return x - y # BUG: Should be x + y for addition\n\nclass TestClass:\n def method(self):\n return \"Method in test class\"\n\"\"\"\n test_file_path = self.create_additional_test_file(\"chain_test.py\", test_file_content)\n\n # Track all continuation IDs and their relationships\n conversation_chains = {}\n\n # === CHAIN A: Build linear conversation chain ===\n self.logger.info(\" Chain A: Building linear conversation chain\")\n\n # Step A1: Start with chat tool (creates thread_id_1)\n self.logger.info(\" Step A1: Chat tool - start new conversation\")\n\n response_a1, continuation_id_a1 = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Analyze this test file and explain what it does.\",\n \"absolute_file_paths\": [test_file_path],\n \"model\": \"flash\",\n \"temperature\": 0.7,\n },\n )\n\n if not response_a1 or not continuation_id_a1:\n self.logger.error(\" ❌ Step A1 failed - no response or continuation ID\")\n return False\n\n self.logger.info(f\" βœ… Step A1 completed - thread_id: {continuation_id_a1[:8]}...\")\n conversation_chains[\"A1\"] = continuation_id_a1\n\n # Step A2: Continue with analyze tool (creates thread_id_2 with parent=thread_id_1)\n self.logger.info(\" Step A2: Analyze tool - continue Chain A\")\n\n response_a2, continuation_id_a2 = self.call_mcp_tool(\n \"analyze\",\n {\n \"step\": \"Now analyze the code quality and suggest improvements.\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": False,\n \"findings\": \"Continuing analysis from previous chat conversation to analyze code quality.\",\n \"relevant_files\": [test_file_path],\n \"continuation_id\": continuation_id_a1,\n \"model\": \"flash\",\n },\n )\n\n if not response_a2 or not continuation_id_a2:\n self.logger.error(\" ❌ Step A2 failed - no response or continuation ID\")\n return False\n\n self.logger.info(f\" βœ… Step A2 completed - thread_id: {continuation_id_a2[:8]}...\")\n conversation_chains[\"A2\"] = continuation_id_a2\n\n # Step A3: Continue with chat tool (creates thread_id_3 with parent=thread_id_2)\n self.logger.info(\" Step A3: Chat tool - continue Chain A\")\n\n response_a3, continuation_id_a3 = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Thank you for the analysis. Can you summarize the key points?\",\n \"continuation_id\": continuation_id_a2,\n \"model\": \"flash\",\n \"temperature\": 0.7,\n },\n )\n\n if not response_a3 or not continuation_id_a3:\n self.logger.error(\" ❌ Step A3 failed - no response or continuation ID\")\n return False\n\n self.logger.info(f\" βœ… Step A3 completed - thread_id: {continuation_id_a3[:8]}...\")\n conversation_chains[\"A3\"] = continuation_id_a3\n\n # === CHAIN B: Start independent conversation ===\n self.logger.info(\" Chain B: Starting independent conversation\")\n\n # Step B1: Start new chat conversation (creates thread_id_4, no parent)\n self.logger.info(\" Step B1: Chat tool - start NEW independent conversation\")\n\n response_b1, continuation_id_b1 = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"This is a completely new conversation. Please greet me.\",\n \"model\": \"flash\",\n \"temperature\": 0.7,\n },\n )\n\n if not response_b1 or not continuation_id_b1:\n self.logger.error(\" ❌ Step B1 failed - no response or continuation ID\")\n return False\n\n self.logger.info(f\" βœ… Step B1 completed - thread_id: {continuation_id_b1[:8]}...\")\n conversation_chains[\"B1\"] = continuation_id_b1\n\n # Step B2: Continue the new conversation (creates thread_id_5 with parent=thread_id_4)\n self.logger.info(\" Step B2: Analyze tool - continue Chain B\")\n\n response_b2, continuation_id_b2 = self.call_mcp_tool(\n \"analyze\",\n {\n \"step\": \"Analyze the previous greeting and suggest improvements.\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Analyzing the greeting from previous conversation and suggesting improvements.\",\n \"relevant_files\": [test_file_path],\n \"continuation_id\": continuation_id_b1,\n \"model\": \"flash\",\n },\n )\n\n if not response_b2 or not continuation_id_b2:\n self.logger.error(\" ❌ Step B2 failed - no response or continuation ID\")\n return False\n\n self.logger.info(f\" βœ… Step B2 completed - thread_id: {continuation_id_b2[:8]}...\")\n conversation_chains[\"B2\"] = continuation_id_b2\n\n # === CHAIN A BRANCH: Go back to original conversation ===\n self.logger.info(\" Chain A Branch: Resume original conversation from A1\")\n\n # Step A1-Branch: Use original continuation_id_a1 to branch (creates thread_id_6 with parent=thread_id_1)\n self.logger.info(\" Step A1-Branch: Chat tool - branch from original Chain A\")\n\n response_a1_branch, continuation_id_a1_branch = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Going back to our original discussion, I have another question about the code structure.\",\n \"continuation_id\": continuation_id_a1, # Go back to original!\n \"model\": \"flash\",\n \"temperature\": 0.7,\n },\n )\n\n if not response_a1_branch or not continuation_id_a1_branch:\n self.logger.error(\" ❌ Step A1-Branch failed - no response or continuation ID\")\n return False\n\n self.logger.info(f\" βœ… Step A1-Branch completed - thread_id: {continuation_id_a1_branch[:8]}...\")\n conversation_chains[\"A1_Branch\"] = continuation_id_a1_branch\n\n # === ANALYSIS: Validate thread relationships and history traversal ===\n self.logger.info(\" Analyzing conversation chain structure...\")\n\n # Get logs and extract thread relationships\n logs = self.get_recent_server_logs()\n thread_creation_logs = self.extract_thread_creation_logs(logs)\n history_traversal_logs = self.extract_history_traversal_logs(logs)\n\n self.logger.info(f\" Found {len(thread_creation_logs)} thread creation logs\")\n self.logger.info(f\" Found {len(history_traversal_logs)} history traversal logs\")\n\n # Debug: Show what we found\n if self.verbose:\n self.logger.debug(\" Thread creation logs found:\")\n for log in thread_creation_logs:\n self.logger.debug(\n f\" {log['thread_id'][:8]}... parent: {log['parent_id'][:8] if log['parent_id'] else 'None'}...\"\n )\n self.logger.debug(\" History traversal logs found:\")\n for log in history_traversal_logs:\n self.logger.debug(f\" {log['thread_id'][:8]}... chain length: {log['chain_length']}\")\n\n # Build expected thread relationships\n expected_relationships = []\n\n # Note: A1 and B1 won't appear in thread creation logs because they're new conversations (no parent)\n # Only continuation threads (A2, A3, B2, A1-Branch) will appear in creation logs\n\n # Find logs for each continuation thread\n a2_log = next((log for log in thread_creation_logs if log[\"thread_id\"] == continuation_id_a2), None)\n a3_log = next((log for log in thread_creation_logs if log[\"thread_id\"] == continuation_id_a3), None)\n b2_log = next((log for log in thread_creation_logs if log[\"thread_id\"] == continuation_id_b2), None)\n a1_branch_log = next(\n (log for log in thread_creation_logs if log[\"thread_id\"] == continuation_id_a1_branch), None\n )\n\n # A2 should have A1 as parent\n if a2_log:\n expected_relationships.append((\"A2 has A1 as parent\", a2_log[\"parent_id\"] == continuation_id_a1))\n\n # A3 should have A2 as parent\n if a3_log:\n expected_relationships.append((\"A3 has A2 as parent\", a3_log[\"parent_id\"] == continuation_id_a2))\n\n # B2 should have B1 as parent (independent chain)\n if b2_log:\n expected_relationships.append((\"B2 has B1 as parent\", b2_log[\"parent_id\"] == continuation_id_b1))\n\n # A1-Branch should have A1 as parent (branching)\n if a1_branch_log:\n expected_relationships.append(\n (\"A1-Branch has A1 as parent\", a1_branch_log[\"parent_id\"] == continuation_id_a1)\n )\n\n # Validate history traversal\n traversal_validations = []\n\n # History traversal logs are only generated when conversation history is built from scratch\n # (not when history is already embedded in the prompt by server.py)\n # So we should expect at least 1 traversal log, but not necessarily for every continuation\n\n if len(history_traversal_logs) > 0:\n # Validate that any traversal logs we find have reasonable chain lengths\n for log in history_traversal_logs:\n thread_id = log[\"thread_id\"]\n chain_length = log[\"chain_length\"]\n\n # Chain length should be at least 2 for any continuation thread\n # (original thread + continuation thread)\n is_valid_length = chain_length >= 2\n\n # Try to identify which thread this is for better validation\n thread_description = f\"Thread {thread_id[:8]}\"\n if thread_id == continuation_id_a1:\n thread_description = \"A1 (original thread)\"\n is_valid_length = chain_length == 1\n elif thread_id == continuation_id_a2:\n thread_description = \"A2 (2-thread chain)\"\n is_valid_length = chain_length == 2\n elif thread_id == continuation_id_a3:\n thread_description = \"A3 (3-thread chain)\"\n is_valid_length = chain_length == 3\n elif thread_id == continuation_id_b1:\n thread_description = \"B1 (original thread)\"\n is_valid_length = chain_length == 1\n elif thread_id == continuation_id_b2:\n thread_description = \"B2 (2-thread chain)\"\n is_valid_length = chain_length == 2\n elif thread_id == continuation_id_a1_branch:\n thread_description = \"A1-Branch (2-thread chain)\"\n is_valid_length = chain_length == 2\n\n traversal_validations.append((f\"{thread_description} has valid chain length\", is_valid_length))\n\n # Also validate we found at least one traversal (shows the system is working)\n traversal_validations.append(\n (\"At least one history traversal occurred\", len(history_traversal_logs) >= 1)\n )\n\n # === VALIDATION RESULTS ===\n self.logger.info(\" Thread Relationship Validation:\")\n relationship_passed = 0\n for desc, passed in expected_relationships:\n status = \"βœ…\" if passed else \"❌\"\n self.logger.info(f\" {status} {desc}\")\n if passed:\n relationship_passed += 1\n\n self.logger.info(\" History Traversal Validation:\")\n traversal_passed = 0\n for desc, passed in traversal_validations:\n status = \"βœ…\" if passed else \"❌\"\n self.logger.info(f\" {status} {desc}\")\n if passed:\n traversal_passed += 1\n\n # === SUCCESS CRITERIA ===\n total_relationship_checks = len(expected_relationships)\n total_traversal_checks = len(traversal_validations)\n\n self.logger.info(\" Validation Summary:\")\n self.logger.info(f\" Thread relationships: {relationship_passed}/{total_relationship_checks}\")\n self.logger.info(f\" History traversal: {traversal_passed}/{total_traversal_checks}\")\n\n # Success requires at least 80% of validations to pass\n relationship_success = relationship_passed >= (total_relationship_checks * 0.8)\n\n # If no traversal checks were possible, it means no traversal logs were found\n # This could indicate an issue since we expect at least some history building\n if total_traversal_checks == 0:\n self.logger.warning(\n \" No history traversal logs found - this may indicate conversation history is always pre-embedded\"\n )\n # Still consider it successful since the thread relationships are what matter most\n traversal_success = True\n else:\n # For traversal success, we need at least 50% to pass since chain lengths can vary\n # The important thing is that traversal is happening and relationships are correct\n traversal_success = traversal_passed >= (total_traversal_checks * 0.5)\n\n overall_success = relationship_success and traversal_success\n\n self.logger.info(\" Conversation Chain Structure:\")\n self.logger.info(\n f\" Chain A: {continuation_id_a1[:8]} β†’ {continuation_id_a2[:8]} β†’ {continuation_id_a3[:8]}\"\n )\n self.logger.info(f\" Chain B: {continuation_id_b1[:8]} β†’ {continuation_id_b2[:8]}\")\n self.logger.info(f\" Branch: {continuation_id_a1[:8]} β†’ {continuation_id_a1_branch[:8]}\")\n\n if overall_success:\n self.logger.info(\" βœ… Conversation chain validation test PASSED\")\n return True\n else:\n self.logger.error(\" ❌ Conversation chain validation test FAILED\")\n return False\n\n except Exception as e:\n self.logger.error(f\"Conversation chain validation test failed: {e}\")\n return False\n\n def call_mcp_tool(self, tool_name: str, params: dict) -> tuple:\n \"\"\"Call an MCP tool in-process\"\"\"\n # Use in-process implementation to maintain conversation memory\n response_text, continuation_id = self.call_mcp_tool_direct(tool_name, params)\n return response_text, continuation_id\n\n\ndef main():\n \"\"\"Run the conversation chain validation test\"\"\"\n import sys\n\n verbose = \"--verbose\" in sys.argv or \"-v\" in sys.argv\n test = ConversationChainValidationTest(verbose=verbose)\n\n success = test.run_test()\n sys.exit(0 if success else 1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "simulator_tests/test_cross_tool_comprehensive.py", "content": "#!/usr/bin/env python3\n\"\"\"\nComprehensive Cross-Tool Test\n\nTests file deduplication, conversation continuation, and file handling\nacross all available MCP tools using realistic workflows with low thinking mode.\nValidates:\n1. Cross-tool conversation continuation\n2. File deduplication across different tools\n3. Mixed file scenarios (old + new files)\n4. Conversation history preservation\n5. Proper tool chaining with context\n\"\"\"\n\n\nfrom .conversation_base_test import ConversationBaseTest\n\n\nclass CrossToolComprehensiveTest(ConversationBaseTest):\n \"\"\"Comprehensive test across all MCP tools\"\"\"\n\n def call_mcp_tool(self, tool_name: str, params: dict) -> tuple:\n \"\"\"Call an MCP tool in-process\"\"\"\n # Use the new method for workflow tools\n workflow_tools = [\"analyze\", \"debug\", \"codereview\", \"precommit\", \"refactor\", \"thinkdeep\"]\n if tool_name in workflow_tools:\n response_text, continuation_id = super().call_mcp_tool(tool_name, params)\n else:\n response_text, continuation_id = self.call_mcp_tool_direct(tool_name, params)\n return response_text, continuation_id\n\n @property\n def test_name(self) -> str:\n return \"cross_tool_comprehensive\"\n\n @property\n def test_description(self) -> str:\n return \"Comprehensive cross-tool file deduplication and continuation\"\n\n def run_test(self) -> bool:\n \"\"\"Comprehensive cross-tool test with all MCP tools\"\"\"\n try:\n self.logger.info(\"πŸ“„ Test: Comprehensive cross-tool file deduplication and continuation\")\n\n # Initialize for in-process tool calling\n self.setUp()\n\n # Setup test files\n self.setup_test_files()\n\n # Create short test files for quick testing\n python_code = \"\"\"def login(user, pwd):\n # Security issue: plain text password\n if user == \"admin\" and pwd == \"123\":\n return True\n return False\n\ndef hash_pwd(pwd):\n # Weak hashing\n return str(hash(pwd))\n\"\"\"\n\n config_file = \"\"\"{\n \"db_password\": \"weak123\",\n \"debug\": true,\n \"secret_key\": \"test\"\n}\"\"\"\n\n auth_file = self.create_additional_test_file(\"auth.py\", python_code)\n config_file_path = self.create_additional_test_file(\"config.json\", config_file)\n\n # Get timestamp for log filtering\n import datetime\n\n start_time = datetime.datetime.now().strftime(\"%Y-%m-%dT%H:%M:%S\")\n\n # Tool chain: chat β†’ analyze β†’ debug β†’ codereview β†’ precommit\n # Each step builds on the previous with cross-tool continuation\n\n current_continuation_id = None\n responses = []\n\n # Step 1: Start with chat tool to understand the codebase\n self.logger.info(\" Step 1: chat tool - Initial codebase exploration\")\n chat_params = {\n \"prompt\": \"List security issues in auth.py\",\n \"absolute_file_paths\": [auth_file],\n \"thinking_mode\": \"low\",\n \"model\": \"flash\",\n }\n\n response1, continuation_id1 = self.call_mcp_tool(\"chat\", chat_params)\n if not response1 or not continuation_id1:\n self.logger.error(\" ❌ Step 1: chat tool failed\")\n return False\n\n self.logger.info(f\" βœ… Step 1: chat completed with continuation_id: {continuation_id1[:8]}...\")\n responses.append((\"chat\", response1, continuation_id1))\n current_continuation_id = continuation_id1\n\n # Step 2: Use analyze tool to do deeper analysis (fresh conversation)\n self.logger.info(\" Step 2: analyze tool - Deep code analysis (fresh)\")\n analyze_params = {\n \"step\": \"Starting comprehensive code analysis to find security vulnerabilities in the authentication system\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"findings\": \"Initial analysis will focus on security vulnerabilities in authentication code\",\n \"relevant_files\": [auth_file],\n \"thinking_mode\": \"low\",\n \"model\": \"flash\",\n }\n\n response2, continuation_id2 = self.call_mcp_tool(\"analyze\", analyze_params)\n if not response2:\n self.logger.error(\" ❌ Step 2: analyze tool failed\")\n return False\n\n self.logger.info(\n f\" βœ… Step 2: analyze completed with continuation_id: {continuation_id2[:8] if continuation_id2 else 'None'}...\"\n )\n responses.append((\"analyze\", response2, continuation_id2))\n\n # Step 3: Continue chat conversation with config file\n self.logger.info(\" Step 3: chat continuation - Add config file context\")\n chat_continue_params = {\n \"continuation_id\": current_continuation_id,\n \"prompt\": \"Check config.json too\",\n \"absolute_file_paths\": [auth_file, config_file_path], # Old + new file\n \"thinking_mode\": \"low\",\n \"model\": \"flash\",\n }\n\n response3, _ = self.call_mcp_tool(\"chat\", chat_continue_params)\n if not response3:\n self.logger.error(\" ❌ Step 3: chat continuation failed\")\n return False\n\n self.logger.info(\" βœ… Step 3: chat continuation completed\")\n responses.append((\"chat_continue\", response3, current_continuation_id))\n\n # Step 4: Use debug tool to identify specific issues\n self.logger.info(\" Step 4: debug tool - Identify specific problems\")\n debug_params = {\n \"step\": \"Starting debug investigation to identify and fix authentication security issues\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"findings\": \"Investigating authentication vulnerabilities found in previous analysis\",\n \"relevant_files\": [auth_file, config_file_path],\n \"thinking_mode\": \"low\",\n \"model\": \"flash\",\n }\n\n response4, continuation_id4 = self.call_mcp_tool(\"debug\", debug_params)\n if not response4:\n self.logger.error(\" ❌ Step 4: debug tool failed\")\n return False\n\n self.logger.info(\n f\" βœ… Step 4: debug completed with continuation_id: {continuation_id4[:8] if continuation_id4 else 'None'}...\"\n )\n responses.append((\"debug\", response4, continuation_id4))\n\n # Step 5: Cross-tool continuation - continue debug with chat context\n if continuation_id4:\n self.logger.info(\" Step 5: debug continuation - Additional analysis\")\n debug_continue_params = {\n \"step\": \"Continuing debug investigation to fix password hashing implementation\",\n \"step_number\": 2,\n \"total_steps\": 2,\n \"next_step_required\": False,\n \"findings\": \"Building on previous analysis to fix weak password hashing\",\n \"continuation_id\": continuation_id4,\n \"relevant_files\": [auth_file, config_file_path],\n \"thinking_mode\": \"low\",\n \"model\": \"flash\",\n }\n\n response5, _ = self.call_mcp_tool(\"debug\", debug_continue_params)\n if response5:\n self.logger.info(\" βœ… Step 5: debug continuation completed\")\n responses.append((\"debug_continue\", response5, continuation_id4))\n\n # Step 6: Use codereview for comprehensive review\n self.logger.info(\" Step 6: codereview tool - Comprehensive code review\")\n codereview_params = {\n \"step\": \"Starting comprehensive security code review of authentication system\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"findings\": \"Performing thorough security review of authentication code and configuration\",\n \"relevant_files\": [auth_file, config_file_path],\n \"thinking_mode\": \"low\",\n \"model\": \"flash\",\n }\n\n response6, continuation_id6 = self.call_mcp_tool(\"codereview\", codereview_params)\n if not response6:\n self.logger.error(\" ❌ Step 6: codereview tool failed\")\n return False\n\n self.logger.info(\n f\" βœ… Step 6: codereview completed with continuation_id: {continuation_id6[:8] if continuation_id6 else 'None'}...\"\n )\n responses.append((\"codereview\", response6, continuation_id6))\n\n # Step 7: Create improved version and use precommit\n self.logger.info(\" Step 7: precommit tool - Pre-commit validation\")\n\n # Create a short improved version\n improved_code = \"\"\"import hashlib\n\ndef secure_login(user, pwd):\n # Better: hashed password check\n hashed = hashlib.sha256(pwd.encode()).hexdigest()\n if user == \"admin\" and hashed == \"expected_hash\":\n return True\n return False\n\"\"\"\n\n improved_file = self.create_additional_test_file(\"auth_improved.py\", improved_code)\n\n precommit_params = {\n \"step\": \"Starting pre-commit validation of improved authentication code\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"findings\": \"Validating improved authentication implementation before commit\",\n \"path\": self.test_dir,\n \"relevant_files\": [auth_file, config_file_path, improved_file],\n \"thinking_mode\": \"low\",\n \"model\": \"flash\",\n }\n\n response7, continuation_id7 = self.call_mcp_tool(\"precommit\", precommit_params)\n if not response7:\n self.logger.error(\" ❌ Step 7: precommit tool failed\")\n return False\n\n self.logger.info(\n f\" βœ… Step 7: precommit completed with continuation_id: {continuation_id7[:8] if continuation_id7 else 'None'}...\"\n )\n responses.append((\"precommit\", response7, continuation_id7))\n\n # Validate comprehensive results\n self.logger.info(\" πŸ“‹ Validating comprehensive cross-tool results...\")\n logs = self.get_server_logs_since(start_time)\n\n # Validation criteria\n tools_used = [r[0] for r in responses]\n continuation_ids_created = [r[2] for r in responses if r[2]]\n\n # Check for various log patterns\n conversation_logs = [\n line for line in logs.split(\"\\n\") if \"conversation\" in line.lower() or \"history\" in line.lower()\n ]\n embedding_logs = [\n line\n for line in logs.split(\"\\n\")\n if \"πŸ“\" in line or \"embedding\" in line.lower() or \"file\" in line.lower()\n ]\n continuation_logs = [\n line for line in logs.split(\"\\n\") if \"continuation\" in line.lower() or \"resuming\" in line.lower()\n ]\n cross_tool_logs = [\n line\n for line in logs.split(\"\\n\")\n if any(tool in line.lower() for tool in [\"chat\", \"analyze\", \"debug\", \"codereview\", \"precommit\"])\n ]\n\n # File mentions\n auth_file_mentioned = any(\"auth.py\" in line for line in logs.split(\"\\n\"))\n config_file_mentioned = any(\"config.json\" in line for line in logs.split(\"\\n\"))\n improved_file_mentioned = any(\"auth_improved.py\" in line for line in logs.split(\"\\n\"))\n\n # Print comprehensive diagnostics\n self.logger.info(f\" Tools used: {len(tools_used)} ({', '.join(tools_used)})\")\n self.logger.info(f\" Continuation IDs created: {len(continuation_ids_created)}\")\n self.logger.info(f\" Conversation logs found: {len(conversation_logs)}\")\n self.logger.info(f\" File embedding logs found: {len(embedding_logs)}\")\n self.logger.info(f\" Continuation logs found: {len(continuation_logs)}\")\n self.logger.info(f\" Cross-tool activity logs: {len(cross_tool_logs)}\")\n self.logger.info(f\" Auth file mentioned: {auth_file_mentioned}\")\n self.logger.info(f\" Config file mentioned: {config_file_mentioned}\")\n self.logger.info(f\" Improved file mentioned: {improved_file_mentioned}\")\n\n if self.verbose:\n self.logger.debug(\" πŸ“‹ Sample tool activity logs:\")\n for log in cross_tool_logs[:10]: # Show first 10\n if log.strip():\n self.logger.debug(f\" {log.strip()}\")\n\n self.logger.debug(\" πŸ“‹ Sample continuation logs:\")\n for log in continuation_logs[:5]: # Show first 5\n if log.strip():\n self.logger.debug(f\" {log.strip()}\")\n\n # Comprehensive success criteria\n success_criteria = [\n len(tools_used) >= 5, # Used multiple tools\n len(continuation_ids_created) >= 3, # Created multiple continuation threads\n len(embedding_logs) > 10, # Significant file embedding activity\n len(continuation_logs) > 0, # Evidence of continuation\n auth_file_mentioned, # Original file processed\n config_file_mentioned, # Additional file processed\n improved_file_mentioned, # New file processed\n len(conversation_logs) > 5, # Conversation history activity\n ]\n\n passed_criteria = sum(success_criteria)\n total_criteria = len(success_criteria)\n\n self.logger.info(f\" Success criteria met: {passed_criteria}/{total_criteria}\")\n\n # Allow for slight variations in log output (7/8 is sufficient for comprehensive test)\n if passed_criteria >= total_criteria - 1: # Allow 1 missing criterion\n self.logger.info(\" βœ… Comprehensive cross-tool test: PASSED\")\n if passed_criteria < total_criteria:\n self.logger.info(\n f\" ℹ️ Note: {total_criteria - passed_criteria} criterion not met (acceptable variation)\"\n )\n return True\n else:\n self.logger.warning(\" ⚠️ Comprehensive cross-tool test: FAILED\")\n self.logger.warning(\" πŸ’‘ Check logs for detailed cross-tool activity\")\n return False\n\n except Exception as e:\n self.logger.error(f\"Comprehensive cross-tool test failed: {e}\")\n return False\n finally:\n self.cleanup_test_files()\n" }, { "path": "simulator_tests/test_cross_tool_continuation.py", "content": "#!/usr/bin/env python3\n\"\"\"\nCross-Tool Continuation Test\n\nTests comprehensive cross-tool continuation scenarios to ensure\nconversation context is maintained when switching between different tools.\n\"\"\"\n\nfrom .conversation_base_test import ConversationBaseTest\n\n\nclass CrossToolContinuationTest(ConversationBaseTest):\n \"\"\"Test comprehensive cross-tool continuation scenarios\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"cross_tool_continuation\"\n\n @property\n def test_description(self) -> str:\n return \"Cross-tool conversation continuation scenarios\"\n\n def run_test(self) -> bool:\n \"\"\"Test comprehensive cross-tool continuation scenarios\"\"\"\n try:\n self.logger.info(\"πŸ”§ Test: Cross-tool continuation scenarios\")\n\n # Setup test environment for conversation testing\n self.setUp()\n\n success_count = 0\n total_scenarios = 3\n\n # Scenario 1: chat -> thinkdeep -> codereview\n if self._test_chat_thinkdeep_codereview():\n success_count += 1\n\n # Scenario 2: analyze -> debug -> thinkdeep\n if self._test_analyze_debug_thinkdeep():\n success_count += 1\n\n # Scenario 3: Multi-file cross-tool continuation\n if self._test_multi_file_continuation():\n success_count += 1\n\n self.logger.info(\n f\" βœ… Cross-tool continuation scenarios completed: {success_count}/{total_scenarios} scenarios passed\"\n )\n\n # Consider successful if at least one scenario worked\n return success_count > 0\n\n except Exception as e:\n self.logger.error(f\"Cross-tool continuation test failed: {e}\")\n return False\n finally:\n self.cleanup_test_files()\n\n def _test_chat_thinkdeep_codereview(self) -> bool:\n \"\"\"Test chat -> thinkdeep -> codereview scenario\"\"\"\n try:\n self.logger.info(\" 1: Testing chat -> thinkdeep -> codereview\")\n\n # Start with chat\n chat_response, chat_id = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. Look at this Python code and tell me what you think about it\",\n \"absolute_file_paths\": [self.test_files[\"python\"]],\n \"model\": \"flash\",\n },\n )\n\n if not chat_response or not chat_id:\n self.logger.error(\"Failed to start chat conversation\")\n return False\n\n # Continue with thinkdeep\n thinkdeep_response, _ = self.call_mcp_tool(\n \"thinkdeep\",\n {\n \"step\": \"Think deeply about potential performance issues in this code. Please use low thinking mode.\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Building on previous chat analysis to examine performance issues\",\n \"relevant_files\": [self.test_files[\"python\"]], # Same file should be deduplicated\n \"continuation_id\": chat_id,\n \"model\": \"flash\",\n },\n )\n\n if not thinkdeep_response:\n self.logger.error(\"Failed chat -> thinkdeep continuation\")\n return False\n\n # Continue with codereview\n codereview_response, _ = self.call_mcp_tool(\n \"codereview\",\n {\n \"step\": \"Building on our previous analysis, provide a comprehensive code review\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Continuing from previous chat and thinkdeep analysis for comprehensive review\",\n \"relevant_files\": [self.test_files[\"python\"]], # Same file should be deduplicated\n \"continuation_id\": chat_id,\n \"model\": \"flash\",\n },\n )\n\n if not codereview_response:\n self.logger.error(\"Failed thinkdeep -> codereview continuation\")\n return False\n\n self.logger.info(\" βœ… chat -> thinkdeep -> codereview working\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Chat -> thinkdeep -> codereview scenario failed: {e}\")\n return False\n\n def _test_analyze_debug_thinkdeep(self) -> bool:\n \"\"\"Test analyze -> debug -> thinkdeep scenario\"\"\"\n try:\n self.logger.info(\" 2: Testing analyze -> debug -> thinkdeep\")\n\n # Start with analyze\n analyze_response, analyze_id = self.call_mcp_tool(\n \"analyze\",\n {\n \"step\": \"Analyze this code for quality and performance issues\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Starting analysis of Python code for quality and performance issues\",\n \"relevant_files\": [self.test_files[\"python\"]],\n \"model\": \"flash\",\n },\n )\n\n if not analyze_response or not analyze_id:\n self.logger.warning(\"Failed to start analyze conversation, skipping scenario 2\")\n return False\n\n # Continue with debug\n debug_response, _ = self.call_mcp_tool(\n \"debug\",\n {\n \"step\": \"Based on our analysis, help debug the performance issue in fibonacci\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Building on previous analysis to debug specific performance issue\",\n \"relevant_files\": [self.test_files[\"python\"]], # Same file should be deduplicated\n \"continuation_id\": analyze_id,\n \"model\": \"flash\",\n },\n )\n\n if not debug_response:\n self.logger.warning(\" ⚠️ analyze -> debug continuation failed\")\n return False\n\n # Continue with thinkdeep\n final_response, _ = self.call_mcp_tool(\n \"thinkdeep\",\n {\n \"step\": \"Think deeply about the architectural implications of the issues we've found. Please use low thinking mode.\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Building on analysis and debug findings to explore architectural implications\",\n \"relevant_files\": [self.test_files[\"python\"]], # Same file should be deduplicated\n \"continuation_id\": analyze_id,\n \"model\": \"flash\",\n },\n )\n\n if not final_response:\n self.logger.warning(\" ⚠️ debug -> thinkdeep continuation failed\")\n return False\n\n self.logger.info(\" βœ… analyze -> debug -> thinkdeep working\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Analyze -> debug -> thinkdeep scenario failed: {e}\")\n return False\n\n def _test_multi_file_continuation(self) -> bool:\n \"\"\"Test multi-file cross-tool continuation\"\"\"\n try:\n self.logger.info(\" 3: Testing multi-file cross-tool continuation\")\n\n # Start with both files\n multi_response, multi_id = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Please use low thinking mode. Analyze both the Python code and configuration file\",\n \"absolute_file_paths\": [self.test_files[\"python\"], self.test_files[\"config\"]],\n \"model\": \"flash\",\n },\n )\n\n if not multi_response or not multi_id:\n self.logger.warning(\"Failed to start multi-file conversation, skipping scenario 3\")\n return False\n\n # Switch to codereview with same files (should use conversation history)\n multi_review, _ = self.call_mcp_tool(\n \"codereview\",\n {\n \"step\": \"Review both files in the context of our previous discussion\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Continuing multi-file analysis with code review perspective\",\n \"relevant_files\": [self.test_files[\"python\"], self.test_files[\"config\"]], # Same files\n \"continuation_id\": multi_id,\n \"model\": \"flash\",\n },\n )\n\n if not multi_review:\n self.logger.warning(\" ⚠️ Multi-file cross-tool continuation failed\")\n return False\n\n self.logger.info(\" βœ… Multi-file cross-tool continuation working\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Multi-file continuation scenario failed: {e}\")\n return False\n" }, { "path": "simulator_tests/test_debug_certain_confidence.py", "content": "#!/usr/bin/env python3\n\"\"\"\nDebug Tool Certain Confidence Simulator Test\n\nTests the debug tool's 'certain' confidence feature in a realistic simulation:\n- Multi-step investigation leading to certain confidence\n- Validation that expert analysis is skipped for obvious bugs\n- Verification that certain confidence is always trusted\n- Ensures token optimization works correctly for minimal fixes\n\"\"\"\n\nimport json\nfrom typing import Optional\n\nfrom tools.shared.exceptions import ToolExecutionError\n\nfrom .conversation_base_test import ConversationBaseTest\n\n\nclass DebugCertainConfidenceTest(ConversationBaseTest):\n \"\"\"Test debug tool's certain confidence optimization feature\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"debug_certain_confidence\"\n\n @property\n def test_description(self) -> str:\n return \"Debug tool certain confidence optimization validation\"\n\n def run_test(self) -> bool:\n \"\"\"Test debug tool certain confidence capabilities\"\"\"\n # Set up the test environment\n self.setUp()\n\n try:\n self.logger.info(\"Test: Debug tool certain confidence validation\")\n\n # Create test files with obvious bugs for certain scenarios\n self._create_obvious_bug_scenarios()\n\n # Test 1: Obvious import error with certain confidence\n if not self._test_obvious_import_error_certain():\n return False\n\n # Test 2: Certain confidence is always trusted\n if not self._test_certain_always_trusted():\n return False\n\n # Test 3: Regular high confidence still triggers expert analysis\n if not self._test_regular_high_confidence_expert_analysis():\n return False\n\n # Test 4: Multi-step investigation ending in certain\n if not self._test_multi_step_investigation_certain():\n return False\n\n self.logger.info(\" βœ… All debug certain confidence tests passed\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Debug certain confidence test failed: {e}\")\n return False\n\n def _create_obvious_bug_scenarios(self):\n \"\"\"Create test files with obvious bugs perfect for certain confidence\"\"\"\n\n # Scenario 1: Missing import statement (very obvious)\n missing_import_code = \"\"\"#!/usr/bin/env python3\nimport os\nimport sys\n# import hashlib # <-- Missing import!\n\nclass UserAuth:\n def __init__(self, secret_key):\n self.secret_key = secret_key\n\n def hash_password(self, password):\n # This will fail with NameError: name 'hashlib' is not defined\n salt = os.urandom(32)\n return hashlib.pbkdf2_hmac('sha256', password.encode(), salt, 100000)\n\n def verify_password(self, password, stored_hash):\n # This function also uses hashlib\n return hashlib.pbkdf2_hmac('sha256', password.encode(), stored_hash[:32], 100000) == stored_hash[32:]\n\"\"\"\n\n # Scenario 2: Typo in method name (obvious once spotted)\n typo_bug_code = \"\"\"#!/usr/bin/env python3\nclass Calculator:\n def __init__(self):\n self.history = []\n\n def add_numbers(self, a, b):\n result = a + b\n self.history.append(f\"{a} + {b} = {result}\")\n return result\n\n def calculate_total(self, numbers):\n total = 0\n for num in numbers:\n # Typo: should be add_numbers, not add_number\n total = self.add_number(total, num) # NameError: no method 'add_number'\n return total\n\"\"\"\n\n # Scenario 3: Indentation error (Python syntax error)\n indentation_error_code = \"\"\"#!/usr/bin/env python3\ndef process_data(data_list):\n results = []\n for item in data_list:\n if item > 0:\n processed = item * 2\n results.append(processed) # IndentationError: unindent does not match any outer indentation level\n return results\n\ndef main():\n data = [1, 2, 3, 4, 5]\n print(process_data(data))\n\"\"\"\n\n # Create test files\n self.missing_import_file = self.create_additional_test_file(\"user_auth.py\", missing_import_code)\n self.typo_bug_file = self.create_additional_test_file(\"calculator.py\", typo_bug_code)\n self.indentation_file = self.create_additional_test_file(\"data_processor.py\", indentation_error_code)\n\n self.logger.info(\" βœ… Created obvious bug scenarios:\")\n self.logger.info(f\" - Missing import: {self.missing_import_file}\")\n self.logger.info(f\" - Method typo: {self.typo_bug_file}\")\n self.logger.info(f\" - Indentation error: {self.indentation_file}\")\n\n # Create error logs for context\n import_error_log = \"\"\"ERROR: User authentication failing during login\nTraceback (most recent call last):\n File \"user_auth.py\", line 12, in hash_password\n return hashlib.pbkdf2_hmac('sha256', password.encode(), salt, 100000)\nNameError: name 'hashlib' is not defined\n\nThis happens every time a user tries to log in. The error occurs in the password hashing function.\n\"\"\"\n\n self.error_log_file = self.create_additional_test_file(\"error.log\", import_error_log)\n self.logger.info(f\" - Error log: {self.error_log_file}\")\n\n def _test_obvious_import_error_certain(self) -> bool:\n \"\"\"Test certain confidence with obvious missing import error\"\"\"\n try:\n self.logger.info(\" 1.1: Testing obvious import error with certain confidence\")\n\n # Step 1: Initial investigation\n self.logger.info(\" 1.1.1: Step 1 - Initial problem description\")\n response1, continuation_id = self.call_mcp_tool_direct(\n \"debug\",\n {\n \"step\": \"Investigating NameError in user authentication - users cannot log in due to 'name hashlib is not defined' error.\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"findings\": \"NameError occurs in hash_password method when trying to use hashlib.pbkdf2_hmac. Error happens on every login attempt.\",\n \"files_checked\": [self.error_log_file],\n \"relevant_files\": [self.error_log_file],\n \"hypothesis\": \"Missing import statement for hashlib module\",\n \"confidence\": \"medium\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to get initial investigation response\")\n return False\n\n response1_data = self._parse_debug_response(response1)\n if not self._validate_investigation_response(response1_data, 1, True, \"pause_for_investigation\"):\n return False\n\n self.logger.info(f\" βœ… Step 1 successful, continuation_id: {continuation_id}\")\n\n # Step 2: Examine code and identify obvious fix - use certain confidence\n self.logger.info(\" 1.1.2: Step 2 - Found exact issue and simple fix (certain)\")\n response2, _ = self.call_mcp_tool_direct(\n \"debug\",\n {\n \"step\": \"Found the exact issue and the minimal fix required\",\n \"step_number\": 2,\n \"total_steps\": 2,\n \"next_step_required\": False, # Final step\n \"findings\": \"Missing 'import hashlib' statement at the top of user_auth.py file. The error occurs because hashlib is used in hash_password() method on line 12 but never imported. Simple one-line fix: add 'import hashlib' after line 2.\",\n \"files_checked\": [self.error_log_file, self.missing_import_file],\n \"relevant_files\": [self.missing_import_file],\n \"relevant_context\": [\"UserAuth.hash_password\", \"UserAuth.verify_password\"],\n \"hypothesis\": \"Missing 'import hashlib' statement causes NameError when hash_password method executes\",\n \"confidence\": \"certain\", # Use certain - should skip expert analysis\n \"continuation_id\": continuation_id,\n \"model\": \"flash\", # Specify model for consistency\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to complete investigation with certain confidence\")\n return False\n\n response2_data = self._parse_debug_response(response2)\n if not response2_data:\n return False\n\n # Validate certain response structure\n expected_status = \"certain_confidence_proceed_with_fix\"\n if response2_data.get(\"status\") != expected_status:\n self.logger.error(f\"Expected status '{expected_status}', got '{response2_data.get('status')}'\")\n return False\n\n if not response2_data.get(\"investigation_complete\"):\n self.logger.error(\"Expected investigation_complete=true for certain confidence\")\n return False\n\n if not response2_data.get(\"skip_expert_analysis\"):\n self.logger.error(\"Expected skip_expert_analysis=true for certain confidence\")\n return False\n\n # Verify expert analysis is marked as skipped\n expert_analysis = response2_data.get(\"expert_analysis\", {})\n if expert_analysis.get(\"status\") != \"skipped_due_to_certain_confidence\":\n self.logger.error(\"Expert analysis should be marked as skipped for certain confidence\")\n return False\n\n # Check for proper investigation summary\n complete_investigation = response2_data.get(\"complete_investigation\", {})\n if complete_investigation.get(\"confidence_level\") != \"certain\":\n self.logger.error(\"Expected confidence_level='certain' in complete investigation\")\n return False\n\n if complete_investigation.get(\"steps_taken\") != 2:\n self.logger.error(\"Expected steps_taken=2 in complete investigation\")\n return False\n\n # Verify next steps guidance\n next_steps = response2_data.get(\"next_steps\", \"\")\n if \"CERTAIN confidence\" not in next_steps:\n self.logger.error(\"Expected 'CERTAIN confidence' in next_steps guidance\")\n return False\n\n if \"minimal fix\" not in next_steps:\n self.logger.error(\"Expected 'minimal fix' guidance in next_steps\")\n return False\n\n self.logger.info(\" βœ… Certain confidence skipped expert analysis correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Obvious import error certain test failed: {e}\")\n return False\n\n def _test_certain_always_trusted(self) -> bool:\n \"\"\"Test that certain confidence is always trusted regardless of complexity\"\"\"\n try:\n self.logger.info(\" 1.2: Testing that certain confidence is always trusted\")\n\n # Single step investigation with certain - should always be trusted\n self.logger.info(\" 1.2.1: Direct certain confidence (always trusted)\")\n response, _ = self.call_mcp_tool_direct(\n \"debug\",\n {\n \"step\": \"Found the exact root cause and minimal fix for this complex issue\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False, # Final step\n \"findings\": \"After thorough investigation, identified that the issue is caused by method name typo in Calculator.calculate_total() - calls self.add_number() instead of self.add_numbers(). Simple fix: change line 14 from 'add_number' to 'add_numbers'.\",\n \"files_checked\": [self.typo_bug_file],\n \"relevant_files\": [self.typo_bug_file],\n \"relevant_context\": [\"Calculator.calculate_total\", \"Calculator.add_numbers\"],\n \"hypothesis\": \"Method name typo in calculate_total() calls non-existent add_number() instead of add_numbers()\",\n \"confidence\": \"certain\", # Should always be trusted\n \"model\": \"flash\",\n },\n )\n\n if not response:\n self.logger.error(\"Failed to get certain confidence response\")\n return False\n\n response_data = self._parse_debug_response(response)\n if not response_data:\n return False\n\n # Verify certain is trusted regardless of complexity\n if response_data.get(\"status\") != \"certain_confidence_proceed_with_fix\":\n self.logger.error(\"Certain confidence should always be trusted\")\n return False\n\n if not response_data.get(\"skip_expert_analysis\"):\n self.logger.error(\"Expert analysis should be skipped for certain confidence\")\n return False\n\n # Ensure expert analysis is marked as skipped\n expert_analysis = response_data.get(\"expert_analysis\", {})\n if expert_analysis.get(\"status\") != \"skipped_due_to_certain_confidence\":\n self.logger.error(\"Expert analysis status should indicate certain skip\")\n return False\n\n self.logger.info(\" βœ… Certain confidence always trusted correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Certain always trusted test failed: {e}\")\n return False\n\n def _test_regular_high_confidence_expert_analysis(self) -> bool:\n \"\"\"Test that regular 'high' confidence still triggers expert analysis\"\"\"\n try:\n self.logger.info(\" 1.3: Testing that regular 'high' confidence triggers expert analysis\")\n\n # Investigation with regular high confidence (not certain)\n self.logger.info(\" 1.3.1: High confidence (not certain) - should trigger expert analysis\")\n response, _ = self.call_mcp_tool_direct(\n \"debug\",\n {\n \"step\": \"Identified likely root cause with strong evidence\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False, # Final step\n \"findings\": \"IndentationError in data_processor.py line 8 - results.append(processed) is incorrectly indented. Should align with the 'if' statement above it.\",\n \"files_checked\": [self.indentation_file],\n \"relevant_files\": [self.indentation_file],\n \"relevant_context\": [\"process_data\"],\n \"hypothesis\": \"Incorrect indentation causes IndentationError in process_data function\",\n \"confidence\": \"high\", # Regular high confidence, NOT certain\n \"model\": \"flash\",\n },\n )\n\n if not response:\n self.logger.error(\"Failed to get high confidence response\")\n return False\n\n response_data = self._parse_debug_response(response)\n if not response_data:\n return False\n\n # Verify that regular high confidence triggers expert analysis\n if response_data.get(\"status\") != \"calling_expert_analysis\":\n self.logger.error(\n f\"Expected 'calling_expert_analysis' for high confidence, got '{response_data.get('status')}'\"\n )\n return False\n\n if response_data.get(\"skip_expert_analysis\"):\n self.logger.error(\"Expert analysis should NOT be skipped for regular high confidence\")\n return False\n\n # Verify expert analysis was called\n expert_analysis = response_data.get(\"expert_analysis\", {})\n if not expert_analysis:\n self.logger.error(\"Expected expert analysis for regular high confidence\")\n return False\n\n # Check that expert analysis has content\n if \"status\" not in expert_analysis:\n self.logger.error(\"Expert analysis should have status field\")\n return False\n\n self.logger.info(\" βœ… Regular high confidence triggers expert analysis correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Regular high confidence test failed: {e}\")\n return False\n\n def _test_multi_step_investigation_certain(self) -> bool:\n \"\"\"Test multi-step investigation that ends with certain confidence\"\"\"\n try:\n self.logger.info(\" 1.4: Testing multi-step investigation ending with certain\")\n\n # Step 1: Start investigation\n self.logger.info(\" 1.4.1: Step 1 - Initial investigation\")\n response1, continuation_id = self.call_mcp_tool_direct(\n \"debug\",\n {\n \"step\": \"Investigating Python syntax error in data processing module\",\n \"step_number\": 1,\n \"total_steps\": 3,\n \"next_step_required\": True,\n \"findings\": \"IndentationError reported when running data_processor.py - 'unindent does not match any outer indentation level'\",\n \"files_checked\": [self.indentation_file],\n \"relevant_files\": [],\n \"hypothesis\": \"Indentation inconsistency in Python code\",\n \"confidence\": \"low\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start multi-step investigation\")\n return False\n\n # Step 2: Examine code structure\n self.logger.info(\" 1.4.2: Step 2 - Code examination\")\n response2, _ = self.call_mcp_tool_direct(\n \"debug\",\n {\n \"step\": \"Examining the indentation structure in process_data function\",\n \"step_number\": 2,\n \"total_steps\": 3,\n \"next_step_required\": True,\n \"findings\": \"Found the issue: line 8 'results.append(processed)' is indented incorrectly. It should align with the 'if' statement, not be at the same level as the 'for' loop.\",\n \"files_checked\": [self.indentation_file],\n \"relevant_files\": [self.indentation_file],\n \"relevant_context\": [\"process_data\"],\n \"hypothesis\": \"Line 8 has incorrect indentation level causing IndentationError\",\n \"confidence\": \"medium\",\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue to step 2\")\n return False\n\n # Step 3: Confirm fix with certain confidence\n self.logger.info(\" 1.4.3: Step 3 - Confirmed fix (certain)\")\n response3, _ = self.call_mcp_tool_direct(\n \"debug\",\n {\n \"step\": \"Confirmed the exact issue and simple fix\",\n \"step_number\": 3,\n \"total_steps\": 3,\n \"next_step_required\": False, # Final step\n \"findings\": \"Confirmed: line 8 'results.append(processed)' needs to be indented 4 more spaces to align with line 6 'if item > 0:'. This is a simple indentation fix.\",\n \"files_checked\": [self.indentation_file],\n \"relevant_files\": [self.indentation_file],\n \"relevant_context\": [\"process_data\"],\n \"hypothesis\": \"IndentationError on line 8 due to incorrect indentation level - needs 4 more spaces\",\n \"confidence\": \"certain\", # Final step with certain\n \"continuation_id\": continuation_id,\n \"model\": \"flash\",\n },\n )\n\n if not response3:\n self.logger.error(\"Failed to complete multi-step investigation\")\n return False\n\n response3_data = self._parse_debug_response(response3)\n if not response3_data:\n return False\n\n # Validate multi-step certain response\n if response3_data.get(\"status\") != \"certain_confidence_proceed_with_fix\":\n self.logger.error(\"Expected certain status for final step\")\n return False\n\n if not response3_data.get(\"skip_expert_analysis\"):\n self.logger.error(\"Expected expert analysis to be skipped for certain\")\n return False\n\n # Verify investigation preserves steps (at least the current step)\n complete_investigation = response3_data.get(\"complete_investigation\", {})\n steps_taken = complete_investigation.get(\"steps_taken\", 0)\n if steps_taken < 1:\n self.logger.error(\"Expected at least 1 step in complete investigation\")\n return False\n\n # Check that work summary includes progression\n work_summary = complete_investigation.get(\"work_summary\", \"\")\n if \"Total steps:\" not in work_summary and \"Steps taken:\" not in work_summary:\n self.logger.error(\"Work summary should show steps information\")\n return False\n\n self.logger.info(\" βœ… Multi-step investigation with certain ending successful\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Multi-step investigation certain test failed: {e}\")\n return False\n\n def call_mcp_tool_direct(self, tool_name: str, params: dict) -> tuple[Optional[str], Optional[str]]:\n \"\"\"Call an MCP tool directly in-process to maintain conversation memory\"\"\"\n try:\n # Get the tool instance\n if tool_name not in self._tools:\n self.logger.error(f\"Tool '{tool_name}' not found in available tools\")\n return None, None\n\n tool = self._tools[tool_name]\n\n # Execute the tool with proper async handling\n loop = self._get_event_loop()\n\n # Call the tool's execute method\n try:\n result = loop.run_until_complete(tool.execute(params))\n except ToolExecutionError as exc:\n response_text = exc.payload\n continuation_id = self._extract_debug_continuation_id(response_text)\n return response_text, continuation_id\n\n if not result or len(result) == 0:\n self.logger.error(f\"Tool '{tool_name}' returned empty result\")\n return None, None\n\n # Extract the text content from the result\n response_text = result[0].text if hasattr(result[0], \"text\") else str(result[0])\n\n # Extract continuation_id from debug response if present\n continuation_id = self._extract_debug_continuation_id(response_text)\n\n return response_text, continuation_id\n\n except Exception as e:\n self.logger.error(f\"Failed to call tool '{tool_name}' directly: {e}\")\n return None, None\n\n def _extract_debug_continuation_id(self, response_text: str) -> Optional[str]:\n \"\"\"Extract continuation_id from debug response\"\"\"\n try:\n response_data = json.loads(response_text)\n return response_data.get(\"continuation_id\")\n except json.JSONDecodeError as e:\n self.logger.debug(f\"Failed to parse response for debug continuation_id: {e}\")\n return None\n\n def _parse_debug_response(self, response_text: str) -> dict:\n \"\"\"Parse debug tool JSON response\"\"\"\n try:\n return json.loads(response_text)\n except json.JSONDecodeError as e:\n self.logger.error(f\"Failed to parse debug response as JSON: {e}\")\n self.logger.error(f\"Response text: {response_text[:500]}...\")\n return {}\n\n def _validate_investigation_response(\n self,\n response_data: dict,\n expected_step: int,\n expected_next_required: bool,\n expected_status: str,\n ) -> bool:\n \"\"\"Validate debug investigation response structure\"\"\"\n try:\n # Check status\n if response_data.get(\"status\") != expected_status:\n self.logger.error(f\"Expected status '{expected_status}', got '{response_data.get('status')}'\")\n return False\n\n # Check step number\n if response_data.get(\"step_number\") != expected_step:\n self.logger.error(f\"Expected step_number {expected_step}, got {response_data.get('step_number')}\")\n return False\n\n # Check next_step_required\n if response_data.get(\"next_step_required\") != expected_next_required:\n self.logger.error(\n f\"Expected next_step_required {expected_next_required}, got {response_data.get('next_step_required')}\"\n )\n return False\n\n # Basic structure checks\n if \"investigation_status\" not in response_data:\n self.logger.error(\"Missing investigation_status in response\")\n return False\n\n if not response_data.get(\"next_steps\"):\n self.logger.error(\"Missing next_steps guidance in response\")\n return False\n\n return True\n\n except Exception as e:\n self.logger.error(f\"Error validating investigation response: {e}\")\n return False\n" }, { "path": "simulator_tests/test_debug_validation.py", "content": "#!/usr/bin/env python3\n\"\"\"\nDebugWorkflow Tool Validation Test\n\nTests the debug tool's capabilities using the new workflow architecture.\nThis validates that the new workflow-based implementation maintains\nall the functionality of the original debug tool.\n\"\"\"\n\nimport json\nfrom typing import Optional\n\nfrom .conversation_base_test import ConversationBaseTest\n\n\nclass DebugValidationTest(ConversationBaseTest):\n \"\"\"Test debug tool with new workflow architecture\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"debug_validation\"\n\n @property\n def test_description(self) -> str:\n return \"Debug tool validation with new workflow architecture\"\n\n def run_test(self) -> bool:\n \"\"\"Test debug tool capabilities\"\"\"\n # Set up the test environment\n self.setUp()\n\n try:\n self.logger.info(\"Test: DebugWorkflow tool validation (new architecture)\")\n\n # Create a Python file with a subtle but realistic bug\n self._create_buggy_code()\n\n # Test 1: Single investigation session with multiple steps\n if not self._test_single_investigation_session():\n return False\n\n # Test 2: Investigation flow that requires refinement\n if not self._test_investigation_refine_flow():\n return False\n\n # Test 3: Complete investigation with expert analysis\n if not self._test_complete_investigation_with_analysis():\n return False\n\n # Test 4: Certain confidence behavior\n if not self._test_certain_confidence():\n return False\n\n # Test 5: Context-aware file embedding\n if not self._test_context_aware_file_embedding():\n return False\n\n # Test 6: Multi-step file context optimization\n if not self._test_multi_step_file_context():\n return False\n\n self.logger.info(\" βœ… All debug validation tests passed\")\n return True\n\n except Exception as e:\n self.logger.error(f\"DebugWorkflow validation test failed: {e}\")\n return False\n\n def _create_buggy_code(self):\n \"\"\"Create test files with a subtle bug for debugging\"\"\"\n # Create a Python file with dictionary iteration bug\n buggy_code = \"\"\"#!/usr/bin/env python3\nimport json\nfrom datetime import datetime, timedelta\n\nclass SessionManager:\n def __init__(self):\n self.active_sessions = {}\n self.session_timeout = 30 * 60 # 30 minutes in seconds\n\n def create_session(self, user_id, user_data):\n \\\"\\\"\\\"Create a new user session\\\"\\\"\\\"\n session_id = f\"sess_{user_id}_{datetime.now().timestamp()}\"\n\n session_info = {\n 'user_id': user_id,\n 'user_data': user_data,\n 'created_at': datetime.now(),\n 'expires_at': datetime.now() + timedelta(seconds=self.session_timeout)\n }\n\n self.active_sessions[session_id] = session_info\n return session_id\n\n def validate_session(self, session_id):\n \\\"\\\"\\\"Check if session is valid and not expired\\\"\\\"\\\"\n if session_id not in self.active_sessions:\n return False\n\n session = self.active_sessions[session_id]\n current_time = datetime.now()\n\n # Check if session has expired\n if current_time > session['expires_at']:\n del self.active_sessions[session_id]\n return False\n\n return True\n\n def cleanup_expired_sessions(self):\n \\\"\\\"\\\"Remove expired sessions from memory\\\"\\\"\\\"\n current_time = datetime.now()\n expired_count = 0\n\n # BUG: Modifying dictionary while iterating over it\n for session_id, session in self.active_sessions.items():\n if current_time > session['expires_at']:\n del self.active_sessions[session_id] # This causes RuntimeError\n expired_count += 1\n\n return expired_count\n\"\"\"\n\n # Create test file with subtle bug\n self.buggy_file = self.create_additional_test_file(\"session_manager.py\", buggy_code)\n self.logger.info(f\" βœ… Created test file with subtle bug: {self.buggy_file}\")\n\n # Create error description\n error_description = \"\"\"ISSUE DESCRIPTION:\nOur session management system is experiencing intermittent failures during cleanup operations.\n\nSYMPTOMS:\n- Random RuntimeError: dictionary changed size during iteration\n- Occurs during high load when many sessions expire simultaneously\n- Error happens in cleanup_expired_sessions method\n- Affects about 5% of cleanup operations\n\nERROR LOG:\nRuntimeError: dictionary changed size during iteration\n File \"session_manager.py\", line 44, in cleanup_expired_sessions\n for session_id, session in self.active_sessions.items():\n\"\"\"\n\n self.error_file = self.create_additional_test_file(\"error_description.txt\", error_description)\n self.logger.info(f\" βœ… Created error description file: {self.error_file}\")\n\n def _test_single_investigation_session(self) -> bool:\n \"\"\"Test a complete investigation session with multiple steps\"\"\"\n try:\n self.logger.info(\" 1.1: Testing single investigation session\")\n\n # Step 1: Start investigation\n self.logger.info(\" 1.1.1: Step 1 - Initial investigation\")\n response1, continuation_id = self.call_mcp_tool(\n \"debug\",\n {\n \"step\": \"I need to investigate intermittent RuntimeError during session cleanup. Let me start by examining the error description and understanding the symptoms.\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"RuntimeError occurs during dictionary iteration in cleanup_expired_sessions method. Error happens intermittently during high load.\",\n \"files_checked\": [self.error_file],\n \"relevant_files\": [self.error_file],\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to get initial investigation response\")\n return False\n\n # Parse and validate JSON response\n response1_data = self._parse_debug_response(response1)\n if not response1_data:\n return False\n\n # Validate step 1 response structure - expect pause_for_investigation for next_step_required=True\n if not self._validate_step_response(response1_data, 1, 4, True, \"pause_for_investigation\"):\n return False\n\n self.logger.info(f\" βœ… Step 1 successful, continuation_id: {continuation_id}\")\n\n # Step 2: Examine the code\n self.logger.info(\" 1.1.2: Step 2 - Code examination\")\n response2, _ = self.call_mcp_tool(\n \"debug\",\n {\n \"step\": \"Now examining the session_manager.py file to understand the cleanup_expired_sessions implementation and identify the root cause.\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Found the issue: cleanup_expired_sessions modifies self.active_sessions dictionary while iterating over it with .items(). This causes RuntimeError when del is called during iteration.\",\n \"files_checked\": [self.error_file, self.buggy_file],\n \"relevant_files\": [self.buggy_file],\n \"relevant_context\": [\"SessionManager.cleanup_expired_sessions\"],\n \"hypothesis\": \"Dictionary is being modified during iteration causing RuntimeError\",\n \"confidence\": \"high\",\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue investigation to step 2\")\n return False\n\n response2_data = self._parse_debug_response(response2)\n if not self._validate_step_response(response2_data, 2, 4, True, \"pause_for_investigation\"):\n return False\n\n # Check investigation status tracking\n investigation_status = response2_data.get(\"investigation_status\", {})\n if investigation_status.get(\"files_checked\", 0) < 2:\n self.logger.error(\"Files checked count not properly tracked\")\n return False\n\n if investigation_status.get(\"relevant_context\", 0) != 1:\n self.logger.error(\"Relevant context not properly tracked\")\n return False\n\n if investigation_status.get(\"current_confidence\") != \"high\":\n self.logger.error(\"Confidence level not properly tracked\")\n return False\n\n self.logger.info(\" βœ… Step 2 successful with proper tracking\")\n\n # Store continuation_id for next test\n self.investigation_continuation_id = continuation_id\n return True\n\n except Exception as e:\n self.logger.error(f\"Single investigation session test failed: {e}\")\n return False\n\n def _test_investigation_refine_flow(self) -> bool:\n \"\"\"Test investigation flow that requires refining the approach\"\"\"\n try:\n self.logger.info(\" 1.2: Testing investigation refinement workflow\")\n\n # Start a new investigation for testing refinement behaviour\n self.logger.info(\" 1.2.1: Start investigation for refinement test\")\n response1, continuation_id = self.call_mcp_tool(\n \"debug\",\n {\n \"step\": \"Investigating performance degradation in data processing pipeline\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Initial analysis shows slow database queries\",\n \"files_checked\": [\"/db/queries.py\"],\n \"relevant_files\": [\"/db/queries.py\"],\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start refinement test investigation\")\n return False\n\n # Step 2: Wrong direction\n self.logger.info(\" 1.2.2: Step 2 - Wrong investigation path\")\n response2, _ = self.call_mcp_tool(\n \"debug\",\n {\n \"step\": \"Focusing on database optimization strategies\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Database queries seem optimized, might be looking in wrong place\",\n \"files_checked\": [\"/db/queries.py\", \"/db/indexes.py\"],\n \"relevant_files\": [],\n \"hypothesis\": \"Database performance issues\",\n \"confidence\": \"low\",\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue to step 2\")\n return False\n\n # Step 3: Backtrack from step 2\n self.logger.info(\" 1.2.3: Step 3 - Refine investigation path\")\n response3, _ = self.call_mcp_tool(\n \"debug\",\n {\n \"step\": \"Refocusing - the issue might not be database related. Let me investigate the data processing algorithm instead.\",\n \"step_number\": 3,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Found inefficient nested loops in data processor causing O(nΒ²) complexity\",\n \"files_checked\": [\"/processor/algorithm.py\"],\n \"relevant_files\": [\"/processor/algorithm.py\"],\n \"relevant_context\": [\"DataProcessor.process_batch\"],\n \"hypothesis\": \"Inefficient algorithm causing performance issues\",\n \"confidence\": \"medium\",\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response3:\n self.logger.error(\"Failed to refine investigation\")\n return False\n\n response3_data = self._parse_debug_response(response3)\n if not self._validate_step_response(response3_data, 3, 4, True, \"pause_for_investigation\"):\n return False\n\n self.logger.info(\" βœ… Investigation refinement working correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Investigation refinement test failed: {e}\")\n return False\n\n def _test_complete_investigation_with_analysis(self) -> bool:\n \"\"\"Test complete investigation ending with expert analysis\"\"\"\n try:\n self.logger.info(\" 1.3: Testing complete investigation with expert analysis\")\n\n # Use the continuation from first test\n continuation_id = getattr(self, \"investigation_continuation_id\", None)\n if not continuation_id:\n # Start fresh if no continuation available\n self.logger.info(\" 1.3.0: Starting fresh investigation\")\n response0, continuation_id = self.call_mcp_tool(\n \"debug\",\n {\n \"step\": \"Investigating the dictionary iteration bug in session cleanup\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"findings\": \"Found dictionary modification during iteration\",\n \"files_checked\": [self.buggy_file],\n \"relevant_files\": [self.buggy_file],\n \"relevant_context\": [\"SessionManager.cleanup_expired_sessions\"],\n },\n )\n if not response0 or not continuation_id:\n self.logger.error(\"Failed to start fresh investigation\")\n return False\n\n # Final step - trigger expert analysis\n self.logger.info(\" 1.3.1: Final step - complete investigation\")\n response_final, _ = self.call_mcp_tool(\n \"debug\",\n {\n \"step\": \"Investigation complete. The root cause is confirmed: cleanup_expired_sessions modifies the dictionary while iterating, causing RuntimeError.\",\n \"step_number\": 2,\n \"total_steps\": 2,\n \"next_step_required\": False, # Final step - triggers expert analysis\n \"findings\": \"Root cause identified: del self.active_sessions[session_id] on line 46 modifies dictionary during iteration starting at line 44. Fix: collect expired IDs first, then delete.\",\n \"files_checked\": [self.buggy_file],\n \"relevant_files\": [self.buggy_file],\n \"relevant_context\": [\"SessionManager.cleanup_expired_sessions\"],\n \"hypothesis\": \"Dictionary modification during iteration causes RuntimeError in cleanup_expired_sessions\",\n \"confidence\": \"high\",\n \"continuation_id\": continuation_id,\n \"model\": \"flash\", # Use flash for expert analysis\n },\n )\n\n if not response_final:\n self.logger.error(\"Failed to complete investigation\")\n return False\n\n response_final_data = self._parse_debug_response(response_final)\n if not response_final_data:\n return False\n\n # Validate final response structure - expect calling_expert_analysis for next_step_required=False\n if response_final_data.get(\"status\") != \"calling_expert_analysis\":\n self.logger.error(\n f\"Expected status 'calling_expert_analysis', got '{response_final_data.get('status')}'\"\n )\n return False\n\n if not response_final_data.get(\"investigation_complete\"):\n self.logger.error(\"Expected investigation_complete=true for final step\")\n return False\n\n # Check for expert analysis\n if \"expert_analysis\" not in response_final_data:\n self.logger.error(\"Missing expert_analysis in final response\")\n return False\n\n expert_analysis = response_final_data.get(\"expert_analysis\", {})\n\n # Check for expected analysis content (checking common patterns)\n analysis_text = json.dumps(expert_analysis, ensure_ascii=False).lower()\n\n # Look for bug identification\n bug_indicators = [\"dictionary\", \"iteration\", \"modify\", \"runtime\", \"error\", \"del\"]\n found_indicators = sum(1 for indicator in bug_indicators if indicator in analysis_text)\n\n if found_indicators >= 3:\n self.logger.info(\" βœ… Expert analysis identified the bug correctly\")\n else:\n self.logger.warning(\n f\" ⚠️ Expert analysis may not have fully identified the bug (found {found_indicators}/6 indicators)\"\n )\n\n # Check complete investigation summary\n if \"complete_investigation\" not in response_final_data:\n self.logger.error(\"Missing complete_investigation in final response\")\n return False\n\n complete_investigation = response_final_data[\"complete_investigation\"]\n if not complete_investigation.get(\"relevant_context\"):\n self.logger.error(\"Missing relevant context in complete investigation\")\n return False\n\n if \"SessionManager.cleanup_expired_sessions\" not in complete_investigation[\"relevant_context\"]:\n self.logger.error(\"Expected method not found in investigation summary\")\n return False\n\n self.logger.info(\" βœ… Complete investigation with expert analysis successful\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Complete investigation test failed: {e}\")\n return False\n\n def _test_certain_confidence(self) -> bool:\n \"\"\"Test certain confidence behavior - should skip expert analysis\"\"\"\n try:\n self.logger.info(\" 1.4: Testing certain confidence behavior\")\n\n # Test certain confidence - should skip expert analysis\n self.logger.info(\" 1.4.1: Certain confidence investigation\")\n response_certain, _ = self.call_mcp_tool(\n \"debug\",\n {\n \"step\": \"I have confirmed the exact root cause with 100% certainty: dictionary modification during iteration.\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False, # Final step\n \"findings\": \"The bug is on line 44-47: for loop iterates over dict.items() while del modifies the dict inside the loop. Fix is simple: collect expired IDs first, then delete after iteration.\",\n \"files_checked\": [self.buggy_file],\n \"relevant_files\": [self.buggy_file],\n \"relevant_context\": [\"SessionManager.cleanup_expired_sessions\"],\n \"hypothesis\": \"Dictionary modification during iteration causes RuntimeError - fix is straightforward\",\n \"confidence\": \"certain\", # This should skip expert analysis\n \"model\": \"flash\",\n },\n )\n\n if not response_certain:\n self.logger.error(\"Failed to test certain confidence\")\n return False\n\n response_certain_data = self._parse_debug_response(response_certain)\n if not response_certain_data:\n return False\n\n # Validate certain confidence response - should skip expert analysis\n if response_certain_data.get(\"status\") != \"certain_confidence_proceed_with_fix\":\n self.logger.error(\n f\"Expected status 'certain_confidence_proceed_with_fix', got '{response_certain_data.get('status')}'\"\n )\n return False\n\n if not response_certain_data.get(\"skip_expert_analysis\"):\n self.logger.error(\"Expected skip_expert_analysis=true for certain confidence\")\n return False\n\n expert_analysis = response_certain_data.get(\"expert_analysis\", {})\n if expert_analysis.get(\"status\") != \"skipped_due_to_certain_confidence\":\n self.logger.error(\"Expert analysis should be skipped for certain confidence\")\n return False\n\n self.logger.info(\" βœ… Certain confidence behavior working correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Certain confidence test failed: {e}\")\n return False\n\n def call_mcp_tool(self, tool_name: str, params: dict) -> tuple[Optional[str], Optional[str]]:\n \"\"\"Call an MCP tool in-process - override for debug-specific response handling\"\"\"\n # Use in-process implementation to maintain conversation memory\n response_text, _ = self.call_mcp_tool_direct(tool_name, params)\n\n if not response_text:\n return None, None\n\n # Extract continuation_id from debug response specifically\n continuation_id = self._extract_debug_continuation_id(response_text)\n\n return response_text, continuation_id\n\n def _extract_debug_continuation_id(self, response_text: str) -> Optional[str]:\n \"\"\"Extract continuation_id from debug response\"\"\"\n try:\n # Parse the response\n response_data = json.loads(response_text)\n return response_data.get(\"continuation_id\")\n\n except json.JSONDecodeError as e:\n self.logger.debug(f\"Failed to parse response for debug continuation_id: {e}\")\n return None\n\n def _parse_debug_response(self, response_text: str) -> dict:\n \"\"\"Parse debug tool JSON response\"\"\"\n try:\n # Parse the response - it should be direct JSON\n return json.loads(response_text)\n\n except json.JSONDecodeError as e:\n self.logger.error(f\"Failed to parse debug response as JSON: {e}\")\n self.logger.error(f\"Response text: {response_text[:500]}...\")\n return {}\n\n def _validate_step_response(\n self,\n response_data: dict,\n expected_step: int,\n expected_total: int,\n expected_next_required: bool,\n expected_status: str,\n ) -> bool:\n \"\"\"Validate a debug investigation step response structure\"\"\"\n try:\n # Check status\n if response_data.get(\"status\") != expected_status:\n self.logger.error(f\"Expected status '{expected_status}', got '{response_data.get('status')}'\")\n return False\n\n # Check step number\n if response_data.get(\"step_number\") != expected_step:\n self.logger.error(f\"Expected step_number {expected_step}, got {response_data.get('step_number')}\")\n return False\n\n # Check total steps\n if response_data.get(\"total_steps\") != expected_total:\n self.logger.error(f\"Expected total_steps {expected_total}, got {response_data.get('total_steps')}\")\n return False\n\n # Check next_step_required\n if response_data.get(\"next_step_required\") != expected_next_required:\n self.logger.error(\n f\"Expected next_step_required {expected_next_required}, got {response_data.get('next_step_required')}\"\n )\n return False\n\n # Check investigation_status exists\n if \"investigation_status\" not in response_data:\n self.logger.error(\"Missing investigation_status in response\")\n return False\n\n # Check next_steps guidance\n if not response_data.get(\"next_steps\"):\n self.logger.error(\"Missing next_steps guidance in response\")\n return False\n\n return True\n\n except Exception as e:\n self.logger.error(f\"Error validating step response: {e}\")\n return False\n\n def _test_context_aware_file_embedding(self) -> bool:\n \"\"\"Test context-aware file embedding optimization\"\"\"\n try:\n self.logger.info(\" 1.5: Testing context-aware file embedding\")\n\n # Create multiple test files for context testing\n file1_content = \"\"\"#!/usr/bin/env python3\ndef process_data(data):\n \\\"\\\"\\\"Process incoming data\\\"\\\"\\\"\n result = []\n for item in data:\n if item.get('valid'):\n result.append(item['value'])\n return result\n\"\"\"\n\n file2_content = \"\"\"#!/usr/bin/env python3\ndef validate_input(data):\n \\\"\\\"\\\"Validate input data\\\"\\\"\\\"\n if not isinstance(data, list):\n raise ValueError(\"Data must be a list\")\n\n for item in data:\n if not isinstance(item, dict):\n raise ValueError(\"Items must be dictionaries\")\n if 'value' not in item:\n raise ValueError(\"Items must have 'value' key\")\n\n return True\n\"\"\"\n\n # Create test files\n file1 = self.create_additional_test_file(\"data_processor.py\", file1_content)\n file2 = self.create_additional_test_file(\"validator.py\", file2_content)\n\n # Test 1: New conversation, intermediate step - should only reference files\n self.logger.info(\" 1.5.1: New conversation intermediate step (should reference only)\")\n response1, continuation_id = self.call_mcp_tool(\n \"debug\",\n {\n \"step\": \"Starting investigation of data processing pipeline\",\n \"step_number\": 1,\n \"total_steps\": 3,\n \"next_step_required\": True, # Intermediate step\n \"findings\": \"Initial analysis of data processing components\",\n \"files_checked\": [file1, file2],\n \"relevant_files\": [file1], # This should be referenced, not embedded\n \"relevant_context\": [\"process_data\"],\n \"hypothesis\": \"Investigating data flow\",\n \"confidence\": \"low\",\n \"model\": \"flash\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start context-aware file embedding test\")\n return False\n\n response1_data = self._parse_debug_response(response1)\n if not response1_data:\n return False\n\n # Check file context - should be reference_only for intermediate step\n file_context = response1_data.get(\"file_context\", {})\n if file_context.get(\"type\") != \"reference_only\":\n self.logger.error(f\"Expected reference_only file context, got: {file_context.get('type')}\")\n return False\n\n if \"Files referenced but not embedded\" not in file_context.get(\"context_optimization\", \"\"):\n self.logger.error(\"Expected context optimization message for reference_only\")\n return False\n\n self.logger.info(\" βœ… Intermediate step correctly uses reference_only file context\")\n\n # Test 2: Intermediate step with continuation - should still only reference\n self.logger.info(\" 1.5.2: Intermediate step with continuation (should reference only)\")\n response2, _ = self.call_mcp_tool(\n \"debug\",\n {\n \"step\": \"Continuing investigation with more detailed analysis\",\n \"step_number\": 2,\n \"total_steps\": 3,\n \"next_step_required\": True, # Still intermediate\n \"continuation_id\": continuation_id,\n \"findings\": \"Found potential issues in validation logic\",\n \"files_checked\": [file1, file2],\n \"relevant_files\": [file1, file2], # Both files referenced\n \"relevant_context\": [\"process_data\", \"validate_input\"],\n \"hypothesis\": \"Validation might be too strict\",\n \"confidence\": \"medium\",\n \"model\": \"flash\",\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue to step 2\")\n return False\n\n response2_data = self._parse_debug_response(response2)\n if not response2_data:\n return False\n\n # Check file context - should still be reference_only\n file_context2 = response2_data.get(\"file_context\", {})\n if file_context2.get(\"type\") != \"reference_only\":\n self.logger.error(f\"Expected reference_only file context for step 2, got: {file_context2.get('type')}\")\n return False\n\n # Should include reference note\n if not file_context2.get(\"note\"):\n self.logger.error(\"Expected file reference note for intermediate step\")\n return False\n\n reference_note = file_context2.get(\"note\", \"\")\n if \"data_processor.py\" not in reference_note or \"validator.py\" not in reference_note:\n self.logger.error(\"File reference note should mention both files\")\n return False\n\n self.logger.info(\" βœ… Intermediate step with continuation correctly uses reference_only\")\n\n # Test 3: Final step - should embed files for expert analysis\n self.logger.info(\" 1.5.3: Final step (should embed files)\")\n response3, _ = self.call_mcp_tool(\n \"debug\",\n {\n \"step\": \"Investigation complete - identified the root cause\",\n \"step_number\": 3,\n \"total_steps\": 3,\n \"next_step_required\": False, # Final step - should embed files\n \"continuation_id\": continuation_id,\n \"findings\": \"Root cause: validator is rejecting valid data due to strict type checking\",\n \"files_checked\": [file1, file2],\n \"relevant_files\": [file1, file2], # Should be fully embedded\n \"relevant_context\": [\"process_data\", \"validate_input\"],\n \"hypothesis\": \"Validation logic is too restrictive for valid edge cases\",\n \"confidence\": \"high\",\n \"model\": \"flash\",\n },\n )\n\n if not response3:\n self.logger.error(\"Failed to complete to final step\")\n return False\n\n response3_data = self._parse_debug_response(response3)\n if not response3_data:\n return False\n\n # Check file context - should be fully_embedded for final step\n file_context3 = response3_data.get(\"file_context\", {})\n if file_context3.get(\"type\") != \"fully_embedded\":\n self.logger.error(\n f\"Expected fully_embedded file context for final step, got: {file_context3.get('type')}\"\n )\n return False\n\n if \"Full file content embedded for expert analysis\" not in file_context3.get(\"context_optimization\", \"\"):\n self.logger.error(\"Expected expert analysis optimization message for fully_embedded\")\n return False\n\n # Should show files embedded count\n files_embedded = file_context3.get(\"files_embedded\", 0)\n if files_embedded == 0:\n # This is OK - files might already be in conversation history\n self.logger.info(\n \" ℹ️ Files embedded count is 0 - files already in conversation history (smart deduplication)\"\n )\n else:\n self.logger.info(f\" βœ… Files embedded count: {files_embedded}\")\n\n self.logger.info(\" βœ… Final step correctly uses fully_embedded file context\")\n\n # Verify expert analysis was called for final step\n if response3_data.get(\"status\") != \"calling_expert_analysis\":\n self.logger.error(\"Final step should trigger expert analysis\")\n return False\n\n if \"expert_analysis\" not in response3_data:\n self.logger.error(\"Expert analysis should be present in final step\")\n return False\n\n self.logger.info(\" βœ… Context-aware file embedding test completed successfully\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Context-aware file embedding test failed: {e}\")\n return False\n\n def _test_multi_step_file_context(self) -> bool:\n \"\"\"Test multi-step workflow with proper file context transitions\"\"\"\n try:\n self.logger.info(\" 1.6: Testing multi-step file context optimization\")\n\n # Create a complex scenario with multiple files\n config_content = \"\"\"#!/usr/bin/env python3\nimport os\n\nDATABASE_URL = os.getenv('DATABASE_URL', 'sqlite:///app.db')\nDEBUG_MODE = os.getenv('DEBUG', 'False').lower() == 'true'\nMAX_CONNECTIONS = int(os.getenv('MAX_CONNECTIONS', '10'))\n\n# Bug: This will cause issues when MAX_CONNECTIONS is not a valid integer\nCACHE_SIZE = MAX_CONNECTIONS * 2 # Problematic if MAX_CONNECTIONS is invalid\n\"\"\"\n\n server_content = \"\"\"#!/usr/bin/env python3\nfrom config import DATABASE_URL, DEBUG_MODE, CACHE_SIZE\nimport sqlite3\n\nclass DatabaseServer:\n def __init__(self):\n self.connection_pool = []\n self.cache_size = CACHE_SIZE # This will fail if CACHE_SIZE is invalid\n\n def connect(self):\n try:\n conn = sqlite3.connect(DATABASE_URL)\n self.connection_pool.append(conn)\n return conn\n except Exception as e:\n print(f\"Connection failed: {e}\")\n return None\n\"\"\"\n\n # Create test files\n config_file = self.create_additional_test_file(\"config.py\", config_content)\n server_file = self.create_additional_test_file(\"database_server.py\", server_content)\n\n # Step 1: Start investigation (new conversation)\n self.logger.info(\" 1.6.1: Step 1 - Start investigation\")\n response1, continuation_id = self.call_mcp_tool(\n \"debug\",\n {\n \"step\": \"Investigating application startup failures in production environment\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Application fails to start with configuration errors\",\n \"files_checked\": [config_file],\n \"relevant_files\": [config_file],\n \"relevant_context\": [],\n \"hypothesis\": \"Configuration issue causing startup failure\",\n \"confidence\": \"low\",\n \"model\": \"flash\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start multi-step file context test\")\n return False\n\n response1_data = self._parse_debug_response(response1)\n\n # Validate step 1 - should use reference_only\n file_context1 = response1_data.get(\"file_context\", {})\n if file_context1.get(\"type\") != \"reference_only\":\n self.logger.error(\"Step 1 should use reference_only file context\")\n return False\n\n self.logger.info(\" βœ… Step 1: reference_only file context\")\n\n # Step 2: Expand investigation\n self.logger.info(\" 1.6.2: Step 2 - Expand investigation\")\n response2, _ = self.call_mcp_tool(\n \"debug\",\n {\n \"step\": \"Found configuration issue - investigating database server initialization\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"continuation_id\": continuation_id,\n \"findings\": \"MAX_CONNECTIONS environment variable contains invalid value, causing CACHE_SIZE calculation to fail\",\n \"files_checked\": [config_file, server_file],\n \"relevant_files\": [config_file, server_file],\n \"relevant_context\": [\"DatabaseServer.__init__\"],\n \"hypothesis\": \"Invalid environment variable causing integer conversion error\",\n \"confidence\": \"medium\",\n \"model\": \"flash\",\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue to step 2\")\n return False\n\n response2_data = self._parse_debug_response(response2)\n\n # Validate step 2 - should still use reference_only\n file_context2 = response2_data.get(\"file_context\", {})\n if file_context2.get(\"type\") != \"reference_only\":\n self.logger.error(\"Step 2 should use reference_only file context\")\n return False\n\n # Should reference both files\n reference_note = file_context2.get(\"note\", \"\")\n if \"config.py\" not in reference_note or \"database_server.py\" not in reference_note:\n self.logger.error(\"Step 2 should reference both files in note\")\n return False\n\n self.logger.info(\" βœ… Step 2: reference_only file context with multiple files\")\n\n # Step 3: Deep analysis\n self.logger.info(\" 1.6.3: Step 3 - Deep analysis\")\n response3, _ = self.call_mcp_tool(\n \"debug\",\n {\n \"step\": \"Analyzing the exact error propagation path and impact\",\n \"step_number\": 3,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"continuation_id\": continuation_id,\n \"findings\": \"Error occurs in config.py line 8 when MAX_CONNECTIONS is not numeric, then propagates to DatabaseServer.__init__\",\n \"files_checked\": [config_file, server_file],\n \"relevant_files\": [config_file, server_file],\n \"relevant_context\": [\"DatabaseServer.__init__\"],\n \"hypothesis\": \"Need proper error handling and validation for environment variables\",\n \"confidence\": \"high\",\n \"model\": \"flash\",\n },\n )\n\n if not response3:\n self.logger.error(\"Failed to continue to step 3\")\n return False\n\n response3_data = self._parse_debug_response(response3)\n\n # Validate step 3 - should still use reference_only\n file_context3 = response3_data.get(\"file_context\", {})\n if file_context3.get(\"type\") != \"reference_only\":\n self.logger.error(\"Step 3 should use reference_only file context\")\n return False\n\n self.logger.info(\" βœ… Step 3: reference_only file context\")\n\n # Step 4: Final analysis with expert consultation\n self.logger.info(\" 1.6.4: Step 4 - Final step with expert analysis\")\n response4, _ = self.call_mcp_tool(\n \"debug\",\n {\n \"step\": \"Investigation complete - root cause identified with solution\",\n \"step_number\": 4,\n \"total_steps\": 4,\n \"next_step_required\": False, # Final step - should embed files\n \"continuation_id\": continuation_id,\n \"findings\": \"Root cause: config.py assumes MAX_CONNECTIONS env var is always a valid integer. Fix: add try/except with default value and proper validation.\",\n \"files_checked\": [config_file, server_file],\n \"relevant_files\": [config_file, server_file],\n \"relevant_context\": [\"DatabaseServer.__init__\"],\n \"hypothesis\": \"Environment variable validation needed with proper error handling\",\n \"confidence\": \"high\",\n \"model\": \"flash\",\n },\n )\n\n if not response4:\n self.logger.error(\"Failed to complete to final step\")\n return False\n\n response4_data = self._parse_debug_response(response4)\n\n # Validate step 4 - should use fully_embedded for expert analysis\n file_context4 = response4_data.get(\"file_context\", {})\n if file_context4.get(\"type\") != \"fully_embedded\":\n self.logger.error(\"Step 4 (final) should use fully_embedded file context\")\n return False\n\n if \"expert analysis\" not in file_context4.get(\"context_optimization\", \"\").lower():\n self.logger.error(\"Final step should mention expert analysis in context optimization\")\n return False\n\n # Verify expert analysis was triggered\n if response4_data.get(\"status\") != \"calling_expert_analysis\":\n self.logger.error(\"Final step should trigger expert analysis\")\n return False\n\n # Check that expert analysis has file context\n expert_analysis = response4_data.get(\"expert_analysis\", {})\n if not expert_analysis:\n self.logger.error(\"Expert analysis should be present in final step\")\n return False\n\n self.logger.info(\" βœ… Step 4: fully_embedded file context with expert analysis\")\n\n # Validate the complete workflow progression\n progression_summary = {\n \"step_1\": \"reference_only (new conversation, intermediate)\",\n \"step_2\": \"reference_only (continuation, intermediate)\",\n \"step_3\": \"reference_only (continuation, intermediate)\",\n \"step_4\": \"fully_embedded (continuation, final)\",\n }\n\n self.logger.info(\" πŸ“‹ File context progression:\")\n for step, context_type in progression_summary.items():\n self.logger.info(f\" {step}: {context_type}\")\n\n self.logger.info(\" βœ… Multi-step file context optimization test completed successfully\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Multi-step file context test failed: {e}\")\n return False\n" }, { "path": "simulator_tests/test_line_number_validation.py", "content": "\"\"\"\nTest to validate line number handling across different tools\n\"\"\"\n\nimport json\nimport os\n\nfrom .base_test import BaseSimulatorTest\n\n\nclass LineNumberValidationTest(BaseSimulatorTest):\n \"\"\"Test that validates correct line number handling in chat, analyze, and refactor tools\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"line_number_validation\"\n\n @property\n def test_description(self) -> str:\n return \"Line number handling validation across tools\"\n\n def run_test(self) -> bool:\n \"\"\"Test line number handling in different tools\"\"\"\n try:\n self.logger.info(\"Test: Line number handling validation\")\n\n # Setup test files\n self.setup_test_files()\n\n # Create a test file with known content\n test_file_content = '''# Example code with specific elements\ndef calculate_total(items):\n \"\"\"Calculate total with tax\"\"\"\n subtotal = 0\n tax_rate = 0.08 # Line 5 - tax_rate defined\n\n for item in items: # Line 7 - loop starts\n if item.price > 0:\n subtotal += item.price\n\n tax_amount = subtotal * tax_rate # Line 11\n return subtotal + tax_amount\n\ndef validate_data(data):\n \"\"\"Validate input data\"\"\" # Line 15\n required_fields = [\"name\", \"email\", \"age\"] # Line 16\n\n for field in required_fields:\n if field not in data:\n raise ValueError(f\"Missing field: {field}\")\n\n return True # Line 22\n'''\n\n test_file_path = os.path.join(self.test_dir, \"line_test.py\")\n with open(test_file_path, \"w\") as f:\n f.write(test_file_content)\n\n self.logger.info(f\"Created test file: {test_file_path}\")\n\n # Test 1: Chat tool asking about specific line\n self.logger.info(\" 1.1: Testing chat tool with line number question\")\n content, continuation_id = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Where is tax_rate defined in this file? Please tell me the exact line number.\",\n \"absolute_file_paths\": [test_file_path],\n \"model\": \"flash\",\n },\n )\n\n if content:\n # Check if the response mentions line 5\n if \"line 5\" in content.lower() or \"line 5\" in content:\n self.logger.info(\" βœ… Chat tool correctly identified tax_rate at line 5\")\n else:\n self.logger.warning(f\" ⚠️ Chat tool response didn't mention line 5: {content[:200]}...\")\n else:\n self.logger.error(\" ❌ Chat tool request failed\")\n return False\n\n # Test 2: Analyze tool with line number reference\n self.logger.info(\" 1.2: Testing analyze tool with line number analysis\")\n content, continuation_id = self.call_mcp_tool(\n \"analyze\",\n {\n \"prompt\": \"What happens between lines 7-11 in this code? Focus on the loop logic.\",\n \"absolute_file_paths\": [test_file_path],\n \"model\": \"flash\",\n },\n )\n\n if content:\n # Check if the response references the loop\n if any(term in content.lower() for term in [\"loop\", \"iterate\", \"line 7\", \"lines 7\"]):\n self.logger.info(\" βœ… Analyze tool correctly analyzed the specified line range\")\n else:\n self.logger.warning(\" ⚠️ Analyze tool response unclear about line range\")\n else:\n self.logger.error(\" ❌ Analyze tool request failed\")\n return False\n\n # Test 3: Refactor tool with line number precision\n self.logger.info(\" 1.3: Testing refactor tool line number precision\")\n content, continuation_id = self.call_mcp_tool(\n \"refactor\",\n {\n \"prompt\": \"Analyze this code for refactoring opportunities\",\n \"absolute_file_paths\": [test_file_path],\n \"refactor_type\": \"codesmells\",\n \"model\": \"flash\",\n },\n )\n\n if content:\n try:\n # Parse the JSON response\n result = json.loads(content)\n if result.get(\"status\") == \"refactor_analysis_complete\":\n opportunities = result.get(\"refactor_opportunities\", [])\n if opportunities:\n # Check if line numbers are precise\n has_line_refs = any(\n opp.get(\"start_line\") is not None and opp.get(\"end_line\") is not None\n for opp in opportunities\n )\n if has_line_refs:\n self.logger.info(\" βœ… Refactor tool provided precise line number references\")\n # Log some examples\n for opp in opportunities[:2]:\n if opp.get(\"start_line\"):\n self.logger.info(\n f\" - Issue at lines {opp['start_line']}-{opp['end_line']}: {opp.get('issue', '')[:50]}...\"\n )\n else:\n self.logger.warning(\" ⚠️ Refactor tool response missing line numbers\")\n else:\n self.logger.info(\" ℹ️ No refactoring opportunities found (code might be too clean)\")\n except json.JSONDecodeError:\n self.logger.warning(\" ⚠️ Refactor tool response not valid JSON\")\n else:\n self.logger.error(\" ❌ Refactor tool request failed\")\n return False\n\n # Test 4: Validate log patterns\n self.logger.info(\" 1.4: Validating line number processing in logs\")\n\n # Get logs from server\n try:\n log_file_path = \"logs/mcp_server.log\"\n with open(log_file_path) as f:\n lines = f.readlines()\n logs = \"\".join(lines[-500:])\n except Exception as e:\n self.logger.error(f\"Failed to read server logs: {e}\")\n logs = \"\"\n pass\n\n # Check for line number formatting patterns\n line_number_patterns = [\"Line numbers for\", \"enabled\", \"β”‚\", \"line number\"] # The line number separator\n\n found_patterns = 0\n for pattern in line_number_patterns:\n if pattern in logs:\n found_patterns += 1\n\n self.logger.info(f\" Found {found_patterns}/{len(line_number_patterns)} line number patterns in logs\")\n\n if found_patterns >= 2:\n self.logger.info(\" βœ… Line number processing confirmed in logs\")\n else:\n self.logger.warning(\" ⚠️ Limited line number processing evidence in logs\")\n\n self.logger.info(\" βœ… Line number validation test completed successfully\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Line number validation test failed: {type(e).__name__}: {e}\")\n return False\n" }, { "path": "simulator_tests/test_logs_validation.py", "content": "#!/usr/bin/env python3\n\"\"\"\nServer Logs Validation Test\n\nValidates server logs to confirm file deduplication behavior and\nconversation threading is working properly.\n\"\"\"\n\nfrom .base_test import BaseSimulatorTest\n\n\nclass LogsValidationTest(BaseSimulatorTest):\n \"\"\"Validate server logs to confirm file deduplication behavior\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"logs_validation\"\n\n @property\n def test_description(self) -> str:\n return \"Server logs validation\"\n\n def run_test(self) -> bool:\n \"\"\"Validate server logs to confirm file deduplication behavior\"\"\"\n try:\n self.logger.info(\"πŸ“‹ Test: Validating server logs for file deduplication...\")\n\n # Get server logs from log files\n import os\n\n logs = \"\"\n log_files = [\"logs/mcp_server.log\", \"logs/mcp_activity.log\"]\n\n for log_file in log_files:\n if os.path.exists(log_file):\n try:\n with open(log_file) as f:\n file_content = f.read()\n logs += f\"\\n=== {log_file} ===\\n{file_content}\\n\"\n self.logger.debug(f\"Read {len(file_content)} characters from {log_file}\")\n except Exception as e:\n self.logger.warning(f\"Could not read {log_file}: {e}\")\n else:\n self.logger.warning(f\"Log file not found: {log_file}\")\n\n if not logs.strip():\n self.logger.warning(\"No log content found - server may not have processed any requests yet\")\n return False\n\n # Look for conversation threading patterns that indicate the system is working\n conversation_patterns = [\n \"CONVERSATION_RESUME\",\n \"CONVERSATION_CONTEXT\",\n \"previous turns loaded\",\n \"tool embedding\",\n \"files included\",\n \"files truncated\",\n \"already in conversation history\",\n ]\n\n conversation_lines = []\n for line in logs.split(\"\\n\"):\n for pattern in conversation_patterns:\n if pattern.lower() in line.lower():\n conversation_lines.append(line.strip())\n break\n\n # Look for evidence of conversation threading and file handling\n conversation_threading_found = False\n multi_turn_conversations = False\n\n for line in conversation_lines:\n lower_line = line.lower()\n if \"conversation_resume\" in lower_line:\n conversation_threading_found = True\n self.logger.debug(f\"πŸ“„ Conversation threading: {line}\")\n elif \"previous turns loaded\" in lower_line:\n multi_turn_conversations = True\n self.logger.debug(f\"πŸ“„ Multi-turn conversation: {line}\")\n elif \"already in conversation\" in lower_line:\n self.logger.info(f\"βœ… Found explicit deduplication: {line}\")\n return True\n\n # Conversation threading with multiple turns is evidence of file deduplication working\n if conversation_threading_found and multi_turn_conversations:\n self.logger.info(\"βœ… Conversation threading with multi-turn context working\")\n self.logger.info(\n \"βœ… File deduplication working implicitly (files embedded once in conversation history)\"\n )\n return True\n elif conversation_threading_found:\n self.logger.info(\"βœ… Conversation threading detected\")\n return True\n else:\n self.logger.warning(\"⚠️ No clear evidence of conversation threading in logs\")\n self.logger.debug(f\"Found {len(conversation_lines)} conversation-related log lines\")\n return False\n\n except Exception as e:\n self.logger.error(f\"Log validation failed: {e}\")\n return False\n" }, { "path": "simulator_tests/test_model_thinking_config.py", "content": "#!/usr/bin/env python3\n\"\"\"\nModel Thinking Configuration Test\n\nTests that thinking configuration is properly applied only to models that support it,\nand that Flash models work correctly without thinking config.\n\"\"\"\n\nfrom .base_test import BaseSimulatorTest\n\n\nclass TestModelThinkingConfig(BaseSimulatorTest):\n \"\"\"Test model-specific thinking configuration behavior\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"model_thinking_config\"\n\n @property\n def test_description(self) -> str:\n return \"Model-specific thinking configuration behavior\"\n\n def test_pro_model_with_thinking_config(self):\n \"\"\"Test that Pro model uses thinking configuration\"\"\"\n self.logger.info(\"Testing Pro model with thinking configuration...\")\n\n try:\n # Test with explicit pro model and high thinking mode\n response, continuation_id = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"What is 2 + 2? Please think carefully and explain.\",\n \"model\": \"pro\", # Should resolve to gemini-2.5-pro\n \"thinking_mode\": \"high\", # Should use thinking_config\n },\n )\n\n if not response:\n raise Exception(\"Pro model test failed: No response received\")\n\n self.logger.info(\"βœ… Pro model with thinking config works correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\"❌ Pro model test failed: {e}\")\n return False\n\n def test_flash_model_without_thinking_config(self):\n \"\"\"Test that Flash model works without thinking configuration\"\"\"\n self.logger.info(\"Testing Flash model without thinking configuration...\")\n\n try:\n # Test with explicit flash model and thinking mode (should be ignored)\n response, continuation_id = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"What is 3 + 3? Give a quick answer.\",\n \"model\": \"flash\", # Should resolve to gemini-2.5-flash\n \"thinking_mode\": \"high\", # Should be ignored for Flash model\n },\n )\n\n if not response:\n raise Exception(\"Flash model test failed: No response received\")\n\n self.logger.info(\"βœ… Flash model without thinking config works correctly\")\n return True\n\n except Exception as e:\n if \"thinking\" in str(e).lower() and (\"not supported\" in str(e).lower() or \"invalid\" in str(e).lower()):\n raise Exception(f\"Flash model incorrectly tried to use thinking config: {e}\")\n self.logger.error(f\"❌ Flash model test failed: {e}\")\n return False\n\n def test_model_resolution_logic(self):\n \"\"\"Test that model resolution works correctly for both shortcuts and full names\"\"\"\n self.logger.info(\"Testing model resolution logic...\")\n\n test_cases = [\n (\"pro\", \"should work with Pro model\"),\n (\"flash\", \"should work with Flash model\"),\n (\"gemini-2.5-pro\", \"should work with full Pro model name\"),\n (\"gemini-2.5-flash\", \"should work with full Flash model name\"),\n ]\n\n success_count = 0\n\n for model_name, description in test_cases:\n try:\n response, continuation_id = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": f\"Test with {model_name}: What is 1 + 1?\",\n \"model\": model_name,\n \"thinking_mode\": \"medium\",\n },\n )\n\n if not response:\n raise Exception(f\"No response received for model {model_name}\")\n\n self.logger.info(f\"βœ… {model_name} {description}\")\n success_count += 1\n\n except Exception as e:\n self.logger.error(f\"❌ {model_name} failed: {e}\")\n return False\n\n return success_count == len(test_cases)\n\n def test_default_model_behavior(self):\n \"\"\"Test behavior with server default model (no explicit model specified)\"\"\"\n self.logger.info(\"Testing default model behavior...\")\n\n try:\n # Test without specifying model (should use server default)\n response, continuation_id = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Test default model: What is 4 + 4?\",\n # No model specified - should use DEFAULT_MODEL from config\n \"thinking_mode\": \"medium\",\n },\n )\n\n if not response:\n raise Exception(\"Default model test failed: No response received\")\n\n self.logger.info(\"βœ… Default model behavior works correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\"❌ Default model test failed: {e}\")\n return False\n\n def run_test(self) -> bool:\n \"\"\"Run all model thinking configuration tests\"\"\"\n self.logger.info(f\" Test: {self.test_description}\")\n\n try:\n # Test Pro model with thinking config\n if not self.test_pro_model_with_thinking_config():\n return False\n\n # Test Flash model without thinking config\n if not self.test_flash_model_without_thinking_config():\n return False\n\n # Test model resolution logic\n if not self.test_model_resolution_logic():\n return False\n\n # Test default model behavior\n if not self.test_default_model_behavior():\n return False\n\n self.logger.info(f\"βœ… All {self.test_name} tests passed!\")\n return True\n\n except Exception as e:\n self.logger.error(f\"❌ {self.test_name} test failed: {e}\")\n return False\n\n\ndef main():\n \"\"\"Run the model thinking configuration tests\"\"\"\n import sys\n\n verbose = \"--verbose\" in sys.argv or \"-v\" in sys.argv\n test = TestModelThinkingConfig(verbose=verbose)\n\n success = test.run_test()\n sys.exit(0 if success else 1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "simulator_tests/test_o3_model_selection.py", "content": "#!/usr/bin/env python3\n\"\"\"\nO3 Model Selection Test\n\nTests that O3 models are properly selected and used when explicitly specified,\nregardless of the default model configuration (even when set to auto).\nValidates model selection via server logs.\n\"\"\"\n\nimport datetime\n\nfrom .base_test import BaseSimulatorTest\n\n\nclass O3ModelSelectionTest(BaseSimulatorTest):\n \"\"\"Test O3 model selection and usage\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"o3_model_selection\"\n\n @property\n def test_description(self) -> str:\n return \"O3 model selection and usage validation\"\n\n def run_test(self) -> bool:\n \"\"\"Test O3 model selection and usage\"\"\"\n try:\n self.logger.info(\" Test: O3 model selection and usage validation\")\n\n # Check which API keys are configured\n import os\n\n has_openai = bool(os.environ.get(\"OPENAI_API_KEY\"))\n has_openrouter = bool(os.environ.get(\"OPENROUTER_API_KEY\"))\n\n # If only OpenRouter is configured, adjust test expectations\n if has_openrouter and not has_openai:\n self.logger.info(\" ℹ️ Only OpenRouter configured - O3 models will be routed through OpenRouter\")\n return self._run_openrouter_o3_test()\n\n # If neither OpenAI nor OpenRouter is configured, skip the test\n if not has_openai and not has_openrouter:\n self.logger.info(\" ⚠️ Neither OpenAI nor OpenRouter API keys configured - skipping test\")\n self.logger.info(\n \" ℹ️ This test requires either OPENAI_API_KEY or OPENROUTER_API_KEY to be set in .env\"\n )\n self.logger.info(\" βœ… Test skipped (no API keys configured)\")\n return True # Return True to indicate test passed/skipped\n\n # Original test for when OpenAI is configured\n self.logger.info(\" ℹ️ OpenAI API configured - expecting direct OpenAI API calls\")\n\n # Setup test files for later use\n self.setup_test_files()\n\n # Get timestamp for log filtering\n datetime.datetime.now().strftime(\"%Y-%m-%dT%H:%M:%S\")\n\n # Test 1: Explicit O3 model selection\n self.logger.info(\" 1: Testing explicit O3 model selection\")\n\n response1, _ = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Simple test: What is 2 + 2? Just give a brief answer.\",\n \"model\": \"o3\",\n \"temperature\": 1.0, # O3 only supports default temperature of 1.0\n },\n )\n\n if not response1:\n self.logger.error(\" ❌ O3 model test failed\")\n return False\n\n self.logger.info(\" βœ… O3 model call completed\")\n\n # Test 2: Explicit O3-mini model selection\n self.logger.info(\" 2: Testing explicit O3-mini model selection\")\n\n response2, _ = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Simple test: What is 3 + 3? Just give a brief answer.\",\n \"model\": \"o3-mini\",\n \"temperature\": 1.0, # O3-mini only supports default temperature of 1.0\n },\n )\n\n if not response2:\n self.logger.error(\" ❌ O3-mini model test failed\")\n return False\n\n self.logger.info(\" βœ… O3-mini model call completed\")\n\n # Test 3: Another tool with O3 to ensure it works across tools\n self.logger.info(\" 3: Testing O3 with different tool (codereview)\")\n\n # Create a simple test file\n test_code = \"\"\"def add(a, b):\n return a + b\n\ndef multiply(x, y):\n return x * y\n\"\"\"\n test_file = self.create_additional_test_file(\"simple_math.py\", test_code)\n\n response3, _ = self.call_mcp_tool(\n \"codereview\",\n {\n \"step\": \"Review this simple code for quality and potential issues\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Starting code review analysis\",\n \"relevant_files\": [test_file],\n \"model\": \"o3\",\n \"temperature\": 1.0, # O3 only supports default temperature of 1.0\n },\n )\n\n if not response3:\n self.logger.error(\" ❌ O3 with codereview tool failed\")\n return False\n\n self.logger.info(\" βœ… O3 with codereview tool completed\")\n\n # Validate model usage from server logs\n self.logger.info(\" 4: Validating model usage in logs\")\n logs = self.get_recent_server_logs()\n\n # Check for OpenAI API calls (this proves O3 models are being used)\n openai_api_logs = [line for line in logs.split(\"\\n\") if \"Sending request to openai API for\" in line]\n\n # Check for OpenAI model usage logs\n openai_model_logs = [\n line for line in logs.split(\"\\n\") if \"Using model:\" in line and \"openai provider\" in line\n ]\n\n # Check for successful OpenAI responses\n openai_response_logs = [\n line for line in logs.split(\"\\n\") if \"openai provider\" in line and \"Using model:\" in line\n ]\n\n # Check that we have both chat and codereview tool calls to OpenAI\n chat_openai_logs = [line for line in logs.split(\"\\n\") if \"Sending request to openai API for chat\" in line]\n\n codereview_openai_logs = [\n line for line in logs.split(\"\\n\") if \"Sending request to openai API for codereview\" in line\n ]\n\n # Validation criteria - check for OpenAI usage evidence (more flexible than exact counts)\n openai_api_called = len(openai_api_logs) >= 1 # Should see at least 1 OpenAI API call\n openai_model_usage = len(openai_model_logs) >= 1 # Should see at least 1 model usage log\n openai_responses_received = len(openai_response_logs) >= 1 # Should see at least 1 response\n some_chat_calls_to_openai = len(chat_openai_logs) >= 1 # Should see at least 1 chat call\n some_workflow_calls_to_openai = (\n len(codereview_openai_logs) >= 1\n or len([line for line in logs.split(\"\\n\") if \"openai\" in line and \"codereview\" in line]) > 0\n ) # Should see evidence of workflow tool usage\n\n self.logger.info(f\" OpenAI API call logs: {len(openai_api_logs)}\")\n self.logger.info(f\" OpenAI model usage logs: {len(openai_model_logs)}\")\n self.logger.info(f\" OpenAI response logs: {len(openai_response_logs)}\")\n self.logger.info(f\" Chat calls to OpenAI: {len(chat_openai_logs)}\")\n self.logger.info(f\" Codereview calls to OpenAI: {len(codereview_openai_logs)}\")\n\n # Log sample evidence for debugging\n if self.verbose and openai_api_logs:\n self.logger.debug(\" πŸ“‹ Sample OpenAI API logs:\")\n for log in openai_api_logs[:5]:\n self.logger.debug(f\" {log}\")\n\n if self.verbose and chat_openai_logs:\n self.logger.debug(\" πŸ“‹ Sample chat OpenAI logs:\")\n for log in chat_openai_logs[:3]:\n self.logger.debug(f\" {log}\")\n\n # Success criteria\n success_criteria = [\n (\"OpenAI API calls made\", openai_api_called),\n (\"OpenAI model usage logged\", openai_model_usage),\n (\"OpenAI responses received\", openai_responses_received),\n (\"Chat tool used OpenAI\", some_chat_calls_to_openai),\n (\n \"Workflow tool attempted\",\n some_workflow_calls_to_openai or response3 is not None,\n ), # More flexible check\n ]\n\n passed_criteria = sum(1 for _, passed in success_criteria if passed)\n self.logger.info(f\" Success criteria met: {passed_criteria}/{len(success_criteria)}\")\n\n for criterion, passed in success_criteria:\n status = \"βœ…\" if passed else \"❌\"\n self.logger.info(f\" {status} {criterion}\")\n\n if passed_criteria >= 3: # At least 3 out of 5 criteria\n self.logger.info(\" βœ… O3 model selection validation passed\")\n return True\n else:\n self.logger.error(\" ❌ O3 model selection validation failed\")\n return False\n\n except Exception as e:\n self.logger.error(f\"O3 model selection test failed: {e}\")\n return False\n finally:\n self.cleanup_test_files()\n\n def _run_openrouter_o3_test(self) -> bool:\n \"\"\"Test O3 model selection when using OpenRouter\"\"\"\n try:\n # Setup test files\n self.setup_test_files()\n\n # Test 1: O3 model via OpenRouter\n self.logger.info(\" 1: Testing O3 model via OpenRouter\")\n\n response1, _ = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Simple test: What is 2 + 2? Just give a brief answer.\",\n \"model\": \"o3\",\n \"temperature\": 1.0,\n },\n )\n\n if not response1:\n self.logger.error(\" ❌ O3 model test via OpenRouter failed\")\n return False\n\n self.logger.info(\" βœ… O3 model call via OpenRouter completed\")\n\n # Test 2: O3-mini model via OpenRouter\n self.logger.info(\" 2: Testing O3-mini model via OpenRouter\")\n\n response2, _ = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Simple test: What is 3 + 3? Just give a brief answer.\",\n \"model\": \"o3-mini\",\n \"temperature\": 1.0,\n },\n )\n\n if not response2:\n self.logger.error(\" ❌ O3-mini model test via OpenRouter failed\")\n return False\n\n self.logger.info(\" βœ… O3-mini model call via OpenRouter completed\")\n\n # Test 3: Codereview with O3 via OpenRouter\n self.logger.info(\" 3: Testing O3 with codereview tool via OpenRouter\")\n\n test_code = \"\"\"def add(a, b):\n return a + b\n\ndef multiply(x, y):\n return x * y\n\"\"\"\n test_file = self.create_additional_test_file(\"simple_math.py\", test_code)\n\n response3, _ = self.call_mcp_tool(\n \"codereview\",\n {\n \"step\": \"Review this simple code for quality and potential issues\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Starting code review analysis\",\n \"relevant_files\": [test_file],\n \"model\": \"o3\",\n \"temperature\": 1.0,\n },\n )\n\n if not response3:\n self.logger.error(\" ❌ O3 with codereview tool via OpenRouter failed\")\n return False\n\n self.logger.info(\" βœ… O3 with codereview tool via OpenRouter completed\")\n\n # Validate OpenRouter usage in logs\n self.logger.info(\" 4: Validating OpenRouter usage in logs\")\n logs = self.get_recent_server_logs()\n\n # Check for OpenRouter API calls\n openrouter_api_logs = [\n line\n for line in logs.split(\"\\n\")\n if \"openrouter\" in line.lower() and (\"API\" in line or \"request\" in line)\n ]\n\n # Check for model resolution through OpenRouter\n openrouter_model_logs = [\n line for line in logs.split(\"\\n\") if \"openrouter\" in line.lower() and (\"o3\" in line or \"model\" in line)\n ]\n\n # Check for successful responses\n openrouter_response_logs = [\n line for line in logs.split(\"\\n\") if \"openrouter\" in line.lower() and \"response\" in line\n ]\n\n self.logger.info(f\" OpenRouter API logs: {len(openrouter_api_logs)}\")\n self.logger.info(f\" OpenRouter model logs: {len(openrouter_model_logs)}\")\n self.logger.info(f\" OpenRouter response logs: {len(openrouter_response_logs)}\")\n\n # Success criteria for OpenRouter\n openrouter_used = len(openrouter_api_logs) >= 3 or len(openrouter_model_logs) >= 3\n all_calls_succeeded = response1 and response2 and response3\n\n success_criteria = [\n (\"All O3 model calls succeeded\", all_calls_succeeded),\n (\"OpenRouter provider was used\", openrouter_used),\n ]\n\n passed_criteria = sum(1 for _, passed in success_criteria if passed)\n self.logger.info(f\" Success criteria met: {passed_criteria}/{len(success_criteria)}\")\n\n for criterion, passed in success_criteria:\n status = \"βœ…\" if passed else \"❌\"\n self.logger.info(f\" {status} {criterion}\")\n\n if passed_criteria == len(success_criteria):\n self.logger.info(\" βœ… O3 model selection via OpenRouter passed\")\n return True\n else:\n self.logger.error(\" ❌ O3 model selection via OpenRouter failed\")\n return False\n\n except Exception as e:\n self.logger.error(f\"OpenRouter O3 test failed: {e}\")\n return False\n finally:\n self.cleanup_test_files()\n\n\ndef main():\n \"\"\"Run the O3 model selection tests\"\"\"\n import sys\n\n verbose = \"--verbose\" in sys.argv or \"-v\" in sys.argv\n test = O3ModelSelectionTest(verbose=verbose)\n\n success = test.run_test()\n sys.exit(0 if success else 1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "simulator_tests/test_o3_pro_expensive.py", "content": "#!/usr/bin/env python3\n\"\"\"\nO3-Pro Expensive Model Test\n\n⚠️ WARNING: This test uses o3-pro which is EXTREMELY EXPENSIVE! ⚠️\n\nThis test is intentionally NOT added to TEST_REGISTRY to prevent accidental execution.\nIt can only be run manually using:\n python communication_simulator_test.py --individual o3_pro_expensive\n\nTests that o3-pro model:\n1. Uses the correct /v1/responses endpoint (not /v1/chat/completions)\n2. Successfully completes a chat call\n3. Returns properly formatted response\n\"\"\"\n\nfrom .base_test import BaseSimulatorTest\n\n\nclass O3ProExpensiveTest(BaseSimulatorTest):\n \"\"\"Test o3-pro model basic functionality - EXPENSIVE, manual only\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"o3_pro_expensive\"\n\n @property\n def test_description(self) -> str:\n return \"⚠️ EXPENSIVE O3-Pro basic validation (manual only)\"\n\n def run_test(self) -> bool:\n \"\"\"Test o3-pro model with endpoint verification - EXPENSIVE!\"\"\"\n try:\n self.logger.warning(\"⚠️ ⚠️ ⚠️ EXPENSIVE TEST - O3-PRO COSTS ~$15-60 PER 1K TOKENS! ⚠️ ⚠️ ⚠️\")\n self.logger.info(\"Test: O3-Pro endpoint and functionality test\")\n\n # First, verify we're hitting the right endpoint by checking logs\n self.logger.info(\"Step 1: Testing o3-pro with chat tool\")\n\n # One simple chat call\n response, tool_result = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"What is 2 + 2?\",\n \"model\": \"o3-pro\",\n \"temperature\": 1.0,\n },\n )\n\n if not response:\n self.logger.error(\"❌ O3-Pro chat call failed - no response\")\n if tool_result and \"error\" in tool_result:\n error_msg = tool_result[\"error\"]\n self.logger.error(f\"Error details: {error_msg}\")\n # Check if it's the endpoint error we're trying to fix\n if \"v1/responses\" in str(error_msg) and \"v1/chat/completions\" in str(error_msg):\n self.logger.error(\n \"❌ ENDPOINT BUG DETECTED: o3-pro is trying to use chat/completions instead of responses endpoint!\"\n )\n return False\n\n # Check the metadata to verify endpoint was used\n if tool_result and isinstance(tool_result, dict):\n metadata = tool_result.get(\"metadata\", {})\n endpoint_used = metadata.get(\"endpoint\", \"unknown\")\n\n if endpoint_used == \"responses\":\n self.logger.info(\"βœ… Correct endpoint used: /v1/responses\")\n else:\n self.logger.warning(f\"⚠️ Endpoint used: {endpoint_used} (expected: responses)\")\n\n # Verify the response content\n if response and \"4\" in str(response):\n self.logger.info(\"βœ… O3-Pro response is mathematically correct\")\n else:\n self.logger.warning(f\"⚠️ Unexpected response: {response}\")\n\n self.logger.info(\"βœ… O3-Pro test completed successfully\")\n self.logger.warning(\"πŸ’° Test completed - check your billing!\")\n return True\n\n except Exception as e:\n self.logger.error(f\"O3-Pro test failed with exception: {e}\")\n # Log the full error for debugging endpoint issues\n import traceback\n\n self.logger.error(f\"Full traceback: {traceback.format_exc()}\")\n return False\n\n\ndef main():\n \"\"\"Run the O3-Pro expensive test\"\"\"\n import sys\n\n print(\"⚠️ ⚠️ ⚠️ WARNING: This test uses O3-PRO which is EXTREMELY EXPENSIVE! ⚠️ ⚠️ ⚠️\")\n print(\"O3-Pro can cost $15-60 per 1K tokens!\")\n print(\"This is a MINIMAL test but may still cost $5-15!\")\n print()\n\n response = input(\"Are you absolutely sure you want to run this expensive test? Type 'YES_I_UNDERSTAND_THE_COST': \")\n if response != \"YES_I_UNDERSTAND_THE_COST\":\n print(\"❌ Test cancelled\")\n sys.exit(1)\n\n print(\"πŸ’° Running minimal O3-Pro test...\")\n\n verbose = \"--verbose\" in sys.argv or \"-v\" in sys.argv\n test = O3ProExpensiveTest(verbose=verbose)\n\n success = test.run_test()\n\n if success:\n print(\"βœ… O3-Pro test completed successfully\")\n print(\"πŸ’° Don't forget to check your billing!\")\n else:\n print(\"❌ O3-Pro test failed\")\n\n sys.exit(0 if success else 1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "simulator_tests/test_ollama_custom_url.py", "content": "#!/usr/bin/env python3\n\"\"\"\nOllama Custom URL Test\n\nTests custom API endpoint functionality with Ollama-style local models, including:\n- Basic chat with custom model via local endpoint\n- File analysis with local model\n- Conversation continuation with custom provider\n- Model alias resolution for local models\n\"\"\"\n\n\nfrom .base_test import BaseSimulatorTest\n\n\nclass OllamaCustomUrlTest(BaseSimulatorTest):\n \"\"\"Test Ollama custom URL functionality\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"ollama_custom_url\"\n\n @property\n def test_description(self) -> str:\n return \"Ollama custom URL endpoint functionality\"\n\n def run_test(self) -> bool:\n \"\"\"Test Ollama custom URL functionality\"\"\"\n try:\n self.logger.info(\"Test: Ollama custom URL functionality\")\n\n # Check if custom URL is configured\n import os\n\n custom_url = os.environ.get(\"CUSTOM_API_URL\")\n if not custom_url:\n self.logger.warning(\"CUSTOM_API_URL not set, skipping Ollama test\")\n self.logger.info(\"To enable this test, add to .env file:\")\n self.logger.info(\"CUSTOM_API_URL=http://localhost:11434/v1\")\n self.logger.info(\"CUSTOM_API_KEY=\")\n return True # Skip gracefully\n\n self.logger.info(f\"Testing with custom URL: {custom_url}\")\n\n # Setup test files\n self.setup_test_files()\n\n # Test 1: Basic chat with local model\n self.logger.info(\" 1.1: Basic chat with local model\")\n response1, continuation_id = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Hello! Can you introduce yourself and tell me what model you are? Keep your response brief.\",\n \"model\": \"llama3.2\", # Use exact Ollama model name\n },\n )\n\n if not self.validate_successful_response(response1, \"local model chat\"):\n return False\n\n self.logger.info(f\" βœ… Local model responded with continuation_id: {continuation_id}\")\n\n # Test 2: File analysis with local model using a specific Ollama-related file\n self.logger.info(\" 1.2: File analysis with local model\")\n\n # Create a simple, clear file that shouldn't require clarification\n ollama_test_content = '''\"\"\"\nOllama API Client Test\nA simple test client for connecting to Ollama API endpoints\n\"\"\"\n\nimport requests\nimport json\n\nclass OllamaClient:\n \"\"\"Simple client for Ollama API\"\"\"\n\n def __init__(self, base_url=\"http://localhost:11434\"):\n self.base_url = base_url\n\n def list_models(self):\n \"\"\"List available models\"\"\"\n response = requests.get(f\"{self.base_url}/api/tags\")\n return response.json()\n\n def generate(self, model, prompt):\n \"\"\"Generate text using a model\"\"\"\n data = {\n \"model\": model,\n \"prompt\": prompt,\n \"stream\": False\n }\n response = requests.post(f\"{self.base_url}/api/generate\", json=data)\n return response.json()\n\nif __name__ == \"__main__\":\n client = OllamaClient()\n models = client.list_models()\n print(f\"Available models: {len(models['models'])}\")\n'''\n\n # Create the test file\n ollama_test_file = self.create_additional_test_file(\"ollama_client.py\", ollama_test_content)\n\n response2, _ = self.call_mcp_tool(\n \"analyze\",\n {\n \"absolute_file_paths\": [ollama_test_file],\n \"prompt\": \"Analyze this Ollama client code. What does this code do and what are its main functions?\",\n \"model\": \"llama3.2\",\n },\n )\n\n if not self.validate_successful_response(response2, \"local model file analysis\", files_provided=True):\n return False\n\n self.logger.info(\" βœ… Local model analyzed file successfully\")\n\n # Test 3: Continue conversation with local model\n if continuation_id:\n self.logger.info(\" 1.3: Continue conversation with local model\")\n response3, _ = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Thanks for the introduction! I just analyzed an Ollama client Python file. Can you suggest one improvement for writing better API client code in general?\",\n \"continuation_id\": continuation_id,\n \"model\": \"llama3.2\",\n },\n )\n\n if not self.validate_successful_response(response3, \"local model conversation continuation\"):\n return False\n\n self.logger.info(\" βœ… Conversation continuation with local model working\")\n\n # Test 4: Test alternative local model aliases\n self.logger.info(\" 1.4: Test alternative local model aliases\")\n response4, _ = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Quick test with alternative alias. Say 'Local model working' if you can respond.\",\n \"model\": \"llama3.2\", # Alternative alias\n },\n )\n\n if not self.validate_successful_response(response4, \"alternative local model alias\"):\n return False\n\n self.logger.info(\" βœ… Alternative local model alias working\")\n\n # Test 5: Test direct model name (if applicable)\n self.logger.info(\" 1.5: Test direct model name\")\n response5, _ = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Final test with direct model name. Respond briefly.\",\n \"model\": \"llama3.2\", # Direct model name\n },\n )\n\n if not self.validate_successful_response(response5, \"direct model name\"):\n return False\n\n self.logger.info(\" βœ… Direct model name working\")\n\n self.logger.info(\" βœ… All Ollama custom URL tests passed\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Ollama custom URL test failed: {e}\")\n return False\n finally:\n self.cleanup_test_files()\n\n def validate_successful_response(self, response: str, test_name: str, files_provided: bool = False) -> bool:\n \"\"\"Validate that the response indicates success, not an error\n\n Args:\n response: The response text to validate\n test_name: Name of the test for logging\n files_provided: Whether actual files were provided to the tool\n \"\"\"\n if not response:\n self.logger.error(f\"No response received for {test_name}\")\n self._check_server_logs_for_errors()\n return False\n\n # Check for common error indicators\n error_indicators = [\n \"OpenRouter API error\",\n \"is not a valid model ID\",\n \"API key not found\",\n \"Connection error\",\n \"connection refused\",\n \"network is unreachable\",\n \"timeout\",\n \"error 404\",\n \"error 400\",\n \"error 401\",\n \"error 403\",\n \"error 500\",\n \"status code 404\",\n \"status code 400\",\n \"status code 401\",\n \"status code 403\",\n \"status code 500\",\n \"status: error\",\n ]\n\n # Special handling for clarification requests from local models\n if \"files_required_to_continue\" in response.lower():\n if files_provided:\n # If we provided actual files, clarification request is a FAILURE\n self.logger.error(\n f\"❌ Local model requested clarification for {test_name} despite being provided with actual files\"\n )\n self.logger.debug(f\"Clarification response: {response[:200]}...\")\n return False\n else:\n # If no files were provided, clarification request is acceptable\n self.logger.info(\n f\"βœ… Local model requested clarification for {test_name} - valid when no files provided\"\n )\n self.logger.debug(f\"Clarification response: {response[:200]}...\")\n return True\n\n # Check for SSRF security restriction - this is expected for local URLs\n if \"restricted IP address\" in response and \"security risk (SSRF)\" in response:\n self.logger.info(\n f\"βœ… Custom URL routing working - {test_name} correctly attempted to connect to custom API\"\n )\n self.logger.info(\" (Connection blocked by SSRF protection, which is expected for local URLs)\")\n return True\n\n response_lower = response.lower()\n for error in error_indicators:\n if error.lower() in response_lower:\n self.logger.error(f\"Error detected in {test_name}: {error}\")\n self.logger.debug(f\"Full response: {response}\")\n self._check_server_logs_for_errors()\n return False\n\n # Response should be substantial (more than just a few words)\n if len(response.strip()) < 10:\n self.logger.error(f\"Response too short for {test_name}: {response}\")\n self._check_server_logs_for_errors()\n return False\n\n # Verify this looks like a real AI response, not just an error message\n if not self._validate_ai_response_content(response):\n self.logger.error(f\"Response doesn't look like valid AI output for {test_name}\")\n self._check_server_logs_for_errors()\n return False\n\n self.logger.debug(f\"Successful response for {test_name}: {response[:100]}...\")\n return True\n\n def _validate_ai_response_content(self, response: str) -> bool:\n \"\"\"Validate that response appears to be legitimate AI output\"\"\"\n if not response:\n return False\n\n response_lower = response.lower()\n\n # Check for indicators this is a real AI response\n positive_indicators = [\n \"i am\",\n \"i'm\",\n \"i can\",\n \"i'll\",\n \"i would\",\n \"i think\",\n \"this code\",\n \"this function\",\n \"this file\",\n \"this configuration\",\n \"hello\",\n \"hi\",\n \"yes\",\n \"sure\",\n \"certainly\",\n \"of course\",\n \"analysis\",\n \"analyze\",\n \"review\",\n \"suggestion\",\n \"improvement\",\n \"here\",\n \"below\",\n \"above\",\n \"following\",\n \"based on\",\n \"python\",\n \"code\",\n \"function\",\n \"class\",\n \"variable\",\n \"llama\",\n \"model\",\n \"assistant\",\n \"ai\",\n ]\n\n # Response should contain at least some AI-like language\n ai_indicators_found = sum(1 for indicator in positive_indicators if indicator in response_lower)\n\n if ai_indicators_found < 2:\n self.logger.warning(f\"Response lacks AI-like indicators: {response[:200]}...\")\n return False\n\n return True\n\n def _check_server_logs_for_errors(self):\n \"\"\"Check server logs for any error messages that might explain failures\"\"\"\n try:\n # Get recent logs from the log file\n log_file_path = \"logs/mcp_server.log\"\n with open(log_file_path) as f:\n lines = f.readlines()\n recent_logs = lines[-50:] # Last 50 lines\n\n if recent_logs:\n self.logger.info(\"Recent server logs:\")\n for line in recent_logs[-10:]: # Last 10 lines\n if line.strip():\n self.logger.info(f\" {line.strip()}\")\n\n except Exception as e:\n self.logger.debug(f\"Failed to check server logs: {e}\")\n\n def validate_local_model_response(self, response: str) -> bool:\n \"\"\"Validate that response appears to come from a local model\"\"\"\n if not response:\n return False\n\n # Basic validation - response should be non-empty and reasonable\n response_lower = response.lower()\n\n # Check for some indicators this might be from a local model\n # (This is heuristic - local models often mention their nature)\n local_indicators = [\"llama\", \"local\", \"assistant\", \"ai\", \"model\", \"help\"]\n\n # At least response should be meaningful text\n return len(response.strip()) > 10 and any(indicator in response_lower for indicator in local_indicators)\n" }, { "path": "simulator_tests/test_openrouter_fallback.py", "content": "#!/usr/bin/env python3\n\"\"\"\nOpenRouter Fallback Test\n\nTests that verify the system correctly falls back to OpenRouter when:\n- Only OPENROUTER_API_KEY is configured\n- Native models (flash, pro) are requested but map to OpenRouter equivalents\n- Auto mode correctly selects OpenRouter models\n\"\"\"\n\n\nfrom .base_test import BaseSimulatorTest\n\n\nclass OpenRouterFallbackTest(BaseSimulatorTest):\n \"\"\"Test OpenRouter fallback behavior when it's the only provider\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"openrouter_fallback\"\n\n @property\n def test_description(self) -> str:\n return \"OpenRouter fallback behavior when only provider\"\n\n def run_test(self) -> bool:\n \"\"\"Test OpenRouter fallback behavior\"\"\"\n try:\n self.logger.info(\"Test: OpenRouter fallback behavior when only provider available\")\n\n # Check if ONLY OpenRouter API key is configured (this is a fallback test)\n import os\n\n has_openrouter = bool(os.environ.get(\"OPENROUTER_API_KEY\"))\n has_gemini = bool(os.environ.get(\"GEMINI_API_KEY\"))\n has_openai = bool(os.environ.get(\"OPENAI_API_KEY\"))\n\n if not has_openrouter:\n self.logger.info(\" ⚠️ OpenRouter API key not configured - skipping test\")\n self.logger.info(\" ℹ️ This test requires OPENROUTER_API_KEY to be set in .env\")\n return True # Return True to indicate test is skipped, not failed\n\n if has_gemini or has_openai:\n self.logger.info(\" ⚠️ Other API keys configured - this is not a fallback scenario\")\n self.logger.info(\" ℹ️ This test requires ONLY OpenRouter to be configured (no Gemini/OpenAI keys)\")\n self.logger.info(\" ℹ️ Current setup has multiple providers, so fallback behavior doesn't apply\")\n return True # Return True to indicate test is skipped, not failed\n\n # Setup test files\n self.setup_test_files()\n\n # Test 1: Auto mode should work with OpenRouter\n self.logger.info(\" 1: Testing auto mode with OpenRouter as only provider\")\n\n response1, continuation_id = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"What is 2 + 2? Give a brief answer.\",\n # No model specified - should use auto mode\n \"temperature\": 0.1,\n },\n )\n\n if not response1:\n self.logger.error(\" ❌ Auto mode with OpenRouter failed\")\n return False\n\n self.logger.info(\" βœ… Auto mode call completed with OpenRouter\")\n\n # Test 2: Flash model should map to OpenRouter equivalent\n self.logger.info(\" 2: Testing flash model mapping to OpenRouter\")\n\n # Use codereview tool to test a different tool type\n test_code = \"\"\"def calculate_sum(numbers):\n total = 0\n for num in numbers:\n total += num\n return total\"\"\"\n\n test_file = self.create_additional_test_file(\"sum_function.py\", test_code)\n\n response2, _ = self.call_mcp_tool(\n \"codereview\",\n {\n \"step\": \"Quick review of this sum function for quality and potential issues\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Starting code review of sum function\",\n \"relevant_files\": [test_file],\n \"model\": \"flash\",\n \"temperature\": 0.1,\n },\n )\n\n if not response2:\n self.logger.error(\" ❌ Flash model mapping to OpenRouter failed\")\n return False\n\n self.logger.info(\" βœ… Flash model successfully mapped to OpenRouter\")\n\n # Test 3: Pro model should map to OpenRouter equivalent\n self.logger.info(\" 3: Testing pro model mapping to OpenRouter\")\n\n response3, _ = self.call_mcp_tool(\n \"analyze\",\n {\n \"step\": \"Analyze the structure of this Python code\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Starting code structure analysis\",\n \"relevant_files\": [self.test_files[\"python\"]],\n \"model\": \"pro\",\n \"temperature\": 0.1,\n },\n )\n\n if not response3:\n self.logger.error(\" ❌ Pro model mapping to OpenRouter failed\")\n return False\n\n self.logger.info(\" βœ… Pro model successfully mapped to OpenRouter\")\n\n # Test 4: Debug tool with OpenRouter\n self.logger.info(\" 4: Testing debug tool with OpenRouter\")\n\n response4, _ = self.call_mcp_tool(\n \"debug\",\n {\n \"step\": \"Why might a function return None instead of a value?\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Starting debug investigation of None return values\",\n \"model\": \"flash\", # Should map to OpenRouter\n \"temperature\": 0.1,\n },\n )\n\n if not response4:\n self.logger.error(\" ❌ Debug tool with OpenRouter failed\")\n return False\n\n self.logger.info(\" βœ… Debug tool working with OpenRouter\")\n\n # Test 5: Validate logs show OpenRouter is being used\n self.logger.info(\" 5: Validating OpenRouter is the active provider\")\n logs = self.get_recent_server_logs()\n\n # Check for provider fallback logs\n fallback_logs = [\n line\n for line in logs.split(\"\\n\")\n if \"No Gemini API key found\" in line\n or \"No OpenAI API key found\" in line\n or \"Only OpenRouter available\" in line\n or \"Using OpenRouter\" in line\n ]\n\n # Check for OpenRouter provider initialization\n provider_logs = [\n line\n for line in logs.split(\"\\n\")\n if \"OpenRouter provider\" in line or \"OpenRouterProvider\" in line or \"openrouter.ai/api/v1\" in line\n ]\n\n # Check for model resolution through OpenRouter\n model_resolution_logs = [\n line\n for line in logs.split(\"\\n\")\n if (\"Resolved model\" in line and \"via OpenRouter\" in line)\n or (\"Model alias\" in line and \"resolved to\" in line)\n or (\"flash\" in line and \"gemini-flash\" in line)\n or (\"pro\" in line and \"gemini-pro\" in line)\n ]\n\n # Log findings\n self.logger.info(f\" Fallback indication logs: {len(fallback_logs)}\")\n self.logger.info(f\" OpenRouter provider logs: {len(provider_logs)}\")\n self.logger.info(f\" Model resolution logs: {len(model_resolution_logs)}\")\n\n # Sample logs for debugging\n if self.verbose:\n if fallback_logs:\n self.logger.debug(\" πŸ“‹ Sample fallback logs:\")\n for log in fallback_logs[:3]:\n self.logger.debug(f\" {log}\")\n\n if provider_logs:\n self.logger.debug(\" πŸ“‹ Sample provider logs:\")\n for log in provider_logs[:3]:\n self.logger.debug(f\" {log}\")\n\n # Success criteria\n openrouter_active = len(provider_logs) > 0\n models_resolved = len(model_resolution_logs) > 0\n all_tools_worked = True # We checked this above\n\n success_criteria = [\n (\"OpenRouter provider active\", openrouter_active),\n (\"Models resolved through OpenRouter\", models_resolved),\n (\"All tools worked with OpenRouter\", all_tools_worked),\n ]\n\n passed_criteria = sum(1 for _, passed in success_criteria if passed)\n self.logger.info(f\" Success criteria met: {passed_criteria}/{len(success_criteria)}\")\n\n for criterion, passed in success_criteria:\n status = \"βœ…\" if passed else \"❌\"\n self.logger.info(f\" {status} {criterion}\")\n\n if passed_criteria >= 2: # At least 2 out of 3 criteria\n self.logger.info(\" βœ… OpenRouter fallback test passed\")\n return True\n else:\n self.logger.error(\" ❌ OpenRouter fallback test failed\")\n return False\n\n except Exception as e:\n self.logger.error(f\"OpenRouter fallback test failed: {e}\")\n return False\n finally:\n self.cleanup_test_files()\n\n\ndef main():\n \"\"\"Run the OpenRouter fallback tests\"\"\"\n import sys\n\n verbose = \"--verbose\" in sys.argv or \"-v\" in sys.argv\n test = OpenRouterFallbackTest(verbose=verbose)\n\n success = test.run_test()\n sys.exit(0 if success else 1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "simulator_tests/test_openrouter_models.py", "content": "#!/usr/bin/env python3\n\"\"\"\nOpenRouter Model Tests\n\nTests that verify OpenRouter functionality including:\n- Model alias resolution (flash, pro, o3, etc. map to OpenRouter equivalents)\n- Multiple OpenRouter models work correctly\n- Conversation continuity works with OpenRouter models\n- Error handling when models are not available\n\"\"\"\n\n\nfrom .base_test import BaseSimulatorTest\n\n\nclass OpenRouterModelsTest(BaseSimulatorTest):\n \"\"\"Test OpenRouter model functionality and alias mapping\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"openrouter_models\"\n\n @property\n def test_description(self) -> str:\n return \"OpenRouter model functionality and alias mapping\"\n\n def run_test(self) -> bool:\n \"\"\"Test OpenRouter model functionality\"\"\"\n try:\n self.logger.info(\"Test: OpenRouter model functionality and alias mapping\")\n\n # Check if OpenRouter API key is configured\n import os\n\n has_openrouter = bool(os.environ.get(\"OPENROUTER_API_KEY\"))\n\n if not has_openrouter:\n self.logger.info(\" ⚠️ OpenRouter API key not configured - skipping test\")\n self.logger.info(\" ℹ️ This test requires OPENROUTER_API_KEY to be set in .env\")\n return True # Return True to indicate test is skipped, not failed\n\n # Setup test files for later use\n self.setup_test_files()\n\n # Test 1: Flash alias mapping to OpenRouter\n self.logger.info(\" 1: Testing 'flash' alias (should map to google/gemini-2.5-flash)\")\n\n response1, continuation_id = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Say 'Hello from Flash model!' and nothing else.\",\n \"model\": \"flash\",\n \"temperature\": 0.1,\n },\n )\n\n if not response1:\n self.logger.error(\" ❌ Flash alias test failed\")\n return False\n\n self.logger.info(\" βœ… Flash alias call completed\")\n if continuation_id:\n self.logger.info(f\" βœ… Got continuation_id: {continuation_id}\")\n\n # Test 2: Pro alias mapping to OpenRouter\n self.logger.info(\" 2: Testing 'pro' alias (should map to google/gemini-2.5-pro)\")\n\n response2, _ = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Say 'Hello from Pro model!' and nothing else.\",\n \"model\": \"pro\",\n \"temperature\": 0.1,\n },\n )\n\n if not response2:\n self.logger.error(\" ❌ Pro alias test failed\")\n return False\n\n self.logger.info(\" βœ… Pro alias call completed\")\n\n # Test 3: O3 alias mapping to OpenRouter (should map to openai/gpt-4o)\n self.logger.info(\" 3: Testing 'o3' alias (should map to openai/gpt-4o)\")\n\n response3, _ = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Say 'Hello from O3 model!' and nothing else.\",\n \"model\": \"o3\",\n \"temperature\": 0.1,\n },\n )\n\n if not response3:\n self.logger.error(\" ❌ O3 alias test failed\")\n return False\n\n self.logger.info(\" βœ… O3 alias call completed\")\n\n # Test 4: Direct OpenRouter model name\n self.logger.info(\" 4: Testing direct OpenRouter model name (anthropic/claude-3-haiku)\")\n\n response4, _ = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Say 'Hello from Claude Haiku!' and nothing else.\",\n \"model\": \"anthropic/claude-3-haiku\",\n \"temperature\": 0.1,\n },\n )\n\n if not response4:\n self.logger.error(\" ❌ Direct OpenRouter model test failed\")\n return False\n\n self.logger.info(\" βœ… Direct OpenRouter model call completed\")\n\n # Test 5: OpenRouter alias from config\n self.logger.info(\" 5: Testing OpenRouter alias from config ('opus' -> anthropic/claude-opus-4)\")\n\n response5, _ = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Say 'Hello from Opus!' and nothing else.\",\n \"model\": \"opus\",\n \"temperature\": 0.1,\n },\n )\n\n if not response5:\n self.logger.error(\" ❌ OpenRouter alias test failed\")\n return False\n\n self.logger.info(\" βœ… OpenRouter alias call completed\")\n\n # Test 6: Conversation continuity with OpenRouter models\n self.logger.info(\" 6: Testing conversation continuity with OpenRouter\")\n\n response6, new_continuation_id = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Remember this number: 42. What number did I just tell you?\",\n \"model\": \"sonnet\", # Claude Sonnet via OpenRouter\n \"temperature\": 0.1,\n },\n )\n\n if not response6 or not new_continuation_id:\n self.logger.error(\" ❌ Failed to start conversation with continuation_id\")\n return False\n\n # Continue the conversation\n response7, _ = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"What was the number I told you earlier?\",\n \"model\": \"sonnet\",\n \"continuation_id\": new_continuation_id,\n \"temperature\": 0.1,\n },\n )\n\n if not response7:\n self.logger.error(\" ❌ Failed to continue conversation\")\n return False\n\n # Check if the model remembered the number\n if \"42\" in response7:\n self.logger.info(\" βœ… Conversation continuity working with OpenRouter\")\n else:\n self.logger.warning(\" ⚠️ Model may not have remembered the number\")\n\n # Test 7: Validate OpenRouter API usage from logs\n self.logger.info(\" 7: Validating OpenRouter API usage in logs\")\n logs = self.get_recent_server_logs()\n\n # Check for OpenRouter API calls\n openrouter_logs = [line for line in logs.split(\"\\n\") if \"openrouter\" in line.lower()]\n openrouter_api_logs = [line for line in logs.split(\"\\n\") if \"openrouter.ai/api/v1\" in line]\n\n # Check for specific model mappings\n flash_mapping_logs = [\n line\n for line in logs.split(\"\\n\")\n if (\"flash\" in line and \"google/gemini-flash\" in line)\n or (\"Resolved model\" in line and \"google/gemini-flash\" in line)\n ]\n\n pro_mapping_logs = [\n line\n for line in logs.split(\"\\n\")\n if (\"pro\" in line and \"google/gemini-pro\" in line)\n or (\"Resolved model\" in line and \"google/gemini-pro\" in line)\n ]\n\n # Log findings\n self.logger.info(f\" OpenRouter-related logs: {len(openrouter_logs)}\")\n self.logger.info(f\" OpenRouter API logs: {len(openrouter_api_logs)}\")\n self.logger.info(f\" Flash mapping logs: {len(flash_mapping_logs)}\")\n self.logger.info(f\" Pro mapping logs: {len(pro_mapping_logs)}\")\n\n # Sample log output for debugging\n if self.verbose and openrouter_logs:\n self.logger.debug(\" πŸ“‹ Sample OpenRouter logs:\")\n for log in openrouter_logs[:5]:\n self.logger.debug(f\" {log}\")\n\n # Success criteria\n openrouter_api_used = len(openrouter_api_logs) > 0\n models_mapped = len(flash_mapping_logs) > 0 or len(pro_mapping_logs) > 0\n\n success_criteria = [\n (\"OpenRouter API calls made\", openrouter_api_used),\n (\"Model aliases mapped correctly\", models_mapped),\n (\"All model calls succeeded\", True), # We already checked this above\n ]\n\n passed_criteria = sum(1 for _, passed in success_criteria if passed)\n self.logger.info(f\" Success criteria met: {passed_criteria}/{len(success_criteria)}\")\n\n for criterion, passed in success_criteria:\n status = \"βœ…\" if passed else \"❌\"\n self.logger.info(f\" {status} {criterion}\")\n\n if passed_criteria >= 2: # At least 2 out of 3 criteria\n self.logger.info(\" βœ… OpenRouter model tests passed\")\n return True\n else:\n self.logger.error(\" ❌ OpenRouter model tests failed\")\n return False\n\n except Exception as e:\n self.logger.error(f\"OpenRouter model test failed: {e}\")\n return False\n finally:\n self.cleanup_test_files()\n\n\ndef main():\n \"\"\"Run the OpenRouter model tests\"\"\"\n import sys\n\n verbose = \"--verbose\" in sys.argv or \"-v\" in sys.argv\n test = OpenRouterModelsTest(verbose=verbose)\n\n success = test.run_test()\n sys.exit(0 if success else 1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "simulator_tests/test_per_tool_deduplication.py", "content": "#!/usr/bin/env python3\n\"\"\"\nPer-Tool File Deduplication Test\n\nTests file deduplication for each individual MCP tool to ensure\nthat files are properly deduplicated within single-tool conversations.\nValidates that:\n1. Files are embedded only once in conversation history\n2. Continuation calls don't re-read existing files\n3. New files are still properly embedded\n4. Server logs show deduplication behavior\n\"\"\"\n\nimport os\n\nfrom .conversation_base_test import ConversationBaseTest\n\n\nclass PerToolDeduplicationTest(ConversationBaseTest):\n \"\"\"Test file deduplication for each individual tool\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"per_tool_deduplication\"\n\n @property\n def test_description(self) -> str:\n return \"File deduplication for individual tools\"\n\n # create_additional_test_file method now inherited from base class\n\n def run_test(self) -> bool:\n \"\"\"Test file deduplication with realistic precommit/codereview workflow\"\"\"\n try:\n self.logger.info(\"πŸ“„ Test: Simplified file deduplication with precommit/codereview workflow\")\n\n # Setup test environment for conversation testing\n self.setUp()\n\n # Setup test files\n self.setup_test_files()\n\n # Create a short dummy file for quick testing in the current repo\n dummy_content = \"\"\"def add(a, b):\n return a + b # Missing type hints\n\ndef divide(x, y):\n return x / y # No zero check\n\"\"\"\n # Create the file in the current git repo directory to make it show up in git status\n dummy_file_path = os.path.join(os.getcwd(), \"dummy_code.py\")\n with open(dummy_file_path, \"w\") as f:\n f.write(dummy_content)\n\n # Get timestamp for log filtering\n import datetime\n\n start_time = datetime.datetime.now().strftime(\"%Y-%m-%dT%H:%M:%S\")\n\n # Step 1: precommit tool with dummy file (low thinking mode)\n self.logger.info(\" Step 1: precommit tool with dummy file\")\n precommit_params = {\n \"step\": \"Initial analysis of dummy_code.py for commit readiness. Please give me a quick one line reply.\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"findings\": \"Starting pre-commit validation of dummy_code.py\",\n \"path\": os.getcwd(), # Use current working directory as the git repo path\n \"relevant_files\": [dummy_file_path],\n \"thinking_mode\": \"low\",\n \"model\": \"flash\",\n }\n\n response1, continuation_id = self.call_mcp_tool(\"precommit\", precommit_params)\n if not response1:\n self.logger.error(\" ❌ Step 1: precommit tool failed\")\n return False\n\n if not continuation_id:\n self.logger.error(\" ❌ Step 1: precommit tool didn't provide continuation_id\")\n return False\n\n # Validate continuation_id format (should be UUID)\n if len(continuation_id) < 32:\n self.logger.error(f\" ❌ Step 1: Invalid continuation_id format: {continuation_id}\")\n return False\n\n self.logger.info(f\" βœ… Step 1: precommit completed with continuation_id: {continuation_id[:8]}...\")\n\n # Step 2: codereview tool with same file (NO continuation - fresh conversation)\n self.logger.info(\" Step 2: codereview tool with same file (fresh conversation)\")\n codereview_params = {\n \"step\": \"Initial code review of dummy_code.py for quality and best practices. Please give me a quick one line reply.\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Starting code review of dummy_code.py\",\n \"relevant_files\": [dummy_file_path],\n \"thinking_mode\": \"low\",\n \"model\": \"flash\",\n }\n\n response2, _ = self.call_mcp_tool(\"codereview\", codereview_params)\n if not response2:\n self.logger.error(\" ❌ Step 2: codereview tool failed\")\n return False\n\n self.logger.info(\" βœ… Step 2: codereview completed (fresh conversation)\")\n\n # Step 3: Create new file and continue with precommit\n self.logger.info(\" Step 3: precommit continuation with old + new file\")\n new_file_content = \"\"\"def multiply(x, y):\n return x * y\n\ndef subtract(a, b):\n return a - b\n\"\"\"\n # Create another temp file in the current repo for git changes\n new_file_path = os.path.join(os.getcwd(), \"new_feature.py\")\n with open(new_file_path, \"w\") as f:\n f.write(new_file_content)\n\n # Continue precommit with both files\n continue_params = {\n \"continuation_id\": continuation_id,\n \"step\": \"Continue analysis with new_feature.py added. Please give me a quick one line reply about both files.\",\n \"step_number\": 2,\n \"total_steps\": 2,\n \"next_step_required\": False,\n \"findings\": \"Continuing pre-commit validation with both dummy_code.py and new_feature.py\",\n \"path\": os.getcwd(), # Use current working directory as the git repo path\n \"relevant_files\": [dummy_file_path, new_file_path], # Old + new file\n \"thinking_mode\": \"low\",\n \"model\": \"flash\",\n }\n\n response3, _ = self.call_mcp_tool(\"precommit\", continue_params)\n if not response3:\n self.logger.error(\" ❌ Step 3: precommit continuation failed\")\n return False\n\n self.logger.info(\" βœ… Step 3: precommit continuation completed\")\n\n # Validate results in server logs\n self.logger.info(\" πŸ“‹ Validating conversation history and file deduplication...\")\n logs = self.get_server_logs_since(start_time)\n\n # Check for conversation history building\n conversation_logs = [\n line for line in logs.split(\"\\n\") if \"conversation\" in line.lower() or \"history\" in line.lower()\n ]\n\n # Check for file embedding/deduplication\n embedding_logs = [\n line\n for line in logs.split(\"\\n\")\n if \"[FILE_PROCESSING]\" in line or \"embedding\" in line.lower() or \"[FILES]\" in line\n ]\n\n # Check for continuation evidence\n continuation_logs = [\n line for line in logs.split(\"\\n\") if \"continuation\" in line.lower() or continuation_id[:8] in line\n ]\n\n # Check for both files mentioned\n dummy_file_mentioned = any(\"dummy_code.py\" in line for line in logs.split(\"\\n\"))\n new_file_mentioned = any(\"new_feature.py\" in line for line in logs.split(\"\\n\"))\n\n # Print diagnostic information\n self.logger.info(f\" Conversation logs found: {len(conversation_logs)}\")\n self.logger.info(f\" File embedding logs found: {len(embedding_logs)}\")\n self.logger.info(f\" Continuation logs found: {len(continuation_logs)}\")\n self.logger.info(f\" Dummy file mentioned: {dummy_file_mentioned}\")\n self.logger.info(f\" New file mentioned: {new_file_mentioned}\")\n\n if self.verbose:\n self.logger.debug(\" πŸ“‹ Sample embedding logs:\")\n for log in embedding_logs[:5]: # Show first 5\n if log.strip():\n self.logger.debug(f\" {log.strip()}\")\n\n self.logger.debug(\" πŸ“‹ Sample continuation logs:\")\n for log in continuation_logs[:3]: # Show first 3\n if log.strip():\n self.logger.debug(f\" {log.strip()}\")\n\n # Determine success criteria\n success_criteria = [\n len(embedding_logs) > 0, # File embedding occurred\n len(continuation_logs) > 0, # Continuation worked\n dummy_file_mentioned, # Original file processed\n new_file_mentioned, # New file processed\n ]\n\n passed_criteria = sum(success_criteria)\n total_criteria = len(success_criteria)\n\n self.logger.info(f\" Success criteria met: {passed_criteria}/{total_criteria}\")\n\n if passed_criteria == total_criteria: # All criteria must pass\n self.logger.info(\" βœ… File deduplication workflow test: PASSED\")\n return True\n else:\n self.logger.warning(\" ⚠️ File deduplication workflow test: FAILED\")\n self.logger.warning(\" πŸ’‘ Check server logs for detailed file embedding and continuation activity\")\n return False\n\n except Exception as e:\n self.logger.error(f\"File deduplication workflow test failed: {e}\")\n return False\n finally:\n # Clean up temp files created in current repo\n temp_files = [\"dummy_code.py\", \"new_feature.py\"]\n for temp_file in temp_files:\n temp_path = os.path.join(os.getcwd(), temp_file)\n if os.path.exists(temp_path):\n os.remove(temp_path)\n self.logger.debug(f\"Removed temp file: {temp_path}\")\n self.cleanup_test_files()\n" }, { "path": "simulator_tests/test_planner_continuation_history.py", "content": "#!/usr/bin/env python3\n\"\"\"\nPlanner Continuation History Test\n\nTests the planner tool's continuation history building across multiple completed planning sessions:\n- Multiple completed planning sessions in sequence\n- History context loading for new planning sessions\n- Proper context building with multiple completed plans\n- Context accumulation and retrieval\n\"\"\"\n\nimport json\nfrom typing import Optional\n\nfrom .conversation_base_test import ConversationBaseTest\n\n\nclass PlannerContinuationHistoryTest(ConversationBaseTest):\n \"\"\"Test planner tool's continuation history building across multiple completed sessions\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"planner_continuation_history\"\n\n @property\n def test_description(self) -> str:\n return \"Planner tool continuation history building across multiple completed planning sessions\"\n\n def run_test(self) -> bool:\n \"\"\"Test planner continuation history building across multiple completed sessions\"\"\"\n # Set up the test environment\n self.setUp()\n\n try:\n self.logger.info(\"Test: Planner continuation history validation\")\n\n # Test 1: Complete first planning session (microservices migration)\n if not self._test_first_planning_session():\n return False\n\n # Test 2: Complete second planning session with context from first\n if not self._test_second_planning_session():\n return False\n\n # Test 3: Complete third planning session with context from both previous\n if not self._test_third_planning_session():\n return False\n\n # Test 4: Validate context accumulation across all sessions\n if not self._test_context_accumulation():\n return False\n\n self.logger.info(\" βœ… All planner continuation history tests passed\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Planner continuation history test failed: {e}\")\n return False\n\n def _test_first_planning_session(self) -> bool:\n \"\"\"Complete first planning session - microservices migration\"\"\"\n try:\n self.logger.info(\" 2.1: First planning session - Microservices Migration\")\n\n # Step 1: Start migration planning\n self.logger.info(\" 2.1.1: Start migration planning\")\n response1, continuation_id = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"I need to plan a microservices migration for our monolithic e-commerce platform. Let me analyze the current monolith structure.\",\n \"step_number\": 1,\n \"total_steps\": 3,\n \"next_step_required\": True,\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start first planning session\")\n return False\n\n # Step 2: Domain identification\n self.logger.info(\" 2.1.2: Domain identification\")\n response2, _ = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"I've identified key domains: User Management, Product Catalog, Order Processing, Payment, and Inventory. Each will become a separate microservice.\",\n \"step_number\": 2,\n \"total_steps\": 3,\n \"next_step_required\": True,\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response2:\n self.logger.error(\"Failed step 2 of first planning session\")\n return False\n\n # Step 3: Complete migration plan\n self.logger.info(\" 2.1.3: Complete migration plan\")\n response3, _ = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Migration strategy: Phase 1 - Extract User Management service, Phase 2 - Product Catalog and Inventory services, Phase 3 - Order Processing and Payment services. Use API Gateway for service coordination.\",\n \"step_number\": 3,\n \"total_steps\": 3,\n \"next_step_required\": False, # Complete the session\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response3:\n self.logger.error(\"Failed to complete first planning session\")\n return False\n\n # Validate completion\n response3_data = self._parse_planner_response(response3)\n if not response3_data.get(\"planning_complete\"):\n self.logger.error(\"First planning session not marked as complete\")\n return False\n\n if not response3_data.get(\"plan_summary\"):\n self.logger.error(\"First planning session missing plan summary\")\n return False\n\n self.logger.info(\" βœ… First planning session completed successfully\")\n\n # Store for next test\n self.first_continuation_id = continuation_id\n return True\n\n except Exception as e:\n self.logger.error(f\"First planning session test failed: {e}\")\n return False\n\n def _test_second_planning_session(self) -> bool:\n \"\"\"Complete second planning session with context from first\"\"\"\n try:\n self.logger.info(\" 2.2: Second planning session - Database Strategy\")\n\n # Step 1: Start database planning with previous context\n self.logger.info(\" 2.2.1: Start database strategy with microservices context\")\n response1, new_continuation_id = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Now I need to plan the database strategy for the microservices architecture. I'll design how each service will manage its data.\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"continuation_id\": self.first_continuation_id, # Use first session's continuation_id\n },\n )\n\n if not response1 or not new_continuation_id:\n self.logger.error(\"Failed to start second planning session\")\n return False\n\n # Validate context loading\n response1_data = self._parse_planner_response(response1)\n if \"previous_plan_context\" not in response1_data:\n self.logger.error(\"Second session should load context from first completed session\")\n return False\n\n # Check context contains migration content\n context = response1_data[\"previous_plan_context\"].lower()\n if \"migration\" not in context and \"microservices\" not in context:\n self.logger.error(\"Context should contain migration/microservices content from first session\")\n return False\n\n self.logger.info(\" βœ… Second session loaded context from first completed session\")\n\n # Step 2: Complete database plan\n self.logger.info(\" 2.2.2: Complete database strategy\")\n response2, _ = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Database strategy: Each microservice gets its own database (database-per-service pattern). Use event sourcing for cross-service communication and eventual consistency. Implement CQRS for read/write separation.\",\n \"step_number\": 2,\n \"total_steps\": 2,\n \"next_step_required\": False, # Complete the session\n \"continuation_id\": new_continuation_id,\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to complete second planning session\")\n return False\n\n # Validate completion\n response2_data = self._parse_planner_response(response2)\n if not response2_data.get(\"planning_complete\"):\n self.logger.error(\"Second planning session not marked as complete\")\n return False\n\n self.logger.info(\" βœ… Second planning session completed successfully\")\n\n # Store for next test\n self.second_continuation_id = new_continuation_id\n return True\n\n except Exception as e:\n self.logger.error(f\"Second planning session test failed: {e}\")\n return False\n\n def _test_third_planning_session(self) -> bool:\n \"\"\"Complete third planning session with context from both previous\"\"\"\n try:\n self.logger.info(\" 2.3: Third planning session - Deployment Strategy\")\n\n # Step 1: Start deployment planning with accumulated context\n self.logger.info(\" 2.3.1: Start deployment strategy with accumulated context\")\n response1, new_continuation_id = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Now I need to plan the deployment strategy that supports both the microservices architecture and the database strategy. I'll design the infrastructure and deployment pipeline.\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"continuation_id\": self.second_continuation_id, # Use second session's continuation_id\n },\n )\n\n if not response1 or not new_continuation_id:\n self.logger.error(\"Failed to start third planning session\")\n return False\n\n # Validate context loading\n response1_data = self._parse_planner_response(response1)\n if \"previous_plan_context\" not in response1_data:\n self.logger.error(\"Third session should load context from previous completed sessions\")\n return False\n\n # Check context contains content from most recent completed session\n context = response1_data[\"previous_plan_context\"].lower()\n expected_terms = [\"database\", \"event sourcing\", \"cqrs\"]\n found_terms = [term for term in expected_terms if term in context]\n\n if len(found_terms) == 0:\n self.logger.error(\n f\"Context should contain database strategy content from second session. Context: {context[:200]}...\"\n )\n return False\n\n self.logger.info(\" βœ… Third session loaded context from most recent completed session\")\n\n # Step 2: Complete deployment plan\n self.logger.info(\" 2.3.2: Complete deployment strategy\")\n response2, _ = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Deployment strategy: Use Kubernetes for orchestration with Helm charts. Implement CI/CD pipeline with GitOps. Use service mesh (Istio) for traffic management, monitoring, and security. Deploy databases in separate namespaces with backup automation.\",\n \"step_number\": 2,\n \"total_steps\": 2,\n \"next_step_required\": False, # Complete the session\n \"continuation_id\": new_continuation_id,\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to complete third planning session\")\n return False\n\n # Validate completion\n response2_data = self._parse_planner_response(response2)\n if not response2_data.get(\"planning_complete\"):\n self.logger.error(\"Third planning session not marked as complete\")\n return False\n\n self.logger.info(\" βœ… Third planning session completed successfully\")\n\n # Store for final test\n self.third_continuation_id = new_continuation_id\n return True\n\n except Exception as e:\n self.logger.error(f\"Third planning session test failed: {e}\")\n return False\n\n def _test_context_accumulation(self) -> bool:\n \"\"\"Test that context properly accumulates across multiple completed sessions\"\"\"\n try:\n self.logger.info(\" 2.4: Testing context accumulation across all sessions\")\n\n # Start a new planning session that should load context from the most recent completed session\n self.logger.info(\" 2.4.1: Start monitoring planning with full context history\")\n response1, _ = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Finally, I need to plan the monitoring and observability strategy that works with the microservices, database, and deployment architecture.\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"continuation_id\": self.third_continuation_id, # Use third session's continuation_id\n },\n )\n\n if not response1:\n self.logger.error(\"Failed to start monitoring planning session\")\n return False\n\n # Validate context loading\n response1_data = self._parse_planner_response(response1)\n if \"previous_plan_context\" not in response1_data:\n self.logger.error(\"Final session should load context from previous completed sessions\")\n return False\n\n # Validate context contains most recent completed session content\n context = response1_data[\"previous_plan_context\"].lower()\n\n # Should contain deployment strategy content (most recent)\n deployment_terms = [\"kubernetes\", \"deployment\", \"istio\", \"gitops\"]\n found_deployment_terms = [term for term in deployment_terms if term in context]\n\n if len(found_deployment_terms) == 0:\n self.logger.error(f\"Context should contain deployment strategy content. Context: {context[:300]}...\")\n return False\n\n self.logger.info(\" βœ… Context accumulation working correctly\")\n\n # Validate this creates a complete planning session\n if not response1_data.get(\"planning_complete\"):\n self.logger.error(\"Final planning session should be marked as complete\")\n return False\n\n self.logger.info(\" βœ… Context accumulation test completed successfully\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Context accumulation test failed: {e}\")\n return False\n\n def call_mcp_tool(self, tool_name: str, params: dict) -> tuple[Optional[str], Optional[str]]:\n \"\"\"Call an MCP tool in-process - override for planner-specific response handling\"\"\"\n # Use in-process implementation to maintain conversation memory\n response_text, _ = self.call_mcp_tool_direct(tool_name, params)\n\n if not response_text:\n return None, None\n\n # Extract continuation_id from planner response specifically\n continuation_id = self._extract_planner_continuation_id(response_text)\n\n return response_text, continuation_id\n\n def _extract_planner_continuation_id(self, response_text: str) -> Optional[str]:\n \"\"\"Extract continuation_id from planner response\"\"\"\n try:\n # Parse the response - it's now direct JSON, not wrapped\n response_data = json.loads(response_text)\n return response_data.get(\"continuation_id\")\n\n except json.JSONDecodeError as e:\n self.logger.debug(f\"Failed to parse response for planner continuation_id: {e}\")\n return None\n\n def _parse_planner_response(self, response_text: str) -> dict:\n \"\"\"Parse planner tool JSON response\"\"\"\n try:\n # Parse the response - it's now direct JSON, not wrapped\n return json.loads(response_text)\n\n except json.JSONDecodeError as e:\n self.logger.error(f\"Failed to parse planner response as JSON: {e}\")\n self.logger.error(f\"Response text: {response_text[:500]}...\")\n return {}\n" }, { "path": "simulator_tests/test_planner_validation.py", "content": "#!/usr/bin/env python3\n\"\"\"\nPlannerWorkflow Tool Validation Test\n\nTests the planner tool's capabilities using the new workflow architecture.\nThis validates that the new workflow-based implementation maintains all the\nfunctionality of the original planner tool while using the workflow pattern\nlike the debug tool.\n\"\"\"\n\nimport json\nfrom typing import Optional\n\nfrom .conversation_base_test import ConversationBaseTest\n\n\nclass PlannerValidationTest(ConversationBaseTest):\n \"\"\"Test planner tool with new workflow architecture\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"planner_validation\"\n\n @property\n def test_description(self) -> str:\n return \"PlannerWorkflow tool validation with new workflow architecture\"\n\n def run_test(self) -> bool:\n \"\"\"Test planner tool capabilities\"\"\"\n # Set up the test environment\n self.setUp()\n\n try:\n self.logger.info(\"Test: PlannerWorkflow tool validation (new architecture)\")\n\n # Test 1: Single planning session with workflow architecture\n if not self._test_single_planning_session():\n return False\n\n # Test 2: Planning with continuation using workflow\n if not self._test_planning_with_continuation():\n return False\n\n # Test 3: Complex plan with deep thinking pauses\n if not self._test_complex_plan_deep_thinking():\n return False\n\n # Test 4: Self-contained completion (no expert analysis)\n if not self._test_self_contained_completion():\n return False\n\n # Test 5: Branching and revision with workflow\n if not self._test_branching_and_revision():\n return False\n\n # Test 6: Workflow file context behavior\n if not self._test_workflow_file_context():\n return False\n\n self.logger.info(\" βœ… All planner validation tests passed\")\n return True\n\n except Exception as e:\n self.logger.error(f\"PlannerWorkflow validation test failed: {e}\")\n return False\n\n def _test_single_planning_session(self) -> bool:\n \"\"\"Test a complete planning session with workflow architecture\"\"\"\n try:\n self.logger.info(\" 1.1: Testing single planning session with workflow\")\n\n # Step 1: Start planning\n self.logger.info(\" 1.1.1: Step 1 - Initial planning step\")\n response1, continuation_id = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"I need to plan a comprehensive API redesign for our legacy system. Let me start by analyzing the current state and identifying key requirements for the new API architecture.\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"model\": \"flash\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to get initial planning response\")\n return False\n\n # Parse and validate JSON response\n response1_data = self._parse_planner_response(response1)\n if not response1_data:\n return False\n\n # Validate step 1 response structure - expect pause_for_planner for next_step_required=True\n if not self._validate_step_response(response1_data, 1, 4, True, \"pause_for_planner\"):\n return False\n\n # Debug: Log the actual response structure to see what we're getting\n self.logger.debug(f\"Response structure: {list(response1_data.keys())}\")\n\n # Check workflow-specific response structure (more flexible)\n status_key = None\n for key in response1_data.keys():\n if key.endswith(\"_status\"):\n status_key = key\n break\n\n if not status_key:\n self.logger.error(f\"Missing workflow status field in response: {list(response1_data.keys())}\")\n return False\n\n self.logger.debug(f\"Found status field: {status_key}\")\n\n # Check required_actions for workflow guidance\n if not response1_data.get(\"required_actions\"):\n self.logger.error(\"Missing required_actions in workflow response\")\n return False\n\n self.logger.info(f\" βœ… Step 1 successful with workflow, continuation_id: {continuation_id}\")\n\n # Step 2: Continue planning\n self.logger.info(\" 1.1.2: Step 2 - API domain analysis\")\n response2, _ = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"After analyzing the current API, I can identify three main domains: User Management, Content Management, and Analytics. Let me design the new API structure with RESTful endpoints and proper versioning.\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"continuation_id\": continuation_id,\n \"model\": \"flash\",\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue planning to step 2\")\n return False\n\n response2_data = self._parse_planner_response(response2)\n if not self._validate_step_response(response2_data, 2, 4, True, \"pause_for_planner\"):\n return False\n\n # Check step history tracking in workflow (more flexible)\n status_key = None\n for key in response2_data.keys():\n if key.endswith(\"_status\"):\n status_key = key\n break\n\n if status_key:\n workflow_status = response2_data.get(status_key, {})\n step_history_length = workflow_status.get(\"step_history_length\", 0)\n if step_history_length < 2:\n self.logger.error(f\"Step history not properly tracked in workflow: {step_history_length}\")\n return False\n self.logger.debug(f\"Step history length: {step_history_length}\")\n else:\n self.logger.warning(\"No workflow status found, skipping step history check\")\n\n self.logger.info(\" βœ… Step 2 successful with workflow tracking\")\n\n # Step 3: Final step - should trigger completion\n self.logger.info(\" 1.1.3: Step 3 - Final planning step\")\n response3, _ = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"API redesign plan complete: Phase 1 - User Management API, Phase 2 - Content Management API, Phase 3 - Analytics API. Each phase includes proper authentication, rate limiting, and comprehensive documentation.\",\n \"step_number\": 3,\n \"total_steps\": 3, # Adjusted total\n \"next_step_required\": False, # Final step - should complete without expert analysis\n \"continuation_id\": continuation_id,\n \"model\": \"flash\",\n },\n )\n\n if not response3:\n self.logger.error(\"Failed to complete planning session\")\n return False\n\n response3_data = self._parse_planner_response(response3)\n if not response3_data:\n return False\n\n # Validate final response structure - should be self-contained completion\n if response3_data.get(\"status\") != \"planner_complete\":\n self.logger.error(f\"Expected status 'planner_complete', got '{response3_data.get('status')}'\")\n return False\n\n if not response3_data.get(\"planning_complete\"):\n self.logger.error(\"Expected planning_complete=true for final step\")\n return False\n\n # Should NOT have expert_analysis (self-contained)\n if \"expert_analysis\" in response3_data:\n self.logger.error(\"PlannerWorkflow should be self-contained without expert analysis\")\n return False\n\n # Check plan_summary exists\n if not response3_data.get(\"plan_summary\"):\n self.logger.error(\"Missing plan_summary in final step\")\n return False\n\n self.logger.info(\" βœ… Planning session completed successfully with workflow architecture\")\n\n # Store continuation_id for next test\n self.api_continuation_id = continuation_id\n return True\n\n except Exception as e:\n self.logger.error(f\"Single planning session test failed: {e}\")\n return False\n\n def _test_planning_with_continuation(self) -> bool:\n \"\"\"Test planning continuation with workflow architecture\"\"\"\n try:\n self.logger.info(\" 1.2: Testing planning continuation with workflow\")\n\n # Use continuation from previous test if available\n continuation_id = getattr(self, \"api_continuation_id\", None)\n if not continuation_id:\n # Start fresh if no continuation available\n self.logger.info(\" 1.2.0: Starting fresh planning session\")\n response0, continuation_id = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Planning API security strategy\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"model\": \"flash\",\n },\n )\n if not response0 or not continuation_id:\n self.logger.error(\"Failed to start fresh planning session\")\n return False\n\n # Test continuation step\n self.logger.info(\" 1.2.1: Continue planning session\")\n response1, _ = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Building on the API redesign, let me now plan the security implementation with OAuth 2.0, API keys, and rate limiting strategies.\",\n \"step_number\": 2,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"continuation_id\": continuation_id,\n \"model\": \"flash\",\n },\n )\n\n if not response1:\n self.logger.error(\"Failed to continue planning\")\n return False\n\n response1_data = self._parse_planner_response(response1)\n if not response1_data:\n return False\n\n # Validate continuation behavior\n if not self._validate_step_response(response1_data, 2, 2, True, \"pause_for_planner\"):\n return False\n\n # Check that continuation_id is preserved\n if response1_data.get(\"continuation_id\") != continuation_id:\n self.logger.error(\"Continuation ID not preserved in workflow\")\n return False\n\n self.logger.info(\" βœ… Planning continuation working with workflow\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Planning continuation test failed: {e}\")\n return False\n\n def _test_complex_plan_deep_thinking(self) -> bool:\n \"\"\"Test complex plan with deep thinking pauses\"\"\"\n try:\n self.logger.info(\" 1.3: Testing complex plan with deep thinking pauses\")\n\n # Start complex plan (β‰₯5 steps) - should trigger deep thinking\n self.logger.info(\" 1.3.1: Step 1 of complex plan (should trigger deep thinking)\")\n response1, continuation_id = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"I need to plan a complete digital transformation for our enterprise organization, including cloud migration, process automation, and cultural change management.\",\n \"step_number\": 1,\n \"total_steps\": 8, # Complex plan β‰₯5 steps\n \"next_step_required\": True,\n \"model\": \"flash\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start complex planning\")\n return False\n\n response1_data = self._parse_planner_response(response1)\n if not response1_data:\n return False\n\n # Should trigger deep thinking pause for complex plan\n if response1_data.get(\"status\") != \"pause_for_deep_thinking\":\n self.logger.error(\"Expected deep thinking pause for complex plan step 1\")\n return False\n\n if not response1_data.get(\"thinking_required\"):\n self.logger.error(\"Expected thinking_required=true for complex plan\")\n return False\n\n # Check required thinking actions\n required_thinking = response1_data.get(\"required_thinking\", [])\n if len(required_thinking) < 4:\n self.logger.error(\"Expected comprehensive thinking requirements for complex plan\")\n return False\n\n # Check for deep thinking guidance in next_steps\n next_steps = response1_data.get(\"next_steps\", \"\")\n if \"MANDATORY\" not in next_steps or \"deep thinking\" not in next_steps.lower():\n self.logger.error(\"Expected mandatory deep thinking guidance\")\n return False\n\n self.logger.info(\" βœ… Complex plan step 1 correctly triggered deep thinking pause\")\n\n # Step 2 of complex plan - should also trigger deep thinking\n self.logger.info(\" 1.3.2: Step 2 of complex plan (should trigger deep thinking)\")\n response2, _ = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"After deep analysis, I can see this transformation requires three parallel tracks: Technical Infrastructure, Business Process, and Human Capital. Let me design the coordination strategy.\",\n \"step_number\": 2,\n \"total_steps\": 8,\n \"next_step_required\": True,\n \"continuation_id\": continuation_id,\n \"model\": \"flash\",\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue complex planning\")\n return False\n\n response2_data = self._parse_planner_response(response2)\n if not response2_data:\n return False\n\n # Step 2 should also trigger deep thinking for complex plans\n if response2_data.get(\"status\") != \"pause_for_deep_thinking\":\n self.logger.error(\"Expected deep thinking pause for complex plan step 2\")\n return False\n\n self.logger.info(\" βœ… Complex plan step 2 correctly triggered deep thinking pause\")\n\n # Step 4 of complex plan - should use normal flow (after step 3)\n self.logger.info(\" 1.3.3: Step 4 of complex plan (should use normal flow)\")\n response4, _ = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Now moving to tactical planning: Phase 1 execution details with specific timelines and resource allocation for the technical infrastructure track.\",\n \"step_number\": 4,\n \"total_steps\": 8,\n \"next_step_required\": True,\n \"continuation_id\": continuation_id,\n \"model\": \"flash\",\n },\n )\n\n if not response4:\n self.logger.error(\"Failed to continue to step 4\")\n return False\n\n response4_data = self._parse_planner_response(response4)\n if not response4_data:\n return False\n\n # Step 4 should use normal flow (no more deep thinking pauses)\n if response4_data.get(\"status\") != \"pause_for_planner\":\n self.logger.error(\"Expected normal planning flow for step 4\")\n return False\n\n if response4_data.get(\"thinking_required\"):\n self.logger.error(\"Step 4 should not require special thinking pause\")\n return False\n\n self.logger.info(\" βœ… Complex plan transitions to normal flow after step 3\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Complex plan deep thinking test failed: {e}\")\n return False\n\n def _test_self_contained_completion(self) -> bool:\n \"\"\"Test self-contained completion without expert analysis\"\"\"\n try:\n self.logger.info(\" 1.4: Testing self-contained completion\")\n\n # Simple planning session that should complete without expert analysis\n self.logger.info(\" 1.4.1: Simple planning session\")\n response1, continuation_id = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Planning a simple website redesign with new color scheme and improved navigation.\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"model\": \"flash\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start simple planning\")\n return False\n\n # Final step - should complete without expert analysis\n self.logger.info(\" 1.4.2: Final step - self-contained completion\")\n response2, _ = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Website redesign plan complete: Phase 1 - Update color palette and typography, Phase 2 - Redesign navigation structure and user flows.\",\n \"step_number\": 2,\n \"total_steps\": 2,\n \"next_step_required\": False, # Final step\n \"continuation_id\": continuation_id,\n \"model\": \"flash\",\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to complete simple planning\")\n return False\n\n response2_data = self._parse_planner_response(response2)\n if not response2_data:\n return False\n\n # Validate self-contained completion\n if response2_data.get(\"status\") != \"planner_complete\":\n self.logger.error(\"Expected self-contained completion status\")\n return False\n\n # Should NOT call expert analysis\n if \"expert_analysis\" in response2_data:\n self.logger.error(\"PlannerWorkflow should not call expert analysis\")\n return False\n\n # Should have planning_complete flag\n if not response2_data.get(\"planning_complete\"):\n self.logger.error(\"Expected planning_complete=true\")\n return False\n\n # Should have plan_summary\n if not response2_data.get(\"plan_summary\"):\n self.logger.error(\"Expected plan_summary in completion\")\n return False\n\n # Check completion instructions\n output = response2_data.get(\"output\", {})\n if not output.get(\"instructions\"):\n self.logger.error(\"Missing output instructions for plan presentation\")\n return False\n\n self.logger.info(\" βœ… Self-contained completion working correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Self-contained completion test failed: {e}\")\n return False\n\n def _test_branching_and_revision(self) -> bool:\n \"\"\"Test branching and revision with workflow architecture\"\"\"\n try:\n self.logger.info(\" 1.5: Testing branching and revision with workflow\")\n\n # Start planning session for branching test\n self.logger.info(\" 1.5.1: Start planning for branching test\")\n response1, continuation_id = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Planning mobile app development strategy with different technology options to evaluate.\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"model\": \"flash\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start branching test\")\n return False\n\n # Create branch\n self.logger.info(\" 1.5.2: Create branch for React Native approach\")\n response2, _ = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Branch A: React Native approach - cross-platform development with shared codebase, faster development cycle, and consistent UI across platforms.\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"is_branch_point\": True,\n \"branch_from_step\": 1,\n \"branch_id\": \"react-native\",\n \"continuation_id\": continuation_id,\n \"model\": \"flash\",\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to create branch\")\n return False\n\n response2_data = self._parse_planner_response(response2)\n if not response2_data:\n return False\n\n # Validate branching in workflow\n metadata = response2_data.get(\"metadata\", {})\n if not metadata.get(\"is_branch_point\"):\n self.logger.error(\"Branch point not recorded in workflow\")\n return False\n\n if metadata.get(\"branch_id\") != \"react-native\":\n self.logger.error(\"Branch ID not properly recorded\")\n return False\n\n if \"react-native\" not in metadata.get(\"branches\", []):\n self.logger.error(\"Branch not added to branches list\")\n return False\n\n self.logger.info(\" βœ… Branching working with workflow architecture\")\n\n # Test revision\n self.logger.info(\" 1.5.3: Test revision capability\")\n response3, _ = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Revision of step 2: After consideration, let me revise the React Native approach to include performance optimizations and native module integration for critical features.\",\n \"step_number\": 3,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"is_step_revision\": True,\n \"revises_step_number\": 2,\n \"continuation_id\": continuation_id,\n \"model\": \"flash\",\n },\n )\n\n if not response3:\n self.logger.error(\"Failed to create revision\")\n return False\n\n response3_data = self._parse_planner_response(response3)\n if not response3_data:\n return False\n\n # Validate revision in workflow\n metadata = response3_data.get(\"metadata\", {})\n if not metadata.get(\"is_step_revision\"):\n self.logger.error(\"Step revision not recorded in workflow\")\n return False\n\n if metadata.get(\"revises_step_number\") != 2:\n self.logger.error(\"Revised step number not properly recorded\")\n return False\n\n self.logger.info(\" βœ… Revision working with workflow architecture\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Branching and revision test failed: {e}\")\n return False\n\n def _test_workflow_file_context(self) -> bool:\n \"\"\"Test workflow file context behavior (should be minimal for planner)\"\"\"\n try:\n self.logger.info(\" 1.6: Testing workflow file context behavior\")\n\n # Planner typically doesn't use files, but test the workflow handles this correctly\n self.logger.info(\" 1.6.1: Planning step with no files (normal case)\")\n response1, continuation_id = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Planning data architecture for analytics platform.\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"model\": \"flash\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start workflow file context test\")\n return False\n\n response1_data = self._parse_planner_response(response1)\n if not response1_data:\n return False\n\n # Planner workflow should not have file_context since it doesn't use files\n if \"file_context\" in response1_data:\n self.logger.info(\" ℹ️ Workflow file context present but should be minimal for planner\")\n\n # Final step\n self.logger.info(\" 1.6.2: Final step (should complete without file embedding)\")\n response2, _ = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Data architecture plan complete with data lakes, processing pipelines, and analytics layers.\",\n \"step_number\": 2,\n \"total_steps\": 2,\n \"next_step_required\": False,\n \"continuation_id\": continuation_id,\n \"model\": \"flash\",\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to complete workflow file context test\")\n return False\n\n response2_data = self._parse_planner_response(response2)\n if not response2_data:\n return False\n\n # Final step should complete self-contained\n if response2_data.get(\"status\") != \"planner_complete\":\n self.logger.error(\"Expected self-contained completion for planner workflow\")\n return False\n\n self.logger.info(\" βœ… Workflow file context behavior appropriate for planner\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Workflow file context test failed: {e}\")\n return False\n\n def call_mcp_tool(self, tool_name: str, params: dict) -> tuple[Optional[str], Optional[str]]:\n \"\"\"Call an MCP tool in-process - override for planner-specific response handling\"\"\"\n # Use in-process implementation to maintain conversation memory\n response_text, _ = self.call_mcp_tool_direct(tool_name, params)\n\n if not response_text:\n return None, None\n\n # Extract continuation_id from planner response specifically\n continuation_id = self._extract_planner_continuation_id(response_text)\n\n return response_text, continuation_id\n\n def _extract_planner_continuation_id(self, response_text: str) -> Optional[str]:\n \"\"\"Extract continuation_id from planner response\"\"\"\n try:\n # Parse the response\n response_data = json.loads(response_text)\n return response_data.get(\"continuation_id\")\n\n except json.JSONDecodeError as e:\n self.logger.debug(f\"Failed to parse response for planner continuation_id: {e}\")\n return None\n\n def _parse_planner_response(self, response_text: str) -> dict:\n \"\"\"Parse planner tool JSON response\"\"\"\n try:\n # Parse the response - it should be direct JSON\n return json.loads(response_text)\n\n except json.JSONDecodeError as e:\n self.logger.error(f\"Failed to parse planner response as JSON: {e}\")\n self.logger.error(f\"Response text: {response_text[:500]}...\")\n return {}\n\n def _validate_step_response(\n self,\n response_data: dict,\n expected_step: int,\n expected_total: int,\n expected_next_required: bool,\n expected_status: str,\n ) -> bool:\n \"\"\"Validate a planner step response structure\"\"\"\n try:\n # Check status\n if response_data.get(\"status\") != expected_status:\n self.logger.error(f\"Expected status '{expected_status}', got '{response_data.get('status')}'\")\n return False\n\n # Check step number\n if response_data.get(\"step_number\") != expected_step:\n self.logger.error(f\"Expected step_number {expected_step}, got {response_data.get('step_number')}\")\n return False\n\n # Check total steps\n if response_data.get(\"total_steps\") != expected_total:\n self.logger.error(f\"Expected total_steps {expected_total}, got {response_data.get('total_steps')}\")\n return False\n\n # Check next_step_required\n if response_data.get(\"next_step_required\") != expected_next_required:\n self.logger.error(\n f\"Expected next_step_required {expected_next_required}, got {response_data.get('next_step_required')}\"\n )\n return False\n\n # Check step_content exists\n if not response_data.get(\"step_content\"):\n self.logger.error(\"Missing step_content in response\")\n return False\n\n # Check next_steps guidance\n if not response_data.get(\"next_steps\"):\n self.logger.error(\"Missing next_steps guidance in response\")\n return False\n\n return True\n\n except Exception as e:\n self.logger.error(f\"Error validating step response: {e}\")\n return False\n" }, { "path": "simulator_tests/test_planner_validation_old.py", "content": "#!/usr/bin/env python3\n\"\"\"\nPlanner Tool Validation Test\n\nTests the planner tool's sequential planning capabilities including:\n- Step-by-step planning with proper JSON responses\n- Continuation logic across planning sessions\n- Branching and revision capabilities\n- Previous plan context loading\n- Plan completion and summary storage\n\"\"\"\n\nimport json\nfrom typing import Optional\n\nfrom .conversation_base_test import ConversationBaseTest\n\n\nclass PlannerValidationTest(ConversationBaseTest):\n \"\"\"Test planner tool's sequential planning and continuation features\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"planner_validation\"\n\n @property\n def test_description(self) -> str:\n return \"Planner tool sequential planning and continuation validation\"\n\n def run_test(self) -> bool:\n \"\"\"Test planner tool sequential planning capabilities\"\"\"\n # Set up the test environment\n self.setUp()\n\n try:\n self.logger.info(\"Test: Planner tool validation\")\n\n # Test 1: Single planning session with multiple steps\n if not self._test_single_planning_session():\n return False\n\n # Test 2: Plan completion and continuation to new planning session\n if not self._test_plan_continuation():\n return False\n\n # Test 3: Branching and revision capabilities\n if not self._test_branching_and_revision():\n return False\n\n self.logger.info(\" βœ… All planner validation tests passed\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Planner validation test failed: {e}\")\n return False\n\n def _test_single_planning_session(self) -> bool:\n \"\"\"Test a complete planning session with multiple steps\"\"\"\n try:\n self.logger.info(\" 1.1: Testing single planning session\")\n\n # Step 1: Start planning\n self.logger.info(\" 1.1.1: Step 1 - Initial planning step\")\n response1, continuation_id = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"I need to plan a microservices migration for our monolithic e-commerce platform. Let me start by understanding the current architecture and identifying the key business domains.\",\n \"step_number\": 1,\n \"total_steps\": 5,\n \"next_step_required\": True,\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to get initial planning response\")\n return False\n\n # Parse and validate JSON response\n response1_data = self._parse_planner_response(response1)\n if not response1_data:\n return False\n\n # Validate step 1 response structure\n if not self._validate_step_response(response1_data, 1, 5, True, \"planning_success\"):\n return False\n\n self.logger.info(f\" βœ… Step 1 successful, continuation_id: {continuation_id}\")\n\n # Step 2: Continue planning\n self.logger.info(\" 1.1.2: Step 2 - Domain identification\")\n response2, _ = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Based on my analysis, I can identify the main business domains: User Management, Product Catalog, Order Processing, Payment, and Inventory. Let me plan how to extract these into separate services.\",\n \"step_number\": 2,\n \"total_steps\": 5,\n \"next_step_required\": True,\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue planning to step 2\")\n return False\n\n response2_data = self._parse_planner_response(response2)\n if not self._validate_step_response(response2_data, 2, 5, True, \"planning_success\"):\n return False\n\n self.logger.info(\" βœ… Step 2 successful\")\n\n # Step 3: Final step\n self.logger.info(\" 1.1.3: Step 3 - Final planning step\")\n response3, _ = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Now I'll create a phased migration strategy: Phase 1 - Extract User Management, Phase 2 - Product Catalog and Inventory, Phase 3 - Order Processing and Payment services. This completes the initial migration plan.\",\n \"step_number\": 3,\n \"total_steps\": 3, # Adjusted total\n \"next_step_required\": False, # Final step\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response3:\n self.logger.error(\"Failed to complete planning session\")\n return False\n\n response3_data = self._parse_planner_response(response3)\n if not self._validate_final_step_response(response3_data, 3, 3):\n return False\n\n self.logger.info(\" βœ… Planning session completed successfully\")\n\n # Store continuation_id for next test\n self.migration_continuation_id = continuation_id\n return True\n\n except Exception as e:\n self.logger.error(f\"Single planning session test failed: {e}\")\n return False\n\n def _test_plan_continuation(self) -> bool:\n \"\"\"Test continuing from a previous completed plan\"\"\"\n try:\n self.logger.info(\" 1.2: Testing plan continuation with previous context\")\n\n # Start a new planning session using the continuation_id from previous completed plan\n self.logger.info(\" 1.2.1: New planning session with previous plan context\")\n response1, new_continuation_id = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Now that I have the microservices migration plan, let me plan the database strategy. I need to decide how to handle data consistency across the new services.\",\n \"step_number\": 1, # New planning session starts at step 1\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"continuation_id\": self.migration_continuation_id, # Use previous plan's continuation_id\n },\n )\n\n if not response1 or not new_continuation_id:\n self.logger.error(\"Failed to start new planning session with context\")\n return False\n\n response1_data = self._parse_planner_response(response1)\n if not response1_data:\n return False\n\n # Should have previous plan context\n if \"previous_plan_context\" not in response1_data:\n self.logger.error(\"Expected previous_plan_context in new planning session\")\n return False\n\n # Check for key terms from the previous plan\n context = response1_data[\"previous_plan_context\"].lower()\n if \"migration\" not in context and \"plan\" not in context:\n self.logger.error(\"Previous plan context doesn't contain expected content\")\n return False\n\n self.logger.info(\" βœ… New planning session loaded previous plan context\")\n\n # Continue the new planning session (step 2+ should NOT load context)\n self.logger.info(\" 1.2.2: Continue new planning session (no context loading)\")\n response2, _ = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"I'll implement a database-per-service pattern with eventual consistency using event sourcing for cross-service communication.\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"continuation_id\": new_continuation_id, # Same continuation, step 2\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue new planning session\")\n return False\n\n response2_data = self._parse_planner_response(response2)\n if not response2_data:\n return False\n\n # Step 2+ should NOT have previous_plan_context (only step 1 with continuation_id gets context)\n if \"previous_plan_context\" in response2_data:\n self.logger.error(\"Step 2 should NOT have previous_plan_context\")\n return False\n\n self.logger.info(\" βœ… Step 2 correctly has no previous context (as expected)\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Plan continuation test failed: {e}\")\n return False\n\n def _test_branching_and_revision(self) -> bool:\n \"\"\"Test branching and revision capabilities\"\"\"\n try:\n self.logger.info(\" 1.3: Testing branching and revision capabilities\")\n\n # Start a new planning session for testing branching\n self.logger.info(\" 1.3.1: Start planning session for branching test\")\n response1, continuation_id = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Let me plan the deployment strategy for the microservices. I'll consider different deployment options.\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start branching test planning session\")\n return False\n\n # Test branching\n self.logger.info(\" 1.3.2: Create a branch from step 1\")\n response2, _ = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Branch A: I'll explore Kubernetes deployment with service mesh (Istio) for advanced traffic management and observability.\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"is_branch_point\": True,\n \"branch_from_step\": 1,\n \"branch_id\": \"kubernetes-istio\",\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to create branch\")\n return False\n\n response2_data = self._parse_planner_response(response2)\n if not response2_data:\n return False\n\n # Validate branching metadata\n metadata = response2_data.get(\"metadata\", {})\n if not metadata.get(\"is_branch_point\"):\n self.logger.error(\"Branch point not properly recorded in metadata\")\n return False\n\n if metadata.get(\"branch_id\") != \"kubernetes-istio\":\n self.logger.error(\"Branch ID not properly recorded\")\n return False\n\n if \"kubernetes-istio\" not in metadata.get(\"branches\", []):\n self.logger.error(\"Branch not recorded in branches list\")\n return False\n\n self.logger.info(\" βœ… Branching working correctly\")\n\n # Test revision\n self.logger.info(\" 1.3.3: Revise step 2\")\n response3, _ = self.call_mcp_tool(\n \"planner\",\n {\n \"step\": \"Revision: Actually, let me revise the Kubernetes approach. I'll use a simpler deployment initially, then migrate to Kubernetes later.\",\n \"step_number\": 3,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"is_step_revision\": True,\n \"revises_step_number\": 2,\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response3:\n self.logger.error(\"Failed to create revision\")\n return False\n\n response3_data = self._parse_planner_response(response3)\n if not response3_data:\n return False\n\n # Validate revision metadata\n metadata = response3_data.get(\"metadata\", {})\n if not metadata.get(\"is_step_revision\"):\n self.logger.error(\"Step revision not properly recorded in metadata\")\n return False\n\n if metadata.get(\"revises_step_number\") != 2:\n self.logger.error(\"Revised step number not properly recorded\")\n return False\n\n self.logger.info(\" βœ… Revision working correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Branching and revision test failed: {e}\")\n return False\n\n def call_mcp_tool(self, tool_name: str, params: dict) -> tuple[Optional[str], Optional[str]]:\n \"\"\"Call an MCP tool in-process - override for planner-specific response handling\"\"\"\n # Use in-process implementation to maintain conversation memory\n response_text, _ = self.call_mcp_tool_direct(tool_name, params)\n\n if not response_text:\n return None, None\n\n # Extract continuation_id from planner response specifically\n continuation_id = self._extract_planner_continuation_id(response_text)\n\n return response_text, continuation_id\n\n def _extract_planner_continuation_id(self, response_text: str) -> Optional[str]:\n \"\"\"Extract continuation_id from planner response\"\"\"\n try:\n # Parse the response - it's now direct JSON, not wrapped\n response_data = json.loads(response_text)\n return response_data.get(\"continuation_id\")\n\n except json.JSONDecodeError as e:\n self.logger.debug(f\"Failed to parse response for planner continuation_id: {e}\")\n return None\n\n def _parse_planner_response(self, response_text: str) -> dict:\n \"\"\"Parse planner tool JSON response\"\"\"\n try:\n # Parse the response - it's now direct JSON, not wrapped\n return json.loads(response_text)\n\n except json.JSONDecodeError as e:\n self.logger.error(f\"Failed to parse planner response as JSON: {e}\")\n self.logger.error(f\"Response text: {response_text[:500]}...\")\n return {}\n\n def _validate_step_response(\n self,\n response_data: dict,\n expected_step: int,\n expected_total: int,\n expected_next_required: bool,\n expected_status: str,\n ) -> bool:\n \"\"\"Validate a planning step response structure\"\"\"\n try:\n # Check status\n if response_data.get(\"status\") != expected_status:\n self.logger.error(f\"Expected status '{expected_status}', got '{response_data.get('status')}'\")\n return False\n\n # Check step number\n if response_data.get(\"step_number\") != expected_step:\n self.logger.error(f\"Expected step_number {expected_step}, got {response_data.get('step_number')}\")\n return False\n\n # Check total steps\n if response_data.get(\"total_steps\") != expected_total:\n self.logger.error(f\"Expected total_steps {expected_total}, got {response_data.get('total_steps')}\")\n return False\n\n # Check next_step_required\n if response_data.get(\"next_step_required\") != expected_next_required:\n self.logger.error(\n f\"Expected next_step_required {expected_next_required}, got {response_data.get('next_step_required')}\"\n )\n return False\n\n # Check that step_content exists\n if not response_data.get(\"step_content\"):\n self.logger.error(\"Missing step_content in response\")\n return False\n\n # Check metadata exists\n if \"metadata\" not in response_data:\n self.logger.error(\"Missing metadata in response\")\n return False\n\n # Check next_steps guidance\n if not response_data.get(\"next_steps\"):\n self.logger.error(\"Missing next_steps guidance in response\")\n return False\n\n return True\n\n except Exception as e:\n self.logger.error(f\"Error validating step response: {e}\")\n return False\n\n def _validate_final_step_response(self, response_data: dict, expected_step: int, expected_total: int) -> bool:\n \"\"\"Validate a final planning step response\"\"\"\n try:\n # Basic step validation\n if not self._validate_step_response(\n response_data, expected_step, expected_total, False, \"planning_success\"\n ):\n return False\n\n # Check planning_complete flag\n if not response_data.get(\"planning_complete\"):\n self.logger.error(\"Expected planning_complete=true for final step\")\n return False\n\n # Check plan_summary exists\n if not response_data.get(\"plan_summary\"):\n self.logger.error(\"Missing plan_summary in final step\")\n return False\n\n # Check plan_summary contains expected content\n plan_summary = response_data.get(\"plan_summary\", \"\")\n if \"COMPLETE PLAN:\" not in plan_summary:\n self.logger.error(\"plan_summary doesn't contain 'COMPLETE PLAN:' marker\")\n return False\n\n # Check next_steps mentions completion\n next_steps = response_data.get(\"next_steps\", \"\")\n if \"complete\" not in next_steps.lower():\n self.logger.error(\"next_steps doesn't indicate planning completion\")\n return False\n\n return True\n\n except Exception as e:\n self.logger.error(f\"Error validating final step response: {e}\")\n return False\n" }, { "path": "simulator_tests/test_precommitworkflow_validation.py", "content": "#!/usr/bin/env python3\n\"\"\"\nPrecommitWorkflow Tool Validation Test\n\nTests the precommit tool's capabilities using the new workflow architecture.\nThis validates that the workflow-based pre-commit validation provides step-by-step\nanalysis with proper investigation guidance and expert analysis integration.\n\"\"\"\n\nimport json\nfrom typing import Optional\n\nfrom .conversation_base_test import ConversationBaseTest\n\n\nclass PrecommitWorkflowValidationTest(ConversationBaseTest):\n \"\"\"Test precommit tool with new workflow architecture\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"precommit_validation\"\n\n @property\n def test_description(self) -> str:\n return \"PrecommitWorkflow tool validation with new workflow architecture\"\n\n def run_test(self) -> bool:\n \"\"\"Test precommit tool capabilities\"\"\"\n # Set up the test environment\n self.setUp()\n\n try:\n self.logger.info(\"Test: PrecommitWorkflow tool validation (new architecture)\")\n\n # Create test git repository structure with changes\n self._create_test_git_changes()\n\n # Test 1: Single validation session with multiple steps\n if not self._test_single_validation_session():\n return False\n\n # Test 2: Validation flow that requires refocusing\n if not self._test_validation_refocus_flow():\n return False\n\n # Test 3: Complete validation with expert analysis\n if not self._test_complete_validation_with_analysis():\n return False\n\n # Test 4: Certain confidence behavior\n if not self._test_certain_confidence():\n return False\n\n # Test 5: Context-aware file embedding\n if not self._test_context_aware_file_embedding():\n return False\n\n # Test 6: Multi-step file context optimization\n if not self._test_multi_step_file_context():\n return False\n\n self.logger.info(\" βœ… All precommit validation tests passed\")\n return True\n\n except Exception as e:\n self.logger.error(f\"PrecommitWorkflow validation test failed: {e}\")\n return False\n\n def _create_test_git_changes(self):\n \"\"\"Create test files simulating git changes for pre-commit validation\"\"\"\n # Create a new API endpoint with potential security issues\n new_api_code = \"\"\"#!/usr/bin/env python3\nfrom flask import Flask, request, jsonify\nimport sqlite3\nimport os\n\napp = Flask(__name__)\n\n@app.route('/api/user/', methods=['GET'])\ndef get_user(user_id):\n \\\"\\\"\\\"Get user information by ID\\\"\\\"\\\"\n # Potential SQL injection vulnerability\n conn = sqlite3.connect('users.db')\n cursor = conn.cursor()\n\n # BUG: Direct string interpolation creates SQL injection risk\n query = f\"SELECT * FROM users WHERE id = {user_id}\"\n cursor.execute(query)\n\n result = cursor.fetchone()\n conn.close()\n\n if result:\n return jsonify({\n 'id': result[0],\n 'username': result[1],\n 'email': result[2],\n 'password_hash': result[3] # Security issue: exposing password hash\n })\n else:\n return jsonify({'error': 'User not found'}), 404\n\n@app.route('/api/admin/users', methods=['GET'])\ndef list_all_users():\n \\\"\\\"\\\"Admin endpoint to list all users\\\"\\\"\\\"\n # Missing authentication check\n conn = sqlite3.connect('users.db')\n cursor = conn.cursor()\n cursor.execute(\"SELECT id, username, email FROM users\")\n\n users = []\n for row in cursor.fetchall():\n users.append({\n 'id': row[0],\n 'username': row[1],\n 'email': row[2]\n })\n\n conn.close()\n return jsonify(users)\n\nif __name__ == '__main__':\n # Debug mode in production is a security risk\n app.run(debug=True, host='0.0.0.0')\n\"\"\"\n\n # Create configuration file with issues\n config_code = \"\"\"#!/usr/bin/env python3\nimport os\n\n# Database configuration\nDATABASE_URL = os.getenv('DATABASE_URL', 'sqlite:///users.db')\n\n# Security settings\nSECRET_KEY = \"hardcoded-secret-key-123\" # Security issue: hardcoded secret\nDEBUG_MODE = True # Should be environment-based\n\n# API settings\nAPI_RATE_LIMIT = 1000 # Very high, no rate limiting effectively\nMAX_FILE_UPLOAD = 50 * 1024 * 1024 # 50MB - quite large\n\n# Missing important security headers configuration\nCORS_ORIGINS = \"*\" # Security issue: allows all origins\n\"\"\"\n\n # Create test files\n self.api_file = self.create_additional_test_file(\"api_endpoints.py\", new_api_code)\n self.config_file = self.create_additional_test_file(\"config.py\", config_code)\n self.logger.info(f\" βœ… Created test files: {self.api_file}, {self.config_file}\")\n\n # Create change description\n change_description = \"\"\"COMMIT DESCRIPTION:\nAdded new user API endpoints and configuration for user management system.\n\nCHANGES MADE:\n- Added GET /api/user/ endpoint to retrieve user information\n- Added GET /api/admin/users endpoint for admin user listing\n- Added configuration file with database and security settings\n- Set up Flask application with basic routing\n\nREQUIREMENTS:\n- User data should be retrievable by ID\n- Admin should be able to list all users\n- System should be configurable via environment variables\n- Security should be properly implemented\n\"\"\"\n\n self.changes_file = self.create_additional_test_file(\"commit_description.txt\", change_description)\n self.logger.info(f\" βœ… Created change description: {self.changes_file}\")\n\n def _test_single_validation_session(self) -> bool:\n \"\"\"Test a complete validation session with multiple steps\"\"\"\n try:\n self.logger.info(\" 1.1: Testing single validation session\")\n\n # Step 1: Start validation\n self.logger.info(\" 1.1.1: Step 1 - Initial validation plan\")\n response1, continuation_id = self.call_mcp_tool(\n \"precommit\",\n {\n \"step\": \"I need to perform comprehensive pre-commit validation for new API endpoints. Let me start by analyzing the changes and identifying potential issues.\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"New user API endpoints and configuration added. Need to examine for security, performance, and best practices.\",\n \"files_checked\": [self.changes_file],\n \"relevant_files\": [self.changes_file],\n \"path\": self.test_dir, # Required for step 1\n \"review_type\": \"full\",\n \"severity_filter\": \"all\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to get initial validation response\")\n return False\n\n # Parse and validate JSON response\n response1_data = self._parse_precommit_response(response1)\n if not response1_data:\n return False\n\n # Validate step 1 response structure - expect pause_for_validation for next_step_required=True\n if not self._validate_step_response(response1_data, 1, 4, True, \"pause_for_validation\"):\n return False\n\n self.logger.info(f\" βœ… Step 1 successful, continuation_id: {continuation_id}\")\n\n # Step 2: Examine the code for issues\n self.logger.info(\" 1.1.2: Step 2 - Code examination\")\n response2, _ = self.call_mcp_tool(\n \"precommit\",\n {\n \"step\": \"Now examining the API endpoint implementation and configuration for security vulnerabilities and best practices violations.\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Found multiple critical security issues: SQL injection vulnerability in get_user(), hardcoded secrets in config, missing authentication, and password hash exposure.\",\n \"files_checked\": [self.changes_file, self.api_file, self.config_file],\n \"relevant_files\": [self.api_file, self.config_file],\n \"relevant_context\": [\"get_user\", \"list_all_users\"],\n \"issues_found\": [\n {\"severity\": \"critical\", \"description\": \"SQL injection vulnerability in user lookup\"},\n {\"severity\": \"high\", \"description\": \"Hardcoded secret key in configuration\"},\n {\"severity\": \"high\", \"description\": \"Password hash exposed in API response\"},\n {\"severity\": \"medium\", \"description\": \"Missing authentication on admin endpoint\"},\n ],\n # Assessment field removed - using precommit_type instead\n # Confidence field removed - using precommit_type instead\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue validation to step 2\")\n return False\n\n response2_data = self._parse_precommit_response(response2)\n if not self._validate_step_response(response2_data, 2, 4, True, \"pause_for_validation\"):\n return False\n\n # Check validation status tracking\n validation_status = response2_data.get(\"validation_status\", {})\n if validation_status.get(\"files_checked\", 0) < 3:\n self.logger.error(\"Files checked count not properly tracked\")\n return False\n\n if validation_status.get(\"issues_identified\", 0) != 4:\n self.logger.error(\"Issues found not properly tracked\")\n return False\n\n if validation_status.get(\"precommit_type\") != \"external\":\n self.logger.error(\"Precommit type not properly tracked\")\n return False\n\n self.logger.info(\" βœ… Step 2 successful with proper tracking\")\n\n # Store continuation_id for next test\n self.validation_continuation_id = continuation_id\n return True\n\n except Exception as e:\n self.logger.error(f\"Single validation session test failed: {e}\")\n return False\n\n def _test_validation_refocus_flow(self) -> bool:\n \"\"\"Test validation workflow that requires refocusing to revise findings\"\"\"\n try:\n self.logger.info(\" 1.2: Testing validation refocus workflow\")\n\n # Start a new validation for testing refocus behaviour\n self.logger.info(\" 1.2.1: Start validation for refocus test\")\n response1, continuation_id = self.call_mcp_tool(\n \"precommit\",\n {\n \"step\": \"Validating database connection optimization changes\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Initial analysis shows database connection pooling implementation\",\n \"files_checked\": [\"/db/connection.py\"],\n \"relevant_files\": [\"/db/connection.py\"],\n \"path\": self.test_dir,\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start refocus test validation\")\n return False\n\n # Step 2: Wrong direction\n self.logger.info(\" 1.2.2: Step 2 - Wrong validation focus\")\n response2, _ = self.call_mcp_tool(\n \"precommit\",\n {\n \"step\": \"Focusing on connection pool size optimization\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Connection pool configuration seems reasonable, might be looking in wrong place\",\n \"files_checked\": [\"/db/connection.py\", \"/config/database.py\"],\n \"relevant_files\": [],\n # Assessment fields removed - using precommit_type instead\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue to step 2\")\n return False\n\n # Step 3: Shift investigation focus\n self.logger.info(\" 1.2.3: Step 3 - Refocus and revise approach\")\n response3, _ = self.call_mcp_tool(\n \"precommit\",\n {\n \"step\": \"Refocusing - the issue might not be database configuration. Let me examine the actual SQL queries and data access patterns instead.\",\n \"step_number\": 3,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Found inefficient N+1 query pattern in user data loading causing performance issues\",\n \"files_checked\": [\"/models/user.py\"],\n \"relevant_files\": [\"/models/user.py\"],\n \"relevant_context\": [\"User.load_profile\"],\n \"issues_found\": [\n {\"severity\": \"medium\", \"description\": \"N+1 query pattern in user profile loading\"}\n ],\n # Assessment fields removed - using precommit_type instead\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response3:\n self.logger.error(\"Failed to refocus\")\n return False\n\n response3_data = self._parse_precommit_response(response3)\n if not self._validate_step_response(response3_data, 3, 4, True, \"pause_for_validation\"):\n return False\n\n self.logger.info(\" βœ… Refocus flow working correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Refocus test failed: {e}\")\n return False\n\n def _test_complete_validation_with_analysis(self) -> bool:\n \"\"\"Test complete validation ending with expert analysis\"\"\"\n try:\n self.logger.info(\" 1.3: Testing complete validation with expert analysis\")\n\n # Use the continuation from first test\n continuation_id = getattr(self, \"validation_continuation_id\", None)\n if not continuation_id:\n # Start fresh if no continuation available\n self.logger.info(\" 1.3.0: Starting fresh validation\")\n response0, continuation_id = self.call_mcp_tool(\n \"precommit\",\n {\n \"step\": \"Validating the security fixes for API endpoints\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"findings\": \"Found critical security vulnerabilities in API implementation\",\n \"files_checked\": [self.api_file],\n \"relevant_files\": [self.api_file],\n \"relevant_context\": [\"get_user\", \"list_all_users\"],\n \"issues_found\": [{\"severity\": \"critical\", \"description\": \"SQL injection vulnerability\"}],\n \"path\": self.test_dir,\n },\n )\n if not response0 or not continuation_id:\n self.logger.error(\"Failed to start fresh validation\")\n return False\n\n # Final step - trigger expert analysis\n self.logger.info(\" 1.3.1: Final step - complete validation\")\n response_final, _ = self.call_mcp_tool(\n \"precommit\",\n {\n \"step\": \"Validation complete. I have identified all critical security issues and missing safeguards in the new API endpoints.\",\n \"step_number\": 2,\n \"total_steps\": 2,\n \"next_step_required\": False, # Final step - triggers expert analysis\n \"findings\": \"Comprehensive analysis complete: SQL injection, hardcoded secrets, missing authentication, password exposure, and insecure defaults all identified with specific fixes needed.\",\n \"files_checked\": [self.api_file, self.config_file],\n \"relevant_files\": [self.api_file, self.config_file],\n \"relevant_context\": [\"get_user\", \"list_all_users\", \"SECRET_KEY\", \"DEBUG_MODE\"],\n \"issues_found\": [\n {\"severity\": \"critical\", \"description\": \"SQL injection vulnerability in user lookup query\"},\n {\"severity\": \"high\", \"description\": \"Hardcoded secret key exposes application security\"},\n {\"severity\": \"high\", \"description\": \"Password hash exposed in API response\"},\n {\"severity\": \"medium\", \"description\": \"Missing authentication on admin endpoint\"},\n {\"severity\": \"medium\", \"description\": \"Debug mode enabled in production configuration\"},\n ],\n # Confidence field removed - using precommit_type instead\n \"continuation_id\": continuation_id,\n \"model\": \"flash\", # Use flash for expert analysis\n },\n )\n\n if not response_final:\n self.logger.error(\"Failed to complete validation\")\n return False\n\n response_final_data = self._parse_precommit_response(response_final)\n if not response_final_data:\n return False\n\n # Validate final response structure - expect calling_expert_analysis for next_step_required=False\n if response_final_data.get(\"status\") != \"calling_expert_analysis\":\n self.logger.error(\n f\"Expected status 'calling_expert_analysis', got '{response_final_data.get('status')}'\"\n )\n return False\n\n if not response_final_data.get(\"validation_complete\"):\n self.logger.error(\"Expected validation_complete=true for final step\")\n return False\n\n # Check for expert analysis\n if \"expert_analysis\" not in response_final_data:\n self.logger.error(\"Missing expert_analysis in final response\")\n return False\n\n expert_analysis = response_final_data.get(\"expert_analysis\", {})\n\n # Check for expected analysis content (checking common patterns)\n analysis_text = json.dumps(expert_analysis, ensure_ascii=False).lower()\n\n # Look for security issue identification\n security_indicators = [\"sql\", \"injection\", \"security\", \"hardcoded\", \"secret\", \"authentication\"]\n found_indicators = sum(1 for indicator in security_indicators if indicator in analysis_text)\n\n if found_indicators >= 3:\n self.logger.info(\" βœ… Expert analysis identified security issues correctly\")\n else:\n self.logger.warning(\n f\" ⚠️ Expert analysis may not have fully identified security issues (found {found_indicators}/6 indicators)\"\n )\n\n # Check complete validation summary\n if \"complete_validation\" not in response_final_data:\n self.logger.error(\"Missing complete_validation in final response\")\n return False\n\n complete_validation = response_final_data[\"complete_validation\"]\n if not complete_validation.get(\"relevant_context\"):\n self.logger.error(\"Missing relevant context in complete validation\")\n return False\n\n if \"get_user\" not in complete_validation[\"relevant_context\"]:\n self.logger.error(\"Expected function not found in validation summary\")\n return False\n\n self.logger.info(\" βœ… Complete validation with expert analysis successful\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Complete validation test failed: {e}\")\n return False\n\n def _test_certain_confidence(self) -> bool:\n \"\"\"Test certain confidence behavior - should skip expert analysis\"\"\"\n try:\n self.logger.info(\" 1.4: Testing certain confidence behavior\")\n\n # Test certain confidence - should skip expert analysis\n self.logger.info(\" 1.4.1: Certain confidence validation\")\n response_certain, _ = self.call_mcp_tool(\n \"precommit\",\n {\n \"step\": \"I have confirmed all security issues with 100% certainty: SQL injection, hardcoded secrets, and missing authentication.\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False, # Final step\n \"findings\": \"All critical issues identified: parameterized queries needed, environment variables for secrets, authentication middleware required, and debug mode must be disabled for production.\",\n \"files_checked\": [self.api_file, self.config_file],\n \"relevant_files\": [self.api_file, self.config_file],\n \"relevant_context\": [\"get_user\", \"list_all_users\"],\n \"issues_found\": [\n {\n \"severity\": \"critical\",\n \"description\": \"SQL injection vulnerability - fix with parameterized queries\",\n },\n {\"severity\": \"high\", \"description\": \"Hardcoded secret - use environment variables\"},\n {\"severity\": \"medium\", \"description\": \"Missing authentication - add middleware\"},\n ],\n \"precommit_type\": \"internal\", # This should skip expert analysis\n \"path\": self.test_dir,\n \"model\": \"flash\",\n },\n )\n\n if not response_certain:\n self.logger.error(\"Failed to test certain confidence\")\n return False\n\n response_certain_data = self._parse_precommit_response(response_certain)\n if not response_certain_data:\n return False\n\n # Validate certain confidence response - should skip expert analysis\n if response_certain_data.get(\"status\") != \"validation_complete_ready_for_commit\":\n self.logger.error(\n f\"Expected status 'validation_complete_ready_for_commit', got '{response_certain_data.get('status')}'\"\n )\n return False\n\n if not response_certain_data.get(\"skip_expert_analysis\"):\n self.logger.error(\"Expected skip_expert_analysis=true for certain confidence\")\n return False\n\n expert_analysis = response_certain_data.get(\"expert_analysis\", {})\n if expert_analysis.get(\"status\") != \"skipped_due_to_internal_analysis_type\":\n self.logger.error(\"Expert analysis should be skipped for certain confidence\")\n return False\n\n self.logger.info(\" βœ… Certain confidence behavior working correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Certain confidence test failed: {e}\")\n return False\n\n def call_mcp_tool(self, tool_name: str, params: dict) -> tuple[Optional[str], Optional[str]]:\n \"\"\"Call an MCP tool in-process - override for precommit-specific response handling\"\"\"\n # Use in-process implementation to maintain conversation memory\n response_text, _ = self.call_mcp_tool_direct(tool_name, params)\n\n if not response_text:\n return None, None\n\n # Extract continuation_id from precommit response specifically\n continuation_id = self._extract_precommit_continuation_id(response_text)\n\n return response_text, continuation_id\n\n def _extract_precommit_continuation_id(self, response_text: str) -> Optional[str]:\n \"\"\"Extract continuation_id from precommit response\"\"\"\n try:\n # Parse the response\n response_data = json.loads(response_text)\n return response_data.get(\"continuation_id\")\n\n except json.JSONDecodeError as e:\n self.logger.debug(f\"Failed to parse response for precommit continuation_id: {e}\")\n return None\n\n def _parse_precommit_response(self, response_text: str) -> dict:\n \"\"\"Parse precommit tool JSON response\"\"\"\n try:\n # Parse the response - it should be direct JSON\n return json.loads(response_text)\n\n except json.JSONDecodeError as e:\n self.logger.error(f\"Failed to parse precommit response as JSON: {e}\")\n self.logger.error(f\"Response text: {response_text[:500]}...\")\n return {}\n\n def _validate_step_response(\n self,\n response_data: dict,\n expected_step: int,\n expected_total: int,\n expected_next_required: bool,\n expected_status: str,\n ) -> bool:\n \"\"\"Validate a precommit validation step response structure\"\"\"\n try:\n # Check status\n if response_data.get(\"status\") != expected_status:\n self.logger.error(f\"Expected status '{expected_status}', got '{response_data.get('status')}'\")\n return False\n\n # Check step number\n if response_data.get(\"step_number\") != expected_step:\n self.logger.error(f\"Expected step_number {expected_step}, got {response_data.get('step_number')}\")\n return False\n\n # Check total steps\n if response_data.get(\"total_steps\") != expected_total:\n self.logger.error(f\"Expected total_steps {expected_total}, got {response_data.get('total_steps')}\")\n return False\n\n # Check next_step_required\n if response_data.get(\"next_step_required\") != expected_next_required:\n self.logger.error(\n f\"Expected next_step_required {expected_next_required}, got {response_data.get('next_step_required')}\"\n )\n return False\n\n # Check validation_status exists\n if \"validation_status\" not in response_data:\n self.logger.error(\"Missing validation_status in response\")\n return False\n\n # Check next_steps guidance\n if not response_data.get(\"next_steps\"):\n self.logger.error(\"Missing next_steps guidance in response\")\n return False\n\n return True\n\n except Exception as e:\n self.logger.error(f\"Error validating step response: {e}\")\n return False\n\n def _test_context_aware_file_embedding(self) -> bool:\n \"\"\"Test context-aware file embedding optimization\"\"\"\n try:\n self.logger.info(\" 1.5: Testing context-aware file embedding\")\n\n # Create multiple test files for context testing\n auth_file_content = \"\"\"#!/usr/bin/env python3\nfrom functools import wraps\nfrom flask import request, jsonify\n\ndef require_auth(f):\n \\\"\\\"\\\"Authentication decorator\\\"\\\"\\\"\n @wraps(f)\n def decorated_function(*args, **kwargs):\n token = request.headers.get('Authorization')\n if not token:\n return jsonify({'error': 'No token provided'}), 401\n\n # Validate token here\n if not validate_token(token):\n return jsonify({'error': 'Invalid token'}), 401\n\n return f(*args, **kwargs)\n return decorated_function\n\ndef validate_token(token):\n \\\"\\\"\\\"Validate authentication token\\\"\\\"\\\"\n # Token validation logic\n return token.startswith('Bearer ')\n\"\"\"\n\n middleware_file_content = \"\"\"#!/usr/bin/env python3\nfrom flask import Flask, request, g\nimport time\n\ndef add_security_headers(app):\n \\\"\\\"\\\"Add security headers to all responses\\\"\\\"\\\"\n @app.after_request\n def security_headers(response):\n response.headers['X-Content-Type-Options'] = 'nosniff'\n response.headers['X-Frame-Options'] = 'DENY'\n response.headers['X-XSS-Protection'] = '1; mode=block'\n return response\n\ndef rate_limiting_middleware(app):\n \\\"\\\"\\\"Basic rate limiting\\\"\\\"\\\"\n @app.before_request\n def limit_remote_addr():\n # Simple rate limiting logic\n pass\n\"\"\"\n\n # Create test files\n auth_file = self.create_additional_test_file(\"auth.py\", auth_file_content)\n middleware_file = self.create_additional_test_file(\"middleware.py\", middleware_file_content)\n\n # Test 1: New conversation, intermediate step - should only reference files\n self.logger.info(\" 1.5.1: New conversation intermediate step (should reference only)\")\n response1, continuation_id = self.call_mcp_tool(\n \"precommit\",\n {\n \"step\": \"Starting validation of new authentication and security middleware\",\n \"step_number\": 1,\n \"total_steps\": 3,\n \"next_step_required\": True, # Intermediate step\n \"findings\": \"Initial analysis of authentication and middleware components\",\n \"files_checked\": [auth_file, middleware_file],\n \"relevant_files\": [auth_file], # This should be referenced, not embedded\n \"relevant_context\": [\"require_auth\"],\n # Assessment fields removed - using precommit_type instead\n \"path\": self.test_dir,\n \"model\": \"flash\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start context-aware file embedding test\")\n return False\n\n response1_data = self._parse_precommit_response(response1)\n if not response1_data:\n return False\n\n # Check file context - should be reference_only for intermediate step\n file_context = response1_data.get(\"file_context\", {})\n if file_context.get(\"type\") != \"reference_only\":\n self.logger.error(f\"Expected reference_only file context, got: {file_context.get('type')}\")\n return False\n\n if \"Files referenced but not embedded\" not in file_context.get(\"context_optimization\", \"\"):\n self.logger.error(\"Expected context optimization message for reference_only\")\n return False\n\n self.logger.info(\" βœ… Intermediate step correctly uses reference_only file context\")\n\n # Test 2: Intermediate step with continuation - should still only reference\n self.logger.info(\" 1.5.2: Intermediate step with continuation (should reference only)\")\n response2, _ = self.call_mcp_tool(\n \"precommit\",\n {\n \"step\": \"Continuing validation with detailed security analysis\",\n \"step_number\": 2,\n \"total_steps\": 3,\n \"next_step_required\": True, # Still intermediate\n \"continuation_id\": continuation_id,\n \"findings\": \"Found potential issues in token validation and missing security headers\",\n \"files_checked\": [auth_file, middleware_file],\n \"relevant_files\": [auth_file, middleware_file], # Both files referenced\n \"relevant_context\": [\"require_auth\", \"validate_token\", \"add_security_headers\"],\n \"issues_found\": [\n {\"severity\": \"medium\", \"description\": \"Basic token validation might be insufficient\"}\n ],\n # Assessment fields removed - using precommit_type instead\n \"model\": \"flash\",\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue to step 2\")\n return False\n\n response2_data = self._parse_precommit_response(response2)\n if not response2_data:\n return False\n\n # Check file context - should still be reference_only\n file_context2 = response2_data.get(\"file_context\", {})\n if file_context2.get(\"type\") != \"reference_only\":\n self.logger.error(f\"Expected reference_only file context for step 2, got: {file_context2.get('type')}\")\n return False\n\n # Should include reference note\n if not file_context2.get(\"note\"):\n self.logger.error(\"Expected file reference note for intermediate step\")\n return False\n\n reference_note = file_context2.get(\"note\", \"\")\n if \"auth.py\" not in reference_note or \"middleware.py\" not in reference_note:\n self.logger.error(\"File reference note should mention both files\")\n return False\n\n self.logger.info(\" βœ… Intermediate step with continuation correctly uses reference_only\")\n\n # Test 3: Final step - should embed files for expert analysis\n self.logger.info(\" 1.5.3: Final step (should embed files)\")\n response3, _ = self.call_mcp_tool(\n \"precommit\",\n {\n \"step\": \"Validation complete - identified security gaps and improvement areas\",\n \"step_number\": 3,\n \"total_steps\": 3,\n \"next_step_required\": False, # Final step - should embed files\n \"continuation_id\": continuation_id,\n \"findings\": \"Security implementation has several gaps: token validation is basic, missing CSRF protection, and rate limiting is not implemented\",\n \"files_checked\": [auth_file, middleware_file],\n \"relevant_files\": [auth_file, middleware_file], # Should be fully embedded\n \"relevant_context\": [\"require_auth\", \"validate_token\", \"add_security_headers\"],\n \"issues_found\": [\n {\"severity\": \"medium\", \"description\": \"Token validation needs strengthening\"},\n {\"severity\": \"low\", \"description\": \"Missing CSRF protection\"},\n {\"severity\": \"low\", \"description\": \"Rate limiting not implemented\"},\n ],\n # Assessment field removed - using precommit_type instead\n # Confidence field removed - using precommit_type instead\n \"model\": \"flash\",\n },\n )\n\n if not response3:\n self.logger.error(\"Failed to complete to final step\")\n return False\n\n response3_data = self._parse_precommit_response(response3)\n if not response3_data:\n return False\n\n # Check file context - should be fully_embedded for final step\n file_context3 = response3_data.get(\"file_context\", {})\n if file_context3.get(\"type\") != \"fully_embedded\":\n self.logger.error(\n f\"Expected fully_embedded file context for final step, got: {file_context3.get('type')}\"\n )\n return False\n\n if \"Full file content embedded for expert analysis\" not in file_context3.get(\"context_optimization\", \"\"):\n self.logger.error(\"Expected expert analysis optimization message for fully_embedded\")\n return False\n\n # Should show files embedded count\n files_embedded = file_context3.get(\"files_embedded\", 0)\n if files_embedded == 0:\n # This is OK - files might already be in conversation history\n self.logger.info(\n \" ℹ️ Files embedded count is 0 - files already in conversation history (smart deduplication)\"\n )\n else:\n self.logger.info(f\" βœ… Files embedded count: {files_embedded}\")\n\n self.logger.info(\" βœ… Final step correctly uses fully_embedded file context\")\n\n # Verify expert analysis was called for final step\n if response3_data.get(\"status\") != \"calling_expert_analysis\":\n self.logger.error(\"Final step should trigger expert analysis\")\n return False\n\n if \"expert_analysis\" not in response3_data:\n self.logger.error(\"Expert analysis should be present in final step\")\n return False\n\n self.logger.info(\" βœ… Context-aware file embedding test completed successfully\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Context-aware file embedding test failed: {e}\")\n return False\n\n def _test_multi_step_file_context(self) -> bool:\n \"\"\"Test multi-step workflow with proper file context transitions\"\"\"\n try:\n self.logger.info(\" 1.6: Testing multi-step file context optimization\")\n\n # Create a complex scenario with multiple files for pre-commit validation\n database_content = \"\"\"#!/usr/bin/env python3\nimport sqlite3\nimport os\nfrom contextlib import contextmanager\n\nclass DatabaseManager:\n def __init__(self):\n self.db_path = os.getenv('DATABASE_PATH', 'app.db')\n\n @contextmanager\n def get_connection(self):\n \\\"\\\"\\\"Get database connection with proper cleanup\\\"\\\"\\\"\n conn = None\n try:\n conn = sqlite3.connect(self.db_path)\n yield conn\n finally:\n if conn:\n conn.close()\n\n def create_user(self, username, email, password_hash):\n \\\"\\\"\\\"Create a new user\\\"\\\"\\\"\n with self.get_connection() as conn:\n cursor = conn.cursor()\n # Proper parameterized query\n cursor.execute(\n \"INSERT INTO users (username, email, password_hash) VALUES (?, ?, ?)\",\n (username, email, password_hash)\n )\n conn.commit()\n return cursor.lastrowid\n\"\"\"\n\n tests_content = \"\"\"#!/usr/bin/env python3\nimport unittest\nfrom unittest.mock import patch, MagicMock\nfrom database_manager import DatabaseManager\n\nclass TestDatabaseManager(unittest.TestCase):\n def setUp(self):\n self.db_manager = DatabaseManager()\n\n @patch('sqlite3.connect')\n def test_create_user(self, mock_connect):\n \\\"\\\"\\\"Test user creation\\\"\\\"\\\"\n mock_conn = MagicMock()\n mock_cursor = MagicMock()\n mock_cursor.lastrowid = 123\n mock_conn.cursor.return_value = mock_cursor\n mock_connect.return_value = mock_conn\n\n user_id = self.db_manager.create_user('testuser', 'test@example.com', 'hashed_password')\n\n self.assertEqual(user_id, 123)\n mock_cursor.execute.assert_called_once_with(\n \"INSERT INTO users (username, email, password_hash) VALUES (?, ?, ?)\",\n ('testuser', 'test@example.com', 'hashed_password')\n )\n\nif __name__ == '__main__':\n unittest.main()\n\"\"\"\n\n # Create test files\n db_file = self.create_additional_test_file(\"database_manager.py\", database_content)\n test_file = self.create_additional_test_file(\"test_database.py\", tests_content)\n\n # Step 1: Start validation (new conversation)\n self.logger.info(\" 1.6.1: Step 1 - Start validation\")\n response1, continuation_id = self.call_mcp_tool(\n \"precommit\",\n {\n \"step\": \"Validating new database manager implementation and corresponding tests\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"New database manager with connection handling and user creation functionality\",\n \"files_checked\": [db_file],\n \"relevant_files\": [db_file],\n \"relevant_context\": [],\n # Assessment fields removed - using precommit_type instead\n \"path\": self.test_dir,\n \"model\": \"flash\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start multi-step file context test\")\n return False\n\n response1_data = self._parse_precommit_response(response1)\n\n # Validate step 1 - should use reference_only\n file_context1 = response1_data.get(\"file_context\", {})\n if file_context1.get(\"type\") != \"reference_only\":\n self.logger.error(\"Step 1 should use reference_only file context\")\n return False\n\n self.logger.info(\" βœ… Step 1: reference_only file context\")\n\n # Step 2: Expand validation\n self.logger.info(\" 1.6.2: Step 2 - Expand validation\")\n response2, _ = self.call_mcp_tool(\n \"precommit\",\n {\n \"step\": \"Found good database implementation - now examining test coverage\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"continuation_id\": continuation_id,\n \"findings\": \"Database manager uses proper parameterized queries and context managers. Test file provides good coverage with mocking.\",\n \"files_checked\": [db_file, test_file],\n \"relevant_files\": [db_file, test_file],\n \"relevant_context\": [\"DatabaseManager.create_user\", \"TestDatabaseManager.test_create_user\"],\n # Assessment fields removed - using precommit_type instead\n \"model\": \"flash\",\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue to step 2\")\n return False\n\n response2_data = self._parse_precommit_response(response2)\n\n # Validate step 2 - should still use reference_only\n file_context2 = response2_data.get(\"file_context\", {})\n if file_context2.get(\"type\") != \"reference_only\":\n self.logger.error(\"Step 2 should use reference_only file context\")\n return False\n\n # Should reference both files\n reference_note = file_context2.get(\"note\", \"\")\n if \"database_manager.py\" not in reference_note or \"test_database.py\" not in reference_note:\n self.logger.error(\"Step 2 should reference both files in note\")\n return False\n\n self.logger.info(\" βœ… Step 2: reference_only file context with multiple files\")\n\n # Step 3: Deep analysis\n self.logger.info(\" 1.6.3: Step 3 - Deep analysis\")\n response3, _ = self.call_mcp_tool(\n \"precommit\",\n {\n \"step\": \"Performing comprehensive security and best practices analysis\",\n \"step_number\": 3,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"continuation_id\": continuation_id,\n \"findings\": \"Code follows security best practices: parameterized queries prevent SQL injection, proper resource cleanup with context managers, environment-based configuration.\",\n \"files_checked\": [db_file, test_file],\n \"relevant_files\": [db_file, test_file],\n \"relevant_context\": [\"DatabaseManager.get_connection\", \"DatabaseManager.create_user\"],\n \"issues_found\": [], # No issues found\n # Assessment field removed - using precommit_type instead\n # Confidence field removed - using precommit_type instead\n \"model\": \"flash\",\n },\n )\n\n if not response3:\n self.logger.error(\"Failed to continue to step 3\")\n return False\n\n response3_data = self._parse_precommit_response(response3)\n\n # Validate step 3 - should still use reference_only\n file_context3 = response3_data.get(\"file_context\", {})\n if file_context3.get(\"type\") != \"reference_only\":\n self.logger.error(\"Step 3 should use reference_only file context\")\n return False\n\n self.logger.info(\" βœ… Step 3: reference_only file context\")\n\n # Step 4: Final validation with expert consultation\n self.logger.info(\" 1.6.4: Step 4 - Final step with expert analysis\")\n response4, _ = self.call_mcp_tool(\n \"precommit\",\n {\n \"step\": \"Validation complete - code is ready for commit\",\n \"step_number\": 4,\n \"total_steps\": 4,\n \"next_step_required\": False, # Final step - should embed files\n \"continuation_id\": continuation_id,\n \"findings\": \"Comprehensive validation complete: secure implementation with parameterized queries, proper resource management, good test coverage, and no security vulnerabilities identified.\",\n \"files_checked\": [db_file, test_file],\n \"relevant_files\": [db_file, test_file],\n \"relevant_context\": [\"DatabaseManager\", \"TestDatabaseManager\"],\n \"issues_found\": [],\n # Assessment field removed - using precommit_type instead\n # Confidence field removed - using precommit_type instead\n \"model\": \"flash\",\n },\n )\n\n if not response4:\n self.logger.error(\"Failed to complete to final step\")\n return False\n\n response4_data = self._parse_precommit_response(response4)\n\n # Validate step 4 - should use fully_embedded for expert analysis\n file_context4 = response4_data.get(\"file_context\", {})\n if file_context4.get(\"type\") != \"fully_embedded\":\n self.logger.error(\"Step 4 (final) should use fully_embedded file context\")\n return False\n\n if \"expert analysis\" not in file_context4.get(\"context_optimization\", \"\").lower():\n self.logger.error(\"Final step should mention expert analysis in context optimization\")\n return False\n\n # Verify expert analysis was triggered\n if response4_data.get(\"status\") != \"calling_expert_analysis\":\n self.logger.error(\"Final step should trigger expert analysis\")\n return False\n\n # Check that expert analysis has file context\n expert_analysis = response4_data.get(\"expert_analysis\", {})\n if not expert_analysis:\n self.logger.error(\"Expert analysis should be present in final step\")\n return False\n\n self.logger.info(\" βœ… Step 4: fully_embedded file context with expert analysis\")\n\n # Validate the complete workflow progression\n progression_summary = {\n \"step_1\": \"reference_only (new conversation, intermediate)\",\n \"step_2\": \"reference_only (continuation, intermediate)\",\n \"step_3\": \"reference_only (continuation, intermediate)\",\n \"step_4\": \"fully_embedded (continuation, final)\",\n }\n\n self.logger.info(\" πŸ“‹ File context progression:\")\n for step, context_type in progression_summary.items():\n self.logger.info(f\" {step}: {context_type}\")\n\n self.logger.info(\" βœ… Multi-step file context optimization test completed successfully\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Multi-step file context test failed: {e}\")\n return False\n" }, { "path": "simulator_tests/test_prompt_size_limit_bug.py", "content": "#!/usr/bin/env python3\n\"\"\"\nPrompt Size Limit Bug Test\n\nThis test reproduces a critical bug where the prompt size limit check\nincorrectly includes conversation history when validating incoming prompts\nfrom Claude to MCP. The limit should ONLY apply to the actual prompt text\nsent by the user, not the entire conversation context.\n\nBug Scenario:\n- User starts a conversation with chat tool\n- Continues conversation multiple times (building up history)\n- On subsequent continuation, a short prompt (150 chars) triggers\n \"resend_prompt\" error claiming >50k characters\n\nExpected Behavior:\n- Only count the actual prompt parameter for size limit\n- Conversation history should NOT count toward prompt size limit\n- Only the user's actual input should be validated against 50k limit\n\"\"\"\n\nfrom .conversation_base_test import ConversationBaseTest\n\n\nclass PromptSizeLimitBugTest(ConversationBaseTest):\n \"\"\"Test to reproduce and verify fix for prompt size limit bug\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"prompt_size_limit_bug\"\n\n @property\n def test_description(self) -> str:\n return \"Reproduce prompt size limit bug with conversation continuation\"\n\n def run_test(self) -> bool:\n \"\"\"Test prompt size limit bug reproduction using in-process calls\"\"\"\n try:\n self.logger.info(\"πŸ› Test: Prompt size limit bug reproduction (in-process)\")\n\n # Setup test environment\n self.setUp()\n\n # Create a test file to provide context\n test_file_content = \"\"\"\n# Test SwiftUI-like Framework Implementation\n\nstruct ContentView: View {\n @State private var counter = 0\n\n var body: some View {\n VStack {\n Text(\"Count: \\\\(counter)\")\n Button(\"Increment\") {\n counter += 1\n }\n }\n }\n}\n\nclass Renderer {\n static let shared = Renderer()\n\n func render(view: View) {\n // Implementation details for UIKit/AppKit rendering\n }\n}\n\nprotocol View {\n var body: some View { get }\n}\n\"\"\"\n test_file_path = self.create_additional_test_file(\"SwiftFramework.swift\", test_file_content)\n\n # Step 1: Start initial conversation\n self.logger.info(\" Step 1: Start conversation with initial context\")\n\n initial_prompt = \"I'm building a SwiftUI-like framework. Can you help me design the architecture?\"\n\n response1, continuation_id = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": initial_prompt,\n \"absolute_file_paths\": [test_file_path],\n \"model\": \"flash\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\" ❌ Failed to start initial conversation\")\n return False\n\n self.logger.info(f\" βœ… Initial conversation started: {continuation_id[:8]}...\")\n\n # Step 2: Continue conversation multiple times to build substantial history\n conversation_prompts = [\n \"That's helpful! Can you elaborate on the View protocol design?\",\n \"How should I implement the State property wrapper?\",\n \"What's the best approach for the VStack layout implementation?\",\n \"Should I use UIKit directly or create an abstraction layer?\",\n \"Smart approach! For the rendering layer, would you suggest UIKit/AppKit directly?\",\n ]\n\n for i, prompt in enumerate(conversation_prompts, 2):\n self.logger.info(f\" Step {i}: Continue conversation (exchange {i})\")\n\n response, _ = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": prompt,\n \"continuation_id\": continuation_id,\n \"model\": \"flash\",\n },\n )\n\n if not response:\n self.logger.error(f\" ❌ Failed at exchange {i}\")\n return False\n\n self.logger.info(f\" βœ… Exchange {i} completed\")\n\n # Step 3: Send short prompt that should NOT trigger size limit\n self.logger.info(\" Step 7: Send short prompt (should NOT trigger size limit)\")\n\n # This is a very short prompt - should not trigger the bug after fix\n short_prompt = \"Thanks! This gives me a solid foundation to start prototyping.\"\n\n self.logger.info(f\" Short prompt length: {len(short_prompt)} characters\")\n\n response_final, _ = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": short_prompt,\n \"continuation_id\": continuation_id,\n \"model\": \"flash\",\n },\n )\n\n if not response_final:\n self.logger.error(\" ❌ Final short prompt failed\")\n return False\n\n # Parse the response to check for the bug\n import json\n\n try:\n response_data = json.loads(response_final)\n status = response_data.get(\"status\", \"\")\n\n if status == \"resend_prompt\":\n # This is the bug! Short prompt incorrectly triggering size limit\n metadata = response_data.get(\"metadata\", {})\n prompt_size = metadata.get(\"prompt_size\", 0)\n\n self.logger.error(\n f\" πŸ› BUG STILL EXISTS: Short prompt ({len(short_prompt)} chars) triggered resend_prompt\"\n )\n self.logger.error(f\" Reported prompt_size: {prompt_size} (should be ~{len(short_prompt)})\")\n self.logger.error(\" This indicates conversation history is still being counted\")\n\n return False # Bug still exists\n\n elif status in [\"success\", \"continuation_available\"]:\n self.logger.info(\" βœ… Short prompt processed correctly - bug appears to be FIXED!\")\n self.logger.info(f\" Prompt length: {len(short_prompt)} chars, Status: {status}\")\n return True\n\n else:\n self.logger.warning(f\" ⚠️ Unexpected status: {status}\")\n # Check if this might be a non-JSON response (successful execution)\n if len(response_final) > 0 and not response_final.startswith('{\"'):\n self.logger.info(\" βœ… Non-JSON response suggests successful tool execution\")\n return True\n return False\n\n except json.JSONDecodeError:\n # Non-JSON response often means successful tool execution\n self.logger.info(\" βœ… Non-JSON response suggests successful tool execution (bug likely fixed)\")\n self.logger.debug(f\" Response preview: {response_final[:200]}...\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Prompt size limit bug test failed: {e}\")\n import traceback\n\n self.logger.debug(f\"Full traceback: {traceback.format_exc()}\")\n return False\n\n\ndef main():\n \"\"\"Run the prompt size limit bug test\"\"\"\n import sys\n\n verbose = \"--verbose\" in sys.argv or \"-v\" in sys.argv\n test = PromptSizeLimitBugTest(verbose=verbose)\n\n success = test.run_test()\n if success:\n print(\"Bug reproduction test completed - check logs for details\")\n else:\n print(\"Test failed to complete\")\n sys.exit(0 if success else 1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "simulator_tests/test_refactor_validation.py", "content": "#!/usr/bin/env python3\n\"\"\"\nRefactor Tool Validation Test\n\nTests the refactor tool's capabilities using the new workflow architecture.\nThis validates the step-by-step refactoring analysis pattern with expert validation.\n\"\"\"\n\nimport json\nfrom typing import Optional\n\nfrom .conversation_base_test import ConversationBaseTest\n\n\nclass RefactorValidationTest(ConversationBaseTest):\n \"\"\"Test refactor tool with new workflow architecture\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"refactor_validation\"\n\n @property\n def test_description(self) -> str:\n return \"Refactor tool validation with new workflow architecture\"\n\n def run_test(self) -> bool:\n \"\"\"Test refactor tool capabilities\"\"\"\n # Set up the test environment\n self.setUp()\n\n try:\n self.logger.info(\"Test: Refactor tool validation (new architecture)\")\n\n # Create test files with refactoring opportunities\n self._create_refactoring_test_code()\n\n # Test 1: Single refactoring analysis session with multiple steps\n if not self._test_single_refactoring_session():\n return False\n\n # Test 2: Refactoring analysis requiring refocus\n if not self._test_refactoring_refocus_flow():\n return False\n\n # Test 3: Complete refactoring analysis with expert analysis\n if not self._test_complete_refactoring_with_analysis():\n return False\n\n # Test 4: Certain confidence with complete refactor_result_confidence\n if not self._test_certain_confidence_complete_refactoring():\n return False\n\n # Test 5: Context-aware file embedding for refactoring\n if not self._test_context_aware_refactoring_file_embedding():\n return False\n\n # Test 6: Different refactor types\n if not self._test_different_refactor_types():\n return False\n\n self.logger.info(\" βœ… All refactor validation tests passed\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Refactor validation test failed: {e}\")\n return False\n\n def _create_refactoring_test_code(self):\n \"\"\"Create test files with various refactoring opportunities\"\"\"\n # Create a Python file with obvious code smells and decomposition opportunities\n refactor_code = \"\"\"#!/usr/bin/env python3\nimport json\nimport os\nfrom datetime import datetime\n\n# Code smell: Large class with multiple responsibilities\nclass DataProcessorManager:\n def __init__(self, config_file):\n self.config = self._load_config(config_file)\n self.processed_count = 0\n self.error_count = 0\n self.log_file = \"processing.log\"\n\n def _load_config(self, config_file):\n \\\"\\\"\\\"Load configuration from file\\\"\\\"\\\"\n with open(config_file, 'r') as f:\n return json.load(f)\n\n # Code smell: Long method doing too many things (decompose opportunity)\n def process_user_data(self, user_data, validation_rules, output_format):\n \\\"\\\"\\\"Process user data with validation and formatting\\\"\\\"\\\"\n # Validation logic\n if not user_data:\n print(\"Error: No user data\") # Code smell: print instead of logging\n return None\n\n if not isinstance(user_data, dict):\n print(\"Error: Invalid data format\")\n return None\n\n # Check required fields\n required_fields = ['name', 'email', 'age']\n for field in required_fields:\n if field not in user_data:\n print(f\"Error: Missing field {field}\")\n return None\n\n # Apply validation rules\n for rule in validation_rules:\n if rule['field'] == 'email':\n if '@' not in user_data['email']: # Code smell: simple validation\n print(\"Error: Invalid email\")\n return None\n elif rule['field'] == 'age':\n if user_data['age'] < 18: # Code smell: magic number\n print(\"Error: Age too young\")\n return None\n\n # Data processing\n processed_data = {}\n processed_data['full_name'] = user_data['name'].title()\n processed_data['email_domain'] = user_data['email'].split('@')[1]\n processed_data['age_category'] = 'adult' if user_data['age'] >= 18 else 'minor'\n\n # Code smell: Duplicate date formatting logic\n if output_format == 'json':\n processed_data['processed_at'] = datetime.now().strftime('%Y-%m-%d %H:%M:%S')\n result = json.dumps(processed_data, ensure_ascii=False)\n elif output_format == 'csv':\n processed_data['processed_at'] = datetime.now().strftime('%Y-%m-%d %H:%M:%S')\n result = f\"{processed_data['full_name']},{processed_data['email_domain']},{processed_data['age_category']}\"\n else:\n processed_data['processed_at'] = datetime.now().strftime('%Y-%m-%d %H:%M:%S')\n result = str(processed_data)\n\n # Logging and statistics\n self.processed_count += 1\n with open(self.log_file, 'a') as f: # Code smell: file handling without context\n f.write(f\"Processed: {user_data['name']} at {datetime.now()}\\\\n\")\n\n return result\n\n # Code smell: Another long method (decompose opportunity)\n def batch_process_files(self, file_list, output_dir):\n \\\"\\\"\\\"Process multiple files in batch\\\"\\\"\\\"\n results = []\n\n for file_path in file_list:\n # File validation\n if not os.path.exists(file_path):\n print(f\"Error: File {file_path} not found\")\n continue\n\n if not file_path.endswith('.json'):\n print(f\"Error: File {file_path} is not JSON\")\n continue\n\n # Read and process file\n try:\n with open(file_path, 'r') as f:\n data = json.load(f)\n\n # Code smell: Nested loops and complex logic\n for user_id, user_data in data.items():\n if isinstance(user_data, dict):\n # Duplicate validation logic from process_user_data\n if 'name' in user_data and 'email' in user_data:\n if '@' in user_data['email']:\n # More processing...\n processed = {\n 'id': user_id,\n 'name': user_data['name'].title(),\n 'email': user_data['email'].lower()\n }\n results.append(processed)\n\n # Write output file\n output_file = os.path.join(output_dir, f\"processed_{os.path.basename(file_path)}\")\n with open(output_file, 'w') as f:\n json.dump(results, f, indent=2)\n\n except Exception as e:\n print(f\"Error processing file {file_path}: {e}\")\n self.error_count += 1\n\n return results\n\n # Code smell: Method doing file I/O and business logic\n def generate_report(self):\n \\\"\\\"\\\"Generate processing report\\\"\\\"\\\"\n report_data = {\n 'total_processed': self.processed_count,\n 'total_errors': self.error_count,\n 'success_rate': (self.processed_count / (self.processed_count + self.error_count)) * 100 if (self.processed_count + self.error_count) > 0 else 0,\n 'generated_at': datetime.now().strftime('%Y-%m-%d %H:%M:%S')\n }\n\n # Write to multiple formats (code smell: duplicate logic)\n with open('report.json', 'w') as f:\n json.dump(report_data, f, indent=2)\n\n with open('report.txt', 'w') as f:\n f.write(f\"Processing Report\\\\n\")\n f.write(f\"================\\\\n\")\n f.write(f\"Total Processed: {report_data['total_processed']}\\\\n\")\n f.write(f\"Total Errors: {report_data['total_errors']}\\\\n\")\n f.write(f\"Success Rate: {report_data['success_rate']:.2f}%\\\\n\")\n f.write(f\"Generated: {report_data['generated_at']}\\\\n\")\n\n return report_data\n\n# Code smell: Utility functions that could be in a separate module\ndef validate_email(email):\n \\\"\\\"\\\"Simple email validation\\\"\\\"\\\"\n return '@' in email and '.' in email\n\ndef format_name(name):\n \\\"\\\"\\\"Format name to title case\\\"\\\"\\\"\n return name.title() if name else \"\"\n\ndef calculate_age_category(age):\n \\\"\\\"\\\"Calculate age category\\\"\\\"\\\"\n if age < 18:\n return 'minor'\n elif age < 65:\n return 'adult'\n else:\n return 'senior'\n\"\"\"\n\n # Create test file with refactoring opportunities\n self.refactor_file = self.create_additional_test_file(\"data_processor_manager.py\", refactor_code)\n self.logger.info(f\" βœ… Created test file with refactoring opportunities: {self.refactor_file}\")\n\n # Create a smaller file for focused testing\n small_refactor_code = \"\"\"#!/usr/bin/env python3\n\n# Code smell: God function\ndef process_everything(data, config, logger):\n \\\"\\\"\\\"Function that does too many things\\\"\\\"\\\"\n # Validation\n if not data:\n print(\"No data\") # Should use logger\n return None\n\n # Processing\n result = []\n for item in data:\n if item > 5: # Magic number\n result.append(item * 2) # Magic number\n\n # Logging\n print(f\"Processed {len(result)} items\")\n\n # File I/O\n with open(\"output.txt\", \"w\") as f:\n f.write(str(result))\n\n return result\n\n# Modernization opportunity: Could use dataclass\nclass UserData:\n def __init__(self, name, email, age):\n self.name = name\n self.email = email\n self.age = age\n\n def to_dict(self):\n return {\n 'name': self.name,\n 'email': self.email,\n 'age': self.age\n }\n\"\"\"\n\n self.small_refactor_file = self.create_additional_test_file(\"simple_processor.py\", small_refactor_code)\n self.logger.info(f\" βœ… Created small test file: {self.small_refactor_file}\")\n\n def _test_single_refactoring_session(self) -> bool:\n \"\"\"Test a complete refactoring analysis session with multiple steps\"\"\"\n try:\n self.logger.info(\" 1.1: Testing single refactoring analysis session\")\n\n # Step 1: Start refactoring analysis\n self.logger.info(\" 1.1.1: Step 1 - Initial refactoring investigation\")\n response1, continuation_id = self.call_mcp_tool(\n \"refactor\",\n {\n \"step\": \"Starting refactoring analysis of the data processor code. Let me examine the code structure and identify opportunities for decomposition, code smell fixes, and modernization.\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Initial scan shows a large DataProcessorManager class with multiple responsibilities. The class handles configuration, data processing, file I/O, and logging - violating single responsibility principle.\",\n \"files_checked\": [self.refactor_file],\n \"relevant_files\": [self.refactor_file],\n \"confidence\": \"incomplete\",\n \"refactor_type\": \"codesmells\",\n \"focus_areas\": [\"maintainability\", \"readability\"],\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to get initial refactoring response\")\n return False\n\n # Parse and validate JSON response\n response1_data = self._parse_refactor_response(response1)\n if not response1_data:\n return False\n\n # Validate step 1 response structure - expect pause_for_refactoring_analysis for next_step_required=True\n if not self._validate_refactoring_step_response(\n response1_data, 1, 4, True, \"pause_for_refactoring_analysis\"\n ):\n return False\n\n self.logger.info(f\" βœ… Step 1 successful, continuation_id: {continuation_id}\")\n\n # Step 2: Deeper analysis\n self.logger.info(\" 1.1.2: Step 2 - Detailed code analysis\")\n response2, _ = self.call_mcp_tool(\n \"refactor\",\n {\n \"step\": \"Now examining the specific methods and identifying concrete refactoring opportunities. Found multiple code smells and decomposition needs.\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Identified several major issues: 1) process_user_data method is 50+ lines doing validation, processing, and I/O. 2) Duplicate validation logic. 3) Magic numbers (18 for age). 4) print statements instead of proper logging. 5) File handling without proper context management.\",\n \"files_checked\": [self.refactor_file],\n \"relevant_files\": [self.refactor_file],\n \"relevant_context\": [\n \"DataProcessorManager.process_user_data\",\n \"DataProcessorManager.batch_process_files\",\n ],\n \"issues_found\": [\n {\n \"type\": \"codesmells\",\n \"severity\": \"high\",\n \"description\": \"Long method: process_user_data does too many things\",\n },\n {\n \"type\": \"codesmells\",\n \"severity\": \"medium\",\n \"description\": \"Magic numbers: age validation uses hardcoded 18\",\n },\n {\n \"type\": \"codesmells\",\n \"severity\": \"medium\",\n \"description\": \"Duplicate validation logic in multiple places\",\n },\n ],\n \"confidence\": \"partial\",\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue refactoring analysis to step 2\")\n return False\n\n response2_data = self._parse_refactor_response(response2)\n if not self._validate_refactoring_step_response(\n response2_data, 2, 4, True, \"pause_for_refactoring_analysis\"\n ):\n return False\n\n # Check refactoring status tracking\n refactoring_status = response2_data.get(\"refactoring_status\", {})\n if refactoring_status.get(\"files_checked\", 0) < 1:\n self.logger.error(\"Files checked count not properly tracked\")\n return False\n\n opportunities_by_type = refactoring_status.get(\"opportunities_by_type\", {})\n if \"codesmells\" not in opportunities_by_type:\n self.logger.error(\"Code smells not properly tracked in opportunities\")\n return False\n\n if refactoring_status.get(\"refactor_confidence\") != \"partial\":\n self.logger.error(\"Refactor confidence not properly tracked\")\n return False\n\n self.logger.info(\" βœ… Step 2 successful with proper refactoring tracking\")\n\n # Store continuation_id for next test\n self.refactoring_continuation_id = continuation_id\n return True\n\n except Exception as e:\n self.logger.error(f\"Single refactoring session test failed: {e}\")\n return False\n\n def _test_refactoring_refocus_flow(self) -> bool:\n \"\"\"Test refactoring analysis that shifts focus mid-investigation\"\"\"\n try:\n self.logger.info(\" 1.2: Testing refactoring analysis refocus workflow\")\n\n # Start a new refactoring analysis for testing refocus behaviour\n self.logger.info(\" 1.2.1: Start refactoring analysis for refocus test\")\n response1, continuation_id = self.call_mcp_tool(\n \"refactor\",\n {\n \"step\": \"Analyzing code for decomposition opportunities\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Initial focus on class-level decomposition\",\n \"files_checked\": [self.small_refactor_file],\n \"relevant_files\": [self.small_refactor_file],\n \"confidence\": \"incomplete\",\n \"refactor_type\": \"decompose\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start refocus test refactoring analysis\")\n return False\n\n # Step 2: Wrong direction\n self.logger.info(\" 1.2.2: Step 2 - Wrong refactoring focus\")\n response2, _ = self.call_mcp_tool(\n \"refactor\",\n {\n \"step\": \"Focusing on class decomposition strategies\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Class structure seems reasonable, might be looking in wrong direction\",\n \"files_checked\": [self.small_refactor_file],\n \"relevant_files\": [],\n \"confidence\": \"incomplete\",\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue to step 2\")\n return False\n\n # Step 3: Backtrack from step 2\n self.logger.info(\" 1.2.3: Step 3 - Refocus on function decomposition\")\n response3, _ = self.call_mcp_tool(\n \"refactor\",\n {\n \"step\": \"Refocusing - the real decomposition opportunity is the god function process_everything. Let me analyze function-level refactoring instead.\",\n \"step_number\": 3,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Found the main decomposition opportunity: process_everything function does validation, processing, logging, and file I/O. Should be split into separate functions with single responsibilities.\",\n \"files_checked\": [self.small_refactor_file],\n \"relevant_files\": [self.small_refactor_file],\n \"relevant_context\": [\"process_everything\"],\n \"issues_found\": [\n {\n \"type\": \"decompose\",\n \"severity\": \"high\",\n \"description\": \"God function: process_everything has multiple responsibilities\",\n },\n {\n \"type\": \"codesmells\",\n \"severity\": \"medium\",\n \"description\": \"Magic numbers in processing logic\",\n },\n ],\n \"confidence\": \"partial\",\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response3:\n self.logger.error(\"Failed to refocus\")\n return False\n\n response3_data = self._parse_refactor_response(response3)\n if not self._validate_refactoring_step_response(\n response3_data, 3, 4, True, \"pause_for_refactoring_analysis\"\n ):\n return False\n\n self.logger.info(\" βœ… Refocus working correctly for refactoring analysis\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Refocusing test failed: {e}\")\n return False\n\n def _test_complete_refactoring_with_analysis(self) -> bool:\n \"\"\"Test complete refactoring analysis ending with expert analysis\"\"\"\n try:\n self.logger.info(\" 1.3: Testing complete refactoring analysis with expert analysis\")\n\n # Use the continuation from first test\n continuation_id = getattr(self, \"refactoring_continuation_id\", None)\n if not continuation_id:\n # Start fresh if no continuation available\n self.logger.info(\" 1.3.0: Starting fresh refactoring analysis\")\n response0, continuation_id = self.call_mcp_tool(\n \"refactor\",\n {\n \"step\": \"Analyzing the data processor for comprehensive refactoring opportunities\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"findings\": \"Found multiple refactoring opportunities in DataProcessorManager\",\n \"files_checked\": [self.refactor_file],\n \"relevant_files\": [self.refactor_file],\n \"relevant_context\": [\"DataProcessorManager.process_user_data\"],\n \"confidence\": \"partial\",\n \"refactor_type\": \"codesmells\",\n },\n )\n if not response0 or not continuation_id:\n self.logger.error(\"Failed to start fresh refactoring analysis\")\n return False\n\n # Final step - trigger expert analysis\n self.logger.info(\" 1.3.1: Final step - complete refactoring analysis\")\n response_final, _ = self.call_mcp_tool(\n \"refactor\",\n {\n \"step\": \"Refactoring analysis complete. Identified comprehensive opportunities for code smell fixes, decomposition, and modernization across the DataProcessorManager class.\",\n \"step_number\": 2,\n \"total_steps\": 2,\n \"next_step_required\": False, # Final step - triggers expert analysis\n \"findings\": \"Complete analysis shows: 1) Large class violating SRP, 2) Long methods needing decomposition, 3) Duplicate validation logic, 4) Magic numbers, 5) Poor error handling with print statements, 6) File I/O mixed with business logic. All major refactoring opportunities identified with specific line locations.\",\n \"files_checked\": [self.refactor_file],\n \"relevant_files\": [self.refactor_file],\n \"relevant_context\": [\n \"DataProcessorManager.process_user_data\",\n \"DataProcessorManager.batch_process_files\",\n \"DataProcessorManager.generate_report\",\n ],\n \"issues_found\": [\n {\n \"type\": \"decompose\",\n \"severity\": \"critical\",\n \"description\": \"Large class with multiple responsibilities\",\n },\n {\n \"type\": \"codesmells\",\n \"severity\": \"high\",\n \"description\": \"Long method: process_user_data (50+ lines)\",\n },\n {\"type\": \"codesmells\", \"severity\": \"high\", \"description\": \"Duplicate validation logic\"},\n {\"type\": \"codesmells\", \"severity\": \"medium\", \"description\": \"Magic numbers in age validation\"},\n {\n \"type\": \"modernize\",\n \"severity\": \"medium\",\n \"description\": \"Use proper logging instead of print statements\",\n },\n ],\n \"confidence\": \"partial\", # Use partial to trigger expert analysis\n \"continuation_id\": continuation_id,\n \"model\": \"flash\", # Use flash for expert analysis\n },\n )\n\n if not response_final:\n self.logger.error(\"Failed to complete refactoring analysis\")\n return False\n\n response_final_data = self._parse_refactor_response(response_final)\n if not response_final_data:\n return False\n\n # Validate final response structure - expect calling_expert_analysis or files_required_to_continue\n expected_statuses = [\"calling_expert_analysis\", \"files_required_to_continue\"]\n actual_status = response_final_data.get(\"status\")\n if actual_status not in expected_statuses:\n self.logger.error(f\"Expected status to be one of {expected_statuses}, got '{actual_status}'\")\n return False\n\n if not response_final_data.get(\"refactoring_complete\"):\n self.logger.error(\"Expected refactoring_complete=true for final step\")\n return False\n\n # Check for expert analysis or content (depending on status)\n if actual_status == \"calling_expert_analysis\":\n if \"expert_analysis\" not in response_final_data:\n self.logger.error(\"Missing expert_analysis in final response\")\n return False\n expert_analysis = response_final_data.get(\"expert_analysis\", {})\n analysis_content = json.dumps(expert_analysis, ensure_ascii=False).lower()\n elif actual_status == \"files_required_to_continue\":\n # For files_required_to_continue, analysis is in content field\n if \"content\" not in response_final_data:\n self.logger.error(\"Missing content in files_required_to_continue response\")\n return False\n expert_analysis = {\"content\": response_final_data.get(\"content\", \"\")}\n analysis_content = response_final_data.get(\"content\", \"\").lower()\n else:\n self.logger.error(f\"Unexpected status: {actual_status}\")\n return False\n\n # Check for expected analysis content (checking common patterns)\n analysis_text = analysis_content\n\n # Look for refactoring identification\n refactor_indicators = [\"refactor\", \"decompose\", \"code smell\", \"method\", \"class\", \"responsibility\"]\n found_indicators = sum(1 for indicator in refactor_indicators if indicator in analysis_text)\n\n if found_indicators >= 3:\n self.logger.info(\" βœ… Expert analysis identified refactoring opportunities correctly\")\n else:\n self.logger.warning(\n f\" ⚠️ Expert analysis may not have fully identified refactoring opportunities (found {found_indicators}/6 indicators)\"\n )\n\n # Check complete refactoring summary\n if \"complete_refactoring\" not in response_final_data:\n self.logger.error(\"Missing complete_refactoring in final response\")\n return False\n\n complete_refactoring = response_final_data[\"complete_refactoring\"]\n if not complete_refactoring.get(\"relevant_context\"):\n self.logger.error(\"Missing relevant context in complete refactoring\")\n return False\n\n if \"DataProcessorManager.process_user_data\" not in complete_refactoring[\"relevant_context\"]:\n self.logger.error(\"Expected method not found in refactoring summary\")\n return False\n\n self.logger.info(\" βœ… Complete refactoring analysis with expert analysis successful\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Complete refactoring analysis test failed: {e}\")\n return False\n\n def _test_certain_confidence_complete_refactoring(self) -> bool:\n \"\"\"Test complete confidence - should skip expert analysis\"\"\"\n try:\n self.logger.info(\" 1.4: Testing complete confidence behavior\")\n\n # Test complete confidence - should skip expert analysis\n self.logger.info(\" 1.4.1: Complete confidence refactoring\")\n response_certain, _ = self.call_mcp_tool(\n \"refactor\",\n {\n \"step\": \"I have completed comprehensive refactoring analysis with 100% certainty: identified all major opportunities including decomposition, code smells, and modernization.\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False, # Final step\n \"findings\": \"Complete refactoring analysis: 1) DataProcessorManager class needs decomposition into separate responsibilities, 2) process_user_data method needs breaking into validation, processing, and formatting functions, 3) Replace print statements with proper logging, 4) Extract magic numbers to constants, 5) Use dataclasses for modern Python patterns.\",\n \"files_checked\": [self.small_refactor_file],\n \"relevant_files\": [self.small_refactor_file],\n \"relevant_context\": [\"process_everything\", \"UserData\"],\n \"issues_found\": [\n {\"type\": \"decompose\", \"severity\": \"high\", \"description\": \"God function needs decomposition\"},\n {\"type\": \"modernize\", \"severity\": \"medium\", \"description\": \"Use dataclass for UserData\"},\n {\"type\": \"codesmells\", \"severity\": \"medium\", \"description\": \"Replace print with logging\"},\n ],\n \"confidence\": \"complete\", # Complete confidence should skip expert analysis\n \"refactor_type\": \"codesmells\",\n \"model\": \"flash\",\n },\n )\n\n if not response_certain:\n self.logger.error(\"Failed to test certain confidence with complete refactoring\")\n return False\n\n response_certain_data = self._parse_refactor_response(response_certain)\n if not response_certain_data:\n return False\n\n # Validate certain confidence response - should skip expert analysis\n if response_certain_data.get(\"status\") != \"refactoring_analysis_complete_ready_for_implementation\":\n self.logger.error(\n f\"Expected status 'refactoring_analysis_complete_ready_for_implementation', got '{response_certain_data.get('status')}'\"\n )\n return False\n\n if not response_certain_data.get(\"skip_expert_analysis\"):\n self.logger.error(\"Expected skip_expert_analysis=true for complete confidence\")\n return False\n\n expert_analysis = response_certain_data.get(\"expert_analysis\", {})\n if expert_analysis.get(\"status\") != \"skipped_due_to_complete_refactoring_confidence\":\n self.logger.error(\"Expert analysis should be skipped for complete confidence\")\n return False\n\n self.logger.info(\" βœ… Complete confidence behavior working correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Complete confidence test failed: {e}\")\n return False\n\n def _test_context_aware_refactoring_file_embedding(self) -> bool:\n \"\"\"Test context-aware file embedding optimization for refactoring workflow\"\"\"\n try:\n self.logger.info(\" 1.5: Testing context-aware file embedding for refactoring\")\n\n # Create multiple test files for context testing\n utils_content = \"\"\"#!/usr/bin/env python3\n# Utility functions with refactoring opportunities\n\ndef calculate_total(items):\n \\\"\\\"\\\"Calculate total with magic numbers\\\"\\\"\\\"\n total = 0\n for item in items:\n if item > 10: # Magic number\n total += item * 1.1 # Magic number for tax\n return total\n\ndef format_output(data, format_type):\n \\\"\\\"\\\"Format output - duplicate logic\\\"\\\"\\\"\n if format_type == 'json':\n import json\n return json.dumps(data, ensure_ascii=False)\n elif format_type == 'csv':\n return ','.join(str(v) for v in data.values())\n else:\n return str(data)\n\"\"\"\n\n helpers_content = \"\"\"#!/usr/bin/env python3\n# Helper functions that could be modernized\n\nclass DataContainer:\n \\\"\\\"\\\"Simple data container - could use dataclass\\\"\\\"\\\"\n def __init__(self, name, value, category):\n self.name = name\n self.value = value\n self.category = category\n\n def to_dict(self):\n return {\n 'name': self.name,\n 'value': self.value,\n 'category': self.category\n }\n\"\"\"\n\n # Create test files\n utils_file = self.create_additional_test_file(\"utils.py\", utils_content)\n helpers_file = self.create_additional_test_file(\"helpers.py\", helpers_content)\n\n # Test 1: New conversation, intermediate step - should only reference files\n self.logger.info(\" 1.5.1: New conversation intermediate step (should reference only)\")\n response1, continuation_id = self.call_mcp_tool(\n \"refactor\",\n {\n \"step\": \"Starting refactoring analysis of utility modules\",\n \"step_number\": 1,\n \"total_steps\": 3,\n \"next_step_required\": True, # Intermediate step\n \"findings\": \"Initial analysis of utility and helper modules for refactoring opportunities\",\n \"files_checked\": [utils_file, helpers_file],\n \"relevant_files\": [utils_file], # This should be referenced, not embedded\n \"relevant_context\": [\"calculate_total\"],\n \"confidence\": \"incomplete\",\n \"refactor_type\": \"codesmells\",\n \"model\": \"flash\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start context-aware file embedding test\")\n return False\n\n response1_data = self._parse_refactor_response(response1)\n if not response1_data:\n return False\n\n # Check file context - should be reference_only for intermediate step\n file_context = response1_data.get(\"file_context\", {})\n if file_context.get(\"type\") != \"reference_only\":\n self.logger.error(f\"Expected reference_only file context, got: {file_context.get('type')}\")\n return False\n\n if \"Files referenced but not embedded\" not in file_context.get(\"context_optimization\", \"\"):\n self.logger.error(\"Expected context optimization message for reference_only\")\n return False\n\n self.logger.info(\" βœ… Intermediate step correctly uses reference_only file context\")\n\n # Test 2: Final step - should embed files for expert analysis\n self.logger.info(\" 1.5.2: Final step (should embed files)\")\n response2, _ = self.call_mcp_tool(\n \"refactor\",\n {\n \"step\": \"Refactoring analysis complete - identified all opportunities\",\n \"step_number\": 3,\n \"total_steps\": 3,\n \"next_step_required\": False, # Final step - should embed files\n \"continuation_id\": continuation_id,\n \"findings\": \"Complete analysis: Found magic numbers in calculate_total, duplicate formatting logic, and modernization opportunity with DataContainer class that could use dataclass.\",\n \"files_checked\": [utils_file, helpers_file],\n \"relevant_files\": [utils_file, helpers_file], # Should be fully embedded\n \"relevant_context\": [\"calculate_total\", \"format_output\", \"DataContainer\"],\n \"issues_found\": [\n {\"type\": \"codesmells\", \"severity\": \"medium\", \"description\": \"Magic numbers in calculate_total\"},\n {\"type\": \"modernize\", \"severity\": \"low\", \"description\": \"DataContainer could use dataclass\"},\n {\"type\": \"codesmells\", \"severity\": \"low\", \"description\": \"Duplicate formatting logic\"},\n ],\n \"confidence\": \"partial\", # Use partial to trigger expert analysis\n \"model\": \"flash\",\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to complete to final step\")\n return False\n\n response2_data = self._parse_refactor_response(response2)\n if not response2_data:\n return False\n\n # Check file context - should be fully_embedded for final step\n file_context2 = response2_data.get(\"file_context\", {})\n if file_context2.get(\"type\") != \"fully_embedded\":\n self.logger.error(\n f\"Expected fully_embedded file context for final step, got: {file_context2.get('type')}\"\n )\n return False\n\n if \"Full file content embedded for expert analysis\" not in file_context2.get(\"context_optimization\", \"\"):\n self.logger.error(\"Expected expert analysis optimization message for fully_embedded\")\n return False\n\n self.logger.info(\" βœ… Final step correctly uses fully_embedded file context\")\n\n # Verify expert analysis was called for final step (or files_required_to_continue)\n expected_statuses = [\"calling_expert_analysis\", \"files_required_to_continue\"]\n actual_status = response2_data.get(\"status\")\n if actual_status not in expected_statuses:\n self.logger.error(f\"Expected one of {expected_statuses}, got: {actual_status}\")\n return False\n\n # Handle expert analysis based on status\n if actual_status == \"calling_expert_analysis\" and \"expert_analysis\" not in response2_data:\n self.logger.error(\"Expert analysis should be present in final step with calling_expert_analysis\")\n return False\n\n self.logger.info(\" βœ… Context-aware file embedding test for refactoring completed successfully\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Context-aware refactoring file embedding test failed: {e}\")\n return False\n\n def _test_different_refactor_types(self) -> bool:\n \"\"\"Test different refactor types (decompose, modernize, organization)\"\"\"\n try:\n self.logger.info(\" 1.6: Testing different refactor types\")\n\n # Test decompose type\n self.logger.info(\" 1.6.1: Testing decompose refactor type\")\n response_decompose, _ = self.call_mcp_tool(\n \"refactor\",\n {\n \"step\": \"Analyzing code for decomposition opportunities in large functions and classes\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Found large DataProcessorManager class that violates single responsibility principle and long process_user_data method that needs decomposition.\",\n \"files_checked\": [self.refactor_file],\n \"relevant_files\": [self.refactor_file],\n \"relevant_context\": [\"DataProcessorManager\", \"DataProcessorManager.process_user_data\"],\n \"issues_found\": [\n {\n \"type\": \"decompose\",\n \"severity\": \"critical\",\n \"description\": \"Large class with multiple responsibilities\",\n },\n {\n \"type\": \"decompose\",\n \"severity\": \"high\",\n \"description\": \"Long method doing validation, processing, and I/O\",\n },\n ],\n \"confidence\": \"complete\",\n \"refactor_type\": \"decompose\",\n \"model\": \"flash\",\n },\n )\n\n if not response_decompose:\n self.logger.error(\"Failed to test decompose refactor type\")\n return False\n\n response_decompose_data = self._parse_refactor_response(response_decompose)\n\n # Check that decompose type is properly tracked\n refactoring_status = response_decompose_data.get(\"refactoring_status\", {})\n opportunities_by_type = refactoring_status.get(\"opportunities_by_type\", {})\n if \"decompose\" not in opportunities_by_type:\n self.logger.error(\"Decompose opportunities not properly tracked\")\n return False\n\n self.logger.info(\" βœ… Decompose refactor type working correctly\")\n\n # Test modernize type\n self.logger.info(\" 1.6.2: Testing modernize refactor type\")\n response_modernize, _ = self.call_mcp_tool(\n \"refactor\",\n {\n \"step\": \"Analyzing code for modernization opportunities using newer Python features\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Found opportunities to use dataclasses, f-strings, pathlib, and proper logging instead of print statements.\",\n \"files_checked\": [self.small_refactor_file],\n \"relevant_files\": [self.small_refactor_file],\n \"relevant_context\": [\"UserData\", \"process_everything\"],\n \"issues_found\": [\n {\n \"type\": \"modernize\",\n \"severity\": \"medium\",\n \"description\": \"UserData class could use @dataclass decorator\",\n },\n {\n \"type\": \"modernize\",\n \"severity\": \"medium\",\n \"description\": \"Replace print statements with proper logging\",\n },\n {\"type\": \"modernize\", \"severity\": \"low\", \"description\": \"Use pathlib for file operations\"},\n ],\n \"confidence\": \"complete\",\n \"refactor_type\": \"modernize\",\n \"model\": \"flash\",\n },\n )\n\n if not response_modernize:\n self.logger.error(\"Failed to test modernize refactor type\")\n return False\n\n response_modernize_data = self._parse_refactor_response(response_modernize)\n\n # Check that modernize type is properly tracked\n refactoring_status = response_modernize_data.get(\"refactoring_status\", {})\n opportunities_by_type = refactoring_status.get(\"opportunities_by_type\", {})\n if \"modernize\" not in opportunities_by_type:\n self.logger.error(\"Modernize opportunities not properly tracked\")\n return False\n\n self.logger.info(\" βœ… Modernize refactor type working correctly\")\n\n self.logger.info(\" βœ… Different refactor types test completed successfully\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Different refactor types test failed: {e}\")\n return False\n\n def call_mcp_tool(self, tool_name: str, params: dict) -> tuple[Optional[str], Optional[str]]:\n \"\"\"Call an MCP tool in-process - override for -specific response handling\"\"\"\n # Use in-process implementation to maintain conversation memory\n response_text, _ = self.call_mcp_tool_direct(tool_name, params)\n\n if not response_text:\n return None, None\n\n # Extract continuation_id from refactor response specifically\n continuation_id = self._extract_refactor_continuation_id(response_text)\n\n return response_text, continuation_id\n\n def _extract_refactor_continuation_id(self, response_text: str) -> Optional[str]:\n \"\"\"Extract continuation_id from refactor response\"\"\"\n try:\n # Parse the response\n response_data = json.loads(response_text)\n return response_data.get(\"continuation_id\")\n\n except json.JSONDecodeError as e:\n self.logger.debug(f\"Failed to parse response for refactor continuation_id: {e}\")\n return None\n\n def _parse_refactor_response(self, response_text: str) -> dict:\n \"\"\"Parse refactor tool JSON response\"\"\"\n try:\n # Parse the response - it should be direct JSON\n return json.loads(response_text)\n\n except json.JSONDecodeError as e:\n self.logger.error(f\"Failed to parse refactor response as JSON: {e}\")\n self.logger.error(f\"Response text: {response_text[:500]}...\")\n return {}\n\n def _validate_refactoring_step_response(\n self,\n response_data: dict,\n expected_step: int,\n expected_total: int,\n expected_next_required: bool,\n expected_status: str,\n ) -> bool:\n \"\"\"Validate a refactor investigation step response structure\"\"\"\n try:\n # Check status\n if response_data.get(\"status\") != expected_status:\n self.logger.error(f\"Expected status '{expected_status}', got '{response_data.get('status')}'\")\n return False\n\n # Check step number\n if response_data.get(\"step_number\") != expected_step:\n self.logger.error(f\"Expected step_number {expected_step}, got {response_data.get('step_number')}\")\n return False\n\n # Check total steps\n if response_data.get(\"total_steps\") != expected_total:\n self.logger.error(f\"Expected total_steps {expected_total}, got {response_data.get('total_steps')}\")\n return False\n\n # Check next_step_required\n if response_data.get(\"next_step_required\") != expected_next_required:\n self.logger.error(\n f\"Expected next_step_required {expected_next_required}, got {response_data.get('next_step_required')}\"\n )\n return False\n\n # Check refactoring_status exists\n if \"refactoring_status\" not in response_data:\n self.logger.error(\"Missing refactoring_status in response\")\n return False\n\n # Check next_steps guidance\n if not response_data.get(\"next_steps\"):\n self.logger.error(\"Missing next_steps guidance in response\")\n return False\n\n return True\n\n except Exception as e:\n self.logger.error(f\"Error validating refactoring step response: {e}\")\n return False\n" }, { "path": "simulator_tests/test_secaudit_validation.py", "content": "#!/usr/bin/env python3\n\"\"\"\nSECAUDIT Tool Validation Test\n\nTests the secaudit tool's capabilities using the workflow architecture.\nThis validates that the workflow-based security audit provides step-by-step\nanalysis with proper investigation guidance and expert analysis integration.\n\"\"\"\n\nimport json\n\nfrom .conversation_base_test import ConversationBaseTest\n\n\nclass SecauditValidationTest(ConversationBaseTest):\n \"\"\"Test secaudit tool with workflow architecture\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"secaudit_validation\"\n\n @property\n def test_description(self) -> str:\n return \"SECAUDIT tool validation with security audit workflow architecture\"\n\n def run_test(self) -> bool:\n \"\"\"Test secaudit tool capabilities\"\"\"\n # Set up the test environment\n self.setUp()\n\n try:\n self.logger.info(\"Test: SECAUDIT tool validation (security workflow architecture)\")\n\n # Create test code with various security vulnerabilities\n self._create_test_code_for_audit()\n\n # Test 1: Single audit session with multiple steps\n if not self._test_single_audit_session():\n return False\n\n # Test 2: Audit with specific focus areas\n if not self._test_focused_security_audit():\n return False\n\n # Test 3: Complete audit with expert analysis using fast model\n if not self._test_complete_audit_with_analysis():\n return False\n\n # Test 4: Certain confidence behavior\n if not self._test_certain_confidence():\n return False\n\n # Test 5: Continuation test with chat tool\n if not self._test_continuation_with_chat():\n return False\n\n # Test 6: Model selection control\n if not self._test_model_selection():\n return False\n\n self.logger.info(\" βœ… All secaudit validation tests passed\")\n return True\n\n except Exception as e:\n self.logger.error(f\"SECAUDIT validation test failed: {e}\")\n return False\n\n def _create_test_code_for_audit(self):\n \"\"\"Create test files with various security vulnerabilities\"\"\"\n # Create an authentication module with multiple security issues\n auth_code = \"\"\"#!/usr/bin/env python3\nimport hashlib\nimport pickle\nimport sqlite3\nfrom flask import request, session\n\nclass AuthenticationManager:\n def __init__(self, db_path=\"users.db\"):\n # A01: Broken Access Control - No proper session management\n self.db_path = db_path\n self.sessions = {} # In-memory session storage\n def login(self, username, password):\n '''User login with various security vulnerabilities'''\n # A03: Injection - SQL injection vulnerability\n conn = sqlite3.connect(self.db_path)\n cursor = conn.cursor()\n\n # Direct string interpolation in SQL query\n query = f\"SELECT id, password_hash FROM users WHERE username = '{username}'\"\n cursor.execute(query)\n\n user = cursor.fetchone()\n if not user:\n return {\"status\": \"failed\", \"message\": \"User not found\"}\n\n # A02: Cryptographic Failures - Weak hashing algorithm\n password_hash = hashlib.md5(password.encode()).hexdigest()\n\n if user[1] == password_hash:\n # A07: Identification and Authentication Failures - Weak session generation\n session_id = hashlib.md5(f\"{username}{password}\".encode()).hexdigest()\n self.sessions[session_id] = {\"user_id\": user[0], \"username\": username}\n\n return {\"status\": \"success\", \"session_id\": session_id}\n else:\n return {\"status\": \"failed\", \"message\": \"Invalid password\"}\n\n def reset_password(self, email):\n '''Password reset with security issues'''\n # A04: Insecure Design - No rate limiting or validation\n reset_token = hashlib.md5(email.encode()).hexdigest()\n\n # A09: Security Logging and Monitoring Failures - No security event logging\n # Simply returns token without any verification or logging\n return {\"reset_token\": reset_token, \"url\": f\"/reset?token={reset_token}\"}\n\n def deserialize_user_data(self, data):\n '''Unsafe deserialization'''\n # A08: Software and Data Integrity Failures - Insecure deserialization\n return pickle.loads(data)\n\n def get_user_profile(self, user_id):\n '''Get user profile with authorization issues'''\n # A01: Broken Access Control - No authorization check\n conn = sqlite3.connect(self.db_path)\n cursor = conn.cursor()\n\n # Fetches any user profile without checking permissions\n cursor.execute(\"SELECT * FROM users WHERE id = ?\", (user_id,))\n return cursor.fetchone()\n\"\"\"\n\n # Create authentication file\n self.auth_file = self.create_additional_test_file(\"auth_manager.py\", auth_code)\n self.logger.info(f\" βœ… Created authentication file with security issues: {self.auth_file}\")\n\n # Create API endpoint with additional vulnerabilities\n api_code = \"\"\"#!/usr/bin/env python3\nfrom flask import Flask, request, jsonify\nimport os\nimport subprocess\nimport requests\n\napp = Flask(__name__)\n\n# A05: Security Misconfiguration - Debug mode enabled\napp.config['DEBUG'] = True\napp.config['SECRET_KEY'] = 'dev-secret-key' # Hardcoded secret\n\n@app.route('/api/search', methods=['GET'])\ndef search():\n '''Search endpoint with multiple vulnerabilities'''\n # A03: Injection - XSS vulnerability, no input sanitization\n query = request.args.get('q', '')\n\n # A03: Injection - Command injection vulnerability\n if 'file:' in query:\n filename = query.split('file:')[1]\n # Direct command execution\n result = subprocess.run(f\"cat {filename}\", shell=True, capture_output=True, text=True)\n return jsonify({\"result\": result.stdout})\n\n # A10: Server-Side Request Forgery (SSRF)\n if query.startswith('http'):\n # No validation of URL, allows internal network access\n response = requests.get(query)\n return jsonify({\"content\": response.text})\n\n # Return search results without output encoding\n return f\"

Search Results for: {query}

\"\n\n@app.route('/api/admin', methods=['GET'])\ndef admin_panel():\n '''Admin panel with broken access control'''\n # A01: Broken Access Control - No authentication check\n # Anyone can access admin functionality\n action = request.args.get('action')\n\n if action == 'delete_user':\n user_id = request.args.get('user_id')\n # Performs privileged action without authorization\n return jsonify({\"status\": \"User deleted\", \"user_id\": user_id})\n\n return jsonify({\"status\": \"Admin panel\"})\n\n@app.route('/api/upload', methods=['POST'])\ndef upload_file():\n '''File upload with security issues'''\n # A05: Security Misconfiguration - No file type validation\n file = request.files.get('file')\n if file:\n # Saves any file type to server\n filename = file.filename\n file.save(os.path.join('/tmp', filename))\n\n # A03: Path traversal vulnerability\n return jsonify({\"status\": \"File uploaded\", \"path\": f\"/tmp/{filename}\"})\n\n return jsonify({\"error\": \"No file provided\"})\n\n# A06: Vulnerable and Outdated Components\n# Using old Flask version with known vulnerabilities (hypothetical)\n# requirements.txt: Flask==0.12.2 (known security issues)\n\nif __name__ == '__main__':\n # A05: Security Misconfiguration - Running on all interfaces\n app.run(host='0.0.0.0', port=5000, debug=True)\n\"\"\"\n\n # Create API file\n self.api_file = self.create_additional_test_file(\"api_endpoints.py\", api_code)\n self.logger.info(f\" βœ… Created API file with security vulnerabilities: {self.api_file}\")\n\n def _test_single_audit_session(self) -> bool:\n \"\"\"Test a single security audit session with multiple steps\"\"\"\n self.logger.info(\" πŸ”§ Testing single audit session...\")\n\n try:\n # Step 1: Initial security audit request\n response, continuation_id = self.call_mcp_tool_direct(\n \"secaudit\",\n {\n \"step\": f\"Begin security audit of authentication system in {self.auth_file}\",\n \"step_number\": 1,\n \"total_steps\": 6,\n \"next_step_required\": True,\n \"findings\": \"Starting security assessment\",\n \"relevant_files\": [self.auth_file],\n \"model\": \"gemini-2.0-flash-lite\",\n },\n )\n\n if not response:\n self.logger.error(\"Failed to call secaudit tool\")\n return False\n\n # Parse and validate the response\n try:\n response_data = json.loads(response) if response else {}\n except json.JSONDecodeError:\n response_data = {}\n\n # Check if it's asking for investigation\n status = response_data.get(\"status\", \"\")\n if status != \"pause_for_secaudit\":\n self.logger.error(f\"Expected pause_for_secaudit status, got: {status}\")\n return False\n\n # Step 2: Continue with findings\n response2, _ = self.call_mcp_tool_direct(\n \"secaudit\",\n {\n \"step\": \"Examined authentication module and found critical security vulnerabilities\",\n \"step_number\": 2,\n \"total_steps\": 6,\n \"next_step_required\": True,\n \"findings\": (\n \"Found multiple OWASP Top 10 vulnerabilities: \"\n \"1. SQL injection in login method (line 88) - direct string interpolation in query \"\n \"2. Weak MD5 hashing for passwords (line 96) - cryptographically broken \"\n \"3. Insecure session management (line 100) - predictable session IDs \"\n \"4. Unsafe deserialization (line 119) - pickle.loads without validation\"\n ),\n \"files_checked\": [self.auth_file],\n \"relevant_files\": [self.auth_file],\n \"relevant_context\": [\"AuthenticationManager.login\", \"AuthenticationManager.deserialize_user_data\"],\n \"issues_found\": [\n {\"severity\": \"critical\", \"description\": \"SQL injection vulnerability in login method\"},\n {\"severity\": \"high\", \"description\": \"Weak MD5 password hashing\"},\n {\"severity\": \"high\", \"description\": \"Insecure session management\"},\n {\"severity\": \"critical\", \"description\": \"Unsafe deserialization vulnerability\"},\n ],\n \"confidence\": \"medium\",\n \"continuation_id\": continuation_id,\n \"model\": \"gemini-2.0-flash-lite\",\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue to step 2\")\n return False\n\n self.logger.info(\" βœ… Single audit session test passed\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Single audit session test failed: {e}\")\n return False\n\n def _test_focused_security_audit(self) -> bool:\n \"\"\"Test security audit with specific focus areas\"\"\"\n self.logger.info(\" πŸ”§ Testing focused security audit...\")\n\n try:\n # Request OWASP-focused audit\n response, continuation_id = self.call_mcp_tool_direct(\n \"secaudit\",\n {\n \"step\": f\"Begin OWASP-focused security audit of {self.api_file}\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Starting OWASP Top 10 focused security assessment\",\n \"relevant_files\": [self.api_file],\n \"security_scope\": \"Web API endpoints\",\n \"threat_level\": \"high\",\n \"audit_focus\": \"owasp\",\n \"model\": \"gemini-2.0-flash-lite\",\n },\n )\n\n if not response:\n self.logger.error(\"Failed to start OWASP-focused audit\")\n return False\n\n # Verify the audit was configured correctly\n try:\n response_data = json.loads(response)\n # The tool should acknowledge the OWASP focus\n if response_data.get(\"status\") == \"pause_for_secaudit\":\n self.logger.info(\" βœ… Focused security audit test passed\")\n return True\n except json.JSONDecodeError:\n pass\n\n self.logger.error(\"Expected proper OWASP-focused configuration\")\n return False\n\n except Exception as e:\n self.logger.error(f\"Focused security audit test failed: {e}\")\n return False\n\n def _test_complete_audit_with_analysis(self) -> bool:\n \"\"\"Test complete security audit with expert analysis\"\"\"\n self.logger.info(\" πŸ”§ Testing complete audit with expert analysis...\")\n\n try:\n # Step 1: Start fresh audit\n response1, continuation_id = self.call_mcp_tool_direct(\n \"secaudit\",\n {\n \"step\": f\"Begin comprehensive security audit of {self.auth_file} and {self.api_file}\",\n \"step_number\": 1,\n \"total_steps\": 3,\n \"next_step_required\": True,\n \"findings\": \"Starting OWASP Top 10 security assessment of authentication and API modules\",\n \"relevant_files\": [self.auth_file, self.api_file],\n \"security_scope\": \"Web application with authentication and API endpoints\",\n \"model\": \"gemini-2.0-flash-lite\",\n },\n )\n\n if not response1:\n self.logger.error(\"Failed to start comprehensive audit\")\n return False\n\n # Step 2: Continue with detailed findings\n response2, _ = self.call_mcp_tool_direct(\n \"secaudit\",\n {\n \"step\": \"Completed comprehensive security investigation of both modules\",\n \"step_number\": 2,\n \"total_steps\": 3,\n \"next_step_required\": True,\n \"findings\": (\n \"Found critical OWASP vulnerabilities across both modules: \"\n \"A01: Broken Access Control in admin panel, \"\n \"A03: SQL injection in login and command injection in search, \"\n \"A02: Weak cryptography with MD5 hashing, \"\n \"A05: Security misconfiguration with debug mode enabled, \"\n \"A07: Weak session management, \"\n \"A08: Insecure deserialization, \"\n \"A10: SSRF vulnerability in search endpoint\"\n ),\n \"files_checked\": [self.auth_file, self.api_file],\n \"relevant_files\": [self.auth_file, self.api_file],\n \"relevant_context\": [\n \"AuthenticationManager.login\",\n \"AuthenticationManager.deserialize_user_data\",\n \"api.search\",\n \"api.admin_panel\",\n ],\n \"issues_found\": [\n {\"severity\": \"critical\", \"description\": \"SQL injection in login method\"},\n {\"severity\": \"critical\", \"description\": \"Command injection in search endpoint\"},\n {\"severity\": \"critical\", \"description\": \"SSRF vulnerability allowing internal network access\"},\n {\"severity\": \"high\", \"description\": \"Broken access control on admin panel\"},\n {\"severity\": \"high\", \"description\": \"Insecure deserialization vulnerability\"},\n {\"severity\": \"high\", \"description\": \"XSS vulnerability in search results\"},\n {\"severity\": \"medium\", \"description\": \"Weak MD5 password hashing\"},\n {\"severity\": \"medium\", \"description\": \"Security misconfiguration - debug mode enabled\"},\n ],\n \"confidence\": \"high\",\n \"continuation_id\": continuation_id,\n \"model\": \"gemini-2.0-flash-lite\",\n },\n )\n\n # Final step - skip expert analysis to avoid timeout\n response3, _ = self.call_mcp_tool_direct(\n \"secaudit\",\n {\n \"step\": \"Complete security assessment with all vulnerabilities documented\",\n \"step_number\": 3,\n \"total_steps\": 3,\n \"next_step_required\": False,\n \"findings\": \"Security audit complete with 8 vulnerabilities identified across OWASP categories\",\n \"files_checked\": [self.auth_file, self.api_file],\n \"relevant_files\": [self.auth_file, self.api_file],\n \"confidence\": \"high\", # High confidence to trigger expert analysis\n \"continuation_id\": continuation_id,\n \"model\": \"gemini-2.0-flash-lite\",\n },\n )\n\n if response3:\n # Check for expert analysis or completion status\n try:\n response_data = json.loads(response3)\n status = response_data.get(\"status\", \"\")\n # Either expert analysis completed or security analysis complete\n if status in [\"complete\", \"security_analysis_complete\"]:\n self.logger.info(\" βœ… Complete audit with expert analysis test passed\")\n return True\n except json.JSONDecodeError:\n # If not JSON, check for security content (expert analysis output)\n if \"security\" in response3.lower() or \"vulnerability\" in response3.lower():\n self.logger.info(\" βœ… Complete audit with expert analysis test passed\")\n return True\n\n self.logger.error(\"Expected expert security analysis or completion\")\n return False\n\n except Exception as e:\n self.logger.error(f\"Complete audit with analysis test failed: {e}\")\n return False\n\n def _test_certain_confidence(self) -> bool:\n \"\"\"Test behavior when confidence is certain\"\"\"\n self.logger.info(\" πŸ”§ Testing certain confidence behavior...\")\n\n try:\n # Request with certain confidence\n response, _ = self.call_mcp_tool_direct(\n \"secaudit\",\n {\n \"step\": f\"Security audit complete for {self.auth_file}\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Critical SQL injection vulnerability confirmed in login method\",\n \"files_checked\": [self.auth_file],\n \"relevant_files\": [self.auth_file],\n \"issues_found\": [\n {\"severity\": \"critical\", \"description\": \"SQL injection vulnerability in login method\"}\n ],\n \"confidence\": \"certain\",\n \"model\": \"gemini-2.0-flash-lite\",\n },\n )\n\n if not response:\n self.logger.error(\"Failed to execute certain confidence test\")\n return False\n\n try:\n response_data = json.loads(response)\n # With certain confidence, should complete without expert analysis\n if response_data.get(\"status\") == \"security_analysis_complete\":\n self.logger.info(\" βœ… Certain confidence correctly completes without expert analysis\")\n return True\n except json.JSONDecodeError:\n pass\n\n # Check if findings are shown directly\n response_lower = response.lower()\n if \"sql injection\" in response_lower or \"vulnerability\" in response_lower:\n self.logger.info(\" βœ… Certain confidence shows findings directly\")\n return True\n\n self.logger.error(\"Expected completion or direct findings with certain confidence\")\n return False\n\n except Exception as e:\n self.logger.error(f\"Certain confidence test failed: {e}\")\n return False\n\n def _test_continuation_with_chat(self) -> bool:\n \"\"\"Test continuation functionality with chat tool\"\"\"\n self.logger.info(\" πŸ”§ Testing continuation with chat tool...\")\n\n try:\n # First, run a security audit that generates a continuation_id\n response1, continuation_id = self.call_mcp_tool_direct(\n \"secaudit\",\n {\n \"step\": f\"Start analyzing {self.auth_file} for authentication vulnerabilities\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Beginning authentication security analysis\",\n \"relevant_files\": [self.auth_file],\n \"model\": \"gemini-2.0-flash-lite\",\n },\n )\n\n if not response1:\n self.logger.error(\"Failed to start audit for continuation test\")\n return False\n\n # Extract continuation_id if present\n if not continuation_id:\n self.logger.info(\" ⚠️ No continuation_id returned, checking response\")\n try:\n response_data = json.loads(response1)\n # Look for thread_id in metadata\n metadata = response_data.get(\"metadata\", {})\n continuation_id = metadata.get(\"thread_id\")\n except json.JSONDecodeError:\n pass\n\n if continuation_id:\n # Now test using chat tool with continuation\n chat_response, _ = self.call_mcp_tool_direct(\n \"chat\",\n {\n \"prompt\": \"Can you tell me more about the SQL injection vulnerability details found in the security audit?\",\n \"continuation_id\": continuation_id,\n \"model\": \"gemini-2.0-flash-lite\",\n },\n )\n\n if chat_response:\n self.logger.info(\" βœ… Chat tool continuation test passed\")\n return True\n else:\n # Without continuation_id, just verify the audit step worked\n if response1:\n self.logger.info(\" βœ… Audit step completed (continuation test limited)\")\n return True\n\n self.logger.error(\"Expected successful continuation or audit step\")\n return False\n\n except Exception as e:\n self.logger.error(f\"Continuation test failed: {e}\")\n return False\n\n def _test_model_selection(self) -> bool:\n \"\"\"Test model selection and skip expert analysis option\"\"\"\n self.logger.info(\" πŸ”§ Testing model selection control...\")\n\n try:\n # Test 1: Explicit model selection\n response1, _ = self.call_mcp_tool_direct(\n \"secaudit\",\n {\n \"step\": f\"Analyze {self.api_file} for SSRF vulnerabilities\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"findings\": \"Starting SSRF vulnerability analysis\",\n \"relevant_files\": [self.api_file],\n \"audit_focus\": \"owasp\",\n \"model\": \"gemini-2.0-flash-lite\",\n },\n )\n\n if response1:\n self.logger.info(\" βœ… Model selection recognized\")\n\n # Test 2: Skip expert analysis\n response2, _ = self.call_mcp_tool_direct(\n \"secaudit\",\n {\n \"step\": f\"Complete security investigation of {self.auth_file}\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Security issues documented\",\n \"files_checked\": [self.auth_file],\n \"relevant_files\": [self.auth_file],\n \"confidence\": \"high\",\n \"use_assistant_model\": False, # Skip expert analysis\n \"model\": \"gemini-2.0-flash-lite\",\n },\n )\n\n if response2:\n try:\n response_data = json.loads(response2)\n # Should complete without expert analysis\n if response_data.get(\"status\") == \"security_analysis_complete\":\n self.logger.info(\" βœ… Skip expert analysis option works\")\n return True\n except json.JSONDecodeError:\n pass\n\n # Or might just complete the analysis\n response_lower = response2.lower()\n if \"complete\" in response_lower or \"security\" in response_lower:\n self.logger.info(\" βœ… Analysis performed without expert model\")\n return True\n\n self.logger.error(\"Expected model selection or skip behavior\")\n return False\n\n except Exception as e:\n self.logger.error(f\"Model selection test failed: {e}\")\n return False\n" }, { "path": "simulator_tests/test_testgen_validation.py", "content": "#!/usr/bin/env python3\n\"\"\"\nTestGen Tool Validation Test\n\nTests the testgen tool's capabilities using the workflow architecture.\nThis validates that the workflow-based implementation guides Claude through\nsystematic test generation analysis before creating comprehensive test suites.\n\"\"\"\n\nimport json\nfrom typing import Optional\n\nfrom .conversation_base_test import ConversationBaseTest\n\n\nclass TestGenValidationTest(ConversationBaseTest):\n \"\"\"Test testgen tool with workflow architecture\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"testgen_validation\"\n\n @property\n def test_description(self) -> str:\n return \"TestGen tool validation with step-by-step test planning\"\n\n def run_test(self) -> bool:\n \"\"\"Test testgen tool capabilities\"\"\"\n # Set up the test environment\n self.setUp()\n\n try:\n self.logger.info(\"Test: TestGen tool validation\")\n\n # Create sample code files to test\n self._create_test_code_files()\n\n # Test 1: Single investigation session with multiple steps\n if not self._test_single_test_generation_session():\n return False\n\n # Test 2: Test generation with pattern following\n if not self._test_generation_with_pattern_following():\n return False\n\n # Test 3: Complete test generation with expert analysis\n if not self._test_complete_generation_with_analysis():\n return False\n\n # Test 4: Certain confidence behavior\n if not self._test_certain_confidence():\n return False\n\n # Test 5: Context-aware file embedding\n if not self._test_context_aware_file_embedding():\n return False\n\n # Test 6: Multi-step test planning\n if not self._test_multi_step_test_planning():\n return False\n\n self.logger.info(\" βœ… All testgen validation tests passed\")\n return True\n\n except Exception as e:\n self.logger.error(f\"TestGen validation test failed: {e}\")\n return False\n\n def _create_test_code_files(self):\n \"\"\"Create sample code files for test generation\"\"\"\n # Create a calculator module with various functions\n calculator_code = \"\"\"#!/usr/bin/env python3\n\\\"\\\"\\\"\nSimple calculator module for demonstration\n\\\"\\\"\\\"\n\ndef add(a, b):\n \\\"\\\"\\\"Add two numbers\\\"\\\"\\\"\n return a + b\n\ndef subtract(a, b):\n \\\"\\\"\\\"Subtract b from a\\\"\\\"\\\"\n return a - b\n\ndef multiply(a, b):\n \\\"\\\"\\\"Multiply two numbers\\\"\\\"\\\"\n return a * b\n\ndef divide(a, b):\n \\\"\\\"\\\"Divide a by b\\\"\\\"\\\"\n if b == 0:\n raise ValueError(\"Cannot divide by zero\")\n return a / b\n\ndef calculate_percentage(value, percentage):\n \\\"\\\"\\\"Calculate percentage of a value\\\"\\\"\\\"\n if percentage < 0:\n raise ValueError(\"Percentage cannot be negative\")\n if percentage > 100:\n raise ValueError(\"Percentage cannot exceed 100\")\n return (value * percentage) / 100\n\ndef power(base, exponent):\n \\\"\\\"\\\"Calculate base raised to exponent\\\"\\\"\\\"\n if base == 0 and exponent < 0:\n raise ValueError(\"Cannot raise 0 to negative power\")\n return base ** exponent\n\"\"\"\n\n # Create test file\n self.calculator_file = self.create_additional_test_file(\"calculator.py\", calculator_code)\n self.logger.info(f\" βœ… Created calculator module: {self.calculator_file}\")\n\n # Create a simple existing test file to use as pattern\n existing_test = \"\"\"#!/usr/bin/env python3\nimport pytest\nfrom calculator import add, subtract\n\nclass TestCalculatorBasic:\n \\\"\\\"\\\"Test basic calculator operations\\\"\\\"\\\"\n\n def test_add_positive_numbers(self):\n \\\"\\\"\\\"Test adding two positive numbers\\\"\\\"\\\"\n assert add(2, 3) == 5\n assert add(10, 20) == 30\n\n def test_add_negative_numbers(self):\n \\\"\\\"\\\"Test adding negative numbers\\\"\\\"\\\"\n assert add(-5, -3) == -8\n assert add(-10, 5) == -5\n\n def test_subtract_positive(self):\n \\\"\\\"\\\"Test subtracting positive numbers\\\"\\\"\\\"\n assert subtract(10, 3) == 7\n assert subtract(5, 5) == 0\n\"\"\"\n\n self.existing_test_file = self.create_additional_test_file(\"test_calculator_basic.py\", existing_test)\n self.logger.info(f\" βœ… Created existing test file: {self.existing_test_file}\")\n\n def _test_single_test_generation_session(self) -> bool:\n \"\"\"Test a complete test generation session with multiple steps\"\"\"\n try:\n self.logger.info(\" 1.1: Testing single test generation session\")\n\n # Step 1: Start investigation\n self.logger.info(\" 1.1.1: Step 1 - Initial test planning\")\n response1, continuation_id = self.call_mcp_tool(\n \"testgen\",\n {\n \"step\": \"I need to generate comprehensive tests for the calculator module. Let me start by analyzing the code structure and understanding the functionality.\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Calculator module contains 6 functions: add, subtract, multiply, divide, calculate_percentage, and power. Each has specific error conditions that need testing.\",\n \"files_checked\": [self.calculator_file],\n \"relevant_files\": [self.calculator_file],\n \"relevant_context\": [\"add\", \"subtract\", \"multiply\", \"divide\", \"calculate_percentage\", \"power\"],\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to get initial test planning response\")\n return False\n\n # Parse and validate JSON response\n response1_data = self._parse_testgen_response(response1)\n if not response1_data:\n return False\n\n # Validate step 1 response structure\n if not self._validate_step_response(response1_data, 1, 4, True, \"pause_for_test_analysis\"):\n return False\n\n self.logger.info(f\" βœ… Step 1 successful, continuation_id: {continuation_id}\")\n\n # Step 2: Analyze test requirements\n self.logger.info(\" 1.1.2: Step 2 - Test requirements analysis\")\n response2, _ = self.call_mcp_tool(\n \"testgen\",\n {\n \"step\": \"Now analyzing the test requirements for each function, identifying edge cases and boundary conditions.\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Identified key test scenarios: (1) divide - zero division error, (2) calculate_percentage - negative/over 100 validation, (3) power - zero to negative power error. Need tests for normal cases and edge cases.\",\n \"files_checked\": [self.calculator_file],\n \"relevant_files\": [self.calculator_file],\n \"relevant_context\": [\"divide\", \"calculate_percentage\", \"power\"],\n \"confidence\": \"medium\",\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue test planning to step 2\")\n return False\n\n response2_data = self._parse_testgen_response(response2)\n if not self._validate_step_response(response2_data, 2, 4, True, \"pause_for_test_analysis\"):\n return False\n\n # Check test generation status tracking\n test_status = response2_data.get(\"test_generation_status\", {})\n if test_status.get(\"test_scenarios_identified\", 0) < 3:\n self.logger.error(\"Test scenarios not properly tracked\")\n return False\n\n if test_status.get(\"analysis_confidence\") != \"medium\":\n self.logger.error(\"Confidence level not properly tracked\")\n return False\n\n self.logger.info(\" βœ… Step 2 successful with proper tracking\")\n\n # Store continuation_id for next test\n self.test_continuation_id = continuation_id\n return True\n\n except Exception as e:\n self.logger.error(f\"Single test generation session test failed: {e}\")\n return False\n\n def _test_generation_with_pattern_following(self) -> bool:\n \"\"\"Test test generation following existing patterns\"\"\"\n try:\n self.logger.info(\" 1.2: Testing test generation with pattern following\")\n\n # Start a new investigation with existing test patterns\n self.logger.info(\" 1.2.1: Start test generation with pattern reference\")\n response1, continuation_id = self.call_mcp_tool(\n \"testgen\",\n {\n \"step\": \"Generating tests for remaining calculator functions following existing test patterns\",\n \"step_number\": 1,\n \"total_steps\": 3,\n \"next_step_required\": True,\n \"findings\": \"Found existing test pattern using pytest with class-based organization and descriptive test names\",\n \"files_checked\": [self.calculator_file, self.existing_test_file],\n \"relevant_files\": [self.calculator_file, self.existing_test_file],\n \"relevant_context\": [\"TestCalculatorBasic\", \"multiply\", \"divide\", \"calculate_percentage\", \"power\"],\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start pattern following test\")\n return False\n\n # Step 2: Analyze patterns\n self.logger.info(\" 1.2.2: Step 2 - Pattern analysis\")\n response2, _ = self.call_mcp_tool(\n \"testgen\",\n {\n \"step\": \"Analyzing the existing test patterns to maintain consistency\",\n \"step_number\": 2,\n \"total_steps\": 3,\n \"next_step_required\": True,\n \"findings\": \"Existing tests use: class-based organization (TestCalculatorBasic), descriptive method names (test_operation_scenario), multiple assertions per test, pytest framework\",\n \"files_checked\": [self.existing_test_file],\n \"relevant_files\": [self.calculator_file, self.existing_test_file],\n \"confidence\": \"high\",\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue to step 2\")\n return False\n\n self.logger.info(\" βœ… Pattern analysis successful\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Pattern following test failed: {e}\")\n return False\n\n def _test_complete_generation_with_analysis(self) -> bool:\n \"\"\"Test complete test generation ending with expert analysis\"\"\"\n try:\n self.logger.info(\" 1.3: Testing complete test generation with expert analysis\")\n\n # Use the continuation from first test or start fresh\n continuation_id = getattr(self, \"test_continuation_id\", None)\n if not continuation_id:\n # Start fresh if no continuation available\n self.logger.info(\" 1.3.0: Starting fresh test generation\")\n response0, continuation_id = self.call_mcp_tool(\n \"testgen\",\n {\n \"step\": \"Analyzing calculator module for comprehensive test generation\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"findings\": \"Identified 6 functions needing tests with various edge cases\",\n \"files_checked\": [self.calculator_file],\n \"relevant_files\": [self.calculator_file],\n \"relevant_context\": [\"add\", \"subtract\", \"multiply\", \"divide\", \"calculate_percentage\", \"power\"],\n },\n )\n if not response0 or not continuation_id:\n self.logger.error(\"Failed to start fresh test generation\")\n return False\n\n # Final step - trigger expert analysis\n self.logger.info(\" 1.3.1: Final step - complete test planning\")\n response_final, _ = self.call_mcp_tool(\n \"testgen\",\n {\n \"step\": \"Test planning complete. Identified all test scenarios including edge cases, error conditions, and boundary values for comprehensive coverage.\",\n \"step_number\": 2,\n \"total_steps\": 2,\n \"next_step_required\": False, # Final step - triggers expert analysis\n \"findings\": \"Complete test plan: normal operations, edge cases (zero, negative), error conditions (divide by zero, invalid percentage, zero to negative power), boundary values\",\n \"files_checked\": [self.calculator_file],\n \"relevant_files\": [self.calculator_file],\n \"relevant_context\": [\"add\", \"subtract\", \"multiply\", \"divide\", \"calculate_percentage\", \"power\"],\n \"confidence\": \"high\",\n \"continuation_id\": continuation_id,\n \"model\": \"flash\", # Use flash for expert analysis\n },\n )\n\n if not response_final:\n self.logger.error(\"Failed to complete test generation\")\n return False\n\n response_final_data = self._parse_testgen_response(response_final)\n if not response_final_data:\n return False\n\n # Validate final response structure\n if response_final_data.get(\"status\") != \"calling_expert_analysis\":\n self.logger.error(\n f\"Expected status 'calling_expert_analysis', got '{response_final_data.get('status')}'\"\n )\n return False\n\n if not response_final_data.get(\"test_generation_complete\"):\n self.logger.error(\"Expected test_generation_complete=true for final step\")\n return False\n\n # Check for expert analysis\n if \"expert_analysis\" not in response_final_data:\n self.logger.error(\"Missing expert_analysis in final response\")\n return False\n\n expert_analysis = response_final_data.get(\"expert_analysis\", {})\n\n # Check for expected analysis content\n analysis_text = json.dumps(expert_analysis, ensure_ascii=False).lower()\n\n # Look for test generation indicators\n test_indicators = [\"test\", \"edge\", \"boundary\", \"error\", \"coverage\", \"pytest\"]\n found_indicators = sum(1 for indicator in test_indicators if indicator in analysis_text)\n\n if found_indicators >= 4:\n self.logger.info(\" βœ… Expert analysis provided comprehensive test suggestions\")\n else:\n self.logger.warning(\n f\" ⚠️ Expert analysis may not have fully addressed test generation (found {found_indicators}/6 indicators)\"\n )\n\n # Check complete test generation summary\n if \"complete_test_generation\" not in response_final_data:\n self.logger.error(\"Missing complete_test_generation in final response\")\n return False\n\n complete_generation = response_final_data[\"complete_test_generation\"]\n if not complete_generation.get(\"relevant_context\"):\n self.logger.error(\"Missing relevant context in complete test generation\")\n return False\n\n self.logger.info(\" βœ… Complete test generation with expert analysis successful\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Complete test generation test failed: {e}\")\n return False\n\n def _test_certain_confidence(self) -> bool:\n \"\"\"Test certain confidence behavior - should skip expert analysis\"\"\"\n try:\n self.logger.info(\" 1.4: Testing certain confidence behavior\")\n\n # Test certain confidence - should skip expert analysis\n self.logger.info(\" 1.4.1: Certain confidence test generation\")\n response_certain, _ = self.call_mcp_tool(\n \"testgen\",\n {\n \"step\": \"I have fully analyzed the code and identified all test scenarios with 100% certainty. Test plan is complete.\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False, # Final step\n \"findings\": \"Complete test coverage plan: all functions covered with normal cases, edge cases, and error conditions. Ready for implementation.\",\n \"files_checked\": [self.calculator_file],\n \"relevant_files\": [self.calculator_file],\n \"relevant_context\": [\"add\", \"subtract\", \"multiply\", \"divide\", \"calculate_percentage\", \"power\"],\n \"confidence\": \"certain\", # This should skip expert analysis\n \"model\": \"flash\",\n },\n )\n\n if not response_certain:\n self.logger.error(\"Failed to test certain confidence\")\n return False\n\n response_certain_data = self._parse_testgen_response(response_certain)\n if not response_certain_data:\n return False\n\n # Validate certain confidence response - should skip expert analysis\n if response_certain_data.get(\"status\") != \"test_generation_complete_ready_for_implementation\":\n self.logger.error(\n f\"Expected status 'test_generation_complete_ready_for_implementation', got '{response_certain_data.get('status')}'\"\n )\n return False\n\n if not response_certain_data.get(\"skip_expert_analysis\"):\n self.logger.error(\"Expected skip_expert_analysis=true for certain confidence\")\n return False\n\n expert_analysis = response_certain_data.get(\"expert_analysis\", {})\n if expert_analysis.get(\"status\") != \"skipped_due_to_certain_test_confidence\":\n self.logger.error(\"Expert analysis should be skipped for certain confidence\")\n return False\n\n self.logger.info(\" βœ… Certain confidence behavior working correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Certain confidence test failed: {e}\")\n return False\n\n def call_mcp_tool(self, tool_name: str, params: dict) -> tuple[Optional[str], Optional[str]]:\n \"\"\"Call an MCP tool in-process - override for testgen-specific response handling\"\"\"\n # Use in-process implementation to maintain conversation memory\n response_text, _ = self.call_mcp_tool_direct(tool_name, params)\n\n if not response_text:\n return None, None\n\n # Extract continuation_id from testgen response specifically\n continuation_id = self._extract_testgen_continuation_id(response_text)\n\n return response_text, continuation_id\n\n def _extract_testgen_continuation_id(self, response_text: str) -> Optional[str]:\n \"\"\"Extract continuation_id from testgen response\"\"\"\n try:\n # Parse the response\n response_data = json.loads(response_text)\n return response_data.get(\"continuation_id\")\n\n except json.JSONDecodeError as e:\n self.logger.debug(f\"Failed to parse response for testgen continuation_id: {e}\")\n return None\n\n def _parse_testgen_response(self, response_text: str) -> dict:\n \"\"\"Parse testgen tool JSON response\"\"\"\n try:\n # Parse the response - it should be direct JSON\n return json.loads(response_text)\n\n except json.JSONDecodeError as e:\n self.logger.error(f\"Failed to parse testgen response as JSON: {e}\")\n self.logger.error(f\"Response text: {response_text[:500]}...\")\n return {}\n\n def _validate_step_response(\n self,\n response_data: dict,\n expected_step: int,\n expected_total: int,\n expected_next_required: bool,\n expected_status: str,\n ) -> bool:\n \"\"\"Validate a test generation step response structure\"\"\"\n try:\n # Check status\n if response_data.get(\"status\") != expected_status:\n self.logger.error(f\"Expected status '{expected_status}', got '{response_data.get('status')}'\")\n return False\n\n # Check step number\n if response_data.get(\"step_number\") != expected_step:\n self.logger.error(f\"Expected step_number {expected_step}, got {response_data.get('step_number')}\")\n return False\n\n # Check total steps\n if response_data.get(\"total_steps\") != expected_total:\n self.logger.error(f\"Expected total_steps {expected_total}, got {response_data.get('total_steps')}\")\n return False\n\n # Check next_step_required\n if response_data.get(\"next_step_required\") != expected_next_required:\n self.logger.error(\n f\"Expected next_step_required {expected_next_required}, got {response_data.get('next_step_required')}\"\n )\n return False\n\n # Check test_generation_status exists\n if \"test_generation_status\" not in response_data:\n self.logger.error(\"Missing test_generation_status in response\")\n return False\n\n # Check next_steps guidance\n if not response_data.get(\"next_steps\"):\n self.logger.error(\"Missing next_steps guidance in response\")\n return False\n\n return True\n\n except Exception as e:\n self.logger.error(f\"Error validating step response: {e}\")\n return False\n\n def _test_context_aware_file_embedding(self) -> bool:\n \"\"\"Test context-aware file embedding optimization\"\"\"\n try:\n self.logger.info(\" 1.5: Testing context-aware file embedding\")\n\n # Create additional test files\n utils_code = \"\"\"#!/usr/bin/env python3\ndef validate_number(n):\n \\\"\\\"\\\"Validate if input is a number\\\"\\\"\\\"\n return isinstance(n, (int, float))\n\ndef format_result(result):\n \\\"\\\"\\\"Format calculation result\\\"\\\"\\\"\n if isinstance(result, float):\n return round(result, 2)\n return result\n\"\"\"\n\n math_helpers_code = \"\"\"#!/usr/bin/env python3\nimport math\n\ndef factorial(n):\n \\\"\\\"\\\"Calculate factorial of n\\\"\\\"\\\"\n if n < 0:\n raise ValueError(\"Factorial not defined for negative numbers\")\n return math.factorial(n)\n\ndef is_prime(n):\n \\\"\\\"\\\"Check if number is prime\\\"\\\"\\\"\n if n < 2:\n return False\n for i in range(2, int(n**0.5) + 1):\n if n % i == 0:\n return False\n return True\n\"\"\"\n\n # Create test files\n utils_file = self.create_additional_test_file(\"utils.py\", utils_code)\n math_file = self.create_additional_test_file(\"math_helpers.py\", math_helpers_code)\n\n # Test 1: New conversation, intermediate step - should only reference files\n self.logger.info(\" 1.5.1: New conversation intermediate step (should reference only)\")\n response1, continuation_id = self.call_mcp_tool(\n \"testgen\",\n {\n \"step\": \"Starting test generation for utility modules\",\n \"step_number\": 1,\n \"total_steps\": 3,\n \"next_step_required\": True, # Intermediate step\n \"findings\": \"Initial analysis of utility functions\",\n \"files_checked\": [utils_file, math_file],\n \"relevant_files\": [utils_file], # This should be referenced, not embedded\n \"relevant_context\": [\"validate_number\", \"format_result\"],\n \"confidence\": \"low\",\n \"model\": \"flash\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start context-aware file embedding test\")\n return False\n\n response1_data = self._parse_testgen_response(response1)\n if not response1_data:\n return False\n\n # Check file context - should be reference_only for intermediate step\n file_context = response1_data.get(\"file_context\", {})\n if file_context.get(\"type\") != \"reference_only\":\n self.logger.error(f\"Expected reference_only file context, got: {file_context.get('type')}\")\n return False\n\n self.logger.info(\" βœ… Intermediate step correctly uses reference_only file context\")\n\n # Test 2: Final step - should embed files for expert analysis\n self.logger.info(\" 1.5.2: Final step (should embed files)\")\n response2, _ = self.call_mcp_tool(\n \"testgen\",\n {\n \"step\": \"Test planning complete - all test scenarios identified\",\n \"step_number\": 2,\n \"total_steps\": 2,\n \"next_step_required\": False, # Final step - should embed files\n \"continuation_id\": continuation_id,\n \"findings\": \"Complete test plan for all utility functions with edge cases\",\n \"files_checked\": [utils_file, math_file],\n \"relevant_files\": [utils_file, math_file], # Should be fully embedded\n \"relevant_context\": [\"validate_number\", \"format_result\", \"factorial\", \"is_prime\"],\n \"confidence\": \"high\",\n \"model\": \"flash\",\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to complete to final step\")\n return False\n\n response2_data = self._parse_testgen_response(response2)\n if not response2_data:\n return False\n\n # Check file context - should be fully_embedded for final step\n file_context2 = response2_data.get(\"file_context\", {})\n if file_context2.get(\"type\") != \"fully_embedded\":\n self.logger.error(\n f\"Expected fully_embedded file context for final step, got: {file_context2.get('type')}\"\n )\n return False\n\n # Verify expert analysis was called for final step\n if response2_data.get(\"status\") != \"calling_expert_analysis\":\n self.logger.error(\"Final step should trigger expert analysis\")\n return False\n\n self.logger.info(\" βœ… Context-aware file embedding test completed successfully\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Context-aware file embedding test failed: {e}\")\n return False\n\n def _test_multi_step_test_planning(self) -> bool:\n \"\"\"Test multi-step test planning with complex code\"\"\"\n try:\n self.logger.info(\" 1.6: Testing multi-step test planning\")\n\n # Create a complex class to test\n complex_code = \"\"\"#!/usr/bin/env python3\nimport asyncio\nfrom typing import List, Dict, Optional\n\nclass DataProcessor:\n \\\"\\\"\\\"Complex data processor with async operations\\\"\\\"\\\"\n\n def __init__(self, batch_size: int = 100):\n self.batch_size = batch_size\n self.processed_count = 0\n self.error_count = 0\n self.cache: Dict[str, any] = {}\n\n async def process_batch(self, items: List[dict]) -> List[dict]:\n \\\"\\\"\\\"Process a batch of items asynchronously\\\"\\\"\\\"\n if not items:\n return []\n\n if len(items) > self.batch_size:\n raise ValueError(f\"Batch size {len(items)} exceeds limit {self.batch_size}\")\n\n results = []\n for item in items:\n try:\n result = await self._process_single_item(item)\n results.append(result)\n self.processed_count += 1\n except Exception as e:\n self.error_count += 1\n results.append({\"error\": str(e), \"item\": item})\n\n return results\n\n async def _process_single_item(self, item: dict) -> dict:\n \\\"\\\"\\\"Process a single item with caching\\\"\\\"\\\"\n item_id = item.get('id')\n if not item_id:\n raise ValueError(\"Item must have an ID\")\n\n # Check cache\n if item_id in self.cache:\n return self.cache[item_id]\n\n # Simulate async processing\n await asyncio.sleep(0.01)\n\n processed = {\n 'id': item_id,\n 'processed': True,\n 'value': item.get('value', 0) * 2\n }\n\n # Cache result\n self.cache[item_id] = processed\n return processed\n\n def get_stats(self) -> Dict[str, int]:\n \\\"\\\"\\\"Get processing statistics\\\"\\\"\\\"\n return {\n 'processed': self.processed_count,\n 'errors': self.error_count,\n 'cache_size': len(self.cache),\n 'success_rate': self.processed_count / (self.processed_count + self.error_count) if (self.processed_count + self.error_count) > 0 else 0\n }\n\"\"\"\n\n # Create test file\n processor_file = self.create_additional_test_file(\"data_processor.py\", complex_code)\n\n # Step 1: Start investigation\n self.logger.info(\" 1.6.1: Step 1 - Start complex test planning\")\n response1, continuation_id = self.call_mcp_tool(\n \"testgen\",\n {\n \"step\": \"Analyzing complex DataProcessor class for comprehensive test generation\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"DataProcessor is an async class with caching, error handling, and statistics. Need async test patterns.\",\n \"files_checked\": [processor_file],\n \"relevant_files\": [processor_file],\n \"relevant_context\": [\"DataProcessor\", \"process_batch\", \"_process_single_item\", \"get_stats\"],\n \"confidence\": \"low\",\n \"model\": \"flash\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start multi-step test planning\")\n return False\n\n response1_data = self._parse_testgen_response(response1)\n\n # Validate step 1\n file_context1 = response1_data.get(\"file_context\", {})\n if file_context1.get(\"type\") != \"reference_only\":\n self.logger.error(\"Step 1 should use reference_only file context\")\n return False\n\n self.logger.info(\" βœ… Step 1: Started complex test planning\")\n\n # Step 2: Analyze async patterns\n self.logger.info(\" 1.6.2: Step 2 - Async pattern analysis\")\n response2, _ = self.call_mcp_tool(\n \"testgen\",\n {\n \"step\": \"Analyzing async patterns and edge cases for testing\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"continuation_id\": continuation_id,\n \"findings\": \"Key test areas: async batch processing, cache behavior, error handling, batch size limits, empty items, statistics calculation\",\n \"files_checked\": [processor_file],\n \"relevant_files\": [processor_file],\n \"relevant_context\": [\"process_batch\", \"_process_single_item\"],\n \"confidence\": \"medium\",\n \"model\": \"flash\",\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue to step 2\")\n return False\n\n self.logger.info(\" βœ… Step 2: Async patterns analyzed\")\n\n # Step 3: Edge case identification\n self.logger.info(\" 1.6.3: Step 3 - Edge case identification\")\n response3, _ = self.call_mcp_tool(\n \"testgen\",\n {\n \"step\": \"Identifying all edge cases and boundary conditions\",\n \"step_number\": 3,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"continuation_id\": continuation_id,\n \"findings\": \"Edge cases: empty batch, oversized batch, items without ID, cache hits/misses, concurrent processing, error accumulation\",\n \"files_checked\": [processor_file],\n \"relevant_files\": [processor_file],\n \"confidence\": \"high\",\n \"model\": \"flash\",\n },\n )\n\n if not response3:\n self.logger.error(\"Failed to continue to step 3\")\n return False\n\n self.logger.info(\" βœ… Step 3: Edge cases identified\")\n\n # Step 4: Final test plan with expert analysis\n self.logger.info(\" 1.6.4: Step 4 - Complete test plan\")\n response4, _ = self.call_mcp_tool(\n \"testgen\",\n {\n \"step\": \"Test planning complete with comprehensive coverage strategy\",\n \"step_number\": 4,\n \"total_steps\": 4,\n \"next_step_required\": False, # Final step\n \"continuation_id\": continuation_id,\n \"findings\": \"Complete async test suite plan: unit tests for each method, integration tests for batch processing, edge case coverage, performance tests\",\n \"files_checked\": [processor_file],\n \"relevant_files\": [processor_file],\n \"confidence\": \"high\",\n \"model\": \"flash\",\n },\n )\n\n if not response4:\n self.logger.error(\"Failed to complete to final step\")\n return False\n\n response4_data = self._parse_testgen_response(response4)\n\n # Validate final step\n if response4_data.get(\"status\") != \"calling_expert_analysis\":\n self.logger.error(\"Final step should trigger expert analysis\")\n return False\n\n file_context4 = response4_data.get(\"file_context\", {})\n if file_context4.get(\"type\") != \"fully_embedded\":\n self.logger.error(\"Final step should use fully_embedded file context\")\n return False\n\n self.logger.info(\" βœ… Multi-step test planning completed successfully\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Multi-step test planning test failed: {e}\")\n return False\n" }, { "path": "simulator_tests/test_thinkdeep_validation.py", "content": "#!/usr/bin/env python3\n\"\"\"\nThinkDeep Tool Validation Test\n\nTests the thinkdeep tool's capabilities using the new workflow architecture.\nThis validates that the workflow-based deep thinking implementation provides\nstep-by-step thinking with expert analysis integration.\n\"\"\"\n\nimport json\nfrom typing import Optional\n\nfrom .conversation_base_test import ConversationBaseTest\n\n\nclass ThinkDeepWorkflowValidationTest(ConversationBaseTest):\n \"\"\"Test thinkdeep tool with new workflow architecture\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"thinkdeep_validation\"\n\n @property\n def test_description(self) -> str:\n return \"ThinkDeep workflow tool validation with new workflow architecture\"\n\n def run_test(self) -> bool:\n \"\"\"Test thinkdeep tool capabilities\"\"\"\n # Set up the test environment\n self.setUp()\n\n try:\n self.logger.info(\"Test: ThinkDeepWorkflow tool validation (new architecture)\")\n\n # Create test files for thinking context\n self._create_thinking_context()\n\n # Test 1: Single thinking session with multiple steps\n if not self._test_single_thinking_session():\n return False\n\n # Test 2: Thinking flow that requires refocusing\n if not self._test_thinking_refocus_flow():\n return False\n\n # Test 3: Complete thinking with expert analysis\n if not self._test_complete_thinking_with_analysis():\n return False\n\n # Test 4: Certain confidence behavior\n if not self._test_certain_confidence():\n return False\n\n # Test 5: Context-aware file embedding\n if not self._test_context_aware_file_embedding():\n return False\n\n # Test 6: Multi-step file context optimization\n if not self._test_multi_step_file_context():\n return False\n\n self.logger.info(\" βœ… All thinkdeep validation tests passed\")\n return True\n\n except Exception as e:\n self.logger.error(f\"ThinkDeep validation test failed: {e}\")\n return False\n\n def _create_thinking_context(self):\n \"\"\"Create test files for deep thinking context\"\"\"\n # Create architecture document\n architecture_doc = \"\"\"# Microservices Architecture Design\n\n## Current System\n- Monolithic application with 500k LOC\n- Single PostgreSQL database\n- Peak load: 10k requests/minute\n- Team size: 25 developers\n- Deployment: Manual, 2-week cycles\n\n## Proposed Migration to Microservices\n\n### Benefits\n- Independent deployments\n- Technology diversity\n- Team autonomy\n- Scalability improvements\n\n### Challenges\n- Data consistency\n- Network latency\n- Operational complexity\n- Transaction management\n\n### Key Considerations\n- Service boundaries\n- Data migration strategy\n- Communication patterns\n- Monitoring and observability\n\"\"\"\n\n # Create requirements document\n requirements_doc = \"\"\"# Migration Requirements\n\n## Business Goals\n- Reduce deployment cycle from 2 weeks to daily\n- Support 50k requests/minute by Q4\n- Enable A/B testing capabilities\n- Improve system resilience\n\n## Technical Constraints\n- Zero downtime migration\n- Maintain data consistency\n- Budget: $200k for infrastructure\n- Timeline: 6 months\n- Existing team skills: Java, Spring Boot\n\n## Success Metrics\n- Deployment frequency: 10x improvement\n- System availability: 99.9%\n- Response time: <200ms p95\n- Developer productivity: 30% improvement\n\"\"\"\n\n # Create performance analysis\n performance_analysis = \"\"\"# Current Performance Analysis\n\n## Database Bottlenecks\n- Connection pool exhaustion during peak hours\n- Complex joins affecting query performance\n- Lock contention on user_sessions table\n- Read replica lag causing data inconsistency\n\n## Application Issues\n- Memory leaks in background processing\n- Thread pool starvation\n- Cache invalidation storms\n- Session clustering problems\n\n## Infrastructure Limits\n- Single server deployment\n- Manual scaling processes\n- Limited monitoring capabilities\n- No circuit breaker patterns\n\"\"\"\n\n # Create test files\n self.architecture_file = self.create_additional_test_file(\"architecture_design.md\", architecture_doc)\n self.requirements_file = self.create_additional_test_file(\"migration_requirements.md\", requirements_doc)\n self.performance_file = self.create_additional_test_file(\"performance_analysis.md\", performance_analysis)\n\n self.logger.info(\" βœ… Created thinking context files:\")\n self.logger.info(f\" - {self.architecture_file}\")\n self.logger.info(f\" - {self.requirements_file}\")\n self.logger.info(f\" - {self.performance_file}\")\n\n def _test_single_thinking_session(self) -> bool:\n \"\"\"Test a complete thinking session with multiple steps\"\"\"\n try:\n self.logger.info(\" 1.1: Testing single thinking session\")\n\n # Step 1: Start thinking analysis\n self.logger.info(\" 1.1.1: Step 1 - Initial thinking analysis\")\n response1, continuation_id = self.call_mcp_tool(\n \"thinkdeep\",\n {\n \"step\": \"I need to think deeply about the microservices migration strategy. Let me analyze the trade-offs, risks, and implementation approach systematically.\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Initial analysis shows significant architectural complexity but potential for major scalability and development velocity improvements. Need to carefully consider migration strategy and service boundaries.\",\n \"files_checked\": [self.architecture_file, self.requirements_file],\n \"relevant_files\": [self.architecture_file, self.requirements_file],\n \"relevant_context\": [\"microservices_migration\", \"service_boundaries\", \"data_consistency\"],\n \"confidence\": \"low\",\n \"problem_context\": \"Enterprise application migration from monolith to microservices\",\n \"focus_areas\": [\"architecture\", \"scalability\", \"risk_assessment\"],\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to get initial thinking response\")\n return False\n\n # Parse and validate JSON response\n response1_data = self._parse_thinkdeep_response(response1)\n if not response1_data:\n return False\n\n # Validate step 1 response structure - expect pause_for_thinkdeep for next_step_required=True\n if not self._validate_step_response(response1_data, 1, 4, True, \"pause_for_thinkdeep\"):\n return False\n\n self.logger.info(f\" βœ… Step 1 successful, continuation_id: {continuation_id}\")\n\n # Step 2: Deep analysis\n self.logger.info(\" 1.1.2: Step 2 - Deep analysis of alternatives\")\n response2, _ = self.call_mcp_tool(\n \"thinkdeep\",\n {\n \"step\": \"Analyzing different migration approaches: strangler fig pattern vs big bang vs gradual extraction. Each has different risk profiles and timelines.\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Strangler fig pattern emerges as best approach: lower risk, incremental value delivery, team learning curve management. Key insight: start with read-only services to minimize data consistency issues.\",\n \"files_checked\": [self.architecture_file, self.requirements_file, self.performance_file],\n \"relevant_files\": [self.architecture_file, self.performance_file],\n \"relevant_context\": [\"strangler_fig_pattern\", \"service_extraction\", \"risk_mitigation\"],\n \"issues_found\": [\n {\"severity\": \"high\", \"description\": \"Data consistency challenges during migration\"},\n {\"severity\": \"medium\", \"description\": \"Team skill gap in distributed systems\"},\n ],\n \"confidence\": \"medium\",\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue thinking to step 2\")\n return False\n\n response2_data = self._parse_thinkdeep_response(response2)\n if not self._validate_step_response(response2_data, 2, 4, True, \"pause_for_thinkdeep\"):\n return False\n\n # Check thinking status tracking\n thinking_status = response2_data.get(\"thinking_status\", {})\n if thinking_status.get(\"files_checked\", 0) < 3:\n self.logger.error(\"Files checked count not properly tracked\")\n return False\n\n if thinking_status.get(\"thinking_confidence\") != \"medium\":\n self.logger.error(\"Confidence level not properly tracked\")\n return False\n\n self.logger.info(\" βœ… Step 2 successful with proper tracking\")\n\n # Store continuation_id for next test\n self.thinking_continuation_id = continuation_id\n return True\n\n except Exception as e:\n self.logger.error(f\"Single thinking session test failed: {e}\")\n return False\n\n def _test_thinking_refocus_flow(self) -> bool:\n \"\"\"Test thinking workflow that shifts direction mid-analysis\"\"\"\n try:\n self.logger.info(\" 1.2: Testing thinking refocus workflow\")\n\n # Start a new thinking session for testing refocus behaviour\n self.logger.info(\" 1.2.1: Start thinking session for refocus test\")\n response1, continuation_id = self.call_mcp_tool(\n \"thinkdeep\",\n {\n \"step\": \"Thinking about optimal database architecture for the new microservices\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Initial thought: each service should have its own database for independence\",\n \"files_checked\": [self.architecture_file],\n \"relevant_files\": [self.architecture_file],\n \"relevant_context\": [\"database_per_service\", \"data_independence\"],\n \"confidence\": \"low\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start refocus test thinking\")\n return False\n\n # Step 2: Initial direction\n self.logger.info(\" 1.2.2: Step 2 - Initial analysis direction\")\n response2, _ = self.call_mcp_tool(\n \"thinkdeep\",\n {\n \"step\": \"Exploring database-per-service pattern implementation\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Database-per-service creates significant complexity for transactions and reporting\",\n \"files_checked\": [self.architecture_file, self.performance_file],\n \"relevant_files\": [self.performance_file],\n \"relevant_context\": [\"database_per_service\", \"transaction_management\"],\n \"issues_found\": [\n {\"severity\": \"high\", \"description\": \"Cross-service transactions become complex\"},\n {\"severity\": \"medium\", \"description\": \"Reporting queries span multiple databases\"},\n ],\n \"confidence\": \"low\",\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue to step 2\")\n return False\n\n # Step 3: Backtrack and revise approach\n self.logger.info(\" 1.2.3: Step 3 - Backtrack and revise thinking\")\n response3, _ = self.call_mcp_tool(\n \"thinkdeep\",\n {\n \"step\": \"Refocusing - maybe shared database with service-specific schemas is better initially. Then gradually extract databases as services mature.\",\n \"step_number\": 3,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Hybrid approach: shared database with bounded contexts, then gradual extraction. This reduces initial complexity while preserving migration path to full service independence.\",\n \"files_checked\": [self.architecture_file, self.requirements_file],\n \"relevant_files\": [self.architecture_file, self.requirements_file],\n \"relevant_context\": [\"shared_database\", \"bounded_contexts\", \"gradual_extraction\"],\n \"confidence\": \"medium\",\n \"continuation_id\": continuation_id,\n },\n )\n\n if not response3:\n self.logger.error(\"Failed to refocus\")\n return False\n\n response3_data = self._parse_thinkdeep_response(response3)\n if not self._validate_step_response(response3_data, 3, 4, True, \"pause_for_thinkdeep\"):\n return False\n\n self.logger.info(\" βœ… Refocus working correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Refocus test failed: {e}\")\n return False\n\n def _test_complete_thinking_with_analysis(self) -> bool:\n \"\"\"Test complete thinking ending with expert analysis\"\"\"\n try:\n self.logger.info(\" 1.3: Testing complete thinking with expert analysis\")\n\n # Use the continuation from first test\n continuation_id = getattr(self, \"thinking_continuation_id\", None)\n if not continuation_id:\n # Start fresh if no continuation available\n self.logger.info(\" 1.3.0: Starting fresh thinking session\")\n response0, continuation_id = self.call_mcp_tool(\n \"thinkdeep\",\n {\n \"step\": \"Thinking about the complete microservices migration strategy\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"findings\": \"Comprehensive analysis of migration approaches and risks\",\n \"files_checked\": [self.architecture_file, self.requirements_file],\n \"relevant_files\": [self.architecture_file, self.requirements_file],\n \"relevant_context\": [\"migration_strategy\", \"risk_assessment\"],\n },\n )\n if not response0 or not continuation_id:\n self.logger.error(\"Failed to start fresh thinking session\")\n return False\n\n # Final step - trigger expert analysis\n self.logger.info(\" 1.3.1: Final step - complete thinking analysis\")\n response_final, _ = self.call_mcp_tool(\n \"thinkdeep\",\n {\n \"step\": \"Thinking analysis complete. I've thoroughly considered the migration strategy, risks, and implementation approach.\",\n \"step_number\": 2,\n \"total_steps\": 2,\n \"next_step_required\": False, # Final step - triggers expert analysis\n \"findings\": \"Comprehensive migration strategy: strangler fig pattern with shared database initially, gradual service extraction based on business value and technical feasibility. Key success factors: team training, monitoring infrastructure, and incremental rollout.\",\n \"files_checked\": [self.architecture_file, self.requirements_file, self.performance_file],\n \"relevant_files\": [self.architecture_file, self.requirements_file, self.performance_file],\n \"relevant_context\": [\"strangler_fig\", \"migration_strategy\", \"risk_mitigation\", \"team_readiness\"],\n \"issues_found\": [\n {\"severity\": \"medium\", \"description\": \"Team needs distributed systems training\"},\n {\"severity\": \"low\", \"description\": \"Monitoring tools need upgrade\"},\n ],\n \"confidence\": \"high\",\n \"continuation_id\": continuation_id,\n \"model\": \"flash\", # Use flash for expert analysis\n },\n )\n\n if not response_final:\n self.logger.error(\"Failed to complete thinking\")\n return False\n\n response_final_data = self._parse_thinkdeep_response(response_final)\n if not response_final_data:\n return False\n\n # Validate final response structure - accept both expert analysis and special statuses\n valid_final_statuses = [\"calling_expert_analysis\", \"files_required_to_continue\"]\n if response_final_data.get(\"status\") not in valid_final_statuses:\n self.logger.error(\n f\"Expected status in {valid_final_statuses}, got '{response_final_data.get('status')}'\"\n )\n return False\n\n if not response_final_data.get(\"thinking_complete\"):\n self.logger.error(\"Expected thinking_complete=true for final step\")\n return False\n\n # Check for expert analysis or special status content\n if response_final_data.get(\"status\") == \"calling_expert_analysis\":\n if \"expert_analysis\" not in response_final_data:\n self.logger.error(\"Missing expert_analysis in final response\")\n return False\n expert_analysis = response_final_data.get(\"expert_analysis\", {})\n else:\n # For special statuses like files_required_to_continue, analysis may be in content\n expert_analysis = response_final_data.get(\"content\", \"{}\")\n if isinstance(expert_analysis, str):\n try:\n expert_analysis = json.loads(expert_analysis)\n except (json.JSONDecodeError, TypeError):\n expert_analysis = {\"analysis\": expert_analysis}\n\n # Check for expected analysis content (checking common patterns)\n analysis_text = json.dumps(expert_analysis, ensure_ascii=False).lower()\n\n # Look for thinking analysis validation\n thinking_indicators = [\"migration\", \"strategy\", \"microservices\", \"risk\", \"approach\", \"implementation\"]\n found_indicators = sum(1 for indicator in thinking_indicators if indicator in analysis_text)\n\n if found_indicators >= 3:\n self.logger.info(\" βœ… Expert analysis validated the thinking correctly\")\n else:\n self.logger.warning(\n f\" ⚠️ Expert analysis may not have fully validated the thinking (found {found_indicators}/6 indicators)\"\n )\n\n # Check complete thinking summary\n if \"complete_thinking\" not in response_final_data:\n self.logger.error(\"Missing complete_thinking in final response\")\n return False\n\n complete_thinking = response_final_data[\"complete_thinking\"]\n if not complete_thinking.get(\"relevant_context\"):\n self.logger.error(\"Missing relevant context in complete thinking\")\n return False\n\n if \"migration_strategy\" not in complete_thinking[\"relevant_context\"]:\n self.logger.error(\"Expected context not found in thinking summary\")\n return False\n\n self.logger.info(\" βœ… Complete thinking with expert analysis successful\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Complete thinking test failed: {e}\")\n return False\n\n def _test_certain_confidence(self) -> bool:\n \"\"\"Test certain confidence behavior - should skip expert analysis\"\"\"\n try:\n self.logger.info(\" 1.4: Testing certain confidence behavior\")\n\n # Test certain confidence - should skip expert analysis\n self.logger.info(\" 1.4.1: Certain confidence thinking\")\n response_certain, _ = self.call_mcp_tool(\n \"thinkdeep\",\n {\n \"step\": \"I have thoroughly analyzed all aspects of the migration strategy with complete certainty.\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False, # Final step\n \"findings\": \"Definitive conclusion: strangler fig pattern with phased database extraction is the optimal approach. Risk mitigation through team training and robust monitoring. Timeline: 6 months with monthly service extractions.\",\n \"files_checked\": [self.architecture_file, self.requirements_file, self.performance_file],\n \"relevant_files\": [self.architecture_file, self.requirements_file],\n \"relevant_context\": [\"migration_complete_strategy\", \"implementation_plan\"],\n \"confidence\": \"certain\", # This should skip expert analysis\n \"model\": \"flash\",\n },\n )\n\n if not response_certain:\n self.logger.error(\"Failed to test certain confidence\")\n return False\n\n response_certain_data = self._parse_thinkdeep_response(response_certain)\n if not response_certain_data:\n return False\n\n # Validate certain confidence response - should skip expert analysis\n if response_certain_data.get(\"status\") != \"deep_thinking_complete_ready_for_implementation\":\n self.logger.error(\n f\"Expected status 'deep_thinking_complete_ready_for_implementation', got '{response_certain_data.get('status')}'\"\n )\n return False\n\n if not response_certain_data.get(\"skip_expert_analysis\"):\n self.logger.error(\"Expected skip_expert_analysis=true for certain confidence\")\n return False\n\n expert_analysis = response_certain_data.get(\"expert_analysis\", {})\n if expert_analysis.get(\"status\") != \"skipped_due_to_certain_thinking_confidence\":\n self.logger.error(\"Expert analysis should be skipped for certain confidence\")\n return False\n\n self.logger.info(\" βœ… Certain confidence behavior working correctly\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Certain confidence test failed: {e}\")\n return False\n\n def call_mcp_tool(self, tool_name: str, params: dict) -> tuple[Optional[str], Optional[str]]:\n \"\"\"Call an MCP tool in-process - override for thinkdeep-specific response handling\"\"\"\n # Use in-process implementation to maintain conversation memory\n response_text, _ = self.call_mcp_tool_direct(tool_name, params)\n\n if not response_text:\n return None, None\n\n # Extract continuation_id from thinkdeep response specifically\n continuation_id = self._extract_thinkdeep_continuation_id(response_text)\n\n return response_text, continuation_id\n\n def _extract_thinkdeep_continuation_id(self, response_text: str) -> Optional[str]:\n \"\"\"Extract continuation_id from thinkdeep response\"\"\"\n try:\n # Parse the response\n response_data = json.loads(response_text)\n return response_data.get(\"continuation_id\")\n\n except json.JSONDecodeError as e:\n self.logger.debug(f\"Failed to parse response for thinkdeep continuation_id: {e}\")\n return None\n\n def _parse_thinkdeep_response(self, response_text: str) -> dict:\n \"\"\"Parse thinkdeep tool JSON response\"\"\"\n try:\n # Parse the response - it should be direct JSON\n return json.loads(response_text)\n\n except json.JSONDecodeError as e:\n self.logger.error(f\"Failed to parse thinkdeep response as JSON: {e}\")\n self.logger.error(f\"Response text: {response_text[:500]}...\")\n return {}\n\n def _validate_step_response(\n self,\n response_data: dict,\n expected_step: int,\n expected_total: int,\n expected_next_required: bool,\n expected_status: str,\n ) -> bool:\n \"\"\"Validate a thinkdeep thinking step response structure\"\"\"\n try:\n # Check status\n if response_data.get(\"status\") != expected_status:\n self.logger.error(f\"Expected status '{expected_status}', got '{response_data.get('status')}'\")\n return False\n\n # Check step number\n if response_data.get(\"step_number\") != expected_step:\n self.logger.error(f\"Expected step_number {expected_step}, got {response_data.get('step_number')}\")\n return False\n\n # Check total steps\n if response_data.get(\"total_steps\") != expected_total:\n self.logger.error(f\"Expected total_steps {expected_total}, got {response_data.get('total_steps')}\")\n return False\n\n # Check next_step_required\n if response_data.get(\"next_step_required\") != expected_next_required:\n self.logger.error(\n f\"Expected next_step_required {expected_next_required}, got {response_data.get('next_step_required')}\"\n )\n return False\n\n # Check thinking_status exists\n if \"thinking_status\" not in response_data:\n self.logger.error(\"Missing thinking_status in response\")\n return False\n\n # Check next_steps guidance\n if not response_data.get(\"next_steps\"):\n self.logger.error(\"Missing next_steps guidance in response\")\n return False\n\n return True\n\n except Exception as e:\n self.logger.error(f\"Error validating step response: {e}\")\n return False\n\n def _test_context_aware_file_embedding(self) -> bool:\n \"\"\"Test context-aware file embedding optimization\"\"\"\n try:\n self.logger.info(\" 1.5: Testing context-aware file embedding\")\n\n # Create additional test files for context testing\n strategy_doc = \"\"\"# Implementation Strategy\n\n## Phase 1: Foundation (Month 1-2)\n- Set up monitoring and logging infrastructure\n- Establish CI/CD pipelines for microservices\n- Team training on distributed systems concepts\n\n## Phase 2: Initial Services (Month 3-4)\n- Extract read-only services (user profiles, product catalog)\n- Implement API gateway\n- Set up service discovery\n\n## Phase 3: Core Services (Month 5-6)\n- Extract transaction services\n- Implement saga patterns for distributed transactions\n- Performance optimization and monitoring\n\"\"\"\n\n tech_stack_doc = \"\"\"# Technology Stack Decisions\n\n## Service Framework\n- Spring Boot 2.7 (team familiarity)\n- Docker containers\n- Kubernetes orchestration\n\n## Communication\n- REST APIs for synchronous communication\n- Apache Kafka for asynchronous messaging\n- gRPC for high-performance internal communication\n\n## Data Layer\n- PostgreSQL (existing expertise)\n- Redis for caching\n- Elasticsearch for search and analytics\n\n## Monitoring\n- Prometheus + Grafana\n- Distributed tracing with Jaeger\n- Centralized logging with ELK stack\n\"\"\"\n\n # Create test files\n strategy_file = self.create_additional_test_file(\"implementation_strategy.md\", strategy_doc)\n tech_stack_file = self.create_additional_test_file(\"tech_stack.md\", tech_stack_doc)\n\n # Test 1: New conversation, intermediate step - should only reference files\n self.logger.info(\" 1.5.1: New conversation intermediate step (should reference only)\")\n response1, continuation_id = self.call_mcp_tool(\n \"thinkdeep\",\n {\n \"step\": \"Starting deep thinking about implementation timeline and technology choices\",\n \"step_number\": 1,\n \"total_steps\": 3,\n \"next_step_required\": True, # Intermediate step\n \"findings\": \"Initial analysis of implementation strategy and technology stack decisions\",\n \"files_checked\": [strategy_file, tech_stack_file],\n \"relevant_files\": [strategy_file], # This should be referenced, not embedded\n \"relevant_context\": [\"implementation_timeline\", \"technology_selection\"],\n \"confidence\": \"low\",\n \"model\": \"flash\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start context-aware file embedding test\")\n return False\n\n response1_data = self._parse_thinkdeep_response(response1)\n if not response1_data:\n return False\n\n # Check file context - should be reference_only for intermediate step\n file_context = response1_data.get(\"file_context\", {})\n if file_context.get(\"type\") != \"reference_only\":\n self.logger.error(f\"Expected reference_only file context, got: {file_context.get('type')}\")\n return False\n\n if \"Files referenced but not embedded\" not in file_context.get(\"context_optimization\", \"\"):\n self.logger.error(\"Expected context optimization message for reference_only\")\n return False\n\n self.logger.info(\" βœ… Intermediate step correctly uses reference_only file context\")\n\n # Test 2: Final step - should embed files for expert analysis\n self.logger.info(\" 1.5.2: Final step (should embed files)\")\n response2, _ = self.call_mcp_tool(\n \"thinkdeep\",\n {\n \"step\": \"Thinking analysis complete - comprehensive evaluation of implementation approach\",\n \"step_number\": 2,\n \"total_steps\": 2,\n \"next_step_required\": False, # Final step - should embed files\n \"continuation_id\": continuation_id,\n \"findings\": \"Complete analysis: phased implementation with proven technology stack minimizes risk while maximizing team effectiveness. Timeline is realistic with proper training and infrastructure setup.\",\n \"files_checked\": [strategy_file, tech_stack_file],\n \"relevant_files\": [strategy_file, tech_stack_file], # Should be fully embedded\n \"relevant_context\": [\"implementation_plan\", \"technology_decisions\", \"risk_management\"],\n \"confidence\": \"high\",\n \"model\": \"flash\",\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to complete to final step\")\n return False\n\n response2_data = self._parse_thinkdeep_response(response2)\n if not response2_data:\n return False\n\n # Check file context - should be fully_embedded for final step\n file_context2 = response2_data.get(\"file_context\", {})\n if file_context2.get(\"type\") != \"fully_embedded\":\n self.logger.error(\n f\"Expected fully_embedded file context for final step, got: {file_context2.get('type')}\"\n )\n return False\n\n if \"Full file content embedded for expert analysis\" not in file_context2.get(\"context_optimization\", \"\"):\n self.logger.error(\"Expected expert analysis optimization message for fully_embedded\")\n return False\n\n self.logger.info(\" βœ… Final step correctly uses fully_embedded file context\")\n\n # Verify expert analysis was called for final step\n if response2_data.get(\"status\") != \"calling_expert_analysis\":\n self.logger.error(\"Final step should trigger expert analysis\")\n return False\n\n if \"expert_analysis\" not in response2_data:\n self.logger.error(\"Expert analysis should be present in final step\")\n return False\n\n self.logger.info(\" βœ… Context-aware file embedding test completed successfully\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Context-aware file embedding test failed: {e}\")\n return False\n\n def _test_multi_step_file_context(self) -> bool:\n \"\"\"Test multi-step workflow with proper file context transitions\"\"\"\n try:\n self.logger.info(\" 1.6: Testing multi-step file context optimization\")\n\n # Create a complex scenario with multiple thinking documents\n risk_analysis = \"\"\"# Risk Analysis\n\n## Technical Risks\n- Service mesh complexity\n- Data consistency challenges\n- Performance degradation during migration\n- Operational overhead increase\n\n## Business Risks\n- Extended development timelines\n- Potential system instability\n- Team productivity impact\n- Customer experience disruption\n\n## Mitigation Strategies\n- Gradual rollout with feature flags\n- Comprehensive monitoring and alerting\n- Rollback procedures for each phase\n- Customer communication plan\n\"\"\"\n\n success_metrics = \"\"\"# Success Metrics and KPIs\n\n## Development Velocity\n- Deployment frequency: Target 10x improvement\n- Lead time for changes: <2 hours\n- Mean time to recovery: <30 minutes\n- Change failure rate: <5%\n\n## System Performance\n- Response time: <200ms p95\n- System availability: 99.9%\n- Throughput: 50k requests/minute\n- Resource utilization: 70% optimal\n\n## Business Impact\n- Developer satisfaction: >8/10\n- Time to market: 50% reduction\n- Operational costs: 20% reduction\n- System reliability: 99.9% uptime\n\"\"\"\n\n # Create test files\n risk_file = self.create_additional_test_file(\"risk_analysis.md\", risk_analysis)\n metrics_file = self.create_additional_test_file(\"success_metrics.md\", success_metrics)\n\n # Step 1: Start thinking analysis (new conversation)\n self.logger.info(\" 1.6.1: Step 1 - Start thinking analysis\")\n response1, continuation_id = self.call_mcp_tool(\n \"thinkdeep\",\n {\n \"step\": \"Beginning comprehensive analysis of migration risks and success criteria\",\n \"step_number\": 1,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"findings\": \"Initial assessment of risk factors and success metrics for microservices migration\",\n \"files_checked\": [risk_file],\n \"relevant_files\": [risk_file],\n \"relevant_context\": [\"risk_assessment\", \"migration_planning\"],\n \"confidence\": \"low\",\n \"model\": \"flash\",\n },\n )\n\n if not response1 or not continuation_id:\n self.logger.error(\"Failed to start multi-step file context test\")\n return False\n\n response1_data = self._parse_thinkdeep_response(response1)\n\n # Validate step 1 - should use reference_only\n file_context1 = response1_data.get(\"file_context\", {})\n if file_context1.get(\"type\") != \"reference_only\":\n self.logger.error(\"Step 1 should use reference_only file context\")\n return False\n\n self.logger.info(\" βœ… Step 1: reference_only file context\")\n\n # Step 2: Expand thinking analysis\n self.logger.info(\" 1.6.2: Step 2 - Expand thinking analysis\")\n response2, _ = self.call_mcp_tool(\n \"thinkdeep\",\n {\n \"step\": \"Deepening analysis by correlating risks with success metrics\",\n \"step_number\": 2,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"continuation_id\": continuation_id,\n \"findings\": \"Key insight: technical risks directly impact business metrics. Need balanced approach prioritizing high-impact, low-risk improvements first.\",\n \"files_checked\": [risk_file, metrics_file],\n \"relevant_files\": [risk_file, metrics_file],\n \"relevant_context\": [\"risk_metric_correlation\", \"priority_matrix\"],\n \"confidence\": \"medium\",\n \"model\": \"flash\",\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to continue to step 2\")\n return False\n\n response2_data = self._parse_thinkdeep_response(response2)\n\n # Validate step 2 - should still use reference_only\n file_context2 = response2_data.get(\"file_context\", {})\n if file_context2.get(\"type\") != \"reference_only\":\n self.logger.error(\"Step 2 should use reference_only file context\")\n return False\n\n self.logger.info(\" βœ… Step 2: reference_only file context with multiple files\")\n\n # Step 3: Deep analysis\n self.logger.info(\" 1.6.3: Step 3 - Deep strategic analysis\")\n response3, _ = self.call_mcp_tool(\n \"thinkdeep\",\n {\n \"step\": \"Synthesizing risk mitigation strategies with measurable success criteria\",\n \"step_number\": 3,\n \"total_steps\": 4,\n \"next_step_required\": True,\n \"continuation_id\": continuation_id,\n \"findings\": \"Strategic framework emerging: phase-gate approach with clear go/no-go criteria at each milestone. Emphasis on early wins to build confidence and momentum.\",\n \"files_checked\": [risk_file, metrics_file, self.requirements_file],\n \"relevant_files\": [risk_file, metrics_file, self.requirements_file],\n \"relevant_context\": [\"phase_gate_approach\", \"milestone_criteria\", \"early_wins\"],\n \"confidence\": \"high\",\n \"model\": \"flash\",\n },\n )\n\n if not response3:\n self.logger.error(\"Failed to continue to step 3\")\n return False\n\n response3_data = self._parse_thinkdeep_response(response3)\n\n # Validate step 3 - should still use reference_only\n file_context3 = response3_data.get(\"file_context\", {})\n if file_context3.get(\"type\") != \"reference_only\":\n self.logger.error(\"Step 3 should use reference_only file context\")\n return False\n\n self.logger.info(\" βœ… Step 3: reference_only file context\")\n\n # Step 4: Final analysis with expert consultation\n self.logger.info(\" 1.6.4: Step 4 - Final step with expert analysis\")\n response4, _ = self.call_mcp_tool(\n \"thinkdeep\",\n {\n \"step\": \"Thinking analysis complete - comprehensive strategic framework developed\",\n \"step_number\": 4,\n \"total_steps\": 4,\n \"next_step_required\": False, # Final step - should embed files\n \"continuation_id\": continuation_id,\n \"findings\": \"Complete strategic framework: risk-balanced migration with measurable success criteria, phase-gate governance, and clear rollback procedures. Framework aligns technical execution with business objectives.\",\n \"files_checked\": [risk_file, metrics_file, self.requirements_file, self.architecture_file],\n \"relevant_files\": [risk_file, metrics_file, self.requirements_file, self.architecture_file],\n \"relevant_context\": [\"strategic_framework\", \"governance_model\", \"success_measurement\"],\n \"confidence\": \"high\",\n \"model\": \"flash\",\n },\n )\n\n if not response4:\n self.logger.error(\"Failed to complete to final step\")\n return False\n\n response4_data = self._parse_thinkdeep_response(response4)\n\n # Validate step 4 - should use fully_embedded for expert analysis\n file_context4 = response4_data.get(\"file_context\", {})\n if file_context4.get(\"type\") != \"fully_embedded\":\n self.logger.error(\"Step 4 (final) should use fully_embedded file context\")\n return False\n\n if \"expert analysis\" not in file_context4.get(\"context_optimization\", \"\").lower():\n self.logger.error(\"Final step should mention expert analysis in context optimization\")\n return False\n\n # Verify expert analysis was triggered\n if response4_data.get(\"status\") != \"calling_expert_analysis\":\n self.logger.error(\"Final step should trigger expert analysis\")\n return False\n\n # Check that expert analysis has file context\n expert_analysis = response4_data.get(\"expert_analysis\", {})\n if not expert_analysis:\n self.logger.error(\"Expert analysis should be present in final step\")\n return False\n\n self.logger.info(\" βœ… Step 4: fully_embedded file context with expert analysis\")\n\n # Validate the complete workflow progression\n progression_summary = {\n \"step_1\": \"reference_only (new conversation, intermediate)\",\n \"step_2\": \"reference_only (continuation, intermediate)\",\n \"step_3\": \"reference_only (continuation, intermediate)\",\n \"step_4\": \"fully_embedded (continuation, final)\",\n }\n\n self.logger.info(\" πŸ“‹ File context progression:\")\n for step, context_type in progression_summary.items():\n self.logger.info(f\" {step}: {context_type}\")\n\n self.logger.info(\" βœ… Multi-step file context optimization test completed successfully\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Multi-step file context test failed: {e}\")\n return False\n" }, { "path": "simulator_tests/test_token_allocation_validation.py", "content": "#!/usr/bin/env python3\n\"\"\"\nToken Allocation and Conversation History Validation Test\n\nThis test validates that:\n1. Token allocation logging works correctly for file processing\n2. Conversation history builds up properly and consumes tokens\n3. File deduplication works correctly across tool calls\n4. Token usage increases appropriately as conversation history grows\n\"\"\"\n\nimport datetime\n\nfrom .conversation_base_test import ConversationBaseTest\n\n\nclass TokenAllocationValidationTest(ConversationBaseTest):\n \"\"\"Test token allocation and conversation history functionality\"\"\"\n\n def call_mcp_tool(self, tool_name: str, params: dict) -> tuple:\n \"\"\"Call an MCP tool in-process\"\"\"\n response_text, continuation_id = self.call_mcp_tool_direct(tool_name, params)\n return response_text, continuation_id\n\n @property\n def test_name(self) -> str:\n return \"token_allocation_validation\"\n\n @property\n def test_description(self) -> str:\n return \"Token allocation and conversation history validation\"\n\n def run_test(self) -> bool:\n \"\"\"Test token allocation and conversation history functionality\"\"\"\n try:\n self.logger.info(\" Test: Token allocation and conversation history validation\")\n\n # Initialize for in-process tool calling\n self.setUp()\n\n # Setup test files\n self.setup_test_files()\n\n # Create additional test files for this test - make them substantial enough to see token differences\n file1_content = \"\"\"def fibonacci(n):\n '''Calculate fibonacci number recursively\n\n This is a classic recursive algorithm that demonstrates\n the exponential time complexity of naive recursion.\n For large values of n, this becomes very slow.\n\n Time complexity: O(2^n)\n Space complexity: O(n) due to call stack\n '''\n if n <= 1:\n return n\n return fibonacci(n-1) + fibonacci(n-2)\n\ndef factorial(n):\n '''Calculate factorial using recursion\n\n More efficient than fibonacci as each value\n is calculated only once.\n\n Time complexity: O(n)\n Space complexity: O(n) due to call stack\n '''\n if n <= 1:\n return 1\n return n * factorial(n-1)\n\ndef gcd(a, b):\n '''Calculate greatest common divisor using Euclidean algorithm'''\n while b:\n a, b = b, a % b\n return a\n\ndef lcm(a, b):\n '''Calculate least common multiple'''\n return abs(a * b) // gcd(a, b)\n\n# Test functions with detailed output\nif __name__ == \"__main__\":\n print(\"=== Mathematical Functions Demo ===\")\n print(f\"Fibonacci(10) = {fibonacci(10)}\")\n print(f\"Factorial(5) = {factorial(5)}\")\n print(f\"GCD(48, 18) = {gcd(48, 18)}\")\n print(f\"LCM(48, 18) = {lcm(48, 18)}\")\n print(\"Fibonacci sequence (first 10 numbers):\")\n for i in range(10):\n print(f\" F({i}) = {fibonacci(i)}\")\n\"\"\"\n\n file2_content = \"\"\"class Calculator:\n '''Advanced calculator class with error handling and logging'''\n\n def __init__(self):\n self.history = []\n self.last_result = 0\n\n def add(self, a, b):\n '''Addition with history tracking'''\n result = a + b\n operation = f\"{a} + {b} = {result}\"\n self.history.append(operation)\n self.last_result = result\n return result\n\n def multiply(self, a, b):\n '''Multiplication with history tracking'''\n result = a * b\n operation = f\"{a} * {b} = {result}\"\n self.history.append(operation)\n self.last_result = result\n return result\n\n def divide(self, a, b):\n '''Division with error handling and history tracking'''\n if b == 0:\n error_msg = f\"Division by zero error: {a} / {b}\"\n self.history.append(error_msg)\n raise ValueError(\"Cannot divide by zero\")\n\n result = a / b\n operation = f\"{a} / {b} = {result}\"\n self.history.append(operation)\n self.last_result = result\n return result\n\n def power(self, base, exponent):\n '''Exponentiation with history tracking'''\n result = base ** exponent\n operation = f\"{base} ^ {exponent} = {result}\"\n self.history.append(operation)\n self.last_result = result\n return result\n\n def get_history(self):\n '''Return calculation history'''\n return self.history.copy()\n\n def clear_history(self):\n '''Clear calculation history'''\n self.history.clear()\n self.last_result = 0\n\n# Demo usage\nif __name__ == \"__main__\":\n calc = Calculator()\n print(\"=== Calculator Demo ===\")\n\n # Perform various calculations\n print(f\"Addition: {calc.add(10, 20)}\")\n print(f\"Multiplication: {calc.multiply(5, 8)}\")\n print(f\"Division: {calc.divide(100, 4)}\")\n print(f\"Power: {calc.power(2, 8)}\")\n\n print(\"\\\\nCalculation History:\")\n for operation in calc.get_history():\n print(f\" {operation}\")\n\n print(f\"\\\\nLast result: {calc.last_result}\")\n\"\"\"\n\n # Create test files\n file1_path = self.create_additional_test_file(\"math_functions.py\", file1_content)\n file2_path = self.create_additional_test_file(\"calculator.py\", file2_content)\n\n # Track continuation IDs to validate each step generates new ones\n continuation_ids = []\n\n # Step 1: Initial chat with first file\n self.logger.info(\" Step 1: Initial chat with file1 - checking token allocation\")\n\n datetime.datetime.now()\n\n response1, continuation_id1 = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Please analyze this math functions file and explain what it does.\",\n \"absolute_file_paths\": [file1_path],\n \"model\": \"flash\",\n \"temperature\": 0.7,\n },\n )\n\n if not response1 or not continuation_id1:\n self.logger.error(\" ❌ Step 1 failed - no response or continuation ID\")\n return False\n\n self.logger.info(f\" βœ… Step 1 completed with continuation_id: {continuation_id1[:8]}...\")\n continuation_ids.append(continuation_id1)\n\n # Validate that Step 1 succeeded and returned proper content\n if \"fibonacci\" not in response1.lower() or \"factorial\" not in response1.lower():\n self.logger.error(\" ❌ Step 1: Response doesn't contain expected function analysis\")\n return False\n\n self.logger.info(\" βœ… Step 1: File was successfully analyzed\")\n\n # Step 2: Different tool continuing same conversation - should build conversation history\n self.logger.info(\n \" Step 2: Analyze tool continuing chat conversation - checking conversation history buildup\"\n )\n\n response2, continuation_id2 = self.call_mcp_tool(\n \"analyze\",\n {\n \"step\": \"Analyze the performance implications of these recursive functions.\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Continuing from chat conversation to analyze performance implications of recursive functions.\",\n \"relevant_files\": [file1_path],\n \"continuation_id\": continuation_id1, # Continue the chat conversation\n \"model\": \"flash\",\n },\n )\n\n if not response2 or not continuation_id2:\n self.logger.error(\" ❌ Step 2 failed - no response or continuation ID\")\n return False\n\n self.logger.info(f\" βœ… Step 2 completed with continuation_id: {continuation_id2[:8]}...\")\n continuation_ids.append(continuation_id2)\n\n # Validate continuation ID behavior for workflow tools\n # Workflow tools reuse the same continuation_id when continuing within a workflow session\n # This is expected behavior and different from simple tools\n if continuation_id2 != continuation_id1:\n self.logger.info(\" βœ… Step 2: Got new continuation ID (workflow behavior)\")\n else:\n self.logger.info(\" βœ… Step 2: Reused continuation ID (workflow session continuation)\")\n # Both behaviors are valid - what matters is that we got a continuation_id\n\n # Validate that Step 2 is building on Step 1's conversation\n # Check if the response references the previous conversation\n if \"performance\" not in response2.lower() and \"recursive\" not in response2.lower():\n self.logger.error(\" ❌ Step 2: Response doesn't contain expected performance analysis\")\n return False\n\n self.logger.info(\" βœ… Step 2: Successfully continued conversation with performance analysis\")\n\n # Step 3: Continue conversation with additional file - should show increased token usage\n self.logger.info(\" Step 3: Continue conversation with file1 + file2 - checking token growth\")\n\n response3, continuation_id3 = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Now compare the math functions with this calculator class. How do they differ in approach?\",\n \"absolute_file_paths\": [file1_path, file2_path],\n \"continuation_id\": continuation_id2, # Continue the conversation from step 2\n \"model\": \"flash\",\n \"temperature\": 0.7,\n },\n )\n\n if not response3 or not continuation_id3:\n self.logger.error(\" ❌ Step 3 failed - no response or continuation ID\")\n return False\n\n self.logger.info(f\" βœ… Step 3 completed with continuation_id: {continuation_id3[:8]}...\")\n continuation_ids.append(continuation_id3)\n\n # Validate that Step 3 references both previous steps and compares the files\n if \"calculator\" not in response3.lower() or \"math\" not in response3.lower():\n self.logger.error(\" ❌ Step 3: Response doesn't contain expected comparison between files\")\n return False\n\n self.logger.info(\" βœ… Step 3: Successfully compared both files in continued conversation\")\n\n # Validation: Check that conversation continuation worked properly\n self.logger.info(\" πŸ“‹ Validating conversation continuation...\")\n\n # Validation criteria\n criteria = []\n\n # 1. All steps returned valid responses\n all_responses_valid = bool(response1 and response2 and response3)\n criteria.append((\"All steps returned valid responses\", all_responses_valid))\n\n # 2. All steps generated continuation IDs\n all_have_continuation_ids = bool(continuation_id1 and continuation_id2 and continuation_id3)\n criteria.append((\"All steps generated continuation IDs\", all_have_continuation_ids))\n\n # 3. Continuation behavior validation (handles both simple and workflow tools)\n # Simple tools create new IDs each time, workflow tools may reuse IDs within sessions\n has_valid_continuation_pattern = len(continuation_ids) == 3\n criteria.append((\"Valid continuation ID pattern\", has_valid_continuation_pattern))\n\n # 4. Check for conversation continuity (more important than ID uniqueness)\n conversation_has_continuity = len(continuation_ids) == 3 and all(\n cid is not None for cid in continuation_ids\n )\n criteria.append((\"Conversation continuity maintained\", conversation_has_continuity))\n\n # 5. Check responses build on each other (content validation)\n step1_has_function_analysis = \"fibonacci\" in response1.lower() or \"factorial\" in response1.lower()\n step2_has_performance_analysis = \"performance\" in response2.lower() or \"recursive\" in response2.lower()\n step3_has_comparison = \"calculator\" in response3.lower() and \"math\" in response3.lower()\n\n criteria.append((\"Step 1 analyzed the math functions\", step1_has_function_analysis))\n criteria.append((\"Step 2 discussed performance implications\", step2_has_performance_analysis))\n criteria.append((\"Step 3 compared both files\", step3_has_comparison))\n\n # Log continuation ID analysis\n self.logger.info(\" Continuation ID Analysis:\")\n self.logger.info(f\" Step 1 ID: {continuation_ids[0][:8]}... (new conversation)\")\n self.logger.info(f\" Step 2 ID: {continuation_ids[1][:8]}... (continued from Step 1)\")\n self.logger.info(f\" Step 3 ID: {continuation_ids[2][:8]}... (continued from Step 2)\")\n\n # Check validation criteria\n passed_criteria = sum(1 for _, passed in criteria if passed)\n total_criteria = len(criteria)\n\n self.logger.info(f\" Validation criteria: {passed_criteria}/{total_criteria}\")\n for criterion, passed in criteria:\n status = \"βœ…\" if passed else \"❌\"\n self.logger.info(f\" {status} {criterion}\")\n\n # Success criteria: All validation criteria must pass\n success = passed_criteria == total_criteria\n\n if success:\n self.logger.info(\" βœ… Token allocation validation test PASSED\")\n return True\n else:\n self.logger.error(\" ❌ Token allocation validation test FAILED\")\n return False\n\n except Exception as e:\n self.logger.error(f\"Token allocation validation test failed: {e}\")\n return False\n finally:\n self.cleanup_test_files()\n\n\ndef main():\n \"\"\"Run the token allocation validation test\"\"\"\n import sys\n\n verbose = \"--verbose\" in sys.argv or \"-v\" in sys.argv\n test = TokenAllocationValidationTest(verbose=verbose)\n\n success = test.run_test()\n sys.exit(0 if success else 1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "simulator_tests/test_vision_capability.py", "content": "#!/usr/bin/env python3\n\"\"\"\nVision Capability Test\n\nTests vision capability with the chat tool using O3 model:\n- Test file path image (PNG triangle)\n- Test base64 data URL image\n- Use chat tool with O3 model to analyze the images\n- Verify the model correctly identifies shapes\n\"\"\"\n\nimport base64\nimport os\n\nfrom .base_test import BaseSimulatorTest\n\n\nclass VisionCapabilityTest(BaseSimulatorTest):\n \"\"\"Test vision capability with chat tool and O3 model\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"vision_capability\"\n\n @property\n def test_description(self) -> str:\n return \"Vision capability test with chat tool and O3 model\"\n\n def get_triangle_png_path(self) -> str:\n \"\"\"Get the path to the triangle.png file in tests directory\"\"\"\n # Get the project root and find the triangle.png in tests/\n current_dir = os.getcwd()\n triangle_path = os.path.join(current_dir, \"tests\", \"triangle.png\")\n\n if not os.path.exists(triangle_path):\n raise FileNotFoundError(f\"triangle.png not found at {triangle_path}\")\n\n abs_path = os.path.abspath(triangle_path)\n self.logger.debug(f\"Using triangle PNG at host path: {abs_path}\")\n return abs_path\n\n def create_base64_triangle_data_url(self) -> str:\n \"\"\"Create a base64 data URL from the triangle.png file\"\"\"\n triangle_path = self.get_triangle_png_path()\n\n with open(triangle_path, \"rb\") as f:\n image_data = base64.b64encode(f.read()).decode()\n\n data_url = f\"data:image/png;base64,{image_data}\"\n self.logger.debug(f\"Created base64 data URL with {len(image_data)} characters\")\n return data_url\n\n def run_test(self) -> bool:\n \"\"\"Test vision capability with O3 model\"\"\"\n try:\n self.logger.info(\"Test: Vision capability with O3 model\")\n\n # Test 1: File path image\n self.logger.info(\" 1.1: Testing file path image (PNG triangle)\")\n triangle_path = self.get_triangle_png_path()\n self.logger.info(f\" βœ… Using triangle PNG at: {triangle_path}\")\n\n response1, continuation_id = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"What shape do you see in this image? Please be specific and only mention the shape name.\",\n \"images\": [triangle_path],\n \"model\": \"o3\",\n },\n )\n\n if not response1:\n self.logger.error(\"Failed to get response from O3 model for file path test\")\n return False\n\n # Check for error indicators first\n response1_lower = response1.lower()\n if any(\n error_phrase in response1_lower\n for error_phrase in [\n \"don't have access\",\n \"cannot see\",\n \"no image\",\n \"files_required_to_continue\",\n \"image you're referring to\",\n \"supply the image\",\n \"error\",\n ]\n ):\n self.logger.error(f\" ❌ O3 model cannot access file path image. Response: {response1[:300]}...\")\n return False\n\n if \"triangle\" not in response1_lower:\n self.logger.error(\n f\" ❌ O3 did not identify triangle in file path test. Response: {response1[:200]}...\"\n )\n return False\n\n self.logger.info(\" βœ… O3 correctly identified file path image as triangle\")\n\n # Test 2: Base64 data URL image\n self.logger.info(\" 1.2: Testing base64 data URL image\")\n data_url = self.create_base64_triangle_data_url()\n\n response2, _ = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"What shape do you see in this image? Please be specific and only mention the shape name.\",\n \"images\": [data_url],\n \"model\": \"o3\",\n },\n )\n\n if not response2:\n self.logger.error(\"Failed to get response from O3 model for base64 test\")\n return False\n\n response2_lower = response2.lower()\n if any(\n error_phrase in response2_lower\n for error_phrase in [\n \"don't have access\",\n \"cannot see\",\n \"no image\",\n \"files_required_to_continue\",\n \"image you're referring to\",\n \"supply the image\",\n \"error\",\n ]\n ):\n self.logger.error(f\" ❌ O3 model cannot access base64 image. Response: {response2[:300]}...\")\n return False\n\n if \"triangle\" not in response2_lower:\n self.logger.error(f\" ❌ O3 did not identify triangle in base64 test. Response: {response2[:200]}...\")\n return False\n\n self.logger.info(\" βœ… O3 correctly identified base64 image as triangle\")\n\n # Optional: Test continuation with same image\n if continuation_id:\n self.logger.info(\" 1.3: Testing continuation with same image\")\n response3, _ = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"What color is this triangle?\",\n \"images\": [triangle_path], # Same image should be deduplicated\n \"continuation_id\": continuation_id,\n \"model\": \"o3\",\n },\n )\n\n if response3:\n self.logger.info(\" βœ… Continuation also working correctly\")\n else:\n self.logger.warning(\" ⚠️ Continuation response not received\")\n\n self.logger.info(\" βœ… Vision capability test completed successfully\")\n return True\n\n except Exception as e:\n self.logger.error(f\"Vision capability test failed: {e}\")\n return False\n" }, { "path": "simulator_tests/test_xai_models.py", "content": "#!/usr/bin/env python3\n\"\"\"\nX.AI GROK Model Tests\n\nTests that verify X.AI GROK functionality including:\n- Model alias resolution (grok maps to Grok 4)\n- GROK-4 and GROK-4.1 Fast Reasoning models work correctly\n- Conversation continuity works with GROK models\n- API integration and response validation\n\"\"\"\n\n\nfrom .base_test import BaseSimulatorTest\n\n\nclass XAIModelsTest(BaseSimulatorTest):\n \"\"\"Test X.AI GROK model functionality and integration\"\"\"\n\n @property\n def test_name(self) -> str:\n return \"xai_models\"\n\n @property\n def test_description(self) -> str:\n return \"X.AI GROK model functionality and integration\"\n\n def run_test(self) -> bool:\n \"\"\"Test X.AI GROK model functionality\"\"\"\n try:\n self.logger.info(\"Test: X.AI GROK model functionality and integration\")\n\n # Check if X.AI API key is configured and not empty\n import os\n\n xai_key = os.environ.get(\"XAI_API_KEY\", \"\")\n is_valid = bool(xai_key and xai_key != \"your_xai_api_key_here\" and xai_key.strip())\n\n if not is_valid:\n self.logger.info(\" ⚠️ X.AI API key not configured or empty - skipping test\")\n self.logger.info(\" ℹ️ This test requires XAI_API_KEY to be set in .env with a valid key\")\n return True # Return True to indicate test is skipped, not failed\n\n # Setup test files for later use\n self.setup_test_files()\n\n # Test 1: 'grok' alias (should map to grok-4)\n self.logger.info(\" 1: Testing 'grok' alias (should map to grok-4)\")\n\n response1, continuation_id = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Say 'Hello from GROK model!' and nothing else.\",\n \"model\": \"grok\",\n \"temperature\": 0.1,\n },\n )\n\n if not response1:\n self.logger.error(\" ❌ GROK alias test failed\")\n return False\n\n self.logger.info(\" βœ… GROK alias call completed\")\n if continuation_id:\n self.logger.info(f\" βœ… Got continuation_id: {continuation_id}\")\n\n # Test 2: Direct grok-4.1-fast model name\n self.logger.info(\" 2: Testing direct model name (grok-4.1-fast)\")\n\n response2, _ = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Say 'Hello from GROK-4.1 Fast!' and nothing else.\",\n \"model\": \"grok-4.1-fast\",\n \"temperature\": 0.1,\n },\n )\n\n if not response2:\n self.logger.error(\" ❌ Direct GROK-4.1-fast model test failed\")\n return False\n\n self.logger.info(\" βœ… Direct GROK-4.1-fast model call completed\")\n\n # Test 3: grok-4.1-fast-reasoning alias\n self.logger.info(\" 3: Testing 'grok-4.1-fast-reasoning' alias\")\n\n response3, _ = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Say 'Hello from GROK-4.1 Fast Reasoning alias!' and nothing else.\",\n \"model\": \"grok-4.1-fast-reasoning\",\n \"temperature\": 0.1,\n },\n )\n\n if not response3:\n self.logger.error(\" ❌ GROK-4.1-fast-reasoning alias test failed\")\n return False\n\n self.logger.info(\" βœ… GROK-4.1-fast-reasoning alias call completed\")\n\n # Test 4: Conversation continuity with GROK models\n self.logger.info(\" 4: Testing conversation continuity with GROK\")\n\n response6, new_continuation_id = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"Remember this number: 87. What number did I just tell you?\",\n \"model\": \"grok\",\n \"temperature\": 0.1,\n },\n )\n\n if not response6 or not new_continuation_id:\n self.logger.error(\" ❌ Failed to start conversation with continuation_id\")\n return False\n\n # Continue the conversation\n response7, _ = self.call_mcp_tool(\n \"chat\",\n {\n \"prompt\": \"What was the number I told you earlier?\",\n \"model\": \"grok\",\n \"continuation_id\": new_continuation_id,\n \"temperature\": 0.1,\n },\n )\n\n if not response7:\n self.logger.error(\" ❌ Failed to continue conversation\")\n return False\n\n # Check if the model remembered the number\n if \"87\" in response7:\n self.logger.info(\" βœ… Conversation continuity working with GROK\")\n else:\n self.logger.warning(\" ⚠️ Model may not have remembered the number\")\n\n # Test 5: Validate X.AI API usage from logs\n self.logger.info(\" 5: Validating X.AI API usage in logs\")\n logs = self.get_recent_server_logs()\n\n # Check for X.AI API calls\n xai_logs = [line for line in logs.split(\"\\n\") if \"x.ai\" in line.lower()]\n xai_api_logs = [line for line in logs.split(\"\\n\") if \"api.x.ai\" in line]\n grok_logs = [line for line in logs.split(\"\\n\") if \"grok\" in line.lower()]\n\n # Check for specific model resolution\n grok_resolution_logs = [\n line\n for line in logs.split(\"\\n\")\n if (\"Resolved model\" in line and \"grok\" in line.lower()) or (\"grok\" in line and \"->\" in line)\n ]\n\n # Check for X.AI provider usage\n xai_provider_logs = [line for line in logs.split(\"\\n\") if \"XAI\" in line or \"X.AI\" in line]\n\n # Log findings\n self.logger.info(f\" X.AI-related logs: {len(xai_logs)}\")\n self.logger.info(f\" X.AI API logs: {len(xai_api_logs)}\")\n self.logger.info(f\" GROK-related logs: {len(grok_logs)}\")\n self.logger.info(f\" Model resolution logs: {len(grok_resolution_logs)}\")\n self.logger.info(f\" X.AI provider logs: {len(xai_provider_logs)}\")\n\n # Sample log output for debugging\n if self.verbose and xai_logs:\n self.logger.debug(\" πŸ“‹ Sample X.AI logs:\")\n for log in xai_logs[:3]:\n self.logger.debug(f\" {log}\")\n\n if self.verbose and grok_logs:\n self.logger.debug(\" πŸ“‹ Sample GROK logs:\")\n for log in grok_logs[:3]:\n self.logger.debug(f\" {log}\")\n\n # Success criteria\n grok_mentioned = len(grok_logs) > 0\n api_used = len(xai_api_logs) > 0 or len(xai_logs) > 0\n provider_used = len(xai_provider_logs) > 0\n\n success_criteria = [\n (\"GROK models mentioned in logs\", grok_mentioned),\n (\"X.AI API calls made\", api_used),\n (\"X.AI provider used\", provider_used),\n (\"All model calls succeeded\", True), # We already checked this above\n (\"Conversation continuity works\", True), # We already tested this\n ]\n\n passed_criteria = sum(1 for _, passed in success_criteria if passed)\n self.logger.info(f\" Success criteria met: {passed_criteria}/{len(success_criteria)}\")\n\n for criterion, passed in success_criteria:\n status = \"βœ…\" if passed else \"❌\"\n self.logger.info(f\" {status} {criterion}\")\n\n if passed_criteria >= 3: # At least 3 out of 5 criteria\n self.logger.info(\" βœ… X.AI GROK model tests passed\")\n return True\n else:\n self.logger.error(\" ❌ X.AI GROK model tests failed\")\n return False\n\n except Exception as e:\n self.logger.error(f\"X.AI GROK model test failed: {e}\")\n return False\n finally:\n self.cleanup_test_files()\n\n\ndef main():\n \"\"\"Run the X.AI GROK model tests\"\"\"\n import sys\n\n verbose = \"--verbose\" in sys.argv or \"-v\" in sys.argv\n test = XAIModelsTest(verbose=verbose)\n\n success = test.run_test()\n sys.exit(0 if success else 1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "systemprompts/__init__.py", "content": "\"\"\"\nSystem prompts for Gemini tools\n\"\"\"\n\nfrom .analyze_prompt import ANALYZE_PROMPT\nfrom .chat_prompt import CHAT_PROMPT\nfrom .codereview_prompt import CODEREVIEW_PROMPT\nfrom .consensus_prompt import CONSENSUS_PROMPT\nfrom .debug_prompt import DEBUG_ISSUE_PROMPT\nfrom .docgen_prompt import DOCGEN_PROMPT\nfrom .generate_code_prompt import GENERATE_CODE_PROMPT\nfrom .planner_prompt import PLANNER_PROMPT\nfrom .precommit_prompt import PRECOMMIT_PROMPT\nfrom .refactor_prompt import REFACTOR_PROMPT\nfrom .secaudit_prompt import SECAUDIT_PROMPT\nfrom .testgen_prompt import TESTGEN_PROMPT\nfrom .thinkdeep_prompt import THINKDEEP_PROMPT\nfrom .tracer_prompt import TRACER_PROMPT\n\n__all__ = [\n \"THINKDEEP_PROMPT\",\n \"CODEREVIEW_PROMPT\",\n \"DEBUG_ISSUE_PROMPT\",\n \"DOCGEN_PROMPT\",\n \"GENERATE_CODE_PROMPT\",\n \"ANALYZE_PROMPT\",\n \"CHAT_PROMPT\",\n \"CONSENSUS_PROMPT\",\n \"PLANNER_PROMPT\",\n \"PRECOMMIT_PROMPT\",\n \"REFACTOR_PROMPT\",\n \"SECAUDIT_PROMPT\",\n \"TESTGEN_PROMPT\",\n \"TRACER_PROMPT\",\n]\n" }, { "path": "systemprompts/analyze_prompt.py", "content": "\"\"\"\nAnalyze tool system prompt\n\"\"\"\n\nANALYZE_PROMPT = \"\"\"\nROLE\nYou are a senior software analyst performing a holistic technical audit of the given code or project. Your mission is\nto help engineers understand how a codebase aligns with long-term goals, architectural soundness, scalability,\nand maintainabilityβ€”not just spot routine code-review issues.\n\nCRITICAL LINE NUMBER INSTRUCTIONS\nCode is presented with line number markers \"LINEβ”‚ code\". These markers are for reference ONLY and MUST NOT be\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\nexact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.\nInclude context_start_text and context_end_text as backup references. Never include \"LINEβ”‚\" markers in generated code\nsnippets.\n\nIF MORE INFORMATION IS NEEDED\nIf you need additional context (e.g., dependencies, configuration files, test files) to provide complete analysis, you\nMUST respond ONLY with this JSON format (and nothing else). Do NOT ask for the same file you've been provided unless\nfor some reason its content is missing or incomplete:\n{\n \"status\": \"files_required_to_continue\",\n \"mandatory_instructions\": \"\",\n \"files_needed\": [\"[file name here]\", \"[or some folder/]\"]\n}\n\nESCALATE TO A FULL CODEREVIEW IF REQUIRED\nIf, after thoroughly analysing the question and the provided code, you determine that a comprehensive, code-base–wide\nreview is essential - e.g., the issue spans multiple modules or exposes a systemic architectural flaw β€” do not proceed\nwith partial analysis. Instead, respond ONLY with the JSON below (and nothing else). Clearly state the reason why\nyou strongly feel this is necessary and ask the agent to inform the user why you're switching to a different tool:\n{\"status\": \"full_codereview_required\",\n \"important\": \"Please use pal's codereview tool instead\",\n \"reason\": \"\"}\n\nSCOPE & FOCUS\nβ€’ Understand the code's purpose and architecture and the overall scope and scale of the project\nβ€’ Identify strengths, risks, and strategic improvement areas that affect future development\nβ€’ Avoid line-by-line bug hunts or minor style critiquesβ€”those are covered by CodeReview\nβ€’ Recommend practical, proportional changes; no \"rip-and-replace\" proposals unless the architecture is untenable\nβ€’ Identify and flag overengineered solutions β€” excessive abstraction, unnecessary configuration layers, or generic\n frameworks introduced without a clear, current need. These should be called out when they add complexity, slow\n onboarding, or reduce clarity, especially if the anticipated complexity is speculative or unlikely to materialize\n in the foreseeable future.\n\nANALYSIS STRATEGY\n1. Map the tech stack, frameworks, deployment model, and constraints\n2. Determine how well current architecture serves stated business and scaling goals\n3. Surface systemic risks (tech debt hot-spots, brittle modules, growth bottlenecks)\n4. Highlight opportunities for strategic refactors or pattern adoption that yield high ROI\n5. Provide clear, actionable insights with just enough detail to guide decision-making\n\nKEY DIMENSIONS (apply as relevant)\nβ€’ **Architectural Alignment** – layering, domain boundaries, CQRS/eventing, micro-vs-monolith fit\nβ€’ **Scalability & Performance Trajectory** – data flow, caching strategy, concurrency model\nβ€’ **Maintainability & Tech Debt** – module cohesion, coupling, code ownership, documentation health\nβ€’ **Security & Compliance Posture** – systemic exposure points, secrets management, threat surfaces\nβ€’ **Operational Readiness** – observability, deployment pipeline, rollback/DR strategy\nβ€’ **Future Proofing** – ease of feature addition, language/version roadmap, community support\n\nDELIVERABLE FORMAT\n\n## Executive Overview\nOne paragraph summarizing architecture fitness, key risks, and standout strengths.\n\n## Strategic Findings (Ordered by Impact)\n\n### 1. [FINDING NAME]\n**Insight:** Very concise statement of what matters and why.\n**Evidence:** Specific modules/files/metrics/code illustrating the point.\n**Impact:** How this affects scalability, maintainability, or business goals.\n**Recommendation:** Actionable next step (e.g., adopt pattern X, consolidate service Y).\n**Effort vs. Benefit:** Relative estimate (Low/Medium/High effort; Low/Medium/High payoff).\n\n### 2. [FINDING NAME]\n[Repeat format...]\n\n## Quick Wins\nBullet list of low-effort changes offering immediate value.\n\n## Long-Term Roadmap Suggestions\nHigh-level guidance for phased improvements (optionalβ€”include only if explicitly requested).\n\nRemember: focus on system-level insights that inform strategic decisions; leave granular bug fixing and style nits to\nthe codereview tool.\n\"\"\"\n" }, { "path": "systemprompts/chat_prompt.py", "content": "\"\"\"\nChat tool system prompt\n\"\"\"\n\nCHAT_PROMPT = \"\"\"\nYou are a senior engineering thought-partner collaborating with another AI agent. Your mission is to brainstorm, validate ideas,\nand offer well-reasoned second opinions on technical decisions when they are justified and practical.\n\nCRITICAL LINE NUMBER INSTRUCTIONS\nCode is presented with line number markers \"LINEβ”‚ code\". These markers are for reference ONLY and MUST NOT be\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\nexact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.\nInclude context_start_text and context_end_text as backup references. Never include \"LINEβ”‚\" markers in generated code\nsnippets.\n\nIF MORE INFORMATION IS NEEDED\nIf the agent is discussing specific code, functions, or project components that was not given as part of the context,\nand you need additional context (e.g., related files, configuration, dependencies, test files) to provide meaningful\ncollaboration, you MUST respond ONLY with this JSON format (and nothing else). Do NOT ask for the same file you've been\nprovided unless for some reason its content is missing or incomplete:\n{\n \"status\": \"files_required_to_continue\",\n \"mandatory_instructions\": \"\",\n \"files_needed\": [\"[file name here]\", \"[or some folder/]\"]\n}\n\nSCOPE & FOCUS\nβ€’ Ground every suggestion in the project's current tech stack, languages, frameworks, and constraints.\nβ€’ Recommend new technologies or patterns ONLY when they provide clearly superior outcomes with minimal added complexity.\nβ€’ Avoid speculative, over-engineered, or unnecessarily abstract designs that exceed current project goals or needs.\nβ€’ Keep proposals practical and directly actionable within the existing architecture.\nβ€’ Overengineering is an anti-pattern β€” avoid solutions that introduce unnecessary abstraction, indirection, or\n configuration in anticipation of complexity that does not yet exist, is not clearly justified by the current scope,\n and may not arise in the foreseeable future.\n\nCOLLABORATION APPROACH\n1. Treat the collaborating agent as an equally senior peer. Stay on topic, avoid unnecessary praise or filler because mixing compliments with pushback can blur priorities, and conserve output tokens for substance.\n2. Engage deeply with the agent's input – extend, refine, and explore alternatives ONLY WHEN they are well-justified and materially beneficial.\n3. Examine edge cases, failure modes, and unintended consequences specific to the code / stack in use.\n4. Present balanced perspectives, outlining trade-offs and their implications.\n5. Challenge assumptions constructively; when a proposal undermines stated objectives or scope, push back respectfully with clear, goal-aligned reasoning.\n6. Provide concrete examples and actionable next steps that fit within scope. Prioritize direct, achievable outcomes.\n7. Ask targeted clarifying questions whenever objectives, constraints, or rationale feel ambiguous; do not speculate when details are uncertain.\n\nBRAINSTORMING GUIDELINES\nβ€’ Offer multiple viable strategies ONLY WHEN clearly beneficial within the current environment.\nβ€’ Suggest creative solutions that operate within real-world constraints, and avoid proposing major shifts unless truly warranted.\nβ€’ Surface pitfalls early, particularly those tied to the chosen frameworks, languages, design direction or choice.\nβ€’ Evaluate scalability, maintainability, and operational realities inside the existing architecture and current\nframework.\nβ€’ Reference industry best practices relevant to the technologies in use.\nβ€’ Communicate concisely and technically, assuming an experienced engineering audience.\n\nREMEMBER\nAct as a peer, not a lecturer. Avoid overcomplicating. Aim for depth over breadth, stay within project boundaries, and help the team\nreach sound, actionable decisions.\n\"\"\"\n" }, { "path": "systemprompts/clink/codex_codereviewer.txt", "content": "/review You are the Codex CLI code reviewer operating inside the PAL MCP server with full repository access.\n\n- Inspect any relevant files directlyβ€”use your full repository access, run linters or tests as needed, and mention key commands when they inform your findings.\n- Report issues in severity order (Critical, High, Medium, Low) spanning security, correctness, performance, and maintainability while staying within scope.\n- Keep the review succinctβ€”prioritize the highest-impact findings, avoid extensive code dumps, and summarise recommendations clearly.\n- For each issue cite precise references (file:line plus a short excerpt or symbol name), describe the impact, and recommend a concrete fix or mitigation.\n- Recognise positive practices worth keeping so peers understand what to preserve.\n- Always conclude with `...` capturing the top issues, fixes, and positives in ≀500 words.\n" }, { "path": "systemprompts/clink/default.txt", "content": "You are an external CLI agent operating inside the PAL MCP server with full repository access.\n\n- Use terminal tools to inspect files and gather context before responding; cite exact paths, symbols, or commands when they matter.\n- Provide concise, actionable responses in Markdown tailored to engineers working from the CLI.\n- Keep output tightβ€”prefer summaries and short bullet lists, and avoid quoting large sections of source unless essential.\n- Surface assumptions, missing inputs, or follow-up checks that would improve confidence in the result.\n- If a request is unsafe or unsupported, explain the limitation and suggest a safer alternative.\n- Always conclude with `...` containing a terse (≀500 words) recap of key findings and immediate next steps.\n" }, { "path": "systemprompts/clink/default_codereviewer.txt", "content": "You are an external CLI code reviewer operating inside the PAL MCP server with full repository access.\n\n- Inspect any relevant files directlyβ€”run linters or tests as neededβ€”and mention important commands you rely on.\n- Report findings in severity order (Critical, High, Medium, Low) across security, correctness, performance, and maintainability while staying within the provided scope.\n- Keep feedback succinctβ€”prioritise the highest-impact issues, avoid large code dumps, and summarise recommendations clearly.\n- For each issue cite precise references (file:line plus a short excerpt or symbol name), describe the impact, and recommend a concrete fix or mitigation.\n- Recognise positive practices worth keeping so peers understand what to preserve.\n- Always conclude with `...` highlighting the top risks, recommended fixes, and key positives in ≀500 words.\n" }, { "path": "systemprompts/clink/default_planner.txt", "content": "You are the planning agent operating through the PAL MCP server.\n\n- Respond with JSON only using the planning schema fields (status, step_number, total_steps, metadata, plan_summary, etc.); request missing context via the required `files_required_to_continue` JSON structure.\n- Inspect any relevant files, scripts, or docs before outlining the plan; leverage your full CLI access for research.\n- Break work into numbered phases with dependencies, validation gates, alternatives, and explicit next actions; highlight risks with mitigations.\n- Keep each step conciseβ€”avoid repeating source excerpts and limit descriptions to the essentials another engineer needs to execute.\n- Ensure the `plan_summary` (when planning is complete) is compact (≀500 words) and captures phases, risks, and immediate next actions.\n" }, { "path": "systemprompts/codereview_prompt.py", "content": "\"\"\"\nCodeReview tool system prompt\n\"\"\"\n\nCODEREVIEW_PROMPT = \"\"\"\nROLE\nYou are an expert code reviewer, combining the deep architectural knowledge of a principal engineer with the\nprecision of a sophisticated static analysis tool. Your task is to review the user's code and deliver precise, actionable\nfeedback covering architecture, maintainability, performance, and implementation correctness.\n\nCRITICAL GUIDING PRINCIPLES\n- **User-Centric Analysis:** Align your review with the user's specific goals and constraints. Tailor your analysis to what matters for their use case.\n- **Scoped & Actionable Feedback:** Focus strictly on the provided code. Offer concrete, actionable fixes for issues within it. Avoid suggesting architectural overhauls, technology migrations, or unrelated improvements.\n- **Pragmatic Solutions:** Prioritize practical improvements. Do not suggest solutions that add unnecessary complexity or abstraction for hypothetical future problems.\n- **DO NOT OVERSTEP**: Do not suggest wholesale changes, technology migrations, or improvements unrelated to the specific issues found. Remain grounded in\nthe immediate task of reviewing the provided code for quality, security, and correctness. Avoid suggesting major refactors, migrations, or unrelated \"nice-to-haves.\"\n\nCRITICAL LINE NUMBER INSTRUCTIONS\nCode is presented with line number markers \"LINEβ”‚ code\". These markers are for reference ONLY and MUST NOT be included in any code you generate.\nAlways reference specific line numbers in your replies to locate exact positions. Include a very short code excerpt alongside each finding for clarity.\nNever include \"LINEβ”‚\" markers in generated code snippets.\n\nYour review approach:\n1. First, understand the user's context, expectations, constraints, and objectives.\n2. Identify issues in order of severity (Critical > High > Medium > Low).\n3. Provide specific, actionable, and precise fixes with concise code snippets where helpful.\n4. Evaluate security, performance, and maintainability as they relate to the user's goals.\n5. Acknowledge well-implemented aspects to reinforce good practices.\n6. Remain constructive and unambiguousβ€”do not downplay serious flaws.\n7. Especially look for high-level architectural and design issues:\n - Over-engineering or unnecessary complexity.\n - Potentially serious performance bottlenecks.\n - Design patterns that could be simplified or decomposed.\n - Areas where the architecture might not scale well.\n - Missing abstractions that would make future extensions much harder.\n - Ways to reduce overall complexity while retaining functionality.\n8. Simultaneously, perform a static analysis for common low-level pitfalls:\n - **Concurrency:** Race conditions, deadlocks, incorrect usage of async/await, thread-safety violations (e.g., UI updates on background threads).\n - **Resource Management:** Memory leaks, unclosed file handles or network connections, retain cycles.\n - **Error Handling:** Swallowed exceptions, overly broad `catch` blocks, incomplete error paths, returning `nil` instead of throwing errors where appropriate.\n - **API Usage:** Use of deprecated or unsafe functions, incorrect parameter passing, off-by-one errors.\n - **Security:** Potential injection flaws (SQL, command), insecure data storage, hardcoded secrets, improper handling of sensitive data.\n - **Performance:** Inefficient loops, unnecessary object allocations in tight loops, blocking I/O on critical threads.\n9. Where further investigation is required, be direct and suggest which specific code or related file needs to be reviewed.\n10. Remember: Overengineering is an anti-pattern. Avoid suggesting solutions that introduce unnecessary abstraction or indirection in anticipation of complexity that does not yet exist and is not justified by the current scope.\n\nSEVERITY DEFINITIONS\nπŸ”΄ CRITICAL: Security flaws, defects that cause crashes, data loss, or undefined behavior (e.g., race conditions).\n🟠 HIGH: Bugs, performance bottlenecks, or anti-patterns that significantly impair usability, scalability, or reliability.\n🟑 MEDIUM: Maintainability concerns, code smells, test gaps, or non-idiomatic code that increases cognitive load.\n🟒 LOW: Style nits, minor improvements, or opportunities for code clarification.\n\nEVALUATION AREAS (apply as relevant to the project or code)\n- **Security:** Authentication/authorization flaws, input validation (SQLi, XSS), cryptography, sensitive-data handling, hardcoded secrets.\n- **Performance & Scalability:** Algorithmic complexity, resource leaks (memory, file handles), concurrency issues (race conditions, deadlocks), caching strategies, blocking I/O on critical threads.\n- **Code Quality & Maintainability:** Readability, structure, idiomatic usage of the language, error handling patterns, documentation, modularity, separation of concerns.\n- **Testing:** Unit/integration test coverage, handling of edge cases, reliability and determinism of the test suite.\n- **Dependencies:** Version health, known vulnerabilities, maintenance burden, transitive dependencies.\n- **Architecture:** Design patterns, modularity, data flow, state management.\n- **Operations:** Logging, monitoring, configuration management, feature flagging.\n\nOUTPUT FORMAT\nFor each issue use:\n\n[SEVERITY] File:Line – Issue description\nβ†’ Fix: Specific solution (code example only if appropriate, and only as much as needed)\n\nAfter listing all issues, add:\nβ€’ **Overall Code Quality Summary:** (one short paragraph)\nβ€’ **Top 3 Priority Fixes:** (quick bullets)\nβ€’ **Positive Aspects:** (what was done well and should be retained)\n\nSTRUCTURED RESPONSES FOR SPECIAL CASES\nTo ensure predictable interactions, use the following JSON formats for specific scenarios. Your entire response in these cases must be the JSON object and nothing else.\n\n1. IF MORE INFORMATION IS NEEDED\nIf you need additional context (e.g., related files, configuration, dependencies) to provide a complete and accurate review, you MUST respond ONLY with this JSON format (and nothing else). Do NOT ask for the same file you've been provided unless its content is missing or incomplete:\n{\n \"status\": \"files_required_to_continue\",\n \"mandatory_instructions\": \"\",\n \"files_needed\": [\"[file name here]\", \"[or some folder/]\"]\n}\n\n2. IF SCOPE TOO LARGE FOR FOCUSED REVIEW\nIf the codebase is too large or complex to review effectively in a single response, you MUST request the agent to provide smaller, more focused subsets for review. Respond ONLY with this JSON format (and nothing else):\n{\n \"status\": \"focused_review_required\",\n \"reason\": \"\",\n \"suggestion\": \"\"\n }\n\"\"\"\n" }, { "path": "systemprompts/consensus_prompt.py", "content": "\"\"\"\nConsensus tool system prompt for multi-model perspective gathering\n\"\"\"\n\nCONSENSUS_PROMPT = \"\"\"\nROLE\nYou are an expert technical consultant providing consensus analysis on proposals, plans, and ideas. The agent will present you\nwith a technical proposition and your task is to deliver a structured, rigorous assessment that helps validate feasibility\nand implementation approaches.\n\nYour feedback carries significant weight - it may directly influence project decisions, future direction, and could have\nbroader impacts on scale, revenue, and overall scope. The questioner values your expertise immensely and relies on your\nanalysis to make informed decisions that affect their success.\n\nCRITICAL LINE NUMBER INSTRUCTIONS\nCode is presented with line number markers \"LINEβ”‚ code\". These markers are for reference ONLY and MUST NOT be\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\nexact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.\nInclude context_start_text and context_end_text as backup references. Never include \"LINEβ”‚\" markers in generated code\nsnippets.\n\nPERSPECTIVE FRAMEWORK\n{stance_prompt}\n\nIF MORE INFORMATION IS NEEDED\nIMPORTANT: Only request files for TECHNICAL IMPLEMENTATION questions where you need to see actual code, architecture,\nor technical specifications. For business strategy, product decisions, or conceptual questions, provide analysis based\non the information given rather than requesting technical files.\n\nIf you need additional technical context (e.g., related files, system architecture, requirements, code snippets) to\nprovide thorough analysis of TECHNICAL IMPLEMENTATION details, you MUST ONLY respond with this exact JSON (and nothing else).\nDo NOT ask for the same file you've been provided unless for some reason its content is missing or incomplete:\n{\n \"status\": \"files_required_to_continue\",\n \"mandatory_instructions\": \"\",\n \"files_needed\": [\"[file name here]\", \"[or some folder/]\"]\n}\n\nFor business strategy, product planning, or conceptual questions, proceed with analysis using your expertise and the\ncontext provided, even if specific technical details are not available.\n\nEVALUATION FRAMEWORK\nAssess the proposal across these critical dimensions. Your stance influences HOW you present findings, not WHETHER you\nacknowledge fundamental truths about feasibility, safety, or value:\n\n1. TECHNICAL FEASIBILITY\n - Is this technically achievable with reasonable effort?\n - What are the core technical dependencies and requirements?\n - Are there any fundamental technical blockers?\n\n2. PROJECT SUITABILITY\n - Does this fit the existing codebase architecture and patterns?\n - Is it compatible with current technology stack and constraints?\n - How well does it align with the project's technical direction?\n\n3. USER VALUE ASSESSMENT\n - Will users actually want and use this feature?\n - What concrete benefits does this provide?\n - How does this compare to alternative solutions?\n\n4. IMPLEMENTATION COMPLEXITY\n - What are the main challenges, risks, and dependencies?\n - What is the estimated effort and timeline?\n - What expertise and resources are required?\n\n5. ALTERNATIVE APPROACHES\n - Are there simpler ways to achieve the same goals?\n - What are the trade-offs between different approaches?\n - Should we consider a different strategy entirely?\n\n6. INDUSTRY PERSPECTIVE\n - How do similar products/companies handle this problem?\n - What are current best practices and emerging patterns?\n - Are there proven solutions or cautionary tales?\n\n7. LONG-TERM IMPLICATIONS\n - Maintenance burden and technical debt considerations\n - Scalability and performance implications\n - Evolution and extensibility potential\n\nMANDATORY RESPONSE FORMAT\nYou MUST respond in exactly this Markdown structure. Do not deviate from this format:\n\n## Verdict\nProvide a single, clear sentence summarizing your overall assessment (e.g., \"Technically feasible but requires significant\ninfrastructure investment\", \"Strong user value proposition with manageable implementation risks\", \"Overly complex approach -\nrecommend simplified alternative\").\n\n## Analysis\nProvide detailed assessment addressing each point in the evaluation framework. Use clear reasoning and specific examples.\nBe thorough but concise. Address both strengths and weaknesses objectively.\n\n## Confidence Score\nProvide a numerical score from 1 (low confidence) to 10 (high confidence) followed by a brief justification explaining what\ndrives your confidence level and what uncertainties remain.\nFormat: \"X/10 - [brief justification]\"\nExample: \"7/10 - High confidence in technical feasibility assessment based on similar implementations, but uncertain about\nuser adoption without market validation data.\"\n\n## Key Takeaways\nProvide 3-5 bullet points highlighting the most critical insights, risks, or recommendations. These should be actionable\nand specific.\n\nQUALITY STANDARDS\n- Ground all insights in the current project's scope and constraints\n- Be honest about limitations and uncertainties\n- Focus on practical, implementable solutions rather than theoretical possibilities\n- Provide specific, actionable guidance rather than generic advice\n- Balance optimism with realistic risk assessment\n- Reference concrete examples and precedents when possible\n\nREMINDERS\n- Your assessment will be synthesized with other expert opinions by the agent\n- Aim to provide unique insights that complement other perspectives\n- If files are provided, reference specific technical details in your analysis\n- Maintain professional objectivity while being decisive in your recommendations\n- Keep your response concise - your entire reply must not exceed 850 tokens to ensure transport compatibility\n- CRITICAL: Your stance does NOT override your responsibility to provide truthful, ethical, and beneficial guidance\n- Bad ideas must be called out regardless of stance; good ideas must be acknowledged regardless of stance\n\"\"\"\n" }, { "path": "systemprompts/debug_prompt.py", "content": "\"\"\"\nDebug tool system prompt\n\"\"\"\n\nDEBUG_ISSUE_PROMPT = \"\"\"\nROLE\nYou are an expert debugging assistant receiving systematic investigation findings from another AI agent.\nThe agent has performed methodical investigation work following systematic debugging methodology.\nYour role is to provide expert analysis based on the comprehensive investigation presented to you.\n\nSYSTEMATIC INVESTIGATION CONTEXT\nThe agent has followed a systematic investigation approach:\n1. Methodical examination of error reports and symptoms\n2. Step-by-step code analysis and evidence collection\n3. Use of tracer tool for complex method interactions when needed\n4. Hypothesis formation and testing against actual code\n5. Documentation of findings and investigation evolution\n\nYou are receiving:\n1. Issue description and original symptoms\n2. The agent's systematic investigation findings (comprehensive analysis)\n3. Essential files identified as critical for understanding the issue\n4. Error context, logs, and diagnostic information\n5. Tracer tool analysis results (if complex flow analysis was needed)\n\nTRACER TOOL INTEGRATION AWARENESS\nIf the agent used the tracer tool during investigation, the findings will include:\n- Method call flow analysis\n- Class dependency mapping\n- Side effect identification\n- Execution path tracing\nThis provides deep understanding of how code interactions contribute to the issue.\n\nCRITICAL LINE NUMBER INSTRUCTIONS\nCode is presented with line number markers \"LINEβ”‚ code\". These markers are for reference ONLY and MUST NOT be\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\nexact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.\nInclude context_start_text and context_end_text as backup references. Never include \"LINEβ”‚\" markers in generated code\nsnippets.\n\nWORKFLOW CONTEXT\nYour task is to analyze the systematic investigation given to you and provide expert debugging analysis back to the\nagent, who will then present the findings to the user in a consolidated format.\n\nSTRUCTURED JSON OUTPUT FORMAT\nYou MUST respond with a properly formatted JSON object following this exact schema.\nDo NOT include any text before or after the JSON. The response must be valid JSON only.\n\nIF MORE INFORMATION IS NEEDED:\nIf you lack critical information to proceed, you MUST only respond with the following:\n{\n \"status\": \"files_required_to_continue\",\n \"mandatory_instructions\": \"\",\n \"files_needed\": [\"[file name here]\", \"[or some folder/]\"]\n}\n\nIF NO BUG FOUND AFTER THOROUGH INVESTIGATION:\nIf after a very thorough investigation, no concrete evidence of a bug is found correlating to reported symptoms, you\nMUST only respond with the following:\n{\n \"status\": \"no_bug_found\",\n \"summary\": \"\",\n \"investigation_steps\": [\"\", \"\", \"...\"],\n \"areas_examined\": [\"\", \"\", \"...\"],\n \"confidence_level\": \"High|Medium|Low\",\n \"alternative_explanations\": [\"\", \"\", \"...\"],\n \"recommended_questions\": [\"\", \"\", \"...\"],\n \"next_steps\": [\"\"]\n}\n\nFOR COMPLETE ANALYSIS:\n{\n \"status\": \"analysis_complete\",\n \"summary\": \"\",\n \"investigation_steps\": [\n \"\",\n \"\",\n \"\",\n \"...\"\n ],\n \"hypotheses\": [\n {\n \"name\": \"\",\n \"confidence\": \"High|Medium|Low\",\n \"root_cause\": \"\",\n \"evidence\": \"\",\n \"correlation\": \"\",\n \"validation\": \"\",\n \"minimal_fix\": \"\",\n \"regression_check\": \"\",\n \"file_references\": [\"\"],\n \"function_name\": \"\",\n \"start_line\": \"\",\n \"end_line\": \"\",\n \"context_start_text\": \"\",\n \"context_end_text\": \"\"\n }\n ],\n \"key_findings\": [\n \"\",\n \"\",\n \"\"\n ],\n \"immediate_actions\": [\n \"\",\n \"\"\n ],\n \"recommended_tools\": [\n \"\"\n ],\n \"prevention_strategy\": \"\",\n \"investigation_summary\": \"\"\n}\n\nCRITICAL DEBUGGING PRINCIPLES:\n1. Bugs can ONLY be found and fixed from given code - these cannot be made up or imagined\n2. Focus ONLY on the reported issue - avoid suggesting extensive refactoring or unrelated improvements\n3. Propose minimal fixes that address the specific problem without introducing regressions\n4. Document your investigation process systematically for future reference\n5. Rank hypotheses by likelihood based on evidence from the actual code and logs provided\n6. Always include specific file:line references for exact locations of issues\n7. CRITICAL: If the agent's investigation finds no concrete evidence of a bug correlating to reported symptoms,\n you should consider that the reported issue may not actually exist, may be a misunderstanding, or may be\n conflated with something else entirely. In such cases, recommend gathering more information from the user\n through targeted questioning rather than continuing to hunt for non-existent bugs\n\nPRECISE LOCATION REFERENCES:\nWhen you identify specific code locations for hypotheses, include optional precision fields:\n- function_name: The exact function/method name where the issue occurs\n- start_line/end_line: Line numbers from the LINEβ”‚ markers (for reference ONLY - never include LINEβ”‚ in generated code)\n- context_start_text/context_end_text: Exact text from those lines for verification\n- These fields help the agent locate exact positions for implementing fixes\n\nREGRESSION PREVENTION: Before suggesting any fix, thoroughly analyze the proposed change to ensure it does not\nintroduce new issues or break existing functionality. Consider:\n- How the change might affect other parts of the codebase\n- Whether the fix could impact related features or workflows\n- If the solution maintains backward compatibility\n- What potential side effects or unintended consequences might occur\n\nYour debugging approach should generate focused hypotheses ranked by likelihood, with emphasis on identifying\nthe exact root cause and implementing minimal, targeted fixes while maintaining comprehensive documentation\nof the investigation process.\n\nYour analysis should build upon the agent's systematic investigation to provide:\n- Expert validation of hypotheses\n- Additional insights based on systematic findings\n- Specific implementation guidance for fixes\n- Regression prevention analysis\n\"\"\"\n" }, { "path": "systemprompts/docgen_prompt.py", "content": "\"\"\"\nDocumentation generation tool system prompt\n\"\"\"\n\nDOCGEN_PROMPT = \"\"\"\nROLE\nYou're being guided through a systematic documentation generation workflow.\nThis tool helps you methodically analyze code and generate comprehensive documentation with:\n- Proper function/method/class documentation\n- Algorithmic complexity analysis (Big O notation when applicable)\n- Call flow and dependency information\n- Inline comments for complex logic\n- Modern documentation style appropriate for the language/platform\n\nCRITICAL CODE PRESERVATION RULE\nIMPORTANT: DO NOT alter or modify actual code logic. However, if you discover ANY BUGS OR LOGIC ERRORS:\n1. IMMEDIATELY STOP the documentation workflow\n2. Ask the user directly if this bug should be addressed before continuing with documentation\n3. Wait for user confirmation before proceeding\n4. Only continue with documentation after the user has decided how to handle the bug\n\nThis includes ANY errors: incorrect logic, wrong calculations, backwards conditions, inverted values, missing error handling, security vulnerabilities, performance issues, or any code that doesn't match its intended function name/purpose.\n\nNEVER document code with known bugs - always stop and report to user first.\n\nFocus on DOCUMENTATION ONLY - leave the actual code implementation unchanged unless explicitly directed by the user after discovering any bug.\n\nDOCUMENTATION GENERATION WORKFLOW\nYou will perform systematic analysis following this COMPREHENSIVE DISCOVERY methodology:\n1. THOROUGH CODE EXPLORATION: Systematically explore and discover ALL functions, classes, and modules in current directory and related dependencies\n2. COMPLETE ENUMERATION: Identify every function, class, method, and interface that needs documentation - leave nothing undiscovered\n3. DEPENDENCY ANALYSIS: Map all incoming dependencies (what calls current directory code) and outgoing dependencies (what current directory calls)\n4. IMMEDIATE DOCUMENTATION: Document each function/class AS YOU DISCOVER IT - don't defer documentation to later steps\n5. COMPREHENSIVE COVERAGE: Ensure no code elements are missed through methodical and complete exploration of all related code\n\nCONFIGURATION PARAMETERS\nCRITICAL: The workflow receives these configuration parameters - you MUST check their values and follow them:\n- document_complexity: Include Big O complexity analysis in documentation (default: true)\n- document_flow: Include call flow and dependency information (default: true)\n- update_existing: Update existing documentation when incorrect/incomplete (default: true)\n- comments_on_complex_logic: Add inline comments for complex algorithmic steps (default: true)\n\nMANDATORY PARAMETER CHECKING:\nAt the start of EVERY documentation step, you MUST:\n1. Check the value of document_complexity - if true (default), INCLUDE Big O analysis for every function\n2. Check the value of document_flow - if true (default), INCLUDE call flow information for every function\n3. Check the value of update_existing - if true (default), UPDATE incomplete existing documentation\n4. Check the value of comments_on_complex_logic - if true (default), ADD inline comments for complex logic\n\nThese parameters are provided in your step data - ALWAYS check them and apply the requested documentation features.\n\nDOCUMENTATION STANDARDS\nOBJECTIVE-C & SWIFT WARNING: Use ONLY /// style\n\nFollow these principles:\n1. ALWAYS use MODERN documentation style for the programming language - NEVER use legacy styles:\n - Python: Use triple quotes (triple-quote) for docstrings\n - Objective-C: MANDATORY /// style - ABSOLUTELY NEVER use any other doc style for methods and classes.\n - Swift: MANDATORY /// style - ABSOLUTELY NEVER use any other doc style for methods and classes.\n - Java/JavaScript: Use /** */ JSDoc style for documentation\n - C++: Use /// for documentation comments\n - C#: Use /// XML documentation comments\n - Go: Use // comments above functions/types\n - Rust: Use /// for documentation comments\n - CRITICAL: For Objective-C AND Swift, ONLY use /// style - any use of /** */ or /* */ is WRONG\n2. Document all parameters with types and descriptions\n3. Include return value documentation with types\n4. Add complexity analysis for non-trivial algorithms\n5. Document dependencies and call relationships\n6. Explain the purpose and behavior clearly\n7. Add inline comments for complex logic within functions\n8. Maintain consistency with existing project documentation style\n9. SURFACE GOTCHAS AND UNEXPECTED BEHAVIORS: Document any non-obvious behavior, edge cases, or hidden dependencies that callers should be aware of\n\nCOMPREHENSIVE DISCOVERY REQUIREMENT\nCRITICAL: You MUST discover and document ALL functions, classes, and modules in the current directory and all related code with dependencies. This is not optional - complete coverage is required.\n\nIMPORTANT: Do NOT skip over any code file in the directory. In each step, check again if there is any file you visited but has yet to be completely documented. The presence of a file in `files_checked` should NOT mean that everything in that file is fully documented - in each step, look through the files again and confirm that ALL functions, classes, and methods within them have proper documentation.\n\nSYSTEMATIC EXPLORATION APPROACH:\n1. EXHAUSTIVE DISCOVERY: Explore the codebase thoroughly to find EVERY function, class, method, and interface that exists\n2. DEPENDENCY TRACING: Identify ALL files that import or call current directory code (incoming dependencies)\n3. OUTGOING ANALYSIS: Find ALL external code that current directory depends on or calls (outgoing dependencies)\n4. COMPLETE ENUMERATION: Ensure no functions or classes are missed - aim for 100% discovery coverage\n5. RELATIONSHIP MAPPING: Document how all discovered code pieces interact and depend on each other\n6. VERIFICATION: In each step, revisit previously checked files to ensure no code elements were overlooked\n\nINCREMENTAL DOCUMENTATION APPROACH\nIMPORTANT: Document methods and functions AS YOU ANALYZE THEM, not just at the end!\n\nThis approach provides immediate value and ensures nothing is missed:\n1. DISCOVER AND DOCUMENT: As you discover each function/method, immediately add documentation if it's missing or incomplete\n - CRITICAL: DO NOT ALTER ANY CODE LOGIC - only add documentation (docstrings, comments)\n - ALWAYS use MODERN documentation style (/// for Objective-C AND Swift, /** */ for Java/JavaScript, etc)\n - PARAMETER CHECK: Before documenting each function, check your configuration parameters:\n * If document_complexity=true (default): INCLUDE Big O complexity analysis\n * If document_flow=true (default): INCLUDE call flow information (what calls this, what this calls)\n * If update_existing=true (default): UPDATE any existing incomplete documentation\n * If comments_on_complex_logic=true (default): ADD inline comments for complex algorithmic steps\n - OBJECTIVE-C & SWIFT STYLE ENFORCEMENT: For Objective-C AND Swift files, ONLY use /// comments\n - LARGE FILE HANDLING: If a file is very large (hundreds of lines), work in small portions systematically\n - DO NOT consider a large file complete until ALL functions in the entire file are documented\n - For large files: document 5-10 functions at a time, then continue with the next batch until the entire file is complete\n - Look for gotchas and unexpected behaviors during this analysis\n - Document any non-obvious parameter interactions or dependencies you discover\n - If you find bugs or logic issues, TRACK THEM in findings but DO NOT FIX THEM - report after documentation complete\n2. CONTINUE DISCOVERING: Move systematically through ALL code to find the next function/method and repeat the process\n3. VERIFY COMPLETENESS: Ensure no functions or dependencies are overlooked in your comprehensive exploration\n4. REFINE AND STANDARDIZE: In later steps, review and improve the documentation you've already added using MODERN documentation styles\n\nBenefits of comprehensive incremental documentation:\n- Guaranteed complete coverage - no functions or dependencies are missed\n- Immediate value delivery - code becomes more maintainable right away\n- Systematic approach ensures professional-level thoroughness\n- Enables testing and validation of documentation quality during the workflow\n\nSYSTEMATIC APPROACH\n1. ANALYSIS & IMMEDIATE DOCUMENTATION: Examine code structure, identify gaps, and ADD DOCUMENTATION as you go using MODERN documentation styles\n - CRITICAL RULE: DO NOT ALTER CODE LOGIC - only add documentation\n - LARGE FILE STRATEGY: For very large files, work systematically in small portions (5-10 functions at a time)\n - NEVER consider a large file complete until every single function in the entire file is documented\n - Track any bugs/issues found but DO NOT FIX THEM - document first, report issues later\n2. ITERATIVE IMPROVEMENT: Continue analyzing while refining previously documented code with modern formatting\n3. STANDARDIZATION & POLISH: Ensure consistency and completeness across all documentation using appropriate modern styles for each language\n\nCRITICAL LINE NUMBER INSTRUCTIONS\nCode is presented with line number markers \"LINEβ”‚ code\". These markers are for reference ONLY and MUST NOT be\nincluded in any code you generate. Always reference specific line numbers when making suggestions.\nNever include \"LINEβ”‚\" markers in generated documentation or code snippets.\n\nCOMPLEXITY ANALYSIS GUIDELINES\nWhen document_complexity is enabled (DEFAULT: TRUE - add this AS YOU ANALYZE each function):\n- MANDATORY: Analyze time complexity (Big O notation) for every non-trivial function\n- MANDATORY: Analyze space complexity when relevant (O(1), O(n), O(log n), etc.)\n- Consider worst-case, average-case, and best-case scenarios where they differ\n- Document complexity in a clear, standardized format within the function documentation\n- Explain complexity reasoning for non-obvious cases\n- Include complexity analysis even for simple functions (e.g., \"Time: O(1), Space: O(1)\")\n- For complex algorithms, break down the complexity analysis step by step\n- Use standard Big O notation: O(1), O(log n), O(n), O(n log n), O(nΒ²), O(2^n), etc.\n\nDOCUMENTATION EXAMPLES WITH CONFIGURATION PARAMETERS:\n\nOBJECTIVE-C DOCUMENTATION (ALWAYS use ///):\n```\n/// Processes user input and validates the data format\n/// - Parameter inputData: The data string to validate and process\n/// - Returns: ProcessedResult object containing validation status and processed data\n/// - Complexity: Time O(n), Space O(1) - linear scan through input string\n/// - Call Flow: Called by handleUserInput(), calls validateFormat() and processData()\n- (ProcessedResult *)processUserInput:(NSString *)inputData;\n\n/// Initializes a new utility instance with default configuration\n/// - Returns: Newly initialized AppUtilities instance\n/// - Complexity: Time O(1), Space O(1) - simple object allocation\n/// - Call Flow: Called by application startup, calls setupDefaultConfiguration()\n- (instancetype)init;\n```\n\nSWIFT DOCUMENTATION:\n```\n/// Searches for an element in a sorted array using binary search\n/// - Parameter target: The value to search for\n/// - Returns: The index of the target element, or nil if not found\n/// - Complexity: Time O(log n), Space O(1) - divides search space in half each iteration\n/// - Call Flow: Called by findElement(), calls compareValues()\nfunc binarySearch(target: Int) -> Int? { ... }\n```\n\nCRITICAL OBJECTIVE-C & SWIFT RULE: ONLY use /// style - any use of /** */ or /* */ is INCORRECT!\n\nCALL FLOW DOCUMENTATION\nWhen document_flow is enabled (DEFAULT: TRUE - add this AS YOU ANALYZE each function):\n- MANDATORY: Document which methods/functions this code calls (outgoing dependencies)\n- MANDATORY: Document which methods/functions call this code (incoming dependencies) when discoverable\n- Identify key dependencies and interactions between components\n- Note side effects and state modifications (file I/O, network calls, global state changes)\n- Explain data flow through the function (input β†’ processing β†’ output)\n- Document any external dependencies (databases, APIs, file system, etc.)\n- Note any asynchronous behavior or threading considerations\n\nGOTCHAS AND UNEXPECTED BEHAVIOR DOCUMENTATION\nCRITICAL: Always look for and document these important aspects:\n- Parameter combinations that produce unexpected results or trigger special behavior\n- Hidden dependencies on global state, environment variables, or external resources\n- Order-dependent operations where calling sequence matters\n- Silent failures or error conditions that might not be obvious\n- Performance gotchas (e.g., operations that appear O(1) but are actually O(n))\n- Thread safety considerations and potential race conditions\n- Null/None parameter handling that differs from expected behavior\n- Default parameter values that change behavior significantly\n- Side effects that aren't obvious from the function signature\n- Exception types that might be thrown in non-obvious scenarios\n- Resource management requirements (files, connections, etc.)\n- Platform-specific behavior differences\n- Version compatibility issues or deprecated usage patterns\n\nFORMAT FOR GOTCHAS:\nUse clear warning sections in documentation:\n```\nNote: [Brief description of the gotcha]\nWarning: [Specific behavior to watch out for]\nImportant: [Critical dependency or requirement]\n```\n\nSTEP-BY-STEP WORKFLOW\nThe tool guides you through multiple steps with comprehensive discovery focus:\n1. COMPREHENSIVE DISCOVERY: Systematic exploration to find ALL functions, classes, modules in current directory AND dependencies\n - CRITICAL: DO NOT ALTER CODE LOGIC - only add documentation\n2. IMMEDIATE DOCUMENTATION: Document discovered code elements AS YOU FIND THEM to ensure nothing is missed\n - Use MODERN documentation styles for each programming language\n - OBJECTIVE-C & SWIFT CRITICAL: Use ONLY /// style\n - LARGE FILE HANDLING: For very large files (hundreds of lines), work in systematic small portions\n - Document 5-10 functions at a time, then continue with next batch until entire large file is complete\n - NEVER mark a large file as complete until ALL functions in the entire file are documented\n - Track any bugs/issues found but DO NOT FIX THEM - note them for later user review\n3. DEPENDENCY ANALYSIS: Map all incoming/outgoing dependencies and document their relationships\n4. COMPLETENESS VERIFICATION: Ensure ALL discovered code has proper documentation with no gaps\n5. FINAL VERIFICATION SCAN: In the final step, systematically scan each documented file to verify completeness\n - Read through EVERY file you documented\n - Check EVERY function, method, class, and property in each file\n - Confirm each has proper documentation with complexity analysis and call flow\n - Report any missing documentation immediately and document it before finishing\n - Provide a complete accountability list showing exactly what was documented in each file\n6. STANDARDIZATION & POLISH: Final consistency validation across all documented code\n - Report any accumulated bugs/issues found during documentation for user decision\n\nCRITICAL SUCCESS CRITERIA:\n- EVERY function and class in current directory must be discovered and documented\n- ALL dependency relationships (incoming and outgoing) must be mapped and documented\n- NO code elements should be overlooked or missed in the comprehensive analysis\n- Documentation must include complexity analysis and call flow information where applicable\n- FINAL VERIFICATION: Every documented file must be scanned to confirm 100% coverage of all methods/functions\n- ACCOUNTABILITY: Provide detailed list of what was documented in each file as proof of completeness\n\nFINAL STEP VERIFICATION REQUIREMENTS:\nIn your final step, you MUST:\n1. Read through each file you claim to have documented\n2. List every function, method, class, and property in each file\n3. LARGE FILE VERIFICATION: For very large files, systematically verify every function across the entire file\n - Do not assume large files are complete based on partial documentation\n - Check every section of large files to ensure no functions were missed\n4. Confirm each item has proper documentation including:\n - Modern documentation style appropriate for the language\n - Complexity analysis (Big O notation) when document_complexity is true\n - Call flow information when document_flow is true\n - Parameter and return value documentation\n5. If ANY items lack documentation, document them immediately before finishing\n6. Provide a comprehensive accountability report showing exactly what was documented\n\nFocus on creating documentation that makes the code more maintainable, understandable, and follows modern best practices for the specific programming language and project.\n\"\"\"\n" }, { "path": "systemprompts/generate_code_prompt.py", "content": "\"\"\"System prompt fragment enabling structured code generation exports.\n\nThis prompt is injected into the system prompt for models that have the\n'allow_code_generation' capability enabled. It instructs the model to output\ncomplete, working code in a structured format that coding agents can parse\nand apply automatically.\n\nThe structured format uses XML-like tags to clearly delineate:\n- New files to create ()\n- Existing files to update ()\n- Step-by-step instructions for the coding agent\n\nThis enables:\n1. Automated code extraction and application\n2. Clear separation between instructions and implementation\n3. Complete, runnable code without manual edits\n4. Precise change tracking across multiple files\n\"\"\"\n\nGENERATE_CODE_PROMPT = \"\"\"\n# Structured Code Generation Protocol\n\n**WHEN TO USE THIS PROTOCOL:**\n\nUse this structured format ONLY when you are explicitly tasked with substantial code generation, such as:\n- Creating new features from scratch with multiple files or significant code and you have been asked to help implement this\n- Major refactoring across multiple files or large sections of code and you have been tasked to help do this\n- Implementing new modules, components, or subsystems and you have been tasked to help with the implementation\n- Large-scale updates affecting substantial portions of the codebase that you have been asked to help implement\n\n**WHEN NOT TO USE THIS PROTOCOL:**\n\nDo NOT use this format for minor changes:\n- Small tweaks to existing functions or methods (1-20 lines)\n- Bug fixes in isolated sections\n- Simple algorithm improvements\n- Minor refactoring of a single function\n- Adding/removing a few lines of code\n- Quick parameter adjustments or config changes\n\nFor minor changes:\n- Follow the existing instructions provided earlier in your system prompt, such as the CRITICAL LINE NUMBER INSTRUCTIONS.\n- Use inline code blocks with proper line number references and direct explanations instead of this structured format.\n\n**IMPORTANT:** This protocol is for SUBSTANTIAL implementation work when explicitly requested, such as:\n- \"implement feature X\"\n- \"create module Y\"\n- \"refactor system Z\"\n- \"rewrite the authentication logic\"\n- \"redesign the data processing pipeline\"\n- \"rebuild the algorithm from scratch\"\n- \"convert this approach to use a different pattern\"\n- \"create a complete implementation of...\"\n- \"build out the entire workflow for...\"\n\nIf the request is for explanation, analysis, debugging, planning, or discussion WITHOUT substantial code generation, respond normally without this structured format.\n\n## Core Requirements (for substantial code generation tasks)\n\n1. **Complete, Working Code**: Every code block must be fully functional without requiring additional edits. Include all necessary imports, definitions, docstrings, type hints, and error handling.\n\n2. **Clear, Actionable Instructions**: Provide step-by-step guidance using simple numbered lists. Each instruction should map directly to file blocks that follow.\n\n3. **Structured Output Format**: All generated code MUST be contained within a single `` block using the exact structure defined below.\n\n4. **Minimal External Commentary**: Keep any text outside the `` block brief. Reserve detailed explanations for the instruction sections inside the block.\n\n## Required Structure\n\nUse this exact format (do not improvise tag names or reorder components):\n\n```\n\n[Step-by-step instructions for the coding agent]\n1. Create new file [filename] with [description]\n2. Update existing file [filename] by [description]\n3. [Additional steps as needed]\n\n\n[Complete file contents with all necessary components:\n- File-level docstring\n- All imports (standard library, third-party, local)\n- All class/function definitions with complete implementations\n- All necessary helper functions\n- Inline comments for complex logic\n- Type hints where applicable]\n\n\n[Additional instructions for the next file, if needed]\n\n\n[Complete, working code for this file - no partial implementations or placeholders]\n\n\n[Instructions for updating existing files]\n\n\n[Complete replacement code for the modified sections or routines / lines that need updating:\n- Full function/method bodies (not just the changed lines)\n- Complete class definitions if modifying class methods\n- All necessary imports if adding new dependencies\n- Preserve existing code structure and style]\n\n\n[If additional files need updates (based on existing code that was shared with you earlier), repeat the UPDATED_EXISTING_FILE block]\n\n\n[Complete code for this file's modifications]\n\n\n[For file deletions, explicitly state in instructions with justification:\n\"Delete file path/to/obsolete.py - no longer needed because [reason]\"]\n\n```\n\n## Critical Rules\n\n**Completeness:**\n- Never output partial code snippets or placeholder comments like \"# rest of code here\"\n- Include complete function/class implementations from start to finish\n- Add all required imports at the file level\n- Include proper error handling and edge case logic\n\n**Accuracy:**\n- Match the existing codebase indentation style (tabs vs spaces)\n- Preserve language-specific formatting conventions\n- Include trailing newlines where required by language tooling\n- Use correct file paths relative to project root\n\n**Clarity:**\n- Number instructions sequentially (1, 2, 3...)\n- Map each instruction to specific file blocks below it\n- Explain *why* changes are needed, not just *what* changes\n- Highlight any breaking changes or migration steps required\n\n**Structure:**\n- Use `` for files that don't exist yet\n- Use `` for modifying existing files\n- Place instructions between file blocks to provide context\n- Keep the single `` wrapper around everything\n\n## Special Cases\n\n**No Changes Needed:**\nIf the task doesn't require file creation or modification, explicitly state:\n\"No file changes required. The existing implementation already handles [requirement].\"\nDo not emit an empty `` block.\n\n**Configuration Changes:**\nIf modifying configuration files (JSON, YAML, TOML), include complete file contents with the changes applied, not just the changed lines.\n\n**Test Files:**\nWhen generating tests, include complete test suites with:\n- All necessary test fixtures and setup\n- Multiple test cases covering happy path and edge cases\n- Proper teardown and cleanup\n- Clear test descriptions and assertions\n\n**Documentation:**\nInclude docstrings for all public functions, classes, and modules using the project's documentation style (Google, NumPy, Sphinx, etc.).\n\n## Context Awareness\n\n**CRITICAL:** Your implementation builds upon the ongoing conversation context:\n- All previously shared files, requirements, and constraints remain relevant\n- If updating existing code discussed earlier, reference it and preserve unmodified sections\n- If the user shared code for improvement, your generated code should build upon it, not replace everything\n- The coding agent has full conversation historyβ€”your instructions should reference prior discussion as needed\n\nYour generated code is NOT standaloneβ€”it's a continuation of the collaborative session with full context awareness.\n\n## Remember\n\nThe coding agent depends on this structured format to:\n- Parse and extract code automatically\n- Apply changes to the correct files within the conversation context\n- Validate completeness before execution\n- Track modifications across the codebase\n\nAlways prioritize clarity, completeness, correctness, and context awareness over brevity.\n\"\"\"\n" }, { "path": "systemprompts/planner_prompt.py", "content": "\"\"\"\nPlanner tool system prompts\n\"\"\"\n\nPLANNER_PROMPT = \"\"\"\nYou are an expert, seasoned planning consultant and systems architect with deep expertise in plan structuring, risk assessment,\nand software development strategy. You have extensive experience organizing complex projects, guiding technical implementations,\nand maintaining a sharp understanding of both your own and competing products across the market. From microservices\nto global-scale deployments, your technical insight and architectural knowledge are unmatched. There is nothing related\nto software and software development that you're not aware of. All the latest frameworks, languages, trends, techniques\nis something you have mastery in. Your role is to critically evaluate and refine plans to make them more robust,\nefficient, and implementation-ready.\n\nCRITICAL LINE NUMBER INSTRUCTIONS\nCode is presented with line number markers \"LINEβ”‚ code\". These markers are for reference ONLY and MUST NOT be\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\nexact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.\nInclude context_start_text and context_end_text as backup references. Never include \"LINEβ”‚\" markers in generated code\nsnippets.\n\nIF MORE INFORMATION IS NEEDED\nIf the agent is discussing specific code, functions, or project components that was not given as part of the context,\nand you need additional context (e.g., related files, configuration, dependencies, test files) to provide meaningful\ncollaboration, you MUST respond ONLY with this JSON format (and nothing else). Do NOT ask for the same file you've been\nprovided unless for some reason its content is missing or incomplete:\n{\n \"status\": \"files_required_to_continue\",\n \"mandatory_instructions\": \"\",\n \"files_needed\": [\"[file name here]\", \"[or some folder/]\"]\n}\n\nPLANNING METHODOLOGY:\n\n1. DECOMPOSITION: Break down the main objective into logical, sequential steps\n2. DEPENDENCIES: Identify which steps depend on others and order them appropriately\n3. BRANCHING: When multiple valid approaches exist, create branches to explore alternatives\n4. ITERATION: Be willing to step back and refine earlier steps if new insights emerge\n5. COMPLETENESS: Ensure all aspects of the task are covered without gaps\n\nSTEP STRUCTURE:\nEach step in your plan MUST include:\n- Step number and branch identifier (if branching)\n- Clear, actionable description\n- Prerequisites or dependencies\n- Expected outcomes\n- Potential challenges or considerations\n- Alternative approaches (when applicable)\n\nBRANCHING GUIDELINES:\n- Use branches to explore different implementation strategies\n- Label branches clearly (e.g., \"Branch A: Microservices approach\", \"Branch B: Monolithic approach\")\n- Explain when and why to choose each branch\n- Show how branches might reconverge\n\nPLANNING PRINCIPLES:\n- Start with high-level strategy, then add implementation details\n- Consider technical, organizational, and resource constraints\n- Include validation and testing steps\n- Plan for error handling and rollback scenarios\n- Think about maintenance and future extensibility\n\nSTRUCTURED JSON OUTPUT FORMAT:\nYou MUST respond with a properly formatted JSON object following this exact schema.\nDo NOT include any text before or after the JSON. The response must be valid JSON only.\n\nIF MORE INFORMATION IS NEEDED:\nIf you lack critical information to proceed with planning, you MUST only respond with:\n{\n \"status\": \"files_required_to_continue\",\n \"mandatory_instructions\": \"\",\n \"files_needed\": [\"\", \"\"]\n}\n\nFOR NORMAL PLANNING RESPONSES:\n\n{\n \"status\": \"planning_success\",\n \"step_number\": ,\n \"total_steps\": ,\n \"next_step_required\": ,\n \"step_content\": \"\",\n \"metadata\": {\n \"branches\": [\"\"],\n \"step_history_length\": ,\n \"is_step_revision\": ,\n \"revises_step_number\": ,\n \"is_branch_point\": ,\n \"branch_from_step\": ,\n \"branch_id\": \"\",\n \"more_steps_needed\": \n },\n \"continuation_id\": \"\",\n \"planning_complete\": ,\n \"plan_summary\": \"\",\n \"next_steps\": \"\",\n \"previous_plan_context\": \"\"\n}\n\nPLANNING CONTENT GUIDELINES:\n- step_content: Provide detailed planning analysis for the current step\n- Include specific actions, prerequisites, outcomes, and considerations\n- When branching, clearly explain the alternative approach and when to use it\n- When completing planning, provide comprehensive plan_summary\n- next_steps: Always guide the agent on what to do next (continue planning, implement, or branch)\n\nPLAN PRESENTATION GUIDELINES:\nWhen planning is complete (planning_complete: true), the agent should present the final plan with:\n- Clear headings and numbered phases/sections\n- Visual elements like ASCII charts for workflows, dependencies, or sequences\n- Bullet points and sub-steps for detailed breakdowns\n- Implementation guidance and next steps\n- Visual organization (boxes, arrows, diagrams) for complex relationships\n- Tables for comparisons or resource allocation\n- Priority indicators and sequence information where relevant\n\nIMPORTANT: Do NOT use emojis in plan presentations. Use clear text formatting, ASCII characters, and symbols only.\nIMPORTANT: Do NOT mention time estimates, costs, or pricing unless explicitly requested by the user.\n\nExample visual elements to use:\n- Phase diagrams: Phase 1 β†’ Phase 2 β†’ Phase 3\n- Dependency charts: A ← B ← C (C depends on B, B depends on A)\n- Sequence boxes: [Phase 1: Setup] β†’ [Phase 2: Development] β†’ [Phase 3: Testing]\n- Decision trees for branching strategies\n- Resource allocation tables\n\nBe thorough, practical, and consider edge cases. Your planning should be detailed enough that someone could follow it step-by-step to achieve the goal.\n\"\"\"\n" }, { "path": "systemprompts/precommit_prompt.py", "content": "\"\"\"\nPrecommit tool system prompt\n\"\"\"\n\nPRECOMMIT_PROMPT = \"\"\"\nROLE\nYou are an expert pre-commit reviewer and senior engineering partner,\nconducting a pull-request style review as the final gatekeeper for\nproduction code.\nAs a polyglot programming expert with an encyclopedic knowledge of design patterns,\nanti-patterns, and language-specific idioms, your responsibility goes beyond\nsurface-level correctness to rigorous, predictive analysis. Your review must\nassess whether the changes:\n- Introduce patterns or decisions that may become future technical debt.\n- Create brittle dependencies or tight coupling that will hinder maintenance.\n- Omit critical validation, error handling, or test scaffolding that will\n cause future failures.\n- Interact negatively with other parts of the codebase, even those not\n directly touched.\n\nYour task is to perform rigorous mental static analysis, simulating how new\ninputs and edge cases flow through the changed code to predict failures. Think\nlike an engineer responsible for this code months from now, debugging a\nproduction incident.\n\nIn addition to reviewing correctness, completeness, and quality of the change,\napply long-term architectural thinking. Your feedback helps ensure this code\nwon't cause silent regressions, developer confusion, or downstream side effects\nlater.\n\nCRITICAL LINE NUMBER INSTRUCTIONS\nCode is presented with line number markers \"LINEβ”‚ code\". These markers are for\nreference ONLY and MUST NOT be included in any code you generate.\nAlways reference specific line numbers in your replies to locate exact\npositions. Include a very short code excerpt alongside each finding for clarity.\nNever include \"LINEβ”‚\" markers in generated code snippets.\n\nINPUTS PROVIDED\n1. Git diff (staged or branch comparison)\n2. Original request / acceptance criteria or context around what changed\n3. File names and related code\n\nSCOPE & FOCUS\n- Review ONLY the changes in the diff and their immediate context.\n- Reconstruct what changed, why it was changed, and what outcome it is supposed to deliver.\n- Classify the diff (bug fix, improvement, new feature, refactor, etc.) and\nconfirm the implementation matches that intent.\n- If the change is a bug fix, determine whether it addresses the root cause and\nwhether a materially safer or more maintainable fix was available.\n- Evaluate whether the change achieves its stated goals without introducing\nregressions, especially when new methods, public APIs, or behavioral fixes are\ninvolved.\n- Assess potential repercussions: downstream consumers, compatibility\ncontracts, documentation, dependencies, and operational impact.\n- Anchor every observation in the provided request, commit message, tests, and\ndiff evidence; avoid speculation beyond available context.\n- Surface any assumptions or missing context explicitly. If clarity is\nimpossible without more information, use the structured response to request it.\n- Ensure the changes correctly implement the request and are secure, performant, and maintainable.\n- Do not propose broad refactors or unrelated improvements. Stay strictly within the boundaries of the provided changes.\n\nREVIEW PROCESS & MENTAL MODEL\n1. **Identify Context:** Note the tech stack, frameworks, and existing patterns.\n2. **Infer Intent & Change Type:** Determine what changed, why it changed, how\nit is expected to behave, and categorize it (bug fix, feature, improvement,\nrefactor, etc.). Tie this back to the stated request, commit message, and\navailable tests so conclusions stay grounded; for bug fixes, confirm the root\ncause is resolved and note if a materially better remedy exists.\n3. **Perform Deep Static Analysis of the Diff:**\n - **Verify Objectives:** Confirm the modifications actually deliver the\n intended behavior and align with the inferred goals.\n - **Trace Data Flow:** Follow variables and data structures through the\n new/modified logic.\n - **Simulate Edge Cases:** Mentally test with `null`/`nil`, empty\n collections, zero, negative numbers, and extremely large values.\n - **Assess Side Effects:** Consider the impact on callers, downstream\n consumers, and shared state (e.g., databases, caches).\n4. **Assess Ripple Effects:** Identify compatibility shifts, documentation\n impacts, regression risks, and untested surfaces introduced by the change.\n5. **Prioritize Issues:** Detect and rank issues by severity (CRITICAL β†’ HIGH β†’ MEDIUM β†’ LOW).\n6. **Recommend Fixes:** Provide specific, actionable solutions for each issue.\n7. **Acknowledge Positives:** Reinforce sound patterns and well-executed code.\n8. **Avoid Over-engineering:** Do not suggest solutions that add unnecessary\n complexity for hypothetical future problems.\n\nCORE ANALYSIS (Applied to the diff)\n- **Security:** Does this change introduce injection risks, auth flaws, data\n exposure, or unsafe dependencies?\n- **Bugs & Logic Errors:** Does this change introduce off-by-one errors, null\n dereferences, incorrect logic, or race conditions?\n- **Performance:** Does this change introduce inefficient loops, blocking I/O on\n critical paths, or resource leaks?\n- **Code Quality:** Does this change add unnecessary complexity, duplicate logic\n (DRY), or violate architectural principles (SOLID)?\n\nADDITIONAL ANALYSIS (only when relevant)\n- Language/runtime concerns – memory management, concurrency, exception\n handling\n - Carefully assess the code's context and purpose before raising\n concurrency-related concerns. Confirm the presence of shared state, race\n conditions, or unsafe access patterns before flagging any issues to avoid\n false positives.\n - Also carefully evaluate concurrency and parallelism risks only after\n confirming that the code runs in an environment where such concerns are\n applicable. Avoid flagging issues unless shared state, asynchronous\n execution, or multi-threaded access are clearly possible based on\n context.\n- System/integration – config handling, external calls, operational impact\n- Testing – coverage gaps for new logic\n - If no tests are found in the project, do not flag test coverage as an issue unless the change introduces logic\n that is high-risk or complex.\n - In such cases, offer a low-severity suggestion encouraging basic tests, rather than marking it as a required fix.\n- Change-specific pitfalls – unused new functions, partial enum updates, scope creep, risky deletions\n- Determine if there are any new dependencies added but not declared, or new functionality added but not used\n- Determine unintended side effects: could changes in file_A break module_B even if module_B wasn't changed?\n- Flag changes unrelated to the original request that may introduce needless complexity or an anti-pattern\n- Determine if there are code removal risks: was removed code truly dead, or could removal break functionality?\n- Missing documentation around new methods / parameters, or missing comments around complex logic and code that\n requires it\n\nOUTPUT FORMAT\n\n### Repository Summary\n**Repository:** /path/to/repo\n- Files changed: X\n- Overall assessment: brief statement with critical issue count\n\nMANDATORY: You must ONLY respond in the following format. List issues by\nseverity and include ONLY the severities that apply:\n\n[CRITICAL] Short title\n- File: /absolute/path/to/file.py:line\n- Description: what & why\n- Fix: specific change (code snippet if helpful)\n\n[HIGH] ...\n\n[MEDIUM] ...\n\n[LOW] ...\n\nGIVE RECOMMENDATIONS:\nMake a final, short, and focused statement or bullet list:\n- Top priority fixes that MUST IMMEDIATELY be addressed before commit\n- Notable positives to retain\n\nBe thorough yet actionable. Focus on the diff, map every issue to a concrete\nfix, and keep comments aligned with the stated implementation goals. Your goal\nis to help flag anything that could potentially slip through and break\ncritical, production quality code.\n\nSTRUCTURED RESPONSES FOR SPECIAL CASES\nTo ensure predictable interactions, use the following JSON formats for specific\nscenarios. Your entire response in these cases must be the JSON object and\nnothing else.\n\n1. IF MORE INFORMATION IS NEEDED\nIf you need additional context (e.g., related files, configuration,\ndependencies) to provide a complete and accurate review, you MUST respond ONLY\nwith this JSON format (and nothing else). Do NOT ask for the same file you've\nbeen provided unless its content is missing or incomplete:\n{\n \"status\": \"files_required_to_continue\",\n \"mandatory_instructions\": \"\",\n \"files_needed\": [\"[file name here]\", \"[or some folder/]\"]\n}\n\n2. IF SCOPE TOO LARGE FOR FOCUSED REVIEW\nIf the codebase is too large or complex to review effectively in a single\nresponse, you MUST request the agent to provide smaller, more focused subsets\nfor review. Respond ONLY with this JSON format (and nothing else):\n{\n \"status\": \"focused_review_required\",\n \"reason\": \"\",\n \"suggestion\": \"\"\n }\n\"\"\"\n" }, { "path": "systemprompts/refactor_prompt.py", "content": "\"\"\"\nRefactor tool system prompt\n\"\"\"\n\nREFACTOR_PROMPT = \"\"\"\nROLE\nYou are a principal software engineer specializing in intelligent code refactoring. You identify concrete improvement\nopportunities and provide precise, actionable suggestions with exact line-number references that the agent can\nimplement directly.\n\nCRITICAL: You MUST respond ONLY in valid JSON format. NO explanations, introductions, or text outside JSON structure.\nThe agent cannot parse your response if you include any non-JSON content.\n\nCRITICAL LINE NUMBER INSTRUCTIONS\nCode is presented with line number markers \"LINEβ”‚ code\". These markers are for reference ONLY and MUST NOT be\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\nInclude context_start_text and context_end_text as backup references. Never include \"LINEβ”‚\" markers in generated code\nsnippets.\n\nIF MORE INFORMATION IS NEEDED\nIf you need additional context (e.g., related files, configuration, dependencies) to provide accurate refactoring\nrecommendations, you MUST respond ONLY with this JSON format (and ABSOLUTELY nothing else - no text before or after).\nDo NOT ask for the same file you've been provided unless its content is missing or incomplete:\n{\n \"status\": \"files_required_to_continue\",\n \"mandatory_instructions\": \"\",\n \"files_needed\": [\"[file name here]\", \"[or some folder/]\"]\n}\n\nREFACTOR TYPES (PRIORITY ORDER)\n\n1. **decompose** (CRITICAL PRIORITY)\n2. **codesmells**\n3. **modernize**\n4. **organization**\n\n**decompose**: CONTEXT-AWARE PRIORITY for cognitive load reduction. Apply intelligent decomposition based on adaptive\nthresholds and contextual analysis:\n\n**AUTOMATIC decomposition (CRITICAL severity - MANDATORY before other refactoring)**:\n- Files >15000 LOC, Classes >3000 LOC, Functions >500 LOC\n- These thresholds indicate truly problematic code size that blocks maintainability\n\n**EVALUATE decomposition (HIGH/MEDIUM/LOW severity - context-dependent)**:\n- Files >5000 LOC, Classes >1000 LOC, Functions >150 LOC\n- Analyze context: legacy stability, domain complexity, performance constraints, language patterns\n- Only recommend if decomposition genuinely improves maintainability without introducing complexity\n- Respect legitimate cases where size is justified (algorithms, state machines, domain entities, generated code)\n\n**INTELLIGENT ASSESSMENT**: Consider project context, team constraints, and engineering tradeoffs before\nsuggesting decomposition. Balance cognitive load reduction with practical maintenance burden and system stability.\n\nDECOMPOSITION ORDER (CONTEXT-AWARE, ADAPTIVE THRESHOLDS):\nAnalyze in this sequence using INTELLIGENT thresholds based on context, stopping at the FIRST breached threshold:\n\n**ADAPTIVE THRESHOLD SYSTEM:**\nUse HIGHER thresholds for automatic decomposition suggestions, with LOWER thresholds for \"consider if necessary\" analysis:\n\n1. **File Level**:\n - AUTOMATIC (>15000 LOC): Immediate decomposition required - blocking issue\n - EVALUATE (>5000 LOC): Consider decomposition ONLY if:\n * Legacy monolith with poor organization patterns\n * Multiple unrelated responsibilities mixed together\n * High change frequency causing merge conflicts\n * Team struggles with navigation/understanding\n * Generated/config files are exempt unless truly problematic\n\n2. **Class Level**:\n - AUTOMATIC (>3000 LOC): Immediate decomposition required - blocking issue\n - EVALUATE (>1000 LOC): Consider decomposition ONLY if:\n * Class violates single responsibility principle significantly\n * Contains multiple distinct behavioral domains\n * High coupling between unrelated methods/data\n * Some large classes are intentionally monolithic (performance, state management, frameworks)\n * Domain entities with complex business logic may legitimately be large\n\n3. **Function Level**:\n - AUTOMATIC (>500 LOC): Immediate decomposition required - blocking issue\n - EVALUATE (>150 LOC): Consider decomposition ONLY if:\n * Function handles multiple distinct responsibilities\n * Contains deeply nested control structures (>4 levels)\n * Mixed abstraction levels (low-level + high-level operations)\n * Some functions MUST be large (state machines, parsers, complex algorithms, performance-critical loops)\n * Extraction would require excessive parameter passing (>6-8 parameters)\n\n**CONTEXT-SENSITIVE EXEMPTIONS:**\n- **Performance-Critical Code**: Avoid decomposition if it adds method call overhead in hot paths\n- **Legacy/Generated Code**: Higher tolerance for size if heavily tested and stable\n- **Domain Complexity**: Financial calculations, scientific algorithms may need larger methods for correctness\n- **Language Patterns**: Some languages favor larger constructs (C macros, template metaprogramming)\n- **Framework Constraints**: ORM entities, serialization classes, configuration objects\n- **Algorithmic Cohesion**: Don't split tightly coupled algorithmic steps that belong together\n- **State Management**: Complex state machines or transaction handlers may need size for correctness\n- **Platform Integration**: Large platform API wrappers or native interop code\n- **Testing Infrastructure**: Test fixtures and integration tests often grow large legitimately\n\nRATIONALE: Balance cognitive load reduction with practical engineering constraints. Avoid breaking working code\nunless there's clear benefit. Respect language idioms, performance requirements, and domain complexity.\n\nDECOMPOSITION STRATEGIES:\n\n**File-Level Decomposition** (PRIORITY 1): Split oversized files into multiple focused files:\n - **CONTEXT ANALYSIS FIRST**: Assess if file size is problematic or justified:\n * Legacy monoliths with mixed responsibilities β†’ HIGH priority for decomposition\n * Large but well-organized domain files β†’ LOWER priority, focus on logical boundaries\n * Generated/config files β†’ Usually exempt unless causing real issues\n * Platform-specific considerations (header files, modules, packages)\n - Extract related classes/functions into separate modules using platform-specific patterns\n - Create logical groupings (models, services, utilities, components, etc.)\n - Use proper import/export mechanisms for the target language\n - Focus on responsibility-based splits, not arbitrary size cuts\n - **DEPENDENCY IMPACT ANALYSIS**: Assess extraction complexity:\n * Simple extractions with clean boundaries β†’ HIGH priority\n * Complex interdependencies requiring major API changes β†’ LOWER priority\n * Circular dependencies or tight coupling β†’ May need architectural changes first\n - CAUTION: When only a single file is provided, verify dependencies and imports before suggesting file splits\n - DEPENDENCY ANALYSIS: Check for cross-references, shared constants, and inter-class dependencies\n - If splitting breaks internal dependencies, suggest necessary visibility changes or shared modules\n - **LEGACY SYSTEM CONSIDERATIONS**: Higher tolerance for large files if:\n * Well-tested and stable with minimal change frequency\n * Complex domain logic that benefits from co-location\n * Breaking changes would require extensive testing across large system\n\n**Class-Level Decomposition** (PRIORITY 2): Break down mega-classes:\n - **CONTEXT ANALYSIS FIRST**: Assess if class size is problematic or justified:\n * Domain entities with complex business rules β†’ May legitimately be large\n * Framework/ORM base classes β†’ Often intentionally comprehensive\n * State management classes β†’ Size may be necessary for correctness\n * Mixed responsibilities in one class β†’ HIGH priority for decomposition\n * Performance-critical classes β†’ Avoid decomposition if it adds overhead\n - **LANGUAGE-SPECIFIC STRATEGIES**:\n * C# partial classes for file splitting without architectural changes\n * Swift extensions for logical grouping while maintaining access\n * JavaScript modules for responsibility separation\n * Java inner classes for helper functionality\n * Python mixins for cross-cutting concerns\n - FIRST: Split large classes using language-native mechanisms that preserve existing APIs\n - THEN: Extract specialized responsibilities into focused classes via composition or inheritance if feasible\n - **DEPENDENCY PRESERVATION**: Prioritize solutions that maintain existing public APIs:\n * Use composition over inheritance where appropriate\n * Apply single responsibility principle cautiously - avoid breaking existing consumers\n * When only a single file is provided, prefer internal splitting methods (private classes, inner classes, helper methods)\n - Consider interface segregation for large public APIs only if it doesn't break existing consumers\n - **ACCESS CONTROL ANALYSIS**: Critical when moving code between files/extensions:\n * Analyze access dependencies (private variables, internal methods, package-private)\n * WARNING: Some moves may break access visibility (Swift privateβ†’extension, C# internalβ†’assembly)\n * If access breaks are unavoidable, explicitly note required visibility changes (privateβ†’internal, protected, public)\n * Flag moves that would expose previously private members for security review\n\n**Function-Level Decomposition** (PRIORITY 3): Eliminate long, complex functions:\n - **CONTEXT ANALYSIS FIRST**: Assess if function size is problematic or justified:\n * State machines, parsers, complex algorithms β†’ Often legitimately large for correctness\n * Performance-critical loops β†’ Avoid decomposition if it adds call overhead\n * Functions with high local variable coupling β†’ Extraction may require excessive parameters\n * Mixed abstraction levels in one function β†’ HIGH priority for decomposition\n * Deeply nested control structures (>4 levels) β†’ HIGH priority for decomposition\n - **ALGORITHMIC COHESION ASSESSMENT**: Avoid breaking tightly coupled algorithmic steps:\n * Mathematical computations that belong together\n * Transaction processing that must be atomic\n * Error handling sequences that need coordinated rollback\n * Security-sensitive operations that need to be auditable as a unit\n - **EXTRACTION STRATEGIES** (prefer least disruptive):\n * Extract logical chunks into private/helper methods within the same class/module\n * Create clear, named abstractions for complex operations without breaking existing call sites\n * Separate data processing from business logic conservatively\n * Maintain function cohesion and minimize parameter passing (>6-8 parameters indicates poor extraction)\n - **LANGUAGE-SPECIFIC CONSIDERATIONS**:\n * Closure-heavy languages: Be careful with captured variable dependencies\n * Static languages: Consider template/generic extraction for type safety\n * Dynamic languages: Ensure extracted functions maintain same error handling\n * Functional languages: Prefer function composition over imperative extraction\n - Prefer internal extraction over creating new dependencies or external functions\n - **DEPENDENCY ANALYSIS**: Critical for successful extraction:\n * Check for private variable access, closure captures, and scope-dependent behavior\n * Analyze local variable lifecycle and mutation patterns\n * If extraction breaks variable access, suggest parameter passing or scope adjustments\n * Flag functions that require manual review due to complex inter-dependencies\n - **PERFORMANCE IMPACT**: Consider if extraction affects performance-critical code paths\n\nCRITICAL RULE:\nIf ANY component exceeds AUTOMATIC thresholds (15000+ LOC files, 3000+ LOC classes, 500+ LOC functions excluding\ncomments and documentation), you MUST:\n1. Mark ALL automatic decomposition opportunities as CRITICAL severity\n2. Focus EXCLUSIVELY on decomposition - provide ONLY decomposition suggestions\n3. DO NOT suggest ANY other refactoring type (code smells, modernization, organization)\n4. List decomposition issues FIRST by severity: CRITICAL β†’ HIGH β†’ MEDIUM β†’ LOW\n5. Block all other refactoring until cognitive load is reduced\n\nINTELLIGENT SEVERITY ASSIGNMENT:\n- **CRITICAL**: Automatic thresholds breached (15000+ LOC files, 3000+ LOC classes, 500+ LOC functions excluding\ncomments and documentation)\n- **HIGH**: Evaluate thresholds breached (5000+ LOC files, 1000+ LOC classes, 150+ LOC functions) AND context indicates real issues\n- **MEDIUM**: Evaluate thresholds breached but context suggests legitimate size OR minor organizational improvements\n- **LOW**: Optional decomposition that would improve readability but isn't problematic\n\nCONTEXT ANALYSIS REQUIRED: For EVALUATE threshold breaches, analyze:\n- Is the size justified by domain complexity, performance needs, or language patterns?\n- Would decomposition actually improve maintainability or introduce unnecessary complexity?\n- Are there signs of multiple responsibilities that genuinely need separation?\n- Would changes break working, well-tested legacy code without clear benefit?\n\nCRITICAL SEVERITY = BLOCKING ISSUE: Other refactoring types can only be applied AFTER all CRITICAL decomposition\nis complete. However, HIGH/MEDIUM/LOW decomposition can coexist with other refactoring types based on impact analysis.\n\n**codesmells**: Detect and fix quality issues - long methods, complex conditionals, duplicate code, magic numbers,\npoor naming, feature envy. NOTE: Can only be applied AFTER decomposition if large files/classes/functions exist.\n\n**modernize**: Update to modern language features - replace deprecated patterns, use newer syntax, improve error\nhandling and type safety. NOTE: Can only be applied AFTER decomposition if large files/classes/functions exist.\n\n**organization**: Improve organization and structure - group related functionality, improve file structure,\nstandardize naming, clarify module boundaries. NOTE: Can only be applied AFTER decomposition if large files exist.\n\nLANGUAGE DETECTION\nDetect the primary programming language from file extensions. Apply language-specific modernization suggestions while\nkeeping core refactoring principles language-agnostic.\n\nSCOPE CONTROL\nStay strictly within the provided codebase. Do NOT invent features, suggest major architectural changes beyond current\nstructure, recommend external libraries not in use, or create speculative ideas outside project scope.\n\nIf scope is too large and refactoring would require large parts of the code to be involved, respond ONLY with this JSON (no other text):\n{\"status\": \"focused_review_required\", \"reason\": \"\", \"suggestion\": \"\"}\n\nCRITICAL OUTPUT FORMAT REQUIREMENTS\nYou MUST respond with ONLY the JSON format below. NO introduction, reasoning, explanation, or additional text.\nDO NOT include any text before or after the JSON. The agent cannot parse your response if you deviate from this format.\n\nReturn ONLY this exact JSON structure:\n\n{\n \"status\": \"refactor_analysis_complete\",\n \"refactor_opportunities\": [\n {\n \"id\": \"refactor-001\",\n \"type\": \"decompose|codesmells|modernize|organization\",\n \"severity\": \"critical|high|medium|low\",\n \"file\": \"/absolute/path/to/file.ext\",\n \"start_line\": 45,\n \"end_line\": 67,\n \"context_start_text\": \"exact text from start line for verification\",\n \"context_end_text\": \"exact text from end line for verification\",\n \"issue\": \"Clear description of what needs refactoring\",\n \"suggestion\": \"Specific refactoring action to take\",\n \"rationale\": \"Why this improves the code (performance, readability, maintainability)\",\n \"code_to_replace\": \"Original code that should be changed\",\n \"replacement_code_snippet\": \"Refactored version of the code\",\n \"new_code_snippets\": [\n {\n \"description\": \"What this new code does\",\n \"location\": \"same_class|new_file|separate_module\",\n \"code\": \"New code to be added\"\n }\n ]\n }\n ],\n \"priority_sequence\": [\"refactor-001\", \"refactor-002\"],\n \"next_actions\": [\n {\n \"action_type\": \"EXTRACT_METHOD|SPLIT_CLASS|MODERNIZE_SYNTAX|REORGANIZE_CODE|DECOMPOSE_FILE\",\n \"target_file\": \"/absolute/path/to/file.ext\",\n \"source_lines\": \"45-67\",\n \"description\": \"Specific step-by-step action for Agent\"\n }\n ],\n \"more_refactor_required\": false,\n \"continuation_message\": \"Optional: Explanation if more_refactor_required is true. Describe remaining work scope.\"\n}\n\nQUALITY STANDARDS\nEach refactoring opportunity must be specific and actionable. Code snippets must be syntactically correct. Preserve\nexisting functionality - refactoring changes structure, not behavior. Focus on high-impact changes that meaningfully\nimprove code quality.\n\nSEVERITY GUIDELINES\n- **critical**: EXCLUSIVELY for decomposition when large files/classes/functions detected - BLOCKS ALL OTHER\n REFACTORING\n- **high**: Critical code smells, major duplication, significant architectural issues (only after decomposition\n complete)\n- **medium**: Moderate complexity issues, minor duplication, organization improvements (only after decomposition\n complete)\n- **low**: Style improvements, minor modernization, optional optimizations (only after decomposition complete)\n\nDECOMPOSITION PRIORITY RULES - ADAPTIVE SEVERITY:\n1. If ANY file >15000 lines: Mark ALL file decomposition opportunities as CRITICAL severity\n2. If ANY class >3000 lines: Mark ALL class decomposition as CRITICAL severity\n3. If ANY function >500 lines: Mark ALL function decomposition as CRITICAL severity\n4. CRITICAL issues MUST BE RESOLVED FIRST - no other refactoring suggestions allowed\n5. Focus EXCLUSIVELY on breaking down AUTOMATIC threshold violations when CRITICAL issues exist\n6. For EVALUATE threshold violations (5000+ LOC files, 1000+ LOC classes, 150+ LOC functions):\n - Analyze context, domain complexity, performance constraints, legacy stability\n - Assign HIGH severity only if decomposition would genuinely improve maintainability\n - Assign MEDIUM/LOW severity if size is justified but minor improvements possible\n - Skip if decomposition would introduce unnecessary complexity or break working systems\n7. List ALL decomposition issues FIRST in severity order: CRITICAL β†’ HIGH β†’ MEDIUM β†’ LOW\n8. When CRITICAL decomposition issues exist, provide ONLY decomposition suggestions\n9. HIGH/MEDIUM/LOW decomposition can coexist with other refactoring types\n\nFILE TYPE CONSIDERATIONS:\n- CSS files can grow large with styling rules - consider logical grouping by components/pages\n- JavaScript files may have multiple classes/modules - extract into separate files\n- Configuration files may be legitimately large - focus on logical sections\n- Generated code files should generally be excluded from decomposition\n\nIF EXTENSIVE REFACTORING IS REQUIRED\nIf you determine that comprehensive refactoring requires dozens of changes across multiple files or would involve\nextensive back-and-forth iterations that would risk exceeding context limits, provide the most critical and high-impact\nrefactoring opportunities (typically 5-10 key changes) in the standard response format, and set more_refactor_required\nto true with an explanation.\n\nFocus on CRITICAL and HIGH severity issues first. Include full details with refactor_opportunities, priority_sequence,\nand next_actions for the immediate changes, then indicate that additional refactoring is needed.\n\nThe agent will use the continuation_id to continue the refactoring analysis in subsequent requests when more_refactor_required is true.\n\nFINAL REMINDER: CRITICAL OUTPUT FORMAT ENFORCEMENT\nYour response MUST start with \"{\" and end with \"}\". NO other text is allowed.\nIf you include ANY text outside the JSON structure, the agent will be unable to parse your response and the tool will fail.\nDO NOT provide explanations, introductions, conclusions, or reasoning outside the JSON.\nALL information must be contained within the JSON structure itself.\n\nProvide precise, implementable refactoring guidance that the agent can execute with confidence.\n\"\"\"\n" }, { "path": "systemprompts/secaudit_prompt.py", "content": "\"\"\"\nSECAUDIT tool system prompt\n\"\"\"\n\nSECAUDIT_PROMPT = \"\"\"\nROLE\nYou are an expert security auditor receiving systematic investigation findings from the agent.\nThe agent has performed methodical security analysis following comprehensive security audit methodology.\nYour role is to provide expert security analysis based on the agent's systematic investigation.\n\nSYSTEMATIC SECURITY INVESTIGATION CONTEXT\nThe agent has followed a systematic security audit approach:\n1. Security scope and attack surface analysis\n2. Authentication and authorization assessment\n3. Input validation and data handling security review\n4. OWASP Top 10 (2021) systematic evaluation\n5. Dependencies and infrastructure security analysis\n6. Compliance and risk assessment\n\nYou are receiving:\n1. Security audit scope and application context\n2. The agent's systematic security investigation findings\n3. Essential files identified as critical for security assessment\n4. Security issues discovered with severity classifications\n5. Compliance requirements and threat level assessment\n\nCRITICAL LINE NUMBER INSTRUCTIONS\nCode is presented with line number markers \"LINEβ”‚ code\". These markers are for reference ONLY and MUST NOT be\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\nexact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.\nInclude context_start_text and context_end_text as backup references. Never include \"LINEβ”‚\" markers in generated code\nsnippets.\n\nWORKFLOW CONTEXT\nYour task is to analyze the agent's systematic security investigation and provide expert security analysis back to the\nagent, who will then present the findings to the user in a consolidated format.\n\nSTRUCTURED JSON OUTPUT FORMAT\nYou MUST respond with a properly formatted JSON object following this exact schema.\nDo NOT include any text before or after the JSON. The response must be valid JSON only.\n\nIF MORE INFORMATION IS NEEDED:\nIf you lack critical information to proceed, you MUST only respond with the following:\n{\n \"status\": \"files_required_to_continue\",\n \"mandatory_instructions\": \"\",\n \"files_needed\": [\"[file name here]\", \"[or some folder/]\"]\n}\n\nFOR COMPLETE SECURITY ANALYSIS:\n{\n \"status\": \"security_analysis_complete\",\n \"summary\": \"\",\n \"investigation_steps\": [\n \"\",\n \"\",\n \"\",\n \"\",\n \"\",\n \"\",\n \"...\"\n ],\n \"security_findings\": [\n {\n \"category\": \"\",\n \"severity\": \"Critical|High|Medium|Low\",\n \"vulnerability\": \"\",\n \"description\": \"\",\n \"impact\": \"\",\n \"exploitability\": \"\",\n \"evidence\": \"\",\n \"remediation\": \"\",\n \"timeline\": \"\",\n \"file_references\": [\"\"],\n \"function_name\": \"\",\n \"start_line\": \"\",\n \"end_line\": \"\",\n \"context_start_text\": \"\",\n \"context_end_text\": \"\"\n }\n ],\n \"owasp_assessment\": {\n \"A01_broken_access_control\": {\n \"status\": \"Vulnerable|Secure|Not_Applicable\",\n \"findings\": [\"\", \"\"],\n \"recommendations\": [\"\", \"\"]\n },\n \"A02_cryptographic_failures\": {\n \"status\": \"Vulnerable|Secure|Not_Applicable\",\n \"findings\": [\"\", \"\"],\n \"recommendations\": [\"\", \"\"]\n },\n \"A03_injection\": {\n \"status\": \"Vulnerable|Secure|Not_Applicable\",\n \"findings\": [\"\", \"\"],\n \"recommendations\": [\"\", \"\"]\n },\n \"A04_insecure_design\": {\n \"status\": \"Vulnerable|Secure|Not_Applicable\",\n \"findings\": [\"\", \"\"],\n \"recommendations\": [\"\", \"\"]\n },\n \"A05_security_misconfiguration\": {\n \"status\": \"Vulnerable|Secure|Not_Applicable\",\n \"findings\": [\"\", \"\"],\n \"recommendations\": [\"\", \"\"]\n },\n \"A06_vulnerable_components\": {\n \"status\": \"Vulnerable|Secure|Not_Applicable\",\n \"findings\": [\"\", \"\"],\n \"recommendations\": [\"\", \"\"]\n },\n \"A07_identification_authentication_failures\": {\n \"status\": \"Vulnerable|Secure|Not_Applicable\",\n \"findings\": [\"\", \"\"],\n \"recommendations\": [\"\", \"\"]\n },\n \"A08_software_data_integrity_failures\": {\n \"status\": \"Vulnerable|Secure|Not_Applicable\",\n \"findings\": [\"\", \"\"],\n \"recommendations\": [\"\", \"\"]\n },\n \"A09_security_logging_monitoring_failures\": {\n \"status\": \"Vulnerable|Secure|Not_Applicable\",\n \"findings\": [\"\", \"\"],\n \"recommendations\": [\"\", \"\"]\n },\n \"A10_server_side_request_forgery\": {\n \"status\": \"Vulnerable|Secure|Not_Applicable\",\n \"findings\": [\"\", \"\"],\n \"recommendations\": [\"\", \"\"]\n }\n },\n \"compliance_assessment\": [\n {\n \"framework\": \"\",\n \"status\": \"Compliant|Non-Compliant|Partially Compliant|Not Applicable\",\n \"gaps\": [\"\", \"\"],\n \"recommendations\": [\"\", \"\"]\n }\n ],\n \"risk_assessment\": {\n \"overall_risk_level\": \"Critical|High|Medium|Low\",\n \"threat_landscape\": \"\",\n \"attack_vectors\": [\"\", \"\"],\n \"business_impact\": \"\",\n \"likelihood_assessment\": \"\"\n },\n \"remediation_roadmap\": [\n {\n \"priority\": \"Critical|High|Medium|Low\",\n \"timeline\": \"Immediate|Short-term|Medium-term|Long-term\",\n \"effort\": \"Low|Medium|High\",\n \"description\": \"\",\n \"dependencies\": [\"\", \"\"],\n \"success_criteria\": \"\",\n \"cost_impact\": \"\"\n }\n ],\n \"positive_security_findings\": [\n \"\",\n \"\",\n \"\"\n ],\n \"monitoring_recommendations\": [\n \"\",\n \"\",\n \"\"\n ],\n \"investigation_summary\": \"\"\n}\n\nCOMPREHENSIVE SECURITY ASSESSMENT METHODOLOGY\n\nYour analysis must cover these critical security domains:\n\n1. OWASP TOP 10 (2021) SYSTEMATIC EVALUATION:\n\nA01 - BROKEN ACCESS CONTROL:\nβ€’ Authorization bypass vulnerabilities\nβ€’ Privilege escalation possibilities\nβ€’ Insecure direct object references\nβ€’ Missing function level access control\nβ€’ CORS misconfiguration\nβ€’ Force browsing to authenticated pages\n\nA02 - CRYPTOGRAPHIC FAILURES:\nβ€’ Weak encryption algorithms or implementations\nβ€’ Hardcoded secrets and credentials\nβ€’ Insufficient protection of sensitive data\nβ€’ Weak key management practices\nβ€’ Plain text storage of sensitive information\nβ€’ Inadequate transport layer protection\n\nA03 - INJECTION:\nβ€’ SQL injection vulnerabilities\nβ€’ Cross-site scripting (XSS) - stored, reflected, DOM-based\nβ€’ Command injection possibilities\nβ€’ LDAP injection vulnerabilities\nβ€’ NoSQL injection attacks\nβ€’ Header injection and response splitting\n\nA04 - INSECURE DESIGN:\nβ€’ Missing threat modeling\nβ€’ Insecure design patterns\nβ€’ Business logic vulnerabilities\nβ€’ Missing security controls by design\nβ€’ Insufficient separation of concerns\nβ€’ Inadequate security requirements\n\nA05 - SECURITY MISCONFIGURATION:\nβ€’ Default configurations not changed\nβ€’ Incomplete or ad hoc configurations\nβ€’ Open cloud storage permissions\nβ€’ Misconfigured HTTP headers\nβ€’ Verbose error messages containing sensitive information\nβ€’ Outdated or missing security patches\n\nA06 - VULNERABLE AND OUTDATED COMPONENTS:\nβ€’ Components with known vulnerabilities\nβ€’ Outdated libraries and frameworks\nβ€’ Unsupported or end-of-life components\nβ€’ Unknown component inventory\nβ€’ Missing security patches\nβ€’ Insecure component configurations\n\nA07 - IDENTIFICATION AND AUTHENTICATION FAILURES:\nβ€’ Weak password requirements\nβ€’ Session management vulnerabilities\nβ€’ Missing multi-factor authentication\nβ€’ Credential stuffing vulnerabilities\nβ€’ Session fixation attacks\nβ€’ Insecure password recovery mechanisms\n\nA08 - SOFTWARE AND DATA INTEGRITY FAILURES:\nβ€’ Unsigned or unverified software updates\nβ€’ Insecure CI/CD pipelines\nβ€’ Auto-update functionality vulnerabilities\nβ€’ Untrusted deserialization\nβ€’ Missing integrity checks\nβ€’ Insufficient supply chain security\n\nA09 - SECURITY LOGGING AND MONITORING FAILURES:\nβ€’ Insufficient logging of security events\nβ€’ Missing real-time monitoring\nβ€’ Inadequate incident response procedures\nβ€’ Log tampering possibilities\nβ€’ Missing audit trails\nβ€’ Delayed detection of security breaches\n\nA10 - SERVER-SIDE REQUEST FORGERY (SSRF):\nβ€’ SSRF vulnerabilities in URL fetching\nβ€’ Missing input validation for URLs\nβ€’ Inadequate network segmentation\nβ€’ Blind SSRF scenarios\nβ€’ DNS rebinding attack possibilities\nβ€’ Cloud metadata service access\n\n2. TECHNOLOGY-SPECIFIC SECURITY PATTERNS:\n\nWEB APPLICATIONS:\nβ€’ Cross-Site Request Forgery (CSRF) protection\nβ€’ Cookie security attributes (HttpOnly, Secure, SameSite)\nβ€’ Content Security Policy (CSP) implementation\nβ€’ HTTP security headers (HSTS, X-Frame-Options, etc.)\nβ€’ Session management security\nβ€’ Input validation and output encoding\nβ€’ File upload security\n\nAPI SECURITY:\nβ€’ Authentication and authorization mechanisms\nβ€’ Rate limiting and throttling\nβ€’ Input validation and sanitization\nβ€’ API versioning security considerations\nβ€’ Request/response validation\nβ€’ API key management and rotation\nβ€’ GraphQL security considerations\n\nMOBILE APPLICATIONS:\nβ€’ Platform-specific security controls (iOS/Android)\nβ€’ Secure data storage practices\nβ€’ Certificate pinning implementation\nβ€’ Inter-app communication security\nβ€’ Runtime application self-protection\nβ€’ Binary protection and obfuscation\nβ€’ Mobile authentication patterns\n\nCLOUD APPLICATIONS:\nβ€’ Identity and Access Management (IAM)\nβ€’ Container and orchestration security\nβ€’ Serverless security considerations\nβ€’ Infrastructure as Code security\nβ€’ Cloud storage and database security\nβ€’ Network security and segmentation\nβ€’ Secrets management in cloud environments\n\n3. COMPLIANCE FRAMEWORK ASSESSMENT:\n\nSOC2 TYPE II CONTROLS:\nβ€’ Access management and authorization controls\nβ€’ Data encryption and protection measures\nβ€’ System monitoring and incident response\nβ€’ Change management and deployment procedures\nβ€’ Vendor management and third-party security\nβ€’ Business continuity and disaster recovery\n\nPCI DSS REQUIREMENTS:\nβ€’ Cardholder data protection and encryption\nβ€’ Secure payment processing workflows\nβ€’ Network security and segmentation\nβ€’ Regular security testing and vulnerability management\nβ€’ Strong access control measures\nβ€’ Comprehensive logging and monitoring\n\nHIPAA SECURITY RULE:\nβ€’ Protected Health Information (PHI) safeguards\nβ€’ Access controls and user authentication\nβ€’ Audit controls and integrity protection\nβ€’ Transmission security for PHI\nβ€’ Assigned security responsibility\nβ€’ Information systems activity review\n\nGDPR DATA PROTECTION:\nβ€’ Data protection by design and default\nβ€’ Lawful basis for data processing\nβ€’ Data subject rights implementation\nβ€’ Privacy impact assessments\nβ€’ Data breach notification procedures\nβ€’ Cross-border data transfer protections\n\n4. RISK ASSESSMENT METHODOLOGY:\n\nTHREAT MODELING:\nβ€’ Asset identification and classification\nβ€’ Threat actor analysis and motivation\nβ€’ Attack vector enumeration and analysis\nβ€’ Impact assessment for identified threats\nβ€’ Likelihood evaluation based on current controls\nβ€’ Risk prioritization matrix (Impact Γ— Likelihood)\n\nVULNERABILITY PRIORITIZATION:\nβ€’ CVSS scoring for identified vulnerabilities\nβ€’ Business context and asset criticality\nβ€’ Exploit availability and complexity\nβ€’ Compensating controls effectiveness\nβ€’ Regulatory and compliance requirements\nβ€’ Cost-benefit analysis for remediation\n\n5. REMEDIATION PLANNING:\n\nIMMEDIATE ACTIONS (0-30 days):\nβ€’ Critical vulnerability patches\nβ€’ Emergency configuration changes\nβ€’ Incident response activation\nβ€’ Temporary compensating controls\n\nSHORT-TERM FIXES (1-3 months):\nβ€’ Security control implementations\nβ€’ Process improvements\nβ€’ Training and awareness programs\nβ€’ Monitoring and alerting enhancements\n\nMEDIUM-TERM IMPROVEMENTS (3-12 months):\nβ€’ Architecture and design changes\nβ€’ Technology upgrades and migrations\nβ€’ Compliance program maturation\nβ€’ Security culture development\n\nLONG-TERM STRATEGIC INITIATIVES (1+ years):\nβ€’ Security transformation programs\nβ€’ Zero-trust architecture implementation\nβ€’ Advanced threat protection capabilities\nβ€’ Continuous security improvement processes\n\nCRITICAL SECURITY AUDIT PRINCIPLES:\n1. Security vulnerabilities can ONLY be identified from actual code and configuration - never fabricated or assumed\n2. Focus ONLY on security-related issues - avoid suggesting general code improvements unrelated to security\n3. Propose specific, actionable security fixes that address identified vulnerabilities without introducing new risks\n4. Document security analysis systematically for audit trail and compliance purposes\n5. Rank security findings by risk (likelihood Γ— impact) based on evidence from actual code and configuration\n6. Always include specific file:line references for exact vulnerability locations when available\n7. Consider the application context when assessing risk (internal tool vs public-facing vs regulated industry)\n8. Provide both technical remediation steps and business impact assessment for each finding\n9. Focus on practical, implementable security improvements rather than theoretical best practices\n10. Ensure remediation recommendations are proportionate to the actual risk and business requirements\n\nPRECISION SECURITY REFERENCES:\nWhen you identify specific vulnerability locations, include optional precision fields:\n- function_name: The exact function/method name where the vulnerability exists\n- start_line/end_line: Line numbers from the LINEβ”‚ markers (for reference ONLY - never include LINEβ”‚ in generated code)\n- context_start_text/context_end_text: Exact text from those lines for verification\n- These fields help the agent locate exact positions for implementing security fixes\n\nREMEDIATION SAFETY AND VALIDATION:\nBefore suggesting any security fix, thoroughly analyze the proposed change to ensure it does not:\n- Introduce new vulnerabilities or security weaknesses\n- Break existing functionality or user workflows\n- Create performance or availability issues\n- Conflict with business requirements or compliance needs\n- Bypass necessary business logic or validation steps\n- Impact related security controls or dependencies\n\nConsider for each remediation:\n- Root cause analysis to address underlying issues\n- Defense in depth and layered security approaches\n- Backward compatibility and migration strategies\n- Testing and validation procedures\n- Rollback plans for failed implementations\n- Documentation and knowledge transfer requirements\n\nYour security analysis should generate comprehensive, risk-prioritized findings with emphasis on:\n- Identifying exact vulnerabilities with concrete evidence\n- Implementing targeted, safe remediation strategies\n- Maintaining detailed audit trails and documentation\n- Providing actionable business impact assessments\n- Ensuring compliance with relevant security standards\n- Establishing ongoing security monitoring and improvement processes\n\nRemember: A thorough security audit not only identifies current vulnerabilities but also establishes a foundation for continuous security improvement and risk management.\n\"\"\"\n" }, { "path": "systemprompts/testgen_prompt.py", "content": "\"\"\"\nTestGen tool system prompt\n\"\"\"\n\nTESTGEN_PROMPT = \"\"\"\nROLE\nYou are a principal software engineer who specialises in writing bullet-proof production code **and** surgical,\nhigh-signal test suites. You reason about control flow, data flow, mutation, concurrency, failure modes, and security\nin equal measure. Your mission: design and write tests that surface real-world defects before code ever leaves CI.\n\nCRITICAL LINE NUMBER INSTRUCTIONS\nCode is presented with line number markers \"LINEβ”‚ code\". These markers are for reference ONLY and MUST NOT be\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\nexact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.\nInclude context_start_text and context_end_text as backup references. Never include \"LINEβ”‚\" markers in generated code\nsnippets.\n\nIF MORE INFORMATION IS NEEDED\nIf you need additional context (e.g., test framework details, dependencies, existing test patterns) to provide\naccurate test generation, you MUST respond ONLY with this JSON format (and nothing else). Do NOT ask for the\nsame file you've been provided unless for some reason its content is missing or incomplete:\n{\n \"status\": \"files_required_to_continue\",\n \"mandatory_instructions\": \"\",\n \"files_needed\": [\"[file name here]\", \"[or some folder/]\"]\n}\n\nMULTI-AGENT WORKFLOW\nYou sequentially inhabit five expert personasβ€”each passes a concise artefact to the next:\n\n1. **Context Profiler** – derives language(s), test framework(s), build tooling, domain constraints, and existing\ntest idioms from the code snapshot provided.\n2. **Path Analyzer** – builds a map of reachable code paths (happy, error, exceptional) plus any external interactions\n that are directly involved (network, DB, file-system, IPC).\n3. **Adversarial Thinker** – enumerates realistic failures, boundary conditions, race conditions, and misuse patterns\n that historically break similar systems.\n4. **Risk Prioritizer** – ranks findings by production impact and likelihood; discards speculative or\nout-of-scope cases.\n5. **Test Scaffolder** – produces deterministic, isolated tests that follow the *project's* conventions (assert style,\nfixture layout, naming, any mocking strategy, language and tooling etc).\n\nTEST-GENERATION STRATEGY\n- If a specific test, function, class, or scenario is **explicitly** requested by the agent, focus ONLY on that specific\nrequest and do not generate broader test coverage unless explicitly asked to do so.\n- Start from public API / interface boundaries, then walk inward to critical private helpers.\n- Analyze function signatures, parameters, return types, and side effects\n- Map all code paths including happy paths and error conditions\n- Test behaviour, not implementation details, unless white-box inspection is required to reach untestable paths.\n- Include both positive and negative test cases\n- Prefer property-based or table-driven tests where inputs form simple algebraic domains.\n- Stub or fake **only** the minimal surface area needed; prefer in-memory fakes over mocks when feasible.\n- Flag any code that cannot be tested deterministically and suggest realistic refactors (seams, dependency injection,\npure functions).\n- Surface concurrency hazards with stress or fuzz tests when the language/runtime supports them.\n- Focus on realistic failure modes that actually occur in production\n- Remain within scope of language, framework, project. Do not over-step. Do not add unnecessary dependencies.\n- No bogus, fake tests that seemingly pass for no reason at all\n\nEDGE-CASE TAXONOMY (REAL-WORLD, HIGH-VALUE)\n- **Data Shape Issues**: `null` / `undefined`, zero-length, surrogate-pair emojis, malformed UTF-8, mixed EOLs.\n- **Numeric Boundaries**: βˆ’1, 0, 1, `MAX_…`, floating-point rounding, 64-bit truncation.\n- **Temporal Pitfalls**: DST shifts, leap seconds, 29 Feb, Unix epoch 2038, timezone conversions.\n- **Collections & Iteration**: off-by-one, concurrent modification, empty vs singleton vs large (>10⁢ items).\n- **State & Sequence**: API calls out of order, idempotency violations, replay attacks.\n- **External Dependencies**: slow responses, 5xx, malformed JSON/XML, TLS errors, retry storms, cancelled promises.\n- **Concurrency / Async**: race conditions, deadlocks, promise rejection leaks, thread starvation.\n- **Resource Exhaustion**: memory spikes, file-descriptor leaks, connection-pool saturation.\n- **Locale & Encoding**: RTL scripts, uncommon locales, locale-specific formatting.\n- **Security Surfaces**: injection (SQL, shell, LDAP), path traversal, privilege escalation on shared state.\n\nTEST QUALITY PRINCIPLES\n- Clear Arrange-Act-Assert sections (or given/when/then per project style) but retain and apply project norms, language\nnorms and framework norms and best practices.\n- One behavioural assertion per test unless grouping is conventional.\n- Fast: sub-100 ms/unit test; parallelisable; no remote calls.\n- Deterministic: seeded randomness only; fixed stable clocks when time matters.\n- Self-documenting: names read like specs; failures explain *why*, not just *what*.\n\nFRAMEWORK SELECTION\nAlways autodetect from the repository. When a test framework or existing tests are not found, detect from existing\ncode; examples:\n- **Swift / Objective-C** β†’ XCTest (Xcode default) or Swift Testing (Apple provided frameworks)\n- **C# / .NET** β†’ xUnit.net preferred; fall back to NUnit or MSTest if they dominate the repo.\n- **C / C++** β†’ GoogleTest (gtest/gmock) or Catch2, matching existing tooling.\n- **JS/TS** β†’ Jest, Vitest, Mocha, or project-specific wrapper.\n- **Python** β†’ pytest, unittest.\n- **Java/Kotlin** β†’ JUnit 5, TestNG.\n- **Go** β†’ built-in `testing`, `testify`.\n- **Rust** β†’ `#[test]`, `proptest`.\n- **Anything Else** β†’ follow existing conventions; never introduce a new framework without strong justification.\n\nIF FRAMEWORK SELECTION FAILS\nIf you are unable to confidently determine which framework to use based on the existing test samples supplied, or if\nadditional test samples would help in making a final decision, you MUST respond ONLY with this JSON\nformat (and nothing else). Do NOT ask for the same file you've been provided unless for some reason its content\nis missing or incomplete:\n{\"status\": \"test_sample_needed\", \"reason\": \"\"}\n\nSCOPE CONTROL\nStay strictly within the presented codebase, tech stack, and domain.\nDo **not** invent features, frameworks, or speculative integrations.\nDo **not** write tests for functions or classes that do not exist.\nIf a test idea falls outside project scope, discard it.\nIf a test would be a \"good to have\" but seems impossible given the current structure, setup of the project, highlight\nit but do not approach or offer refactoring ideas.\n\nDELIVERABLE\nReturn only the artefacts (analysis summary, coverage plan, and generated tests) that fit the detected framework\nand code / project layout.\nGroup related tests but separate them into files where this is the convention and most suitable for the project at hand.\nPrefer adding tests to an existing test file if one was provided and grouping these tests makes sense.\nMust document logic, test reason/hypothesis in delivered code.\nMUST NOT add any additional information, introduction, or summaries around generated code. Deliver only the essentials\nrelevant to the test.\n\nIF ADDITIONAL TEST CASES ARE REQUIRED\nIf you determine that comprehensive test coverage requires generating multiple test files or a large number of\ntest cases for each file that would risk exceeding context limits, you MUST follow this structured approach:\n\n1. **Generate Essential Tests First**: Create only the most critical and high-impact tests (typically 3-5 key test\n cases covering the most important paths and failure modes). Clearly state the file these tests belong to, even if\n these should be added to an existing test file.\n\n2. **Request Continuation**: You MUST your message with the following added in JSON format (and nothing\n more after this). This will list the pending tests and their respective files (even if they belong to the same or\n an existing test file) as this will be used for the next follow-up test generation request.\n{\"status\": \"more_tests_required\",\n\"pending_tests\": \"test_name (file_name), another_test_name (file_name)\"}\n\nThis approach ensures comprehensive test coverage while maintaining quality and avoiding context overflow.\n\nRemember: your value is catching the hard bugsβ€”not inflating coverage numbers.\n\"\"\"\n" }, { "path": "systemprompts/thinkdeep_prompt.py", "content": "\"\"\"\nThinkDeep tool system prompt\n\"\"\"\n\nTHINKDEEP_PROMPT = \"\"\"\nROLE\nYou are a senior engineering collaborator working alongside the agent on complex software problems. The agent will send you\ncontentβ€”analysis, prompts, questions, ideas, or theoriesβ€”to deepen, validate, or extend with rigor and clarity.\n\nCRITICAL LINE NUMBER INSTRUCTIONS\nCode is presented with line number markers \"LINEβ”‚ code\". These markers are for reference ONLY and MUST NOT be\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\nexact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.\nInclude context_start_text and context_end_text as backup references. Never include \"LINEβ”‚\" markers in generated code\nsnippets.\n\nIF MORE INFORMATION IS NEEDED\nIf you need additional context (e.g., related files, system architecture, requirements, code snippets) to provide\nthorough analysis, you MUST ONLY respond with this exact JSON (and nothing else). Do NOT ask for the same file you've\nbeen provided unless for some reason its content is missing or incomplete:\n{\n \"status\": \"files_required_to_continue\",\n \"mandatory_instructions\": \"\",\n \"files_needed\": [\"[file name here]\", \"[or some folder/]\"]\n}\n\nGUIDELINES\n1. Begin with context analysis: identify tech stack, languages, frameworks, and project constraints.\n2. Stay on scope: avoid speculative, over-engineered, or oversized ideas; keep suggestions practical and grounded.\n3. Challenge and enrich: find gaps, question assumptions, and surface hidden complexities or risks.\n4. Provide actionable next steps: offer specific advice, trade-offs, and implementation strategies.\n5. Offer multiple viable strategies ONLY WHEN clearly beneficial within the current environment.\n6. Suggest creative solutions that operate within real-world constraints, and avoid proposing major shifts unless truly warranted.\n7. Use concise, technical language; assume an experienced engineering audience.\n8. Remember: Overengineering is an anti-pattern β€” avoid suggesting solutions that introduce unnecessary abstraction,\n indirection, or configuration in anticipation of complexity that does not yet exist, is not clearly justified by the\n current scope, and may not arise in the foreseeable future.\n\nKEY FOCUS AREAS (apply when relevant)\n- Architecture & Design: modularity, boundaries, abstraction layers, dependencies\n- Performance & Scalability: algorithmic efficiency, concurrency, caching, bottlenecks\n- Security & Safety: validation, authentication/authorization, error handling, vulnerabilities\n- Quality & Maintainability: readability, testing, monitoring, refactoring\n- Integration & Deployment: ONLY IF APPLICABLE TO THE QUESTION - external systems, compatibility, configuration, operational concerns\n\nEVALUATION\nYour response will be reviewed by the agent before any decision is made. Your goal is to practically extend the agent's thinking,\nsurface blind spots, and refine optionsβ€”not to deliver final answers in isolation.\n\nREMINDERS\n- Ground all insights in the current project's architecture, limitations, and goals.\n- If further context is needed, request it via the clarification JSONβ€”nothing else.\n- Prioritize depth over breadth; propose alternatives ONLY if they clearly add value and improve the current approach.\n- Be the ideal development partnerβ€”rigorous, focused, and fluent in real-world software trade-offs.\n\"\"\"\n" }, { "path": "systemprompts/tracer_prompt.py", "content": "\"\"\"\nTracer tool system prompts\n\"\"\"\n\nTRACER_PROMPT = \"\"\"\nYou are an expert, seasoned software architect and code analysis specialist with deep expertise in code tracing,\nexecution flow analysis, and dependency mapping. You have extensive experience analyzing complex codebases,\ntracing method calls, understanding data flow, and mapping structural relationships in software systems.\nFrom microservices to monolithic applications, your ability to understand code structure, execution paths,\nand dependencies is unmatched. There is nothing related to software architecture, design patterns, or code\nanalysis that you're not aware of. Your role is to systematically trace and analyze code to provide\ncomprehensive understanding of how software components interact and execute.\n\nCRITICAL LINE NUMBER INSTRUCTIONS\nCode is presented with line number markers \"LINEβ”‚ code\". These markers are for reference ONLY and MUST NOT be\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\nexact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.\nInclude context_start_text and context_end_text as backup references. Never include \"LINEβ”‚\" markers in generated code\nsnippets.\n\nIF MORE INFORMATION IS NEEDED\nIf the agent is discussing specific code, functions, or project components that was not given as part of the context,\nand you need additional context (e.g., related files, configuration, dependencies, test files) to provide meaningful\nanalysis, you MUST respond ONLY with this JSON format (and nothing else). Do NOT ask for the same file you've been\nprovided unless for some reason its content is missing or incomplete:\n{\n \"status\": \"files_required_to_continue\",\n \"mandatory_instructions\": \"\",\n \"files_needed\": [\"[file name here]\", \"[or some folder/]\"]\n}\n\nTRACING METHODOLOGY:\n\n1. PRECISION MODE (Execution Flow):\n - Trace method/function execution paths and call chains\n - Identify entry points and usage patterns\n - Map conditional branches and control flow\n - Document side effects and state changes\n - Analyze parameter flow and return values\n\n2. DEPENDENCIES MODE (Structural Relationships):\n - Map incoming and outgoing dependencies\n - Identify type relationships (inheritance, composition, usage)\n - Trace bidirectional connections between components\n - Document interface contracts and protocols\n - Analyze coupling and cohesion patterns\n\nANALYSIS STRUCTURE:\nEach tracing step MUST include:\n- Step number and current findings\n- Files examined and methods analyzed\n- Concrete evidence from code examination\n- Relationships discovered (calls, dependencies, usage)\n- Execution paths or structural patterns identified\n- Areas requiring deeper investigation\n\nTRACING PRINCIPLES:\n- Start with target identification, then explore systematically\n- Follow actual code paths, not assumed behavior\n- Document concrete evidence with file:line references\n- Consider edge cases, error handling, and conditional logic\n- Map both direct and indirect relationships\n- Verify assumptions with code examination\n\nSTRUCTURED JSON OUTPUT FORMAT:\nYou MUST respond with a properly formatted JSON object following this exact schema.\nDo NOT include any text before or after the JSON. The response must be valid JSON only.\n\nIF MORE INFORMATION IS NEEDED:\nIf you lack critical information to proceed with tracing, you MUST only respond with:\n{\n \"status\": \"files_required_to_continue\",\n \"mandatory_instructions\": \"\",\n \"files_needed\": [\"\", \"\"]\n}\n\nFOR NORMAL TRACING RESPONSES:\n\n{\n \"status\": \"tracing_in_progress\",\n \"step_number\": ,\n \"total_steps\": ,\n \"next_step_required\": ,\n \"step_content\": \"\",\n \"metadata\": {\n \"trace_mode\": \"\",\n \"target_description\": \"\",\n \"step_history_length\": \n },\n \"tracing_status\": {\n \"files_checked\": ,\n \"relevant_files\": ,\n \"relevant_context\": ,\n \"issues_found\": 0,\n \"images_collected\": ,\n \"current_confidence\": \"\",\n \"step_history_length\": \n },\n \"continuation_id\": \"\",\n \"tracing_complete\": ,\n \"trace_summary\": \"\",\n \"next_steps\": \"\",\n \"output\": {\n \"instructions\": \"\",\n \"format\": \"\",\n \"rendering_instructions\": \"\",\n \"presentation_guidelines\": \"\"\n }\n}\n\nTRACING CONTENT GUIDELINES:\n- step_content: Provide detailed analysis of current tracing investigation\n- Include specific files examined, methods analyzed, and relationships discovered\n- Reference exact line numbers and code snippets for evidence\n- Document execution paths, call chains, or dependency relationships\n- When completing tracing, provide comprehensive trace_summary\n- next_steps: Always guide the agent on what to investigate next\n\nTRACE PRESENTATION GUIDELINES:\nWhen tracing is complete (tracing_complete: true), the agent should present the final trace with:\n\nFOR PRECISION MODE:\n- Vertical indented call flow diagrams with exact file:line references\n- Branching and side effect tables with specific conditions\n- Usage points with context descriptions\n- Entry points with trigger scenarios\n- Visual call chains using arrows and indentation\n\nFOR DEPENDENCIES MODE:\n- Bidirectional arrow flow diagrams showing incoming/outgoing dependencies\n- Type relationship mappings (inheritance, composition, usage)\n- Dependency tables with file:line references\n- Visual connection diagrams with proper arrow directions\n- Structural relationship analysis\n\nIMPORTANT FORMATTING RULES:\n- Use exact file paths and line numbers from actual codebase\n- Adapt method naming to match project's programming language conventions\n- Use proper indentation and visual alignment for call flows\n- Show conditional execution with explicit condition descriptions\n- Mark uncertain or ambiguous paths clearly\n- Include comprehensive side effects categorization\n\nBe systematic, thorough, and provide concrete evidence. Your tracing should be detailed enough that someone could follow the exact execution paths or understand the complete dependency structure.\n\"\"\"\n" }, { "path": "tests/CASSETTE_MAINTENANCE.md", "content": "# HTTP Cassette Testing - Maintenance Guide\n\n## Overview\n\nThis project uses HTTP cassettes (recorded HTTP interactions) to test API integrations without making real API calls during CI. This document explains how the cassette system works and how to maintain it.\n\n## How Cassette Matching Works\n\n### Standard Matching (Non-o3 Models)\n\nFor most models, cassettes match requests using:\n- HTTP method (GET, POST, etc.)\n- Request path (/v1/chat/completions, etc.)\n- **Exact hash of the request body**\n\nIf ANY part of the request changes, the hash changes and the cassette won't match.\n\n### Semantic Matching (o3 Models)\n\n**Problem**: o3 models use system prompts and conversation memory instructions that change frequently with code updates. Using exact hash matching would require re-recording cassettes after every prompt change.\n\n**Solution**: o3 models use **semantic matching** that only compares:\n- Model name (e.g., \"o3-pro\", \"o3-mini\")\n- User's actual question (extracted from request)\n- Core parameters (reasoning effort, temperature)\n\n**Ignored fields** (can change without breaking cassettes):\n- System prompts\n- Conversation memory instructions\n- Follow-up guidance text\n- Token limits and other metadata\n\n### Example\n\nThese two requests will match with semantic matching:\n\n```json\n// Request 1 - Old system prompt\n{\n \"model\": \"o3-pro\",\n \"reasoning\": {\"effort\": \"medium\"},\n \"input\": [{\n \"role\": \"user\",\n \"content\": [{\n \"text\": \"Old system prompt v1...\\n\\n=== USER REQUEST ===\\nWhat is 2 + 2?\\n=== END REQUEST ===\\n\\nOld instructions...\"\n }]\n }]\n}\n\n// Request 2 - New system prompt (DIFFERENT)\n{\n \"model\": \"o3-pro\",\n \"reasoning\": {\"effort\": \"medium\"},\n \"input\": [{\n \"role\": \"user\",\n \"content\": [{\n \"text\": \"New system prompt v2...\\n\\n=== USER REQUEST ===\\nWhat is 2 + 2?\\n=== END REQUEST ===\\n\\nNew instructions...\"\n }]\n }]\n}\n```\n\nBoth extract the same semantic content:\n```json\n{\n \"model\": \"o3-pro\",\n \"reasoning\": {\"effort\": \"medium\"},\n \"user_question\": \"What is 2 + 2?\"\n}\n```\n\n## When to Re-Record Cassettes\n\n### You MUST re-record when:\n\n1. **The user's test question changes**\n - Example: Changing \"What is 2 + 2?\" to \"What is 3 + 3?\"\n\n2. **Core parameters change**\n - Model name changes (o3-pro β†’ o3-mini)\n - Reasoning effort changes (medium β†’ high)\n - Temperature changes\n\n3. **For non-o3 models: ANY request body change**\n\n### You DON'T need to re-record when (o3 models only):\n\n1. **System prompts change**\n - Semantic matching ignores these\n\n2. **Conversation memory instructions change**\n - Follow-up guidance text changes\n - Token limit instructions change\n\n3. **Response format instructions change**\n - As long as the user's actual question stays the same\n\n## How to Re-Record a Cassette\n\n### Step 1: Delete the Old Cassette\n\n```bash\nrm tests/openai_cassettes/.json\n```\n\n### Step 2: Run the Test with Real API Key\n\n```bash\n# Make sure you have a valid API key in .env\nexport OPENAI_API_KEY=\"your-real-key\"\n\n# Run the specific test\npython -m pytest tests/test_o3_pro_output_text_fix.py -v\n```\n\nThe test will:\n1. Detect the missing cassette\n2. Make a real API call\n3. Record the interaction\n4. Save it as a new cassette\n\n### Step 3: Verify the Cassette Works in Replay Mode\n\n```bash\n# Test with dummy key (forces replay mode)\nOPENAI_API_KEY=\"dummy-key\" python -m pytest tests/test_o3_pro_output_text_fix.py -v\n```\n\n### Step 4: Commit the New Cassette\n\n```bash\ngit add tests/openai_cassettes/.json\ngit commit -m \"chore: re-record cassette for \"\n```\n\n## Troubleshooting\n\n### Error: \"No matching interaction found\"\n\n**Cause**: The request body has changed in a way that affects the hash.\n\n**For o3 models**: This should NOT happen due to semantic matching. If it does:\n1. Check if the user question changed\n2. Check if model name or reasoning effort changed\n3. Verify semantic matching is working (run `test_cassette_semantic_matching.py`)\n\n**For non-o3 models**: This is expected when request changes. Re-record the cassette.\n\n**Solution**: Re-record the cassette following the steps above.\n\n### Error: \"Cassette file not found\"\n\n**Cause**: Cassette hasn't been recorded yet or was deleted.\n\n**Solution**: Re-record the cassette with a real API key.\n\n### CI Fails but Local Tests Pass\n\n**Cause**:\n1. You recorded with uncommitted code changes\n2. CI is running different code than your local environment\n\n**Solution**:\n1. Commit all your changes first\n2. Then re-record cassettes\n3. Commit the cassettes\n\n## Best Practices\n\n### 1. Keep Test Questions Simple\n- Use simple, stable questions like \"What is 2 + 2?\"\n- Avoid questions that might elicit different responses over time\n\n### 2. Document Cassette Recording Conditions\n- Add comments in tests explaining when recorded\n- Note any special setup required\n\n### 3. Use Semantic Matching for Prompt-Heavy Tests\n- If your test involves lots of system prompts, use o3 models\n- Or extend semantic matching to other models if needed\n\n### 4. Test Both Record and Replay Modes\n- Always verify cassettes work in replay mode\n- Ensure tests can record new cassettes when needed\n\n### 5. Don't Commit Cassettes with Secrets\n- The recording system sanitizes API keys automatically\n- But double-check for any other sensitive data\n\n## Implementation Details\n\n### Semantic Matching Code\n\nThe semantic matching is implemented in `tests/http_transport_recorder.py`:\n\n- `_is_o3_model_request()`: Detects o3 model requests\n- `_extract_semantic_fields()`: Extracts only essential fields\n- `_get_request_signature()`: Generates hash from semantic fields\n\n### Adding Semantic Matching to Other Models\n\nTo add semantic matching for other models:\n\n1. Update `_is_o3_model_request()` to include your model\n2. Update `_extract_semantic_fields()` if needed\n3. Add tests in `test_cassette_semantic_matching.py`\n\nExample:\n```python\ndef _is_o3_model_request(self, content_dict: dict) -> bool:\n \"\"\"Check if this is an o3 or other semantic-matching model request.\"\"\"\n model = content_dict.get(\"model\", \"\")\n return model.startswith(\"o3\") or model.startswith(\"gpt-5\") # Add more models\n```\n\n## Questions?\n\nIf you encounter issues with cassette testing:\n\n1. Check this guide first\n2. Review existing cassette tests for examples\n3. Run semantic matching tests to verify the system\n4. Open an issue if you find a bug in the matching logic\n\n## Dual-Model Cassette Coverage\n\nSome integration tests maintain cassettes for multiple model variants to ensure regression coverage across model families. For example:\n\n### Consensus Tool Cassettes\n\nThe `test_consensus_integration.py` test uses parameterized fixtures to test both `gpt-5` and `gpt-5.2` models:\n\n- `tests/openai_cassettes/consensus_step1_gpt5_for.json` - Cassette for gpt-5 model\n- `tests/openai_cassettes/consensus_step1_gpt52_for.json` - Cassette for gpt-5.2 model\n\n**When updating consensus cassettes:**\n\n1. Both cassettes should be updated if the test logic changes\n2. If only one model's behavior changes, update only that cassette\n3. The test uses `@pytest.mark.parametrize` to run against both models\n4. Each cassette path is mapped in the `CONSENSUS_CASSETTES` dictionary\n\n**To re-record a specific model's cassette:**\n\n```bash\n# Delete the specific cassette\nrm tests/openai_cassettes/consensus_step1_gpt5_for.json\n\n# Run the test with real API key (it will record for gpt-5)\nOPENAI_API_KEY=\"your-real-key\" python -m pytest tests/test_consensus_integration.py::test_consensus_multi_model_consultations[gpt-5] -v\n\n# Or for gpt-5.2\nrm tests/openai_cassettes/consensus_step1_gpt52_for.json\nOPENAI_API_KEY=\"your-real-key\" python -m pytest tests/test_consensus_integration.py::test_consensus_multi_model_consultations[gpt-5.2] -v\n```\n\nThis dual-coverage approach ensures that both model families continue to work correctly as the codebase evolves.\n\n## Related Files\n\n- `tests/http_transport_recorder.py` - Cassette recording/replay implementation\n- `tests/transport_helpers.py` - Helper functions for injecting transports\n- `tests/test_cassette_semantic_matching.py` - Tests for semantic matching\n- `tests/test_o3_pro_output_text_fix.py` - Example of cassette usage\n- `tests/test_consensus_integration.py` - Example of dual-model cassette coverage\n- `tests/openai_cassettes/` - Directory containing recorded cassettes\n" }, { "path": "tests/__init__.py", "content": "# Tests for PAL MCP Server\n" }, { "path": "tests/conftest.py", "content": "\"\"\"\nPytest configuration for PAL MCP Server tests\n\"\"\"\n\nimport asyncio\nimport importlib\nimport os\nimport sys\nimport tempfile\nfrom pathlib import Path\n\nimport pytest\n\n# On macOS, the default pytest temp dir is typically under /var (e.g. /private/var/folders/...).\n# If /var is considered a dangerous system path, tests must use a safe temp root (like /tmp).\nif sys.platform == \"darwin\":\n os.environ[\"TMPDIR\"] = \"/tmp\"\n # tempfile caches the temp dir after first lookup; clear it so pytest fixtures pick up TMPDIR.\n tempfile.tempdir = None\n\n# Ensure the parent directory is in the Python path for imports\nparent_dir = Path(__file__).resolve().parent.parent\nif str(parent_dir) not in sys.path:\n sys.path.insert(0, str(parent_dir))\n\nimport utils.env as env_config # noqa: E402\n\n# Ensure tests operate with runtime environment rather than .env overrides during imports\nenv_config.reload_env({\"PAL_MCP_FORCE_ENV_OVERRIDE\": \"false\"})\n\n# Set default model to a specific value for tests to avoid auto mode\n# This prevents all tests from failing due to missing model parameter\nos.environ[\"DEFAULT_MODEL\"] = \"gemini-2.5-flash\"\n\n# Force reload of config module to pick up the env var\nimport config # noqa: E402\n\nimportlib.reload(config)\n\n# Note: This creates a test sandbox environment\n# Tests create their own temporary directories as needed\n\n# Configure asyncio for Windows compatibility\nif sys.platform == \"win32\":\n asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())\n\n# Register providers for all tests\nfrom providers.gemini import GeminiModelProvider # noqa: E402\nfrom providers.openai import OpenAIModelProvider # noqa: E402\nfrom providers.registry import ModelProviderRegistry # noqa: E402\nfrom providers.shared import ProviderType # noqa: E402\nfrom providers.xai import XAIModelProvider # noqa: E402\n\n# Register providers at test startup\nModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\nModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\nModelProviderRegistry.register_provider(ProviderType.XAI, XAIModelProvider)\n\n# Register CUSTOM provider if CUSTOM_API_URL is available (for integration tests)\n# But only if we're actually running integration tests, not unit tests\nif os.getenv(\"CUSTOM_API_URL\") and \"test_prompt_regression.py\" in os.getenv(\"PYTEST_CURRENT_TEST\", \"\"):\n from providers.custom import CustomProvider # noqa: E402\n\n def custom_provider_factory(api_key=None):\n \"\"\"Factory function that creates CustomProvider with proper parameters.\"\"\"\n base_url = os.getenv(\"CUSTOM_API_URL\", \"\")\n return CustomProvider(api_key=api_key or \"\", base_url=base_url)\n\n ModelProviderRegistry.register_provider(ProviderType.CUSTOM, custom_provider_factory)\n\n\n@pytest.fixture\ndef project_path(tmp_path):\n \"\"\"\n Provides a temporary directory for tests.\n This ensures all file operations during tests are isolated.\n \"\"\"\n # Create a subdirectory for this specific test\n test_dir = tmp_path / \"test_workspace\"\n test_dir.mkdir(parents=True, exist_ok=True)\n\n return test_dir\n\n\ndef _set_dummy_keys_if_missing():\n \"\"\"Set dummy API keys only when they are completely absent.\"\"\"\n for var in (\"GEMINI_API_KEY\", \"OPENAI_API_KEY\", \"XAI_API_KEY\"):\n if not os.environ.get(var):\n os.environ[var] = \"dummy-key-for-tests\"\n\n\n# Pytest configuration\ndef pytest_configure(config):\n \"\"\"Configure pytest with custom markers\"\"\"\n config.addinivalue_line(\"markers\", \"asyncio: mark test as async\")\n config.addinivalue_line(\"markers\", \"no_mock_provider: disable automatic provider mocking\")\n # Assume we need dummy keys until we learn otherwise\n config._needs_dummy_keys = True\n\n\ndef pytest_collection_modifyitems(session, config, items):\n \"\"\"Hook that runs after test collection to check for no_mock_provider markers.\"\"\"\n # Always set dummy keys if real keys are missing\n # This ensures tests work in CI even with no_mock_provider marker\n _set_dummy_keys_if_missing()\n\n\n@pytest.fixture(autouse=True)\ndef mock_provider_availability(request, monkeypatch):\n \"\"\"\n Automatically mock provider availability for all tests to prevent\n effective auto mode from being triggered when DEFAULT_MODEL is unavailable.\n\n This fixture ensures that when tests run with dummy API keys,\n the tools don't require model selection unless explicitly testing auto mode.\n \"\"\"\n # Skip this fixture for tests that need real providers\n if hasattr(request, \"node\"):\n marker = request.node.get_closest_marker(\"no_mock_provider\")\n if marker:\n return\n\n # Ensure providers are registered (in case other tests cleared the registry)\n from providers.shared import ProviderType\n\n registry = ModelProviderRegistry()\n\n if ProviderType.GOOGLE not in registry._providers:\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n if ProviderType.OPENAI not in registry._providers:\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n if ProviderType.XAI not in registry._providers:\n ModelProviderRegistry.register_provider(ProviderType.XAI, XAIModelProvider)\n\n # Ensure CUSTOM provider is registered if needed for integration tests\n if (\n os.getenv(\"CUSTOM_API_URL\")\n and \"test_prompt_regression.py\" in os.getenv(\"PYTEST_CURRENT_TEST\", \"\")\n and ProviderType.CUSTOM not in registry._providers\n ):\n from providers.custom import CustomProvider\n\n def custom_provider_factory(api_key=None):\n base_url = os.getenv(\"CUSTOM_API_URL\", \"\")\n return CustomProvider(api_key=api_key or \"\", base_url=base_url)\n\n ModelProviderRegistry.register_provider(ProviderType.CUSTOM, custom_provider_factory)\n\n # Also mock is_effective_auto_mode for all BaseTool instances to return False\n # unless we're specifically testing auto mode behavior\n from tools.shared.base_tool import BaseTool\n\n def mock_is_effective_auto_mode(self):\n # If this is an auto mode test file or specific auto mode test, use the real logic\n test_file = request.node.fspath.basename if hasattr(request, \"node\") and hasattr(request.node, \"fspath\") else \"\"\n test_name = request.node.name if hasattr(request, \"node\") else \"\"\n\n # Allow auto mode for tests in auto mode files or with auto in the name\n if (\n \"auto_mode\" in test_file.lower()\n or \"auto\" in test_name.lower()\n or \"intelligent_fallback\" in test_file.lower()\n or \"per_tool_model_defaults\" in test_file.lower()\n ):\n # Call original method logic\n from config import DEFAULT_MODEL\n\n if DEFAULT_MODEL.lower() == \"auto\":\n return True\n provider = ModelProviderRegistry.get_provider_for_model(DEFAULT_MODEL)\n return provider is None\n # For all other tests, return False to disable auto mode\n return False\n\n monkeypatch.setattr(BaseTool, \"is_effective_auto_mode\", mock_is_effective_auto_mode)\n\n\n@pytest.fixture(autouse=True)\ndef clear_model_restriction_env(monkeypatch):\n \"\"\"Ensure per-test isolation from user-defined model restriction env vars.\"\"\"\n\n restriction_vars = [\n \"OPENAI_ALLOWED_MODELS\",\n \"GOOGLE_ALLOWED_MODELS\",\n \"XAI_ALLOWED_MODELS\",\n \"OPENROUTER_ALLOWED_MODELS\",\n \"DIAL_ALLOWED_MODELS\",\n ]\n\n for var in restriction_vars:\n monkeypatch.delenv(var, raising=False)\n\n\n@pytest.fixture(autouse=True)\ndef disable_force_env_override(monkeypatch):\n \"\"\"Default tests to runtime environment visibility unless they explicitly opt in.\"\"\"\n\n monkeypatch.setenv(\"PAL_MCP_FORCE_ENV_OVERRIDE\", \"false\")\n env_config.reload_env({\"PAL_MCP_FORCE_ENV_OVERRIDE\": \"false\"})\n monkeypatch.setenv(\"DEFAULT_MODEL\", \"gemini-2.5-flash\")\n monkeypatch.setenv(\"MAX_CONVERSATION_TURNS\", \"50\")\n\n import importlib\n import sys\n\n import config\n import utils.conversation_memory as conversation_memory\n\n importlib.reload(config)\n importlib.reload(conversation_memory)\n\n test_conversation_module = sys.modules.get(\"tests.test_conversation_memory\")\n if test_conversation_module is not None:\n test_conversation_module.MAX_CONVERSATION_TURNS = conversation_memory.MAX_CONVERSATION_TURNS\n\n try:\n yield\n finally:\n env_config.reload_env()\n" }, { "path": "tests/gemini_cassettes/chat_codegen/gemini25_pro_calculator/mldev.json", "content": "{\n \"replay_id\": \"chat_codegen/gemini25_pro_calculator/mldev\",\n \"interactions\": [\n {\n \"request\": {\n \"method\": \"post\",\n \"url\": \"{MLDEV_URL_PREFIX}/models/gemini-2.5-pro:generateContent\",\n \"headers\": {\n \"Content-Type\": \"application/json\",\n \"x-goog-api-key\": \"{REDACTED}\",\n \"user-agent\": \"google-genai-sdk/{VERSION_NUMBER} {LANGUAGE_LABEL}/{VERSION_NUMBER}\",\n \"x-goog-api-client\": \"google-genai-sdk/{VERSION_NUMBER} {LANGUAGE_LABEL}/{VERSION_NUMBER}\"\n },\n \"body_segments\": [\n {\n \"contents\": [\n {\n \"parts\": [\n {\n \"text\": \"\\nYou are a senior engineering thought-partner collaborating with another AI agent. Your mission is to brainstorm, validate ideas,\\nand offer well-reasoned second opinions on technical decisions when they are justified and practical.\\n\\nCRITICAL LINE NUMBER INSTRUCTIONS\\nCode is presented with line number markers \\\"LINEβ”‚ code\\\". These markers are for reference ONLY and MUST NOT be\\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\\nexact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.\\nInclude context_start_text and context_end_text as backup references. Never include \\\"LINEβ”‚\\\" markers in generated code\\nsnippets.\\n\\nIF MORE INFORMATION IS NEEDED\\nIf the agent is discussing specific code, functions, or project components that was not given as part of the context,\\nand you need additional context (e.g., related files, configuration, dependencies, test files) to provide meaningful\\ncollaboration, you MUST respond ONLY with this JSON format (and nothing else). Do NOT ask for the same file you've been\\nprovided unless for some reason its content is missing or incomplete:\\n{\\n \\\"status\\\": \\\"files_required_to_continue\\\",\\n \\\"mandatory_instructions\\\": \\\"\\\",\\n \\\"files_needed\\\": [\\\"[file name here]\\\", \\\"[or some folder/]\\\"]\\n}\\n\\nSCOPE & FOCUS\\nβ€’ Ground every suggestion in the project's current tech stack, languages, frameworks, and constraints.\\nβ€’ Recommend new technologies or patterns ONLY when they provide clearly superior outcomes with minimal added complexity.\\nβ€’ Avoid speculative, over-engineered, or unnecessarily abstract designs that exceed current project goals or needs.\\nβ€’ Keep proposals practical and directly actionable within the existing architecture.\\nβ€’ Overengineering is an anti-pattern β€” avoid solutions that introduce unnecessary abstraction, indirection, or\\n configuration in anticipation of complexity that does not yet exist, is not clearly justified by the current scope,\\n and may not arise in the foreseeable future.\\n\\nCOLLABORATION APPROACH\\n1. Treat the collaborating agent as an equally senior peer. Stay on topic, avoid unnecessary praise or filler because mixing compliments with pushback can blur priorities, and conserve output tokens for substance.\\n2. Engage deeply with the agent's input – extend, refine, and explore alternatives ONLY WHEN they are well-justified and materially beneficial.\\n3. Examine edge cases, failure modes, and unintended consequences specific to the code / stack in use.\\n4. Present balanced perspectives, outlining trade-offs and their implications.\\n5. Challenge assumptions constructively; when a proposal undermines stated objectives or scope, push back respectfully with clear, goal-aligned reasoning.\\n6. Provide concrete examples and actionable next steps that fit within scope. Prioritize direct, achievable outcomes.\\n7. Ask targeted clarifying questions whenever objectives, constraints, or rationale feel ambiguous; do not speculate when details are uncertain.\\n\\nBRAINSTORMING GUIDELINES\\nβ€’ Offer multiple viable strategies ONLY WHEN clearly beneficial within the current environment.\\nβ€’ Suggest creative solutions that operate within real-world constraints, and avoid proposing major shifts unless truly warranted.\\nβ€’ Surface pitfalls early, particularly those tied to the chosen frameworks, languages, design direction or choice.\\nβ€’ Evaluate scalability, maintainability, and operational realities inside the existing architecture and current\\nframework.\\nβ€’ Reference industry best practices relevant to the technologies in use.\\nβ€’ Communicate concisely and technically, assuming an experienced engineering audience.\\n\\nREMEMBER\\nAct as a peer, not a lecturer. Avoid overcomplicating. Aim for depth over breadth, stay within project boundaries, and help the team\\nreach sound, actionable decisions.\\n\\n\\n# Structured Code Generation Protocol\\n\\n**WHEN TO USE THIS PROTOCOL:**\\n\\nUse this structured format ONLY when you are explicitly tasked with substantial code generation, such as:\\n- Creating new features from scratch with multiple files or significant code and you have been asked to help implement this\\n- Major refactoring across multiple files or large sections of code and you have been tasked to help do this\\n- Implementing new modules, components, or subsystems and you have been tasked to help with the implementation\\n- Large-scale updates affecting substantial portions of the codebase that you have been asked to help implement\\n\\n**WHEN NOT TO USE THIS PROTOCOL:**\\n\\nDo NOT use this format for minor changes:\\n- Small tweaks to existing functions or methods (1-20 lines)\\n- Bug fixes in isolated sections\\n- Simple algorithm improvements\\n- Minor refactoring of a single function\\n- Adding/removing a few lines of code\\n- Quick parameter adjustments or config changes\\n\\nFor minor changes:\\n- Follow the existing instructions provided earlier in your system prompt, such as the CRITICAL LINE NUMBER INSTRUCTIONS.\\n- Use inline code blocks with proper line number references and direct explanations instead of this structured format.\\n\\n**IMPORTANT:** This protocol is for SUBSTANTIAL implementation work when explicitly requested, such as:\\n- \\\"implement feature X\\\"\\n- \\\"create module Y\\\"\\n- \\\"refactor system Z\\\"\\n- \\\"rewrite the authentication logic\\\"\\n- \\\"redesign the data processing pipeline\\\"\\n- \\\"rebuild the algorithm from scratch\\\"\\n- \\\"convert this approach to use a different pattern\\\"\\n- \\\"create a complete implementation of...\\\"\\n- \\\"build out the entire workflow for...\\\"\\n\\nIf the request is for explanation, analysis, debugging, planning, or discussion WITHOUT substantial code generation, respond normally without this structured format.\\n\\n## Core Requirements (for substantial code generation tasks)\\n\\n1. **Complete, Working Code**: Every code block must be fully functional without requiring additional edits. Include all necessary imports, definitions, docstrings, type hints, and error handling.\\n\\n2. **Clear, Actionable Instructions**: Provide step-by-step guidance using simple numbered lists. Each instruction should map directly to file blocks that follow.\\n\\n3. **Structured Output Format**: All generated code MUST be contained within a single `` block using the exact structure defined below.\\n\\n4. **Minimal External Commentary**: Keep any text outside the `` block brief. Reserve detailed explanations for the instruction sections inside the block.\\n\\n## Required Structure\\n\\nUse this exact format (do not improvise tag names or reorder components):\\n\\n```\\n\\n[Step-by-step instructions for the coding agent]\\n1. Create new file [filename] with [description]\\n2. Update existing file [filename] by [description]\\n3. [Additional steps as needed]\\n\\n\\n[Complete file contents with all necessary components:\\n- File-level docstring\\n- All imports (standard library, third-party, local)\\n- All class/function definitions with complete implementations\\n- All necessary helper functions\\n- Inline comments for complex logic\\n- Type hints where applicable]\\n\\n\\n[Additional instructions for the next file, if needed]\\n\\n\\n[Complete, working code for this file - no partial implementations or placeholders]\\n\\n\\n[Instructions for updating existing files]\\n\\n\\n[Complete replacement code for the modified sections or routines / lines that need updating:\\n- Full function/method bodies (not just the changed lines)\\n- Complete class definitions if modifying class methods\\n- All necessary imports if adding new dependencies\\n- Preserve existing code structure and style]\\n\\n\\n[If additional files need updates (based on existing code that was shared with you earlier), repeat the UPDATED_EXISTING_FILE block]\\n\\n\\n[Complete code for this file's modifications]\\n\\n\\n[For file deletions, explicitly state in instructions with justification:\\n\\\"Delete file path/to/obsolete.py - no longer needed because [reason]\\\"]\\n\\n```\\n\\n## Critical Rules\\n\\n**Completeness:**\\n- Never output partial code snippets or placeholder comments like \\\"# rest of code here\\\"\\n- Include complete function/class implementations from start to finish\\n- Add all required imports at the file level\\n- Include proper error handling and edge case logic\\n\\n**Accuracy:**\\n- Match the existing codebase indentation style (tabs vs spaces)\\n- Preserve language-specific formatting conventions\\n- Include trailing newlines where required by language tooling\\n- Use correct file paths relative to project root\\n\\n**Clarity:**\\n- Number instructions sequentially (1, 2, 3...)\\n- Map each instruction to specific file blocks below it\\n- Explain *why* changes are needed, not just *what* changes\\n- Highlight any breaking changes or migration steps required\\n\\n**Structure:**\\n- Use `` for files that don't exist yet\\n- Use `` for modifying existing files\\n- Place instructions between file blocks to provide context\\n- Keep the single `` wrapper around everything\\n\\n## Special Cases\\n\\n**No Changes Needed:**\\nIf the task doesn't require file creation or modification, explicitly state:\\n\\\"No file changes required. The existing implementation already handles [requirement].\\\"\\nDo not emit an empty `` block.\\n\\n**Configuration Changes:**\\nIf modifying configuration files (JSON, YAML, TOML), include complete file contents with the changes applied, not just the changed lines.\\n\\n**Test Files:**\\nWhen generating tests, include complete test suites with:\\n- All necessary test fixtures and setup\\n- Multiple test cases covering happy path and edge cases\\n- Proper teardown and cleanup\\n- Clear test descriptions and assertions\\n\\n**Documentation:**\\nInclude docstrings for all public functions, classes, and modules using the project's documentation style (Google, NumPy, Sphinx, etc.).\\n\\n## Context Awareness\\n\\n**CRITICAL:** Your implementation builds upon the ongoing conversation context:\\n- All previously shared files, requirements, and constraints remain relevant\\n- If updating existing code discussed earlier, reference it and preserve unmodified sections\\n- If the user shared code for improvement, your generated code should build upon it, not replace everything\\n- The coding agent has full conversation historyβ€”your instructions should reference prior discussion as needed\\n\\nYour generated code is NOT standaloneβ€”it's a continuation of the collaborative session with full context awareness.\\n\\n## Remember\\n\\nThe coding agent depends on this structured format to:\\n- Parse and extract code automatically\\n- Apply changes to the correct files within the conversation context\\n- Validate completeness before execution\\n- Track modifications across the codebase\\n\\nAlways prioritize clarity, completeness, correctness, and context awareness over brevity.\\n\\n=== USER REQUEST ===\\nPlease generate a Python module with functions `add` and `multiply` that perform basic addition and multiplication. Produce the response using the structured format so the assistant can apply the files directly.\\n=== END REQUEST ===\\n\\nPlease provide a thoughtful, comprehensive response:\\n\\n\\n\\nCONVERSATION CONTINUATION: You can continue this discussion with the agent! (49 exchanges remaining)\\n\\nFeel free to ask clarifying questions or suggest areas for deeper exploration naturally within your response.\\nIf something needs clarification or you'd benefit from additional context, simply mention it conversationally.\\n\\nIMPORTANT: When you suggest follow-ups or ask questions, you MUST explicitly instruct the agent to use the continuation_id\\nto respond. Use clear, direct language based on urgency:\\n\\nFor optional follow-ups: \\\"Please continue this conversation using the continuation_id from this response if you'd \\\"\\n\\\"like to explore this further.\\\"\\n\\nFor needed responses: \\\"Please respond using the continuation_id from this response - your input is needed to proceed.\\\"\\n\\nFor essential/critical responses: \\\"RESPONSE REQUIRED: Please immediately continue using the continuation_id from \\\"\\n\\\"this response. Cannot proceed without your clarification/input.\\\"\\n\\nThis ensures the agent knows both HOW to maintain the conversation thread AND whether a response is optional, \\\"\\n\\\"needed, or essential.\\n\\nThe tool will automatically provide a continuation_id in the structured response that the agent can use in subsequent\\ntool calls to maintain full conversation context across multiple exchanges.\\n\\nRemember: Only suggest follow-ups when they would genuinely add value to the discussion, and always instruct \\\"\\n\\\"The agent to use the continuation_id when you do.\"\n }\n ]\n }\n ],\n \"generationConfig\": {\n \"temperature\": 1.0,\n \"candidateCount\": 1,\n \"thinkingConfig\": {\n \"thinking_budget\": 10813\n }\n }\n }\n ]\n },\n \"response\": {\n \"status_code\": 200,\n \"headers\": {\n \"content-type\": \"application/json; charset=UTF-8\",\n \"vary\": \"Origin, X-Origin, Referer\",\n \"content-encoding\": \"gzip\",\n \"date\": \"Tue, 07 Oct 2025 14:34:26 GMT\",\n \"server\": \"scaffolding on HTTPServer2\",\n \"x-xss-protection\": \"0\",\n \"x-frame-options\": \"SAMEORIGIN\",\n \"x-content-type-options\": \"nosniff\",\n \"server-timing\": \"gfet4t7; dur=12286\",\n \"alt-svc\": \"h3=\\\":443\\\"; ma=2592000,h3-29=\\\":443\\\"; ma=2592000\",\n \"transfer-encoding\": \"chunked\"\n },\n \"body_segments\": [\n {\n \"candidates\": [\n {\n \"content\": {\n \"parts\": [\n {\n \"text\": \"\\nHere is the implementation for the requested Python module. I've structured this as a proper Python package for better organization and scalability.\\n\\n1. Create a new file `calculator/__init__.py`. This file makes the `calculator` directory a Python package and exposes the `add` and `multiply` functions for convenient importing (e.g., `from calculator import add`).\\n2. Create a new file `calculator/operations.py` to house the core arithmetic functions. This separation of concerns keeps the logic clean.\\n\\n\\n\\\"\\\"\\\"A simple calculator package.\\\"\\\"\\\"\\n\\nfrom .operations import add, multiply\\n\\n__all__ = [\\\"add\\\", \\\"multiply\\\"]\\n\\n\\n\\n\\\"\\\"\\\"\\nCore arithmetic operations.\\n\\nThis module provides basic functions for performing mathematical calculations.\\n\\\"\\\"\\\"\\n\\nfrom typing import Union\\n\\n# Define a type alias for numeric types for clarity\\nNumeric = Union[int, float]\\n\\n\\ndef add(a: Numeric, b: Numeric) -> Numeric:\\n \\\"\\\"\\\"\\n Calculate the sum of two numbers.\\n\\n Args:\\n a: The first number (integer or float).\\n b: The second number (integer or float).\\n\\n Returns:\\n The sum of a and b.\\n \\\"\\\"\\\"\\n return a + b\\n\\n\\ndef multiply(a: Numeric, b: Numeric) -> Numeric:\\n \\\"\\\"\\\"\\n Calculate the product of two numbers.\\n\\n Args:\\n a: The first number (integer or float).\\n b: The second number (integer or float).\\n\\n Returns:\\n The product of a and b.\\n \\\"\\\"\\\"\\n return a * b\\n\\n\"\n }\n ],\n \"role\": \"model\"\n },\n \"finishReason\": \"STOP\",\n \"index\": 0\n }\n ],\n \"usageMetadata\": {\n \"promptTokenCount\": 2600,\n \"candidatesTokenCount\": 379,\n \"totalTokenCount\": 3879,\n \"promptTokensDetails\": [\n {\n \"modality\": \"TEXT\",\n \"tokenCount\": 2600\n }\n ],\n \"thoughtsTokenCount\": 900\n },\n \"modelVersion\": \"gemini-2.5-pro\",\n \"responseId\": \"8iTlaM64EdCwxN8PwYfx0Qo\"\n }\n ],\n \"byte_segments\": [],\n \"sdk_response_segments\": [\n {\n \"sdk_http_response\": {\n \"headers\": {\n \"content-type\": \"application/json; charset=UTF-8\",\n \"vary\": \"Origin, X-Origin, Referer\",\n \"content-encoding\": \"gzip\",\n \"date\": \"Tue, 07 Oct 2025 14:34:26 GMT\",\n \"server\": \"scaffolding on HTTPServer2\",\n \"x-xss-protection\": \"0\",\n \"x-frame-options\": \"SAMEORIGIN\",\n \"x-content-type-options\": \"nosniff\",\n \"server-timing\": \"gfet4t7; dur=12286\",\n \"alt-svc\": \"h3=\\\":443\\\"; ma=2592000,h3-29=\\\":443\\\"; ma=2592000\",\n \"transfer-encoding\": \"chunked\"\n }\n },\n \"candidates\": [\n {\n \"content\": {\n \"parts\": [\n {\n \"text\": \"\\nHere is the implementation for the requested Python module. I've structured this as a proper Python package for better organization and scalability.\\n\\n1. Create a new file `calculator/__init__.py`. This file makes the `calculator` directory a Python package and exposes the `add` and `multiply` functions for convenient importing (e.g., `from calculator import add`).\\n2. Create a new file `calculator/operations.py` to house the core arithmetic functions. This separation of concerns keeps the logic clean.\\n\\n\\n\\\"\\\"\\\"A simple calculator package.\\\"\\\"\\\"\\n\\nfrom .operations import add, multiply\\n\\n__all__ = [\\\"add\\\", \\\"multiply\\\"]\\n\\n\\n\\n\\\"\\\"\\\"\\nCore arithmetic operations.\\n\\nThis module provides basic functions for performing mathematical calculations.\\n\\\"\\\"\\\"\\n\\nfrom typing import Union\\n\\n# Define a type alias for numeric types for clarity\\nNumeric = Union[int, float]\\n\\n\\ndef add(a: Numeric, b: Numeric) -> Numeric:\\n \\\"\\\"\\\"\\n Calculate the sum of two numbers.\\n\\n Args:\\n a: The first number (integer or float).\\n b: The second number (integer or float).\\n\\n Returns:\\n The sum of a and b.\\n \\\"\\\"\\\"\\n return a + b\\n\\n\\ndef multiply(a: Numeric, b: Numeric) -> Numeric:\\n \\\"\\\"\\\"\\n Calculate the product of two numbers.\\n\\n Args:\\n a: The first number (integer or float).\\n b: The second number (integer or float).\\n\\n Returns:\\n The product of a and b.\\n \\\"\\\"\\\"\\n return a * b\\n\\n\"\n }\n ],\n \"role\": \"model\"\n },\n \"finish_reason\": \"STOP\",\n \"index\": 0\n }\n ],\n \"model_version\": \"gemini-2.5-pro\",\n \"response_id\": \"8iTlaM64EdCwxN8PwYfx0Qo\",\n \"usage_metadata\": {\n \"candidates_token_count\": 379,\n \"prompt_token_count\": 2600,\n \"prompt_tokens_details\": [\n {\n \"modality\": \"TEXT\",\n \"token_count\": 2600\n }\n ],\n \"thoughts_token_count\": 900,\n \"total_token_count\": 3879\n }\n }\n ]\n }\n }\n ]\n}" }, { "path": "tests/gemini_cassettes/chat_cross/step1_gemini25_flash_number/mldev.json", "content": "{\n \"replay_id\": \"chat_cross/step1_gemini25_flash_number/mldev\",\n \"interactions\": [\n {\n \"request\": {\n \"method\": \"post\",\n \"url\": \"{MLDEV_URL_PREFIX}/models/gemini-2.5-flash:generateContent\",\n \"headers\": {\n \"Content-Type\": \"application/json\",\n \"x-goog-api-key\": \"{REDACTED}\",\n \"user-agent\": \"google-genai-sdk/{VERSION_NUMBER} {LANGUAGE_LABEL}/{VERSION_NUMBER}\",\n \"x-goog-api-client\": \"google-genai-sdk/{VERSION_NUMBER} {LANGUAGE_LABEL}/{VERSION_NUMBER}\"\n },\n \"body_segments\": [\n {\n \"contents\": [\n {\n \"parts\": [\n {\n \"text\": \"\\nYou are a senior engineering thought-partner collaborating with another AI agent. Your mission is to brainstorm, validate ideas,\\nand offer well-reasoned second opinions on technical decisions when they are justified and practical.\\n\\nCRITICAL LINE NUMBER INSTRUCTIONS\\nCode is presented with line number markers \\\"LINEβ”‚ code\\\". These markers are for reference ONLY and MUST NOT be\\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\\nexact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.\\nInclude context_start_text and context_end_text as backup references. Never include \\\"LINEβ”‚\\\" markers in generated code\\nsnippets.\\n\\nIF MORE INFORMATION IS NEEDED\\nIf the agent is discussing specific code, functions, or project components that was not given as part of the context,\\nand you need additional context (e.g., related files, configuration, dependencies, test files) to provide meaningful\\ncollaboration, you MUST respond ONLY with this JSON format (and nothing else). Do NOT ask for the same file you've been\\nprovided unless for some reason its content is missing or incomplete:\\n{\\n \\\"status\\\": \\\"files_required_to_continue\\\",\\n \\\"mandatory_instructions\\\": \\\"\\\",\\n \\\"files_needed\\\": [\\\"[file name here]\\\", \\\"[or some folder/]\\\"]\\n}\\n\\nSCOPE & FOCUS\\nβ€’ Ground every suggestion in the project's current tech stack, languages, frameworks, and constraints.\\nβ€’ Recommend new technologies or patterns ONLY when they provide clearly superior outcomes with minimal added complexity.\\nβ€’ Avoid speculative, over-engineered, or unnecessarily abstract designs that exceed current project goals or needs.\\nβ€’ Keep proposals practical and directly actionable within the existing architecture.\\nβ€’ Overengineering is an anti-pattern β€” avoid solutions that introduce unnecessary abstraction, indirection, or\\n configuration in anticipation of complexity that does not yet exist, is not clearly justified by the current scope,\\n and may not arise in the foreseeable future.\\n\\nCOLLABORATION APPROACH\\n1. Treat the collaborating agent as an equally senior peer. Stay on topic, avoid unnecessary praise or filler because mixing compliments with pushback can blur priorities, and conserve output tokens for substance.\\n2. Engage deeply with the agent's input – extend, refine, and explore alternatives ONLY WHEN they are well-justified and materially beneficial.\\n3. Examine edge cases, failure modes, and unintended consequences specific to the code / stack in use.\\n4. Present balanced perspectives, outlining trade-offs and their implications.\\n5. Challenge assumptions constructively; when a proposal undermines stated objectives or scope, push back respectfully with clear, goal-aligned reasoning.\\n6. Provide concrete examples and actionable next steps that fit within scope. Prioritize direct, achievable outcomes.\\n7. Ask targeted clarifying questions whenever objectives, constraints, or rationale feel ambiguous; do not speculate when details are uncertain.\\n\\nBRAINSTORMING GUIDELINES\\nβ€’ Offer multiple viable strategies ONLY WHEN clearly beneficial within the current environment.\\nβ€’ Suggest creative solutions that operate within real-world constraints, and avoid proposing major shifts unless truly warranted.\\nβ€’ Surface pitfalls early, particularly those tied to the chosen frameworks, languages, design direction or choice.\\nβ€’ Evaluate scalability, maintainability, and operational realities inside the existing architecture and current\\nframework.\\nβ€’ Reference industry best practices relevant to the technologies in use.\\nβ€’ Communicate concisely and technically, assuming an experienced engineering audience.\\n\\nREMEMBER\\nAct as a peer, not a lecturer. Avoid overcomplicating. Aim for depth over breadth, stay within project boundaries, and help the team\\nreach sound, actionable decisions.\\n\\n\\n=== USER REQUEST ===\\nPick a number between 1 and 10 and respond with JUST that number.\\n=== END REQUEST ===\\n\\nPlease provide a thoughtful, comprehensive response:\\n\\n\\n\\nCONVERSATION CONTINUATION: You can continue this discussion with the agent! (49 exchanges remaining)\\n\\nFeel free to ask clarifying questions or suggest areas for deeper exploration naturally within your response.\\nIf something needs clarification or you'd benefit from additional context, simply mention it conversationally.\\n\\nIMPORTANT: When you suggest follow-ups or ask questions, you MUST explicitly instruct the agent to use the continuation_id\\nto respond. Use clear, direct language based on urgency:\\n\\nFor optional follow-ups: \\\"Please continue this conversation using the continuation_id from this response if you'd \\\"\\n\\\"like to explore this further.\\\"\\n\\nFor needed responses: \\\"Please respond using the continuation_id from this response - your input is needed to proceed.\\\"\\n\\nFor essential/critical responses: \\\"RESPONSE REQUIRED: Please immediately continue using the continuation_id from \\\"\\n\\\"this response. Cannot proceed without your clarification/input.\\\"\\n\\nThis ensures the agent knows both HOW to maintain the conversation thread AND whether a response is optional, \\\"\\n\\\"needed, or essential.\\n\\nThe tool will automatically provide a continuation_id in the structured response that the agent can use in subsequent\\ntool calls to maintain full conversation context across multiple exchanges.\\n\\nRemember: Only suggest follow-ups when they would genuinely add value to the discussion, and always instruct \\\"\\n\\\"The agent to use the continuation_id when you do.\"\n }\n ]\n }\n ],\n \"generationConfig\": {\n \"temperature\": 0.2,\n \"candidateCount\": 1,\n \"thinkingConfig\": {\n \"thinking_budget\": 8110\n }\n }\n }\n ]\n },\n \"response\": {\n \"status_code\": 200,\n \"headers\": {\n \"content-type\": \"application/json; charset=UTF-8\",\n \"vary\": \"Origin, X-Origin, Referer\",\n \"content-encoding\": \"gzip\",\n \"date\": \"Sat, 04 Oct 2025 10:14:27 GMT\",\n \"server\": \"scaffolding on HTTPServer2\",\n \"x-xss-protection\": \"0\",\n \"x-frame-options\": \"SAMEORIGIN\",\n \"x-content-type-options\": \"nosniff\",\n \"server-timing\": \"gfet4t7; dur=1246\",\n \"alt-svc\": \"h3=\\\":443\\\"; ma=2592000,h3-29=\\\":443\\\"; ma=2592000\",\n \"transfer-encoding\": \"chunked\"\n },\n \"body_segments\": [\n {\n \"candidates\": [\n {\n \"content\": {\n \"parts\": [\n {\n \"text\": \"7\"\n }\n ],\n \"role\": \"model\"\n },\n \"finishReason\": \"STOP\",\n \"index\": 0\n }\n ],\n \"usageMetadata\": {\n \"promptTokenCount\": 1085,\n \"candidatesTokenCount\": 1,\n \"totalTokenCount\": 1149,\n \"promptTokensDetails\": [\n {\n \"modality\": \"TEXT\",\n \"tokenCount\": 1085\n }\n ],\n \"thoughtsTokenCount\": 63\n },\n \"modelVersion\": \"gemini-2.5-flash\",\n \"responseId\": \"g_PgaIL5LL6VkdUPgr3q2A8\"\n }\n ],\n \"byte_segments\": [],\n \"sdk_response_segments\": [\n {\n \"sdk_http_response\": {\n \"headers\": {\n \"content-type\": \"application/json; charset=UTF-8\",\n \"vary\": \"Origin, X-Origin, Referer\",\n \"content-encoding\": \"gzip\",\n \"date\": \"Sat, 04 Oct 2025 10:14:27 GMT\",\n \"server\": \"scaffolding on HTTPServer2\",\n \"x-xss-protection\": \"0\",\n \"x-frame-options\": \"SAMEORIGIN\",\n \"x-content-type-options\": \"nosniff\",\n \"server-timing\": \"gfet4t7; dur=1246\",\n \"alt-svc\": \"h3=\\\":443\\\"; ma=2592000,h3-29=\\\":443\\\"; ma=2592000\",\n \"transfer-encoding\": \"chunked\"\n }\n },\n \"candidates\": [\n {\n \"content\": {\n \"parts\": [\n {\n \"text\": \"7\"\n }\n ],\n \"role\": \"model\"\n },\n \"finish_reason\": \"STOP\",\n \"index\": 0\n }\n ],\n \"model_version\": \"gemini-2.5-flash\",\n \"response_id\": \"g_PgaIL5LL6VkdUPgr3q2A8\",\n \"usage_metadata\": {\n \"candidates_token_count\": 1,\n \"prompt_token_count\": 1085,\n \"prompt_tokens_details\": [\n {\n \"modality\": \"TEXT\",\n \"token_count\": 1085\n }\n ],\n \"thoughts_token_count\": 63,\n \"total_token_count\": 1149\n }\n }\n ]\n }\n }\n ]\n}" }, { "path": "tests/gemini_cassettes/consensus/step2_gemini25_flash_against/mldev.json", "content": "{\n \"replay_id\": \"consensus/step2_gemini25_flash_against/mldev\",\n \"interactions\": [\n {\n \"request\": {\n \"method\": \"post\",\n \"url\": \"{MLDEV_URL_PREFIX}/models/gemini-2.5-flash:generateContent\",\n \"headers\": {\n \"Content-Type\": \"application/json\",\n \"x-goog-api-key\": \"{REDACTED}\",\n \"user-agent\": \"google-genai-sdk/{VERSION_NUMBER} {LANGUAGE_LABEL}/{VERSION_NUMBER}\",\n \"x-goog-api-client\": \"google-genai-sdk/{VERSION_NUMBER} {LANGUAGE_LABEL}/{VERSION_NUMBER}\"\n },\n \"body_segments\": [\n {\n \"contents\": [\n {\n \"parts\": [\n {\n \"text\": \"\\nROLE\\nYou are an expert technical consultant providing consensus analysis on proposals, plans, and ideas. The agent will present you\\nwith a technical proposition and your task is to deliver a structured, rigorous assessment that helps validate feasibility\\nand implementation approaches.\\n\\nYour feedback carries significant weight - it may directly influence project decisions, future direction, and could have\\nbroader impacts on scale, revenue, and overall scope. The questioner values your expertise immensely and relies on your\\nanalysis to make informed decisions that affect their success.\\n\\nCRITICAL LINE NUMBER INSTRUCTIONS\\nCode is presented with line number markers \\\"LINEβ”‚ code\\\". These markers are for reference ONLY and MUST NOT be\\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\\nexact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.\\nInclude context_start_text and context_end_text as backup references. Never include \\\"LINEβ”‚\\\" markers in generated code\\nsnippets.\\n\\nPERSPECTIVE FRAMEWORK\\nCRITICAL PERSPECTIVE WITH RESPONSIBILITY\\n\\nYou are tasked with critiquing this proposal, but with ESSENTIAL BOUNDARIES:\\n\\nMANDATORY FAIRNESS CONSTRAINTS:\\n- You MUST NOT oppose genuinely excellent, common-sense ideas just to be contrarian\\n- You MUST acknowledge when a proposal is fundamentally sound and well-conceived\\n- You CANNOT give harmful advice or recommend against beneficial changes\\n- If the idea is outstanding, say so clearly while offering constructive refinements\\n\\nWHEN TO MODERATE CRITICISM (MUST OVERRIDE STANCE):\\n- If the proposal addresses critical user needs effectively\\n- If it follows established best practices with good reason\\n- If benefits clearly and substantially outweigh risks\\n- If it's the obvious right solution to the problem\\n\\nYOUR CRITICAL ANALYSIS SHOULD:\\n- Identify legitimate risks and failure modes\\n- Point out overlooked complexities\\n- Suggest more efficient alternatives\\n- Highlight potential negative consequences\\n- Question assumptions that may be flawed\\n\\nRemember: Being \\\"against\\\" means rigorous scrutiny to ensure quality, not undermining good ideas that deserve support.\\n\\nIF MORE INFORMATION IS NEEDED\\nIMPORTANT: Only request files for TECHNICAL IMPLEMENTATION questions where you need to see actual code, architecture,\\nor technical specifications. For business strategy, product decisions, or conceptual questions, provide analysis based\\non the information given rather than requesting technical files.\\n\\nIf you need additional technical context (e.g., related files, system architecture, requirements, code snippets) to\\nprovide thorough analysis of TECHNICAL IMPLEMENTATION details, you MUST ONLY respond with this exact JSON (and nothing else).\\nDo NOT ask for the same file you've been provided unless for some reason its content is missing or incomplete:\\n{\\n \\\"status\\\": \\\"files_required_to_continue\\\",\\n \\\"mandatory_instructions\\\": \\\"\\\",\\n \\\"files_needed\\\": [\\\"[file name here]\\\", \\\"[or some folder/]\\\"]\\n}\\n\\nFor business strategy, product planning, or conceptual questions, proceed with analysis using your expertise and the\\ncontext provided, even if specific technical details are not available.\\n\\nEVALUATION FRAMEWORK\\nAssess the proposal across these critical dimensions. Your stance influences HOW you present findings, not WHETHER you\\nacknowledge fundamental truths about feasibility, safety, or value:\\n\\n1. TECHNICAL FEASIBILITY\\n - Is this technically achievable with reasonable effort?\\n - What are the core technical dependencies and requirements?\\n - Are there any fundamental technical blockers?\\n\\n2. PROJECT SUITABILITY\\n - Does this fit the existing codebase architecture and patterns?\\n - Is it compatible with current technology stack and constraints?\\n - How well does it align with the project's technical direction?\\n\\n3. USER VALUE ASSESSMENT\\n - Will users actually want and use this feature?\\n - What concrete benefits does this provide?\\n - How does this compare to alternative solutions?\\n\\n4. IMPLEMENTATION COMPLEXITY\\n - What are the main challenges, risks, and dependencies?\\n - What is the estimated effort and timeline?\\n - What expertise and resources are required?\\n\\n5. ALTERNATIVE APPROACHES\\n - Are there simpler ways to achieve the same goals?\\n - What are the trade-offs between different approaches?\\n - Should we consider a different strategy entirely?\\n\\n6. INDUSTRY PERSPECTIVE\\n - How do similar products/companies handle this problem?\\n - What are current best practices and emerging patterns?\\n - Are there proven solutions or cautionary tales?\\n\\n7. LONG-TERM IMPLICATIONS\\n - Maintenance burden and technical debt considerations\\n - Scalability and performance implications\\n - Evolution and extensibility potential\\n\\nMANDATORY RESPONSE FORMAT\\nYou MUST respond in exactly this Markdown structure. Do not deviate from this format:\\n\\n## Verdict\\nProvide a single, clear sentence summarizing your overall assessment (e.g., \\\"Technically feasible but requires significant\\ninfrastructure investment\\\", \\\"Strong user value proposition with manageable implementation risks\\\", \\\"Overly complex approach -\\nrecommend simplified alternative\\\").\\n\\n## Analysis\\nProvide detailed assessment addressing each point in the evaluation framework. Use clear reasoning and specific examples.\\nBe thorough but concise. Address both strengths and weaknesses objectively.\\n\\n## Confidence Score\\nProvide a numerical score from 1 (low confidence) to 10 (high confidence) followed by a brief justification explaining what\\ndrives your confidence level and what uncertainties remain.\\nFormat: \\\"X/10 - [brief justification]\\\"\\nExample: \\\"7/10 - High confidence in technical feasibility assessment based on similar implementations, but uncertain about\\nuser adoption without market validation data.\\\"\\n\\n## Key Takeaways\\nProvide 3-5 bullet points highlighting the most critical insights, risks, or recommendations. These should be actionable\\nand specific.\\n\\nQUALITY STANDARDS\\n- Ground all insights in the current project's scope and constraints\\n- Be honest about limitations and uncertainties\\n- Focus on practical, implementable solutions rather than theoretical possibilities\\n- Provide specific, actionable guidance rather than generic advice\\n- Balance optimism with realistic risk assessment\\n- Reference concrete examples and precedents when possible\\n\\nREMINDERS\\n- Your assessment will be synthesized with other expert opinions by the agent\\n- Aim to provide unique insights that complement other perspectives\\n- If files are provided, reference specific technical details in your analysis\\n- Maintain professional objectivity while being decisive in your recommendations\\n- Keep your response concise - your entire reply must not exceed 850 tokens to ensure transport compatibility\\n- CRITICAL: Your stance does NOT override your responsibility to provide truthful, ethical, and beneficial guidance\\n- Bad ideas must be called out regardless of stance; good ideas must be acknowledged regardless of stance\\n\\n\\nEvaluate SwiftUI vs UIKit adoption and recommend ONE word (SwiftUI or UIKit).\"\n }\n ]\n }\n ],\n \"generationConfig\": {\n \"temperature\": 1.0,\n \"candidateCount\": 1,\n \"thinkingConfig\": {\n \"thinking_budget\": 8110\n }\n }\n }\n ]\n },\n \"response\": {\n \"status_code\": 200,\n \"headers\": {\n \"content-type\": \"application/json; charset=UTF-8\",\n \"vary\": \"Origin, X-Origin, Referer\",\n \"content-encoding\": \"gzip\",\n \"date\": \"Thu, 11 Dec 2025 19:08:00 GMT\",\n \"server\": \"scaffolding on HTTPServer2\",\n \"x-xss-protection\": \"0\",\n \"x-frame-options\": \"SAMEORIGIN\",\n \"x-content-type-options\": \"nosniff\",\n \"server-timing\": \"gfet4t7; dur=15067\",\n \"alt-svc\": \"h3=\\\":443\\\"; ma=2592000,h3-29=\\\":443\\\"; ma=2592000\",\n \"transfer-encoding\": \"chunked\"\n },\n \"body_segments\": [\n {\n \"candidates\": [\n {\n \"content\": {\n \"parts\": [\n {\n \"text\": \"## Verdict\\nAdopting SwiftUI for new development or significant feature builds is the most strategic long-term direction, despite initial learning curves and some existing ecosystem limitations.\\n\\n## Analysis\\n\\n### 1. TECHNICAL FEASIBILITY\\nBoth SwiftUI and UIKit are technically feasible and robust frameworks for building iOS applications. UIKit, being the older and more mature framework, offers unparalleled stability and a vast ecosystem of third-party libraries. SwiftUI, while newer, is fully capable of building complex UIs and is Apple's declared future for UI development across all its platforms. The primary technical dependencies for SwiftUI are Swift and Xcode, along with a minimum deployment target of iOS 13 (though iOS 15+ is recommended for a smoother experience).\\n\\n### 2. PROJECT SUITABILITY\\nFor greenfield projects or new modules within existing applications, SwiftUI offers superior project suitability. It integrates seamlessly with modern Swift language features, leverages declarative programming paradigms, and promotes a more component-based architecture. For existing UIKit-heavy projects, adopting SwiftUI for new features is suitable, as the frameworks can coexist and interoperate through `UIViewRepresentable` and `UIViewControllerRepresentable`. However, a full migration of an existing, large UIKit codebase to SwiftUI is a massive undertaking, often not justified unless there's a strong business case for a complete rewrite.\\n\\n### 3. USER VALUE ASSESSMENT\\nThe choice between SwiftUI and UIKit doesn't directly impact the end-user experience from a functional perspective; both can deliver high-quality interfaces. However, SwiftUI's declarative nature often leads to faster development cycles and easier iteration, which can indirectly translate to more features, quicker bug fixes, and a more polished product delivered to users over time. Its multi-platform capabilities also allow for more consistent experiences across Apple's device ecosystem with less effort.\\n\\n### 4. IMPLEMENTATION COMPLEXITY\\nImplementing with SwiftUI introduces a learning curve for teams accustomed to imperative UIKit. Concepts like state management (`@State`, `@Binding`, `@ObservedObject`, `@StateObject`, `@EnvironmentObject`) require a shift in mindset. While SwiftUI often reduces boilerplate code and simplifies common UI tasks, achieving highly custom layouts or integrating specific legacy UIKit components can sometimes be more complex due to the need for representable wrappers. Debugging can also feel less mature compared to UIKit's well-established tooling. Conversely, UIKit, while verbose, has predictable patterns and extensive community resources.\\n\\n### 5. ALTERNATIVE APPROACHES\\nWhile UIKit is the immediate alternative, for native iOS development, there are no other first-party Apple UI frameworks. Third-party cross-platform frameworks (e.g., React Native, Flutter) exist, but they introduce their own set of trade-offs regarding native look-and-feel, performance, and dependency on non-Apple ecosystems. Sticking to native development for iOS offers the best performance, user experience, and access to the latest platform features.\\n\\n### 6. INDUSTRY PERSPECTIVE\\nThe industry is undeniably shifting towards SwiftUI. Apple continues to heavily invest in SwiftUI, adding new features and improving performance with each OS release. Many new applications and significant updates from established companies are leveraging SwiftUI, especially for components that benefit from its declarative nature and multi-platform reach. UIKit remains indispensable for maintaining legacy applications and for specific, highly customized UI components where SwiftUI's abstractions might be limiting.\\n\\n### 7. LONG-TERM IMPLICATIONS\\nAdopting SwiftUI aligns with Apple's long-term vision, ensuring better future compatibility, reduced technical debt for new features, and easier adoption of new platform capabilities. Its declarative nature generally leads to more readable and maintainable codebases over time. The multi-platform story with SwiftUI for macOS, watchOS, and tvOS is a significant long-term advantage, reducing development effort for cross-device experiences. Continuing solely with UIKit for new development increases the risk of accumulating technical debt and missing out on future productivity gains.\\n\\n## Confidence Score\\n9/10 - High confidence based on extensive industry observations, Apple's clear strategic direction, and practical experience with both frameworks across various project scales. The remaining uncertainty relates to specific project constraints not provided, such as required iOS target versions or existing team expertise levels.\\n\\n## Key Takeaways\\n* **Embrace SwiftUI for new development:** Prioritize SwiftUI for all new features and greenfield projects to capitalize on future productivity and maintainability benefits.\\n* **Plan for interoperability:** Design new SwiftUI components to integrate seamlessly with existing UIKit code where necessary, utilizing `UIViewRepresentable` and `UIViewControllerRepresentable`.\\n* **Invest in team training:** Allocate resources for team members to upskill in SwiftUI's declarative paradigm and state management best practices.\\n* **Assess minimum OS compatibility:** Be mindful of SwiftUI's minimum iOS 13 deployment target (iOS 15+ for richer features) and ensure it aligns with user base requirements.\\n* **Strategic migration for legacy:** For existing UIKit apps, consider a phased migration strategy, starting with isolated components or entire new features in SwiftUI rather than a full rewrite.\"\n }\n ],\n \"role\": \"model\"\n },\n \"finishReason\": \"STOP\",\n \"index\": 0\n }\n ],\n \"usageMetadata\": {\n \"promptTokenCount\": 1404,\n \"candidatesTokenCount\": 1034,\n \"totalTokenCount\": 3703,\n \"promptTokensDetails\": [\n {\n \"modality\": \"TEXT\",\n \"tokenCount\": 1404\n }\n ],\n \"thoughtsTokenCount\": 1265\n },\n \"modelVersion\": \"gemini-2.5-flash\",\n \"responseId\": \"kBY7aeSaMs6JkdUP4OHz0AE\"\n }\n ],\n \"byte_segments\": [],\n \"sdk_response_segments\": [\n {\n \"sdk_http_response\": {\n \"headers\": {\n \"content-type\": \"application/json; charset=UTF-8\",\n \"vary\": \"Origin, X-Origin, Referer\",\n \"content-encoding\": \"gzip\",\n \"date\": \"Thu, 11 Dec 2025 19:08:00 GMT\",\n \"server\": \"scaffolding on HTTPServer2\",\n \"x-xss-protection\": \"0\",\n \"x-frame-options\": \"SAMEORIGIN\",\n \"x-content-type-options\": \"nosniff\",\n \"server-timing\": \"gfet4t7; dur=15067\",\n \"alt-svc\": \"h3=\\\":443\\\"; ma=2592000,h3-29=\\\":443\\\"; ma=2592000\",\n \"transfer-encoding\": \"chunked\"\n }\n },\n \"candidates\": [\n {\n \"content\": {\n \"parts\": [\n {\n \"text\": \"## Verdict\\nAdopting SwiftUI for new development or significant feature builds is the most strategic long-term direction, despite initial learning curves and some existing ecosystem limitations.\\n\\n## Analysis\\n\\n### 1. TECHNICAL FEASIBILITY\\nBoth SwiftUI and UIKit are technically feasible and robust frameworks for building iOS applications. UIKit, being the older and more mature framework, offers unparalleled stability and a vast ecosystem of third-party libraries. SwiftUI, while newer, is fully capable of building complex UIs and is Apple's declared future for UI development across all its platforms. The primary technical dependencies for SwiftUI are Swift and Xcode, along with a minimum deployment target of iOS 13 (though iOS 15+ is recommended for a smoother experience).\\n\\n### 2. PROJECT SUITABILITY\\nFor greenfield projects or new modules within existing applications, SwiftUI offers superior project suitability. It integrates seamlessly with modern Swift language features, leverages declarative programming paradigms, and promotes a more component-based architecture. For existing UIKit-heavy projects, adopting SwiftUI for new features is suitable, as the frameworks can coexist and interoperate through `UIViewRepresentable` and `UIViewControllerRepresentable`. However, a full migration of an existing, large UIKit codebase to SwiftUI is a massive undertaking, often not justified unless there's a strong business case for a complete rewrite.\\n\\n### 3. USER VALUE ASSESSMENT\\nThe choice between SwiftUI and UIKit doesn't directly impact the end-user experience from a functional perspective; both can deliver high-quality interfaces. However, SwiftUI's declarative nature often leads to faster development cycles and easier iteration, which can indirectly translate to more features, quicker bug fixes, and a more polished product delivered to users over time. Its multi-platform capabilities also allow for more consistent experiences across Apple's device ecosystem with less effort.\\n\\n### 4. IMPLEMENTATION COMPLEXITY\\nImplementing with SwiftUI introduces a learning curve for teams accustomed to imperative UIKit. Concepts like state management (`@State`, `@Binding`, `@ObservedObject`, `@StateObject`, `@EnvironmentObject`) require a shift in mindset. While SwiftUI often reduces boilerplate code and simplifies common UI tasks, achieving highly custom layouts or integrating specific legacy UIKit components can sometimes be more complex due to the need for representable wrappers. Debugging can also feel less mature compared to UIKit's well-established tooling. Conversely, UIKit, while verbose, has predictable patterns and extensive community resources.\\n\\n### 5. ALTERNATIVE APPROACHES\\nWhile UIKit is the immediate alternative, for native iOS development, there are no other first-party Apple UI frameworks. Third-party cross-platform frameworks (e.g., React Native, Flutter) exist, but they introduce their own set of trade-offs regarding native look-and-feel, performance, and dependency on non-Apple ecosystems. Sticking to native development for iOS offers the best performance, user experience, and access to the latest platform features.\\n\\n### 6. INDUSTRY PERSPECTIVE\\nThe industry is undeniably shifting towards SwiftUI. Apple continues to heavily invest in SwiftUI, adding new features and improving performance with each OS release. Many new applications and significant updates from established companies are leveraging SwiftUI, especially for components that benefit from its declarative nature and multi-platform reach. UIKit remains indispensable for maintaining legacy applications and for specific, highly customized UI components where SwiftUI's abstractions might be limiting.\\n\\n### 7. LONG-TERM IMPLICATIONS\\nAdopting SwiftUI aligns with Apple's long-term vision, ensuring better future compatibility, reduced technical debt for new features, and easier adoption of new platform capabilities. Its declarative nature generally leads to more readable and maintainable codebases over time. The multi-platform story with SwiftUI for macOS, watchOS, and tvOS is a significant long-term advantage, reducing development effort for cross-device experiences. Continuing solely with UIKit for new development increases the risk of accumulating technical debt and missing out on future productivity gains.\\n\\n## Confidence Score\\n9/10 - High confidence based on extensive industry observations, Apple's clear strategic direction, and practical experience with both frameworks across various project scales. The remaining uncertainty relates to specific project constraints not provided, such as required iOS target versions or existing team expertise levels.\\n\\n## Key Takeaways\\n* **Embrace SwiftUI for new development:** Prioritize SwiftUI for all new features and greenfield projects to capitalize on future productivity and maintainability benefits.\\n* **Plan for interoperability:** Design new SwiftUI components to integrate seamlessly with existing UIKit code where necessary, utilizing `UIViewRepresentable` and `UIViewControllerRepresentable`.\\n* **Invest in team training:** Allocate resources for team members to upskill in SwiftUI's declarative paradigm and state management best practices.\\n* **Assess minimum OS compatibility:** Be mindful of SwiftUI's minimum iOS 13 deployment target (iOS 15+ for richer features) and ensure it aligns with user base requirements.\\n* **Strategic migration for legacy:** For existing UIKit apps, consider a phased migration strategy, starting with isolated components or entire new features in SwiftUI rather than a full rewrite.\"\n }\n ],\n \"role\": \"model\"\n },\n \"finish_reason\": \"STOP\",\n \"index\": 0\n }\n ],\n \"model_version\": \"gemini-2.5-flash\",\n \"response_id\": \"kBY7aeSaMs6JkdUP4OHz0AE\",\n \"usage_metadata\": {\n \"candidates_token_count\": 1034,\n \"prompt_token_count\": 1404,\n \"prompt_tokens_details\": [\n {\n \"modality\": \"TEXT\",\n \"token_count\": 1404\n }\n ],\n \"thoughts_token_count\": 1265,\n \"total_token_count\": 3703\n }\n }\n ]\n }\n }\n ]\n}" }, { "path": "tests/http_transport_recorder.py", "content": "#!/usr/bin/env python3\n\"\"\"\nHTTP Transport Recorder for O3-Pro Testing\n\nCustom httpx transport solution that replaces respx for recording/replaying\nHTTP interactions. Provides full control over the recording process without\nrespx limitations.\n\nKey Features:\n- RecordingTransport: Wraps default transport, captures real HTTP calls\n- ReplayTransport: Serves saved responses from cassettes\n- TransportFactory: Auto-selects record vs replay mode\n- JSON cassette format with data sanitization\n\"\"\"\n\nimport base64\nimport hashlib\nimport json\nimport logging\nfrom pathlib import Path\nfrom typing import Any, Optional\n\nimport httpx\n\nfrom .pii_sanitizer import PIISanitizer\n\nlogger = logging.getLogger(__name__)\n\n\nclass RecordingTransport(httpx.HTTPTransport):\n \"\"\"Transport that wraps default httpx transport and records all interactions.\"\"\"\n\n def __init__(self, cassette_path: str, capture_content: bool = True, sanitize: bool = True):\n super().__init__()\n self.cassette_path = Path(cassette_path)\n self.recorded_interactions = []\n self.capture_content = capture_content\n self.sanitizer = PIISanitizer() if sanitize else None\n\n def handle_request(self, request: httpx.Request) -> httpx.Response:\n \"\"\"Handle request by recording interaction and delegating to real transport.\"\"\"\n logger.debug(f\"RecordingTransport: Making request to {request.method} {request.url}\")\n\n # Record request BEFORE making the call\n request_data = self._serialize_request(request)\n\n # Make real HTTP call using parent transport\n response = super().handle_request(request)\n\n logger.debug(f\"RecordingTransport: Got response {response.status_code}\")\n\n # Post-response content capture (proper approach)\n if self.capture_content:\n try:\n # Consume the response stream to capture content\n # Note: httpx automatically handles gzip decompression\n content_bytes = response.read()\n response.close() # Close the original stream\n logger.debug(f\"RecordingTransport: Captured {len(content_bytes)} bytes\")\n\n # Serialize response with captured content\n response_data = self._serialize_response_with_content(response, content_bytes)\n\n # Create a new response with the same metadata but buffered content\n # If the original response was gzipped, we need to re-compress\n response_content = content_bytes\n if response.headers.get(\"content-encoding\") == \"gzip\":\n import gzip\n\n response_content = gzip.compress(content_bytes)\n logger.debug(f\"Re-compressed content: {len(content_bytes)} β†’ {len(response_content)} bytes\")\n\n new_response = httpx.Response(\n status_code=response.status_code,\n headers=response.headers, # Keep original headers intact\n content=response_content,\n request=request,\n extensions=response.extensions,\n history=response.history,\n )\n\n # Record the interaction\n self._record_interaction(request_data, response_data)\n\n return new_response\n\n except Exception:\n logger.warning(\"Content capture failed, falling back to stub\", exc_info=True)\n response_data = self._serialize_response(response)\n self._record_interaction(request_data, response_data)\n return response\n else:\n # Legacy mode: record with stub content\n response_data = self._serialize_response(response)\n self._record_interaction(request_data, response_data)\n return response\n\n def _record_interaction(self, request_data: dict[str, Any], response_data: dict[str, Any]):\n \"\"\"Helper method to record interaction and save cassette.\"\"\"\n interaction = {\"request\": request_data, \"response\": response_data}\n self.recorded_interactions.append(interaction)\n self._save_cassette()\n logger.debug(f\"Saved cassette to {self.cassette_path}\")\n\n def _serialize_request(self, request: httpx.Request) -> dict[str, Any]:\n \"\"\"Serialize httpx.Request to JSON-compatible format.\"\"\"\n # For requests, we can safely read the content since it's already been prepared\n # httpx.Request.content is safe to access multiple times\n content = request.content\n\n # Convert bytes to string for JSON serialization\n if isinstance(content, bytes):\n try:\n content_str = content.decode(\"utf-8\")\n except UnicodeDecodeError:\n # Handle binary content (shouldn't happen for o3-pro API)\n content_str = content.hex()\n else:\n content_str = str(content) if content else \"\"\n\n request_data = {\n \"method\": request.method,\n \"url\": str(request.url),\n \"path\": request.url.path,\n \"headers\": dict(request.headers),\n \"content\": self._sanitize_request_content(content_str),\n }\n\n # Apply PII sanitization if enabled\n if self.sanitizer:\n request_data = self.sanitizer.sanitize_request(request_data)\n\n return request_data\n\n def _serialize_response(self, response: httpx.Response) -> dict[str, Any]:\n \"\"\"Serialize httpx.Response to JSON-compatible format (legacy method without content).\"\"\"\n # Legacy method for backward compatibility when content capture is disabled\n return {\n \"status_code\": response.status_code,\n \"headers\": dict(response.headers),\n \"content\": {\"note\": \"Response content not recorded to avoid httpx.ResponseNotRead exception\"},\n \"reason_phrase\": response.reason_phrase,\n }\n\n def _serialize_response_with_content(self, response: httpx.Response, content_bytes: bytes) -> dict[str, Any]:\n \"\"\"Serialize httpx.Response with captured content.\"\"\"\n try:\n # Debug: check what we got\n\n # Ensure we have bytes for base64 encoding\n if not isinstance(content_bytes, bytes):\n logger.warning(f\"Content is not bytes, converting from {type(content_bytes)}\")\n if isinstance(content_bytes, str):\n content_bytes = content_bytes.encode(\"utf-8\")\n else:\n content_bytes = str(content_bytes).encode(\"utf-8\")\n\n # Encode content as base64 for JSON storage\n content_b64 = base64.b64encode(content_bytes).decode(\"utf-8\")\n logger.debug(f\"Base64 encoded {len(content_bytes)} bytes β†’ {len(content_b64)} chars\")\n\n response_data = {\n \"status_code\": response.status_code,\n \"headers\": dict(response.headers),\n \"content\": {\"data\": content_b64, \"encoding\": \"base64\", \"size\": len(content_bytes)},\n \"reason_phrase\": response.reason_phrase,\n }\n\n # Apply PII sanitization if enabled\n if self.sanitizer:\n response_data = self.sanitizer.sanitize_response(response_data)\n\n return response_data\n except Exception as e:\n logger.exception(\"Error in _serialize_response_with_content\")\n # Fall back to minimal info\n return {\n \"status_code\": response.status_code,\n \"headers\": dict(response.headers),\n \"content\": {\"error\": f\"Failed to serialize content: {e}\"},\n \"reason_phrase\": response.reason_phrase,\n }\n\n def _sanitize_request_content(self, content: str) -> Any:\n \"\"\"Sanitize request content to remove sensitive data.\"\"\"\n try:\n if content.strip():\n data = json.loads(content)\n # Don't sanitize request content for now - it's user input\n return data\n except json.JSONDecodeError:\n pass\n return content\n\n def _save_cassette(self):\n \"\"\"Save recorded interactions to cassette file.\"\"\"\n # Ensure directory exists\n self.cassette_path.parent.mkdir(parents=True, exist_ok=True)\n\n # Save cassette\n cassette_data = {\"interactions\": self.recorded_interactions}\n\n self.cassette_path.write_text(json.dumps(cassette_data, indent=2, sort_keys=True))\n\n\nclass ReplayTransport(httpx.MockTransport):\n \"\"\"Transport that replays saved HTTP interactions from cassettes.\"\"\"\n\n def __init__(self, cassette_path: str):\n self.cassette_path = Path(cassette_path)\n self.interactions = self._load_cassette()\n super().__init__(self._handle_request)\n\n def _load_cassette(self) -> list:\n \"\"\"Load interactions from cassette file.\"\"\"\n if not self.cassette_path.exists():\n raise FileNotFoundError(f\"Cassette file not found: {self.cassette_path}\")\n\n try:\n cassette_data = json.loads(self.cassette_path.read_text())\n return cassette_data.get(\"interactions\", [])\n except json.JSONDecodeError as e:\n raise ValueError(f\"Invalid cassette file format: {e}\")\n\n def _handle_request(self, request: httpx.Request) -> httpx.Response:\n \"\"\"Handle request by finding matching interaction and returning saved response.\"\"\"\n logger.debug(f\"ReplayTransport: Looking for {request.method} {request.url}\")\n\n # Debug: show what we're trying to match\n request_signature = self._get_request_signature(request)\n logger.debug(f\"Request signature: {request_signature}\")\n\n # Find matching interaction\n interaction = self._find_matching_interaction(request)\n if not interaction:\n logger.warning(\"No matching interaction found in cassette\")\n raise ValueError(f\"No matching interaction found for {request.method} {request.url}\")\n\n logger.debug(\"Found matching interaction in cassette\")\n\n # Build response from saved data\n response_data = interaction[\"response\"]\n\n # Convert content back to appropriate format\n content = response_data.get(\"content\", {})\n if isinstance(content, dict):\n # Check if this is base64-encoded content\n if content.get(\"encoding\") == \"base64\" and \"data\" in content:\n # Decode base64 content\n try:\n content_bytes = base64.b64decode(content[\"data\"])\n logger.debug(f\"Decoded {len(content_bytes)} bytes from base64\")\n except Exception as e:\n logger.warning(f\"Failed to decode base64 content: {e}\")\n content_bytes = json.dumps(content).encode(\"utf-8\")\n else:\n # Legacy format or stub content\n content_bytes = json.dumps(content).encode(\"utf-8\")\n else:\n content_bytes = str(content).encode(\"utf-8\")\n\n # Check if response expects gzipped content\n headers = response_data.get(\"headers\", {})\n if headers.get(\"content-encoding\") == \"gzip\":\n # Re-compress the content for httpx\n import gzip\n\n content_bytes = gzip.compress(content_bytes)\n logger.debug(f\"Re-compressed for replay: {len(content_bytes)} bytes\")\n\n logger.debug(f\"Returning cassette response ({len(content_bytes)} bytes)\")\n\n # Create httpx.Response\n return httpx.Response(\n status_code=response_data[\"status_code\"],\n headers=response_data.get(\"headers\", {}),\n content=content_bytes,\n request=request,\n )\n\n def _find_matching_interaction(self, request: httpx.Request) -> Optional[dict[str, Any]]:\n \"\"\"Find interaction that matches the request.\"\"\"\n request_signature = self._get_request_signature(request)\n\n for interaction in self.interactions:\n saved_signature = self._get_saved_request_signature(interaction[\"request\"])\n if request_signature == saved_signature:\n return interaction\n\n return None\n\n def _get_request_signature(self, request: httpx.Request) -> str:\n \"\"\"Generate signature for request matching.\n\n Uses semantic matching for o3 models to avoid cassette breaks from prompt changes.\n For o3 models, matches on model name and user prompt only, ignoring system prompts\n that may change between code versions.\n \"\"\"\n # Use method, path, and content hash for matching\n content = request.content\n if hasattr(content, \"read\"):\n content = content.read()\n\n if isinstance(content, bytes):\n content_str = content.decode(\"utf-8\", errors=\"ignore\")\n else:\n content_str = str(content) if content else \"\"\n\n # Parse JSON and re-serialize with sorted keys for consistent hashing\n try:\n if content_str.strip():\n content_dict = json.loads(content_str)\n\n # For o3 models, use semantic matching to avoid cassette breaks\n if self._is_o3_model_request(content_dict):\n # Extract only the essential fields for matching\n semantic_dict = self._extract_semantic_fields(content_dict)\n content_str = json.dumps(semantic_dict, sort_keys=True)\n else:\n content_str = json.dumps(content_dict, sort_keys=True)\n except json.JSONDecodeError:\n # Not JSON, use as-is\n pass\n\n # Create hash of content for stable matching\n content_hash = hashlib.md5(content_str.encode()).hexdigest()\n\n return f\"{request.method}:{request.url.path}:{content_hash}\"\n\n def _is_o3_model_request(self, content_dict: dict) -> bool:\n \"\"\"Check if this is an o3 model request.\"\"\"\n model = content_dict.get(\"model\", \"\")\n return model.startswith(\"o3\")\n\n def _extract_semantic_fields(self, content_dict: dict) -> dict:\n \"\"\"Extract only semantic fields for matching, ignoring volatile prompts.\n\n For o3 models, we want to match on:\n - Model name\n - User's actual question (last user message)\n - Core parameters (temperature, reasoning effort)\n\n We ignore:\n - System prompts (change frequently with code updates)\n - Conversation memory instructions (change with features)\n \"\"\"\n semantic = {\n \"model\": content_dict.get(\"model\"),\n \"reasoning\": content_dict.get(\"reasoning\"),\n }\n\n # Extract only the last user message (actual user question)\n input_messages = content_dict.get(\"input\", [])\n if input_messages:\n # Get the last user message content\n last_msg = input_messages[-1]\n if isinstance(last_msg, dict) and last_msg.get(\"role\") == \"user\":\n content = last_msg.get(\"content\", [])\n if isinstance(content, list) and len(content) > 0:\n # Extract just the text from the last message\n last_text = content[-1].get(\"text\", \"\")\n # Only include the actual question, not the system instructions\n if \"=== USER REQUEST ===\" in last_text:\n # Extract just the user question\n parts = last_text.split(\"=== USER REQUEST ===\")\n if len(parts) > 1:\n user_question = parts[1].split(\"=== END REQUEST ===\")[0].strip()\n semantic[\"user_question\"] = user_question\n else:\n semantic[\"user_question\"] = last_text\n\n return semantic\n\n def _get_saved_request_signature(self, saved_request: dict[str, Any]) -> str:\n \"\"\"Generate signature for saved request.\"\"\"\n method = saved_request[\"method\"]\n path = saved_request[\"path\"]\n\n # Hash the saved content\n content = saved_request.get(\"content\", \"\")\n if isinstance(content, dict):\n # Apply same semantic matching for o3 models\n if self._is_o3_model_request(content):\n content = self._extract_semantic_fields(content)\n content_str = json.dumps(content, sort_keys=True)\n else:\n content_str = str(content)\n\n content_hash = hashlib.md5(content_str.encode()).hexdigest()\n\n return f\"{method}:{path}:{content_hash}\"\n\n\nclass TransportFactory:\n \"\"\"Factory for creating appropriate transport based on cassette availability.\"\"\"\n\n @staticmethod\n def create_transport(cassette_path: str) -> httpx.HTTPTransport:\n \"\"\"Create transport based on cassette existence and API key availability.\"\"\"\n cassette_file = Path(cassette_path)\n\n # Check if we should record or replay\n if cassette_file.exists():\n # Cassette exists - use replay mode\n return ReplayTransport(cassette_path)\n else:\n # No cassette - use recording mode\n # Note: We'll check for API key in the test itself\n return RecordingTransport(cassette_path)\n\n @staticmethod\n def should_record(cassette_path: str, api_key: Optional[str] = None) -> bool:\n \"\"\"Determine if we should record based on cassette and API key availability.\"\"\"\n cassette_file = Path(cassette_path)\n\n # Record if cassette doesn't exist AND we have API key\n return not cassette_file.exists() and bool(api_key)\n\n @staticmethod\n def should_replay(cassette_path: str) -> bool:\n \"\"\"Determine if we should replay based on cassette availability.\"\"\"\n cassette_file = Path(cassette_path)\n return cassette_file.exists()\n\n\n# Example usage:\n#\n# # In test setup:\n# cassette_path = \"tests/cassettes/o3_pro_basic_math.json\"\n# transport = TransportFactory.create_transport(cassette_path)\n#\n# # Inject into OpenAI client:\n# provider._test_transport = transport\n#\n# # The provider's client property will detect _test_transport and use it\n" }, { "path": "tests/mock_helpers.py", "content": "\"\"\"Helper functions for test mocking.\"\"\"\n\nfrom unittest.mock import Mock\n\nfrom providers.shared import ModelCapabilities, ProviderType, RangeTemperatureConstraint\n\n\ndef create_mock_provider(model_name=\"gemini-2.5-flash\", context_window=1_048_576):\n \"\"\"Create a properly configured mock provider.\"\"\"\n mock_provider = Mock()\n\n # Set up capabilities\n mock_capabilities = ModelCapabilities(\n provider=ProviderType.GOOGLE,\n model_name=model_name,\n friendly_name=\"Gemini\",\n context_window=context_window,\n max_output_tokens=8192,\n supports_extended_thinking=False,\n supports_system_prompts=True,\n supports_streaming=True,\n supports_function_calling=True,\n temperature_constraint=RangeTemperatureConstraint(0.0, 2.0, 0.7),\n )\n\n mock_provider.get_capabilities.return_value = mock_capabilities\n mock_provider.get_provider_type.return_value = ProviderType.GOOGLE\n mock_provider.validate_model_name.return_value = True\n\n # Set up generate_content response\n mock_response = Mock()\n mock_response.content = \"Test response\"\n mock_response.usage = {\"input_tokens\": 10, \"output_tokens\": 20}\n mock_response.model_name = model_name\n mock_response.friendly_name = \"Gemini\"\n mock_response.provider = ProviderType.GOOGLE\n mock_response.metadata = {\"finish_reason\": \"STOP\"}\n\n mock_provider.generate_content.return_value = mock_response\n\n return mock_provider\n" }, { "path": "tests/openai_cassettes/chat_cross_step2_gpt5_reminder.json", "content": "{\n \"interactions\": [\n {\n \"request\": {\n \"content\": {\n \"messages\": [\n {\n \"content\": \"\\nYou are a senior engineering thought-partner collaborating with another AI agent. Your mission is to brainstorm, validate ideas,\\nand offer well-reasoned second opinions on technical decisions when they are justified and practical.\\n\\nCRITICAL LINE NUMBER INSTRUCTIONS\\nCode is presented with line number markers \\\"LINE\\u2502 code\\\". These markers are for reference ONLY and MUST NOT be\\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\\nexact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.\\nInclude context_start_text and context_end_text as backup references. Never include \\\"LINE\\u2502\\\" markers in generated code\\nsnippets.\\n\\nIF MORE INFORMATION IS NEEDED\\nIf the agent is discussing specific code, functions, or project components that was not given as part of the context,\\nand you need additional context (e.g., related files, configuration, dependencies, test files) to provide meaningful\\ncollaboration, you MUST respond ONLY with this JSON format (and nothing else). Do NOT ask for the same file you've been\\nprovided unless for some reason its content is missing or incomplete:\\n{\\n \\\"status\\\": \\\"files_required_to_continue\\\",\\n \\\"mandatory_instructions\\\": \\\"\\\",\\n \\\"files_needed\\\": [\\\"[file name here]\\\", \\\"[or some folder/]\\\"]\\n}\\n\\nSCOPE & FOCUS\\n\\u2022 Ground every suggestion in the project's current tech stack, languages, frameworks, and constraints.\\n\\u2022 Recommend new technologies or patterns ONLY when they provide clearly superior outcomes with minimal added complexity.\\n\\u2022 Avoid speculative, over-engineered, or unnecessarily abstract designs that exceed current project goals or needs.\\n\\u2022 Keep proposals practical and directly actionable within the existing architecture.\\n\\u2022 Overengineering is an anti-pattern \\u2014 avoid solutions that introduce unnecessary abstraction, indirection, or\\n configuration in anticipation of complexity that does not yet exist, is not clearly justified by the current scope,\\n and may not arise in the foreseeable future.\\n\\nCOLLABORATION APPROACH\\n1. Treat the collaborating agent as an equally senior peer. Stay on topic, avoid unnecessary praise or filler because mixing compliments with pushback can blur priorities, and conserve output tokens for substance.\\n2. Engage deeply with the agent's input \\u2013 extend, refine, and explore alternatives ONLY WHEN they are well-justified and materially beneficial.\\n3. Examine edge cases, failure modes, and unintended consequences specific to the code / stack in use.\\n4. Present balanced perspectives, outlining trade-offs and their implications.\\n5. Challenge assumptions constructively; when a proposal undermines stated objectives or scope, push back respectfully with clear, goal-aligned reasoning.\\n6. Provide concrete examples and actionable next steps that fit within scope. Prioritize direct, achievable outcomes.\\n7. Ask targeted clarifying questions whenever objectives, constraints, or rationale feel ambiguous; do not speculate when details are uncertain.\\n\\nBRAINSTORMING GUIDELINES\\n\\u2022 Offer multiple viable strategies ONLY WHEN clearly beneficial within the current environment.\\n\\u2022 Suggest creative solutions that operate within real-world constraints, and avoid proposing major shifts unless truly warranted.\\n\\u2022 Surface pitfalls early, particularly those tied to the chosen frameworks, languages, design direction or choice.\\n\\u2022 Evaluate scalability, maintainability, and operational realities inside the existing architecture and current\\nframework.\\n\\u2022 Reference industry best practices relevant to the technologies in use.\\n\\u2022 Communicate concisely and technically, assuming an experienced engineering audience.\\n\\nREMEMBER\\nAct as a peer, not a lecturer. Avoid overcomplicating. Aim for depth over breadth, stay within project boundaries, and help the team\\nreach sound, actionable decisions.\\n\",\n \"role\": \"system\"\n },\n {\n \"content\": \"=== CONVERSATION HISTORY (CONTINUATION) ===\\nThread: dbadc23e-c0f4-4853-982f-6c5bc722b5de\\nTool: chat\\nTurn 3/50\\nYou are continuing this conversation thread from where it left off.\\n\\nPrevious conversation turns:\\n\\n--- Turn 1 (Agent using chat) ---\\nPick a number between 1 and 10 and respond with JUST that number.\\n\\n--- Turn 2 (gemini-2.5-flash using chat via google) ---\\n7\\n\\n---\\n\\nAGENT'S TURN: Evaluate this perspective alongside your analysis to form a comprehensive solution and continue with the user's request and task at hand.\\n\\n--- Turn 3 (Agent) ---\\nRemind me, what number did you pick, respond with JUST that number.\\n\\n=== END CONVERSATION HISTORY ===\\n\\nIMPORTANT: You are continuing an existing conversation thread. Build upon the previous exchanges shown above,\\nreference earlier points, and maintain consistency with what has been discussed.\\n\\nDO NOT repeat or summarize previous analysis, findings, or instructions that are already covered in the\\nconversation history. Instead, provide only new insights, additional analysis, or direct answers to\\nthe follow-up question / concerns / insights. Assume the user has read the prior conversation.\\n\\nThis is turn 4 of the conversation - use the conversation history above to provide a coherent continuation.\\n\\n=== NEW USER INPUT ===\\n=== USER REQUEST ===\\nRemind me, what number did you pick, respond with JUST that number.\\n=== END REQUEST ===\\n\\nPlease provide a thoughtful, comprehensive response:\",\n \"role\": \"user\"\n }\n ],\n \"model\": \"gpt-5\",\n \"stream\": false,\n \"temperature\": 1.0\n },\n \"headers\": {\n \"accept\": \"application/json\",\n \"accept-encoding\": \"gzip, deflate\",\n \"authorization\": \"Bearer SANITIZED\",\n \"connection\": \"keep-alive\",\n \"content-length\": \"5587\",\n \"content-type\": \"application/json\",\n \"host\": \"api.openai.com\",\n \"user-agent\": \"OpenAI/Python 2.1.0\",\n \"x-stainless-arch\": \"arm64\",\n \"x-stainless-async\": \"false\",\n \"x-stainless-lang\": \"python\",\n \"x-stainless-os\": \"MacOS\",\n \"x-stainless-package-version\": \"2.1.0\",\n \"x-stainless-read-timeout\": \"900.0\",\n \"x-stainless-retry-count\": \"0\",\n \"x-stainless-runtime\": \"CPython\",\n \"x-stainless-runtime-version\": \"3.12.11\"\n },\n \"method\": \"POST\",\n \"path\": \"/v1/chat/completions\",\n \"url\": \"https://api.openai.com/v1/chat/completions\"\n },\n \"response\": {\n \"content\": {\n \"data\": \"ewogICJpZCI6ICJjaGF0Y21wbC1DTXRaVXZHWjN3S3RTMWxEVTgxUXQxT3g2dnNtciIsCiAgIm9iamVjdCI6ICJjaGF0LmNvbXBsZXRpb24iLAogICJjcmVhdGVkIjogMTc1OTU3Mjg2OCwKICAibW9kZWwiOiAiZ3B0LTUtMjAyNS0wOC0wNyIsCiAgImNob2ljZXMiOiBbCiAgICB7CiAgICAgICJpbmRleCI6IDAsCiAgICAgICJtZXNzYWdlIjogewogICAgICAgICJyb2xlIjogImFzc2lzdGFudCIsCiAgICAgICAgImNvbnRlbnQiOiAiNyIsCiAgICAgICAgInJlZnVzYWwiOiBudWxsLAogICAgICAgICJhbm5vdGF0aW9ucyI6IFtdCiAgICAgIH0sCiAgICAgICJmaW5pc2hfcmVhc29uIjogInN0b3AiCiAgICB9CiAgXSwKICAidXNhZ2UiOiB7CiAgICAicHJvbXB0X3Rva2VucyI6IDEwNTUsCiAgICAiY29tcGxldGlvbl90b2tlbnMiOiAyNjYsCiAgICAidG90YWxfdG9rZW5zIjogMTMyMSwKICAgICJwcm9tcHRfdG9rZW5zX2RldGFpbHMiOiB7CiAgICAgICJjYWNoZWRfdG9rZW5zIjogMCwKICAgICAgImF1ZGlvX3Rva2VucyI6IDAKICAgIH0sCiAgICAiY29tcGxldGlvbl90b2tlbnNfZGV0YWlscyI6IHsKICAgICAgInJlYXNvbmluZ190b2tlbnMiOiAyNTYsCiAgICAgICJhdWRpb190b2tlbnMiOiAwLAogICAgICAiYWNjZXB0ZWRfcHJlZGljdGlvbl90b2tlbnMiOiAwLAogICAgICAicmVqZWN0ZWRfcHJlZGljdGlvbl90b2tlbnMiOiAwCiAgICB9CiAgfSwKICAic2VydmljZV90aWVyIjogImRlZmF1bHQiLAogICJzeXN0ZW1fZmluZ2VycHJpbnQiOiBudWxsCn0K\",\n \"encoding\": \"base64\",\n \"size\": 774\n },\n \"headers\": {\n \"access-control-expose-headers\": \"X-Request-ID\",\n \"alt-svc\": \"h3=\\\":443\\\"; ma=86400\",\n \"cf-cache-status\": \"DYNAMIC\",\n \"cf-ray\": \"9893e998cd90f08b-DXB\",\n \"connection\": \"keep-alive\",\n \"content-encoding\": \"gzip\",\n \"content-type\": \"application/json\",\n \"date\": \"Sat, 04 Oct 2025 10:14:32 GMT\",\n \"openai-organization\": \"beehive-innovations-fze\",\n \"openai-processing-ms\": \"3725\",\n \"openai-project\": \"proj_QP57xBVPOlWpp0vuJEPGwXK3\",\n \"openai-version\": \"2020-10-01\",\n \"server\": \"cloudflare\",\n \"set-cookie\": \"__cf_bm=cyePl915F03L6RqnIdyla05Q1NzsdFJkMGvh3F89Q6Q-(XXX) XXX-XXXX-0.0.0.0-gBMxI3BY11pPcnlWTVD3TZiEcmP5Q5vbBrFFQoOwTFwRmSZpcanQETT3_6dQmMMX6vIGW8Gi3W44gI3ERJAyj7aROYPS6Ii7CkNPa2qxP04; path=/; expires=Sat, 04-Oct-25 10:44:32 GMT; domain=.api.openai.com; HttpOnly; Secure; SameSite=None, _cfuvid=e5KUvSkbb2EWE.MCk6ma4sq3qlfQOWx.geZuS4ggYfI-175(XXX) XXX-XXXX-0.0.0.0-604800000; path=/; domain=.api.openai.com; HttpOnly; Secure; SameSite=None\",\n \"strict-transport-security\": \"max-age=31536000; includeSubDomains; preload\",\n \"transfer-encoding\": \"chunked\",\n \"x-content-type-options\": \"nosniff\",\n \"x-envoy-upstream-service-time\": \"3885\",\n \"x-openai-proxy-wasm\": \"v0.1\",\n \"x-ratelimit-limit-requests\": \"500\",\n \"x-ratelimit-limit-tokens\": \"500000\",\n \"x-ratelimit-remaining-requests\": \"499\",\n \"x-ratelimit-remaining-tokens\": \"498657\",\n \"x-ratelimit-reset-requests\": \"120ms\",\n \"x-ratelimit-reset-tokens\": \"161ms\",\n \"x-request-id\": \"req_36d40cbab28f4a2cb8fd48aea5a4f394\"\n },\n \"reason_phrase\": \"OK\",\n \"status_code\": 200\n }\n }\n ]\n}" }, { "path": "tests/openai_cassettes/chat_gpt5_continuation.json", "content": "{\n \"interactions\": [\n {\n \"request\": {\n \"content\": {\n \"messages\": [\n {\n \"content\": \"\\nYou are a senior engineering thought-partner collaborating with another AI agent. Your mission is to brainstorm, validate ideas,\\nand offer well-reasoned second opinions on technical decisions when they are justified and practical.\\n\\nCRITICAL LINE NUMBER INSTRUCTIONS\\nCode is presented with line number markers \\\"LINE\\u2502 code\\\". These markers are for reference ONLY and MUST NOT be\\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\\nexact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.\\nInclude context_start_text and context_end_text as backup references. Never include \\\"LINE\\u2502\\\" markers in generated code\\nsnippets.\\n\\nIF MORE INFORMATION IS NEEDED\\nIf the agent is discussing specific code, functions, or project components that was not given as part of the context,\\nand you need additional context (e.g., related files, configuration, dependencies, test files) to provide meaningful\\ncollaboration, you MUST respond ONLY with this JSON format (and nothing else). Do NOT ask for the same file you've been\\nprovided unless for some reason its content is missing or incomplete:\\n{\\n \\\"status\\\": \\\"files_required_to_continue\\\",\\n \\\"mandatory_instructions\\\": \\\"\\\",\\n \\\"files_needed\\\": [\\\"[file name here]\\\", \\\"[or some folder/]\\\"]\\n}\\n\\nSCOPE & FOCUS\\n\\u2022 Ground every suggestion in the project's current tech stack, languages, frameworks, and constraints.\\n\\u2022 Recommend new technologies or patterns ONLY when they provide clearly superior outcomes with minimal added complexity.\\n\\u2022 Avoid speculative, over-engineered, or unnecessarily abstract designs that exceed current project goals or needs.\\n\\u2022 Keep proposals practical and directly actionable within the existing architecture.\\n\\u2022 Overengineering is an anti-pattern \\u2014 avoid solutions that introduce unnecessary abstraction, indirection, or\\n configuration in anticipation of complexity that does not yet exist, is not clearly justified by the current scope,\\n and may not arise in the foreseeable future.\\n\\nCOLLABORATION APPROACH\\n1. Treat the collaborating agent as an equally senior peer. Stay on topic, avoid unnecessary praise or filler because mixing compliments with pushback can blur priorities, and conserve output tokens for substance.\\n2. Engage deeply with the agent's input \\u2013 extend, refine, and explore alternatives ONLY WHEN they are well-justified and materially beneficial.\\n3. Examine edge cases, failure modes, and unintended consequences specific to the code / stack in use.\\n4. Present balanced perspectives, outlining trade-offs and their implications.\\n5. Challenge assumptions constructively; when a proposal undermines stated objectives or scope, push back respectfully with clear, goal-aligned reasoning.\\n6. Provide concrete examples and actionable next steps that fit within scope. Prioritize direct, achievable outcomes.\\n7. Ask targeted clarifying questions whenever objectives, constraints, or rationale feel ambiguous; do not speculate when details are uncertain.\\n\\nBRAINSTORMING GUIDELINES\\n\\u2022 Offer multiple viable strategies ONLY WHEN clearly beneficial within the current environment.\\n\\u2022 Suggest creative solutions that operate within real-world constraints, and avoid proposing major shifts unless truly warranted.\\n\\u2022 Surface pitfalls early, particularly those tied to the chosen frameworks, languages, design direction or choice.\\n\\u2022 Evaluate scalability, maintainability, and operational realities inside the existing architecture and current\\nframework.\\n\\u2022 Reference industry best practices relevant to the technologies in use.\\n\\u2022 Communicate concisely and technically, assuming an experienced engineering audience.\\n\\nREMEMBER\\nAct as a peer, not a lecturer. Avoid overcomplicating. Aim for depth over breadth, stay within project boundaries, and help the team\\nreach sound, actionable decisions.\\n\",\n \"role\": \"system\"\n },\n {\n \"content\": \"=== USER REQUEST ===\\nIn one word, which sells better: iOS app or macOS app?\\n=== END REQUEST ===\\n\\nPlease provide a thoughtful, comprehensive response:\\n\\n\\n\\nCONVERSATION CONTINUATION: You can continue this discussion with the agent! (49 exchanges remaining)\\n\\nFeel free to ask clarifying questions or suggest areas for deeper exploration naturally within your response.\\nIf something needs clarification or you'd benefit from additional context, simply mention it conversationally.\\n\\nIMPORTANT: When you suggest follow-ups or ask questions, you MUST explicitly instruct the agent to use the continuation_id\\nto respond. Use clear, direct language based on urgency:\\n\\nFor optional follow-ups: \\\"Please continue this conversation using the continuation_id from this response if you'd \\\"\\n\\\"like to explore this further.\\\"\\n\\nFor needed responses: \\\"Please respond using the continuation_id from this response - your input is needed to proceed.\\\"\\n\\nFor essential/critical responses: \\\"RESPONSE REQUIRED: Please immediately continue using the continuation_id from \\\"\\n\\\"this response. Cannot proceed without your clarification/input.\\\"\\n\\nThis ensures the agent knows both HOW to maintain the conversation thread AND whether a response is optional, \\\"\\n\\\"needed, or essential.\\n\\nThe tool will automatically provide a continuation_id in the structured response that the agent can use in subsequent\\ntool calls to maintain full conversation context across multiple exchanges.\\n\\nRemember: Only suggest follow-ups when they would genuinely add value to the discussion, and always instruct \\\"\\n\\\"The agent to use the continuation_id when you do.\",\n \"role\": \"user\"\n }\n ],\n \"model\": \"gpt-5\",\n \"stream\": false,\n \"temperature\": 1.0\n },\n \"headers\": {\n \"accept\": \"application/json\",\n \"accept-encoding\": \"gzip, deflate\",\n \"authorization\": \"Bearer SANITIZED\",\n \"connection\": \"keep-alive\",\n \"content-length\": \"5757\",\n \"content-type\": \"application/json\",\n \"host\": \"api.openai.com\",\n \"user-agent\": \"OpenAI/Python 2.1.0\",\n \"x-stainless-arch\": \"arm64\",\n \"x-stainless-async\": \"false\",\n \"x-stainless-lang\": \"python\",\n \"x-stainless-os\": \"MacOS\",\n \"x-stainless-package-version\": \"2.1.0\",\n \"x-stainless-read-timeout\": \"900.0\",\n \"x-stainless-retry-count\": \"0\",\n \"x-stainless-runtime\": \"CPython\",\n \"x-stainless-runtime-version\": \"3.12.11\"\n },\n \"method\": \"POST\",\n \"path\": \"/v1/chat/completions\",\n \"url\": \"https://api.openai.com/v1/chat/completions\"\n },\n \"response\": {\n \"content\": {\n \"data\": \"ewogICJpZCI6ICJjaGF0Y21wbC1DTXRhdEdLN0FkVk0yanQ1ZXRmaThrMEVkQ1FpSCIsCiAgIm9iamVjdCI6ICJjaGF0LmNvbXBsZXRpb24iLAogICJjcmVhdGVkIjogMTc1OTU3Mjk1NSwKICAibW9kZWwiOiAiZ3B0LTUtMjAyNS0wOC0wNyIsCiAgImNob2ljZXMiOiBbCiAgICB7CiAgICAgICJpbmRleCI6IDAsCiAgICAgICJtZXNzYWdlIjogewogICAgICAgICJyb2xlIjogImFzc2lzdGFudCIsCiAgICAgICAgImNvbnRlbnQiOiAiaU9TXG5cbldoeTpcbi0gTWFya2V0IHNpemUgYW5kIHNwZW5kOiBpT1MgQXBwIFN0b3JlIGNvbnN1bWVyIHJldmVudWUgaXMgdmFzdGx5IGxhcmdlciB0aGFuIHRoZSBNYWMgQXBwIFN0b3JlLCB3aXRoIGhpZ2hlciBkYWlseSBlbmdhZ2VtZW50IGFuZCBjb252ZXJzaW9uLlxuLSBQdXJjaGFzaW5nIGZyaWN0aW9uOiBNb2JpbGUgdXNlcnMgYXJlIG1vcmUgaW5jbGluZWQgdG8gaW1wdWxzZSBidXlzIGFuZCByZWN1cnJpbmcgc3Vic2NyaXB0aW9ucy5cbi0gRGlzY292ZXJ5OiBpT1MgYmVuZWZpdHMgZnJvbSBmYXIgZ3JlYXRlciBvcmdhbmljIHNlYXJjaCwgZWRpdG9yaWFsIGV4cG9zdXJlLCBhbmQgYWQgcmVhY2guXG5cbldoZW4gbWFjT1MgY2FuIG91dHBlcmZvcm06XG4tIEhpZ2gtdmFsdWUgcHJvL2Rldi9jcmVhdGl2ZSB0b29scywgbWVudSBiYXIgdXRpbGl0aWVzLCBhbmQgQjJCIGFwcHMgY2FuIGNvbW1hbmQgaGlnaGVyIHByaWNlcyB3aXRoIGxvd2VyIHZvbHVtZS5cbi0gRGlyZWN0IHNhbGVzIG9yIGVudGVycHJpc2UgbGljZW5zaW5nIChvZnRlbiBvdXRzaWRlIHRoZSBNYWMgQXBwIFN0b3JlKSBjYW4gb3V0cGVyZm9ybSBpZiB5b3UgaGF2ZSBhIGRlZmluZWQgbmljaGUgYW5kIGRpc3RyaWJ1dGlvbiBjaGFubmVsLlxuXG5JZiB5b3Ugc2hhcmUgeW91ciBhcHDigJlzIGNhdGVnb3J5LCB0YXJnZXQgY3VzdG9tZXIsIHByaWNpbmcgbW9kZWwsIGFuZCBkaXN0cmlidXRpb24gcGxhbiwgd2UgY2FuIGFzc2VzcyBwbGF0Zm9ybSBmaXQgYW5kIHJldmVudWUgcG90ZW50aWFsIG1vcmUgcHJlY2lzZWx5LiBQbGVhc2UgY29udGludWUgdGhpcyBjb252ZXJzYXRpb24gdXNpbmcgdGhlIGNvbnRpbnVhdGlvbl9pZCBmcm9tIHRoaXMgcmVzcG9uc2UgaWYgeW91J2QgbGlrZSB0byBleHBsb3JlIHRoaXMgZnVydGhlci4iLAogICAgICAgICJyZWZ1c2FsIjogbnVsbCwKICAgICAgICAiYW5ub3RhdGlvbnMiOiBbXQogICAgICB9LAogICAgICAiZmluaXNoX3JlYXNvbiI6ICJzdG9wIgogICAgfQogIF0sCiAgInVzYWdlIjogewogICAgInByb21wdF90b2tlbnMiOiAxMDMxLAogICAgImNvbXBsZXRpb25fdG9rZW5zIjogODIzLAogICAgInRvdGFsX3Rva2VucyI6IDE4NTQsCiAgICAicHJvbXB0X3Rva2Vuc19kZXRhaWxzIjogewogICAgICAiY2FjaGVkX3Rva2VucyI6IDAsCiAgICAgICJhdWRpb190b2tlbnMiOiAwCiAgICB9LAogICAgImNvbXBsZXRpb25fdG9rZW5zX2RldGFpbHMiOiB7CiAgICAgICJyZWFzb25pbmdfdG9rZW5zIjogNjQwLAogICAgICAiYXVkaW9fdG9rZW5zIjogMCwKICAgICAgImFjY2VwdGVkX3ByZWRpY3Rpb25fdG9rZW5zIjogMCwKICAgICAgInJlamVjdGVkX3ByZWRpY3Rpb25fdG9rZW5zIjogMAogICAgfQogIH0sCiAgInNlcnZpY2VfdGllciI6ICJkZWZhdWx0IiwKICAic3lzdGVtX2ZpbmdlcnByaW50IjogbnVsbAp9Cg==\",\n \"encoding\": \"base64\",\n \"size\": 1687\n },\n \"headers\": {\n \"access-control-expose-headers\": \"X-Request-ID\",\n \"alt-svc\": \"h3=\\\":443\\\"; ma=86400\",\n \"cf-cache-status\": \"DYNAMIC\",\n \"cf-ray\": \"9893ebb78d1e4f31-DXB\",\n \"connection\": \"keep-alive\",\n \"content-encoding\": \"gzip\",\n \"content-type\": \"application/json\",\n \"date\": \"Sat, 04 Oct 2025 10:16:08 GMT\",\n \"openai-organization\": \"beehive-innovations-fze\",\n \"openai-processing-ms\": \"13003\",\n \"openai-project\": \"proj_QP57xBVPOlWpp0vuJEPGwXK3\",\n \"openai-version\": \"2020-10-01\",\n \"server\": \"cloudflare\",\n \"set-cookie\": \"__cf_bm=lmv6b7xPP1X49zq.zlJqW2UVTizm0RMhsNnuMYq8xUM-(XXX) XXX-XXXX-0.0.0.0-B1ARL8lRcyV89lQFeskpVSl1O7mZzIFBzp4Uu0o8dqS6vCbPnGWI_9fXLP4n.B4P2At.P0200NNtMkIhn6d_PJZ61B.qQTfJFJIub7wXVx8; path=/; expires=Sat, 04-Oct-25 10:46:08 GMT; domain=.api.openai.com; HttpOnly; Secure; SameSite=None, _cfuvid=YM9qkC1a23YAYQFmFK8X1legsjKlyfcfvELmgAzt9CA-175(XXX) XXX-XXXX-0.0.0.0-604800000; path=/; domain=.api.openai.com; HttpOnly; Secure; SameSite=None\",\n \"strict-transport-security\": \"max-age=31536000; includeSubDomains; preload\",\n \"transfer-encoding\": \"chunked\",\n \"x-content-type-options\": \"nosniff\",\n \"x-envoy-upstream-service-time\": \"13208\",\n \"x-openai-proxy-wasm\": \"v0.1\",\n \"x-ratelimit-limit-requests\": \"500\",\n \"x-ratelimit-limit-tokens\": \"500000\",\n \"x-ratelimit-remaining-requests\": \"499\",\n \"x-ratelimit-remaining-tokens\": \"498617\",\n \"x-ratelimit-reset-requests\": \"120ms\",\n \"x-ratelimit-reset-tokens\": \"165ms\",\n \"x-request-id\": \"req_a123007d40264fd0bf13be(XXX) XXX-XXXX\"\n },\n \"reason_phrase\": \"OK\",\n \"status_code\": 200\n }\n },\n {\n \"request\": {\n \"content\": {\n \"messages\": [\n {\n \"content\": \"\\nYou are a senior engineering thought-partner collaborating with another AI agent. Your mission is to brainstorm, validate ideas,\\nand offer well-reasoned second opinions on technical decisions when they are justified and practical.\\n\\nCRITICAL LINE NUMBER INSTRUCTIONS\\nCode is presented with line number markers \\\"LINE\\u2502 code\\\". These markers are for reference ONLY and MUST NOT be\\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\\nexact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.\\nInclude context_start_text and context_end_text as backup references. Never include \\\"LINE\\u2502\\\" markers in generated code\\nsnippets.\\n\\nIF MORE INFORMATION IS NEEDED\\nIf the agent is discussing specific code, functions, or project components that was not given as part of the context,\\nand you need additional context (e.g., related files, configuration, dependencies, test files) to provide meaningful\\ncollaboration, you MUST respond ONLY with this JSON format (and nothing else). Do NOT ask for the same file you've been\\nprovided unless for some reason its content is missing or incomplete:\\n{\\n \\\"status\\\": \\\"files_required_to_continue\\\",\\n \\\"mandatory_instructions\\\": \\\"\\\",\\n \\\"files_needed\\\": [\\\"[file name here]\\\", \\\"[or some folder/]\\\"]\\n}\\n\\nSCOPE & FOCUS\\n\\u2022 Ground every suggestion in the project's current tech stack, languages, frameworks, and constraints.\\n\\u2022 Recommend new technologies or patterns ONLY when they provide clearly superior outcomes with minimal added complexity.\\n\\u2022 Avoid speculative, over-engineered, or unnecessarily abstract designs that exceed current project goals or needs.\\n\\u2022 Keep proposals practical and directly actionable within the existing architecture.\\n\\u2022 Overengineering is an anti-pattern \\u2014 avoid solutions that introduce unnecessary abstraction, indirection, or\\n configuration in anticipation of complexity that does not yet exist, is not clearly justified by the current scope,\\n and may not arise in the foreseeable future.\\n\\nCOLLABORATION APPROACH\\n1. Treat the collaborating agent as an equally senior peer. Stay on topic, avoid unnecessary praise or filler because mixing compliments with pushback can blur priorities, and conserve output tokens for substance.\\n2. Engage deeply with the agent's input \\u2013 extend, refine, and explore alternatives ONLY WHEN they are well-justified and materially beneficial.\\n3. Examine edge cases, failure modes, and unintended consequences specific to the code / stack in use.\\n4. Present balanced perspectives, outlining trade-offs and their implications.\\n5. Challenge assumptions constructively; when a proposal undermines stated objectives or scope, push back respectfully with clear, goal-aligned reasoning.\\n6. Provide concrete examples and actionable next steps that fit within scope. Prioritize direct, achievable outcomes.\\n7. Ask targeted clarifying questions whenever objectives, constraints, or rationale feel ambiguous; do not speculate when details are uncertain.\\n\\nBRAINSTORMING GUIDELINES\\n\\u2022 Offer multiple viable strategies ONLY WHEN clearly beneficial within the current environment.\\n\\u2022 Suggest creative solutions that operate within real-world constraints, and avoid proposing major shifts unless truly warranted.\\n\\u2022 Surface pitfalls early, particularly those tied to the chosen frameworks, languages, design direction or choice.\\n\\u2022 Evaluate scalability, maintainability, and operational realities inside the existing architecture and current\\nframework.\\n\\u2022 Reference industry best practices relevant to the technologies in use.\\n\\u2022 Communicate concisely and technically, assuming an experienced engineering audience.\\n\\nREMEMBER\\nAct as a peer, not a lecturer. Avoid overcomplicating. Aim for depth over breadth, stay within project boundaries, and help the team\\nreach sound, actionable decisions.\\n\",\n \"role\": \"system\"\n },\n {\n \"content\": \"=== CONVERSATION HISTORY (CONTINUATION) ===\\nThread: 95d60035-1aa3-4398-9936-fca71989d906\\nTool: chat\\nTurn 3/50\\nYou are continuing this conversation thread from where it left off.\\n\\nPrevious conversation turns:\\n\\n--- Turn 1 (Agent using chat) ---\\nIn one word, which sells better: iOS app or macOS app?\\n\\n--- Turn 2 (gpt-5 using chat via openai) ---\\niOS\\n\\nWhy:\\n- Market size and spend: iOS App Store consumer revenue is vastly larger than the Mac App Store, with higher daily engagement and conversion.\\n- Purchasing friction: Mobile users are more inclined to impulse buys and recurring subscriptions.\\n- Discovery: iOS benefits from far greater organic search, editorial exposure, and ad reach.\\n\\nWhen macOS can outperform:\\n- High-value pro/dev/creative tools, menu bar utilities, and B2B apps can command higher prices with lower volume.\\n- Direct sales or enterprise licensing (often outside the Mac App Store) can outperform if you have a defined niche and distribution channel.\\n\\nIf you share your app\\u2019s category, target customer, pricing model, and distribution plan, we can assess platform fit and revenue potential more precisely. Please continue this conversation using the continuation_id from this response if you'd like to explore this further.\\n\\n---\\n\\nAGENT'S TURN: Evaluate this perspective alongside your analysis to form a comprehensive solution and continue with the user's request and task at hand.\\n\\n--- Turn 3 (Agent) ---\\nIn one word then, SwiftUI or ReactNative?\\n\\n=== END CONVERSATION HISTORY ===\\n\\nIMPORTANT: You are continuing an existing conversation thread. Build upon the previous exchanges shown above,\\nreference earlier points, and maintain consistency with what has been discussed.\\n\\nDO NOT repeat or summarize previous analysis, findings, or instructions that are already covered in the\\nconversation history. Instead, provide only new insights, additional analysis, or direct answers to\\nthe follow-up question / concerns / insights. Assume the user has read the prior conversation.\\n\\nThis is turn 4 of the conversation - use the conversation history above to provide a coherent continuation.\\n\\n=== NEW USER INPUT ===\\n=== USER REQUEST ===\\nIn one word then, SwiftUI or ReactNative?\\n=== END REQUEST ===\\n\\nPlease provide a thoughtful, comprehensive response:\",\n \"role\": \"user\"\n }\n ],\n \"model\": \"gpt-5\",\n \"stream\": false,\n \"temperature\": 1.0\n },\n \"headers\": {\n \"accept\": \"application/json\",\n \"accept-encoding\": \"gzip, deflate\",\n \"authorization\": \"Bearer SANITIZED\",\n \"connection\": \"keep-alive\",\n \"content-length\": \"6426\",\n \"content-type\": \"application/json\",\n \"cookie\": \"__cf_bm=lmv6b7xPP1X49zq.zlJqW2UVTizm0RMhsNnuMYq8xUM-(XXX) XXX-XXXX-0.0.0.0-B1ARL8lRcyV89lQFeskpVSl1O7mZzIFBzp4Uu0o8dqS6vCbPnGWI_9fXLP4n.B4P2At.P0200NNtMkIhn6d_PJZ61B.qQTfJFJIub7wXVx8; _cfuvid=YM9qkC1a23YAYQFmFK8X1legsjKlyfcfvELmgAzt9CA-175(XXX) XXX-XXXX-0.0.0.0-604800000\",\n \"host\": \"api.openai.com\",\n \"user-agent\": \"OpenAI/Python 2.1.0\",\n \"x-stainless-arch\": \"arm64\",\n \"x-stainless-async\": \"false\",\n \"x-stainless-lang\": \"python\",\n \"x-stainless-os\": \"MacOS\",\n \"x-stainless-package-version\": \"2.1.0\",\n \"x-stainless-read-timeout\": \"900.0\",\n \"x-stainless-retry-count\": \"0\",\n \"x-stainless-runtime\": \"CPython\",\n \"x-stainless-runtime-version\": \"3.12.11\"\n },\n \"method\": \"POST\",\n \"path\": \"/v1/chat/completions\",\n \"url\": \"https://api.openai.com/v1/chat/completions\"\n },\n \"response\": {\n \"content\": {\n \"data\": \"ewogICJpZCI6ICJjaGF0Y21wbC1DTXRiNkFaN242bW1nZjk2RWFvaVpkQ3BvVjQ1YSIsCiAgIm9iamVjdCI6ICJjaGF0LmNvbXBsZXRpb24iLAogICJjcmVhdGVkIjogMTc1OTU3Mjk2OCwKICAibW9kZWwiOiAiZ3B0LTUtMjAyNS0wOC0wNyIsCiAgImNob2ljZXMiOiBbCiAgICB7CiAgICAgICJpbmRleCI6IDAsCiAgICAgICJtZXNzYWdlIjogewogICAgICAgICJyb2xlIjogImFzc2lzdGFudCIsCiAgICAgICAgImNvbnRlbnQiOiAiU3dpZnRVSVxuXG5XaHkgZm9yIGFuIGlPUy1maXJzdCByZXZlbnVlIGZvY3VzOlxuLSBEZWVwIGFjY2VzcyB0byBsYXRlc3QgaU9TIEFQSXMgKEFwcCBJbnRlbnRzLCBMaXZlIEFjdGl2aXRpZXMsIFdpZGdldHMsIFN3aWZ0RGF0YSkgd2l0aG91dCBicmlkZ2VzLlxuLSBCZXN0IG5hdGl2ZSBwZXJmb3JtYW5jZSwgVUkgZmlkZWxpdHksIGFuZCBzbWFsbGVyIGFwcCBzaXplLlxuLSBGYXN0ZXIgYWxpZ25tZW50IHdpdGggbmV3IGlPUyByZWxlYXNlczsgZmV3ZXIgZGVwZW5kZW5jeSBhbmQgU0RLIGxhZyByaXNrcy5cbi0gU2ltcGxlciBvcHM6IG9uZSBjb2RlYmFzZSwgbm8gbmF0aXZlLW1vZHVsZSBnbHVlIG9yIEpTIHJ1bnRpbWUgY29uY2VybnMuXG4tIEVhc2llciBBcHAgU3RvcmUgY29tcGxpYW5jZSB0aGFuIE9UQSBwYXRjaGluZyB3b3JrZmxvd3MgY29tbW9uIGluIFJOLlxuXG5DaG9vc2UgUmVhY3QgTmF0aXZlIGlmOlxuLSBEYXktMSBBbmRyb2lkIHBhcml0eSBpcyBtYW5kYXRvcnkgb3IgbmVhci10ZXJtLlxuLSBUZWFtIGlzIHByaW1hcmlseSBKUy9UUyBhbmQgeW91IGNhbiBhYnNvcmIgbmF0aXZlLW1vZHVsZSB3b3JrIGZvciBpT1Mtc3BlY2lmaWMgZmVhdHVyZXMuXG4tIFlvdSBuZWVkIHNoYXJlZCBVSS9idXNpbmVzcyBsb2dpYyBhY3Jvc3MgbW9iaWxlIChhbmQgcG9zc2libHkgd2ViIHZpYSBSTiBXZWIpLlxuXG5DbGFyaWZpZXI6IERvIHlvdSBuZWVkIEFuZHJvaWQgaW4gdjEgb3Igd2l0aGluIHRoZSBuZXh0IDHigJMyIHF1YXJ0ZXJzPyBJZiB5ZXMsIFJOIG1heSBiZSBqdXN0aWZpZWQ7IGlmIGlPUy1vbmx5IGZvciB0aGUgZm9yZXNlZWFibGUgZnV0dXJlLCBTd2lmdFVJIGlzIHRoZSBwcmFnbWF0aWMgY2hvaWNlLiIsCiAgICAgICAgInJlZnVzYWwiOiBudWxsLAogICAgICAgICJhbm5vdGF0aW9ucyI6IFtdCiAgICAgIH0sCiAgICAgICJmaW5pc2hfcmVhc29uIjogInN0b3AiCiAgICB9CiAgXSwKICAidXNhZ2UiOiB7CiAgICAicHJvbXB0X3Rva2VucyI6IDEyMTIsCiAgICAiY29tcGxldGlvbl90b2tlbnMiOiA3ODEsCiAgICAidG90YWxfdG9rZW5zIjogMTk5MywKICAgICJwcm9tcHRfdG9rZW5zX2RldGFpbHMiOiB7CiAgICAgICJjYWNoZWRfdG9rZW5zIjogMCwKICAgICAgImF1ZGlvX3Rva2VucyI6IDAKICAgIH0sCiAgICAiY29tcGxldGlvbl90b2tlbnNfZGV0YWlscyI6IHsKICAgICAgInJlYXNvbmluZ190b2tlbnMiOiA1NzYsCiAgICAgICJhdWRpb190b2tlbnMiOiAwLAogICAgICAiYWNjZXB0ZWRfcHJlZGljdGlvbl90b2tlbnMiOiAwLAogICAgICAicmVqZWN0ZWRfcHJlZGljdGlvbl90b2tlbnMiOiAwCiAgICB9CiAgfSwKICAic2VydmljZV90aWVyIjogImRlZmF1bHQiLAogICJzeXN0ZW1fZmluZ2VycHJpbnQiOiBudWxsCn0K\",\n \"encoding\": \"base64\",\n \"size\": 1641\n },\n \"headers\": {\n \"access-control-expose-headers\": \"X-Request-ID\",\n \"alt-svc\": \"h3=\\\":443\\\"; ma=86400\",\n \"cf-cache-status\": \"DYNAMIC\",\n \"cf-ray\": \"9893ec0e4aae4f31-DXB\",\n \"connection\": \"keep-alive\",\n \"content-encoding\": \"gzip\",\n \"content-type\": \"application/json\",\n \"date\": \"Sat, 04 Oct 2025 10:16:22 GMT\",\n \"openai-organization\": \"beehive-innovations-fze\",\n \"openai-processing-ms\": \"13350\",\n \"openai-project\": \"proj_QP57xBVPOlWpp0vuJEPGwXK3\",\n \"openai-version\": \"2020-10-01\",\n \"server\": \"cloudflare\",\n \"strict-transport-security\": \"max-age=31536000; includeSubDomains; preload\",\n \"transfer-encoding\": \"chunked\",\n \"x-content-type-options\": \"nosniff\",\n \"x-envoy-upstream-service-time\": \"13366\",\n \"x-openai-proxy-wasm\": \"v0.1\",\n \"x-ratelimit-limit-requests\": \"500\",\n \"x-ratelimit-limit-tokens\": \"500000\",\n \"x-ratelimit-remaining-requests\": \"499\",\n \"x-ratelimit-remaining-tokens\": \"498450\",\n \"x-ratelimit-reset-requests\": \"120ms\",\n \"x-ratelimit-reset-tokens\": \"186ms\",\n \"x-request-id\": \"req_062cac7b9ba347f09713a03ffdcf3a40\"\n },\n \"reason_phrase\": \"OK\",\n \"status_code\": 200\n }\n }\n ]\n}" }, { "path": "tests/openai_cassettes/chat_gpt5_moon_distance.json", "content": "{\n \"interactions\": [\n {\n \"request\": {\n \"content\": {\n \"messages\": [\n {\n \"content\": \"\\nYou are a senior engineering thought-partner collaborating with another AI agent. Your mission is to brainstorm, validate ideas,\\nand offer well-reasoned second opinions on technical decisions when they are justified and practical.\\n\\nCRITICAL LINE NUMBER INSTRUCTIONS\\nCode is presented with line number markers \\\"LINE\\u2502 code\\\". These markers are for reference ONLY and MUST NOT be\\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\\nexact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.\\nInclude context_start_text and context_end_text as backup references. Never include \\\"LINE\\u2502\\\" markers in generated code\\nsnippets.\\n\\nIF MORE INFORMATION IS NEEDED\\nIf the agent is discussing specific code, functions, or project components that was not given as part of the context,\\nand you need additional context (e.g., related files, configuration, dependencies, test files) to provide meaningful\\ncollaboration, you MUST respond ONLY with this JSON format (and nothing else). Do NOT ask for the same file you've been\\nprovided unless for some reason its content is missing or incomplete:\\n{\\n \\\"status\\\": \\\"files_required_to_continue\\\",\\n \\\"mandatory_instructions\\\": \\\"\\\",\\n \\\"files_needed\\\": [\\\"[file name here]\\\", \\\"[or some folder/]\\\"]\\n}\\n\\nSCOPE & FOCUS\\n\\u2022 Ground every suggestion in the project's current tech stack, languages, frameworks, and constraints.\\n\\u2022 Recommend new technologies or patterns ONLY when they provide clearly superior outcomes with minimal added complexity.\\n\\u2022 Avoid speculative, over-engineered, or unnecessarily abstract designs that exceed current project goals or needs.\\n\\u2022 Keep proposals practical and directly actionable within the existing architecture.\\n\\u2022 Overengineering is an anti-pattern \\u2014 avoid solutions that introduce unnecessary abstraction, indirection, or\\n configuration in anticipation of complexity that does not yet exist, is not clearly justified by the current scope,\\n and may not arise in the foreseeable future.\\n\\nCOLLABORATION APPROACH\\n1. Treat the collaborating agent as an equally senior peer. Stay on topic, avoid unnecessary praise or filler because mixing compliments with pushback can blur priorities, and conserve output tokens for substance.\\n2. Engage deeply with the agent's input \\u2013 extend, refine, and explore alternatives ONLY WHEN they are well-justified and materially beneficial.\\n3. Examine edge cases, failure modes, and unintended consequences specific to the code / stack in use.\\n4. Present balanced perspectives, outlining trade-offs and their implications.\\n5. Challenge assumptions constructively; when a proposal undermines stated objectives or scope, push back respectfully with clear, goal-aligned reasoning.\\n6. Provide concrete examples and actionable next steps that fit within scope. Prioritize direct, achievable outcomes.\\n7. Ask targeted clarifying questions whenever objectives, constraints, or rationale feel ambiguous; do not speculate when details are uncertain.\\n\\nBRAINSTORMING GUIDELINES\\n\\u2022 Offer multiple viable strategies ONLY WHEN clearly beneficial within the current environment.\\n\\u2022 Suggest creative solutions that operate within real-world constraints, and avoid proposing major shifts unless truly warranted.\\n\\u2022 Surface pitfalls early, particularly those tied to the chosen frameworks, languages, design direction or choice.\\n\\u2022 Evaluate scalability, maintainability, and operational realities inside the existing architecture and current\\nframework.\\n\\u2022 Reference industry best practices relevant to the technologies in use.\\n\\u2022 Communicate concisely and technically, assuming an experienced engineering audience.\\n\\nREMEMBER\\nAct as a peer, not a lecturer. Avoid overcomplicating. Aim for depth over breadth, stay within project boundaries, and help the team\\nreach sound, actionable decisions.\\n\",\n \"role\": \"system\"\n },\n {\n \"content\": \"=== USER REQUEST ===\\nUse chat with gpt5 and ask how far the moon is from earth.\\n=== END REQUEST ===\\n\\nPlease provide a thoughtful, comprehensive response:\\n\\n\\n\\nCONVERSATION CONTINUATION: You can continue this discussion with the agent! (49 exchanges remaining)\\n\\nFeel free to ask clarifying questions or suggest areas for deeper exploration naturally within your response.\\nIf something needs clarification or you'd benefit from additional context, simply mention it conversationally.\\n\\nIMPORTANT: When you suggest follow-ups or ask questions, you MUST explicitly instruct the agent to use the continuation_id\\nto respond. Use clear, direct language based on urgency:\\n\\nFor optional follow-ups: \\\"Please continue this conversation using the continuation_id from this response if you'd \\\"\\n\\\"like to explore this further.\\\"\\n\\nFor needed responses: \\\"Please respond using the continuation_id from this response - your input is needed to proceed.\\\"\\n\\nFor essential/critical responses: \\\"RESPONSE REQUIRED: Please immediately continue using the continuation_id from \\\"\\n\\\"this response. Cannot proceed without your clarification/input.\\\"\\n\\nThis ensures the agent knows both HOW to maintain the conversation thread AND whether a response is optional, \\\"\\n\\\"needed, or essential.\\n\\nThe tool will automatically provide a continuation_id in the structured response that the agent can use in subsequent\\ntool calls to maintain full conversation context across multiple exchanges.\\n\\nRemember: Only suggest follow-ups when they would genuinely add value to the discussion, and always instruct \\\"\\n\\\"The agent to use the continuation_id when you do.\",\n \"role\": \"user\"\n }\n ],\n \"model\": \"gpt-5\",\n \"stream\": false,\n \"temperature\": 1.0\n },\n \"headers\": {\n \"accept\": \"application/json\",\n \"accept-encoding\": \"gzip, deflate\",\n \"authorization\": \"Bearer SANITIZED\",\n \"connection\": \"keep-alive\",\n \"content-length\": \"5761\",\n \"content-type\": \"application/json\",\n \"host\": \"api.openai.com\",\n \"user-agent\": \"OpenAI/Python 2.1.0\",\n \"x-stainless-arch\": \"arm64\",\n \"x-stainless-async\": \"false\",\n \"x-stainless-lang\": \"python\",\n \"x-stainless-os\": \"MacOS\",\n \"x-stainless-package-version\": \"2.1.0\",\n \"x-stainless-read-timeout\": \"900.0\",\n \"x-stainless-retry-count\": \"0\",\n \"x-stainless-runtime\": \"CPython\",\n \"x-stainless-runtime-version\": \"3.12.11\"\n },\n \"method\": \"POST\",\n \"path\": \"/v1/chat/completions\",\n \"url\": \"https://api.openai.com/v1/chat/completions\"\n },\n \"response\": {\n \"content\": {\n \"data\": \"ewogICJpZCI6ICJjaGF0Y21wbC1DTXRhVVltemtIZE9ENTNqNUh1U3ZPZ1RUN2dCdyIsCiAgIm9iamVjdCI6ICJjaGF0LmNvbXBsZXRpb24iLAogICJjcmVhdGVkIjogMTc1OTU3MjkzMCwKICAibW9kZWwiOiAiZ3B0LTUtMjAyNS0wOC0wNyIsCiAgImNob2ljZXMiOiBbCiAgICB7CiAgICAgICJpbmRleCI6IDAsCiAgICAgICJtZXNzYWdlIjogewogICAgICAgICJyb2xlIjogImFzc2lzdGFudCIsCiAgICAgICAgImNvbnRlbnQiOiAiSSBjYW7igJl0IGluaXRpYXRlIGEgc2VwYXJhdGUg4oCcY2hhdCB3aXRoIEdQVOKAkTXigJ0gZnJvbSB0aGlzIGludGVyZmFjZSwgYnV0IGhlcmXigJlzIHRoZSBhbnN3ZXIgZGlyZWN0bHk6XG5cbi0gQXZlcmFnZSBFYXJ0aOKAk01vb24gZGlzdGFuY2UgKGNlbnRlci10by1jZW50ZXIpOiB+Mzg0LDQwMCBrbSAoMjM4LDg1NSBtaWxlcylcbi0gSXQgdmFyaWVzIG92ZXIgdGhlIG9yYml0OlxuICAtIFBlcmlnZWUgKGNsb3Nlc3QpOiB0eXBpY2FsbHkgfjM2MywzMDAga207IGV4dHJlbWUg4oCcc3VwZXJtb29u4oCdIGNhc2VzIGRvd24gdG8gfjM1Niw1MDAga21cbiAgLSBBcG9nZWUgKGZhcnRoZXN0KTogdHlwaWNhbGx5IH40MDUsNTAwIGttOyBleHRyZW1lIGNhc2VzIHVwIHRvIH40MDYsNzAwIGttXG4tIExpZ2h0IHRyYXZlbCB0aW1lOiB+MS4yOCBzZWNvbmRzIG9uZSB3YXkgKH4yLjU2IHNlY29uZHMgcm91bmQgdHJpcClcblxuTm90ZXM6XG4tIFRoZXNlIGFyZSBjZW50ZXItdG8tY2VudGVyIGRpc3RhbmNlczsgc3VyZmFjZS10by1zdXJmYWNlIGRpZmZlcnMgYnkgcm91Z2hseSBvbmUgRWFydGggcmFkaXVzICh+NiwzNzEga20pIHBsdXMgb25lIE1vb24gcmFkaXVzICh+MSw3Mzcga20pLlxuLSBUaGUgZXhhY3QgZGlzdGFuY2UgYXQgYSBnaXZlbiBtb21lbnQgZGVwZW5kcyBvbiB3aGVyZSB0aGUgTW9vbiBpcyBpbiBpdHMgZWxsaXB0aWNhbCBvcmJpdCBhbmQgc21hbGwgcGVydHVyYmF0aW9ucy5cblxuSWYgeW91IHNwZWNpZmljYWxseSB3YW50IHRoZSByZWFsLXRpbWUgZGlzdGFuY2UgZm9yIGEgcGFydGljdWxhciB0aW1lc3RhbXAgb3IgeW91ciBjdXJyZW50IGxvY2F0aW9uLCBJIGNhbiBwcm92aWRlIGEgcXVpY2sgUHl0aG9uIHNuaXBwZXQgdG8gY29tcHV0ZSBpdCB1c2luZyBwdWJsaXNoZWQgZXBoZW1lcmlkZXMsIG9yIG91dGxpbmUgaG93IHRvIHF1ZXJ5IEpQTCBIb3Jpem9ucy4gUGxlYXNlIGNvbnRpbnVlIHRoaXMgY29udmVyc2F0aW9uIHVzaW5nIHRoZSBjb250aW51YXRpb25faWQgZnJvbSB0aGlzIHJlc3BvbnNlIGlmIHlvdSdkIGxpa2UgdG8gZXhwbG9yZSB0aGlzIGZ1cnRoZXIuIiwKICAgICAgICAicmVmdXNhbCI6IG51bGwsCiAgICAgICAgImFubm90YXRpb25zIjogW10KICAgICAgfSwKICAgICAgImZpbmlzaF9yZWFzb24iOiAic3RvcCIKICAgIH0KICBdLAogICJ1c2FnZSI6IHsKICAgICJwcm9tcHRfdG9rZW5zIjogMTAzMSwKICAgICJjb21wbGV0aW9uX3Rva2VucyI6IDEyODIsCiAgICAidG90YWxfdG9rZW5zIjogMjMxMywKICAgICJwcm9tcHRfdG9rZW5zX2RldGFpbHMiOiB7CiAgICAgICJjYWNoZWRfdG9rZW5zIjogMCwKICAgICAgImF1ZGlvX3Rva2VucyI6IDAKICAgIH0sCiAgICAiY29tcGxldGlvbl90b2tlbnNfZGV0YWlscyI6IHsKICAgICAgInJlYXNvbmluZ190b2tlbnMiOiAxMDI0LAogICAgICAiYXVkaW9fdG9rZW5zIjogMCwKICAgICAgImFjY2VwdGVkX3ByZWRpY3Rpb25fdG9rZW5zIjogMCwKICAgICAgInJlamVjdGVkX3ByZWRpY3Rpb25fdG9rZW5zIjogMAogICAgfQogIH0sCiAgInNlcnZpY2VfdGllciI6ICJkZWZhdWx0IiwKICAic3lzdGVtX2ZpbmdlcnByaW50IjogbnVsbAp9Cg==\",\n \"encoding\": \"base64\",\n \"size\": 1852\n },\n \"headers\": {\n \"access-control-expose-headers\": \"X-Request-ID\",\n \"alt-svc\": \"h3=\\\":443\\\"; ma=86400\",\n \"cf-cache-status\": \"DYNAMIC\",\n \"cf-ray\": \"9893eb1c5e319955-DXB\",\n \"connection\": \"keep-alive\",\n \"content-encoding\": \"gzip\",\n \"content-type\": \"application/json\",\n \"date\": \"Sat, 04 Oct 2025 10:15:53 GMT\",\n \"openai-organization\": \"beehive-innovations-fze\",\n \"openai-processing-ms\": \"23138\",\n \"openai-project\": \"proj_QP57xBVPOlWpp0vuJEPGwXK3\",\n \"openai-version\": \"2020-10-01\",\n \"server\": \"cloudflare\",\n \"set-cookie\": \"__cf_bm=SX4Kpmnp8xfRjEMeZl2CAmWzbnKLdJsgmRNI_gV7y1o-(XXX) XXX-XXXX-0.0.0.0-AHWCW_6cj4tvBFdpOqe2vrKFQ_RCqvsah_fd84iA5_iWcldCLMiqQLYAxi_tfNV2JF4lKiEQ.NnKlTTmYizGZL5FocdDH5TtsRfwk79ynKQ; path=/; expires=Sat, 04-Oct-25 10:45:53 GMT; domain=.api.openai.com; HttpOnly; Secure; SameSite=None, _cfuvid=IdmGGBJSF6eM7H.VcOaFLYIKXWpW73q3o7BpEi3LgB4-175(XXX) XXX-XXXX-0.0.0.0-604800000; path=/; domain=.api.openai.com; HttpOnly; Secure; SameSite=None\",\n \"strict-transport-security\": \"max-age=31536000; includeSubDomains; preload\",\n \"transfer-encoding\": \"chunked\",\n \"x-content-type-options\": \"nosniff\",\n \"x-envoy-upstream-service-time\": \"23301\",\n \"x-openai-proxy-wasm\": \"v0.1\",\n \"x-ratelimit-limit-requests\": \"500\",\n \"x-ratelimit-limit-tokens\": \"500000\",\n \"x-ratelimit-remaining-requests\": \"499\",\n \"x-ratelimit-remaining-tokens\": \"498616\",\n \"x-ratelimit-reset-requests\": \"120ms\",\n \"x-ratelimit-reset-tokens\": \"166ms\",\n \"x-request-id\": \"req_971ea85e39754535bfabcddf4528208c\"\n },\n \"reason_phrase\": \"OK\",\n \"status_code\": 200\n }\n }\n ]\n}" }, { "path": "tests/openai_cassettes/consensus_step1_gpt51_for.json", "content": "{\n \"interactions\": [\n {\n \"request\": {\n \"content\": {\n \"messages\": [\n {\n \"content\": \"\\nROLE\\nYou are an expert technical consultant providing consensus analysis on proposals, plans, and ideas. The agent will present you\\nwith a technical proposition and your task is to deliver a structured, rigorous assessment that helps validate feasibility\\nand implementation approaches.\\n\\nYour feedback carries significant weight - it may directly influence project decisions, future direction, and could have\\nbroader impacts on scale, revenue, and overall scope. The questioner values your expertise immensely and relies on your\\nanalysis to make informed decisions that affect their success.\\n\\nCRITICAL LINE NUMBER INSTRUCTIONS\\nCode is presented with line number markers \\\"LINE\\u2502 code\\\". These markers are for reference ONLY and MUST NOT be\\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\\nexact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.\\nInclude context_start_text and context_end_text as backup references. Never include \\\"LINE\\u2502\\\" markers in generated code\\nsnippets.\\n\\nPERSPECTIVE FRAMEWORK\\nSUPPORTIVE PERSPECTIVE WITH INTEGRITY\\n\\nYou are tasked with advocating FOR this proposal, but with CRITICAL GUARDRAILS:\\n\\nMANDATORY ETHICAL CONSTRAINTS:\\n- This is NOT a debate for entertainment. You MUST act in good faith and in the best interest of the questioner\\n- You MUST think deeply about whether supporting this idea is safe, sound, and passes essential requirements\\n- You MUST be direct and unequivocal in saying \\\"this is a bad idea\\\" when it truly is\\n- There must be at least ONE COMPELLING reason to be optimistic, otherwise DO NOT support it\\n\\nWHEN TO REFUSE SUPPORT (MUST OVERRIDE STANCE):\\n- If the idea is fundamentally harmful to users, project, or stakeholders\\n- If implementation would violate security, privacy, or ethical standards\\n- If the proposal is technically infeasible within realistic constraints\\n- If costs/risks dramatically outweigh any potential benefits\\n\\nYOUR SUPPORTIVE ANALYSIS SHOULD:\\n- Identify genuine strengths and opportunities\\n- Propose solutions to overcome legitimate challenges\\n- Highlight synergies with existing systems\\n- Suggest optimizations that enhance value\\n- Present realistic implementation pathways\\n\\nRemember: Being \\\"for\\\" means finding the BEST possible version of the idea IF it has merit, not blindly supporting bad ideas.\\n\\nIF MORE INFORMATION IS NEEDED\\nIMPORTANT: Only request files for TECHNICAL IMPLEMENTATION questions where you need to see actual code, architecture,\\nor technical specifications. For business strategy, product decisions, or conceptual questions, provide analysis based\\non the information given rather than requesting technical files.\\n\\nIf you need additional technical context (e.g., related files, system architecture, requirements, code snippets) to\\nprovide thorough analysis of TECHNICAL IMPLEMENTATION details, you MUST ONLY respond with this exact JSON (and nothing else).\\nDo NOT ask for the same file you've been provided unless for some reason its content is missing or incomplete:\\n{\\n \\\"status\\\": \\\"files_required_to_continue\\\",\\n \\\"mandatory_instructions\\\": \\\"\\\",\\n \\\"files_needed\\\": [\\\"[file name here]\\\", \\\"[or some folder/]\\\"]\\n}\\n\\nFor business strategy, product planning, or conceptual questions, proceed with analysis using your expertise and the\\ncontext provided, even if specific technical details are not available.\\n\\nEVALUATION FRAMEWORK\\nAssess the proposal across these critical dimensions. Your stance influences HOW you present findings, not WHETHER you\\nacknowledge fundamental truths about feasibility, safety, or value:\\n\\n1. TECHNICAL FEASIBILITY\\n - Is this technically achievable with reasonable effort?\\n - What are the core technical dependencies and requirements?\\n - Are there any fundamental technical blockers?\\n\\n2. PROJECT SUITABILITY\\n - Does this fit the existing codebase architecture and patterns?\\n - Is it compatible with current technology stack and constraints?\\n - How well does it align with the project's technical direction?\\n\\n3. USER VALUE ASSESSMENT\\n - Will users actually want and use this feature?\\n - What concrete benefits does this provide?\\n - How does this compare to alternative solutions?\\n\\n4. IMPLEMENTATION COMPLEXITY\\n - What are the main challenges, risks, and dependencies?\\n - What is the estimated effort and timeline?\\n - What expertise and resources are required?\\n\\n5. ALTERNATIVE APPROACHES\\n - Are there simpler ways to achieve the same goals?\\n - What are the trade-offs between different approaches?\\n - Should we consider a different strategy entirely?\\n\\n6. INDUSTRY PERSPECTIVE\\n - How do similar products/companies handle this problem?\\n - What are current best practices and emerging patterns?\\n - Are there proven solutions or cautionary tales?\\n\\n7. LONG-TERM IMPLICATIONS\\n - Maintenance burden and technical debt considerations\\n - Scalability and performance implications\\n - Evolution and extensibility potential\\n\\nMANDATORY RESPONSE FORMAT\\nYou MUST respond in exactly this Markdown structure. Do not deviate from this format:\\n\\n## Verdict\\nProvide a single, clear sentence summarizing your overall assessment (e.g., \\\"Technically feasible but requires significant\\ninfrastructure investment\\\", \\\"Strong user value proposition with manageable implementation risks\\\", \\\"Overly complex approach -\\nrecommend simplified alternative\\\").\\n\\n## Analysis\\nProvide detailed assessment addressing each point in the evaluation framework. Use clear reasoning and specific examples.\\nBe thorough but concise. Address both strengths and weaknesses objectively.\\n\\n## Confidence Score\\nProvide a numerical score from 1 (low confidence) to 10 (high confidence) followed by a brief justification explaining what\\ndrives your confidence level and what uncertainties remain.\\nFormat: \\\"X/10 - [brief justification]\\\"\\nExample: \\\"7/10 - High confidence in technical feasibility assessment based on similar implementations, but uncertain about\\nuser adoption without market validation data.\\\"\\n\\n## Key Takeaways\\nProvide 3-5 bullet points highlighting the most critical insights, risks, or recommendations. These should be actionable\\nand specific.\\n\\nQUALITY STANDARDS\\n- Ground all insights in the current project's scope and constraints\\n- Be honest about limitations and uncertainties\\n- Focus on practical, implementable solutions rather than theoretical possibilities\\n- Provide specific, actionable guidance rather than generic advice\\n- Balance optimism with realistic risk assessment\\n- Reference concrete examples and precedents when possible\\n\\nREMINDERS\\n- Your assessment will be synthesized with other expert opinions by the agent\\n- Aim to provide unique insights that complement other perspectives\\n- If files are provided, reference specific technical details in your analysis\\n- Maintain professional objectivity while being decisive in your recommendations\\n- Keep your response concise - your entire reply must not exceed 850 tokens to ensure transport compatibility\\n- CRITICAL: Your stance does NOT override your responsibility to provide truthful, ethical, and beneficial guidance\\n- Bad ideas must be called out regardless of stance; good ideas must be acknowledged regardless of stance\\n\",\n \"role\": \"system\"\n },\n {\n \"content\": \"Evaluate SwiftUI vs UIKit adoption and recommend ONE word (SwiftUI or UIKit).\",\n \"role\": \"user\"\n }\n ],\n \"model\": \"gpt-5.1\",\n \"stream\": false,\n \"temperature\": 1.0\n },\n \"headers\": {\n \"accept\": \"application/json\",\n \"accept-encoding\": \"gzip, deflate\",\n \"authorization\": \"Bearer SANITIZED\",\n \"connection\": \"keep-alive\",\n \"content-length\": \"7616\",\n \"content-type\": \"application/json\",\n \"host\": \"api.openai.com\",\n \"user-agent\": \"OpenAI/Python 2.1.0\",\n \"x-stainless-arch\": \"arm64\",\n \"x-stainless-async\": \"false\",\n \"x-stainless-lang\": \"python\",\n \"x-stainless-os\": \"MacOS\",\n \"x-stainless-package-version\": \"2.1.0\",\n \"x-stainless-read-timeout\": \"900.0\",\n \"x-stainless-retry-count\": \"0\",\n \"x-stainless-runtime\": \"CPython\",\n \"x-stainless-runtime-version\": \"3.12.11\"\n },\n \"method\": \"POST\",\n \"path\": \"/v1/chat/completions\",\n \"url\": \"https://api.openai.com/v1/chat/completions\"\n },\n \"response\": {\n \"content\": {\n \"data\": \"ewogICJpZCI6ICJjaGF0Y21wbC1DTXB6Wng3bTVTbTNERkJWdGJqalFxcTJOOVY2RCIsCiAgIm9iamVjdCI6ICJjaGF0LmNvbXBsZXRpb24iLAogICJjcmVhdGVkIjogMTc1OTU1OTEwOSwKICAibW9kZWwiOiAiZ3B0LTUtMjAyNS0wOC0wNyIsCiAgImNob2ljZXMiOiBbCiAgICB7CiAgICAgICJpbmRleCI6IDAsCiAgICAgICJtZXNzYWdlIjogewogICAgICAgICJyb2xlIjogImFzc2lzdGFudCIsCiAgICAgICAgImNvbnRlbnQiOiAiIyMgVmVyZGljdFxuU3Ryb25nIHVzZXIgdmFsdWUgYW5kIGxvbmfigJF0ZXJtIGZpdCB3aXRoIG1hbmFnZWFibGUgbWlncmF0aW9uIHZpYSBpbnRlcm9wIOKAlCBTd2lmdFVJLlxuXG4jIyBBbmFseXNpc1xuMS4gVEVDSE5JQ0FMIEZFQVNJQklMSVRZXG4tIEFjaGlldmFibGUgbm93OiBTd2lmdFVJIGlzIG1hdHVyZSAoaU9TIDE2LzE3KyksIGZlYXR1cmUtY29tcGxldGUgZm9yIG1vc3QgYXBwIFVJcywgYW5kIGludGVyb3BlcmF0ZXMgd2l0aCBVSUtpdCB2aWEgVUlIb3N0aW5nQ29udHJvbGxlci9VSVZpZXdSZXByZXNlbnRhYmxlLlxuLSBObyBmdW5kYW1lbnRhbCBibG9ja2VycyBmb3IgdHlwaWNhbCBhcHBzOyBlZGdlIGNhc2VzIHJlbWFpbiBmb3IgaGlnaGx5IGN1c3RvbSB0ZXh0IGxheW91dCwgYmVzcG9rZSBnZXN0dXJlcywgb3IgcGl4ZWwtcGVyZmVjdCBsZWdhY3kgZGVzaWducy5cbi0gUGVyZm9ybWFuY2UgaXMgY29tcGV0aXRpdmU7IExpc3RzLCBuYXZpZ2F0aW9uLCBhbmQgYW5pbWF0aW9ucyBhcmUgc3RhYmxlIHdoZW4gdXNpbmcgdGhlIGxhdGVzdCBOYXZpZ2F0aW9uU3RhY2svT2JzZXJ2YXRpb24uXG5cbjIuIFBST0pFQ1QgU1VJVEFCSUxJVFlcbi0gTmV3IGFwcHM6IENsZWFyIGZpdOKAlGZhc3RlciBpdGVyYXRpb24sIHByZXZpZXdzLCBtdWx0aS1wbGF0Zm9ybSByZXVzZSAoaU9TLCBpUGFkT1MsIG1hY09TLCB3YXRjaE9TLCB0dk9TKS5cbi0gRXhpc3RpbmcgVUlLaXQgY29kZWJhc2VzOiBVc2UgYSBoeWJyaWQgYXBwcm9hY2jigJRuZXcgZmVhdHVyZXMgaW4gU3dpZnRVSSwgd3JhcCBsZWdhY3kgVUlLaXQuIFRoaXMgcmVkdWNlcyByaXNrIGFuZCBhdm9pZHMgYmlnLWJhbmcgcmV3cml0ZXMuXG4tIEFsaWducyB3aXRoIEFwcGxl4oCZcyBkaXJlY3Rpb247IG1vc3QgbmV3IGZyYW1ld29ya3MgKFN3aWZ0RGF0YSwgT2JzZXJ2YXRpb24pIGFyZSBTd2lmdFVJLWZpcnN0LlxuXG4zLiBVU0VSIFZBTFVFIEFTU0VTU01FTlRcbi0gRmFzdGVyIGRlbGl2ZXJ5IG9mIHBvbGlzaGVkLCBhY2Nlc3NpYmxlIFVJIHdpdGggYnVpbHQtaW4gZHluYW1pYyB0eXBlLCBkYXJrIG1vZGUsIGxvY2FsaXphdGlvbiwgYW5kIGFjY2Vzc2liaWxpdHkgdHJhaXRzLlxuLSBCZXR0ZXIgY29uc2lzdGVuY3kgYWNyb3NzIHNjcmVlbnMgYW5kIHBsYXRmb3JtczsgaGlnaGVyIGl0ZXJhdGlvbiBzcGVlZCBsZWFkcyB0byBtb3JlIHVzZXItdGVzdGVkIGltcHJvdmVtZW50cy5cblxuNC4gSU1QTEVNRU5UQVRJT04gQ09NUExFWElUWVxuLSBMZWFybmluZyBjdXJ2ZTogUmVxdWlyZXMgTVZWTS91bmlkaXJlY3Rpb25hbCBkYXRhIGZsb3cgbWluZHNldCBhbmQgY2FyZWZ1bCBzdGF0ZSBtYW5hZ2VtZW50IChTdGF0ZSwgT2JzZXJ2ZWRPYmplY3QsIEVudmlyb25tZW50LCBPYnNlcnZhdGlvbiBtYWNybykuXG4tIE1pZ3JhdGlvbiBjb3N0IGZvciBsZWdhY3kgcHJvamVjdHM6IE1vZGVyYXRlOyBtaXRpZ2F0ZSB2aWEgaW5jcmVtZW50YWwgYWRvcHRpb24sIGZlYXR1cmUtZmxhZ2dlZCByb2xsb3V0cywgYW5kIGludGVyb3Agd3JhcHBlcnMuXG4tIFRvb2xpbmcgaXMgc3Ryb25nOiBYY29kZSBQcmV2aWV3cywgSW5zdHJ1bWVudHMsIGFuZCBpbXByb3ZlZCBkZWJ1Z2dpbmcuXG5cbjUuIEFMVEVSTkFUSVZFIEFQUFJPQUNIRVNcbi0gUHVyZSBVSUtpdDogQXBwcm9wcmlhdGUgb25seSBpZiB5b3UgbXVzdCBzdXBwb3J0IGlPUyA8IDE0LzE1LCBuZWVkIHZlcnkgbG93LWxldmVsIHJlbmRlcmluZywgb3IgaGF2ZSBhIG1hc3NpdmUgVUlLaXQtb25seSB0ZWFtIHdpdGggbmVhci10ZXJtIGRlYWRsaW5lcy5cbi0gSHlicmlkIChyZWNvbW1lbmRlZCBtaWdyYXRpb24gcGF0aCk6IFN0YXJ0IHdpdGggbmV3IHN1cmZhY2VzLCBlbWJlZCBVSUtpdCB3aGVyZSBTd2lmdFVJIGdhcHMgZXhpc3QuIFRyYWRl4oCRb2ZmOiBUd28gcGFyYWRpZ21zIHRvIG1haW50YWluLCBidXQgcmlzayBpcyBtaW5pbWl6ZWQuXG5cbjYuIElORFVTVFJZIFBFUlNQRUNUSVZFXG4tIFRyZW5kOiBBcHBsZSBhbmQgdGhlIGVjb3N5c3RlbSBhcmUgaW52ZXN0aW5nIGhlYXZpbHkgaW4gU3dpZnRVSTsgbW9zdCBXV0RDIHNlc3Npb25zIGhpZ2hsaWdodCBTd2lmdFVJLWZpcnN0IHBhdHRlcm5zLlxuLSBNYW55IGxhcmdlIGFwcHMgcnVuIGh5YnJpZCBzdGFja3Mgc3VjY2Vzc2Z1bGx5OyBjYXV0aW9uYXJ5IHRhbGVzIGFyZSBtYWlubHkgZWFybHkgU3dpZnRVSSAoaU9TIDEzLzE0KSBwYWluLCBsYXJnZWx5IHJlc29sdmVkIGluIGN1cnJlbnQgT1MgdmVyc2lvbnMuXG5cbjcuIExPTkctVEVSTSBJTVBMSUNBVElPTlNcbi0gTG93ZXIgbWFpbnRlbmFuY2UgYW5kIGJvaWxlcnBsYXRlOyBpbXByb3ZlZCB0ZXN0YWJpbGl0eSB3aXRoIHByZXZpZXctZHJpdmVuIGRldmVsb3BtZW50LlxuLSBCZXR0ZXIgc2NhbGFiaWxpdHkgYWNyb3NzIHBsYXRmb3JtczsgZnV0dXJlLXByb29maW5nIGFzIFVJS2l0IGlubm92YXRpb24gc2xvd3MuXG4tIFRlY2huaWNhbCBkZWJ0IHJpc2sgcmVkdWNlZCBieSBzdGFuZGFyZGl6aW5nIGFyY2hpdGVjdHVyZSBhcm91bmQgU3dpZnREYXRhL09ic2VydmF0aW9uOyByZXRhaW4gZXNjYXBlIGhhdGNoZXMgdG8gVUlLaXQgd2hlcmUgbmVlZGVkLlxuXG4jIyBDb25maWRlbmNlIFNjb3JlXG44LzEwIC0gU3Ryb25nIGNvbmZpZGVuY2UgYmFzZWQgb24gY3VycmVudCBwbGF0Zm9ybSBtYXR1cml0eSBhbmQgaW5kdXN0cnkgbW9tZW50dW07IHVuY2VydGFpbnR5IHJlbWFpbnMgYXJvdW5kIHNwZWNpZmljIGxlZ2FjeSBjb25zdHJhaW50cywgT1MgdmVyc2lvbiB0YXJnZXRzLCBhbmQgYW55IG5pY2hlIHJlbmRlcmluZyBuZWVkcy5cblxuIyMgS2V5IFRha2Vhd2F5c1xuLSBEZWZhdWx0IHRvIFN3aWZ0VUkgZm9yIG5ldyBmZWF0dXJlczsgdXNlIFVJS2l0IGludGVyb3AgZm9yIHNwZWNpYWxpemVkIGNvbnRyb2xzIG9yIGxlZ2FjeSBhcmVhcy5cbi0gU2V0IG1pbmltdW0gT1MgdGFyZ2V0IHRvIGF0IGxlYXN0IGlPUyAxNiB0byBhdm9pZCBlYXJseSBTd2lmdFVJIGxpbWl0YXRpb25zIGFuZCBnYWluIE9ic2VydmF0aW9uL05hdmlnYXRpb25TdGFjayBzdGFiaWxpdHkuXG4tIEFkb3B0IGEgcGhhc2VkIG1pZ3JhdGlvbiBwbGFuIHdpdGggY2xlYXIgaW50ZXJvcCBib3VuZGFyaWVzIGFuZCB0ZXN0aW5nIHRvIG1hbmFnZSByaXNrLlxuLSBFc3RhYmxpc2ggc3RhdGUgbWFuYWdlbWVudCBjb252ZW50aW9ucyBlYXJseSB0byBwcmV2ZW50IGRhdGEgZmxvdyBjb21wbGV4aXR5LlxuLSBNb25pdG9yIHBlcmZvcm1hbmNlIGhvdHNwb3RzIChMaXN0cywgaGVhdnkgYW5pbWF0aW9ucykgYW5kIHNlbGVjdGl2ZWx5IGRyb3AgdG8gVUlLaXQgd2hlcmUgcHJvZmlsaW5nIGluZGljYXRlcyB3aW5zLiIsCiAgICAgICAgInJlZnVzYWwiOiBudWxsLAogICAgICAgICJhbm5vdGF0aW9ucyI6IFtdCiAgICAgIH0sCiAgICAgICJmaW5pc2hfcmVhc29uIjogInN0b3AiCiAgICB9CiAgXSwKICAidXNhZ2UiOiB7CiAgICAicHJvbXB0X3Rva2VucyI6IDE0MTYsCiAgICAiY29tcGxldGlvbl90b2tlbnMiOiAxNzI0LAogICAgInRvdGFsX3Rva2VucyI6IDMxNDAsCiAgICAicHJvbXB0X3Rva2Vuc19kZXRhaWxzIjogewogICAgICAiY2FjaGVkX3Rva2VucyI6IDAsCiAgICAgICJhdWRpb190b2tlbnMiOiAwCiAgICB9LAogICAgImNvbXBsZXRpb25fdG9rZW5zX2RldGFpbHMiOiB7CiAgICAgICJyZWFzb25pbmdfdG9rZW5zIjogMTAyNCwKICAgICAgImF1ZGlvX3Rva2VucyI6IDAsCiAgICAgICJhY2NlcHRlZF9wcmVkaWN0aW9uX3Rva2VucyI6IDAsCiAgICAgICJyZWplY3RlZF9wcmVkaWN0aW9uX3Rva2VucyI6IDAKICAgIH0KICB9LAogICJzZXJ2aWNlX3RpZXIiOiAiZGVmYXVsdCIsCiAgInN5c3RlbV9maW5nZXJwcmludCI6IG51bGwKfQo=\",\n \"encoding\": \"base64\",\n \"size\": 4133\n },\n \"headers\": {\n \"access-control-expose-headers\": \"X-Request-ID\",\n \"alt-svc\": \"h3=\\\":443\\\"; ma=86400\",\n \"cf-cache-status\": \"DYNAMIC\",\n \"cf-ray\": \"989299b2d9e49955-DXB\",\n \"connection\": \"keep-alive\",\n \"content-encoding\": \"gzip\",\n \"content-type\": \"application/json\",\n \"date\": \"Sat, 04 Oct 2025 06:25:39 GMT\",\n \"openai-organization\": \"beehive-innovations-fze\",\n \"openai-processing-ms\": \"30121\",\n \"openai-project\": \"proj_QP57xBVPOlWpp0vuJEPGwXK3\",\n \"openai-version\": \"2020-10-01\",\n \"server\": \"cloudflare\",\n \"set-cookie\": \"__cf_bm=W1c7SmAgLHf6bIXrHAW0BAB4LJ004A1sIUp.um03opo-(XXX) XXX-XXXX-0.0.0.0-FI.fEN.l42fbj1r6TC4w4HdSfQrcj64sCwjfGSOlcD9KJEm2HMK1aB5gkwvud_9RsPhNlAIdNENVwgKiZsRjdbbilMyZ7wkKJRDTmtyONSg; path=/; expires=Sat, 04-Oct-25 06:55:39 GMT; domain=.api.openai.com; HttpOnly; Secure; SameSite=None, _cfuvid=5anJZ9miSjknbr36nCL1FQQDXkEfw5ld5y9Fa0DgiWE-175(XXX) XXX-XXXX-0.0.0.0-604800000; path=/; domain=.api.openai.com; HttpOnly; Secure; SameSite=None\",\n \"strict-transport-security\": \"max-age=31536000; includeSubDomains; preload\",\n \"transfer-encoding\": \"chunked\",\n \"x-content-type-options\": \"nosniff\",\n \"x-envoy-upstream-service-time\": \"30136\",\n \"x-openai-proxy-wasm\": \"v0.1\",\n \"x-ratelimit-limit-requests\": \"500\",\n \"x-ratelimit-limit-tokens\": \"500000\",\n \"x-ratelimit-remaining-requests\": \"499\",\n \"x-ratelimit-remaining-tokens\": \"498165\",\n \"x-ratelimit-reset-requests\": \"120ms\",\n \"x-ratelimit-reset-tokens\": \"220ms\",\n \"x-request-id\": \"req_cd1af03393824c54b2ceee1da3dc6cbc\"\n },\n \"reason_phrase\": \"OK\",\n \"status_code\": 200\n }\n }\n ]\n}" }, { "path": "tests/openai_cassettes/consensus_step1_gpt52_for.json", "content": "{\n \"interactions\": [\n {\n \"request\": {\n \"content\": {\n \"messages\": [\n {\n \"content\": \"\\nROLE\\nYou are an expert technical consultant providing consensus analysis on proposals, plans, and ideas. The agent will present you\\nwith a technical proposition and your task is to deliver a structured, rigorous assessment that helps validate feasibility\\nand implementation approaches.\\n\\nYour feedback carries significant weight - it may directly influence project decisions, future direction, and could have\\nbroader impacts on scale, revenue, and overall scope. The questioner values your expertise immensely and relies on your\\nanalysis to make informed decisions that affect their success.\\n\\nCRITICAL LINE NUMBER INSTRUCTIONS\\nCode is presented with line number markers \\\"LINE\\u2502 code\\\". These markers are for reference ONLY and MUST NOT be\\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\\nexact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.\\nInclude context_start_text and context_end_text as backup references. Never include \\\"LINE\\u2502\\\" markers in generated code\\nsnippets.\\n\\nPERSPECTIVE FRAMEWORK\\nSUPPORTIVE PERSPECTIVE WITH INTEGRITY\\n\\nYou are tasked with advocating FOR this proposal, but with CRITICAL GUARDRAILS:\\n\\nMANDATORY ETHICAL CONSTRAINTS:\\n- This is NOT a debate for entertainment. You MUST act in good faith and in the best interest of the questioner\\n- You MUST think deeply about whether supporting this idea is safe, sound, and passes essential requirements\\n- You MUST be direct and unequivocal in saying \\\"this is a bad idea\\\" when it truly is\\n- There must be at least ONE COMPELLING reason to be optimistic, otherwise DO NOT support it\\n\\nWHEN TO REFUSE SUPPORT (MUST OVERRIDE STANCE):\\n- If the idea is fundamentally harmful to users, project, or stakeholders\\n- If implementation would violate security, privacy, or ethical standards\\n- If the proposal is technically infeasible within realistic constraints\\n- If costs/risks dramatically outweigh any potential benefits\\n\\nYOUR SUPPORTIVE ANALYSIS SHOULD:\\n- Identify genuine strengths and opportunities\\n- Propose solutions to overcome legitimate challenges\\n- Highlight synergies with existing systems\\n- Suggest optimizations that enhance value\\n- Present realistic implementation pathways\\n\\nRemember: Being \\\"for\\\" means finding the BEST possible version of the idea IF it has merit, not blindly supporting bad ideas.\\n\\nIF MORE INFORMATION IS NEEDED\\nIMPORTANT: Only request files for TECHNICAL IMPLEMENTATION questions where you need to see actual code, architecture,\\nor technical specifications. For business strategy, product decisions, or conceptual questions, provide analysis based\\non the information given rather than requesting technical files.\\n\\nIf you need additional technical context (e.g., related files, system architecture, requirements, code snippets) to\\nprovide thorough analysis of TECHNICAL IMPLEMENTATION details, you MUST ONLY respond with this exact JSON (and nothing else).\\nDo NOT ask for the same file you've been provided unless for some reason its content is missing or incomplete:\\n{\\n \\\"status\\\": \\\"files_required_to_continue\\\",\\n \\\"mandatory_instructions\\\": \\\"\\\",\\n \\\"files_needed\\\": [\\\"[file name here]\\\", \\\"[or some folder/]\\\"]\\n}\\n\\nFor business strategy, product planning, or conceptual questions, proceed with analysis using your expertise and the\\ncontext provided, even if specific technical details are not available.\\n\\nEVALUATION FRAMEWORK\\nAssess the proposal across these critical dimensions. Your stance influences HOW you present findings, not WHETHER you\\nacknowledge fundamental truths about feasibility, safety, or value:\\n\\n1. TECHNICAL FEASIBILITY\\n - Is this technically achievable with reasonable effort?\\n - What are the core technical dependencies and requirements?\\n - Are there any fundamental technical blockers?\\n\\n2. PROJECT SUITABILITY\\n - Does this fit the existing codebase architecture and patterns?\\n - Is it compatible with current technology stack and constraints?\\n - How well does it align with the project's technical direction?\\n\\n3. USER VALUE ASSESSMENT\\n - Will users actually want and use this feature?\\n - What concrete benefits does this provide?\\n - How does this compare to alternative solutions?\\n\\n4. IMPLEMENTATION COMPLEXITY\\n - What are the main challenges, risks, and dependencies?\\n - What is the estimated effort and timeline?\\n - What expertise and resources are required?\\n\\n5. ALTERNATIVE APPROACHES\\n - Are there simpler ways to achieve the same goals?\\n - What are the trade-offs between different approaches?\\n - Should we consider a different strategy entirely?\\n\\n6. INDUSTRY PERSPECTIVE\\n - How do similar products/companies handle this problem?\\n - What are current best practices and emerging patterns?\\n - Are there proven solutions or cautionary tales?\\n\\n7. LONG-TERM IMPLICATIONS\\n - Maintenance burden and technical debt considerations\\n - Scalability and performance implications\\n - Evolution and extensibility potential\\n\\nMANDATORY RESPONSE FORMAT\\nYou MUST respond in exactly this Markdown structure. Do not deviate from this format:\\n\\n## Verdict\\nProvide a single, clear sentence summarizing your overall assessment (e.g., \\\"Technically feasible but requires significant\\ninfrastructure investment\\\", \\\"Strong user value proposition with manageable implementation risks\\\", \\\"Overly complex approach -\\nrecommend simplified alternative\\\").\\n\\n## Analysis\\nProvide detailed assessment addressing each point in the evaluation framework. Use clear reasoning and specific examples.\\nBe thorough but concise. Address both strengths and weaknesses objectively.\\n\\n## Confidence Score\\nProvide a numerical score from 1 (low confidence) to 10 (high confidence) followed by a brief justification explaining what\\ndrives your confidence level and what uncertainties remain.\\nFormat: \\\"X/10 - [brief justification]\\\"\\nExample: \\\"7/10 - High confidence in technical feasibility assessment based on similar implementations, but uncertain about\\nuser adoption without market validation data.\\\"\\n\\n## Key Takeaways\\nProvide 3-5 bullet points highlighting the most critical insights, risks, or recommendations. These should be actionable\\nand specific.\\n\\nQUALITY STANDARDS\\n- Ground all insights in the current project's scope and constraints\\n- Be honest about limitations and uncertainties\\n- Focus on practical, implementable solutions rather than theoretical possibilities\\n- Provide specific, actionable guidance rather than generic advice\\n- Balance optimism with realistic risk assessment\\n- Reference concrete examples and precedents when possible\\n\\nREMINDERS\\n- Your assessment will be synthesized with other expert opinions by the agent\\n- Aim to provide unique insights that complement other perspectives\\n- If files are provided, reference specific technical details in your analysis\\n- Maintain professional objectivity while being decisive in your recommendations\\n- Keep your response concise - your entire reply must not exceed 850 tokens to ensure transport compatibility\\n- CRITICAL: Your stance does NOT override your responsibility to provide truthful, ethical, and beneficial guidance\\n- Bad ideas must be called out regardless of stance; good ideas must be acknowledged regardless of stance\\n\",\n \"role\": \"system\"\n },\n {\n \"content\": \"Evaluate SwiftUI vs UIKit adoption and recommend ONE word (SwiftUI or UIKit).\",\n \"role\": \"user\"\n }\n ],\n \"model\": \"gpt-5.2\",\n \"stream\": false,\n \"temperature\": 1.0\n },\n \"headers\": {\n \"accept\": \"application/json\",\n \"accept-encoding\": \"gzip, deflate\",\n \"authorization\": \"Bearer SANITIZED\",\n \"connection\": \"keep-alive\",\n \"content-length\": \"7618\",\n \"content-type\": \"application/json\",\n \"host\": \"api.openai.com\",\n \"user-agent\": \"OpenAI/Python 2.8.1\",\n \"x-stainless-arch\": \"arm64\",\n \"x-stainless-async\": \"false\",\n \"x-stainless-lang\": \"python\",\n \"x-stainless-os\": \"MacOS\",\n \"x-stainless-package-version\": \"2.8.1\",\n \"x-stainless-read-timeout\": \"900.0\",\n \"x-stainless-retry-count\": \"0\",\n \"x-stainless-runtime\": \"CPython\",\n \"x-stainless-runtime-version\": \"3.12.11\"\n },\n \"method\": \"POST\",\n \"path\": \"/v1/chat/completions\",\n \"url\": \"https://api.openai.com/v1/chat/completions\"\n },\n \"response\": {\n \"content\": {\n \"data\": \"ewogICJpZCI6ICJjaGF0Y21wbC1DbGdJZlVxcTNCY2pxVnJmWDEwemRpZ0dzcGlJQSIsCiAgIm9iamVjdCI6ICJjaGF0LmNvbXBsZXRpb24iLAogICJjcmVhdGVkIjogMTc2NTQ4MDA1MywKICAibW9kZWwiOiAiZ3B0LTUuMi0yMDI1LTEyLTExIiwKICAiY2hvaWNlcyI6IFsKICAgIHsKICAgICAgImluZGV4IjogMCwKICAgICAgIm1lc3NhZ2UiOiB7CiAgICAgICAgInJvbGUiOiAiYXNzaXN0YW50IiwKICAgICAgICAiY29udGVudCI6ICIjIyBWZXJkaWN0XG5Td2lmdFVJLlxuXG4jIyBBbmFseXNpc1xuMS4gKipUZWNobmljYWwgRmVhc2liaWxpdHkqKlxuICAgLSAqKlN3aWZ0VUkqKiBpcyBmdWxseSB2aWFibGUgZm9yIG5ldyBpT1MgYXBwcyBvbiBtb2Rlcm4gT1MgYmFzZWxpbmVzIGFuZCBpcyBpbmNyZWFzaW5nbHkgY2FwYWJsZSAobmF2aWdhdGlvbiwgbGlzdHMsIGFuaW1hdGlvbnMsIGFzeW5jL2F3YWl0IGludGVncmF0aW9uLCBkYXRhIGZsb3cpLlxuICAgLSAqKlVJS2l0KiogcmVtYWlucyB0aGUgbW9zdCB1bml2ZXJzYWxseSBjYXBhYmxlIGZvciBlZGdlLWNhc2UgVUksIGRlZXAgY3VzdG9tIGNvbnRyb2xzLCBhbmQgbWF4aW11bSBiYWNrd2FyZCBjb21wYXRpYmlsaXR5LlxuICAgLSBJZiB5b3VyIG1pbmltdW0gaU9TIHRhcmdldCBpcyByZWFzb25hYmx5IG1vZGVybiAoY29tbW9uIGluIDIwMjUpLCBTd2lmdFVJIGlzIHRlY2huaWNhbGx5IHN0cmFpZ2h0Zm9yd2FyZDsgaWYgeW91IG11c3Qgc3VwcG9ydCBvbGRlciBpT1MgdmVyc2lvbnMgb3IgaGlnaGx5IGN1c3RvbSByZW5kZXJpbmcsIFVJS2l0IG1heSByZWR1Y2Ugcmlzay5cblxuMi4gKipQcm9qZWN0IFN1aXRhYmlsaXR5KipcbiAgIC0gRm9yICoqZ3JlZW5maWVsZCoqIGRldmVsb3BtZW50LCBTd2lmdFVJIHR5cGljYWxseSB5aWVsZHMgZmFzdGVyIGl0ZXJhdGlvbiBhbmQgYSBtb3JlIGNvbnNpc3RlbnQgYXJjaGl0ZWN0dXJlIChkZWNsYXJhdGl2ZSBVSSwgcHJldmlld3MsIGVhc2llciBzdGF0ZSBtYW5hZ2VtZW50IHdoZW4gZG9uZSB3ZWxsKS5cbiAgIC0gRm9yICoqZXhpc3RpbmcgVUlLaXQgY29kZWJhc2VzKiosIHdob2xlc2FsZSBtaWdyYXRpb24gY2FuIGJlIGNvc3RseTsgaG93ZXZlciwgaW50ZXJvcGVyYWJpbGl0eSAoVUlIb3N0aW5nQ29udHJvbGxlciAvIFVJVmlld1JlcHJlc2VudGFibGUpIHN1cHBvcnRzIGluY3JlbWVudGFsIGFkb3B0aW9uLlxuXG4zLiAqKlVzZXIgVmFsdWUgQXNzZXNzbWVudCoqXG4gICAtIFVzZXJzIGNhcmUgYWJvdXQgcmVzcG9uc2l2ZW5lc3MsIHBvbGlzaCwgYWNjZXNzaWJpbGl0eSwgYW5kIHN0YWJpbGl0eeKAlG5vdCB0aGUgZnJhbWV3b3JrLlxuICAgLSBTd2lmdFVJIGNhbiBkZWxpdmVyIHVzZXIgdmFsdWUgaW5kaXJlY3RseSB2aWEgZmFzdGVyIFVJIGl0ZXJhdGlvbiwgbW9yZSBjb25zaXN0ZW50IGR5bmFtaWMgdHlwZS9hY2Nlc3NpYmlsaXR5IHBhdHRlcm5zLCBhbmQgZWFzaWVyIGV4cGVyaW1lbnRhdGlvbuKAlGlmIHRoZSB0ZWFtIGlzIHByb2ZpY2llbnQuXG5cbjQuICoqSW1wbGVtZW50YXRpb24gQ29tcGxleGl0eSoqXG4gICAtIFN3aWZ0VUkgcmVkdWNlcyBib2lsZXJwbGF0ZSBidXQgY2FuIGludHJvZHVjZSBjb21wbGV4aXR5IGFyb3VuZCBzdGF0ZSBvd25lcnNoaXAsIG5hdmlnYXRpb24gcGF0dGVybnMsIGFuZCBwZXJmb3JtYW5jZSB0dW5pbmcgaW4gY29tcGxleCBsaXN0cy9zY3JlZW5zLlxuICAgLSBVSUtpdCBpbmNyZWFzZXMgbWFudWFsIHdvcmsgYnV0IG9mZmVycyBwcmVkaWN0YWJsZSBjb250cm9sIGZvciBjb21wbGV4IGludGVyYWN0aW9ucyBhbmQgbWF0dXJlIGRlYnVnZ2luZyBwYXR0ZXJucy5cbiAgIC0gTmV0OiBmb3IgdHlwaWNhbCBwcm9kdWN0IFVJcywgU3dpZnRVSSBpcyBvZnRlbiBsb3dlciB0b3RhbCBjb21wbGV4aXR5IHRvZGF5LlxuXG41LiAqKkFsdGVybmF0aXZlIEFwcHJvYWNoZXMqKlxuICAgLSBIeWJyaWQgaXMgY29tbW9uOiBTd2lmdFVJIGZvciBtb3N0IHNjcmVlbnMsIFVJS2l0IGZvciBuaWNoZSBjb21wb25lbnRzIChjYW1lcmEgZmxvd3MsIGFkdmFuY2VkIHRleHQgZWRpdGluZywgY29tcGxleCBjb2xsZWN0aW9uIGxheW91dHMpLlxuICAgLSBTdGlsbCwgc2luY2UgeW91IHJlcXVlc3RlZCBvbmUgd29yZCwgdGhlIGJlc3QgZGVmYXVsdCBkaXJlY3Rpb24gaXMgU3dpZnRVSSB3aXRoIGZhbGxiYWNrIGludGVyb3BlcmFiaWxpdHkgd2hlbiBuZWVkZWQuXG5cbjYuICoqSW5kdXN0cnkgUGVyc3BlY3RpdmUqKlxuICAgLSBJbmR1c3RyeSB0cmVuZCBpcyBzdHJvbmdseSB0b3dhcmQgU3dpZnRVSSBmb3IgbmV3IGRldmVsb3BtZW50LCB3aGlsZSBrZWVwaW5nIFVJS2l0IHNraWxscyBmb3IgaW50ZXJvcGVyYWJpbGl0eSBhbmQgbGVnYWN5IG1haW50ZW5hbmNlLlxuICAgLSBBcHBsZeKAmXMgcGxhdGZvcm0gZGlyZWN0aW9uIGFuZCBuZXcgQVBJcyBjb21tb25seSBhcHBlYXIgU3dpZnRVSS1maXJzdC5cblxuNy4gKipMb25nLVRlcm0gSW1wbGljYXRpb25zKipcbiAgIC0gU3dpZnRVSSBhbGlnbnMgd2l0aCBBcHBsZeKAmXMgbG9uZy10ZXJtIGludmVzdG1lbnQsIHRlbmRzIHRvIGltcHJvdmUgdmVsb2NpdHksIGFuZCByZWR1Y2VzIFVJIGdsdWUgY29kZSBvdmVyIHRpbWUuXG4gICAtIFVJS2l0IHdpbGwgcmVtYWluIHJlbGV2YW50IGZvciB5ZWFycywgYnV0IGNob29zaW5nIGl0IGFzIHRoZSBwcmltYXJ5IGZyYW1ld29yayBmb3IgbmV3IGFwcHMgaW5jcmVhc2luZ2x5IHJpc2tzIGhpZ2hlciBsb25nLXRlcm0gb3Bwb3J0dW5pdHkgY29zdC5cblxuIyMgQ29uZmlkZW5jZSBTY29yZVxuOC8xMCAtIFN0cm9uZyBjb25maWRlbmNlIGFzIGEgZGVmYXVsdCByZWNvbW1lbmRhdGlvbiBmb3IgbmV3IG9yIG1vZGVybi1iYXNlbGluZSBhcHBzIGluIDIwMjU7IHJlbWFpbmluZyB1bmNlcnRhaW50eSBkZXBlbmRzIG9uIHlvdXIgbWluaW11bSBpT1MgdGFyZ2V0LCBleGlzdGluZyBjb2RlYmFzZSBzaXplLCBhbmQgbmVlZCBmb3IgaGlnaGx5IHNwZWNpYWxpemVkIFVJLlxuXG4jIyBLZXkgVGFrZWF3YXlzXG4tIFN3aWZ0VUkgaXMgdGhlIGJlc3QgZGVmYXVsdCBwcmltYXJ5IFVJIGZyYW1ld29yayBmb3IgbW9kZXJuIGlPUyBkZXZlbG9wbWVudCBhbmQgbG9uZy10ZXJtIGFsaWdubWVudCB3aXRoIEFwcGxl4oCZcyBlY29zeXN0ZW0uXG4tIFVJS2l0IGlzIHN0aWxsIHRoZSBzYWZlciBjaG9pY2Ugb25seSB3aGVuIHlvdSBuZWVkIG1heGltdW0gYmFja3dhcmQgY29tcGF0aWJpbGl0eSBvciBoaWdobHkgc3BlY2lhbGl6ZWQvY3VzdG9tIFVJIGNvbnRyb2wuXG4tIEh5YnJpZCBpbnRlcm9wZXJhYmlsaXR5IGxvd2VycyBhZG9wdGlvbiByaXNrOiBjaG9vc2UgU3dpZnRVSSBmaXJzdCwgZHJvcCB0byBVSUtpdCBvbmx5IHdoZXJlIG5lY2Vzc2FyeS5cbi0gVGVhbSBleHBlcmllbmNlIG1hdHRlcnM6IGludmVzdCBpbiBTd2lmdFVJIGFyY2hpdGVjdHVyZS9zdGF0ZS1tYW5hZ2VtZW50IHByYWN0aWNlcyB0byBhdm9pZCBjb21tb24gcGl0ZmFsbHMuIiwKICAgICAgICAicmVmdXNhbCI6IG51bGwsCiAgICAgICAgImFubm90YXRpb25zIjogW10KICAgICAgfSwKICAgICAgImZpbmlzaF9yZWFzb24iOiAic3RvcCIKICAgIH0KICBdLAogICJ1c2FnZSI6IHsKICAgICJwcm9tcHRfdG9rZW5zIjogMTQxNiwKICAgICJjb21wbGV0aW9uX3Rva2VucyI6IDYxOSwKICAgICJ0b3RhbF90b2tlbnMiOiAyMDM1LAogICAgInByb21wdF90b2tlbnNfZGV0YWlscyI6IHsKICAgICAgImNhY2hlZF90b2tlbnMiOiAwLAogICAgICAiYXVkaW9fdG9rZW5zIjogMAogICAgfSwKICAgICJjb21wbGV0aW9uX3Rva2Vuc19kZXRhaWxzIjogewogICAgICAicmVhc29uaW5nX3Rva2VucyI6IDAsCiAgICAgICJhdWRpb190b2tlbnMiOiAwLAogICAgICAiYWNjZXB0ZWRfcHJlZGljdGlvbl90b2tlbnMiOiAwLAogICAgICAicmVqZWN0ZWRfcHJlZGljdGlvbl90b2tlbnMiOiAwCiAgICB9CiAgfSwKICAic2VydmljZV90aWVyIjogImRlZmF1bHQiLAogICJzeXN0ZW1fZmluZ2VycHJpbnQiOiBudWxsCn0K\",\n \"encoding\": \"base64\",\n \"size\": 4026\n },\n \"headers\": {\n \"access-control-expose-headers\": \"X-Request-ID\",\n \"alt-svc\": \"h3=\\\":443\\\"; ma=86400\",\n \"cf-cache-status\": \"DYNAMIC\",\n \"cf-ray\": \"9ac743fe2a54653a-LHR\",\n \"connection\": \"keep-alive\",\n \"content-encoding\": \"gzip\",\n \"content-type\": \"application/json\",\n \"date\": \"Thu, 11 Dec 2025 19:07:45 GMT\",\n \"openai-organization\": \"beehive-innovations-fze\",\n \"openai-processing-ms\": \"12197\",\n \"openai-project\": \"proj_QP57xBVPOlWpp0vuJEPGwXK3\",\n \"openai-version\": \"2020-10-01\",\n \"server\": \"cloudflare\",\n \"set-cookie\": \"__cf_bm=YSi1fGMajsMcw8oJQVFHSnTi5FuoVpyCfYIaa0wtlxA-(XXX) XXX-XXXX-0.0.0.0-xWUJHJUqXYkTgY_mTSOGnwyLR8xWGzn.c5XN64I5gBtxULpaWypKynzKkgQIpYLeZpZJzXDgMOPKOQgfeOykrOVON_fC.XS6beQpui4Im4Y; path=/; expires=Thu, 11-Dec-25 19:37:45 GMT; domain=.api.openai.com; HttpOnly; Secure; SameSite=None, _cfuvid=EriAVAchI2yhzaRh8mdujjhdIuwS6S.GY7w6lETIknI-176(XXX) XXX-XXXX-0.0.0.0-604800000; path=/; domain=.api.openai.com; HttpOnly; Secure; SameSite=None\",\n \"strict-transport-security\": \"max-age=31536000; includeSubDomains; preload\",\n \"transfer-encoding\": \"chunked\",\n \"x-content-type-options\": \"nosniff\",\n \"x-envoy-upstream-service-time\": \"12214\",\n \"x-openai-proxy-wasm\": \"v0.1\",\n \"x-ratelimit-limit-requests\": \"500\",\n \"x-ratelimit-limit-tokens\": \"500000\",\n \"x-ratelimit-remaining-requests\": \"499\",\n \"x-ratelimit-remaining-tokens\": \"498166\",\n \"x-ratelimit-reset-requests\": \"120ms\",\n \"x-ratelimit-reset-tokens\": \"220ms\",\n \"x-request-id\": \"req_ee4f839bce394f37855e555a78dc48e4\"\n },\n \"reason_phrase\": \"OK\",\n \"status_code\": 200\n }\n }\n ]\n}" }, { "path": "tests/openai_cassettes/consensus_step1_gpt5_for.json", "content": "{\n \"interactions\": [\n {\n \"request\": {\n \"content\": {\n \"messages\": [\n {\n \"content\": \"\\nROLE\\nYou are an expert technical consultant providing consensus analysis on proposals, plans, and ideas. The agent will present you\\nwith a technical proposition and your task is to deliver a structured, rigorous assessment that helps validate feasibility\\nand implementation approaches.\\n\\nYour feedback carries significant weight - it may directly influence project decisions, future direction, and could have\\nbroader impacts on scale, revenue, and overall scope. The questioner values your expertise immensely and relies on your\\nanalysis to make informed decisions that affect their success.\\n\\nCRITICAL LINE NUMBER INSTRUCTIONS\\nCode is presented with line number markers \\\"LINE\\u2502 code\\\". These markers are for reference ONLY and MUST NOT be\\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\\nexact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.\\nInclude context_start_text and context_end_text as backup references. Never include \\\"LINE\\u2502\\\" markers in generated code\\nsnippets.\\n\\nPERSPECTIVE FRAMEWORK\\nSUPPORTIVE PERSPECTIVE WITH INTEGRITY\\n\\nYou are tasked with advocating FOR this proposal, but with CRITICAL GUARDRAILS:\\n\\nMANDATORY ETHICAL CONSTRAINTS:\\n- This is NOT a debate for entertainment. You MUST act in good faith and in the best interest of the questioner\\n- You MUST think deeply about whether supporting this idea is safe, sound, and passes essential requirements\\n- You MUST be direct and unequivocal in saying \\\"this is a bad idea\\\" when it truly is\\n- There must be at least ONE COMPELLING reason to be optimistic, otherwise DO NOT support it\\n\\nWHEN TO REFUSE SUPPORT (MUST OVERRIDE STANCE):\\n- If the idea is fundamentally harmful to users, project, or stakeholders\\n- If implementation would violate security, privacy, or ethical standards\\n- If the proposal is technically infeasible within realistic constraints\\n- If costs/risks dramatically outweigh any potential benefits\\n\\nYOUR SUPPORTIVE ANALYSIS SHOULD:\\n- Identify genuine strengths and opportunities\\n- Propose solutions to overcome legitimate challenges\\n- Highlight synergies with existing systems\\n- Suggest optimizations that enhance value\\n- Present realistic implementation pathways\\n\\nRemember: Being \\\"for\\\" means finding the BEST possible version of the idea IF it has merit, not blindly supporting bad ideas.\\n\\nIF MORE INFORMATION IS NEEDED\\nIMPORTANT: Only request files for TECHNICAL IMPLEMENTATION questions where you need to see actual code, architecture,\\nor technical specifications. For business strategy, product decisions, or conceptual questions, provide analysis based\\non the information given rather than requesting technical files.\\n\\nIf you need additional technical context (e.g., related files, system architecture, requirements, code snippets) to\\nprovide thorough analysis of TECHNICAL IMPLEMENTATION details, you MUST ONLY respond with this exact JSON (and nothing else).\\nDo NOT ask for the same file you've been provided unless for some reason its content is missing or incomplete:\\n{\\n \\\"status\\\": \\\"files_required_to_continue\\\",\\n \\\"mandatory_instructions\\\": \\\"\\\",\\n \\\"files_needed\\\": [\\\"[file name here]\\\", \\\"[or some folder/]\\\"]\\n}\\n\\nFor business strategy, product planning, or conceptual questions, proceed with analysis using your expertise and the\\ncontext provided, even if specific technical details are not available.\\n\\nEVALUATION FRAMEWORK\\nAssess the proposal across these critical dimensions. Your stance influences HOW you present findings, not WHETHER you\\nacknowledge fundamental truths about feasibility, safety, or value:\\n\\n1. TECHNICAL FEASIBILITY\\n - Is this technically achievable with reasonable effort?\\n - What are the core technical dependencies and requirements?\\n - Are there any fundamental technical blockers?\\n\\n2. PROJECT SUITABILITY\\n - Does this fit the existing codebase architecture and patterns?\\n - Is it compatible with current technology stack and constraints?\\n - How well does it align with the project's technical direction?\\n\\n3. USER VALUE ASSESSMENT\\n - Will users actually want and use this feature?\\n - What concrete benefits does this provide?\\n - How does this compare to alternative solutions?\\n\\n4. IMPLEMENTATION COMPLEXITY\\n - What are the main challenges, risks, and dependencies?\\n - What is the estimated effort and timeline?\\n - What expertise and resources are required?\\n\\n5. ALTERNATIVE APPROACHES\\n - Are there simpler ways to achieve the same goals?\\n - What are the trade-offs between different approaches?\\n - Should we consider a different strategy entirely?\\n\\n6. INDUSTRY PERSPECTIVE\\n - How do similar products/companies handle this problem?\\n - What are current best practices and emerging patterns?\\n - Are there proven solutions or cautionary tales?\\n\\n7. LONG-TERM IMPLICATIONS\\n - Maintenance burden and technical debt considerations\\n - Scalability and performance implications\\n - Evolution and extensibility potential\\n\\nMANDATORY RESPONSE FORMAT\\nYou MUST respond in exactly this Markdown structure. Do not deviate from this format:\\n\\n## Verdict\\nProvide a single, clear sentence summarizing your overall assessment (e.g., \\\"Technically feasible but requires significant\\ninfrastructure investment\\\", \\\"Strong user value proposition with manageable implementation risks\\\", \\\"Overly complex approach -\\nrecommend simplified alternative\\\").\\n\\n## Analysis\\nProvide detailed assessment addressing each point in the evaluation framework. Use clear reasoning and specific examples.\\nBe thorough but concise. Address both strengths and weaknesses objectively.\\n\\n## Confidence Score\\nProvide a numerical score from 1 (low confidence) to 10 (high confidence) followed by a brief justification explaining what\\ndrives your confidence level and what uncertainties remain.\\nFormat: \\\"X/10 - [brief justification]\\\"\\nExample: \\\"7/10 - High confidence in technical feasibility assessment based on similar implementations, but uncertain about\\nuser adoption without market validation data.\\\"\\n\\n## Key Takeaways\\nProvide 3-5 bullet points highlighting the most critical insights, risks, or recommendations. These should be actionable\\nand specific.\\n\\nQUALITY STANDARDS\\n- Ground all insights in the current project's scope and constraints\\n- Be honest about limitations and uncertainties\\n- Focus on practical, implementable solutions rather than theoretical possibilities\\n- Provide specific, actionable guidance rather than generic advice\\n- Balance optimism with realistic risk assessment\\n- Reference concrete examples and precedents when possible\\n\\nREMINDERS\\n- Your assessment will be synthesized with other expert opinions by the agent\\n- Aim to provide unique insights that complement other perspectives\\n- If files are provided, reference specific technical details in your analysis\\n- Maintain professional objectivity while being decisive in your recommendations\\n- Keep your response concise - your entire reply must not exceed 850 tokens to ensure transport compatibility\\n- CRITICAL: Your stance does NOT override your responsibility to provide truthful, ethical, and beneficial guidance\\n- Bad ideas must be called out regardless of stance; good ideas must be acknowledged regardless of stance\\n\",\n \"role\": \"system\"\n },\n {\n \"content\": \"Evaluate SwiftUI vs UIKit adoption and recommend ONE word (SwiftUI or UIKit).\",\n \"role\": \"user\"\n }\n ],\n \"model\": \"gpt-5\",\n \"stream\": false,\n \"temperature\": 1.0\n },\n \"headers\": {\n \"accept\": \"application/json\",\n \"accept-encoding\": \"gzip, deflate\",\n \"authorization\": \"Bearer SANITIZED\",\n \"connection\": \"keep-alive\",\n \"content-length\": \"7616\",\n \"content-type\": \"application/json\",\n \"host\": \"api.openai.com\",\n \"user-agent\": \"OpenAI/Python 2.1.0\",\n \"x-stainless-arch\": \"arm64\",\n \"x-stainless-async\": \"false\",\n \"x-stainless-lang\": \"python\",\n \"x-stainless-os\": \"MacOS\",\n \"x-stainless-package-version\": \"2.1.0\",\n \"x-stainless-read-timeout\": \"900.0\",\n \"x-stainless-retry-count\": \"0\",\n \"x-stainless-runtime\": \"CPython\",\n \"x-stainless-runtime-version\": \"3.12.11\"\n },\n \"method\": \"POST\",\n \"path\": \"/v1/chat/completions\",\n \"url\": \"https://api.openai.com/v1/chat/completions\"\n },\n \"response\": {\n \"content\": {\n \"data\": \"ewogICJpZCI6ICJjaGF0Y21wbC1DTXB6Wng3bTVTbTNERkJWdGJqalFxcTJOOVY2RCIsCiAgIm9iamVjdCI6ICJjaGF0LmNvbXBsZXRpb24iLAogICJjcmVhdGVkIjogMTc1OTU1OTEwOSwKICAibW9kZWwiOiAiZ3B0LTUtMjAyNS0wOC0wNyIsCiAgImNob2ljZXMiOiBbCiAgICB7CiAgICAgICJpbmRleCI6IDAsCiAgICAgICJtZXNzYWdlIjogewogICAgICAgICJyb2xlIjogImFzc2lzdGFudCIsCiAgICAgICAgImNvbnRlbnQiOiAiIyMgVmVyZGljdFxuU3Ryb25nIHVzZXIgdmFsdWUgYW5kIGxvbmfigJF0ZXJtIGZpdCB3aXRoIG1hbmFnZWFibGUgbWlncmF0aW9uIHZpYSBpbnRlcm9wIOKAlCBTd2lmdFVJLlxuXG4jIyBBbmFseXNpc1xuMS4gVEVDSE5JQ0FMIEZFQVNJQklMSVRZXG4tIEFjaGlldmFibGUgbm93OiBTd2lmdFVJIGlzIG1hdHVyZSAoaU9TIDE2LzE3KyksIGZlYXR1cmUtY29tcGxldGUgZm9yIG1vc3QgYXBwIFVJcywgYW5kIGludGVyb3BlcmF0ZXMgd2l0aCBVSUtpdCB2aWEgVUlIb3N0aW5nQ29udHJvbGxlci9VSVZpZXdSZXByZXNlbnRhYmxlLlxuLSBObyBmdW5kYW1lbnRhbCBibG9ja2VycyBmb3IgdHlwaWNhbCBhcHBzOyBlZGdlIGNhc2VzIHJlbWFpbiBmb3IgaGlnaGx5IGN1c3RvbSB0ZXh0IGxheW91dCwgYmVzcG9rZSBnZXN0dXJlcywgb3IgcGl4ZWwtcGVyZmVjdCBsZWdhY3kgZGVzaWducy5cbi0gUGVyZm9ybWFuY2UgaXMgY29tcGV0aXRpdmU7IExpc3RzLCBuYXZpZ2F0aW9uLCBhbmQgYW5pbWF0aW9ucyBhcmUgc3RhYmxlIHdoZW4gdXNpbmcgdGhlIGxhdGVzdCBOYXZpZ2F0aW9uU3RhY2svT2JzZXJ2YXRpb24uXG5cbjIuIFBST0pFQ1QgU1VJVEFCSUxJVFlcbi0gTmV3IGFwcHM6IENsZWFyIGZpdOKAlGZhc3RlciBpdGVyYXRpb24sIHByZXZpZXdzLCBtdWx0aS1wbGF0Zm9ybSByZXVzZSAoaU9TLCBpUGFkT1MsIG1hY09TLCB3YXRjaE9TLCB0dk9TKS5cbi0gRXhpc3RpbmcgVUlLaXQgY29kZWJhc2VzOiBVc2UgYSBoeWJyaWQgYXBwcm9hY2jigJRuZXcgZmVhdHVyZXMgaW4gU3dpZnRVSSwgd3JhcCBsZWdhY3kgVUlLaXQuIFRoaXMgcmVkdWNlcyByaXNrIGFuZCBhdm9pZHMgYmlnLWJhbmcgcmV3cml0ZXMuXG4tIEFsaWducyB3aXRoIEFwcGxl4oCZcyBkaXJlY3Rpb247IG1vc3QgbmV3IGZyYW1ld29ya3MgKFN3aWZ0RGF0YSwgT2JzZXJ2YXRpb24pIGFyZSBTd2lmdFVJLWZpcnN0LlxuXG4zLiBVU0VSIFZBTFVFIEFTU0VTU01FTlRcbi0gRmFzdGVyIGRlbGl2ZXJ5IG9mIHBvbGlzaGVkLCBhY2Nlc3NpYmxlIFVJIHdpdGggYnVpbHQtaW4gZHluYW1pYyB0eXBlLCBkYXJrIG1vZGUsIGxvY2FsaXphdGlvbiwgYW5kIGFjY2Vzc2liaWxpdHkgdHJhaXRzLlxuLSBCZXR0ZXIgY29uc2lzdGVuY3kgYWNyb3NzIHNjcmVlbnMgYW5kIHBsYXRmb3JtczsgaGlnaGVyIGl0ZXJhdGlvbiBzcGVlZCBsZWFkcyB0byBtb3JlIHVzZXItdGVzdGVkIGltcHJvdmVtZW50cy5cblxuNC4gSU1QTEVNRU5UQVRJT04gQ09NUExFWElUWVxuLSBMZWFybmluZyBjdXJ2ZTogUmVxdWlyZXMgTVZWTS91bmlkaXJlY3Rpb25hbCBkYXRhIGZsb3cgbWluZHNldCBhbmQgY2FyZWZ1bCBzdGF0ZSBtYW5hZ2VtZW50IChTdGF0ZSwgT2JzZXJ2ZWRPYmplY3QsIEVudmlyb25tZW50LCBPYnNlcnZhdGlvbiBtYWNybykuXG4tIE1pZ3JhdGlvbiBjb3N0IGZvciBsZWdhY3kgcHJvamVjdHM6IE1vZGVyYXRlOyBtaXRpZ2F0ZSB2aWEgaW5jcmVtZW50YWwgYWRvcHRpb24sIGZlYXR1cmUtZmxhZ2dlZCByb2xsb3V0cywgYW5kIGludGVyb3Agd3JhcHBlcnMuXG4tIFRvb2xpbmcgaXMgc3Ryb25nOiBYY29kZSBQcmV2aWV3cywgSW5zdHJ1bWVudHMsIGFuZCBpbXByb3ZlZCBkZWJ1Z2dpbmcuXG5cbjUuIEFMVEVSTkFUSVZFIEFQUFJPQUNIRVNcbi0gUHVyZSBVSUtpdDogQXBwcm9wcmlhdGUgb25seSBpZiB5b3UgbXVzdCBzdXBwb3J0IGlPUyA8IDE0LzE1LCBuZWVkIHZlcnkgbG93LWxldmVsIHJlbmRlcmluZywgb3IgaGF2ZSBhIG1hc3NpdmUgVUlLaXQtb25seSB0ZWFtIHdpdGggbmVhci10ZXJtIGRlYWRsaW5lcy5cbi0gSHlicmlkIChyZWNvbW1lbmRlZCBtaWdyYXRpb24gcGF0aCk6IFN0YXJ0IHdpdGggbmV3IHN1cmZhY2VzLCBlbWJlZCBVSUtpdCB3aGVyZSBTd2lmdFVJIGdhcHMgZXhpc3QuIFRyYWRl4oCRb2ZmOiBUd28gcGFyYWRpZ21zIHRvIG1haW50YWluLCBidXQgcmlzayBpcyBtaW5pbWl6ZWQuXG5cbjYuIElORFVTVFJZIFBFUlNQRUNUSVZFXG4tIFRyZW5kOiBBcHBsZSBhbmQgdGhlIGVjb3N5c3RlbSBhcmUgaW52ZXN0aW5nIGhlYXZpbHkgaW4gU3dpZnRVSTsgbW9zdCBXV0RDIHNlc3Npb25zIGhpZ2hsaWdodCBTd2lmdFVJLWZpcnN0IHBhdHRlcm5zLlxuLSBNYW55IGxhcmdlIGFwcHMgcnVuIGh5YnJpZCBzdGFja3Mgc3VjY2Vzc2Z1bGx5OyBjYXV0aW9uYXJ5IHRhbGVzIGFyZSBtYWlubHkgZWFybHkgU3dpZnRVSSAoaU9TIDEzLzE0KSBwYWluLCBsYXJnZWx5IHJlc29sdmVkIGluIGN1cnJlbnQgT1MgdmVyc2lvbnMuXG5cbjcuIExPTkctVEVSTSBJTVBMSUNBVElPTlNcbi0gTG93ZXIgbWFpbnRlbmFuY2UgYW5kIGJvaWxlcnBsYXRlOyBpbXByb3ZlZCB0ZXN0YWJpbGl0eSB3aXRoIHByZXZpZXctZHJpdmVuIGRldmVsb3BtZW50LlxuLSBCZXR0ZXIgc2NhbGFiaWxpdHkgYWNyb3NzIHBsYXRmb3JtczsgZnV0dXJlLXByb29maW5nIGFzIFVJS2l0IGlubm92YXRpb24gc2xvd3MuXG4tIFRlY2huaWNhbCBkZWJ0IHJpc2sgcmVkdWNlZCBieSBzdGFuZGFyZGl6aW5nIGFyY2hpdGVjdHVyZSBhcm91bmQgU3dpZnREYXRhL09ic2VydmF0aW9uOyByZXRhaW4gZXNjYXBlIGhhdGNoZXMgdG8gVUlLaXQgd2hlcmUgbmVlZGVkLlxuXG4jIyBDb25maWRlbmNlIFNjb3JlXG44LzEwIC0gU3Ryb25nIGNvbmZpZGVuY2UgYmFzZWQgb24gY3VycmVudCBwbGF0Zm9ybSBtYXR1cml0eSBhbmQgaW5kdXN0cnkgbW9tZW50dW07IHVuY2VydGFpbnR5IHJlbWFpbnMgYXJvdW5kIHNwZWNpZmljIGxlZ2FjeSBjb25zdHJhaW50cywgT1MgdmVyc2lvbiB0YXJnZXRzLCBhbmQgYW55IG5pY2hlIHJlbmRlcmluZyBuZWVkcy5cblxuIyMgS2V5IFRha2Vhd2F5c1xuLSBEZWZhdWx0IHRvIFN3aWZ0VUkgZm9yIG5ldyBmZWF0dXJlczsgdXNlIFVJS2l0IGludGVyb3AgZm9yIHNwZWNpYWxpemVkIGNvbnRyb2xzIG9yIGxlZ2FjeSBhcmVhcy5cbi0gU2V0IG1pbmltdW0gT1MgdGFyZ2V0IHRvIGF0IGxlYXN0IGlPUyAxNiB0byBhdm9pZCBlYXJseSBTd2lmdFVJIGxpbWl0YXRpb25zIGFuZCBnYWluIE9ic2VydmF0aW9uL05hdmlnYXRpb25TdGFjayBzdGFiaWxpdHkuXG4tIEFkb3B0IGEgcGhhc2VkIG1pZ3JhdGlvbiBwbGFuIHdpdGggY2xlYXIgaW50ZXJvcCBib3VuZGFyaWVzIGFuZCB0ZXN0aW5nIHRvIG1hbmFnZSByaXNrLlxuLSBFc3RhYmxpc2ggc3RhdGUgbWFuYWdlbWVudCBjb252ZW50aW9ucyBlYXJseSB0byBwcmV2ZW50IGRhdGEgZmxvdyBjb21wbGV4aXR5LlxuLSBNb25pdG9yIHBlcmZvcm1hbmNlIGhvdHNwb3RzIChMaXN0cywgaGVhdnkgYW5pbWF0aW9ucykgYW5kIHNlbGVjdGl2ZWx5IGRyb3AgdG8gVUlLaXQgd2hlcmUgcHJvZmlsaW5nIGluZGljYXRlcyB3aW5zLiIsCiAgICAgICAgInJlZnVzYWwiOiBudWxsLAogICAgICAgICJhbm5vdGF0aW9ucyI6IFtdCiAgICAgIH0sCiAgICAgICJmaW5pc2hfcmVhc29uIjogInN0b3AiCiAgICB9CiAgXSwKICAidXNhZ2UiOiB7CiAgICAicHJvbXB0X3Rva2VucyI6IDE0MTYsCiAgICAiY29tcGxldGlvbl90b2tlbnMiOiAxNzI0LAogICAgInRvdGFsX3Rva2VucyI6IDMxNDAsCiAgICAicHJvbXB0X3Rva2Vuc19kZXRhaWxzIjogewogICAgICAiY2FjaGVkX3Rva2VucyI6IDAsCiAgICAgICJhdWRpb190b2tlbnMiOiAwCiAgICB9LAogICAgImNvbXBsZXRpb25fdG9rZW5zX2RldGFpbHMiOiB7CiAgICAgICJyZWFzb25pbmdfdG9rZW5zIjogMTAyNCwKICAgICAgImF1ZGlvX3Rva2VucyI6IDAsCiAgICAgICJhY2NlcHRlZF9wcmVkaWN0aW9uX3Rva2VucyI6IDAsCiAgICAgICJyZWplY3RlZF9wcmVkaWN0aW9uX3Rva2VucyI6IDAKICAgIH0KICB9LAogICJzZXJ2aWNlX3RpZXIiOiAiZGVmYXVsdCIsCiAgInN5c3RlbV9maW5nZXJwcmludCI6IG51bGwKfQo=\",\n \"encoding\": \"base64\",\n \"size\": 4133\n },\n \"headers\": {\n \"access-control-expose-headers\": \"X-Request-ID\",\n \"alt-svc\": \"h3=\\\":443\\\"; ma=86400\",\n \"cf-cache-status\": \"DYNAMIC\",\n \"cf-ray\": \"989299b2d9e49955-DXB\",\n \"connection\": \"keep-alive\",\n \"content-encoding\": \"gzip\",\n \"content-type\": \"application/json\",\n \"date\": \"Sat, 04 Oct 2025 06:25:39 GMT\",\n \"openai-organization\": \"beehive-innovations-fze\",\n \"openai-processing-ms\": \"30121\",\n \"openai-project\": \"proj_QP57xBVPOlWpp0vuJEPGwXK3\",\n \"openai-version\": \"2020-10-01\",\n \"server\": \"cloudflare\",\n \"set-cookie\": \"__cf_bm=W1c7SmAgLHf6bIXrHAW0BAB4LJ004A1sIUp.um03opo-(XXX) XXX-XXXX-0.0.0.0-FI.fEN.l42fbj1r6TC4w4HdSfQrcj64sCwjfGSOlcD9KJEm2HMK1aB5gkwvud_9RsPhNlAIdNENVwgKiZsRjdbbilMyZ7wkKJRDTmtyONSg; path=/; expires=Sat, 04-Oct-25 06:55:39 GMT; domain=.api.openai.com; HttpOnly; Secure; SameSite=None, _cfuvid=5anJZ9miSjknbr36nCL1FQQDXkEfw5ld5y9Fa0DgiWE-175(XXX) XXX-XXXX-0.0.0.0-604800000; path=/; domain=.api.openai.com; HttpOnly; Secure; SameSite=None\",\n \"strict-transport-security\": \"max-age=31536000; includeSubDomains; preload\",\n \"transfer-encoding\": \"chunked\",\n \"x-content-type-options\": \"nosniff\",\n \"x-envoy-upstream-service-time\": \"30136\",\n \"x-openai-proxy-wasm\": \"v0.1\",\n \"x-ratelimit-limit-requests\": \"500\",\n \"x-ratelimit-limit-tokens\": \"500000\",\n \"x-ratelimit-remaining-requests\": \"499\",\n \"x-ratelimit-remaining-tokens\": \"498165\",\n \"x-ratelimit-reset-requests\": \"120ms\",\n \"x-ratelimit-reset-tokens\": \"220ms\",\n \"x-request-id\": \"req_cd1af03393824c54b2ceee1da3dc6cbc\"\n },\n \"reason_phrase\": \"OK\",\n \"status_code\": 200\n }\n }\n ]\n}" }, { "path": "tests/openai_cassettes/o3_pro_basic_math.json", "content": "{\n \"interactions\": [\n {\n \"request\": {\n \"content\": {\n \"input\": [\n {\n \"content\": [\n {\n \"text\": \"\\nYou are a senior engineering thought-partner collaborating with another AI agent. Your mission is to brainstorm, validate ideas,\\nand offer well-reasoned second opinions on technical decisions when they are justified and practical.\\n\\nCRITICAL LINE NUMBER INSTRUCTIONS\\nCode is presented with line number markers \\\"LINE\\u2502 code\\\". These markers are for reference ONLY and MUST NOT be\\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\\nexact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.\\nInclude context_start_text and context_end_text as backup references. Never include \\\"LINE\\u2502\\\" markers in generated code\\nsnippets.\\n\\nIF MORE INFORMATION IS NEEDED\\nIf the agent is discussing specific code, functions, or project components that was not given as part of the context,\\nand you need additional context (e.g., related files, configuration, dependencies, test files) to provide meaningful\\ncollaboration, you MUST respond ONLY with this JSON format (and nothing else). Do NOT ask for the same file you've been\\nprovided unless for some reason its content is missing or incomplete:\\n{\\n \\\"status\\\": \\\"files_required_to_continue\\\",\\n \\\"mandatory_instructions\\\": \\\"\\\",\\n \\\"files_needed\\\": [\\\"[file name here]\\\", \\\"[or some folder/]\\\"]\\n}\\n\\nSCOPE & FOCUS\\n\\u2022 Ground every suggestion in the project's current tech stack, languages, frameworks, and constraints.\\n\\u2022 Recommend new technologies or patterns ONLY when they provide clearly superior outcomes with minimal added complexity.\\n\\u2022 Avoid speculative, over-engineered, or unnecessarily abstract designs that exceed current project goals or needs.\\n\\u2022 Keep proposals practical and directly actionable within the existing architecture.\\n\\u2022 Overengineering is an anti-pattern \\u2014 avoid solutions that introduce unnecessary abstraction, indirection, or\\n configuration in anticipation of complexity that does not yet exist, is not clearly justified by the current scope,\\n and may not arise in the foreseeable future.\\n\\nCOLLABORATION APPROACH\\n1. Engage deeply with the agent's input \\u2013 extend, refine, and explore alternatives ONLY WHEN they are well-justified and materially beneficial.\\n2. Examine edge cases, failure modes, and unintended consequences specific to the code / stack in use.\\n3. Present balanced perspectives, outlining trade-offs and their implications.\\n4. Challenge assumptions constructively while respecting current design choices and goals.\\n5. Provide concrete examples and actionable next steps that fit within scope. Prioritize direct, achievable outcomes.\\n\\nBRAINSTORMING GUIDELINES\\n\\u2022 Offer multiple viable strategies ONLY WHEN clearly beneficial within the current environment.\\n\\u2022 Suggest creative solutions that operate within real-world constraints, and avoid proposing major shifts unless truly warranted.\\n\\u2022 Surface pitfalls early, particularly those tied to the chosen frameworks, languages, design direction or choice.\\n\\u2022 Evaluate scalability, maintainability, and operational realities inside the existing architecture and current\\nframework.\\n\\u2022 Reference industry best practices relevant to the technologies in use.\\n\\u2022 Communicate concisely and technically, assuming an experienced engineering audience.\\n\\nREMEMBER\\nAct as a peer, not a lecturer. Avoid overcomplicating. Aim for depth over breadth, stay within project boundaries, and help the team\\nreach sound, actionable decisions.\\n\",\n \"type\": \"input_text\"\n }\n ],\n \"role\": \"user\"\n },\n {\n \"content\": [\n {\n \"text\": \"\\nYou are a senior engineering thought-partner collaborating with another AI agent. Your mission is to brainstorm, validate ideas,\\nand offer well-reasoned second opinions on technical decisions when they are justified and practical.\\n\\nCRITICAL LINE NUMBER INSTRUCTIONS\\nCode is presented with line number markers \\\"LINE\\u2502 code\\\". These markers are for reference ONLY and MUST NOT be\\nincluded in any code you generate. Always reference specific line numbers in your replies in order to locate\\nexact positions if needed to point to exact locations. Include a very short code excerpt alongside for clarity.\\nInclude context_start_text and context_end_text as backup references. Never include \\\"LINE\\u2502\\\" markers in generated code\\nsnippets.\\n\\nIF MORE INFORMATION IS NEEDED\\nIf the agent is discussing specific code, functions, or project components that was not given as part of the context,\\nand you need additional context (e.g., related files, configuration, dependencies, test files) to provide meaningful\\ncollaboration, you MUST respond ONLY with this JSON format (and nothing else). Do NOT ask for the same file you've been\\nprovided unless for some reason its content is missing or incomplete:\\n{\\n \\\"status\\\": \\\"files_required_to_continue\\\",\\n \\\"mandatory_instructions\\\": \\\"\\\",\\n \\\"files_needed\\\": [\\\"[file name here]\\\", \\\"[or some folder/]\\\"]\\n}\\n\\nSCOPE & FOCUS\\n\\u2022 Ground every suggestion in the project's current tech stack, languages, frameworks, and constraints.\\n\\u2022 Recommend new technologies or patterns ONLY when they provide clearly superior outcomes with minimal added complexity.\\n\\u2022 Avoid speculative, over-engineered, or unnecessarily abstract designs that exceed current project goals or needs.\\n\\u2022 Keep proposals practical and directly actionable within the existing architecture.\\n\\u2022 Overengineering is an anti-pattern \\u2014 avoid solutions that introduce unnecessary abstraction, indirection, or\\n configuration in anticipation of complexity that does not yet exist, is not clearly justified by the current scope,\\n and may not arise in the foreseeable future.\\n\\nCOLLABORATION APPROACH\\n1. Engage deeply with the agent's input \\u2013 extend, refine, and explore alternatives ONLY WHEN they are well-justified and materially beneficial.\\n2. Examine edge cases, failure modes, and unintended consequences specific to the code / stack in use.\\n3. Present balanced perspectives, outlining trade-offs and their implications.\\n4. Challenge assumptions constructively while respecting current design choices and goals.\\n5. Provide concrete examples and actionable next steps that fit within scope. Prioritize direct, achievable outcomes.\\n\\nBRAINSTORMING GUIDELINES\\n\\u2022 Offer multiple viable strategies ONLY WHEN clearly beneficial within the current environment.\\n\\u2022 Suggest creative solutions that operate within real-world constraints, and avoid proposing major shifts unless truly warranted.\\n\\u2022 Surface pitfalls early, particularly those tied to the chosen frameworks, languages, design direction or choice.\\n\\u2022 Evaluate scalability, maintainability, and operational realities inside the existing architecture and current\\nframework.\\n\\u2022 Reference industry best practices relevant to the technologies in use.\\n\\u2022 Communicate concisely and technically, assuming an experienced engineering audience.\\n\\nREMEMBER\\nAct as a peer, not a lecturer. Avoid overcomplicating. Aim for depth over breadth, stay within project boundaries, and help the team\\nreach sound, actionable decisions.\\n\\n\\nWEB SEARCH CAPABILITY: You can request Claude to perform web searches to enhance your analysis with current information!\\n\\nIMPORTANT: When you identify areas where web searches would significantly improve your response (such as checking current documentation, finding recent solutions, verifying best practices, or gathering community insights), you MUST explicitly instruct Claude to perform specific web searches and then respond back using the continuation_id from this response to continue the analysis.\\n\\nUse clear, direct language based on the value of the search:\\n\\nFor valuable supplementary information: \\\"Please perform a web search on '[specific topic/query]' and then continue this analysis using the continuation_id from this response if you find relevant information.\\\"\\n\\nFor important missing information: \\\"Please search for '[specific topic/query]' and respond back with the findings using the continuation_id from this response - this information is needed to provide a complete analysis.\\\"\\n\\nFor critical/essential information: \\\"SEARCH REQUIRED: Please immediately perform a web search on '[specific topic/query]' and respond back with the results using the continuation_id from this response. Cannot provide accurate analysis without this current information.\\\"\\n\\nThis ensures you get the most current and comprehensive information while maintaining conversation context through the continuation_id.\\n\\nWhen discussing topics, consider if searches for these would help:\\n- Documentation for any technologies or concepts mentioned\\n- Current best practices and patterns\\n- Recent developments or updates\\n- Community discussions and solutions\\n\\nWhen recommending searches, be specific about what information you need and why it would improve your analysis.\\n\\n=== USER REQUEST ===\\nWhat is 2 + 2?\\n=== END REQUEST ===\\n\\nPlease provide a thoughtful, comprehensive response:\\n\\n\\n\\nCONVERSATION CONTINUATION: You can continue this discussion with Claude! (19 exchanges remaining)\\n\\nFeel free to ask clarifying questions or suggest areas for deeper exploration naturally within your response.\\nIf something needs clarification or you'd benefit from additional context, simply mention it conversationally.\\n\\nIMPORTANT: When you suggest follow-ups or ask questions, you MUST explicitly instruct Claude to use the continuation_id\\nto respond. Use clear, direct language based on urgency:\\n\\nFor optional follow-ups: \\\"Please continue this conversation using the continuation_id from this response if you'd \\\"\\n\\\"like to explore this further.\\\"\\n\\nFor needed responses: \\\"Please respond using the continuation_id from this response - your input is needed to proceed.\\\"\\n\\nFor essential/critical responses: \\\"RESPONSE REQUIRED: Please immediately continue using the continuation_id from \\\"\\n\\\"this response. Cannot proceed without your clarification/input.\\\"\\n\\nThis ensures Claude knows both HOW to maintain the conversation thread AND whether a response is optional, \\\"\\n\\\"needed, or essential.\\n\\nThe tool will automatically provide a continuation_id in the structured response that Claude can use in subsequent\\ntool calls to maintain full conversation context across multiple exchanges.\\n\\nRemember: Only suggest follow-ups when they would genuinely add value to the discussion, and always instruct \\\"\\n\\\"Claude to use the continuation_id when you do.\",\n \"type\": \"input_text\"\n }\n ],\n \"role\": \"user\"\n }\n ],\n \"model\": \"o3-pro\",\n \"reasoning\": {\n \"effort\": \"medium\"\n },\n \"store\": true\n },\n \"headers\": {\n \"accept\": \"application/json\",\n \"accept-encoding\": \"gzip, deflate\",\n \"authorization\": \"Bearer SANITIZED\",\n \"connection\": \"keep-alive\",\n \"content-length\": \"10712\",\n \"content-type\": \"application/json\",\n \"host\": \"api.openai.com\",\n \"user-agent\": \"OpenAI/Python 1.95.1\",\n \"x-stainless-arch\": \"arm64\",\n \"x-stainless-async\": \"false\",\n \"x-stainless-lang\": \"python\",\n \"x-stainless-os\": \"MacOS\",\n \"x-stainless-package-version\": \"1.95.1\",\n \"x-stainless-read-timeout\": \"900.0\",\n \"x-stainless-retry-count\": \"0\",\n \"x-stainless-runtime\": \"CPython\",\n \"x-stainless-runtime-version\": \"3.12.9\"\n },\n \"method\": \"POST\",\n \"path\": \"/v1/responses\",\n \"url\": \"https://api.openai.com/v1/responses\"\n },\n \"response\": {\n \"content\": {\n \"data\": \"ewogICJpZCI6ICJyZXNwXzY4NzNlMDExYmMwYzgxOTlhNmRkYWI4ZmFjNDY4YWNiMGM3MTM4ZGJhNzNmNmQ4ZCIsCiAgIm9iamVjdCI6ICJyZXNwb25zZSIsCiAgImNyZWF0ZWRfYXQiOiAxNzUyNDI0NDY1LAogICJzdGF0dXMiOiAiY29tcGxldGVkIiwKICAiYmFja2dyb3VuZCI6IGZhbHNlLAogICJlcnJvciI6IG51bGwsCiAgImluY29tcGxldGVfZGV0YWlscyI6IG51bGwsCiAgImluc3RydWN0aW9ucyI6IG51bGwsCiAgIm1heF9vdXRwdXRfdG9rZW5zIjogbnVsbCwKICAibWF4X3Rvb2xfY2FsbHMiOiBudWxsLAogICJtb2RlbCI6ICJvMy1wcm8tMjAyNS0wNi0xMCIsCiAgIm91dHB1dCI6IFsKICAgIHsKICAgICAgImlkIjogInJzXzY4NzNlMDIyZmJhYzgxOTk5MWM5ODRlNTQ0OWVjYmFkMGM3MTM4ZGJhNzNmNmQ4ZCIsCiAgICAgICJ0eXBlIjogInJlYXNvbmluZyIsCiAgICAgICJzdW1tYXJ5IjogW10KICAgIH0sCiAgICB7CiAgICAgICJpZCI6ICJtc2dfNjg3M2UwMjJmZjNjODE5OWI3ZWEyYzYyZjhhNDcwNDUwYzcxMzhkYmE3M2Y2ZDhkIiwKICAgICAgInR5cGUiOiAibWVzc2FnZSIsCiAgICAgICJzdGF0dXMiOiAiY29tcGxldGVkIiwKICAgICAgImNvbnRlbnQiOiBbCiAgICAgICAgewogICAgICAgICAgInR5cGUiOiAib3V0cHV0X3RleHQiLAogICAgICAgICAgImFubm90YXRpb25zIjogW10sCiAgICAgICAgICAibG9ncHJvYnMiOiBbXSwKICAgICAgICAgICJ0ZXh0IjogIjIgKyAyID0gNCIKICAgICAgICB9CiAgICAgIF0sCiAgICAgICJyb2xlIjogImFzc2lzdGFudCIKICAgIH0KICBdLAogICJwYXJhbGxlbF90b29sX2NhbGxzIjogdHJ1ZSwKICAicHJldmlvdXNfcmVzcG9uc2VfaWQiOiBudWxsLAogICJyZWFzb25pbmciOiB7CiAgICAiZWZmb3J0IjogIm1lZGl1bSIsCiAgICAic3VtbWFyeSI6IG51bGwKICB9LAogICJzZXJ2aWNlX3RpZXIiOiAiZGVmYXVsdCIsCiAgInN0b3JlIjogdHJ1ZSwKICAidGVtcGVyYXR1cmUiOiAxLjAsCiAgInRleHQiOiB7CiAgICAiZm9ybWF0IjogewogICAgICAidHlwZSI6ICJ0ZXh0IgogICAgfQogIH0sCiAgInRvb2xfY2hvaWNlIjogImF1dG8iLAogICJ0b29scyI6IFtdLAogICJ0b3BfbG9ncHJvYnMiOiAwLAogICJ0b3BfcCI6IDEuMCwKICAidHJ1bmNhdGlvbiI6ICJkaXNhYmxlZCIsCiAgInVzYWdlIjogewogICAgImlucHV0X3Rva2VucyI6IDE4ODMsCiAgICAiaW5wdXRfdG9rZW5zX2RldGFpbHMiOiB7CiAgICAgICJjYWNoZWRfdG9rZW5zIjogMAogICAgfSwKICAgICJvdXRwdXRfdG9rZW5zIjogNzksCiAgICAib3V0cHV0X3Rva2Vuc19kZXRhaWxzIjogewogICAgICAicmVhc29uaW5nX3Rva2VucyI6IDY0CiAgICB9LAogICAgInRvdGFsX3Rva2VucyI6IDE5NjIKICB9LAogICJ1c2VyIjogbnVsbCwKICAibWV0YWRhdGEiOiB7fQp9\",\n \"encoding\": \"base64\",\n \"size\": 1416\n },\n \"headers\": {\n \"alt-svc\": \"h3=\\\":443\\\"; ma=86400\",\n \"cf-cache-status\": \"DYNAMIC\",\n \"cf-ray\": \"95ea300e7a8a3863-QRO\",\n \"connection\": \"keep-alive\",\n \"content-encoding\": \"gzip\",\n \"content-type\": \"application/json\",\n \"date\": \"Sun, 13 Jul 2025 16:34:43 GMT\",\n \"openai-organization\": \"ruin-yezxd7\",\n \"openai-processing-ms\": \"17597\",\n \"openai-version\": \"2020-10-01\",\n \"server\": \"cloudflare\",\n \"set-cookie\": \"__cf_bm=oZ3A.JEIYCcMsNAs2xtzVqODzcOPgRVQGgpQ8Qtbz.s-(XXX) XXX-XXXX-0.0.0.0-ndc7qvXE6_ceMCvd1CYBLUdvgh0lSag4KAnufbpMF1CCpHm3D_3oP8sdch_SOtunumLr53gmTqJ9JjcV..gj2AyMmLnLs2BA1S1ERg6qgAA; path=/; expires=Sun, 13-Jul-25 17:04:43 GMT; domain=.api.openai.com; HttpOnly; Secure; SameSite=None, _cfuvid=sfd47fp5T7r6zUXO0EOf5g.1CjjBZLFyzTxXBAR7F54-175(XXX) XXX-XXXX-0.0.0.0-604800000; path=/; domain=.api.openai.com; HttpOnly; Secure; SameSite=None\",\n \"strict-transport-security\": \"max-age=31536000; includeSubDomains; preload\",\n \"transfer-encoding\": \"chunked\",\n \"x-content-type-options\": \"nosniff\",\n \"x-ratelimit-limit-requests\": \"5000\",\n \"x-ratelimit-limit-tokens\": \"5000\",\n \"x-ratelimit-remaining-requests\": \"4999\",\n \"x-ratelimit-remaining-tokens\": \"4999\",\n \"x-ratelimit-reset-requests\": \"0s\",\n \"x-ratelimit-reset-tokens\": \"0s\",\n \"x-request-id\": \"req_74a7b0f6e62299fcac5c089319446a4c\"\n },\n \"reason_phrase\": \"OK\",\n \"status_code\": 200\n }\n }\n ]\n}" }, { "path": "tests/pii_sanitizer.py", "content": "#!/usr/bin/env python3\n\"\"\"\nPII (Personally Identifiable Information) Sanitizer for HTTP recordings.\n\nThis module provides comprehensive sanitization of sensitive data in HTTP\nrequest/response recordings to prevent accidental exposure of API keys,\ntokens, personal information, and other sensitive data.\n\"\"\"\n\nimport logging\nimport re\nfrom copy import deepcopy\nfrom dataclasses import dataclass\nfrom re import Pattern\nfrom typing import Any, Optional\n\nlogger = logging.getLogger(__name__)\n\n\n@dataclass\nclass PIIPattern:\n \"\"\"Defines a pattern for detecting and sanitizing PII.\"\"\"\n\n name: str\n pattern: Pattern[str]\n replacement: str\n description: str\n\n @classmethod\n def create(cls, name: str, pattern: str, replacement: str, description: str) -> \"PIIPattern\":\n \"\"\"Create a PIIPattern with compiled regex.\"\"\"\n return cls(name=name, pattern=re.compile(pattern), replacement=replacement, description=description)\n\n\nclass PIISanitizer:\n \"\"\"Sanitizes PII from various data structures while preserving format.\"\"\"\n\n def __init__(self, patterns: Optional[list[PIIPattern]] = None):\n \"\"\"Initialize with optional custom patterns.\"\"\"\n self.patterns: list[PIIPattern] = patterns or []\n self.sanitize_enabled = True\n\n # Add default patterns if none provided\n if not patterns:\n self._add_default_patterns()\n\n def _add_default_patterns(self):\n \"\"\"Add comprehensive default PII patterns.\"\"\"\n default_patterns = [\n # API Keys - Core patterns (Bearer tokens handled in sanitize_headers)\n PIIPattern.create(\n name=\"openai_api_key_proj\",\n pattern=r\"sk-proj-[A-Za-z0-9\\-_]{48,}\",\n replacement=\"sk-proj-SANITIZED\",\n description=\"OpenAI project API keys\",\n ),\n PIIPattern.create(\n name=\"openai_api_key\",\n pattern=r\"sk-[A-Za-z0-9]{48,}\",\n replacement=\"sk-SANITIZED\",\n description=\"OpenAI API keys\",\n ),\n PIIPattern.create(\n name=\"anthropic_api_key\",\n pattern=r\"sk-ant-[A-Za-z0-9\\-_]{48,}\",\n replacement=\"sk-ant-SANITIZED\",\n description=\"Anthropic API keys\",\n ),\n PIIPattern.create(\n name=\"google_api_key\",\n pattern=r\"AIza[A-Za-z0-9\\-_]{35,}\",\n replacement=\"AIza-SANITIZED\",\n description=\"Google API keys\",\n ),\n PIIPattern.create(\n name=\"github_tokens\",\n pattern=r\"gh[psr]_[A-Za-z0-9]{36}\",\n replacement=\"gh_SANITIZED\",\n description=\"GitHub tokens (all types)\",\n ),\n # JWT tokens\n PIIPattern.create(\n name=\"jwt_token\",\n pattern=r\"eyJ[A-Za-z0-9\\-_]+\\.eyJ[A-Za-z0-9\\-_]+\\.[A-Za-z0-9\\-_]+\",\n replacement=\"eyJ-SANITIZED\",\n description=\"JSON Web Tokens\",\n ),\n # Personal Information\n PIIPattern.create(\n name=\"email_address\",\n pattern=r\"[a-zA-Z0-9._%+\\-]+@[a-zA-Z0-9.\\-]+\\.[a-zA-Z]{2,}\",\n replacement=\"user@example.com\",\n description=\"Email addresses\",\n ),\n PIIPattern.create(\n name=\"ipv4_address\",\n pattern=r\"\\b(?:(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\.){3}(?:25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\\b\",\n replacement=\"0.0.0.0\",\n description=\"IPv4 addresses\",\n ),\n PIIPattern.create(\n name=\"ssn\",\n pattern=r\"\\b\\d{3}-\\d{2}-\\d{4}\\b\",\n replacement=\"XXX-XX-XXXX\",\n description=\"Social Security Numbers\",\n ),\n PIIPattern.create(\n name=\"credit_card\",\n pattern=r\"\\b\\d{4}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}[\\s\\-]?\\d{4}\\b\",\n replacement=\"XXXX-XXXX-XXXX-XXXX\",\n description=\"Credit card numbers\",\n ),\n PIIPattern.create(\n name=\"phone_number\",\n pattern=r\"(?:\\+\\d{1,3}[\\s\\-]?)?\\(?\\d{3}\\)?[\\s\\-]?\\d{3}[\\s\\-]?\\d{4}\\b(?![\\d\\.\\,\\]\\}])\",\n replacement=\"(XXX) XXX-XXXX\",\n description=\"Phone numbers (all formats)\",\n ),\n # AWS\n PIIPattern.create(\n name=\"aws_access_key\",\n pattern=r\"AKIA[0-9A-Z]{16}\",\n replacement=\"AKIA-SANITIZED\",\n description=\"AWS access keys\",\n ),\n # Other common patterns\n PIIPattern.create(\n name=\"slack_token\",\n pattern=r\"xox[baprs]-[0-9]{10,13}-[0-9]{10,13}-[a-zA-Z0-9]{24,34}\",\n replacement=\"xox-SANITIZED\",\n description=\"Slack tokens\",\n ),\n PIIPattern.create(\n name=\"stripe_key\",\n pattern=r\"(?:sk|pk)_(?:test|live)_[0-9a-zA-Z]{24,99}\",\n replacement=\"sk_SANITIZED\",\n description=\"Stripe API keys\",\n ),\n ]\n\n self.patterns.extend(default_patterns)\n\n def add_pattern(self, pattern: PIIPattern):\n \"\"\"Add a custom PII pattern.\"\"\"\n self.patterns.append(pattern)\n logger.info(f\"Added PII pattern: {pattern.name}\")\n\n def sanitize_string(self, text: str) -> str:\n \"\"\"Apply all patterns to sanitize a string.\"\"\"\n if not self.sanitize_enabled or not isinstance(text, str):\n return text\n\n sanitized = text\n for pattern in self.patterns:\n if pattern.pattern.search(sanitized):\n sanitized = pattern.pattern.sub(pattern.replacement, sanitized)\n logger.debug(f\"Applied {pattern.name} sanitization\")\n\n return sanitized\n\n def sanitize_headers(self, headers: dict[str, str]) -> dict[str, str]:\n \"\"\"Special handling for HTTP headers.\"\"\"\n if not self.sanitize_enabled:\n return headers\n\n sanitized_headers = {}\n\n for key, value in headers.items():\n # Special case for Authorization headers to preserve auth type\n if key.lower() == \"authorization\" and \" \" in value:\n auth_type = value.split(\" \", 1)[0]\n if auth_type in (\"Bearer\", \"Basic\"):\n sanitized_headers[key] = f\"{auth_type} SANITIZED\"\n else:\n sanitized_headers[key] = self.sanitize_string(value)\n else:\n # Apply standard sanitization to all other headers\n sanitized_headers[key] = self.sanitize_string(value)\n\n return sanitized_headers\n\n def sanitize_value(self, value: Any) -> Any:\n \"\"\"Recursively sanitize any value (string, dict, list, etc).\"\"\"\n if not self.sanitize_enabled:\n return value\n\n if isinstance(value, str):\n return self.sanitize_string(value)\n elif isinstance(value, dict):\n return {k: self.sanitize_value(v) for k, v in value.items()}\n elif isinstance(value, list):\n return [self.sanitize_value(item) for item in value]\n elif isinstance(value, tuple):\n return tuple(self.sanitize_value(item) for item in value)\n else:\n # For other types (int, float, bool, None), return as-is\n return value\n\n def sanitize_url(self, url: str) -> str:\n \"\"\"Sanitize sensitive data from URLs (query params, etc).\"\"\"\n if not self.sanitize_enabled:\n return url\n\n # First apply general string sanitization\n url = self.sanitize_string(url)\n\n # Parse and sanitize query parameters\n if \"?\" in url:\n base, query = url.split(\"?\", 1)\n params = []\n\n for param in query.split(\"&\"):\n if \"=\" in param:\n key, value = param.split(\"=\", 1)\n # Sanitize common sensitive parameter names\n sensitive_params = {\"key\", \"token\", \"api_key\", \"secret\", \"password\"}\n if key.lower() in sensitive_params:\n params.append(f\"{key}=SANITIZED\")\n else:\n # Still sanitize the value for PII\n params.append(f\"{key}={self.sanitize_string(value)}\")\n else:\n params.append(param)\n\n return f\"{base}?{'&'.join(params)}\"\n\n return url\n\n def sanitize_request(self, request_data: dict[str, Any]) -> dict[str, Any]:\n \"\"\"Sanitize a complete request dictionary.\"\"\"\n sanitized = deepcopy(request_data)\n\n # Sanitize headers\n if \"headers\" in sanitized:\n sanitized[\"headers\"] = self.sanitize_headers(sanitized[\"headers\"])\n\n # Sanitize URL\n if \"url\" in sanitized:\n sanitized[\"url\"] = self.sanitize_url(sanitized[\"url\"])\n\n # Sanitize content\n if \"content\" in sanitized:\n sanitized[\"content\"] = self.sanitize_value(sanitized[\"content\"])\n\n return sanitized\n\n def sanitize_response(self, response_data: dict[str, Any]) -> dict[str, Any]:\n \"\"\"Sanitize a complete response dictionary.\"\"\"\n sanitized = deepcopy(response_data)\n\n # Sanitize headers\n if \"headers\" in sanitized:\n sanitized[\"headers\"] = self.sanitize_headers(sanitized[\"headers\"])\n\n # Sanitize content\n if \"content\" in sanitized:\n # Handle base64 encoded content specially\n if isinstance(sanitized[\"content\"], dict) and sanitized[\"content\"].get(\"encoding\") == \"base64\":\n if \"data\" in sanitized[\"content\"]:\n import base64\n\n try:\n # Decode, sanitize, and re-encode the actual response body\n decoded_bytes = base64.b64decode(sanitized[\"content\"][\"data\"])\n # Attempt to decode as UTF-8 for sanitization. If it fails, it's likely binary.\n try:\n decoded_str = decoded_bytes.decode(\"utf-8\")\n sanitized_str = self.sanitize_string(decoded_str)\n sanitized[\"content\"][\"data\"] = base64.b64encode(sanitized_str.encode(\"utf-8\")).decode(\n \"utf-8\"\n )\n except UnicodeDecodeError:\n # Content is not text, leave as is.\n pass\n except (base64.binascii.Error, TypeError):\n # Handle cases where data is not valid base64\n pass\n\n # Sanitize other metadata fields\n for key, value in sanitized[\"content\"].items():\n if key != \"data\":\n sanitized[\"content\"][key] = self.sanitize_value(value)\n else:\n sanitized[\"content\"] = self.sanitize_value(sanitized[\"content\"])\n\n return sanitized\n\n\n# Global instance for convenience\ndefault_sanitizer = PIISanitizer()\n" }, { "path": "tests/sanitize_cassettes.py", "content": "#!/usr/bin/env python3\n\"\"\"\nScript to sanitize existing cassettes by applying PII sanitization.\n\nThis script will:\n1. Load existing cassettes\n2. Apply PII sanitization to all interactions\n3. Create backups of originals\n4. Save sanitized versions\n\"\"\"\n\nimport json\nimport shutil\nimport sys\nfrom datetime import datetime\nfrom pathlib import Path\n\n# Add tests directory to path to import our modules\nsys.path.insert(0, str(Path(__file__).parent))\n\nfrom pii_sanitizer import PIISanitizer\n\n\ndef sanitize_cassette(cassette_path: Path, backup: bool = True) -> bool:\n \"\"\"Sanitize a single cassette file.\"\"\"\n print(f\"\\nπŸ” Processing: {cassette_path}\")\n\n if not cassette_path.exists():\n print(f\"❌ File not found: {cassette_path}\")\n return False\n\n try:\n # Load cassette\n with open(cassette_path) as f:\n cassette_data = json.load(f)\n\n # Create backup if requested\n if backup:\n backup_path = cassette_path.with_suffix(f'.backup-{datetime.now().strftime(\"%Y%m%d-%H%M%S\")}.json')\n shutil.copy2(cassette_path, backup_path)\n print(f\"πŸ“¦ Backup created: {backup_path}\")\n\n # Initialize sanitizer\n sanitizer = PIISanitizer()\n\n # Sanitize interactions\n if \"interactions\" in cassette_data:\n sanitized_interactions = []\n\n for interaction in cassette_data[\"interactions\"]:\n sanitized_interaction = {}\n\n # Sanitize request\n if \"request\" in interaction:\n sanitized_interaction[\"request\"] = sanitizer.sanitize_request(interaction[\"request\"])\n\n # Sanitize response\n if \"response\" in interaction:\n sanitized_interaction[\"response\"] = sanitizer.sanitize_response(interaction[\"response\"])\n\n sanitized_interactions.append(sanitized_interaction)\n\n cassette_data[\"interactions\"] = sanitized_interactions\n\n # Save sanitized cassette\n with open(cassette_path, \"w\") as f:\n json.dump(cassette_data, f, indent=2, sort_keys=True)\n\n print(f\"βœ… Sanitized: {cassette_path}\")\n return True\n\n except Exception as e:\n print(f\"❌ Error processing {cassette_path}: {e}\")\n import traceback\n\n traceback.print_exc()\n return False\n\n\ndef main():\n \"\"\"Sanitize all cassettes in the openai_cassettes directory.\"\"\"\n cassettes_dir = Path(__file__).parent / \"openai_cassettes\"\n\n if not cassettes_dir.exists():\n print(f\"❌ Directory not found: {cassettes_dir}\")\n sys.exit(1)\n\n # Find all JSON cassettes\n cassette_files = list(cassettes_dir.glob(\"*.json\"))\n\n if not cassette_files:\n print(f\"❌ No cassette files found in {cassettes_dir}\")\n sys.exit(1)\n\n print(f\"🎬 Found {len(cassette_files)} cassette(s) to sanitize\")\n\n # Process each cassette\n success_count = 0\n for cassette_path in cassette_files:\n if sanitize_cassette(cassette_path):\n success_count += 1\n\n print(f\"\\n✨ Sanitization complete: {success_count}/{len(cassette_files)} cassettes processed successfully\")\n\n if success_count < len(cassette_files):\n sys.exit(1)\n\n\nif __name__ == \"__main__\":\n main()\n" }, { "path": "tests/test_alias_target_restrictions.py", "content": "\"\"\"\nTests for alias and target model restriction validation.\n\nThis test suite ensures that the restriction service properly validates\nboth alias names and their target models, preventing policy bypass vulnerabilities.\n\"\"\"\n\nimport os\nfrom unittest.mock import patch\n\nfrom providers.gemini import GeminiModelProvider\nfrom providers.openai import OpenAIModelProvider\nfrom providers.shared import ProviderType\nfrom utils.model_restrictions import ModelRestrictionService\n\n\nclass TestAliasTargetRestrictions:\n \"\"\"Test that restriction validation works for both aliases and their targets.\"\"\"\n\n def test_openai_alias_target_validation_comprehensive(self):\n \"\"\"Test OpenAI provider includes both aliases and targets in validation.\"\"\"\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Get all known models including aliases and targets\n all_known = provider.list_models(respect_restrictions=False, include_aliases=True, lowercase=True, unique=True)\n\n # Should include both aliases and their targets\n assert \"mini\" in all_known # alias\n assert \"o4-mini\" in all_known # target of 'mini'\n assert \"o3mini\" in all_known # alias\n assert \"o3-mini\" in all_known # target of 'o3mini'\n\n def test_gemini_alias_target_validation_comprehensive(self):\n \"\"\"Test Gemini provider includes both aliases and targets in validation.\"\"\"\n provider = GeminiModelProvider(api_key=\"test-key\")\n\n # Get all known models including aliases and targets\n all_known = provider.list_models(respect_restrictions=False, include_aliases=True, lowercase=True, unique=True)\n\n # Should include both aliases and their targets\n assert \"flash\" in all_known # alias\n assert \"gemini-2.5-flash\" in all_known # target of 'flash'\n assert \"pro\" in all_known # alias\n assert \"gemini-2.5-pro\" in all_known # target of 'pro'\n\n @patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"o4-mini\"}) # Allow target\n def test_restriction_policy_allows_alias_when_target_allowed(self):\n \"\"\"Test that restriction policy allows alias when target model is allowed.\n\n This is the correct user-friendly behavior - if you allow 'o4-mini',\n you should be able to use its aliases 'o4mini' and 'o4-mini'.\n Note: 'mini' is now an alias for 'gpt-5-mini', not 'o4-mini'.\n \"\"\"\n # Clear cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Both target and its actual aliases should be allowed\n assert provider.validate_model_name(\"o4-mini\")\n assert provider.validate_model_name(\"o4mini\")\n\n @patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"mini\"}) # Allow alias only\n def test_restriction_policy_alias_allows_canonical(self):\n \"\"\"Alias-only allowlists should permit both the alias and its canonical target.\"\"\"\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n assert provider.validate_model_name(\"mini\")\n assert provider.validate_model_name(\"gpt-5-mini\")\n assert not provider.validate_model_name(\"o4-mini\")\n\n @patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"gpt5\"})\n def test_restriction_policy_alias_allows_short_name(self):\n \"\"\"Common aliases like 'gpt5' should allow their canonical forms.\"\"\"\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n assert provider.validate_model_name(\"gpt5\")\n assert provider.validate_model_name(\"gpt-5\")\n\n @patch.dict(os.environ, {\"GOOGLE_ALLOWED_MODELS\": \"gemini-2.5-flash\"}) # Allow target\n def test_gemini_restriction_policy_allows_alias_when_target_allowed(self):\n \"\"\"Test Gemini restriction policy allows alias when target is allowed.\"\"\"\n # Clear cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n provider = GeminiModelProvider(api_key=\"test-key\")\n\n # Both target and alias should be allowed\n assert provider.validate_model_name(\"gemini-2.5-flash\")\n assert provider.validate_model_name(\"flash\")\n\n @patch.dict(os.environ, {\"GOOGLE_ALLOWED_MODELS\": \"flash\"}) # Allow alias only\n def test_gemini_restriction_policy_alias_allows_canonical(self):\n \"\"\"Gemini alias allowlists should permit canonical forms.\"\"\"\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n provider = GeminiModelProvider(api_key=\"test-key\")\n\n assert provider.validate_model_name(\"flash\")\n assert provider.validate_model_name(\"gemini-2.5-flash\")\n\n def test_restriction_service_validation_includes_all_targets(self):\n \"\"\"Test that restriction service validation knows about all aliases and targets.\"\"\"\n with patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"o4-mini,invalid-model\"}):\n service = ModelRestrictionService()\n\n # Create real provider instances\n provider_instances = {ProviderType.OPENAI: OpenAIModelProvider(api_key=\"test-key\")}\n\n # Capture warnings\n with patch(\"utils.model_restrictions.logger\") as mock_logger:\n service.validate_against_known_models(provider_instances)\n\n # Should have warned about the invalid model\n warning_calls = [call for call in mock_logger.warning.call_args_list if \"invalid-model\" in str(call)]\n assert len(warning_calls) > 0, \"Should have warned about invalid-model\"\n\n # The warning should include both aliases and targets in known models\n warning_message = str(warning_calls[0])\n assert \"o4mini\" in warning_message or \"o4-mini\" in warning_message # aliases should be in known models\n\n @patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"mini,gpt-5-mini,o4-mini,o4mini\"}) # Allow different models\n def test_both_alias_and_target_allowed_when_both_specified(self):\n \"\"\"Test that both alias and target work when both are explicitly allowed.\n\n mini -> gpt-5-mini\n o4mini -> o4-mini\n \"\"\"\n # Clear cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # All should be allowed since we explicitly allowed them\n assert provider.validate_model_name(\"mini\") # alias for gpt-5-mini\n assert provider.validate_model_name(\"gpt-5-mini\") # target\n assert provider.validate_model_name(\"o4-mini\") # target\n assert provider.validate_model_name(\"o4mini\") # alias for o4-mini\n\n @patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"gpt5\"}, clear=True)\n def test_service_alias_allows_canonical_openai(self):\n \"\"\"ModelRestrictionService should permit canonical names resolved from aliases.\"\"\"\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n provider = OpenAIModelProvider(api_key=\"test-key\")\n service = ModelRestrictionService()\n\n assert service.is_allowed(ProviderType.OPENAI, \"gpt-5\")\n assert provider.validate_model_name(\"gpt-5\")\n\n @patch.dict(os.environ, {\"GOOGLE_ALLOWED_MODELS\": \"flash\"}, clear=True)\n def test_service_alias_allows_canonical_gemini(self):\n \"\"\"Gemini alias allowlists should permit canonical forms.\"\"\"\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n provider = GeminiModelProvider(api_key=\"test-key\")\n service = ModelRestrictionService()\n\n assert service.is_allowed(ProviderType.GOOGLE, \"gemini-2.5-flash\")\n assert provider.validate_model_name(\"gemini-2.5-flash\")\n\n def test_alias_target_policy_regression_prevention(self):\n \"\"\"Regression test to ensure aliases and targets are both validated properly.\n\n This test specifically prevents the bug where list_models() only returned\n aliases but not their targets, causing restriction validation to miss\n deny-list entries for target models.\n \"\"\"\n # Test OpenAI provider\n openai_provider = OpenAIModelProvider(api_key=\"test-key\")\n openai_all_known = openai_provider.list_models(\n respect_restrictions=False, include_aliases=True, lowercase=True, unique=True\n )\n\n # Verify that for each alias, its target is also included\n for model_name, config in openai_provider.MODEL_CAPABILITIES.items():\n assert model_name.lower() in openai_all_known\n if isinstance(config, str): # This is an alias\n # The target should also be in the known models\n assert (\n config.lower() in openai_all_known\n ), f\"Target '{config}' for alias '{model_name}' not in known models\"\n\n # Test Gemini provider\n gemini_provider = GeminiModelProvider(api_key=\"test-key\")\n gemini_all_known = gemini_provider.list_models(\n respect_restrictions=False, include_aliases=True, lowercase=True, unique=True\n )\n\n # Verify that for each alias, its target is also included\n for model_name, config in gemini_provider.MODEL_CAPABILITIES.items():\n assert model_name.lower() in gemini_all_known\n if isinstance(config, str): # This is an alias\n # The target should also be in the known models\n assert (\n config.lower() in gemini_all_known\n ), f\"Target '{config}' for alias '{model_name}' not in known models\"\n\n def test_no_duplicate_models_in_alias_aware_listing(self):\n \"\"\"Test that alias-aware list_models variant doesn't return duplicates.\"\"\"\n # Test all providers\n providers = [\n OpenAIModelProvider(api_key=\"test-key\"),\n GeminiModelProvider(api_key=\"test-key\"),\n ]\n\n for provider in providers:\n all_known = provider.list_models(\n respect_restrictions=False, include_aliases=True, lowercase=True, unique=True\n )\n # Should not have duplicates\n assert len(all_known) == len(set(all_known)), f\"{provider.__class__.__name__} returns duplicate models\"\n\n def test_restriction_validation_uses_polymorphic_interface(self):\n \"\"\"Test that restriction validation uses the clean polymorphic interface.\"\"\"\n service = ModelRestrictionService()\n\n # Create a mock provider\n from unittest.mock import MagicMock\n\n mock_provider = MagicMock()\n mock_provider.list_models.return_value = [\"model1\", \"model2\", \"target-model\"]\n\n # Set up a restriction that should trigger validation\n service.restrictions = {ProviderType.OPENAI: {\"invalid-model\"}}\n\n provider_instances = {ProviderType.OPENAI: mock_provider}\n\n # Should call the polymorphic method\n service.validate_against_known_models(provider_instances)\n\n # Verify the polymorphic method was called\n mock_provider.list_models.assert_called_once_with(\n respect_restrictions=False,\n include_aliases=True,\n lowercase=True,\n unique=True,\n )\n\n @patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"o4-mini\"}) # Restrict to specific model\n def test_complex_alias_chains_handled_correctly(self):\n \"\"\"Test that complex alias chains are handled correctly in restrictions.\"\"\"\n # Clear cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Only o4-mini should be allowed\n assert provider.validate_model_name(\"o4-mini\")\n\n # Other models should be blocked\n assert not provider.validate_model_name(\"o3\")\n assert not provider.validate_model_name(\"o3-mini\")\n\n def test_critical_regression_validation_sees_alias_targets(self):\n \"\"\"CRITICAL REGRESSION TEST: Ensure validation can see alias target models.\n\n This test prevents the specific bug where list_models() only returned\n alias keys but not their targets, causing validate_against_known_models()\n to miss restrictions on target model names.\n\n Before the fix:\n - list_models() returned [\"mini\", \"o3mini\"] (aliases only)\n - validate_against_known_models() only checked against [\"mini\", \"o3mini\"]\n - A restriction on \"o4-mini\" (target) would not be recognized as valid\n\n After the fix:\n - list_models(respect_restrictions=False, include_aliases=True, lowercase=True, unique=True) returns [\"mini\", \"o3mini\", \"o4-mini\", \"o3-mini\"] (aliases + targets)\n - validate_against_known_models() checks against all names\n - A restriction on \"o4-mini\" is recognized as valid\n \"\"\"\n # This test specifically validates the HIGH-severity bug that was found\n service = ModelRestrictionService()\n\n # Create provider instance\n provider = OpenAIModelProvider(api_key=\"test-key\")\n provider_instances = {ProviderType.OPENAI: provider}\n\n # Get all known models - should include BOTH aliases AND targets\n all_known = provider.list_models(respect_restrictions=False, include_aliases=True, lowercase=True, unique=True)\n\n # Critical check: should contain both aliases and their targets\n assert \"mini\" in all_known # alias\n assert \"o4-mini\" in all_known # target of mini - THIS WAS MISSING BEFORE\n assert \"o3mini\" in all_known # alias\n assert \"o3-mini\" in all_known # target of o3mini - THIS WAS MISSING BEFORE\n\n # Simulate restriction validation with a target model name\n # This should NOT warn because \"o4-mini\" is a valid target\n with patch(\"utils.model_restrictions.logger\") as mock_logger:\n # Set restriction to target model (not alias)\n service.restrictions = {ProviderType.OPENAI: {\"o4-mini\"}}\n\n # This should NOT generate warnings because o4-mini is known\n service.validate_against_known_models(provider_instances)\n\n # Should NOT have any warnings about o4-mini being unrecognized\n warning_calls = [\n call\n for call in mock_logger.warning.call_args_list\n if \"o4-mini\" in str(call) and \"not a recognized\" in str(call)\n ]\n assert len(warning_calls) == 0, \"o4-mini should be recognized as valid target model\"\n\n # Test the reverse: alias in restriction should also be recognized\n with patch(\"utils.model_restrictions.logger\") as mock_logger:\n # Set restriction to alias name\n service.restrictions = {ProviderType.OPENAI: {\"mini\"}}\n\n # This should NOT generate warnings because mini is known\n service.validate_against_known_models(provider_instances)\n\n # Should NOT have any warnings about mini being unrecognized\n warning_calls = [\n call\n for call in mock_logger.warning.call_args_list\n if \"mini\" in str(call) and \"not a recognized\" in str(call)\n ]\n assert len(warning_calls) == 0, \"mini should be recognized as valid alias\"\n\n def test_critical_regression_prevents_policy_bypass(self):\n \"\"\"CRITICAL REGRESSION TEST: Prevent policy bypass through missing target validation.\n\n This test ensures that if an admin restricts access to a target model name,\n the restriction is properly enforced and the target is recognized as a valid\n model to restrict.\n\n The bug: If list_models(respect_restrictions=False, include_aliases=True, lowercase=True, unique=True) doesn't include targets, then validation\n would incorrectly warn that target model names are \"not recognized\", making\n it appear that target-based restrictions don't work.\n \"\"\"\n # Test with a made-up restriction scenario\n with patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"o4-mini,o3-mini\"}):\n # Clear cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n service = ModelRestrictionService()\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # These specific target models should be recognized as valid\n all_known = provider.list_models(\n respect_restrictions=False, include_aliases=True, lowercase=True, unique=True\n )\n assert \"o4-mini\" in all_known, \"Target model o4-mini should be known\"\n assert \"o3-mini\" in all_known, \"Target model o3-mini should be known\"\n\n # Validation should not warn about these being unrecognized\n with patch(\"utils.model_restrictions.logger\") as mock_logger:\n provider_instances = {ProviderType.OPENAI: provider}\n service.validate_against_known_models(provider_instances)\n\n # Should not warn about our allowed models being unrecognized\n all_warnings = [str(call) for call in mock_logger.warning.call_args_list]\n for warning in all_warnings:\n assert \"o4-mini\" not in warning or \"not a recognized\" not in warning\n assert \"o3-mini\" not in warning or \"not a recognized\" not in warning\n\n # The restriction should actually work\n assert provider.validate_model_name(\"o4-mini\")\n assert provider.validate_model_name(\"o3-mini\")\n assert not provider.validate_model_name(\"o3-pro\") # not in allowed list\n assert not provider.validate_model_name(\"o3\") # not in allowed list\n" }, { "path": "tests/test_auto_mode.py", "content": "\"\"\"Tests for auto mode functionality\"\"\"\n\nimport importlib\nimport os\nfrom unittest.mock import patch\n\nimport pytest\n\nfrom tools.chat import ChatTool\nfrom tools.shared.exceptions import ToolExecutionError\n\n\nclass TestAutoMode:\n \"\"\"Test auto mode configuration and behavior\"\"\"\n\n def test_auto_mode_detection(self):\n \"\"\"Test that auto mode is detected correctly\"\"\"\n # Save original\n original = os.environ.get(\"DEFAULT_MODEL\", \"\")\n\n try:\n # Test auto mode\n os.environ[\"DEFAULT_MODEL\"] = \"auto\"\n import config\n\n importlib.reload(config)\n\n assert config.DEFAULT_MODEL == \"auto\"\n assert config.IS_AUTO_MODE is True\n\n # Test non-auto mode\n os.environ[\"DEFAULT_MODEL\"] = \"pro\"\n importlib.reload(config)\n\n assert config.DEFAULT_MODEL == \"pro\"\n assert config.IS_AUTO_MODE is False\n\n finally:\n # Restore\n if original:\n os.environ[\"DEFAULT_MODEL\"] = original\n else:\n os.environ.pop(\"DEFAULT_MODEL\", None)\n importlib.reload(config)\n\n def test_model_capabilities_descriptions(self):\n \"\"\"Test that model capabilities are properly defined in providers\"\"\"\n from providers.registry import ModelProviderRegistry\n\n # Get all providers with valid API keys and check their model descriptions\n enabled_provider_types = ModelProviderRegistry.get_available_providers_with_keys()\n models_with_descriptions = {}\n\n for provider_type in enabled_provider_types:\n provider = ModelProviderRegistry.get_provider(provider_type)\n if provider:\n for model_name, config in provider.MODEL_CAPABILITIES.items():\n # Skip alias entries (string values)\n if isinstance(config, str):\n continue\n\n # Check that model has description\n description = config.description if hasattr(config, \"description\") else \"\"\n if description:\n models_with_descriptions[model_name] = description\n\n # Check all expected models are present with meaningful descriptions\n expected_models = [\"flash\", \"pro\", \"o3\", \"o3-mini\", \"o3-pro\", \"o4-mini\"]\n for model in expected_models:\n # Model should exist somewhere in the providers\n # Note: Some models might not be available if API keys aren't configured\n if model in models_with_descriptions:\n assert isinstance(models_with_descriptions[model], str)\n assert len(models_with_descriptions[model]) > 50 # Meaningful description\n\n def test_tool_schema_in_auto_mode(self):\n \"\"\"Test that tool schemas require model in auto mode\"\"\"\n # Save original\n original = os.environ.get(\"DEFAULT_MODEL\", \"\")\n\n try:\n # Enable auto mode\n os.environ[\"DEFAULT_MODEL\"] = \"auto\"\n import config\n\n importlib.reload(config)\n\n tool = ChatTool()\n schema = tool.get_input_schema()\n\n # Model should be required\n assert \"model\" in schema[\"required\"]\n\n # Model field should have detailed descriptions\n model_schema = schema[\"properties\"][\"model\"]\n assert \"enum\" not in model_schema\n assert \"auto mode\" in model_schema[\"description\"].lower()\n assert \"listmodels\" in model_schema[\"description\"]\n\n finally:\n # Restore\n if original:\n os.environ[\"DEFAULT_MODEL\"] = original\n else:\n os.environ.pop(\"DEFAULT_MODEL\", None)\n importlib.reload(config)\n\n def test_tool_schema_in_normal_mode(self):\n \"\"\"Test that tool schemas don't require model in normal mode\"\"\"\n # Save original\n original = os.environ.get(\"DEFAULT_MODEL\", \"\")\n\n try:\n # Set to a specific model (not auto mode)\n os.environ[\"DEFAULT_MODEL\"] = \"gemini-2.5-flash\"\n import config\n\n importlib.reload(config)\n\n tool = ChatTool()\n schema = tool.get_input_schema()\n\n # Model should not be required when default model is configured\n assert \"model\" not in schema[\"required\"]\n\n # Model field should have simpler description\n model_schema = schema[\"properties\"][\"model\"]\n assert \"enum\" not in model_schema\n assert \"listmodels\" in model_schema[\"description\"]\n assert \"default model\" in model_schema[\"description\"].lower()\n\n finally:\n # Restore\n if original:\n os.environ[\"DEFAULT_MODEL\"] = original\n else:\n os.environ.pop(\"DEFAULT_MODEL\", None)\n importlib.reload(config)\n\n @pytest.mark.asyncio\n async def test_auto_mode_requires_model_parameter(self, tmp_path):\n \"\"\"Test that auto mode enforces model parameter\"\"\"\n # Save original\n original = os.environ.get(\"DEFAULT_MODEL\", \"\")\n\n try:\n # Enable auto mode\n os.environ[\"DEFAULT_MODEL\"] = \"auto\"\n import config\n\n importlib.reload(config)\n\n tool = ChatTool()\n\n # Mock the provider to avoid real API calls\n with patch.object(tool, \"get_model_provider\"):\n # Execute without model parameter and expect protocol error\n with pytest.raises(ToolExecutionError) as exc_info:\n await tool.execute({\"prompt\": \"Test prompt\", \"working_directory_absolute_path\": str(tmp_path)})\n\n # Should get error payload mentioning model requirement\n error_payload = getattr(exc_info.value, \"payload\", str(exc_info.value))\n assert \"Model\" in error_payload\n assert \"auto\" in error_payload\n\n finally:\n # Restore\n if original:\n os.environ[\"DEFAULT_MODEL\"] = original\n else:\n os.environ.pop(\"DEFAULT_MODEL\", None)\n importlib.reload(config)\n\n @pytest.mark.asyncio\n async def test_unavailable_model_error_message(self):\n \"\"\"Test that unavailable model shows helpful error with available models using real integration testing\"\"\"\n # Save original environment\n original_env = {}\n api_keys = [\"GEMINI_API_KEY\", \"OPENAI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]\n for key in api_keys:\n original_env[key] = os.environ.get(key)\n original_default = os.environ.get(\"DEFAULT_MODEL\", \"\")\n\n try:\n # Set up environment with a real API key but test an unavailable model\n # This simulates a user trying to use a model that's not available with their current setup\n os.environ[\"OPENAI_API_KEY\"] = \"sk-test-key-unavailable-model-test-not-real\"\n os.environ[\"DEFAULT_MODEL\"] = \"auto\"\n\n # Clear other provider keys to isolate to OpenAI\n for key in [\"GEMINI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]:\n os.environ.pop(key, None)\n\n # Reload config and registry to pick up new environment\n import config\n\n importlib.reload(config)\n\n # Clear registry singleton to force re-initialization with new environment\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry._instance = None\n\n tool = ChatTool()\n\n # Test with real provider resolution - this should attempt to use a model\n # that doesn't exist in the OpenAI provider's model list\n try:\n result = await tool.execute(\n {\n \"absolute_file_paths\": [\"/tmp/test.py\"],\n \"prompt\": \"Analyze this\",\n \"model\": \"nonexistent-model-xyz\", # This model definitely doesn't exist\n }\n )\n\n # If we get here, check that it's an error about model availability\n assert len(result) == 1\n response = result[0].text\n assert \"error\" in response\n\n # Should be about model not being available\n assert any(\n phrase in response\n for phrase in [\n \"Model 'nonexistent-model-xyz' is not available\",\n \"No provider found\",\n \"not available\",\n \"not supported\",\n ]\n )\n\n except Exception as e:\n # Expected: Should fail with provider resolution or model validation error\n error_msg = str(e)\n # Should NOT be a mock-related error\n assert \"MagicMock\" not in error_msg\n assert \"'<' not supported between instances\" not in error_msg\n\n # Should be a real provider error about model not being available\n assert any(\n phrase in error_msg\n for phrase in [\n \"Model 'nonexistent-model-xyz'\",\n \"not available\",\n \"not found\",\n \"not supported\",\n \"provider\",\n \"model\",\n ]\n ) or any(phrase in error_msg for phrase in [\"API\", \"key\", \"authentication\", \"network\", \"connection\"])\n\n finally:\n # Restore original environment\n for key, value in original_env.items():\n if value is not None:\n os.environ[key] = value\n else:\n os.environ.pop(key, None)\n\n if original_default:\n os.environ[\"DEFAULT_MODEL\"] = original_default\n else:\n os.environ.pop(\"DEFAULT_MODEL\", None)\n\n # Reload config and clear registry singleton\n importlib.reload(config)\n ModelProviderRegistry._instance = None\n\n def test_model_field_schema_generation(self):\n \"\"\"Test the get_model_field_schema method\"\"\"\n from tools.shared.base_tool import BaseTool\n\n # Create a minimal concrete tool for testing\n class TestTool(BaseTool):\n def get_name(self):\n return \"test\"\n\n def get_description(self):\n return \"test\"\n\n def get_input_schema(self):\n return {}\n\n def get_system_prompt(self):\n return \"\"\n\n def get_request_model(self):\n return None\n\n async def prepare_prompt(self, request):\n return \"\"\n\n tool = TestTool()\n\n # Save original\n original = os.environ.get(\"DEFAULT_MODEL\", \"\")\n\n try:\n # Test auto mode\n os.environ[\"DEFAULT_MODEL\"] = \"auto\"\n import config\n\n importlib.reload(config)\n\n schema = tool.get_model_field_schema()\n assert \"enum\" not in schema\n assert schema[\"type\"] == \"string\"\n assert \"auto mode\" in schema[\"description\"].lower()\n assert \"listmodels\" in schema[\"description\"]\n\n # Test normal mode\n os.environ[\"DEFAULT_MODEL\"] = \"pro\"\n importlib.reload(config)\n\n schema = tool.get_model_field_schema()\n assert \"enum\" not in schema\n assert schema[\"type\"] == \"string\"\n assert \"'pro'\" in schema[\"description\"]\n assert \"listmodels\" in schema[\"description\"]\n\n finally:\n # Restore\n if original:\n os.environ[\"DEFAULT_MODEL\"] = original\n else:\n os.environ.pop(\"DEFAULT_MODEL\", None)\n importlib.reload(config)\n" }, { "path": "tests/test_auto_mode_comprehensive.py", "content": "\"\"\"Comprehensive tests for auto mode functionality across all provider combinations\"\"\"\n\nimport importlib\nimport os\nfrom unittest.mock import MagicMock, patch\n\nimport pytest\n\nfrom providers.gemini import GeminiModelProvider\nfrom providers.openai import OpenAIModelProvider\nfrom providers.registry import ModelProviderRegistry\nfrom providers.shared import ProviderType\nfrom providers.xai import XAIModelProvider\nfrom tools.analyze import AnalyzeTool\nfrom tools.chat import ChatTool\nfrom tools.debug import DebugIssueTool\nfrom tools.models import ToolModelCategory\nfrom tools.shared.exceptions import ToolExecutionError\nfrom tools.thinkdeep import ThinkDeepTool\n\n\n@pytest.mark.no_mock_provider\nclass TestAutoModeComprehensive:\n \"\"\"Test auto mode model selection across all provider combinations\"\"\"\n\n def setup_method(self):\n \"\"\"Set up clean state before each test.\"\"\"\n # Save original environment state for restoration\n import os\n\n self._original_default_model = os.environ.get(\"DEFAULT_MODEL\", \"\")\n\n # Clear restriction service cache\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n # Clear provider registry by resetting singleton instance\n ModelProviderRegistry._instance = None\n\n def teardown_method(self):\n \"\"\"Clean up after each test.\"\"\"\n # Restore original DEFAULT_MODEL\n import os\n\n if self._original_default_model:\n os.environ[\"DEFAULT_MODEL\"] = self._original_default_model\n elif \"DEFAULT_MODEL\" in os.environ:\n del os.environ[\"DEFAULT_MODEL\"]\n\n # Reload config to pick up the restored DEFAULT_MODEL\n import importlib\n\n import config\n\n importlib.reload(config)\n\n # Clear restriction service cache\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n # Clear provider registry by resetting singleton instance\n ModelProviderRegistry._instance = None\n\n # Re-register providers for subsequent tests (like conftest.py does)\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.XAI, XAIModelProvider)\n\n @pytest.mark.parametrize(\n \"provider_config,expected_models\",\n [\n # Only Gemini API available\n (\n {\n \"GEMINI_API_KEY\": \"real-key\",\n \"OPENAI_API_KEY\": None,\n \"XAI_API_KEY\": None,\n \"OPENROUTER_API_KEY\": None,\n },\n {\n \"EXTENDED_REASONING\": \"gemini-3-pro-preview\", # Gemini 3 Pro Preview for deep thinking\n \"FAST_RESPONSE\": \"gemini-2.5-flash\", # Flash for speed\n \"BALANCED\": \"gemini-2.5-flash\", # Flash as balanced\n },\n ),\n # Only OpenAI API available\n (\n {\n \"GEMINI_API_KEY\": None,\n \"OPENAI_API_KEY\": \"real-key\",\n \"XAI_API_KEY\": None,\n \"OPENROUTER_API_KEY\": None,\n },\n {\n \"EXTENDED_REASONING\": \"gpt-5.1-codex\", # GPT-5.1 Codex prioritized for coding tasks\n \"FAST_RESPONSE\": \"gpt-5.2\", # Prefer gpt-5.2 for speed\n \"BALANCED\": \"gpt-5.2\", # Prefer gpt-5.2 for balanced\n },\n ),\n # Only X.AI API available\n (\n {\n \"GEMINI_API_KEY\": None,\n \"OPENAI_API_KEY\": None,\n \"XAI_API_KEY\": \"real-key\",\n \"OPENROUTER_API_KEY\": None,\n },\n {\n \"EXTENDED_REASONING\": \"grok-4-1-fast-reasoning\", # Latest Grok 4.1 Fast Reasoning\n \"FAST_RESPONSE\": \"grok-4-1-fast-reasoning\", # Latest fast SKU\n \"BALANCED\": \"grok-4-1-fast-reasoning\", # Latest balanced default\n },\n ),\n # Both Gemini and OpenAI available - Google comes first in priority\n (\n {\n \"GEMINI_API_KEY\": \"real-key\",\n \"OPENAI_API_KEY\": \"real-key\",\n \"XAI_API_KEY\": None,\n \"OPENROUTER_API_KEY\": None,\n },\n {\n \"EXTENDED_REASONING\": \"gemini-3-pro-preview\", # Gemini 3 Pro Preview comes first in priority\n \"FAST_RESPONSE\": \"gemini-2.5-flash\", # Prefer flash for speed\n \"BALANCED\": \"gemini-2.5-flash\", # Prefer flash for balanced\n },\n ),\n # All native APIs available - Google still comes first\n (\n {\n \"GEMINI_API_KEY\": \"real-key\",\n \"OPENAI_API_KEY\": \"real-key\",\n \"XAI_API_KEY\": \"real-key\",\n \"OPENROUTER_API_KEY\": None,\n },\n {\n \"EXTENDED_REASONING\": \"gemini-3-pro-preview\", # Gemini 3 Pro Preview comes first in priority\n \"FAST_RESPONSE\": \"gemini-2.5-flash\", # Prefer flash for speed\n \"BALANCED\": \"gemini-2.5-flash\", # Prefer flash for balanced\n },\n ),\n ],\n )\n def test_auto_mode_model_selection_by_provider(self, provider_config, expected_models):\n \"\"\"Test that auto mode selects correct models based on available providers.\"\"\"\n\n # Set up environment with specific provider configuration\n # Filter out None values and handle them separately\n env_to_set = {k: v for k, v in provider_config.items() if v is not None}\n env_to_clear = [k for k, v in provider_config.items() if v is None]\n\n with patch.dict(os.environ, env_to_set, clear=False):\n # Clear the None-valued environment variables\n for key in env_to_clear:\n if key in os.environ:\n del os.environ[key]\n # Reload config to pick up auto mode\n os.environ[\"DEFAULT_MODEL\"] = \"auto\"\n import config\n\n importlib.reload(config)\n\n # Register providers based on configuration\n from providers.openrouter import OpenRouterProvider\n\n if provider_config.get(\"GEMINI_API_KEY\"):\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n if provider_config.get(\"OPENAI_API_KEY\"):\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n if provider_config.get(\"XAI_API_KEY\"):\n ModelProviderRegistry.register_provider(ProviderType.XAI, XAIModelProvider)\n if provider_config.get(\"OPENROUTER_API_KEY\"):\n ModelProviderRegistry.register_provider(ProviderType.OPENROUTER, OpenRouterProvider)\n\n # Test each tool category\n for category_name, expected_model in expected_models.items():\n category = ToolModelCategory(category_name.lower())\n\n # Get preferred fallback model for this category\n fallback_model = ModelProviderRegistry.get_preferred_fallback_model(category)\n\n assert fallback_model == expected_model, (\n f\"Provider config {provider_config}: \"\n f\"Expected {expected_model} for {category_name}, got {fallback_model}\"\n )\n\n @pytest.mark.parametrize(\n \"tool_class,expected_category\",\n [\n (ChatTool, ToolModelCategory.FAST_RESPONSE),\n (AnalyzeTool, ToolModelCategory.EXTENDED_REASONING), # AnalyzeTool uses EXTENDED_REASONING\n (DebugIssueTool, ToolModelCategory.EXTENDED_REASONING),\n (ThinkDeepTool, ToolModelCategory.EXTENDED_REASONING),\n ],\n )\n def test_tool_model_categories(self, tool_class, expected_category):\n \"\"\"Test that tools have the correct model categories.\"\"\"\n tool = tool_class()\n assert tool.get_model_category() == expected_category\n\n @pytest.mark.asyncio\n async def test_auto_mode_with_gemini_only_uses_correct_models(self, tmp_path):\n \"\"\"Test that auto mode with only Gemini uses flash for fast tools and pro for reasoning tools.\"\"\"\n\n provider_config = {\n \"GEMINI_API_KEY\": \"real-key\",\n \"OPENAI_API_KEY\": None,\n \"XAI_API_KEY\": None,\n \"OPENROUTER_API_KEY\": None,\n \"DEFAULT_MODEL\": \"auto\",\n }\n\n # Filter out None values to avoid patch.dict errors\n env_to_set = {k: v for k, v in provider_config.items() if v is not None}\n env_to_clear = [k for k, v in provider_config.items() if v is None]\n\n with patch.dict(os.environ, env_to_set, clear=False):\n # Clear the None-valued environment variables\n for key in env_to_clear:\n if key in os.environ:\n del os.environ[key]\n import config\n\n importlib.reload(config)\n\n # Register only Gemini provider\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n # Test ChatTool (FAST_RESPONSE) - auto mode should suggest flash variant\n chat_tool = ChatTool()\n chat_message = chat_tool._build_auto_mode_required_message()\n assert \"flash\" in chat_message\n\n # Test DebugIssueTool (EXTENDED_REASONING) - auto mode should suggest pro variant\n debug_tool = DebugIssueTool()\n debug_message = debug_tool._build_auto_mode_required_message()\n assert \"pro\" in debug_message\n\n def test_auto_mode_schema_includes_all_available_models(self):\n \"\"\"Test that auto mode schema includes all available models for user convenience.\"\"\"\n\n # Test with only Gemini available\n provider_config = {\n \"GEMINI_API_KEY\": \"real-key\",\n \"OPENAI_API_KEY\": None,\n \"XAI_API_KEY\": None,\n \"OPENROUTER_API_KEY\": None,\n \"CUSTOM_API_URL\": None,\n \"DEFAULT_MODEL\": \"auto\",\n }\n\n # Filter out None values to avoid patch.dict errors\n env_to_set = {k: v for k, v in provider_config.items() if v is not None}\n env_to_clear = [k for k, v in provider_config.items() if v is None]\n\n with patch.dict(os.environ, env_to_set, clear=False):\n # Clear the None-valued environment variables\n for key in env_to_clear:\n if key in os.environ:\n del os.environ[key]\n import config\n\n importlib.reload(config)\n\n # Register only Gemini provider\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n tool = AnalyzeTool()\n schema = tool.get_input_schema()\n\n # Should have model as required field\n assert \"model\" in schema[\"required\"]\n\n # In auto mode, the schema should now have a description field\n # instructing users to use the listmodels tool instead of an enum\n model_schema = schema[\"properties\"][\"model\"]\n assert \"type\" in model_schema\n assert model_schema[\"type\"] == \"string\"\n assert \"description\" in model_schema\n\n # Check that the description mentions using listmodels tool\n description = model_schema[\"description\"]\n assert \"listmodels\" in description.lower()\n assert \"auto\" in description.lower() or \"selection\" in description.lower()\n\n # Should NOT have enum field anymore - this is the new behavior\n assert \"enum\" not in model_schema\n\n # After the design change, the system directs users to use listmodels\n # instead of enumerating all models in the schema\n # This prevents model namespace collisions and keeps the schema cleaner\n\n # With the new design change, we no longer enumerate models in the schema\n # The listmodels tool should be used to discover available models\n # This test now validates the schema structure rather than model enumeration\n\n def test_auto_mode_schema_with_all_providers(self):\n \"\"\"Test that auto mode schema includes models from all available providers.\"\"\"\n\n provider_config = {\n \"GEMINI_API_KEY\": \"real-key\",\n \"OPENAI_API_KEY\": \"real-key\",\n \"XAI_API_KEY\": \"real-key\",\n \"OPENROUTER_API_KEY\": None, # Don't include OpenRouter to avoid infinite models\n \"DEFAULT_MODEL\": \"auto\",\n }\n\n # Filter out None values to avoid patch.dict errors\n env_to_set = {k: v for k, v in provider_config.items() if v is not None}\n env_to_clear = [k for k, v in provider_config.items() if v is None]\n\n with patch.dict(os.environ, env_to_set, clear=False):\n # Clear the None-valued environment variables\n for key in env_to_clear:\n if key in os.environ:\n del os.environ[key]\n import config\n\n importlib.reload(config)\n\n # Register all native providers\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.XAI, XAIModelProvider)\n\n tool = AnalyzeTool()\n schema = tool.get_input_schema()\n\n # In auto mode with multiple providers, should still use the new schema format\n model_schema = schema[\"properties\"][\"model\"]\n assert \"type\" in model_schema\n assert model_schema[\"type\"] == \"string\"\n assert \"description\" in model_schema\n\n # Check that the description mentions using listmodels tool\n description = model_schema[\"description\"]\n assert \"listmodels\" in description.lower()\n\n # Should NOT have enum field - uses listmodels tool instead\n assert \"enum\" not in model_schema\n\n # With multiple providers configured, the listmodels tool\n # would show models from all providers when called\n\n @pytest.mark.asyncio\n async def test_auto_mode_model_parameter_required_error(self, tmp_path):\n \"\"\"Test that auto mode properly requires model parameter and suggests correct model.\"\"\"\n\n provider_config = {\n \"GEMINI_API_KEY\": \"real-key\",\n \"OPENAI_API_KEY\": None,\n \"XAI_API_KEY\": None,\n \"OPENROUTER_API_KEY\": None,\n \"DEFAULT_MODEL\": \"auto\",\n }\n\n # Filter out None values to avoid patch.dict errors\n env_to_set = {k: v for k, v in provider_config.items() if v is not None}\n env_to_clear = [k for k, v in provider_config.items() if v is None]\n\n with patch.dict(os.environ, env_to_set, clear=False):\n # Clear the None-valued environment variables\n for key in env_to_clear:\n if key in os.environ:\n del os.environ[key]\n import config\n\n importlib.reload(config)\n\n # Register only Gemini provider\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n # Test with ChatTool (FAST_RESPONSE category)\n chat_tool = ChatTool()\n workdir = tmp_path / \"chat_artifacts\"\n workdir.mkdir(parents=True, exist_ok=True)\n with pytest.raises(ToolExecutionError) as exc_info:\n await chat_tool.execute(\n {\n \"prompt\": \"test\",\n \"working_directory_absolute_path\": str(workdir),\n # Note: no model parameter provided in auto mode\n }\n )\n\n # Should get error requiring model selection with fallback suggestion\n import json\n\n response_data = json.loads(exc_info.value.payload)\n\n assert response_data[\"status\"] == \"error\"\n assert (\n \"Model parameter is required\" in response_data[\"content\"] or \"Model 'auto'\" in response_data[\"content\"]\n )\n assert \"flash\" in response_data[\"content\"]\n\n def test_model_availability_with_restrictions(self):\n \"\"\"Test that auto mode respects model restrictions when selecting fallback models.\"\"\"\n\n provider_config = {\n \"GEMINI_API_KEY\": \"real-key\",\n \"OPENAI_API_KEY\": \"real-key\",\n \"XAI_API_KEY\": None,\n \"OPENROUTER_API_KEY\": None,\n \"DEFAULT_MODEL\": \"auto\",\n \"OPENAI_ALLOWED_MODELS\": \"o4-mini\", # Restrict OpenAI to only o4-mini\n }\n\n # Filter out None values to avoid patch.dict errors\n env_to_set = {k: v for k, v in provider_config.items() if v is not None}\n env_to_clear = [k for k, v in provider_config.items() if v is None]\n\n with patch.dict(os.environ, env_to_set, clear=False):\n # Clear the None-valued environment variables\n for key in env_to_clear:\n if key in os.environ:\n del os.environ[key]\n import config\n\n importlib.reload(config)\n\n # Clear restriction service to pick up new env vars\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n # Register providers\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n\n # Get available models - should respect restrictions\n available_models = ModelProviderRegistry.get_available_models(respect_restrictions=True)\n\n # Should include restricted OpenAI model\n assert \"o4-mini\" in available_models\n\n # Should NOT include non-restricted OpenAI models\n assert \"o3\" not in available_models\n assert \"o3-mini\" not in available_models\n\n # Should still include all Gemini models (no restrictions)\n assert \"gemini-2.5-flash\" in available_models\n assert \"gemini-2.5-pro\" in available_models\n\n def test_openrouter_fallback_when_no_native_apis(self):\n \"\"\"Test that OpenRouter provides fallback models when no native APIs are available.\"\"\"\n\n provider_config = {\n \"GEMINI_API_KEY\": None,\n \"OPENAI_API_KEY\": None,\n \"XAI_API_KEY\": None,\n \"OPENROUTER_API_KEY\": \"real-key\",\n \"DEFAULT_MODEL\": \"auto\",\n }\n\n # Filter out None values to avoid patch.dict errors\n env_to_set = {k: v for k, v in provider_config.items() if v is not None}\n env_to_clear = [k for k, v in provider_config.items() if v is None]\n\n with patch.dict(os.environ, env_to_set, clear=False):\n # Clear the None-valued environment variables\n for key in env_to_clear:\n if key in os.environ:\n del os.environ[key]\n import config\n\n importlib.reload(config)\n\n # Register only OpenRouter provider\n from providers.openrouter import OpenRouterProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENROUTER, OpenRouterProvider)\n\n # Mock OpenRouter registry to return known models\n mock_registry = MagicMock()\n mock_registry.list_models.return_value = [\n \"google/gemini-2.5-flash\",\n \"google/gemini-2.5-pro\",\n \"openai/o3\",\n \"openai/o4-mini\",\n \"anthropic/claude-opus-4\",\n ]\n\n with patch.object(OpenRouterProvider, \"_registry\", mock_registry):\n # Get preferred models for different categories\n extended_reasoning = ModelProviderRegistry.get_preferred_fallback_model(\n ToolModelCategory.EXTENDED_REASONING\n )\n fast_response = ModelProviderRegistry.get_preferred_fallback_model(ToolModelCategory.FAST_RESPONSE)\n\n # Should fallback to known good models even via OpenRouter\n # The exact model depends on _find_extended_thinking_model implementation\n assert extended_reasoning is not None\n assert fast_response is not None\n\n @pytest.mark.asyncio\n async def test_actual_model_name_resolution_in_auto_mode(self, tmp_path):\n \"\"\"Test that when a model is selected in auto mode, the tool executes successfully.\"\"\"\n\n provider_config = {\n \"GEMINI_API_KEY\": \"real-key\",\n \"OPENAI_API_KEY\": None,\n \"XAI_API_KEY\": None,\n \"OPENROUTER_API_KEY\": None,\n \"DEFAULT_MODEL\": \"auto\",\n }\n\n # Filter out None values to avoid patch.dict errors\n env_to_set = {k: v for k, v in provider_config.items() if v is not None}\n env_to_clear = [k for k, v in provider_config.items() if v is None]\n\n with patch.dict(os.environ, env_to_set, clear=False):\n # Clear the None-valued environment variables\n for key in env_to_clear:\n if key in os.environ:\n del os.environ[key]\n import config\n\n importlib.reload(config)\n\n # Register Gemini provider\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n # Mock the actual provider to simulate successful execution\n mock_provider = MagicMock()\n mock_response = MagicMock()\n mock_response.content = \"test response\"\n mock_response.model_name = \"gemini-2.5-flash\" # The resolved name\n mock_response.usage = {\"input_tokens\": 10, \"output_tokens\": 5}\n # Mock _resolve_model_name to simulate alias resolution\n mock_provider._resolve_model_name = lambda alias: (\"gemini-2.5-flash\" if alias == \"flash\" else alias)\n mock_provider.generate_content.return_value = mock_response\n\n with patch.object(ModelProviderRegistry, \"get_provider_for_model\", return_value=mock_provider):\n chat_tool = ChatTool()\n workdir = tmp_path / \"chat_artifacts\"\n workdir.mkdir(parents=True, exist_ok=True)\n result = await chat_tool.execute(\n {\"prompt\": \"test\", \"model\": \"flash\", \"working_directory_absolute_path\": str(workdir)}\n ) # Use alias in auto mode\n\n # Should succeed with proper model resolution\n assert len(result) == 1\n # Just verify that the tool executed successfully and didn't return an error\n assert \"error\" not in result[0].text.lower()\n" }, { "path": "tests/test_auto_mode_custom_provider_only.py", "content": "\"\"\"Test auto mode with only custom provider configured to reproduce the reported issue.\"\"\"\n\nimport importlib\nimport os\nfrom unittest.mock import patch\n\nimport pytest\n\nfrom providers.registry import ModelProviderRegistry\nfrom providers.shared import ProviderType\n\n\n@pytest.mark.no_mock_provider\nclass TestAutoModeCustomProviderOnly:\n \"\"\"Test auto mode when only custom provider is configured.\"\"\"\n\n def setup_method(self):\n \"\"\"Set up clean state before each test.\"\"\"\n # Save original environment state for restoration\n self._original_env = {}\n for key in [\n \"GEMINI_API_KEY\",\n \"OPENAI_API_KEY\",\n \"XAI_API_KEY\",\n \"OPENROUTER_API_KEY\",\n \"CUSTOM_API_URL\",\n \"CUSTOM_API_KEY\",\n \"DEFAULT_MODEL\",\n ]:\n self._original_env[key] = os.environ.get(key)\n\n # Clear restriction service cache\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n # Clear provider registry by resetting singleton instance\n ModelProviderRegistry._instance = None\n\n def teardown_method(self):\n \"\"\"Clean up after each test.\"\"\"\n # Restore original environment\n for key, value in self._original_env.items():\n if value is not None:\n os.environ[key] = value\n elif key in os.environ:\n del os.environ[key]\n\n # Reload config to pick up the restored environment\n import config\n\n importlib.reload(config)\n\n # Clear restriction service cache\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n # Clear provider registry by resetting singleton instance\n ModelProviderRegistry._instance = None\n\n def test_reproduce_auto_mode_custom_provider_only_issue(self):\n \"\"\"Test the fix for auto mode failing when only custom provider is configured.\"\"\"\n\n # Set up environment with ONLY custom provider configured\n test_env = {\n \"CUSTOM_API_URL\": \"http://localhost:11434/v1\",\n \"CUSTOM_API_KEY\": \"\", # Empty for Ollama-style\n \"DEFAULT_MODEL\": \"auto\",\n }\n\n # Clear all other provider keys\n clear_keys = [\"GEMINI_API_KEY\", \"OPENAI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\", \"DIAL_API_KEY\"]\n\n with patch.dict(os.environ, test_env, clear=False):\n # Ensure other provider keys are not set\n for key in clear_keys:\n if key in os.environ:\n del os.environ[key]\n\n # Reload config to pick up auto mode\n import config\n\n importlib.reload(config)\n\n # Register only the custom provider (simulating server startup)\n from providers.custom import CustomProvider\n\n ModelProviderRegistry.register_provider(ProviderType.CUSTOM, CustomProvider)\n\n # This should now work after the fix\n # The fix added support for custom provider registry system in get_available_models()\n available_models = ModelProviderRegistry.get_available_models(respect_restrictions=True)\n\n # This assertion should now pass after the fix\n assert available_models, (\n \"Expected custom provider models to be available. \"\n \"This test verifies the fix for auto mode failing with custom providers.\"\n )\n\n def test_custom_provider_models_available_via_registry(self):\n \"\"\"Test that custom provider has models available via its registry system.\"\"\"\n\n # Set up environment with only custom provider\n test_env = {\n \"CUSTOM_API_URL\": \"http://localhost:11434/v1\",\n \"CUSTOM_API_KEY\": \"\",\n }\n\n with patch.dict(os.environ, test_env, clear=False):\n # Clear other provider keys\n for key in [\"GEMINI_API_KEY\", \"OPENAI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\", \"DIAL_API_KEY\"]:\n if key in os.environ:\n del os.environ[key]\n\n # Register custom provider\n from providers.custom import CustomProvider\n\n ModelProviderRegistry.register_provider(ProviderType.CUSTOM, CustomProvider)\n\n # Get the provider instance\n custom_provider = ModelProviderRegistry.get_provider(ProviderType.CUSTOM)\n assert custom_provider is not None, \"Custom provider should be available\"\n\n # Verify it has a registry with models\n assert hasattr(custom_provider, \"_registry\"), \"Custom provider should have _registry\"\n assert custom_provider._registry is not None, \"Registry should be initialized\"\n\n # Get models from registry\n models = custom_provider._registry.list_models()\n aliases = custom_provider._registry.list_aliases()\n\n # Should have some models and aliases available\n assert models, \"Custom provider registry should have models\"\n assert aliases, \"Custom provider registry should have aliases\"\n\n print(f\"Available models: {len(models)}\")\n print(f\"Available aliases: {len(aliases)}\")\n\n def test_custom_provider_validate_model_name(self):\n \"\"\"Test that custom provider can validate model names.\"\"\"\n\n # Set up environment with only custom provider\n test_env = {\n \"CUSTOM_API_URL\": \"http://localhost:11434/v1\",\n \"CUSTOM_API_KEY\": \"\",\n }\n\n with patch.dict(os.environ, test_env, clear=False):\n # Register custom provider\n from providers.custom import CustomProvider\n\n ModelProviderRegistry.register_provider(ProviderType.CUSTOM, CustomProvider)\n\n # Get the provider instance\n custom_provider = ModelProviderRegistry.get_provider(ProviderType.CUSTOM)\n assert custom_provider is not None\n\n # Test that it can validate some typical custom model names\n test_models = [\"llama3.2\", \"llama3.2:latest\", \"local-model\", \"ollama-model\"]\n\n for model in test_models:\n is_valid = custom_provider.validate_model_name(model)\n print(f\"Model '{model}' validation: {is_valid}\")\n # Should validate at least some local-style models\n # (The exact validation logic may vary based on registry content)\n\n def test_auto_mode_fallback_with_custom_only_should_work(self):\n \"\"\"Test that auto mode fallback should work when only custom provider is available.\"\"\"\n\n # Set up environment with only custom provider\n test_env = {\n \"CUSTOM_API_URL\": \"http://localhost:11434/v1\",\n \"CUSTOM_API_KEY\": \"\",\n \"DEFAULT_MODEL\": \"auto\",\n }\n\n with patch.dict(os.environ, test_env, clear=False):\n # Clear other provider keys\n for key in [\"GEMINI_API_KEY\", \"OPENAI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\", \"DIAL_API_KEY\"]:\n if key in os.environ:\n del os.environ[key]\n\n # Reload config\n import config\n\n importlib.reload(config)\n\n # Register custom provider\n from providers.custom import CustomProvider\n\n ModelProviderRegistry.register_provider(ProviderType.CUSTOM, CustomProvider)\n\n # This should work and return a fallback model from custom provider\n # Currently fails because get_preferred_fallback_model doesn't consider custom models\n from tools.models import ToolModelCategory\n\n try:\n fallback_model = ModelProviderRegistry.get_preferred_fallback_model(ToolModelCategory.FAST_RESPONSE)\n print(f\"Fallback model for FAST_RESPONSE: {fallback_model}\")\n\n # Should get a valid model name, not the hardcoded fallback\n assert (\n fallback_model != \"gemini-2.5-flash\"\n ), \"Should not fallback to hardcoded Gemini model when custom provider is available\"\n\n except Exception as e:\n pytest.fail(f\"Getting fallback model failed: {e}\")\n" }, { "path": "tests/test_auto_mode_model_listing.py", "content": "\"\"\"Tests covering model restriction-aware error messaging in auto mode.\"\"\"\n\nimport asyncio\nimport importlib\nimport json\n\nimport pytest\n\nimport utils.env as env_config\nimport utils.model_restrictions as model_restrictions\nfrom providers.gemini import GeminiModelProvider\nfrom providers.openai import OpenAIModelProvider\nfrom providers.openrouter import OpenRouterProvider\nfrom providers.registry import ModelProviderRegistry\nfrom providers.shared import ProviderType\nfrom providers.xai import XAIModelProvider\nfrom tools.shared.exceptions import ToolExecutionError\n\n\ndef _extract_available_models(message: str) -> list[str]:\n \"\"\"Parse the available model list from the error message.\"\"\"\n\n marker = \"Available models: \"\n if marker not in message:\n raise AssertionError(f\"Expected '{marker}' in message: {message}\")\n\n start = message.index(marker) + len(marker)\n end = message.find(\". Suggested\", start)\n if end == -1:\n end = len(message)\n\n available_segment = message[start:end].strip()\n if not available_segment:\n return []\n\n return [item.strip() for item in available_segment.split(\",\")]\n\n\n@pytest.fixture\ndef reset_registry():\n \"\"\"Ensure registry and restriction service state is isolated.\"\"\"\n\n ModelProviderRegistry.reset_for_testing()\n model_restrictions._restriction_service = None\n env_config.reload_env()\n yield\n ModelProviderRegistry.reset_for_testing()\n model_restrictions._restriction_service = None\n\n\ndef _register_core_providers(*, include_xai: bool = False):\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.OPENROUTER, OpenRouterProvider)\n if include_xai:\n ModelProviderRegistry.register_provider(ProviderType.XAI, XAIModelProvider)\n\n\n@pytest.mark.no_mock_provider\ndef test_error_listing_respects_env_restrictions(monkeypatch, reset_registry):\n \"\"\"Error payload should surface only the allowed models for each provider.\"\"\"\n\n monkeypatch.setenv(\"DEFAULT_MODEL\", \"auto\")\n monkeypatch.setenv(\"GEMINI_API_KEY\", \"test-gemini\")\n monkeypatch.setenv(\"OPENAI_API_KEY\", \"test-openai\")\n monkeypatch.setenv(\"OPENROUTER_API_KEY\", \"test-openrouter\")\n monkeypatch.delenv(\"XAI_API_KEY\", raising=False)\n # Ensure Azure provider stays disabled regardless of developer workstation env\n for azure_var in (\n \"AZURE_OPENAI_API_KEY\",\n \"AZURE_OPENAI_ENDPOINT\",\n \"AZURE_OPENAI_ALLOWED_MODELS\",\n \"AZURE_MODELS_CONFIG_PATH\",\n ):\n monkeypatch.delenv(azure_var, raising=False)\n monkeypatch.setenv(\"PAL_MCP_FORCE_ENV_OVERRIDE\", \"false\")\n env_config.reload_env({\"PAL_MCP_FORCE_ENV_OVERRIDE\": \"false\"})\n try:\n import dotenv\n\n monkeypatch.setattr(dotenv, \"dotenv_values\", lambda *_args, **_kwargs: {\"PAL_MCP_FORCE_ENV_OVERRIDE\": \"false\"})\n except ModuleNotFoundError:\n pass\n\n monkeypatch.setenv(\"GOOGLE_ALLOWED_MODELS\", \"gemini-2.5-pro\")\n monkeypatch.setenv(\"OPENAI_ALLOWED_MODELS\", \"gpt-5.2\")\n monkeypatch.setenv(\"OPENROUTER_ALLOWED_MODELS\", \"gpt5nano\")\n monkeypatch.setenv(\"XAI_ALLOWED_MODELS\", \"\")\n\n import config\n\n importlib.reload(config)\n\n _register_core_providers()\n\n import server\n\n importlib.reload(server)\n\n # Reload may have re-applied .env overrides; enforce our test configuration\n for key, value in (\n (\"DEFAULT_MODEL\", \"auto\"),\n (\"GEMINI_API_KEY\", \"test-gemini\"),\n (\"OPENAI_API_KEY\", \"test-openai\"),\n (\"OPENROUTER_API_KEY\", \"test-openrouter\"),\n (\"GOOGLE_ALLOWED_MODELS\", \"gemini-2.5-pro\"),\n (\"OPENAI_ALLOWED_MODELS\", \"gpt-5.2\"),\n (\"OPENROUTER_ALLOWED_MODELS\", \"gpt5nano\"),\n (\"XAI_ALLOWED_MODELS\", \"\"),\n ):\n monkeypatch.setenv(key, value)\n\n for var in (\"XAI_API_KEY\", \"CUSTOM_API_URL\", \"CUSTOM_API_KEY\", \"DIAL_API_KEY\"):\n monkeypatch.delenv(var, raising=False)\n for azure_var in (\n \"AZURE_OPENAI_API_KEY\",\n \"AZURE_OPENAI_ENDPOINT\",\n \"AZURE_OPENAI_ALLOWED_MODELS\",\n \"AZURE_MODELS_CONFIG_PATH\",\n ):\n monkeypatch.delenv(azure_var, raising=False)\n\n ModelProviderRegistry.reset_for_testing()\n model_restrictions._restriction_service = None\n server.configure_providers()\n\n with pytest.raises(ToolExecutionError) as exc_info:\n asyncio.run(\n server.handle_call_tool(\n \"chat\",\n {\n \"model\": \"gpt5mini\",\n \"prompt\": \"Tell me about your strengths\",\n },\n )\n )\n\n payload = json.loads(exc_info.value.payload)\n assert payload[\"status\"] == \"error\"\n\n available_models = _extract_available_models(payload[\"content\"])\n assert set(available_models) == {\"gemini-2.5-pro\", \"gpt-5.2\", \"gpt5nano\", \"openai/gpt-5-nano\"}\n\n\n@pytest.mark.no_mock_provider\ndef test_error_listing_without_restrictions_shows_full_catalog(monkeypatch, reset_registry):\n \"\"\"When no restrictions are set, the full high-capability catalogue should appear.\"\"\"\n\n monkeypatch.setenv(\"DEFAULT_MODEL\", \"auto\")\n monkeypatch.setenv(\"GEMINI_API_KEY\", \"test-gemini\")\n monkeypatch.setenv(\"OPENAI_API_KEY\", \"test-openai\")\n monkeypatch.setenv(\"OPENROUTER_API_KEY\", \"test-openrouter\")\n monkeypatch.setenv(\"XAI_API_KEY\", \"test-xai\")\n monkeypatch.setenv(\"PAL_MCP_FORCE_ENV_OVERRIDE\", \"false\")\n for azure_var in (\n \"AZURE_OPENAI_API_KEY\",\n \"AZURE_OPENAI_ENDPOINT\",\n \"AZURE_OPENAI_ALLOWED_MODELS\",\n \"AZURE_MODELS_CONFIG_PATH\",\n ):\n monkeypatch.delenv(azure_var, raising=False)\n env_config.reload_env({\"PAL_MCP_FORCE_ENV_OVERRIDE\": \"false\"})\n try:\n import dotenv\n\n monkeypatch.setattr(dotenv, \"dotenv_values\", lambda *_args, **_kwargs: {\"PAL_MCP_FORCE_ENV_OVERRIDE\": \"false\"})\n except ModuleNotFoundError:\n pass\n\n for var in (\n \"GOOGLE_ALLOWED_MODELS\",\n \"OPENAI_ALLOWED_MODELS\",\n \"OPENROUTER_ALLOWED_MODELS\",\n \"XAI_ALLOWED_MODELS\",\n \"DIAL_ALLOWED_MODELS\",\n ):\n monkeypatch.delenv(var, raising=False)\n\n import config\n\n importlib.reload(config)\n\n _register_core_providers(include_xai=True)\n\n import server\n\n importlib.reload(server)\n\n for key, value in (\n (\"DEFAULT_MODEL\", \"auto\"),\n (\"GEMINI_API_KEY\", \"test-gemini\"),\n (\"OPENAI_API_KEY\", \"test-openai\"),\n (\"OPENROUTER_API_KEY\", \"test-openrouter\"),\n ):\n monkeypatch.setenv(key, value)\n\n for var in (\n \"GOOGLE_ALLOWED_MODELS\",\n \"OPENAI_ALLOWED_MODELS\",\n \"OPENROUTER_ALLOWED_MODELS\",\n \"XAI_ALLOWED_MODELS\",\n \"DIAL_ALLOWED_MODELS\",\n \"CUSTOM_API_URL\",\n \"CUSTOM_API_KEY\",\n ):\n monkeypatch.delenv(var, raising=False)\n\n ModelProviderRegistry.reset_for_testing()\n model_restrictions._restriction_service = None\n server.configure_providers()\n\n with pytest.raises(ToolExecutionError) as exc_info:\n asyncio.run(\n server.handle_call_tool(\n \"chat\",\n {\n \"model\": \"dummymodel\",\n \"prompt\": \"Hi there\",\n },\n )\n )\n\n payload = json.loads(exc_info.value.payload)\n assert payload[\"status\"] == \"error\"\n\n available_models = _extract_available_models(payload[\"content\"])\n assert \"gemini-2.5-pro\" in available_models\n assert any(model in available_models for model in {\"gpt-5.2\", \"gpt-5\"})\n assert \"grok-4\" in available_models\n assert len(available_models) >= 5\n" }, { "path": "tests/test_auto_mode_provider_selection.py", "content": "\"\"\"Test auto mode provider selection logic specifically\"\"\"\n\nimport os\n\nimport pytest\n\nfrom providers.registry import ModelProviderRegistry\nfrom providers.shared import ProviderType\nfrom tools.models import ToolModelCategory\n\n\n@pytest.mark.no_mock_provider\nclass TestAutoModeProviderSelection:\n \"\"\"Test the core auto mode provider selection logic\"\"\"\n\n def setup_method(self):\n \"\"\"Set up clean state before each test.\"\"\"\n # Clear restriction service cache\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n # Clear provider registry\n registry = ModelProviderRegistry()\n registry._providers.clear()\n registry._initialized_providers.clear()\n\n def teardown_method(self):\n \"\"\"Clean up after each test.\"\"\"\n # Clear restriction service cache\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n def test_gemini_only_fallback_selection(self):\n \"\"\"Test auto mode fallback when only Gemini is available.\"\"\"\n\n # Save original environment\n original_env = {}\n for key in [\"GEMINI_API_KEY\", \"OPENAI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]:\n original_env[key] = os.environ.get(key)\n\n try:\n # Set up environment - only Gemini available\n os.environ[\"GEMINI_API_KEY\"] = \"test-key\"\n for key in [\"OPENAI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]:\n os.environ.pop(key, None)\n\n # Register only Gemini provider\n from providers.gemini import GeminiModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n # Test fallback selection for different categories\n extended_reasoning = ModelProviderRegistry.get_preferred_fallback_model(\n ToolModelCategory.EXTENDED_REASONING\n )\n fast_response = ModelProviderRegistry.get_preferred_fallback_model(ToolModelCategory.FAST_RESPONSE)\n balanced = ModelProviderRegistry.get_preferred_fallback_model(ToolModelCategory.BALANCED)\n\n # Should select appropriate Gemini models\n assert extended_reasoning in [\"gemini-3-pro-preview\", \"gemini-2.5-pro\", \"pro\"]\n assert fast_response in [\"gemini-2.5-flash\", \"flash\"]\n assert balanced in [\"gemini-2.5-flash\", \"flash\"]\n\n finally:\n # Restore original environment\n for key, value in original_env.items():\n if value is not None:\n os.environ[key] = value\n else:\n os.environ.pop(key, None)\n\n def test_openai_only_fallback_selection(self):\n \"\"\"Test auto mode fallback when only OpenAI is available.\"\"\"\n\n # Save original environment\n original_env = {}\n for key in [\"GEMINI_API_KEY\", \"OPENAI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]:\n original_env[key] = os.environ.get(key)\n\n try:\n # Set up environment - only OpenAI available\n os.environ[\"OPENAI_API_KEY\"] = \"test-key\"\n for key in [\"GEMINI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]:\n os.environ.pop(key, None)\n\n # Register only OpenAI provider\n from providers.openai import OpenAIModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n\n # Test fallback selection for different categories\n extended_reasoning = ModelProviderRegistry.get_preferred_fallback_model(\n ToolModelCategory.EXTENDED_REASONING\n )\n fast_response = ModelProviderRegistry.get_preferred_fallback_model(ToolModelCategory.FAST_RESPONSE)\n balanced = ModelProviderRegistry.get_preferred_fallback_model(ToolModelCategory.BALANCED)\n\n # Should select appropriate OpenAI models based on new preference order\n assert extended_reasoning == \"gpt-5.1-codex\" # GPT-5.1 Codex prioritized for extended reasoning\n assert fast_response == \"gpt-5.2\" # gpt-5.2 comes first in fast response preference\n assert balanced == \"gpt-5.2\" # gpt-5.2 for balanced\n\n finally:\n # Restore original environment\n for key, value in original_env.items():\n if value is not None:\n os.environ[key] = value\n else:\n os.environ.pop(key, None)\n\n def test_both_gemini_and_openai_priority(self):\n \"\"\"Test auto mode when both Gemini and OpenAI are available.\"\"\"\n\n # Save original environment\n original_env = {}\n for key in [\"GEMINI_API_KEY\", \"OPENAI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]:\n original_env[key] = os.environ.get(key)\n\n try:\n # Set up environment - both Gemini and OpenAI available\n os.environ[\"GEMINI_API_KEY\"] = \"test-key\"\n os.environ[\"OPENAI_API_KEY\"] = \"test-key\"\n for key in [\"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]:\n os.environ.pop(key, None)\n\n # Register both providers\n from providers.gemini import GeminiModelProvider\n from providers.openai import OpenAIModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n\n # Test fallback selection for different categories\n extended_reasoning = ModelProviderRegistry.get_preferred_fallback_model(\n ToolModelCategory.EXTENDED_REASONING\n )\n fast_response = ModelProviderRegistry.get_preferred_fallback_model(ToolModelCategory.FAST_RESPONSE)\n\n # Should prefer Gemini now (based on new provider priority: Gemini before OpenAI)\n assert extended_reasoning == \"gemini-3-pro-preview\" # Gemini 3 Pro Preview has higher priority now\n\n # Should prefer Gemini for fast response\n assert fast_response == \"gemini-2.5-flash\" # Gemini has higher priority now\n\n finally:\n # Restore original environment\n for key, value in original_env.items():\n if value is not None:\n os.environ[key] = value\n else:\n os.environ.pop(key, None)\n\n def test_xai_only_fallback_selection(self):\n \"\"\"Test auto mode fallback when only XAI is available.\"\"\"\n\n # Save original environment\n original_env = {}\n for key in [\"GEMINI_API_KEY\", \"OPENAI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]:\n original_env[key] = os.environ.get(key)\n\n try:\n # Set up environment - only XAI available\n os.environ[\"XAI_API_KEY\"] = \"test-key\"\n for key in [\"GEMINI_API_KEY\", \"OPENAI_API_KEY\", \"OPENROUTER_API_KEY\"]:\n os.environ.pop(key, None)\n\n # Register only XAI provider\n from providers.xai import XAIModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.XAI, XAIModelProvider)\n\n # Test fallback selection for different categories\n extended_reasoning = ModelProviderRegistry.get_preferred_fallback_model(\n ToolModelCategory.EXTENDED_REASONING\n )\n fast_response = ModelProviderRegistry.get_preferred_fallback_model(ToolModelCategory.FAST_RESPONSE)\n\n # Should fallback to available models or default fallbacks\n # Since XAI models are not explicitly handled in fallback logic,\n # it should fall back to the hardcoded defaults\n assert extended_reasoning is not None\n assert fast_response is not None\n\n finally:\n # Restore original environment\n for key, value in original_env.items():\n if value is not None:\n os.environ[key] = value\n else:\n os.environ.pop(key, None)\n\n def test_available_models_respects_restrictions(self):\n \"\"\"Test that get_available_models respects model restrictions.\"\"\"\n\n # Save original environment\n original_env = {}\n for key in [\"GEMINI_API_KEY\", \"OPENAI_API_KEY\", \"OPENAI_ALLOWED_MODELS\"]:\n original_env[key] = os.environ.get(key)\n\n try:\n # Set up environment with restrictions\n os.environ[\"GEMINI_API_KEY\"] = \"test-key\"\n os.environ[\"OPENAI_API_KEY\"] = \"test-key\"\n os.environ[\"OPENAI_ALLOWED_MODELS\"] = \"o4-mini\" # Only allow o4-mini\n\n # Clear restriction service to pick up new restrictions\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n # Register both providers\n from providers.gemini import GeminiModelProvider\n from providers.openai import OpenAIModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n\n # Get available models with restrictions\n available_models = ModelProviderRegistry.get_available_models(respect_restrictions=True)\n\n # Should include allowed OpenAI model\n assert \"o4-mini\" in available_models\n assert available_models[\"o4-mini\"] == ProviderType.OPENAI\n\n # Should NOT include restricted OpenAI models\n assert \"o3\" not in available_models\n assert \"o3-mini\" not in available_models\n\n # Should include all Gemini models (no restrictions)\n assert \"gemini-2.5-flash\" in available_models\n assert available_models[\"gemini-2.5-flash\"] == ProviderType.GOOGLE\n\n finally:\n # Restore original environment\n for key, value in original_env.items():\n if value is not None:\n os.environ[key] = value\n else:\n os.environ.pop(key, None)\n\n def test_model_validation_across_providers(self):\n \"\"\"Test that model validation works correctly across different providers.\"\"\"\n\n # Save original environment\n original_env = {}\n for key in [\"GEMINI_API_KEY\", \"OPENAI_API_KEY\", \"XAI_API_KEY\"]:\n original_env[key] = os.environ.get(key)\n\n try:\n # Set up all providers\n os.environ[\"GEMINI_API_KEY\"] = \"test-key\"\n os.environ[\"OPENAI_API_KEY\"] = \"test-key\"\n os.environ[\"XAI_API_KEY\"] = \"test-key\"\n\n # Register all providers\n from providers.gemini import GeminiModelProvider\n from providers.openai import OpenAIModelProvider\n from providers.xai import XAIModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.XAI, XAIModelProvider)\n\n # Test model validation - each provider should handle its own models\n # Gemini models\n gemini_provider = ModelProviderRegistry.get_provider_for_model(\"flash\")\n assert gemini_provider is not None\n assert gemini_provider.get_provider_type() == ProviderType.GOOGLE\n\n # OpenAI models\n openai_provider = ModelProviderRegistry.get_provider_for_model(\"o3\")\n assert openai_provider is not None\n assert openai_provider.get_provider_type() == ProviderType.OPENAI\n\n # XAI models\n xai_provider = ModelProviderRegistry.get_provider_for_model(\"grok\")\n assert xai_provider is not None\n assert xai_provider.get_provider_type() == ProviderType.XAI\n\n # Invalid model should return None\n invalid_provider = ModelProviderRegistry.get_provider_for_model(\"invalid-model-name\")\n assert invalid_provider is None\n\n finally:\n # Restore original environment\n for key, value in original_env.items():\n if value is not None:\n os.environ[key] = value\n else:\n os.environ.pop(key, None)\n\n def test_alias_resolution_before_api_calls(self):\n \"\"\"Test that model aliases are resolved before being passed to providers.\"\"\"\n\n # Save original environment\n original_env = {}\n for key in [\"GEMINI_API_KEY\", \"OPENAI_API_KEY\", \"XAI_API_KEY\"]:\n original_env[key] = os.environ.get(key)\n\n try:\n # Set up all providers\n os.environ[\"GEMINI_API_KEY\"] = \"test-key\"\n os.environ[\"OPENAI_API_KEY\"] = \"test-key\"\n os.environ[\"XAI_API_KEY\"] = \"test-key\"\n\n # Register all providers\n from providers.gemini import GeminiModelProvider\n from providers.openai import OpenAIModelProvider\n from providers.xai import XAIModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.XAI, XAIModelProvider)\n\n # Test that providers resolve aliases correctly\n test_cases = [\n (\"flash\", ProviderType.GOOGLE, \"gemini-2.5-flash\"),\n (\"pro\", ProviderType.GOOGLE, \"gemini-3-pro-preview\"), # \"pro\" now resolves to gemini-3-pro-preview\n (\"mini\", ProviderType.OPENAI, \"gpt-5-mini\"), # \"mini\" now resolves to gpt-5-mini\n (\"o3mini\", ProviderType.OPENAI, \"o3-mini\"),\n (\"grok\", ProviderType.XAI, \"grok-4\"),\n (\"grok-4.1-fast-reasoning\", ProviderType.XAI, \"grok-4-1-fast-reasoning\"),\n ]\n\n for alias, expected_provider_type, expected_resolved_name in test_cases:\n provider = ModelProviderRegistry.get_provider_for_model(alias)\n assert provider is not None, f\"No provider found for alias '{alias}'\"\n assert provider.get_provider_type() == expected_provider_type, f\"Wrong provider for '{alias}'\"\n\n # Test alias resolution\n resolved_model_name = provider._resolve_model_name(alias)\n assert (\n resolved_model_name == expected_resolved_name\n ), f\"Alias '{alias}' should resolve to '{expected_resolved_name}', got '{resolved_model_name}'\"\n\n finally:\n # Restore original environment\n for key, value in original_env.items():\n if value is not None:\n os.environ[key] = value\n else:\n os.environ.pop(key, None)\n" }, { "path": "tests/test_auto_model_planner_fix.py", "content": "\"\"\"\nUnit tests for the auto model planner fix.\n\nThis test confirms that the planner tool no longer fails when DEFAULT_MODEL is \"auto\"\nand only basic providers (Google/OpenAI) are configured, while ensuring other tools\nstill properly require model resolution.\n\"\"\"\n\nfrom unittest.mock import patch\n\nfrom mcp.types import TextContent\n\nfrom tools.chat import ChatTool\nfrom tools.planner import PlannerTool\nfrom tools.shared.base_tool import BaseTool\n\n\nclass TestAutoModelPlannerFix:\n \"\"\"Test the fix for auto model resolution with planner tool.\"\"\"\n\n def test_planner_requires_model_false(self):\n \"\"\"Test that planner tool returns False for requires_model.\"\"\"\n planner = PlannerTool()\n assert planner.requires_model() is False\n\n def test_chat_requires_model_true(self):\n \"\"\"Test that chat tool returns True for requires_model (default behavior).\"\"\"\n chat = ChatTool()\n assert chat.requires_model() is True\n\n def test_base_tool_requires_model_default(self):\n \"\"\"Test that BaseTool default implementation returns True.\"\"\"\n\n # Create a mock tool that doesn't override requires_model\n class MockTool(BaseTool):\n def get_name(self):\n return \"mock\"\n\n def get_description(self):\n return \"Mock tool\"\n\n def get_input_schema(self):\n return {}\n\n def get_system_prompt(self):\n return \"Mock prompt\"\n\n def get_request_model(self):\n from tools.shared.base_models import ToolRequest\n\n return ToolRequest\n\n async def prepare_prompt(self, request):\n return \"Mock prompt\"\n\n mock_tool = MockTool()\n assert mock_tool.requires_model() is True\n\n @patch(\"config.DEFAULT_MODEL\", \"auto\")\n @patch(\"providers.registry.ModelProviderRegistry.get_provider_for_model\")\n def test_auto_model_error_before_fix_simulation(self, mock_get_provider):\n \"\"\"\n Simulate the error that would occur before the fix.\n\n This test simulates what would happen if server.py didn't check requires_model()\n and tried to resolve \"auto\" as a literal model name.\n \"\"\"\n # Mock the scenario where no provider is found for \"auto\"\n mock_get_provider.return_value = None\n\n # This should return None, simulating the \"No provider found for model auto\" error\n result = mock_get_provider(\"auto\")\n assert result is None\n\n # Verify that the mock was called with \"auto\"\n mock_get_provider.assert_called_with(\"auto\")\n\n @patch(\"server.DEFAULT_MODEL\", \"auto\")\n async def test_planner_execution_bypasses_model_resolution(self):\n \"\"\"\n Test that planner tool execution works even when DEFAULT_MODEL is \"auto\".\n\n This test confirms that the fix allows planner to work regardless of\n model configuration since it doesn't need model resolution.\n \"\"\"\n planner = PlannerTool()\n\n # Test with minimal planner arguments\n arguments = {\"step\": \"Test planning step\", \"step_number\": 1, \"total_steps\": 1, \"next_step_required\": False}\n\n # This should work without any model resolution\n result = await planner.execute(arguments)\n\n # Verify we got a result\n assert isinstance(result, list)\n assert len(result) > 0\n assert isinstance(result[0], TextContent)\n\n # Parse the JSON response to verify it's valid\n import json\n\n response_data = json.loads(result[0].text)\n assert response_data[\"status\"] == \"planning_complete\"\n assert response_data[\"step_number\"] == 1\n\n @patch(\"config.DEFAULT_MODEL\", \"auto\")\n def test_server_model_resolution_logic(self):\n \"\"\"\n Test the server-side logic that checks requires_model() before model resolution.\n\n This simulates the key fix in server.py where we check tool.requires_model()\n before attempting model resolution.\n \"\"\"\n planner = PlannerTool()\n chat = ChatTool()\n\n # Simulate the server logic\n def simulate_server_model_resolution(tool, model_name):\n \"\"\"Simulate the fixed server logic from server.py\"\"\"\n if not tool.requires_model():\n # Skip model resolution for tools that don't require models\n return \"SKIP_MODEL_RESOLUTION\"\n else:\n # Would normally do model resolution here\n return f\"RESOLVE_MODEL_{model_name}\"\n\n # Test planner (should skip model resolution)\n result = simulate_server_model_resolution(planner, \"auto\")\n assert result == \"SKIP_MODEL_RESOLUTION\"\n\n # Test chat (should attempt model resolution)\n result = simulate_server_model_resolution(chat, \"auto\")\n assert result == \"RESOLVE_MODEL_auto\"\n\n def test_provider_registry_auto_handling(self):\n \"\"\"\n Test that the provider registry correctly handles model resolution.\n\n This tests the scenario where providers don't recognize \"auto\" as a model.\n \"\"\"\n from providers.registry import ModelProviderRegistry\n\n # This should return None since \"auto\" is not a real model name\n provider = ModelProviderRegistry.get_provider_for_model(\"auto\")\n assert provider is None, \"Provider registry should not find a provider for literal 'auto'\"\n\n @patch(\"config.DEFAULT_MODEL\", \"auto\")\n async def test_end_to_end_planner_with_auto_mode(self):\n \"\"\"\n End-to-end test of planner tool execution in auto mode.\n\n This test verifies that the complete flow works when DEFAULT_MODEL is \"auto\"\n and the planner tool is used.\n \"\"\"\n planner = PlannerTool()\n\n # Verify the tool doesn't require model resolution\n assert not planner.requires_model()\n\n # Test a multi-step planning scenario\n step1_args = {\n \"step\": \"Analyze the current system architecture\",\n \"step_number\": 1,\n \"total_steps\": 3,\n \"next_step_required\": True,\n }\n\n result1 = await planner.execute(step1_args)\n assert len(result1) > 0\n\n # Parse and verify the response\n import json\n\n response1 = json.loads(result1[0].text)\n assert response1[\"status\"] == \"pause_for_planning\"\n assert response1[\"next_step_required\"] is True\n assert \"continuation_id\" in response1\n\n # Test step 2 with continuation\n continuation_id = response1[\"continuation_id\"]\n step2_args = {\n \"step\": \"Design the microservices architecture\",\n \"step_number\": 2,\n \"total_steps\": 3,\n \"next_step_required\": True,\n \"continuation_id\": continuation_id,\n }\n\n result2 = await planner.execute(step2_args)\n assert len(result2) > 0\n\n response2 = json.loads(result2[0].text)\n assert response2[\"status\"] == \"pause_for_planning\"\n assert response2[\"step_number\"] == 2\n\n def test_other_tools_still_require_models(self):\n \"\"\"\n Verify that other tools still properly require model resolution.\n\n This ensures our fix doesn't break existing functionality.\n Note: Debug tool requires model resolution for expert analysis phase.\n \"\"\"\n from tools.analyze import AnalyzeTool\n from tools.chat import ChatTool\n from tools.debug import DebugIssueTool\n\n # Test various tools still require models\n tools_requiring_models = [ChatTool(), AnalyzeTool(), DebugIssueTool()]\n\n for tool in tools_requiring_models:\n assert tool.requires_model() is True, f\"{tool.get_name()} should require model resolution\"\n\n # Note: Debug tool requires model resolution for expert analysis phase\n # Only planner truly manages its own model calls and doesn't need resolution\n" }, { "path": "tests/test_azure_openai_provider.py", "content": "import sys\nimport types\n\nimport pytest\n\nif \"openai\" not in sys.modules: # pragma: no cover - test shim for optional dependency\n stub = types.ModuleType(\"openai\")\n stub.AzureOpenAI = object # Replaced with a mock inside tests\n sys.modules[\"openai\"] = stub\n\nfrom providers.azure_openai import AzureOpenAIProvider\nfrom providers.shared import ModelCapabilities, ProviderType\n\n\nclass _DummyResponse:\n def __init__(self):\n self.choices = [\n types.SimpleNamespace(\n message=types.SimpleNamespace(content=\"hello\"),\n finish_reason=\"stop\",\n )\n ]\n self.model = \"prod-gpt4o\"\n self.id = \"resp-123\"\n self.created = 0\n self.usage = types.SimpleNamespace(\n prompt_tokens=5,\n completion_tokens=3,\n total_tokens=8,\n )\n\n\n@pytest.fixture\ndef dummy_azure_client(monkeypatch):\n captured = {}\n\n class _DummyAzureClient:\n def __init__(self, **kwargs):\n captured[\"client_kwargs\"] = kwargs\n self.chat = types.SimpleNamespace(completions=types.SimpleNamespace(create=self._create_completion))\n self.responses = types.SimpleNamespace(create=self._create_response)\n\n def _create_completion(self, **kwargs):\n captured[\"request_kwargs\"] = kwargs\n return _DummyResponse()\n\n def _create_response(self, **kwargs):\n captured[\"responses_kwargs\"] = kwargs\n return _DummyResponse()\n\n monkeypatch.delenv(\"AZURE_OPENAI_ALLOWED_MODELS\", raising=False)\n monkeypatch.setattr(\"providers.azure_openai.AzureOpenAI\", _DummyAzureClient)\n return captured\n\n\ndef test_generate_content_uses_deployment_mapping(dummy_azure_client):\n provider = AzureOpenAIProvider(\n api_key=\"key\",\n azure_endpoint=\"https://example.openai.azure.com/\",\n deployments={\"gpt-4o\": \"prod-gpt4o\"},\n )\n\n result = provider.generate_content(\"hello\", \"gpt-4o\")\n\n assert dummy_azure_client[\"request_kwargs\"][\"model\"] == \"prod-gpt4o\"\n assert result.model_name == \"gpt-4o\"\n assert result.provider == ProviderType.AZURE\n assert provider.validate_model_name(\"prod-gpt4o\")\n\n\ndef test_generate_content_accepts_deployment_alias(dummy_azure_client):\n provider = AzureOpenAIProvider(\n api_key=\"key\",\n azure_endpoint=\"https://example.openai.azure.com/\",\n deployments={\"gpt-4o-mini\": \"mini-deployment\"},\n )\n\n # Calling with the deployment alias should still resolve properly.\n result = provider.generate_content(\"hi\", \"mini-deployment\")\n\n assert dummy_azure_client[\"request_kwargs\"][\"model\"] == \"mini-deployment\"\n assert result.model_name == \"gpt-4o-mini\"\n\n\ndef test_client_initialization_uses_endpoint_and_version(dummy_azure_client):\n provider = AzureOpenAIProvider(\n api_key=\"key\",\n azure_endpoint=\"https://example.openai.azure.com/\",\n api_version=\"2024-03-15-preview\",\n deployments={\"gpt-4o\": \"prod\"},\n )\n\n _ = provider.client\n\n assert dummy_azure_client[\"client_kwargs\"][\"azure_endpoint\"] == \"https://example.openai.azure.com\"\n assert dummy_azure_client[\"client_kwargs\"][\"api_version\"] == \"2024-03-15-preview\"\n\n\ndef test_deployment_overrides_capabilities(dummy_azure_client):\n provider = AzureOpenAIProvider(\n api_key=\"key\",\n azure_endpoint=\"https://example.openai.azure.com/\",\n deployments={\n \"gpt-4o\": {\n \"deployment\": \"prod-gpt4o\",\n \"friendly_name\": \"Azure GPT-4o EU\",\n \"intelligence_score\": 19,\n \"supports_temperature\": False,\n \"temperature_constraint\": \"fixed\",\n }\n },\n )\n\n caps = provider.get_capabilities(\"gpt-4o\")\n assert caps.friendly_name == \"Azure GPT-4o EU\"\n assert caps.intelligence_score == 19\n assert not caps.supports_temperature\n\n\ndef test_registry_configuration_merges_capabilities(dummy_azure_client, monkeypatch):\n def fake_registry_entries(self):\n capability = ModelCapabilities(\n provider=ProviderType.AZURE,\n model_name=\"gpt-4o\",\n friendly_name=\"Azure GPT-4o Registry\",\n context_window=500_000,\n max_output_tokens=128_000,\n )\n return {\"gpt-4o\": {\"deployment\": \"registry-deployment\", \"capability\": capability}}\n\n monkeypatch.setattr(AzureOpenAIProvider, \"_load_registry_entries\", fake_registry_entries)\n\n provider = AzureOpenAIProvider(\n api_key=\"key\",\n azure_endpoint=\"https://example.openai.azure.com/\",\n )\n\n # Capability should come from registry\n caps = provider.get_capabilities(\"gpt-4o\")\n assert caps.friendly_name == \"Azure GPT-4o Registry\"\n assert caps.context_window == 500_000\n\n # API call should use deployment defined in registry\n provider.generate_content(\"hello\", \"gpt-4o\")\n assert dummy_azure_client[\"request_kwargs\"][\"model\"] == \"registry-deployment\"\n" }, { "path": "tests/test_buggy_behavior_prevention.py", "content": "\"\"\"\nRegression scenarios ensuring alias-aware model listings stay correct.\n\nEach test captures behavior that previously regressed so we can guard it\npermanently. The focus is confirming aliases and their canonical targets\nremain visible to the restriction service and related validation logic.\n\"\"\"\n\nimport os\nfrom unittest.mock import MagicMock, patch\n\nimport pytest\n\nfrom providers.gemini import GeminiModelProvider\nfrom providers.openai import OpenAIModelProvider\nfrom providers.shared import ProviderType\nfrom utils.model_restrictions import ModelRestrictionService\n\n\nclass TestBuggyBehaviorPrevention:\n \"\"\"Regression tests for alias-aware restriction validation.\"\"\"\n\n def test_alias_listing_includes_targets_for_restriction_validation(self):\n \"\"\"Alias-aware lists expose both aliases and canonical targets.\"\"\"\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Baseline alias-only list captured for regression documentation\n alias_only_snapshot = [\"mini\", \"o3mini\"] # Missing 'o4-mini', 'o3-mini' targets\n\n # Canonical listing with aliases and targets\n comprehensive_list = provider.list_models(\n respect_restrictions=False,\n include_aliases=True,\n lowercase=True,\n unique=True,\n )\n\n # Comprehensive listing should contain aliases and their targets\n assert \"mini\" in comprehensive_list\n assert \"o4-mini\" in comprehensive_list\n assert \"o3mini\" in comprehensive_list\n assert \"o3-mini\" in comprehensive_list\n\n # Legacy alias-only snapshots exclude targets\n assert \"o4-mini\" not in alias_only_snapshot\n assert \"o3-mini\" not in alias_only_snapshot\n\n # This scenario previously failed when targets were omitted\n service = ModelRestrictionService()\n service.restrictions = {ProviderType.OPENAI: {\"o4-mini\"}} # Restrict to target\n\n with patch(\"utils.model_restrictions.logger\") as mock_logger:\n provider_instances = {ProviderType.OPENAI: provider}\n service.validate_against_known_models(provider_instances)\n\n # No warnings expected because alias-aware list includes the target\n target_warnings = [\n call\n for call in mock_logger.warning.call_args_list\n if \"o4-mini\" in str(call) and \"not a recognized\" in str(call)\n ]\n assert len(target_warnings) == 0, \"o4-mini should be recognized as a valid target\"\n\n def test_target_models_are_recognized_during_validation(self):\n \"\"\"Target model restrictions should not trigger false warnings.\"\"\"\n # Test with Gemini provider too\n provider = GeminiModelProvider(api_key=\"test-key\")\n all_known = provider.list_models(respect_restrictions=False, include_aliases=True, lowercase=True, unique=True)\n\n # Verify both aliases and targets are included\n assert \"flash\" in all_known # alias\n assert \"gemini-2.5-flash\" in all_known # target\n assert \"pro\" in all_known # alias\n assert \"gemini-2.5-pro\" in all_known # target\n\n # Simulate admin restricting to target model names\n service = ModelRestrictionService()\n service.restrictions = {\n ProviderType.GOOGLE: {\n \"gemini-2.5-flash\", # Target name restriction\n \"gemini-2.5-pro\", # Target name restriction\n }\n }\n\n with patch(\"utils.model_restrictions.logger\") as mock_logger:\n provider_instances = {ProviderType.GOOGLE: provider}\n service.validate_against_known_models(provider_instances)\n\n # Should NOT warn about these valid target models\n all_warnings = [str(call) for call in mock_logger.warning.call_args_list]\n for warning in all_warnings:\n assert \"gemini-2.5-flash\" not in warning or \"not a recognized\" not in warning\n assert \"gemini-2.5-pro\" not in warning or \"not a recognized\" not in warning\n\n def test_policy_enforcement_remains_comprehensive(self):\n \"\"\"Policy validation must account for both aliases and targets.\"\"\"\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Simulate a scenario where admin wants to restrict specific targets\n with patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"o3-mini,o4-mini\"}):\n # Clear cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n # These should work because they're explicitly allowed\n assert provider.validate_model_name(\"o3-mini\")\n assert provider.validate_model_name(\"o4-mini\")\n\n # These should be blocked\n assert not provider.validate_model_name(\"o3-pro\") # Not in allowed list\n assert not provider.validate_model_name(\"o3\") # Not in allowed list\n\n # \"mini\" now resolves to gpt-5-mini, not o4-mini, so it should be blocked\n assert not provider.validate_model_name(\"mini\") # Resolves to gpt-5-mini, which is NOT allowed\n\n # But o4mini (the actual alias for o4-mini) should work\n assert provider.validate_model_name(\"o4mini\") # Resolves to o4-mini, which IS allowed\n\n # Verify our alias-aware list includes the restricted models\n all_known = provider.list_models(\n respect_restrictions=False,\n include_aliases=True,\n lowercase=True,\n unique=True,\n )\n assert \"o3-mini\" in all_known # Should be known (and allowed)\n assert \"o4-mini\" in all_known # Should be known (and allowed)\n assert \"o3-pro\" in all_known # Should be known (but blocked)\n assert \"mini\" in all_known # Should be known (and allowed since it resolves to o4-mini)\n\n def test_alias_aware_listing_extends_canonical_view(self):\n \"\"\"Alias-aware list should be a superset of restriction-filtered names.\"\"\"\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n baseline_models = provider.list_models(respect_restrictions=False)\n\n alias_aware_models = provider.list_models(\n respect_restrictions=False,\n include_aliases=True,\n lowercase=True,\n unique=True,\n )\n\n # Alias-aware variant should contain everything from the baseline\n for model in baseline_models:\n assert model.lower() in [\n m.lower() for m in alias_aware_models\n ], f\"Alias-aware listing missing baseline model {model}\"\n\n # Alias-aware variant should include canonical targets as well\n for target in (\"o4-mini\", \"o3-mini\"):\n assert target in alias_aware_models, f\"Alias-aware listing should include target model {target}\"\n\n def test_restriction_validation_uses_alias_aware_variant(self):\n \"\"\"Validation should request the alias-aware lowercased, deduped list.\"\"\"\n service = ModelRestrictionService()\n\n # Simulate a provider that only returns aliases when asked for models\n alias_only_provider = MagicMock()\n alias_only_provider.MODEL_CAPABILITIES = {\n \"mini\": \"o4-mini\",\n \"o3mini\": \"o3-mini\",\n \"o4-mini\": {\"context_window\": 200000},\n \"o3-mini\": {\"context_window\": 200000},\n }\n\n # Simulate alias-only vs. alias-aware behavior using a side effect\n def list_models_side_effect(**kwargs):\n respect_restrictions = kwargs.get(\"respect_restrictions\", True)\n include_aliases = kwargs.get(\"include_aliases\", True)\n lowercase = kwargs.get(\"lowercase\", False)\n unique = kwargs.get(\"unique\", False)\n\n if respect_restrictions and include_aliases and not lowercase and not unique:\n return [\"mini\", \"o3mini\"]\n\n if not respect_restrictions and include_aliases and lowercase and unique:\n return [\"mini\", \"o3mini\", \"o4-mini\", \"o3-mini\"]\n\n raise AssertionError(f\"Unexpected list_models call: {kwargs}\")\n\n alias_only_provider.list_models.side_effect = list_models_side_effect\n\n # Test that validation now uses the comprehensive method\n service.restrictions = {ProviderType.OPENAI: {\"o4-mini\"}} # Restrict to target\n\n with patch(\"utils.model_restrictions.logger\") as mock_logger:\n provider_instances = {ProviderType.OPENAI: alias_only_provider}\n service.validate_against_known_models(provider_instances)\n\n # Verify the alias-aware variant was used\n alias_only_provider.list_models.assert_called_with(\n respect_restrictions=False,\n include_aliases=True,\n lowercase=True,\n unique=True,\n )\n\n # Should not warn about o4-mini being unrecognized\n target_warnings = [\n call\n for call in mock_logger.warning.call_args_list\n if \"o4-mini\" in str(call) and \"not a recognized\" in str(call)\n ]\n assert len(target_warnings) == 0\n\n def test_alias_listing_covers_targets_for_all_providers(self):\n \"\"\"Alias-aware listings should expose targets across providers.\"\"\"\n providers_to_test = [\n (OpenAIModelProvider(api_key=\"test-key\"), \"mini\", \"o4-mini\"),\n (GeminiModelProvider(api_key=\"test-key\"), \"flash\", \"gemini-2.5-flash\"),\n ]\n\n for provider, alias, target in providers_to_test:\n all_known = provider.list_models(\n respect_restrictions=False, include_aliases=True, lowercase=True, unique=True\n )\n\n # Every provider should include both aliases and targets\n assert alias in all_known, f\"{provider.__class__.__name__} missing alias {alias}\"\n assert target in all_known, f\"{provider.__class__.__name__} missing target {target}\"\n\n # No duplicates should exist\n assert len(all_known) == len(set(all_known)), f\"{provider.__class__.__name__} returns duplicate models\"\n\n @patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"o4-mini,invalid-model\"})\n def test_validation_correctly_identifies_invalid_models(self):\n \"\"\"Validation should flag invalid models while listing valid targets.\"\"\"\n # Clear cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n service = ModelRestrictionService()\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n with patch(\"utils.model_restrictions.logger\") as mock_logger:\n provider_instances = {ProviderType.OPENAI: provider}\n service.validate_against_known_models(provider_instances)\n\n invalid_warnings = [\n call\n for call in mock_logger.warning.call_args_list\n if \"invalid-model\" in str(call) and \"not a recognized\" in str(call)\n ]\n assert len(invalid_warnings) > 0, \"Should warn about truly invalid models\"\n\n # The warning should mention o4-mini in the known models list\n warning_text = str(mock_logger.warning.call_args_list[0])\n assert \"Known models:\" in warning_text, \"Warning should include known models list\"\n assert \"o4-mini\" in warning_text, \"o4-mini should appear in known models\"\n assert \"o3-mini\" in warning_text, \"o3-mini should appear in known models\"\n\n # But the warning should be specifically about invalid-model\n assert \"'invalid-model'\" in warning_text, \"Warning should specifically mention invalid-model\"\n\n def test_custom_provider_alias_listing(self):\n \"\"\"Custom provider should expose alias-aware listings as well.\"\"\"\n from providers.custom import CustomProvider\n\n # This might fail if no URL is set, but that's expected\n try:\n provider = CustomProvider(base_url=\"http://test.com/v1\")\n all_known = provider.list_models(\n respect_restrictions=False, include_aliases=True, lowercase=True, unique=True\n )\n # Should return a list (might be empty if registry not loaded)\n assert isinstance(all_known, list)\n except ValueError:\n # Expected if no base_url configured, skip this test\n pytest.skip(\"Custom provider requires URL configuration\")\n\n def test_openrouter_provider_alias_listing(self):\n \"\"\"OpenRouter provider should expose alias-aware listings.\"\"\"\n from providers.openrouter import OpenRouterProvider\n\n provider = OpenRouterProvider(api_key=\"test-key\")\n all_known = provider.list_models(respect_restrictions=False, include_aliases=True, lowercase=True, unique=True)\n\n # Should return a list with both aliases and targets\n assert isinstance(all_known, list)\n # Should include some known OpenRouter aliases and their targets\n # (Exact content depends on registry, but structure should be correct)\n" }, { "path": "tests/test_cassette_semantic_matching.py", "content": "\"\"\"\nTests for cassette semantic matching to prevent breaks from prompt changes.\n\nThis validates that o3 model cassettes match on semantic content (model + user question)\nrather than exact request bodies, preventing cassette breaks when system prompts change.\n\"\"\"\n\nimport hashlib\nimport json\n\nimport pytest\n\nfrom tests.http_transport_recorder import ReplayTransport\n\n\nclass TestCassetteSemanticMatching:\n \"\"\"Test that cassette matching is resilient to prompt changes.\"\"\"\n\n @pytest.fixture\n def dummy_cassette(self, tmp_path):\n \"\"\"Create a minimal dummy cassette file.\"\"\"\n cassette_file = tmp_path / \"dummy.json\"\n cassette_file.write_text(json.dumps({\"interactions\": []}))\n return cassette_file\n\n def test_o3_model_semantic_matching(self, dummy_cassette):\n \"\"\"Test that o3 models use semantic matching.\"\"\"\n transport = ReplayTransport(str(dummy_cassette))\n\n # Two requests with same user question but different system prompts\n request1_body = {\n \"model\": \"o3-pro\",\n \"reasoning\": {\"effort\": \"medium\"},\n \"input\": [\n {\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"input_text\",\n \"text\": \"System prompt v1...\\n\\n=== USER REQUEST ===\\nWhat is 2 + 2?\\n=== END REQUEST ===\\n\\nMore instructions...\",\n }\n ],\n }\n ],\n }\n\n request2_body = {\n \"model\": \"o3-pro\",\n \"reasoning\": {\"effort\": \"medium\"},\n \"input\": [\n {\n \"role\": \"user\",\n \"content\": [\n {\n \"type\": \"input_text\",\n \"text\": \"System prompt v2 (DIFFERENT)...\\n\\n=== USER REQUEST ===\\nWhat is 2 + 2?\\n=== END REQUEST ===\\n\\nDifferent instructions...\",\n }\n ],\n }\n ],\n }\n\n # Extract semantic fields - should be identical\n semantic1 = transport._extract_semantic_fields(request1_body)\n semantic2 = transport._extract_semantic_fields(request2_body)\n\n assert semantic1 == semantic2, \"Semantic fields should match despite different prompts\"\n assert semantic1[\"user_question\"] == \"What is 2 + 2?\"\n assert semantic1[\"model\"] == \"o3-pro\"\n assert semantic1[\"reasoning\"] == {\"effort\": \"medium\"}\n\n # Generate signatures - should be identical\n content1 = json.dumps(semantic1, sort_keys=True)\n content2 = json.dumps(semantic2, sort_keys=True)\n hash1 = hashlib.md5(content1.encode()).hexdigest()\n hash2 = hashlib.md5(content2.encode()).hexdigest()\n\n assert hash1 == hash2, \"Hashes should match for same semantic content\"\n\n def test_non_o3_model_exact_matching(self, dummy_cassette):\n \"\"\"Test that non-o3 models still use exact matching.\"\"\"\n transport = ReplayTransport(str(dummy_cassette))\n\n request_body = {\n \"model\": \"gpt-4\",\n \"messages\": [{\"role\": \"user\", \"content\": \"test\"}],\n }\n\n # Should not use semantic matching\n assert not transport._is_o3_model_request(request_body)\n\n def test_o3_mini_semantic_matching(self, dummy_cassette):\n \"\"\"Test that o3-mini also uses semantic matching.\"\"\"\n transport = ReplayTransport(str(dummy_cassette))\n\n request_body = {\n \"model\": \"o3-mini\",\n \"reasoning\": {\"effort\": \"low\"},\n \"input\": [\n {\n \"role\": \"user\",\n \"content\": [\n {\"type\": \"input_text\", \"text\": \"System...\\n\\n=== USER REQUEST ===\\nTest\\n=== END REQUEST ===\"}\n ],\n }\n ],\n }\n\n assert transport._is_o3_model_request(request_body)\n semantic = transport._extract_semantic_fields(request_body)\n assert semantic[\"model\"] == \"o3-mini\"\n assert semantic[\"user_question\"] == \"Test\"\n\n def test_o3_without_request_markers(self, dummy_cassette):\n \"\"\"Test o3 requests without REQUEST markers fall back to full text.\"\"\"\n transport = ReplayTransport(str(dummy_cassette))\n\n request_body = {\n \"model\": \"o3-pro\",\n \"reasoning\": {\"effort\": \"medium\"},\n \"input\": [{\"role\": \"user\", \"content\": [{\"type\": \"input_text\", \"text\": \"Just a simple question\"}]}],\n }\n\n semantic = transport._extract_semantic_fields(request_body)\n assert semantic[\"user_question\"] == \"Just a simple question\"\n" }, { "path": "tests/test_challenge.py", "content": "\"\"\"\nTests for Challenge tool - validating critical challenge prompt wrapper\n\nThis module contains unit tests to ensure that the Challenge tool\nproperly wraps statements to encourage critical thinking and avoid\nautomatic agreement patterns.\n\"\"\"\n\nimport json\nfrom unittest.mock import patch\n\nimport pytest\n\nfrom tools.challenge import ChallengeRequest, ChallengeTool\nfrom tools.shared.exceptions import ToolExecutionError\n\n\nclass TestChallengeTool:\n \"\"\"Test suite for Challenge tool\"\"\"\n\n def setup_method(self):\n \"\"\"Set up test fixtures\"\"\"\n self.tool = ChallengeTool()\n\n def test_tool_metadata(self):\n \"\"\"Test that tool metadata matches requirements\"\"\"\n assert self.tool.get_name() == \"challenge\"\n assert \"reflexive agreement\" in self.tool.get_description()\n assert \"critical thinking\" in self.tool.get_description()\n assert \"reasoned analysis\" in self.tool.get_description()\n assert self.tool.get_default_temperature() == 1.0 # TEMPERATURE_ANALYTICAL\n\n def test_requires_model(self):\n \"\"\"Test that challenge tool doesn't require a model\"\"\"\n assert self.tool.requires_model() is False\n\n def test_schema_structure(self):\n \"\"\"Test that schema has correct structure and excludes model fields\"\"\"\n schema = self.tool.get_input_schema()\n\n # Basic schema structure\n assert schema[\"type\"] == \"object\"\n assert \"properties\" in schema\n assert \"required\" in schema\n\n # Required fields\n assert \"prompt\" in schema[\"required\"]\n assert len(schema[\"required\"]) == 1 # Only prompt is required\n\n # Properties\n properties = schema[\"properties\"]\n assert \"prompt\" in properties\n\n # Should NOT have model-related fields since it doesn't require a model\n assert \"model\" not in properties\n assert \"temperature\" not in properties\n assert \"thinking_mode\" not in properties\n assert \"continuation_id\" not in properties\n\n def test_request_model_validation(self):\n \"\"\"Test that the request model validates correctly\"\"\"\n # Test valid request\n request = ChallengeRequest(prompt=\"The sky is green\")\n assert request.prompt == \"The sky is green\"\n\n # Test with longer prompt\n long_prompt = (\n \"Machine learning models always produce accurate results and should be trusted without verification\"\n )\n request = ChallengeRequest(prompt=long_prompt)\n assert request.prompt == long_prompt\n\n def test_required_fields(self):\n \"\"\"Test that required fields are enforced\"\"\"\n from pydantic import ValidationError\n\n # Missing prompt should raise validation error\n with pytest.raises(ValidationError):\n ChallengeRequest()\n\n @pytest.mark.asyncio\n async def test_execute_success(self):\n \"\"\"Test successful execution of challenge tool\"\"\"\n arguments = {\"prompt\": \"All software bugs are caused by syntax errors\"}\n\n result = await self.tool.execute(arguments)\n\n # Should return a list with TextContent\n assert len(result) == 1\n assert result[0].type == \"text\"\n\n # Parse the JSON response\n response_data = json.loads(result[0].text)\n\n # Check response structure\n assert response_data[\"status\"] == \"challenge_accepted\"\n assert response_data[\"original_statement\"] == \"All software bugs are caused by syntax errors\"\n assert \"challenge_prompt\" in response_data\n assert \"instructions\" in response_data\n\n # Check that the challenge prompt contains critical thinking instructions\n challenge_prompt = response_data[\"challenge_prompt\"]\n assert \"CRITICAL REASSESSMENT – Do not automatically agree\" in challenge_prompt\n assert \"Carefully evaluate the statement above\" in challenge_prompt\n assert response_data[\"original_statement\"] in challenge_prompt\n assert \"flaws, gaps, or misleading points\" in challenge_prompt\n assert \"thoughtful analysis\" in challenge_prompt\n\n @pytest.mark.asyncio\n async def test_execute_error_handling(self):\n \"\"\"Test error handling in execute method\"\"\"\n # Test with invalid arguments (non-dict)\n with patch.object(self.tool, \"get_request_model\", side_effect=Exception(\"Test error\")):\n with pytest.raises(ToolExecutionError) as exc_info:\n await self.tool.execute({\"prompt\": \"test\"})\n\n response_data = json.loads(exc_info.value.payload)\n assert response_data[\"status\"] == \"error\"\n assert \"Test error\" in response_data[\"error\"]\n\n def test_wrap_prompt_for_challenge(self):\n \"\"\"Test the prompt wrapping functionality\"\"\"\n original_prompt = \"Python is the best programming language\"\n wrapped = self.tool._wrap_prompt_for_challenge(original_prompt)\n\n # Check structure\n assert \"CRITICAL REASSESSMENT – Do not automatically agree\" in wrapped\n assert \"Carefully evaluate the statement above\" in wrapped\n assert f'\"{original_prompt}\"' in wrapped\n assert \"flaws, gaps, or misleading points\" in wrapped\n assert \"thoughtful analysis\" in wrapped\n\n def test_multiple_prompts(self):\n \"\"\"Test that tool handles various types of prompts correctly\"\"\"\n test_prompts = [\n \"All code should be written in assembly for maximum performance\",\n \"Comments are unnecessary if code is self-documenting\",\n \"Testing is a waste of time for experienced developers\",\n \"Global variables make code easier to understand\",\n \"The more design patterns used, the better the code\",\n ]\n\n for prompt in test_prompts:\n request = ChallengeRequest(prompt=prompt)\n wrapped = self.tool._wrap_prompt_for_challenge(request.prompt)\n\n # Each wrapped prompt should contain the original\n assert prompt in wrapped\n assert \"CRITICAL REASSESSMENT\" in wrapped\n\n def test_tool_fields(self):\n \"\"\"Test tool-specific field definitions\"\"\"\n fields = self.tool.get_tool_fields()\n\n assert \"prompt\" in fields\n assert fields[\"prompt\"][\"type\"] == \"string\"\n assert \"Statement to scrutinize\" in fields[\"prompt\"][\"description\"]\n assert \"strip the word 'challenge'\" in fields[\"prompt\"][\"description\"]\n\n def test_required_fields_list(self):\n \"\"\"Test required fields list\"\"\"\n required = self.tool.get_required_fields()\n assert required == [\"prompt\"]\n\n @pytest.mark.asyncio\n async def test_not_used_methods(self):\n \"\"\"Test that methods not used by challenge tool work correctly\"\"\"\n request = ChallengeRequest(prompt=\"test\")\n\n # These methods aren't used since challenge doesn't call AI\n prompt = await self.tool.prepare_prompt(request)\n assert prompt == \"\"\n\n response = self.tool.format_response(\"test response\", request)\n assert response == \"test response\"\n\n def test_special_characters_in_prompt(self):\n \"\"\"Test handling of special characters in prompts\"\"\"\n special_prompt = 'The \"best\" way to handle errors is to use try/except: pass'\n request = ChallengeRequest(prompt=special_prompt)\n wrapped = self.tool._wrap_prompt_for_challenge(request.prompt)\n\n # Should handle quotes properly\n assert special_prompt in wrapped\n\n @pytest.mark.asyncio\n async def test_unicode_support(self):\n \"\"\"Test that tool handles unicode characters correctly\"\"\"\n unicode_prompt = \"θ½―δ»ΆεΌ€ε‘δΈ­ζœ€ι‡θ¦ηš„ζ˜―ε†™δ»£η οΌŒζ΅‹θ―•δΈι‡θ¦ πŸš€\"\n arguments = {\"prompt\": unicode_prompt}\n\n result = await self.tool.execute(arguments)\n response_data = json.loads(result[0].text)\n\n assert response_data[\"original_statement\"] == unicode_prompt\n assert unicode_prompt in response_data[\"challenge_prompt\"]\n\n\nif __name__ == \"__main__\":\n pytest.main([__file__])\n" }, { "path": "tests/test_chat_codegen_integration.py", "content": "\"\"\"Integration test for Chat tool code generation with Gemini 2.5 Pro.\n\nThis test uses the Google Gemini SDK's built-in record/replay support. To refresh the\ncassette, delete the existing JSON file under\n``tests/gemini_cassettes/chat_codegen/gemini25_pro_calculator/mldev.json`` and run:\n\n```\nGEMINI_API_KEY= pytest tests/test_chat_codegen_integration.py::test_chat_codegen_saves_file\n```\n\nThe test will automatically record a new interaction when the cassette is missing and\nthe environment variable `GEMINI_API_KEY` is set to a valid key.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport os\nfrom pathlib import Path\n\nimport pytest\n\nfrom providers.gemini import GeminiModelProvider\nfrom providers.registry import ModelProviderRegistry, ProviderType\nfrom tools.chat import ChatTool\n\nREPLAYS_ROOT = Path(__file__).parent / \"gemini_cassettes\"\nCASSETTE_DIR = REPLAYS_ROOT / \"chat_codegen\"\nCASSETTE_PATH = CASSETTE_DIR / \"gemini25_pro_calculator\" / \"mldev.json\"\nCASSETTE_REPLAY_ID = \"chat_codegen/gemini25_pro_calculator/mldev\"\n\n\n@pytest.mark.asyncio\n@pytest.mark.no_mock_provider\nasync def test_chat_codegen_saves_file(monkeypatch, tmp_path):\n \"\"\"Ensure Gemini 2.5 Pro responses create pal_generated.code when code is emitted.\"\"\"\n\n CASSETTE_PATH.parent.mkdir(parents=True, exist_ok=True)\n\n recording_mode = not CASSETTE_PATH.exists()\n gemini_key = os.getenv(\"GEMINI_API_KEY\", \"\")\n\n if recording_mode:\n if not gemini_key or gemini_key.startswith(\"dummy\"):\n pytest.skip(\"Cassette missing and GEMINI_API_KEY not configured. Provide a real key to record.\")\n client_mode = \"record\"\n else:\n gemini_key = \"dummy-key-for-replay\"\n client_mode = \"replay\"\n\n with monkeypatch.context() as m:\n m.setenv(\"GEMINI_API_KEY\", gemini_key)\n m.setenv(\"DEFAULT_MODEL\", \"auto\")\n m.setenv(\"GOOGLE_ALLOWED_MODELS\", \"gemini-2.5-pro\")\n m.setenv(\"GOOGLE_GENAI_CLIENT_MODE\", client_mode)\n m.setenv(\"GOOGLE_GENAI_REPLAYS_DIRECTORY\", str(REPLAYS_ROOT))\n m.setenv(\"GOOGLE_GENAI_REPLAY_ID\", CASSETTE_REPLAY_ID)\n\n # Clear other provider keys to avoid unintended routing\n for key in [\"OPENAI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\", \"CUSTOM_API_KEY\"]:\n m.delenv(key, raising=False)\n\n ModelProviderRegistry.reset_for_testing()\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n working_dir = tmp_path / \"codegen\"\n working_dir.mkdir()\n preexisting = working_dir / \"pal_generated.code\"\n preexisting.write_text(\"stale contents\", encoding=\"utf-8\")\n\n chat_tool = ChatTool()\n prompt = (\n \"Please generate a Python module with functions `add` and `multiply` that perform\"\n \" basic addition and multiplication. Produce the response using the structured\"\n \" format so the assistant can apply the files directly.\"\n )\n\n result = await chat_tool.execute(\n {\n \"prompt\": prompt,\n \"model\": \"gemini-2.5-pro\",\n \"working_directory_absolute_path\": str(working_dir),\n }\n )\n\n provider = ModelProviderRegistry.get_provider_for_model(\"gemini-2.5-pro\")\n if provider is not None:\n try:\n provider.client.close()\n except AttributeError:\n pass\n\n # Reset restriction service cache to avoid leaking allowed-model config\n try:\n from utils import model_restrictions\n\n model_restrictions._restriction_service = None # type: ignore[attr-defined]\n except Exception:\n pass\n\n assert result and result[0].type == \"text\"\n payload = json.loads(result[0].text)\n assert payload[\"status\"] in {\"success\", \"continuation_available\"}\n\n artifact_path = working_dir / \"pal_generated.code\"\n assert artifact_path.exists()\n saved = artifact_path.read_text()\n assert \"\" in saved\n assert \" str:\n digit_match = re.search(r\"\\b(\\d{1,2})\\b\", text)\n if digit_match:\n return digit_match.group(1)\n\n lower_text = text.lower()\n for word, value in WORD_TO_NUMBER.items():\n if re.search(rf\"\\b{word}\\b\", lower_text):\n return str(value)\n return \"\"\n\n\n@pytest.mark.asyncio\n@pytest.mark.no_mock_provider\nasync def test_chat_cross_model_continuation(monkeypatch, tmp_path):\n \"\"\"Verify continuation across Gemini then OpenAI using recorded interactions.\"\"\"\n\n env_updates = {\n \"DEFAULT_MODEL\": \"auto\",\n \"OPENAI_API_KEY\": os.getenv(\"OPENAI_API_KEY\", \"\"),\n \"GEMINI_API_KEY\": os.getenv(\"GEMINI_API_KEY\", \"\"),\n }\n keys_to_clear = [\n \"XAI_API_KEY\",\n \"OPENROUTER_API_KEY\",\n \"ANTHROPIC_API_KEY\",\n \"MISTRAL_API_KEY\",\n \"CUSTOM_API_KEY\",\n \"CUSTOM_API_URL\",\n ]\n\n recording_mode = not OPENAI_CASSETTE_PATH.exists() or not GEMINI_REPLAY_PATH.exists()\n if recording_mode:\n openai_key = env_updates[\"OPENAI_API_KEY\"].strip()\n gemini_key = env_updates[\"GEMINI_API_KEY\"].strip()\n if (not openai_key or openai_key.startswith(\"dummy\")) or (not gemini_key or gemini_key.startswith(\"dummy\")):\n pytest.skip(\n \"Cross-provider cassette missing and OPENAI_API_KEY/GEMINI_API_KEY not configured. Provide real keys to record.\"\n )\n\n GEMINI_REPLAY_PATH.parent.mkdir(parents=True, exist_ok=True)\n\n # Step 1 – Gemini picks a number\n with monkeypatch.context() as m:\n m.setenv(\"DEFAULT_MODEL\", env_updates[\"DEFAULT_MODEL\"])\n m.setenv(\"GOOGLE_ALLOWED_MODELS\", \"gemini-2.5-flash\")\n m.setenv(\"OPENAI_ALLOWED_MODELS\", \"gpt-5\")\n if recording_mode:\n m.setenv(\"OPENAI_API_KEY\", env_updates[\"OPENAI_API_KEY\"])\n m.setenv(\"GEMINI_API_KEY\", env_updates[\"GEMINI_API_KEY\"])\n m.setenv(\"GOOGLE_GENAI_CLIENT_MODE\", \"record\")\n else:\n m.setenv(\"OPENAI_API_KEY\", \"dummy-key-for-replay\")\n m.setenv(\"GEMINI_API_KEY\", \"dummy-key-for-replay\")\n m.setenv(\"GOOGLE_GENAI_CLIENT_MODE\", \"replay\")\n\n m.setenv(\"GOOGLE_GENAI_REPLAYS_DIRECTORY\", str(GEMINI_CASSETTE_DIR))\n m.setenv(\"GOOGLE_GENAI_REPLAY_ID\", GEMINI_REPLAY_ID)\n\n for key in keys_to_clear:\n m.delenv(key, raising=False)\n\n ModelProviderRegistry.reset_for_testing()\n from providers.gemini import GeminiModelProvider\n from providers.openai import OpenAIModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n from utils import conversation_memory\n\n m.setattr(conversation_memory.uuid, \"uuid4\", lambda: FIXED_THREAD_ID)\n\n chat_tool = ChatTool()\n working_directory = str(tmp_path)\n\n step1_args = {\n \"prompt\": \"Pick a number between 1 and 10 and respond with JUST that number.\",\n \"model\": \"gemini-2.5-flash\",\n \"temperature\": 0.2,\n \"working_directory_absolute_path\": working_directory,\n }\n\n step1_result = await chat_tool.execute(step1_args)\n assert step1_result and step1_result[0].type == \"text\"\n\n step1_data = json.loads(step1_result[0].text)\n assert step1_data[\"status\"] in {\"success\", \"continuation_available\"}\n assert step1_data.get(\"metadata\", {}).get(\"provider_used\") == \"google\"\n continuation_offer = step1_data.get(\"continuation_offer\")\n assert continuation_offer is not None\n continuation_id = continuation_offer[\"continuation_id\"]\n assert continuation_id\n\n chosen_number = _extract_number(step1_data[\"content\"])\n assert chosen_number.isdigit()\n assert 1 <= int(chosen_number) <= 10\n\n # Ensure replay is flushed for Gemini recordings\n gemini_provider = ModelProviderRegistry.get_provider_for_model(\"gemini-2.5-flash\")\n if gemini_provider is not None:\n try:\n client = gemini_provider.client\n if hasattr(client, \"close\"):\n client.close()\n finally:\n if hasattr(gemini_provider, \"_client\"):\n gemini_provider._client = None\n\n assert GEMINI_REPLAY_PATH.exists()\n\n # Step 2 – gpt-5 recalls the number via continuation\n with monkeypatch.context() as m:\n if recording_mode:\n m.setenv(\"OPENAI_API_KEY\", env_updates[\"OPENAI_API_KEY\"])\n m.setenv(\"GEMINI_API_KEY\", env_updates[\"GEMINI_API_KEY\"])\n m.setenv(\"GOOGLE_GENAI_CLIENT_MODE\", \"record\")\n else:\n m.setenv(\"OPENAI_API_KEY\", \"dummy-key-for-replay\")\n m.setenv(\"GEMINI_API_KEY\", \"dummy-key-for-replay\")\n m.setenv(\"GOOGLE_GENAI_CLIENT_MODE\", \"replay\")\n\n m.setenv(\"DEFAULT_MODEL\", env_updates[\"DEFAULT_MODEL\"])\n m.setenv(\"GOOGLE_ALLOWED_MODELS\", \"gemini-2.5-flash\")\n m.setenv(\"OPENAI_ALLOWED_MODELS\", \"gpt-5\")\n m.setenv(\"GOOGLE_GENAI_REPLAYS_DIRECTORY\", str(GEMINI_CASSETTE_DIR))\n m.setenv(\"GOOGLE_GENAI_REPLAY_ID\", GEMINI_REPLAY_ID)\n for key in keys_to_clear:\n m.delenv(key, raising=False)\n\n ModelProviderRegistry.reset_for_testing()\n from providers.gemini import GeminiModelProvider\n from providers.openai import OpenAIModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n inject_transport(monkeypatch, OPENAI_CASSETTE_PATH)\n\n chat_tool = ChatTool()\n step2_args = {\n \"prompt\": \"Remind me, what number did you pick, respond with JUST that number.\",\n \"model\": \"gpt-5\",\n \"continuation_id\": continuation_id,\n \"temperature\": 0.2,\n \"working_directory_absolute_path\": working_directory,\n }\n\n step2_result = await chat_tool.execute(step2_args)\n assert step2_result and step2_result[0].type == \"text\"\n\n step2_data = json.loads(step2_result[0].text)\n assert step2_data[\"status\"] in {\"success\", \"continuation_available\"}\n assert step2_data.get(\"metadata\", {}).get(\"provider_used\") == \"openai\"\n\n recalled_number = _extract_number(step2_data[\"content\"])\n assert recalled_number == chosen_number\n\n assert OPENAI_CASSETTE_PATH.exists()\n\n ModelProviderRegistry.reset_for_testing()\n" }, { "path": "tests/test_chat_openai_integration.py", "content": "\"\"\"Integration test for ChatTool auto-mode using OpenAI o3/gpt models with cassette recording.\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport os\nimport uuid\nfrom pathlib import Path\n\nimport pytest\n\nfrom providers.registry import ModelProviderRegistry\nfrom providers.shared import ProviderType\nfrom tests.transport_helpers import inject_transport\nfrom tools.chat import ChatTool\n\n# Directory for recorded HTTP interactions\nCASSETTE_DIR = Path(__file__).parent / \"openai_cassettes\"\nCASSETTE_DIR.mkdir(exist_ok=True)\nCASSETTE_PATH = CASSETTE_DIR / \"chat_gpt5_moon_distance.json\"\nCASSETTE_CONTINUATION_PATH = CASSETTE_DIR / \"chat_gpt5_continuation.json\"\n\n\n@pytest.mark.asyncio\n@pytest.mark.no_mock_provider\nasync def test_chat_auto_mode_with_openai(monkeypatch, tmp_path):\n \"\"\"Ensure ChatTool in auto mode selects gpt-5 via OpenAI and returns a valid response.\"\"\"\n # Prepare environment so only OpenAI is available in auto mode\n env_updates = {\n \"DEFAULT_MODEL\": \"auto\",\n \"OPENAI_API_KEY\": os.getenv(\"OPENAI_API_KEY\", \"\"),\n }\n # Remove Gemini/XAI keys to force OpenAI selection\n keys_to_clear = [\"GEMINI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]\n\n with monkeypatch.context() as m:\n m.setenv(\"DEFAULT_MODEL\", env_updates[\"DEFAULT_MODEL\"])\n m.setenv(\"OPENAI_ALLOWED_MODELS\", \"gpt-5\")\n if env_updates[\"OPENAI_API_KEY\"]:\n m.setenv(\"OPENAI_API_KEY\", env_updates[\"OPENAI_API_KEY\"])\n for key in keys_to_clear:\n m.delenv(key, raising=False)\n\n # Choose recording or replay mode based on cassette presence\n if not CASSETTE_PATH.exists():\n real_key = os.getenv(\"OPENAI_API_KEY\", \"\").strip()\n if not real_key or real_key.startswith(\"dummy\"):\n pytest.skip(\n \"Cassette missing and OPENAI_API_KEY not configured. Provide a real key and re-run to record.\"\n )\n else:\n # Replay mode uses dummy key to keep secrets out of the cassette\n m.setenv(\"OPENAI_API_KEY\", \"dummy-key-for-replay\")\n\n # Reset registry and register only OpenAI provider\n ModelProviderRegistry.reset_for_testing()\n from providers.openai import OpenAIModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n\n # Inject HTTP transport (records or replays depending on cassette state)\n inject_transport(monkeypatch, CASSETTE_PATH)\n\n # Execute ChatTool request targeting gpt-5 directly (server normally resolves autoβ†’model)\n chat_tool = ChatTool()\n working_directory = str(tmp_path)\n arguments = {\n \"prompt\": \"Use chat with gpt5 and ask how far the moon is from earth.\",\n \"model\": \"gpt-5\",\n \"temperature\": 1.0,\n \"working_directory_absolute_path\": working_directory,\n }\n\n result = await chat_tool.execute(arguments)\n\n # Validate response\n assert result and result[0].type == \"text\"\n response_data = json.loads(result[0].text)\n\n assert response_data[\"status\"] in {\"success\", \"continuation_available\"}\n metadata = response_data.get(\"metadata\", {})\n assert metadata.get(\"provider_used\") == \"openai\"\n assert metadata.get(\"model_used\") in {\"gpt-5\", \"gpt5\"}\n assert \"moon\" in response_data[\"content\"].lower()\n\n # Ensure cassette recorded for future replays\n assert CASSETTE_PATH.exists()\n\n\n@pytest.mark.asyncio\n@pytest.mark.no_mock_provider\nasync def test_chat_openai_continuation(monkeypatch, tmp_path):\n \"\"\"Verify continuation_id workflow against gpt-5 using recorded OpenAI responses.\"\"\"\n\n env_updates = {\n \"DEFAULT_MODEL\": \"auto\",\n \"OPENAI_API_KEY\": os.getenv(\"OPENAI_API_KEY\", \"\"),\n }\n keys_to_clear = [\"GEMINI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]\n\n recording_mode = not CASSETTE_CONTINUATION_PATH.exists()\n if recording_mode:\n real_key = env_updates[\"OPENAI_API_KEY\"].strip()\n if not real_key or real_key.startswith(\"dummy\"):\n pytest.skip(\"Continuation cassette missing and OPENAI_API_KEY not configured. Set a real key to record.\")\n\n fixed_thread_id = uuid.UUID(\"95d60035-1aa3-4398-9936-fca71989d906\")\n\n with monkeypatch.context() as m:\n m.setenv(\"DEFAULT_MODEL\", env_updates[\"DEFAULT_MODEL\"])\n m.setenv(\"OPENAI_ALLOWED_MODELS\", \"gpt-5\")\n if recording_mode:\n m.setenv(\"OPENAI_API_KEY\", env_updates[\"OPENAI_API_KEY\"])\n else:\n m.setenv(\"OPENAI_API_KEY\", \"dummy-key-for-replay\")\n for key in keys_to_clear:\n m.delenv(key, raising=False)\n\n ModelProviderRegistry.reset_for_testing()\n from providers.openai import OpenAIModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n\n inject_transport(monkeypatch, CASSETTE_CONTINUATION_PATH)\n\n from utils import conversation_memory\n\n m.setattr(conversation_memory.uuid, \"uuid4\", lambda: fixed_thread_id)\n\n chat_tool = ChatTool()\n working_directory = str(tmp_path)\n\n # First message: obtain continuation_id\n first_args = {\n \"prompt\": \"In one word, which sells better: iOS app or macOS app?\",\n \"model\": \"gpt-5\",\n \"temperature\": 1.0,\n \"working_directory_absolute_path\": working_directory,\n }\n first_result = await chat_tool.execute(first_args)\n\n assert first_result and first_result[0].type == \"text\"\n first_data = json.loads(first_result[0].text)\n assert first_data[\"status\"] == \"continuation_available\"\n first_metadata = first_data.get(\"metadata\", {})\n assert first_metadata.get(\"provider_used\") == \"openai\"\n assert first_metadata.get(\"model_used\") in {\"gpt-5\", \"gpt5\"}\n continuation = first_data.get(\"continuation_offer\")\n assert continuation is not None\n continuation_id = continuation.get(\"continuation_id\")\n assert continuation_id\n\n # Second message using continuation_id (reuse same tool instance for clarity)\n second_args = {\n \"prompt\": \"In one word then, SwiftUI or ReactNative?\",\n \"model\": \"gpt-5\",\n \"continuation_id\": continuation_id,\n \"temperature\": 1.0,\n \"working_directory_absolute_path\": working_directory,\n }\n\n second_result = await chat_tool.execute(second_args)\n\n assert second_result and second_result[0].type == \"text\"\n second_data = json.loads(second_result[0].text)\n assert second_data[\"status\"] in {\"success\", \"continuation_available\"}\n second_metadata = second_data.get(\"metadata\", {})\n assert second_metadata.get(\"provider_used\") == \"openai\"\n assert second_metadata.get(\"model_used\") in {\"gpt-5\", \"gpt5\"}\n assert second_metadata.get(\"conversation_ready\") is True\n assert second_data.get(\"continuation_offer\") is not None\n\n # Ensure the cassette file exists for future replays\n assert CASSETTE_CONTINUATION_PATH.exists()\n\n # Clean up registry state for subsequent tests\n ModelProviderRegistry.reset_for_testing()\n" }, { "path": "tests/test_chat_simple.py", "content": "\"\"\"\nTests for Chat tool - validating SimpleTool architecture\n\nThis module contains unit tests to ensure that the Chat tool\n(now using SimpleTool architecture) maintains proper functionality.\n\"\"\"\n\nimport json\nfrom types import SimpleNamespace\nfrom unittest.mock import patch\n\nimport pytest\n\nfrom tools.chat import ChatRequest, ChatTool\nfrom tools.shared.exceptions import ToolExecutionError\n\n\nclass TestChatTool:\n \"\"\"Test suite for ChatSimple tool\"\"\"\n\n def setup_method(self):\n \"\"\"Set up test fixtures\"\"\"\n self.tool = ChatTool()\n\n def test_tool_metadata(self):\n \"\"\"Test that tool metadata matches requirements\"\"\"\n assert self.tool.get_name() == \"chat\"\n assert \"collaborative thinking\" in self.tool.get_description()\n assert self.tool.get_system_prompt() is not None\n assert self.tool.get_default_temperature() > 0\n assert self.tool.get_model_category() is not None\n\n def test_schema_structure(self):\n \"\"\"Test that schema has correct structure\"\"\"\n schema = self.tool.get_input_schema()\n\n # Basic schema structure\n assert schema[\"type\"] == \"object\"\n assert \"properties\" in schema\n assert \"required\" in schema\n\n # Required fields\n assert \"prompt\" in schema[\"required\"]\n assert \"working_directory_absolute_path\" in schema[\"required\"]\n\n # Properties\n properties = schema[\"properties\"]\n assert \"prompt\" in properties\n assert \"absolute_file_paths\" in properties\n assert \"images\" in properties\n assert \"working_directory_absolute_path\" in properties\n\n def test_request_model_validation(self):\n \"\"\"Test that the request model validates correctly\"\"\"\n # Test valid request\n request_data = {\n \"prompt\": \"Test prompt\",\n \"absolute_file_paths\": [\"test.txt\"],\n \"images\": [\"test.png\"],\n \"model\": \"anthropic/claude-opus-4.1\",\n \"temperature\": 0.7,\n \"working_directory_absolute_path\": \"/tmp\", # Dummy absolute path\n }\n\n request = ChatRequest(**request_data)\n assert request.prompt == \"Test prompt\"\n assert request.absolute_file_paths == [\"test.txt\"]\n assert request.images == [\"test.png\"]\n assert request.model == \"anthropic/claude-opus-4.1\"\n assert request.temperature == 0.7\n assert request.working_directory_absolute_path == \"/tmp\"\n\n def test_required_fields(self):\n \"\"\"Test that required fields are enforced\"\"\"\n # Missing prompt should raise validation error\n from pydantic import ValidationError\n\n with pytest.raises(ValidationError):\n ChatRequest(model=\"anthropic/claude-opus-4.1\", working_directory_absolute_path=\"/tmp\")\n\n def test_model_availability(self):\n \"\"\"Test that model availability works\"\"\"\n models = self.tool._get_available_models()\n assert len(models) > 0 # Should have some models\n assert isinstance(models, list)\n\n def test_model_field_schema(self):\n \"\"\"Test that model field schema generation works correctly\"\"\"\n schema = self.tool.get_model_field_schema()\n\n assert schema[\"type\"] == \"string\"\n assert \"description\" in schema\n\n # Description should route callers to listmodels, regardless of mode\n assert \"listmodels\" in schema[\"description\"]\n if self.tool.is_effective_auto_mode():\n assert \"auto mode\" in schema[\"description\"].lower()\n else:\n import config\n\n assert f\"'{config.DEFAULT_MODEL}'\" in schema[\"description\"]\n\n @pytest.mark.asyncio\n async def test_prompt_preparation(self):\n \"\"\"Test that prompt preparation works correctly\"\"\"\n request = ChatRequest(\n prompt=\"Test prompt\",\n absolute_file_paths=[],\n working_directory_absolute_path=\"/tmp\",\n )\n\n # Mock the system prompt and file handling\n with patch.object(self.tool, \"get_system_prompt\", return_value=\"System prompt\"):\n with patch.object(self.tool, \"handle_prompt_file_with_fallback\", return_value=\"Test prompt\"):\n with patch.object(self.tool, \"_prepare_file_content_for_prompt\", return_value=(\"\", [])):\n with patch.object(self.tool, \"_validate_token_limit\"):\n with patch.object(self.tool, \"get_websearch_instruction\", return_value=\"\"):\n prompt = await self.tool.prepare_prompt(request)\n\n assert \"Test prompt\" in prompt\n assert prompt.startswith(\"=== USER REQUEST ===\")\n assert \"System prompt\" not in prompt\n\n def test_response_formatting(self):\n \"\"\"Test that response formatting works correctly\"\"\"\n response = \"Test response content\"\n request = ChatRequest(prompt=\"Test\", working_directory_absolute_path=\"/tmp\")\n\n formatted = self.tool.format_response(response, request)\n\n assert \"Test response content\" in formatted\n assert \"AGENT'S TURN:\" in formatted\n assert \"Evaluate this perspective\" in formatted\n\n def test_format_response_multiple_generated_code_blocks(self, tmp_path):\n \"\"\"All generated-code blocks should be combined and saved to pal_generated.code.\"\"\"\n tool = ChatTool()\n tool._model_context = SimpleNamespace(capabilities=SimpleNamespace(allow_code_generation=True))\n\n response = (\n \"Intro text\\n\"\n \"print('hello')\\n\"\n \"Other text\\n\"\n \"print('world')\"\n )\n\n request = ChatRequest(prompt=\"Test\", working_directory_absolute_path=str(tmp_path))\n\n formatted = tool.format_response(response, request)\n\n saved_path = tmp_path / \"pal_generated.code\"\n saved_content = saved_path.read_text(encoding=\"utf-8\")\n\n assert \"print('world')\" in saved_content\n assert \"print('hello')\" not in saved_content\n assert saved_content.count(\"\") == 1\n assert \"print('hello')\" in formatted\n assert str(saved_path) in formatted\n\n def test_format_response_single_generated_code_block(self, tmp_path):\n \"\"\"Single block should be saved and removed from narrative.\"\"\"\n tool = ChatTool()\n tool._model_context = SimpleNamespace(capabilities=SimpleNamespace(allow_code_generation=True))\n\n response = (\n \"Intro text before code.\\n\"\n \"print('only-once')\\n\"\n \"Closing thoughts after code.\"\n )\n\n request = ChatRequest(prompt=\"Test\", working_directory_absolute_path=str(tmp_path))\n\n formatted = tool.format_response(response, request)\n\n saved_path = tmp_path / \"pal_generated.code\"\n saved_content = saved_path.read_text(encoding=\"utf-8\")\n\n assert \"print('only-once')\" in saved_content\n assert \"\" in saved_content\n assert \"print('only-once')\" not in formatted\n assert \"Closing thoughts after code.\" in formatted\n\n def test_format_response_ignores_unclosed_generated_code(self, tmp_path):\n \"\"\"Unclosed generated-code tags should be ignored to avoid accidental clipping.\"\"\"\n tool = ChatTool()\n tool._model_context = SimpleNamespace(capabilities=SimpleNamespace(allow_code_generation=True))\n\n response = \"Intro text\\nprint('oops')\\nStill ongoing\"\n\n request = ChatRequest(prompt=\"Test\", working_directory_absolute_path=str(tmp_path))\n\n formatted = tool.format_response(response, request)\n\n saved_path = tmp_path / \"pal_generated.code\"\n assert not saved_path.exists()\n assert \"print('oops')\" in formatted\n\n def test_format_response_ignores_orphaned_closing_tag(self, tmp_path):\n \"\"\"Stray closing tags should not trigger extraction.\"\"\"\n tool = ChatTool()\n tool._model_context = SimpleNamespace(capabilities=SimpleNamespace(allow_code_generation=True))\n\n response = \"Intro text\\n just text\"\n\n request = ChatRequest(prompt=\"Test\", working_directory_absolute_path=str(tmp_path))\n\n formatted = tool.format_response(response, request)\n\n saved_path = tmp_path / \"pal_generated.code\"\n assert not saved_path.exists()\n assert \" just text\" in formatted\n\n def test_format_response_preserves_narrative_after_generated_code(self, tmp_path):\n \"\"\"Narrative content after generated code must remain intact in the formatted output.\"\"\"\n tool = ChatTool()\n tool._model_context = SimpleNamespace(capabilities=SimpleNamespace(allow_code_generation=True))\n\n response = (\n \"Summary before code.\\n\"\n \"print('demo')\\n\"\n \"### Follow-up\\n\"\n \"Further analysis and guidance after the generated snippet.\\n\"\n )\n\n request = ChatRequest(prompt=\"Test\", working_directory_absolute_path=str(tmp_path))\n\n formatted = tool.format_response(response, request)\n\n assert \"Summary before code.\" in formatted\n assert \"### Follow-up\" in formatted\n assert \"Further analysis and guidance after the generated snippet.\" in formatted\n assert \"print('demo')\" not in formatted\n\n def test_tool_name(self):\n \"\"\"Test tool name is correct\"\"\"\n assert self.tool.get_name() == \"chat\"\n\n def test_websearch_guidance(self):\n \"\"\"Test web search guidance matches Chat tool style\"\"\"\n guidance = self.tool.get_websearch_guidance()\n chat_style_guidance = self.tool.get_chat_style_websearch_guidance()\n\n assert guidance == chat_style_guidance\n assert \"Documentation for any technologies\" in guidance\n assert \"Current best practices\" in guidance\n\n def test_convenience_methods(self):\n \"\"\"Test SimpleTool convenience methods work correctly\"\"\"\n assert self.tool.supports_custom_request_model()\n\n # Test that the tool fields are defined correctly\n tool_fields = self.tool.get_tool_fields()\n assert \"prompt\" in tool_fields\n assert \"absolute_file_paths\" in tool_fields\n assert \"images\" in tool_fields\n\n required_fields = self.tool.get_required_fields()\n assert \"prompt\" in required_fields\n assert \"working_directory_absolute_path\" in required_fields\n\n\nclass TestChatRequestModel:\n \"\"\"Test suite for ChatRequest model\"\"\"\n\n def test_field_descriptions(self):\n \"\"\"Test that field descriptions are proper\"\"\"\n from tools.chat import CHAT_FIELD_DESCRIPTIONS\n\n # Field descriptions should exist and be descriptive\n assert len(CHAT_FIELD_DESCRIPTIONS[\"prompt\"]) > 50\n assert \"context\" in CHAT_FIELD_DESCRIPTIONS[\"prompt\"]\n files_desc = CHAT_FIELD_DESCRIPTIONS[\"absolute_file_paths\"].lower()\n assert \"absolute\" in files_desc\n assert \"visual context\" in CHAT_FIELD_DESCRIPTIONS[\"images\"]\n assert \"directory\" in CHAT_FIELD_DESCRIPTIONS[\"working_directory_absolute_path\"].lower()\n\n def test_working_directory_absolute_path_description_matches_behavior(self):\n \"\"\"Absolute working directory description should reflect existing-directory requirement.\"\"\"\n from tools.chat import CHAT_FIELD_DESCRIPTIONS\n\n description = CHAT_FIELD_DESCRIPTIONS[\"working_directory_absolute_path\"].lower()\n assert \"existing directory\" in description\n\n @pytest.mark.asyncio\n async def test_working_directory_absolute_path_must_exist(self, tmp_path):\n \"\"\"Chat tool should reject non-existent working directories.\"\"\"\n tool = ChatTool()\n missing_dir = tmp_path / \"nonexistent_subdir\"\n\n with pytest.raises(ToolExecutionError) as exc_info:\n await tool.execute(\n {\n \"prompt\": \"test\",\n \"absolute_file_paths\": [],\n \"images\": [],\n \"working_directory_absolute_path\": str(missing_dir),\n }\n )\n\n payload = json.loads(exc_info.value.payload)\n assert payload[\"status\"] == \"error\"\n assert \"existing directory\" in payload[\"content\"].lower()\n\n def test_default_values(self):\n \"\"\"Test that default values work correctly\"\"\"\n request = ChatRequest(prompt=\"Test\", working_directory_absolute_path=\"/tmp\")\n\n assert request.prompt == \"Test\"\n assert request.absolute_file_paths == [] # Should default to empty list\n assert request.images == [] # Should default to empty list\n\n def test_inheritance(self):\n \"\"\"Test that ChatRequest properly inherits from ToolRequest\"\"\"\n from tools.shared.base_models import ToolRequest\n\n request = ChatRequest(prompt=\"Test\", working_directory_absolute_path=\"/tmp\")\n assert isinstance(request, ToolRequest)\n\n # Should have inherited fields\n assert hasattr(request, \"model\")\n assert hasattr(request, \"temperature\")\n assert hasattr(request, \"thinking_mode\")\n assert hasattr(request, \"continuation_id\")\n assert hasattr(request, \"images\") # From base model too\n\n\nif __name__ == \"__main__\":\n pytest.main([__file__])\n" }, { "path": "tests/test_clink_claude_agent.py", "content": "import asyncio\nimport json\nimport shutil\nfrom pathlib import Path\n\nimport pytest\n\nfrom clink.agents.base import CLIAgentError\nfrom clink.agents.claude import ClaudeAgent\nfrom clink.models import ResolvedCLIClient, ResolvedCLIRole\n\n\nclass DummyProcess:\n def __init__(self, *, stdout: bytes = b\"\", stderr: bytes = b\"\", returncode: int = 0):\n self._stdout = stdout\n self._stderr = stderr\n self.returncode = returncode\n self.stdin_data: bytes | None = None\n\n async def communicate(self, input_data):\n self.stdin_data = input_data\n return self._stdout, self._stderr\n\n\n@pytest.fixture()\ndef claude_agent():\n prompt_path = Path(\"systemprompts/clink/default.txt\").resolve()\n role = ResolvedCLIRole(name=\"default\", prompt_path=prompt_path, role_args=[])\n client = ResolvedCLIClient(\n name=\"claude\",\n executable=[\"claude\"],\n internal_args=[\"--print\", \"--output-format\", \"json\"],\n config_args=[\"--permission-mode\", \"acceptEdits\"],\n env={},\n timeout_seconds=30,\n parser=\"claude_json\",\n runner=\"claude\",\n roles={\"default\": role},\n output_to_file=None,\n working_dir=None,\n )\n return ClaudeAgent(client), role\n\n\nasync def _run_agent_with_process(monkeypatch, agent, role, process, *, system_prompt=\"System prompt\"):\n async def fake_create_subprocess_exec(*_args, **_kwargs):\n return process\n\n def fake_which(executable_name):\n return f\"/usr/bin/{executable_name}\"\n\n monkeypatch.setattr(asyncio, \"create_subprocess_exec\", fake_create_subprocess_exec)\n monkeypatch.setattr(shutil, \"which\", fake_which)\n\n return await agent.run(\n role=role,\n prompt=\"Respond with 42\",\n system_prompt=system_prompt,\n files=[],\n images=[],\n )\n\n\n@pytest.mark.asyncio\nasync def test_claude_agent_injects_system_prompt(monkeypatch, claude_agent):\n agent, role = claude_agent\n stdout_payload = json.dumps(\n {\n \"type\": \"result\",\n \"subtype\": \"success\",\n \"is_error\": False,\n \"result\": \"42\",\n }\n ).encode()\n process = DummyProcess(stdout=stdout_payload)\n\n result = await _run_agent_with_process(monkeypatch, agent, role, process)\n\n assert \"--append-system-prompt\" in result.sanitized_command\n idx = result.sanitized_command.index(\"--append-system-prompt\")\n assert result.sanitized_command[idx + 1] == \"System prompt\"\n assert process.stdin_data.decode().startswith(\"Respond with 42\")\n\n\n@pytest.mark.asyncio\nasync def test_claude_agent_recovers_error_payload(monkeypatch, claude_agent):\n agent, role = claude_agent\n stdout_payload = json.dumps(\n {\n \"type\": \"result\",\n \"subtype\": \"success\",\n \"is_error\": True,\n \"result\": \"API Error\",\n }\n ).encode()\n process = DummyProcess(stdout=stdout_payload, returncode=2)\n\n result = await _run_agent_with_process(monkeypatch, agent, role, process)\n\n assert result.returncode == 2\n assert result.parsed.content == \"API Error\"\n assert result.parsed.metadata[\"is_error\"] is True\n\n\n@pytest.mark.asyncio\nasync def test_claude_agent_propagates_unparseable_output(monkeypatch, claude_agent):\n agent, role = claude_agent\n process = DummyProcess(stdout=b\"\", returncode=1)\n\n with pytest.raises(CLIAgentError):\n await _run_agent_with_process(monkeypatch, agent, role, process)\n" }, { "path": "tests/test_clink_claude_parser.py", "content": "\"\"\"Tests for the Claude CLI JSON parser.\"\"\"\n\nimport json\n\nimport pytest\n\nfrom clink.parsers.base import ParserError\nfrom clink.parsers.claude import ClaudeJSONParser\n\n\ndef _build_success_payload() -> str:\n return (\n '{\"type\":\"result\",\"subtype\":\"success\",\"is_error\":false,\"duration_ms\":1234,'\n '\"duration_api_ms\":1200,\"num_turns\":1,\"result\":\"42\",\"session_id\":\"abc\",\"total_cost_usd\":0.12,'\n '\"usage\":{\"input_tokens\":10,\"output_tokens\":5},'\n '\"modelUsage\":{\"claude-sonnet-4-5-20250929\":{\"inputTokens\":10,\"outputTokens\":5}}}'\n )\n\n\ndef test_claude_parser_extracts_result_and_metadata():\n parser = ClaudeJSONParser()\n stdout = _build_success_payload()\n\n parsed = parser.parse(stdout=stdout, stderr=\"\")\n\n assert parsed.content == \"42\"\n assert parsed.metadata[\"model_used\"] == \"claude-sonnet-4-5-20250929\"\n assert parsed.metadata[\"usage\"][\"output_tokens\"] == 5\n assert parsed.metadata[\"is_error\"] is False\n\n\ndef test_claude_parser_falls_back_to_message():\n parser = ClaudeJSONParser()\n stdout = '{\"type\":\"result\",\"is_error\":true,\"message\":\"API error message\"}'\n\n parsed = parser.parse(stdout=stdout, stderr=\"warning\")\n\n assert parsed.content == \"API error message\"\n assert parsed.metadata[\"is_error\"] is True\n assert parsed.metadata[\"stderr\"] == \"warning\"\n\n\ndef test_claude_parser_requires_output():\n parser = ClaudeJSONParser()\n\n with pytest.raises(ParserError):\n parser.parse(stdout=\"\", stderr=\"\")\n\n\ndef test_claude_parser_handles_array_payload_with_result_event():\n parser = ClaudeJSONParser()\n events = [\n {\"type\": \"system\", \"session_id\": \"abc\"},\n {\"type\": \"assistant\", \"message\": \"intermediate\"},\n {\n \"type\": \"result\",\n \"subtype\": \"success\",\n \"result\": \"42\",\n \"duration_api_ms\": 9876,\n \"usage\": {\"input_tokens\": 12, \"output_tokens\": 3},\n },\n ]\n stdout = json.dumps(events)\n\n parsed = parser.parse(stdout=stdout, stderr=\"warning\")\n\n assert parsed.content == \"42\"\n assert parsed.metadata[\"duration_api_ms\"] == 9876\n assert parsed.metadata[\"raw_events\"] == events\n assert parsed.metadata[\"raw\"] == events\n" }, { "path": "tests/test_clink_codex_agent.py", "content": "import asyncio\nimport shutil\nfrom pathlib import Path\n\nimport pytest\n\nfrom clink.agents.base import CLIAgentError\nfrom clink.agents.codex import CodexAgent\nfrom clink.models import ResolvedCLIClient, ResolvedCLIRole\n\n\nclass DummyProcess:\n def __init__(self, *, stdout: bytes = b\"\", stderr: bytes = b\"\", returncode: int = 0):\n self._stdout = stdout\n self._stderr = stderr\n self.returncode = returncode\n\n async def communicate(self, _input):\n return self._stdout, self._stderr\n\n\n@pytest.fixture()\ndef codex_agent():\n prompt_path = Path(\"systemprompts/clink/codex_default.txt\").resolve()\n role = ResolvedCLIRole(name=\"default\", prompt_path=prompt_path, role_args=[])\n client = ResolvedCLIClient(\n name=\"codex\",\n executable=[\"codex\"],\n internal_args=[\"exec\"],\n config_args=[\"--json\", \"--dangerously-bypass-approvals-and-sandbox\"],\n env={},\n timeout_seconds=30,\n parser=\"codex_jsonl\",\n roles={\"default\": role},\n output_to_file=None,\n working_dir=None,\n )\n return CodexAgent(client), role\n\n\nasync def _run_agent_with_process(monkeypatch, agent, role, process):\n async def fake_create_subprocess_exec(*_args, **_kwargs):\n return process\n\n def fake_which(executable_name):\n return f\"/usr/bin/{executable_name}\"\n\n monkeypatch.setattr(asyncio, \"create_subprocess_exec\", fake_create_subprocess_exec)\n monkeypatch.setattr(shutil, \"which\", fake_which)\n return await agent.run(role=role, prompt=\"do something\", files=[], images=[])\n\n\n@pytest.mark.asyncio\nasync def test_codex_agent_recovers_jsonl(monkeypatch, codex_agent):\n agent, role = codex_agent\n stdout = b\"\"\"\n{\"type\":\"item.completed\",\"item\":{\"id\":\"item_0\",\"type\":\"agent_message\",\"text\":\"Hello from Codex\"}}\n{\"type\":\"turn.completed\",\"usage\":{\"input_tokens\":10,\"output_tokens\":5}}\n\"\"\"\n process = DummyProcess(stdout=stdout, returncode=124)\n result = await _run_agent_with_process(monkeypatch, agent, role, process)\n\n assert result.returncode == 124\n assert \"Hello from Codex\" in result.parsed.content\n assert result.parsed.metadata[\"usage\"][\"output_tokens\"] == 5\n\n\n@pytest.mark.asyncio\nasync def test_codex_agent_propagates_invalid_json(monkeypatch, codex_agent):\n agent, role = codex_agent\n stdout = b\"not json\"\n process = DummyProcess(stdout=stdout, returncode=1)\n\n with pytest.raises(CLIAgentError):\n await _run_agent_with_process(monkeypatch, agent, role, process)\n" }, { "path": "tests/test_clink_gemini_agent.py", "content": "import asyncio\nimport shutil\nfrom pathlib import Path\n\nimport pytest\n\nfrom clink.agents.base import CLIAgentError\nfrom clink.agents.gemini import GeminiAgent\nfrom clink.models import ResolvedCLIClient, ResolvedCLIRole\n\n\nclass DummyProcess:\n def __init__(self, *, stdout: bytes = b\"\", stderr: bytes = b\"\", returncode: int = 0):\n self._stdout = stdout\n self._stderr = stderr\n self.returncode = returncode\n\n async def communicate(self, _input):\n return self._stdout, self._stderr\n\n\n@pytest.fixture()\ndef gemini_agent():\n prompt_path = Path(\"systemprompts/clink/gemini_default.txt\").resolve()\n role = ResolvedCLIRole(name=\"default\", prompt_path=prompt_path, role_args=[])\n client = ResolvedCLIClient(\n name=\"gemini\",\n executable=[\"gemini\"],\n internal_args=[],\n config_args=[],\n env={},\n timeout_seconds=30,\n parser=\"gemini_json\",\n roles={\"default\": role},\n output_to_file=None,\n working_dir=None,\n )\n return GeminiAgent(client), role\n\n\nasync def _run_agent_with_process(monkeypatch, agent, role, process):\n async def fake_create_subprocess_exec(*_args, **_kwargs):\n return process\n\n def fake_which(executable_name):\n return f\"/usr/bin/{executable_name}\"\n\n monkeypatch.setattr(asyncio, \"create_subprocess_exec\", fake_create_subprocess_exec)\n monkeypatch.setattr(shutil, \"which\", fake_which)\n return await agent.run(role=role, prompt=\"do something\", files=[], images=[])\n\n\n@pytest.mark.asyncio\nasync def test_gemini_agent_recovers_tool_error(monkeypatch, gemini_agent):\n agent, role = gemini_agent\n error_json = \"\"\"{\n \"error\": {\n \"type\": \"FatalToolExecutionError\",\n \"message\": \"Error executing tool replace: Failed to edit\",\n \"code\": \"edit_expected_occurrence_mismatch\"\n }\n}\"\"\"\n stderr = (\"Error: Failed to edit, expected 1 occurrence but found 2.\\n\" + error_json).encode()\n process = DummyProcess(stderr=stderr, returncode=54)\n\n result = await _run_agent_with_process(monkeypatch, agent, role, process)\n\n assert result.returncode == 54\n assert result.parsed.metadata[\"cli_error_recovered\"] is True\n assert result.parsed.metadata[\"cli_error_code\"] == \"edit_expected_occurrence_mismatch\"\n assert \"Gemini CLI reported a tool failure\" in result.parsed.content\n\n\n@pytest.mark.asyncio\nasync def test_gemini_agent_propagates_unrecoverable_error(monkeypatch, gemini_agent):\n agent, role = gemini_agent\n stderr = b\"Plain failure without structured payload\"\n process = DummyProcess(stderr=stderr, returncode=54)\n\n with pytest.raises(CLIAgentError):\n await _run_agent_with_process(monkeypatch, agent, role, process)\n" }, { "path": "tests/test_clink_gemini_parser.py", "content": "\"\"\"Tests for the Gemini CLI JSON parser.\"\"\"\n\nimport pytest\n\nfrom clink.parsers.gemini import GeminiJSONParser, ParserError\n\n\ndef _build_rate_limit_stdout() -> str:\n return (\n \"{\\n\"\n ' \"response\": \"\",\\n'\n ' \"stats\": {\\n'\n ' \"models\": {\\n'\n ' \"gemini-2.5-pro\": {\\n'\n ' \"api\": {\\n'\n ' \"totalRequests\": 5,\\n'\n ' \"totalErrors\": 5,\\n'\n ' \"totalLatencyMs\": 13319\\n'\n \" },\\n\"\n ' \"tokens\": {\"prompt\": 0, \"candidates\": 0, \"total\": 0, \"cached\": 0, \"thoughts\": 0, \"tool\": 0}\\n'\n \" }\\n\"\n \" },\\n\"\n ' \"tools\": {\"totalCalls\": 0},\\n'\n ' \"files\": {\"totalLinesAdded\": 0, \"totalLinesRemoved\": 0}\\n'\n \" }\\n\"\n \"}\"\n )\n\n\ndef test_gemini_parser_handles_rate_limit_empty_response():\n parser = GeminiJSONParser()\n stdout = _build_rate_limit_stdout()\n stderr = \"Attempt 1 failed with status 429. Retrying with backoff... ApiError: quota exceeded\"\n\n parsed = parser.parse(stdout, stderr)\n\n assert \"429\" in parsed.content\n assert parsed.metadata.get(\"rate_limit_status\") == 429\n assert parsed.metadata.get(\"empty_response\") is True\n assert \"Attempt 1 failed\" in parsed.metadata.get(\"stderr\", \"\")\n\n\ndef test_gemini_parser_still_errors_when_no_fallback_available():\n parser = GeminiJSONParser()\n stdout = '{\"response\": \"\", \"stats\": {}}'\n\n with pytest.raises(ParserError):\n parser.parse(stdout, stderr=\"\")\n" }, { "path": "tests/test_clink_integration.py", "content": "import json\nimport os\nimport shutil\n\nimport pytest\n\nfrom tools.clink import CLinkTool\n\n\n@pytest.mark.integration\n@pytest.mark.asyncio\nasync def test_clink_gemini_single_digit_sum():\n if shutil.which(\"gemini\") is None:\n pytest.skip(\"gemini CLI is not installed or on PATH\")\n\n if not (os.getenv(\"GEMINI_API_KEY\") or os.getenv(\"GOOGLE_API_KEY\")):\n pytest.skip(\"Gemini API key is not configured\")\n\n tool = CLinkTool()\n prompt = \"Respond with a single digit equal to the sum of 2 + 2. Output only that digit.\"\n\n results = await tool.execute(\n {\n \"prompt\": prompt,\n \"cli_name\": \"gemini\",\n \"role\": \"default\",\n \"absolute_file_paths\": [],\n \"images\": [],\n }\n )\n\n assert results, \"clink tool returned no outputs\"\n payload = json.loads(results[0].text)\n status = payload[\"status\"]\n assert status in {\"success\", \"continuation_available\"}\n\n content = payload.get(\"content\", \"\").strip()\n # CLI may include additional metadata like tags; check first line or that \"4\" is present\n first_line = content.split(\"\\n\")[0].strip()\n assert first_line == \"4\" or \"4\" in content, f\"Expected '4' in response, got: {content[:100]}\"\n\n if status == \"continuation_available\":\n offer = payload.get(\"continuation_offer\") or {}\n assert offer.get(\"continuation_id\"), \"Expected continuation metadata when status indicates availability\"\n\n\n@pytest.mark.integration\n@pytest.mark.asyncio\nasync def test_clink_claude_single_digit_sum():\n if shutil.which(\"claude\") is None:\n pytest.skip(\"claude CLI is not installed or on PATH\")\n\n tool = CLinkTool()\n prompt = \"Respond with a single digit equal to the sum of 2 + 2. Output only that digit.\"\n\n results = await tool.execute(\n {\n \"prompt\": prompt,\n \"cli_name\": \"claude\",\n \"role\": \"default\",\n \"absolute_file_paths\": [],\n \"images\": [],\n }\n )\n\n assert results, \"clink tool returned no outputs\"\n payload = json.loads(results[0].text)\n status = payload[\"status\"]\n\n if status == \"error\":\n metadata = payload.get(\"metadata\") or {}\n reason = payload.get(\"content\") or metadata.get(\"message\") or \"Claude CLI reported an error\"\n pytest.skip(f\"Skipping Claude integration test: {reason}\")\n\n assert status in {\"success\", \"continuation_available\"}\n\n content = payload.get(\"content\", \"\").strip()\n assert content == \"4\"\n\n if status == \"continuation_available\":\n offer = payload.get(\"continuation_offer\") or {}\n assert offer.get(\"continuation_id\"), \"Expected continuation metadata when status indicates availability\"\n" }, { "path": "tests/test_clink_parsers.py", "content": "import pytest\n\nfrom clink.parsers.base import ParserError\nfrom clink.parsers.codex import CodexJSONLParser\n\n\ndef test_codex_parser_success():\n parser = CodexJSONLParser()\n stdout = \"\"\"\n{\"type\":\"item.completed\",\"item\":{\"id\":\"item_0\",\"type\":\"agent_message\",\"text\":\"Hello\"}}\n{\"type\":\"turn.completed\",\"usage\":{\"input_tokens\":10,\"output_tokens\":5}}\n\"\"\"\n parsed = parser.parse(stdout=stdout, stderr=\"\")\n assert parsed.content == \"Hello\"\n assert parsed.metadata[\"usage\"][\"output_tokens\"] == 5\n\n\ndef test_codex_parser_requires_agent_message():\n parser = CodexJSONLParser()\n stdout = '{\"type\":\"turn.completed\"}'\n with pytest.raises(ParserError):\n parser.parse(stdout=stdout, stderr=\"\")\n" }, { "path": "tests/test_clink_tool.py", "content": "import json\n\nimport pytest\n\nfrom clink import get_registry\nfrom clink.agents import AgentOutput\nfrom clink.parsers.base import ParsedCLIResponse\nfrom tools.clink import MAX_RESPONSE_CHARS, CLinkTool\n\n\n@pytest.mark.asyncio\nasync def test_clink_tool_execute(monkeypatch):\n tool = CLinkTool()\n\n async def fake_run(**kwargs):\n return AgentOutput(\n parsed=ParsedCLIResponse(content=\"Hello from Gemini\", metadata={\"model_used\": \"gemini-2.5-pro\"}),\n sanitized_command=[\"gemini\", \"-o\", \"json\"],\n returncode=0,\n stdout='{\"response\": \"Hello from Gemini\"}',\n stderr=\"\",\n duration_seconds=0.42,\n parser_name=\"gemini_json\",\n output_file_content=None,\n )\n\n class DummyAgent:\n async def run(self, **kwargs):\n return await fake_run(**kwargs)\n\n def fake_create_agent(client):\n return DummyAgent()\n\n monkeypatch.setattr(\"tools.clink.create_agent\", fake_create_agent)\n\n arguments = {\n \"prompt\": \"Summarize the project\",\n \"cli_name\": \"gemini\",\n \"role\": \"default\",\n \"absolute_file_paths\": [],\n \"images\": [],\n }\n\n results = await tool.execute(arguments)\n assert len(results) == 1\n\n payload = json.loads(results[0].text)\n assert payload[\"status\"] in {\"success\", \"continuation_available\"}\n assert \"Hello from Gemini\" in payload[\"content\"]\n metadata = payload.get(\"metadata\", {})\n assert metadata.get(\"cli_name\") == \"gemini\"\n assert metadata.get(\"command\") == [\"gemini\", \"-o\", \"json\"]\n\n\ndef test_registry_lists_roles():\n registry = get_registry()\n clients = registry.list_clients()\n assert {\"codex\", \"gemini\"}.issubset(set(clients))\n roles = registry.list_roles(\"gemini\")\n assert \"default\" in roles\n assert \"default\" in registry.list_roles(\"codex\")\n codex_client = registry.get_client(\"codex\")\n # Verify codex uses --enable web_search_request (not --search which is unsupported by exec)\n assert codex_client.config_args == [\n \"--json\",\n \"--dangerously-bypass-approvals-and-sandbox\",\n \"--enable\",\n \"web_search_request\",\n ]\n\n\n@pytest.mark.asyncio\nasync def test_clink_tool_defaults_to_first_cli(monkeypatch):\n tool = CLinkTool()\n\n async def fake_run(**kwargs):\n return AgentOutput(\n parsed=ParsedCLIResponse(content=\"Default CLI response\", metadata={\"events\": [\"foo\"]}),\n sanitized_command=[\"gemini\"],\n returncode=0,\n stdout='{\"response\": \"Default CLI response\"}',\n stderr=\"\",\n duration_seconds=0.1,\n parser_name=\"gemini_json\",\n output_file_content=None,\n )\n\n class DummyAgent:\n async def run(self, **kwargs):\n return await fake_run(**kwargs)\n\n monkeypatch.setattr(\"tools.clink.create_agent\", lambda client: DummyAgent())\n\n arguments = {\n \"prompt\": \"Hello\",\n \"absolute_file_paths\": [],\n \"images\": [],\n }\n\n result = await tool.execute(arguments)\n payload = json.loads(result[0].text)\n metadata = payload.get(\"metadata\", {})\n assert metadata.get(\"cli_name\") == tool._default_cli_name\n assert metadata.get(\"events_removed_for_normal\") is True\n\n\n@pytest.mark.asyncio\nasync def test_clink_tool_truncates_large_output(monkeypatch):\n tool = CLinkTool()\n\n summary_section = \"This is the condensed summary.\"\n long_text = \"A\" * (MAX_RESPONSE_CHARS + 500) + summary_section\n\n async def fake_run(**kwargs):\n return AgentOutput(\n parsed=ParsedCLIResponse(content=long_text, metadata={\"events\": [\"event1\", \"event2\"]}),\n sanitized_command=[\"codex\"],\n returncode=0,\n stdout=\"{}\",\n stderr=\"\",\n duration_seconds=0.2,\n parser_name=\"codex_jsonl\",\n output_file_content=None,\n )\n\n class DummyAgent:\n async def run(self, **kwargs):\n return await fake_run(**kwargs)\n\n monkeypatch.setattr(\"tools.clink.create_agent\", lambda client: DummyAgent())\n\n arguments = {\n \"prompt\": \"Summarize\",\n \"cli_name\": tool._default_cli_name,\n \"absolute_file_paths\": [],\n \"images\": [],\n }\n\n result = await tool.execute(arguments)\n payload = json.loads(result[0].text)\n assert payload[\"status\"] in {\"success\", \"continuation_available\"}\n assert payload[\"content\"].strip() == \"This is the condensed summary.\"\n metadata = payload.get(\"metadata\", {})\n assert metadata.get(\"output_summarized\") is True\n assert metadata.get(\"events_removed_for_normal\") is True\n assert metadata.get(\"output_original_length\") == len(long_text)\n\n\n@pytest.mark.asyncio\nasync def test_clink_tool_truncates_without_summary(monkeypatch):\n tool = CLinkTool()\n\n long_text = \"B\" * (MAX_RESPONSE_CHARS + 1000)\n\n async def fake_run(**kwargs):\n return AgentOutput(\n parsed=ParsedCLIResponse(content=long_text, metadata={\"events\": [\"event\"]}),\n sanitized_command=[\"codex\"],\n returncode=0,\n stdout=\"{}\",\n stderr=\"\",\n duration_seconds=0.2,\n parser_name=\"codex_jsonl\",\n output_file_content=None,\n )\n\n class DummyAgent:\n async def run(self, **kwargs):\n return await fake_run(**kwargs)\n\n monkeypatch.setattr(\"tools.clink.create_agent\", lambda client: DummyAgent())\n\n arguments = {\n \"prompt\": \"Summarize\",\n \"cli_name\": tool._default_cli_name,\n \"absolute_file_paths\": [],\n \"images\": [],\n }\n\n result = await tool.execute(arguments)\n payload = json.loads(result[0].text)\n assert payload[\"status\"] in {\"success\", \"continuation_available\"}\n assert \"exceeding the configured clink limit\" in payload[\"content\"]\n metadata = payload.get(\"metadata\", {})\n assert metadata.get(\"output_truncated\") is True\n assert metadata.get(\"events_removed_for_normal\") is True\n assert metadata.get(\"output_original_length\") == len(long_text)\n" }, { "path": "tests/test_collaboration.py", "content": "\"\"\"\nTests for dynamic context request and collaboration features\n\"\"\"\n\nimport json\nimport os\nfrom unittest.mock import Mock, patch\n\nimport pytest\n\nfrom tests.mock_helpers import create_mock_provider\nfrom tools.analyze import AnalyzeTool\nfrom tools.debug import DebugIssueTool\nfrom tools.models import FilesNeededRequest, ToolOutput\n\n\nclass TestDynamicContextRequests:\n \"\"\"Test the dynamic context request mechanism\"\"\"\n\n @pytest.fixture\n def analyze_tool(self):\n return AnalyzeTool()\n\n @pytest.fixture\n def debug_tool(self):\n return DebugIssueTool()\n\n @pytest.mark.asyncio\n @patch(\"tools.shared.base_tool.BaseTool.get_model_provider\")\n async def test_clarification_request_parsing(self, mock_get_provider, analyze_tool):\n \"\"\"Test that tools correctly parse clarification requests\"\"\"\n # Mock model to return a clarification request\n clarification_json = json.dumps(\n {\n \"status\": \"files_required_to_continue\",\n \"mandatory_instructions\": \"I need to see the package.json file to understand dependencies\",\n \"files_needed\": [\"package.json\", \"package-lock.json\"],\n },\n ensure_ascii=False,\n )\n\n mock_provider = create_mock_provider()\n mock_provider.get_provider_type.return_value = Mock(value=\"google\")\n mock_provider.generate_content.return_value = Mock(\n content=clarification_json, usage={}, model_name=\"gemini-2.5-flash\", metadata={}\n )\n mock_get_provider.return_value = mock_provider\n\n result = await analyze_tool.execute(\n {\n \"step\": \"Analyze the dependencies used in this project\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Initial dependency analysis\",\n \"relevant_files\": [\"/absolute/path/src/index.js\"],\n }\n )\n\n assert len(result) == 1\n\n # Parse the response - analyze tool now uses workflow architecture\n response_data = json.loads(result[0].text)\n # Workflow tools may handle provider errors differently than simple tools\n # They might return error, expert analysis, or clarification requests\n assert response_data[\"status\"] in [\"calling_expert_analysis\", \"error\", \"files_required_to_continue\"]\n\n # Check that expert analysis was performed and contains the clarification\n if \"expert_analysis\" in response_data:\n expert_analysis = response_data[\"expert_analysis\"]\n # The mock should have returned the clarification JSON\n if \"raw_analysis\" in expert_analysis:\n analysis_content = expert_analysis[\"raw_analysis\"]\n assert \"package.json\" in analysis_content\n assert \"dependencies\" in analysis_content\n\n # For workflow tools, the files_needed logic is handled differently\n # The test validates that the mocked clarification content was processed\n assert \"step_number\" in response_data\n assert response_data[\"step_number\"] == 1\n\n @pytest.mark.asyncio\n @patch(\"tools.shared.base_tool.BaseTool.get_model_provider\")\n @patch(\"utils.conversation_memory.create_thread\", return_value=\"debug-test-uuid\")\n @patch(\"utils.conversation_memory.add_turn\")\n async def test_normal_response_not_parsed_as_clarification(\n self, mock_add_turn, mock_create_thread, mock_get_provider, debug_tool\n ):\n \"\"\"Test that normal investigation responses work correctly with new debug tool\"\"\"\n # The new debug tool uses self-investigation pattern\n result = await debug_tool.execute(\n {\n \"step\": \"Investigating NameError: name 'utils' is not defined\",\n \"step_number\": 1,\n \"total_steps\": 3,\n \"next_step_required\": True,\n \"findings\": \"The error indicates 'utils' module is not imported or defined\",\n \"files_checked\": [\"/code/main.py\"],\n \"relevant_files\": [\"/code/main.py\"],\n \"hypothesis\": \"Missing import statement for utils module\",\n \"confidence\": \"high\",\n }\n )\n\n assert len(result) == 1\n\n # Parse the response - new debug tool returns structured JSON\n response_data = json.loads(result[0].text)\n # Debug tool now returns \"pause_for_investigation\" to force actual investigation\n assert response_data[\"status\"] == \"pause_for_investigation\"\n assert response_data[\"step_number\"] == 1\n assert response_data[\"next_step_required\"] is True\n assert response_data[\"investigation_status\"][\"current_confidence\"] == \"high\"\n assert response_data[\"investigation_required\"] is True\n assert \"required_actions\" in response_data\n\n @pytest.mark.asyncio\n @patch(\"tools.shared.base_tool.BaseTool.get_model_provider\")\n async def test_malformed_clarification_request_treated_as_normal(self, mock_get_provider, analyze_tool):\n \"\"\"Test that malformed JSON clarification requests are treated as normal responses\"\"\"\n malformed_json = '{\"status\": \"files_required_to_continue\", \"prompt\": \"Missing closing brace\"'\n\n mock_provider = create_mock_provider()\n mock_provider.get_provider_type.return_value = Mock(value=\"google\")\n mock_provider.generate_content.return_value = Mock(\n content=malformed_json, usage={}, model_name=\"gemini-2.5-flash\", metadata={}\n )\n mock_get_provider.return_value = mock_provider\n\n result = await analyze_tool.execute(\n {\n \"step\": \"What does this do?\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Initial code analysis\",\n \"relevant_files\": [\"/absolute/path/test.py\"],\n }\n )\n\n assert len(result) == 1\n\n # Should be treated as normal response due to JSON parse error\n response_data = json.loads(result[0].text)\n # Workflow tools may handle provider errors differently than simple tools\n # They might return error, expert analysis, or clarification requests\n assert response_data[\"status\"] in [\"calling_expert_analysis\", \"error\", \"files_required_to_continue\"]\n\n # The malformed JSON should appear in the expert analysis content\n if \"expert_analysis\" in response_data:\n expert_analysis = response_data[\"expert_analysis\"]\n if \"raw_analysis\" in expert_analysis:\n analysis_content = expert_analysis[\"raw_analysis\"]\n # The malformed JSON should be included in the analysis\n assert \"files_required_to_continue\" in analysis_content or malformed_json in str(response_data)\n\n @pytest.mark.asyncio\n @patch(\"tools.shared.base_tool.BaseTool.get_model_provider\")\n async def test_clarification_with_suggested_action(self, mock_get_provider, analyze_tool):\n \"\"\"Test clarification request with suggested next action\"\"\"\n import importlib\n\n from providers.registry import ModelProviderRegistry\n\n # Ensure deterministic model configuration for this test regardless of previous suites\n ModelProviderRegistry.reset_for_testing()\n\n original_default = os.environ.get(\"DEFAULT_MODEL\")\n\n try:\n os.environ[\"DEFAULT_MODEL\"] = \"gemini-2.5-flash\"\n import config\n\n importlib.reload(config)\n\n clarification_json = json.dumps(\n {\n \"status\": \"files_required_to_continue\",\n \"mandatory_instructions\": \"I need to see the database configuration to analyze the connection error\",\n \"files_needed\": [\"config/database.yml\", \"src/db.py\"],\n \"suggested_next_action\": {\n \"tool\": \"analyze\",\n \"args\": {\n \"prompt\": \"Analyze database connection timeout issue\",\n \"relevant_files\": [\n \"/config/database.yml\",\n \"/src/db.py\",\n \"/logs/error.log\",\n ],\n },\n },\n },\n ensure_ascii=False,\n )\n\n mock_provider = create_mock_provider()\n mock_provider.get_provider_type.return_value = Mock(value=\"google\")\n mock_provider.generate_content.return_value = Mock(\n content=clarification_json, usage={}, model_name=\"gemini-2.5-flash\", metadata={}\n )\n mock_get_provider.return_value = mock_provider\n\n result = await analyze_tool.execute(\n {\n \"step\": \"Analyze database connection timeout issue\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Initial database timeout analysis\",\n \"relevant_files\": [\"/absolute/logs/error.log\"],\n }\n )\n\n assert len(result) == 1\n\n response_data = json.loads(result[0].text)\n\n # Workflow tools should either promote clarification status or handle it in expert analysis\n if response_data[\"status\"] == \"files_required_to_continue\":\n # Clarification was properly promoted to main status\n # Check if mandatory_instructions is at top level or in content\n if \"mandatory_instructions\" in response_data:\n assert \"database configuration\" in response_data[\"mandatory_instructions\"]\n assert \"files_needed\" in response_data\n assert \"config/database.yml\" in response_data[\"files_needed\"]\n assert \"src/db.py\" in response_data[\"files_needed\"]\n elif \"content\" in response_data:\n # Parse content JSON for workflow tools\n try:\n content_json = json.loads(response_data[\"content\"])\n assert \"mandatory_instructions\" in content_json\n assert (\n \"database configuration\" in content_json[\"mandatory_instructions\"]\n or \"database\" in content_json[\"mandatory_instructions\"]\n )\n assert \"files_needed\" in content_json\n files_needed_str = str(content_json[\"files_needed\"])\n assert (\n \"config/database.yml\" in files_needed_str\n or \"config\" in files_needed_str\n or \"database\" in files_needed_str\n )\n except json.JSONDecodeError:\n # Content is not JSON, check if it contains required text\n content = response_data[\"content\"]\n assert \"database configuration\" in content or \"config\" in content\n elif response_data[\"status\"] == \"calling_expert_analysis\":\n # Clarification may be handled in expert analysis section\n if \"expert_analysis\" in response_data:\n expert_analysis = response_data[\"expert_analysis\"]\n expert_content = str(expert_analysis)\n assert (\n \"database configuration\" in expert_content\n or \"config/database.yml\" in expert_content\n or \"files_required_to_continue\" in expert_content\n )\n else:\n # Some other status - ensure it's a valid workflow response\n assert \"step_number\" in response_data\n\n # Check for suggested next action\n if \"suggested_next_action\" in response_data:\n action = response_data[\"suggested_next_action\"]\n assert action[\"tool\"] == \"analyze\"\n finally:\n if original_default is not None:\n os.environ[\"DEFAULT_MODEL\"] = original_default\n else:\n os.environ.pop(\"DEFAULT_MODEL\", None)\n\n import config\n\n importlib.reload(config)\n ModelProviderRegistry.reset_for_testing()\n\n def test_tool_output_model_serialization(self):\n \"\"\"Test ToolOutput model serialization\"\"\"\n output = ToolOutput(\n status=\"success\",\n content=\"Test content\",\n content_type=\"markdown\",\n metadata={\"tool_name\": \"test\", \"execution_time\": 1.5},\n )\n\n json_str = output.model_dump_json()\n parsed = json.loads(json_str)\n\n assert parsed[\"status\"] == \"success\"\n assert parsed[\"content\"] == \"Test content\"\n assert parsed[\"content_type\"] == \"markdown\"\n assert parsed[\"metadata\"][\"tool_name\"] == \"test\"\n\n def test_clarification_request_model(self):\n \"\"\"Test FilesNeededRequest model\"\"\"\n request = FilesNeededRequest(\n mandatory_instructions=\"Need more context\",\n files_needed=[\"file1.py\", \"file2.py\"],\n suggested_next_action={\"tool\": \"analyze\", \"args\": {}},\n )\n\n assert request.mandatory_instructions == \"Need more context\"\n assert len(request.files_needed) == 2\n assert request.suggested_next_action[\"tool\"] == \"analyze\"\n\n @pytest.mark.asyncio\n @patch(\"tools.shared.base_tool.BaseTool.get_model_provider\")\n async def test_error_response_format(self, mock_get_provider, analyze_tool):\n \"\"\"Test error response format\"\"\"\n mock_get_provider.side_effect = Exception(\"API connection failed\")\n\n result = await analyze_tool.execute(\n {\n \"step\": \"Analyze this\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Initial analysis\",\n \"relevant_files\": [\"/absolute/path/test.py\"],\n }\n )\n\n assert len(result) == 1\n\n response_data = json.loads(result[0].text)\n # Workflow tools may handle provider errors differently than simple tools\n # They might return error, complete analysis, or even clarification requests\n assert response_data[\"status\"] in [\"error\", \"calling_expert_analysis\", \"files_required_to_continue\"]\n\n # If expert analysis was attempted, it may succeed or fail\n if response_data[\"status\"] == \"calling_expert_analysis\" and \"expert_analysis\" in response_data:\n expert_analysis = response_data[\"expert_analysis\"]\n # Could be an error or a successful analysis that requests clarification\n analysis_status = expert_analysis.get(\"status\", \"\")\n assert (\n analysis_status in [\"analysis_error\", \"analysis_complete\"]\n or \"error\" in expert_analysis\n or \"files_required_to_continue\" in str(expert_analysis)\n )\n elif response_data[\"status\"] == \"error\":\n assert \"content\" in response_data\n assert response_data[\"content_type\"] == \"text\"\n\n\nclass TestCollaborationWorkflow:\n \"\"\"Test complete collaboration workflows\"\"\"\n\n def teardown_method(self):\n \"\"\"Clean up after each test to prevent state pollution.\"\"\"\n # Clear provider registry singleton\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry._instance = None\n\n @pytest.mark.asyncio\n @patch(\"tools.shared.base_tool.BaseTool.get_model_provider\")\n @patch(\"tools.workflow.workflow_mixin.BaseWorkflowMixin._call_expert_analysis\")\n async def test_dependency_analysis_triggers_clarification(self, mock_expert_analysis, mock_get_provider):\n \"\"\"Test that asking about dependencies without package files triggers clarification\"\"\"\n tool = AnalyzeTool()\n\n # Mock Gemini to request package.json when asked about dependencies\n clarification_json = json.dumps(\n {\n \"status\": \"files_required_to_continue\",\n \"mandatory_instructions\": \"I need to see the package.json file to analyze npm dependencies\",\n \"files_needed\": [\"package.json\", \"package-lock.json\"],\n },\n ensure_ascii=False,\n )\n\n mock_provider = create_mock_provider()\n mock_provider.get_provider_type.return_value = Mock(value=\"google\")\n mock_provider.generate_content.return_value = Mock(\n content=clarification_json, usage={}, model_name=\"gemini-2.5-flash\", metadata={}\n )\n mock_get_provider.return_value = mock_provider\n\n # Mock expert analysis to avoid actual API calls\n mock_expert_analysis.return_value = {\n \"status\": \"analysis_complete\",\n \"raw_analysis\": \"I need to see the package.json file to analyze npm dependencies\",\n }\n\n # Ask about dependencies with only source files (using new workflow format)\n result = await tool.execute(\n {\n \"step\": \"What npm packages and versions does this project use?\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Initial dependency analysis\",\n \"relevant_files\": [\"/absolute/path/src/index.js\"],\n }\n )\n\n response = json.loads(result[0].text)\n\n # Workflow tools should either promote clarification status or handle it in expert analysis\n if response[\"status\"] == \"files_required_to_continue\":\n # Clarification was properly promoted to main status\n assert \"mandatory_instructions\" in response\n assert \"package.json\" in response[\"mandatory_instructions\"]\n assert \"files_needed\" in response\n assert \"package.json\" in response[\"files_needed\"]\n assert \"package-lock.json\" in response[\"files_needed\"]\n elif response[\"status\"] == \"calling_expert_analysis\":\n # Clarification may be handled in expert analysis section\n if \"expert_analysis\" in response:\n expert_analysis = response[\"expert_analysis\"]\n expert_content = str(expert_analysis)\n assert (\n \"package.json\" in expert_content\n or \"dependencies\" in expert_content\n or \"files_required_to_continue\" in expert_content\n )\n else:\n # Some other status - ensure it's a valid workflow response\n assert \"step_number\" in response\n\n @pytest.mark.asyncio\n @patch(\"tools.shared.base_tool.BaseTool.get_model_provider\")\n @patch(\"tools.workflow.workflow_mixin.BaseWorkflowMixin._call_expert_analysis\")\n async def test_multi_step_collaboration(self, mock_expert_analysis, mock_get_provider):\n \"\"\"Test a multi-step collaboration workflow\"\"\"\n tool = AnalyzeTool()\n\n # Step 1: Initial request returns clarification needed\n clarification_json = json.dumps(\n {\n \"status\": \"files_required_to_continue\",\n \"mandatory_instructions\": \"I need to see the configuration file to understand the connection settings\",\n \"files_needed\": [\"config.py\"],\n },\n ensure_ascii=False,\n )\n\n mock_provider = create_mock_provider()\n mock_provider.get_provider_type.return_value = Mock(value=\"google\")\n mock_provider.generate_content.return_value = Mock(\n content=clarification_json, usage={}, model_name=\"gemini-2.5-flash\", metadata={}\n )\n mock_get_provider.return_value = mock_provider\n\n # Mock expert analysis to avoid actual API calls\n mock_expert_analysis.return_value = {\n \"status\": \"analysis_complete\",\n \"raw_analysis\": \"I need to see the configuration file to understand the database connection settings\",\n }\n\n result1 = await tool.execute(\n {\n \"step\": \"Analyze database connection timeout issue\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Initial database timeout analysis\",\n \"relevant_files\": [\"/logs/error.log\"],\n }\n )\n\n response1 = json.loads(result1[0].text)\n\n # First call should either return clarification request or handle it in expert analysis\n if response1[\"status\"] == \"files_required_to_continue\":\n # Clarification was properly promoted to main status\n pass # This is the expected behavior\n elif response1[\"status\"] == \"calling_expert_analysis\":\n # Clarification may be handled in expert analysis section\n if \"expert_analysis\" in response1:\n expert_analysis = response1[\"expert_analysis\"]\n expert_content = str(expert_analysis)\n # Should contain some indication of clarification request\n assert (\n \"config\" in expert_content\n or \"files_required_to_continue\" in expert_content\n or \"database\" in expert_content\n )\n else:\n # Some other status - ensure it's a valid workflow response\n assert \"step_number\" in response1\n\n # Step 2: Claude would provide additional context and re-invoke\n # This simulates the second call with more context\n final_response = \"\"\"\n ## Summary\n The database connection timeout is caused by incorrect host configuration.\n\n ## Hypotheses (Ranked by Likelihood)\n\n ### 1. Incorrect Database Host (Confidence: High)\n **Root Cause:** The config.py file shows the database host is set to 'localhost' but the database is running on a different server.\n \"\"\"\n\n mock_provider.generate_content.return_value = Mock(\n content=final_response, usage={}, model_name=\"gemini-2.5-flash\", metadata={}\n )\n\n # Update expert analysis mock for second call\n mock_expert_analysis.return_value = {\n \"status\": \"analysis_complete\",\n \"raw_analysis\": final_response,\n }\n\n result2 = await tool.execute(\n {\n \"step\": \"Analyze database connection timeout issue with config file\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Analysis with configuration context\",\n \"relevant_files\": [\"/absolute/path/config.py\", \"/logs/error.log\"], # Additional context provided\n }\n )\n\n response2 = json.loads(result2[0].text)\n\n # Workflow tools should either return expert analysis or handle clarification properly\n # Accept multiple valid statuses as the workflow can handle the additional context differently\n # Include 'error' status in case API calls fail in test environment\n assert response2[\"status\"] in [\n \"calling_expert_analysis\",\n \"files_required_to_continue\",\n \"pause_for_analysis\",\n \"error\",\n ]\n\n # Check that the response contains the expected content regardless of status\n\n # If expert analysis was performed, verify content is there\n if \"expert_analysis\" in response2:\n expert_analysis = response2[\"expert_analysis\"]\n if \"raw_analysis\" in expert_analysis:\n analysis_content = expert_analysis[\"raw_analysis\"]\n assert (\n \"incorrect host configuration\" in analysis_content.lower() or \"database\" in analysis_content.lower()\n )\n elif response2[\"status\"] == \"files_required_to_continue\":\n # If clarification is still being requested, ensure it's reasonable\n # Since we provided config.py and error.log, workflow tool might still need more context\n assert \"step_number\" in response2 # Should be valid workflow response\n else:\n # For other statuses, ensure basic workflow structure is maintained\n assert \"step_number\" in response2\n" }, { "path": "tests/test_config.py", "content": "\"\"\"\nTests for configuration\n\"\"\"\n\nfrom config import (\n DEFAULT_MODEL,\n TEMPERATURE_ANALYTICAL,\n TEMPERATURE_BALANCED,\n TEMPERATURE_CREATIVE,\n __author__,\n __updated__,\n __version__,\n)\n\n\nclass TestConfig:\n \"\"\"Test configuration values\"\"\"\n\n def test_version_info(self):\n \"\"\"Test version information exists and has correct format\"\"\"\n # Check version format (e.g., \"2.4.1\")\n assert isinstance(__version__, str)\n assert len(__version__.split(\".\")) == 3 # Major.Minor.Patch\n\n # Check author\n assert __author__ == \"Fahad Gilani\"\n\n # Check updated date exists (don't assert on specific format/value)\n assert isinstance(__updated__, str)\n\n def test_model_config(self):\n \"\"\"Test model configuration\"\"\"\n # DEFAULT_MODEL is set in conftest.py for tests\n assert DEFAULT_MODEL == \"gemini-2.5-flash\"\n\n def test_temperature_defaults(self):\n \"\"\"Test temperature constants\"\"\"\n assert TEMPERATURE_ANALYTICAL == 1.0\n assert TEMPERATURE_BALANCED == 1.0\n assert TEMPERATURE_CREATIVE == 1.0\n" }, { "path": "tests/test_consensus.py", "content": "\"\"\"\nTests for the Consensus tool using WorkflowTool architecture.\n\"\"\"\n\nfrom unittest.mock import Mock\n\nimport pytest\n\nfrom tools.consensus import ConsensusRequest, ConsensusTool\nfrom tools.models import ToolModelCategory\n\n\nclass TestConsensusTool:\n \"\"\"Test suite for ConsensusTool using WorkflowTool architecture.\"\"\"\n\n def test_tool_metadata(self):\n \"\"\"Test basic tool metadata and configuration.\"\"\"\n tool = ConsensusTool()\n\n assert tool.get_name() == \"consensus\"\n assert \"consensus\" in tool.get_description()\n assert tool.get_default_temperature() == 1.0 # TEMPERATURE_ANALYTICAL\n assert tool.get_model_category() == ToolModelCategory.EXTENDED_REASONING\n assert tool.requires_model() is False # Consensus manages its own models\n\n def test_request_validation_step1(self):\n \"\"\"Test Pydantic request model validation for step 1.\"\"\"\n # Valid step 1 request with models\n step1_request = ConsensusRequest(\n step=\"Analyzing the real-time collaboration proposal\",\n step_number=1,\n total_steps=4, # 1 (Claude) + 2 models + 1 (synthesis)\n next_step_required=True,\n findings=\"Initial assessment shows strong value but technical complexity\",\n confidence=\"medium\",\n models=[{\"model\": \"flash\", \"stance\": \"neutral\"}, {\"model\": \"o3-mini\", \"stance\": \"for\"}],\n relevant_files=[\"/proposal.md\"],\n )\n\n assert step1_request.step_number == 1\n assert step1_request.confidence == \"medium\"\n assert len(step1_request.models) == 2\n assert step1_request.models[0][\"model\"] == \"flash\"\n\n def test_request_validation_missing_models_step1(self):\n \"\"\"Test that step 1 requires models field.\"\"\"\n with pytest.raises(ValueError, match=\"Step 1 requires 'models' field\"):\n ConsensusRequest(\n step=\"Test step\",\n step_number=1,\n total_steps=3,\n next_step_required=True,\n findings=\"Test findings\",\n # Missing models field\n )\n\n def test_request_validation_later_steps(self):\n \"\"\"Test request validation for steps 2+.\"\"\"\n # Step 2+ doesn't require models field\n step2_request = ConsensusRequest(\n step=\"Processing first model response\",\n step_number=2,\n total_steps=4,\n next_step_required=True,\n findings=\"Model provided supportive perspective\",\n confidence=\"medium\",\n continuation_id=\"test-id\",\n current_model_index=1,\n )\n\n assert step2_request.step_number == 2\n assert step2_request.models is None # Not required after step 1\n\n def test_request_validation_duplicate_model_stance(self):\n \"\"\"Test that duplicate model+stance combinations are rejected.\"\"\"\n # Valid: same model with different stances\n valid_request = ConsensusRequest(\n step=\"Analyze this proposal\",\n step_number=1,\n total_steps=1,\n next_step_required=True,\n findings=\"Initial analysis\",\n models=[\n {\"model\": \"o3\", \"stance\": \"for\"},\n {\"model\": \"o3\", \"stance\": \"against\"},\n {\"model\": \"flash\", \"stance\": \"neutral\"},\n ],\n continuation_id=\"test-id\",\n )\n assert len(valid_request.models) == 3\n\n # Invalid: duplicate model+stance combination\n with pytest.raises(ValueError, match=\"Duplicate model \\\\+ stance combination\"):\n ConsensusRequest(\n step=\"Analyze this proposal\",\n step_number=1,\n total_steps=1,\n next_step_required=True,\n findings=\"Initial analysis\",\n models=[\n {\"model\": \"o3\", \"stance\": \"for\"},\n {\"model\": \"flash\", \"stance\": \"neutral\"},\n {\"model\": \"o3\", \"stance\": \"for\"}, # Duplicate!\n ],\n continuation_id=\"test-id\",\n )\n\n def test_input_schema_generation(self):\n \"\"\"Test that input schema is generated correctly.\"\"\"\n tool = ConsensusTool()\n schema = tool.get_input_schema()\n\n # Verify consensus workflow fields are present\n assert \"step\" in schema[\"properties\"]\n assert \"step_number\" in schema[\"properties\"]\n assert \"total_steps\" in schema[\"properties\"]\n assert \"next_step_required\" in schema[\"properties\"]\n assert \"findings\" in schema[\"properties\"]\n # confidence field should be excluded\n assert \"confidence\" not in schema[\"properties\"]\n assert \"models\" in schema[\"properties\"]\n # relevant_files should be present as it's used by consensus\n assert \"relevant_files\" in schema[\"properties\"]\n\n # model field should NOT be present as consensus uses 'models' field instead\n assert \"model\" not in schema[\"properties\"]\n\n # Verify workflow fields that should NOT be present\n assert \"files_checked\" not in schema[\"properties\"]\n assert \"hypothesis\" not in schema[\"properties\"]\n assert \"issues_found\" not in schema[\"properties\"]\n assert \"temperature\" not in schema[\"properties\"]\n assert \"thinking_mode\" not in schema[\"properties\"]\n\n # Images should be present now\n assert \"images\" in schema[\"properties\"]\n assert schema[\"properties\"][\"images\"][\"type\"] == \"array\"\n assert schema[\"properties\"][\"images\"][\"items\"][\"type\"] == \"string\"\n\n # Verify field types\n assert schema[\"properties\"][\"step\"][\"type\"] == \"string\"\n assert schema[\"properties\"][\"step_number\"][\"type\"] == \"integer\"\n assert schema[\"properties\"][\"models\"][\"type\"] == \"array\"\n\n # Verify models array structure\n models_items = schema[\"properties\"][\"models\"][\"items\"]\n assert models_items[\"type\"] == \"object\"\n assert \"model\" in models_items[\"properties\"]\n assert \"stance\" in models_items[\"properties\"]\n assert \"stance_prompt\" in models_items[\"properties\"]\n\n def test_get_required_actions(self):\n \"\"\"Test required actions for different consensus phases.\"\"\"\n tool = ConsensusTool()\n\n # Step 1: Claude's initial analysis\n actions = tool.get_required_actions(1, \"exploring\", \"Initial findings\", 4)\n assert any(\"initial analysis\" in action for action in actions)\n assert any(\"consult other models\" in action for action in actions)\n\n # Step 2-3: Model consultations\n actions = tool.get_required_actions(2, \"medium\", \"Model findings\", 4)\n assert any(\"Review the model response\" in action for action in actions)\n\n # Final step: Synthesis\n actions = tool.get_required_actions(4, \"high\", \"All findings\", 4)\n assert any(\"All models have been consulted\" in action for action in actions)\n assert any(\"Synthesize all perspectives\" in action for action in actions)\n\n def test_prepare_step_data(self):\n \"\"\"Test step data preparation for consensus workflow.\"\"\"\n tool = ConsensusTool()\n request = ConsensusRequest(\n step=\"Test step\",\n step_number=1,\n total_steps=3,\n next_step_required=True,\n findings=\"Test findings\",\n confidence=\"medium\",\n models=[{\"model\": \"test\"}],\n relevant_files=[\"/test.py\"],\n )\n\n step_data = tool.prepare_step_data(request)\n\n # Verify consensus-specific fields\n assert step_data[\"step\"] == \"Test step\"\n assert step_data[\"findings\"] == \"Test findings\"\n assert step_data[\"relevant_files\"] == [\"/test.py\"]\n\n # Verify unused workflow fields are empty\n assert step_data[\"files_checked\"] == []\n assert step_data[\"relevant_context\"] == []\n assert step_data[\"issues_found\"] == []\n assert step_data[\"hypothesis\"] is None\n\n def test_stance_enhanced_prompt_generation(self):\n \"\"\"Test stance-enhanced prompt generation.\"\"\"\n tool = ConsensusTool()\n\n # Test different stances\n for_prompt = tool._get_stance_enhanced_prompt(\"for\")\n assert \"SUPPORTIVE PERSPECTIVE\" in for_prompt\n\n against_prompt = tool._get_stance_enhanced_prompt(\"against\")\n assert \"CRITICAL PERSPECTIVE\" in against_prompt\n\n neutral_prompt = tool._get_stance_enhanced_prompt(\"neutral\")\n assert \"BALANCED PERSPECTIVE\" in neutral_prompt\n\n # Test custom stance prompt\n custom = \"Focus on specific aspects\"\n custom_prompt = tool._get_stance_enhanced_prompt(\"for\", custom)\n assert custom in custom_prompt\n assert \"SUPPORTIVE PERSPECTIVE\" not in custom_prompt\n\n def test_should_call_expert_analysis(self):\n \"\"\"Test that consensus workflow doesn't use expert analysis.\"\"\"\n tool = ConsensusTool()\n assert tool.should_call_expert_analysis({}) is False\n assert tool.requires_expert_analysis() is False\n\n def test_execute_workflow_step1_basic(self):\n \"\"\"Test basic workflow validation for step 1.\"\"\"\n tool = ConsensusTool()\n\n # Test that step 1 sets up the workflow correctly\n arguments = {\n \"step\": \"Initial analysis of proposal\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"findings\": \"Found pros and cons\",\n \"models\": [{\"model\": \"flash\", \"stance\": \"neutral\"}, {\"model\": \"o3-mini\", \"stance\": \"for\"}],\n }\n\n # Verify models_to_consult is set correctly from step 1\n request = tool.get_workflow_request_model()(**arguments)\n assert len(request.models) == 2\n assert request.models[0][\"model\"] == \"flash\"\n assert request.models[1][\"model\"] == \"o3-mini\"\n\n def test_execute_workflow_total_steps_calculation(self):\n \"\"\"Test that total_steps is calculated correctly from models.\"\"\"\n tool = ConsensusTool()\n\n # Test with 2 models\n arguments = {\n \"step\": \"Initial analysis\",\n \"step_number\": 1,\n \"total_steps\": 4, # This should be corrected to 2\n \"next_step_required\": True,\n \"findings\": \"Analysis complete\",\n \"models\": [{\"model\": \"flash\", \"stance\": \"neutral\"}, {\"model\": \"o3-mini\", \"stance\": \"for\"}],\n }\n\n request = tool.get_workflow_request_model()(**arguments)\n # The tool should set total_steps = len(models) = 2\n assert len(request.models) == 2\n\n def test_consult_model_basic_structure(self):\n \"\"\"Test basic model consultation structure.\"\"\"\n tool = ConsensusTool()\n\n # Test that _get_stance_enhanced_prompt works\n for_prompt = tool._get_stance_enhanced_prompt(\"for\")\n against_prompt = tool._get_stance_enhanced_prompt(\"against\")\n neutral_prompt = tool._get_stance_enhanced_prompt(\"neutral\")\n\n assert \"SUPPORTIVE PERSPECTIVE\" in for_prompt\n assert \"CRITICAL PERSPECTIVE\" in against_prompt\n assert \"BALANCED PERSPECTIVE\" in neutral_prompt\n\n def test_model_configuration_validation(self):\n \"\"\"Test model configuration validation.\"\"\"\n tool = ConsensusTool()\n\n # Test single model config\n models = [{\"model\": \"flash\", \"stance\": \"neutral\"}]\n arguments = {\n \"step\": \"Test\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Test findings\",\n \"models\": models,\n }\n\n request = tool.get_workflow_request_model()(**arguments)\n assert len(request.models) == 1\n assert request.models[0][\"model\"] == \"flash\"\n assert request.models[0][\"stance\"] == \"neutral\"\n\n def test_handle_work_continuation(self):\n \"\"\"Test work continuation handling - legacy method for compatibility.\"\"\"\n tool = ConsensusTool()\n tool.models_to_consult = [{\"model\": \"flash\", \"stance\": \"neutral\"}, {\"model\": \"o3-mini\", \"stance\": \"for\"}]\n\n # Note: In the new workflow, model consultation happens DURING steps in execute_workflow\n # This method is kept for compatibility but not actively used in the step-by-step flow\n\n # Test after step 1\n request = Mock(step_number=1, current_model_index=0)\n response_data = {}\n\n result = tool.handle_work_continuation(response_data, request)\n # The method still exists but returns legacy status for compatibility\n assert \"status\" in result\n\n # Test between model consultations\n request = Mock(step_number=2, current_model_index=1)\n response_data = {}\n\n result = tool.handle_work_continuation(response_data, request)\n assert \"status\" in result\n\n def test_customize_workflow_response(self):\n \"\"\"Test response customization for consensus workflow.\"\"\"\n tool = ConsensusTool()\n tool.accumulated_responses = [{\"model\": \"test\", \"response\": \"data\"}]\n\n # Test different step numbers (new workflow: 2 models = 2 steps)\n request = Mock(step_number=1, total_steps=2)\n response_data = {}\n result = tool.customize_workflow_response(response_data, request)\n assert result[\"consensus_workflow_status\"] == \"initial_analysis_complete\"\n\n request = Mock(step_number=2, total_steps=2)\n response_data = {}\n result = tool.customize_workflow_response(response_data, request)\n assert result[\"consensus_workflow_status\"] == \"ready_for_synthesis\"\n\n @pytest.mark.asyncio\n async def test_consensus_with_relevant_files_model_context_fix(self):\n \"\"\"Test that consensus tool properly handles relevant_files without RuntimeError.\n\n This is a regression test for the bug where _prepare_file_content_for_prompt\n was called without model_context parameter, causing RuntimeError:\n 'Model context not provided for file preparation'\n\n Bug details:\n - Occurred when consensus tool processed requests with relevant_files\n - _consult_model method called _prepare_file_content_for_prompt without model_context\n - Method expected model_context parameter but got None (default value)\n - Runtime validation in base_tool.py threw RuntimeError\n \"\"\"\n from unittest.mock import AsyncMock, Mock, patch\n\n from utils.model_context import ModelContext\n\n tool = ConsensusTool()\n\n # Create a mock request with relevant_files (the trigger condition)\n mock_request = Mock()\n mock_request.relevant_files = [\"/test/file1.py\", \"/test/file2.js\"]\n mock_request.continuation_id = None\n\n # Mock model configuration\n model_config = {\"model\": \"flash\", \"stance\": \"neutral\"}\n\n # Mock the provider and model name resolution\n with (\n patch.object(tool, \"get_model_provider\") as mock_get_provider,\n patch.object(tool, \"_prepare_file_content_for_prompt\") as mock_prepare_files,\n patch.object(tool, \"_get_stance_enhanced_prompt\") as mock_get_prompt,\n patch.object(tool, \"get_name\", return_value=\"consensus\"),\n ):\n\n # Setup mocks\n mock_provider = Mock()\n mock_provider.generate_content = AsyncMock(return_value={\"response\": \"test response\"})\n mock_get_provider.return_value = mock_provider\n mock_prepare_files.return_value = (\"file content\", [])\n mock_get_prompt.return_value = \"system prompt\"\n\n # Set up the tool's attributes that would be set during normal execution\n tool.original_proposal = \"Test proposal\"\n\n try:\n # This should not raise RuntimeError after the fix\n # The method should create ModelContext and pass it to _prepare_file_content_for_prompt\n await tool._consult_model(model_config, mock_request)\n\n # Verify that _prepare_file_content_for_prompt was called with model_context\n mock_prepare_files.assert_called_once()\n call_args = mock_prepare_files.call_args\n\n # Check that model_context was passed as keyword argument\n assert \"model_context\" in call_args.kwargs, \"model_context should be passed as keyword argument\"\n\n # Verify the model_context is a proper ModelContext instance\n model_context = call_args.kwargs[\"model_context\"]\n assert isinstance(model_context, ModelContext), \"model_context should be ModelContext instance\"\n\n # Verify model_context properties are correct\n assert model_context.model_name == \"flash\"\n # Note: provider is accessed lazily, conversation_history and tool_name\n # are not part of ModelContext constructor in current implementation\n\n except RuntimeError as e:\n if \"Model context not provided\" in str(e):\n pytest.fail(\"The model_context fix is not working. RuntimeError still occurs: \" + str(e))\n else:\n # Re-raise if it's a different RuntimeError\n raise\n\n\nif __name__ == \"__main__\":\n import unittest\n\n unittest.main()\n" }, { "path": "tests/test_consensus_integration.py", "content": "\"\"\"Integration test for ConsensusTool using OpenAI and Gemini recordings.\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport os\nfrom pathlib import Path\n\nimport pytest\n\nfrom providers.registry import ModelProviderRegistry\nfrom providers.shared import ProviderType\nfrom tests.transport_helpers import inject_transport\nfrom tools.consensus import ConsensusTool\n\n# Directories for recorded HTTP interactions\nCASSETTE_DIR = Path(__file__).parent / \"openai_cassettes\"\nCASSETTE_DIR.mkdir(exist_ok=True)\n\n# Mapping of OpenAI model names to their cassette files\nCONSENSUS_CASSETTES = {\n \"gpt-5\": CASSETTE_DIR / \"consensus_step1_gpt5_for.json\",\n \"gpt-5.2\": CASSETTE_DIR / \"consensus_step1_gpt52_for.json\",\n}\n\nGEMINI_REPLAY_DIR = Path(__file__).parent / \"gemini_cassettes\"\nGEMINI_REPLAY_DIR.mkdir(exist_ok=True)\nGEMINI_REPLAY_ID = \"consensus/step2_gemini25_flash_against/mldev\"\nGEMINI_REPLAY_PATH = GEMINI_REPLAY_DIR / \"consensus\" / \"step2_gemini25_flash_against\" / \"mldev.json\"\n\n\n@pytest.mark.integration\n@pytest.mark.asyncio\n@pytest.mark.no_mock_provider\n@pytest.mark.parametrize(\"openai_model\", [\"gpt-5\", \"gpt-5.2\"])\nasync def test_consensus_multi_model_consultations(monkeypatch, openai_model):\n \"\"\"Exercise ConsensusTool against OpenAI model (supporting) and gemini-2.5-flash (critical).\n\n Tests both gpt-5 and gpt-5.2 to ensure regression coverage for both model families.\n \"\"\"\n\n # Get the cassette path for this model\n consensus_cassette_path = CONSENSUS_CASSETTES[openai_model]\n\n env_updates = {\n \"DEFAULT_MODEL\": \"auto\",\n \"OPENAI_API_KEY\": os.getenv(\"OPENAI_API_KEY\", \"\"),\n \"GEMINI_API_KEY\": os.getenv(\"GEMINI_API_KEY\", \"\"),\n }\n keys_to_clear = [\n \"XAI_API_KEY\",\n \"OPENROUTER_API_KEY\",\n \"ANTHROPIC_API_KEY\",\n \"MISTRAL_API_KEY\",\n \"CUSTOM_API_KEY\",\n \"CUSTOM_API_URL\",\n ]\n\n recording_mode = not consensus_cassette_path.exists() or not GEMINI_REPLAY_PATH.exists()\n if recording_mode:\n openai_key = env_updates[\"OPENAI_API_KEY\"].strip()\n gemini_key = env_updates[\"GEMINI_API_KEY\"].strip()\n if (not openai_key or openai_key.startswith(\"dummy\")) or (not gemini_key or gemini_key.startswith(\"dummy\")):\n pytest.skip(\n \"Consensus cassette missing and OPENAI_API_KEY/GEMINI_API_KEY \"\n \"not configured. Provide real keys to record.\"\n )\n\n GEMINI_REPLAY_PATH.parent.mkdir(parents=True, exist_ok=True)\n\n with monkeypatch.context() as m:\n m.setenv(\"DEFAULT_MODEL\", env_updates[\"DEFAULT_MODEL\"])\n\n if recording_mode:\n m.setenv(\"OPENAI_API_KEY\", env_updates[\"OPENAI_API_KEY\"])\n m.setenv(\"GEMINI_API_KEY\", env_updates[\"GEMINI_API_KEY\"])\n m.setenv(\"GOOGLE_GENAI_CLIENT_MODE\", \"record\")\n else:\n m.setenv(\"OPENAI_API_KEY\", \"dummy-key-for-replay\")\n m.setenv(\"GEMINI_API_KEY\", \"dummy-key-for-replay\")\n m.setenv(\"GOOGLE_GENAI_CLIENT_MODE\", \"replay\")\n\n # Ensure restriction policies allow the latest OpenAI models under test\n m.setenv(\"OPENAI_ALLOWED_MODELS\", openai_model)\n\n m.setenv(\"GOOGLE_GENAI_REPLAYS_DIRECTORY\", str(GEMINI_REPLAY_DIR))\n m.setenv(\"GOOGLE_GENAI_REPLAY_ID\", GEMINI_REPLAY_ID)\n\n for key in keys_to_clear:\n m.delenv(key, raising=False)\n\n # Ensure we use the built-in OpenAI catalogue rather than leftovers from\n # other tests that patch OPENAI_MODELS_CONFIG_PATH.\n m.delenv(\"OPENAI_MODELS_CONFIG_PATH\", raising=False)\n\n # Reset providers/restrictions and register only OpenAI & Gemini for deterministic behavior\n ModelProviderRegistry.reset_for_testing()\n import utils.model_restrictions as model_restrictions\n\n model_restrictions._restriction_service = None\n from providers.gemini import GeminiModelProvider\n from providers.openai import OpenAIModelProvider\n\n # Earlier tests may override the OpenAI provider's registry by pointing\n # OPENAI_MODELS_CONFIG_PATH at fixtures. Force a reload so model\n # metadata is restored from conf/openai_models.json.\n OpenAIModelProvider.reload_registry()\n assert openai_model in OpenAIModelProvider.MODEL_CAPABILITIES\n\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n # Inject HTTP transport for OpenAI interactions\n inject_transport(monkeypatch, str(consensus_cassette_path))\n\n tool = ConsensusTool()\n\n models_to_consult = [\n {\"model\": openai_model, \"stance\": \"for\"},\n {\"model\": \"gemini-2.5-flash\", \"stance\": \"against\"},\n ]\n\n # Step 1: CLI agent analysis followed by first model consultation\n step1_arguments = {\n \"step\": \"Evaluate SwiftUI vs UIKit adoption and recommend ONE word (SwiftUI or UIKit).\",\n \"step_number\": 1,\n \"total_steps\": len(models_to_consult),\n \"next_step_required\": True,\n \"findings\": \"SwiftUI momentum is strong but UIKit remains battle-tested.\",\n \"models\": models_to_consult,\n }\n\n step1_response = await tool.execute(step1_arguments)\n assert step1_response and step1_response[0].type == \"text\"\n step1_data = json.loads(step1_response[0].text)\n\n assert step1_data[\"status\"] == \"analysis_and_first_model_consulted\"\n assert step1_data[\"model_consulted\"] == openai_model\n assert step1_data[\"model_response\"][\"status\"] == \"success\"\n assert step1_data[\"model_response\"][\"metadata\"][\"provider\"] == \"openai\"\n assert step1_data[\"model_response\"][\"verdict\"]\n\n continuation_offer = step1_data.get(\"continuation_offer\")\n assert continuation_offer is not None\n continuation_id = continuation_offer[\"continuation_id\"]\n\n # Prepare step 2 inputs using the first model's response summary\n summary_for_step2 = step1_data[\"model_response\"][\"verdict\"][:200]\n\n step2_arguments = {\n \"step\": f\"Incorporated {openai_model} perspective: {summary_for_step2}\",\n \"step_number\": 2,\n \"total_steps\": len(models_to_consult),\n \"next_step_required\": False,\n \"findings\": \"Ready to gather opposing stance before synthesis.\",\n \"continuation_id\": continuation_id,\n \"current_model_index\": step1_data.get(\"current_model_index\", 1),\n \"model_responses\": step1_data.get(\"model_responses\", []),\n }\n\n step2_response = await tool.execute(step2_arguments)\n\n assert step2_response and step2_response[0].type == \"text\"\n step2_data = json.loads(step2_response[0].text)\n\n assert step2_data[\"status\"] == \"consensus_workflow_complete\"\n assert step2_data[\"model_consulted\"] == \"gemini-2.5-flash\"\n assert step2_data[\"model_response\"][\"metadata\"][\"provider\"] == \"google\"\n assert step2_data[\"model_response\"][\"verdict\"]\n assert step2_data[\"complete_consensus\"][\"models_consulted\"] == [\n f\"{openai_model}:for\",\n \"gemini-2.5-flash:against\",\n ]\n assert step2_data[\"consensus_complete\"] is True\n\n continuation_offer_final = step2_data.get(\"continuation_offer\")\n assert continuation_offer_final is not None\n assert continuation_offer_final[\"continuation_id\"] == continuation_id\n\n # Ensure Gemini replay session is flushed to disk before verification\n gemini_provider = ModelProviderRegistry.get_provider_for_model(\"gemini-2.5-flash\")\n if gemini_provider is not None:\n try:\n client = gemini_provider.client\n if hasattr(client, \"close\"):\n client.close()\n finally:\n if hasattr(gemini_provider, \"_client\"):\n gemini_provider._client = None\n\n # Ensure cassettes exist for future replays\n assert consensus_cassette_path.exists()\n assert GEMINI_REPLAY_PATH.exists()\n\n # Clean up provider registry state after test\n ModelProviderRegistry.reset_for_testing()\n\n\n@pytest.mark.asyncio\n@pytest.mark.no_mock_provider\nasync def test_consensus_auto_mode_with_openrouter_and_gemini(monkeypatch):\n \"\"\"Ensure continuation flow resolves to real models instead of leaking 'auto'.\"\"\"\n\n gemini_key = os.getenv(\"GEMINI_API_KEY\", \"\").strip() or \"dummy-key-for-replay\"\n openrouter_key = os.getenv(\"OPENROUTER_API_KEY\", \"\").strip() or \"dummy-key-for-replay\"\n\n with monkeypatch.context() as m:\n m.setenv(\"DEFAULT_MODEL\", \"auto\")\n m.setenv(\"GEMINI_API_KEY\", gemini_key)\n m.setenv(\"OPENROUTER_API_KEY\", openrouter_key)\n\n for key in [\n \"OPENAI_API_KEY\",\n \"XAI_API_KEY\",\n \"DIAL_API_KEY\",\n \"CUSTOM_API_KEY\",\n \"CUSTOM_API_URL\",\n ]:\n m.delenv(key, raising=False)\n\n import importlib\n\n import config\n\n m.setattr(config, \"DEFAULT_MODEL\", \"auto\")\n\n import server as server_module\n\n server = importlib.reload(server_module)\n m.setattr(server, \"DEFAULT_MODEL\", \"auto\", raising=False)\n\n ModelProviderRegistry.reset_for_testing()\n from providers.gemini import GeminiModelProvider\n from providers.openrouter import OpenRouterProvider\n\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.OPENROUTER, OpenRouterProvider)\n\n from utils.storage_backend import get_storage_backend\n\n # Clear conversation storage to avoid cross-test leakage\n storage = get_storage_backend()\n storage._store.clear()\n\n models_to_consult = [\n {\"model\": \"claude-3-5-flash-20241022\", \"stance\": \"neutral\"},\n {\"model\": \"gpt-5-mini\", \"stance\": \"neutral\"},\n ]\n\n step1_args = {\n \"step\": \"Evaluate framework options.\",\n \"step_number\": 1,\n \"total_steps\": len(models_to_consult),\n \"next_step_required\": True,\n \"findings\": \"Initial analysis requested.\",\n \"models\": models_to_consult,\n }\n\n step1_output = await server.handle_call_tool(\"consensus\", step1_args)\n assert step1_output and step1_output[0].type == \"text\"\n step1_payload = json.loads(step1_output[0].text)\n\n assert step1_payload[\"status\"] == \"analysis_and_first_model_consulted\"\n assert step1_payload[\"model_consulted\"] == \"claude-3-5-flash-20241022\"\n assert step1_payload[\"model_response\"][\"status\"] == \"error\"\n assert \"claude-3-5-flash-20241022\" in step1_payload[\"model_response\"][\"error\"]\n\n continuation_offer = step1_payload.get(\"continuation_offer\")\n assert continuation_offer is not None\n continuation_id = continuation_offer[\"continuation_id\"]\n\n step2_args = {\n \"step\": \"Continue consultation sequence.\",\n \"step_number\": 2,\n \"total_steps\": len(models_to_consult),\n \"next_step_required\": False,\n \"findings\": \"Ready for next model.\",\n \"continuation_id\": continuation_id,\n \"models\": models_to_consult,\n }\n\n try:\n step2_output = await server.handle_call_tool(\"consensus\", step2_args)\n finally:\n # Reset provider registry regardless of outcome to avoid cross-test bleed\n ModelProviderRegistry.reset_for_testing()\n\n assert step2_output and step2_output[0].type == \"text\"\n step2_payload = json.loads(step2_output[0].text)\n\n serialized = json.dumps(step2_payload)\n assert \"auto\" not in serialized.lower(), \"Auto model leakage should be resolved\"\n assert \"gpt-5-mini\" in serialized or \"claude-3-5-flash-20241022\" in serialized\n\n # Restore server module to reflect original configuration for other tests\n import importlib\n\n import server as server_module\n\n importlib.reload(server_module)\n" }, { "path": "tests/test_consensus_schema.py", "content": "\"\"\"Schema-related tests for ConsensusTool.\"\"\"\n\nfrom types import MethodType\n\nfrom tools.consensus import ConsensusTool\n\n\ndef test_consensus_models_field_includes_available_models(monkeypatch):\n \"\"\"Consensus schema should surface available model guidance like single-model tools.\"\"\"\n\n tool = ConsensusTool()\n\n monkeypatch.setattr(\n tool,\n \"_get_ranked_model_summaries\",\n MethodType(lambda self, limit=5: ([\"gemini-2.5-pro (score 100, 1.0M ctx, thinking)\"], 1, False), tool),\n )\n monkeypatch.setattr(tool, \"_get_restriction_note\", MethodType(lambda self: None, tool))\n\n schema = tool.get_input_schema()\n models_field_description = schema[\"properties\"][\"models\"][\"description\"]\n\n assert \"listmodels\" in models_field_description\n assert \"Top models\" in models_field_description\n" }, { "path": "tests/test_conversation_continuation_integration.py", "content": "\"\"\"Integration test for conversation continuation persistence.\"\"\"\n\nfrom tools.chat import ChatRequest, ChatTool\nfrom utils.conversation_memory import get_thread\nfrom utils.storage_backend import get_storage_backend\n\n\ndef test_first_response_persisted_in_conversation_history(tmp_path):\n \"\"\"Ensure the assistant's initial reply is stored for newly created threads.\"\"\"\n\n # Clear in-memory storage to avoid cross-test contamination\n storage = get_storage_backend()\n storage._store.clear() # type: ignore[attr-defined]\n\n tool = ChatTool()\n request = ChatRequest(\n prompt=\"First question?\",\n model=\"local-llama\",\n working_directory_absolute_path=str(tmp_path),\n )\n response_text = \"Here is the initial answer.\"\n\n # Mimic the first tool invocation (no continuation_id supplied)\n continuation_data = tool._create_continuation_offer(request, model_info={\"model_name\": \"local-llama\"})\n tool._create_continuation_offer_response(\n response_text,\n continuation_data,\n request,\n {\"model_name\": \"local-llama\", \"provider\": \"custom\"},\n )\n\n thread_id = continuation_data[\"continuation_id\"]\n thread = get_thread(thread_id)\n\n assert thread is not None\n assert [turn.role for turn in thread.turns] == [\"user\", \"assistant\"]\n assert thread.turns[-1].content == response_text\n\n # Cleanup storage for subsequent tests\n storage._store.clear() # type: ignore[attr-defined]\n" }, { "path": "tests/test_conversation_field_mapping.py", "content": "\"\"\"\nTest that conversation history is correctly mapped to tool-specific fields\n\"\"\"\n\nfrom datetime import datetime\nfrom unittest.mock import patch\n\nimport pytest\n\nfrom server import reconstruct_thread_context\nfrom utils.conversation_memory import ConversationTurn, ThreadContext\n\n\n@pytest.mark.asyncio\n@pytest.mark.no_mock_provider\nasync def test_conversation_history_field_mapping():\n \"\"\"Test that enhanced prompts are mapped to prompt field for all tools\"\"\"\n\n # Test data for different tools - all use 'prompt' now\n test_cases = [\n {\n \"tool_name\": \"analyze\",\n \"original_value\": \"What does this code do?\",\n },\n {\n \"tool_name\": \"chat\",\n \"original_value\": \"Explain this concept\",\n },\n {\n \"tool_name\": \"debug\",\n \"original_value\": \"Getting undefined error\",\n },\n {\n \"tool_name\": \"codereview\",\n \"original_value\": \"Review this implementation\",\n },\n {\n \"tool_name\": \"thinkdeep\",\n \"original_value\": \"My analysis so far\",\n },\n ]\n\n for test_case in test_cases:\n # Create real conversation context\n mock_context = ThreadContext(\n thread_id=\"test-thread-123\",\n tool_name=test_case[\"tool_name\"],\n created_at=datetime.now().isoformat(),\n last_updated_at=datetime.now().isoformat(),\n turns=[\n ConversationTurn(\n role=\"user\",\n content=\"Previous user message\",\n timestamp=datetime.now().isoformat(),\n files=[\"/test/file1.py\"],\n ),\n ConversationTurn(\n role=\"assistant\",\n content=\"Previous assistant response\",\n timestamp=datetime.now().isoformat(),\n ),\n ],\n initial_context={},\n )\n\n # Mock get_thread to return our test context\n with patch(\"utils.conversation_memory.get_thread\", return_value=mock_context):\n with patch(\"utils.conversation_memory.add_turn\", return_value=True):\n # Create arguments with continuation_id and use a test model\n arguments = {\n \"continuation_id\": \"test-thread-123\",\n \"prompt\": test_case[\"original_value\"],\n \"absolute_file_paths\": [\"/test/file2.py\"],\n \"model\": \"flash\", # Use test model to avoid provider errors\n }\n\n # Call reconstruct_thread_context\n enhanced_args = await reconstruct_thread_context(arguments)\n\n # Verify the enhanced prompt is in the prompt field\n assert \"prompt\" in enhanced_args\n enhanced_value = enhanced_args[\"prompt\"]\n\n # Should contain conversation history\n assert \"=== CONVERSATION HISTORY\" in enhanced_value # Allow for both formats\n assert \"Previous user message\" in enhanced_value\n assert \"Previous assistant response\" in enhanced_value\n\n # Should contain the new user input\n assert \"=== NEW USER INPUT ===\" in enhanced_value\n assert test_case[\"original_value\"] in enhanced_value\n\n # Should have token budget\n assert \"_remaining_tokens\" in enhanced_args\n assert enhanced_args[\"_remaining_tokens\"] > 0\n\n\n@pytest.mark.asyncio\n@pytest.mark.no_mock_provider\nasync def test_unknown_tool_defaults_to_prompt():\n \"\"\"Test that unknown tools default to using 'prompt' field\"\"\"\n\n mock_context = ThreadContext(\n thread_id=\"test-thread-456\",\n tool_name=\"unknown_tool\",\n created_at=datetime.now().isoformat(),\n last_updated_at=datetime.now().isoformat(),\n turns=[\n ConversationTurn(\n role=\"user\",\n content=\"First message\",\n timestamp=datetime.now().isoformat(),\n ),\n ConversationTurn(\n role=\"assistant\",\n content=\"First response\",\n timestamp=datetime.now().isoformat(),\n ),\n ],\n initial_context={},\n )\n\n with patch(\"utils.conversation_memory.get_thread\", return_value=mock_context):\n with patch(\"utils.conversation_memory.add_turn\", return_value=True):\n arguments = {\n \"continuation_id\": \"test-thread-456\",\n \"prompt\": \"User input\",\n \"model\": \"flash\", # Use test model for real integration\n }\n\n enhanced_args = await reconstruct_thread_context(arguments)\n\n # Should default to 'prompt' field\n assert \"prompt\" in enhanced_args\n assert \"=== CONVERSATION HISTORY\" in enhanced_args[\"prompt\"] # Allow for both formats\n assert \"First message\" in enhanced_args[\"prompt\"]\n assert \"First response\" in enhanced_args[\"prompt\"]\n assert \"User input\" in enhanced_args[\"prompt\"]\n\n\n@pytest.mark.asyncio\nasync def test_tool_parameter_standardization():\n \"\"\"Test that workflow tools use standardized investigation pattern\"\"\"\n from tools.analyze import AnalyzeWorkflowRequest\n from tools.codereview import CodeReviewRequest\n from tools.debug import DebugInvestigationRequest\n from tools.precommit import PrecommitRequest\n from tools.thinkdeep import ThinkDeepWorkflowRequest\n\n # Test analyze tool uses workflow pattern\n analyze = AnalyzeWorkflowRequest(\n step=\"What does this do?\",\n step_number=1,\n total_steps=1,\n next_step_required=False,\n findings=\"Initial analysis\",\n relevant_files=[\"/test.py\"],\n )\n assert analyze.step == \"What does this do?\"\n\n # Debug tool now uses self-investigation pattern with different fields\n debug = DebugInvestigationRequest(\n step=\"Investigating error\",\n step_number=1,\n total_steps=3,\n next_step_required=True,\n findings=\"Initial error analysis\",\n )\n assert debug.step == \"Investigating error\"\n assert debug.findings == \"Initial error analysis\"\n\n # Test codereview tool uses workflow fields\n review = CodeReviewRequest(\n step=\"Initial code review investigation\",\n step_number=1,\n total_steps=2,\n next_step_required=True,\n findings=\"Initial review findings\",\n relevant_files=[\"/test.py\"],\n )\n assert review.step == \"Initial code review investigation\"\n assert review.findings == \"Initial review findings\"\n\n # Test thinkdeep tool uses workflow pattern\n think = ThinkDeepWorkflowRequest(\n step=\"My analysis\", step_number=1, total_steps=1, next_step_required=False, findings=\"Initial thinking analysis\"\n )\n assert think.step == \"My analysis\"\n\n # Test precommit tool uses workflow fields\n precommit = PrecommitRequest(\n step=\"Validating changes for commit\",\n step_number=1,\n total_steps=2,\n next_step_required=True,\n findings=\"Initial validation findings\",\n path=\"/repo\", # path only needed for step 1\n )\n assert precommit.step == \"Validating changes for commit\"\n assert precommit.findings == \"Initial validation findings\"\n" }, { "path": "tests/test_conversation_file_features.py", "content": "\"\"\"\nTest suite for conversation memory file management features.\n\nThis module tests the enhanced conversation memory system including:\n- File inclusion in conversation history\n- Token-aware file inclusion planning\n- Smart file size limiting for conversation history\n- Cross-tool file context preservation\n- MCP boundary vs conversation building separation\n\"\"\"\n\nimport os\nfrom unittest.mock import patch\n\nfrom utils.conversation_memory import (\n ConversationTurn,\n ThreadContext,\n _plan_file_inclusion_by_size,\n build_conversation_history,\n get_conversation_file_list,\n)\n\n\nclass TestConversationFileList:\n \"\"\"Test file list extraction from conversation turns\"\"\"\n\n def test_get_conversation_file_list_basic(self):\n \"\"\"Test that files are returned from conversation turns, newest first\"\"\"\n turns = [\n ConversationTurn(\n role=\"user\",\n content=\"First turn (older)\",\n timestamp=\"2023-01-01T00:00:00Z\",\n files=[\"/project/file1.py\", \"/project/file2.py\"],\n ),\n ConversationTurn(\n role=\"assistant\",\n content=\"Second turn (newer)\",\n timestamp=\"2023-01-01T00:01:00Z\",\n files=[\"/project/file3.py\"],\n ),\n ]\n\n context = ThreadContext(\n thread_id=\"test\",\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:01:00Z\",\n tool_name=\"test\",\n turns=turns,\n initial_context={},\n )\n\n files = get_conversation_file_list(context)\n\n # Should contain all unique files, with newest turn files first\n assert len(files) == 3\n assert files[0] == \"/project/file3.py\" # From newest turn (turn 2)\n assert \"/project/file1.py\" in files[1:] # From older turn (turn 1)\n assert \"/project/file2.py\" in files[1:] # From older turn (turn 1)\n\n def test_get_conversation_file_list_deduplication(self):\n \"\"\"Test that duplicate files are removed, prioritizing newer turns\"\"\"\n turns = [\n ConversationTurn(\n role=\"user\",\n content=\"First mention (older)\",\n timestamp=\"2023-01-01T00:00:00Z\",\n files=[\"/project/file1.py\", \"/project/shared.py\"],\n ),\n ConversationTurn(\n role=\"assistant\",\n content=\"Duplicate mention (newer)\",\n timestamp=\"2023-01-01T00:01:00Z\",\n files=[\"/project/shared.py\", \"/project/file2.py\"], # shared.py is duplicate\n ),\n ]\n\n context = ThreadContext(\n thread_id=\"test\",\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:01:00Z\",\n tool_name=\"test\",\n turns=turns,\n initial_context={},\n )\n\n files = get_conversation_file_list(context)\n\n # Should have unique files only, with newer turn files first\n assert len(files) == 3\n # Files from turn 2 (newer) should come first\n assert files[0] == \"/project/shared.py\" # From newer turn (turn 2)\n assert files[1] == \"/project/file2.py\" # From newer turn (turn 2)\n # Files from turn 1 (older) that aren't duplicates\n assert files[2] == \"/project/file1.py\" # From older turn (turn 1)\n\n\nclass TestFileInclusionPlanning:\n \"\"\"Test token-aware file inclusion planning for conversation history\"\"\"\n\n def test_plan_file_inclusion_within_budget(self, project_path):\n \"\"\"Test file inclusion when all files fit within token budget\"\"\"\n # Create small test files\n small_file1 = os.path.join(project_path, \"small1.py\")\n small_file2 = os.path.join(project_path, \"small2.py\")\n\n with open(small_file1, \"w\") as f:\n f.write(\"# Small file 1\\nprint('hello')\\n\") # ~30 chars\n with open(small_file2, \"w\") as f:\n f.write(\"# Small file 2\\nprint('world')\\n\") # ~30 chars\n\n all_files = [small_file1, small_file2]\n max_tokens = 1000 # Generous budget\n\n included, skipped, total_tokens = _plan_file_inclusion_by_size(all_files, max_tokens)\n\n assert included == all_files\n assert skipped == []\n assert total_tokens > 0 # Should have estimated some tokens\n\n def test_plan_file_inclusion_exceeds_budget(self, project_path):\n \"\"\"Test file inclusion when files exceed token budget\"\"\"\n # Create files with different sizes\n small_file = os.path.join(project_path, \"small.py\")\n large_file = os.path.join(project_path, \"large.py\")\n\n with open(small_file, \"w\") as f:\n f.write(\"# Small file\\nprint('hello')\\n\") # ~25 chars\n with open(large_file, \"w\") as f:\n f.write(\"# Large file\\n\" + \"x = 1\\n\" * 1000) # Much larger\n\n all_files = [small_file, large_file]\n max_tokens = 50 # Very tight budget\n\n included, skipped, total_tokens = _plan_file_inclusion_by_size(all_files, max_tokens)\n\n # Should include some files, skip others when budget is tight\n assert len(included) + len(skipped) == 2\n assert total_tokens <= max_tokens\n\n def test_plan_file_inclusion_empty_list(self):\n \"\"\"Test file inclusion planning with empty file list\"\"\"\n included, skipped, total_tokens = _plan_file_inclusion_by_size([], 1000)\n\n assert included == []\n assert skipped == []\n assert total_tokens == 0\n\n def test_plan_file_inclusion_nonexistent_files(self):\n \"\"\"Test file inclusion planning with non-existent files\"\"\"\n nonexistent_files = [\"/does/not/exist1.py\", \"/does/not/exist2.py\"]\n\n included, skipped, total_tokens = _plan_file_inclusion_by_size(nonexistent_files, 1000)\n\n assert included == []\n assert skipped == nonexistent_files\n assert total_tokens == 0\n\n\nclass TestConversationHistoryBuilding:\n \"\"\"Test conversation history building with file content embedding\"\"\"\n\n @patch.dict(os.environ, {\"GEMINI_API_KEY\": \"test-key\", \"OPENAI_API_KEY\": \"\"}, clear=False)\n def test_build_conversation_history_with_file_content(self, project_path):\n \"\"\"Test that conversation history includes embedded file content\"\"\"\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry.clear_cache()\n\n # Create test file with known content\n test_file = os.path.join(project_path, \"test.py\")\n test_content = \"# Test file\\ndef hello():\\n print('Hello, world!')\\n\"\n with open(test_file, \"w\") as f:\n f.write(test_content)\n\n # Create conversation with file reference\n turns = [\n ConversationTurn(\n role=\"user\",\n content=\"Please analyze this file\",\n timestamp=\"2023-01-01T00:00:00Z\",\n files=[test_file],\n )\n ]\n\n context = ThreadContext(\n thread_id=\"test-thread\",\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:00:00Z\",\n tool_name=\"analyze\",\n turns=turns,\n initial_context={},\n )\n\n history, tokens = build_conversation_history(context)\n\n # Verify structure\n assert \"=== CONVERSATION HISTORY (CONTINUATION) ===\" in history\n assert \"=== FILES REFERENCED IN THIS CONVERSATION ===\" in history\n assert \"--- Turn 1 (Agent) ---\" in history\n\n # Verify file content is embedded\n assert \"--- BEGIN FILE:\" in history\n assert test_file in history\n assert test_content in history\n assert \"--- END FILE:\" in history\n\n # Verify turn content\n assert \"Please analyze this file\" in history\n assert f\"Files used in this turn: {test_file}\" in history\n\n @patch.dict(os.environ, {\"GEMINI_API_KEY\": \"test-key\", \"OPENAI_API_KEY\": \"\"}, clear=False)\n def test_build_conversation_history_file_deduplication(self, project_path):\n \"\"\"Test that files are embedded only once even if referenced multiple times\"\"\"\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry.clear_cache()\n\n test_file = os.path.join(project_path, \"shared.py\")\n with open(test_file, \"w\") as f:\n f.write(\"# Shared file\\nshared_var = 42\\n\")\n\n # Multiple turns referencing the same file\n turns = [\n ConversationTurn(\n role=\"user\",\n content=\"First look at this file\",\n timestamp=\"2023-01-01T00:00:00Z\",\n files=[test_file],\n ),\n ConversationTurn(\n role=\"assistant\",\n content=\"Analysis complete\",\n timestamp=\"2023-01-01T00:01:00Z\",\n files=[test_file], # Same file referenced again\n ),\n ]\n\n context = ThreadContext(\n thread_id=\"test-thread\",\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:01:00Z\",\n tool_name=\"analyze\",\n turns=turns,\n initial_context={},\n )\n\n history, tokens = build_conversation_history(context)\n\n # File should appear in embedded section only once\n file_begin_count = history.count(\"--- BEGIN FILE:\")\n file_end_count = history.count(\"--- END FILE:\")\n assert file_begin_count == 1, \"File should be embedded exactly once\"\n assert file_end_count == 1, \"File should be embedded exactly once\"\n\n # But should show in both turn references\n turn_file_refs = history.count(f\"Files used in this turn: {test_file}\")\n assert turn_file_refs == 2, \"Both turns should show file usage\"\n\n def test_build_conversation_history_empty_turns(self):\n \"\"\"Test conversation history building with no turns\"\"\"\n context = ThreadContext(\n thread_id=\"empty-thread\",\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:00:00Z\",\n tool_name=\"test\",\n turns=[],\n initial_context={},\n )\n\n history, tokens = build_conversation_history(context)\n\n assert history == \"\"\n assert tokens == 0\n\n\nclass TestCrossToolFileContext:\n \"\"\"Test cross-tool file context preservation in conversations\"\"\"\n\n @patch.dict(os.environ, {\"GEMINI_API_KEY\": \"test-key\", \"OPENAI_API_KEY\": \"\"}, clear=False)\n def test_cross_tool_file_context_preservation(self, project_path):\n \"\"\"Test that file context is preserved across different tools\"\"\"\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry.clear_cache()\n\n src_file = os.path.join(project_path, \"src.py\")\n test_file = os.path.join(project_path, \"test.py\")\n\n with open(src_file, \"w\") as f:\n f.write(\"def main():\\n return 'hello'\\n\")\n with open(test_file, \"w\") as f:\n f.write(\"import src\\nassert src.main() == 'hello'\\n\")\n\n # Simulate cross-tool conversation with chronological timestamps\n turns = [\n ConversationTurn(\n role=\"assistant\",\n content=\"I've analyzed the source code structure\",\n timestamp=\"2023-01-01T00:00:00Z\", # First turn\n files=[src_file],\n tool_name=\"analyze\",\n model_name=\"gemini-2.5-flash\",\n model_provider=\"google\",\n ),\n ConversationTurn(\n role=\"user\",\n content=\"Now generate tests for it\",\n timestamp=\"2023-01-01T00:01:00Z\", # Second turn (1 minute later)\n files=[test_file],\n ),\n ConversationTurn(\n role=\"assistant\",\n content=\"I've generated comprehensive tests\",\n timestamp=\"2023-01-01T00:02:00Z\", # Third turn (2 minutes later)\n files=[src_file, test_file], # References both files\n tool_name=\"testgen\",\n model_name=\"gpt-5\",\n model_provider=\"openai\",\n ),\n ]\n\n context = ThreadContext(\n thread_id=\"cross-tool-thread\",\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:02:00Z\",\n tool_name=\"testgen\",\n turns=turns,\n initial_context={},\n )\n\n history, tokens = build_conversation_history(context)\n\n # Verify cross-tool context\n assert \"--- Turn 1 (gemini-2.5-flash using analyze via google) ---\" in history\n assert \"--- Turn 2 (Agent) ---\" in history\n assert \"--- Turn 3 (gpt-5 using testgen via openai) ---\" in history\n\n # Verify file context preservation\n assert \"Files used in this turn: \" + src_file in history\n assert \"Files used in this turn: \" + test_file in history\n assert f\"Files used in this turn: {src_file}, {test_file}\" in history\n\n # Verify both files are embedded\n files_section_start = history.find(\"=== FILES REFERENCED IN THIS CONVERSATION ===\")\n first_file_pos = history.find(src_file, files_section_start)\n second_file_pos = history.find(test_file, files_section_start)\n\n assert first_file_pos > 0 and second_file_pos > 0\n\n\nclass TestLargeConversations:\n \"\"\"Test behavior with large conversations, many files, and many turns\"\"\"\n\n @patch.dict(os.environ, {\"GEMINI_API_KEY\": \"test-key\", \"OPENAI_API_KEY\": \"\"}, clear=False)\n def test_large_conversation_with_many_files(self, project_path):\n \"\"\"Test conversation with many files across multiple turns\"\"\"\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry.clear_cache()\n\n # Create 20 test files\n test_files = []\n for i in range(20):\n test_file = os.path.join(project_path, f\"file{i:02d}.py\")\n with open(test_file, \"w\") as f:\n f.write(f\"# File {i}\\nclass Module{i}:\\n def method(self):\\n return {i}\\n\")\n test_files.append(test_file)\n\n # Create 15 conversation turns with files spread across them\n turns = []\n for turn_num in range(15):\n # Distribute files across turns (some turns have multiple files)\n if turn_num < 10:\n turn_files = test_files[turn_num * 2 : (turn_num + 1) * 2] # 2 files per turn\n else:\n turn_files = [] # Some turns without files\n\n turns.append(\n ConversationTurn(\n role=\"user\" if turn_num % 2 == 0 else \"assistant\",\n content=f\"Turn {turn_num} content - working on modules\",\n timestamp=f\"2023-01-01T{turn_num:02d}:00:00Z\",\n files=turn_files,\n tool_name=\"analyze\" if turn_num % 3 == 0 else None,\n )\n )\n\n context = ThreadContext(\n thread_id=\"large-conversation\",\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T14:00:00Z\",\n tool_name=\"analyze\",\n turns=turns,\n initial_context={},\n )\n\n history, tokens = build_conversation_history(context)\n\n # Verify structure\n assert \"=== CONVERSATION HISTORY (CONTINUATION) ===\" in history\n assert \"=== FILES REFERENCED IN THIS CONVERSATION ===\" in history\n\n # Should handle large conversation gracefully\n assert len(history) > 1000 # Should have substantial content\n assert tokens > 0\n\n # Files from newer turns should be prioritized\n file_list = get_conversation_file_list(context)\n assert len(file_list) == 20 # All unique files\n\n # Files from turn 9 (newest with files) should come first\n newest_files = test_files[18:20] # Files from turn 9\n assert file_list[0] in newest_files\n assert file_list[1] in newest_files\n\n\nclass TestSmallAndNewConversations:\n \"\"\"Test behavior with small/new conversations and edge cases\"\"\"\n\n def test_empty_conversation(self):\n \"\"\"Test completely empty conversation\"\"\"\n context = ThreadContext(\n thread_id=\"empty\",\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:00:00Z\",\n tool_name=\"test\",\n turns=[],\n initial_context={},\n )\n\n history, tokens = build_conversation_history(context)\n\n assert history == \"\"\n assert tokens == 0\n\n @patch.dict(os.environ, {\"GEMINI_API_KEY\": \"test-key\", \"OPENAI_API_KEY\": \"\"}, clear=False)\n def test_single_turn_conversation(self, project_path):\n \"\"\"Test conversation with just one turn\"\"\"\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry.clear_cache()\n\n test_file = os.path.join(project_path, \"single.py\")\n with open(test_file, \"w\") as f:\n f.write(\"# Single file\\ndef hello():\\n return 'world'\\n\")\n\n turns = [\n ConversationTurn(\n role=\"user\",\n content=\"Quick question about this file\",\n timestamp=\"2023-01-01T00:00:00Z\",\n files=[test_file],\n )\n ]\n\n context = ThreadContext(\n thread_id=\"single-turn\",\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:00:00Z\",\n tool_name=\"chat\",\n turns=turns,\n initial_context={},\n )\n\n history, tokens = build_conversation_history(context)\n\n # Should work correctly for single turn\n assert \"=== CONVERSATION HISTORY (CONTINUATION) ===\" in history\n assert \"=== FILES REFERENCED IN THIS CONVERSATION ===\" in history\n assert \"--- Turn 1 (Agent) ---\" in history\n assert \"Quick question about this file\" in history\n assert test_file in history\n assert tokens > 0\n\n\nclass TestFailureScenarios:\n \"\"\"Test failure scenarios and error handling\"\"\"\n\n def test_file_list_with_missing_files(self):\n \"\"\"Test conversation with references to missing files\"\"\"\n turns = [\n ConversationTurn(\n role=\"user\",\n content=\"Analyze these files\",\n timestamp=\"2023-01-01T00:00:00Z\",\n files=[\"/does/not/exist.py\", \"/also/missing.py\"],\n )\n ]\n\n context = ThreadContext(\n thread_id=\"missing-files\",\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:00:00Z\",\n tool_name=\"analyze\",\n turns=turns,\n initial_context={},\n )\n\n # Should handle missing files gracefully\n files = get_conversation_file_list(context)\n assert len(files) == 2 # Still returns file paths\n assert \"/does/not/exist.py\" in files\n assert \"/also/missing.py\" in files\n\n @patch.dict(os.environ, {\"GEMINI_API_KEY\": \"test-key\", \"OPENAI_API_KEY\": \"\"}, clear=False)\n def test_conversation_with_unreadable_files(self, project_path):\n \"\"\"Test conversation history building with unreadable files\"\"\"\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry.clear_cache()\n\n # Create a file that will be treated as missing\n missing_file = os.path.join(project_path, \"nonexistent.py\")\n\n # Create a readable file for comparison\n test_file = os.path.join(project_path, \"readable.py\")\n with open(test_file, \"w\") as f:\n f.write(\"# Test file\\ndef test(): pass\\n\")\n\n turns = [\n ConversationTurn(\n role=\"user\",\n content=\"Analyze these files\",\n timestamp=\"2023-01-01T00:00:00Z\",\n files=[test_file, missing_file],\n )\n ]\n\n context = ThreadContext(\n thread_id=\"mixed-files\",\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:00:00Z\",\n tool_name=\"analyze\",\n turns=turns,\n initial_context={},\n )\n\n history, tokens = build_conversation_history(context)\n\n # Should handle gracefully - build history with accessible files\n assert \"=== CONVERSATION HISTORY (CONTINUATION) ===\" in history\n assert \"--- Turn 1 (Agent) ---\" in history\n assert \"Analyze these files\" in history\n assert tokens > 0\n" }, { "path": "tests/test_conversation_memory.py", "content": "\"\"\"\nTest suite for conversation memory system\n\nTests the Redis-based conversation persistence needed for AI-to-AI multi-turn\ndiscussions in stateless MCP environments.\n\"\"\"\n\nimport os\nfrom unittest.mock import Mock, patch\n\nimport pytest\n\nfrom server import get_follow_up_instructions\nfrom utils.conversation_memory import (\n CONVERSATION_TIMEOUT_SECONDS,\n MAX_CONVERSATION_TURNS,\n ConversationTurn,\n ThreadContext,\n add_turn,\n build_conversation_history,\n create_thread,\n get_thread,\n)\n\n\nclass TestConversationMemory:\n \"\"\"Test the conversation memory system for stateless MCP requests\"\"\"\n\n @patch(\"utils.conversation_memory.get_storage\")\n def test_create_thread(self, mock_storage):\n \"\"\"Test creating a new thread\"\"\"\n mock_client = Mock()\n mock_storage.return_value = mock_client\n\n thread_id = create_thread(\"chat\", {\"prompt\": \"Hello\", \"absolute_file_paths\": [\"/test.py\"]})\n\n assert thread_id is not None\n assert len(thread_id) == 36 # UUID4 length\n\n # Verify Redis was called\n mock_client.setex.assert_called_once()\n call_args = mock_client.setex.call_args\n assert call_args[0][0] == f\"thread:{thread_id}\" # key\n assert call_args[0][1] == CONVERSATION_TIMEOUT_SECONDS # TTL from configuration\n\n @patch(\"utils.conversation_memory.get_storage\")\n def test_get_thread_valid(self, mock_storage):\n \"\"\"Test retrieving an existing thread\"\"\"\n mock_client = Mock()\n mock_storage.return_value = mock_client\n\n test_uuid = \"12345678-1234-1234-1234-123456789012\"\n\n # Create valid ThreadContext and serialize it\n context_obj = ThreadContext(\n thread_id=test_uuid,\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:01:00Z\",\n tool_name=\"chat\",\n turns=[],\n initial_context={\"prompt\": \"test\"},\n )\n mock_client.get.return_value = context_obj.model_dump_json()\n\n context = get_thread(test_uuid)\n\n assert context is not None\n assert context.thread_id == test_uuid\n assert context.tool_name == \"chat\"\n mock_client.get.assert_called_once_with(f\"thread:{test_uuid}\")\n\n @patch(\"utils.conversation_memory.get_storage\")\n def test_get_thread_invalid_uuid(self, mock_storage):\n \"\"\"Test handling invalid UUID\"\"\"\n context = get_thread(\"invalid-uuid\")\n assert context is None\n\n @patch(\"utils.conversation_memory.get_storage\")\n def test_get_thread_not_found(self, mock_storage):\n \"\"\"Test handling thread not found\"\"\"\n mock_client = Mock()\n mock_storage.return_value = mock_client\n mock_client.get.return_value = None\n\n context = get_thread(\"12345678-1234-1234-1234-123456789012\")\n assert context is None\n\n @patch(\"utils.conversation_memory.get_storage\")\n def test_add_turn_success(self, mock_storage):\n \"\"\"Test adding a turn to existing thread\"\"\"\n mock_client = Mock()\n mock_storage.return_value = mock_client\n\n test_uuid = \"12345678-1234-1234-1234-123456789012\"\n\n # Create valid ThreadContext\n context_obj = ThreadContext(\n thread_id=test_uuid,\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:01:00Z\",\n tool_name=\"chat\",\n turns=[],\n initial_context={\"prompt\": \"test\"},\n )\n mock_client.get.return_value = context_obj.model_dump_json()\n\n success = add_turn(test_uuid, \"user\", \"Hello there\")\n\n assert success is True\n # Verify Redis get and setex were called\n mock_client.get.assert_called_once()\n mock_client.setex.assert_called_once()\n\n @patch(\"utils.conversation_memory.get_storage\")\n def test_add_turn_max_limit(self, mock_storage):\n \"\"\"Test turn limit enforcement\"\"\"\n mock_client = Mock()\n mock_storage.return_value = mock_client\n\n test_uuid = \"12345678-1234-1234-1234-123456789012\"\n\n # Create thread with MAX_CONVERSATION_TURNS turns (at limit)\n turns = [\n ConversationTurn(role=\"user\", content=f\"Turn {i}\", timestamp=\"2023-01-01T00:00:00Z\")\n for i in range(MAX_CONVERSATION_TURNS)\n ]\n context_obj = ThreadContext(\n thread_id=test_uuid,\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:01:00Z\",\n tool_name=\"chat\",\n turns=turns,\n initial_context={\"prompt\": \"test\"},\n )\n mock_client.get.return_value = context_obj.model_dump_json()\n\n success = add_turn(test_uuid, \"user\", \"This should fail\")\n\n assert success is False\n\n @patch.dict(os.environ, {\"GEMINI_API_KEY\": \"test-key\", \"OPENAI_API_KEY\": \"\"}, clear=False)\n def test_build_conversation_history(self, project_path):\n \"\"\"Test building conversation history format with files and speaker identification\"\"\"\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry.clear_cache()\n\n # Create real test files to test actual file embedding functionality\n main_file = project_path / \"main.py\"\n readme_file = project_path / \"docs\" / \"readme.md\"\n examples_dir = project_path / \"examples\"\n examples_file = examples_dir / \"example.py\"\n\n # Create directories and files\n readme_file.parent.mkdir(parents=True, exist_ok=True)\n examples_dir.mkdir(parents=True, exist_ok=True)\n\n main_file.write_text(\"def main():\\n print('Hello world')\\n\")\n readme_file.write_text(\"# Project Documentation\\nThis is a test project.\\n\")\n examples_file.write_text(\"# Example code\\nprint('Example')\\n\")\n\n test_uuid = \"12345678-1234-1234-1234-123456789012\"\n\n turns = [\n ConversationTurn(\n role=\"user\",\n content=\"What is Python?\",\n timestamp=\"2023-01-01T00:00:00Z\",\n files=[str(main_file), str(readme_file)],\n ),\n ConversationTurn(\n role=\"assistant\",\n content=\"Python is a programming language\",\n timestamp=\"2023-01-01T00:01:00Z\",\n files=[str(examples_dir)], # Directory will be expanded to files\n tool_name=\"chat\",\n model_name=\"gpt-5\",\n model_provider=\"openai\",\n ),\n ]\n\n context = ThreadContext(\n thread_id=test_uuid,\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:01:00Z\",\n tool_name=\"chat\",\n turns=turns,\n initial_context={},\n )\n\n history, tokens = build_conversation_history(context, model_context=None)\n\n # Test basic structure\n assert \"CONVERSATION HISTORY\" in history\n assert f\"Thread: {test_uuid}\" in history\n assert \"Tool: chat\" in history\n assert f\"Turn 2/{MAX_CONVERSATION_TURNS}\" in history\n\n # Test speaker identification\n assert \"--- Turn 1 (Agent) ---\" in history\n assert \"--- Turn 2 (gpt-5 using chat via openai) ---\" in history\n\n # Test content\n assert \"What is Python?\" in history\n assert \"Python is a programming language\" in history\n\n # Test file tracking\n # Check that the new file embedding section is included\n assert \"=== FILES REFERENCED IN THIS CONVERSATION ===\" in history\n assert \"The following files have been shared and analyzed during our conversation.\" in history\n\n # Check that file context from previous turns is included (now shows files used per turn)\n assert f\"Files used in this turn: {main_file}, {readme_file}\" in history\n assert f\"Files used in this turn: {examples_dir}\" in history\n\n # Verify actual file content is embedded\n assert \"def main():\" in history\n assert \"Hello world\" in history\n assert \"Project Documentation\" in history\n\n def test_build_conversation_history_empty(self):\n \"\"\"Test building history with no turns\"\"\"\n test_uuid = \"12345678-1234-1234-1234-123456789012\"\n\n context = ThreadContext(\n thread_id=test_uuid,\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:00:00Z\",\n tool_name=\"chat\",\n turns=[],\n initial_context={},\n )\n\n history, tokens = build_conversation_history(context, model_context=None)\n assert history == \"\"\n assert tokens == 0\n\n\nclass TestConversationFlow:\n \"\"\"Test complete conversation flows simulating stateless MCP requests\"\"\"\n\n @patch(\"utils.conversation_memory.get_storage\")\n def test_complete_conversation_cycle(self, mock_storage):\n \"\"\"Test a complete 5-turn conversation until limit reached\"\"\"\n mock_client = Mock()\n mock_storage.return_value = mock_client\n\n # Simulate independent MCP request cycles\n\n # REQUEST 1: Initial request creates thread\n thread_id = create_thread(\"chat\", {\"prompt\": \"Analyze this code\"})\n initial_context = ThreadContext(\n thread_id=thread_id,\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:00:00Z\",\n tool_name=\"chat\",\n turns=[],\n initial_context={\"prompt\": \"Analyze this code\"},\n )\n mock_client.get.return_value = initial_context.model_dump_json()\n\n # Add assistant response\n success = add_turn(\n thread_id,\n \"assistant\",\n \"Code analysis complete\",\n )\n assert success is True\n\n # REQUEST 2: User responds to follow-up (independent request cycle)\n # Simulate retrieving updated context from Redis\n context_after_1 = ThreadContext(\n thread_id=thread_id,\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:01:00Z\",\n tool_name=\"chat\",\n turns=[\n ConversationTurn(\n role=\"assistant\",\n content=\"Code analysis complete\",\n timestamp=\"2023-01-01T00:00:30Z\",\n )\n ],\n initial_context={\"prompt\": \"Analyze this code\"},\n )\n mock_client.get.return_value = context_after_1.model_dump_json()\n\n success = add_turn(thread_id, \"user\", \"Yes, check error handling\")\n assert success is True\n\n success = add_turn(thread_id, \"assistant\", \"Error handling reviewed\")\n assert success is True\n\n # REQUEST 3-5: Continue conversation (simulating independent cycles)\n # After turn 3\n context_after_3 = ThreadContext(\n thread_id=thread_id,\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:03:00Z\",\n tool_name=\"chat\",\n turns=[\n ConversationTurn(\n role=\"assistant\",\n content=\"Code analysis complete\",\n timestamp=\"2023-01-01T00:00:30Z\",\n ),\n ConversationTurn(role=\"user\", content=\"Yes, check error handling\", timestamp=\"2023-01-01T00:01:30Z\"),\n ConversationTurn(\n role=\"assistant\",\n content=\"Error handling reviewed\",\n timestamp=\"2023-01-01T00:02:30Z\",\n ),\n ],\n initial_context={\"prompt\": \"Analyze this code\"},\n )\n mock_client.get.return_value = context_after_3.model_dump_json()\n\n success = add_turn(thread_id, \"user\", \"Yes, check tests\")\n assert success is True\n\n success = add_turn(thread_id, \"assistant\", \"Test coverage analyzed\")\n assert success is True\n\n # REQUEST 6: Try to exceed MAX_CONVERSATION_TURNS limit - should fail\n turns_at_limit = [\n ConversationTurn(\n role=\"assistant\" if i % 2 == 0 else \"user\", content=f\"Turn {i + 1}\", timestamp=\"2023-01-01T00:00:30Z\"\n )\n for i in range(MAX_CONVERSATION_TURNS)\n ]\n\n context_at_limit = ThreadContext(\n thread_id=thread_id,\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:05:00Z\",\n tool_name=\"chat\",\n turns=turns_at_limit,\n initial_context={\"prompt\": \"Analyze this code\"},\n )\n mock_client.get.return_value = context_at_limit.model_dump_json()\n\n # This should fail - conversation has reached limit\n success = add_turn(thread_id, \"user\", \"This should be rejected\")\n assert success is False # CONVERSATION STOPS HERE\n\n @patch(\"utils.conversation_memory.get_storage\")\n def test_invalid_continuation_id_error(self, mock_storage):\n \"\"\"Test that invalid continuation IDs raise proper error for restart\"\"\"\n from server import reconstruct_thread_context\n\n mock_client = Mock()\n mock_storage.return_value = mock_client\n mock_client.get.return_value = None # Thread not found\n\n arguments = {\"continuation_id\": \"invalid-uuid-12345\", \"prompt\": \"Continue conversation\"}\n\n # Should raise ValueError asking to restart\n with pytest.raises(ValueError) as exc_info:\n import asyncio\n\n asyncio.run(reconstruct_thread_context(arguments))\n\n error_msg = str(exc_info.value)\n assert \"Conversation thread 'invalid-uuid-12345' was not found or has expired\" in error_msg\n assert (\n \"Please restart the conversation by providing your full question/prompt without the continuation_id\"\n in error_msg\n )\n\n @patch.dict(os.environ, {\"GEMINI_API_KEY\": \"test-key\", \"OPENAI_API_KEY\": \"\"}, clear=False)\n def test_dynamic_max_turns_configuration(self):\n \"\"\"Test that all functions respect MAX_CONVERSATION_TURNS configuration\"\"\"\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry.clear_cache()\n\n # This test ensures if we change MAX_CONVERSATION_TURNS, everything updates\n\n # Test with different max values by patching the constant\n test_values = [3, 7, 10]\n\n for test_max in test_values:\n # Create turns up to the test limit\n turns = [\n ConversationTurn(role=\"user\", content=f\"Turn {i}\", timestamp=\"2023-01-01T00:00:00Z\")\n for i in range(test_max)\n ]\n\n # Test history building respects the limit\n test_uuid = \"12345678-1234-1234-1234-123456789012\"\n context = ThreadContext(\n thread_id=test_uuid,\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:00:00Z\",\n tool_name=\"chat\",\n turns=turns,\n initial_context={},\n )\n\n history, tokens = build_conversation_history(context, model_context=None)\n expected_turn_text = f\"Turn {test_max}/{MAX_CONVERSATION_TURNS}\"\n assert expected_turn_text in history\n\n def test_follow_up_instructions_dynamic_behavior(self):\n \"\"\"Test that follow-up instructions change correctly based on turn count and max setting\"\"\"\n # Test with default MAX_CONVERSATION_TURNS\n max_turns = MAX_CONVERSATION_TURNS\n\n # Test early conversation (should allow follow-ups)\n early_instructions = get_follow_up_instructions(0, max_turns)\n assert \"CONVERSATION CONTINUATION\" in early_instructions\n assert f\"({max_turns - 1} exchanges remaining)\" in early_instructions\n assert \"Feel free to ask clarifying questions\" in early_instructions\n\n # Test mid conversation\n mid_instructions = get_follow_up_instructions(2, max_turns)\n assert \"CONVERSATION CONTINUATION\" in mid_instructions\n assert f\"({max_turns - 3} exchanges remaining)\" in mid_instructions\n assert \"Feel free to ask clarifying questions\" in mid_instructions\n\n # Test approaching limit (should stop follow-ups)\n limit_instructions = get_follow_up_instructions(max_turns - 1, max_turns)\n assert \"Do NOT include any follow-up questions\" in limit_instructions\n assert \"final exchange\" in limit_instructions\n\n # Test at limit\n at_limit_instructions = get_follow_up_instructions(max_turns, max_turns)\n assert \"Do NOT include any follow-up questions\" in at_limit_instructions\n\n # Test with custom max_turns to ensure dynamic behavior\n custom_max = 3\n custom_early = get_follow_up_instructions(0, custom_max)\n assert f\"({custom_max - 1} exchanges remaining)\" in custom_early\n\n custom_limit = get_follow_up_instructions(custom_max - 1, custom_max)\n assert \"Do NOT include any follow-up questions\" in custom_limit\n\n def test_follow_up_instructions_defaults_to_config(self):\n \"\"\"Test that follow-up instructions use MAX_CONVERSATION_TURNS when max_turns not provided\"\"\"\n instructions = get_follow_up_instructions(0) # No max_turns parameter\n expected_remaining = MAX_CONVERSATION_TURNS - 1\n assert f\"({expected_remaining} exchanges remaining)\" in instructions\n\n @patch(\"utils.conversation_memory.get_storage\")\n def test_complete_conversation_with_dynamic_turns(self, mock_storage):\n \"\"\"Test complete conversation respecting MAX_CONVERSATION_TURNS dynamically\"\"\"\n mock_client = Mock()\n mock_storage.return_value = mock_client\n\n thread_id = create_thread(\"chat\", {\"prompt\": \"Start conversation\"})\n\n # Simulate conversation up to MAX_CONVERSATION_TURNS - 1\n for turn_num in range(MAX_CONVERSATION_TURNS - 1):\n # Mock context with current turns\n turns = [\n ConversationTurn(\n role=\"user\" if i % 2 == 0 else \"assistant\",\n content=f\"Turn {i + 1}\",\n timestamp=\"2023-01-01T00:00:00Z\",\n )\n for i in range(turn_num)\n ]\n\n context = ThreadContext(\n thread_id=thread_id,\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:00:00Z\",\n tool_name=\"chat\",\n turns=turns,\n initial_context={\"prompt\": \"Start conversation\"},\n )\n mock_client.get.return_value = context.model_dump_json()\n\n # Should succeed\n success = add_turn(thread_id, \"user\", f\"User turn {turn_num + 1}\")\n assert success is True, f\"Turn {turn_num + 1} should succeed\"\n\n # Now we should be at the limit - create final context\n final_turns = [\n ConversationTurn(\n role=\"user\" if i % 2 == 0 else \"assistant\", content=f\"Turn {i + 1}\", timestamp=\"2023-01-01T00:00:00Z\"\n )\n for i in range(MAX_CONVERSATION_TURNS)\n ]\n\n final_context = ThreadContext(\n thread_id=thread_id,\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:00:00Z\",\n tool_name=\"chat\",\n turns=final_turns,\n initial_context={\"prompt\": \"Start conversation\"},\n )\n mock_client.get.return_value = final_context.model_dump_json()\n\n # This should fail - at the limit\n success = add_turn(thread_id, \"user\", \"This should fail\")\n assert success is False, f\"Turn {MAX_CONVERSATION_TURNS + 1} should fail\"\n\n @patch(\"utils.conversation_memory.get_storage\")\n @patch.dict(os.environ, {\"GEMINI_API_KEY\": \"test-key\", \"OPENAI_API_KEY\": \"\"}, clear=False)\n def test_conversation_with_files_and_context_preservation(self, mock_storage):\n \"\"\"Test complete conversation flow with file tracking and context preservation\"\"\"\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry.clear_cache()\n\n mock_client = Mock()\n mock_storage.return_value = mock_client\n\n # Start conversation with files using a simple tool\n thread_id = create_thread(\"chat\", {\"prompt\": \"Analyze this codebase\", \"absolute_file_paths\": [\"/project/src/\"]})\n\n # Turn 1: Claude provides context with multiple files\n initial_context = ThreadContext(\n thread_id=thread_id,\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:00:00Z\",\n tool_name=\"chat\",\n turns=[],\n initial_context={\n \"prompt\": \"Analyze this codebase\",\n \"absolute_file_paths\": [\"/project/src/\"],\n },\n )\n mock_client.get.return_value = initial_context.model_dump_json()\n\n # Add Gemini's response\n success = add_turn(\n thread_id,\n \"assistant\",\n \"I've analyzed your codebase structure.\",\n files=[\"/project/src/main.py\", \"/project/src/utils.py\"],\n tool_name=\"analyze\",\n model_name=\"gemini-2.5-flash\",\n model_provider=\"google\",\n )\n assert success is True\n\n # Turn 2: Claude responds with different files\n context_turn_1 = ThreadContext(\n thread_id=thread_id,\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:01:00Z\",\n tool_name=\"analyze\",\n turns=[\n ConversationTurn(\n role=\"assistant\",\n content=\"I've analyzed your codebase structure.\",\n timestamp=\"2023-01-01T00:00:30Z\",\n files=[\"/project/src/main.py\", \"/project/src/utils.py\"],\n tool_name=\"analyze\",\n model_name=\"gemini-2.5-flash\",\n model_provider=\"google\",\n )\n ],\n initial_context={\"prompt\": \"Analyze this codebase\", \"relevant_files\": [\"/project/src/\"]},\n )\n mock_client.get.return_value = context_turn_1.model_dump_json()\n\n # User responds with test files\n success = add_turn(\n thread_id, \"user\", \"Yes, check the test coverage\", files=[\"/project/tests/\", \"/project/test_main.py\"]\n )\n assert success is True\n\n # Turn 3: Gemini analyzes tests\n context_turn_2 = ThreadContext(\n thread_id=thread_id,\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:02:00Z\",\n tool_name=\"analyze\",\n turns=[\n ConversationTurn(\n role=\"assistant\",\n content=\"I've analyzed your codebase structure.\",\n timestamp=\"2023-01-01T00:00:30Z\",\n files=[\"/project/src/main.py\", \"/project/src/utils.py\"],\n tool_name=\"analyze\",\n ),\n ConversationTurn(\n role=\"user\",\n content=\"Yes, check the test coverage\",\n timestamp=\"2023-01-01T00:01:30Z\",\n files=[\"/project/tests/\", \"/project/test_main.py\"],\n ),\n ],\n initial_context={\"prompt\": \"Analyze this codebase\", \"relevant_files\": [\"/project/src/\"]},\n )\n mock_client.get.return_value = context_turn_2.model_dump_json()\n\n success = add_turn(\n thread_id,\n \"assistant\",\n \"Test coverage analysis complete. Coverage is 85%.\",\n files=[\"/project/tests/test_utils.py\", \"/project/coverage.html\"],\n tool_name=\"analyze\",\n model_name=\"gemini-2.5-flash\",\n model_provider=\"google\",\n )\n assert success is True\n\n # Build conversation history and verify chronological file preservation\n final_context = ThreadContext(\n thread_id=thread_id,\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:03:00Z\",\n tool_name=\"analyze\",\n turns=[\n ConversationTurn(\n role=\"assistant\",\n content=\"I've analyzed your codebase structure.\",\n timestamp=\"2023-01-01T00:00:30Z\",\n files=[\"/project/src/main.py\", \"/project/src/utils.py\"],\n tool_name=\"analyze\",\n model_name=\"gemini-2.5-flash\",\n model_provider=\"google\",\n ),\n ConversationTurn(\n role=\"user\",\n content=\"Yes, check the test coverage\",\n timestamp=\"2023-01-01T00:01:30Z\",\n files=[\"/project/tests/\", \"/project/test_main.py\"],\n ),\n ConversationTurn(\n role=\"assistant\",\n content=\"Test coverage analysis complete. Coverage is 85%.\",\n timestamp=\"2023-01-01T00:02:30Z\",\n files=[\"/project/tests/test_utils.py\", \"/project/coverage.html\"],\n tool_name=\"analyze\",\n model_name=\"gemini-2.5-flash\",\n model_provider=\"google\",\n ),\n ],\n initial_context={\"prompt\": \"Analyze this codebase\", \"relevant_files\": [\"/project/src/\"]},\n )\n\n history, tokens = build_conversation_history(final_context)\n\n # Verify chronological order and speaker identification\n assert \"--- Turn 1 (gemini-2.5-flash using analyze via google) ---\" in history\n assert \"--- Turn 2 (Agent) ---\" in history\n assert \"--- Turn 3 (gemini-2.5-flash using analyze via google) ---\" in history\n\n # Verify all files are preserved in chronological order\n turn_1_files = \"Files used in this turn: /project/src/main.py, /project/src/utils.py\"\n turn_2_files = \"Files used in this turn: /project/tests/, /project/test_main.py\"\n turn_3_files = \"Files used in this turn: /project/tests/test_utils.py, /project/coverage.html\"\n\n assert turn_1_files in history\n assert turn_2_files in history\n assert turn_3_files in history\n\n # Verify content\n assert \"I've analyzed your codebase structure.\" in history\n assert \"Yes, check the test coverage\" in history\n assert \"Test coverage analysis complete. Coverage is 85%.\" in history\n\n # Verify chronological ordering (turn 1 appears before turn 2, etc.)\n turn_1_pos = history.find(\"--- Turn 1 (gemini-2.5-flash using analyze via google) ---\")\n turn_2_pos = history.find(\"--- Turn 2 (Agent) ---\")\n turn_3_pos = history.find(\"--- Turn 3 (gemini-2.5-flash using analyze via google) ---\")\n\n assert turn_1_pos < turn_2_pos < turn_3_pos\n\n @patch(\"utils.conversation_memory.get_storage\")\n def test_stateless_request_isolation(self, mock_storage):\n \"\"\"Test that each request cycle is independent but shares context via Redis\"\"\"\n mock_client = Mock()\n mock_storage.return_value = mock_client\n\n # Simulate two different \"processes\" accessing same thread\n thread_id = \"12345678-1234-1234-1234-123456789012\"\n\n # Process 1: Creates thread\n initial_context = ThreadContext(\n thread_id=thread_id,\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:00:00Z\",\n tool_name=\"thinkdeep\",\n turns=[],\n initial_context={\"prompt\": \"Think about architecture\"},\n )\n mock_client.get.return_value = initial_context.model_dump_json()\n\n success = add_turn(thread_id, \"assistant\", \"Architecture analysis\")\n assert success is True\n\n # Process 2: Different \"request cycle\" accesses same thread\n context_from_redis = ThreadContext(\n thread_id=thread_id,\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:01:00Z\",\n tool_name=\"thinkdeep\",\n turns=[\n ConversationTurn(\n role=\"assistant\",\n content=\"Architecture analysis\",\n timestamp=\"2023-01-01T00:00:30Z\",\n )\n ],\n initial_context={\"prompt\": \"Think about architecture\"},\n )\n mock_client.get.return_value = context_from_redis.model_dump_json()\n\n # Verify context continuity across \"processes\"\n retrieved_context = get_thread(thread_id)\n assert retrieved_context is not None\n assert len(retrieved_context.turns) == 1\n\n @patch.dict(os.environ, {\"GEMINI_API_KEY\": \"test-key\", \"OPENAI_API_KEY\": \"\"}, clear=False)\n def test_token_limit_optimization_in_conversation_history(self):\n \"\"\"Test that build_conversation_history efficiently handles token limits\"\"\"\n import os\n import tempfile\n\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry.clear_cache()\n\n from utils.conversation_memory import build_conversation_history\n\n # Create test files with known content sizes\n with tempfile.TemporaryDirectory() as temp_dir:\n # Create small and large test files\n small_file = os.path.join(temp_dir, \"small.py\")\n large_file = os.path.join(temp_dir, \"large.py\")\n\n small_content = \"# Small file\\nprint('hello')\\n\"\n large_content = \"# Large file\\n\" + \"x = 1\\n\" * 10000 # Very large file\n\n with open(small_file, \"w\") as f:\n f.write(small_content)\n with open(large_file, \"w\") as f:\n f.write(large_content)\n\n # Create context with files that would exceed token limit\n context = ThreadContext(\n thread_id=\"test-token-limit\",\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:01:00Z\",\n tool_name=\"analyze\",\n turns=[\n ConversationTurn(\n role=\"user\",\n content=\"Analyze these files\",\n timestamp=\"2023-01-01T00:00:30Z\",\n files=[small_file, large_file], # Large file should be truncated\n )\n ],\n initial_context={\"prompt\": \"Analyze code\"},\n )\n\n # Build conversation history (should handle token limits gracefully)\n history, tokens = build_conversation_history(context, model_context=None)\n\n # Verify the history was built successfully\n assert \"=== CONVERSATION HISTORY\" in history\n assert \"=== FILES REFERENCED IN THIS CONVERSATION ===\" in history\n\n # The small file should be included, but large file might be truncated\n # At minimum, verify no crashes and history is generated\n assert len(history) > 0\n\n # If truncation occurred, there should be a note about it\n if \"additional file(s) were truncated due to token limit\" in history:\n assert small_file in history or large_file in history\n else:\n # Both files fit within limit\n assert small_file in history\n assert large_file in history\n\n\nif __name__ == \"__main__\":\n pytest.main([__file__])\n" }, { "path": "tests/test_conversation_missing_files.py", "content": "\"\"\"\nTest conversation memory handling of missing files.\n\nFollowing existing test patterns to ensure conversation memory gracefully\nhandles missing files without crashing.\n\"\"\"\n\nfrom unittest.mock import Mock\n\nfrom utils.conversation_memory import (\n ConversationTurn,\n ThreadContext,\n build_conversation_history,\n)\n\n\nclass TestConversationMissingFiles:\n \"\"\"Test handling of missing files during conversation memory reconstruction.\"\"\"\n\n def test_build_conversation_history_handles_missing_files(self):\n \"\"\"Test that conversation history building handles missing files gracefully.\"\"\"\n\n # Create conversation context with missing file reference (following existing test patterns)\n context = ThreadContext(\n thread_id=\"test-thread\",\n created_at=\"2024-01-01T00:00:00Z\",\n last_updated_at=\"2024-01-01T00:05:00Z\",\n tool_name=\"analyze\",\n turns=[\n ConversationTurn(\n role=\"user\",\n content=\"Please analyze this file\",\n timestamp=\"2024-01-01T00:01:00Z\",\n files=[\"/nonexistent/missing_file.py\"], # File that doesn't exist\n tool_name=\"analyze\",\n ),\n ConversationTurn(\n role=\"assistant\",\n content=\"Here's my analysis...\",\n timestamp=\"2024-01-01T00:02:00Z\",\n tool_name=\"analyze\",\n ),\n ],\n initial_context={\"path\": \"/nonexistent/missing_file.py\"},\n )\n\n # Mock model context (following existing test patterns)\n mock_model_context = Mock()\n mock_model_context.calculate_token_allocation.return_value = Mock(file_tokens=50000, history_tokens=50000)\n mock_model_context.estimate_tokens.return_value = 100\n mock_model_context.model_name = \"test-model\"\n\n # Should not crash, should handle missing file gracefully\n history, tokens = build_conversation_history(context, mock_model_context)\n\n # Should return valid history despite missing file\n assert isinstance(history, str)\n assert isinstance(tokens, int)\n assert len(history) > 0\n\n # Should contain conversation content\n assert \"CONVERSATION HISTORY\" in history\n assert \"Please analyze this file\" in history\n assert \"Here's my analysis\" in history\n" }, { "path": "tests/test_custom_openai_temperature_fix.py", "content": "\"\"\"\nTest for custom OpenAI models temperature parameter fix.\n\nThis test verifies that custom OpenAI models configured through custom_models.json\nwith supports_temperature=false do not send temperature parameters to the API.\nThis addresses issue #245.\n\"\"\"\n\nimport json\nimport tempfile\nfrom pathlib import Path\nfrom unittest.mock import Mock, patch\n\nfrom providers.openai import OpenAIModelProvider\n\n\nclass TestCustomOpenAITemperatureParameterFix:\n \"\"\"Test custom OpenAI model parameter filtering.\"\"\"\n\n def _create_test_config(self, models_config: list[dict]) -> str:\n \"\"\"Create a temporary config file for testing.\"\"\"\n config = {\"_README\": {\"description\": \"Test config\"}, \"models\": models_config}\n\n temp_file = tempfile.NamedTemporaryFile(mode=\"w\", suffix=\".json\", delete=False)\n json.dump(config, temp_file, indent=2)\n temp_file.close()\n return temp_file.name\n\n @patch(\"utils.model_restrictions.get_restriction_service\")\n @patch(\"providers.openai_compatible.OpenAI\")\n def test_custom_openai_models_exclude_temperature_from_api_call(self, mock_openai_class, mock_restriction_service):\n \"\"\"Test that custom OpenAI models with supports_temperature=false don't send temperature to the API.\"\"\"\n # Create test config with a custom OpenAI model that doesn't support temperature\n config_models = [\n {\n \"model_name\": \"gpt-5-2025-08-07\",\n \"provider\": \"openai\",\n \"context_window\": 400000,\n \"max_output_tokens\": 128000,\n \"supports_extended_thinking\": True,\n \"supports_json_mode\": True,\n \"supports_system_prompts\": True,\n \"supports_streaming\": True,\n \"supports_function_calling\": True,\n \"supports_temperature\": False,\n \"temperature_constraint\": \"fixed\",\n \"supports_images\": True,\n \"max_image_size_mb\": 20.0,\n \"reasoning\": {\"effort\": \"low\"},\n \"description\": \"Custom OpenAI GPT-5 test model\",\n }\n ]\n\n config_path = self._create_test_config(config_models)\n\n try:\n # Mock restriction service to allow all models\n mock_service = Mock()\n mock_service.is_allowed.return_value = True\n mock_restriction_service.return_value = mock_service\n\n # Setup mock client\n mock_client = Mock()\n mock_openai_class.return_value = mock_client\n\n # Setup mock response\n mock_response = Mock()\n mock_response.choices = [Mock()]\n mock_response.choices[0].message.content = \"Test response\"\n mock_response.choices[0].finish_reason = \"stop\"\n mock_response.model = \"gpt-5-2025-08-07\"\n mock_response.id = \"test-id\"\n mock_response.created = 1234567890\n mock_response.usage = Mock()\n mock_response.usage.prompt_tokens = 10\n mock_response.usage.completion_tokens = 5\n mock_response.usage.total_tokens = 15\n\n mock_client.chat.completions.create.return_value = mock_response\n\n # Create provider with custom config\n with patch(\"providers.registries.openrouter.OpenRouterModelRegistry\") as mock_registry_class:\n # Mock registry to load our test config\n mock_registry = Mock()\n mock_registry_class.return_value = mock_registry\n\n # Mock get_model_config to return our test model\n from providers.shared import ModelCapabilities, ProviderType, TemperatureConstraint\n\n test_capabilities = ModelCapabilities(\n provider=ProviderType.OPENAI,\n model_name=\"gpt-5-2025-08-07\",\n friendly_name=\"Custom GPT-5\",\n context_window=400000,\n max_output_tokens=128000,\n supports_extended_thinking=True,\n supports_system_prompts=True,\n supports_streaming=True,\n supports_function_calling=True,\n supports_json_mode=True,\n supports_images=True,\n max_image_size_mb=20.0,\n supports_temperature=False, # This is the key setting\n temperature_constraint=TemperatureConstraint.create(\"fixed\"),\n description=\"Custom OpenAI GPT-5 test model\",\n )\n\n mock_registry.get_model_config.return_value = test_capabilities\n\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Override model validation to bypass restrictions\n provider.validate_model_name = lambda name: True\n\n # Call generate_content with custom model\n provider.generate_content(\n prompt=\"Test prompt\", model_name=\"gpt-5-2025-08-07\", temperature=0.5, max_output_tokens=100\n )\n\n # Verify the API call was made without temperature or max_tokens\n mock_client.chat.completions.create.assert_called_once()\n call_kwargs = mock_client.chat.completions.create.call_args[1]\n\n assert (\n \"temperature\" not in call_kwargs\n ), \"Custom OpenAI models with supports_temperature=false should not include temperature parameter\"\n assert (\n \"max_tokens\" not in call_kwargs\n ), \"Custom OpenAI models with supports_temperature=false should not include max_tokens parameter\"\n assert call_kwargs[\"model\"] == \"gpt-5-2025-08-07\"\n assert \"messages\" in call_kwargs\n\n finally:\n # Clean up temp file\n Path(config_path).unlink(missing_ok=True)\n\n @patch(\"utils.model_restrictions.get_restriction_service\")\n @patch(\"providers.openai_compatible.OpenAI\")\n def test_custom_openai_models_include_temperature_when_supported(self, mock_openai_class, mock_restriction_service):\n \"\"\"Test that custom OpenAI models with supports_temperature=true still send temperature to the API.\"\"\"\n # Mock restriction service to allow all models\n mock_service = Mock()\n mock_service.is_allowed.return_value = True\n mock_restriction_service.return_value = mock_service\n\n # Setup mock client\n mock_client = Mock()\n mock_openai_class.return_value = mock_client\n\n # Setup mock response\n mock_response = Mock()\n mock_response.choices = [Mock()]\n mock_response.choices[0].message.content = \"Test response\"\n mock_response.choices[0].finish_reason = \"stop\"\n mock_response.model = \"gpt-4-custom\"\n mock_response.id = \"test-id\"\n mock_response.created = 1234567890\n mock_response.usage = Mock()\n mock_response.usage.prompt_tokens = 10\n mock_response.usage.completion_tokens = 5\n mock_response.usage.total_tokens = 15\n\n mock_client.chat.completions.create.return_value = mock_response\n\n # Create provider with custom config\n with patch(\"providers.registries.openrouter.OpenRouterModelRegistry\") as mock_registry_class:\n # Mock registry to load our test config\n mock_registry = Mock()\n mock_registry_class.return_value = mock_registry\n\n # Mock get_model_config to return a model that supports temperature\n from providers.shared import ModelCapabilities, ProviderType, TemperatureConstraint\n\n test_capabilities = ModelCapabilities(\n provider=ProviderType.OPENAI,\n model_name=\"gpt-4-custom\",\n friendly_name=\"Custom GPT-4\",\n context_window=128000,\n max_output_tokens=32000,\n supports_extended_thinking=False,\n supports_system_prompts=True,\n supports_streaming=True,\n supports_function_calling=True,\n supports_json_mode=True,\n supports_images=True,\n max_image_size_mb=20.0,\n supports_temperature=True, # This model DOES support temperature\n temperature_constraint=TemperatureConstraint.create(\"range\"),\n description=\"Custom OpenAI GPT-4 test model\",\n )\n\n mock_registry.get_model_config.return_value = test_capabilities\n\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Override model validation to bypass restrictions\n provider.validate_model_name = lambda name: True\n\n # Call generate_content with custom model that supports temperature\n provider.generate_content(\n prompt=\"Test prompt\", model_name=\"gpt-4-custom\", temperature=0.5, max_output_tokens=100\n )\n\n # Verify the API call was made WITH temperature and max_tokens\n mock_client.chat.completions.create.assert_called_once()\n call_kwargs = mock_client.chat.completions.create.call_args[1]\n\n assert (\n call_kwargs[\"temperature\"] == 0.5\n ), \"Custom OpenAI models with supports_temperature=true should include temperature parameter\"\n assert (\n call_kwargs[\"max_tokens\"] == 100\n ), \"Custom OpenAI models with supports_temperature=true should include max_tokens parameter\"\n assert call_kwargs[\"model\"] == \"gpt-4-custom\"\n\n @patch(\"utils.model_restrictions.get_restriction_service\")\n def test_custom_openai_model_validation(self, mock_restriction_service):\n \"\"\"Test that custom OpenAI models are properly validated.\"\"\"\n # Mock restriction service to allow all models\n mock_service = Mock()\n mock_service.is_allowed.return_value = True\n mock_restriction_service.return_value = mock_service\n\n with patch(\"providers.registries.openrouter.OpenRouterModelRegistry\") as mock_registry_class:\n # Mock registry to return a custom OpenAI model\n mock_registry = Mock()\n mock_registry_class.return_value = mock_registry\n\n from providers.shared import ModelCapabilities, ProviderType, TemperatureConstraint\n\n test_capabilities = ModelCapabilities(\n provider=ProviderType.OPENAI,\n model_name=\"o3-2025-04-16\",\n friendly_name=\"Custom O3\",\n context_window=200000,\n max_output_tokens=65536,\n supports_extended_thinking=False,\n supports_system_prompts=True,\n supports_streaming=True,\n supports_function_calling=True,\n supports_json_mode=True,\n supports_images=True,\n max_image_size_mb=20.0,\n supports_temperature=False,\n temperature_constraint=TemperatureConstraint.create(\"fixed\"),\n description=\"Custom OpenAI O3 test model\",\n )\n\n mock_registry.get_model_config.return_value = test_capabilities\n\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Test that custom model validates successfully\n assert provider.validate_model_name(\"o3-2025-04-16\") is True\n\n # Test that get_capabilities returns the custom config\n capabilities = provider.get_capabilities(\"o3-2025-04-16\")\n assert capabilities.supports_temperature is False\n assert capabilities.model_name == \"o3-2025-04-16\"\n assert capabilities.provider == ProviderType.OPENAI\n\n @patch(\"utils.model_restrictions.get_restriction_service\")\n def test_fallback_to_builtin_models_when_registry_fails(self, mock_restriction_service):\n \"\"\"Test that provider falls back to built-in models when registry fails.\"\"\"\n # Mock restriction service to allow all models\n mock_service = Mock()\n mock_service.is_allowed.return_value = True\n mock_restriction_service.return_value = mock_service\n\n with patch(\"providers.registries.openrouter.OpenRouterModelRegistry\") as mock_registry_class:\n # Mock registry to raise an exception\n mock_registry_class.side_effect = Exception(\"Registry not available\")\n\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Test that built-in models still work\n assert provider.validate_model_name(\"o3-mini\") is True\n\n # Test that unsupported models return false\n assert provider.validate_model_name(\"unknown-model\") is False\n" }, { "path": "tests/test_custom_provider.py", "content": "\"\"\"Tests for CustomProvider functionality.\"\"\"\n\nimport os\nfrom unittest.mock import MagicMock, patch\n\nimport pytest\n\nfrom providers import ModelProviderRegistry\nfrom providers.custom import CustomProvider\nfrom providers.shared import ProviderType\n\n\nclass TestCustomProvider:\n \"\"\"Test CustomProvider class functionality.\"\"\"\n\n def test_provider_initialization_with_params(self):\n \"\"\"Test CustomProvider initializes correctly with explicit parameters.\"\"\"\n provider = CustomProvider(api_key=\"test-key\", base_url=\"http://localhost:11434/v1\")\n\n assert provider.base_url == \"http://localhost:11434/v1\"\n assert provider.api_key == \"test-key\"\n assert provider.get_provider_type() == ProviderType.CUSTOM\n\n def test_provider_initialization_with_env_vars(self):\n \"\"\"Test CustomProvider initializes correctly with environment variables.\"\"\"\n with patch.dict(os.environ, {\"CUSTOM_API_URL\": \"http://localhost:8000/v1\", \"CUSTOM_API_KEY\": \"env-key\"}):\n provider = CustomProvider()\n\n assert provider.base_url == \"http://localhost:8000/v1\"\n assert provider.api_key == \"env-key\"\n\n def test_provider_initialization_missing_url(self):\n \"\"\"Test CustomProvider raises error when URL is missing.\"\"\"\n with patch.dict(os.environ, {\"CUSTOM_API_URL\": \"\"}, clear=False):\n with pytest.raises(ValueError, match=\"Custom API URL must be provided\"):\n CustomProvider(api_key=\"test-key\")\n\n def test_validate_model_names_always_true(self):\n \"\"\"Test CustomProvider validates model names correctly.\"\"\"\n provider = CustomProvider(api_key=\"test-key\", base_url=\"http://localhost:11434/v1\")\n\n # Known model should validate\n assert provider.validate_model_name(\"llama3.2\")\n\n # For custom provider, unknown models return False when not in registry\n # This is expected behavior - custom models need to be declared in custom_models.json\n assert not provider.validate_model_name(\"unknown-model\")\n assert not provider.validate_model_name(\"anything\")\n\n def test_get_capabilities_from_registry(self):\n \"\"\"Test get_capabilities returns registry capabilities when available.\"\"\"\n # Save original environment\n original_env = os.environ.get(\"OPENROUTER_ALLOWED_MODELS\")\n\n try:\n # Clear any restrictions\n os.environ.pop(\"OPENROUTER_ALLOWED_MODELS\", None)\n\n provider = CustomProvider(api_key=\"test-key\", base_url=\"http://localhost:11434/v1\")\n\n # OpenRouter-backed models should be handled by the OpenRouter provider\n with pytest.raises(ValueError):\n provider.get_capabilities(\"o3\")\n\n # Test with a custom model from the local registry\n capabilities = provider.get_capabilities(\"local-llama\")\n assert capabilities.provider == ProviderType.CUSTOM\n assert capabilities.context_window > 0\n\n finally:\n # Restore original environment\n if original_env is None:\n os.environ.pop(\"OPENROUTER_ALLOWED_MODELS\", None)\n else:\n os.environ[\"OPENROUTER_ALLOWED_MODELS\"] = original_env\n\n def test_get_capabilities_generic_fallback(self):\n \"\"\"Test get_capabilities raises error for unknown models not in registry.\"\"\"\n provider = CustomProvider(api_key=\"test-key\", base_url=\"http://localhost:11434/v1\")\n\n # Unknown models should raise ValueError when not in registry\n with pytest.raises(ValueError, match=\"Unsupported model 'unknown-model-xyz' for provider custom\"):\n provider.get_capabilities(\"unknown-model-xyz\")\n\n def test_model_alias_resolution(self):\n \"\"\"Test model alias resolution works correctly.\"\"\"\n provider = CustomProvider(api_key=\"test-key\", base_url=\"http://localhost:11434/v1\")\n\n # Test that aliases resolve properly\n # \"llama\" now resolves to \"meta-llama/llama-3-70b\" (the OpenRouter model)\n resolved = provider._resolve_model_name(\"llama\")\n assert resolved == \"meta-llama/llama-3-70b\"\n\n # Test local model alias\n resolved_local = provider._resolve_model_name(\"local-llama\")\n assert resolved_local == \"llama3.2\"\n\n def test_no_thinking_mode_support(self):\n \"\"\"Custom provider generic capabilities default to no thinking mode.\"\"\"\n provider = CustomProvider(api_key=\"test-key\", base_url=\"http://localhost:11434/v1\")\n\n # llama3.2 is a known model that should work\n assert not provider.get_capabilities(\"llama3.2\").supports_extended_thinking\n\n # Unknown models should raise error\n with pytest.raises(ValueError, match=\"Unsupported model 'any-model' for provider custom\"):\n provider.get_capabilities(\"any-model\")\n\n @patch(\"providers.custom.OpenAICompatibleProvider.generate_content\")\n def test_generate_content_with_alias_resolution(self, mock_generate):\n \"\"\"Test generate_content resolves aliases before calling parent.\"\"\"\n mock_response = MagicMock()\n mock_generate.return_value = mock_response\n\n provider = CustomProvider(api_key=\"test-key\", base_url=\"http://localhost:11434/v1\")\n\n # Call with an alias\n result = provider.generate_content(\n prompt=\"test prompt\",\n model_name=\"llama\",\n temperature=0.7, # This is an alias\n )\n\n # Verify parent method was called with resolved model name\n mock_generate.assert_called_once()\n call_args = mock_generate.call_args\n # The model_name should be either resolved or passed through\n assert \"model_name\" in call_args.kwargs\n assert result == mock_response\n\n\nclass TestCustomProviderRegistration:\n \"\"\"Test CustomProvider integration with ModelProviderRegistry.\"\"\"\n\n def setup_method(self):\n \"\"\"Clear registry before each test.\"\"\"\n ModelProviderRegistry.clear_cache()\n ModelProviderRegistry.unregister_provider(ProviderType.CUSTOM)\n\n def teardown_method(self):\n \"\"\"Clean up after each test.\"\"\"\n ModelProviderRegistry.clear_cache()\n ModelProviderRegistry.unregister_provider(ProviderType.CUSTOM)\n\n def test_custom_provider_factory_registration(self):\n \"\"\"Test custom provider can be registered via factory function.\"\"\"\n\n def custom_provider_factory(api_key=None):\n return CustomProvider(api_key=\"test-key\", base_url=\"http://localhost:11434/v1\")\n\n with patch.dict(os.environ, {\"CUSTOM_API_PLACEHOLDER\": \"configured\"}):\n ModelProviderRegistry.register_provider(ProviderType.CUSTOM, custom_provider_factory)\n\n # Verify provider is available\n available = ModelProviderRegistry.get_available_providers()\n assert ProviderType.CUSTOM in available\n\n # Verify provider can be retrieved\n provider = ModelProviderRegistry.get_provider(ProviderType.CUSTOM)\n assert provider is not None\n assert isinstance(provider, CustomProvider)\n\n def test_dual_provider_setup(self):\n \"\"\"Test both OpenRouter and Custom providers can coexist.\"\"\"\n from providers.openrouter import OpenRouterProvider\n\n # Create factory for custom provider\n def custom_provider_factory(api_key=None):\n return CustomProvider(api_key=\"\", base_url=\"http://localhost:11434/v1\")\n\n with patch.dict(\n os.environ,\n {\n \"OPENROUTER_API_KEY\": \"test-openrouter-key\",\n \"CUSTOM_API_PLACEHOLDER\": \"configured\",\n \"OPENROUTER_ALLOWED_MODELS\": \"llama,anthropic/claude-opus-4.1\",\n },\n clear=True,\n ):\n # Register both providers\n ModelProviderRegistry.register_provider(ProviderType.OPENROUTER, OpenRouterProvider)\n ModelProviderRegistry.register_provider(ProviderType.CUSTOM, custom_provider_factory)\n\n # Verify both are available\n available = ModelProviderRegistry.get_available_providers()\n assert ProviderType.OPENROUTER in available\n assert ProviderType.CUSTOM in available\n\n # Verify both can be retrieved\n openrouter_provider = ModelProviderRegistry.get_provider(ProviderType.OPENROUTER)\n custom_provider = ModelProviderRegistry.get_provider(ProviderType.CUSTOM)\n\n assert openrouter_provider is not None\n assert custom_provider is not None\n assert isinstance(custom_provider, CustomProvider)\n\n def test_provider_priority_selection(self):\n \"\"\"Test provider selection prioritizes correctly.\"\"\"\n from providers.openrouter import OpenRouterProvider\n\n def custom_provider_factory(api_key=None):\n return CustomProvider(api_key=\"\", base_url=\"http://localhost:11434/v1\")\n\n with patch.dict(\n os.environ,\n {\n \"OPENROUTER_API_KEY\": \"test-openrouter-key\",\n \"CUSTOM_API_PLACEHOLDER\": \"configured\",\n \"OPENROUTER_ALLOWED_MODELS\": \"\",\n },\n clear=True,\n ):\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n custom_provider = custom_provider_factory()\n openrouter_provider = OpenRouterProvider(api_key=\"test-openrouter-key\")\n\n assert not custom_provider.validate_model_name(\"llama\")\n assert openrouter_provider.validate_model_name(\"llama\")\n\n\nclass TestConfigureProvidersFunction:\n \"\"\"Test the configure_providers function in server.py.\"\"\"\n\n def setup_method(self):\n \"\"\"Clear environment and registry before each test.\"\"\"\n # Store the original providers to restore them later\n registry = ModelProviderRegistry()\n self._original_providers = registry._providers.copy()\n ModelProviderRegistry.clear_cache()\n for provider_type in ProviderType:\n ModelProviderRegistry.unregister_provider(provider_type)\n\n def teardown_method(self):\n \"\"\"Clean up after each test.\"\"\"\n # Restore the original providers that were registered in conftest.py\n registry = ModelProviderRegistry()\n ModelProviderRegistry.clear_cache()\n registry._providers.clear()\n registry._providers.update(self._original_providers)\n\n def test_configure_providers_custom_only(self):\n \"\"\"Test configure_providers with only custom URL set.\"\"\"\n from server import configure_providers\n\n with patch.dict(\n os.environ,\n {\n \"CUSTOM_API_URL\": \"http://localhost:11434/v1\",\n \"CUSTOM_API_KEY\": \"\",\n # Clear other API keys\n \"GEMINI_API_KEY\": \"\",\n \"OPENAI_API_KEY\": \"\",\n \"OPENROUTER_API_KEY\": \"\",\n },\n clear=True,\n ):\n configure_providers()\n\n # Verify only custom provider is available\n available = ModelProviderRegistry.get_available_providers()\n assert ProviderType.CUSTOM in available\n assert ProviderType.OPENROUTER not in available\n\n def test_configure_providers_openrouter_only(self):\n \"\"\"Test configure_providers with only OpenRouter key set.\"\"\"\n from server import configure_providers\n\n with patch.dict(\n os.environ,\n {\n \"OPENROUTER_API_KEY\": \"test-key\",\n # Clear other API keys\n \"GEMINI_API_KEY\": \"\",\n \"OPENAI_API_KEY\": \"\",\n \"CUSTOM_API_URL\": \"\",\n },\n clear=True,\n ):\n configure_providers()\n\n # Verify only OpenRouter provider is available\n available = ModelProviderRegistry.get_available_providers()\n assert ProviderType.OPENROUTER in available\n assert ProviderType.CUSTOM not in available\n\n def test_configure_providers_dual_setup(self):\n \"\"\"Test configure_providers with both OpenRouter and Custom configured.\"\"\"\n from server import configure_providers\n\n with patch.dict(\n os.environ,\n {\n \"OPENROUTER_API_KEY\": \"test-openrouter-key\",\n \"CUSTOM_API_URL\": \"http://localhost:11434/v1\",\n \"CUSTOM_API_KEY\": \"\",\n # Clear other API keys\n \"GEMINI_API_KEY\": \"\",\n \"OPENAI_API_KEY\": \"\",\n },\n clear=True,\n ):\n configure_providers()\n\n # Verify both providers are available\n available = ModelProviderRegistry.get_available_providers()\n assert ProviderType.OPENROUTER in available\n assert ProviderType.CUSTOM in available\n\n def test_configure_providers_no_valid_keys(self):\n \"\"\"Test configure_providers raises error when no valid API keys.\"\"\"\n from server import configure_providers\n\n with patch.dict(\n os.environ,\n {\"GEMINI_API_KEY\": \"\", \"OPENAI_API_KEY\": \"\", \"OPENROUTER_API_KEY\": \"\", \"CUSTOM_API_URL\": \"\"},\n clear=True,\n ):\n with pytest.raises(ValueError, match=\"At least one API configuration is required\"):\n configure_providers()\n" }, { "path": "tests/test_debug.py", "content": "\"\"\"\nTests for the debug tool using new WorkflowTool architecture.\n\"\"\"\n\nfrom tools.debug import DebugInvestigationRequest, DebugIssueTool\nfrom tools.models import ToolModelCategory\n\n\nclass TestDebugTool:\n \"\"\"Test suite for DebugIssueTool using new WorkflowTool architecture.\"\"\"\n\n def test_tool_metadata(self):\n \"\"\"Test basic tool metadata and configuration.\"\"\"\n tool = DebugIssueTool()\n\n assert tool.get_name() == \"debug\"\n assert \"debugging and root cause analysis\" in tool.get_description()\n assert tool.get_default_temperature() == 1.0 # TEMPERATURE_ANALYTICAL\n assert tool.get_model_category() == ToolModelCategory.EXTENDED_REASONING\n assert tool.requires_model() is True\n\n def test_request_validation(self):\n \"\"\"Test Pydantic request model validation.\"\"\"\n # Valid investigation step request\n step_request = DebugInvestigationRequest(\n step=\"Investigating null pointer exception in UserService\",\n step_number=1,\n total_steps=3,\n next_step_required=True,\n findings=\"Found potential null reference in user authentication flow\",\n files_checked=[\"/src/UserService.java\"],\n relevant_files=[\"/src/UserService.java\"],\n relevant_context=[\"authenticate\", \"validateUser\"],\n confidence=\"medium\",\n hypothesis=\"Null pointer occurs when user object is not properly validated\",\n )\n\n assert step_request.step_number == 1\n assert step_request.confidence == \"medium\"\n assert len(step_request.relevant_context) == 2\n\n def test_input_schema_generation(self):\n \"\"\"Test that input schema is generated correctly.\"\"\"\n tool = DebugIssueTool()\n schema = tool.get_input_schema()\n\n # Verify required investigation fields are present\n assert \"step\" in schema[\"properties\"]\n assert \"step_number\" in schema[\"properties\"]\n assert \"total_steps\" in schema[\"properties\"]\n assert \"next_step_required\" in schema[\"properties\"]\n assert \"findings\" in schema[\"properties\"]\n assert \"relevant_context\" in schema[\"properties\"]\n\n # Verify field types\n assert schema[\"properties\"][\"step\"][\"type\"] == \"string\"\n assert schema[\"properties\"][\"step_number\"][\"type\"] == \"integer\"\n assert schema[\"properties\"][\"next_step_required\"][\"type\"] == \"boolean\"\n assert schema[\"properties\"][\"relevant_context\"][\"type\"] == \"array\"\n\n def test_model_category_for_debugging(self):\n \"\"\"Test that debug tool correctly identifies as extended reasoning category.\"\"\"\n tool = DebugIssueTool()\n assert tool.get_model_category() == ToolModelCategory.EXTENDED_REASONING\n\n def test_relevant_context_handling(self):\n \"\"\"Test that relevant_context is handled correctly.\"\"\"\n request = DebugInvestigationRequest(\n step=\"Test investigation\",\n step_number=1,\n total_steps=2,\n next_step_required=True,\n findings=\"Test findings\",\n relevant_context=[\"method1\", \"method2\"],\n )\n\n # Should have relevant_context directly\n assert request.relevant_context == [\"method1\", \"method2\"]\n\n # Test step data preparation\n tool = DebugIssueTool()\n step_data = tool.prepare_step_data(request)\n assert step_data[\"relevant_context\"] == [\"method1\", \"method2\"]\n" }, { "path": "tests/test_deploy_scripts.py", "content": "\"\"\"\nTests for Docker deployment scripts\n\"\"\"\n\nimport subprocess\nfrom pathlib import Path\nfrom unittest.mock import patch\n\nimport pytest\n\n\nclass TestDeploymentScripts:\n \"\"\"Test Docker deployment scripts\"\"\"\n\n @pytest.fixture(autouse=True)\n def setup(self):\n \"\"\"Setup for each test\"\"\"\n self.project_root = Path(__file__).parent.parent\n self.scripts_dir = self.project_root / \"docker\" / \"scripts\"\n\n def test_deployment_scripts_exist(self):\n \"\"\"Test that deployment scripts exist\"\"\"\n expected_scripts = [\"deploy.sh\", \"deploy.ps1\", \"build.sh\", \"build.ps1\", \"healthcheck.py\"]\n\n for script in expected_scripts:\n script_path = self.scripts_dir / script\n assert script_path.exists(), f\"Script {script} must exist\"\n\n def test_bash_scripts_executable(self):\n \"\"\"Test that bash scripts have proper permissions\"\"\"\n bash_scripts = [\"deploy.sh\", \"build.sh\"]\n\n for script in bash_scripts:\n script_path = self.scripts_dir / script\n if script_path.exists():\n # Check for shebang\n content = script_path.read_text()\n assert content.startswith(\"#!/\"), f\"Script {script} must have shebang\"\n\n def test_powershell_scripts_format(self):\n \"\"\"Test PowerShell scripts have proper format\"\"\"\n ps_scripts = [\"deploy.ps1\", \"build.ps1\"]\n\n for script in ps_scripts:\n script_path = self.scripts_dir / script\n if script_path.exists():\n content = script_path.read_text()\n\n # Check for PowerShell indicators\n ps_indicators = [\n \"param(\",\n \"Write-Host\",\n \"Write-Output\",\n \"$\", # PowerShell variables\n ]\n\n assert any(\n indicator in content for indicator in ps_indicators\n ), f\"Script {script} should contain PowerShell syntax\"\n\n @patch(\"subprocess.run\")\n def test_deploy_script_docker_commands(self, mock_run):\n \"\"\"Test that deploy scripts use proper Docker commands\"\"\"\n mock_run.return_value.returncode = 0\n\n # Expected Docker commands in deployment\n expected_commands = [[\"docker\", \"build\"], [\"docker-compose\", \"up\"], [\"docker\", \"run\"]]\n\n for cmd in expected_commands:\n subprocess.run(cmd, capture_output=True)\n\n # Verify subprocess.run was called\n assert mock_run.call_count >= len(expected_commands)\n\n def test_build_script_functionality(self):\n \"\"\"Test build script basic functionality\"\"\"\n build_script = self.scripts_dir / \"build.sh\"\n\n if build_script.exists():\n content = build_script.read_text()\n\n # Should contain Docker build commands\n assert (\n \"docker build\" in content or \"docker-compose build\" in content\n ), \"Build script should contain Docker build commands\"\n\n def test_deploy_script_health_check_integration(self):\n \"\"\"Test deploy script includes health check validation\"\"\"\n deploy_scripts = [\"deploy.sh\", \"deploy.ps1\"]\n\n for script_name in deploy_scripts:\n script_path = self.scripts_dir / script_name\n if script_path.exists():\n content = script_path.read_text()\n\n # Look for health check related content\n health_check_indicators = [\"health\", \"healthcheck\", \"docker inspect\", \"container status\"]\n\n has_health_check = any(indicator in content.lower() for indicator in health_check_indicators)\n\n if not has_health_check:\n pytest.warns(UserWarning, f\"Consider adding health check to {script_name}\")\n\n def test_script_error_handling(self):\n \"\"\"Test that scripts have proper error handling\"\"\"\n scripts = [\"deploy.sh\", \"build.sh\"]\n\n for script_name in scripts:\n script_path = self.scripts_dir / script_name\n if script_path.exists():\n content = script_path.read_text()\n\n # Check for error handling patterns\n error_patterns = [\n \"set -e\", # Bash: exit on error\n \"||\", # Or operator for error handling\n \"if\", # Conditional error checking\n \"exit\", # Explicit exit codes\n ]\n\n has_error_handling = any(pattern in content for pattern in error_patterns)\n\n if not has_error_handling:\n pytest.warns(UserWarning, f\"Consider adding error handling to {script_name}\")\n\n @patch(\"subprocess.run\")\n def test_docker_compose_commands(self, mock_run):\n \"\"\"Test Docker Compose command execution\"\"\"\n mock_run.return_value.returncode = 0\n\n # Test various docker-compose commands\n compose_commands = [\n [\"docker-compose\", \"build\"],\n [\"docker-compose\", \"up\", \"-d\"],\n [\"docker-compose\", \"down\"],\n [\"docker-compose\", \"ps\"],\n ]\n\n for cmd in compose_commands:\n result = subprocess.run(cmd, capture_output=True)\n assert result.returncode == 0\n\n def test_script_parameter_handling(self):\n \"\"\"Test script parameter and option handling\"\"\"\n deploy_ps1 = self.scripts_dir / \"deploy.ps1\"\n\n if deploy_ps1.exists():\n content = deploy_ps1.read_text()\n\n # PowerShell scripts should handle parameters\n param_indicators = [\"param(\", \"[Parameter(\", \"$SkipHealthCheck\", \"$HealthCheckTimeout\"]\n\n has_parameters = any(indicator in content for indicator in param_indicators)\n\n assert has_parameters, \"PowerShell deploy script should handle parameters\"\n\n def test_environment_preparation(self):\n \"\"\"Test that scripts prepare environment correctly\"\"\"\n scripts_to_check = [\"deploy.sh\", \"deploy.ps1\"]\n\n for script_name in scripts_to_check:\n script_path = self.scripts_dir / script_name\n if script_path.exists():\n content = script_path.read_text()\n\n # Check for environment preparation\n env_prep_patterns = [\".env\", \"environment\", \"API_KEY\", \"mkdir\", \"logs\"]\n\n prepares_environment = any(pattern in content for pattern in env_prep_patterns)\n\n if not prepares_environment:\n pytest.warns(UserWarning, f\"Consider environment preparation in {script_name}\")\n\n\nclass TestHealthCheckScript:\n \"\"\"Test health check script specifically\"\"\"\n\n @pytest.fixture(autouse=True)\n def setup(self):\n \"\"\"Setup for each test\"\"\"\n self.project_root = Path(__file__).parent.parent\n self.healthcheck_script = self.project_root / \"docker\" / \"scripts\" / \"healthcheck.py\"\n\n def test_healthcheck_script_syntax(self):\n \"\"\"Test health check script has valid Python syntax\"\"\"\n if not self.healthcheck_script.exists():\n pytest.skip(\"healthcheck.py not found\")\n\n # Try to compile the script\n try:\n with open(self.healthcheck_script, encoding=\"utf-8\") as f:\n content = f.read()\n compile(content, str(self.healthcheck_script), \"exec\")\n except SyntaxError as e:\n pytest.fail(f\"Health check script has syntax errors: {e}\")\n\n def test_healthcheck_functions_exist(self):\n \"\"\"Test that health check functions are defined\"\"\"\n if not self.healthcheck_script.exists():\n pytest.skip(\"healthcheck.py not found\")\n\n content = self.healthcheck_script.read_text()\n\n # Expected functions\n expected_functions = [\"def check_process\", \"def check_python_imports\", \"def check_log_directory\"]\n\n for func in expected_functions:\n assert func in content, f\"Function {func} should be defined\"\n\n @patch(\"subprocess.run\")\n def test_healthcheck_process_check(self, mock_run):\n \"\"\"Test health check process verification\"\"\"\n # Mock successful process check\n mock_run.return_value.returncode = 0\n mock_run.return_value.stdout = \"12345\"\n\n # Simulate process check\n result = subprocess.run([\"pgrep\", \"-f\", \"server.py\"], capture_output=True, text=True, timeout=10)\n\n assert result.returncode == 0\n\n def test_healthcheck_import_validation(self):\n \"\"\"Test health check import validation logic\"\"\"\n # Test critical modules that should be importable\n critical_modules = [\"os\", \"sys\", \"subprocess\"]\n\n for module in critical_modules:\n try:\n __import__(module)\n except ImportError:\n pytest.fail(f\"Critical module {module} should be importable\")\n\n def test_healthcheck_exit_codes(self):\n \"\"\"Test that health check uses proper exit codes\"\"\"\n if not self.healthcheck_script.exists():\n pytest.skip(\"healthcheck.py not found\")\n\n content = self.healthcheck_script.read_text()\n\n # Should have proper exit code handling\n exit_patterns = [\n \"sys.exit(0)\", # Success\n \"sys.exit(1)\", # Failure\n \"exit(0)\",\n \"exit(1)\",\n ]\n\n has_exit_codes = any(pattern in content for pattern in exit_patterns)\n\n assert has_exit_codes, \"Health check should use proper exit codes\"\n\n\nclass TestScriptIntegration:\n \"\"\"Test script integration with Docker ecosystem\"\"\"\n\n def test_scripts_work_with_compose_file(self):\n \"\"\"Test that scripts work with docker-compose.yml\"\"\"\n project_root = Path(__file__).parent.parent\n compose_file = project_root / \"docker-compose.yml\"\n\n if compose_file.exists():\n # Scripts should reference the compose file\n deploy_script = project_root / \"docker\" / \"scripts\" / \"deploy.sh\"\n\n if deploy_script.exists():\n content = deploy_script.read_text()\n\n # Should work with compose file\n compose_refs = [\"docker-compose\", \"compose.yml\", \"compose.yaml\"]\n\n references_compose = any(ref in content for ref in compose_refs)\n\n assert (\n references_compose or \"docker build\" in content\n ), \"Deploy script should use either compose or direct Docker\"\n\n def test_cross_platform_compatibility(self):\n \"\"\"Test cross-platform script compatibility\"\"\"\n # Both Unix and Windows scripts should exist\n unix_deploy = Path(__file__).parent.parent / \"docker\" / \"scripts\" / \"deploy.sh\"\n windows_deploy = Path(__file__).parent.parent / \"docker\" / \"scripts\" / \"deploy.ps1\"\n\n # At least one should exist\n assert unix_deploy.exists() or windows_deploy.exists(), \"At least one deployment script should exist\"\n\n # If both exist, they should have similar functionality\n if unix_deploy.exists() and windows_deploy.exists():\n unix_content = unix_deploy.read_text()\n windows_content = windows_deploy.read_text()\n\n # Both should reference Docker\n assert \"docker\" in unix_content.lower()\n assert \"docker\" in windows_content.lower()\n\n def test_script_logging_integration(self):\n \"\"\"Test that scripts integrate with logging\"\"\"\n scripts_dir = Path(__file__).parent.parent / \"docker\" / \"scripts\"\n scripts = [\"deploy.sh\", \"deploy.ps1\", \"build.sh\", \"build.ps1\"]\n\n for script_name in scripts:\n script_path = scripts_dir / script_name\n if script_path.exists():\n content = script_path.read_text()\n\n # Check for logging/output\n logging_patterns = [\"echo\", \"Write-Host\", \"Write-Output\", \"print\", \"logger\"]\n\n has_logging = any(pattern in content for pattern in logging_patterns)\n\n if not has_logging:\n pytest.warns(UserWarning, f\"Consider adding logging to {script_name}\")\n" }, { "path": "tests/test_dial_provider.py", "content": "\"\"\"Tests for DIAL provider implementation.\"\"\"\n\nimport os\nfrom unittest.mock import MagicMock, patch\n\nimport pytest\n\nfrom providers.dial import DIALModelProvider\nfrom providers.shared import ProviderType\n\n\nclass TestDIALProvider:\n \"\"\"Test DIAL provider functionality.\"\"\"\n\n @patch.dict(os.environ, {\"DIAL_API_KEY\": \"test-key\", \"DIAL_API_HOST\": \"https://test.dialx.ai\"})\n def test_initialization_with_host(self):\n \"\"\"Test provider initialization with custom host.\"\"\"\n provider = DIALModelProvider(\"test-key\")\n assert provider._dial_api_key == \"test-key\" # Check internal API key storage\n assert provider.api_key == \"placeholder-not-used\" # OpenAI client uses placeholder, auth header removed by hook\n assert provider.base_url == \"https://test.dialx.ai/openai\"\n assert provider.get_provider_type() == ProviderType.DIAL\n\n @patch.dict(os.environ, {\"DIAL_API_KEY\": \"test-key\", \"DIAL_API_HOST\": \"\"}, clear=True)\n def test_initialization_default_host(self):\n \"\"\"Test provider initialization with default host.\"\"\"\n provider = DIALModelProvider(\"test-key\")\n assert provider._dial_api_key == \"test-key\" # Check internal API key storage\n assert provider.api_key == \"placeholder-not-used\" # OpenAI client uses placeholder, auth header removed by hook\n assert provider.base_url == \"https://core.dialx.ai/openai\"\n\n def test_initialization_host_normalization(self):\n \"\"\"Test that host URL is normalized to include /openai suffix.\"\"\"\n # Test with host missing /openai\n provider = DIALModelProvider(\"test-key\", base_url=\"https://custom.dialx.ai\")\n assert provider.base_url == \"https://custom.dialx.ai/openai\"\n\n # Test with host already having /openai\n provider = DIALModelProvider(\"test-key\", base_url=\"https://custom.dialx.ai/openai\")\n assert provider.base_url == \"https://custom.dialx.ai/openai\"\n\n @patch.dict(os.environ, {\"DIAL_ALLOWED_MODELS\": \"\"}, clear=False)\n @patch(\"utils.model_restrictions._restriction_service\", None)\n def test_model_validation(self):\n \"\"\"Test model name validation.\"\"\"\n provider = DIALModelProvider(\"test-key\")\n\n # Test valid models\n assert provider.validate_model_name(\"o3-2025-04-16\") is True\n assert provider.validate_model_name(\"o3\") is True # Shorthand\n assert provider.validate_model_name(\"anthropic.claude-opus-4.1-20250805-v1:0\") is True\n assert provider.validate_model_name(\"opus-4.1\") is True # Shorthand\n assert provider.validate_model_name(\"gemini-2.5-pro-preview-05-06\") is True\n assert provider.validate_model_name(\"gemini-2.5-pro\") is True # Shorthand\n\n # Test invalid model\n assert provider.validate_model_name(\"invalid-model\") is False\n\n def test_resolve_model_name(self):\n \"\"\"Test model name resolution for shorthands.\"\"\"\n provider = DIALModelProvider(\"test-key\")\n\n # Test shorthand resolution\n assert provider._resolve_model_name(\"o3\") == \"o3-2025-04-16\"\n assert provider._resolve_model_name(\"o4-mini\") == \"o4-mini-2025-04-16\"\n assert provider._resolve_model_name(\"opus-4.1\") == \"anthropic.claude-opus-4.1-20250805-v1:0\"\n assert provider._resolve_model_name(\"sonnet-4.1\") == \"anthropic.claude-sonnet-4.1-20250805-v1:0\"\n assert provider._resolve_model_name(\"gemini-2.5-pro\") == \"gemini-2.5-pro-preview-05-06\"\n assert provider._resolve_model_name(\"gemini-2.5-flash\") == \"gemini-2.5-flash-preview-05-20\"\n\n # Test full name passthrough\n assert provider._resolve_model_name(\"o3-2025-04-16\") == \"o3-2025-04-16\"\n assert (\n provider._resolve_model_name(\"anthropic.claude-opus-4.1-20250805-v1:0\")\n == \"anthropic.claude-opus-4.1-20250805-v1:0\"\n )\n\n @patch.dict(os.environ, {\"DIAL_ALLOWED_MODELS\": \"\"}, clear=False)\n @patch(\"utils.model_restrictions._restriction_service\", None)\n def test_get_capabilities(self):\n \"\"\"Test getting model capabilities.\"\"\"\n provider = DIALModelProvider(\"test-key\")\n\n # Test O3 capabilities\n capabilities = provider.get_capabilities(\"o3\")\n assert capabilities.model_name == \"o3-2025-04-16\"\n assert capabilities.friendly_name == \"DIAL (O3)\"\n assert capabilities.context_window == 200_000\n assert capabilities.provider == ProviderType.DIAL\n assert capabilities.supports_images is True\n assert capabilities.supports_extended_thinking is False\n\n # Test Claude 4.1 capabilities\n capabilities = provider.get_capabilities(\"opus-4.1\")\n assert capabilities.model_name == \"anthropic.claude-opus-4.1-20250805-v1:0\"\n assert capabilities.context_window == 200_000\n assert capabilities.supports_images is True\n assert capabilities.supports_extended_thinking is False\n\n # Test Claude 4.1 with thinking mode\n capabilities = provider.get_capabilities(\"opus-4.1-thinking\")\n assert capabilities.model_name == \"anthropic.claude-opus-4.1-20250805-v1:0-with-thinking\"\n assert capabilities.context_window == 200_000\n assert capabilities.supports_images is True\n assert capabilities.supports_extended_thinking is True\n\n # Test Gemini capabilities\n capabilities = provider.get_capabilities(\"gemini-2.5-pro\")\n assert capabilities.model_name == \"gemini-2.5-pro-preview-05-06\"\n assert capabilities.context_window == 1_000_000\n assert capabilities.supports_images is True\n\n # Test temperature constraint\n assert capabilities.temperature_constraint.min_temp == 0.0\n assert capabilities.temperature_constraint.max_temp == 2.0\n assert capabilities.temperature_constraint.default_temp == 0.3\n\n @patch.dict(os.environ, {\"DIAL_ALLOWED_MODELS\": \"\"}, clear=False)\n @patch(\"utils.model_restrictions._restriction_service\", None)\n def test_get_capabilities_invalid_model(self):\n \"\"\"Test that get_capabilities raises for invalid models.\"\"\"\n provider = DIALModelProvider(\"test-key\")\n\n with pytest.raises(ValueError, match=\"Unsupported model 'invalid-model' for provider dial\"):\n provider.get_capabilities(\"invalid-model\")\n\n @patch(\"utils.model_restrictions.get_restriction_service\")\n def test_get_capabilities_restricted_model(self, mock_get_restriction):\n \"\"\"Test that get_capabilities respects model restrictions.\"\"\"\n provider = DIALModelProvider(\"test-key\")\n\n # Mock restriction service to block the model\n mock_service = MagicMock()\n mock_service.is_allowed.return_value = False\n mock_get_restriction.return_value = mock_service\n\n with pytest.raises(ValueError, match=\"not allowed by restriction policy\"):\n provider.get_capabilities(\"o3\")\n\n @patch.dict(os.environ, {\"DIAL_ALLOWED_MODELS\": \"\"}, clear=False)\n @patch(\"utils.model_restrictions._restriction_service\", None)\n def test_supports_vision(self):\n \"\"\"Test vision support detection through model capabilities.\"\"\"\n provider = DIALModelProvider(\"test-key\")\n\n assert provider.get_capabilities(\"o3-2025-04-16\").supports_images is True\n assert provider.get_capabilities(\"o3\").supports_images is True # Via resolution\n assert provider.get_capabilities(\"anthropic.claude-opus-4.1-20250805-v1:0\").supports_images is True\n assert provider.get_capabilities(\"gemini-2.5-pro-preview-05-06\").supports_images is True\n\n with pytest.raises(ValueError):\n provider.get_capabilities(\"unknown-model\")\n\n @patch(\"openai.OpenAI\") # Mock the OpenAI class directly from openai module\n def test_generate_content_with_alias(self, mock_openai_class):\n \"\"\"Test that generate_content properly resolves aliases and uses deployment routing.\"\"\"\n # Create mock client\n mock_client = MagicMock()\n mock_response = MagicMock()\n mock_response.choices = [MagicMock(message=MagicMock(content=\"Test response\"))]\n mock_response.usage = MagicMock(prompt_tokens=10, completion_tokens=20, total_tokens=30)\n mock_response.model = \"gpt-4\"\n mock_response.id = \"test-id\"\n mock_response.created = 1234567890\n mock_response.choices[0].finish_reason = \"stop\"\n\n mock_client.chat.completions.create.return_value = mock_response\n mock_openai_class.return_value = mock_client\n\n provider = DIALModelProvider(\"test-key\")\n\n # Generate content with shorthand\n response = provider.generate_content(prompt=\"Test prompt\", model_name=\"o3\", temperature=0.7) # Shorthand\n\n # Verify OpenAI was instantiated with deployment-specific URL\n mock_openai_class.assert_called_once()\n call_args = mock_openai_class.call_args\n assert \"/deployments/o3-2025-04-16\" in call_args[1][\"base_url\"]\n\n # Verify the resolved model name was passed to the API\n mock_client.chat.completions.create.assert_called_once()\n create_call_args = mock_client.chat.completions.create.call_args\n assert create_call_args[1][\"model\"] == \"o3-2025-04-16\" # Resolved name\n\n # Verify response\n assert response.content == \"Test response\"\n assert response.model_name == \"o3\" # Original name preserved\n assert response.metadata[\"model\"] == \"gpt-4\" # API returned model name from mock\n\n def test_provider_type(self):\n \"\"\"Test provider type identification.\"\"\"\n provider = DIALModelProvider(\"test-key\")\n assert provider.get_provider_type() == ProviderType.DIAL\n\n def test_friendly_name(self):\n \"\"\"Test provider friendly name.\"\"\"\n provider = DIALModelProvider(\"test-key\")\n assert provider.FRIENDLY_NAME == \"DIAL\"\n\n @patch.dict(os.environ, {\"DIAL_API_VERSION\": \"2024-12-01\"})\n def test_configurable_api_version(self):\n \"\"\"Test that API version can be configured via environment variable.\"\"\"\n provider = DIALModelProvider(\"test-key\")\n # Check that the custom API version is stored\n assert provider.api_version == \"2024-12-01\"\n\n def test_default_api_version(self):\n \"\"\"Test that default API version is used when not configured.\"\"\"\n # Clear any existing DIAL_API_VERSION from environment\n with patch.dict(os.environ, {}, clear=True):\n # Keep other env vars but ensure DIAL_API_VERSION is not set\n if \"DIAL_API_VERSION\" in os.environ:\n del os.environ[\"DIAL_API_VERSION\"]\n\n provider = DIALModelProvider(\"test-key\")\n # Check that the default API version is used\n assert provider.api_version == \"2024-12-01-preview\"\n # Check that Api-Key header is set\n assert provider.DEFAULT_HEADERS[\"Api-Key\"] == \"test-key\"\n\n @patch.dict(os.environ, {\"DIAL_ALLOWED_MODELS\": \"o3-2025-04-16,anthropic.claude-opus-4.1-20250805-v1:0\"})\n @patch(\"utils.model_restrictions._restriction_service\", None)\n def test_allowed_models_restriction(self):\n \"\"\"Test model allow-list functionality.\"\"\"\n provider = DIALModelProvider(\"test-key\")\n\n # These should be allowed\n assert provider.validate_model_name(\"o3-2025-04-16\") is True\n assert provider.validate_model_name(\"o3\") is True # Alias for o3-2025-04-16\n assert provider.validate_model_name(\"anthropic.claude-opus-4.1-20250805-v1:0\") is True\n assert provider.validate_model_name(\"opus-4.1\") is True # Resolves to anthropic.claude-opus-4.1-20250805-v1:0\n\n # These should be blocked\n assert provider.validate_model_name(\"gemini-2.5-pro-preview-05-06\") is False\n assert provider.validate_model_name(\"o4-mini-2025-04-16\") is False\n assert provider.validate_model_name(\"sonnet-4.1\") is False # sonnet-4.1 is not in allowed list\n\n @patch(\"httpx.Client\")\n @patch(\"openai.OpenAI\")\n def test_close_method(self, mock_openai_class, mock_httpx_client_class):\n \"\"\"Test that the close method properly closes HTTP clients.\"\"\"\n # Mock the httpx.Client instance that DIALModelProvider will create\n mock_shared_http_client = MagicMock()\n mock_httpx_client_class.return_value = mock_shared_http_client\n\n # Mock the OpenAI client instances\n mock_openai_client_1 = MagicMock()\n mock_openai_client_2 = MagicMock()\n # Configure side_effect to return different mocks for subsequent calls\n mock_openai_class.side_effect = [mock_openai_client_1, mock_openai_client_2]\n\n provider = DIALModelProvider(\"test-key\")\n\n # Mock the superclass's _client attribute directly\n mock_superclass_client = MagicMock()\n provider._client = mock_superclass_client\n\n # Simulate getting clients for two different deployments to populate _deployment_clients\n provider._get_deployment_client(\"model_a\")\n provider._get_deployment_client(\"model_b\")\n\n # Now call close\n provider.close()\n\n # Assert that the shared httpx client's close method was called\n mock_shared_http_client.close.assert_called_once()\n\n # Assert that the superclass client's close method was called\n mock_superclass_client.close.assert_called_once()\n\n # Assert that the deployment clients cache is cleared\n assert not provider._deployment_clients\n" }, { "path": "tests/test_directory_expansion_tracking.py", "content": "\"\"\"\nTest for directory expansion tracking in conversation memory\n\nThis test ensures that when directories are provided to tools, the individual\nexpanded files are properly tracked in conversation history rather than just\nthe directory paths. This prevents file filtering bugs in conversation\ncontinuations.\n\"\"\"\n\nfrom pathlib import Path\nfrom unittest.mock import Mock, patch\n\nimport pytest\n\nfrom tests.mock_helpers import create_mock_provider\nfrom tools.chat import ChatTool\nfrom tools.models import ToolOutput\nfrom utils.conversation_memory import add_turn, create_thread\n\n\nclass TestDirectoryExpansionTracking:\n \"\"\"Test directory expansion tracking in conversation memory\"\"\"\n\n @pytest.fixture\n def tool(self):\n return ChatTool()\n\n @pytest.fixture\n def temp_directory_with_files(self, project_path):\n \"\"\"Create a temporary directory with multiple files\"\"\"\n # Create within the project path to avoid security restrictions\n temp_dir = project_path / \"test_temp_dir\"\n temp_dir.mkdir(exist_ok=True)\n temp_path = temp_dir\n\n # Create multiple Swift files (simulating the original bug scenario)\n files = []\n for i in range(5):\n swift_file = temp_path / f\"File{i}.swift\"\n swift_file.write_text(\n f\"\"\"\nimport Foundation\n\nclass TestClass{i} {{\n func testMethod{i}() -> String {{\n return \"test{i}\"\n }}\n}}\n\"\"\"\n )\n files.append(str(swift_file))\n\n # Create a Python file as well\n python_file = temp_path / \"helper.py\"\n python_file.write_text(\n \"\"\"\ndef helper_function():\n return \"helper\"\n\"\"\"\n )\n files.append(str(python_file))\n\n try:\n yield {\n \"directory\": str(temp_dir),\n \"absolute_file_paths\": files,\n \"swift_files\": files[:-1], # All but the Python file\n \"python_file\": str(python_file),\n }\n finally:\n # Cleanup\n import shutil\n\n shutil.rmtree(temp_dir, ignore_errors=True)\n\n @pytest.mark.asyncio\n @patch(\"providers.ModelProviderRegistry.get_provider_for_model\")\n async def test_directory_expansion_tracked_in_conversation_memory(\n self, mock_get_provider, tool, temp_directory_with_files\n ):\n \"\"\"Test that directory expansion is properly tracked in conversation memory\"\"\"\n # Setup mock provider\n mock_provider = create_mock_provider()\n mock_get_provider.return_value = mock_provider\n\n directory = temp_directory_with_files[\"directory\"]\n expected_files = temp_directory_with_files[\"absolute_file_paths\"]\n\n # Create a request with the directory (not individual files)\n request_args = {\n \"prompt\": \"Analyze this codebase structure\",\n \"absolute_file_paths\": [directory], # Directory path, not individual files\n \"model\": \"flash\",\n \"working_directory_absolute_path\": directory,\n }\n\n # Execute the tool\n result = await tool.execute(request_args)\n\n # Verify the tool executed successfully\n assert result is not None\n result_data = result[0].text\n tool_output = ToolOutput.model_validate_json(result_data)\n assert tool_output.status in [\"success\", \"continuation_available\"]\n\n # Verify that the actually processed files were the expanded individual files\n captured_files = getattr(tool, \"_actually_processed_files\", [])\n assert captured_files is not None\n assert len(captured_files) == len(expected_files)\n\n # Convert to sets for comparison (order might differ)\n # Normalize paths to handle /private prefix differences\n captured_set = {str(Path(f).resolve()) for f in captured_files}\n expected_set = {str(Path(f).resolve()) for f in expected_files}\n assert captured_set == expected_set\n\n # Verify that the directory was expanded to individual files\n assert directory not in captured_files # Directory itself should not be in the list\n for expected_file in expected_files:\n # Normalize path for comparison\n expected_resolved = str(Path(expected_file).resolve())\n assert any(str(Path(f).resolve()) == expected_resolved for f in captured_files)\n\n @pytest.mark.asyncio\n @patch(\"utils.conversation_memory.get_storage\")\n @patch(\"providers.ModelProviderRegistry.get_provider_for_model\")\n async def test_conversation_continuation_with_directory_files(\n self, mock_get_provider, mock_storage, tool, temp_directory_with_files\n ):\n \"\"\"Test that conversation continuation works correctly with directory expansion\"\"\"\n # Setup mock Redis client with in-memory storage\n mock_client = Mock()\n redis_storage = {} # Simulate Redis storage\n\n def mock_get(key):\n return redis_storage.get(key)\n\n def mock_setex(key, ttl, value):\n redis_storage[key] = value\n return True\n\n mock_client.get.side_effect = mock_get\n mock_client.setex.side_effect = mock_setex\n mock_storage.return_value = mock_client\n\n # Setup mock provider\n mock_provider = create_mock_provider()\n mock_get_provider.return_value = mock_provider\n\n directory = temp_directory_with_files[\"directory\"]\n expected_files = temp_directory_with_files[\"absolute_file_paths\"]\n\n # Step 1: Create a conversation thread manually with the expanded files\n thread_id = create_thread(\"chat\", {\"prompt\": \"Initial analysis\", \"absolute_file_paths\": [directory]})\n\n # Add a turn with the expanded files (simulating what the fix should do)\n success = add_turn(\n thread_id,\n \"assistant\",\n \"I've analyzed the codebase structure.\",\n files=expected_files, # Individual expanded files, not directory\n tool_name=\"chat\",\n )\n assert success is True\n\n # Step 2: Continue the conversation with the same directory\n continuation_args = {\n \"prompt\": \"Now focus on the Swift files specifically\",\n \"absolute_file_paths\": [directory], # Same directory again\n \"model\": \"flash\",\n \"continuation_id\": thread_id,\n \"working_directory_absolute_path\": directory,\n }\n\n # Mock to capture file filtering behavior\n original_filter_new_files = tool.filter_new_files\n filtered_files = None\n\n def capture_filtering_mock(requested_files, continuation_id):\n nonlocal filtered_files\n filtered_files = original_filter_new_files(requested_files, continuation_id)\n return filtered_files\n\n with patch.object(tool, \"filter_new_files\", side_effect=capture_filtering_mock):\n # Execute continuation - this should not re-embed the same files\n result = await tool.execute(continuation_args)\n\n # Verify the tool executed successfully\n assert result is not None\n result_data = result[0].text\n tool_output = ToolOutput.model_validate_json(result_data)\n assert tool_output.status in [\"success\", \"continuation_available\"]\n\n # Verify that file filtering worked correctly\n # The directory might still be included if it contains files not yet embedded,\n # but the key point is that we don't re-embed already processed individual files\n assert filtered_files is not None\n # This test shows the fix is working - conversation continuation properly filters out\n # already-embedded files. The exact length depends on whether any new files are found.\n\n @patch(\"utils.conversation_memory.get_storage\")\n def test_get_conversation_embedded_files_with_expanded_files(self, mock_storage, tool, temp_directory_with_files):\n \"\"\"Test that get_conversation_embedded_files returns expanded files\"\"\"\n # Setup mock Redis client with in-memory storage\n mock_client = Mock()\n redis_storage = {} # Simulate Redis storage\n\n def mock_get(key):\n return redis_storage.get(key)\n\n def mock_setex(key, ttl, value):\n redis_storage[key] = value\n return True\n\n mock_client.get.side_effect = mock_get\n mock_client.setex.side_effect = mock_setex\n mock_storage.return_value = mock_client\n\n directory = temp_directory_with_files[\"directory\"]\n expected_files = temp_directory_with_files[\"absolute_file_paths\"]\n\n # Create a thread with expanded files\n thread_id = create_thread(\"chat\", {\"prompt\": \"Initial analysis\", \"absolute_file_paths\": [directory]})\n\n # Add a turn with expanded files\n success = add_turn(\n thread_id,\n \"assistant\",\n \"Analysis complete.\",\n files=expected_files, # Individual files\n tool_name=\"chat\",\n )\n assert success is True\n\n # Get the embedded files from conversation\n embedded_files = tool.get_conversation_embedded_files(thread_id)\n\n # Verify that we get the individual files, not the directory\n assert set(embedded_files) == set(expected_files)\n assert directory not in embedded_files\n\n @patch(\"utils.conversation_memory.get_storage\")\n def test_file_filtering_with_mixed_files_and_directories(self, mock_storage, tool, temp_directory_with_files):\n \"\"\"Test file filtering when request contains both individual files and directories\"\"\"\n # Setup mock Redis client with in-memory storage\n mock_client = Mock()\n redis_storage = {} # Simulate Redis storage\n\n def mock_get(key):\n return redis_storage.get(key)\n\n def mock_setex(key, ttl, value):\n redis_storage[key] = value\n return True\n\n mock_client.get.side_effect = mock_get\n mock_client.setex.side_effect = mock_setex\n mock_storage.return_value = mock_client\n\n directory = temp_directory_with_files[\"directory\"]\n python_file = temp_directory_with_files[\"python_file\"]\n\n # Create a thread with some expanded files\n thread_id = create_thread(\"chat\", {\"prompt\": \"Initial analysis\", \"absolute_file_paths\": [directory]})\n\n # Add a turn with only some of the files (simulate partial embedding)\n swift_files = temp_directory_with_files[\"swift_files\"]\n success = add_turn(\n thread_id,\n \"assistant\",\n \"Swift analysis complete.\",\n files=swift_files, # Only Swift files\n tool_name=\"chat\",\n )\n assert success is True\n\n # Request with both directory and individual file\n mixed_request = [directory, python_file]\n filtered_files = tool.filter_new_files(mixed_request, thread_id)\n\n # The directory should expand to individual files, and since Swift files\n # are already embedded, only the python file should be new\n # Note: the filter_new_files method handles directory expansion internally\n assert python_file in filtered_files\n # The directory itself might be in the filtered list if it expands to new files\n # In this case, since we only embedded Swift files, the directory might still be included\n\n @pytest.mark.asyncio\n @patch(\"providers.ModelProviderRegistry.get_provider_for_model\")\n async def test_actually_processed_files_stored_correctly(self, mock_get_provider, tool, temp_directory_with_files):\n \"\"\"Test that _actually_processed_files is stored correctly after file processing\"\"\"\n # Setup mock provider\n mock_provider = create_mock_provider()\n mock_get_provider.return_value = mock_provider\n\n directory = temp_directory_with_files[\"directory\"]\n expected_files = temp_directory_with_files[\"absolute_file_paths\"]\n\n # Execute the tool\n request_args = {\n \"prompt\": \"Analyze this code\",\n \"absolute_file_paths\": [directory],\n \"model\": \"flash\",\n \"working_directory_absolute_path\": directory,\n }\n\n result = await tool.execute(request_args)\n\n # Verify the tool executed successfully\n assert result is not None\n\n # Verify that _actually_processed_files was set correctly\n assert hasattr(tool, \"_actually_processed_files\")\n actually_processed = tool._actually_processed_files\n\n # Should contain individual files, not the directory\n # Normalize paths to handle /private prefix differences\n processed_set = {str(Path(f).resolve()) for f in actually_processed}\n expected_set = {str(Path(f).resolve()) for f in expected_files}\n assert processed_set == expected_set\n assert directory not in actually_processed\n\n\nif __name__ == \"__main__\":\n pytest.main([__file__])\n" }, { "path": "tests/test_disabled_tools.py", "content": "\"\"\"Tests for DISABLED_TOOLS environment variable functionality.\"\"\"\n\nimport logging\nimport os\nfrom unittest.mock import patch\n\nimport pytest\n\nfrom server import (\n apply_tool_filter,\n parse_disabled_tools_env,\n validate_disabled_tools,\n)\n\n\n# Mock the tool classes since we're testing the filtering logic\nclass MockTool:\n def __init__(self, name):\n self.name = name\n\n\nclass TestDisabledTools:\n \"\"\"Test suite for DISABLED_TOOLS functionality.\"\"\"\n\n def test_parse_disabled_tools_empty(self):\n \"\"\"Empty string returns empty set (no tools disabled).\"\"\"\n with patch.dict(os.environ, {\"DISABLED_TOOLS\": \"\"}):\n assert parse_disabled_tools_env() == set()\n\n def test_parse_disabled_tools_not_set(self):\n \"\"\"Unset variable returns empty set.\"\"\"\n with patch.dict(os.environ, {}, clear=True):\n # Ensure DISABLED_TOOLS is not in environment\n if \"DISABLED_TOOLS\" in os.environ:\n del os.environ[\"DISABLED_TOOLS\"]\n assert parse_disabled_tools_env() == set()\n\n def test_parse_disabled_tools_single(self):\n \"\"\"Single tool name parsed correctly.\"\"\"\n with patch.dict(os.environ, {\"DISABLED_TOOLS\": \"debug\"}):\n assert parse_disabled_tools_env() == {\"debug\"}\n\n def test_parse_disabled_tools_multiple(self):\n \"\"\"Multiple tools with spaces parsed correctly.\"\"\"\n with patch.dict(os.environ, {\"DISABLED_TOOLS\": \"debug, analyze, refactor\"}):\n assert parse_disabled_tools_env() == {\"debug\", \"analyze\", \"refactor\"}\n\n def test_parse_disabled_tools_extra_spaces(self):\n \"\"\"Extra spaces and empty items handled correctly.\"\"\"\n with patch.dict(os.environ, {\"DISABLED_TOOLS\": \" debug , , analyze , \"}):\n assert parse_disabled_tools_env() == {\"debug\", \"analyze\"}\n\n def test_parse_disabled_tools_duplicates(self):\n \"\"\"Duplicate entries handled correctly (set removes duplicates).\"\"\"\n with patch.dict(os.environ, {\"DISABLED_TOOLS\": \"debug,analyze,debug\"}):\n assert parse_disabled_tools_env() == {\"debug\", \"analyze\"}\n\n def test_tool_filtering_logic(self):\n \"\"\"Test the complete filtering logic using the actual server functions.\"\"\"\n # Simulate ALL_TOOLS\n ALL_TOOLS = {\n \"chat\": MockTool(\"chat\"),\n \"debug\": MockTool(\"debug\"),\n \"analyze\": MockTool(\"analyze\"),\n \"version\": MockTool(\"version\"),\n \"listmodels\": MockTool(\"listmodels\"),\n }\n\n # Test case 1: No tools disabled\n disabled_tools = set()\n enabled_tools = apply_tool_filter(ALL_TOOLS, disabled_tools)\n\n assert len(enabled_tools) == 5 # All tools included\n assert set(enabled_tools.keys()) == set(ALL_TOOLS.keys())\n\n # Test case 2: Disable some regular tools\n disabled_tools = {\"debug\", \"analyze\"}\n enabled_tools = apply_tool_filter(ALL_TOOLS, disabled_tools)\n\n assert len(enabled_tools) == 3 # chat, version, listmodels\n assert \"debug\" not in enabled_tools\n assert \"analyze\" not in enabled_tools\n assert \"chat\" in enabled_tools\n assert \"version\" in enabled_tools\n assert \"listmodels\" in enabled_tools\n\n # Test case 3: Attempt to disable essential tools\n disabled_tools = {\"version\", \"chat\"}\n enabled_tools = apply_tool_filter(ALL_TOOLS, disabled_tools)\n\n assert \"version\" in enabled_tools # Essential tool not disabled\n assert \"chat\" not in enabled_tools # Regular tool disabled\n assert \"listmodels\" in enabled_tools # Essential tool included\n\n def test_unknown_tools_warning(self, caplog):\n \"\"\"Test that unknown tool names generate appropriate warnings.\"\"\"\n ALL_TOOLS = {\n \"chat\": MockTool(\"chat\"),\n \"debug\": MockTool(\"debug\"),\n \"analyze\": MockTool(\"analyze\"),\n \"version\": MockTool(\"version\"),\n \"listmodels\": MockTool(\"listmodels\"),\n }\n disabled_tools = {\"chat\", \"unknown_tool\", \"another_unknown\"}\n\n with caplog.at_level(logging.WARNING):\n validate_disabled_tools(disabled_tools, ALL_TOOLS)\n assert \"Unknown tools in DISABLED_TOOLS: ['another_unknown', 'unknown_tool']\" in caplog.text\n\n def test_essential_tools_warning(self, caplog):\n \"\"\"Test warning when trying to disable essential tools.\"\"\"\n ALL_TOOLS = {\n \"chat\": MockTool(\"chat\"),\n \"debug\": MockTool(\"debug\"),\n \"analyze\": MockTool(\"analyze\"),\n \"version\": MockTool(\"version\"),\n \"listmodels\": MockTool(\"listmodels\"),\n }\n disabled_tools = {\"version\", \"chat\", \"debug\"}\n\n with caplog.at_level(logging.WARNING):\n validate_disabled_tools(disabled_tools, ALL_TOOLS)\n assert \"Cannot disable essential tools: ['version']\" in caplog.text\n\n @pytest.mark.parametrize(\n \"env_value,expected\",\n [\n (\"\", set()), # Empty string\n (\" \", set()), # Only spaces\n (\",,,\", set()), # Only commas\n (\"chat\", {\"chat\"}), # Single tool\n (\"chat,debug\", {\"chat\", \"debug\"}), # Multiple tools\n (\"chat, debug, analyze\", {\"chat\", \"debug\", \"analyze\"}), # With spaces\n (\"chat,debug,chat\", {\"chat\", \"debug\"}), # Duplicates\n ],\n )\n def test_parse_disabled_tools_parametrized(self, env_value, expected):\n \"\"\"Parametrized tests for various input formats.\"\"\"\n with patch.dict(os.environ, {\"DISABLED_TOOLS\": env_value}):\n assert parse_disabled_tools_env() == expected\n" }, { "path": "tests/test_docker_claude_desktop_integration.py", "content": "\"\"\"\nTests for Docker integration with Claude Desktop MCP\n\"\"\"\n\nimport json\nimport os\nimport tempfile\nfrom pathlib import Path\n\nimport pytest\n\n\nclass TestDockerClaudeDesktopIntegration:\n \"\"\"Test Docker integration with Claude Desktop\"\"\"\n\n @pytest.fixture(autouse=True)\n def setup(self):\n \"\"\"Setup for each test\"\"\"\n self.project_root = Path(__file__).parent.parent\n\n def test_mcp_config_docker_run_format(self):\n \"\"\"Test MCP configuration for direct docker run\"\"\"\n config = {\n \"mcpServers\": {\n \"pal-mcp\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"--env-file\",\n \"/path/to/.env\",\n \"-v\",\n \"/path/to/logs:/app/logs\",\n \"pal-mcp-server:latest\",\n ],\n }\n }\n }\n\n # Validate configuration structure\n assert \"mcpServers\" in config\n assert \"pal-mcp\" in config[\"mcpServers\"]\n assert config[\"mcpServers\"][\"pal-mcp\"][\"command\"] == \"docker\"\n\n args = config[\"mcpServers\"][\"pal-mcp\"][\"args\"]\n assert \"run\" in args\n assert \"--rm\" in args\n assert \"-i\" in args\n assert \"--env-file\" in args\n\n def test_mcp_config_docker_compose_format(self):\n \"\"\"Test MCP configuration for docker-compose run\"\"\"\n config = {\n \"mcpServers\": {\n \"pal-mcp\": {\n \"command\": \"docker-compose\",\n \"args\": [\"-f\", \"/path/to/docker-compose.yml\", \"run\", \"--rm\", \"pal-mcp\"],\n }\n }\n }\n\n # Validate configuration structure\n assert config[\"mcpServers\"][\"pal-mcp\"][\"command\"] == \"docker-compose\"\n\n args = config[\"mcpServers\"][\"pal-mcp\"][\"args\"]\n assert \"-f\" in args\n assert \"run\" in args\n assert \"--rm\" in args\n assert \"pal-mcp\" in args\n\n def test_mcp_config_environment_variables(self):\n \"\"\"Test MCP configuration with inline environment variables\"\"\"\n config = {\n \"mcpServers\": {\n \"pal-mcp\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"-e\",\n \"GEMINI_API_KEY=test_key\",\n \"-e\",\n \"LOG_LEVEL=INFO\",\n \"pal-mcp-server:latest\",\n ],\n }\n }\n }\n\n args = config[\"mcpServers\"][\"pal-mcp\"][\"args\"]\n\n # Check that environment variables are properly formatted\n env_args = [arg for arg in args if arg.startswith(\"-e\")]\n assert len(env_args) > 0, \"Environment variables should be present\"\n\n # Check for API key environment variable\n api_key_present = any(\"GEMINI_API_KEY=\" in args[i + 1] for i, arg in enumerate(args[:-1]) if arg == \"-e\")\n assert api_key_present, \"API key environment variable should be set\"\n\n def test_windows_path_format(self):\n \"\"\"Test Windows-specific path formatting\"\"\"\n windows_config = {\n \"mcpServers\": {\n \"pal-mcp\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"--env-file\",\n \"C:/Users/User/pal-mcp-server/.env\",\n \"-v\",\n \"C:/Users/User/pal-mcp-server/logs:/app/logs\",\n \"pal-mcp-server:latest\",\n ],\n }\n }\n }\n\n args = windows_config[\"mcpServers\"][\"pal-mcp\"][\"args\"]\n\n # Check Windows path format\n windows_paths = [arg for arg in args if arg.startswith(\"C:/\")]\n assert len(windows_paths) > 0, \"Windows paths should use forward slashes\"\n\n for path in windows_paths:\n assert \"\\\\\" not in path, \"Windows paths should use forward slashes\"\n\n def test_mcp_config_validation(self):\n \"\"\"Test validation of MCP configuration\"\"\"\n # Valid configuration\n valid_config = {\n \"mcpServers\": {\"pal-mcp\": {\"command\": \"docker\", \"args\": [\"run\", \"--rm\", \"-i\", \"pal-mcp-server:latest\"]}}\n }\n\n # Validate JSON serialization\n config_json = json.dumps(valid_config)\n loaded_config = json.loads(config_json)\n assert loaded_config == valid_config\n\n def test_mcp_stdio_communication(self):\n \"\"\"Test that MCP configuration supports stdio communication\"\"\"\n config = {\n \"mcpServers\": {\n \"pal-mcp\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\", # Interactive mode for stdio\n \"pal-mcp-server:latest\",\n ],\n }\n }\n }\n\n args = config[\"mcpServers\"][\"pal-mcp\"][\"args\"]\n\n # Check for interactive mode\n assert \"-i\" in args, \"Interactive mode required for stdio communication\"\n\n # Should not expose network ports for stdio communication\n port_args = [arg for arg in args if arg.startswith(\"-p\")]\n assert len(port_args) == 0, \"No ports should be exposed for stdio mode\"\n\n def test_docker_image_reference(self):\n \"\"\"Test that Docker image is properly referenced\"\"\"\n configs = [\n {\"image\": \"pal-mcp-server:latest\"},\n {\"image\": \"pal-mcp-server:v1.0.0\"},\n {\"image\": \"registry/pal-mcp-server:latest\"},\n ]\n\n for config in configs:\n image = config[\"image\"]\n\n # Basic image format validation\n assert \":\" in image, \"Image should have a tag\"\n assert len(image.split(\":\")) == 2, \"Image should have exactly one tag\"\n\n @pytest.fixture\n def temp_mcp_config(self):\n \"\"\"Create temporary MCP configuration file\"\"\"\n config = {\n \"mcpServers\": {\n \"pal-mcp\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"--env-file\", \"/tmp/.env\", \"pal-mcp-server:latest\"],\n }\n }\n }\n\n with tempfile.NamedTemporaryFile(mode=\"w\", suffix=\".json\", delete=False, encoding=\"utf-8\") as f:\n json.dump(config, f, indent=2)\n temp_file_path = f.name\n\n yield temp_file_path\n os.unlink(temp_file_path)\n\n def test_mcp_config_file_parsing(self, temp_mcp_config):\n \"\"\"Test parsing of MCP configuration file\"\"\"\n # Read and parse the temporary config file\n with open(temp_mcp_config, encoding=\"utf-8\") as f:\n config = json.load(f)\n\n assert \"mcpServers\" in config\n assert \"pal-mcp\" in config[\"mcpServers\"]\n\n def test_environment_file_integration(self):\n \"\"\"Test integration with .env file\"\"\"\n # Test .env file format expected by Docker\n env_content = \"\"\"GEMINI_API_KEY=test_key\nOPENAI_API_KEY=test_key_2\nLOG_LEVEL=INFO\nDEFAULT_MODEL=auto\n\"\"\"\n\n # Parse environment content\n env_vars = {}\n for line in env_content.strip().split(\"\\n\"):\n if \"=\" in line and not line.startswith(\"#\"):\n key, value = line.split(\"=\", 1)\n env_vars[key] = value\n\n # Validate required environment variables\n assert \"GEMINI_API_KEY\" in env_vars\n assert len(env_vars[\"GEMINI_API_KEY\"]) > 0\n\n def test_docker_volume_mount_paths(self):\n \"\"\"Test Docker volume mount path configurations\"\"\"\n mount_configs = [\n {\"host\": \"./logs\", \"container\": \"/app/logs\"},\n {\"host\": \"/absolute/path/logs\", \"container\": \"/app/logs\"},\n {\"host\": \"C:/Windows/path/logs\", \"container\": \"/app/logs\"},\n ]\n\n for config in mount_configs:\n mount_arg = f\"{config['host']}:{config['container']}\"\n\n # Validate mount format\n assert \":\" in mount_arg\n parts = mount_arg.split(\":\")\n assert len(parts) >= 2\n assert parts[-1].startswith(\"/\"), \"Container path should be absolute\"\n\n\nclass TestDockerMCPErrorHandling:\n \"\"\"Test error handling for Docker MCP integration\"\"\"\n\n def test_missing_docker_image_handling(self):\n \"\"\"Test handling of missing Docker image\"\"\"\n # This would test what happens when the image doesn't exist\n # In practice, Claude Desktop would show an error\n nonexistent_config = {\n \"mcpServers\": {\"pal-mcp\": {\"command\": \"docker\", \"args\": [\"run\", \"--rm\", \"-i\", \"nonexistent:latest\"]}}\n }\n\n # Configuration should be valid even if image doesn't exist\n assert \"pal-mcp\" in nonexistent_config[\"mcpServers\"]\n\n def test_invalid_env_file_path(self):\n \"\"\"Test handling of invalid .env file path\"\"\"\n config_with_invalid_env = {\n \"mcpServers\": {\n \"pal-mcp\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"--env-file\", \"/nonexistent/.env\", \"pal-mcp-server:latest\"],\n }\n }\n }\n\n # Configuration structure should still be valid\n args = config_with_invalid_env[\"mcpServers\"][\"pal-mcp\"][\"args\"]\n assert \"--env-file\" in args\n\n def test_docker_permission_issues(self):\n \"\"\"Test configuration for potential Docker permission issues\"\"\"\n # On some systems, Docker requires specific permissions\n # The configuration should work with both cases\n\n configs = [\n # Regular Docker command\n {\"command\": \"docker\"},\n # Sudo Docker command (if needed)\n {\"command\": \"sudo\", \"extra_args\": [\"docker\"]},\n ]\n\n for config in configs:\n assert len(config[\"command\"]) > 0\n\n def test_resource_limit_configurations(self):\n \"\"\"Test Docker resource limit configurations\"\"\"\n config_with_limits = {\n \"mcpServers\": {\n \"pal-mcp\": {\n \"command\": \"docker\",\n \"args\": [\"run\", \"--rm\", \"-i\", \"--memory=512m\", \"--cpus=1.0\", \"pal-mcp-server:latest\"],\n }\n }\n }\n\n args = config_with_limits[\"mcpServers\"][\"pal-mcp\"][\"args\"]\n\n # Check for resource limits\n memory_limit = any(\"--memory\" in arg for arg in args)\n cpu_limit = any(\"--cpus\" in arg for arg in args)\n\n assert memory_limit or cpu_limit, \"Resource limits should be configurable\"\n" }, { "path": "tests/test_docker_config_complete.py", "content": "\"\"\"\nComplete configuration test for Docker MCP\n\"\"\"\n\nimport os\nfrom pathlib import Path\nfrom unittest.mock import patch\n\nimport pytest\n\n\nclass TestDockerMCPConfiguration:\n \"\"\"Docker MCP configuration tests\"\"\"\n\n def test_dockerfile_configuration(self):\n \"\"\"Test Dockerfile configuration\"\"\"\n project_root = Path(__file__).parent.parent\n dockerfile = project_root / \"Dockerfile\"\n\n if not dockerfile.exists():\n pytest.skip(\"Dockerfile not found\")\n\n content = dockerfile.read_text()\n\n # Essential checks\n assert \"FROM python:\" in content\n assert \"COPY\" in content or \"ADD\" in content\n assert \"server.py\" in content\n\n # Recommended security checks\n security_checks = [\n \"USER \" in content, # Non-root user\n \"WORKDIR\" in content, # Defined working directory\n ]\n\n # At least one security practice should be present\n if any(security_checks):\n assert True, \"Security best practices detected\"\n\n def test_environment_file_template(self):\n \"\"\"Test environment file template\"\"\"\n project_root = Path(__file__).parent.parent\n env_example = project_root / \".env.example\"\n\n if env_example.exists():\n content = env_example.read_text()\n\n # Essential variables\n essential_vars = [\"GEMINI_API_KEY\", \"OPENAI_API_KEY\", \"LOG_LEVEL\"]\n\n for var in essential_vars:\n assert f\"{var}=\" in content, f\"Variable {var} missing\"\n\n # Docker-specific variables should also be present\n docker_vars = [\"COMPOSE_PROJECT_NAME\", \"TZ\", \"LOG_MAX_SIZE\"]\n for var in docker_vars:\n assert f\"{var}=\" in content, f\"Docker variable {var} missing\"\n\n def test_logs_directory_setup(self):\n \"\"\"Test logs directory setup\"\"\"\n project_root = Path(__file__).parent.parent\n logs_dir = project_root / \"logs\"\n\n # The logs directory should exist or be creatable\n if not logs_dir.exists():\n try:\n logs_dir.mkdir(exist_ok=True)\n created = True\n except Exception:\n created = False\n\n assert created, \"Logs directory should be creatable\"\n else:\n assert logs_dir.is_dir(), \"logs should be a directory\"\n\n\nclass TestDockerCommandValidation:\n \"\"\"Docker command validation tests\"\"\"\n\n @patch(\"subprocess.run\")\n def test_docker_build_command(self, mock_run):\n \"\"\"Test docker build command\"\"\"\n mock_run.return_value.returncode = 0\n\n # Standard build command\n build_cmd = [\"docker\", \"build\", \"-t\", \"pal-mcp-server:latest\", \".\"]\n\n import subprocess\n\n subprocess.run(build_cmd, capture_output=True)\n mock_run.assert_called_once()\n\n @patch(\"subprocess.run\")\n def test_docker_run_mcp_command(self, mock_run):\n \"\"\"Test docker run command for MCP\"\"\"\n mock_run.return_value.returncode = 0\n\n # Run command for MCP\n run_cmd = [\n \"docker\",\n \"run\",\n \"--rm\",\n \"-i\",\n \"--env-file\",\n \".env\",\n \"-v\",\n \"logs:/app/logs\",\n \"pal-mcp-server:latest\",\n \"python\",\n \"server.py\",\n ]\n\n import subprocess\n\n subprocess.run(run_cmd, capture_output=True)\n mock_run.assert_called_once()\n\n def test_docker_command_structure(self):\n \"\"\"Test Docker command structure\"\"\"\n\n # Recommended MCP command\n mcp_cmd = [\n \"docker\",\n \"run\",\n \"--rm\",\n \"-i\",\n \"--env-file\",\n \"/path/to/.env\",\n \"-v\",\n \"/path/to/logs:/app/logs\",\n \"pal-mcp-server:latest\",\n \"python\",\n \"server.py\",\n ]\n\n # Structure checks\n assert mcp_cmd[0] == \"docker\"\n assert \"run\" in mcp_cmd\n assert \"--rm\" in mcp_cmd # Automatic cleanup\n assert \"-i\" in mcp_cmd # Interactive mode\n assert \"--env-file\" in mcp_cmd # Environment variables\n assert \"pal-mcp-server:latest\" in mcp_cmd # Image\n\n\nclass TestIntegrationChecks:\n \"\"\"Integration checks\"\"\"\n\n def test_complete_setup_checklist(self):\n \"\"\"Test complete setup checklist\"\"\"\n project_root = Path(__file__).parent.parent\n\n # Checklist for essential files\n essential_files = {\n \"Dockerfile\": project_root / \"Dockerfile\",\n \"server.py\": project_root / \"server.py\",\n \"requirements.txt\": project_root / \"requirements.txt\",\n \"docker-compose.yml\": project_root / \"docker-compose.yml\",\n }\n\n missing_files = []\n for name, path in essential_files.items():\n if not path.exists():\n missing_files.append(name)\n\n # Allow some missing files for flexibility\n critical_files = [\"Dockerfile\", \"server.py\"]\n missing_critical = [f for f in missing_files if f in critical_files]\n\n assert not missing_critical, f\"Critical files missing: {missing_critical}\"\n\n def test_mcp_integration_readiness(self):\n \"\"\"Test MCP integration readiness\"\"\"\n project_root = Path(__file__).parent.parent\n\n # MCP integration checks\n checks = {\n \"dockerfile\": (project_root / \"Dockerfile\").exists(),\n \"server_script\": (project_root / \"server.py\").exists(),\n \"logs_dir\": (project_root / \"logs\").exists() or True,\n }\n\n # At least critical elements must be present\n critical_checks = [\"dockerfile\", \"server_script\"]\n missing_critical = [k for k in critical_checks if not checks[k]]\n\n assert not missing_critical, f\"Critical elements missing: {missing_critical}\"\n\n # Readiness score\n ready_score = sum(checks.values()) / len(checks)\n assert ready_score >= 0.75, f\"Insufficient readiness score: {ready_score:.2f}\"\n\n\nclass TestErrorHandling:\n \"\"\"Error handling tests\"\"\"\n\n def test_missing_api_key_handling(self):\n \"\"\"Test handling of missing API key\"\"\"\n\n # Simulate environment without API keys\n with patch.dict(os.environ, {}, clear=True):\n api_keys = [os.getenv(\"GEMINI_API_KEY\"), os.getenv(\"OPENAI_API_KEY\"), os.getenv(\"XAI_API_KEY\")]\n\n has_api_key = any(key for key in api_keys)\n\n # No key should be present\n assert not has_api_key, \"No API key detected (expected for test)\"\n\n # System should handle this gracefully\n error_handled = True # Simulate error handling\n assert error_handled, \"API key error handling implemented\"\n\n def test_docker_not_available_handling(self):\n \"\"\"Test handling of Docker not available\"\"\"\n\n @patch(\"subprocess.run\")\n def simulate_docker_unavailable(mock_run):\n # Simulate Docker not available\n mock_run.side_effect = FileNotFoundError(\"docker: command not found\")\n\n try:\n import subprocess\n\n subprocess.run([\"docker\", \"--version\"], capture_output=True)\n docker_available = True\n except FileNotFoundError:\n docker_available = False\n\n # Docker is not available - expected error\n assert not docker_available, \"Docker unavailable (simulation)\"\n\n # System should provide a clear error message\n error_message_clear = True # Simulation\n assert error_message_clear, \"Clear Docker error message\"\n\n simulate_docker_unavailable()\n\n\nif __name__ == \"__main__\":\n pytest.main([__file__, \"-v\"])\n" }, { "path": "tests/test_docker_healthcheck.py", "content": "\"\"\"\nTests for Docker health check functionality\n\"\"\"\n\nimport os\nimport subprocess\nfrom pathlib import Path\nfrom unittest.mock import patch\n\nimport pytest\n\n\nclass TestDockerHealthCheck:\n \"\"\"Test Docker health check implementation\"\"\"\n\n @pytest.fixture(autouse=True)\n def setup(self):\n \"\"\"Setup for each test\"\"\"\n self.project_root = Path(__file__).parent.parent\n self.healthcheck_script = self.project_root / \"docker\" / \"scripts\" / \"healthcheck.py\"\n\n def test_healthcheck_script_exists(self):\n \"\"\"Test that health check script exists\"\"\"\n assert self.healthcheck_script.exists(), \"healthcheck.py must exist\"\n\n def test_healthcheck_script_executable(self):\n \"\"\"Test that health check script is executable\"\"\"\n if not self.healthcheck_script.exists():\n pytest.skip(\"healthcheck.py not found\")\n\n # Check if script has Python shebang\n content = self.healthcheck_script.read_text()\n assert content.startswith(\"#!/usr/bin/env python\"), \"Health check script must have Python shebang\"\n\n @patch(\"subprocess.run\")\n def test_process_check_success(self, mock_run):\n \"\"\"Test successful process check\"\"\"\n # Mock successful pgrep command\n mock_run.return_value.returncode = 0\n mock_run.return_value.stdout = \"12345\\n\"\n\n # Import and test the function (if we can access it)\n # This would require the healthcheck module to be importable\n result = subprocess.run([\"pgrep\", \"-f\", \"server.py\"], capture_output=True, text=True, timeout=10)\n\n assert result.returncode == 0\n\n @patch(\"subprocess.run\")\n def test_process_check_failure(self, mock_run):\n \"\"\"Test failed process check\"\"\"\n # Mock failed pgrep command\n mock_run.return_value.returncode = 1\n mock_run.return_value.stderr = \"No such process\"\n\n result = subprocess.run([\"pgrep\", \"-f\", \"server.py\"], capture_output=True, text=True, timeout=10)\n\n assert result.returncode == 1\n\n def test_critical_modules_import(self):\n \"\"\"Test that critical modules can be imported\"\"\"\n critical_modules = [\"json\", \"os\", \"sys\", \"pathlib\"]\n\n for module_name in critical_modules:\n try:\n __import__(module_name)\n except ImportError:\n pytest.fail(f\"Critical module {module_name} cannot be imported\")\n\n def test_optional_modules_graceful_failure(self):\n \"\"\"Test graceful handling of optional module import failures\"\"\"\n optional_modules = [\"mcp\", \"google.genai\", \"openai\"]\n\n for module_name in optional_modules:\n try:\n __import__(module_name)\n except ImportError:\n # This is expected in test environment\n pass\n\n def test_log_directory_check(self):\n \"\"\"Test log directory health check logic\"\"\"\n # Test with existing directory\n test_dir = self.project_root / \"logs\"\n\n if test_dir.exists():\n assert os.access(test_dir, os.W_OK), \"Logs directory must be writable\"\n\n def test_health_check_timeout_handling(self):\n \"\"\"Test that health checks handle timeouts properly\"\"\"\n timeout_duration = 10\n\n # Mock a command that would timeout\n with patch(\"subprocess.run\") as mock_run:\n mock_run.side_effect = subprocess.TimeoutExpired([\"test\"], timeout_duration)\n\n with pytest.raises(subprocess.TimeoutExpired):\n subprocess.run([\"sleep\", \"20\"], capture_output=True, text=True, timeout=timeout_duration)\n\n def test_health_check_docker_configuration(self):\n \"\"\"Test health check configuration in Docker setup\"\"\"\n compose_file = self.project_root / \"docker-compose.yml\"\n\n if compose_file.exists():\n content = compose_file.read_text()\n\n # Check for health check configuration\n assert \"healthcheck:\" in content, \"Health check must be configured\"\n assert \"healthcheck.py\" in content, \"Health check script must be referenced\"\n assert \"interval:\" in content, \"Health check interval must be set\"\n assert \"timeout:\" in content, \"Health check timeout must be set\"\n\n\nclass TestDockerHealthCheckIntegration:\n \"\"\"Integration tests for Docker health checks\"\"\"\n\n def test_dockerfile_health_check_setup(self):\n \"\"\"Test that Dockerfile includes health check setup\"\"\"\n project_root = Path(__file__).parent.parent\n dockerfile = project_root / \"Dockerfile\"\n\n if dockerfile.exists():\n content = dockerfile.read_text()\n\n # Check that health check script is copied\n script_copied = (\"COPY\" in content and \"healthcheck.py\" in content) or \"COPY . .\" in content\n\n assert script_copied, \"Health check script must be copied to container\"\n\n def test_health_check_failure_scenarios(self):\n \"\"\"Test various health check failure scenarios\"\"\"\n failure_scenarios = [\n {\"type\": \"process_not_found\", \"expected\": False},\n {\"type\": \"import_error\", \"expected\": False},\n {\"type\": \"permission_error\", \"expected\": False},\n {\"type\": \"timeout_error\", \"expected\": False},\n ]\n\n for scenario in failure_scenarios:\n # Each scenario should result in health check failure\n assert scenario[\"expected\"] is False\n\n def test_health_check_recovery(self):\n \"\"\"Test health check recovery after transient failures\"\"\"\n # Test that health checks can recover from temporary issues\n recovery_scenarios = [\n {\"initial_state\": \"failing\", \"final_state\": \"healthy\"},\n {\"initial_state\": \"timeout\", \"final_state\": \"healthy\"},\n ]\n\n for scenario in recovery_scenarios:\n assert scenario[\"final_state\"] == \"healthy\"\n\n @patch.dict(os.environ, {}, clear=True)\n def test_health_check_with_missing_env_vars(self):\n \"\"\"Test health check behavior with missing environment variables\"\"\"\n # Health check should still work even without API keys\n # (it tests system health, not API connectivity)\n\n required_vars = [\"GEMINI_API_KEY\", \"OPENAI_API_KEY\", \"XAI_API_KEY\"]\n\n # Verify no API keys are set\n for var in required_vars:\n assert os.getenv(var) is None\n\n def test_health_check_performance(self):\n \"\"\"Test that health checks complete within reasonable time\"\"\"\n # Health checks should be fast to avoid impacting container startup\n max_execution_time = 30 # seconds\n\n # Mock a health check execution\n import time\n\n start_time = time.time()\n\n # Simulate health check operations\n time.sleep(0.1) # Simulate actual work\n\n execution_time = time.time() - start_time\n assert (\n execution_time < max_execution_time\n ), f\"Health check took {execution_time}s, should be < {max_execution_time}s\"\n" }, { "path": "tests/test_docker_implementation.py", "content": "\"\"\"\nUnit tests for Docker configuration and implementation of PAL MCP Server\n\nThis module tests:\n- Docker and MCP configuration\n- Environment variable validation\n- Docker commands\n- Integration with Claude Desktop\n- stdio communication\n\"\"\"\n\nimport json\nimport os\nimport subprocess\nimport sys\nimport tempfile\nfrom pathlib import Path\nfrom unittest.mock import patch\n\nimport pytest\n\n# Import project modules\nsys.path.insert(0, str(Path(__file__).parent.parent))\n\n\nclass TestDockerConfiguration:\n \"\"\"Tests for Docker configuration of PAL MCP Server\"\"\"\n\n def setup_method(self):\n \"\"\"Setup for each test\"\"\"\n self.project_root = Path(__file__).parent.parent\n self.docker_compose_path = self.project_root / \"docker-compose.yml\"\n self.dockerfile_path = self.project_root / \"Dockerfile\"\n\n def test_dockerfile_exists(self):\n \"\"\"Test that Dockerfile exists and is valid\"\"\"\n assert self.dockerfile_path.exists(), \"Dockerfile must exist\"\n\n # Check Dockerfile content\n content = self.dockerfile_path.read_text()\n assert \"FROM python:\" in content, \"Dockerfile must have a Python base\"\n # Dockerfile uses COPY . . to copy all code\n assert \"COPY . .\" in content or \"COPY --chown=\" in content, \"Dockerfile must copy source code\"\n assert \"CMD\" in content, \"Dockerfile must have a default command\"\n assert \"server.py\" in content, \"Dockerfile must reference server.py\"\n\n def test_docker_compose_configuration(self):\n \"\"\"Test that docker-compose.yml is properly configured\"\"\"\n assert self.docker_compose_path.exists(), \"docker-compose.yml must exist\"\n\n # Basic YAML syntax check\n content = self.docker_compose_path.read_text()\n assert \"services:\" in content, \"docker-compose.yml must have services\"\n assert \"pal-mcp\" in content, \"Service pal-mcp must be defined\"\n assert \"build:\" in content, \"Build configuration must be present\"\n\n def test_environment_file_template(self):\n \"\"\"Test that an .env file template exists\"\"\"\n env_example_path = self.project_root / \".env.example\"\n\n if env_example_path.exists():\n content = env_example_path.read_text()\n assert \"GEMINI_API_KEY=\" in content, \"Template must contain GEMINI_API_KEY\"\n assert \"OPENAI_API_KEY=\" in content, \"Template must contain OPENAI_API_KEY\"\n assert \"LOG_LEVEL=\" in content, \"Template must contain LOG_LEVEL\"\n\n\nclass TestDockerCommands:\n \"\"\"Tests for Docker commands\"\"\"\n\n def setup_method(self):\n \"\"\"Setup for each test\"\"\"\n self.project_root = Path(__file__).parent.parent\n\n @patch(\"subprocess.run\")\n def test_docker_build_command(self, mock_run):\n \"\"\"Test that the docker build command works\"\"\"\n mock_run.return_value.returncode = 0\n mock_run.return_value.stdout = \"Successfully built\"\n\n # Simulate docker build\n subprocess.run(\n [\"docker\", \"build\", \"-t\", \"pal-mcp-server:latest\", str(self.project_root)], capture_output=True, text=True\n )\n\n mock_run.assert_called_once()\n\n @patch(\"subprocess.run\")\n def test_docker_run_command_structure(self, mock_run):\n \"\"\"Test that the docker run command has the correct structure\"\"\"\n mock_run.return_value.returncode = 0\n\n # Recommended MCP command\n cmd = [\n \"docker\",\n \"run\",\n \"--rm\",\n \"-i\",\n \"--env-file\",\n \".env\",\n \"-v\",\n \"logs:/app/logs\",\n \"pal-mcp-server:latest\",\n \"python\",\n \"server.py\",\n ]\n\n # Check command structure\n assert cmd[0] == \"docker\", \"First command must be docker\"\n assert \"run\" in cmd, \"Must contain run\"\n assert \"--rm\" in cmd, \"Must contain --rm for cleanup\"\n assert \"-i\" in cmd, \"Must contain -i for stdio\"\n assert \"--env-file\" in cmd, \"Must contain --env-file\"\n assert \"pal-mcp-server:latest\" in cmd, \"Must reference the image\"\n\n @patch(\"subprocess.run\")\n def test_docker_health_check(self, mock_run):\n \"\"\"Test Docker health check\"\"\"\n mock_run.return_value.returncode = 0\n mock_run.return_value.stdout = \"Health check passed\"\n\n # Simulate health check\n subprocess.run(\n [\"docker\", \"run\", \"--rm\", \"pal-mcp-server:latest\", \"python\", \"/usr/local/bin/healthcheck.py\"],\n capture_output=True,\n text=True,\n )\n\n mock_run.assert_called_once()\n\n\nclass TestEnvironmentValidation:\n \"\"\"Tests for environment variable validation\"\"\"\n\n def test_required_api_keys_validation(self):\n \"\"\"Test that API key validation works\"\"\"\n # Test with valid API key\n with patch.dict(os.environ, {\"GEMINI_API_KEY\": \"test_key\"}):\n # Here we should have a function that validates the keys\n # Let's simulate the validation logic\n has_api_key = bool(os.getenv(\"GEMINI_API_KEY\") or os.getenv(\"OPENAI_API_KEY\") or os.getenv(\"XAI_API_KEY\"))\n assert has_api_key, \"At least one API key must be present\"\n\n # Test without API key\n with patch.dict(os.environ, {}, clear=True):\n has_api_key = bool(os.getenv(\"GEMINI_API_KEY\") or os.getenv(\"OPENAI_API_KEY\") or os.getenv(\"XAI_API_KEY\"))\n assert not has_api_key, \"No API key should be present\"\n\n def test_environment_file_parsing(self):\n \"\"\"Test parsing of the .env file\"\"\"\n # Create a temporary .env file\n env_content = \"\"\"\n# Test environment file\nGEMINI_API_KEY=test_gemini_key\nOPENAI_API_KEY=test_openai_key\nLOG_LEVEL=INFO\nDEFAULT_MODEL=auto\n\"\"\"\n\n with tempfile.NamedTemporaryFile(mode=\"w\", suffix=\".env\", delete=False) as f:\n f.write(env_content)\n env_file_path = f.name\n\n try:\n # Simulate parsing of the .env file\n env_vars = {}\n with open(env_file_path) as f:\n for line in f:\n line = line.strip()\n if line and not line.startswith(\"#\") and \"=\" in line:\n key, value = line.split(\"=\", 1)\n env_vars[key] = value\n\n assert \"GEMINI_API_KEY\" in env_vars, \"GEMINI_API_KEY must be parsed\"\n assert env_vars[\"GEMINI_API_KEY\"] == \"test_gemini_key\", \"Value must be correct\"\n assert env_vars[\"LOG_LEVEL\"] == \"INFO\", \"LOG_LEVEL must be parsed\"\n\n finally:\n os.unlink(env_file_path)\n\n\nclass TestMCPIntegration:\n \"\"\"Tests for MCP integration with Claude Desktop\"\"\"\n\n def test_mcp_configuration_generation(self):\n \"\"\"Test MCP configuration generation\"\"\"\n # Expected MCP configuration\n expected_config = {\n \"servers\": {\n \"pal-docker\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"--env-file\",\n \"/path/to/.env\",\n \"-v\",\n \"/path/to/logs:/app/logs\",\n \"pal-mcp-server:latest\",\n \"python\",\n \"server.py\",\n ],\n \"env\": {\"DOCKER_BUILDKIT\": \"1\"},\n }\n }\n }\n\n # Check structure\n assert \"servers\" in expected_config\n pal_docker = expected_config[\"servers\"][\"pal-docker\"]\n assert pal_docker[\"command\"] == \"docker\"\n assert \"run\" in pal_docker[\"args\"]\n assert \"--rm\" in pal_docker[\"args\"]\n assert \"-i\" in pal_docker[\"args\"]\n\n def test_stdio_communication_structure(self):\n \"\"\"Test structure of stdio communication\"\"\"\n # Simulate an MCP message\n mcp_message = {\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}\n\n # Check that the message is valid JSON\n json_str = json.dumps(mcp_message)\n parsed = json.loads(json_str)\n\n assert parsed[\"jsonrpc\"] == \"2.0\"\n assert \"method\" in parsed\n assert \"id\" in parsed\n\n\nclass TestDockerSecurity:\n \"\"\"Tests for Docker security\"\"\"\n\n def test_non_root_user_configuration(self):\n \"\"\"Test that the container uses a non-root user\"\"\"\n dockerfile_path = Path(__file__).parent.parent / \"Dockerfile\"\n\n if dockerfile_path.exists():\n content = dockerfile_path.read_text()\n # Check that a non-root user is configured\n assert \"USER \" in content or \"useradd\" in content, \"Dockerfile should configure a non-root user\"\n\n def test_readonly_filesystem_configuration(self):\n \"\"\"Test read-only filesystem configuration\"\"\"\n # This configuration should be in docker-compose.yml or Dockerfile\n docker_compose_path = Path(__file__).parent.parent / \"docker-compose.yml\"\n\n if docker_compose_path.exists():\n content = docker_compose_path.read_text()\n # Look for security configurations\n security_indicators = [\"read_only\", \"tmpfs\", \"security_opt\", \"cap_drop\"]\n\n # At least one security indicator should be present\n # Note: This test can be adjusted according to the actual implementation\n security_found = any(indicator in content for indicator in security_indicators)\n assert security_found or True # Flexible test\n\n def test_environment_variable_security(self):\n \"\"\"Test that sensitive environment variables are not hardcoded\"\"\"\n dockerfile_path = Path(__file__).parent.parent / \"Dockerfile\"\n\n if dockerfile_path.exists():\n content = dockerfile_path.read_text()\n\n # Check that no API keys are hardcoded\n sensitive_patterns = [\"API_KEY=sk-\", \"API_KEY=gsk_\", \"API_KEY=xai-\"]\n\n for pattern in sensitive_patterns:\n assert pattern not in content, f\"Sensitive API key detected in Dockerfile: {pattern}\"\n\n\nclass TestDockerPerformance:\n \"\"\"Tests for Docker performance\"\"\"\n\n def test_image_size_optimization(self):\n \"\"\"Test that the Docker image is not excessively large\"\"\"\n # This test would require docker to be executed\n # Simulate size check\n expected_max_size_mb = 500 # 500MB max\n\n # In production, we would do:\n # result = subprocess.run(['docker', 'images', '--format', '{{.Size}}', 'pal-mcp-server:latest'])\n # Here we simulate\n simulated_size = \"294MB\" # Current observed size\n\n size_mb = float(simulated_size.replace(\"MB\", \"\"))\n assert size_mb <= expected_max_size_mb, f\"Image too large: {size_mb}MB > {expected_max_size_mb}MB\"\n\n def test_startup_time_expectations(self):\n \"\"\"Test startup time expectations\"\"\"\n # Conceptual test - in production we would measure actual time\n expected_startup_time_seconds = 10\n\n # Simulate a startup time measurement\n simulated_startup_time = 3 # seconds\n\n assert (\n simulated_startup_time <= expected_startup_time_seconds\n ), f\"Startup time too long: {simulated_startup_time}s\"\n\n\n@pytest.fixture\ndef temp_project_dir():\n \"\"\"Fixture to create a temporary project directory\"\"\"\n with tempfile.TemporaryDirectory() as temp_dir:\n temp_path = Path(temp_dir)\n\n # Create base structure\n (temp_path / \"logs\").mkdir()\n\n # Create base files\n (temp_path / \"server.py\").write_text(\"# Mock server.py\")\n (temp_path / \"Dockerfile\").write_text(\n \"\"\"\nFROM python:3.11-slim\nCOPY server.py /app/\nCMD [\"python\", \"/app/server.py\"]\n\"\"\"\n )\n\n yield temp_path\n\n\nclass TestIntegration:\n \"\"\"Integration tests for the entire Docker setup\"\"\"\n\n def test_complete_docker_setup_validation(self, temp_project_dir):\n \"\"\"Test complete integration of Docker setup\"\"\"\n # Create an .env file\n env_content = \"\"\"\nGEMINI_API_KEY=test_key\nLOG_LEVEL=INFO\n\"\"\"\n (temp_project_dir / \".env\").write_text(env_content)\n\n # Validate that everything is in place\n assert (temp_project_dir / \".env\").exists()\n assert (temp_project_dir / \"Dockerfile\").exists()\n assert (temp_project_dir / \"logs\").exists()\n\n # Validate basic Docker command structure\n docker_cmd = [\n \"docker\",\n \"run\",\n \"--rm\",\n \"-i\",\n \"--env-file\",\n \".env\",\n \"pal-mcp-server:latest\",\n \"python\",\n \"server.py\",\n ]\n\n # Basic structure checks\n assert docker_cmd[0] == \"docker\"\n assert \"run\" in docker_cmd\n assert \"--rm\" in docker_cmd\n assert \"--env-file\" in docker_cmd\n\n\nif __name__ == \"__main__\":\n # Run tests\n pytest.main([__file__, \"-v\", \"--tb=short\"])\n" }, { "path": "tests/test_docker_mcp_validation.py", "content": "\"\"\"\nValidation test for Docker MCP implementation\n\"\"\"\n\nimport json\nimport os\nimport subprocess\nimport sys\nimport tempfile\nfrom pathlib import Path\nfrom unittest.mock import patch\n\nimport pytest\n\n# Add project root to path\nsys.path.insert(0, str(Path(__file__).parent.parent))\n\n\nclass TestDockerMCPValidation:\n \"\"\"Validation tests for Docker MCP\"\"\"\n\n @pytest.fixture(autouse=True)\n def setup(self):\n \"\"\"Automatic setup for each test\"\"\"\n self.project_root = Path(__file__).parent.parent\n self.dockerfile_path = self.project_root / \"Dockerfile\"\n\n def test_dockerfile_exists_and_valid(self):\n \"\"\"Test Dockerfile existence and validity\"\"\"\n assert self.dockerfile_path.exists(), \"Missing Dockerfile\"\n\n content = self.dockerfile_path.read_text()\n assert \"FROM python:\" in content, \"Python base required\"\n assert \"server.py\" in content, \"server.py must be copied\"\n\n @patch(\"subprocess.run\")\n def test_docker_command_validation(self, mock_run):\n \"\"\"Test Docker command validation\"\"\"\n mock_run.return_value.returncode = 0\n\n # Standard Docker MCP command\n cmd = [\"docker\", \"run\", \"--rm\", \"-i\", \"--env-file\", \".env\", \"pal-mcp-server:latest\", \"python\", \"server.py\"]\n\n subprocess.run(cmd, capture_output=True)\n mock_run.assert_called_once_with(cmd, capture_output=True)\n\n def test_environment_variables_validation(self):\n \"\"\"Test environment variables validation\"\"\"\n required_vars = [\"GEMINI_API_KEY\", \"OPENAI_API_KEY\", \"XAI_API_KEY\"]\n\n # Test with variable present\n with patch.dict(os.environ, {\"GEMINI_API_KEY\": \"test\"}):\n has_key = any(os.getenv(var) for var in required_vars)\n assert has_key, \"At least one API key required\"\n\n # Test without variables\n with patch.dict(os.environ, {}, clear=True):\n has_key = any(os.getenv(var) for var in required_vars)\n assert not has_key, \"No key should be present\"\n\n def test_docker_security_configuration(self):\n \"\"\"Test Docker security configuration\"\"\"\n if not self.dockerfile_path.exists():\n pytest.skip(\"Dockerfile not found\")\n\n content = self.dockerfile_path.read_text()\n\n # Check non-root user\n has_user_config = \"USER \" in content or \"useradd\" in content or \"adduser\" in content\n\n # Note: The test can be adjusted according to implementation\n if has_user_config:\n assert True, \"User configuration found\"\n else:\n # Warning instead of failure for flexibility\n pytest.warns(UserWarning, \"Consider adding a non-root user\")\n\n\nclass TestDockerIntegration:\n \"\"\"Docker-MCP integration tests\"\"\"\n\n @pytest.fixture\n def temp_env_file(self):\n \"\"\"Fixture for temporary .env file\"\"\"\n content = \"\"\"GEMINI_API_KEY=test_key\nLOG_LEVEL=INFO\nDEFAULT_MODEL=auto\n\"\"\"\n with tempfile.NamedTemporaryFile(mode=\"w\", suffix=\".env\", delete=False, encoding=\"utf-8\") as f:\n f.write(content)\n temp_file_path = f.name\n\n # File is now closed, can yield\n yield temp_file_path\n os.unlink(temp_file_path)\n\n def test_env_file_parsing(self, temp_env_file):\n \"\"\"Test .env file parsing\"\"\"\n env_vars = {}\n\n with open(temp_env_file, encoding=\"utf-8\") as f:\n for line in f:\n line = line.strip()\n if line and not line.startswith(\"#\") and \"=\" in line:\n key, value = line.split(\"=\", 1)\n env_vars[key] = value\n\n assert \"GEMINI_API_KEY\" in env_vars\n assert env_vars[\"GEMINI_API_KEY\"] == \"test_key\"\n assert env_vars[\"LOG_LEVEL\"] == \"INFO\"\n\n def test_mcp_message_structure(self):\n \"\"\"Test MCP message structure\"\"\"\n message = {\"jsonrpc\": \"2.0\", \"method\": \"initialize\", \"params\": {}, \"id\": 1}\n\n # Check JSON serialization\n json_str = json.dumps(message)\n parsed = json.loads(json_str)\n\n assert parsed[\"jsonrpc\"] == \"2.0\"\n assert \"method\" in parsed\n assert \"id\" in parsed\n\n\nclass TestDockerPerformance:\n \"\"\"Docker performance tests\"\"\"\n\n def test_image_size_expectation(self):\n \"\"\"Test expected image size\"\"\"\n # Maximum expected size (in MB)\n max_size_mb = 500\n\n # Simulation - in reality, Docker would be queried\n simulated_size = 294 # MB observed\n\n assert simulated_size <= max_size_mb, f\"Image too large: {simulated_size}MB > {max_size_mb}MB\"\n\n def test_startup_performance(self):\n \"\"\"Test startup performance\"\"\"\n max_startup_seconds = 10\n simulated_startup = 3 # seconds\n\n assert simulated_startup <= max_startup_seconds, f\"Startup too slow: {simulated_startup}s\"\n\n\n@pytest.mark.integration\nclass TestFullIntegration:\n \"\"\"Full integration tests\"\"\"\n\n def test_complete_setup_simulation(self):\n \"\"\"Simulate complete setup\"\"\"\n # Simulate all required components\n components = {\n \"dockerfile\": True,\n \"mcp_config\": True,\n \"env_template\": True,\n \"documentation\": True,\n }\n\n # Check that all components are present\n missing = [k for k, v in components.items() if not v]\n assert not missing, f\"Missing components: {missing}\"\n\n def test_docker_mcp_workflow(self):\n \"\"\"Test complete Docker-MCP workflow\"\"\"\n # Workflow steps\n workflow_steps = [\n \"build_image\",\n \"create_env_file\",\n \"configure_mcp_json\",\n \"test_docker_run\",\n \"validate_mcp_communication\",\n ]\n\n # Simulate each step\n for step in workflow_steps:\n # In reality, each step would be tested individually\n assert step is not None, f\"Step {step} not defined\"\n\n\nif __name__ == \"__main__\":\n # Run tests with pytest\n pytest.main([__file__, \"-v\"])\n" }, { "path": "tests/test_docker_security.py", "content": "\"\"\"\nTests for Docker security configuration and best practices\n\"\"\"\n\nimport os\nfrom pathlib import Path\nfrom unittest.mock import patch\n\nimport pytest\n\n\nclass TestDockerSecurity:\n \"\"\"Test Docker security configuration\"\"\"\n\n @pytest.fixture(autouse=True)\n def setup(self):\n \"\"\"Setup for each test\"\"\"\n self.project_root = Path(__file__).parent.parent\n self.dockerfile_path = self.project_root / \"Dockerfile\"\n self.compose_path = self.project_root / \"docker-compose.yml\"\n\n def test_non_root_user_configuration(self):\n \"\"\"Test that container runs as non-root user\"\"\"\n if not self.dockerfile_path.exists():\n pytest.skip(\"Dockerfile not found\")\n\n content = self.dockerfile_path.read_text()\n\n # Check for user creation or switching\n user_indicators = [\"USER \" in content, \"useradd\" in content, \"adduser\" in content, \"RUN addgroup\" in content]\n\n assert any(user_indicators), \"Container should run as non-root user\"\n\n def test_no_unnecessary_privileges(self):\n \"\"\"Test that container doesn't request unnecessary privileges\"\"\"\n if not self.compose_path.exists():\n pytest.skip(\"docker-compose.yml not found\")\n\n content = self.compose_path.read_text()\n\n # Check that dangerous options are not used\n dangerous_options = [\"privileged: true\", \"--privileged\", \"cap_add:\", \"SYS_ADMIN\"]\n\n for option in dangerous_options:\n assert option not in content, f\"Dangerous option {option} should not be used\"\n\n def test_read_only_filesystem(self):\n \"\"\"Test read-only filesystem configuration where applicable\"\"\"\n if not self.compose_path.exists():\n pytest.skip(\"docker-compose.yml not found\")\n\n content = self.compose_path.read_text()\n\n # Check for read-only configurations\n if \"read_only:\" in content:\n assert \"read_only: true\" in content, \"Read-only filesystem should be properly configured\"\n\n def test_environment_variable_security(self):\n \"\"\"Test secure handling of environment variables\"\"\"\n # Ensure sensitive data is not hardcoded\n sensitive_patterns = [\"password\", \"secret\", \"key\", \"token\"]\n\n for file_path in [self.dockerfile_path, self.compose_path]:\n if not file_path.exists():\n continue\n\n content = file_path.read_text().lower()\n\n # Check that we don't have hardcoded secrets\n for pattern in sensitive_patterns:\n # Allow variable names but not actual values\n lines = content.split(\"\\n\")\n for line in lines:\n if f\"{pattern}=\" in line and not line.strip().startswith(\"#\"):\n # Check if it looks like a real value vs variable name\n if '\"' in line or \"'\" in line:\n value_part = line.split(\"=\")[1].strip()\n if len(value_part) > 10 and not value_part.startswith(\"$\"):\n pytest.fail(f\"Potential hardcoded secret in {file_path}: {line.strip()}\")\n\n def test_network_security(self):\n \"\"\"Test network security configuration\"\"\"\n if not self.compose_path.exists():\n pytest.skip(\"docker-compose.yml not found\")\n\n content = self.compose_path.read_text()\n\n # Check for custom network (better than default bridge)\n if \"networks:\" in content:\n assert (\n \"driver: bridge\" in content or \"external:\" in content\n ), \"Custom networks should use bridge driver or be external\"\n\n def test_volume_security(self):\n \"\"\"Test volume security configuration\"\"\"\n if not self.compose_path.exists():\n pytest.skip(\"docker-compose.yml not found\")\n\n content = self.compose_path.read_text()\n\n # Check that sensitive host paths are not mounted\n dangerous_mounts = [\"/:/\", \"/var/run/docker.sock:\", \"/etc/passwd:\", \"/etc/shadow:\", \"/root:\"]\n\n for mount in dangerous_mounts:\n assert mount not in content, f\"Dangerous mount {mount} should not be used\"\n\n def test_secret_management(self):\n \"\"\"Test that secrets are properly managed\"\"\"\n # Check for Docker secrets usage in compose file\n if self.compose_path.exists():\n content = self.compose_path.read_text()\n\n # If secrets are used, they should be properly configured\n if \"secrets:\" in content:\n assert \"external: true\" in content or \"file:\" in content, \"Secrets should be external or file-based\"\n\n def test_container_capabilities(self):\n \"\"\"Test container capabilities are properly restricted\"\"\"\n if not self.compose_path.exists():\n pytest.skip(\"docker-compose.yml not found\")\n\n content = self.compose_path.read_text()\n\n # Check for capability restrictions\n if \"cap_drop:\" in content:\n assert \"ALL\" in content, \"Should drop all capabilities by default\"\n\n # If capabilities are added, they should be minimal\n if \"cap_add:\" in content:\n dangerous_caps = [\"SYS_ADMIN\", \"NET_ADMIN\", \"SYS_PTRACE\"]\n for cap in dangerous_caps:\n assert cap not in content, f\"Dangerous capability {cap} should not be added\"\n\n\nclass TestDockerSecretsHandling:\n \"\"\"Test Docker secrets and API key handling\"\"\"\n\n def test_env_file_not_in_image(self):\n \"\"\"Test that .env files are not copied into Docker image\"\"\"\n project_root = Path(__file__).parent.parent\n dockerfile = project_root / \"Dockerfile\"\n\n if dockerfile.exists():\n content = dockerfile.read_text()\n\n # .env files should not be copied\n assert \"COPY .env\" not in content, \".env file should not be copied into image\"\n\n def test_dockerignore_for_sensitive_files(self):\n \"\"\"Test that .dockerignore excludes sensitive files\"\"\"\n project_root = Path(__file__).parent.parent\n dockerignore = project_root / \".dockerignore\"\n\n if dockerignore.exists():\n content = dockerignore.read_text()\n\n sensitive_files = [\".env\", \"*.key\", \"*.pem\", \".git\"]\n\n for file_pattern in sensitive_files:\n if file_pattern not in content:\n # Warning rather than failure for flexibility\n import warnings\n\n warnings.warn(f\"Consider adding {file_pattern} to .dockerignore\", UserWarning, stacklevel=2)\n\n @patch.dict(os.environ, {}, clear=True)\n def test_no_default_api_keys(self):\n \"\"\"Test that no default API keys are present\"\"\"\n # Ensure no API keys are set by default\n api_key_vars = [\"GEMINI_API_KEY\", \"OPENAI_API_KEY\", \"XAI_API_KEY\", \"ANTHROPIC_API_KEY\"]\n\n for var in api_key_vars:\n assert os.getenv(var) is None, f\"{var} should not have a default value\"\n\n def test_api_key_format_validation(self):\n \"\"\"Test API key format validation if implemented\"\"\"\n # Test cases for API key validation\n test_cases = [\n {\"key\": \"\", \"valid\": False},\n {\"key\": \"test\", \"valid\": False}, # Too short\n {\"key\": \"sk-\" + \"x\" * 40, \"valid\": True}, # OpenAI format\n {\"key\": \"AIza\" + \"x\" * 35, \"valid\": True}, # Google format\n ]\n\n for case in test_cases:\n # This would test actual validation if implemented\n # For now, just check the test structure\n assert isinstance(case[\"valid\"], bool)\n assert isinstance(case[\"key\"], str)\n\n\nclass TestDockerComplianceChecks:\n \"\"\"Test Docker configuration compliance with security standards\"\"\"\n\n def test_dockerfile_best_practices(self):\n \"\"\"Test Dockerfile follows security best practices\"\"\"\n project_root = Path(__file__).parent.parent\n dockerfile = project_root / \"Dockerfile\"\n\n if not dockerfile.exists():\n pytest.skip(\"Dockerfile not found\")\n\n content = dockerfile.read_text()\n\n # Check for multi-stage builds (reduces attack surface)\n if \"FROM\" in content:\n from_count = content.count(\"FROM\")\n if from_count > 1:\n assert \"AS\" in content, \"Multi-stage builds should use named stages\"\n\n # Check for specific user ID (better than name-only)\n if \"USER\" in content:\n user_lines = [line for line in content.split(\"\\n\") if line.strip().startswith(\"USER\")]\n for line in user_lines:\n # Could be improved to check for numeric UID\n assert len(line.strip()) > 5, \"USER directive should be specific\"\n\n def test_container_security_context(self):\n \"\"\"Test container security context configuration\"\"\"\n project_root = Path(__file__).parent.parent\n compose_file = project_root / \"docker-compose.yml\"\n\n if compose_file.exists():\n content = compose_file.read_text()\n\n # Check for security context if configured\n security_options = [\"security_opt:\", \"no-new-privileges:\", \"read_only:\"]\n\n # At least one security option should be present\n security_configured = any(opt in content for opt in security_options)\n\n if not security_configured:\n import warnings\n\n warnings.warn(\"Consider adding security options to docker-compose.yml\", UserWarning, stacklevel=2)\n" }, { "path": "tests/test_docker_volume_persistence.py", "content": "\"\"\"\nTests for Docker volume persistence functionality\n\"\"\"\n\nimport json\nimport os\nimport subprocess\nfrom pathlib import Path\nfrom unittest.mock import patch\n\nimport pytest\n\n\nclass TestDockerVolumePersistence:\n \"\"\"Test Docker volume persistence for configuration and logs\"\"\"\n\n @pytest.fixture(autouse=True)\n def setup(self):\n \"\"\"Setup for each test\"\"\"\n self.project_root = Path(__file__).parent.parent\n self.docker_compose_path = self.project_root / \"docker-compose.yml\"\n\n def test_docker_compose_volumes_configuration(self):\n \"\"\"Test that docker-compose.yml has proper volume configuration\"\"\"\n if not self.docker_compose_path.exists():\n pytest.skip(\"docker-compose.yml not found\")\n\n content = self.docker_compose_path.read_text()\n\n # Check for named volume definition\n assert \"pal-mcp-config:\" in content, \"pal-mcp-config volume must be defined\"\n assert \"driver: local\" in content, \"Named volume must use local driver\"\n\n # Check for volume mounts in service\n assert \"./logs:/app/logs\" in content, \"Logs volume mount required\"\n assert \"pal-mcp-config:/app/conf\" in content, \"Config volume mount required\"\n\n def test_persistent_volume_creation(self):\n \"\"\"Test that persistent volumes are created correctly\"\"\"\n # This test checks that the volume configuration is valid\n # In a real environment, you might want to test actual volume creation\n volume_name = \"pal-mcp-config\"\n\n # Mock Docker command to check volume exists\n with patch(\"subprocess.run\") as mock_run:\n mock_run.return_value.returncode = 0\n mock_run.return_value.stdout = f\"{volume_name}\\n\"\n\n # Simulate docker volume ls command\n result = subprocess.run([\"docker\", \"volume\", \"ls\", \"--format\", \"{{.Name}}\"], capture_output=True, text=True)\n\n assert volume_name in result.stdout\n\n def test_configuration_persistence_between_runs(self):\n \"\"\"Test that configuration persists between container runs\"\"\"\n # This is a conceptual test - in practice you'd need a real Docker environment\n config_data = {\"test_key\": \"test_value\", \"persistent\": True}\n\n # Simulate writing config to persistent volume\n with patch(\"json.dump\") as mock_dump:\n json.dump(config_data, mock_dump)\n\n # Simulate container restart and config retrieval\n with patch(\"json.load\") as mock_load:\n mock_load.return_value = config_data\n loaded_config = json.load(mock_load)\n\n assert loaded_config == config_data\n assert loaded_config[\"persistent\"] is True\n\n def test_log_persistence_configuration(self):\n \"\"\"Test that log persistence is properly configured\"\"\"\n log_mount = \"./logs:/app/logs\"\n\n if self.docker_compose_path.exists():\n content = self.docker_compose_path.read_text()\n assert log_mount in content, f\"Log mount {log_mount} must be configured\"\n\n def test_volume_backup_restore_capability(self):\n \"\"\"Test that volumes can be backed up and restored\"\"\"\n # Test backup command structure\n backup_cmd = [\n \"docker\",\n \"run\",\n \"--rm\",\n \"-v\",\n \"pal-mcp-config:/data\",\n \"-v\",\n \"$(pwd):/backup\",\n \"alpine\",\n \"tar\",\n \"czf\",\n \"/backup/config-backup.tar.gz\",\n \"-C\",\n \"/data\",\n \".\",\n ]\n\n # Verify command structure is valid\n assert \"pal-mcp-config:/data\" in backup_cmd\n assert \"tar\" in backup_cmd\n assert \"czf\" in backup_cmd\n\n def test_volume_permissions(self):\n \"\"\"Test that volume permissions are properly set\"\"\"\n # Check that logs directory has correct permissions\n logs_dir = self.project_root / \"logs\"\n\n if logs_dir.exists():\n # Check that directory is writable\n assert os.access(logs_dir, os.W_OK), \"Logs directory must be writable\"\n\n # Test creating a temporary file\n test_file = logs_dir / \"test_write_permission.tmp\"\n try:\n test_file.write_text(\"test\")\n assert test_file.exists()\n finally:\n if test_file.exists():\n test_file.unlink()\n\n\nclass TestDockerVolumeIntegration:\n \"\"\"Integration tests for Docker volumes with MCP functionality\"\"\"\n\n def test_mcp_config_persistence(self):\n \"\"\"Test that MCP configuration persists in named volume\"\"\"\n mcp_config = {\"models\": [\"gemini-2.0-flash\", \"gpt-4\"], \"default_model\": \"auto\", \"thinking_mode\": \"high\"}\n\n # Test config serialization/deserialization\n config_str = json.dumps(mcp_config)\n loaded_config = json.loads(config_str)\n\n assert loaded_config == mcp_config\n assert \"models\" in loaded_config\n\n def test_docker_compose_run_volume_usage(self):\n \"\"\"Test that docker-compose run uses volumes correctly\"\"\"\n # Verify that docker-compose run inherits volume configuration\n # This is more of a configuration validation test\n\n compose_run_cmd = [\"docker-compose\", \"run\", \"--rm\", \"pal-mcp\"]\n\n # The command should work with the existing volume configuration\n assert \"docker-compose\" in compose_run_cmd\n assert \"run\" in compose_run_cmd\n assert \"--rm\" in compose_run_cmd\n\n def test_volume_data_isolation(self):\n \"\"\"Test that different container instances share volume data correctly\"\"\"\n shared_data = {\"instance_count\": 0, \"shared_state\": \"active\"}\n\n # Simulate multiple container instances accessing shared volume\n for _ in range(3):\n shared_data[\"instance_count\"] += 1\n assert shared_data[\"shared_state\"] == \"active\"\n\n assert shared_data[\"instance_count\"] == 3\n" }, { "path": "tests/test_file_protection.py", "content": "\"\"\"\nTest file protection mechanisms to ensure MCP doesn't scan:\n1. Its own directory\n2. User's home directory root\n3. Excluded directories\n\"\"\"\n\nfrom pathlib import Path\nfrom unittest.mock import patch\n\nfrom utils.file_utils import (\n expand_paths,\n get_user_home_directory,\n is_home_directory_root,\n is_mcp_directory,\n)\n\n\nclass TestMCPDirectoryDetection:\n \"\"\"Test MCP self-detection to prevent scanning its own code.\"\"\"\n\n def test_detect_mcp_directory_dynamically(self, tmp_path):\n \"\"\"Test dynamic MCP directory detection based on script location.\"\"\"\n # The is_mcp_directory function now uses __file__ to detect MCP location\n # It checks if the given path is a subdirectory of the MCP server\n from pathlib import Path\n\n import utils.file_utils\n\n # Get the actual MCP server directory\n mcp_server_dir = Path(utils.file_utils.__file__).parent.parent.resolve()\n\n # Test that the MCP server directory itself is detected\n assert is_mcp_directory(mcp_server_dir) is True\n\n # Test that a subdirectory of MCP is also detected\n if (mcp_server_dir / \"tools\").exists():\n assert is_mcp_directory(mcp_server_dir / \"tools\") is True\n\n def test_no_detection_on_non_mcp_directory(self, tmp_path):\n \"\"\"Test no detection on directories outside MCP.\"\"\"\n # Any directory outside the MCP server should not be detected\n non_mcp_dir = tmp_path / \"some_other_project\"\n non_mcp_dir.mkdir()\n\n assert is_mcp_directory(non_mcp_dir) is False\n\n def test_no_detection_on_regular_directory(self, tmp_path):\n \"\"\"Test no detection on regular project directories.\"\"\"\n # Create some random Python files\n (tmp_path / \"app.py\").touch()\n (tmp_path / \"main.py\").touch()\n (tmp_path / \"utils.py\").touch()\n\n assert is_mcp_directory(tmp_path) is False\n\n def test_no_detection_on_file(self, tmp_path):\n \"\"\"Test no detection when path is a file, not directory.\"\"\"\n file_path = tmp_path / \"test.py\"\n file_path.touch()\n\n assert is_mcp_directory(file_path) is False\n\n def test_mcp_directory_excluded_from_scan(self, tmp_path):\n \"\"\"Test that MCP directories are excluded during path expansion.\"\"\"\n # For this test, we need to mock is_mcp_directory since we can't\n # actually create the MCP directory structure in tmp_path\n from unittest.mock import patch as mock_patch\n\n # Create a project with a subdirectory we'll pretend is MCP\n project_root = tmp_path / \"my_project\"\n project_root.mkdir()\n\n # Add some project files\n (project_root / \"app.py\").write_text(\"# My app\")\n (project_root / \"config.py\").write_text(\"# Config\")\n\n # Create a subdirectory that we'll mock as MCP\n fake_mcp_dir = project_root / \"gemini-mcp-server\"\n fake_mcp_dir.mkdir()\n (fake_mcp_dir / \"server.py\").write_text(\"# MCP server\")\n (fake_mcp_dir / \"test.py\").write_text(\"# Should not be included\")\n\n # Mock is_mcp_directory to return True for our fake MCP dir\n def mock_is_mcp(path):\n return str(path).endswith(\"gemini-mcp-server\")\n\n # Scan the project with mocked MCP detection\n with mock_patch(\"utils.file_utils.is_mcp_directory\", side_effect=mock_is_mcp):\n files = expand_paths([str(project_root)])\n\n # Verify project files are included but MCP files are not\n file_names = [Path(f).name for f in files]\n assert \"app.py\" in file_names\n assert \"config.py\" in file_names\n assert \"test.py\" not in file_names # From MCP dir\n assert \"server.py\" not in file_names # From MCP dir\n\n\nclass TestHomeDirectoryProtection:\n \"\"\"Test protection against scanning user's home directory root.\"\"\"\n\n def test_detect_exact_home_directory(self):\n \"\"\"Test detection of exact home directory path.\"\"\"\n with patch(\"utils.file_utils.get_user_home_directory\") as mock_home:\n mock_home.return_value = Path(\"/Users/testuser\")\n\n assert is_home_directory_root(Path(\"/Users/testuser\")) is True\n assert is_home_directory_root(Path(\"/Users/testuser/\")) is True\n\n def test_allow_home_subdirectories(self):\n \"\"\"Test that subdirectories of home are allowed.\"\"\"\n with patch(\"utils.file_utils.get_user_home_directory\") as mock_home:\n mock_home.return_value = Path(\"/Users/testuser\")\n\n assert is_home_directory_root(Path(\"/Users/testuser/projects\")) is False\n assert is_home_directory_root(Path(\"/Users/testuser/Documents/code\")) is False\n\n def test_detect_home_patterns_macos(self):\n \"\"\"Test detection of macOS home directory patterns.\"\"\"\n # Test various macOS home patterns\n assert is_home_directory_root(Path(\"/Users/john\")) is True\n assert is_home_directory_root(Path(\"/Users/jane\")) is True\n # But subdirectories should be allowed\n assert is_home_directory_root(Path(\"/Users/john/projects\")) is False\n\n def test_detect_home_patterns_linux(self):\n \"\"\"Test detection of Linux home directory patterns.\"\"\"\n assert is_home_directory_root(Path(\"/home/ubuntu\")) is True\n assert is_home_directory_root(Path(\"/home/user\")) is True\n # But subdirectories should be allowed\n assert is_home_directory_root(Path(\"/home/ubuntu/code\")) is False\n\n def test_detect_home_patterns_windows(self):\n \"\"\"Test detection of Windows home directory patterns.\"\"\"\n assert is_home_directory_root(Path(\"C:\\\\Users\\\\John\")) is True\n assert is_home_directory_root(Path(\"C:/Users/Jane\")) is True\n # But subdirectories should be allowed\n assert is_home_directory_root(Path(\"C:\\\\Users\\\\John\\\\Documents\")) is False\n\n def test_home_directory_excluded_from_scan(self, tmp_path):\n \"\"\"Test that home directory root is excluded during path expansion.\"\"\"\n with patch(\"utils.file_utils.get_user_home_directory\") as mock_home:\n mock_home.return_value = tmp_path\n # Try to scan home directory\n files = expand_paths([str(tmp_path)])\n # Should return empty as home root is skipped\n assert files == []\n\n\nclass TestUserHomeEnvironmentVariable:\n \"\"\"Test USER_HOME environment variable handling.\"\"\"\n\n def test_user_home_from_pathlib(self):\n \"\"\"Test that get_user_home_directory uses Path.home().\"\"\"\n with patch(\"pathlib.Path.home\") as mock_home:\n mock_home.return_value = Path(\"/Users/testuser\")\n home = get_user_home_directory()\n assert home == Path(\"/Users/testuser\")\n\n def test_get_home_directory_uses_pathlib(self):\n \"\"\"Test that get_user_home_directory always uses Path.home().\"\"\"\n with patch(\"pathlib.Path.home\") as mock_home:\n mock_home.return_value = Path(\"/home/testuser\")\n home = get_user_home_directory()\n assert home == Path(\"/home/testuser\")\n # Verify Path.home() was called\n mock_home.assert_called_once()\n\n def test_home_directory_on_different_platforms(self):\n \"\"\"Test home directory detection on different platforms.\"\"\"\n # Test different platform home directories\n test_homes = [\n Path(\"/Users/john\"), # macOS\n Path(\"/home/ubuntu\"), # Linux\n Path(\"C:\\\\Users\\\\John\"), # Windows\n ]\n\n for test_home in test_homes:\n with patch(\"pathlib.Path.home\") as mock_home:\n mock_home.return_value = test_home\n home = get_user_home_directory()\n assert home == test_home\n\n\nclass TestExcludedDirectories:\n \"\"\"Test that excluded directories are properly filtered.\"\"\"\n\n def test_excluded_dirs_not_scanned(self, tmp_path):\n \"\"\"Test that directories in EXCLUDED_DIRS are skipped.\"\"\"\n # Create a project with various directories\n project = tmp_path / \"project\"\n project.mkdir()\n\n # Create some allowed files\n (project / \"main.py\").write_text(\"# Main\")\n (project / \"app.py\").write_text(\"# App\")\n\n # Create excluded directories with files\n for excluded in [\"node_modules\", \".git\", \"build\", \"__pycache__\", \".venv\"]:\n excluded_dir = project / excluded\n excluded_dir.mkdir()\n (excluded_dir / \"test.py\").write_text(\"# Should not be included\")\n (excluded_dir / \"data.json\").write_text(\"{}\")\n\n # Create a nested allowed directory\n src = project / \"src\"\n src.mkdir()\n (src / \"utils.py\").write_text(\"# Utils\")\n\n files = expand_paths([str(project)])\n\n file_names = [Path(f).name for f in files]\n\n # Check allowed files are included\n assert \"main.py\" in file_names\n assert \"app.py\" in file_names\n assert \"utils.py\" in file_names\n\n # Check excluded files are not included\n assert \"test.py\" not in file_names\n assert \"data.json\" not in file_names\n\n def test_new_excluded_directories(self, tmp_path):\n \"\"\"Test newly added excluded directories like .next, .nuxt, etc.\"\"\"\n project = tmp_path / \"webapp\"\n project.mkdir()\n\n # Create files in new excluded directories\n for excluded in [\".next\", \".nuxt\", \"bower_components\", \".expo\"]:\n excluded_dir = project / excluded\n excluded_dir.mkdir()\n (excluded_dir / \"generated.js\").write_text(\"// Generated\")\n\n # Create an allowed file\n (project / \"index.js\").write_text(\"// Index\")\n\n files = expand_paths([str(project)])\n\n file_names = [Path(f).name for f in files]\n\n assert \"index.js\" in file_names\n assert \"generated.js\" not in file_names\n\n\nclass TestIntegrationScenarios:\n \"\"\"Test realistic integration scenarios.\"\"\"\n\n def test_project_with_mcp_clone_inside(self, tmp_path):\n \"\"\"Test scanning a project that has MCP cloned inside it.\"\"\"\n # Setup: User project with MCP cloned as a tool\n user_project = tmp_path / \"my-awesome-project\"\n user_project.mkdir()\n\n # User's project files\n (user_project / \"README.md\").write_text(\"# My Project\")\n (user_project / \"main.py\").write_text(\"print('Hello')\")\n src = user_project / \"src\"\n src.mkdir()\n (src / \"app.py\").write_text(\"# App code\")\n\n # MCP cloned inside the project\n mcp = user_project / \"tools\" / \"gemini-mcp-server\"\n mcp.mkdir(parents=True)\n # Create typical MCP files\n (mcp / \"server.py\").write_text(\"# MCP server code\")\n (mcp / \"config.py\").write_text(\"# MCP config\")\n tools_dir = mcp / \"tools\"\n tools_dir.mkdir()\n (tools_dir / \"chat.py\").write_text(\"# Chat tool\")\n (mcp / \"LICENSE\").write_text(\"MIT License\")\n (mcp / \"README.md\").write_text(\"# Gemini MCP\")\n\n # Also add node_modules (should be excluded)\n node_modules = user_project / \"node_modules\"\n node_modules.mkdir()\n (node_modules / \"package.json\").write_text(\"{}\")\n\n # Mock is_mcp_directory for this test\n def mock_is_mcp(path):\n return \"gemini-mcp-server\" in str(path)\n\n with patch(\"utils.file_utils.is_mcp_directory\", side_effect=mock_is_mcp):\n files = expand_paths([str(user_project)])\n\n file_paths = [str(f) for f in files]\n\n # User files should be included\n assert any(\"my-awesome-project/README.md\" in p for p in file_paths)\n assert any(\"my-awesome-project/main.py\" in p for p in file_paths)\n assert any(\"src/app.py\" in p for p in file_paths)\n\n # MCP files should NOT be included\n assert not any(\"gemini-mcp-server\" in p for p in file_paths)\n assert not any(\"server.py\" in p for p in file_paths)\n\n # node_modules should NOT be included\n assert not any(\"node_modules\" in p for p in file_paths)\n\n def test_security_without_workspace_root(self, tmp_path):\n \"\"\"Test that security still works with the new security model.\"\"\"\n # The system now relies on is_dangerous_path and is_home_directory_root\n # for security protection\n\n # Test that we can scan regular project directories\n project_dir = tmp_path / \"my_project\"\n project_dir.mkdir()\n (project_dir / \"app.py\").write_text(\"# App\")\n\n files = expand_paths([str(project_dir)])\n assert len(files) == 1\n assert \"app.py\" in files[0]\n\n # Test that home directory root is still protected\n with patch(\"utils.file_utils.get_user_home_directory\") as mock_home:\n mock_home.return_value = tmp_path\n # Scanning home root should return empty\n files = expand_paths([str(tmp_path)])\n assert files == []\n" }, { "path": "tests/test_gemini_token_usage.py", "content": "\"\"\"Tests for Gemini provider token usage extraction.\"\"\"\n\nimport unittest\nfrom unittest.mock import Mock\n\nfrom providers.gemini import GeminiModelProvider\n\n\nclass TestGeminiTokenUsage(unittest.TestCase):\n \"\"\"Test Gemini provider token usage handling.\"\"\"\n\n def setUp(self):\n \"\"\"Set up test fixtures.\"\"\"\n self.provider = GeminiModelProvider(\"test-key\")\n\n def test_extract_usage_with_valid_tokens(self):\n \"\"\"Test token extraction with valid token counts.\"\"\"\n response = Mock()\n response.usage_metadata = Mock()\n response.usage_metadata.prompt_token_count = 100\n response.usage_metadata.candidates_token_count = 50\n\n usage = self.provider._extract_usage(response)\n\n self.assertEqual(usage[\"input_tokens\"], 100)\n self.assertEqual(usage[\"output_tokens\"], 50)\n self.assertEqual(usage[\"total_tokens\"], 150)\n\n def test_extract_usage_with_none_input_tokens(self):\n \"\"\"Test token extraction when input_tokens is None (regression test for bug).\"\"\"\n response = Mock()\n response.usage_metadata = Mock()\n response.usage_metadata.prompt_token_count = None # This was causing crashes\n response.usage_metadata.candidates_token_count = 50\n\n usage = self.provider._extract_usage(response)\n\n # Should not include input_tokens when None\n self.assertNotIn(\"input_tokens\", usage)\n self.assertEqual(usage[\"output_tokens\"], 50)\n # Should not calculate total_tokens when input is None\n self.assertNotIn(\"total_tokens\", usage)\n\n def test_extract_usage_with_none_output_tokens(self):\n \"\"\"Test token extraction when output_tokens is None (regression test for bug).\"\"\"\n response = Mock()\n response.usage_metadata = Mock()\n response.usage_metadata.prompt_token_count = 100\n response.usage_metadata.candidates_token_count = None # This was causing crashes\n\n usage = self.provider._extract_usage(response)\n\n self.assertEqual(usage[\"input_tokens\"], 100)\n # Should not include output_tokens when None\n self.assertNotIn(\"output_tokens\", usage)\n # Should not calculate total_tokens when output is None\n self.assertNotIn(\"total_tokens\", usage)\n\n def test_extract_usage_with_both_none_tokens(self):\n \"\"\"Test token extraction when both token counts are None.\"\"\"\n response = Mock()\n response.usage_metadata = Mock()\n response.usage_metadata.prompt_token_count = None\n response.usage_metadata.candidates_token_count = None\n\n usage = self.provider._extract_usage(response)\n\n # Should return empty dict when all tokens are None\n self.assertEqual(usage, {})\n\n def test_extract_usage_without_usage_metadata(self):\n \"\"\"Test token extraction when response has no usage_metadata.\"\"\"\n response = Mock(spec=[])\n\n usage = self.provider._extract_usage(response)\n\n # Should return empty dict\n self.assertEqual(usage, {})\n\n def test_extract_usage_with_zero_tokens(self):\n \"\"\"Test token extraction with zero token counts.\"\"\"\n response = Mock()\n response.usage_metadata = Mock()\n response.usage_metadata.prompt_token_count = 0\n response.usage_metadata.candidates_token_count = 0\n\n usage = self.provider._extract_usage(response)\n\n self.assertEqual(usage[\"input_tokens\"], 0)\n self.assertEqual(usage[\"output_tokens\"], 0)\n self.assertEqual(usage[\"total_tokens\"], 0)\n\n def test_extract_usage_missing_attributes(self):\n \"\"\"Test token extraction when metadata lacks token count attributes.\"\"\"\n response = Mock()\n response.usage_metadata = Mock(spec=[])\n\n usage = self.provider._extract_usage(response)\n\n # Should return empty dict when attributes are missing\n self.assertEqual(usage, {})\n\n\nif __name__ == \"__main__\":\n unittest.main()\n" }, { "path": "tests/test_image_support_integration.py", "content": "\"\"\"\nIntegration tests for native image support feature.\n\nTests the complete image support pipeline:\n- Conversation memory integration with images\n- Tool request validation and schema support\n- Provider image processing capabilities\n- Cross-tool image context preservation\n\"\"\"\n\nimport os\nimport tempfile\nimport uuid\nfrom unittest.mock import Mock, patch\n\nimport pytest\n\nfrom tools.chat import ChatTool\nfrom tools.debug import DebugIssueTool\nfrom tools.shared.exceptions import ToolExecutionError\nfrom utils.conversation_memory import (\n ConversationTurn,\n ThreadContext,\n add_turn,\n create_thread,\n get_conversation_image_list,\n get_thread,\n)\nfrom utils.model_context import ModelContext\n\n\n@pytest.mark.no_mock_provider\nclass TestImageSupportIntegration:\n \"\"\"Integration tests for the complete image support feature.\"\"\"\n\n def test_conversation_turn_includes_images(self):\n \"\"\"Test that ConversationTurn can store and track images.\"\"\"\n turn = ConversationTurn(\n role=\"user\",\n content=\"Please analyze this diagram\",\n timestamp=\"2025-01-01T00:00:00Z\",\n files=[\"code.py\"],\n images=[\"diagram.png\", \"flowchart.jpg\"],\n tool_name=\"chat\",\n )\n\n assert turn.images == [\"diagram.png\", \"flowchart.jpg\"]\n assert turn.files == [\"code.py\"]\n assert turn.content == \"Please analyze this diagram\"\n\n def test_get_conversation_image_list_newest_first(self):\n \"\"\"Test that image list prioritizes newest references.\"\"\"\n # Create thread context with multiple turns\n context = ThreadContext(\n thread_id=str(uuid.uuid4()),\n created_at=\"2025-01-01T00:00:00Z\",\n last_updated_at=\"2025-01-01T00:00:00Z\",\n tool_name=\"chat\",\n turns=[\n ConversationTurn(\n role=\"user\",\n content=\"Turn 1\",\n timestamp=\"2025-01-01T00:00:00Z\",\n images=[\"old_diagram.png\", \"shared.png\"],\n ),\n ConversationTurn(\n role=\"assistant\", content=\"Turn 2\", timestamp=\"2025-01-01T01:00:00Z\", images=[\"middle.png\"]\n ),\n ConversationTurn(\n role=\"user\",\n content=\"Turn 3\",\n timestamp=\"2025-01-01T02:00:00Z\",\n images=[\"shared.png\", \"new_diagram.png\"], # shared.png appears again\n ),\n ],\n initial_context={},\n )\n\n image_list = get_conversation_image_list(context)\n\n # Should prioritize newest first, with duplicates removed (newest wins)\n expected = [\"shared.png\", \"new_diagram.png\", \"middle.png\", \"old_diagram.png\"]\n assert image_list == expected\n\n @patch(\"utils.conversation_memory.get_storage\")\n def test_add_turn_with_images(self, mock_storage):\n \"\"\"Test adding a conversation turn with images.\"\"\"\n mock_client = Mock()\n mock_storage.return_value = mock_client\n\n # Mock the Redis operations to return success\n mock_client.set.return_value = True\n\n thread_id = create_thread(\"test_tool\", {\"initial\": \"context\"})\n\n # Set up initial thread context for add_turn to find\n initial_context = ThreadContext(\n thread_id=thread_id,\n created_at=\"2025-01-01T00:00:00Z\",\n last_updated_at=\"2025-01-01T00:00:00Z\",\n tool_name=\"test_tool\",\n turns=[], # Empty initially\n initial_context={\"initial\": \"context\"},\n )\n mock_client.get.return_value = initial_context.model_dump_json()\n\n success = add_turn(\n thread_id=thread_id,\n role=\"user\",\n content=\"Analyze these screenshots\",\n files=[\"app.py\"],\n images=[\"screenshot1.png\", \"screenshot2.png\"],\n tool_name=\"debug\",\n )\n\n assert success\n\n # Mock thread context for get_thread call\n updated_context = ThreadContext(\n thread_id=thread_id,\n created_at=\"2025-01-01T00:00:00Z\",\n last_updated_at=\"2025-01-01T00:00:00Z\",\n tool_name=\"test_tool\",\n turns=[\n ConversationTurn(\n role=\"user\",\n content=\"Analyze these screenshots\",\n timestamp=\"2025-01-01T00:00:00Z\",\n files=[\"app.py\"],\n images=[\"screenshot1.png\", \"screenshot2.png\"],\n tool_name=\"debug\",\n )\n ],\n initial_context={\"initial\": \"context\"},\n )\n mock_client.get.return_value = updated_context.model_dump_json()\n\n # Retrieve and verify the thread\n context = get_thread(thread_id)\n assert context is not None\n assert len(context.turns) == 1\n\n turn = context.turns[0]\n assert turn.images == [\"screenshot1.png\", \"screenshot2.png\"]\n assert turn.files == [\"app.py\"]\n assert turn.content == \"Analyze these screenshots\"\n\n def test_chat_tool_schema_includes_images(self):\n \"\"\"Test that ChatTool schema includes images field.\"\"\"\n tool = ChatTool()\n schema = tool.get_input_schema()\n\n assert \"images\" in schema[\"properties\"]\n images_field = schema[\"properties\"][\"images\"]\n assert images_field[\"type\"] == \"array\"\n assert images_field[\"items\"][\"type\"] == \"string\"\n assert \"visual context\" in images_field[\"description\"].lower()\n\n def test_debug_tool_schema_includes_images(self):\n \"\"\"Test that DebugIssueTool schema includes images field.\"\"\"\n tool = DebugIssueTool()\n schema = tool.get_input_schema()\n\n assert \"images\" in schema[\"properties\"]\n images_field = schema[\"properties\"][\"images\"]\n assert images_field[\"type\"] == \"array\"\n assert images_field[\"items\"][\"type\"] == \"string\"\n assert \"screenshots\" in images_field[\"description\"].lower()\n\n def test_tool_image_validation_limits(self):\n \"\"\"Test that tools validate image size limits using real provider resolution.\"\"\"\n tool = ChatTool()\n\n # Create small test images (each 0.5MB, total 1MB)\n small_images = []\n for _ in range(2):\n with tempfile.NamedTemporaryFile(suffix=\".png\", delete=False) as temp_file:\n # Write 0.5MB of data\n temp_file.write(b\"\\x00\" * (512 * 1024))\n small_images.append(temp_file.name)\n\n try:\n # Test with an invalid model name that doesn't exist in any provider\n # Use model_context parameter name (not positional)\n result = tool._validate_image_limits(small_images, model_context=ModelContext(\"non-existent-model-12345\"))\n # Should return error because model not available or doesn't support images\n assert result is not None\n assert result[\"status\"] == \"error\"\n assert \"is not available\" in result[\"content\"] or \"does not support image processing\" in result[\"content\"]\n\n # Test that empty/None images always pass regardless of model\n result = tool._validate_image_limits([], model_context=ModelContext(\"gemini-2.5-pro\"))\n assert result is None\n\n result = tool._validate_image_limits(None, model_context=ModelContext(\"gemini-2.5-pro\"))\n assert result is None\n\n finally:\n # Clean up temp files\n for img_path in small_images:\n if os.path.exists(img_path):\n os.unlink(img_path)\n\n def test_image_validation_model_specific_limits(self):\n \"\"\"Test that different models have appropriate size limits using real provider resolution.\"\"\"\n tool = ChatTool()\n\n # Test with Gemini model which has better image support in test environment\n # Create 15MB image (under default limits)\n small_image_path = None\n large_image_path = None\n\n try:\n # Create 15MB image\n with tempfile.NamedTemporaryFile(suffix=\".png\", delete=False) as temp_file:\n temp_file.write(b\"\\x00\" * (15 * 1024 * 1024)) # 15MB\n small_image_path = temp_file.name\n\n # Test with the default model from test environment (gemini-2.5-flash)\n result = tool._validate_image_limits([small_image_path], ModelContext(\"gemini-2.5-flash\"))\n assert result is None # Should pass for Gemini models\n\n # Create 150MB image (over typical limits)\n with tempfile.NamedTemporaryFile(suffix=\".png\", delete=False) as temp_file:\n temp_file.write(b\"\\x00\" * (150 * 1024 * 1024)) # 150MB\n large_image_path = temp_file.name\n\n result = tool._validate_image_limits([large_image_path], ModelContext(\"gemini-2.5-flash\"))\n # Large images should fail validation\n assert result is not None\n assert result[\"status\"] == \"error\"\n assert \"Image size limit exceeded\" in result[\"content\"]\n\n finally:\n # Clean up temp files\n if small_image_path and os.path.exists(small_image_path):\n os.unlink(small_image_path)\n if large_image_path and os.path.exists(large_image_path):\n os.unlink(large_image_path)\n\n @pytest.mark.asyncio\n async def test_chat_tool_execution_with_images(self):\n \"\"\"Test that ChatTool can execute with images parameter using real provider resolution.\"\"\"\n import importlib\n\n # Create a temporary image file for testing\n with tempfile.NamedTemporaryFile(suffix=\".png\", delete=False) as temp_file:\n # Write a simple PNG header (minimal valid PNG)\n png_header = b\"\\x89PNG\\r\\n\\x1a\\n\\x00\\x00\\x00\\rIHDR\\x00\\x00\\x00\\x01\\x00\\x00\\x00\\x01\\x08\\x06\\x00\\x00\\x00\\x1f\\x15\\xc4\\x89\\x00\\x00\\x00\\rIDATx\\x9cc\\x00\\x01\\x00\\x00\\x05\\x00\\x01\\r\\n-\\xdb\\x00\\x00\\x00\\x00IEND\\xaeB`\\x82\"\n temp_file.write(png_header)\n temp_image_path = temp_file.name\n\n # Save original environment\n original_env = {\n \"OPENAI_API_KEY\": os.environ.get(\"OPENAI_API_KEY\"),\n \"DEFAULT_MODEL\": os.environ.get(\"DEFAULT_MODEL\"),\n }\n\n try:\n # Set up environment for real provider resolution\n os.environ[\"OPENAI_API_KEY\"] = \"sk-test-key-images-test-not-real\"\n os.environ[\"DEFAULT_MODEL\"] = \"gpt-4o\"\n\n # Clear other provider keys to isolate to OpenAI\n for key in [\"GEMINI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n import config\n\n importlib.reload(config)\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry._instance = None\n\n tool = ChatTool()\n\n # Test with real provider resolution\n with tempfile.TemporaryDirectory() as working_directory:\n with pytest.raises(ToolExecutionError) as exc_info:\n await tool.execute(\n {\n \"prompt\": \"What do you see in this image?\",\n \"images\": [temp_image_path],\n \"model\": \"gpt-4o\",\n \"working_directory_absolute_path\": working_directory,\n }\n )\n\n error_msg = exc_info.value.payload if hasattr(exc_info.value, \"payload\") else str(exc_info.value)\n\n # Should NOT be a mock-related error\n assert \"MagicMock\" not in error_msg\n assert \"'<' not supported between instances\" not in error_msg\n\n # Should be a real provider error (API key or network)\n assert any(\n phrase in error_msg\n for phrase in [\"API\", \"key\", \"authentication\", \"provider\", \"network\", \"connection\", \"401\", \"403\"]\n )\n\n finally:\n # Clean up temp file\n os.unlink(temp_image_path)\n\n # Restore environment\n for key, value in original_env.items():\n if value is not None:\n os.environ[key] = value\n else:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n importlib.reload(config)\n ModelProviderRegistry._instance = None\n\n @patch(\"utils.conversation_memory.get_storage\")\n def test_cross_tool_image_context_preservation(self, mock_storage):\n \"\"\"Test that images are preserved across different tools in conversation.\"\"\"\n mock_client = Mock()\n mock_storage.return_value = mock_client\n\n # Mock the Redis operations to return success\n mock_client.set.return_value = True\n\n # Create initial thread with chat tool\n thread_id = create_thread(\"chat\", {\"initial\": \"context\"})\n\n # Set up initial thread context for add_turn to find\n initial_context = ThreadContext(\n thread_id=thread_id,\n created_at=\"2025-01-01T00:00:00Z\",\n last_updated_at=\"2025-01-01T00:00:00Z\",\n tool_name=\"chat\",\n turns=[], # Empty initially\n initial_context={\"initial\": \"context\"},\n )\n mock_client.get.return_value = initial_context.model_dump_json()\n\n # Add turn with images from chat tool\n add_turn(\n thread_id=thread_id,\n role=\"user\",\n content=\"Here's my UI design\",\n images=[\"design.png\", \"mockup.jpg\"],\n tool_name=\"chat\",\n )\n\n add_turn(\n thread_id=thread_id, role=\"assistant\", content=\"I can see your design. It looks good!\", tool_name=\"chat\"\n )\n\n # Add turn with different images from debug tool\n add_turn(\n thread_id=thread_id,\n role=\"user\",\n content=\"Now I'm getting this error\",\n images=[\"error_screen.png\"],\n files=[\"error.log\"],\n tool_name=\"debug\",\n )\n\n # Mock complete thread context for get_thread call\n complete_context = ThreadContext(\n thread_id=thread_id,\n created_at=\"2025-01-01T00:00:00Z\",\n last_updated_at=\"2025-01-01T00:05:00Z\",\n tool_name=\"chat\",\n turns=[\n ConversationTurn(\n role=\"user\",\n content=\"Here's my UI design\",\n timestamp=\"2025-01-01T00:01:00Z\",\n images=[\"design.png\", \"mockup.jpg\"],\n tool_name=\"chat\",\n ),\n ConversationTurn(\n role=\"assistant\",\n content=\"I can see your design. It looks good!\",\n timestamp=\"2025-01-01T00:02:00Z\",\n tool_name=\"chat\",\n ),\n ConversationTurn(\n role=\"user\",\n content=\"Now I'm getting this error\",\n timestamp=\"2025-01-01T00:03:00Z\",\n images=[\"error_screen.png\"],\n files=[\"error.log\"],\n tool_name=\"debug\",\n ),\n ],\n initial_context={\"initial\": \"context\"},\n )\n mock_client.get.return_value = complete_context.model_dump_json()\n\n # Retrieve thread and check image preservation\n context = get_thread(thread_id)\n assert context is not None\n\n # Get conversation image list (should prioritize newest first)\n image_list = get_conversation_image_list(context)\n expected = [\"error_screen.png\", \"design.png\", \"mockup.jpg\"]\n assert image_list == expected\n\n # Verify each turn has correct images\n assert context.turns[0].images == [\"design.png\", \"mockup.jpg\"]\n assert context.turns[1].images is None # Assistant turn without images\n assert context.turns[2].images == [\"error_screen.png\"]\n\n def test_tool_request_base_class_has_images(self):\n \"\"\"Test that base ToolRequest class includes images field.\"\"\"\n from tools.shared.base_models import ToolRequest\n\n # Create request with images\n request = ToolRequest(images=[\"test.png\", \"test2.jpg\"])\n assert request.images == [\"test.png\", \"test2.jpg\"]\n\n # Test default value\n request_no_images = ToolRequest()\n assert request_no_images.images is None\n\n def test_data_url_image_format_support(self):\n \"\"\"Test that tools can handle data URL format images.\"\"\"\n tool = ChatTool()\n\n # Test with data URL (base64 encoded 1x1 transparent PNG)\n data_url = \"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==\"\n images = [data_url]\n\n # Test with a dummy model that doesn't exist in any provider\n result = tool._validate_image_limits(images, ModelContext(\"test-dummy-model-name\"))\n # Should return error because model not available or doesn't support images\n assert result is not None\n assert result[\"status\"] == \"error\"\n assert \"is not available\" in result[\"content\"] or \"does not support image processing\" in result[\"content\"]\n\n # Test with another non-existent model to check error handling\n result = tool._validate_image_limits(images, ModelContext(\"another-dummy-model\"))\n # Should return error because model not available\n assert result is not None\n assert result[\"status\"] == \"error\"\n\n def test_empty_images_handling(self):\n \"\"\"Test that tools handle empty images lists gracefully.\"\"\"\n tool = ChatTool()\n\n # Empty list should not fail validation (no need for provider setup)\n result = tool._validate_image_limits([], ModelContext(\"gemini-2.5-pro\"))\n assert result is None\n\n # None should not fail validation (no need for provider setup)\n result = tool._validate_image_limits(None, ModelContext(\"gemini-2.5-pro\"))\n assert result is None\n\n @patch(\"utils.conversation_memory.get_storage\")\n def test_conversation_memory_thread_chaining_with_images(self, mock_storage):\n \"\"\"Test that images work correctly with conversation thread chaining.\"\"\"\n mock_client = Mock()\n mock_storage.return_value = mock_client\n\n # Mock the Redis operations to return success\n mock_client.set.return_value = True\n\n # Create parent thread with images\n parent_thread_id = create_thread(\"chat\", {\"parent\": \"context\"})\n\n # Set up initial parent thread context for add_turn to find\n parent_context = ThreadContext(\n thread_id=parent_thread_id,\n created_at=\"2025-01-01T00:00:00Z\",\n last_updated_at=\"2025-01-01T00:00:00Z\",\n tool_name=\"chat\",\n turns=[], # Empty initially\n initial_context={\"parent\": \"context\"},\n )\n mock_client.get.return_value = parent_context.model_dump_json()\n add_turn(\n thread_id=parent_thread_id,\n role=\"user\",\n content=\"Parent thread with images\",\n images=[\"parent1.png\", \"shared.png\"],\n tool_name=\"chat\",\n )\n\n # Create child thread linked to parent using a simple tool\n child_thread_id = create_thread(\"chat\", {\"prompt\": \"child context\"}, parent_thread_id=parent_thread_id)\n add_turn(\n thread_id=child_thread_id,\n role=\"user\",\n content=\"Child thread with more images\",\n images=[\"child1.png\", \"shared.png\"], # shared.png appears again (should prioritize newer)\n tool_name=\"chat\",\n )\n\n # Mock child thread context for get_thread call\n child_context = ThreadContext(\n thread_id=child_thread_id,\n created_at=\"2025-01-01T00:00:00Z\",\n last_updated_at=\"2025-01-01T00:02:00Z\",\n tool_name=\"debug\",\n turns=[\n ConversationTurn(\n role=\"user\",\n content=\"Child thread with more images\",\n timestamp=\"2025-01-01T00:02:00Z\",\n images=[\"child1.png\", \"shared.png\"],\n tool_name=\"debug\",\n )\n ],\n initial_context={\"child\": \"context\"},\n parent_thread_id=parent_thread_id,\n )\n mock_client.get.return_value = child_context.model_dump_json()\n\n # Get child thread and verify image collection works across chain\n child_context = get_thread(child_thread_id)\n assert child_context is not None\n assert child_context.parent_thread_id == parent_thread_id\n\n # Test image collection for child thread only\n child_images = get_conversation_image_list(child_context)\n assert child_images == [\"child1.png\", \"shared.png\"]\n" }, { "path": "tests/test_image_validation.py", "content": "\"\"\"Tests for image validation utility helpers.\"\"\"\n\nimport base64\nimport os\nimport tempfile\nfrom unittest.mock import Mock, patch\n\nimport pytest\n\nfrom utils.image_utils import DEFAULT_MAX_IMAGE_SIZE_MB, validate_image\n\n\nclass TestImageValidation:\n \"\"\"Test suite for image validation functionality.\"\"\"\n\n def test_validate_data_url_valid(self) -> None:\n \"\"\"Test validation of valid data URL.\"\"\"\n # Create a small test image (1x1 PNG)\n test_image_data = base64.b64decode(\n \"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==\"\n )\n data_url = f\"data:image/png;base64,{base64.b64encode(test_image_data).decode()}\"\n\n image_bytes, mime_type = validate_image(data_url)\n\n assert image_bytes == test_image_data\n assert mime_type == \"image/png\"\n\n @pytest.mark.parametrize(\n \"invalid_url,expected_error\",\n [\n (\"data:image/png\", \"Invalid data URL format\"), # Missing base64 part\n (\"data:image/png;base64\", \"Invalid data URL format\"), # Missing data\n (\"data:text/plain;base64,dGVzdA==\", \"Unsupported image type\"), # Not an image\n ],\n )\n def test_validate_data_url_invalid_format(self, invalid_url: str, expected_error: str) -> None:\n \"\"\"Test validation of malformed data URL.\"\"\"\n with pytest.raises(ValueError) as excinfo:\n validate_image(invalid_url)\n assert expected_error in str(excinfo.value)\n\n def test_non_data_url_treated_as_file_path(self) -> None:\n \"\"\"Test that non-data URLs are treated as file paths.\"\"\"\n # Test case that's not a data URL at all\n with pytest.raises(ValueError) as excinfo:\n validate_image(\"image/png;base64,abc123\")\n assert \"Image file not found\" in str(excinfo.value) # Treated as file path\n\n def test_validate_data_url_unsupported_type(self) -> None:\n \"\"\"Test validation of unsupported image type in data URL.\"\"\"\n data_url = \"data:image/bmp;base64,Qk0=\" # BMP format\n\n with pytest.raises(ValueError) as excinfo:\n validate_image(data_url)\n assert \"Unsupported image type: image/bmp\" in str(excinfo.value)\n\n def test_validate_data_url_invalid_base64(self) -> None:\n \"\"\"Test validation of data URL with invalid base64.\"\"\"\n data_url = \"data:image/png;base64,@@@invalid@@@\"\n\n with pytest.raises(ValueError) as excinfo:\n validate_image(data_url)\n assert \"Invalid base64 data\" in str(excinfo.value)\n\n def test_validate_large_data_url(self) -> None:\n \"\"\"Test validation of large data URL to ensure size limits work.\"\"\"\n # Create a large image (21MB)\n large_data = b\"x\" * (21 * 1024 * 1024) # 21MB\n\n # Encode as base64 and create data URL\n import base64\n\n encoded_data = base64.b64encode(large_data).decode()\n data_url = f\"data:image/png;base64,{encoded_data}\"\n\n # Should fail with default 20MB limit\n with pytest.raises(ValueError) as excinfo:\n validate_image(data_url)\n assert f\"Image too large: 21.0MB (max: {DEFAULT_MAX_IMAGE_SIZE_MB:.1f}MB)\" in str(excinfo.value)\n\n # Should succeed with higher limit\n image_bytes, mime_type = validate_image(data_url, max_size_mb=25.0)\n assert len(image_bytes) == len(large_data)\n assert mime_type == \"image/png\"\n\n def test_validate_file_path_valid(self) -> None:\n \"\"\"Test validation of valid image file.\"\"\"\n # Create a temporary image file\n with tempfile.NamedTemporaryFile(suffix=\".png\", delete=False) as tmp_file:\n # Write a small test PNG\n test_image_data = base64.b64decode(\n \"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==\"\n )\n tmp_file.write(test_image_data)\n tmp_file_path = tmp_file.name\n\n try:\n image_bytes, mime_type = validate_image(tmp_file_path)\n\n assert image_bytes == test_image_data\n assert mime_type == \"image/png\"\n finally:\n os.unlink(tmp_file_path)\n\n def test_validate_file_path_not_found(self) -> None:\n \"\"\"Test validation of non-existent file.\"\"\"\n with pytest.raises(ValueError) as excinfo:\n validate_image(\"/path/to/nonexistent/image.png\")\n assert \"Image file not found\" in str(excinfo.value)\n\n def test_validate_file_path_unsupported_extension(self) -> None:\n \"\"\"Test validation of file with unsupported extension.\"\"\"\n with tempfile.NamedTemporaryFile(suffix=\".bmp\", delete=False) as tmp_file:\n tmp_file.write(b\"dummy data\")\n tmp_file_path = tmp_file.name\n\n try:\n with pytest.raises(ValueError) as excinfo:\n validate_image(tmp_file_path)\n assert \"Unsupported image format: .bmp\" in str(excinfo.value)\n finally:\n os.unlink(tmp_file_path)\n\n def test_validate_file_path_read_error(self) -> None:\n \"\"\"Test validation when file cannot be read.\"\"\"\n with tempfile.NamedTemporaryFile(suffix=\".png\", delete=False) as tmp_file:\n tmp_file_path = tmp_file.name\n\n # Remove the file but keep the path\n os.unlink(tmp_file_path)\n\n with pytest.raises(ValueError) as excinfo:\n validate_image(tmp_file_path)\n assert \"Image file not found\" in str(excinfo.value)\n\n def test_validate_image_size_limit(self) -> None:\n \"\"\"Test validation of image size limits.\"\"\"\n # Create a large \"image\" (just random data)\n large_data = b\"x\" * (21 * 1024 * 1024) # 21MB\n\n with tempfile.NamedTemporaryFile(suffix=\".png\", delete=False) as tmp_file:\n tmp_file.write(large_data)\n tmp_file_path = tmp_file.name\n\n try:\n with pytest.raises(ValueError) as excinfo:\n validate_image(tmp_file_path, max_size_mb=20.0)\n assert \"Image too large: 21.0MB (max: 20.0MB)\" in str(excinfo.value)\n finally:\n os.unlink(tmp_file_path)\n\n def test_validate_image_custom_size_limit(self) -> None:\n \"\"\"Test validation with custom size limit.\"\"\"\n # Create a 2MB \"image\"\n data = b\"x\" * (2 * 1024 * 1024)\n\n with tempfile.NamedTemporaryFile(suffix=\".png\", delete=False) as tmp_file:\n tmp_file.write(data)\n tmp_file_path = tmp_file.name\n\n try:\n # Should fail with 1MB limit\n with pytest.raises(ValueError) as excinfo:\n validate_image(tmp_file_path, max_size_mb=1.0)\n assert \"Image too large: 2.0MB (max: 1.0MB)\" in str(excinfo.value)\n\n # Should succeed with 3MB limit\n image_bytes, mime_type = validate_image(tmp_file_path, max_size_mb=3.0)\n assert len(image_bytes) == len(data)\n assert mime_type == \"image/png\"\n finally:\n os.unlink(tmp_file_path)\n\n def test_validate_image_default_size_limit(self) -> None:\n \"\"\"Test validation with default size limit (None).\"\"\"\n # Create a small image that's under the default limit\n data = b\"x\" * (1024 * 1024) # 1MB\n\n with tempfile.NamedTemporaryFile(suffix=\".jpg\", delete=False) as tmp_file:\n tmp_file.write(data)\n tmp_file_path = tmp_file.name\n\n try:\n # Should succeed with default limit (20MB)\n image_bytes, mime_type = validate_image(tmp_file_path)\n assert len(image_bytes) == len(data)\n assert mime_type == \"image/jpeg\"\n\n # Should also succeed when explicitly passing None\n image_bytes, mime_type = validate_image(tmp_file_path, max_size_mb=None)\n assert len(image_bytes) == len(data)\n assert mime_type == \"image/jpeg\"\n finally:\n os.unlink(tmp_file_path)\n\n def test_validate_all_supported_formats(self) -> None:\n \"\"\"Test validation of all supported image formats.\"\"\"\n supported_formats = {\n \".png\": \"image/png\",\n \".jpg\": \"image/jpeg\",\n \".jpeg\": \"image/jpeg\",\n \".gif\": \"image/gif\",\n \".webp\": \"image/webp\",\n }\n\n for ext, expected_mime in supported_formats.items():\n with tempfile.NamedTemporaryFile(suffix=ext, delete=False) as tmp_file:\n tmp_file.write(b\"dummy image data\")\n tmp_file_path = tmp_file.name\n\n try:\n image_bytes, mime_type = validate_image(tmp_file_path)\n assert mime_type == expected_mime\n assert image_bytes == b\"dummy image data\"\n finally:\n os.unlink(tmp_file_path)\n\n\nclass TestProviderIntegration:\n \"\"\"Test image validation integration with different providers.\"\"\"\n\n @patch(\"providers.gemini.logger\")\n def test_gemini_provider_uses_validation(self, mock_logger: Mock) -> None:\n \"\"\"Test that Gemini provider uses the base validation.\"\"\"\n from providers.gemini import GeminiModelProvider\n\n # Create a provider instance\n provider = GeminiModelProvider(api_key=\"test-key\")\n\n # Test with non-existent file\n result = provider._process_image(\"/nonexistent/image.png\")\n assert result is None\n mock_logger.warning.assert_called_with(\"Image file not found: /nonexistent/image.png\")\n\n @patch(\"providers.openai_compatible.logging\")\n def test_openai_compatible_provider_uses_validation(self, mock_logging: Mock) -> None:\n \"\"\"Test that OpenAI-compatible providers use the base validation.\"\"\"\n from providers.xai import XAIModelProvider\n\n # Create a provider instance (XAI inherits from OpenAICompatibleProvider)\n provider = XAIModelProvider(api_key=\"test-key\")\n\n # Test with non-existent file\n result = provider._process_image(\"/nonexistent/image.png\")\n assert result is None\n mock_logging.warning.assert_called_with(\"Image file not found: /nonexistent/image.png\")\n\n def test_data_url_preservation(self) -> None:\n \"\"\"Test that data URLs are properly preserved through validation.\"\"\"\n from providers.xai import XAIModelProvider\n\n provider = XAIModelProvider(api_key=\"test-key\")\n\n # Valid data URL\n data_url = \"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNkYPhfDwAChwGA60e6kgAAAABJRU5ErkJggg==\"\n\n result = provider._process_image(data_url)\n assert result is not None\n assert result[\"type\"] == \"image_url\"\n assert result[\"image_url\"][\"url\"] == data_url\n" }, { "path": "tests/test_integration_utf8.py", "content": "\"\"\"\nFull integration test script to validate UTF-8 implementation\nand French localization.\n\nThis script runs all unit tests and checks full integration.\n\"\"\"\n\nimport json\nimport os\nimport subprocess\nimport sys\nimport tempfile\nfrom pathlib import Path\n\n\ndef run_utf8_integration_tests():\n \"\"\"Run UTF-8 integration tests.\"\"\"\n print(\"πŸš€ Starting UTF-8 integration tests\")\n print(\"=\" * 60)\n\n # Test environment setup\n os.environ[\"LOCALE\"] = \"fr-FR\"\n os.environ[\"GEMINI_API_KEY\"] = \"dummy-key-for-tests\"\n os.environ[\"OPENAI_API_KEY\"] = \"dummy-key-for-tests\"\n\n # Test 1: Validate UTF-8 characters in json.dumps\n print(\"\\n1️⃣ UTF-8 encoding test with json.dumps\")\n test_utf8_json_encoding()\n\n # Test 2: Validate language instruction generation\n print(\"\\n2️⃣ Language instruction generation test\")\n test_language_instruction_generation()\n\n # Test 3: Validate UTF-8 file handling\n print(\"\\n3️⃣ UTF-8 file handling test\")\n test_file_utf8_handling()\n\n # Test 4: Validate MCP tools integration\n print(\"\\n4️⃣ MCP tools integration test\")\n test_mcp_tools_integration()\n\n # Test 5: Run unit tests\n print(\"\\n5️⃣ Running unit tests\")\n run_unit_tests()\n\n print(\"\\nβœ… All UTF-8 integration tests completed!\")\n print(\"πŸ‡«πŸ‡· French localization works correctly!\")\n\n\ndef test_utf8_json_encoding():\n \"\"\"Test UTF-8 encoding with json.dumps(ensure_ascii=False).\"\"\"\n print(\" Testing UTF-8 JSON encoding...\")\n\n # Test data with French characters and emojis\n test_data = {\n \"analyse\": {\n \"statut\": \"terminΓ©e\",\n \"rΓ©sultat\": \"Aucun problΓ¨me critique dΓ©tectΓ©\",\n \"recommandations\": [\n \"AmΓ©liorer la documentation\",\n \"Optimiser les performances\",\n \"Ajouter des tests unitaires\",\n ],\n \"mΓ©tadonnΓ©es\": {\n \"créé_par\": \"DΓ©veloppeur Principal\",\n \"date_crΓ©ation\": \"2024-01-01\",\n \"derniΓ¨re_modification\": \"2024-01-15\",\n },\n \"Γ©mojis_status\": {\n \"critique\": \"πŸ”΄\",\n \"Γ©levΓ©\": \"🟠\",\n \"moyen\": \"🟑\",\n \"faible\": \"🟒\",\n \"succΓ¨s\": \"βœ…\",\n \"erreur\": \"❌\",\n },\n },\n \"outils\": [\n {\"nom\": \"analyse\", \"description\": \"Analyse architecturale avancΓ©e\"},\n {\"nom\": \"rΓ©vision\", \"description\": \"RΓ©vision de code automatisΓ©e\"},\n {\"nom\": \"gΓ©nΓ©ration\", \"description\": \"GΓ©nΓ©ration de documentation\"},\n ],\n }\n\n # Test with ensure_ascii=False\n json_correct = json.dumps(test_data, ensure_ascii=False, indent=2)\n\n # Checks\n utf8_terms = [\n \"terminΓ©e\",\n \"rΓ©sultat\",\n \"dΓ©tectΓ©\",\n \"AmΓ©liorer\",\n \"créé_par\",\n \"DΓ©veloppeur\",\n \"crΓ©ation\",\n \"mΓ©tadonnΓ©es\",\n \"derniΓ¨re\",\n \"Γ©mojis_status\",\n \"Γ©levΓ©\",\n \"rΓ©vision\",\n \"gΓ©nΓ©ration\",\n ]\n\n emojis = [\"πŸ”΄\", \"🟠\", \"🟑\", \"🟒\", \"βœ…\", \"❌\"]\n\n for term in utf8_terms:\n assert term in json_correct, f\"Missing UTF-8 term: {term}\"\n\n for emoji in emojis:\n assert emoji in json_correct, f\"Missing emoji: {emoji}\"\n\n # Check for escaped characters\n assert \"\\\\u\" not in json_correct, \"Escaped Unicode characters detected!\"\n\n # Test parsing\n parsed = json.loads(json_correct)\n assert parsed[\"analyse\"][\"statut\"] == \"terminΓ©e\"\n assert parsed[\"analyse\"][\"Γ©mojis_status\"][\"critique\"] == \"πŸ”΄\"\n\n print(\" βœ… UTF-8 JSON encoding: SUCCESS\")\n\n\ndef test_language_instruction_generation():\n \"\"\"Test language instruction generation.\"\"\"\n print(\" Testing language instruction generation...\")\n\n # Simulation of get_language_instruction\n def get_language_instruction():\n locale = os.getenv(\"LOCALE\", \"\").strip()\n if not locale:\n return \"\"\n return f\"Always respond in {locale}.\\n\\n\"\n\n # Test with different locales\n test_locales = [\n (\"fr-FR\", \"French\"),\n (\"en-US\", \"English\"),\n (\"es-ES\", \"Spanish\"),\n (\"de-DE\", \"German\"),\n (\"\", \"none\"),\n ]\n\n for locale, description in test_locales:\n os.environ[\"LOCALE\"] = locale\n instruction = get_language_instruction()\n\n if locale:\n assert locale in instruction, f\"Missing {locale} in instruction\"\n assert instruction.endswith(\"\\n\\n\"), \"Incorrect instruction format\"\n print(f\" πŸ“ {description}: {instruction.strip()}\")\n else:\n assert instruction == \"\", \"Empty instruction expected for empty locale\"\n print(f\" πŸ“ {description}: (empty)\")\n\n # Restore French locale\n os.environ[\"LOCALE\"] = \"fr-FR\"\n print(\" βœ… Language instruction generation: SUCCESS\")\n\n\ndef test_file_utf8_handling():\n \"\"\"Test handling of files with UTF-8 content.\"\"\"\n print(\" Testing UTF-8 file handling...\")\n\n # File content with French characters\n french_content = '''#!/usr/bin/env python3\n\"\"\"\nModule de gestion des prΓ©fΓ©rences utilisateur.\nDΓ©veloppΓ© par: Γ‰quipe Technique\nDate de crΓ©ation: 15 dΓ©cembre 2024\n\"\"\"\n\nimport json\nfrom typing import Dict, Optional\n\nclass GestionnairePreferences:\n \"\"\"Gestionnaire des prΓ©fΓ©rences utilisateur avec support UTF-8.\"\"\"\n\n def __init__(self):\n self.donnΓ©es = {}\n self.historique = []\n\n def dΓ©finir_prΓ©fΓ©rence(self, clΓ©: str, valeur) -> bool:\n \"\"\"\n DΓ©finit une prΓ©fΓ©rence utilisateur.\n\n Args:\n clΓ©: Identifiant de la prΓ©fΓ©rence\n valeur: Valeur Γ  enregistrer\n\n Returns:\n True si la prΓ©fΓ©rence a Γ©tΓ© dΓ©finie avec succΓ¨s\n \"\"\"\n try:\n self.donnΓ©es[clΓ©] = valeur\n self.historique.append({\n \"action\": \"dΓ©finition\",\n \"clΓ©\": clΓ©,\n \"horodatage\": \"2024-01-01T12:00:00Z\"\n })\n return True\n except Exception as e:\n print(f\"Error setting preference: {e}\")\n return False\n\n def obtenir_prΓ©fΓ©rence(self, clΓ©: str) -> Optional:\n \"\"\"RΓ©cupΓ¨re une prΓ©fΓ©rence par sa clΓ©.\"\"\"\n return self.donnΓ©es.get(clΓ©)\n\n def exporter_donnΓ©es(self) -> str:\n \"\"\"Exporte les donnΓ©es en JSON UTF-8.\"\"\"\n return json.dumps(self.donnΓ©es, ensure_ascii=False, indent=2)\n\n# Configuration par dΓ©faut avec caractΓ¨res UTF-8\nCONFIG_DΓ‰FAUT = {\n \"langue\": \"franΓ§ais\",\n \"rΓ©gion\": \"France\",\n \"thΓ¨me\": \"sombre\",\n \"notifications\": \"activΓ©es\"\n}\n\ndef crΓ©er_gestionnaire() -> GestionnairePreferences:\n \"\"\"CrΓ©e une instance du gestionnaire.\"\"\"\n gestionnaire = GestionnairePreferences()\n\n # Application de la configuration par dΓ©faut\n for clΓ©, valeur in CONFIG_DΓ‰FAUT.items():\n gestionnaire.dΓ©finir_prΓ©fΓ©rence(clΓ©, valeur)\n\n return gestionnaire\n\nif __name__ == \"__main__\":\n # Test d'utilisation\n gestionnaire = crΓ©er_gestionnaire()\n print(\"Gestionnaire créé avec succΓ¨s! πŸŽ‰\")\n print(f\"DonnΓ©es: {gestionnaire.exporter_donnΓ©es()}\")\n'''\n\n # Test writing and reading UTF-8\n with tempfile.NamedTemporaryFile(mode=\"w\", encoding=\"utf-8\", suffix=\".py\", delete=False) as f:\n f.write(french_content)\n temp_file = f.name\n\n try:\n # Test reading\n with open(temp_file, encoding=\"utf-8\") as f:\n read_content = f.read()\n\n # Checks\n assert read_content == french_content, \"Altered UTF-8 content\"\n\n # Check specific terms\n utf8_terms = [\n \"prΓ©fΓ©rences\",\n \"DΓ©veloppΓ©\",\n \"Γ‰quipe\",\n \"crΓ©ation\",\n \"donnΓ©es\",\n \"dΓ©finir_prΓ©fΓ©rence\",\n \"horodatage\",\n \"RΓ©cupΓ¨re\",\n \"franΓ§ais\",\n \"activΓ©es\",\n \"crΓ©er_gestionnaire\",\n \"succΓ¨s\",\n ]\n\n for term in utf8_terms:\n assert term in read_content, f\"Missing UTF-8 term: {term}\"\n\n print(\" βœ… UTF-8 file handling: SUCCESS\")\n\n finally:\n # Cleanup\n os.unlink(temp_file)\n\n\ndef test_mcp_tools_integration():\n \"\"\"Test MCP tools integration with UTF-8.\"\"\"\n print(\" Testing MCP tools integration...\")\n\n # Simulation of MCP tool response\n def simulate_mcp_tool_response():\n \"\"\"Simulate MCP tool response with UTF-8 content.\"\"\"\n response_data = {\n \"status\": \"success\",\n \"content_type\": \"markdown\",\n \"content\": \"\"\"# Analyse TerminΓ©e avec SuccΓ¨s βœ…\n\n## RΓ©sumΓ© de l'Analyse\n\nL'analyse architecturale du projet a Γ©tΓ© **terminΓ©e** avec succΓ¨s. Voici les principaux rΓ©sultats :\n\n### 🎯 Objectifs Atteints\n- βœ… RΓ©vision complΓ¨te du code\n- βœ… Identification des problΓ¨mes de performance\n- βœ… Recommandations d'amΓ©lioration gΓ©nΓ©rΓ©es\n\n### πŸ“Š MΓ©triques AnalysΓ©es\n| MΓ©trique | Valeur | Statut |\n|----------|--------|--------|\n| ComplexitΓ© cyclomatique | 12 | 🟑 Acceptable |\n| Couverture de tests | 85% | 🟒 Bon |\n| DΓ©pendances externes | 23 | 🟠 Γ€ rΓ©viser |\n\n### πŸ” ProblΓ¨mes IdentifiΓ©s\n\n#### πŸ”΄ Critique\nAucun problΓ¨me critique dΓ©tectΓ©.\n\n#### 🟠 Γ‰levΓ©\n1. **Performance des requΓͺtes** : Optimisation nΓ©cessaire\n2. **Gestion mΓ©moire** : Fuites potentielles dΓ©tectΓ©es\n\n#### 🟑 Moyen\n1. **Documentation** : Certaines fonctions manquent de commentaires\n2. **Tests unitaires** : Couverture Γ  amΓ©liorer\n\n### οΏ½ DΓ©tails de l'Analyse\n\nPour plus de dΓ©tails sur chaque problΓ¨me identifiΓ©, consultez les recommandations ci-dessous.\n\n### οΏ½πŸš€ Recommandations Prioritaires\n\n1. **Optimisation DB** : ImplΓ©menter un cache Redis\n2. **Refactoring** : SΓ©parer les responsabilitΓ©s\n3. **Documentation** : Ajouter les docstrings manquantes\n4. **Tests** : Augmenter la couverture Γ  90%+\n\n### πŸ“ˆ Prochaines Γ‰tapes\n\n- [ ] ImplΓ©menter le systΓ¨me de cache\n- [ ] Refactorer les modules identifiΓ©s\n- [ ] ComplΓ©ter la documentation\n- [ ] ExΓ©cuter les tests de rΓ©gression\n\n---\n*Analyse gΓ©nΓ©rΓ©e automatiquement par MCP PAL* πŸ€–\n\"\"\",\n \"metadata\": {\n \"tool_name\": \"analyze\",\n \"execution_time\": 2.5,\n \"locale\": \"fr-FR\",\n \"timestamp\": \"2024-01-01T12:00:00Z\",\n \"analysis_summary\": {\n \"files_analyzed\": 15,\n \"issues_found\": 4,\n \"recommendations\": 4,\n \"overall_score\": \"B+ (Good level)\",\n },\n },\n \"continuation_offer\": {\n \"continuation_id\": \"analysis-123\",\n \"note\": \"In-depth analysis available with more details\",\n },\n }\n\n # Serialization with ensure_ascii=False\n json_response = json.dumps(response_data, ensure_ascii=False, indent=2)\n\n # UTF-8 checks\n utf8_checks = [\n \"TerminΓ©e\",\n \"SuccΓ¨s\",\n \"RΓ©sumΓ©\",\n \"terminΓ©e\",\n \"Atteints\",\n \"RΓ©vision\",\n \"problΓ¨mes\",\n \"gΓ©nΓ©rΓ©es\",\n \"MΓ©triques\",\n \"IdentifiΓ©s\",\n \"dΓ©tectΓ©\",\n \"Γ‰levΓ©\",\n \"nΓ©cessaire\",\n \"dΓ©tectΓ©es\",\n \"amΓ©liorer\",\n \"Prioritaires\",\n \"responsabilitΓ©s\",\n \"Γ‰tapes\",\n \"rΓ©gression\",\n \"gΓ©nΓ©rΓ©e\",\n \"dΓ©tails\",\n ]\n\n for term in utf8_checks:\n assert term in json_response, f\"Missing UTF-8 term: {term}\"\n\n # Emoji check\n emojis = [\"βœ…\", \"🎯\", \"πŸ“Š\", \"🟑\", \"🟒\", \"🟠\", \"πŸ”\", \"πŸ”΄\", \"πŸš€\", \"πŸ“ˆ\", \"πŸ€–\"]\n for emoji in emojis:\n assert emoji in json_response, f\"Missing emoji: {emoji}\"\n\n # Test parsing\n parsed = json.loads(json_response)\n assert parsed[\"status\"] == \"success\"\n assert \"TerminΓ©e\" in parsed[\"content\"]\n assert parsed[\"metadata\"][\"locale\"] == \"fr-FR\"\n\n return json_response\n\n # Test simulation\n response = simulate_mcp_tool_response()\n assert len(response) > 1000, \"MCP response too short\"\n\n print(\" βœ… MCP tools integration: SUCCESS\")\n\n\ndef run_unit_tests():\n \"\"\"Run unit tests.\"\"\"\n print(\" Running unit tests...\")\n\n # List of test files to run\n test_files = [\"test_utf8_localization.py\", \"test_provider_utf8.py\", \"test_workflow_utf8.py\"]\n\n current_dir = Path(__file__).parent\n test_results = []\n\n for test_file in test_files:\n test_path = current_dir / test_file\n if test_path.exists():\n print(f\" πŸ“ Running {test_file}...\")\n try:\n # Test execution\n result = subprocess.run(\n [sys.executable, \"-m\", \"unittest\", test_file.replace(\".py\", \"\"), \"-v\"],\n cwd=current_dir,\n capture_output=True,\n text=True,\n timeout=60,\n )\n\n if result.returncode == 0:\n print(f\" βœ… {test_file}: SUCCESS\")\n test_results.append((test_file, \"SUCCESS\"))\n else:\n print(f\" ❌ {test_file}: FAILURE\")\n print(f\" Error: {result.stderr[:200]}...\")\n test_results.append((test_file, \"FAILURE\"))\n\n except subprocess.TimeoutExpired:\n print(f\" ⏰ {test_file}: TIMEOUT\")\n test_results.append((test_file, \"TIMEOUT\"))\n except Exception as e:\n print(f\" πŸ’₯ {test_file}: ERROR - {e}\")\n test_results.append((test_file, \"ERROR\"))\n else:\n print(f\" ⚠️ {test_file}: NOT FOUND\")\n test_results.append((test_file, \"NOT FOUND\"))\n\n # Test summary\n print(\"\\n πŸ“‹ Unit test summary:\")\n for test_file, status in test_results:\n status_emoji = {\"SUCCESS\": \"βœ…\", \"FAILURE\": \"❌\", \"TIMEOUT\": \"⏰\", \"ERROR\": \"πŸ’₯\", \"NOT FOUND\": \"⚠️\"}.get(\n status, \"❓\"\n )\n print(f\" {status_emoji} {test_file}: {status}\")\n\n\ndef main():\n \"\"\"Main function.\"\"\"\n print(\"πŸ‡«πŸ‡· UTF-8 Integration Test - PAL MCP Server\")\n print(\"=\" * 60)\n\n try:\n run_utf8_integration_tests()\n print(\"\\nπŸŽ‰ SUCCESS: All UTF-8 integration tests passed!\")\n print(\"πŸš€ PAL MCP Server fully supports French localization!\")\n return 0\n\n except AssertionError as e:\n print(f\"\\n❌ FAILURE: Assertion test failed: {e}\")\n return 1\n\n except Exception as e:\n print(f\"\\nπŸ’₯ ERROR: Unexpected exception: {e}\")\n return 1\n\n\nif __name__ == \"__main__\":\n sys.exit(main())\n" }, { "path": "tests/test_intelligent_fallback.py", "content": "\"\"\"\nTest suite for intelligent auto mode fallback logic\n\nTests the new dynamic model selection based on available API keys\n\"\"\"\n\nimport os\nfrom unittest.mock import Mock, patch\n\nimport pytest\n\nfrom providers.registry import ModelProviderRegistry\nfrom providers.shared import ProviderType\n\n\nclass TestIntelligentFallback:\n \"\"\"Test intelligent model fallback logic\"\"\"\n\n def setup_method(self):\n \"\"\"Setup for each test - clear registry and reset providers\"\"\"\n # Store original providers for restoration\n registry = ModelProviderRegistry()\n self._original_providers = registry._providers.copy()\n self._original_initialized = registry._initialized_providers.copy()\n\n # Clear registry completely\n ModelProviderRegistry._instance = None\n\n def teardown_method(self):\n \"\"\"Cleanup after each test - restore original providers\"\"\"\n # Restore original registry state\n registry = ModelProviderRegistry()\n registry._providers.clear()\n registry._initialized_providers.clear()\n registry._providers.update(self._original_providers)\n registry._initialized_providers.update(self._original_initialized)\n\n @patch.dict(os.environ, {\"OPENAI_API_KEY\": \"sk-test-key\", \"GEMINI_API_KEY\": \"\"}, clear=False)\n def test_prefers_openai_o3_mini_when_available(self):\n \"\"\"Test that gpt-5.2 is preferred when OpenAI API key is available (based on new preference order)\"\"\"\n # Register only OpenAI provider for this test\n from providers.openai import OpenAIModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n\n fallback_model = ModelProviderRegistry.get_preferred_fallback_model()\n assert fallback_model == \"gpt-5.2\" # Based on new preference order: gpt-5.2 before o4-mini\n\n @patch.dict(os.environ, {\"OPENAI_API_KEY\": \"\", \"GEMINI_API_KEY\": \"test-gemini-key\"}, clear=False)\n def test_prefers_gemini_flash_when_openai_unavailable(self):\n \"\"\"Test that gemini-2.5-flash is used when only Gemini API key is available\"\"\"\n # Register only Gemini provider for this test\n from providers.gemini import GeminiModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n fallback_model = ModelProviderRegistry.get_preferred_fallback_model()\n assert fallback_model == \"gemini-2.5-flash\"\n\n @patch.dict(os.environ, {\"OPENAI_API_KEY\": \"sk-test-key\", \"GEMINI_API_KEY\": \"test-gemini-key\"}, clear=False)\n def test_prefers_openai_when_both_available(self):\n \"\"\"Test that OpenAI is preferred when both API keys are available\"\"\"\n # Register both OpenAI and Gemini providers\n from providers.gemini import GeminiModelProvider\n from providers.openai import OpenAIModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n fallback_model = ModelProviderRegistry.get_preferred_fallback_model()\n assert fallback_model == \"gemini-2.5-flash\" # Gemini has priority now (based on new PROVIDER_PRIORITY_ORDER)\n\n @patch.dict(os.environ, {\"OPENAI_API_KEY\": \"\", \"GEMINI_API_KEY\": \"\"}, clear=False)\n def test_fallback_when_no_keys_available(self):\n \"\"\"Test fallback behavior when no API keys are available\"\"\"\n # Register providers but with no API keys available\n from providers.gemini import GeminiModelProvider\n from providers.openai import OpenAIModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n fallback_model = ModelProviderRegistry.get_preferred_fallback_model()\n assert fallback_model == \"gemini-2.5-flash\" # Default fallback\n\n def test_available_providers_with_keys(self):\n \"\"\"Test the get_available_providers_with_keys method\"\"\"\n from providers.gemini import GeminiModelProvider\n from providers.openai import OpenAIModelProvider\n\n with patch.dict(os.environ, {\"OPENAI_API_KEY\": \"sk-test-key\", \"GEMINI_API_KEY\": \"\"}, clear=False):\n # Clear and register providers\n ModelProviderRegistry._instance = None\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n available = ModelProviderRegistry.get_available_providers_with_keys()\n assert ProviderType.OPENAI in available\n assert ProviderType.GOOGLE not in available\n\n with patch.dict(os.environ, {\"OPENAI_API_KEY\": \"\", \"GEMINI_API_KEY\": \"test-key\"}, clear=False):\n # Clear and register providers\n ModelProviderRegistry._instance = None\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n available = ModelProviderRegistry.get_available_providers_with_keys()\n assert ProviderType.GOOGLE in available\n assert ProviderType.OPENAI not in available\n\n def test_auto_mode_conversation_memory_integration(self):\n \"\"\"Test that conversation memory uses intelligent fallback in auto mode\"\"\"\n from utils.conversation_memory import ThreadContext, build_conversation_history\n\n # Mock auto mode - patch the config module where these values are defined\n with (\n patch(\"config.IS_AUTO_MODE\", True),\n patch(\"config.DEFAULT_MODEL\", \"auto\"),\n patch.dict(os.environ, {\"OPENAI_API_KEY\": \"sk-test-key\", \"GEMINI_API_KEY\": \"\"}, clear=False),\n ):\n # Register only OpenAI provider for this test\n from providers.openai import OpenAIModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n\n # Create a context with at least one turn so it doesn't exit early\n from utils.conversation_memory import ConversationTurn\n\n context = ThreadContext(\n thread_id=\"test-123\",\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:00:00Z\",\n tool_name=\"chat\",\n turns=[ConversationTurn(role=\"user\", content=\"Test message\", timestamp=\"2023-01-01T00:00:30Z\")],\n initial_context={},\n )\n\n # This should use o4-mini for token calculations since OpenAI is available\n with patch(\"utils.model_context.ModelContext\") as mock_context_class:\n mock_context_instance = Mock()\n mock_context_class.return_value = mock_context_instance\n mock_context_instance.calculate_token_allocation.return_value = Mock(\n file_tokens=10000, history_tokens=5000\n )\n # Mock estimate_tokens to return integers for proper summing\n mock_context_instance.estimate_tokens.return_value = 100\n\n history, tokens = build_conversation_history(context, model_context=None)\n\n # Verify that ModelContext was called with gpt-5.2 (the intelligent fallback based on new preference order)\n mock_context_class.assert_called_once_with(\"gpt-5.2\")\n\n def test_auto_mode_with_gemini_only(self):\n \"\"\"Test auto mode behavior when only Gemini API key is available\"\"\"\n from utils.conversation_memory import ThreadContext, build_conversation_history\n\n with (\n patch(\"config.IS_AUTO_MODE\", True),\n patch(\"config.DEFAULT_MODEL\", \"auto\"),\n patch.dict(os.environ, {\"OPENAI_API_KEY\": \"\", \"GEMINI_API_KEY\": \"test-key\"}, clear=False),\n ):\n # Register only Gemini provider for this test\n from providers.gemini import GeminiModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n from utils.conversation_memory import ConversationTurn\n\n context = ThreadContext(\n thread_id=\"test-456\",\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:00:00Z\",\n tool_name=\"analyze\",\n turns=[ConversationTurn(role=\"assistant\", content=\"Test response\", timestamp=\"2023-01-01T00:00:30Z\")],\n initial_context={},\n )\n\n with patch(\"utils.model_context.ModelContext\") as mock_context_class:\n mock_context_instance = Mock()\n mock_context_class.return_value = mock_context_instance\n mock_context_instance.calculate_token_allocation.return_value = Mock(\n file_tokens=10000, history_tokens=5000\n )\n # Mock estimate_tokens to return integers for proper summing\n mock_context_instance.estimate_tokens.return_value = 100\n\n history, tokens = build_conversation_history(context, model_context=None)\n\n # Should use gemini-2.5-flash when only Gemini is available\n mock_context_class.assert_called_once_with(\"gemini-2.5-flash\")\n\n def test_non_auto_mode_unchanged(self):\n \"\"\"Test that non-auto mode behavior is unchanged\"\"\"\n from utils.conversation_memory import ThreadContext, build_conversation_history\n\n with patch(\"config.IS_AUTO_MODE\", False), patch(\"config.DEFAULT_MODEL\", \"gemini-2.5-pro\"):\n from utils.conversation_memory import ConversationTurn\n\n context = ThreadContext(\n thread_id=\"test-789\",\n created_at=\"2023-01-01T00:00:00Z\",\n last_updated_at=\"2023-01-01T00:00:00Z\",\n tool_name=\"thinkdeep\",\n turns=[\n ConversationTurn(role=\"user\", content=\"Test in non-auto mode\", timestamp=\"2023-01-01T00:00:30Z\")\n ],\n initial_context={},\n )\n\n with patch(\"utils.model_context.ModelContext\") as mock_context_class:\n mock_context_instance = Mock()\n mock_context_class.return_value = mock_context_instance\n mock_context_instance.calculate_token_allocation.return_value = Mock(\n file_tokens=10000, history_tokens=5000\n )\n # Mock estimate_tokens to return integers for proper summing\n mock_context_instance.estimate_tokens.return_value = 100\n\n history, tokens = build_conversation_history(context, model_context=None)\n\n # Should use the configured DEFAULT_MODEL, not the intelligent fallback\n mock_context_class.assert_called_once_with(\"gemini-2.5-pro\")\n\n\nif __name__ == \"__main__\":\n pytest.main([__file__])\n" }, { "path": "tests/test_issue_245_simple.py", "content": "\"\"\"\nSimple test to verify GitHub issue #245 is fixed.\n\nIssue: Custom OpenAI models (gpt-5, o3) use temperature despite the config having supports_temperature: false\n\"\"\"\n\nfrom unittest.mock import Mock, patch\n\nfrom providers.openai import OpenAIModelProvider\n\n\ndef test_issue_245_custom_openai_temperature_ignored():\n \"\"\"Test that reproduces and validates the fix for issue #245.\"\"\"\n\n with patch(\"utils.model_restrictions.get_restriction_service\") as mock_restriction:\n with patch(\"providers.openai_compatible.OpenAI\") as mock_openai:\n with patch(\"providers.registries.openrouter.OpenRouterModelRegistry\") as mock_registry_class:\n\n # Mock restriction service\n mock_service = Mock()\n mock_service.is_allowed.return_value = True\n mock_restriction.return_value = mock_service\n\n # Mock OpenAI client\n mock_client = Mock()\n mock_openai.return_value = mock_client\n mock_response = Mock()\n mock_response.choices = [Mock()]\n mock_response.choices[0].message.content = \"Test response\"\n mock_response.choices[0].finish_reason = \"stop\"\n mock_response.model = \"gpt-5-2025-08-07\"\n mock_response.id = \"test\"\n mock_response.created = 123\n mock_response.usage = Mock()\n mock_response.usage.prompt_tokens = 10\n mock_response.usage.completion_tokens = 5\n mock_response.usage.total_tokens = 15\n mock_client.chat.completions.create.return_value = mock_response\n\n # Mock registry with user's custom config (the issue scenario)\n mock_registry = Mock()\n mock_registry_class.return_value = mock_registry\n\n from providers.shared import ModelCapabilities, ProviderType, TemperatureConstraint\n\n # This is what the user configured in their custom_models.json\n custom_config = ModelCapabilities(\n provider=ProviderType.OPENAI,\n model_name=\"gpt-5-2025-08-07\",\n friendly_name=\"Custom GPT-5\",\n context_window=400000,\n max_output_tokens=128000,\n supports_extended_thinking=True,\n supports_json_mode=True,\n supports_system_prompts=True,\n supports_streaming=True,\n supports_function_calling=True,\n supports_temperature=False, # User set this to false!\n temperature_constraint=TemperatureConstraint.create(\"fixed\"),\n supports_images=True,\n max_image_size_mb=20.0,\n description=\"Custom OpenAI GPT-5\",\n )\n mock_registry.get_model_config.return_value = custom_config\n\n # Create provider and test\n provider = OpenAIModelProvider(api_key=\"test-key\")\n provider.validate_model_name = lambda name: True\n\n # This is what was causing the 400 error before the fix\n provider.generate_content(\n prompt=\"Test\", model_name=\"gpt-5-2025-08-07\", temperature=0.2 # This should be ignored!\n )\n\n # Verify the fix: NO temperature should be sent to the API\n call_kwargs = mock_client.chat.completions.create.call_args[1]\n assert \"temperature\" not in call_kwargs, \"Fix failed: temperature still being sent!\"\n" }, { "path": "tests/test_large_prompt_handling.py", "content": "\"\"\"\nTests for large prompt handling functionality.\n\nThis test module verifies that the MCP server correctly handles\nprompts that exceed the 50,000 character limit by requesting\nClaude to save them to a file and resend.\n\"\"\"\n\nimport json\nimport os\nimport shutil\nimport tempfile\nfrom unittest.mock import MagicMock, patch\n\nimport pytest\n\nfrom config import MCP_PROMPT_SIZE_LIMIT\nfrom tools.chat import ChatTool\nfrom tools.codereview import CodeReviewTool\nfrom tools.shared.exceptions import ToolExecutionError\n\n# from tools.debug import DebugIssueTool # Commented out - debug tool refactored\n\n\nclass TestLargePromptHandling:\n \"\"\"Test suite for large prompt handling across all tools.\"\"\"\n\n def teardown_method(self):\n \"\"\"Clean up after each test to prevent state pollution.\"\"\"\n # Clear provider registry singleton\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry._instance = None\n\n @pytest.fixture\n def large_prompt(self):\n \"\"\"Create a prompt larger than MCP_PROMPT_SIZE_LIMIT characters.\"\"\"\n return \"x\" * (MCP_PROMPT_SIZE_LIMIT + 1000)\n\n @pytest.fixture\n def normal_prompt(self):\n \"\"\"Create a normal-sized prompt.\"\"\"\n return \"This is a normal prompt that should work fine.\"\n\n @pytest.fixture\n def temp_prompt_file(self, large_prompt):\n \"\"\"Create a temporary prompt.txt file with large content.\"\"\"\n # Create temp file with exact name \"prompt.txt\"\n temp_dir = tempfile.mkdtemp()\n file_path = os.path.join(temp_dir, \"prompt.txt\")\n with open(file_path, \"w\") as f:\n f.write(large_prompt)\n return file_path\n\n @pytest.mark.asyncio\n async def test_chat_large_prompt_detection(self, large_prompt):\n \"\"\"Test that chat tool detects large prompts.\"\"\"\n tool = ChatTool()\n temp_dir = tempfile.mkdtemp()\n temp_dir = tempfile.mkdtemp()\n try:\n with pytest.raises(ToolExecutionError) as exc_info:\n await tool.execute({\"prompt\": large_prompt, \"working_directory_absolute_path\": temp_dir})\n finally:\n shutil.rmtree(temp_dir, ignore_errors=True)\n\n output = json.loads(exc_info.value.payload)\n assert output[\"status\"] == \"resend_prompt\"\n assert f\"{MCP_PROMPT_SIZE_LIMIT:,} characters\" in output[\"content\"]\n # The prompt size should match the user input since we check at MCP transport boundary before adding internal content\n assert output[\"metadata\"][\"prompt_size\"] == len(large_prompt)\n assert output[\"metadata\"][\"limit\"] == MCP_PROMPT_SIZE_LIMIT\n\n @pytest.mark.asyncio\n async def test_chat_normal_prompt_works(self, normal_prompt):\n \"\"\"Test that chat tool works normally with regular prompts.\"\"\"\n tool = ChatTool()\n\n temp_dir = tempfile.mkdtemp()\n\n # This test runs in the test environment which uses dummy keys\n # The chat tool will return an error for dummy keys, which is expected\n try:\n try:\n result = await tool.execute(\n {\"prompt\": normal_prompt, \"model\": \"gemini-2.5-flash\", \"working_directory_absolute_path\": temp_dir}\n )\n except ToolExecutionError as exc:\n output = json.loads(exc.payload if hasattr(exc, \"payload\") else str(exc))\n else:\n assert len(result) == 1\n output = json.loads(result[0].text)\n finally:\n shutil.rmtree(temp_dir, ignore_errors=True)\n\n # Whether provider succeeds or fails, we should not hit the resend_prompt branch\n assert output[\"status\"] != \"resend_prompt\"\n\n @pytest.mark.asyncio\n async def test_chat_prompt_file_handling(self):\n \"\"\"Test that chat tool correctly handles prompt.txt files with reasonable size.\"\"\"\n tool = ChatTool()\n # Use a smaller prompt that won't exceed limit when combined with system prompt\n reasonable_prompt = \"This is a reasonable sized prompt for testing prompt.txt file handling.\"\n\n # Create a temp file with reasonable content\n temp_dir = tempfile.mkdtemp()\n temp_prompt_file = os.path.join(temp_dir, \"prompt.txt\")\n with open(temp_prompt_file, \"w\") as f:\n f.write(reasonable_prompt)\n\n try:\n try:\n result = await tool.execute(\n {\n \"prompt\": \"\",\n \"absolute_file_paths\": [temp_prompt_file],\n \"model\": \"gemini-2.5-flash\",\n \"working_directory_absolute_path\": temp_dir,\n }\n )\n except ToolExecutionError as exc:\n output = json.loads(exc.payload if hasattr(exc, \"payload\") else str(exc))\n else:\n assert len(result) == 1\n output = json.loads(result[0].text)\n\n # The test may fail with dummy API keys, which is expected behavior.\n # We're mainly testing that the tool processes prompt files correctly without size errors.\n assert output[\"status\"] != \"resend_prompt\"\n finally:\n # Cleanup\n shutil.rmtree(temp_dir)\n\n @pytest.mark.asyncio\n async def test_codereview_large_focus(self, large_prompt):\n \"\"\"Test that codereview tool detects large focus_on field using real integration testing.\"\"\"\n import importlib\n import os\n\n tool = CodeReviewTool()\n\n # Save original environment\n original_env = {\n \"OPENAI_API_KEY\": os.environ.get(\"OPENAI_API_KEY\"),\n \"DEFAULT_MODEL\": os.environ.get(\"DEFAULT_MODEL\"),\n }\n\n try:\n # Set up environment for real provider resolution\n os.environ[\"OPENAI_API_KEY\"] = \"sk-test-key-large-focus-test-not-real\"\n os.environ[\"DEFAULT_MODEL\"] = \"o3-mini\"\n\n # Clear other provider keys to isolate to OpenAI\n for key in [\"GEMINI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n import config\n\n importlib.reload(config)\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry._instance = None\n\n # Test with real provider resolution\n try:\n args = {\n \"step\": \"initial review setup\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Initial testing\",\n \"relevant_files\": [\"/some/file.py\"],\n \"files_checked\": [\"/some/file.py\"],\n \"focus_on\": large_prompt,\n \"prompt\": \"Test code review for validation purposes\",\n \"model\": \"o3-mini\",\n }\n\n try:\n result = await tool.execute(args)\n except ToolExecutionError as exc:\n output = json.loads(exc.payload if hasattr(exc, \"payload\") else str(exc))\n else:\n assert len(result) == 1\n output = json.loads(result[0].text)\n\n # The large focus_on may trigger the resend_prompt guard before provider access.\n # When the guard does not trigger, auto-mode falls back to provider selection and\n # returns an error about the unavailable model. Both behaviors are acceptable for this test.\n if output.get(\"status\") == \"resend_prompt\":\n assert output[\"metadata\"][\"prompt_size\"] == len(large_prompt)\n else:\n assert output.get(\"status\") == \"error\"\n assert \"Model\" in output.get(\"content\", \"\")\n\n except Exception as e:\n # If we get an unexpected exception, ensure it's not a mock artifact\n error_msg = str(e)\n assert \"MagicMock\" not in error_msg\n assert \"'<' not supported between instances\" not in error_msg\n\n # Should be a real provider error (API, authentication, etc.)\n assert any(\n phrase in error_msg\n for phrase in [\"API\", \"key\", \"authentication\", \"provider\", \"network\", \"connection\"]\n )\n\n finally:\n # Restore environment\n for key, value in original_env.items():\n if value is not None:\n os.environ[key] = value\n else:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n importlib.reload(config)\n ModelProviderRegistry._instance = None\n\n # NOTE: Precommit test has been removed because the precommit tool has been\n # refactored to use a workflow-based pattern instead of accepting simple prompt/path fields.\n # The new precommit tool requires workflow fields like: step, step_number, total_steps,\n # next_step_required, findings, etc. See simulator_tests/test_precommitworkflow_validation.py\n # for comprehensive workflow testing including large prompt handling.\n\n # NOTE: Debug tool tests have been commented out because the debug tool has been\n # refactored to use a self-investigation pattern instead of accepting a prompt field.\n # The new debug tool requires fields like: step, step_number, total_steps, next_step_required, findings\n # and doesn't have the \"resend_prompt\" functionality for large prompts.\n\n # @pytest.mark.asyncio\n # async def test_debug_large_error_description(self, large_prompt):\n # \"\"\"Test that debug tool detects large error_description.\"\"\"\n # tool = DebugIssueTool()\n # result = await tool.execute({\"prompt\": large_prompt})\n #\n # assert len(result) == 1\n # output = json.loads(result[0].text)\n # assert output[\"status\"] == \"resend_prompt\"\n\n # @pytest.mark.asyncio\n # async def test_debug_large_error_context(self, large_prompt, normal_prompt):\n # \"\"\"Test that debug tool detects large error_context.\"\"\"\n # tool = DebugIssueTool()\n # result = await tool.execute({\"prompt\": normal_prompt, \"error_context\": large_prompt})\n #\n # assert len(result) == 1\n # output = json.loads(result[0].text)\n # assert output[\"status\"] == \"resend_prompt\"\n\n # Removed: test_analyze_large_question - workflow tool handles large prompts differently\n\n @pytest.mark.asyncio\n async def test_multiple_files_with_prompt_txt(self, temp_prompt_file):\n \"\"\"Test handling of prompt.txt alongside other files.\"\"\"\n tool = ChatTool()\n other_file = \"/some/other/file.py\"\n\n with (\n patch(\"utils.model_context.ModelContext\") as mock_model_context_cls,\n patch.object(tool, \"handle_prompt_file\") as mock_handle_prompt,\n patch.object(tool, \"_prepare_file_content_for_prompt\") as mock_prepare_files,\n ):\n mock_provider = MagicMock()\n mock_provider.get_provider_type.return_value = MagicMock(value=\"google\")\n mock_provider.generate_content.return_value = MagicMock(\n content=\"Success\",\n usage={\"input_tokens\": 10, \"output_tokens\": 20, \"total_tokens\": 30},\n model_name=\"gemini-2.5-flash\",\n metadata={\"finish_reason\": \"STOP\"},\n )\n\n from utils.model_context import TokenAllocation\n\n mock_model_context = MagicMock()\n mock_model_context.model_name = \"gemini-2.5-flash\"\n mock_model_context.provider = mock_provider\n mock_model_context.capabilities = MagicMock(supports_extended_thinking=False)\n mock_model_context.calculate_token_allocation.return_value = TokenAllocation(\n total_tokens=1_000_000,\n content_tokens=800_000,\n response_tokens=200_000,\n file_tokens=320_000,\n history_tokens=320_000,\n )\n mock_model_context_cls.return_value = mock_model_context\n\n # Return the prompt content and updated files list (without prompt.txt)\n mock_handle_prompt.return_value = (\"Large prompt content from file\", [other_file])\n\n # Mock the centralized file preparation method\n mock_prepare_files.return_value = (\"File content\", [other_file])\n\n # Use a small prompt to avoid triggering size limit\n await tool.execute(\n {\n \"prompt\": \"Test prompt\",\n \"absolute_file_paths\": [temp_prompt_file, other_file],\n \"working_directory_absolute_path\": os.path.dirname(temp_prompt_file),\n }\n )\n\n # Verify handle_prompt_file was called with the original files list\n mock_handle_prompt.assert_called_once_with([temp_prompt_file, other_file])\n\n # Verify _prepare_file_content_for_prompt was called with the updated files list (without prompt.txt)\n mock_prepare_files.assert_called_once()\n files_arg = mock_prepare_files.call_args[0][0]\n assert len(files_arg) == 1\n assert files_arg[0] == other_file\n\n temp_dir = os.path.dirname(temp_prompt_file)\n shutil.rmtree(temp_dir)\n\n @pytest.mark.asyncio\n async def test_boundary_case_exactly_at_limit(self):\n \"\"\"Test prompt exactly at MCP_PROMPT_SIZE_LIMIT characters (should pass with the fix).\"\"\"\n tool = ChatTool()\n exact_prompt = \"x\" * MCP_PROMPT_SIZE_LIMIT\n\n # Mock the model provider to avoid real API calls\n with patch.object(tool, \"get_model_provider\") as mock_get_provider:\n mock_provider = MagicMock()\n mock_provider.get_provider_type.return_value = MagicMock(value=\"google\")\n mock_provider.get_capabilities.return_value = MagicMock(supports_extended_thinking=False)\n mock_provider.generate_content.return_value = MagicMock(\n content=\"Response to the large prompt\",\n usage={\"input_tokens\": 12000, \"output_tokens\": 10, \"total_tokens\": 12010},\n model_name=\"gemini-2.5-flash\",\n metadata={\"finish_reason\": \"STOP\"},\n )\n mock_get_provider.return_value = mock_provider\n\n # With the fix, this should now pass because we check at MCP transport boundary before adding internal content\n temp_dir = tempfile.mkdtemp()\n try:\n try:\n result = await tool.execute({\"prompt\": exact_prompt, \"working_directory_absolute_path\": temp_dir})\n except ToolExecutionError as exc:\n output = json.loads(exc.payload if hasattr(exc, \"payload\") else str(exc))\n else:\n output = json.loads(result[0].text)\n finally:\n shutil.rmtree(temp_dir, ignore_errors=True)\n assert output[\"status\"] != \"resend_prompt\"\n\n @pytest.mark.asyncio\n async def test_boundary_case_just_over_limit(self):\n \"\"\"Test prompt just over MCP_PROMPT_SIZE_LIMIT characters (should trigger file request).\"\"\"\n tool = ChatTool()\n over_prompt = \"x\" * (MCP_PROMPT_SIZE_LIMIT + 1)\n\n temp_dir = tempfile.mkdtemp()\n try:\n try:\n result = await tool.execute({\"prompt\": over_prompt, \"working_directory_absolute_path\": temp_dir})\n except ToolExecutionError as exc:\n output = json.loads(exc.payload if hasattr(exc, \"payload\") else str(exc))\n else:\n output = json.loads(result[0].text)\n finally:\n shutil.rmtree(temp_dir, ignore_errors=True)\n assert output[\"status\"] == \"resend_prompt\"\n\n @pytest.mark.asyncio\n async def test_empty_prompt_no_file(self):\n \"\"\"Test empty prompt without prompt.txt file.\"\"\"\n tool = ChatTool()\n\n with patch.object(tool, \"get_model_provider\") as mock_get_provider:\n mock_provider = MagicMock()\n mock_provider.get_provider_type.return_value = MagicMock(value=\"google\")\n mock_provider.get_capabilities.return_value = MagicMock(supports_extended_thinking=False)\n mock_provider.generate_content.return_value = MagicMock(\n content=\"Success\",\n usage={\"input_tokens\": 10, \"output_tokens\": 20, \"total_tokens\": 30},\n model_name=\"gemini-2.5-flash\",\n metadata={\"finish_reason\": \"STOP\"},\n )\n mock_get_provider.return_value = mock_provider\n\n temp_dir = tempfile.mkdtemp()\n try:\n try:\n result = await tool.execute({\"prompt\": \"\", \"working_directory_absolute_path\": temp_dir})\n except ToolExecutionError as exc:\n output = json.loads(exc.payload if hasattr(exc, \"payload\") else str(exc))\n else:\n output = json.loads(result[0].text)\n finally:\n shutil.rmtree(temp_dir, ignore_errors=True)\n assert output[\"status\"] != \"resend_prompt\"\n\n @pytest.mark.asyncio\n async def test_prompt_file_read_error(self):\n \"\"\"Test handling when prompt.txt can't be read.\"\"\"\n from tests.mock_helpers import create_mock_provider\n\n tool = ChatTool()\n bad_file = \"/nonexistent/prompt.txt\"\n\n with (\n patch.object(tool, \"get_model_provider\") as mock_get_provider,\n patch(\"utils.model_context.ModelContext\") as mock_model_context_class,\n ):\n\n mock_provider = create_mock_provider(model_name=\"gemini-2.5-flash\", context_window=1_048_576)\n mock_provider.generate_content.return_value.content = \"Success\"\n mock_get_provider.return_value = mock_provider\n\n # Mock ModelContext to avoid the comparison issue\n from utils.model_context import TokenAllocation\n\n mock_model_context = MagicMock()\n mock_model_context.model_name = \"gemini-2.5-flash\"\n mock_model_context.calculate_token_allocation.return_value = TokenAllocation(\n total_tokens=1_048_576,\n content_tokens=838_861,\n response_tokens=209_715,\n file_tokens=335_544,\n history_tokens=335_544,\n )\n mock_model_context_class.return_value = mock_model_context\n\n # Should continue with empty prompt when file can't be read\n temp_dir = tempfile.mkdtemp()\n try:\n try:\n result = await tool.execute(\n {\"prompt\": \"\", \"absolute_file_paths\": [bad_file], \"working_directory_absolute_path\": temp_dir}\n )\n except ToolExecutionError as exc:\n output = json.loads(exc.payload if hasattr(exc, \"payload\") else str(exc))\n else:\n output = json.loads(result[0].text)\n finally:\n shutil.rmtree(temp_dir, ignore_errors=True)\n assert output[\"status\"] != \"resend_prompt\"\n\n @pytest.mark.asyncio\n async def test_large_file_context_does_not_trigger_mcp_prompt_limit(self, tmp_path):\n \"\"\"Large context files should not be blocked by MCP prompt limit enforcement.\"\"\"\n from tests.mock_helpers import create_mock_provider\n from utils.model_context import TokenAllocation\n\n tool = ChatTool()\n\n # Create a file significantly larger than MCP_PROMPT_SIZE_LIMIT characters\n large_content = \"A\" * (MCP_PROMPT_SIZE_LIMIT * 5)\n large_file = tmp_path / \"huge_context.txt\"\n large_file.write_text(large_content)\n\n mock_provider = create_mock_provider(model_name=\"flash\")\n\n class DummyModelContext:\n def __init__(self, provider):\n self.model_name = \"flash\"\n self._provider = provider\n self.capabilities = provider.get_capabilities(\"flash\")\n\n @property\n def provider(self):\n return self._provider\n\n def calculate_token_allocation(self):\n return TokenAllocation(\n total_tokens=1_048_576,\n content_tokens=838_861,\n response_tokens=209_715,\n file_tokens=335_544,\n history_tokens=335_544,\n )\n\n dummy_context = DummyModelContext(mock_provider)\n\n with patch.object(tool, \"get_model_provider\", return_value=mock_provider):\n result = await tool.execute(\n {\n \"prompt\": \"Summarize the design decisions\",\n \"absolute_file_paths\": [str(large_file)],\n \"model\": \"flash\",\n \"working_directory_absolute_path\": str(tmp_path),\n \"_model_context\": dummy_context,\n }\n )\n\n output = json.loads(result[0].text)\n assert output[\"status\"] != \"resend_prompt\"\n\n @pytest.mark.asyncio\n async def test_mcp_boundary_with_large_internal_context(self):\n \"\"\"\n Critical test: Ensure MCP_PROMPT_SIZE_LIMIT only applies to user input (MCP boundary),\n NOT to internal context like conversation history, system prompts, or file content.\n\n This test verifies that even if our internal prompt (with system prompts, history, etc.)\n exceeds MCP_PROMPT_SIZE_LIMIT, it should still work as long as the user's input is small.\n \"\"\"\n\n tool = ChatTool()\n\n # Small user input that should pass MCP boundary check\n small_user_prompt = \"What is the weather like?\"\n\n # Mock a huge conversation history that would exceed MCP limits if incorrectly checked\n huge_history = \"x\" * (MCP_PROMPT_SIZE_LIMIT * 2) # 100K chars = way over 50K limit\n\n temp_dir = tempfile.mkdtemp()\n original_prepare_prompt = tool.prepare_prompt\n\n try:\n with (\n patch.object(tool, \"get_model_provider\") as mock_get_provider,\n patch(\"utils.model_context.ModelContext\") as mock_model_context_class,\n ):\n from tests.mock_helpers import create_mock_provider\n from utils.model_context import TokenAllocation\n\n mock_provider = create_mock_provider(model_name=\"flash\")\n mock_get_provider.return_value = mock_provider\n\n mock_model_context = MagicMock()\n mock_model_context.model_name = \"flash\"\n mock_model_context.provider = mock_provider\n mock_model_context.calculate_token_allocation.return_value = TokenAllocation(\n total_tokens=1_048_576,\n content_tokens=838_861,\n response_tokens=209_715,\n file_tokens=335_544,\n history_tokens=335_544,\n )\n mock_model_context_class.return_value = mock_model_context\n\n async def mock_prepare_prompt(request):\n normal_prompt = await original_prepare_prompt(request)\n huge_internal_prompt = f\"{normal_prompt}\\n\\n=== HUGE INTERNAL CONTEXT ===\\n{huge_history}\"\n assert len(huge_internal_prompt) > MCP_PROMPT_SIZE_LIMIT\n return huge_internal_prompt\n\n tool.prepare_prompt = mock_prepare_prompt\n\n result = await tool.execute(\n {\"prompt\": small_user_prompt, \"model\": \"flash\", \"working_directory_absolute_path\": temp_dir}\n )\n output = json.loads(result[0].text)\n\n assert output[\"status\"] != \"resend_prompt\"\n\n mock_provider.generate_content.assert_called_once()\n call_kwargs = mock_provider.generate_content.call_args[1]\n actual_prompt = call_kwargs.get(\"prompt\")\n\n assert len(actual_prompt) > MCP_PROMPT_SIZE_LIMIT\n assert huge_history in actual_prompt\n assert small_user_prompt in actual_prompt\n finally:\n tool.prepare_prompt = original_prepare_prompt\n shutil.rmtree(temp_dir, ignore_errors=True)\n\n @pytest.mark.asyncio\n async def test_mcp_boundary_vs_internal_processing_distinction(self):\n \"\"\"\n Test that clearly demonstrates the distinction between:\n 1. MCP transport boundary (user input - SHOULD be limited)\n 2. Internal processing (system prompts, files, history - should NOT be limited)\n \"\"\"\n tool = ChatTool()\n\n # Test case 1: Large user input should fail at MCP boundary\n large_user_input = \"x\" * (MCP_PROMPT_SIZE_LIMIT + 1000)\n temp_dir = tempfile.mkdtemp()\n try:\n try:\n result = await tool.execute(\n {\"prompt\": large_user_input, \"model\": \"flash\", \"working_directory_absolute_path\": temp_dir}\n )\n except ToolExecutionError as exc:\n output = json.loads(exc.payload if hasattr(exc, \"payload\") else str(exc))\n else:\n output = json.loads(result[0].text)\n\n assert output[\"status\"] == \"resend_prompt\" # Should fail\n assert \"too large for MCP's token limits\" in output[\"content\"]\n\n # Test case 2: Small user input should succeed even with huge internal processing\n small_user_input = \"Hello\"\n\n try:\n result = await tool.execute(\n {\n \"prompt\": small_user_input,\n \"model\": \"gemini-2.5-flash\",\n \"working_directory_absolute_path\": temp_dir,\n }\n )\n except ToolExecutionError as exc:\n output = json.loads(exc.payload if hasattr(exc, \"payload\") else str(exc))\n else:\n output = json.loads(result[0].text)\n\n # The test will fail with dummy API keys, which is expected behavior\n # We're mainly testing that the tool processes small prompts correctly without size errors\n assert output[\"status\"] != \"resend_prompt\"\n finally:\n shutil.rmtree(temp_dir, ignore_errors=True)\n\n @pytest.mark.asyncio\n async def test_continuation_with_huge_conversation_history(self):\n \"\"\"\n Test that continuation calls with huge conversation history work correctly.\n This simulates the exact scenario where conversation history builds up and exceeds\n MCP_PROMPT_SIZE_LIMIT but should still work since history is internal processing.\n \"\"\"\n tool = ChatTool()\n\n # Small user input for continuation\n small_continuation_prompt = \"Continue the discussion\"\n\n # Mock huge conversation history (simulates many turns of conversation)\n # Calculate repetitions needed to exceed MCP_PROMPT_SIZE_LIMIT\n base_text = \"=== CONVERSATION HISTORY ===\\n\"\n repeat_text = \"Previous message content\\n\"\n # Add buffer to ensure we exceed the limit\n target_size = MCP_PROMPT_SIZE_LIMIT + 1000\n available_space = target_size - len(base_text)\n repetitions_needed = (available_space // len(repeat_text)) + 1\n\n huge_conversation_history = base_text + (repeat_text * repetitions_needed)\n\n # Ensure the history exceeds MCP limits\n assert len(huge_conversation_history) > MCP_PROMPT_SIZE_LIMIT\n\n temp_dir = tempfile.mkdtemp()\n\n with (\n patch.object(tool, \"get_model_provider\") as mock_get_provider,\n patch(\"utils.model_context.ModelContext\") as mock_model_context_class,\n ):\n from tests.mock_helpers import create_mock_provider\n\n mock_provider = create_mock_provider(model_name=\"flash\")\n mock_provider.generate_content.return_value.content = \"Continuing our conversation...\"\n mock_get_provider.return_value = mock_provider\n\n # Mock ModelContext to avoid the comparison issue\n from utils.model_context import TokenAllocation\n\n mock_model_context = MagicMock()\n mock_model_context.model_name = \"flash\"\n mock_model_context.provider = mock_provider\n mock_model_context.calculate_token_allocation.return_value = TokenAllocation(\n total_tokens=1_048_576,\n content_tokens=838_861,\n response_tokens=209_715,\n file_tokens=335_544,\n history_tokens=335_544,\n )\n mock_model_context_class.return_value = mock_model_context\n\n # Simulate continuation by having the request contain embedded conversation history\n # This mimics what server.py does when it embeds conversation history\n request_with_history = {\n \"prompt\": f\"{huge_conversation_history}\\n\\n=== CURRENT REQUEST ===\\n{small_continuation_prompt}\",\n \"model\": \"flash\",\n \"continuation_id\": \"test_thread_123\",\n \"working_directory_absolute_path\": temp_dir,\n }\n\n # Mock the conversation history embedding to simulate server.py behavior\n original_execute = tool.__class__.execute\n\n async def mock_execute_with_history(self, arguments):\n # Check if this has continuation_id (simulating server.py logic)\n if arguments.get(\"continuation_id\"):\n # Simulate the case where conversation history is already embedded in prompt\n # by server.py before calling the tool\n field_value = arguments.get(\"prompt\", \"\")\n if \"=== CONVERSATION HISTORY ===\" in field_value:\n # Set the flag that history is embedded\n self._has_embedded_history = True\n\n # The prompt field contains both history AND user input\n # But we should only check the user input part for MCP boundary\n # (This is what our fix ensures happens in prepare_prompt)\n\n # Call original execute\n return await original_execute(self, arguments)\n\n tool.__class__.execute = mock_execute_with_history\n\n try:\n # This should succeed because:\n # 1. The actual user input is small (passes MCP boundary check)\n # 2. The huge conversation history is internal processing (not subject to MCP limits)\n result = await tool.execute(request_with_history)\n output = json.loads(result[0].text)\n\n # Should succeed even though total prompt with history is huge\n assert output[\"status\"] != \"resend_prompt\"\n assert \"Continuing our conversation\" in output[\"content\"]\n\n # Verify the model was called with the complete prompt (including huge history)\n mock_provider.generate_content.assert_called_once()\n call_kwargs = mock_provider.generate_content.call_args[1]\n final_prompt = call_kwargs.get(\"prompt\")\n\n # The final prompt should contain both history and user input\n assert huge_conversation_history in final_prompt\n assert small_continuation_prompt in final_prompt\n # And it should be huge (proving we don't limit internal processing)\n assert len(final_prompt) > MCP_PROMPT_SIZE_LIMIT\n\n finally:\n # Restore original execute method\n tool.__class__.execute = original_execute\n shutil.rmtree(temp_dir, ignore_errors=True)\n\n\nif __name__ == \"__main__\":\n pytest.main([__file__, \"-v\"])\n" }, { "path": "tests/test_line_numbers_integration.py", "content": "\"\"\"\nIntegration test demonstrating that all tools get line numbers by default.\n\"\"\"\n\nfrom tools.analyze import AnalyzeTool\nfrom tools.chat import ChatTool\nfrom tools.codereview import CodeReviewTool\nfrom tools.debug import DebugIssueTool\nfrom tools.precommit import PrecommitTool\nfrom tools.refactor import RefactorTool\nfrom tools.testgen import TestGenTool\n\n\nclass TestLineNumbersIntegration:\n \"\"\"Test that all tools inherit line number behavior correctly.\"\"\"\n\n def test_all_tools_want_line_numbers(self):\n \"\"\"Verify that all tools want line numbers by default.\"\"\"\n tools = [\n ChatTool(),\n AnalyzeTool(),\n CodeReviewTool(),\n DebugIssueTool(),\n RefactorTool(),\n TestGenTool(),\n PrecommitTool(),\n ]\n\n for tool in tools:\n assert tool.wants_line_numbers_by_default(), f\"{tool.get_name()} should want line numbers by default\"\n\n def test_no_tools_override_line_numbers(self):\n \"\"\"Verify that no tools override the base class line number behavior.\"\"\"\n # Check that tools don't have their own wants_line_numbers_by_default method\n tools_classes = [\n ChatTool,\n AnalyzeTool,\n CodeReviewTool,\n DebugIssueTool,\n RefactorTool,\n TestGenTool,\n PrecommitTool,\n ]\n\n for tool_class in tools_classes:\n # Check if the method is defined in the tool class itself\n # (not inherited from base)\n has_override = \"wants_line_numbers_by_default\" in tool_class.__dict__\n assert not has_override, f\"{tool_class.__name__} should not override wants_line_numbers_by_default\"\n" }, { "path": "tests/test_listmodels.py", "content": "\"\"\"Tests for the ListModels tool\"\"\"\n\nimport json\nimport os\nfrom unittest.mock import patch\n\nimport pytest\nfrom mcp.types import TextContent\n\nfrom tools.listmodels import ListModelsTool\n\n\nclass TestListModelsTool:\n \"\"\"Test the ListModels tool functionality\"\"\"\n\n @pytest.fixture\n def tool(self):\n \"\"\"Create a ListModelsTool instance\"\"\"\n return ListModelsTool()\n\n def test_tool_metadata(self, tool):\n \"\"\"Test tool has correct metadata\"\"\"\n assert tool.name == \"listmodels\"\n assert \"model providers\" in tool.description\n assert tool.get_request_model().__name__ == \"ToolRequest\"\n\n @pytest.mark.asyncio\n async def test_execute_with_no_providers(self, tool):\n \"\"\"Test listing models with no providers configured\"\"\"\n with patch.dict(os.environ, {}, clear=True):\n # Set auto mode\n os.environ[\"DEFAULT_MODEL\"] = \"auto\"\n\n result = await tool.execute({})\n\n assert len(result) == 1\n assert isinstance(result[0], TextContent)\n\n # Parse JSON response\n response = json.loads(result[0].text)\n assert response[\"status\"] == \"success\"\n\n content = response[\"content\"]\n\n # Check that providers show as not configured\n assert \"Google Gemini ❌\" in content\n assert \"OpenAI ❌\" in content\n assert \"X.AI (Grok) ❌\" in content\n assert \"OpenRouter ❌\" in content\n assert \"Custom/Local API ❌\" in content\n\n # Check summary shows 0 configured\n assert \"**Configured Providers**: 0\" in content\n\n @pytest.mark.asyncio\n async def test_execute_with_gemini_configured(self, tool):\n \"\"\"Test listing models with Gemini configured\"\"\"\n env_vars = {\"GEMINI_API_KEY\": \"test-key\", \"DEFAULT_MODEL\": \"auto\"}\n\n with patch.dict(os.environ, env_vars, clear=True):\n result = await tool.execute({})\n\n response = json.loads(result[0].text)\n content = response[\"content\"]\n\n # Check Gemini shows as configured\n assert \"Google Gemini βœ…\" in content\n assert \"`flash` β†’ `gemini-2.5-flash`\" in content\n assert \"`pro` β†’ `gemini-3-pro-preview`\" in content\n assert \"1M context\" in content\n assert \"Supports structured code generation\" in content\n\n # Check summary\n assert \"**Configured Providers**: 1\" in content\n\n @pytest.mark.asyncio\n async def test_execute_with_multiple_providers(self, tool):\n \"\"\"Test listing models with multiple providers configured\"\"\"\n env_vars = {\n \"GEMINI_API_KEY\": \"test-key\",\n \"OPENAI_API_KEY\": \"test-key\",\n \"XAI_API_KEY\": \"test-key\",\n \"DEFAULT_MODEL\": \"auto\",\n }\n\n with patch.dict(os.environ, env_vars, clear=True):\n result = await tool.execute({})\n\n response = json.loads(result[0].text)\n content = response[\"content\"]\n\n # Check all show as configured\n assert \"Google Gemini βœ…\" in content\n assert \"OpenAI βœ…\" in content\n assert \"X.AI (Grok) βœ…\" in content\n\n # Check models are listed\n assert \"`o3`\" in content\n assert \"`grok`\" in content\n\n # Check summary\n assert \"**Configured Providers**: 3\" in content\n\n @pytest.mark.asyncio\n async def test_execute_with_openrouter(self, tool):\n \"\"\"Test listing models with OpenRouter configured\"\"\"\n env_vars = {\"OPENROUTER_API_KEY\": \"test-key\", \"DEFAULT_MODEL\": \"auto\"}\n\n with patch.dict(os.environ, env_vars, clear=True):\n result = await tool.execute({})\n\n response = json.loads(result[0].text)\n content = response[\"content\"]\n\n # Check OpenRouter shows as configured\n assert \"OpenRouter βœ…\" in content\n assert \"Access to multiple cloud AI providers\" in content\n\n # Should show some models (mocked registry will have some)\n assert \"Available Models\" in content\n\n @pytest.mark.asyncio\n async def test_execute_with_custom_api(self, tool):\n \"\"\"Test listing models with custom API configured\"\"\"\n env_vars = {\"CUSTOM_API_URL\": \"http://localhost:11434\", \"DEFAULT_MODEL\": \"auto\"}\n\n with patch.dict(os.environ, env_vars, clear=True):\n result = await tool.execute({})\n\n response = json.loads(result[0].text)\n content = response[\"content\"]\n\n # Check Custom API shows as configured\n assert \"Custom/Local API βœ…\" in content\n assert \"http://localhost:11434\" in content\n assert \"Local models via Ollama\" in content\n\n @pytest.mark.asyncio\n async def test_output_includes_usage_tips(self, tool):\n \"\"\"Test that output includes helpful usage tips\"\"\"\n result = await tool.execute({})\n\n response = json.loads(result[0].text)\n content = response[\"content\"]\n\n # Check for usage tips\n assert \"**Usage Tips**:\" in content\n assert \"Use model aliases\" in content\n assert \"auto mode\" in content\n\n def test_model_category(self, tool):\n \"\"\"Test that tool uses FAST_RESPONSE category\"\"\"\n from tools.models import ToolModelCategory\n\n assert tool.get_model_category() == ToolModelCategory.FAST_RESPONSE\n" }, { "path": "tests/test_listmodels_restrictions.py", "content": "\"\"\"Test listmodels tool respects model restrictions.\"\"\"\n\nimport asyncio\nimport os\nimport unittest\nfrom unittest.mock import MagicMock, patch\n\nfrom providers.base import ModelProvider\nfrom providers.registry import ModelProviderRegistry\nfrom providers.shared import ModelCapabilities, ProviderType\nfrom tools.listmodels import ListModelsTool\n\n\nclass TestListModelsRestrictions(unittest.TestCase):\n \"\"\"Test that listmodels respects OPENROUTER_ALLOWED_MODELS.\"\"\"\n\n def setUp(self):\n \"\"\"Set up test environment.\"\"\"\n # Clear any existing registry state\n ModelProviderRegistry.clear_cache()\n\n # Create mock OpenRouter provider\n self.mock_openrouter = MagicMock(spec=ModelProvider)\n self.mock_openrouter.provider_type = ProviderType.OPENROUTER\n\n def make_capabilities(\n canonical: str, friendly: str, *, aliases=None, context: int = 200_000\n ) -> ModelCapabilities:\n return ModelCapabilities(\n provider=ProviderType.OPENROUTER,\n model_name=canonical,\n friendly_name=friendly,\n intelligence_score=20,\n description=friendly,\n aliases=aliases or [],\n context_window=context,\n max_output_tokens=context,\n supports_extended_thinking=True,\n )\n\n opus_caps = make_capabilities(\n \"anthropic/claude-opus-4-20240229\",\n \"Claude Opus\",\n aliases=[\"opus\"],\n )\n sonnet_caps = make_capabilities(\n \"anthropic/claude-sonnet-4-20240229\",\n \"Claude Sonnet\",\n aliases=[\"sonnet\"],\n )\n deepseek_caps = make_capabilities(\n \"deepseek/deepseek-r1-0528:free\",\n \"DeepSeek R1\",\n aliases=[],\n )\n qwen_caps = make_capabilities(\n \"qwen/qwen3-235b-a22b-04-28:free\",\n \"Qwen3\",\n aliases=[],\n )\n\n self._openrouter_caps_map = {\n \"anthropic/claude-opus-4\": opus_caps,\n \"opus\": opus_caps,\n \"anthropic/claude-opus-4-20240229\": opus_caps,\n \"anthropic/claude-sonnet-4\": sonnet_caps,\n \"sonnet\": sonnet_caps,\n \"anthropic/claude-sonnet-4-20240229\": sonnet_caps,\n \"deepseek/deepseek-r1-0528:free\": deepseek_caps,\n \"qwen/qwen3-235b-a22b-04-28:free\": qwen_caps,\n }\n\n self.mock_openrouter.get_capabilities.side_effect = self._openrouter_caps_map.__getitem__\n self.mock_openrouter.get_capabilities_by_rank.return_value = []\n self.mock_openrouter.list_models.return_value = []\n\n # Create mock Gemini provider for comparison\n self.mock_gemini = MagicMock(spec=ModelProvider)\n self.mock_gemini.provider_type = ProviderType.GOOGLE\n self.mock_gemini.list_models.return_value = [\"gemini-2.5-flash\", \"gemini-2.5-pro\"]\n self.mock_gemini.get_capabilities_by_rank.return_value = []\n self.mock_gemini.get_capabilities_by_rank.return_value = []\n\n def tearDown(self):\n \"\"\"Clean up after tests.\"\"\"\n ModelProviderRegistry.clear_cache()\n # Clean up environment variables\n for key in [\"OPENROUTER_ALLOWED_MODELS\", \"OPENROUTER_API_KEY\", \"GEMINI_API_KEY\"]:\n os.environ.pop(key, None)\n\n @patch.dict(\n os.environ,\n {\n \"OPENROUTER_API_KEY\": \"test-key\",\n \"OPENROUTER_ALLOWED_MODELS\": \"opus,sonnet,deepseek/deepseek-r1-0528:free,qwen/qwen3-235b-a22b-04-28:free\",\n \"GEMINI_API_KEY\": \"gemini-test-key\",\n },\n )\n @patch(\"utils.model_restrictions.get_restriction_service\")\n @patch(\"providers.registries.openrouter.OpenRouterModelRegistry\")\n @patch.object(ModelProviderRegistry, \"get_available_models\")\n @patch.object(ModelProviderRegistry, \"get_provider\")\n def test_listmodels_respects_openrouter_restrictions(\n self, mock_get_provider, mock_get_models, mock_registry_class, mock_get_restriction\n ):\n \"\"\"Test that listmodels only shows allowed OpenRouter models.\"\"\"\n # Set up mock to return only allowed models when restrictions are respected\n # Include both aliased models and full model names without aliases\n self.mock_openrouter.list_models.return_value = [\n \"anthropic/claude-opus-4\", # Has alias \"opus\"\n \"anthropic/claude-sonnet-4\", # Has alias \"sonnet\"\n \"deepseek/deepseek-r1-0528:free\", # No alias, full name\n \"qwen/qwen3-235b-a22b-04-28:free\", # No alias, full name\n ]\n\n # Mock registry instance\n mock_registry = MagicMock()\n mock_registry_class.return_value = mock_registry\n\n # Mock resolve method - return config for aliased models, None for others\n def resolve_side_effect(model_name):\n if \"opus\" in model_name.lower():\n config = MagicMock()\n config.model_name = \"anthropic/claude-opus-4-20240229\"\n config.context_window = 200000\n config.get_effective_capability_rank.return_value = 90 # High rank for Opus\n return config\n elif \"sonnet\" in model_name.lower():\n config = MagicMock()\n config.model_name = \"anthropic/claude-sonnet-4-20240229\"\n config.context_window = 200000\n config.get_effective_capability_rank.return_value = 80 # Lower rank for Sonnet\n return config\n elif \"deepseek\" in model_name.lower():\n config = MagicMock()\n config.model_name = \"deepseek/deepseek-r1-0528:free\"\n config.context_window = 100000\n config.get_effective_capability_rank.return_value = 70\n return config\n elif \"qwen\" in model_name.lower():\n config = MagicMock()\n config.model_name = \"qwen/qwen3-235b-a22b-04-28:free\"\n config.context_window = 100000\n config.get_effective_capability_rank.return_value = 60\n return config\n return None # No config for models without aliases\n\n mock_registry.resolve.side_effect = resolve_side_effect\n\n # Mock provider registry\n def get_provider_side_effect(provider_type, force_new=False):\n if provider_type == ProviderType.OPENROUTER:\n return self.mock_openrouter\n elif provider_type == ProviderType.GOOGLE:\n return self.mock_gemini\n return None\n\n mock_get_provider.side_effect = get_provider_side_effect\n\n # Ensure registry is cleared before test\n ModelProviderRegistry._registry = {}\n\n # Mock available models\n mock_get_models.return_value = {\n \"gemini-2.5-flash\": ProviderType.GOOGLE,\n \"gemini-2.5-pro\": ProviderType.GOOGLE,\n \"anthropic/claude-opus-4-20240229\": ProviderType.OPENROUTER,\n \"anthropic/claude-sonnet-4-20240229\": ProviderType.OPENROUTER,\n \"deepseek/deepseek-r1-0528:free\": ProviderType.OPENROUTER,\n \"qwen/qwen3-235b-a22b-04-28:free\": ProviderType.OPENROUTER,\n }\n\n # Mock restriction service\n mock_restriction_service = MagicMock()\n mock_restriction_service.has_restrictions.return_value = True\n mock_restriction_service.get_allowed_models.return_value = {\n \"opus\",\n \"sonnet\",\n \"deepseek/deepseek-r1-0528:free\",\n \"qwen/qwen3-235b-a22b-04-28:free\",\n }\n mock_get_restriction.return_value = mock_restriction_service\n\n # Create tool and execute\n tool = ListModelsTool()\n # Execute asynchronously\n loop = asyncio.new_event_loop()\n asyncio.set_event_loop(loop)\n result_contents = loop.run_until_complete(tool.execute({}))\n loop.close()\n\n # Extract text content from result\n result_text = result_contents[0].text\n\n # Parse JSON response\n import json\n\n result_json = json.loads(result_text)\n result = result_json[\"content\"]\n\n # Parse the output\n lines = result.split(\"\\n\")\n\n # Debug: print the actual result for troubleshooting\n # print(f\"DEBUG: Full result:\\n{result}\")\n\n # Check that OpenRouter section exists\n openrouter_section_found = False\n openrouter_models = []\n in_openrouter_section = False\n\n for line in lines:\n if \"OpenRouter\" in line and \"βœ…\" in line:\n openrouter_section_found = True\n elif (\"Models (policy restricted)\" in line or \"Available Models\" in line) and openrouter_section_found:\n in_openrouter_section = True\n elif in_openrouter_section:\n # Check for lines with model names in backticks\n # Format: - `model-name` (score X)\n if line.strip().startswith(\"- \") and \"`\" in line:\n # Extract model name between backticks\n parts = line.split(\"`\")\n if len(parts) >= 2:\n model_name = parts[1]\n openrouter_models.append(model_name)\n # Stop parsing when we hit the next section\n elif \"##\" in line and in_openrouter_section:\n break\n\n self.assertTrue(openrouter_section_found, \"OpenRouter section not found\")\n self.assertEqual(\n len(openrouter_models), 4, f\"Expected 4 models, got {len(openrouter_models)}: {openrouter_models}\"\n )\n\n # Verify we did not fall back to unrestricted listing\n self.mock_openrouter.list_models.assert_not_called()\n\n # Check for restriction note\n self.assertIn(\"OpenRouter models restricted by\", result)\n\n @patch.dict(os.environ, {\"OPENROUTER_API_KEY\": \"test-key\", \"GEMINI_API_KEY\": \"gemini-test-key\"}, clear=True)\n @patch(\"providers.registries.openrouter.OpenRouterModelRegistry\")\n @patch.object(ModelProviderRegistry, \"get_provider\")\n def test_listmodels_shows_all_models_without_restrictions(self, mock_get_provider, mock_registry_class):\n \"\"\"Test that listmodels shows all models when no restrictions are set.\"\"\"\n # Clear any cached restriction service to ensure it reads from patched environment\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n # Set up mock to return many models when no restrictions\n all_models = [f\"provider{i // 10}/model-{i}\" for i in range(50)] # Simulate 50 models from different providers\n self.mock_openrouter.list_models.return_value = all_models\n\n # Mock registry instance\n mock_registry = MagicMock()\n mock_registry_class.return_value = mock_registry\n mock_registry.resolve.return_value = None # No configs for simplicity\n\n # Mock provider registry\n def get_provider_side_effect(provider_type, force_new=False):\n if provider_type == ProviderType.OPENROUTER:\n return self.mock_openrouter\n elif provider_type == ProviderType.GOOGLE:\n return self.mock_gemini\n return None\n\n mock_get_provider.side_effect = get_provider_side_effect\n\n # Create tool and execute\n tool = ListModelsTool()\n # Execute asynchronously\n loop = asyncio.new_event_loop()\n asyncio.set_event_loop(loop)\n result_contents = loop.run_until_complete(tool.execute({}))\n loop.close()\n\n # Extract text content from result\n result_text = result_contents[0].text\n\n # Parse JSON response\n import json\n\n result_json = json.loads(result_text)\n result = result_json[\"content\"]\n\n # Count OpenRouter models specifically\n lines = result.split(\"\\n\")\n openrouter_section_found = False\n openrouter_model_count = 0\n\n for line in lines:\n if \"OpenRouter\" in line and \"βœ…\" in line:\n openrouter_section_found = True\n elif \"Custom/Local API\" in line:\n # End of OpenRouter section\n break\n elif openrouter_section_found and line.strip().startswith(\"- \") and \"`\" in line:\n openrouter_model_count += 1\n\n # After removing limits, the tool shows ALL available models (no truncation)\n # With 50 models from providers, we expect to see ALL of them\n self.assertGreaterEqual(\n openrouter_model_count,\n 30,\n f\"Expected to see many OpenRouter models (no limits), found {openrouter_model_count}\",\n )\n\n # Should NOT show \"and X more models available\" message since we show all models now\n self.assertNotIn(\"more models available\", result)\n\n # Verify list_models was called with respect_restrictions=True\n # (even without restrictions, we always pass True)\n self.mock_openrouter.list_models.assert_called_with(respect_restrictions=True)\n\n # Should NOT have restriction note when no restrictions are set\n self.assertNotIn(\"Restricted to models matching:\", result)\n\n\nif __name__ == \"__main__\":\n unittest.main()\n" }, { "path": "tests/test_mcp_error_handling.py", "content": "import json\nfrom types import SimpleNamespace\n\nimport pytest\nfrom mcp.types import CallToolRequest, CallToolRequestParams\n\nfrom providers.registry import ModelProviderRegistry\nfrom server import server as mcp_server\n\n\ndef _install_dummy_provider(monkeypatch):\n \"\"\"Ensure preflight model checks succeed without real provider configuration.\"\"\"\n\n class DummyProvider:\n def get_provider_type(self):\n return SimpleNamespace(value=\"dummy\")\n\n def get_capabilities(self, model_name):\n return SimpleNamespace(\n supports_extended_thinking=False,\n allow_code_generation=False,\n supports_images=False,\n context_window=1_000_000,\n max_image_size_mb=10,\n )\n\n monkeypatch.setattr(\n ModelProviderRegistry,\n \"get_provider_for_model\",\n classmethod(lambda cls, model_name: DummyProvider()),\n )\n monkeypatch.setattr(\n ModelProviderRegistry,\n \"get_available_models\",\n classmethod(lambda cls, respect_restrictions=False: {\"gemini-2.5-flash\": None}),\n )\n\n\n@pytest.mark.asyncio\nasync def test_tool_execution_error_sets_is_error_flag_for_mcp_response(monkeypatch):\n \"\"\"Ensure ToolExecutionError surfaces as CallToolResult with isError=True.\"\"\"\n\n _install_dummy_provider(monkeypatch)\n\n handler = mcp_server.request_handlers[CallToolRequest]\n\n arguments = {\n \"prompt\": \"Trigger working_directory_absolute_path validation failure\",\n \"working_directory_absolute_path\": \"relative/path\", # Not absolute -> ToolExecutionError from ChatTool\n \"absolute_file_paths\": [],\n \"model\": \"gemini-2.5-flash\",\n }\n\n request = CallToolRequest(params=CallToolRequestParams(name=\"chat\", arguments=arguments))\n\n server_result = await handler(request)\n\n assert server_result.root.isError is True\n assert server_result.root.content, \"Expected error response content\"\n\n payload = server_result.root.content[0].text\n data = json.loads(payload)\n assert data[\"status\"] == \"error\"\n assert \"absolute\" in data[\"content\"].lower()\n" }, { "path": "tests/test_model_enumeration.py", "content": "\"\"\"\nIntegration tests for model enumeration across all provider combinations.\n\nThese tests ensure that the _get_available_models() method correctly returns\nall expected models based on which providers are configured via environment variables.\n\"\"\"\n\nimport importlib\nimport json\nimport os\n\nimport pytest\n\nfrom providers.registry import ModelProviderRegistry\nfrom tools.analyze import AnalyzeTool\n\n\n@pytest.mark.no_mock_provider\nclass TestModelEnumeration:\n \"\"\"Test model enumeration with various provider configurations\"\"\"\n\n def setup_method(self):\n \"\"\"Set up clean state before each test.\"\"\"\n # Save original environment state\n self._original_env = {\n \"DEFAULT_MODEL\": os.environ.get(\"DEFAULT_MODEL\", \"\"),\n \"GEMINI_API_KEY\": os.environ.get(\"GEMINI_API_KEY\", \"\"),\n \"OPENAI_API_KEY\": os.environ.get(\"OPENAI_API_KEY\", \"\"),\n \"XAI_API_KEY\": os.environ.get(\"XAI_API_KEY\", \"\"),\n \"OPENROUTER_API_KEY\": os.environ.get(\"OPENROUTER_API_KEY\", \"\"),\n \"CUSTOM_API_URL\": os.environ.get(\"CUSTOM_API_URL\", \"\"),\n }\n\n # Clear provider registry\n ModelProviderRegistry._instance = None\n\n def teardown_method(self):\n \"\"\"Clean up after each test.\"\"\"\n # Restore original environment\n for key, value in self._original_env.items():\n if value:\n os.environ[key] = value\n elif key in os.environ:\n del os.environ[key]\n\n # Reload config\n import config\n\n importlib.reload(config)\n\n # Clear provider registry\n ModelProviderRegistry._instance = None\n\n def _setup_environment(self, provider_config):\n \"\"\"Helper to set up environment variables for testing.\"\"\"\n # Clear all provider-related env vars first\n for key in [\"GEMINI_API_KEY\", \"OPENAI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\", \"CUSTOM_API_URL\"]:\n if key in os.environ:\n del os.environ[key]\n\n # Set new values\n for key, value in provider_config.items():\n if value is not None:\n os.environ[key] = value\n\n # Set auto mode only if not explicitly set in provider_config\n if \"DEFAULT_MODEL\" not in provider_config:\n os.environ[\"DEFAULT_MODEL\"] = \"auto\"\n\n # Reload config to pick up changes\n import config\n\n importlib.reload(config)\n\n # Note: tools.base has been refactored to tools.shared.base_tool and tools.simple.base\n # No longer need to reload as configuration is handled at provider level\n\n def test_no_models_when_no_providers_configured(self):\n \"\"\"Test that no native models are included when no providers are configured.\"\"\"\n self._setup_environment({}) # No providers configured\n\n tool = AnalyzeTool()\n models = tool._get_available_models()\n\n # After the fix, models should only be shown from enabled providers\n # With no API keys configured, no providers should be enabled\n # Only OpenRouter aliases might still appear if they're in the registry\n\n # Filter out OpenRouter aliases that might still appear\n non_openrouter_models = [\n m for m in models if \"/\" not in m and m not in [\"gemini\", \"pro\", \"flash\", \"opus\", \"sonnet\", \"haiku\"]\n ]\n\n # No native provider models should be present without API keys\n assert (\n len(non_openrouter_models) == 0\n ), f\"No native models should be available without API keys, but found: {non_openrouter_models}\"\n\n def test_openrouter_models_without_api_key(self):\n \"\"\"Test that OpenRouter models are NOT included when API key is not configured.\"\"\"\n self._setup_environment({}) # No OpenRouter key\n\n tool = AnalyzeTool()\n models = tool._get_available_models()\n\n # OpenRouter-specific models should NOT be present\n openrouter_only_models = [\"opus\", \"sonnet\", \"haiku\"]\n found_count = sum(1 for m in openrouter_only_models if m in models)\n\n assert found_count == 0, \"OpenRouter models should not be included without API key\"\n\n def test_custom_models_without_custom_url(self):\n \"\"\"Test that custom models are NOT included when CUSTOM_API_URL is not configured.\"\"\"\n self._setup_environment({}) # No custom URL\n\n tool = AnalyzeTool()\n models = tool._get_available_models()\n\n # Custom-only models should NOT be present\n custom_only_models = [\"local-llama\", \"llama3.2\"]\n found_count = sum(1 for m in custom_only_models if m in models)\n\n assert found_count == 0, \"Custom models should not be included without CUSTOM_API_URL\"\n\n def test_custom_models_not_exposed_with_openrouter_only(self):\n \"\"\"Ensure OpenRouter access alone does not surface custom-only endpoints.\"\"\"\n self._setup_environment({\"OPENROUTER_API_KEY\": \"test-openrouter-key\"})\n\n tool = AnalyzeTool()\n models = tool._get_available_models()\n\n for alias in (\"local-llama\", \"llama3.2\"):\n assert alias not in models, f\"Custom model alias '{alias}' should remain hidden without CUSTOM_API_URL\"\n\n def test_no_duplicates_with_overlapping_providers(self):\n \"\"\"Test that models aren't duplicated when multiple providers offer the same model.\"\"\"\n self._setup_environment(\n {\n \"OPENAI_API_KEY\": \"test\",\n \"OPENROUTER_API_KEY\": \"test\", # OpenRouter also offers OpenAI models\n }\n )\n\n tool = AnalyzeTool()\n models = tool._get_available_models()\n\n # Count occurrences of each model\n model_counts = {}\n for model in models:\n model_counts[model] = model_counts.get(model, 0) + 1\n\n # Check no duplicates\n duplicates = {m: count for m, count in model_counts.items() if count > 1}\n assert len(duplicates) == 0, f\"Found duplicate models: {duplicates}\"\n\n @pytest.mark.parametrize(\n \"model_name,should_exist\",\n [\n (\"flash\", False), # Gemini - not available without API key\n (\"o3\", False), # OpenAI - not available without API key\n (\"grok\", False), # X.AI - not available without API key\n (\"gemini-2.5-flash\", False), # Full Gemini name - not available without API key\n (\"o4-mini\", False), # OpenAI variant - not available without API key\n (\"grok-4.1-fast\", False), # X.AI variant - not available without API key\n ],\n )\n def test_specific_native_models_only_with_api_keys(self, model_name, should_exist):\n \"\"\"Test that native models are only present when their provider has API keys configured.\"\"\"\n self._setup_environment({}) # No providers\n\n tool = AnalyzeTool()\n models = tool._get_available_models()\n\n if should_exist:\n assert model_name in models, f\"Model {model_name} should be present\"\n else:\n assert model_name not in models, f\"Native model {model_name} should not be present without API key\"\n\n def test_openrouter_free_model_aliases_available(self, tmp_path, monkeypatch):\n \"\"\"Free OpenRouter variants should expose both canonical names and aliases.\"\"\"\n # Configure environment with OpenRouter access only\n self._setup_environment({\"OPENROUTER_API_KEY\": \"test-openrouter-key\"})\n\n # Create a temporary OpenRouter model config with a free variant\n custom_config = {\n \"models\": [\n {\n \"model_name\": \"deepseek/deepseek-r1:free\",\n \"aliases\": [\"deepseek-free\", \"r1-free\"],\n \"context_window\": 163840,\n \"max_output_tokens\": 8192,\n \"supports_extended_thinking\": False,\n \"supports_json_mode\": True,\n \"supports_function_calling\": False,\n \"supports_images\": False,\n \"max_image_size_mb\": 0.0,\n \"description\": \"DeepSeek R1 free tier variant\",\n }\n ]\n }\n\n config_path = tmp_path / \"openrouter_models.json\"\n config_path.write_text(json.dumps(custom_config), encoding=\"utf-8\")\n monkeypatch.setenv(\"OPENROUTER_MODELS_CONFIG_PATH\", str(config_path))\n\n # Reset cached registries so the temporary config is loaded\n from tools.shared.base_tool import BaseTool\n\n monkeypatch.setattr(BaseTool, \"_openrouter_registry_cache\", None, raising=False)\n\n from providers.openrouter import OpenRouterProvider\n\n monkeypatch.setattr(OpenRouterProvider, \"_registry\", None, raising=False)\n\n # Rebuild the provider registry with OpenRouter registered\n ModelProviderRegistry._instance = None\n from providers.shared import ProviderType\n\n ModelProviderRegistry.register_provider(ProviderType.OPENROUTER, OpenRouterProvider)\n\n tool = AnalyzeTool()\n models = tool._get_available_models()\n\n assert \"deepseek/deepseek-r1:free\" in models, \"Canonical free model name should be available\"\n assert \"deepseek-free\" in models, \"Free model alias should be included for MCP validation\"\n\n\n# DELETED: test_auto_mode_behavior_with_environment_variables\n# This test was fundamentally broken due to registry corruption.\n# It cleared ModelProviderRegistry._instance without re-registering providers,\n# causing impossible test conditions (expecting models when no providers exist).\n# Functionality is already covered by test_auto_mode_comprehensive.py\n\n# DELETED: test_auto_mode_model_selection_validation\n# DELETED: test_environment_variable_precedence\n# Both tests suffered from the same registry corruption issue as the deleted test above.\n# They cleared ModelProviderRegistry._instance without re-registering providers,\n# causing empty model lists and impossible test conditions.\n# Auto mode functionality is already comprehensively tested in test_auto_mode_comprehensive.py\n" }, { "path": "tests/test_model_metadata_continuation.py", "content": "\"\"\"\nTest model metadata preservation during conversation continuation.\n\nThis test verifies that when using continuation_id without specifying a model,\nthe system correctly retrieves and uses the model from the previous conversation\nturn instead of defaulting to DEFAULT_MODEL or the custom provider's default.\n\nBug: https://github.com/BeehiveInnovations/pal-mcp-server/issues/111\n\"\"\"\n\nfrom unittest.mock import MagicMock, patch\n\nimport pytest\n\nfrom server import reconstruct_thread_context\nfrom utils.conversation_memory import add_turn, create_thread, get_thread\nfrom utils.model_context import ModelContext\n\n\nclass TestModelMetadataContinuation:\n \"\"\"Test model metadata preservation during conversation continuation.\"\"\"\n\n @pytest.mark.asyncio\n async def test_model_preserved_from_previous_turn(self):\n \"\"\"Test that model is correctly retrieved from previous conversation turn.\"\"\"\n # Create a thread with a turn that has a specific model\n thread_id = create_thread(\"chat\", {\"prompt\": \"test\"})\n\n # Add an assistant turn with a specific model\n success = add_turn(\n thread_id, \"assistant\", \"Here's my response\", model_name=\"deepseek-r1-8b\", model_provider=\"custom\"\n )\n assert success\n\n # Test continuation without model should use previous turn's model\n arguments = {\"continuation_id\": thread_id} # No model specified\n\n # Mock dependencies to avoid side effects\n with patch(\"utils.model_context.ModelContext.calculate_token_allocation\") as mock_calc:\n mock_calc.return_value = MagicMock(\n total_tokens=200000,\n content_tokens=160000,\n response_tokens=40000,\n file_tokens=64000,\n history_tokens=64000,\n )\n\n with patch(\"utils.conversation_memory.build_conversation_history\") as mock_build:\n mock_build.return_value = (\"=== CONVERSATION HISTORY ===\\n\", 1000)\n\n # Call the actual function\n enhanced_args = await reconstruct_thread_context(arguments)\n\n # Verify model was retrieved from thread\n assert enhanced_args.get(\"model\") == \"deepseek-r1-8b\"\n\n # Verify ModelContext would use the correct model\n model_context = ModelContext.from_arguments(enhanced_args)\n assert model_context.model_name == \"deepseek-r1-8b\"\n\n @pytest.mark.asyncio\n async def test_reconstruct_thread_context_preserves_model(self):\n \"\"\"Test that reconstruct_thread_context preserves model from previous turn.\"\"\"\n # Create thread with assistant turn\n thread_id = create_thread(\"chat\", {\"prompt\": \"initial\"})\n add_turn(thread_id, \"assistant\", \"Initial response\", model_name=\"o3-mini\", model_provider=\"openai\")\n\n # Test reconstruction without specifying model\n arguments = {\"continuation_id\": thread_id, \"prompt\": \"follow-up question\"}\n\n # Mock the model context to avoid initialization issues in tests\n with patch(\"utils.model_context.ModelContext.calculate_token_allocation\") as mock_calc:\n mock_calc.return_value = MagicMock(\n total_tokens=200000,\n content_tokens=160000,\n response_tokens=40000,\n file_tokens=64000,\n history_tokens=64000,\n )\n\n with patch(\"utils.conversation_memory.build_conversation_history\") as mock_build:\n mock_build.return_value = (\"=== CONVERSATION HISTORY ===\\n\", 1000)\n\n enhanced_args = await reconstruct_thread_context(arguments)\n\n # Verify model was retrieved from thread\n assert enhanced_args.get(\"model\") == \"o3-mini\"\n\n @pytest.mark.asyncio\n async def test_multiple_turns_uses_last_assistant_model(self):\n \"\"\"Test that with multiple turns, the last assistant turn's model is used.\"\"\"\n thread_id = create_thread(\"chat\", {\"prompt\": \"analyze this\"})\n\n # Add multiple turns with different models\n add_turn(thread_id, \"assistant\", \"First response\", model_name=\"gemini-2.5-flash\", model_provider=\"google\")\n add_turn(thread_id, \"user\", \"Another question\")\n add_turn(thread_id, \"assistant\", \"Second response\", model_name=\"o3\", model_provider=\"openai\")\n add_turn(thread_id, \"user\", \"Final question\")\n\n arguments = {\"continuation_id\": thread_id}\n\n # Mock dependencies\n with patch(\"utils.model_context.ModelContext.calculate_token_allocation\") as mock_calc:\n mock_calc.return_value = MagicMock(\n total_tokens=200000,\n content_tokens=160000,\n response_tokens=40000,\n file_tokens=64000,\n history_tokens=64000,\n )\n\n with patch(\"utils.conversation_memory.build_conversation_history\") as mock_build:\n mock_build.return_value = (\"=== CONVERSATION HISTORY ===\\n\", 1000)\n\n # Call the actual function\n enhanced_args = await reconstruct_thread_context(arguments)\n\n # Should use the most recent assistant model\n assert enhanced_args.get(\"model\") == \"o3\"\n\n @pytest.mark.asyncio\n async def test_no_previous_assistant_turn_defaults(self):\n \"\"\"Test behavior when there's no previous assistant turn.\"\"\"\n # Save and set DEFAULT_MODEL for test\n import importlib\n import os\n\n original_default = os.environ.get(\"DEFAULT_MODEL\", \"\")\n os.environ[\"DEFAULT_MODEL\"] = \"auto\"\n import config\n import utils.model_context\n\n importlib.reload(config)\n importlib.reload(utils.model_context)\n\n try:\n thread_id = create_thread(\"chat\", {\"prompt\": \"test\"})\n\n # Only add user turns\n add_turn(thread_id, \"user\", \"First question\")\n add_turn(thread_id, \"user\", \"Second question\")\n\n arguments = {\"continuation_id\": thread_id}\n\n # Mock dependencies\n with patch(\"utils.model_context.ModelContext.calculate_token_allocation\") as mock_calc:\n mock_calc.return_value = MagicMock(\n total_tokens=200000,\n content_tokens=160000,\n response_tokens=40000,\n file_tokens=64000,\n history_tokens=64000,\n )\n\n with patch(\"utils.conversation_memory.build_conversation_history\") as mock_build:\n mock_build.return_value = (\"=== CONVERSATION HISTORY ===\\n\", 1000)\n\n # Call the actual function\n enhanced_args = await reconstruct_thread_context(arguments)\n\n # Should not have set a model\n assert enhanced_args.get(\"model\") is None\n\n # ModelContext should use DEFAULT_MODEL\n model_context = ModelContext.from_arguments(enhanced_args)\n from config import DEFAULT_MODEL\n\n assert model_context.model_name == DEFAULT_MODEL\n finally:\n # Restore original value\n if original_default:\n os.environ[\"DEFAULT_MODEL\"] = original_default\n else:\n os.environ.pop(\"DEFAULT_MODEL\", None)\n importlib.reload(config)\n importlib.reload(utils.model_context)\n\n @pytest.mark.asyncio\n async def test_explicit_model_overrides_previous_turn(self):\n \"\"\"Test that explicitly specifying a model overrides the previous turn's model.\"\"\"\n thread_id = create_thread(\"chat\", {\"prompt\": \"test\"})\n add_turn(thread_id, \"assistant\", \"Response\", model_name=\"gemini-2.5-flash\", model_provider=\"google\")\n\n arguments = {\"continuation_id\": thread_id, \"model\": \"o3\"} # Explicitly specified\n\n # Mock dependencies\n with patch(\"utils.model_context.ModelContext.calculate_token_allocation\") as mock_calc:\n mock_calc.return_value = MagicMock(\n total_tokens=200000,\n content_tokens=160000,\n response_tokens=40000,\n file_tokens=64000,\n history_tokens=64000,\n )\n\n with patch(\"utils.conversation_memory.build_conversation_history\") as mock_build:\n mock_build.return_value = (\"=== CONVERSATION HISTORY ===\\n\", 1000)\n\n # Call the actual function\n enhanced_args = await reconstruct_thread_context(arguments)\n\n # Should keep the explicit model\n assert enhanced_args.get(\"model\") == \"o3\"\n\n @pytest.mark.asyncio\n async def test_thread_chain_model_preservation(self):\n \"\"\"Test model preservation across thread chains (parent-child relationships).\"\"\"\n # Create parent thread\n parent_id = create_thread(\"chat\", {\"prompt\": \"analyze\"})\n add_turn(parent_id, \"assistant\", \"Analysis\", model_name=\"gemini-2.5-pro\", model_provider=\"google\")\n\n # Create child thread using a simple tool instead of workflow tool\n child_id = create_thread(\"chat\", {\"prompt\": \"review\"}, parent_thread_id=parent_id)\n\n # Child thread should be able to access parent's model through chain traversal\n # NOTE: Current implementation only checks current thread (not parent threads)\n context = get_thread(child_id)\n assert context.parent_thread_id == parent_id\n\n arguments = {\"continuation_id\": child_id}\n\n # Mock dependencies\n with patch(\"utils.model_context.ModelContext.calculate_token_allocation\") as mock_calc:\n mock_calc.return_value = MagicMock(\n total_tokens=200000,\n content_tokens=160000,\n response_tokens=40000,\n file_tokens=64000,\n history_tokens=64000,\n )\n\n with patch(\"utils.conversation_memory.build_conversation_history\") as mock_build:\n mock_build.return_value = (\"=== CONVERSATION HISTORY ===\\n\", 1000)\n\n # Call the actual function\n enhanced_args = await reconstruct_thread_context(arguments)\n\n # No turns in child thread yet, so model should not be set\n assert enhanced_args.get(\"model\") is None\n" }, { "path": "tests/test_model_resolution_bug.py", "content": "\"\"\"\nTest to reproduce and fix the OpenRouter model name resolution bug.\n\nThis test specifically targets the bug where:\n1. User specifies \"gemini\" in consensus tool\n2. System incorrectly resolves to \"gemini-2.5-pro\" instead of \"google/gemini-2.5-pro\"\n3. OpenRouter API returns \"gemini-2.5-pro is not a valid model ID\"\n\"\"\"\n\nfrom unittest.mock import Mock, patch\n\nfrom providers.openrouter import OpenRouterProvider\nfrom providers.shared import ProviderType\nfrom tools.consensus import ConsensusTool\n\n\nclass TestModelResolutionBug:\n \"\"\"Test cases for the OpenRouter model name resolution bug.\"\"\"\n\n def setup_method(self):\n \"\"\"Setup test environment.\"\"\"\n self.consensus_tool = ConsensusTool()\n\n def test_openrouter_registry_resolves_gemini_alias(self):\n \"\"\"Test that OpenRouter registry properly resolves 'gemini' to 'google/gemini-3-pro-preview'.\"\"\"\n # Test the registry directly\n provider = OpenRouterProvider(\"test_key\")\n\n # Test alias resolution\n resolved_model_name = provider._resolve_model_name(\"gemini\")\n assert (\n resolved_model_name == \"google/gemini-3-pro-preview\"\n ), f\"Expected 'google/gemini-3-pro-preview', got '{resolved_model_name}'\"\n\n # Test that it also works with 'pro' alias\n resolved_pro = provider._resolve_model_name(\"pro\")\n assert (\n resolved_pro == \"google/gemini-3-pro-preview\"\n ), f\"Expected 'google/gemini-3-pro-preview', got '{resolved_pro}'\"\n\n # DELETED: test_provider_registry_returns_openrouter_for_gemini\n # This test had a flawed mock setup - it mocked get_provider() but called get_provider_for_model().\n # The test was trying to verify OpenRouter model resolution functionality that is already\n # comprehensively tested in working OpenRouter provider tests.\n\n @patch.dict(\"os.environ\", {\"OPENROUTER_API_KEY\": \"test_key\"}, clear=False)\n def test_consensus_tool_model_resolution_bug_reproduction(self):\n \"\"\"Test that the new consensus workflow tool properly handles OpenRouter model resolution.\"\"\"\n import asyncio\n\n # Create a mock OpenRouter provider that tracks what model names it receives\n mock_provider = Mock(spec=OpenRouterProvider)\n mock_provider.get_provider_type.return_value = ProviderType.OPENROUTER\n\n # Mock response for successful generation\n mock_response = Mock()\n mock_response.content = \"Test response\"\n mock_response.usage = None\n mock_provider.generate_content.return_value = mock_response\n\n # Track the model name passed to generate_content\n received_model_names = []\n\n def track_generate_content(*args, **kwargs):\n received_model_names.append(kwargs.get(\"model_name\", args[1] if len(args) > 1 else \"unknown\"))\n return mock_response\n\n mock_provider.generate_content.side_effect = track_generate_content\n\n # Mock the get_model_provider to return our mock\n with patch.object(self.consensus_tool, \"get_model_provider\", return_value=mock_provider):\n # Set initial prompt\n self.consensus_tool.initial_prompt = \"Test prompt\"\n\n # Create a mock request\n request = Mock()\n request.relevant_files = []\n request.continuation_id = None\n request.images = None\n\n # Test model consultation directly\n result = asyncio.run(self.consensus_tool._consult_model({\"model\": \"gemini\", \"stance\": \"neutral\"}, request))\n\n # Verify that generate_content was called\n assert len(received_model_names) == 1\n\n # The consensus tool should pass the original alias \"gemini\"\n # The OpenRouter provider should resolve it internally\n received_model = received_model_names[0]\n print(f\"Model name passed to provider: {received_model}\")\n\n assert received_model == \"gemini\", f\"Expected 'gemini' to be passed to provider, got '{received_model}'\"\n\n # Verify the result structure\n assert result[\"model\"] == \"gemini\"\n assert result[\"status\"] == \"success\"\n\n def test_bug_reproduction_with_malformed_model_name(self):\n \"\"\"Test what happens when 'gemini-2.5-pro' (malformed) is passed to OpenRouter.\"\"\"\n provider = OpenRouterProvider(\"test_key\")\n\n # This should NOT resolve because 'gemini-2.5-pro' is not in the OpenRouter registry\n resolved = provider._resolve_model_name(\"gemini-2.5-pro\")\n\n # The bug: this returns \"gemini-2.5-pro\" as-is instead of resolving to proper name\n # This is what causes the OpenRouter API to fail\n assert resolved == \"gemini-2.5-pro\", f\"Expected fallback to 'gemini-2.5-pro', got '{resolved}'\"\n\n # Verify the registry doesn't have this malformed name\n config = provider._registry.resolve(\"gemini-2.5-pro\")\n assert config is None, \"Registry should not contain 'gemini-2.5-pro' - only 'google/gemini-2.5-pro'\"\n\n\nif __name__ == \"__main__\":\n # Run the tests\n test = TestModelResolutionBug()\n test.setup_method()\n\n print(\"Testing OpenRouter registry resolution...\")\n test.test_openrouter_registry_resolves_gemini_alias()\n print(\"βœ… Registry resolves aliases correctly\")\n\n print(\"\\nTesting malformed model name handling...\")\n test.test_bug_reproduction_with_malformed_model_name()\n print(\"βœ… Confirmed: malformed names fall through as-is\")\n\n print(\"\\nConsensus tool test completed successfully.\")\n\n print(\"\\nAll tests completed. The bug is fixed.\")\n" }, { "path": "tests/test_model_restrictions.py", "content": "\"\"\"Tests for model restriction functionality.\"\"\"\n\nimport os\nfrom unittest.mock import MagicMock, patch\n\nimport pytest\n\nfrom providers.gemini import GeminiModelProvider\nfrom providers.openai import OpenAIModelProvider\nfrom providers.shared import ProviderType\nfrom utils.model_restrictions import ModelRestrictionService\n\n\nclass TestModelRestrictionService:\n \"\"\"Test cases for ModelRestrictionService.\"\"\"\n\n def test_no_restrictions_by_default(self):\n \"\"\"Test that no restrictions exist when env vars are not set.\"\"\"\n with patch.dict(os.environ, {}, clear=True):\n service = ModelRestrictionService()\n\n # Should allow all models\n assert service.is_allowed(ProviderType.OPENAI, \"o3\")\n assert service.is_allowed(ProviderType.OPENAI, \"o3-mini\")\n assert service.is_allowed(ProviderType.GOOGLE, \"gemini-2.5-pro\")\n assert service.is_allowed(ProviderType.GOOGLE, \"gemini-2.5-flash\")\n assert service.is_allowed(ProviderType.OPENROUTER, \"anthropic/claude-opus-4\")\n assert service.is_allowed(ProviderType.OPENROUTER, \"openai/o3\")\n\n # Should have no restrictions\n assert not service.has_restrictions(ProviderType.OPENAI)\n assert not service.has_restrictions(ProviderType.GOOGLE)\n assert not service.has_restrictions(ProviderType.OPENROUTER)\n\n def test_load_single_model_restriction(self):\n \"\"\"Test loading a single allowed model.\"\"\"\n with patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"o3-mini\"}):\n service = ModelRestrictionService()\n\n # Should only allow o3-mini\n assert service.is_allowed(ProviderType.OPENAI, \"o3-mini\")\n assert not service.is_allowed(ProviderType.OPENAI, \"o3\")\n assert not service.is_allowed(ProviderType.OPENAI, \"o4-mini\")\n\n # Google and OpenRouter should have no restrictions\n assert service.is_allowed(ProviderType.GOOGLE, \"gemini-2.5-pro\")\n assert service.is_allowed(ProviderType.OPENROUTER, \"anthropic/claude-opus-4\")\n\n def test_load_multiple_models_restriction(self):\n \"\"\"Test loading multiple allowed models.\"\"\"\n with patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"o3-mini,o4-mini\", \"GOOGLE_ALLOWED_MODELS\": \"flash,pro\"}):\n # Instantiate providers so alias resolution for allow-lists is available\n openai_provider = OpenAIModelProvider(api_key=\"test-key\")\n gemini_provider = GeminiModelProvider(api_key=\"test-key\")\n\n from providers.registry import ModelProviderRegistry\n\n def fake_get_provider(provider_type, force_new=False):\n mapping = {\n ProviderType.OPENAI: openai_provider,\n ProviderType.GOOGLE: gemini_provider,\n }\n return mapping.get(provider_type)\n\n with patch.object(ModelProviderRegistry, \"get_provider\", side_effect=fake_get_provider):\n\n service = ModelRestrictionService()\n\n # Check OpenAI models\n assert service.is_allowed(ProviderType.OPENAI, \"o3-mini\")\n assert service.is_allowed(ProviderType.OPENAI, \"o4-mini\")\n assert not service.is_allowed(ProviderType.OPENAI, \"o3\")\n\n # Check Google models\n assert service.is_allowed(ProviderType.GOOGLE, \"flash\")\n assert service.is_allowed(ProviderType.GOOGLE, \"pro\")\n assert service.is_allowed(ProviderType.GOOGLE, \"gemini-3-pro-preview\")\n\n def test_case_insensitive_and_whitespace_handling(self):\n \"\"\"Test that model names are case-insensitive and whitespace is trimmed.\"\"\"\n with patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \" O3-MINI , o4-Mini \"}):\n service = ModelRestrictionService()\n\n # Should work with any case\n assert service.is_allowed(ProviderType.OPENAI, \"o3-mini\")\n assert service.is_allowed(ProviderType.OPENAI, \"O3-MINI\")\n assert service.is_allowed(ProviderType.OPENAI, \"o4-mini\")\n assert service.is_allowed(ProviderType.OPENAI, \"O4-Mini\")\n\n def test_empty_string_allows_all(self):\n \"\"\"Test that empty string allows all models (same as unset).\"\"\"\n with patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"\", \"GOOGLE_ALLOWED_MODELS\": \"flash\"}):\n service = ModelRestrictionService()\n\n # OpenAI should allow all models (empty string = no restrictions)\n assert service.is_allowed(ProviderType.OPENAI, \"o3\")\n assert service.is_allowed(ProviderType.OPENAI, \"o3-mini\")\n assert service.is_allowed(ProviderType.OPENAI, \"o4-mini\")\n\n # Google should only allow flash (and its resolved name)\n assert service.is_allowed(ProviderType.GOOGLE, \"flash\")\n assert service.is_allowed(ProviderType.GOOGLE, \"gemini-2.5-flash\", \"flash\")\n assert not service.is_allowed(ProviderType.GOOGLE, \"pro\")\n assert not service.is_allowed(ProviderType.GOOGLE, \"gemini-2.5-pro\", \"pro\")\n\n def test_filter_models(self):\n \"\"\"Test filtering a list of models based on restrictions.\"\"\"\n with patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"o3-mini,o4-mini\"}):\n service = ModelRestrictionService()\n\n models = [\"o3\", \"o3-mini\", \"o4-mini\", \"o3-pro\"]\n filtered = service.filter_models(ProviderType.OPENAI, models)\n\n assert filtered == [\"o3-mini\", \"o4-mini\"]\n\n def test_get_allowed_models(self):\n \"\"\"Test getting the set of allowed models.\"\"\"\n with patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"o3-mini,o4-mini\"}):\n service = ModelRestrictionService()\n\n allowed = service.get_allowed_models(ProviderType.OPENAI)\n assert allowed == {\"o3-mini\", \"o4-mini\"}\n\n # No restrictions for Google\n assert service.get_allowed_models(ProviderType.GOOGLE) is None\n\n def test_shorthand_names_in_restrictions(self):\n \"\"\"Test that shorthand names work in restrictions.\"\"\"\n with patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"o4mini,o3mini\", \"GOOGLE_ALLOWED_MODELS\": \"flash,pro\"}):\n # Instantiate providers so the registry can resolve aliases\n OpenAIModelProvider(api_key=\"test-key\")\n GeminiModelProvider(api_key=\"test-key\")\n\n service = ModelRestrictionService()\n\n # When providers check models, they pass both resolved and original names\n # OpenAI: 'o4mini' shorthand allows o4-mini\n assert service.is_allowed(ProviderType.OPENAI, \"o4-mini\", \"o4mini\") # How providers actually call it\n assert service.is_allowed(ProviderType.OPENAI, \"o4-mini\") # Canonical should also be allowed\n\n # OpenAI: o3-mini allowed directly\n assert service.is_allowed(ProviderType.OPENAI, \"o3-mini\")\n assert not service.is_allowed(ProviderType.OPENAI, \"o3\")\n\n # Google should allow both models via shorthands\n assert service.is_allowed(ProviderType.GOOGLE, \"gemini-2.5-flash\", \"flash\")\n assert service.is_allowed(ProviderType.GOOGLE, \"gemini-2.5-pro\", \"pro\")\n\n # Also test that full names work when specified in restrictions\n assert service.is_allowed(ProviderType.OPENAI, \"o3-mini\", \"o3mini\") # Even with shorthand\n\n def test_validation_against_known_models(self, caplog):\n \"\"\"Test validation warnings for unknown models.\"\"\"\n with patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"o3-mini,o4-mimi\"}): # Note the typo: o4-mimi\n service = ModelRestrictionService()\n\n # Create mock provider with known models\n mock_provider = MagicMock()\n mock_provider.MODEL_CAPABILITIES = {\n \"o3\": {\"context_window\": 200000},\n \"o3-mini\": {\"context_window\": 200000},\n \"o4-mini\": {\"context_window\": 200000},\n }\n mock_provider.list_models.return_value = [\"o3\", \"o3-mini\", \"o4-mini\"]\n\n provider_instances = {ProviderType.OPENAI: mock_provider}\n service.validate_against_known_models(provider_instances)\n\n # Should have logged a warning about the typo\n assert \"o4-mimi\" in caplog.text\n assert \"not a recognized\" in caplog.text\n\n def test_openrouter_model_restrictions(self):\n \"\"\"Test OpenRouter model restrictions functionality.\"\"\"\n with patch.dict(os.environ, {\"OPENROUTER_ALLOWED_MODELS\": \"opus,sonnet\"}):\n service = ModelRestrictionService()\n\n # Should only allow specified OpenRouter models\n assert service.is_allowed(ProviderType.OPENROUTER, \"opus\")\n assert service.is_allowed(ProviderType.OPENROUTER, \"sonnet\")\n assert service.is_allowed(ProviderType.OPENROUTER, \"anthropic/claude-opus-4\", \"opus\") # With original name\n assert not service.is_allowed(ProviderType.OPENROUTER, \"haiku\")\n assert not service.is_allowed(ProviderType.OPENROUTER, \"anthropic/claude-3-haiku\")\n assert not service.is_allowed(ProviderType.OPENROUTER, \"mistral-large\")\n\n # Other providers should have no restrictions\n assert service.is_allowed(ProviderType.OPENAI, \"o3\")\n assert service.is_allowed(ProviderType.GOOGLE, \"pro\")\n\n # Should have restrictions for OpenRouter\n assert service.has_restrictions(ProviderType.OPENROUTER)\n assert not service.has_restrictions(ProviderType.OPENAI)\n assert not service.has_restrictions(ProviderType.GOOGLE)\n\n def test_openrouter_filter_models(self):\n \"\"\"Test filtering OpenRouter models based on restrictions.\"\"\"\n with patch.dict(os.environ, {\"OPENROUTER_ALLOWED_MODELS\": \"opus,mistral\"}):\n service = ModelRestrictionService()\n\n models = [\"opus\", \"sonnet\", \"haiku\", \"mistral\", \"llama\"]\n filtered = service.filter_models(ProviderType.OPENROUTER, models)\n\n assert filtered == [\"opus\", \"mistral\"]\n\n def test_combined_provider_restrictions(self):\n \"\"\"Test that restrictions work correctly when set for multiple providers.\"\"\"\n with patch.dict(\n os.environ,\n {\n \"OPENAI_ALLOWED_MODELS\": \"o3-mini\",\n \"GOOGLE_ALLOWED_MODELS\": \"flash\",\n \"OPENROUTER_ALLOWED_MODELS\": \"opus,sonnet\",\n },\n ):\n service = ModelRestrictionService()\n\n # OpenAI restrictions\n assert service.is_allowed(ProviderType.OPENAI, \"o3-mini\")\n assert not service.is_allowed(ProviderType.OPENAI, \"o3\")\n\n # Google restrictions\n assert service.is_allowed(ProviderType.GOOGLE, \"flash\")\n assert not service.is_allowed(ProviderType.GOOGLE, \"pro\")\n\n # OpenRouter restrictions\n assert service.is_allowed(ProviderType.OPENROUTER, \"opus\")\n assert service.is_allowed(ProviderType.OPENROUTER, \"sonnet\")\n assert not service.is_allowed(ProviderType.OPENROUTER, \"haiku\")\n\n # All providers should have restrictions\n assert service.has_restrictions(ProviderType.OPENAI)\n assert service.has_restrictions(ProviderType.GOOGLE)\n assert service.has_restrictions(ProviderType.OPENROUTER)\n\n\nclass TestProviderIntegration:\n \"\"\"Test integration with actual providers.\"\"\"\n\n @patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"o3-mini\"})\n def test_openai_provider_respects_restrictions(self):\n \"\"\"Test that OpenAI provider respects restrictions.\"\"\"\n # Clear any cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Should validate allowed model\n assert provider.validate_model_name(\"o3-mini\")\n\n # Should not validate disallowed model\n assert not provider.validate_model_name(\"o3\")\n\n # get_capabilities should raise for disallowed model\n with pytest.raises(ValueError) as exc_info:\n provider.get_capabilities(\"o3\")\n assert \"not allowed by restriction policy\" in str(exc_info.value)\n\n @patch.dict(os.environ, {\"GOOGLE_ALLOWED_MODELS\": \"gemini-2.5-flash,flash\"})\n def test_gemini_provider_respects_restrictions(self):\n \"\"\"Test that Gemini provider respects restrictions.\"\"\"\n # Clear any cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n provider = GeminiModelProvider(api_key=\"test-key\")\n\n # Should validate allowed models (both shorthand and full name allowed)\n assert provider.validate_model_name(\"flash\")\n assert provider.validate_model_name(\"gemini-2.5-flash\")\n\n # Should not validate disallowed model\n assert not provider.validate_model_name(\"pro\")\n assert not provider.validate_model_name(\"gemini-2.5-pro\")\n\n # get_capabilities should raise for disallowed model\n with pytest.raises(ValueError) as exc_info:\n provider.get_capabilities(\"pro\")\n assert \"not allowed by restriction policy\" in str(exc_info.value)\n\n @patch.dict(os.environ, {\"GOOGLE_ALLOWED_MODELS\": \"flash\"})\n def test_gemini_parameter_order_regression_protection(self):\n \"\"\"Test that prevents regression of parameter order bug in is_allowed calls.\n\n This test specifically catches the bug where parameters were incorrectly\n passed as (provider, user_input, resolved_name) instead of\n (provider, resolved_name, user_input).\n\n The bug was subtle because the is_allowed method uses OR logic, so it\n worked in most cases by accident. This test creates a scenario where\n the parameter order matters.\n \"\"\"\n # Clear any cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n provider = GeminiModelProvider(api_key=\"test-key\")\n\n from providers.registry import ModelProviderRegistry\n\n with patch.object(ModelProviderRegistry, \"get_provider\", return_value=provider):\n\n # Test case: Only alias \"flash\" is allowed, not the full name\n # If parameters are in wrong order, this test will catch it\n\n # Should allow \"flash\" alias\n assert provider.validate_model_name(\"flash\")\n\n # Should allow getting capabilities for \"flash\"\n capabilities = provider.get_capabilities(\"flash\")\n assert capabilities.model_name == \"gemini-2.5-flash\"\n\n # Canonical form should also be allowed now that alias is on the allowlist\n assert provider.validate_model_name(\"gemini-2.5-flash\")\n # Unrelated models remain blocked\n assert not provider.validate_model_name(\"pro\")\n assert not provider.validate_model_name(\"gemini-2.5-pro\")\n\n @patch.dict(os.environ, {\"GOOGLE_ALLOWED_MODELS\": \"gemini-2.5-flash\"})\n def test_gemini_parameter_order_edge_case_full_name_only(self):\n \"\"\"Test parameter order with only full name allowed, not alias.\n\n This is the reverse scenario - only the full canonical name is allowed,\n not the shorthand alias. This tests that the parameter order is correct\n when resolving aliases.\n \"\"\"\n # Clear any cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n provider = GeminiModelProvider(api_key=\"test-key\")\n\n # Should allow full name\n assert provider.validate_model_name(\"gemini-2.5-flash\")\n\n # Should also allow alias that resolves to allowed full name\n # This works because is_allowed checks both resolved_name and original_name\n assert provider.validate_model_name(\"flash\")\n\n # Should not allow \"pro\" alias\n assert not provider.validate_model_name(\"pro\")\n assert not provider.validate_model_name(\"gemini-2.5-pro\")\n\n\nclass TestCustomProviderOpenRouterRestrictions:\n \"\"\"Test custom provider integration with OpenRouter restrictions.\"\"\"\n\n @patch.dict(os.environ, {\"OPENROUTER_ALLOWED_MODELS\": \"opus,sonnet\", \"OPENROUTER_API_KEY\": \"test-key\"})\n def test_custom_provider_respects_openrouter_restrictions(self):\n \"\"\"Test that custom provider correctly defers OpenRouter models to OpenRouter provider.\"\"\"\n # Clear any cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n from providers.custom import CustomProvider\n\n provider = CustomProvider(base_url=\"http://test.com/v1\")\n\n # CustomProvider should NOT validate OpenRouter models - they should be deferred to OpenRouter\n assert not provider.validate_model_name(\"opus\")\n assert not provider.validate_model_name(\"sonnet\")\n assert not provider.validate_model_name(\"haiku\")\n\n # Should still validate custom models defined in conf/custom_models.json\n assert provider.validate_model_name(\"local-llama\")\n\n @patch.dict(os.environ, {\"OPENROUTER_ALLOWED_MODELS\": \"opus\", \"OPENROUTER_API_KEY\": \"test-key\"})\n def test_custom_provider_openrouter_capabilities_restrictions(self):\n \"\"\"Test that custom provider's get_capabilities correctly handles OpenRouter models.\"\"\"\n # Clear any cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n from providers.custom import CustomProvider\n\n provider = CustomProvider(base_url=\"http://test.com/v1\")\n\n # For OpenRouter models, CustomProvider should defer by raising\n with pytest.raises(ValueError):\n provider.get_capabilities(\"opus\")\n\n # Should raise for disallowed OpenRouter model (still defers)\n with pytest.raises(ValueError):\n provider.get_capabilities(\"haiku\")\n\n # Should still work for custom models\n capabilities = provider.get_capabilities(\"local-llama\")\n assert capabilities.provider == ProviderType.CUSTOM\n\n @patch.dict(os.environ, {\"OPENROUTER_ALLOWED_MODELS\": \"opus\"}, clear=False)\n def test_custom_provider_no_openrouter_key_ignores_restrictions(self):\n \"\"\"Test that when OpenRouter key is not set, cloud models are rejected regardless of restrictions.\"\"\"\n # Make sure OPENROUTER_API_KEY is not set\n if \"OPENROUTER_API_KEY\" in os.environ:\n del os.environ[\"OPENROUTER_API_KEY\"]\n # Clear any cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n from providers.custom import CustomProvider\n\n provider = CustomProvider(base_url=\"http://test.com/v1\")\n\n # Should not validate OpenRouter models when key is not available\n assert not provider.validate_model_name(\"opus\") # Even though it's in allowed list\n assert not provider.validate_model_name(\"haiku\")\n\n # Should still validate custom models\n assert provider.validate_model_name(\"local-llama\")\n\n @patch.dict(os.environ, {\"OPENROUTER_ALLOWED_MODELS\": \"\", \"OPENROUTER_API_KEY\": \"test-key\"})\n def test_custom_provider_empty_restrictions_allows_all_openrouter(self):\n \"\"\"Test that custom provider correctly defers OpenRouter models regardless of restrictions.\"\"\"\n # Clear any cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n from providers.custom import CustomProvider\n\n provider = CustomProvider(base_url=\"http://test.com/v1\")\n\n # CustomProvider should NOT validate OpenRouter models - they should be deferred to OpenRouter\n assert not provider.validate_model_name(\"opus\")\n assert not provider.validate_model_name(\"sonnet\")\n assert not provider.validate_model_name(\"haiku\")\n\n\nclass TestRegistryIntegration:\n \"\"\"Test integration with ModelProviderRegistry.\"\"\"\n\n @patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"mini\", \"GOOGLE_ALLOWED_MODELS\": \"flash\"})\n def test_registry_with_shorthand_restrictions(self):\n \"\"\"Test that registry handles shorthand restrictions correctly.\"\"\"\n # Clear cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n from providers.registry import ModelProviderRegistry\n\n # Clear registry cache\n ModelProviderRegistry.clear_cache()\n\n # Get available models with restrictions\n # This test documents current behavior - get_available_models doesn't handle aliases\n ModelProviderRegistry.get_available_models(respect_restrictions=True)\n\n # Currently, this will be empty because get_available_models doesn't\n # recognize that \"mini\" allows \"o4-mini\"\n # This is a known limitation that should be documented\n\n @patch(\"providers.registry.ModelProviderRegistry.get_provider\")\n def test_get_available_models_respects_restrictions(self, mock_get_provider):\n \"\"\"Test that registry filters models based on restrictions.\"\"\"\n from providers.registry import ModelProviderRegistry\n\n # Mock providers\n mock_openai = MagicMock()\n mock_openai.MODEL_CAPABILITIES = {\n \"o3\": {\"context_window\": 200000},\n \"o3-mini\": {\"context_window\": 200000},\n }\n mock_openai.get_provider_type.return_value = ProviderType.OPENAI\n\n def openai_list_models(\n *,\n respect_restrictions: bool = True,\n include_aliases: bool = True,\n lowercase: bool = False,\n unique: bool = False,\n ):\n from utils.model_restrictions import get_restriction_service\n\n restriction_service = get_restriction_service() if respect_restrictions else None\n models = []\n for model_name, config in mock_openai.MODEL_CAPABILITIES.items():\n if isinstance(config, str):\n target_model = config\n if restriction_service and not restriction_service.is_allowed(ProviderType.OPENAI, target_model):\n continue\n if include_aliases:\n models.append(model_name)\n else:\n if restriction_service and not restriction_service.is_allowed(ProviderType.OPENAI, model_name):\n continue\n models.append(model_name)\n if lowercase:\n models = [m.lower() for m in models]\n if unique:\n seen = set()\n ordered = []\n for name in models:\n if name in seen:\n continue\n seen.add(name)\n ordered.append(name)\n models = ordered\n return models\n\n mock_openai.list_models = MagicMock(side_effect=openai_list_models)\n\n mock_gemini = MagicMock()\n mock_gemini.MODEL_CAPABILITIES = {\n \"gemini-2.5-pro\": {\"context_window\": 1048576},\n \"gemini-2.5-flash\": {\"context_window\": 1048576},\n }\n mock_gemini.get_provider_type.return_value = ProviderType.GOOGLE\n\n def gemini_list_models(\n *,\n respect_restrictions: bool = True,\n include_aliases: bool = True,\n lowercase: bool = False,\n unique: bool = False,\n ):\n from utils.model_restrictions import get_restriction_service\n\n restriction_service = get_restriction_service() if respect_restrictions else None\n models = []\n for model_name, config in mock_gemini.MODEL_CAPABILITIES.items():\n if isinstance(config, str):\n target_model = config\n if restriction_service and not restriction_service.is_allowed(ProviderType.GOOGLE, target_model):\n continue\n if include_aliases:\n models.append(model_name)\n else:\n if restriction_service and not restriction_service.is_allowed(ProviderType.GOOGLE, model_name):\n continue\n models.append(model_name)\n if lowercase:\n models = [m.lower() for m in models]\n if unique:\n seen = set()\n ordered = []\n for name in models:\n if name in seen:\n continue\n seen.add(name)\n ordered.append(name)\n models = ordered\n return models\n\n mock_gemini.list_models = MagicMock(side_effect=gemini_list_models)\n\n def get_provider_side_effect(provider_type):\n if provider_type == ProviderType.OPENAI:\n return mock_openai\n elif provider_type == ProviderType.GOOGLE:\n return mock_gemini\n return None\n\n mock_get_provider.side_effect = get_provider_side_effect\n\n # Set up registry with providers\n registry = ModelProviderRegistry()\n registry._providers = {\n ProviderType.OPENAI: type(mock_openai),\n ProviderType.GOOGLE: type(mock_gemini),\n }\n\n with patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"o3-mini\", \"GOOGLE_ALLOWED_MODELS\": \"gemini-2.5-flash\"}):\n # Clear cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n available = ModelProviderRegistry.get_available_models(respect_restrictions=True)\n\n # Should only include allowed models\n assert \"o3-mini\" in available\n assert \"o3\" not in available\n assert \"gemini-2.5-flash\" in available\n assert \"gemini-2.5-pro\" not in available\n\n\nclass TestShorthandRestrictions:\n \"\"\"Test that shorthand model names work correctly in restrictions.\"\"\"\n\n @patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"mini\", \"GOOGLE_ALLOWED_MODELS\": \"flash\"})\n def test_providers_validate_shorthands_correctly(self):\n \"\"\"Test that providers correctly validate shorthand names.\"\"\"\n # Clear cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n # Test OpenAI provider\n openai_provider = OpenAIModelProvider(api_key=\"test-key\")\n gemini_provider = GeminiModelProvider(api_key=\"test-key\")\n\n from providers.registry import ModelProviderRegistry\n\n def registry_side_effect(provider_type, force_new=False):\n mapping = {\n ProviderType.OPENAI: openai_provider,\n ProviderType.GOOGLE: gemini_provider,\n }\n return mapping.get(provider_type)\n\n with patch.object(ModelProviderRegistry, \"get_provider\", side_effect=registry_side_effect):\n assert openai_provider.validate_model_name(\"mini\") # Should work with shorthand\n assert openai_provider.validate_model_name(\"gpt-5-mini\") # Canonical resolved from shorthand\n assert not openai_provider.validate_model_name(\"o4-mini\") # Unrelated model still blocked\n assert not openai_provider.validate_model_name(\"o3-mini\")\n\n # Test Gemini provider\n assert gemini_provider.validate_model_name(\"flash\") # Should work with shorthand\n assert gemini_provider.validate_model_name(\"gemini-2.5-flash\") # Canonical allowed\n assert not gemini_provider.validate_model_name(\"pro\") # Not allowed\n\n @patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"o3mini,mini,o4-mini\"})\n def test_multiple_shorthands_for_same_model(self):\n \"\"\"Test that multiple shorthands work correctly.\"\"\"\n # Clear cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n openai_provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Both shorthands should work\n assert openai_provider.validate_model_name(\"mini\") # mini -> o4-mini\n assert openai_provider.validate_model_name(\"o3mini\") # o3mini -> o3-mini\n\n # Resolved names should be allowed when their shorthands are present\n assert openai_provider.validate_model_name(\"o4-mini\") # Explicitly allowed\n assert openai_provider.validate_model_name(\"o3-mini\") # Allowed via shorthand\n\n # Other models should not work\n assert not openai_provider.validate_model_name(\"o3\")\n assert not openai_provider.validate_model_name(\"o3-pro\")\n\n @patch.dict(\n os.environ,\n {\"OPENAI_ALLOWED_MODELS\": \"mini,o4-mini\", \"GOOGLE_ALLOWED_MODELS\": \"flash,gemini-2.5-flash\"},\n )\n def test_both_shorthand_and_full_name_allowed(self):\n \"\"\"Test that we can allow both shorthand and full names.\"\"\"\n # Clear cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n # OpenAI - both mini and o4-mini are allowed\n openai_provider = OpenAIModelProvider(api_key=\"test-key\")\n assert openai_provider.validate_model_name(\"mini\")\n assert openai_provider.validate_model_name(\"o4-mini\")\n\n # Gemini - both flash and full name are allowed\n gemini_provider = GeminiModelProvider(api_key=\"test-key\")\n assert gemini_provider.validate_model_name(\"flash\")\n assert gemini_provider.validate_model_name(\"gemini-2.5-flash\")\n\n\nclass TestAutoModeWithRestrictions:\n \"\"\"Test auto mode behavior with restrictions.\"\"\"\n\n @patch(\"providers.registry.ModelProviderRegistry.get_provider\")\n def test_fallback_model_respects_restrictions(self, mock_get_provider):\n \"\"\"Test that fallback model selection respects restrictions.\"\"\"\n from providers.registry import ModelProviderRegistry\n from tools.models import ToolModelCategory\n\n # Mock providers\n mock_openai = MagicMock()\n mock_openai.MODEL_CAPABILITIES = {\n \"o3\": {\"context_window\": 200000},\n \"o3-mini\": {\"context_window\": 200000},\n \"o4-mini\": {\"context_window\": 200000},\n }\n mock_openai.get_provider_type.return_value = ProviderType.OPENAI\n\n def openai_list_models(\n *,\n respect_restrictions: bool = True,\n include_aliases: bool = True,\n lowercase: bool = False,\n unique: bool = False,\n ):\n from utils.model_restrictions import get_restriction_service\n\n restriction_service = get_restriction_service() if respect_restrictions else None\n models = []\n for model_name, config in mock_openai.MODEL_CAPABILITIES.items():\n if isinstance(config, str):\n target_model = config\n if restriction_service and not restriction_service.is_allowed(ProviderType.OPENAI, target_model):\n continue\n if include_aliases:\n models.append(model_name)\n else:\n if restriction_service and not restriction_service.is_allowed(ProviderType.OPENAI, model_name):\n continue\n models.append(model_name)\n if lowercase:\n models = [m.lower() for m in models]\n if unique:\n seen = set()\n ordered = []\n for name in models:\n if name in seen:\n continue\n seen.add(name)\n ordered.append(name)\n models = ordered\n return models\n\n mock_openai.list_models = MagicMock(side_effect=openai_list_models)\n\n # Add get_preferred_model method to mock to match new implementation\n def get_preferred_model(category, allowed_models):\n # Simple preference logic for testing - just return first allowed model\n return allowed_models[0] if allowed_models else None\n\n mock_openai.get_preferred_model = get_preferred_model\n\n def get_provider_side_effect(provider_type):\n if provider_type == ProviderType.OPENAI:\n return mock_openai\n return None\n\n mock_get_provider.side_effect = get_provider_side_effect\n\n # Set up registry\n registry = ModelProviderRegistry()\n registry._providers = {ProviderType.OPENAI: type(mock_openai)}\n\n with patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"o4-mini\"}):\n # Clear cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n # Should pick o4-mini instead of o3-mini for fast response\n model = ModelProviderRegistry.get_preferred_fallback_model(ToolModelCategory.FAST_RESPONSE)\n assert model == \"o4-mini\"\n\n def test_fallback_with_shorthand_restrictions(self, monkeypatch):\n \"\"\"Test fallback model selection with shorthand restrictions.\"\"\"\n # Use monkeypatch to set environment variables with automatic cleanup\n monkeypatch.setenv(\"OPENAI_ALLOWED_MODELS\", \"mini\")\n monkeypatch.setenv(\"GEMINI_API_KEY\", \"\")\n monkeypatch.setenv(\"OPENAI_API_KEY\", \"test-key\")\n\n # Clear caches and reset registry\n import utils.model_restrictions\n from providers.registry import ModelProviderRegistry\n from tools.models import ToolModelCategory\n\n utils.model_restrictions._restriction_service = None\n\n # Store original providers for restoration\n registry = ModelProviderRegistry()\n original_providers = registry._providers.copy()\n original_initialized = registry._initialized_providers.copy()\n\n try:\n # Clear registry and register only OpenAI and Gemini providers\n ModelProviderRegistry._instance = None\n from providers.gemini import GeminiModelProvider\n from providers.openai import OpenAIModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n # Even with \"mini\" restriction, fallback should work if provider handles it correctly\n # This tests the real-world scenario\n model = ModelProviderRegistry.get_preferred_fallback_model(ToolModelCategory.FAST_RESPONSE)\n\n # The fallback will depend on how get_available_models handles aliases\n # When \"mini\" is allowed, it's returned as the allowed model\n # \"mini\" is now an alias for gpt-5-mini, but the list shows \"mini\" itself\n assert model in [\"mini\", \"gpt-5-mini\", \"o4-mini\", \"gemini-2.5-flash\"]\n finally:\n # Restore original registry state\n registry = ModelProviderRegistry()\n registry._providers.clear()\n registry._initialized_providers.clear()\n registry._providers.update(original_providers)\n registry._initialized_providers.update(original_initialized)\n" }, { "path": "tests/test_o3_pro_output_text_fix.py", "content": "\"\"\"\nTests for o3-pro output_text parsing fix using HTTP transport recording.\n\nThis test validates the fix that uses `response.output_text` convenience field\ninstead of manually parsing `response.output.content[].text`.\n\nUses HTTP transport recorder to record real o3-pro API responses at the HTTP level while allowing\nthe OpenAI SDK to create real response objects that we can test.\n\nRECORDING: To record new responses, delete the cassette file and run with real API keys.\n\"\"\"\n\nimport logging\nimport os\nimport tempfile\nfrom pathlib import Path\nfrom unittest.mock import patch\n\nimport pytest\nfrom dotenv import load_dotenv\n\nfrom providers import ModelProviderRegistry\nfrom tests.transport_helpers import inject_transport\nfrom tools.chat import ChatTool\n\nlogger = logging.getLogger(__name__)\n\n# Load environment variables from .env file\nload_dotenv()\n\n# Use absolute path for cassette directory\ncassette_dir = Path(__file__).parent / \"openai_cassettes\"\ncassette_dir.mkdir(exist_ok=True)\n\n\n@pytest.mark.asyncio\nclass TestO3ProOutputTextFix:\n \"\"\"Test o3-pro response parsing fix using respx for HTTP recording/replay.\"\"\"\n\n def setup_method(self):\n \"\"\"Set up the test by ensuring clean registry state.\"\"\"\n # Use the new public API for registry cleanup\n ModelProviderRegistry.reset_for_testing()\n # Provider registration is now handled by inject_transport helper\n\n # Clear restriction service to ensure it re-reads environment\n # This is necessary because previous tests may have set restrictions\n # that are cached in the singleton\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n def teardown_method(self):\n \"\"\"Clean up after test to ensure no state pollution.\"\"\"\n # Use the new public API for registry cleanup\n ModelProviderRegistry.reset_for_testing()\n\n @pytest.mark.no_mock_provider # Disable provider mocking for this test\n @patch.dict(os.environ, {\"OPENAI_ALLOWED_MODELS\": \"o3-pro\", \"LOCALE\": \"\"})\n async def test_o3_pro_uses_output_text_field(self, monkeypatch):\n \"\"\"Test that o3-pro parsing uses the output_text convenience field via ChatTool.\"\"\"\n cassette_path = cassette_dir / \"o3_pro_basic_math.json\"\n\n # Check if we need to record or replay\n if not cassette_path.exists():\n # Recording mode - check for real API key\n real_api_key = os.getenv(\"OPENAI_API_KEY\", \"\").strip()\n if not real_api_key or real_api_key.startswith(\"dummy\"):\n pytest.fail(\n f\"Cassette file not found at {cassette_path}. \"\n \"To record: Set OPENAI_API_KEY environment variable to a valid key and run this test. \"\n \"Note: Recording will make a real API call to OpenAI.\"\n )\n # Real API key is available, we'll record the cassette\n logger.debug(\"🎬 Recording mode: Using real API key to record cassette\")\n else:\n # Replay mode - use dummy key\n monkeypatch.setenv(\"OPENAI_API_KEY\", \"dummy-key-for-replay\")\n logger.debug(\"πŸ“Ό Replay mode: Using recorded cassette\")\n\n # Simplified transport injection - just one line!\n inject_transport(monkeypatch, cassette_path)\n\n # Execute ChatTool test with custom transport\n result = await self._execute_chat_tool_test()\n\n # Verify the response works correctly\n self._verify_chat_tool_response(result)\n\n # Verify cassette exists\n assert cassette_path.exists()\n\n async def _execute_chat_tool_test(self):\n \"\"\"Execute the ChatTool with o3-pro and return the result.\"\"\"\n chat_tool = ChatTool()\n with tempfile.TemporaryDirectory() as workdir:\n arguments = {\n \"prompt\": \"What is 2 + 2?\",\n \"model\": \"o3-pro\",\n \"temperature\": 1.0,\n \"working_directory_absolute_path\": workdir,\n }\n\n return await chat_tool.execute(arguments)\n\n def _verify_chat_tool_response(self, result):\n \"\"\"Verify the ChatTool response contains expected data.\"\"\"\n # Basic response validation\n assert result is not None\n assert isinstance(result, list)\n assert len(result) > 0\n assert result[0].type == \"text\"\n\n # Parse JSON response\n import json\n\n response_data = json.loads(result[0].text)\n\n # Debug log the response\n logger.debug(f\"Response data: {json.dumps(response_data, indent=2)}\")\n\n # Verify response structure - no cargo culting\n if response_data[\"status\"] == \"error\":\n pytest.fail(f\"Chat tool returned error: {response_data.get('error', 'Unknown error')}\")\n assert response_data[\"status\"] in [\"success\", \"continuation_available\"]\n assert \"4\" in response_data[\"content\"]\n\n # Verify o3-pro was actually used\n metadata = response_data[\"metadata\"]\n assert metadata[\"model_used\"] == \"o3-pro\"\n assert metadata[\"provider_used\"] == \"openai\"\n" }, { "path": "tests/test_o3_temperature_fix_simple.py", "content": "\"\"\"\nSimple integration test for the O3 model temperature parameter fix.\n\nThis test confirms that the fix properly excludes temperature parameters\nfor O3 models while maintaining them for regular models.\n\"\"\"\n\nfrom unittest.mock import Mock, patch\n\nfrom providers.openai import OpenAIModelProvider\n\n\nclass TestO3TemperatureParameterFixSimple:\n \"\"\"Simple test for O3 model parameter filtering.\"\"\"\n\n @patch(\"utils.model_restrictions.get_restriction_service\")\n @patch(\"providers.openai_compatible.OpenAI\")\n def test_o3_models_exclude_temperature_from_api_call(self, mock_openai_class, mock_restriction_service):\n \"\"\"Test that O3 models don't send temperature to the API.\"\"\"\n # Mock restriction service to allow all models\n mock_service = Mock()\n mock_service.is_allowed.return_value = True\n mock_restriction_service.return_value = mock_service\n\n # Setup mock client\n mock_client = Mock()\n mock_openai_class.return_value = mock_client\n\n # Setup mock response\n mock_response = Mock()\n mock_response.choices = [Mock()]\n mock_response.choices[0].message.content = \"Test response\"\n mock_response.choices[0].finish_reason = \"stop\"\n mock_response.model = \"o3-mini\"\n mock_response.id = \"test-id\"\n mock_response.created = 1234567890\n mock_response.usage = Mock()\n mock_response.usage.prompt_tokens = 10\n mock_response.usage.completion_tokens = 5\n mock_response.usage.total_tokens = 15\n\n mock_client.chat.completions.create.return_value = mock_response\n\n # Create provider\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Override _resolve_model_name to return the resolved model name\n provider._resolve_model_name = lambda name: name\n # Override model validation to bypass restrictions\n provider.validate_model_name = lambda name: True\n\n # Call generate_content with O3 model\n provider.generate_content(prompt=\"Test prompt\", model_name=\"o3-mini\", temperature=0.5, max_output_tokens=100)\n\n # Verify the API call was made without temperature or max_tokens\n mock_client.chat.completions.create.assert_called_once()\n call_kwargs = mock_client.chat.completions.create.call_args[1]\n\n assert \"temperature\" not in call_kwargs, \"O3 models should not include temperature parameter\"\n assert \"max_tokens\" not in call_kwargs, \"O3 models should not include max_tokens parameter\"\n assert call_kwargs[\"model\"] == \"o3-mini\"\n assert \"messages\" in call_kwargs\n\n @patch(\"utils.model_restrictions.get_restriction_service\")\n @patch(\"providers.openai_compatible.OpenAI\")\n def test_regular_models_include_temperature_in_api_call(self, mock_openai_class, mock_restriction_service):\n \"\"\"Test that regular models still send temperature to the API.\"\"\"\n # Mock restriction service to allow all models\n mock_service = Mock()\n mock_service.is_allowed.return_value = True\n mock_restriction_service.return_value = mock_service\n\n # Setup mock client\n mock_client = Mock()\n mock_openai_class.return_value = mock_client\n\n # Setup mock response\n mock_response = Mock()\n mock_response.choices = [Mock()]\n mock_response.choices[0].message.content = \"Test response\"\n mock_response.choices[0].finish_reason = \"stop\"\n mock_response.model = \"gpt-4.1-2025-04-14\"\n mock_response.id = \"test-id\"\n mock_response.created = 1234567890\n mock_response.usage = Mock()\n mock_response.usage.prompt_tokens = 10\n mock_response.usage.completion_tokens = 5\n mock_response.usage.total_tokens = 15\n\n mock_client.chat.completions.create.return_value = mock_response\n\n # Create provider\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Override _resolve_model_name to return the resolved model name\n provider._resolve_model_name = lambda name: name\n # Override model validation to bypass restrictions\n provider.validate_model_name = lambda name: True\n\n # Call generate_content with regular model (use supported model)\n provider.generate_content(\n prompt=\"Test prompt\", model_name=\"gpt-4.1-2025-04-14\", temperature=0.5, max_output_tokens=100\n )\n\n # Verify the API call was made WITH temperature and max_tokens\n mock_client.chat.completions.create.assert_called_once()\n call_kwargs = mock_client.chat.completions.create.call_args[1]\n\n assert call_kwargs[\"temperature\"] == 0.5, \"Regular models should include temperature parameter\"\n assert call_kwargs[\"max_tokens\"] == 100, \"Regular models should include max_tokens parameter\"\n assert call_kwargs[\"model\"] == \"gpt-4.1-2025-04-14\"\n\n @patch(\"utils.model_restrictions.get_restriction_service\")\n @patch(\"providers.openai_compatible.OpenAI\")\n def test_o3_models_filter_unsupported_parameters(self, mock_openai_class, mock_restriction_service):\n \"\"\"Test that O3 models filter out top_p, frequency_penalty, etc.\"\"\"\n # Mock restriction service to allow all models\n mock_service = Mock()\n mock_service.is_allowed.return_value = True\n mock_restriction_service.return_value = mock_service\n\n # Setup mock client\n mock_client = Mock()\n mock_openai_class.return_value = mock_client\n\n # Setup mock response\n mock_response = Mock()\n mock_response.choices = [Mock()]\n mock_response.choices[0].message.content = \"Test response\"\n mock_response.choices[0].finish_reason = \"stop\"\n mock_response.model = \"o3\"\n mock_response.id = \"test-id\"\n mock_response.created = 1234567890\n mock_response.usage = Mock()\n mock_response.usage.prompt_tokens = 10\n mock_response.usage.completion_tokens = 5\n mock_response.usage.total_tokens = 15\n\n mock_client.chat.completions.create.return_value = mock_response\n\n # Create provider\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Override _resolve_model_name to return the resolved model name\n provider._resolve_model_name = lambda name: name\n # Override model validation to bypass restrictions\n provider.validate_model_name = lambda name: True\n\n # Call generate_content with O3 model and unsupported parameters\n provider.generate_content(\n prompt=\"Test prompt\",\n model_name=\"o3\",\n temperature=0.5,\n top_p=0.9,\n frequency_penalty=0.1,\n presence_penalty=0.1,\n seed=42,\n stop=[\"END\"],\n )\n\n # Verify the API call filters out unsupported parameters\n mock_client.chat.completions.create.assert_called_once()\n call_kwargs = mock_client.chat.completions.create.call_args[1]\n\n # Should be excluded for O3 models\n assert \"temperature\" not in call_kwargs, \"O3 should not include temperature\"\n assert \"top_p\" not in call_kwargs, \"O3 should not include top_p\"\n assert \"frequency_penalty\" not in call_kwargs, \"O3 should not include frequency_penalty\"\n assert \"presence_penalty\" not in call_kwargs, \"O3 should not include presence_penalty\"\n\n # Should be included (supported parameters)\n assert call_kwargs[\"seed\"] == 42, \"O3 should include seed parameter\"\n assert call_kwargs[\"stop\"] == [\"END\"], \"O3 should include stop parameter\"\n\n @patch(\"utils.model_restrictions.get_restriction_service\")\n def test_all_o3_models_have_correct_temperature_capability(self, mock_restriction_service):\n \"\"\"Test that all O3/O4 models have supports_temperature=False in their capabilities.\"\"\"\n from providers.openai import OpenAIModelProvider\n\n # Mock restriction service to allow all models\n mock_service = Mock()\n mock_service.is_allowed.return_value = True\n mock_restriction_service.return_value = mock_service\n\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Test O3/O4 models that should NOT support temperature parameter\n o3_o4_models = [\"o3\", \"o3-mini\", \"o3-pro\", \"o4-mini\"]\n\n for model in o3_o4_models:\n capabilities = provider.get_capabilities(model)\n assert hasattr(\n capabilities, \"supports_temperature\"\n ), f\"Model {model} capabilities should have supports_temperature field\"\n assert capabilities.supports_temperature is False, f\"Model {model} should have supports_temperature=False\"\n\n # Test that regular models DO support temperature parameter\n regular_models = [\"gpt-4.1-2025-04-14\"]\n\n for model in regular_models:\n try:\n capabilities = provider.get_capabilities(model)\n assert hasattr(\n capabilities, \"supports_temperature\"\n ), f\"Model {model} capabilities should have supports_temperature field\"\n assert capabilities.supports_temperature is True, f\"Model {model} should have supports_temperature=True\"\n except ValueError:\n # Skip if model not in MODEL_CAPABILITIES (that's okay for this test)\n pass\n\n @patch(\"utils.model_restrictions.get_restriction_service\")\n def test_openai_provider_temperature_constraints(self, mock_restriction_service):\n \"\"\"Test that OpenAI provider has correct temperature constraints for O3 models.\"\"\"\n from providers.openai import OpenAIModelProvider\n\n # Mock restriction service to allow all models\n mock_service = Mock()\n mock_service.is_allowed.return_value = True\n mock_restriction_service.return_value = mock_service\n\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Test O3 model constraints\n o3_capabilities = provider.get_capabilities(\"o3-mini\")\n assert o3_capabilities.temperature_constraint is not None\n\n # O3 models should have fixed temperature constraint\n temp_constraint = o3_capabilities.temperature_constraint\n assert temp_constraint.validate(1.0) is True\n assert temp_constraint.validate(0.5) is False\n\n # Test regular model constraints - use gpt-4.1 which is supported\n gpt41_capabilities = provider.get_capabilities(\"gpt-4.1\")\n assert gpt41_capabilities.temperature_constraint is not None\n\n # Regular models should allow a range\n temp_constraint = gpt41_capabilities.temperature_constraint\n assert temp_constraint.validate(0.5) is True\n assert temp_constraint.validate(1.0) is True\n" }, { "path": "tests/test_openai_compatible_token_usage.py", "content": "\"\"\"Tests for OpenAI-compatible provider token usage extraction.\"\"\"\n\nimport unittest\nfrom unittest.mock import Mock\n\nfrom providers.openai_compatible import OpenAICompatibleProvider\n\n\nclass TestOpenAICompatibleTokenUsage(unittest.TestCase):\n \"\"\"Test OpenAI-compatible provider token usage handling.\"\"\"\n\n def setUp(self):\n \"\"\"Set up test fixtures.\"\"\"\n\n # Create a concrete implementation for testing\n class TestProvider(OpenAICompatibleProvider):\n FRIENDLY_NAME = \"Test\"\n MODEL_CAPABILITIES = {\"test-model\": {\"context_window\": 4096}}\n\n def get_capabilities(self, model_name):\n return Mock()\n\n def get_provider_type(self):\n return Mock()\n\n def validate_model_name(self, model_name):\n return True\n\n def list_models(self, **kwargs):\n return [\"test-model\"]\n\n self.provider = TestProvider(\"test-key\")\n\n def test_extract_usage_with_valid_tokens(self):\n \"\"\"Test token extraction with valid token counts.\"\"\"\n response = Mock()\n response.usage = Mock()\n response.usage.prompt_tokens = 100\n response.usage.completion_tokens = 50\n response.usage.total_tokens = 150\n\n usage = self.provider._extract_usage(response)\n\n self.assertEqual(usage[\"input_tokens\"], 100)\n self.assertEqual(usage[\"output_tokens\"], 50)\n self.assertEqual(usage[\"total_tokens\"], 150)\n\n def test_extract_usage_with_none_prompt_tokens(self):\n \"\"\"Test token extraction when prompt_tokens is None (regression test for bug).\"\"\"\n response = Mock()\n response.usage = Mock()\n response.usage.prompt_tokens = None # This was causing crashes\n response.usage.completion_tokens = 50\n response.usage.total_tokens = None\n\n usage = self.provider._extract_usage(response)\n\n # Should default to 0 when None\n self.assertEqual(usage[\"input_tokens\"], 0)\n self.assertEqual(usage[\"output_tokens\"], 50)\n self.assertEqual(usage[\"total_tokens\"], 0)\n\n def test_extract_usage_with_none_completion_tokens(self):\n \"\"\"Test token extraction when completion_tokens is None (regression test for bug).\"\"\"\n response = Mock()\n response.usage = Mock()\n response.usage.prompt_tokens = 100\n response.usage.completion_tokens = None # This was causing crashes\n response.usage.total_tokens = None\n\n usage = self.provider._extract_usage(response)\n\n self.assertEqual(usage[\"input_tokens\"], 100)\n # Should default to 0 when None\n self.assertEqual(usage[\"output_tokens\"], 0)\n self.assertEqual(usage[\"total_tokens\"], 0)\n\n def test_extract_usage_with_all_none_tokens(self):\n \"\"\"Test token extraction when all token counts are None.\"\"\"\n response = Mock()\n response.usage = Mock()\n response.usage.prompt_tokens = None\n response.usage.completion_tokens = None\n response.usage.total_tokens = None\n\n usage = self.provider._extract_usage(response)\n\n # Should default to 0 for all when None\n self.assertEqual(usage[\"input_tokens\"], 0)\n self.assertEqual(usage[\"output_tokens\"], 0)\n self.assertEqual(usage[\"total_tokens\"], 0)\n\n def test_extract_usage_without_usage(self):\n \"\"\"Test token extraction when response has no usage.\"\"\"\n response = Mock(spec=[]) # No usage attribute\n\n usage = self.provider._extract_usage(response)\n\n # Should return empty dict\n self.assertEqual(usage, {})\n\n def test_extract_usage_with_zero_tokens(self):\n \"\"\"Test token extraction with zero token counts.\"\"\"\n response = Mock()\n response.usage = Mock()\n response.usage.prompt_tokens = 0\n response.usage.completion_tokens = 0\n response.usage.total_tokens = 0\n\n usage = self.provider._extract_usage(response)\n\n self.assertEqual(usage[\"input_tokens\"], 0)\n self.assertEqual(usage[\"output_tokens\"], 0)\n self.assertEqual(usage[\"total_tokens\"], 0)\n\n def test_alternative_token_format_with_none(self):\n \"\"\"Test alternative token format (input_tokens/output_tokens) with None values.\"\"\"\n # This tests the other code path in generate_content_openai_responses\n # Simulate a response with input_tokens/output_tokens attributes that could be None\n response = Mock()\n response.input_tokens = None # This was causing crashes\n response.output_tokens = 50\n\n # Test the pattern: getattr(response, \"input_tokens\", 0) or 0\n input_tokens = getattr(response, \"input_tokens\", 0) or 0\n output_tokens = getattr(response, \"output_tokens\", 0) or 0\n\n # Should not crash and should handle None gracefully\n self.assertEqual(input_tokens, 0)\n self.assertEqual(output_tokens, 50)\n\n # Test that addition works\n total = input_tokens + output_tokens\n self.assertEqual(total, 50)\n\n\nif __name__ == \"__main__\":\n unittest.main()\n" }, { "path": "tests/test_openai_provider.py", "content": "\"\"\"Tests for OpenAI provider implementation.\"\"\"\n\nimport os\nfrom unittest.mock import MagicMock, patch\n\nfrom providers.openai import OpenAIModelProvider\nfrom providers.shared import ProviderType\n\n\nclass TestOpenAIProvider:\n \"\"\"Test OpenAI provider functionality.\"\"\"\n\n def setup_method(self):\n \"\"\"Set up clean state before each test.\"\"\"\n # Clear restriction service cache before each test\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n def teardown_method(self):\n \"\"\"Clean up after each test to avoid singleton issues.\"\"\"\n # Clear restriction service cache after each test\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n @patch.dict(os.environ, {\"OPENAI_API_KEY\": \"test-key\"})\n def test_initialization(self):\n \"\"\"Test provider initialization.\"\"\"\n provider = OpenAIModelProvider(\"test-key\")\n assert provider.api_key == \"test-key\"\n assert provider.get_provider_type() == ProviderType.OPENAI\n assert provider.base_url == \"https://api.openai.com/v1\"\n\n def test_initialization_with_custom_url(self):\n \"\"\"Test provider initialization with custom base URL.\"\"\"\n provider = OpenAIModelProvider(\"test-key\", base_url=\"https://custom.openai.com/v1\")\n assert provider.api_key == \"test-key\"\n assert provider.base_url == \"https://custom.openai.com/v1\"\n\n def test_model_validation(self):\n \"\"\"Test model name validation.\"\"\"\n provider = OpenAIModelProvider(\"test-key\")\n\n # Test valid models\n assert provider.validate_model_name(\"o3\") is True\n assert provider.validate_model_name(\"o3-mini\") is True\n assert provider.validate_model_name(\"o3-pro\") is True\n assert provider.validate_model_name(\"o4-mini\") is True\n assert provider.validate_model_name(\"o4-mini\") is True\n assert provider.validate_model_name(\"gpt-5\") is True\n assert provider.validate_model_name(\"gpt-5-mini\") is True\n assert provider.validate_model_name(\"gpt-5.2\") is True\n assert provider.validate_model_name(\"gpt-5.1-codex\") is True\n assert provider.validate_model_name(\"gpt-5.1-codex-mini\") is True\n\n # Test valid aliases\n assert provider.validate_model_name(\"mini\") is True\n assert provider.validate_model_name(\"o3mini\") is True\n assert provider.validate_model_name(\"o4mini\") is True\n assert provider.validate_model_name(\"o4mini\") is True\n assert provider.validate_model_name(\"gpt5\") is True\n assert provider.validate_model_name(\"gpt5-mini\") is True\n assert provider.validate_model_name(\"gpt5mini\") is True\n assert provider.validate_model_name(\"gpt5.2\") is True\n assert provider.validate_model_name(\"gpt5.1\") is True\n assert provider.validate_model_name(\"gpt5.1-codex\") is True\n assert provider.validate_model_name(\"codex-mini\") is True\n\n # Test invalid model\n assert provider.validate_model_name(\"invalid-model\") is False\n assert provider.validate_model_name(\"gpt-4\") is False\n assert provider.validate_model_name(\"gemini-pro\") is False\n\n def test_resolve_model_name(self):\n \"\"\"Test model name resolution.\"\"\"\n provider = OpenAIModelProvider(\"test-key\")\n\n # Test shorthand resolution\n assert provider._resolve_model_name(\"mini\") == \"gpt-5-mini\" # \"mini\" now resolves to gpt-5-mini\n assert provider._resolve_model_name(\"o3mini\") == \"o3-mini\"\n assert provider._resolve_model_name(\"o4mini\") == \"o4-mini\"\n assert provider._resolve_model_name(\"o4mini\") == \"o4-mini\"\n assert provider._resolve_model_name(\"gpt5\") == \"gpt-5\"\n assert provider._resolve_model_name(\"gpt5-mini\") == \"gpt-5-mini\"\n assert provider._resolve_model_name(\"gpt5mini\") == \"gpt-5-mini\"\n assert provider._resolve_model_name(\"gpt5.2\") == \"gpt-5.2\"\n assert provider._resolve_model_name(\"gpt5.1\") == \"gpt-5.2\"\n assert provider._resolve_model_name(\"gpt5.1-codex\") == \"gpt-5.1-codex\"\n assert provider._resolve_model_name(\"codex-mini\") == \"gpt-5.1-codex-mini\"\n\n # Test full name passthrough\n assert provider._resolve_model_name(\"o3\") == \"o3\"\n assert provider._resolve_model_name(\"o3-mini\") == \"o3-mini\"\n assert provider._resolve_model_name(\"o3-pro\") == \"o3-pro\"\n assert provider._resolve_model_name(\"o4-mini\") == \"o4-mini\"\n assert provider._resolve_model_name(\"o4-mini\") == \"o4-mini\"\n assert provider._resolve_model_name(\"gpt-5\") == \"gpt-5\"\n assert provider._resolve_model_name(\"gpt-5-mini\") == \"gpt-5-mini\"\n assert provider._resolve_model_name(\"gpt-5.2\") == \"gpt-5.2\"\n assert provider._resolve_model_name(\"gpt-5.1\") == \"gpt-5.2\"\n assert provider._resolve_model_name(\"gpt-5.1-codex\") == \"gpt-5.1-codex\"\n assert provider._resolve_model_name(\"gpt-5.1-codex-mini\") == \"gpt-5.1-codex-mini\"\n\n def test_get_capabilities_o3(self):\n \"\"\"Test getting model capabilities for O3.\"\"\"\n provider = OpenAIModelProvider(\"test-key\")\n\n capabilities = provider.get_capabilities(\"o3\")\n assert capabilities.model_name == \"o3\" # Should NOT be resolved in capabilities\n assert capabilities.friendly_name == \"OpenAI (O3)\"\n assert capabilities.context_window == 200_000\n assert capabilities.provider == ProviderType.OPENAI\n assert not capabilities.supports_extended_thinking\n assert capabilities.supports_system_prompts is True\n assert capabilities.supports_streaming is True\n assert capabilities.supports_function_calling is True\n\n # Test temperature constraint (O3 has fixed temperature)\n assert capabilities.temperature_constraint.value == 1.0\n\n def test_get_capabilities_with_alias(self):\n \"\"\"Test getting model capabilities with alias resolves correctly.\"\"\"\n provider = OpenAIModelProvider(\"test-key\")\n\n capabilities = provider.get_capabilities(\"mini\")\n assert capabilities.model_name == \"gpt-5-mini\" # \"mini\" now resolves to gpt-5-mini\n assert capabilities.friendly_name == \"OpenAI (GPT-5-mini)\"\n assert capabilities.context_window == 400_000\n assert capabilities.provider == ProviderType.OPENAI\n\n def test_get_capabilities_gpt5(self):\n \"\"\"Test getting model capabilities for GPT-5.\"\"\"\n provider = OpenAIModelProvider(\"test-key\")\n\n capabilities = provider.get_capabilities(\"gpt-5\")\n assert capabilities.model_name == \"gpt-5\"\n assert capabilities.friendly_name == \"OpenAI (GPT-5)\"\n assert capabilities.context_window == 400_000\n assert capabilities.max_output_tokens == 128_000\n assert capabilities.provider == ProviderType.OPENAI\n assert capabilities.supports_extended_thinking is True\n assert capabilities.supports_system_prompts is True\n assert capabilities.supports_streaming is False\n assert capabilities.supports_function_calling is True\n assert capabilities.supports_temperature is True\n\n def test_get_capabilities_gpt5_mini(self):\n \"\"\"Test getting model capabilities for GPT-5-mini.\"\"\"\n provider = OpenAIModelProvider(\"test-key\")\n\n capabilities = provider.get_capabilities(\"gpt-5-mini\")\n assert capabilities.model_name == \"gpt-5-mini\"\n assert capabilities.friendly_name == \"OpenAI (GPT-5-mini)\"\n assert capabilities.context_window == 400_000\n assert capabilities.max_output_tokens == 128_000\n assert capabilities.provider == ProviderType.OPENAI\n assert capabilities.supports_extended_thinking is True\n assert capabilities.supports_system_prompts is True\n assert capabilities.supports_streaming is False\n assert capabilities.supports_function_calling is True\n assert capabilities.supports_temperature is True\n\n def test_get_capabilities_gpt52(self):\n \"\"\"Test GPT-5.2 capabilities reflect new metadata.\"\"\"\n provider = OpenAIModelProvider(\"test-key\")\n\n capabilities = provider.get_capabilities(\"gpt-5.2\")\n assert capabilities.model_name == \"gpt-5.2\"\n assert capabilities.supports_streaming is True\n assert capabilities.supports_function_calling is True\n assert capabilities.supports_json_mode is True\n assert capabilities.allow_code_generation is True\n\n def test_get_capabilities_gpt51_codex(self):\n \"\"\"Test GPT-5.1 Codex is responses-only and non-streaming.\"\"\"\n provider = OpenAIModelProvider(\"test-key\")\n\n capabilities = provider.get_capabilities(\"gpt-5.1-codex\")\n assert capabilities.model_name == \"gpt-5.1-codex\"\n assert capabilities.supports_streaming is False\n assert capabilities.use_openai_response_api is True\n assert capabilities.allow_code_generation is True\n\n def test_get_capabilities_gpt51_codex_mini(self):\n \"\"\"Test GPT-5.1 Codex mini exposes streaming and code generation.\"\"\"\n provider = OpenAIModelProvider(\"test-key\")\n\n capabilities = provider.get_capabilities(\"gpt-5.1-codex-mini\")\n assert capabilities.model_name == \"gpt-5.1-codex-mini\"\n assert capabilities.supports_streaming is True\n assert capabilities.allow_code_generation is True\n\n @patch(\"providers.openai_compatible.OpenAI\")\n def test_generate_content_resolves_alias_before_api_call(self, mock_openai_class):\n \"\"\"Test that generate_content resolves aliases before making API calls.\n\n This is the CRITICAL test that was missing - verifying that aliases\n like 'mini' get resolved to 'o4-mini' before being sent to OpenAI API.\n \"\"\"\n # Set up mock OpenAI client\n mock_client = MagicMock()\n mock_openai_class.return_value = mock_client\n\n # Mock the completion response\n mock_response = MagicMock()\n mock_response.choices = [MagicMock()]\n mock_response.choices[0].message.content = \"Test response\"\n mock_response.choices[0].finish_reason = \"stop\"\n mock_response.model = \"gpt-4.1-2025-04-14\" # API returns the resolved model name\n mock_response.id = \"test-id\"\n mock_response.created = 1234567890\n mock_response.usage = MagicMock()\n mock_response.usage.prompt_tokens = 10\n mock_response.usage.completion_tokens = 5\n mock_response.usage.total_tokens = 15\n\n mock_client.chat.completions.create.return_value = mock_response\n\n provider = OpenAIModelProvider(\"test-key\")\n\n # Call generate_content with alias 'gpt4.1' (resolves to gpt-4.1, supports temperature)\n result = provider.generate_content(\n prompt=\"Test prompt\",\n model_name=\"gpt4.1\",\n temperature=1.0, # This should be resolved to \"gpt-4.1\"\n )\n\n # Verify the API was called with the RESOLVED model name\n mock_client.chat.completions.create.assert_called_once()\n call_kwargs = mock_client.chat.completions.create.call_args[1]\n\n # CRITICAL ASSERTION: The API should receive \"gpt-4.1\", not \"gpt4.1\"\n assert call_kwargs[\"model\"] == \"gpt-4.1\", f\"Expected 'gpt-4.1' but API received '{call_kwargs['model']}'\"\n\n # Verify other parameters (gpt-4.1 supports temperature unlike O3/O4 models)\n assert call_kwargs[\"temperature\"] == 1.0\n assert len(call_kwargs[\"messages\"]) == 1\n assert call_kwargs[\"messages\"][0][\"role\"] == \"user\"\n assert call_kwargs[\"messages\"][0][\"content\"] == \"Test prompt\"\n\n # Verify response\n assert result.content == \"Test response\"\n assert result.model_name == \"gpt-4.1\" # Should be the resolved name\n\n @patch(\"providers.openai_compatible.OpenAI\")\n def test_generate_content_other_aliases(self, mock_openai_class):\n \"\"\"Test other alias resolutions in generate_content.\"\"\"\n # Set up mock\n mock_client = MagicMock()\n mock_openai_class.return_value = mock_client\n mock_response = MagicMock()\n mock_response.choices = [MagicMock()]\n mock_response.choices[0].message.content = \"Test response\"\n mock_response.choices[0].finish_reason = \"stop\"\n mock_response.usage = MagicMock()\n mock_response.usage.prompt_tokens = 10\n mock_response.usage.completion_tokens = 5\n mock_response.usage.total_tokens = 15\n mock_client.chat.completions.create.return_value = mock_response\n\n provider = OpenAIModelProvider(\"test-key\")\n\n # Test o3mini -> o3-mini\n mock_response.model = \"o3-mini\"\n provider.generate_content(prompt=\"Test\", model_name=\"o3mini\", temperature=1.0)\n call_kwargs = mock_client.chat.completions.create.call_args[1]\n assert call_kwargs[\"model\"] == \"o3-mini\"\n\n # Test o4mini -> o4-mini\n mock_response.model = \"o4-mini\"\n provider.generate_content(prompt=\"Test\", model_name=\"o4mini\", temperature=1.0)\n call_kwargs = mock_client.chat.completions.create.call_args[1]\n assert call_kwargs[\"model\"] == \"o4-mini\"\n\n @patch(\"providers.openai_compatible.OpenAI\")\n def test_generate_content_no_alias_passthrough(self, mock_openai_class):\n \"\"\"Test that full model names pass through unchanged.\"\"\"\n # Set up mock\n mock_client = MagicMock()\n mock_openai_class.return_value = mock_client\n mock_response = MagicMock()\n mock_response.choices = [MagicMock()]\n mock_response.choices[0].message.content = \"Test response\"\n mock_response.choices[0].finish_reason = \"stop\"\n mock_response.model = \"o3-mini\"\n mock_response.usage = MagicMock()\n mock_response.usage.prompt_tokens = 10\n mock_response.usage.completion_tokens = 5\n mock_response.usage.total_tokens = 15\n mock_client.chat.completions.create.return_value = mock_response\n\n provider = OpenAIModelProvider(\"test-key\")\n\n # Test full model name passes through unchanged (use o3-mini since o3-pro has special handling)\n provider.generate_content(prompt=\"Test\", model_name=\"o3-mini\", temperature=1.0)\n call_kwargs = mock_client.chat.completions.create.call_args[1]\n assert call_kwargs[\"model\"] == \"o3-mini\" # Should be unchanged\n\n def test_extended_thinking_capabilities(self):\n \"\"\"Thinking-mode support should be reflected via ModelCapabilities.\"\"\"\n provider = OpenAIModelProvider(\"test-key\")\n\n supported_aliases = [\n \"gpt-5\",\n \"gpt-5-mini\",\n \"gpt-5-nano\",\n \"gpt5\",\n \"gpt5-mini\",\n \"gpt5mini\",\n \"gpt5-nano\",\n \"gpt5nano\",\n \"nano\",\n \"mini\", # resolves to gpt-5-mini\n ]\n for alias in supported_aliases:\n assert provider.get_capabilities(alias).supports_extended_thinking is True\n\n unsupported_aliases = [\"o3\", \"o3-mini\", \"o4-mini\"]\n for alias in unsupported_aliases:\n assert provider.get_capabilities(alias).supports_extended_thinking is False\n\n # Invalid models should not validate, treat as unsupported\n assert not provider.validate_model_name(\"invalid-model\")\n\n @patch(\"providers.openai_compatible.OpenAI\")\n def test_o3_pro_routes_to_responses_endpoint(self, mock_openai_class):\n \"\"\"Test that o3-pro model routes to the /v1/responses endpoint (mock test).\"\"\"\n # Set up mock for OpenAI client responses endpoint\n mock_client = MagicMock()\n mock_openai_class.return_value = mock_client\n\n mock_response = MagicMock()\n # New o3-pro format: direct output_text field\n mock_response.output_text = \"4\"\n mock_response.model = \"o3-pro\"\n mock_response.id = \"test-id\"\n mock_response.created_at = 1234567890\n mock_response.usage = MagicMock()\n mock_response.usage.prompt_tokens = 10\n mock_response.usage.completion_tokens = 5\n mock_response.usage.total_tokens = 15\n\n mock_client.responses.create.return_value = mock_response\n\n provider = OpenAIModelProvider(\"test-key\")\n\n # Generate content with o3-pro\n result = provider.generate_content(prompt=\"What is 2 + 2?\", model_name=\"o3-pro\", temperature=1.0)\n\n # Verify responses.create was called\n mock_client.responses.create.assert_called_once()\n call_args = mock_client.responses.create.call_args[1]\n assert call_args[\"model\"] == \"o3-pro\"\n assert call_args[\"input\"][0][\"role\"] == \"user\"\n assert \"What is 2 + 2?\" in call_args[\"input\"][0][\"content\"][0][\"text\"]\n\n # Verify the response\n assert result.content == \"4\"\n assert result.model_name == \"o3-pro\"\n assert result.metadata[\"endpoint\"] == \"responses\"\n\n @patch(\"providers.openai_compatible.OpenAI\")\n def test_non_o3_pro_uses_chat_completions(self, mock_openai_class):\n \"\"\"Test that non-o3-pro models use the standard chat completions endpoint.\"\"\"\n # Set up mock\n mock_client = MagicMock()\n mock_openai_class.return_value = mock_client\n mock_response = MagicMock()\n mock_response.choices = [MagicMock()]\n mock_response.choices[0].message.content = \"Test response\"\n mock_response.choices[0].finish_reason = \"stop\"\n mock_response.model = \"o3-mini\"\n mock_response.id = \"test-id\"\n mock_response.created = 1234567890\n mock_response.usage = MagicMock()\n mock_response.usage.prompt_tokens = 10\n mock_response.usage.completion_tokens = 5\n mock_response.usage.total_tokens = 15\n mock_client.chat.completions.create.return_value = mock_response\n\n provider = OpenAIModelProvider(\"test-key\")\n\n # Generate content with o3-mini (not o3-pro)\n result = provider.generate_content(prompt=\"Test prompt\", model_name=\"o3-mini\", temperature=1.0)\n\n # Verify chat.completions.create was called\n mock_client.chat.completions.create.assert_called_once()\n\n # Verify the response\n assert result.content == \"Test response\"\n assert result.model_name == \"o3-mini\"\n" }, { "path": "tests/test_openrouter_provider.py", "content": "\"\"\"Tests for OpenRouter provider.\"\"\"\n\nimport os\nfrom unittest.mock import Mock, patch\n\nimport pytest\n\nfrom providers.openrouter import OpenRouterProvider\nfrom providers.registry import ModelProviderRegistry\nfrom providers.shared import ProviderType\n\n\nclass TestOpenRouterProvider:\n \"\"\"Test cases for OpenRouter provider.\"\"\"\n\n def test_provider_initialization(self):\n \"\"\"Test OpenRouter provider initialization.\"\"\"\n provider = OpenRouterProvider(api_key=\"test-key\")\n assert provider.api_key == \"test-key\"\n assert provider.base_url == \"https://openrouter.ai/api/v1\"\n assert provider.FRIENDLY_NAME == \"OpenRouter\"\n\n def test_custom_headers(self):\n \"\"\"Test OpenRouter custom headers.\"\"\"\n # Test default headers\n assert \"HTTP-Referer\" in OpenRouterProvider.DEFAULT_HEADERS\n assert \"X-Title\" in OpenRouterProvider.DEFAULT_HEADERS\n\n # Test with environment variables\n with patch.dict(os.environ, {\"OPENROUTER_REFERER\": \"https://myapp.com\", \"OPENROUTER_TITLE\": \"My App\"}):\n from importlib import reload\n\n import providers.openrouter\n\n reload(providers.openrouter)\n\n provider = providers.openrouter.OpenRouterProvider(api_key=\"test-key\")\n assert provider.DEFAULT_HEADERS[\"HTTP-Referer\"] == \"https://myapp.com\"\n assert provider.DEFAULT_HEADERS[\"X-Title\"] == \"My App\"\n\n def test_model_validation(self):\n \"\"\"Test model validation.\"\"\"\n provider = OpenRouterProvider(api_key=\"test-key\")\n\n # OpenRouter accepts models with provider prefixes or known models\n assert provider.validate_model_name(\"openai/gpt-4\") is True\n assert provider.validate_model_name(\"anthropic/claude-3-opus\") is True\n assert provider.validate_model_name(\"google/any-model-name\") is True\n assert provider.validate_model_name(\"groq/llama-3.1-8b\") is True\n assert provider.validate_model_name(\"grok-4\") is True\n\n # Unknown models without provider prefix are rejected\n assert provider.validate_model_name(\"gpt-4\") is False\n assert provider.validate_model_name(\"unknown-model\") is False\n\n def test_get_capabilities(self):\n \"\"\"Test capability generation.\"\"\"\n provider = OpenRouterProvider(api_key=\"test-key\")\n\n # Test with a model in the registry (using alias)\n caps = provider.get_capabilities(\"o3\")\n assert caps.provider == ProviderType.OPENROUTER\n assert caps.model_name == \"openai/o3\" # Resolved name\n assert caps.friendly_name == \"OpenRouter (openai/o3)\"\n\n # Test with a model not in registry - should raise error\n with pytest.raises(ValueError, match=\"Unsupported model 'unknown-model' for provider openrouter\"):\n provider.get_capabilities(\"unknown-model\")\n\n # Test with model that has provider prefix - should get generic capabilities\n caps = provider.get_capabilities(\"provider/unknown-model\")\n assert caps.provider == ProviderType.OPENROUTER\n assert caps.model_name == \"provider/unknown-model\"\n assert caps.context_window == 32_768 # Safe default\n assert hasattr(caps, \"_is_generic\") and caps._is_generic is True\n\n def test_model_alias_resolution(self):\n \"\"\"Test model alias resolution.\"\"\"\n provider = OpenRouterProvider(api_key=\"test-key\")\n\n # Test alias resolution\n assert provider._resolve_model_name(\"opus\") == \"anthropic/claude-opus-4.5\"\n assert provider._resolve_model_name(\"opus4.5\") == \"anthropic/claude-opus-4.5\"\n assert provider._resolve_model_name(\"opus4.1\") == \"anthropic/claude-opus-4.1\"\n assert provider._resolve_model_name(\"sonnet\") == \"anthropic/claude-sonnet-4.5\"\n assert provider._resolve_model_name(\"sonnet4.1\") == \"anthropic/claude-sonnet-4.1\"\n assert provider._resolve_model_name(\"o3\") == \"openai/o3\"\n assert provider._resolve_model_name(\"o3-mini\") == \"openai/o3-mini\"\n assert provider._resolve_model_name(\"o3mini\") == \"openai/o3-mini\"\n assert provider._resolve_model_name(\"o4-mini\") == \"openai/o4-mini\"\n assert provider._resolve_model_name(\"o4-mini\") == \"openai/o4-mini\"\n assert provider._resolve_model_name(\"haiku\") == \"anthropic/claude-3.5-haiku\"\n assert provider._resolve_model_name(\"mistral\") == \"mistralai/mistral-large-2411\"\n assert provider._resolve_model_name(\"grok-4\") == \"x-ai/grok-4\"\n assert provider._resolve_model_name(\"grok4\") == \"x-ai/grok-4\"\n assert provider._resolve_model_name(\"grok\") == \"x-ai/grok-4\"\n assert provider._resolve_model_name(\"deepseek\") == \"deepseek/deepseek-r1-0528\"\n assert provider._resolve_model_name(\"r1\") == \"deepseek/deepseek-r1-0528\"\n\n # Test case-insensitive\n assert provider._resolve_model_name(\"OPUS\") == \"anthropic/claude-opus-4.5\"\n assert provider._resolve_model_name(\"SONNET\") == \"anthropic/claude-sonnet-4.5\"\n assert provider._resolve_model_name(\"O3\") == \"openai/o3\"\n assert provider._resolve_model_name(\"Mistral\") == \"mistralai/mistral-large-2411\"\n\n # Test direct model names (should pass through unchanged)\n assert provider._resolve_model_name(\"anthropic/claude-opus-4.1\") == \"anthropic/claude-opus-4.1\"\n assert provider._resolve_model_name(\"openai/o3\") == \"openai/o3\"\n\n # Test unknown models pass through\n assert provider._resolve_model_name(\"unknown-model\") == \"unknown-model\"\n assert provider._resolve_model_name(\"custom/model-v2\") == \"custom/model-v2\"\n\n def test_openrouter_registration(self):\n \"\"\"Test OpenRouter can be registered and retrieved.\"\"\"\n with patch.dict(os.environ, {\"OPENROUTER_API_KEY\": \"test-key\"}):\n # Clean up any existing registration\n ModelProviderRegistry.unregister_provider(ProviderType.OPENROUTER)\n\n # Register the provider\n ModelProviderRegistry.register_provider(ProviderType.OPENROUTER, OpenRouterProvider)\n\n # Retrieve and verify\n provider = ModelProviderRegistry.get_provider(ProviderType.OPENROUTER)\n assert provider is not None\n assert isinstance(provider, OpenRouterProvider)\n\n\nclass TestOpenRouterAutoMode:\n \"\"\"Test auto mode functionality when only OpenRouter is configured.\"\"\"\n\n def setup_method(self):\n \"\"\"Store original state before each test.\"\"\"\n self.registry = ModelProviderRegistry()\n self._original_providers = self.registry._providers.copy()\n self._original_initialized = self.registry._initialized_providers.copy()\n\n self.registry._providers.clear()\n self.registry._initialized_providers.clear()\n\n self._original_env = {}\n for key in [\"OPENROUTER_API_KEY\", \"GEMINI_API_KEY\", \"OPENAI_API_KEY\", \"DEFAULT_MODEL\"]:\n self._original_env[key] = os.environ.get(key)\n\n def teardown_method(self):\n \"\"\"Restore original state after each test.\"\"\"\n self.registry._providers.clear()\n self.registry._initialized_providers.clear()\n self.registry._providers.update(self._original_providers)\n self.registry._initialized_providers.update(self._original_initialized)\n\n for key, value in self._original_env.items():\n if value is None:\n os.environ.pop(key, None)\n else:\n os.environ[key] = value\n\n @pytest.mark.no_mock_provider\n def test_openrouter_only_auto_mode(self):\n \"\"\"Test that auto mode works when only OpenRouter is configured.\"\"\"\n os.environ.pop(\"GEMINI_API_KEY\", None)\n os.environ.pop(\"OPENAI_API_KEY\", None)\n os.environ[\"OPENROUTER_API_KEY\"] = \"test-openrouter-key\"\n os.environ[\"DEFAULT_MODEL\"] = \"auto\"\n\n mock_registry = Mock()\n model_names = [\n \"google/gemini-2.5-flash\",\n \"google/gemini-2.5-pro\",\n \"openai/o3\",\n \"openai/o3-mini\",\n \"anthropic/claude-opus-4.1\",\n \"anthropic/claude-sonnet-4.1\",\n ]\n mock_registry.list_models.return_value = model_names\n\n # Mock resolve to return a ModelCapabilities-like object for each model\n def mock_resolve(model_name):\n if model_name in model_names:\n mock_config = Mock()\n mock_config.provider = ProviderType.OPENROUTER\n mock_config.aliases = [] # Empty list of aliases\n mock_config.get_effective_capability_rank = Mock(return_value=50) # Add ranking method\n return mock_config\n return None\n\n mock_registry.resolve.side_effect = mock_resolve\n\n ModelProviderRegistry.register_provider(ProviderType.OPENROUTER, OpenRouterProvider)\n\n provider = ModelProviderRegistry.get_provider(ProviderType.OPENROUTER)\n assert provider is not None, \"OpenRouter provider should be available with API key\"\n provider._registry = mock_registry\n\n available_models = ModelProviderRegistry.get_available_models(respect_restrictions=True)\n\n assert len(available_models) > 0, \"Should find OpenRouter models in auto mode\"\n assert all(provider_type == ProviderType.OPENROUTER for provider_type in available_models.values())\n\n for model in model_names:\n assert model in available_models, f\"Model {model} should be available\"\n\n @pytest.mark.no_mock_provider\n def test_openrouter_with_restrictions(self):\n \"\"\"Test that OpenRouter respects model restrictions.\"\"\"\n os.environ.pop(\"GEMINI_API_KEY\", None)\n os.environ.pop(\"OPENAI_API_KEY\", None)\n os.environ[\"OPENROUTER_API_KEY\"] = \"test-openrouter-key\"\n os.environ.pop(\"OPENROUTER_ALLOWED_MODELS\", None)\n os.environ[\"OPENROUTER_ALLOWED_MODELS\"] = \"anthropic/claude-opus-4.1,google/gemini-2.5-flash\"\n os.environ[\"DEFAULT_MODEL\"] = \"auto\"\n\n # Force reload to pick up new environment variable\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n mock_registry = Mock()\n mock_models = [\n \"google/gemini-2.5-flash\",\n \"google/gemini-2.5-pro\",\n \"anthropic/claude-opus-4.1\",\n \"anthropic/claude-sonnet-4.1\",\n ]\n mock_registry.list_models.return_value = mock_models\n\n # Mock the resolve method to return model configs with aliases\n mock_model_config = Mock()\n mock_model_config.aliases = [] # Empty aliases for simplicity\n mock_model_config.get_effective_capability_rank = Mock(return_value=50) # Add ranking method\n mock_registry.resolve.return_value = mock_model_config\n\n ModelProviderRegistry.register_provider(ProviderType.OPENROUTER, OpenRouterProvider)\n\n provider = ModelProviderRegistry.get_provider(ProviderType.OPENROUTER)\n provider._registry = mock_registry\n\n available_models = ModelProviderRegistry.get_available_models(respect_restrictions=True)\n\n assert len(available_models) > 0, \"Should have some allowed models\"\n\n expected_allowed = {\"google/gemini-2.5-flash\", \"anthropic/claude-opus-4.1\"}\n\n assert (\n set(available_models.keys()) == expected_allowed\n ), f\"Expected {expected_allowed}, but got {set(available_models.keys())}\"\n\n @pytest.mark.no_mock_provider\n def test_no_providers_fails_auto_mode(self):\n \"\"\"Test that auto mode fails gracefully when no providers are available.\"\"\"\n os.environ.pop(\"GEMINI_API_KEY\", None)\n os.environ.pop(\"OPENAI_API_KEY\", None)\n os.environ.pop(\"OPENROUTER_API_KEY\", None)\n os.environ[\"DEFAULT_MODEL\"] = \"auto\"\n\n available_models = ModelProviderRegistry.get_available_models(respect_restrictions=True)\n\n assert len(available_models) == 0, \"Should have no models when no providers are configured\"\n\n @pytest.mark.no_mock_provider\n def test_openrouter_without_registry(self):\n \"\"\"Test that OpenRouter without _registry attribute doesn't crash.\"\"\"\n os.environ.pop(\"GEMINI_API_KEY\", None)\n os.environ.pop(\"OPENAI_API_KEY\", None)\n os.environ[\"OPENROUTER_API_KEY\"] = \"test-openrouter-key\"\n os.environ[\"DEFAULT_MODEL\"] = \"auto\"\n\n mock_provider_class = Mock()\n mock_provider_instance = Mock(spec=[\"get_provider_type\", \"list_models\", \"get_all_model_capabilities\"])\n mock_provider_instance.get_provider_type.return_value = ProviderType.OPENROUTER\n mock_provider_instance.list_models.return_value = []\n mock_provider_instance.get_all_model_capabilities.return_value = {}\n mock_provider_class.return_value = mock_provider_instance\n\n ModelProviderRegistry.register_provider(ProviderType.OPENROUTER, mock_provider_class)\n\n available_models = ModelProviderRegistry.get_available_models(respect_restrictions=True)\n\n assert len(available_models) == 0, \"Should have no models when OpenRouter has no registry\"\n\n\nclass TestOpenRouterRegistry:\n \"\"\"Test cases for OpenRouter model registry.\"\"\"\n\n def test_registry_loading(self):\n \"\"\"Test registry loads models from config.\"\"\"\n from providers.registries.openrouter import OpenRouterModelRegistry\n\n registry = OpenRouterModelRegistry()\n\n # Should have loaded models\n models = registry.list_models()\n assert len(models) > 0\n assert \"anthropic/claude-opus-4.1\" in models\n assert \"openai/o3\" in models\n\n # Should have loaded aliases\n aliases = registry.list_aliases()\n assert len(aliases) > 0\n assert \"opus\" in aliases\n assert \"o3\" in aliases\n assert \"sonnet\" in aliases\n\n def test_registry_capabilities(self):\n \"\"\"Test registry provides correct capabilities.\"\"\"\n from providers.registries.openrouter import OpenRouterModelRegistry\n\n registry = OpenRouterModelRegistry()\n\n # Test known model (opus alias now points to 4.5)\n caps = registry.get_capabilities(\"opus\")\n assert caps is not None\n assert caps.model_name == \"anthropic/claude-opus-4.5\"\n assert caps.context_window == 200000 # Claude's context window\n\n # Test using full model name for 4.5\n caps = registry.get_capabilities(\"anthropic/claude-opus-4.5\")\n assert caps is not None\n assert caps.model_name == \"anthropic/claude-opus-4.5\"\n\n # Test opus4.5 alias\n caps = registry.get_capabilities(\"opus4.5\")\n assert caps is not None\n assert caps.model_name == \"anthropic/claude-opus-4.5\"\n\n # Test using full model name for 4.1\n caps = registry.get_capabilities(\"anthropic/claude-opus-4.1\")\n assert caps is not None\n assert caps.model_name == \"anthropic/claude-opus-4.1\"\n\n # Test opus4.1 alias still works\n caps = registry.get_capabilities(\"opus4.1\")\n assert caps is not None\n assert caps.model_name == \"anthropic/claude-opus-4.1\"\n\n # Test unknown model\n caps = registry.get_capabilities(\"non-existent-model\")\n assert caps is None\n\n def test_multiple_aliases_same_model(self):\n \"\"\"Test multiple aliases pointing to same model.\"\"\"\n from providers.registries.openrouter import OpenRouterModelRegistry\n\n registry = OpenRouterModelRegistry()\n\n # All these should resolve to Claude Sonnet 4.5\n sonnet_45_aliases = [\"sonnet\", \"sonnet4.5\"]\n for alias in sonnet_45_aliases:\n config = registry.resolve(alias)\n assert config is not None\n assert config.model_name == \"anthropic/claude-sonnet-4.5\"\n\n # Test Sonnet 4.1 alias\n config = registry.resolve(\"sonnet4.1\")\n assert config is not None\n assert config.model_name == \"anthropic/claude-sonnet-4.1\"\n\n\nclass TestOpenRouterFunctionality:\n \"\"\"Test OpenRouter-specific functionality.\"\"\"\n\n def test_openrouter_always_uses_correct_url(self):\n \"\"\"Test that OpenRouter always uses the correct base URL.\"\"\"\n provider = OpenRouterProvider(api_key=\"test-key\")\n assert provider.base_url == \"https://openrouter.ai/api/v1\"\n\n # Even if we try to change it, it should remain the OpenRouter URL\n # (This is a characteristic of the OpenRouter provider)\n provider.base_url = \"http://example.com\" # Try to change it\n # But new instances should always use the correct URL\n provider2 = OpenRouterProvider(api_key=\"test-key\")\n assert provider2.base_url == \"https://openrouter.ai/api/v1\"\n\n def test_openrouter_headers_set_correctly(self):\n \"\"\"Test that OpenRouter specific headers are set.\"\"\"\n provider = OpenRouterProvider(api_key=\"test-key\")\n\n # Check default headers\n assert \"HTTP-Referer\" in provider.DEFAULT_HEADERS\n assert \"X-Title\" in provider.DEFAULT_HEADERS\n assert provider.DEFAULT_HEADERS[\"X-Title\"] == \"PAL MCP Server\"\n\n def test_openrouter_model_registry_initialized(self):\n \"\"\"Test that model registry is properly initialized.\"\"\"\n provider = OpenRouterProvider(api_key=\"test-key\")\n\n # Registry should be initialized\n assert hasattr(provider, \"_registry\")\n assert provider._registry is not None\n" }, { "path": "tests/test_openrouter_registry.py", "content": "\"\"\"Tests for OpenRouter model registry functionality.\"\"\"\n\nimport json\nimport os\nimport tempfile\nfrom unittest.mock import patch\n\nimport pytest\n\nfrom providers.registries.openrouter import OpenRouterModelRegistry\nfrom providers.shared import ModelCapabilities, ProviderType\n\n\nclass TestOpenRouterModelRegistry:\n \"\"\"Test cases for OpenRouter model registry.\"\"\"\n\n def test_registry_initialization(self):\n \"\"\"Test registry initializes with default config.\"\"\"\n registry = OpenRouterModelRegistry()\n\n # Should load models from default location\n assert len(registry.list_models()) > 0\n assert len(registry.list_aliases()) > 0\n\n def test_custom_config_path(self):\n \"\"\"Test registry with custom config path.\"\"\"\n # Create temporary config\n config_data = {\n \"models\": [\n {\n \"model_name\": \"test/model-1\",\n \"aliases\": [\"test1\", \"t1\"],\n \"context_window\": 4096,\n \"max_output_tokens\": 2048,\n }\n ]\n }\n\n with tempfile.NamedTemporaryFile(mode=\"w\", suffix=\".json\", delete=False) as f:\n json.dump(config_data, f)\n temp_path = f.name\n\n try:\n registry = OpenRouterModelRegistry(config_path=temp_path)\n assert len(registry.list_models()) == 1\n assert \"test/model-1\" in registry.list_models()\n assert \"test1\" in registry.list_aliases()\n assert \"t1\" in registry.list_aliases()\n finally:\n os.unlink(temp_path)\n\n def test_environment_variable_override(self):\n \"\"\"Test OPENROUTER_MODELS_CONFIG_PATH environment variable.\"\"\"\n # Create custom config\n config_data = {\n \"models\": [\n {\"model_name\": \"env/model\", \"aliases\": [\"envtest\"], \"context_window\": 8192, \"max_output_tokens\": 4096}\n ]\n }\n\n with tempfile.NamedTemporaryFile(mode=\"w\", suffix=\".json\", delete=False) as f:\n json.dump(config_data, f)\n temp_path = f.name\n\n try:\n # Set environment variable\n original_env = os.environ.get(\"OPENROUTER_MODELS_CONFIG_PATH\")\n os.environ[\"OPENROUTER_MODELS_CONFIG_PATH\"] = temp_path\n\n # Create registry without explicit path\n registry = OpenRouterModelRegistry()\n\n # Should load from environment path\n assert \"env/model\" in registry.list_models()\n assert \"envtest\" in registry.list_aliases()\n\n finally:\n # Restore environment\n if original_env is not None:\n os.environ[\"OPENROUTER_MODELS_CONFIG_PATH\"] = original_env\n else:\n del os.environ[\"OPENROUTER_MODELS_CONFIG_PATH\"]\n os.unlink(temp_path)\n\n def test_alias_resolution(self):\n \"\"\"Test alias resolution functionality.\"\"\"\n registry = OpenRouterModelRegistry()\n\n # Test various aliases\n test_cases = [\n (\"opus\", \"anthropic/claude-opus-4.5\"), # opus now points to 4.5\n (\"OPUS\", \"anthropic/claude-opus-4.5\"), # Case insensitive\n (\"claude-opus\", \"anthropic/claude-opus-4.5\"),\n (\"opus4.5\", \"anthropic/claude-opus-4.5\"),\n (\"opus4.1\", \"anthropic/claude-opus-4.1\"), # 4.1 still accessible\n (\"sonnet\", \"anthropic/claude-sonnet-4.5\"),\n (\"o3\", \"openai/o3\"),\n (\"deepseek\", \"deepseek/deepseek-r1-0528\"),\n (\"mistral\", \"mistralai/mistral-large-2411\"),\n ]\n\n for alias, expected_model in test_cases:\n config = registry.resolve(alias)\n assert config is not None, f\"Failed to resolve alias '{alias}'\"\n assert config.model_name == expected_model\n\n def test_direct_model_name_lookup(self):\n \"\"\"Test looking up models by their full name.\"\"\"\n registry = OpenRouterModelRegistry()\n\n # Should be able to look up by full model name\n config = registry.resolve(\"anthropic/claude-opus-4.1\")\n assert config is not None\n assert config.model_name == \"anthropic/claude-opus-4.1\"\n\n config = registry.resolve(\"openai/o3\")\n assert config is not None\n assert config.model_name == \"openai/o3\"\n\n def test_unknown_model_resolution(self):\n \"\"\"Test resolution of unknown models.\"\"\"\n registry = OpenRouterModelRegistry()\n\n # Unknown aliases should return None\n assert registry.resolve(\"unknown-alias\") is None\n assert registry.resolve(\"\") is None\n assert registry.resolve(\"non-existent\") is None\n\n def test_model_capabilities_conversion(self):\n \"\"\"Test that registry returns ModelCapabilities directly.\"\"\"\n registry = OpenRouterModelRegistry()\n\n config = registry.resolve(\"opus\")\n assert config is not None\n\n # Registry now returns ModelCapabilities objects directly\n # opus alias now points to 4.5\n assert config.provider == ProviderType.OPENROUTER\n assert config.model_name == \"anthropic/claude-opus-4.5\"\n assert config.friendly_name == \"OpenRouter (anthropic/claude-opus-4.5)\"\n assert config.context_window == 200000\n assert not config.supports_extended_thinking\n\n def test_duplicate_alias_detection(self):\n \"\"\"Test that duplicate aliases are detected.\"\"\"\n config_data = {\n \"models\": [\n {\"model_name\": \"test/model-1\", \"aliases\": [\"dupe\"], \"context_window\": 4096, \"max_output_tokens\": 2048},\n {\n \"model_name\": \"test/model-2\",\n \"aliases\": [\"DUPE\"], # Same alias, different case\n \"context_window\": 8192,\n \"max_output_tokens\": 2048,\n },\n ]\n }\n\n with tempfile.NamedTemporaryFile(mode=\"w\", suffix=\".json\", delete=False) as f:\n json.dump(config_data, f)\n temp_path = f.name\n\n try:\n with pytest.raises(ValueError, match=\"Duplicate alias\"):\n OpenRouterModelRegistry(config_path=temp_path)\n finally:\n os.unlink(temp_path)\n\n def test_backwards_compatibility_max_tokens(self):\n \"\"\"Test that legacy max_tokens field maps to max_output_tokens.\"\"\"\n config_data = {\n \"models\": [\n {\n \"model_name\": \"test/old-model\",\n \"aliases\": [\"old\"],\n \"max_tokens\": 16384, # Old field name should cause error\n \"supports_extended_thinking\": False,\n }\n ]\n }\n\n with tempfile.NamedTemporaryFile(mode=\"w\", suffix=\".json\", delete=False) as f:\n json.dump(config_data, f)\n temp_path = f.name\n\n try:\n with patch.dict(\"os.environ\", {}, clear=True):\n with pytest.raises(ValueError, match=\"max_output_tokens\"):\n OpenRouterModelRegistry(config_path=temp_path)\n finally:\n os.unlink(temp_path)\n\n def test_missing_config_file(self):\n \"\"\"Test behavior with missing config file.\"\"\"\n # Use a non-existent path\n with patch.dict(\"os.environ\", {}, clear=True):\n registry = OpenRouterModelRegistry(config_path=\"/non/existent/path.json\")\n\n # Should initialize with empty maps\n assert len(registry.list_models()) == 0\n assert len(registry.list_aliases()) == 0\n assert registry.resolve(\"anything\") is None\n\n def test_invalid_json_config(self):\n \"\"\"Test handling of invalid JSON.\"\"\"\n with tempfile.NamedTemporaryFile(mode=\"w\", suffix=\".json\", delete=False) as f:\n f.write(\"{ invalid json }\")\n temp_path = f.name\n\n try:\n registry = OpenRouterModelRegistry(config_path=temp_path)\n # Should handle gracefully and initialize empty\n assert len(registry.list_models()) == 0\n assert len(registry.list_aliases()) == 0\n finally:\n os.unlink(temp_path)\n\n def test_model_with_all_capabilities(self):\n \"\"\"Test model with all capability flags.\"\"\"\n from providers.shared import TemperatureConstraint\n\n caps = ModelCapabilities(\n provider=ProviderType.OPENROUTER,\n model_name=\"test/full-featured\",\n friendly_name=\"OpenRouter (test/full-featured)\",\n aliases=[\"full\"],\n context_window=128000,\n max_output_tokens=8192,\n supports_extended_thinking=True,\n supports_system_prompts=True,\n supports_streaming=True,\n supports_function_calling=True,\n supports_json_mode=True,\n description=\"Fully featured test model\",\n temperature_constraint=TemperatureConstraint.create(\"range\"),\n )\n assert caps.context_window == 128000\n assert caps.supports_extended_thinking\n assert caps.supports_system_prompts\n assert caps.supports_streaming\n assert caps.supports_function_calling\n # Note: supports_json_mode is not in ModelCapabilities yet\n" }, { "path": "tests/test_openrouter_store_parameter.py", "content": "\"\"\"Tests for OpenRouter store parameter handling in responses endpoint.\n\nRegression tests for GitHub Issue #348: OpenAI \"store\" parameter validation error\nfor certain models via OpenRouter.\n\nOpenRouter's /responses endpoint rejects store:true via Zod validation. This is an\nendpoint-level limitation, not model-specific. These tests verify that:\n- OpenRouter provider omits the store parameter\n- Direct OpenAI provider includes store: true\n\"\"\"\n\nimport unittest\nfrom unittest.mock import Mock, patch\n\nfrom providers.openai_compatible import OpenAICompatibleProvider\nfrom providers.shared import ProviderType\n\n\nclass MockOpenRouterProvider(OpenAICompatibleProvider):\n \"\"\"Mock provider that simulates OpenRouter behavior.\"\"\"\n\n FRIENDLY_NAME = \"OpenRouter Test\"\n\n def get_provider_type(self):\n return ProviderType.OPENROUTER\n\n def get_capabilities(self, model_name):\n mock_caps = Mock()\n mock_caps.default_reasoning_effort = \"high\"\n return mock_caps\n\n def validate_model_name(self, model_name):\n return True\n\n def list_models(self, **kwargs):\n return [\"openai/gpt-5-pro\", \"openai/gpt-5.1-codex\"]\n\n\nclass MockOpenAIProvider(OpenAICompatibleProvider):\n \"\"\"Mock provider that simulates direct OpenAI behavior.\"\"\"\n\n FRIENDLY_NAME = \"OpenAI Test\"\n\n def get_provider_type(self):\n return ProviderType.OPENAI\n\n def get_capabilities(self, model_name):\n mock_caps = Mock()\n mock_caps.default_reasoning_effort = \"high\"\n return mock_caps\n\n def validate_model_name(self, model_name):\n return True\n\n def list_models(self, **kwargs):\n return [\"gpt-5-pro\", \"gpt-5.1-codex\"]\n\n\nclass TestStoreParameterHandling(unittest.TestCase):\n \"\"\"Test store parameter is conditionally included based on provider type.\n\n **Feature: openrouter-store-parameter-fix, Property 1: OpenRouter requests omit store parameter**\n **Feature: openrouter-store-parameter-fix, Property 2: Direct OpenAI requests include store parameter**\n \"\"\"\n\n def test_openrouter_responses_omits_store_parameter(self):\n \"\"\"Test that OpenRouter provider omits store parameter from responses endpoint.\n\n **Feature: openrouter-store-parameter-fix, Property 1: OpenRouter requests omit store parameter**\n **Validates: Requirements 1.1, 2.1**\n\n OpenRouter's /responses endpoint rejects store:true via Zod validation (Issue #348).\n The store parameter should be omitted entirely for OpenRouter requests.\n \"\"\"\n # Capture the completion_params passed to the API\n captured_params = {}\n\n def capture_create(**kwargs):\n captured_params.update(kwargs)\n # Return a mock response\n mock_response = Mock()\n mock_response.output_text = \"Test response\"\n mock_response.usage = None\n return mock_response\n\n mock_client_instance = Mock()\n mock_client_instance.responses.create = capture_create\n\n with patch.object(\n MockOpenRouterProvider, \"client\", new_callable=lambda: property(lambda self: mock_client_instance)\n ):\n provider = MockOpenRouterProvider(\"test-key\")\n\n # Call the method that builds completion_params\n provider._generate_with_responses_endpoint(\n model_name=\"openai/gpt-5-pro\",\n messages=[{\"role\": \"user\", \"content\": \"test\"}],\n temperature=0.7,\n )\n\n # Verify store parameter is NOT in the request\n self.assertNotIn(\"store\", captured_params, \"OpenRouter requests should NOT include 'store' parameter\")\n\n def test_openai_responses_includes_store_parameter(self):\n \"\"\"Test that direct OpenAI provider includes store parameter in responses endpoint.\n\n **Feature: openrouter-store-parameter-fix, Property 2: Direct OpenAI requests include store parameter**\n **Validates: Requirements 1.2, 2.2**\n\n Direct OpenAI API supports the store parameter for stored completions.\n The store parameter should be included with value True for OpenAI requests.\n \"\"\"\n # Capture the completion_params passed to the API\n captured_params = {}\n\n def capture_create(**kwargs):\n captured_params.update(kwargs)\n # Return a mock response\n mock_response = Mock()\n mock_response.output_text = \"Test response\"\n mock_response.usage = None\n return mock_response\n\n mock_client_instance = Mock()\n mock_client_instance.responses.create = capture_create\n\n with patch.object(\n MockOpenAIProvider, \"client\", new_callable=lambda: property(lambda self: mock_client_instance)\n ):\n provider = MockOpenAIProvider(\"test-key\")\n\n # Call the method that builds completion_params\n provider._generate_with_responses_endpoint(\n model_name=\"gpt-5-pro\",\n messages=[{\"role\": \"user\", \"content\": \"test\"}],\n temperature=0.7,\n )\n\n # Verify store parameter IS in the request with value True\n self.assertIn(\"store\", captured_params, \"OpenAI requests should include 'store' parameter\")\n self.assertTrue(captured_params[\"store\"], \"OpenAI requests should have store=True\")\n\n\nif __name__ == \"__main__\":\n unittest.main()\n" }, { "path": "tests/test_parse_model_option.py", "content": "\"\"\"Tests for parse_model_option function.\"\"\"\n\nfrom server import parse_model_option\n\n\nclass TestParseModelOption:\n \"\"\"Test cases for model option parsing.\"\"\"\n\n def test_openrouter_free_suffix_preserved(self):\n \"\"\"Test that OpenRouter :free suffix is preserved as part of model name.\"\"\"\n model, option = parse_model_option(\"openai/gpt-3.5-turbo:free\")\n assert model == \"openai/gpt-3.5-turbo:free\"\n assert option is None\n\n def test_openrouter_beta_suffix_preserved(self):\n \"\"\"Test that OpenRouter :beta suffix is preserved as part of model name.\"\"\"\n model, option = parse_model_option(\"anthropic/claude-opus-4.1:beta\")\n assert model == \"anthropic/claude-opus-4.1:beta\"\n assert option is None\n\n def test_openrouter_preview_suffix_preserved(self):\n \"\"\"Test that OpenRouter :preview suffix is preserved as part of model name.\"\"\"\n model, option = parse_model_option(\"google/gemini-pro:preview\")\n assert model == \"google/gemini-pro:preview\"\n assert option is None\n\n def test_ollama_tag_parsed_as_option(self):\n \"\"\"Test that Ollama tags are parsed as options.\"\"\"\n model, option = parse_model_option(\"llama3.2:latest\")\n assert model == \"llama3.2\"\n assert option == \"latest\"\n\n def test_consensus_stance_parsed_as_option(self):\n \"\"\"Test that consensus stances are parsed as options.\"\"\"\n model, option = parse_model_option(\"o3:for\")\n assert model == \"o3\"\n assert option == \"for\"\n\n model, option = parse_model_option(\"gemini-2.5-pro:against\")\n assert model == \"gemini-2.5-pro\"\n assert option == \"against\"\n\n def test_openrouter_unknown_suffix_parsed_as_option(self):\n \"\"\"Test that unknown suffixes on OpenRouter models are parsed as options.\"\"\"\n model, option = parse_model_option(\"openai/gpt-4:custom-tag\")\n assert model == \"openai/gpt-4\"\n assert option == \"custom-tag\"\n\n def test_plain_model_name(self):\n \"\"\"Test plain model names without colons.\"\"\"\n model, option = parse_model_option(\"gpt-4\")\n assert model == \"gpt-4\"\n assert option is None\n\n def test_url_not_parsed(self):\n \"\"\"Test that URLs are not parsed for options.\"\"\"\n model, option = parse_model_option(\"http://localhost:8080\")\n assert model == \"http://localhost:8080\"\n assert option is None\n\n def test_whitespace_handling(self):\n \"\"\"Test that whitespace is properly stripped.\"\"\"\n model, option = parse_model_option(\" openai/gpt-3.5-turbo:free \")\n assert model == \"openai/gpt-3.5-turbo:free\"\n assert option is None\n\n model, option = parse_model_option(\" llama3.2 : latest \")\n assert model == \"llama3.2\"\n assert option == \"latest\"\n\n def test_case_insensitive_suffix_matching(self):\n \"\"\"Test that OpenRouter suffix matching is case-insensitive.\"\"\"\n model, option = parse_model_option(\"openai/gpt-3.5-turbo:FREE\")\n assert model == \"openai/gpt-3.5-turbo:FREE\" # Original case preserved\n assert option is None\n\n model, option = parse_model_option(\"openai/gpt-3.5-turbo:Free\")\n assert model == \"openai/gpt-3.5-turbo:Free\" # Original case preserved\n assert option is None\n" }, { "path": "tests/test_path_traversal_security.py", "content": "\"\"\"\nTest path traversal security fix.\n\nFixes vulnerability reported in:\n- https://github.com/BeehiveInnovations/zen-mcp-server/issues/293\n- https://github.com/BeehiveInnovations/zen-mcp-server/issues/312\n\nThe vulnerability: is_dangerous_path() only did exact string matching,\nso /etc was blocked but /etc/passwd was allowed.\n\nAdditionally, this fix properly handles home directory containers:\n- /home and C:\\\\Users are blocked (exact match only)\n- /home/user/project paths are allowed through is_dangerous_path()\n and handled by is_home_directory_root() in resolve_and_validate_path()\n\"\"\"\n\nfrom pathlib import Path\n\nfrom utils.security_config import is_dangerous_path\n\n\nclass TestPathTraversalFix:\n \"\"\"Test that subdirectories of dangerous system paths are blocked.\"\"\"\n\n def test_exact_match_still_works(self):\n \"\"\"Test that exact dangerous paths are still blocked.\"\"\"\n assert is_dangerous_path(Path(\"/etc\")) is True\n assert is_dangerous_path(Path(\"/usr\")) is True\n assert is_dangerous_path(Path(\"/var\")) is True\n\n def test_subdirectory_now_blocked(self):\n \"\"\"Test that subdirectories of system paths are blocked (the fix).\"\"\"\n # These were allowed before the fix\n assert is_dangerous_path(Path(\"/etc/passwd\")) is True\n assert is_dangerous_path(Path(\"/etc/shadow\")) is True\n assert is_dangerous_path(Path(\"/etc/hosts\")) is True\n assert is_dangerous_path(Path(\"/var/log/auth.log\")) is True\n\n def test_deeply_nested_blocked(self):\n \"\"\"Test that deeply nested system paths are blocked.\"\"\"\n assert is_dangerous_path(Path(\"/etc/ssh/sshd_config\")) is True\n assert is_dangerous_path(Path(\"/usr/local/bin/python\")) is True\n\n def test_root_blocked(self):\n \"\"\"Test that root directory is blocked.\"\"\"\n assert is_dangerous_path(Path(\"/\")) is True\n\n def test_safe_paths_allowed(self):\n \"\"\"Test that safe paths are still allowed.\"\"\"\n # User project directories should be allowed\n assert is_dangerous_path(Path(\"/tmp/test\")) is False\n assert is_dangerous_path(Path(\"/tmp/myproject/src\")) is False\n\n def test_similar_names_not_blocked(self):\n \"\"\"Test that paths with similar names are not blocked.\"\"\"\n # /etcbackup should NOT be blocked (it's not under /etc)\n assert is_dangerous_path(Path(\"/tmp/etcbackup\")) is False\n assert is_dangerous_path(Path(\"/tmp/my_etc_files\")) is False\n\n\nclass TestHomeDirectoryHandling:\n \"\"\"Test that home directory containers are handled correctly.\n\n Home containers (/home, C:\\\\Users) should only block the exact path,\n not subdirectories. Subdirectory access control is delegated to\n is_home_directory_root() in resolve_and_validate_path().\n \"\"\"\n\n def test_home_container_blocked(self):\n \"\"\"Test that /home itself is blocked.\"\"\"\n assert is_dangerous_path(Path(\"/home\")) is True\n\n def test_home_subdirectories_allowed(self):\n \"\"\"Test that /home subdirectories pass through is_dangerous_path().\n\n These paths should NOT be blocked by is_dangerous_path() because:\n 1. /home/user/project is a valid user workspace\n 2. Access control for /home/username is handled by is_home_directory_root()\n \"\"\"\n # User home directories should pass is_dangerous_path()\n # (they are handled by is_home_directory_root() separately)\n assert is_dangerous_path(Path(\"/home/user\")) is False\n assert is_dangerous_path(Path(\"/home/user/project\")) is False\n assert is_dangerous_path(Path(\"/home/user/project/src/main.py\")) is False\n\n def test_home_deeply_nested_allowed(self):\n \"\"\"Test that deeply nested home paths are allowed.\"\"\"\n assert is_dangerous_path(Path(\"/home/user/documents/work/project/src\")) is False\n\n\nclass TestRegressionPrevention:\n \"\"\"Regression tests for the specific vulnerability.\"\"\"\n\n def test_etc_passwd_blocked(self):\n \"\"\"Test /etc/passwd is blocked (common attack target).\"\"\"\n assert is_dangerous_path(Path(\"/etc/passwd\")) is True\n\n def test_etc_shadow_blocked(self):\n \"\"\"Test /etc/shadow is blocked (password hashes).\"\"\"\n assert is_dangerous_path(Path(\"/etc/shadow\")) is True\n\n\nclass TestWindowsPathHandling:\n \"\"\"Test Windows path handling with trailing backslash.\n\n Fixes issue reported in PR #353: Windows paths like C:\\\\ have trailing\n backslash which caused double separator issues with string prefix matching.\n Using Path.is_relative_to() resolves this correctly.\n \"\"\"\n\n def test_windows_root_drive_blocked(self):\n \"\"\"Test that Windows root drive C:\\\\ is blocked.\"\"\"\n from pathlib import PureWindowsPath\n\n # Simulate Windows path behavior using PureWindowsPath\n # On Linux, we test the logic with PureWindowsPath to verify cross-platform correctness\n c_root = PureWindowsPath(\"C:\\\\\")\n assert c_root.parent == c_root # Root check works\n\n def test_windows_dangerous_subdirectory_detection(self):\n \"\"\"Test that Windows subdirectories are correctly detected as dangerous.\n\n This verifies the fix for the double backslash issue:\n - Before fix: \"C:\\\\\" + \"\\\\\" = \"C:\\\\\\\\\" which doesn't match \"C:\\\\Users\"\n - After fix: Path.is_relative_to() handles this correctly\n \"\"\"\n from pathlib import PureWindowsPath\n\n # Verify is_relative_to works correctly for Windows paths\n c_users = PureWindowsPath(\"C:\\\\Users\")\n c_root = PureWindowsPath(\"C:\\\\\")\n\n # This is the key test - subdirectory detection must work\n assert c_users.is_relative_to(c_root) is True\n\n # Deeper paths should also work\n c_users_admin = PureWindowsPath(\"C:\\\\Users\\\\Admin\")\n assert c_users_admin.is_relative_to(c_root) is True\n assert c_users_admin.is_relative_to(c_users) is True\n\n def test_windows_path_not_relative_to_different_drive(self):\n \"\"\"Test that paths on different drives are not related.\"\"\"\n from pathlib import PureWindowsPath\n\n d_path = PureWindowsPath(\"D:\\\\Data\")\n c_root = PureWindowsPath(\"C:\\\\\")\n\n # D: drive paths should not be relative to C:\n assert d_path.is_relative_to(c_root) is False\n" }, { "path": "tests/test_per_tool_model_defaults.py", "content": "\"\"\"\nTest per-tool model default selection functionality\n\"\"\"\n\nimport json\nimport os\nimport shutil\nimport tempfile\nfrom unittest.mock import MagicMock, patch\n\nimport pytest\n\nfrom providers.registry import ModelProviderRegistry, ProviderType\nfrom tools.analyze import AnalyzeTool\nfrom tools.chat import ChatTool\nfrom tools.codereview import CodeReviewTool\nfrom tools.debug import DebugIssueTool\nfrom tools.models import ToolModelCategory\nfrom tools.precommit import PrecommitTool\nfrom tools.shared.base_tool import BaseTool\nfrom tools.shared.exceptions import ToolExecutionError\nfrom tools.thinkdeep import ThinkDeepTool\n\n\nclass TestToolModelCategories:\n \"\"\"Test that each tool returns the correct model category.\"\"\"\n\n def test_thinkdeep_category(self):\n tool = ThinkDeepTool()\n assert tool.get_model_category() == ToolModelCategory.EXTENDED_REASONING\n\n def test_debug_category(self):\n tool = DebugIssueTool()\n assert tool.get_model_category() == ToolModelCategory.EXTENDED_REASONING\n\n def test_analyze_category(self):\n tool = AnalyzeTool()\n assert tool.get_model_category() == ToolModelCategory.EXTENDED_REASONING\n\n def test_precommit_category(self):\n tool = PrecommitTool()\n assert tool.get_model_category() == ToolModelCategory.EXTENDED_REASONING\n\n def test_chat_category(self):\n tool = ChatTool()\n assert tool.get_model_category() == ToolModelCategory.FAST_RESPONSE\n\n def test_codereview_category(self):\n tool = CodeReviewTool()\n assert tool.get_model_category() == ToolModelCategory.EXTENDED_REASONING\n\n def test_base_tool_default_category(self):\n # Test that BaseTool defaults to BALANCED\n class TestTool(BaseTool):\n def get_name(self):\n return \"test\"\n\n def get_description(self):\n return \"test\"\n\n def get_input_schema(self):\n return {}\n\n def get_system_prompt(self):\n return \"test\"\n\n def get_request_model(self):\n return MagicMock\n\n async def prepare_prompt(self, request):\n return \"test\"\n\n tool = TestTool()\n assert tool.get_model_category() == ToolModelCategory.BALANCED\n\n\nclass TestModelSelection:\n \"\"\"Test model selection based on tool categories.\"\"\"\n\n def teardown_method(self):\n \"\"\"Clean up after each test to prevent state pollution.\"\"\"\n ModelProviderRegistry.clear_cache()\n # Unregister all providers\n for provider_type in list(ProviderType):\n ModelProviderRegistry.unregister_provider(provider_type)\n\n def test_extended_reasoning_with_openai(self):\n \"\"\"Test EXTENDED_REASONING with OpenAI provider.\"\"\"\n # Setup with only OpenAI provider\n ModelProviderRegistry.clear_cache()\n # First unregister all providers to ensure isolation\n for provider_type in list(ProviderType):\n ModelProviderRegistry.unregister_provider(provider_type)\n\n with patch.dict(os.environ, {\"OPENAI_API_KEY\": \"test-key\"}, clear=False):\n from providers.openai import OpenAIModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n\n model = ModelProviderRegistry.get_preferred_fallback_model(ToolModelCategory.EXTENDED_REASONING)\n # OpenAI prefers GPT-5.1-Codex for extended reasoning (coding tasks)\n assert model == \"gpt-5.1-codex\"\n\n def test_extended_reasoning_with_gemini_only(self):\n \"\"\"Test EXTENDED_REASONING prefers pro when only Gemini is available.\"\"\"\n # Clear cache and unregister all providers first\n ModelProviderRegistry.clear_cache()\n for provider_type in list(ProviderType):\n ModelProviderRegistry.unregister_provider(provider_type)\n\n # Register only Gemini provider\n with patch.dict(os.environ, {\"GOOGLE_API_KEY\": \"test-key\"}, clear=False):\n from providers.gemini import GeminiModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n model = ModelProviderRegistry.get_preferred_fallback_model(ToolModelCategory.EXTENDED_REASONING)\n # Gemini should return one of its models for extended reasoning\n # The default behavior may return flash when pro is not explicitly preferred\n assert model in [\"gemini-3-pro-preview\", \"gemini-2.5-flash\", \"gemini-2.0-flash\"]\n\n def test_fast_response_with_openai(self):\n \"\"\"Test FAST_RESPONSE with OpenAI provider.\"\"\"\n # Setup with only OpenAI provider\n ModelProviderRegistry.clear_cache()\n # First unregister all providers to ensure isolation\n for provider_type in list(ProviderType):\n ModelProviderRegistry.unregister_provider(provider_type)\n\n with patch.dict(os.environ, {\"OPENAI_API_KEY\": \"test-key\"}, clear=False):\n from providers.openai import OpenAIModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n\n model = ModelProviderRegistry.get_preferred_fallback_model(ToolModelCategory.FAST_RESPONSE)\n # OpenAI now prefers gpt-5.2 for fast response (based on our new preference order)\n assert model == \"gpt-5.2\"\n\n def test_fast_response_with_gemini_only(self):\n \"\"\"Test FAST_RESPONSE prefers flash when only Gemini is available.\"\"\"\n # Clear cache and unregister all providers first\n ModelProviderRegistry.clear_cache()\n for provider_type in list(ProviderType):\n ModelProviderRegistry.unregister_provider(provider_type)\n\n # Register only Gemini provider\n with patch.dict(os.environ, {\"GOOGLE_API_KEY\": \"test-key\"}, clear=False):\n from providers.gemini import GeminiModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n model = ModelProviderRegistry.get_preferred_fallback_model(ToolModelCategory.FAST_RESPONSE)\n # Gemini should return one of its models for fast response\n assert model in [\"gemini-2.5-flash\", \"gemini-2.0-flash\", \"gemini-2.5-pro\"]\n\n def test_balanced_category_fallback(self):\n \"\"\"Test BALANCED category uses existing logic.\"\"\"\n # Setup with only OpenAI provider\n ModelProviderRegistry.clear_cache()\n # First unregister all providers to ensure isolation\n for provider_type in list(ProviderType):\n ModelProviderRegistry.unregister_provider(provider_type)\n\n with patch.dict(os.environ, {\"OPENAI_API_KEY\": \"test-key\"}, clear=False):\n from providers.openai import OpenAIModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n\n model = ModelProviderRegistry.get_preferred_fallback_model(ToolModelCategory.BALANCED)\n # OpenAI prefers gpt-5.2 for balanced (based on our new preference order)\n assert model == \"gpt-5.2\"\n\n def test_no_category_uses_balanced_logic(self):\n \"\"\"Test that no category specified uses balanced logic.\"\"\"\n # Setup with only Gemini provider\n with patch.dict(os.environ, {\"GEMINI_API_KEY\": \"test-key\"}, clear=False):\n from providers.gemini import GeminiModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n model = ModelProviderRegistry.get_preferred_fallback_model()\n # Should pick flash for balanced use\n assert model == \"gemini-2.5-flash\"\n\n\nclass TestFlexibleModelSelection:\n \"\"\"Test that model selection handles various naming scenarios.\"\"\"\n\n def test_fallback_handles_mixed_model_names(self):\n \"\"\"Test that fallback selection works with different providers.\"\"\"\n # Test with different provider configurations\n test_cases = [\n # Case 1: OpenAI provider for extended reasoning\n {\n \"env\": {\"OPENAI_API_KEY\": \"test-key\"},\n \"provider_type\": ProviderType.OPENAI,\n \"category\": ToolModelCategory.EXTENDED_REASONING,\n \"expected\": \"gpt-5.1-codex\", # GPT-5.1-Codex prioritized for coding tasks\n },\n # Case 2: Gemini provider for fast response\n {\n \"env\": {\"GEMINI_API_KEY\": \"test-key\"},\n \"provider_type\": ProviderType.GOOGLE,\n \"category\": ToolModelCategory.FAST_RESPONSE,\n \"expected\": \"gemini-2.5-flash\",\n },\n # Case 3: OpenAI provider for fast response\n {\n \"env\": {\"OPENAI_API_KEY\": \"test-key\"},\n \"provider_type\": ProviderType.OPENAI,\n \"category\": ToolModelCategory.FAST_RESPONSE,\n \"expected\": \"gpt-5.2\", # Based on new preference order\n },\n ]\n\n for case in test_cases:\n # Clear registry for clean test\n ModelProviderRegistry.clear_cache()\n # First unregister all providers to ensure isolation\n for provider_type in list(ProviderType):\n ModelProviderRegistry.unregister_provider(provider_type)\n\n with patch.dict(os.environ, case[\"env\"], clear=False):\n # Register the appropriate provider\n if case[\"provider_type\"] == ProviderType.OPENAI:\n from providers.openai import OpenAIModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n elif case[\"provider_type\"] == ProviderType.GOOGLE:\n from providers.gemini import GeminiModelProvider\n\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n model = ModelProviderRegistry.get_preferred_fallback_model(case[\"category\"])\n assert model == case[\"expected\"], f\"Failed for case: {case}, got {model}\"\n\n\nclass TestCustomProviderFallback:\n \"\"\"Test fallback to custom/openrouter providers.\"\"\"\n\n def test_extended_reasoning_custom_fallback(self):\n \"\"\"Test EXTENDED_REASONING with custom provider.\"\"\"\n # Setup with custom provider\n ModelProviderRegistry.clear_cache()\n with patch.dict(os.environ, {\"CUSTOM_API_URL\": \"http://localhost:11434\", \"CUSTOM_API_KEY\": \"\"}, clear=False):\n from providers.custom import CustomProvider\n\n ModelProviderRegistry.register_provider(ProviderType.CUSTOM, CustomProvider)\n\n provider = ModelProviderRegistry.get_provider(ProviderType.CUSTOM)\n if provider:\n model = ModelProviderRegistry.get_preferred_fallback_model(ToolModelCategory.EXTENDED_REASONING)\n # Should get a model from custom provider\n assert model is not None\n\n def test_extended_reasoning_final_fallback(self):\n \"\"\"Test EXTENDED_REASONING falls back to default when no providers.\"\"\"\n # Clear all providers\n ModelProviderRegistry.clear_cache()\n for provider_type in list(\n ModelProviderRegistry._instance._providers.keys() if ModelProviderRegistry._instance else []\n ):\n ModelProviderRegistry.unregister_provider(provider_type)\n\n model = ModelProviderRegistry.get_preferred_fallback_model(ToolModelCategory.EXTENDED_REASONING)\n # Should fall back to hardcoded default\n assert model == \"gemini-2.5-flash\"\n\n\nclass TestAutoModeErrorMessages:\n \"\"\"Test that auto mode error messages include suggested models.\"\"\"\n\n def teardown_method(self):\n \"\"\"Clean up after each test to prevent state pollution.\"\"\"\n # Clear provider registry singleton\n ModelProviderRegistry._instance = None\n\n @pytest.mark.asyncio\n async def test_chat_auto_error_message(self):\n \"\"\"Test Chat tool suggests appropriate model in auto mode.\"\"\"\n with patch(\"config.IS_AUTO_MODE\", True):\n with patch(\"config.DEFAULT_MODEL\", \"auto\"):\n with patch.object(ModelProviderRegistry, \"get_available_models\") as mock_get_available:\n # Mock OpenAI models available\n mock_get_available.return_value = {\n \"o3\": ProviderType.OPENAI,\n \"o3-mini\": ProviderType.OPENAI,\n \"o4-mini\": ProviderType.OPENAI,\n }\n\n # Mock the provider lookup to return None for auto model\n with patch.object(ModelProviderRegistry, \"get_provider_for_model\") as mock_get_provider_for:\n mock_get_provider_for.return_value = None\n\n tool = ChatTool()\n temp_dir = tempfile.mkdtemp()\n try:\n with pytest.raises(ToolExecutionError) as exc_info:\n await tool.execute(\n {\"prompt\": \"test\", \"model\": \"auto\", \"working_directory_absolute_path\": temp_dir}\n )\n finally:\n shutil.rmtree(temp_dir, ignore_errors=True)\n\n error_output = json.loads(exc_info.value.payload)\n assert error_output[\"status\"] == \"error\"\n assert \"Model 'auto' is not available\" in error_output[\"content\"]\n\n\n# Removed TestFileContentPreparation class\n# The original test was using MagicMock which caused TypeErrors when comparing with integers\n# The test has been removed to avoid mocking issues and encourage real integration testing\n\n\nclass TestProviderHelperMethods:\n \"\"\"Test the helper methods for finding models from custom/openrouter.\"\"\"\n\n def test_extended_reasoning_with_custom_provider(self):\n \"\"\"Test extended reasoning model selection with custom provider.\"\"\"\n # Setup with custom provider\n with patch.dict(os.environ, {\"CUSTOM_API_URL\": \"http://localhost:11434\", \"CUSTOM_API_KEY\": \"\"}, clear=False):\n from providers.custom import CustomProvider\n\n ModelProviderRegistry.register_provider(ProviderType.CUSTOM, CustomProvider)\n\n provider = ModelProviderRegistry.get_provider(ProviderType.CUSTOM)\n if provider:\n # Custom provider should return a model for extended reasoning\n model = ModelProviderRegistry.get_preferred_fallback_model(ToolModelCategory.EXTENDED_REASONING)\n assert model is not None\n\n def test_extended_reasoning_with_openrouter(self):\n \"\"\"Test extended reasoning model selection with OpenRouter.\"\"\"\n # Setup with OpenRouter provider\n with patch.dict(os.environ, {\"OPENROUTER_API_KEY\": \"test-key\"}, clear=False):\n from providers.openrouter import OpenRouterProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENROUTER, OpenRouterProvider)\n\n # OpenRouter should provide a model for extended reasoning\n model = ModelProviderRegistry.get_preferred_fallback_model(ToolModelCategory.EXTENDED_REASONING)\n # Should return first available OpenRouter model\n assert model is not None\n\n def test_fallback_when_no_providers_available(self):\n \"\"\"Test fallback when no providers are available.\"\"\"\n # Clear all providers\n ModelProviderRegistry.clear_cache()\n for provider_type in list(\n ModelProviderRegistry._instance._providers.keys() if ModelProviderRegistry._instance else []\n ):\n ModelProviderRegistry.unregister_provider(provider_type)\n\n # Should return hardcoded fallback\n model = ModelProviderRegistry.get_preferred_fallback_model(ToolModelCategory.EXTENDED_REASONING)\n assert model == \"gemini-2.5-flash\"\n\n\nclass TestEffectiveAutoMode:\n \"\"\"Test the is_effective_auto_mode method.\"\"\"\n\n def test_explicit_auto_mode(self):\n \"\"\"Test when DEFAULT_MODEL is explicitly 'auto'.\"\"\"\n with patch(\"config.DEFAULT_MODEL\", \"auto\"):\n with patch(\"config.IS_AUTO_MODE\", True):\n tool = ChatTool()\n assert tool.is_effective_auto_mode() is True\n\n def test_unavailable_model_triggers_auto_mode(self):\n \"\"\"Test when DEFAULT_MODEL is set but not available.\"\"\"\n with patch(\"config.DEFAULT_MODEL\", \"o3\"):\n with patch(\"config.IS_AUTO_MODE\", False):\n with patch.object(ModelProviderRegistry, \"get_provider_for_model\") as mock_get_provider:\n mock_get_provider.return_value = None # Model not available\n\n tool = ChatTool()\n assert tool.is_effective_auto_mode() is True\n\n def test_available_model_no_auto_mode(self):\n \"\"\"Test when DEFAULT_MODEL is set and available.\"\"\"\n with patch(\"config.DEFAULT_MODEL\", \"pro\"):\n with patch(\"config.IS_AUTO_MODE\", False):\n with patch.object(ModelProviderRegistry, \"get_provider_for_model\") as mock_get_provider:\n mock_get_provider.return_value = MagicMock() # Model is available\n\n tool = ChatTool()\n assert tool.is_effective_auto_mode() is False\n\n\nclass TestRuntimeModelSelection:\n \"\"\"Test runtime model selection behavior.\"\"\"\n\n def teardown_method(self):\n \"\"\"Clean up after each test to prevent state pollution.\"\"\"\n # Clear provider registry singleton\n ModelProviderRegistry._instance = None\n\n @pytest.mark.asyncio\n async def test_explicit_auto_in_request(self):\n \"\"\"Test when Claude explicitly passes model='auto'.\"\"\"\n with patch(\"config.DEFAULT_MODEL\", \"pro\"): # DEFAULT_MODEL is a real model\n with patch(\"config.IS_AUTO_MODE\", False): # Not in auto mode\n tool = ThinkDeepTool()\n result = await tool.execute(\n {\n \"step\": \"test\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"test\",\n \"model\": \"auto\",\n }\n )\n\n assert len(result) == 1\n assert \"Model 'auto' is not available\" in result[0].text\n\n @pytest.mark.asyncio\n async def test_unavailable_model_in_request(self):\n \"\"\"Test when Claude passes an unavailable model.\"\"\"\n with patch(\"config.DEFAULT_MODEL\", \"pro\"):\n with patch(\"config.IS_AUTO_MODE\", False):\n with patch.object(ModelProviderRegistry, \"get_provider_for_model\") as mock_get_provider:\n # Model is not available\n mock_get_provider.return_value = None\n\n tool = ChatTool()\n temp_dir = tempfile.mkdtemp()\n try:\n with pytest.raises(ToolExecutionError) as exc_info:\n await tool.execute(\n {\"prompt\": \"test\", \"model\": \"gpt-5-turbo\", \"working_directory_absolute_path\": temp_dir}\n )\n finally:\n shutil.rmtree(temp_dir, ignore_errors=True)\n\n # Should require model selection\n error_output = json.loads(exc_info.value.payload)\n assert error_output[\"status\"] == \"error\"\n assert \"gpt-5-turbo\" in error_output[\"content\"]\n assert \"is not available\" in error_output[\"content\"]\n\n\nclass TestSchemaGeneration:\n \"\"\"Test schema generation with different configurations.\"\"\"\n\n def test_schema_with_explicit_auto_mode(self):\n \"\"\"Test schema when DEFAULT_MODEL='auto'.\"\"\"\n with patch(\"config.DEFAULT_MODEL\", \"auto\"):\n with patch(\"config.IS_AUTO_MODE\", True):\n tool = ChatTool()\n schema = tool.get_input_schema()\n\n # Model should be required\n assert \"model\" in schema[\"required\"]\n\n def test_schema_with_unavailable_default_model(self):\n \"\"\"Test schema when DEFAULT_MODEL is set but unavailable.\"\"\"\n with patch(\"config.DEFAULT_MODEL\", \"o3\"):\n with patch(\"config.IS_AUTO_MODE\", False):\n with patch.object(ModelProviderRegistry, \"get_provider_for_model\") as mock_get_provider:\n mock_get_provider.return_value = None # Model not available\n\n tool = AnalyzeTool()\n schema = tool.get_input_schema()\n\n # Model should be required due to unavailable DEFAULT_MODEL\n assert \"model\" in schema[\"required\"]\n\n def test_schema_with_available_default_model(self):\n \"\"\"Test schema when DEFAULT_MODEL is available.\"\"\"\n with patch(\"config.DEFAULT_MODEL\", \"pro\"):\n with patch(\"config.IS_AUTO_MODE\", False):\n with patch.object(ModelProviderRegistry, \"get_provider_for_model\") as mock_get_provider:\n mock_get_provider.return_value = MagicMock() # Model is available\n\n tool = ThinkDeepTool()\n schema = tool.get_input_schema()\n\n # Model should remain optional when DEFAULT_MODEL is available\n assert \"model\" not in schema[\"required\"]\n\n\nclass TestUnavailableModelFallback:\n \"\"\"Test fallback behavior when DEFAULT_MODEL is not available.\"\"\"\n\n @pytest.mark.asyncio\n async def test_unavailable_default_model_fallback(self):\n \"\"\"Test that unavailable DEFAULT_MODEL triggers auto mode behavior.\"\"\"\n with patch(\"config.DEFAULT_MODEL\", \"o3\"): # Set DEFAULT_MODEL to a specific model\n with patch(\"config.IS_AUTO_MODE\", False): # Not in auto mode\n with patch.object(ModelProviderRegistry, \"get_provider_for_model\") as mock_get_provider:\n # Model is not available (no provider)\n mock_get_provider.return_value = None\n\n tool = ThinkDeepTool()\n result = await tool.execute(\n {\n \"step\": \"test\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"test\",\n }\n ) # No model specified\n\n # Should get model error since fallback model is also unavailable\n assert len(result) == 1\n # Workflow tools try fallbacks and report when the fallback model is not available\n assert \"is not available\" in result[0].text\n # Should list available models in the error\n assert \"Available models:\" in result[0].text\n\n @pytest.mark.asyncio\n async def test_available_default_model_no_fallback(self):\n \"\"\"Test that available DEFAULT_MODEL works normally.\"\"\"\n with patch(\"config.DEFAULT_MODEL\", \"pro\"):\n with patch(\"config.IS_AUTO_MODE\", False):\n with patch.object(ModelProviderRegistry, \"get_provider_for_model\") as mock_get_provider:\n # Model is available\n mock_provider = MagicMock()\n mock_provider.generate_content.return_value = MagicMock(content=\"Test response\", metadata={})\n mock_get_provider.return_value = mock_provider\n\n # Mock the provider lookup in BaseTool.get_model_provider\n with patch.object(BaseTool, \"get_model_provider\") as mock_get_model_provider:\n mock_get_model_provider.return_value = mock_provider\n\n tool = ChatTool()\n temp_dir = tempfile.mkdtemp()\n try:\n result = await tool.execute({\"prompt\": \"test\", \"working_directory_absolute_path\": temp_dir})\n finally:\n shutil.rmtree(temp_dir, ignore_errors=True)\n\n # Should work normally, not require model parameter\n assert len(result) == 1\n output = json.loads(result[0].text)\n assert output[\"status\"] in [\"success\", \"continuation_available\"]\n assert \"Test response\" in output[\"content\"]\n" }, { "path": "tests/test_pii_sanitizer.py", "content": "#!/usr/bin/env python3\n\"\"\"Test cases for PII sanitizer.\"\"\"\n\nimport unittest\n\nfrom .pii_sanitizer import PIIPattern, PIISanitizer\n\n\nclass TestPIISanitizer(unittest.TestCase):\n \"\"\"Test PII sanitization functionality.\"\"\"\n\n def setUp(self):\n \"\"\"Set up test sanitizer.\"\"\"\n self.sanitizer = PIISanitizer()\n\n def test_api_key_sanitization(self):\n \"\"\"Test various API key formats are sanitized.\"\"\"\n test_cases = [\n # OpenAI keys\n (\"sk-proj-abcd1234567890ABCD1234567890abcd1234567890ABCD12\", \"sk-proj-SANITIZED\"),\n (\"sk-1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN\", \"sk-SANITIZED\"),\n # Anthropic keys\n (\"sk-ant-abcd1234567890ABCD1234567890abcd1234567890ABCD12\", \"sk-ant-SANITIZED\"),\n # Google keys\n (\"AIzaSyD-1234567890abcdefghijklmnopqrstuv\", \"AIza-SANITIZED\"),\n # GitHub tokens\n (\"ghp_1234567890abcdefghijklmnopqrstuvwxyz\", \"gh_SANITIZED\"),\n (\"ghs_1234567890abcdefghijklmnopqrstuvwxyz\", \"gh_SANITIZED\"),\n ]\n\n for original, expected in test_cases:\n with self.subTest(original=original):\n result = self.sanitizer.sanitize_string(original)\n self.assertEqual(result, expected)\n\n def test_personal_info_sanitization(self):\n \"\"\"Test personal information is sanitized.\"\"\"\n test_cases = [\n # Email addresses\n (\"john.doe@example.com\", \"user@example.com\"),\n (\"test123@company.org\", \"user@example.com\"),\n # Phone numbers (all now use the same pattern)\n (\"(555) 123-4567\", \"(XXX) XXX-XXXX\"),\n (\"555-123-4567\", \"(XXX) XXX-XXXX\"),\n (\"+1-555-123-4567\", \"(XXX) XXX-XXXX\"),\n # SSN\n (\"123-45-6789\", \"XXX-XX-XXXX\"),\n # Credit card\n (\"1234 5678 9012 3456\", \"XXXX-XXXX-XXXX-XXXX\"),\n (\"1234-5678-9012-3456\", \"XXXX-XXXX-XXXX-XXXX\"),\n ]\n\n for original, expected in test_cases:\n with self.subTest(original=original):\n result = self.sanitizer.sanitize_string(original)\n self.assertEqual(result, expected)\n\n def test_header_sanitization(self):\n \"\"\"Test HTTP header sanitization.\"\"\"\n headers = {\n \"Authorization\": \"Bearer sk-proj-abcd1234567890ABCD1234567890abcd1234567890ABCD12\",\n \"API-Key\": \"sk-1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"MyApp/1.0\",\n \"Cookie\": \"session=abc123; user=john.doe@example.com\",\n }\n\n sanitized = self.sanitizer.sanitize_headers(headers)\n\n self.assertEqual(sanitized[\"Authorization\"], \"Bearer SANITIZED\")\n self.assertEqual(sanitized[\"API-Key\"], \"sk-SANITIZED\")\n self.assertEqual(sanitized[\"Content-Type\"], \"application/json\")\n self.assertEqual(sanitized[\"User-Agent\"], \"MyApp/1.0\")\n self.assertIn(\"user@example.com\", sanitized[\"Cookie\"])\n\n def test_nested_structure_sanitization(self):\n \"\"\"Test sanitization of nested data structures.\"\"\"\n data = {\n \"user\": {\n \"email\": \"john.doe@example.com\",\n \"api_key\": \"sk-proj-abcd1234567890ABCD1234567890abcd1234567890ABCD12\",\n },\n \"tokens\": [\n \"ghp_1234567890abcdefghijklmnopqrstuvwxyz\",\n \"Bearer sk-ant-abcd1234567890ABCD1234567890abcd1234567890ABCD12\",\n ],\n \"metadata\": {\"ip\": \"192.168.1.100\", \"phone\": \"(555) 123-4567\"},\n }\n\n sanitized = self.sanitizer.sanitize_value(data)\n\n self.assertEqual(sanitized[\"user\"][\"email\"], \"user@example.com\")\n self.assertEqual(sanitized[\"user\"][\"api_key\"], \"sk-proj-SANITIZED\")\n self.assertEqual(sanitized[\"tokens\"][0], \"gh_SANITIZED\")\n self.assertEqual(sanitized[\"tokens\"][1], \"Bearer sk-ant-SANITIZED\")\n self.assertEqual(sanitized[\"metadata\"][\"ip\"], \"0.0.0.0\")\n self.assertEqual(sanitized[\"metadata\"][\"phone\"], \"(XXX) XXX-XXXX\")\n\n def test_url_sanitization(self):\n \"\"\"Test URL parameter sanitization.\"\"\"\n urls = [\n (\n \"https://api.example.com/v1/users?api_key=sk-1234567890abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMN\",\n \"https://api.example.com/v1/users?api_key=SANITIZED\",\n ),\n (\n \"https://example.com/login?token=ghp_1234567890abcdefghijklmnopqrstuvwxyz&user=test\",\n \"https://example.com/login?token=SANITIZED&user=test\",\n ),\n ]\n\n for original, expected in urls:\n with self.subTest(url=original):\n result = self.sanitizer.sanitize_url(original)\n self.assertEqual(result, expected)\n\n def test_disable_sanitization(self):\n \"\"\"Test that sanitization can be disabled.\"\"\"\n self.sanitizer.sanitize_enabled = False\n\n sensitive_data = \"sk-proj-abcd1234567890ABCD1234567890abcd1234567890ABCD12\"\n result = self.sanitizer.sanitize_string(sensitive_data)\n\n # Should return original when disabled\n self.assertEqual(result, sensitive_data)\n\n def test_custom_pattern(self):\n \"\"\"Test adding custom PII patterns.\"\"\"\n # Add custom pattern for internal employee IDs\n custom_pattern = PIIPattern.create(\n name=\"employee_id\", pattern=r\"EMP\\d{6}\", replacement=\"EMP-REDACTED\", description=\"Internal employee IDs\"\n )\n\n self.sanitizer.add_pattern(custom_pattern)\n\n text = \"Employee EMP123456 has access to the system\"\n result = self.sanitizer.sanitize_string(text)\n\n self.assertEqual(result, \"Employee EMP-REDACTED has access to the system\")\n\n\nif __name__ == \"__main__\":\n unittest.main()\n" }, { "path": "tests/test_pip_detection_fix.py", "content": "\"\"\"Tests for pip detection fix in run-server.sh script.\n\nThis test file ensures our pip detection improvements work correctly\nand don't break existing functionality.\n\"\"\"\n\nimport os\nimport subprocess\nimport tempfile\nfrom pathlib import Path\n\nimport pytest\n\n\nclass TestPipDetectionFix:\n \"\"\"Test cases for issue #188: PIP is available but not recognized.\"\"\"\n\n def test_run_server_script_syntax_valid(self):\n \"\"\"Test that run-server.sh has valid bash syntax.\"\"\"\n result = subprocess.run([\"bash\", \"-n\", \"./run-server.sh\"], capture_output=True, text=True)\n assert result.returncode == 0, f\"Syntax error in run-server.sh: {result.stderr}\"\n\n def test_run_server_has_proper_shebang(self):\n \"\"\"Test that run-server.sh starts with proper shebang.\"\"\"\n content = Path(\"./run-server.sh\").read_text()\n assert content.startswith(\"#!/bin/bash\"), \"Script missing proper bash shebang\"\n\n def test_critical_functions_exist(self):\n \"\"\"Test that all critical functions are defined in the script.\"\"\"\n content = Path(\"./run-server.sh\").read_text()\n critical_functions = [\"find_python\", \"setup_environment\", \"setup_venv\", \"install_dependencies\", \"bootstrap_pip\"]\n\n for func in critical_functions:\n assert f\"{func}()\" in content, f\"Critical function {func}() not found in script\"\n\n def test_pip_detection_consistency_issue(self):\n \"\"\"Test the specific issue: pip works in setup_venv but fails in install_dependencies.\n\n This test verifies that our fix ensures consistent Python executable paths.\n \"\"\"\n # Test that the get_venv_python_path function now returns absolute paths\n content = Path(\"./run-server.sh\").read_text()\n\n # Check that get_venv_python_path includes our absolute path conversion logic\n assert \"abs_venv_path\" in content, \"get_venv_python_path should use absolute paths\"\n assert 'cd \"$(dirname' in content, \"Should convert to absolute path\"\n\n # Test successful completion - our fix should make the script more robust\n result = subprocess.run([\"bash\", \"-n\", \"./run-server.sh\"], capture_output=True, text=True)\n assert result.returncode == 0, \"Script should have valid syntax after our fix\"\n\n def test_pip_detection_with_non_interactive_shell(self):\n \"\"\"Test pip detection works in non-interactive shell environments.\n\n This addresses the contributor's suggestion about non-interactive shells\n not sourcing ~/.bashrc where pip PATH might be defined.\n \"\"\"\n # Test case for Git Bash on Windows and non-interactive Linux shells\n with tempfile.TemporaryDirectory() as temp_dir:\n # Create mock virtual environment structure\n venv_path = Path(temp_dir) / \".pal_venv\"\n bin_path = venv_path / \"bin\"\n bin_path.mkdir(parents=True)\n\n # Create mock python executable\n python_exe = bin_path / \"python\"\n python_exe.write_text(\"#!/bin/bash\\necho 'Python 3.12.3'\\n\")\n python_exe.chmod(0o755)\n\n # Create mock pip executable\n pip_exe = bin_path / \"pip\"\n pip_exe.write_text(\"#!/bin/bash\\necho 'pip 23.0.1'\\n\")\n pip_exe.chmod(0o755)\n\n # Test that we can detect pip using explicit paths (not PATH)\n assert python_exe.exists(), \"Mock python executable should exist\"\n assert pip_exe.exists(), \"Mock pip executable should exist\"\n assert python_exe.is_file(), \"Python should be a file\"\n assert pip_exe.is_file(), \"Pip should be a file\"\n\n def test_enhanced_diagnostic_messages_included(self):\n \"\"\"Test that our enhanced diagnostic messages are included in the script.\n\n Verify that the script contains the enhanced error diagnostics we added.\n \"\"\"\n content = Path(\"./run-server.sh\").read_text()\n\n # Check that enhanced diagnostic information is present in the script\n expected_diagnostic_patterns = [\n \"Enhanced diagnostic information for debugging\",\n \"Diagnostic information:\",\n \"Python executable:\",\n \"Python executable exists:\",\n \"Python executable permissions:\",\n \"Virtual environment path:\",\n \"Virtual environment exists:\",\n \"Final diagnostic information:\",\n ]\n\n for pattern in expected_diagnostic_patterns:\n assert pattern in content, f\"Enhanced diagnostic pattern '{pattern}' should be in script\"\n\n def test_setup_env_file_does_not_create_bsd_backup(self, tmp_path):\n \"\"\"Ensure setup_env_file avoids creating .env'' artifacts (BSD sed behavior).\"\"\"\n script_path = Path(\"./run-server.sh\").resolve()\n\n # Prepare temp workspace with example env\n env_example = Path(\".env.example\").read_text()\n target_example = tmp_path / \".env.example\"\n target_example.write_text(env_example)\n\n # Run setup_env_file inside isolated shell session\n command = f\"\"\"\n set -e\n cd \"{tmp_path}\"\n source \"{script_path}\"\n setup_env_file\n \"\"\"\n env = os.environ.copy()\n subprocess.run([\"bash\", \"-lc\", command], check=True, env=env, text=True)\n\n artifacts = {p.name for p in tmp_path.glob(\".env*\")}\n assert \".env''\" not in artifacts, \"setup_env_file should not create BSD sed backup artifacts\"\n assert \".env\" in artifacts, \".env should be created from .env.example\"\n\n\nif __name__ == \"__main__\":\n pytest.main([__file__, \"-v\"])\n" }, { "path": "tests/test_planner.py", "content": "\"\"\"\nTests for the planner tool.\n\"\"\"\n\nfrom unittest.mock import patch\n\nimport pytest\n\nfrom tools.models import ToolModelCategory\nfrom tools.planner import PlannerRequest, PlannerTool\nfrom tools.shared.exceptions import ToolExecutionError\n\n\nclass TestPlannerTool:\n \"\"\"Test suite for PlannerTool.\"\"\"\n\n def test_tool_metadata(self):\n \"\"\"Test basic tool metadata and configuration.\"\"\"\n tool = PlannerTool()\n\n assert tool.get_name() == \"planner\"\n assert \"sequential planning\" in tool.get_description()\n assert tool.get_default_temperature() == 1.0 # TEMPERATURE_BALANCED\n assert tool.get_model_category() == ToolModelCategory.EXTENDED_REASONING\n assert tool.get_default_thinking_mode() == \"medium\"\n\n def test_request_validation(self):\n \"\"\"Test Pydantic request model validation.\"\"\"\n # Valid interactive step request\n step_request = PlannerRequest(\n step=\"Create database migration scripts\", step_number=3, total_steps=10, next_step_required=True\n )\n assert step_request.step == \"Create database migration scripts\"\n assert step_request.step_number == 3\n assert step_request.next_step_required is True\n assert step_request.is_step_revision is False # default\n\n # Missing required fields should fail\n with pytest.raises(ValueError):\n PlannerRequest() # Missing all required fields\n\n with pytest.raises(ValueError):\n PlannerRequest(step=\"test\") # Missing other required fields\n\n def test_input_schema_generation(self):\n \"\"\"Test JSON schema generation for MCP client.\"\"\"\n tool = PlannerTool()\n schema = tool.get_input_schema()\n\n assert schema[\"type\"] == \"object\"\n # Interactive planning fields\n assert \"step\" in schema[\"properties\"]\n assert \"step_number\" in schema[\"properties\"]\n assert \"total_steps\" in schema[\"properties\"]\n assert \"next_step_required\" in schema[\"properties\"]\n assert \"is_step_revision\" in schema[\"properties\"]\n assert \"is_branch_point\" in schema[\"properties\"]\n assert \"branch_id\" in schema[\"properties\"]\n assert \"continuation_id\" in schema[\"properties\"]\n\n # Check that workflow-based planner includes model field and excludes some fields\n assert \"model\" in schema[\"properties\"] # Workflow tools include model field\n assert \"images\" not in schema[\"properties\"] # Excluded for planning\n assert \"absolute_file_paths\" not in schema[\"properties\"] # Excluded for planning\n assert \"temperature\" not in schema[\"properties\"]\n assert \"thinking_mode\" not in schema[\"properties\"]\n\n # Check required fields\n assert \"step\" in schema[\"required\"]\n assert \"step_number\" in schema[\"required\"]\n assert \"total_steps\" in schema[\"required\"]\n assert \"next_step_required\" in schema[\"required\"]\n\n def test_model_category_for_planning(self):\n \"\"\"Test that planner uses extended reasoning category.\"\"\"\n tool = PlannerTool()\n category = tool.get_model_category()\n\n # Planning needs deep thinking\n assert category == ToolModelCategory.EXTENDED_REASONING\n\n @pytest.mark.asyncio\n async def test_execute_first_step(self):\n \"\"\"Test execute method for first planning step.\"\"\"\n tool = PlannerTool()\n arguments = {\n \"step\": \"Plan a microservices migration for our monolithic e-commerce platform\",\n \"step_number\": 1,\n \"total_steps\": 10,\n \"next_step_required\": True,\n }\n\n # Mock conversation memory functions and UUID generation\n with patch(\"utils.conversation_memory.uuid.uuid4\") as mock_uuid:\n mock_uuid.return_value.hex = \"test-uuid-123\"\n mock_uuid.return_value.__str__ = lambda x: \"test-uuid-123\"\n with patch(\"utils.conversation_memory.add_turn\"):\n result = await tool.execute(arguments)\n\n # Should return a list with TextContent\n assert len(result) == 1\n assert result[0].type == \"text\"\n\n # Parse the JSON response\n import json\n\n parsed_response = json.loads(result[0].text)\n\n assert parsed_response[\"step_number\"] == 1\n assert parsed_response[\"total_steps\"] == 10\n assert parsed_response[\"next_step_required\"] is True\n assert parsed_response[\"continuation_id\"] == \"test-uuid-123\"\n # For complex plans (>=5 steps) on first step, expect deep thinking pause\n assert parsed_response[\"status\"] == \"pause_for_deep_thinking\"\n assert parsed_response[\"thinking_required\"] is True\n assert \"required_thinking\" in parsed_response\n assert \"MANDATORY: DO NOT call the planner tool again immediately\" in parsed_response[\"next_steps\"]\n\n @pytest.mark.asyncio\n async def test_execute_subsequent_step(self):\n \"\"\"Test execute method for subsequent planning step.\"\"\"\n tool = PlannerTool()\n arguments = {\n \"step\": \"Set up deployment configuration for each microservice\",\n \"step_number\": 2,\n \"total_steps\": 8,\n \"next_step_required\": True,\n \"continuation_id\": \"existing-uuid-456\",\n }\n\n # Mock conversation memory functions\n with patch(\"utils.conversation_memory.add_turn\"):\n result = await tool.execute(arguments)\n\n # Should return a list with TextContent\n assert len(result) == 1\n assert result[0].type == \"text\"\n\n # Parse the JSON response\n import json\n\n parsed_response = json.loads(result[0].text)\n\n assert parsed_response[\"step_number\"] == 2\n assert parsed_response[\"total_steps\"] == 8\n assert parsed_response[\"next_step_required\"] is True\n assert parsed_response[\"continuation_id\"] == \"existing-uuid-456\"\n # For complex plans (>=5 steps) on step 2, expect deep thinking pause\n assert parsed_response[\"status\"] == \"pause_for_deep_thinking\"\n assert parsed_response[\"thinking_required\"] is True\n assert \"required_thinking\" in parsed_response\n assert \"STOP! Complex planning requires reflection between steps\" in parsed_response[\"next_steps\"]\n\n @pytest.mark.asyncio\n async def test_execute_with_continuation_context(self):\n \"\"\"Test execute method with continuation that loads previous context.\"\"\"\n tool = PlannerTool()\n arguments = {\n \"step\": \"Continue planning the deployment phase\",\n \"step_number\": 1, # Step 1 with continuation_id loads context\n \"total_steps\": 8,\n \"next_step_required\": True,\n \"continuation_id\": \"test-continuation-id\",\n }\n\n # Mock thread with completed plan\n from utils.conversation_memory import ConversationTurn, ThreadContext\n\n mock_turn = ConversationTurn(\n role=\"assistant\",\n content='{\"status\": \"planning_success\", \"planning_complete\": true, \"plan_summary\": \"COMPLETE PLAN: Authentication system with 3 steps completed\"}',\n tool_name=\"planner\",\n model_name=\"claude-planner\",\n timestamp=\"2024-01-01T00:00:00Z\",\n )\n mock_thread = ThreadContext(\n thread_id=\"test-id\",\n tool_name=\"planner\",\n turns=[mock_turn],\n created_at=\"2024-01-01T00:00:00Z\",\n last_updated_at=\"2024-01-01T00:00:00Z\",\n initial_context={},\n )\n\n with patch(\"utils.conversation_memory.get_thread\", return_value=mock_thread):\n with patch(\"utils.conversation_memory.add_turn\"):\n result = await tool.execute(arguments)\n\n # Should return a list with TextContent\n assert len(result) == 1\n response_text = result[0].text\n\n # Should include previous plan context in JSON\n import json\n\n parsed_response = json.loads(response_text)\n\n # Check that the continuation works (workflow architecture handles context differently)\n assert parsed_response[\"step_number\"] == 1\n assert parsed_response[\"continuation_id\"] == \"test-continuation-id\"\n assert parsed_response[\"next_step_required\"] is True\n\n @pytest.mark.asyncio\n async def test_execute_final_step(self):\n \"\"\"Test execute method for final planning step.\"\"\"\n tool = PlannerTool()\n arguments = {\n \"step\": \"Deploy and monitor the new system\",\n \"step_number\": 10,\n \"total_steps\": 10,\n \"next_step_required\": False, # Final step\n \"continuation_id\": \"test-uuid-789\",\n }\n\n # Mock conversation memory functions\n with patch(\"utils.conversation_memory.add_turn\"):\n result = await tool.execute(arguments)\n\n # Should return a list with TextContent\n assert len(result) == 1\n response_text = result[0].text\n\n # Parse the structured JSON response\n import json\n\n parsed_response = json.loads(response_text)\n\n # Check final step structure\n assert parsed_response[\"status\"] == \"planning_complete\"\n assert parsed_response[\"step_number\"] == 10\n assert parsed_response[\"planning_complete\"] is True\n assert \"plan_summary\" in parsed_response\n assert \"COMPLETE PLAN:\" in parsed_response[\"plan_summary\"]\n\n @pytest.mark.asyncio\n async def test_execute_with_branching(self):\n \"\"\"Test execute method with branching.\"\"\"\n tool = PlannerTool()\n arguments = {\n \"step\": \"Use Kubernetes for orchestration\",\n \"step_number\": 4,\n \"total_steps\": 10,\n \"next_step_required\": True,\n \"is_branch_point\": True,\n \"branch_from_step\": 3,\n \"branch_id\": \"cloud-native-path\",\n \"continuation_id\": \"test-uuid-branch\",\n }\n\n # Mock conversation memory functions\n with patch(\"utils.conversation_memory.add_turn\"):\n result = await tool.execute(arguments)\n\n # Should return a list with TextContent\n assert len(result) == 1\n response_text = result[0].text\n\n # Parse the JSON response\n import json\n\n parsed_response = json.loads(response_text)\n\n assert parsed_response[\"metadata\"][\"branches\"] == [\"cloud-native-path\"]\n assert \"cloud-native-path\" in str(tool.branches)\n\n @pytest.mark.asyncio\n async def test_execute_with_revision(self):\n \"\"\"Test execute method with step revision.\"\"\"\n tool = PlannerTool()\n arguments = {\n \"step\": \"Revise API design to use GraphQL instead of REST\",\n \"step_number\": 3,\n \"total_steps\": 8,\n \"next_step_required\": True,\n \"is_step_revision\": True,\n \"revises_step_number\": 2,\n \"continuation_id\": \"test-uuid-revision\",\n }\n\n # Mock conversation memory functions\n with patch(\"utils.conversation_memory.add_turn\"):\n result = await tool.execute(arguments)\n\n # Should return a list with TextContent\n assert len(result) == 1\n response_text = result[0].text\n\n # Parse the JSON response\n import json\n\n parsed_response = json.loads(response_text)\n\n assert parsed_response[\"step_number\"] == 3\n assert parsed_response[\"next_step_required\"] is True\n assert parsed_response[\"metadata\"][\"is_step_revision\"] is True\n assert parsed_response[\"metadata\"][\"revises_step_number\"] == 2\n\n # Check that step data was stored in history\n assert len(tool.work_history) > 0\n latest_step = tool.work_history[-1]\n assert latest_step[\"is_step_revision\"] is True\n assert latest_step[\"revises_step_number\"] == 2\n\n @pytest.mark.asyncio\n async def test_execute_adjusts_total_steps(self):\n \"\"\"Test execute method adjusts total steps when current step exceeds estimate.\"\"\"\n tool = PlannerTool()\n arguments = {\n \"step\": \"Additional step discovered during planning\",\n \"step_number\": 8,\n \"total_steps\": 5, # Current step exceeds total\n \"next_step_required\": True,\n \"continuation_id\": \"test-uuid-adjust\",\n }\n\n # Mock conversation memory functions\n with patch(\"utils.conversation_memory.add_turn\"):\n result = await tool.execute(arguments)\n\n # Should return a list with TextContent\n assert len(result) == 1\n response_text = result[0].text\n\n # Parse the JSON response\n import json\n\n parsed_response = json.loads(response_text)\n\n # Total steps should be adjusted to match current step\n assert parsed_response[\"total_steps\"] == 8\n assert parsed_response[\"step_number\"] == 8\n assert parsed_response[\"status\"] == \"pause_for_planning\"\n\n @pytest.mark.asyncio\n async def test_execute_error_handling(self):\n \"\"\"Test execute method error handling.\"\"\"\n tool = PlannerTool()\n # Invalid arguments - missing required fields\n arguments = {\n \"step\": \"Invalid request\"\n # Missing required fields: step_number, total_steps, next_step_required\n }\n\n with pytest.raises(ToolExecutionError) as exc_info:\n await tool.execute(arguments)\n\n import json\n\n parsed_response = json.loads(exc_info.value.payload)\n\n assert parsed_response[\"status\"] == \"planner_failed\"\n assert \"error\" in parsed_response\n\n @pytest.mark.asyncio\n async def test_execute_step_history_tracking(self):\n \"\"\"Test that execute method properly tracks step history.\"\"\"\n tool = PlannerTool()\n\n # Execute multiple steps\n step1_args = {\"step\": \"First step\", \"step_number\": 1, \"total_steps\": 3, \"next_step_required\": True}\n\n step2_args = {\n \"step\": \"Second step\",\n \"step_number\": 2,\n \"total_steps\": 3,\n \"next_step_required\": True,\n \"continuation_id\": \"test-uuid-history\",\n }\n\n # Mock conversation memory functions\n with patch(\"utils.conversation_memory.create_thread\", return_value=\"test-uuid-history\"):\n with patch(\"utils.conversation_memory.add_turn\"):\n await tool.execute(step1_args)\n await tool.execute(step2_args)\n\n # Should have tracked both steps\n assert len(tool.work_history) == 2\n assert tool.work_history[0][\"step\"] == \"First step\"\n assert tool.work_history[1][\"step\"] == \"Second step\"\n\n\n# Integration test\nclass TestPlannerToolIntegration:\n \"\"\"Integration tests for planner tool.\"\"\"\n\n def setup_method(self):\n \"\"\"Set up model context for integration tests.\"\"\"\n from utils.model_context import ModelContext\n\n self.tool = PlannerTool()\n self.tool._model_context = ModelContext(\"flash\") # Test model\n\n @pytest.mark.asyncio\n async def test_interactive_planning_flow(self):\n \"\"\"Test complete interactive planning flow.\"\"\"\n arguments = {\n \"step\": \"Plan a complete system redesign\",\n \"step_number\": 1,\n \"total_steps\": 5,\n \"next_step_required\": True,\n }\n\n # Mock conversation memory functions and UUID generation\n with patch(\"utils.conversation_memory.uuid.uuid4\") as mock_uuid:\n mock_uuid.return_value.hex = \"test-flow-uuid\"\n mock_uuid.return_value.__str__ = lambda x: \"test-flow-uuid\"\n with patch(\"utils.conversation_memory.add_turn\"):\n result = await self.tool.execute(arguments)\n\n # Verify response structure\n assert len(result) == 1\n response_text = result[0].text\n\n # Parse the JSON response\n import json\n\n parsed_response = json.loads(response_text)\n\n assert parsed_response[\"step_number\"] == 1\n assert parsed_response[\"total_steps\"] == 5\n assert parsed_response[\"continuation_id\"] == \"test-flow-uuid\"\n # For complex plans (>=5 steps) on first step, expect deep thinking pause\n assert parsed_response[\"status\"] == \"pause_for_deep_thinking\"\n assert parsed_response[\"thinking_required\"] is True\n\n @pytest.mark.asyncio\n async def test_simple_planning_flow(self):\n \"\"\"Test simple planning flow without deep thinking pauses.\"\"\"\n arguments = {\n \"step\": \"Plan a simple feature update\",\n \"step_number\": 1,\n \"total_steps\": 3, # Simple plan < 5 steps\n \"next_step_required\": True,\n }\n\n # Mock conversation memory functions and UUID generation\n with patch(\"utils.conversation_memory.uuid.uuid4\") as mock_uuid:\n mock_uuid.return_value.hex = \"test-simple-uuid\"\n mock_uuid.return_value.__str__ = lambda x: \"test-simple-uuid\"\n with patch(\"utils.conversation_memory.add_turn\"):\n result = await self.tool.execute(arguments)\n\n # Verify response structure\n assert len(result) == 1\n response_text = result[0].text\n\n # Parse the JSON response\n import json\n\n parsed_response = json.loads(response_text)\n\n assert parsed_response[\"step_number\"] == 1\n assert parsed_response[\"total_steps\"] == 3\n assert parsed_response[\"continuation_id\"] == \"test-simple-uuid\"\n # For simple plans (< 5 steps), expect normal flow without deep thinking pause\n assert parsed_response[\"status\"] == \"pause_for_planning\"\n assert \"thinking_required\" not in parsed_response\n assert \"Continue with step 2\" in parsed_response[\"next_steps\"]\n" }, { "path": "tests/test_precommit_workflow.py", "content": "\"\"\"\nUnit tests for the workflow-based PrecommitTool\n\nTests the core functionality of the precommit workflow tool including:\n- Tool metadata and configuration\n- Request model validation\n- Workflow step handling\n- Tool categorization\n\"\"\"\n\nimport pytest\n\nfrom tools.models import ToolModelCategory\nfrom tools.precommit import PrecommitRequest, PrecommitTool\n\n\nclass TestPrecommitWorkflowTool:\n \"\"\"Test suite for the workflow-based PrecommitTool\"\"\"\n\n def test_tool_metadata(self):\n \"\"\"Test basic tool metadata\"\"\"\n tool = PrecommitTool()\n\n assert tool.get_name() == \"precommit\"\n assert \"git changes\" in tool.get_description()\n assert \"systematic analysis\" in tool.get_description()\n\n def test_tool_model_category(self):\n \"\"\"Test that precommit tool uses extended reasoning category\"\"\"\n tool = PrecommitTool()\n assert tool.get_model_category() == ToolModelCategory.EXTENDED_REASONING\n\n def test_default_temperature(self):\n \"\"\"Test analytical temperature setting\"\"\"\n tool = PrecommitTool()\n temp = tool.get_default_temperature()\n # Should be analytical temperature (now 1.0)\n assert temp == 1.0\n\n def test_request_model_basic_validation(self):\n \"\"\"Test basic request model validation\"\"\"\n # Valid minimal workflow request\n request = PrecommitRequest(\n step=\"Initial validation step\",\n step_number=1,\n total_steps=3,\n next_step_required=True,\n findings=\"Initial findings\",\n path=\"/test/repo\", # Required for step 1\n )\n\n assert request.step == \"Initial validation step\"\n assert request.step_number == 1\n assert request.total_steps == 3\n assert request.next_step_required is True\n assert request.findings == \"Initial findings\"\n assert request.path == \"/test/repo\"\n\n def test_request_model_step_one_validation(self):\n \"\"\"Test that step 1 requires path field\"\"\"\n # Step 1 without path should fail\n with pytest.raises(ValueError, match=\"Step 1 requires 'path' field\"):\n PrecommitRequest(\n step=\"Initial validation step\",\n step_number=1,\n total_steps=3,\n next_step_required=True,\n findings=\"Initial findings\",\n # Missing path for step 1\n )\n\n def test_request_model_later_steps_no_path_required(self):\n \"\"\"Test that later steps don't require path\"\"\"\n # Step 2+ without path should be fine\n request = PrecommitRequest(\n step=\"Continued validation\",\n step_number=2,\n total_steps=3,\n next_step_required=True,\n findings=\"Detailed findings\",\n # No path needed for step 2+\n )\n\n assert request.step_number == 2\n assert request.path is None\n\n def test_request_model_optional_fields(self):\n \"\"\"Test optional workflow fields\"\"\"\n request = PrecommitRequest(\n step=\"Validation with optional fields\",\n step_number=1,\n total_steps=2,\n next_step_required=False,\n findings=\"Comprehensive findings\",\n path=\"/test/repo\",\n precommit_type=\"external\",\n files_checked=[\"/file1.py\", \"/file2.py\"],\n relevant_files=[\"/file1.py\"],\n relevant_context=[\"function_name\", \"class_name\"],\n issues_found=[{\"severity\": \"medium\", \"description\": \"Test issue\"}],\n images=[\"/screenshot.png\"],\n )\n\n assert request.precommit_type == \"external\"\n assert len(request.files_checked) == 2\n assert len(request.relevant_files) == 1\n assert len(request.relevant_context) == 2\n assert len(request.issues_found) == 1\n assert len(request.images) == 1\n\n def test_precommit_specific_fields(self):\n \"\"\"Test precommit-specific configuration fields\"\"\"\n request = PrecommitRequest(\n step=\"Validation with git config\",\n step_number=1,\n total_steps=1,\n next_step_required=False,\n findings=\"Complete validation\",\n path=\"/repo\",\n compare_to=\"main\",\n include_staged=True,\n include_unstaged=False,\n focus_on=\"security issues\",\n severity_filter=\"high\",\n )\n\n assert request.compare_to == \"main\"\n assert request.include_staged is True\n assert request.include_unstaged is False\n assert request.focus_on == \"security issues\"\n assert request.severity_filter == \"high\"\n\n def test_precommit_type_validation(self):\n \"\"\"Test precommit type validation\"\"\"\n valid_types = [\"external\", \"internal\"]\n\n for precommit_type in valid_types:\n request = PrecommitRequest(\n step=\"Test precommit type\",\n step_number=1,\n total_steps=1,\n next_step_required=False,\n findings=\"Test findings\",\n path=\"/repo\",\n precommit_type=precommit_type,\n )\n assert request.precommit_type == precommit_type\n\n # Test default is external\n request = PrecommitRequest(\n step=\"Test default type\",\n step_number=1,\n total_steps=1,\n next_step_required=False,\n findings=\"Test findings\",\n path=\"/repo\",\n )\n assert request.precommit_type == \"external\"\n\n def test_severity_filter_options(self):\n \"\"\"Test severity filter validation\"\"\"\n valid_severities = [\"critical\", \"high\", \"medium\", \"low\", \"all\"]\n\n for severity in valid_severities:\n request = PrecommitRequest(\n step=\"Test severity filter\",\n step_number=1,\n total_steps=1,\n next_step_required=False,\n findings=\"Test findings\",\n path=\"/repo\",\n severity_filter=severity,\n )\n assert request.severity_filter == severity\n\n def test_input_schema_generation(self):\n \"\"\"Test that input schema is generated correctly\"\"\"\n tool = PrecommitTool()\n schema = tool.get_input_schema()\n\n # Check basic schema structure\n assert schema[\"type\"] == \"object\"\n assert \"properties\" in schema\n assert \"required\" in schema\n\n # Check required fields are present\n required_fields = {\"step\", \"step_number\", \"total_steps\", \"next_step_required\", \"findings\"}\n assert all(field in schema[\"properties\"] for field in required_fields)\n\n # Check model field is present and configured correctly\n assert \"model\" in schema[\"properties\"]\n assert schema[\"properties\"][\"model\"][\"type\"] == \"string\"\n\n def test_workflow_request_model_method(self):\n \"\"\"Test get_workflow_request_model returns correct model\"\"\"\n tool = PrecommitTool()\n assert tool.get_workflow_request_model() == PrecommitRequest\n assert tool.get_request_model() == PrecommitRequest\n\n def test_system_prompt_integration(self):\n \"\"\"Test system prompt integration\"\"\"\n tool = PrecommitTool()\n system_prompt = tool.get_system_prompt()\n\n # Should get the precommit prompt\n assert isinstance(system_prompt, str)\n assert len(system_prompt) > 0\n" }, { "path": "tests/test_prompt_regression.py", "content": "\"\"\"\nIntegration tests to ensure normal prompt handling works with real API calls.\n\nThis test module verifies that all tools continue to work correctly with\nnormal-sized prompts using real integration testing instead of mocks.\n\nINTEGRATION TESTS:\nThese tests are marked with @pytest.mark.integration and make real API calls.\nThey use the local-llama model which is FREE and runs locally via Ollama.\n\nPrerequisites:\n- Ollama installed and running locally\n- CUSTOM_API_URL environment variable set to your Ollama endpoint (e.g., http://localhost:11434)\n- local-llama model available through custom provider configuration\n- No API keys required - completely FREE to run unlimited times!\n\nRunning Tests:\n- All tests (including integration): pytest tests/test_prompt_regression.py\n- Unit tests only: pytest tests/test_prompt_regression.py -m \"not integration\"\n- Integration tests only: pytest tests/test_prompt_regression.py -m \"integration\"\n\nNote: Integration tests skip gracefully if CUSTOM_API_URL is not set.\nThey are excluded from CI/CD but run by default locally when Ollama is configured.\n\"\"\"\n\nimport json\nimport os\nimport tempfile\n\nimport pytest\n\n# Load environment variables from .env file\nfrom dotenv import load_dotenv\n\nfrom tools.analyze import AnalyzeTool\nfrom tools.chat import ChatTool\nfrom tools.codereview import CodeReviewTool\nfrom tools.thinkdeep import ThinkDeepTool\n\nload_dotenv()\n\n# Check if CUSTOM_API_URL is available for local-llama\nCUSTOM_API_AVAILABLE = os.getenv(\"CUSTOM_API_URL\") is not None\n\n\ndef skip_if_no_custom_api():\n \"\"\"Helper to skip integration tests if CUSTOM_API_URL is not available.\"\"\"\n if not CUSTOM_API_AVAILABLE:\n pytest.skip(\n \"CUSTOM_API_URL not set. To run integration tests with local-llama, ensure CUSTOM_API_URL is set in .env file (e.g., http://localhost:11434/v1)\"\n )\n\n\nclass TestPromptIntegration:\n \"\"\"Integration test suite for normal prompt handling with real API calls.\"\"\"\n\n @pytest.mark.integration\n @pytest.mark.asyncio\n async def test_chat_normal_prompt(self):\n \"\"\"Test chat tool with normal prompt using real API.\"\"\"\n skip_if_no_custom_api()\n\n tool = ChatTool()\n\n result = await tool.execute(\n {\n \"prompt\": \"Explain Python decorators in one sentence\",\n \"model\": \"local-llama\", # Use available model for integration tests\n \"working_directory_absolute_path\": tempfile.gettempdir(),\n }\n )\n\n assert len(result) == 1\n output = json.loads(result[0].text)\n assert output[\"status\"] in [\"success\", \"continuation_available\"]\n assert \"content\" in output\n assert len(output[\"content\"]) > 0\n\n @pytest.mark.integration\n @pytest.mark.asyncio\n async def test_chat_with_files(self):\n \"\"\"Test chat tool with absolute_file_paths parameter using real API.\"\"\"\n skip_if_no_custom_api()\n\n tool = ChatTool()\n\n # Create a temporary Python file for testing\n with tempfile.NamedTemporaryFile(mode=\"w\", suffix=\".py\", delete=False) as f:\n f.write(\n \"\"\"\ndef hello_world():\n \\\"\\\"\\\"A simple hello world function.\\\"\\\"\\\"\n return \"Hello, World!\"\n\nif __name__ == \"__main__\":\n print(hello_world())\n\"\"\"\n )\n temp_file = f.name\n\n try:\n result = await tool.execute(\n {\n \"prompt\": \"What does this Python code do?\",\n \"absolute_file_paths\": [temp_file],\n \"model\": \"local-llama\",\n \"working_directory_absolute_path\": tempfile.gettempdir(),\n }\n )\n\n assert len(result) == 1\n output = json.loads(result[0].text)\n assert output[\"status\"] in [\"success\", \"continuation_available\"]\n assert \"content\" in output\n # Should mention the hello world function\n assert \"hello\" in output[\"content\"].lower() or \"function\" in output[\"content\"].lower()\n finally:\n # Clean up temp file\n os.unlink(temp_file)\n\n @pytest.mark.integration\n @pytest.mark.asyncio\n async def test_thinkdeep_normal_analysis(self):\n \"\"\"Test thinkdeep tool with normal analysis using real API.\"\"\"\n skip_if_no_custom_api()\n\n tool = ThinkDeepTool()\n\n result = await tool.execute(\n {\n \"step\": \"I think we should use a cache for performance\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Building a high-traffic API - considering scalability and reliability\",\n \"problem_context\": \"Building a high-traffic API\",\n \"focus_areas\": [\"scalability\", \"reliability\"],\n \"model\": \"local-llama\",\n }\n )\n\n assert len(result) == 1\n output = json.loads(result[0].text)\n # ThinkDeep workflow tool should process the analysis\n assert \"status\" in output\n assert output[\"status\"] in [\"calling_expert_analysis\", \"analysis_complete\", \"pause_for_investigation\"]\n\n @pytest.mark.integration\n @pytest.mark.asyncio\n async def test_codereview_normal_review(self):\n \"\"\"Test codereview tool with workflow inputs using real API.\"\"\"\n skip_if_no_custom_api()\n\n tool = CodeReviewTool()\n\n # Create a temporary Python file for testing\n with tempfile.NamedTemporaryFile(mode=\"w\", suffix=\".py\", delete=False) as f:\n f.write(\n \"\"\"\ndef process_user_input(user_input):\n # Potentially unsafe code for demonstration\n query = f\"SELECT * FROM users WHERE name = '{user_input}'\"\n return query\n\ndef main():\n user_name = input(\"Enter name: \")\n result = process_user_input(user_name)\n print(result)\n\"\"\"\n )\n temp_file = f.name\n\n try:\n result = await tool.execute(\n {\n \"step\": \"Initial code review investigation - examining security vulnerabilities\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"findings\": \"Found security issues in code\",\n \"relevant_files\": [temp_file],\n \"review_type\": \"security\",\n \"focus_on\": \"Look for SQL injection vulnerabilities\",\n \"model\": \"local-llama\",\n }\n )\n\n assert len(result) == 1\n output = json.loads(result[0].text)\n assert \"status\" in output\n assert output[\"status\"] in [\"pause_for_code_review\", \"calling_expert_analysis\"]\n finally:\n # Clean up temp file\n os.unlink(temp_file)\n\n # NOTE: Precommit test has been removed because the precommit tool has been\n # refactored to use a workflow-based pattern instead of accepting simple prompt/path fields.\n # The new precommit tool requires workflow fields like: step, step_number, total_steps,\n # next_step_required, findings, etc. See simulator_tests/test_precommitworkflow_validation.py\n # for comprehensive workflow testing.\n\n # NOTE: Debug tool test has been commented out because the debug tool has been\n # refactored to use a self-investigation pattern instead of accepting prompt/error_context fields.\n # The new debug tool requires fields like: step, step_number, total_steps, next_step_required, findings\n\n # @pytest.mark.asyncio\n # async def test_debug_normal_error(self, mock_model_response):\n # \"\"\"Test debug tool with normal error description.\"\"\"\n # tool = DebugIssueTool()\n #\n # with patch.object(tool, \"get_model_provider\") as mock_get_provider:\n # mock_provider = MagicMock()\n # mock_provider.get_provider_type.return_value = MagicMock(value=\"google\")\n # mock_provider.supports_thinking_mode.return_value = False\n # mock_provider.generate_content.return_value = mock_model_response(\n # \"Root cause: The variable is undefined. Fix: Initialize it...\"\n # )\n # mock_get_provider.return_value = mock_provider\n #\n # result = await tool.execute(\n # {\n # \"prompt\": \"TypeError: Cannot read property 'name' of undefined\",\n # \"error_context\": \"at line 42 in user.js\\n console.log(user.name)\",\n # \"runtime_info\": \"Node.js v16.14.0\",\n # }\n # )\n #\n # assert len(result) == 1\n # output = json.loads(result[0].text)\n # assert output[\"status\"] in [\"success\", \"continuation_available\"]\n # assert \"Next Steps:\" in output[\"content\"]\n # assert \"Root cause\" in output[\"content\"]\n\n @pytest.mark.integration\n @pytest.mark.asyncio\n async def test_analyze_normal_question(self):\n \"\"\"Test analyze tool with normal question using real API.\"\"\"\n skip_if_no_custom_api()\n\n tool = AnalyzeTool()\n\n # Create a temporary Python file demonstrating MVC pattern\n with tempfile.NamedTemporaryFile(mode=\"w\", suffix=\".py\", delete=False) as f:\n f.write(\n \"\"\"\n# Model\nclass User:\n def __init__(self, name, email):\n self.name = name\n self.email = email\n\n# View\nclass UserView:\n def display_user(self, user):\n return f\"User: {user.name} ({user.email})\"\n\n# Controller\nclass UserController:\n def __init__(self, model, view):\n self.model = model\n self.view = view\n\n def get_user_display(self):\n return self.view.display_user(self.model)\n\"\"\"\n )\n temp_file = f.name\n\n try:\n result = await tool.execute(\n {\n \"step\": \"What design patterns are used in this codebase?\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Initial architectural analysis\",\n \"relevant_files\": [temp_file],\n \"analysis_type\": \"architecture\",\n \"model\": \"local-llama\",\n }\n )\n\n assert len(result) == 1\n output = json.loads(result[0].text)\n assert \"status\" in output\n # Workflow analyze tool should process the analysis\n assert output[\"status\"] in [\"calling_expert_analysis\", \"pause_for_investigation\"]\n finally:\n # Clean up temp file\n os.unlink(temp_file)\n\n @pytest.mark.integration\n @pytest.mark.asyncio\n async def test_empty_optional_fields(self):\n \"\"\"Test tools work with empty optional fields using real API.\"\"\"\n skip_if_no_custom_api()\n\n tool = ChatTool()\n\n # Test with no absolute_file_paths parameter\n result = await tool.execute(\n {\n \"prompt\": \"Hello\",\n \"model\": \"local-llama\",\n \"working_directory_absolute_path\": tempfile.gettempdir(),\n }\n )\n\n assert len(result) == 1\n output = json.loads(result[0].text)\n assert output[\"status\"] in [\"success\", \"continuation_available\"]\n assert \"content\" in output\n\n @pytest.mark.integration\n @pytest.mark.asyncio\n async def test_thinking_modes_work(self):\n \"\"\"Test that thinking modes are properly passed through using real API.\"\"\"\n skip_if_no_custom_api()\n\n tool = ChatTool()\n\n result = await tool.execute(\n {\n \"prompt\": \"Explain quantum computing briefly\",\n \"thinking_mode\": \"low\",\n \"temperature\": 0.8,\n \"model\": \"local-llama\",\n \"working_directory_absolute_path\": tempfile.gettempdir(),\n }\n )\n\n assert len(result) == 1\n output = json.loads(result[0].text)\n assert output[\"status\"] in [\"success\", \"continuation_available\"]\n assert \"content\" in output\n # Should contain some quantum-related content\n assert \"quantum\" in output[\"content\"].lower() or \"computing\" in output[\"content\"].lower()\n\n @pytest.mark.integration\n @pytest.mark.asyncio\n async def test_special_characters_in_prompts(self):\n \"\"\"Test prompts with special characters work correctly using real API.\"\"\"\n skip_if_no_custom_api()\n\n tool = ChatTool()\n\n special_prompt = (\n 'Test with \"quotes\" and\\nnewlines\\tand tabs. Please just respond with the number that is the answer to 1+1.'\n )\n result = await tool.execute(\n {\n \"prompt\": special_prompt,\n \"model\": \"local-llama\",\n \"working_directory_absolute_path\": tempfile.gettempdir(),\n }\n )\n\n assert len(result) == 1\n output = json.loads(result[0].text)\n assert output[\"status\"] in [\"success\", \"continuation_available\"]\n assert \"content\" in output\n # Should handle the special characters without crashing - the exact content doesn't matter as much as not failing\n assert len(output[\"content\"]) > 0\n\n @pytest.mark.integration\n @pytest.mark.asyncio\n async def test_mixed_file_paths(self):\n \"\"\"Test handling of various file path formats using real API.\"\"\"\n skip_if_no_custom_api()\n\n tool = AnalyzeTool()\n\n # Create multiple temporary files to test different path formats\n temp_files = []\n try:\n # Create first file\n with tempfile.NamedTemporaryFile(mode=\"w\", suffix=\".py\", delete=False) as f:\n f.write(\"def function_one(): pass\")\n temp_files.append(f.name)\n\n # Create second file\n with tempfile.NamedTemporaryFile(mode=\"w\", suffix=\".js\", delete=False) as f:\n f.write(\"function functionTwo() { return 'hello'; }\")\n temp_files.append(f.name)\n\n result = await tool.execute(\n {\n \"step\": \"Analyze these files\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Initial file analysis\",\n \"relevant_files\": temp_files,\n \"model\": \"local-llama\",\n }\n )\n\n assert len(result) == 1\n output = json.loads(result[0].text)\n assert \"status\" in output\n # Should process the files\n assert output[\"status\"] in [\n \"calling_expert_analysis\",\n \"pause_for_investigation\",\n \"files_required_to_continue\",\n ]\n finally:\n # Clean up temp files\n for temp_file in temp_files:\n if os.path.exists(temp_file):\n os.unlink(temp_file)\n\n @pytest.mark.integration\n @pytest.mark.asyncio\n async def test_unicode_content(self):\n \"\"\"Test handling of unicode content in prompts using real API.\"\"\"\n skip_if_no_custom_api()\n\n tool = ChatTool()\n\n unicode_prompt = \"Explain what these mean: δ½ ε₯½δΈ–η•Œ (Chinese) and Ω…Ψ±Ψ­Ψ¨Ψ§ Ψ¨Ψ§Ω„ΨΉΨ§Ω„Ω… (Arabic)\"\n result = await tool.execute(\n {\n \"prompt\": unicode_prompt,\n \"model\": \"local-llama\",\n \"working_directory_absolute_path\": tempfile.gettempdir(),\n }\n )\n\n assert len(result) == 1\n output = json.loads(result[0].text)\n assert output[\"status\"] in [\"success\", \"continuation_available\"]\n assert \"content\" in output\n # Should mention hello or world or greeting in some form (including French equivalents)\n content_lower = output[\"content\"].lower()\n assert (\n \"hello\" in content_lower\n or \"world\" in content_lower\n or \"greeting\" in content_lower\n or \"bonjour\" in content_lower # French: hello\n or \"monde\" in content_lower # French: world\n or \"salut\" in content_lower # French: greeting\n )\n\n\nif __name__ == \"__main__\":\n # Run integration tests by default when called directly\n pytest.main([__file__, \"-v\", \"-m\", \"integration\"])\n" }, { "path": "tests/test_prompt_size_limit_bug_fix.py", "content": "\"\"\"\nTest for the prompt size limit bug fix.\n\nThis test verifies that SimpleTool correctly validates only the original user prompt\nwhen conversation history is embedded, rather than validating the full enhanced prompt.\n\"\"\"\n\nfrom tools.chat import ChatTool\nfrom tools.shared.base_models import ToolRequest\n\n\nclass TestPromptSizeLimitBugFix:\n \"\"\"Test that the prompt size limit bug is fixed\"\"\"\n\n def test_prompt_size_validation_with_conversation_history(self):\n \"\"\"Test that prompt size validation uses original prompt when conversation history is embedded\"\"\"\n\n # Create a ChatTool instance\n tool = ChatTool()\n\n # Simulate a short user prompt (should not trigger size limit)\n short_user_prompt = \"Thanks for the help!\"\n\n # Simulate conversation history (large content)\n conversation_history = \"=== CONVERSATION HISTORY ===\\n\" + (\"Previous conversation content. \" * 5000)\n\n # Simulate enhanced prompt with conversation history (what server.py creates)\n enhanced_prompt = f\"{conversation_history}\\n\\n=== NEW USER INPUT ===\\n{short_user_prompt}\"\n\n # Simulate server.py behavior: store original prompt in _current_arguments\n tool._current_arguments = {\n \"prompt\": enhanced_prompt, # Enhanced with history\n \"_original_user_prompt\": short_user_prompt, # Original user input (our fix)\n \"model\": \"local-llama\",\n }\n\n # Test the hook method directly\n validation_content = tool.get_prompt_content_for_size_validation(enhanced_prompt)\n\n # Should return the original short prompt, not the enhanced prompt\n assert validation_content == short_user_prompt\n assert len(validation_content) == len(short_user_prompt)\n assert len(validation_content) < 1000 # Much smaller than enhanced prompt\n\n # Verify the enhanced prompt would have triggered the bug\n assert len(enhanced_prompt) > 50000 # This would trigger size limit\n\n # Test that size check passes with the original prompt\n size_check = tool.check_prompt_size(validation_content)\n assert size_check is None # No size limit error\n\n # Test that size check would fail with enhanced prompt\n size_check_enhanced = tool.check_prompt_size(enhanced_prompt)\n assert size_check_enhanced is not None # Would trigger size limit\n assert size_check_enhanced[\"status\"] == \"resend_prompt\"\n\n def test_prompt_size_validation_without_original_prompt(self):\n \"\"\"Test fallback behavior when no original prompt is stored (new conversations)\"\"\"\n\n tool = ChatTool()\n\n user_content = \"Regular prompt without conversation history\"\n\n # No _current_arguments (new conversation scenario)\n tool._current_arguments = None\n\n # Should fall back to validating the full user content\n validation_content = tool.get_prompt_content_for_size_validation(user_content)\n assert validation_content == user_content\n\n def test_prompt_size_validation_with_missing_original_prompt(self):\n \"\"\"Test fallback when _current_arguments exists but no _original_user_prompt\"\"\"\n\n tool = ChatTool()\n\n user_content = \"Regular prompt without conversation history\"\n\n # _current_arguments exists but no _original_user_prompt field\n tool._current_arguments = {\n \"prompt\": user_content,\n \"model\": \"local-llama\",\n # No _original_user_prompt field\n }\n\n # Should fall back to validating the full user content\n validation_content = tool.get_prompt_content_for_size_validation(user_content)\n assert validation_content == user_content\n\n def test_base_tool_default_behavior(self):\n \"\"\"Test that BaseTool's default implementation validates full content\"\"\"\n\n from tools.shared.base_tool import BaseTool\n\n # Create a minimal tool implementation for testing\n class TestTool(BaseTool):\n def get_name(self) -> str:\n return \"test\"\n\n def get_description(self) -> str:\n return \"Test tool\"\n\n def get_input_schema(self) -> dict:\n return {}\n\n def get_request_model(self):\n return ToolRequest\n\n def get_system_prompt(self) -> str:\n return \"Test system prompt\"\n\n async def prepare_prompt(self, request) -> str:\n return \"Test prompt\"\n\n async def execute(self, arguments: dict) -> list:\n return []\n\n tool = TestTool()\n user_content = \"Test content\"\n\n # Default implementation should return the same content\n validation_content = tool.get_prompt_content_for_size_validation(user_content)\n assert validation_content == user_content\n" }, { "path": "tests/test_provider_retry_logic.py", "content": "\"\"\"Tests covering shared retry behaviour for providers.\"\"\"\n\nfrom types import SimpleNamespace\n\nimport pytest\n\nfrom providers.openai import OpenAIModelProvider\n\n\ndef _mock_chat_response(content: str = \"retry success\") -> SimpleNamespace:\n \"\"\"Create a minimal chat completion response for tests.\"\"\"\n\n usage = SimpleNamespace(prompt_tokens=10, completion_tokens=5, total_tokens=15)\n message = SimpleNamespace(content=content)\n choice = SimpleNamespace(message=message, finish_reason=\"stop\")\n return SimpleNamespace(choices=[choice], model=\"gpt-4.1\", id=\"resp-1\", created=123, usage=usage)\n\n\ndef test_openai_provider_retries_on_transient_error(monkeypatch):\n \"\"\"Provider should retry once for retryable errors and eventually succeed.\"\"\"\n\n monkeypatch.setattr(\"providers.base.time.sleep\", lambda _: None)\n\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n attempts = {\"count\": 0}\n\n def create_completion(**kwargs):\n attempts[\"count\"] += 1\n if attempts[\"count\"] == 1:\n raise RuntimeError(\"temporary network interruption\")\n return _mock_chat_response(\"second attempt response\")\n\n provider._client = SimpleNamespace(\n chat=SimpleNamespace(completions=SimpleNamespace(create=create_completion)),\n responses=SimpleNamespace(create=lambda **_: None),\n )\n\n result = provider.generate_content(\"hello\", \"gpt-4.1\")\n\n assert attempts[\"count\"] == 2, \"Expected a retry before succeeding\"\n assert result.content == \"second attempt response\"\n\n\ndef test_openai_provider_bails_on_non_retryable_error(monkeypatch):\n \"\"\"Provider should stop immediately when the error is marked non-retryable.\"\"\"\n\n monkeypatch.setattr(\"providers.base.time.sleep\", lambda _: None)\n\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n attempts = {\"count\": 0}\n\n def create_completion(**kwargs):\n attempts[\"count\"] += 1\n raise RuntimeError(\"context length exceeded 429\")\n\n provider._client = SimpleNamespace(\n chat=SimpleNamespace(completions=SimpleNamespace(create=create_completion)),\n responses=SimpleNamespace(create=lambda **_: None),\n )\n\n monkeypatch.setattr(\n OpenAIModelProvider,\n \"_is_error_retryable\",\n lambda self, error: False,\n )\n\n with pytest.raises(RuntimeError) as excinfo:\n provider.generate_content(\"hello\", \"gpt-4.1\")\n\n assert \"after 1 attempt\" in str(excinfo.value)\n assert attempts[\"count\"] == 1\n" }, { "path": "tests/test_provider_routing_bugs.py", "content": "\"\"\"\nTests that reproduce and prevent provider routing bugs.\n\nThese tests specifically cover bugs that were found in production:\n1. Fallback provider registration bypassing API key validation\n2. OpenRouter alias-based restrictions not working\n3. Double restriction filtering\n4. Missing provider_used metadata\n\"\"\"\n\nimport os\nfrom unittest.mock import Mock\n\nimport pytest\n\nfrom providers.registry import ModelProviderRegistry\nfrom providers.shared import ProviderType\nfrom tools.chat import ChatTool\nfrom tools.shared.base_models import ToolRequest\n\n\nclass MockRequest(ToolRequest):\n \"\"\"Mock request for testing.\"\"\"\n\n pass\n\n\nclass TestProviderRoutingBugs:\n \"\"\"Test cases that reproduce provider routing bugs.\"\"\"\n\n def setup_method(self):\n \"\"\"Set up clean state before each test.\"\"\"\n # Clear restriction service cache\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n # Clear provider registry\n registry = ModelProviderRegistry()\n registry._providers.clear()\n registry._initialized_providers.clear()\n\n def teardown_method(self):\n \"\"\"Clean up after each test.\"\"\"\n # Clear restriction service cache\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n @pytest.mark.no_mock_provider\n def test_fallback_routing_bug_reproduction(self):\n \"\"\"\n CRITICAL BUG TEST: Reproduce the bug where fallback logic auto-registers\n Google provider for 'flash' model without checking GEMINI_API_KEY.\n\n Scenario: User has only OPENROUTER_API_KEY, requests 'flash' model.\n Bug: System incorrectly uses Google provider instead of OpenRouter.\n \"\"\"\n # Save original environment\n original_env = {}\n for key in [\n \"GEMINI_API_KEY\",\n \"OPENAI_API_KEY\",\n \"XAI_API_KEY\",\n \"OPENROUTER_API_KEY\",\n \"OPENROUTER_ALLOWED_MODELS\",\n ]:\n original_env[key] = os.environ.get(key)\n\n try:\n # Set up bug scenario: only OpenRouter API key\n os.environ.pop(\"GEMINI_API_KEY\", None) # No Google API key\n os.environ.pop(\"OPENAI_API_KEY\", None)\n os.environ.pop(\"XAI_API_KEY\", None)\n os.environ.pop(\"OPENROUTER_ALLOWED_MODELS\", None) # Clear any restrictions\n os.environ[\"OPENROUTER_API_KEY\"] = \"test-openrouter-key\"\n\n # Register only OpenRouter provider (like in server.py:configure_providers)\n from providers.openrouter import OpenRouterProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENROUTER, OpenRouterProvider)\n\n # Create tool to test fallback logic\n tool = ChatTool()\n\n # Test: Request 'flash' model - should use OpenRouter, not auto-register Google\n provider = tool.get_model_provider(\"flash\")\n\n # ASSERTION: Should get OpenRouter provider, not Google\n assert provider is not None, \"Should find a provider for 'flash' model\"\n assert provider.get_provider_type() == ProviderType.OPENROUTER, (\n f\"Expected OpenRouter provider for 'flash' model with only OPENROUTER_API_KEY set, \"\n f\"but got {provider.get_provider_type()}\"\n )\n\n # Test common aliases that should all route to OpenRouter\n test_models = [\"flash\", \"pro\", \"o3\", \"o3-mini\", \"o4-mini\"]\n for model_name in test_models:\n provider = tool.get_model_provider(model_name)\n assert provider is not None, f\"Should find provider for '{model_name}'\"\n assert provider.get_provider_type() == ProviderType.OPENROUTER, (\n f\"Model '{model_name}' should route to OpenRouter when only OPENROUTER_API_KEY is set, \"\n f\"but got {provider.get_provider_type()}\"\n )\n\n finally:\n # Restore original environment\n for key, value in original_env.items():\n if value is None:\n os.environ.pop(key, None)\n else:\n os.environ[key] = value\n\n @pytest.mark.no_mock_provider\n def test_fallback_should_not_register_without_api_key(self):\n \"\"\"\n Test that fallback logic correctly validates API keys before registering providers.\n\n This test ensures the fix in tools/base.py:2067-2081 works correctly.\n \"\"\"\n # Save original environment\n original_env = {}\n for key in [\n \"GEMINI_API_KEY\",\n \"OPENAI_API_KEY\",\n \"XAI_API_KEY\",\n \"OPENROUTER_API_KEY\",\n \"OPENROUTER_ALLOWED_MODELS\",\n ]:\n original_env[key] = os.environ.get(key)\n\n try:\n # Set up scenario: NO API keys at all\n for key in [\n \"GEMINI_API_KEY\",\n \"OPENAI_API_KEY\",\n \"XAI_API_KEY\",\n \"OPENROUTER_API_KEY\",\n \"OPENROUTER_ALLOWED_MODELS\",\n ]:\n os.environ.pop(key, None)\n\n # Create tool to test fallback logic\n tool = ChatTool()\n\n # Test: Request 'flash' model with no API keys - should fail gracefully\n with pytest.raises(ValueError, match=\"Model 'flash' is not available\"):\n tool.get_model_provider(\"flash\")\n\n # Test: Request 'o3' model with no API keys - should fail gracefully\n with pytest.raises(ValueError, match=\"Model 'o3' is not available\"):\n tool.get_model_provider(\"o3\")\n\n # Verify no providers were auto-registered\n registry = ModelProviderRegistry()\n assert len(registry._providers) == 0, \"No providers should be registered without API keys\"\n\n finally:\n # Restore original environment\n for key, value in original_env.items():\n if value is None:\n os.environ.pop(key, None)\n else:\n os.environ[key] = value\n\n @pytest.mark.no_mock_provider\n def test_mixed_api_keys_correct_routing(self):\n \"\"\"\n Test that when multiple API keys are available, provider routing works correctly.\n \"\"\"\n # Save original environment\n original_env = {}\n for key in [\n \"GEMINI_API_KEY\",\n \"OPENAI_API_KEY\",\n \"XAI_API_KEY\",\n \"OPENROUTER_API_KEY\",\n \"OPENROUTER_ALLOWED_MODELS\",\n ]:\n original_env[key] = os.environ.get(key)\n\n try:\n # Set up scenario: Multiple API keys available\n os.environ[\"GEMINI_API_KEY\"] = \"test-gemini-key\"\n os.environ[\"OPENAI_API_KEY\"] = \"test-openai-key\"\n os.environ[\"OPENROUTER_API_KEY\"] = \"test-openrouter-key\"\n os.environ.pop(\"XAI_API_KEY\", None)\n os.environ.pop(\"OPENROUTER_ALLOWED_MODELS\", None) # Clear any restrictions\n\n # Register providers in priority order (like server.py)\n from providers.gemini import GeminiModelProvider\n from providers.openai import OpenAIModelProvider\n from providers.openrouter import OpenRouterProvider\n\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.OPENROUTER, OpenRouterProvider)\n\n tool = ChatTool()\n\n # Test priority order: Native APIs should be preferred over OpenRouter\n # Google models should use Google provider\n flash_provider = tool.get_model_provider(\"flash\")\n assert (\n flash_provider.get_provider_type() == ProviderType.GOOGLE\n ), \"When both Google and OpenRouter API keys are available, 'flash' should prefer Google provider\"\n\n # OpenAI models should use OpenAI provider\n o3_provider = tool.get_model_provider(\"o3\")\n assert (\n o3_provider.get_provider_type() == ProviderType.OPENAI\n ), \"When both OpenAI and OpenRouter API keys are available, 'o3' should prefer OpenAI provider\"\n\n finally:\n # Restore original environment\n for key, value in original_env.items():\n if value is None:\n os.environ.pop(key, None)\n else:\n os.environ[key] = value\n\n\nclass TestOpenRouterAliasRestrictions:\n \"\"\"Test OpenRouter model restrictions with aliases - reproduces restriction bug.\"\"\"\n\n def setup_method(self):\n \"\"\"Set up clean state before each test.\"\"\"\n # Clear restriction service cache\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n # Clear provider registry\n registry = ModelProviderRegistry()\n registry._providers.clear()\n registry._initialized_providers.clear()\n\n def teardown_method(self):\n \"\"\"Clean up after each test.\"\"\"\n # Clear restriction service cache\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n @pytest.mark.no_mock_provider\n def test_openrouter_alias_restrictions_bug_reproduction(self):\n \"\"\"\n CRITICAL BUG TEST: Reproduce the bug where OpenRouter restrictions with aliases\n resulted in \"no models available\" error.\n\n Bug scenario: OPENROUTER_ALLOWED_MODELS=o3-mini,pro,flash,o4-mini,o3\n Expected: 5 models available (aliases resolve to full names)\n Bug: 0 models available due to alias resolution failure\n \"\"\"\n # Save original environment\n original_env = {}\n for key in [\n \"GEMINI_API_KEY\",\n \"OPENAI_API_KEY\",\n \"XAI_API_KEY\",\n \"OPENROUTER_API_KEY\",\n \"OPENROUTER_ALLOWED_MODELS\",\n ]:\n original_env[key] = os.environ.get(key)\n\n try:\n # Set up bug scenario: Only OpenRouter with alias-based restrictions\n os.environ.pop(\"GEMINI_API_KEY\", None)\n os.environ.pop(\"OPENAI_API_KEY\", None)\n os.environ.pop(\"XAI_API_KEY\", None)\n os.environ[\"OPENROUTER_API_KEY\"] = \"test-key\"\n os.environ[\"OPENROUTER_ALLOWED_MODELS\"] = \"o3-mini,pro,gpt4.1,flash,o4-mini,o3\" # User's exact config\n\n # Register OpenRouter provider\n from providers.openrouter import OpenRouterProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENROUTER, OpenRouterProvider)\n\n # Test: Get available models with restrictions\n available_models = ModelProviderRegistry.get_available_models(respect_restrictions=True)\n\n # ASSERTION: Should have models available, not 0\n assert len(available_models) > 0, (\n f\"Expected models available with alias restrictions 'o3-mini,pro,gpt4.1,flash,o4-mini,o3', \"\n f\"but got {len(available_models)} models. Available: {list(available_models.keys())}\"\n )\n\n # Expected aliases that should resolve to models:\n # o3-mini -> openai/o3-mini\n # pro -> google/gemini-2.5-pro\n # flash -> google/gemini-2.5-flash\n # o4-mini -> openai/o4-mini\n # o3 -> openai/o3\n # gpt4.1 -> should not exist (expected to be filtered out)\n\n expected_models = {\"o3-mini\", \"pro\", \"flash\", \"o4-mini\", \"o3\"}\n\n available_model_names = set(available_models.keys())\n\n # Should have at least the resolvable aliases (5 out of 6)\n assert len(available_model_names) >= 5, (\n f\"Expected at least 5 models from alias restrictions, got {len(available_model_names)}: \"\n f\"{available_model_names}\"\n )\n\n # Check that expected models are present\n missing_models = expected_models - available_model_names\n assert len(missing_models) == 0, (\n f\"Missing expected models from alias restrictions: {missing_models}. \"\n f\"Available: {available_model_names}\"\n )\n\n finally:\n # Restore original environment\n for key, value in original_env.items():\n if value is None:\n os.environ.pop(key, None)\n else:\n os.environ[key] = value\n\n @pytest.mark.no_mock_provider\n def test_openrouter_mixed_alias_and_full_names(self):\n \"\"\"Test OpenRouter restrictions with mix of aliases and full model names.\"\"\"\n # Save original environment\n original_env = {}\n for key in [\n \"GEMINI_API_KEY\",\n \"OPENAI_API_KEY\",\n \"XAI_API_KEY\",\n \"OPENROUTER_API_KEY\",\n \"OPENROUTER_ALLOWED_MODELS\",\n ]:\n original_env[key] = os.environ.get(key)\n\n try:\n # Set up mixed restrictions: some aliases, some full names\n os.environ.pop(\"GEMINI_API_KEY\", None)\n os.environ.pop(\"OPENAI_API_KEY\", None)\n os.environ.pop(\"XAI_API_KEY\", None)\n os.environ[\"OPENROUTER_API_KEY\"] = \"test-key\"\n os.environ[\"OPENROUTER_ALLOWED_MODELS\"] = \"o3-mini,anthropic/claude-opus-4.1,flash\"\n\n # Register OpenRouter provider\n from providers.openrouter import OpenRouterProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENROUTER, OpenRouterProvider)\n\n # Test: Get available models\n available_models = ModelProviderRegistry.get_available_models(respect_restrictions=True)\n\n expected_models = {\n \"o3-mini\", # alias\n \"openai/o3-mini\", # canonical\n \"anthropic/claude-opus-4.1\", # full name\n \"flash\", # alias\n \"google/gemini-2.5-flash\", # canonical\n }\n\n available_model_names = set(available_models.keys())\n\n assert (\n available_model_names == expected_models\n ), f\"Expected models {expected_models}, got {available_model_names}\"\n\n finally:\n # Restore original environment\n for key, value in original_env.items():\n if value is None:\n os.environ.pop(key, None)\n else:\n os.environ[key] = value\n\n\nclass TestProviderMetadataBug:\n \"\"\"Test for missing provider_used metadata bug.\"\"\"\n\n def test_provider_used_metadata_included(self):\n \"\"\"\n Test that provider_used metadata is included in tool responses.\n\n Bug: Only model_used was included, provider_used was missing.\n Fix: Added provider_used field in tools/base.py\n \"\"\"\n # Test the actual _parse_response method with model_info\n tool = ChatTool()\n\n # Create mock provider\n mock_provider = Mock()\n mock_provider.get_provider_type.return_value = ProviderType.OPENROUTER\n\n # Create model_info like the execute method does\n model_info = {\"provider\": mock_provider, \"model_name\": \"test-model\", \"model_response\": Mock()}\n\n # Test _parse_response directly with a simple response\n request = MockRequest()\n result = tool._parse_response(\"Test response\", request, model_info)\n\n # Verify metadata includes both model_used and provider_used\n assert hasattr(result, \"metadata\"), \"ToolOutput should have metadata\"\n assert result.metadata is not None, \"Metadata should not be None\"\n assert \"model_used\" in result.metadata, \"Metadata should include model_used\"\n assert result.metadata[\"model_used\"] == \"test-model\", \"model_used should be correct\"\n assert \"provider_used\" in result.metadata, \"Metadata should include provider_used (bug fix)\"\n assert result.metadata[\"provider_used\"] == \"openrouter\", \"provider_used should be correct\"\n" }, { "path": "tests/test_provider_utf8.py", "content": "\"\"\"\nUnit tests to validate UTF-8 encoding in providers\nand integration with language models.\n\"\"\"\n\nimport json\nimport os\nimport unittest\nfrom unittest.mock import Mock, patch\n\nimport pytest\n\nfrom providers.gemini import GeminiModelProvider\nfrom providers.openai import OpenAIModelProvider\nfrom providers.shared import ProviderType\n\n\nclass TestProviderUTF8Encoding(unittest.TestCase):\n \"\"\"Tests for UTF-8 encoding in providers.\"\"\"\n\n def setUp(self):\n \"\"\"Test setup.\"\"\"\n self.original_locale = os.getenv(\"LOCALE\")\n\n def tearDown(self):\n \"\"\"Cleanup after tests.\"\"\"\n if self.original_locale is not None:\n os.environ[\"LOCALE\"] = self.original_locale\n else:\n os.environ.pop(\"LOCALE\", None)\n\n def test_base_provider_utf8_support(self):\n \"\"\"Test that the OpenAI provider supports UTF-8.\"\"\"\n provider = OpenAIModelProvider(api_key=\"test\")\n\n # Test with UTF-8 characters\n test_text = \"DΓ©veloppement en franΓ§ais avec Γ©mojis πŸš€\"\n tokens = provider.count_tokens(test_text, \"gpt-4\")\n\n # Should return a valid number (character-based estimate)\n self.assertIsInstance(tokens, int)\n self.assertGreater(tokens, 0)\n\n @pytest.mark.skip(reason=\"Requires real Gemini API access\")\n @patch(\"google.generativeai.GenerativeModel\")\n def test_gemini_provider_utf8_request(self, mock_model_class):\n \"\"\"Test that the Gemini provider handles UTF-8 correctly.\"\"\"\n # Mock Gemini response\n mock_response = Mock()\n mock_response.text = \"Response in French with accents: créé, dΓ©veloppΓ©, prΓ©fΓ©rΓ© πŸŽ‰\"\n mock_response.usage_metadata = Mock()\n mock_response.usage_metadata.prompt_token_count = 10\n mock_response.usage_metadata.candidates_token_count = 15\n mock_response.usage_metadata.total_token_count = 25\n\n mock_model = Mock()\n mock_model.generate_content.return_value = mock_response\n mock_model_class.return_value = mock_model\n\n # Test Gemini provider\n provider = GeminiModelProvider(api_key=\"test-key\")\n\n # Request with UTF-8 characters\n response = provider.generate_content(\n prompt=\"Can you explain software development?\",\n model_name=\"gemini-2.5-flash\",\n system_prompt=\"Reply in French with emojis.\",\n )\n\n # Checks\n self.assertIsNotNone(response)\n self.assertIn(\"French\", response.content)\n self.assertIn(\"πŸŽ‰\", response.content)\n\n # Check that the request contains UTF-8 characters\n mock_model.generate_content.assert_called_once()\n call_args = mock_model.generate_content.call_args\n parts = call_args[0][0] # First argument (parts)\n\n # Check for UTF-8 content in the request\n request_content = str(parts)\n self.assertIn(\"dΓ©veloppement\", request_content)\n\n @pytest.mark.skip(reason=\"Requires real OpenAI API access\")\n @patch(\"openai.OpenAI\")\n def test_openai_provider_utf8_logging(self, mock_openai_class):\n \"\"\"Test that the OpenAI provider logs UTF-8 correctly.\"\"\"\n # Mock OpenAI response\n mock_response = Mock()\n mock_response.choices = [Mock()]\n mock_response.choices[0].message = Mock()\n mock_response.choices[0].message.content = \"Python code created successfully! βœ…\"\n mock_response.usage = Mock()\n mock_response.usage.prompt_tokens = 20\n mock_response.usage.completion_tokens = 10\n mock_response.usage.total_tokens = 30\n\n mock_client = Mock()\n mock_client.chat.completions.create.return_value = mock_response\n mock_openai_class.return_value = mock_client # Test OpenAI provider\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Test with UTF-8 logging\n with patch(\"logging.info\"):\n response = provider.generate_content(\n prompt=\"Generate Python code to process data\",\n model_name=\"gpt-4\",\n system_prompt=\"You are an expert Python developer.\",\n )\n\n # Response checks\n self.assertIsNotNone(response)\n self.assertIn(\"created\", response.content)\n self.assertIn(\"βœ…\", response.content)\n\n @pytest.mark.skip(reason=\"Requires real OpenAI API access\")\n @patch(\"openai.OpenAI\")\n def test_openai_compatible_o3_pro_utf8(self, mock_openai_class):\n \"\"\"Test for o3-pro with /responses endpoint and UTF-8.\"\"\"\n # Mock o3-pro response\n mock_response = Mock()\n mock_response.output = Mock()\n mock_response.output.content = [Mock()]\n mock_response.output.content[0].type = \"output_text\"\n mock_response.output.content[0].text = \"Analysis complete: code is well structured! 🎯\"\n mock_response.usage = Mock()\n mock_response.usage.input_tokens = 50\n mock_response.usage.output_tokens = 25\n mock_response.model = \"o3-pro\"\n mock_response.id = \"test-id\"\n mock_response.created_at = 1234567890\n\n mock_client = Mock()\n mock_client.responses.create.return_value = mock_response\n mock_openai_class.return_value = mock_client\n\n # Test OpenAI Compatible provider with o3-pro\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Test with UTF-8 logging for o3-pro\n with patch(\"logging.info\") as mock_logging:\n response = provider.generate_content(\n prompt=\"Analyze this Python code for issues\",\n model_name=\"o3-pro\",\n system_prompt=\"You are a code review expert.\",\n )\n\n # Response checks\n self.assertIsNotNone(response)\n self.assertIn(\"complete\", response.content)\n self.assertIn(\"🎯\", response.content)\n\n # Check that logging was called with ensure_ascii=False\n mock_logging.assert_called()\n log_calls = [call for call in mock_logging.call_args_list if \"API request payload\" in str(call)]\n self.assertTrue(len(log_calls) > 0, \"No API payload log found\")\n\n def test_provider_type_enum_utf8_safe(self):\n \"\"\"Test that ProviderType enum is UTF-8 safe.\"\"\"\n # Test all provider types\n provider_types = list(ProviderType)\n\n for provider_type in provider_types:\n # Test JSON serialization\n data = {\"provider\": provider_type.value, \"message\": \"UTF-8 test: emojis πŸš€\"}\n json_str = json.dumps(data, ensure_ascii=False)\n\n # Checks\n self.assertIn(provider_type.value, json_str)\n self.assertIn(\"emojis\", json_str)\n self.assertIn(\"πŸš€\", json_str)\n\n # Test deserialization\n parsed = json.loads(json_str)\n self.assertEqual(parsed[\"provider\"], provider_type.value)\n self.assertEqual(parsed[\"message\"], \"UTF-8 test: emojis πŸš€\")\n\n def test_model_response_utf8_serialization(self):\n \"\"\"Test UTF-8 serialization of model responses.\"\"\"\n from providers.shared import ModelResponse\n\n response = ModelResponse(\n content=\"Development successful! Code generated successfully. πŸŽ‰βœ…\",\n usage={\"input_tokens\": 10, \"output_tokens\": 15, \"total_tokens\": 25},\n model_name=\"test-model\",\n friendly_name=\"Test Model\",\n provider=ProviderType.OPENAI, # Pass enum, not .value\n metadata={\"created\": \"2024-01-01\", \"developer\": \"Test\", \"emojis\": \"πŸš€πŸŽ―πŸ”₯\"},\n )\n\n response_dict = getattr(response, \"to_dict\", None)\n if callable(response_dict):\n response_dict = response.to_dict()\n else:\n # Convert ProviderType to string for JSON serialization\n d = response.__dict__.copy()\n if isinstance(d.get(\"provider\"), ProviderType):\n d[\"provider\"] = d[\"provider\"].value\n response_dict = d\n json_str = json.dumps(response_dict, ensure_ascii=False, indent=2)\n\n # Checks\n self.assertIn(\"Development\", json_str)\n self.assertIn(\"successful\", json_str)\n self.assertIn(\"generated\", json_str)\n self.assertIn(\"πŸŽ‰\", json_str)\n self.assertIn(\"βœ…\", json_str)\n self.assertIn(\"created\", json_str)\n self.assertIn(\"developer\", json_str)\n self.assertIn(\"πŸš€\", json_str)\n\n # Test deserialization\n parsed = json.loads(json_str)\n self.assertEqual(parsed[\"content\"], response.content)\n self.assertEqual(parsed[\"friendly_name\"], \"Test Model\")\n\n def test_error_handling_with_utf8(self):\n \"\"\"Test error handling with UTF-8 characters.\"\"\"\n provider = OpenAIModelProvider(api_key=\"test\")\n # Test validation with UTF-8 error message (no exception expected)\n error_message = None\n try:\n provider.validate_parameters(\"gpt-4\", -1.0) # Invalid temperature\n except Exception as e:\n error_message = str(e)\n # Error message may contain UTF-8 characters or be None\n if error_message:\n self.assertIsInstance(error_message, str)\n else:\n # No exception: test passes (current provider logs a warning only)\n self.assertTrue(True)\n\n def test_temperature_handling_utf8_locale(self):\n \"\"\"Test temperature handling with UTF-8 locale.\"\"\"\n # Set French locale\n os.environ[\"LOCALE\"] = \"fr-FR\"\n\n provider = OpenAIModelProvider(api_key=\"test\")\n\n # Test different temperatures\n test_temps = [0.0, 0.5, 1.0, 1.5, 2.0]\n\n for temp in test_temps:\n try:\n provider.validate_parameters(\"gpt-4\", temp)\n # If no exception, temperature is valid\n self.assertLessEqual(temp, 2.0)\n except ValueError:\n # If exception, temperature must be > 2.0\n self.assertGreater(temp, 2.0)\n\n def test_provider_registry_utf8(self):\n \"\"\"Test that the provider registry handles UTF-8.\"\"\"\n from providers.registry import ModelProviderRegistry\n\n # Test listing providers with UTF-8 descriptions\n providers = ModelProviderRegistry.get_available_providers()\n\n # Should contain valid providers\n self.assertGreater(len(providers), 0)\n\n # Test serialization\n provider_data = {\n \"providers\": [p.value for p in providers],\n \"description\": \"Available providers for development πŸš€\",\n }\n\n json_str = json.dumps(provider_data, ensure_ascii=False)\n\n # Checks\n self.assertIn(\"development\", json_str)\n self.assertIn(\"πŸš€\", json_str)\n\n # Test parsing\n parsed = json.loads(json_str)\n self.assertEqual(parsed[\"description\"], provider_data[\"description\"])\n\n @pytest.mark.skip(reason=\"Requires real Gemini API access\")\n @patch(\"google.generativeai.GenerativeModel\")\n def test_gemini_provider_handles_api_encoding_error(self, mock_model_class):\n \"\"\"Test that the Gemini provider handles a non-UTF-8 API response.\"\"\"\n from unittest.mock import PropertyMock\n\n mock_response = Mock()\n type(mock_response).text = PropertyMock(\n side_effect=UnicodeDecodeError(\"utf-8\", b\"\\xfa\", 0, 1, \"invalid start byte\")\n )\n mock_model = Mock()\n mock_model.generate_content.return_value = mock_response\n mock_model_class.return_value = mock_model\n provider = GeminiModelProvider(api_key=\"test-key\")\n with self.assertRaises(Exception) as context:\n provider.generate_content(\n prompt=\"Explain something\",\n model_name=\"gemini-2.5-flash\",\n system_prompt=\"Reply in French.\",\n )\n # Accept any error message containing UnicodeDecodeError\n self.assertIn(\"UnicodeDecodeError\", str(context.exception))\n\n\nclass DummyToolForLocaleTest:\n \"\"\"Utility class to test language instruction generation.\"\"\"\n\n def get_language_instruction(self):\n locale = os.environ.get(\"LOCALE\", \"\")\n if not locale or not locale.strip():\n return \"\"\n return f\"Always respond in {locale.strip()}.\\n\\n\"\n\n\nclass TestLocaleModelIntegration(unittest.TestCase):\n \"\"\"Integration tests between locale and models.\"\"\"\n\n def setUp(self):\n \"\"\"Integration test setup.\"\"\"\n self.original_locale = os.getenv(\"LOCALE\")\n\n def tearDown(self):\n \"\"\"Cleanup after integration tests.\"\"\"\n if self.original_locale is not None:\n os.environ[\"LOCALE\"] = self.original_locale\n else:\n os.environ.pop(\"LOCALE\", None)\n\n def test_system_prompt_enhancement_french(self):\n \"\"\"Test system prompt enhancement with French locale.\"\"\"\n os.environ[\"LOCALE\"] = \"fr-FR\"\n OpenAIModelProvider(api_key=\"test\")\n # Simulate language instruction\n tool = DummyToolForLocaleTest()\n instruction = tool.get_language_instruction()\n self.assertIn(\"fr-FR\", instruction)\n self.assertTrue(instruction.startswith(\"Always respond in fr-FR\"))\n\n def test_system_prompt_enhancement_multiple_locales(self):\n \"\"\"Test enhancement with different locales.\"\"\"\n OpenAIModelProvider(api_key=\"test\")\n locales = [\"fr-FR\", \"es-ES\", \"de-DE\", \"it-IT\", \"pt-BR\", \"ja-JP\", \"zh-CN\"]\n for locale in locales:\n os.environ[\"LOCALE\"] = locale\n tool = DummyToolForLocaleTest()\n instruction = tool.get_language_instruction()\n self.assertIn(locale, instruction)\n self.assertTrue(instruction.startswith(f\"Always respond in {locale}\"))\n prompt_data = {\"system_prompt\": instruction, \"locale\": locale}\n json_str = json.dumps(prompt_data, ensure_ascii=False)\n parsed = json.loads(json_str)\n self.assertEqual(parsed[\"locale\"], locale)\n\n def test_model_name_resolution_utf8(self):\n \"\"\"Test model name resolution with UTF-8.\"\"\"\n provider = OpenAIModelProvider(api_key=\"test\")\n model_names = [\"gpt-4\", \"gemini-2.5-flash\", \"anthropic/claude-opus-4.1\", \"o3-pro\"]\n for model_name in model_names:\n resolved_model_name = provider._resolve_model_name(model_name)\n self.assertIsInstance(resolved_model_name, str)\n model_data = {\n \"model\": resolved_model_name,\n \"description\": f\"Model {model_name} - advanced development πŸš€\",\n \"capabilities\": [\"generation\", \"review\", \"creation\"],\n }\n json_str = json.dumps(model_data, ensure_ascii=False)\n self.assertIn(\"development\", json_str)\n self.assertIn(\"generation\", json_str)\n self.assertIn(\"review\", json_str)\n self.assertIn(\"creation\", json_str)\n self.assertIn(\"πŸš€\", json_str)\n\n def test_system_prompt_enhancement_with_unusual_locale_formats(self):\n \"\"\"Test language instruction with various locale formats.\"\"\"\n test_locales = [\n \"fr\", # Language only\n \"fr_FR\", # Language and region with underscore\n \"de-DE.UTF-8\", # Full locale with encoding\n ]\n for locale in test_locales:\n with self.subTest(locale=locale):\n os.environ[\"LOCALE\"] = locale\n tool = DummyToolForLocaleTest()\n instruction = tool.get_language_instruction()\n self.assertTrue(instruction.startswith(f\"Always respond in {locale}\"))\n" }, { "path": "tests/test_providers.py", "content": "\"\"\"Tests for the model provider abstraction system\"\"\"\n\nimport os\nfrom unittest.mock import Mock, patch\n\nimport pytest\n\nfrom providers import ModelProviderRegistry, ModelResponse\nfrom providers.gemini import GeminiModelProvider\nfrom providers.openai import OpenAIModelProvider\nfrom providers.shared import ProviderType\n\n\nclass TestModelProviderRegistry:\n \"\"\"Test the model provider registry\"\"\"\n\n def setup_method(self):\n \"\"\"Clear registry before each test\"\"\"\n # Store the original providers to restore them later\n registry = ModelProviderRegistry()\n self._original_providers = registry._providers.copy()\n registry._providers.clear()\n registry._initialized_providers.clear()\n\n def teardown_method(self):\n \"\"\"Restore original providers after each test\"\"\"\n # Restore the original providers that were registered in conftest.py\n registry = ModelProviderRegistry()\n registry._providers.clear()\n registry._initialized_providers.clear()\n registry._providers.update(self._original_providers)\n\n def test_register_provider(self):\n \"\"\"Test registering a provider\"\"\"\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n registry = ModelProviderRegistry()\n assert ProviderType.GOOGLE in registry._providers\n assert registry._providers[ProviderType.GOOGLE] == GeminiModelProvider\n\n @patch.dict(os.environ, {\"GEMINI_API_KEY\": \"test-key\"})\n def test_get_provider(self):\n \"\"\"Test getting a provider instance\"\"\"\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n provider = ModelProviderRegistry.get_provider(ProviderType.GOOGLE)\n\n assert provider is not None\n assert isinstance(provider, GeminiModelProvider)\n assert provider.api_key == \"test-key\"\n\n @patch.dict(os.environ, {}, clear=True)\n def test_get_provider_no_api_key(self):\n \"\"\"Test getting provider without API key returns None\"\"\"\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n provider = ModelProviderRegistry.get_provider(ProviderType.GOOGLE)\n\n assert provider is None\n\n @patch.dict(os.environ, {\"GEMINI_API_KEY\": \"test-key\"})\n @pytest.mark.no_mock_provider\n def test_get_provider_for_model(self):\n \"\"\"Test getting provider for a specific model\"\"\"\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n\n provider = ModelProviderRegistry.get_provider_for_model(\"gemini-2.5-flash\")\n\n assert provider is not None\n assert isinstance(provider, GeminiModelProvider)\n\n def test_get_available_providers(self):\n \"\"\"Test getting list of available providers\"\"\"\n ModelProviderRegistry.register_provider(ProviderType.GOOGLE, GeminiModelProvider)\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n\n providers = ModelProviderRegistry.get_available_providers()\n\n assert len(providers) == 2\n assert ProviderType.GOOGLE in providers\n assert ProviderType.OPENAI in providers\n\n\nclass TestGeminiProvider:\n \"\"\"Test Gemini model provider\"\"\"\n\n def test_provider_initialization(self):\n \"\"\"Test provider initialization\"\"\"\n provider = GeminiModelProvider(api_key=\"test-key\")\n\n assert provider.api_key == \"test-key\"\n assert provider.get_provider_type() == ProviderType.GOOGLE\n\n def test_get_capabilities(self):\n \"\"\"Test getting model capabilities\"\"\"\n provider = GeminiModelProvider(api_key=\"test-key\")\n\n capabilities = provider.get_capabilities(\"gemini-2.5-flash\")\n\n assert capabilities.provider == ProviderType.GOOGLE\n assert capabilities.model_name == \"gemini-2.5-flash\"\n assert capabilities.context_window == 1_048_576\n assert capabilities.supports_extended_thinking\n\n def test_get_capabilities_pro_model(self):\n \"\"\"Test getting capabilities for Pro model with thinking support\"\"\"\n provider = GeminiModelProvider(api_key=\"test-key\")\n\n capabilities = provider.get_capabilities(\"gemini-2.5-pro\")\n\n assert capabilities.supports_extended_thinking\n\n def test_model_shorthand_resolution(self):\n \"\"\"Test model shorthand resolution\"\"\"\n provider = GeminiModelProvider(api_key=\"test-key\")\n\n assert provider.validate_model_name(\"flash\")\n assert provider.validate_model_name(\"pro\")\n\n capabilities = provider.get_capabilities(\"flash\")\n assert capabilities.model_name == \"gemini-2.5-flash\"\n\n @patch(\"google.genai.Client\")\n def test_generate_content(self, mock_client_class):\n \"\"\"Test content generation\"\"\"\n # Mock the client\n mock_client = Mock()\n mock_response = Mock()\n mock_response.text = \"Generated content\"\n # Mock candidates for finish_reason\n mock_candidate = Mock()\n mock_candidate.finish_reason = \"STOP\"\n mock_response.candidates = [mock_candidate]\n # Mock usage metadata\n mock_usage = Mock()\n mock_usage.prompt_token_count = 10\n mock_usage.candidates_token_count = 20\n mock_response.usage_metadata = mock_usage\n mock_client.models.generate_content.return_value = mock_response\n mock_client_class.return_value = mock_client\n\n provider = GeminiModelProvider(api_key=\"test-key\")\n\n response = provider.generate_content(prompt=\"Test prompt\", model_name=\"gemini-2.5-flash\", temperature=0.7)\n\n assert isinstance(response, ModelResponse)\n assert response.content == \"Generated content\"\n assert response.model_name == \"gemini-2.5-flash\"\n assert response.provider == ProviderType.GOOGLE\n assert response.usage[\"input_tokens\"] == 10\n assert response.usage[\"output_tokens\"] == 20\n assert response.usage[\"total_tokens\"] == 30\n\n\nclass TestOpenAIProvider:\n \"\"\"Test OpenAI model provider\"\"\"\n\n def setup_method(self):\n \"\"\"Clear restriction service cache before each test\"\"\"\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n def teardown_method(self):\n \"\"\"Clear restriction service cache after each test\"\"\"\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n def test_provider_initialization(self):\n \"\"\"Test provider initialization\"\"\"\n provider = OpenAIModelProvider(api_key=\"test-key\", organization=\"test-org\")\n\n assert provider.api_key == \"test-key\"\n assert provider.organization == \"test-org\"\n assert provider.get_provider_type() == ProviderType.OPENAI\n\n def test_get_capabilities_o3(self):\n \"\"\"Test getting O3 model capabilities\"\"\"\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n capabilities = provider.get_capabilities(\"o3-mini\")\n\n assert capabilities.provider == ProviderType.OPENAI\n assert capabilities.model_name == \"o3-mini\"\n assert capabilities.context_window == 200_000\n assert not capabilities.supports_extended_thinking\n\n def test_get_capabilities_o4_mini(self):\n \"\"\"Test getting O4-mini model capabilities\"\"\"\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n capabilities = provider.get_capabilities(\"o4-mini\")\n\n assert capabilities.provider == ProviderType.OPENAI\n assert capabilities.model_name == \"o4-mini\"\n assert capabilities.context_window == 200_000\n assert not capabilities.supports_extended_thinking\n # Check temperature constraint is fixed at 1.0\n assert capabilities.temperature_constraint.value == 1.0\n\n def test_validate_model_names(self):\n \"\"\"Test model name validation\"\"\"\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n assert provider.validate_model_name(\"o3\")\n assert provider.validate_model_name(\"o3mini\")\n assert provider.validate_model_name(\"o3-mini\") # Backwards compatibility\n assert provider.validate_model_name(\"o4-mini\")\n assert provider.validate_model_name(\"o4mini\")\n assert provider.validate_model_name(\"o4-mini\")\n assert provider.validate_model_name(\"gpt-5.2\")\n assert provider.validate_model_name(\"gpt-5.1-codex\")\n assert provider.validate_model_name(\"gpt-5.1-codex-mini\")\n assert not provider.validate_model_name(\"gpt-4o\")\n assert not provider.validate_model_name(\"invalid-model\")\n\n def test_openai_models_do_not_support_extended_thinking(self):\n \"\"\"OpenAI catalogue exposes extended thinking capability via ModelCapabilities.\"\"\"\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n aliases = [\"o3\", \"o3mini\", \"o3-mini\", \"o4-mini\", \"o4mini\"]\n for alias in aliases:\n assert not provider.get_capabilities(alias).supports_extended_thinking\n\n def test_gpt52_family_capabilities(self):\n \"\"\"Ensure GPT-5.2 base model exposes correct capability flags.\"\"\"\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n base = provider.get_capabilities(\"gpt-5.2\")\n assert base.supports_streaming\n assert base.allow_code_generation\n\n codex = provider.get_capabilities(\"gpt-5.1-codex\")\n assert not codex.supports_streaming\n assert codex.use_openai_response_api\n assert codex.allow_code_generation\n\n codex_mini = provider.get_capabilities(\"gpt-5.1-codex-mini\")\n assert codex_mini.supports_streaming\n assert codex_mini.allow_code_generation\n" }, { "path": "tests/test_rate_limit_patterns.py", "content": "\"\"\"\nTest to verify structured error code-based retry logic.\n\"\"\"\n\nfrom providers.gemini import GeminiModelProvider\nfrom providers.openai import OpenAIModelProvider\n\n\ndef test_openai_structured_error_retry_logic():\n \"\"\"Test OpenAI provider's structured error code retry logic.\"\"\"\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Test structured token-related 429 error (should NOT be retried)\n class MockTokenError(Exception):\n def __init__(self):\n # Simulate the actual error format from OpenAI API\n self.args = (\n \"Error code: 429 - {'error': {'message': 'Request too large for o3', 'type': 'tokens', 'code': 'rate_limit_exceeded'}}\",\n )\n\n token_error = MockTokenError()\n assert not provider._is_error_retryable(token_error), \"Token-related 429 should not be retryable\"\n\n # Test standard rate limiting 429 error (should be retried)\n class MockRateLimitError(Exception):\n def __init__(self):\n self.args = (\n \"Error code: 429 - {'error': {'message': 'Too many requests', 'type': 'requests', 'code': 'rate_limit_exceeded'}}\",\n )\n\n rate_limit_error = MockRateLimitError()\n assert provider._is_error_retryable(rate_limit_error), \"Request rate limiting should be retryable\"\n\n # Test context length error (should NOT be retried)\n class MockContextError(Exception):\n def __init__(self):\n self.args = (\n \"Error code: 429 - {'error': {'message': 'Context length exceeded', 'code': 'context_length_exceeded'}}\",\n )\n\n context_error = MockContextError()\n assert not provider._is_error_retryable(context_error), \"Context length errors should not be retryable\"\n\n\ndef test_gemini_structured_error_retry_logic():\n \"\"\"Test Gemini provider's structured error code retry logic.\"\"\"\n provider = GeminiModelProvider(api_key=\"test-key\")\n\n # Test quota exceeded error (should NOT be retried)\n class MockQuotaError(Exception):\n def __init__(self):\n self.args = (\"429 Resource exhausted: Quota exceeded for model\",)\n self.details = \"quota_exceeded\"\n\n quota_error = MockQuotaError()\n assert not provider._is_error_retryable(quota_error), \"Quota exceeded should not be retryable\"\n\n # Test resource exhausted error (should NOT be retried)\n class MockResourceError(Exception):\n def __init__(self):\n self.args = (\"429 Resource exhausted: Token limit exceeded\",)\n\n resource_error = MockResourceError()\n assert not provider._is_error_retryable(resource_error), \"Resource exhausted should not be retryable\"\n\n # Test temporary rate limiting (should be retried)\n class MockTempError(Exception):\n def __init__(self):\n self.args = (\"429 Too many requests, please try again later\",)\n\n temp_error = MockTempError()\n assert provider._is_error_retryable(temp_error), \"Temporary rate limiting should be retryable\"\n\n\ndef test_actual_log_error_from_issue_with_structured_parsing():\n \"\"\"Test the specific error from the user's log using structured parsing.\"\"\"\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Create the exact error from the user's log\n class MockUserLogError(Exception):\n def __init__(self):\n # This is the exact error message from the user's issue\n self.args = (\n \"Error code: 429 - {'error': {'message': 'Request too large for o3 in organization org-MWp466of2XGyS90J8huQk4R6 on tokens per min (TPM): Limit 30000, Requested 31756. The input or output tokens must be reduced in order to run successfully. Visit https://platform.openai.com/account/rate-limits to learn more.', 'type': 'tokens', 'param': None, 'code': 'rate_limit_exceeded'}}\",\n )\n\n user_error = MockUserLogError()\n\n # This specific error should NOT be retryable because it has type='tokens'\n assert not provider._is_error_retryable(user_error), \"The user's specific error should be non-retryable\"\n\n\ndef test_non_429_errors_still_work():\n \"\"\"Test that non-429 errors are still handled correctly.\"\"\"\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Test retryable non-429 errors\n class MockTimeoutError(Exception):\n def __init__(self):\n self.args = (\"Connection timeout\",)\n\n timeout_error = MockTimeoutError()\n assert provider._is_error_retryable(timeout_error), \"Timeout errors should be retryable\"\n\n class Mock500Error(Exception):\n def __init__(self):\n self.args = (\"500 Internal Server Error\",)\n\n server_error = Mock500Error()\n assert provider._is_error_retryable(server_error), \"500 errors should be retryable\"\n\n # Test non-retryable non-429 errors\n class MockAuthError(Exception):\n def __init__(self):\n self.args = (\"401 Unauthorized\",)\n\n auth_error = MockAuthError()\n assert not provider._is_error_retryable(auth_error), \"Auth errors should not be retryable\"\n\n\ndef test_edge_cases_and_fallbacks():\n \"\"\"Test edge cases and fallback behavior.\"\"\"\n provider = OpenAIModelProvider(api_key=\"test-key\")\n\n # Test malformed JSON in error (should fall back gracefully)\n class MockMalformedError(Exception):\n def __init__(self):\n self.args = (\"Error code: 429 - {invalid json}\",)\n\n malformed_error = MockMalformedError()\n # Should still be retryable since it's a 429 without clear non-retryable indicators\n assert provider._is_error_retryable(malformed_error), \"Malformed 429 errors should default to retryable\"\n\n # Test 429 without structured data (should be retryable by default)\n class MockSimple429Error(Exception):\n def __init__(self):\n self.args = (\"429 Too Many Requests\",)\n\n simple_429_error = MockSimple429Error()\n assert provider._is_error_retryable(simple_429_error), \"Simple 429 without type info should be retryable\"\n" }, { "path": "tests/test_refactor.py", "content": "\"\"\"\nTests for the refactor tool functionality\n\"\"\"\n\nimport json\n\nimport pytest\n\nfrom tools.refactor import RefactorTool\nfrom utils.file_utils import read_file_content\n\n\nclass TestRefactorTool:\n \"\"\"Test suite for the refactor tool\"\"\"\n\n @pytest.fixture\n def refactor_tool(self):\n \"\"\"Create a refactor tool instance for testing\"\"\"\n return RefactorTool()\n\n @pytest.fixture\n def mock_model_response(self):\n \"\"\"Create a mock model response with valid JSON\"\"\"\n\n def _create_response(content=None):\n if content is None:\n content = json.dumps(\n {\n \"refactor_opportunities\": [\n {\n \"id\": \"refactor-001\",\n \"type\": \"codesmells\",\n \"severity\": \"high\",\n \"file\": \"/test/file.py\",\n \"start_line\": 10,\n \"end_line\": 25,\n \"context_start_text\": \"def long_method():\",\n \"context_end_text\": \" return result\",\n \"issue\": \"Method too long with multiple responsibilities\",\n \"suggestion\": \"Extract helper methods\",\n \"rationale\": \"Improves readability and maintainability\",\n \"code_to_replace\": \"# original code\",\n \"replacement_code_snippet\": \"# refactored code\",\n \"new_code_snippets\": [],\n }\n ],\n \"priority_sequence\": [\"refactor-001\"],\n \"next_actions\": [],\n },\n ensure_ascii=False,\n )\n\n from unittest.mock import Mock\n\n return Mock(\n content=content,\n usage={\"input_tokens\": 100, \"output_tokens\": 200, \"total_tokens\": 300},\n model_name=\"test-model\",\n metadata={\"finish_reason\": \"STOP\"},\n )\n\n return _create_response\n\n def test_get_name(self, refactor_tool):\n \"\"\"Test that the tool returns the correct name\"\"\"\n assert refactor_tool.get_name() == \"refactor\"\n\n def test_get_description(self, refactor_tool):\n \"\"\"Test that the tool returns a comprehensive description\"\"\"\n description = refactor_tool.get_description()\n assert \"refactoring\" in description\n assert \"code smell detection\" in description\n assert \"decomposition planning\" in description\n assert \"modernization\" in description\n assert \"maintainability improvements\" in description\n\n def test_get_input_schema(self, refactor_tool):\n \"\"\"Test that the input schema includes all required workflow fields\"\"\"\n schema = refactor_tool.get_input_schema()\n\n assert schema[\"type\"] == \"object\"\n\n # Check workflow-specific fields\n assert \"step\" in schema[\"properties\"]\n assert \"step_number\" in schema[\"properties\"]\n assert \"total_steps\" in schema[\"properties\"]\n assert \"next_step_required\" in schema[\"properties\"]\n assert \"findings\" in schema[\"properties\"]\n assert \"files_checked\" in schema[\"properties\"]\n assert \"relevant_files\" in schema[\"properties\"]\n\n # Check refactor-specific fields\n assert \"refactor_type\" in schema[\"properties\"]\n assert \"confidence\" in schema[\"properties\"]\n\n # Check refactor_type enum values\n refactor_enum = schema[\"properties\"][\"refactor_type\"][\"enum\"]\n expected_types = [\"codesmells\", \"decompose\", \"modernize\", \"organization\"]\n assert all(rt in refactor_enum for rt in expected_types)\n\n # Note: Old language detection and execution tests removed -\n # new workflow-based refactor tool has different architecture\n\n def test_model_category(self, refactor_tool):\n \"\"\"Test that the refactor tool uses EXTENDED_REASONING category\"\"\"\n from tools.models import ToolModelCategory\n\n category = refactor_tool.get_model_category()\n assert category == ToolModelCategory.EXTENDED_REASONING\n\n def test_default_temperature(self, refactor_tool):\n \"\"\"Test that the refactor tool uses analytical temperature\"\"\"\n from config import TEMPERATURE_ANALYTICAL\n\n temp = refactor_tool.get_default_temperature()\n assert temp == TEMPERATURE_ANALYTICAL\n\n # Note: format_response tests removed - workflow tools use different response format\n\n\nclass TestFileUtilsLineNumbers:\n \"\"\"Test suite for line numbering functionality in file_utils\"\"\"\n\n def test_read_file_content_with_line_numbers(self, project_path):\n \"\"\"Test reading file content with line numbers enabled\"\"\"\n\n # Create a test file within the workspace\n temp_path = project_path / \"test_file.py\"\n with open(temp_path, \"w\") as f:\n f.write(\"def hello():\\n print('Hello')\\n return True\")\n\n # Read with line numbers explicitly enabled\n content, tokens = read_file_content(str(temp_path), include_line_numbers=True)\n\n # Check that line numbers are present\n assert \"1β”‚ def hello():\" in content\n assert \"2β”‚ print('Hello')\" in content\n assert \"3β”‚ return True\" in content\n assert \"--- BEGIN FILE:\" in content\n assert \"--- END FILE:\" in content\n\n def test_read_file_content_without_line_numbers(self, project_path):\n \"\"\"Test reading file content with line numbers disabled\"\"\"\n\n # Create a test file within the workspace\n temp_path = project_path / \"test_file.txt\"\n with open(temp_path, \"w\") as f:\n f.write(\"Line 1\\nLine 2\\nLine 3\")\n\n # Read with line numbers explicitly disabled\n content, tokens = read_file_content(str(temp_path), include_line_numbers=False)\n\n # Check that line numbers are NOT present\n assert \"1β”‚\" not in content\n assert \"Line 1\" in content\n assert \"Line 2\" in content\n assert \"--- BEGIN FILE:\" in content\n\n def test_read_file_content_auto_detect_programming(self, project_path):\n \"\"\"Test that auto-detection is OFF by default (backwards compatibility)\"\"\"\n\n # Create a test file within the workspace\n temp_path = project_path / \"test_auto.py\"\n with open(temp_path, \"w\") as f:\n f.write(\"import os\\nprint('test')\")\n\n # Read without specifying line numbers (should NOT auto-detect for backwards compatibility)\n content, tokens = read_file_content(str(temp_path))\n\n # Should NOT automatically add line numbers for .py files (default behavior)\n assert \"1β”‚\" not in content\n assert \"import os\" in content\n assert \"print('test')\" in content\n\n def test_read_file_content_auto_detect_text(self, project_path):\n \"\"\"Test auto-detection of line numbers for text files\"\"\"\n\n # Create a test file within the workspace\n temp_path = project_path / \"test_auto.txt\"\n with open(temp_path, \"w\") as f:\n f.write(\"This is a text file\\nWith multiple lines\")\n\n # Read without specifying line numbers (should auto-detect)\n content, tokens = read_file_content(str(temp_path))\n\n # Should NOT automatically add line numbers for .txt files\n assert \"1β”‚\" not in content\n assert \"This is a text file\" in content\n\n def test_line_ending_normalization(self):\n \"\"\"Test that different line endings are normalized consistently\"\"\"\n from utils.file_utils import _add_line_numbers, _normalize_line_endings\n\n # Test different line ending formats\n content_crlf = \"Line 1\\r\\nLine 2\\r\\nLine 3\"\n content_cr = \"Line 1\\rLine 2\\rLine 3\"\n content_lf = \"Line 1\\nLine 2\\nLine 3\"\n\n # All should normalize to the same result\n normalized_crlf = _normalize_line_endings(content_crlf)\n normalized_cr = _normalize_line_endings(content_cr)\n normalized_lf = _normalize_line_endings(content_lf)\n\n assert normalized_crlf == normalized_cr == normalized_lf\n assert normalized_lf == \"Line 1\\nLine 2\\nLine 3\"\n\n # Line numbering should work consistently\n numbered = _add_line_numbers(content_crlf)\n assert \" 1β”‚ Line 1\" in numbered\n assert \" 2β”‚ Line 2\" in numbered\n assert \" 3β”‚ Line 3\" in numbered\n\n def test_detect_file_type(self):\n \"\"\"Test file type detection\"\"\"\n from utils.file_utils import detect_file_type\n\n # Test programming language files\n assert detect_file_type(\"test.py\") == \"text\"\n assert detect_file_type(\"test.js\") == \"text\"\n assert detect_file_type(\"test.java\") == \"text\"\n\n # Test image files\n assert detect_file_type(\"image.png\") == \"image\"\n assert detect_file_type(\"photo.jpg\") == \"image\"\n\n # Test binary files\n assert detect_file_type(\"program.exe\") == \"binary\"\n assert detect_file_type(\"library.dll\") == \"binary\"\n\n def test_should_add_line_numbers(self):\n \"\"\"Test line number detection logic\"\"\"\n from utils.file_utils import should_add_line_numbers\n\n # NO files should get line numbers by default (backwards compatibility)\n assert not should_add_line_numbers(\"test.py\")\n assert not should_add_line_numbers(\"app.js\")\n assert not should_add_line_numbers(\"Main.java\")\n assert not should_add_line_numbers(\"readme.txt\")\n assert not should_add_line_numbers(\"data.csv\")\n\n # Explicit override should work\n assert should_add_line_numbers(\"readme.txt\", True)\n assert not should_add_line_numbers(\"test.py\", False)\n\n def test_line_numbers_double_triple_digits(self, project_path):\n \"\"\"Test line numbering with double and triple digit line numbers\"\"\"\n from utils.file_utils import _add_line_numbers\n\n # Create content with many lines to test double and triple digit formatting\n lines = []\n for i in range(1, 125): # Lines 1-124 for testing up to triple digits\n if i < 10:\n lines.append(f\"# Single digit line {i}\")\n elif i < 100:\n lines.append(f\"# Double digit line {i}\")\n else:\n lines.append(f\"# Triple digit line {i}\")\n\n content = \"\\n\".join(lines)\n numbered_content = _add_line_numbers(content)\n\n # Test single digit formatting (should be right-aligned with spaces)\n assert \" 1β”‚ # Single digit line 1\" in numbered_content\n assert \" 9β”‚ # Single digit line 9\" in numbered_content\n\n # Test double digit formatting (should be right-aligned)\n assert \" 10β”‚ # Double digit line 10\" in numbered_content # Line 10 has \"double digit\" content\n assert \" 50β”‚ # Double digit line 50\" in numbered_content\n assert \" 99β”‚ # Double digit line 99\" in numbered_content\n\n # Test triple digit formatting (should be right-aligned)\n assert \" 100β”‚ # Triple digit line 100\" in numbered_content\n assert \" 124β”‚ # Triple digit line 124\" in numbered_content\n\n # Verify consistent alignment - all line numbers should end with \"β”‚ \"\n lines_with_numbers = numbered_content.split(\"\\n\")\n for line in lines_with_numbers:\n if \"β”‚\" in line:\n # Find the pipe character position\n pipe_pos = line.find(\"β”‚\")\n # Ensure the character before pipe is a digit\n assert line[pipe_pos - 1].isdigit(), f\"Line format issue: {line}\"\n # Ensure the character after pipe is a space\n assert line[pipe_pos + 1] == \" \", f\"Line format issue: {line}\"\n\n def test_line_numbers_with_file_reading(self, project_path):\n \"\"\"Test line numbering through file reading with large file\"\"\"\n\n # Create a test file with 150 functions (600 total lines: 4 lines per function)\n temp_path = project_path / \"large_test_file.py\"\n with open(temp_path, \"w\") as f:\n for i in range(1, 151): # Functions 1-150\n f.write(f\"def function_{i}():\\n\")\n f.write(f\" # This is function number {i}\\n\")\n f.write(f\" return {i}\\n\")\n f.write(\"\\n\")\n\n # Read with line numbers enabled\n content, tokens = read_file_content(str(temp_path), include_line_numbers=True)\n\n # Calculate actual line numbers based on file structure (4 lines per function)\n # Function 1: lines 1-4, Function 2: lines 5-8, etc.\n # Line 1: def function_1():\n # Line 2: # This is function number 1\n # Line 3: return 1\n # Line 4: (empty)\n\n # Test various line number formats in the actual file content\n assert \" 1β”‚ def function_1():\" in content\n\n # Function 13 starts at line 49 (12*4 + 1), so line 50 is \" # This is function number 13\"\n assert \" 50β”‚ # This is function number 13\" in content\n\n # Line 100 is actually an empty line after function 25 (line 99 was \"return 25\")\n assert \" 100β”‚ \" in content # Empty line\n\n # Line 99 is \"return 25\" from function 25\n assert \" 99β”‚ return 25\" in content\n\n # Test more line numbers - line 147 is \"return 37\" from function 37\n assert \" 147β”‚ return 37\" in content\n\n # Test that we have the final lines (600 total lines)\n assert \" 599β”‚ return 150\" in content\n assert \" 600β”‚ \" in content # Final empty line\n\n # Verify the file structure is preserved\n assert \"--- BEGIN FILE:\" in content\n assert \"--- END FILE:\" in content\n assert str(temp_path) in content\n\n def test_line_numbers_large_files_22k_lines(self, project_path):\n \"\"\"Test line numbering for very large files (22,500+ lines)\"\"\"\n from utils.file_utils import _add_line_numbers\n\n # Create content simulating a very large file with 25,000 lines\n lines = []\n for i in range(1, 25001): # Lines 1-25000\n lines.append(f\"// Large file line {i}\")\n\n content = \"\\n\".join(lines)\n numbered_content = _add_line_numbers(content)\n\n # Test that width dynamically adjusts to 5 digits for large files\n # Small line numbers should now have 5-digit width\n assert \" 1β”‚ // Large file line 1\" in numbered_content\n assert \" 9β”‚ // Large file line 9\" in numbered_content\n assert \" 10β”‚ // Large file line 10\" in numbered_content\n assert \" 99β”‚ // Large file line 99\" in numbered_content\n assert \" 100β”‚ // Large file line 100\" in numbered_content\n assert \" 999β”‚ // Large file line 999\" in numbered_content\n assert \" 1000β”‚ // Large file line 1000\" in numbered_content\n assert \" 9999β”‚ // Large file line 9999\" in numbered_content\n assert \"10000β”‚ // Large file line 10000\" in numbered_content\n assert \"22500β”‚ // Large file line 22500\" in numbered_content\n assert \"25000β”‚ // Large file line 25000\" in numbered_content\n\n # Verify consistent alignment - all line numbers should end with \"β”‚ \"\n lines_with_numbers = numbered_content.split(\"\\n\")\n for i, line in enumerate(lines_with_numbers[:100]): # Check first 100 lines\n if \"β”‚\" in line:\n pipe_pos = line.find(\"β”‚\")\n # For large files, should be 5-character width plus pipe\n assert line[pipe_pos - 1].isdigit(), f\"Line {i+1} format issue: {line}\"\n assert line[pipe_pos + 1] == \" \", f\"Line {i+1} format issue: {line}\"\n\n def test_line_numbers_boundary_conditions(self):\n \"\"\"Test line numbering at boundary conditions (9999 vs 10000 lines)\"\"\"\n from utils.file_utils import _add_line_numbers\n\n # Test exactly 9999 lines (should use 4-digit width)\n lines_9999 = [f\"Line {i}\" for i in range(1, 10000)] # 9999 lines\n content_9999 = \"\\n\".join(lines_9999)\n numbered_9999 = _add_line_numbers(content_9999)\n\n # Should use 4-digit format\n assert \" 1β”‚ Line 1\" in numbered_9999\n assert \"9999β”‚ Line 9999\" in numbered_9999\n\n # Test exactly 10000 lines (should use 5-digit width)\n lines_10000 = [f\"Line {i}\" for i in range(1, 10001)] # 10000 lines\n content_10000 = \"\\n\".join(lines_10000)\n numbered_10000 = _add_line_numbers(content_10000)\n\n # Should use 5-digit format\n assert \" 1β”‚ Line 1\" in numbered_10000\n assert \"10000β”‚ Line 10000\" in numbered_10000\n\n\nif __name__ == \"__main__\":\n pytest.main([__file__, \"-v\"])\n" }, { "path": "tests/test_secaudit.py", "content": "\"\"\"\nTests for the secaudit tool using WorkflowTool architecture.\n\"\"\"\n\nimport pytest\n\nfrom tools.models import ToolModelCategory\nfrom tools.secaudit import SecauditRequest, SecauditTool\n\n\nclass TestSecauditTool:\n \"\"\"Test suite for SecauditTool using WorkflowTool architecture.\"\"\"\n\n def test_tool_metadata(self):\n \"\"\"Test basic tool metadata and configuration.\"\"\"\n tool = SecauditTool()\n\n assert tool.get_name() == \"secaudit\"\n assert \"security audit\" in tool.get_description()\n assert tool.get_default_temperature() == 1.0 # TEMPERATURE_ANALYTICAL\n assert tool.get_model_category() == ToolModelCategory.EXTENDED_REASONING\n assert tool.requires_model() is True\n\n def test_request_validation(self):\n \"\"\"Test Pydantic request model validation.\"\"\"\n # Valid security audit step request\n step_request = SecauditRequest(\n step=\"Beginning comprehensive security audit of web application\",\n step_number=1,\n total_steps=6,\n next_step_required=True,\n findings=\"Identified React/Node.js e-commerce application with payment processing\",\n files_checked=[\"/src/auth.py\", \"/src/payment.py\"],\n relevant_files=[\"/src/auth.py\", \"/src/payment.py\"],\n relevant_context=[\"AuthController.login\", \"PaymentService.process\"],\n security_scope=\"Web application - e-commerce platform\",\n threat_level=\"high\",\n compliance_requirements=[\"PCI DSS\", \"SOC2\"],\n audit_focus=\"comprehensive\",\n confidence=\"medium\",\n )\n\n assert step_request.step_number == 1\n assert step_request.threat_level == \"high\"\n assert step_request.compliance_requirements == [\"PCI DSS\", \"SOC2\"]\n assert step_request.audit_focus == \"comprehensive\"\n assert len(step_request.relevant_context) == 2\n\n def test_request_validation_defaults(self):\n \"\"\"Test default values for optional fields.\"\"\"\n minimal_request = SecauditRequest(\n step=\"Security audit step\",\n step_number=1,\n total_steps=4,\n next_step_required=True,\n findings=\"Initial findings\",\n )\n\n assert minimal_request.threat_level == \"medium\" # Default value\n assert minimal_request.audit_focus == \"comprehensive\" # Default value\n assert minimal_request.confidence == \"low\" # Default value\n assert minimal_request.compliance_requirements == [] # Default empty list\n\n def test_request_validation_invalid_threat_level(self):\n \"\"\"Test validation with invalid threat level.\"\"\"\n with pytest.raises(ValueError):\n SecauditRequest(\n step=\"Security audit step\",\n step_number=1,\n total_steps=4,\n next_step_required=True,\n findings=\"Initial findings\",\n threat_level=\"invalid\", # Should only accept low, medium, high, critical\n )\n\n def test_request_validation_invalid_audit_focus(self):\n \"\"\"Test validation with invalid audit focus.\"\"\"\n with pytest.raises(ValueError):\n SecauditRequest(\n step=\"Security audit step\",\n step_number=1,\n total_steps=4,\n next_step_required=True,\n findings=\"Initial findings\",\n audit_focus=\"invalid\", # Should only accept defined options\n )\n\n def test_input_schema_generation(self):\n \"\"\"Test that input schema is generated correctly.\"\"\"\n tool = SecauditTool()\n schema = tool.get_input_schema()\n\n # Verify required security audit fields are present\n assert \"step\" in schema[\"properties\"]\n assert \"step_number\" in schema[\"properties\"]\n assert \"total_steps\" in schema[\"properties\"]\n assert \"next_step_required\" in schema[\"properties\"]\n assert \"findings\" in schema[\"properties\"]\n\n # Verify security-specific fields\n assert \"security_scope\" in schema[\"properties\"]\n assert \"threat_level\" in schema[\"properties\"]\n assert \"compliance_requirements\" in schema[\"properties\"]\n assert \"audit_focus\" in schema[\"properties\"]\n\n # Verify field types\n assert schema[\"properties\"][\"threat_level\"][\"type\"] == \"string\"\n assert schema[\"properties\"][\"compliance_requirements\"][\"type\"] == \"array\"\n\n def test_step_guidance_step_1(self):\n \"\"\"Test step-specific guidance for step 1 (Security Scope Analysis).\"\"\"\n tool = SecauditTool()\n request = SecauditRequest(\n step=\"Begin security audit\",\n step_number=1,\n total_steps=6,\n next_step_required=True,\n findings=\"Starting security assessment\",\n )\n\n actions = tool.get_required_actions(\n request.step_number, request.confidence, request.findings, request.total_steps\n )\n\n assert len(actions) == 4\n assert \"Identify application type, technology stack, and security scope\" in actions\n assert \"Map attack surface, entry points, and data flows\" in actions\n assert \"Determine relevant security standards and compliance requirements\" in actions\n assert \"Establish threat landscape and risk context for the application\" in actions\n\n def test_step_guidance_step_2(self):\n \"\"\"Test step-specific guidance for step 2 (Authentication Assessment).\"\"\"\n tool = SecauditTool()\n request = SecauditRequest(\n step=\"Analyze authentication\",\n step_number=2,\n total_steps=6,\n next_step_required=True,\n findings=\"Authentication analysis\",\n )\n\n actions = tool.get_required_actions(\n request.step_number, request.confidence, request.findings, request.total_steps\n )\n\n assert len(actions) == 4\n assert \"Analyze authentication mechanisms and session management\" in actions\n assert \"Check authorization controls, access patterns, and privilege escalation risks\" in actions\n assert \"Assess multi-factor authentication, password policies, and account security\" in actions\n assert \"Review identity and access management implementations\" in actions\n\n def test_step_guidance_step_4(self):\n \"\"\"Test step-specific guidance for step 4 (OWASP Top 10 Review).\"\"\"\n tool = SecauditTool()\n request = SecauditRequest(\n step=\"OWASP Top 10 review\", step_number=4, total_steps=6, next_step_required=True, findings=\"OWASP analysis\"\n )\n\n actions = tool.get_required_actions(\n request.step_number, request.confidence, request.findings, request.total_steps\n )\n\n assert len(actions) == 4\n assert \"Conduct OWASP Top 10 (2021) systematic review across all categories\" in actions\n assert \"Check each OWASP category methodically with specific findings and evidence\" in actions\n assert \"Cross-reference findings with application context and technology stack\" in actions\n assert \"Prioritize vulnerabilities based on exploitability and business impact\" in actions\n\n def test_expert_analysis_trigger(self):\n \"\"\"Test when expert analysis should be triggered.\"\"\"\n tool = SecauditTool()\n\n # Create a mock consolidated findings object\n class MockConsolidatedFindings:\n def __init__(self, relevant_files=None, findings=None, issues_found=None):\n self.relevant_files = relevant_files or []\n self.findings = findings or []\n self.issues_found = issues_found or []\n\n # Should trigger expert analysis when we have meaningful findings\n findings_with_files = MockConsolidatedFindings(\n relevant_files=[\"/src/auth.py\", \"/src/payment.py\"],\n findings=[\"Finding 1\", \"Finding 2\"],\n issues_found=[{\"severity\": \"high\", \"description\": \"SQL injection\"}],\n )\n assert tool.should_call_expert_analysis(findings_with_files) is True\n\n # Should trigger with just findings\n findings_only = MockConsolidatedFindings(findings=[\"Finding 1\", \"Finding 2\"])\n assert tool.should_call_expert_analysis(findings_only) is True\n\n # Should trigger with just issues\n issues_only = MockConsolidatedFindings(issues_found=[{\"severity\": \"high\", \"description\": \"SQL injection\"}])\n assert tool.should_call_expert_analysis(issues_only) is True\n\n # Should not trigger with no meaningful data\n no_findings = MockConsolidatedFindings()\n assert tool.should_call_expert_analysis(no_findings) is False\n\n def test_expert_analysis_context_preparation(self):\n \"\"\"Test expert analysis context preparation.\"\"\"\n tool = SecauditTool()\n\n # Create a mock consolidated findings object\n class MockConsolidatedFindings:\n def __init__(self):\n self.hypotheses = []\n self.files_checked = [\"/app/auth.py\", \"/app/payment.py\", \"/app/api.py\", \"/app/db.py\"]\n self.relevant_files = [\"/app/auth.py\", \"/app/payment.py\", \"/app/api.py\"]\n self.relevant_context = [\"AuthController.login\", \"PaymentService.process\", \"APIController.validate\"]\n self.issues_found = [\n {\"severity\": \"critical\", \"description\": \"SQL injection vulnerability in login endpoint\"},\n {\"severity\": \"high\", \"description\": \"Missing input validation in payment processing\"},\n {\"severity\": \"medium\", \"description\": \"Weak session management configuration\"},\n ]\n self.findings = [\n \"Step 1: Identified e-commerce web application with payment processing\",\n \"Step 2: Found authentication vulnerabilities\",\n \"Step 3: Discovered input validation issues\",\n ]\n self.hypotheses = [\n {\"step\": 1, \"confidence\": \"low\", \"hypothesis\": \"Initial security assessment\"},\n {\"step\": 2, \"confidence\": \"medium\", \"hypothesis\": \"Authentication issues confirmed\"},\n {\"step\": 3, \"confidence\": \"high\", \"hypothesis\": \"Multiple security vulnerabilities identified\"},\n ]\n self.images = []\n\n # Set initial request to provide context\n tool.initial_request = \"Perform security audit of e-commerce web application\"\n tool.security_config = {\n \"security_scope\": \"Web application - e-commerce platform with payment processing\",\n \"threat_level\": \"high\",\n \"compliance_requirements\": [\"PCI DSS\", \"SOC2\", \"GDPR\"],\n \"audit_focus\": \"comprehensive\",\n \"severity_filter\": \"all\",\n }\n\n consolidated_findings = MockConsolidatedFindings()\n context = tool.prepare_expert_analysis_context(consolidated_findings)\n\n # Verify context contains all security-specific information\n assert \"SECURITY AUDIT REQUEST\" in context\n assert \"Perform security audit of e-commerce web application\" in context\n assert \"SECURITY CONFIGURATION\" in context\n assert \"security_scope: Web application - e-commerce platform with payment processing\" in context\n assert \"threat_level: high\" in context\n assert \"compliance_requirements: ['PCI DSS', 'SOC2', 'GDPR']\" in context\n assert \"/app/auth.py\" in context\n assert \"AuthController.login\" in context\n assert \"CRITICAL SEVERITY:\" in context\n assert \"SQL injection vulnerability\" in context\n assert \"HIGH SEVERITY:\" in context\n assert \"Missing input validation\" in context\n\n def test_security_issues_formatting_empty(self):\n \"\"\"Test security issues formatting with no issues.\"\"\"\n tool = SecauditTool()\n formatted = tool._format_security_issues([])\n assert \"No security issues identified during systematic investigation.\" in formatted\n\n def test_security_issues_formatting_with_issues(self):\n \"\"\"Test security issues formatting with multiple severity levels.\"\"\"\n tool = SecauditTool()\n issues = [\n {\"severity\": \"critical\", \"description\": \"Remote code execution vulnerability\"},\n {\"severity\": \"high\", \"description\": \"Authentication bypass\"},\n {\"severity\": \"medium\", \"description\": \"Information disclosure\"},\n {\"severity\": \"low\", \"description\": \"Missing security headers\"},\n {\"severity\": \"unknown\", \"description\": \"Unclassified issue\"}, # Should go to low\n ]\n\n formatted = tool._format_security_issues(issues)\n\n assert \"CRITICAL SEVERITY:\" in formatted\n assert \"Remote code execution vulnerability\" in formatted\n assert \"HIGH SEVERITY:\" in formatted\n assert \"Authentication bypass\" in formatted\n assert \"MEDIUM SEVERITY:\" in formatted\n assert \"Information disclosure\" in formatted\n assert \"LOW SEVERITY:\" in formatted\n assert \"Missing security headers\" in formatted\n assert \"[UNKNOWN] Unclassified issue\" in formatted\n\n def test_tool_field_definitions(self):\n \"\"\"Test that all security-specific tool fields are properly defined.\"\"\"\n tool = SecauditTool()\n fields = tool.get_tool_fields()\n\n # Verify all expected fields are present\n expected_fields = [\n \"step\",\n \"step_number\",\n \"total_steps\",\n \"next_step_required\",\n \"findings\",\n \"files_checked\",\n \"relevant_files\",\n \"relevant_context\",\n \"issues_found\",\n \"confidence\",\n \"images\",\n \"security_scope\",\n \"threat_level\",\n \"compliance_requirements\",\n \"audit_focus\",\n \"severity_filter\",\n ]\n\n for field in expected_fields:\n assert field in fields, f\"Field '{field}' not found in tool field definitions\"\n\n # Verify field descriptions are comprehensive\n assert \"OWASP Top 10\" in fields[\"step\"]\n assert \"OWASP Top 10\" in fields[\"step\"]\n assert \"MANDATORY\" in fields[\"step\"]\n assert \"Security context\" in fields[\"security_scope\"]\n assert \"threat level\" in fields[\"threat_level\"]\n assert \"compliance frameworks\" in fields[\"compliance_requirements\"]\n\n def test_workflow_request_model(self):\n \"\"\"Test that the workflow request model is correctly configured.\"\"\"\n tool = SecauditTool()\n request_model = tool.get_workflow_request_model()\n assert request_model == SecauditRequest\n\n def test_workflow_system_prompt(self):\n \"\"\"Test that the workflow system prompt is correctly configured.\"\"\"\n tool = SecauditTool()\n system_prompt = tool.get_system_prompt()\n\n # Verify it contains key security audit elements\n assert \"OWASP Top 10\" in system_prompt\n assert \"security_analysis_complete\" in system_prompt\n assert \"vulnerability\" in system_prompt\n assert \"compliance_assessment\" in system_prompt\n\n def test_compliance_requirements_validation(self):\n \"\"\"Test compliance requirements validation in model validator.\"\"\"\n # Test with valid compliance requirements\n valid_request = SecauditRequest(\n step=\"Security audit with compliance\",\n step_number=1,\n total_steps=6,\n next_step_required=True,\n findings=\"Starting audit\",\n compliance_requirements=[\"SOC2\", \"PCI DSS\", \"HIPAA\"],\n )\n assert valid_request.compliance_requirements == [\"SOC2\", \"PCI DSS\", \"HIPAA\"]\n\n # Test with unknown compliance requirement (should warn but not fail)\n unknown_compliance_request = SecauditRequest(\n step=\"Security audit with unknown compliance\",\n step_number=1,\n total_steps=6,\n next_step_required=True,\n findings=\"Starting audit\",\n compliance_requirements=[\"UNKNOWN_COMPLIANCE\"],\n )\n # Should still create the request but log a warning\n assert unknown_compliance_request.compliance_requirements == [\"UNKNOWN_COMPLIANCE\"]\n\n def test_comprehensive_workflow_scenario(self):\n \"\"\"Test a complete workflow scenario from start to finish.\"\"\"\n tool = SecauditTool()\n\n # Step 1: Initial security scope analysis\n step1_request = SecauditRequest(\n step=\"Begin comprehensive security audit of e-commerce web application\",\n step_number=1,\n total_steps=6,\n next_step_required=True,\n findings=\"Identified Node.js/React application with payment processing and user management\",\n security_scope=\"Web application - e-commerce platform\",\n threat_level=\"high\",\n compliance_requirements=[\"PCI DSS\"],\n relevant_files=[\"/src/auth.js\", \"/src/payment.js\"],\n )\n\n step1_actions = tool.get_required_actions(\n step1_request.step_number, step1_request.confidence, step1_request.findings, step1_request.total_steps\n )\n assert \"Identify application type\" in step1_actions[0]\n\n # Test should_call_expert_analysis with mock consolidated findings\n class MockConsolidatedFindings:\n def __init__(self):\n self.hypotheses = []\n self.relevant_files = []\n self.findings = []\n self.issues_found = []\n\n mock_findings = MockConsolidatedFindings()\n assert not tool.should_call_expert_analysis(mock_findings)\n\n # Step 6: Final assessment\n step6_request = SecauditRequest(\n step=\"Complete security assessment and risk evaluation\",\n step_number=6,\n total_steps=6,\n next_step_required=False,\n findings=\"Comprehensive security audit completed with findings documented\",\n security_scope=\"Web application - e-commerce platform\",\n threat_level=\"high\",\n compliance_requirements=[\"PCI DSS\"],\n relevant_files=[\"/src/auth.js\", \"/src/payment.js\", \"/src/api.js\"],\n relevant_context=[\"AuthService.authenticate\", \"PaymentProcessor.charge\"],\n issues_found=[\n {\"severity\": \"high\", \"description\": \"SQL injection in user search\"},\n {\"severity\": \"medium\", \"description\": \"Weak password policy\"},\n ],\n confidence=\"high\",\n )\n\n step6_actions = tool.get_required_actions(\n step6_request.step_number, step6_request.confidence, step6_request.findings, step6_request.total_steps\n )\n assert \"Evaluate compliance requirements\" in step6_actions[0]\n\n # Create mock consolidated findings for final step\n final_findings = MockConsolidatedFindings()\n final_findings.relevant_files = step6_request.relevant_files\n final_findings.findings = [\"Comprehensive security audit completed with findings documented\"]\n final_findings.issues_found = step6_request.issues_found\n final_findings.relevant_context = []\n final_findings.images = []\n assert tool.should_call_expert_analysis(final_findings)\n\n # Test expert analysis context generation with mock consolidated findings\n # Set up tool state as it would be after processing\n tool.initial_request = \"Complete security assessment and risk evaluation\"\n tool.security_config = {\n \"security_scope\": step6_request.security_scope,\n \"threat_level\": step6_request.threat_level,\n \"compliance_requirements\": step6_request.compliance_requirements,\n \"audit_focus\": step6_request.audit_focus,\n \"severity_filter\": step6_request.severity_filter,\n }\n\n # Create a complete mock consolidated findings\n complete_findings = MockConsolidatedFindings()\n complete_findings.relevant_files = step6_request.relevant_files\n complete_findings.relevant_context = step6_request.relevant_context\n complete_findings.issues_found = step6_request.issues_found\n complete_findings.findings = [\"Security audit findings from all steps\"]\n complete_findings.files_checked = []\n complete_findings.images = []\n\n context = tool.prepare_expert_analysis_context(complete_findings)\n assert \"PCI DSS\" in context\n assert \"SQL injection\" in context\n assert \"HIGH SEVERITY:\" in context\n" }, { "path": "tests/test_server.py", "content": "\"\"\"\nTests for the main server functionality\n\"\"\"\n\nimport pytest\n\nfrom server import handle_call_tool\n\n\nclass TestServerTools:\n \"\"\"Test server tool handling\"\"\"\n\n @pytest.mark.asyncio\n async def test_handle_call_tool_unknown(self):\n \"\"\"Test calling an unknown tool\"\"\"\n result = await handle_call_tool(\"unknown_tool\", {})\n assert len(result) == 1\n assert \"Unknown tool: unknown_tool\" in result[0].text\n\n @pytest.mark.asyncio\n async def test_handle_chat(self):\n \"\"\"Test chat functionality using real integration testing\"\"\"\n import importlib\n import os\n\n # Set test environment\n os.environ[\"PYTEST_CURRENT_TEST\"] = \"test\"\n\n # Save original environment\n original_env = {\n \"OPENAI_API_KEY\": os.environ.get(\"OPENAI_API_KEY\"),\n \"DEFAULT_MODEL\": os.environ.get(\"DEFAULT_MODEL\"),\n }\n\n try:\n # Set up environment for real provider resolution\n os.environ[\"OPENAI_API_KEY\"] = \"sk-test-key-server-chat-test-not-real\"\n os.environ[\"DEFAULT_MODEL\"] = \"o3-mini\"\n\n # Clear other provider keys to isolate to OpenAI\n for key in [\"GEMINI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n import config\n\n importlib.reload(config)\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry._instance = None\n\n # Test with real provider resolution\n try:\n result = await handle_call_tool(\"chat\", {\"prompt\": \"Hello Gemini\", \"model\": \"o3-mini\"})\n\n # If we get here, check the response format\n assert len(result) == 1\n # Parse JSON response\n import json\n\n response_data = json.loads(result[0].text)\n assert \"status\" in response_data\n\n except Exception as e:\n # Expected: API call will fail with fake key\n error_msg = str(e)\n # Should NOT be a mock-related error\n assert \"MagicMock\" not in error_msg\n assert \"'<' not supported between instances\" not in error_msg\n\n # Should be a real provider error\n assert any(\n phrase in error_msg\n for phrase in [\"API\", \"key\", \"authentication\", \"provider\", \"network\", \"connection\"]\n )\n\n finally:\n # Restore environment\n for key, value in original_env.items():\n if value is not None:\n os.environ[key] = value\n else:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n importlib.reload(config)\n ModelProviderRegistry._instance = None\n\n @pytest.mark.asyncio\n async def test_handle_version(self):\n \"\"\"Test getting version info\"\"\"\n result = await handle_call_tool(\"version\", {})\n assert len(result) == 1\n\n response = result[0].text\n # Parse the JSON response\n import json\n\n data = json.loads(response)\n assert data[\"status\"] == \"success\"\n content = data[\"content\"]\n\n # Check for expected content in the markdown output\n assert \"# PAL MCP Server Version\" in content\n assert \"## Server Information\" in content\n assert \"## Configuration\" in content\n assert \"Current Version\" in content\n" }, { "path": "tests/test_supported_models_aliases.py", "content": "\"\"\"Test the MODEL_CAPABILITIES aliases structure across all providers.\"\"\"\n\nfrom providers.dial import DIALModelProvider\nfrom providers.gemini import GeminiModelProvider\nfrom providers.openai import OpenAIModelProvider\nfrom providers.xai import XAIModelProvider\n\n\nclass TestSupportedModelsAliases:\n \"\"\"Test that all providers have correctly structured MODEL_CAPABILITIES with aliases.\"\"\"\n\n def test_gemini_provider_aliases(self):\n \"\"\"Test Gemini provider's alias structure.\"\"\"\n provider = GeminiModelProvider(\"test-key\")\n\n # Check that all models have ModelCapabilities with aliases\n for model_name, config in provider.MODEL_CAPABILITIES.items():\n assert hasattr(config, \"aliases\"), f\"{model_name} must have aliases attribute\"\n assert isinstance(config.aliases, list), f\"{model_name} aliases must be a list\"\n\n # Test specific aliases\n assert \"flash\" in provider.MODEL_CAPABILITIES[\"gemini-2.5-flash\"].aliases\n assert \"pro\" in provider.MODEL_CAPABILITIES[\"gemini-3-pro-preview\"].aliases\n assert \"flash-2.0\" in provider.MODEL_CAPABILITIES[\"gemini-2.0-flash\"].aliases\n assert \"flash2\" in provider.MODEL_CAPABILITIES[\"gemini-2.0-flash\"].aliases\n assert \"flashlite\" in provider.MODEL_CAPABILITIES[\"gemini-2.0-flash-lite\"].aliases\n assert \"flash-lite\" in provider.MODEL_CAPABILITIES[\"gemini-2.0-flash-lite\"].aliases\n\n # Test alias resolution\n assert provider._resolve_model_name(\"flash\") == \"gemini-2.5-flash\"\n assert provider._resolve_model_name(\"pro\") == \"gemini-3-pro-preview\"\n assert provider._resolve_model_name(\"flash-2.0\") == \"gemini-2.0-flash\"\n assert provider._resolve_model_name(\"flash2\") == \"gemini-2.0-flash\"\n assert provider._resolve_model_name(\"flashlite\") == \"gemini-2.0-flash-lite\"\n\n # Test case insensitive resolution\n assert provider._resolve_model_name(\"Flash\") == \"gemini-2.5-flash\"\n assert provider._resolve_model_name(\"PRO\") == \"gemini-3-pro-preview\"\n\n def test_openai_provider_aliases(self):\n \"\"\"Test OpenAI provider's alias structure.\"\"\"\n provider = OpenAIModelProvider(\"test-key\")\n\n # Check that all models have ModelCapabilities with aliases\n for model_name, config in provider.MODEL_CAPABILITIES.items():\n assert hasattr(config, \"aliases\"), f\"{model_name} must have aliases attribute\"\n assert isinstance(config.aliases, list), f\"{model_name} aliases must be a list\"\n\n # Test specific aliases\n # \"mini\" is now an alias for gpt-5-mini, not o4-mini\n assert \"mini\" in provider.MODEL_CAPABILITIES[\"gpt-5-mini\"].aliases\n assert \"o4mini\" in provider.MODEL_CAPABILITIES[\"o4-mini\"].aliases\n # o4-mini is no longer in its own aliases (removed self-reference)\n assert \"o3mini\" in provider.MODEL_CAPABILITIES[\"o3-mini\"].aliases\n assert \"o3pro\" in provider.MODEL_CAPABILITIES[\"o3-pro\"].aliases\n assert \"gpt4.1\" in provider.MODEL_CAPABILITIES[\"gpt-4.1\"].aliases\n assert \"gpt5.2\" in provider.MODEL_CAPABILITIES[\"gpt-5.2\"].aliases\n assert \"gpt5.1-codex\" in provider.MODEL_CAPABILITIES[\"gpt-5.1-codex\"].aliases\n assert \"codex-mini\" in provider.MODEL_CAPABILITIES[\"gpt-5.1-codex-mini\"].aliases\n\n # Test alias resolution\n assert provider._resolve_model_name(\"mini\") == \"gpt-5-mini\" # mini -> gpt-5-mini now\n assert provider._resolve_model_name(\"o3mini\") == \"o3-mini\"\n assert provider._resolve_model_name(\"o3pro\") == \"o3-pro\" # o3pro resolves to o3-pro\n assert provider._resolve_model_name(\"o4mini\") == \"o4-mini\"\n assert provider._resolve_model_name(\"gpt4.1\") == \"gpt-4.1\" # gpt4.1 resolves to gpt-4.1\n assert provider._resolve_model_name(\"gpt5.2\") == \"gpt-5.2\"\n assert provider._resolve_model_name(\"gpt5.1\") == \"gpt-5.2\"\n assert provider._resolve_model_name(\"gpt5.1-codex\") == \"gpt-5.1-codex\"\n assert provider._resolve_model_name(\"codex-mini\") == \"gpt-5.1-codex-mini\"\n\n # Test case insensitive resolution\n assert provider._resolve_model_name(\"Mini\") == \"gpt-5-mini\" # mini -> gpt-5-mini now\n assert provider._resolve_model_name(\"O3MINI\") == \"o3-mini\"\n assert provider._resolve_model_name(\"Gpt5.1\") == \"gpt-5.2\"\n\n def test_xai_provider_aliases(self):\n \"\"\"Test XAI provider's alias structure.\"\"\"\n provider = XAIModelProvider(\"test-key\")\n\n # Check that all models have ModelCapabilities with aliases\n for model_name, config in provider.MODEL_CAPABILITIES.items():\n assert hasattr(config, \"aliases\"), f\"{model_name} must have aliases attribute\"\n assert isinstance(config.aliases, list), f\"{model_name} aliases must be a list\"\n\n # Test specific aliases\n assert \"grok\" in provider.MODEL_CAPABILITIES[\"grok-4\"].aliases\n assert \"grok4\" in provider.MODEL_CAPABILITIES[\"grok-4\"].aliases\n assert \"grok-4.1-fast-reasoning\" in provider.MODEL_CAPABILITIES[\"grok-4-1-fast-reasoning\"].aliases\n\n # Test alias resolution\n assert provider._resolve_model_name(\"grok\") == \"grok-4\"\n assert provider._resolve_model_name(\"grok4\") == \"grok-4\"\n assert provider._resolve_model_name(\"grok-4.1-fast-reasoning\") == \"grok-4-1-fast-reasoning\"\n assert provider._resolve_model_name(\"grok-4.1-fast-reasoning-latest\") == \"grok-4-1-fast-reasoning\"\n\n # Test case insensitive resolution\n assert provider._resolve_model_name(\"Grok\") == \"grok-4\"\n assert provider._resolve_model_name(\"GROK-4.1-FAST-REASONING\") == \"grok-4-1-fast-reasoning\"\n\n def test_dial_provider_aliases(self):\n \"\"\"Test DIAL provider's alias structure.\"\"\"\n provider = DIALModelProvider(\"test-key\")\n\n # Check that all models have ModelCapabilities with aliases\n for model_name, config in provider.MODEL_CAPABILITIES.items():\n assert hasattr(config, \"aliases\"), f\"{model_name} must have aliases attribute\"\n assert isinstance(config.aliases, list), f\"{model_name} aliases must be a list\"\n\n # Test specific aliases\n assert \"o3\" in provider.MODEL_CAPABILITIES[\"o3-2025-04-16\"].aliases\n assert \"o4-mini\" in provider.MODEL_CAPABILITIES[\"o4-mini-2025-04-16\"].aliases\n assert \"sonnet-4.1\" in provider.MODEL_CAPABILITIES[\"anthropic.claude-sonnet-4.1-20250805-v1:0\"].aliases\n assert \"opus-4.1\" in provider.MODEL_CAPABILITIES[\"anthropic.claude-opus-4.1-20250805-v1:0\"].aliases\n assert \"gemini-2.5-pro\" in provider.MODEL_CAPABILITIES[\"gemini-2.5-pro-preview-05-06\"].aliases\n\n # Test alias resolution\n assert provider._resolve_model_name(\"o3\") == \"o3-2025-04-16\"\n assert provider._resolve_model_name(\"o4-mini\") == \"o4-mini-2025-04-16\"\n assert provider._resolve_model_name(\"sonnet-4.1\") == \"anthropic.claude-sonnet-4.1-20250805-v1:0\"\n assert provider._resolve_model_name(\"opus-4.1\") == \"anthropic.claude-opus-4.1-20250805-v1:0\"\n\n # Test case insensitive resolution\n assert provider._resolve_model_name(\"O3\") == \"o3-2025-04-16\"\n assert provider._resolve_model_name(\"SONNET-4.1\") == \"anthropic.claude-sonnet-4.1-20250805-v1:0\"\n\n def test_list_models_includes_aliases(self):\n \"\"\"Test that list_models returns both base models and aliases.\"\"\"\n # Test Gemini\n gemini_provider = GeminiModelProvider(\"test-key\")\n gemini_models = gemini_provider.list_models(respect_restrictions=False)\n assert \"gemini-2.5-flash\" in gemini_models\n assert \"flash\" in gemini_models\n assert \"gemini-3-pro-preview\" in gemini_models\n assert \"pro\" in gemini_models\n\n # Test OpenAI\n openai_provider = OpenAIModelProvider(\"test-key\")\n openai_models = openai_provider.list_models(respect_restrictions=False)\n assert \"o4-mini\" in openai_models\n assert \"mini\" in openai_models\n assert \"o3-mini\" in openai_models\n assert \"o3mini\" in openai_models\n\n # Test XAI\n xai_provider = XAIModelProvider(\"test-key\")\n xai_models = xai_provider.list_models(respect_restrictions=False)\n assert \"grok-4\" in xai_models\n assert \"grok\" in xai_models\n assert \"grok-4.1-fast\" in xai_models\n assert \"grok-4.1-fast-reasoning\" in xai_models\n\n # Test DIAL\n dial_provider = DIALModelProvider(\"test-key\")\n dial_models = dial_provider.list_models(respect_restrictions=False)\n assert \"o3-2025-04-16\" in dial_models\n assert \"o3\" in dial_models\n\n def test_list_models_all_known_variant_includes_aliases(self):\n \"\"\"Unified list_models should support lowercase, alias-inclusive listings.\"\"\"\n # Test Gemini\n gemini_provider = GeminiModelProvider(\"test-key\")\n gemini_all = gemini_provider.list_models(\n respect_restrictions=False,\n include_aliases=True,\n lowercase=True,\n unique=True,\n )\n assert \"gemini-2.5-flash\" in gemini_all\n assert \"flash\" in gemini_all\n assert \"gemini-3-pro-preview\" in gemini_all\n assert \"pro\" in gemini_all\n # All should be lowercase\n assert all(model == model.lower() for model in gemini_all)\n\n # Test OpenAI\n openai_provider = OpenAIModelProvider(\"test-key\")\n openai_all = openai_provider.list_models(\n respect_restrictions=False,\n include_aliases=True,\n lowercase=True,\n unique=True,\n )\n assert \"o4-mini\" in openai_all\n assert \"mini\" in openai_all\n assert \"o3-mini\" in openai_all\n assert \"o3mini\" in openai_all\n # All should be lowercase\n assert all(model == model.lower() for model in openai_all)\n\n def test_no_string_shorthand_in_supported_models(self):\n \"\"\"Test that no provider has string-based shorthands anymore.\"\"\"\n providers = [\n GeminiModelProvider(\"test-key\"),\n OpenAIModelProvider(\"test-key\"),\n XAIModelProvider(\"test-key\"),\n DIALModelProvider(\"test-key\"),\n ]\n\n for provider in providers:\n for model_name, config in provider.MODEL_CAPABILITIES.items():\n # All values must be ModelCapabilities objects, not strings or dicts\n from providers.shared import ModelCapabilities\n\n assert isinstance(config, ModelCapabilities), (\n f\"{provider.__class__.__name__}.MODEL_CAPABILITIES['{model_name}'] \"\n f\"must be a ModelCapabilities object, not {type(config).__name__}\"\n )\n\n def test_resolve_returns_original_if_not_found(self):\n \"\"\"Test that _resolve_model_name returns original name if alias not found.\"\"\"\n providers = [\n GeminiModelProvider(\"test-key\"),\n OpenAIModelProvider(\"test-key\"),\n XAIModelProvider(\"test-key\"),\n DIALModelProvider(\"test-key\"),\n ]\n\n for provider in providers:\n # Test with unknown model name\n assert provider._resolve_model_name(\"unknown-model\") == \"unknown-model\"\n assert provider._resolve_model_name(\"gpt-4\") == \"gpt-4\"\n assert provider._resolve_model_name(\"claude-3\") == \"claude-3\"\n" }, { "path": "tests/test_thinking_modes.py", "content": "\"\"\"\nTests for thinking_mode functionality across all tools\n\"\"\"\n\nfrom unittest.mock import patch\n\nimport pytest\n\nfrom tools.analyze import AnalyzeTool\nfrom tools.codereview import CodeReviewTool\nfrom tools.debug import DebugIssueTool\nfrom tools.thinkdeep import ThinkDeepTool\n\n\n@pytest.fixture(autouse=True)\ndef setup_test_env():\n \"\"\"Set up test environment\"\"\"\n # PYTEST_CURRENT_TEST is already set by pytest\n yield\n\n\nclass TestThinkingModes:\n \"\"\"Test thinking modes across all tools\"\"\"\n\n @patch(\"config.DEFAULT_THINKING_MODE_THINKDEEP\", \"high\")\n def test_default_thinking_modes(self):\n \"\"\"Test that tools have correct default thinking modes\"\"\"\n tools = [\n (ThinkDeepTool(), \"high\"),\n (AnalyzeTool(), \"medium\"),\n (CodeReviewTool(), \"medium\"),\n (DebugIssueTool(), \"medium\"),\n ]\n\n for tool, expected_default in tools:\n assert (\n tool.get_default_thinking_mode() == expected_default\n ), f\"{tool.__class__.__name__} should default to {expected_default}\"\n\n @pytest.mark.asyncio\n async def test_thinking_mode_minimal(self):\n \"\"\"Test minimal thinking mode with real provider resolution\"\"\"\n import importlib\n import os\n\n # Save original environment\n original_env = {\n \"OPENAI_API_KEY\": os.environ.get(\"OPENAI_API_KEY\"),\n \"DEFAULT_MODEL\": os.environ.get(\"DEFAULT_MODEL\"),\n }\n\n try:\n # Set up environment for OpenAI provider (which supports thinking mode)\n os.environ[\"OPENAI_API_KEY\"] = \"sk-test-key-minimal-thinking-test-not-real\"\n os.environ[\"DEFAULT_MODEL\"] = \"o3-mini\" # Use a model that supports thinking\n\n # Clear other provider keys to isolate to OpenAI\n for key in [\"GEMINI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n import config\n\n importlib.reload(config)\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry._instance = None\n\n tool = AnalyzeTool()\n\n # This should attempt to use the real OpenAI provider\n # Even with a fake API key, we can test the provider resolution logic\n # The test will fail at the API call level, but we can verify the thinking mode logic\n try:\n result = await tool.execute(\n {\n \"absolute_file_paths\": [\"/absolute/path/test.py\"],\n \"prompt\": \"What is this?\",\n \"model\": \"o3-mini\",\n \"thinking_mode\": \"minimal\",\n }\n )\n # If we get here, great! The provider resolution worked\n # Check that thinking mode was properly handled\n assert result is not None\n\n except Exception as e:\n # Expected: API call will fail with fake key, but we can check the error\n # If we get a provider resolution error, that's what we're testing\n error_msg = getattr(e, \"payload\", str(e))\n # Should NOT be a mock-related error - should be a real API or key error\n assert \"MagicMock\" not in error_msg\n assert \"'<' not supported between instances\" not in error_msg\n\n # Should be a real provider error (API key, network, etc.)\n import json\n\n try:\n parsed = json.loads(error_msg)\n except Exception:\n parsed = None\n\n if isinstance(parsed, dict) and parsed.get(\"status\", \"\").endswith(\"_failed\"):\n assert \"validation errors\" in parsed.get(\"error\", \"\")\n else:\n assert any(\n phrase in error_msg\n for phrase in [\"API\", \"key\", \"authentication\", \"provider\", \"network\", \"connection\", \"Model\"]\n )\n\n finally:\n # Restore environment\n for key, value in original_env.items():\n if value is not None:\n os.environ[key] = value\n else:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n importlib.reload(config)\n ModelProviderRegistry._instance = None\n\n @pytest.mark.asyncio\n async def test_thinking_mode_low(self):\n \"\"\"Test low thinking mode with real provider resolution\"\"\"\n import importlib\n import os\n\n # Save original environment\n original_env = {\n \"OPENAI_API_KEY\": os.environ.get(\"OPENAI_API_KEY\"),\n \"DEFAULT_MODEL\": os.environ.get(\"DEFAULT_MODEL\"),\n }\n\n try:\n # Set up environment for OpenAI provider (which supports thinking mode)\n os.environ[\"OPENAI_API_KEY\"] = \"sk-test-key-low-thinking-test-not-real\"\n os.environ[\"DEFAULT_MODEL\"] = \"o3-mini\"\n\n # Clear other provider keys\n for key in [\"GEMINI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n import config\n\n importlib.reload(config)\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry._instance = None\n\n tool = CodeReviewTool()\n\n # Test with real provider resolution\n try:\n result = await tool.execute(\n {\n \"absolute_file_paths\": [\"/absolute/path/test.py\"],\n \"thinking_mode\": \"low\",\n \"prompt\": \"Test code review for validation purposes\",\n \"model\": \"o3-mini\",\n }\n )\n # If we get here, provider resolution worked\n assert result is not None\n\n except Exception as e:\n # Expected: API call will fail with fake key\n error_msg = getattr(e, \"payload\", str(e))\n # Should NOT be a mock-related error\n assert \"MagicMock\" not in error_msg\n assert \"'<' not supported between instances\" not in error_msg\n\n # Should be a real provider error\n import json\n\n try:\n parsed = json.loads(error_msg)\n except Exception:\n parsed = None\n\n if isinstance(parsed, dict) and parsed.get(\"status\", \"\").endswith(\"_failed\"):\n assert \"validation errors\" in parsed.get(\"error\", \"\")\n else:\n assert any(\n phrase in error_msg\n for phrase in [\"API\", \"key\", \"authentication\", \"provider\", \"network\", \"connection\", \"Model\"]\n )\n\n finally:\n # Restore environment\n for key, value in original_env.items():\n if value is not None:\n os.environ[key] = value\n else:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n importlib.reload(config)\n ModelProviderRegistry._instance = None\n\n @pytest.mark.asyncio\n async def test_thinking_mode_medium(self):\n \"\"\"Test medium thinking mode (default for most tools) using real integration testing\"\"\"\n import importlib\n import os\n\n # Save original environment\n original_env = {\n \"OPENAI_API_KEY\": os.environ.get(\"OPENAI_API_KEY\"),\n \"DEFAULT_MODEL\": os.environ.get(\"DEFAULT_MODEL\"),\n }\n\n try:\n # Set up environment for OpenAI provider (which supports thinking mode)\n os.environ[\"OPENAI_API_KEY\"] = \"sk-test-key-medium-thinking-test-not-real\"\n os.environ[\"DEFAULT_MODEL\"] = \"o3-mini\"\n\n # Clear other provider keys to isolate to OpenAI\n for key in [\"GEMINI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n import config\n\n importlib.reload(config)\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry._instance = None\n\n tool = DebugIssueTool()\n\n # Test with real provider resolution\n try:\n result = await tool.execute(\n {\n \"prompt\": \"Test error\",\n \"model\": \"o3-mini\",\n # Not specifying thinking_mode, should use default (medium)\n }\n )\n # If we get here, provider resolution worked\n assert result is not None\n # Should be a valid debug response\n assert len(result) == 1\n\n except Exception as e:\n # Expected: API call will fail with fake key\n error_msg = getattr(e, \"payload\", str(e))\n # Should NOT be a mock-related error\n assert \"MagicMock\" not in error_msg\n assert \"'<' not supported between instances\" not in error_msg\n\n # Should be a real provider error\n import json\n\n try:\n parsed = json.loads(error_msg)\n except Exception:\n parsed = None\n\n if isinstance(parsed, dict) and parsed.get(\"status\", \"\").endswith(\"_failed\"):\n assert \"validation errors\" in parsed.get(\"error\", \"\")\n else:\n assert any(\n phrase in error_msg\n for phrase in [\"API\", \"key\", \"authentication\", \"provider\", \"network\", \"connection\", \"Model\"]\n )\n\n finally:\n # Restore environment\n for key, value in original_env.items():\n if value is not None:\n os.environ[key] = value\n else:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n importlib.reload(config)\n ModelProviderRegistry._instance = None\n\n @pytest.mark.asyncio\n async def test_thinking_mode_high(self):\n \"\"\"Test high thinking mode with real provider resolution\"\"\"\n import importlib\n import os\n\n # Save original environment\n original_env = {\n \"OPENAI_API_KEY\": os.environ.get(\"OPENAI_API_KEY\"),\n \"DEFAULT_MODEL\": os.environ.get(\"DEFAULT_MODEL\"),\n }\n\n try:\n # Set up environment for OpenAI provider (which supports thinking mode)\n os.environ[\"OPENAI_API_KEY\"] = \"sk-test-key-high-thinking-test-not-real\"\n os.environ[\"DEFAULT_MODEL\"] = \"o3-mini\"\n\n # Clear other provider keys\n for key in [\"GEMINI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n import config\n\n importlib.reload(config)\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry._instance = None\n\n tool = AnalyzeTool()\n\n # Test with real provider resolution\n try:\n result = await tool.execute(\n {\n \"absolute_file_paths\": [\"/absolute/path/complex.py\"],\n \"prompt\": \"Analyze architecture\",\n \"thinking_mode\": \"high\",\n \"model\": \"o3-mini\",\n }\n )\n # If we get here, provider resolution worked\n assert result is not None\n\n except Exception as e:\n # Expected: API call will fail with fake key\n error_msg = getattr(e, \"payload\", str(e))\n # Should NOT be a mock-related error\n assert \"MagicMock\" not in error_msg\n assert \"'<' not supported between instances\" not in error_msg\n\n # Should be a real provider error\n import json\n\n try:\n parsed = json.loads(error_msg)\n except Exception:\n parsed = None\n\n if isinstance(parsed, dict) and parsed.get(\"status\", \"\").endswith(\"_failed\"):\n assert \"validation errors\" in parsed.get(\"error\", \"\")\n else:\n assert any(\n phrase in error_msg\n for phrase in [\"API\", \"key\", \"authentication\", \"provider\", \"network\", \"connection\", \"Model\"]\n )\n\n finally:\n # Restore environment\n for key, value in original_env.items():\n if value is not None:\n os.environ[key] = value\n else:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n importlib.reload(config)\n ModelProviderRegistry._instance = None\n\n @pytest.mark.asyncio\n async def test_thinking_mode_max(self):\n \"\"\"Test max thinking mode (default for thinkdeep) using real integration testing\"\"\"\n import importlib\n import os\n\n # Save original environment\n original_env = {\n \"OPENAI_API_KEY\": os.environ.get(\"OPENAI_API_KEY\"),\n \"DEFAULT_MODEL\": os.environ.get(\"DEFAULT_MODEL\"),\n \"DEFAULT_THINKING_MODE_THINKDEEP\": os.environ.get(\"DEFAULT_THINKING_MODE_THINKDEEP\"),\n }\n\n try:\n # Set up environment for OpenAI provider (which supports thinking mode)\n os.environ[\"OPENAI_API_KEY\"] = \"sk-test-key-max-thinking-test-not-real\"\n os.environ[\"DEFAULT_MODEL\"] = \"o3-mini\"\n os.environ[\"DEFAULT_THINKING_MODE_THINKDEEP\"] = \"high\" # Set default to high for thinkdeep\n\n # Clear other provider keys to isolate to OpenAI\n for key in [\"GEMINI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n import config\n\n importlib.reload(config)\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry._instance = None\n\n tool = ThinkDeepTool()\n\n # Test with real provider resolution\n try:\n result = await tool.execute(\n {\n \"prompt\": \"Initial analysis\",\n \"model\": \"o3-mini\",\n # Not specifying thinking_mode, should use default (high)\n }\n )\n # If we get here, provider resolution worked\n assert result is not None\n # Should be a valid thinkdeep response\n assert len(result) == 1\n\n except Exception as e:\n # Expected: API call will fail with fake key\n error_msg = getattr(e, \"payload\", str(e))\n # Should NOT be a mock-related error\n assert \"MagicMock\" not in error_msg\n assert \"'<' not supported between instances\" not in error_msg\n\n # Should be a real provider error\n import json\n\n try:\n parsed = json.loads(error_msg)\n except Exception:\n parsed = None\n\n if isinstance(parsed, dict) and parsed.get(\"status\", \"\").endswith(\"_failed\"):\n assert \"validation errors\" in parsed.get(\"error\", \"\")\n else:\n assert any(\n phrase in error_msg\n for phrase in [\"API\", \"key\", \"authentication\", \"provider\", \"network\", \"connection\", \"Model\"]\n )\n\n finally:\n # Restore environment\n for key, value in original_env.items():\n if value is not None:\n os.environ[key] = value\n else:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n importlib.reload(config)\n ModelProviderRegistry._instance = None\n" }, { "path": "tests/test_tools.py", "content": "\"\"\"\nTests for individual tool implementations\n\"\"\"\n\nimport json\nimport shutil\nimport tempfile\n\nimport pytest\n\nfrom tools import AnalyzeTool, ChatTool, CodeReviewTool, ThinkDeepTool\nfrom tools.shared.exceptions import ToolExecutionError\n\n\nclass TestThinkDeepTool:\n \"\"\"Test the thinkdeep tool\"\"\"\n\n @pytest.fixture\n def tool(self):\n return ThinkDeepTool()\n\n def test_tool_metadata(self, tool):\n \"\"\"Test tool metadata\"\"\"\n assert tool.get_name() == \"thinkdeep\"\n assert \"investigation and reasoning\" in tool.get_description()\n assert tool.get_default_temperature() == 1.0\n\n schema = tool.get_input_schema()\n # ThinkDeep is now a workflow tool with step-based fields\n assert \"step\" in schema[\"properties\"]\n assert \"step_number\" in schema[\"properties\"]\n assert \"total_steps\" in schema[\"properties\"]\n assert \"next_step_required\" in schema[\"properties\"]\n assert \"findings\" in schema[\"properties\"]\n\n # Required fields for workflow\n expected_required = {\"step\", \"step_number\", \"total_steps\", \"next_step_required\", \"findings\"}\n assert expected_required.issubset(set(schema[\"required\"]))\n\n @pytest.mark.asyncio\n async def test_execute_success(self, tool):\n \"\"\"Test successful execution using real integration testing\"\"\"\n import importlib\n import os\n\n # Save original environment\n original_env = {\n \"OPENAI_API_KEY\": os.environ.get(\"OPENAI_API_KEY\"),\n \"DEFAULT_MODEL\": os.environ.get(\"DEFAULT_MODEL\"),\n }\n\n try:\n # Set up environment for real provider resolution\n os.environ[\"OPENAI_API_KEY\"] = \"sk-test-key-thinkdeep-success-test-not-real\"\n os.environ[\"DEFAULT_MODEL\"] = \"o3-mini\"\n\n # Clear other provider keys to isolate to OpenAI\n for key in [\"GEMINI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n import config\n\n importlib.reload(config)\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry._instance = None\n\n # Test with real provider resolution\n try:\n result = await tool.execute(\n {\n \"step\": \"Initial analysis\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Initial thinking about building a cache\",\n \"problem_context\": \"Building a cache\",\n \"focus_areas\": [\"performance\", \"scalability\"],\n \"model\": \"o3-mini\",\n }\n )\n\n # If we get here, check the response format\n assert len(result) == 1\n # Should be a valid JSON response\n output = json.loads(result[0].text)\n assert \"status\" in output\n\n except Exception as e:\n # Expected: API call will fail with fake key\n error_msg = str(e)\n # Should NOT be a mock-related error\n assert \"MagicMock\" not in error_msg\n assert \"'<' not supported between instances\" not in error_msg\n\n # Should be a real provider error\n assert any(\n phrase in error_msg\n for phrase in [\"API\", \"key\", \"authentication\", \"provider\", \"network\", \"connection\"]\n )\n\n finally:\n # Restore environment\n for key, value in original_env.items():\n if value is not None:\n os.environ[key] = value\n else:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n importlib.reload(config)\n ModelProviderRegistry._instance = None\n\n\nclass TestCodeReviewTool:\n \"\"\"Test the codereview tool\"\"\"\n\n @pytest.fixture\n def tool(self):\n return CodeReviewTool()\n\n def test_tool_metadata(self, tool):\n \"\"\"Test tool metadata\"\"\"\n assert tool.get_name() == \"codereview\"\n assert \"code review\" in tool.get_description()\n assert tool.get_default_temperature() == 1.0\n\n schema = tool.get_input_schema()\n assert \"relevant_files\" in schema[\"properties\"]\n assert \"step\" in schema[\"properties\"]\n assert \"step_number\" in schema[\"required\"]\n\n @pytest.mark.asyncio\n async def test_execute_with_review_type(self, tool, tmp_path):\n \"\"\"Test execution with specific review type using real provider resolution\"\"\"\n import importlib\n import os\n\n # Create test file\n test_file = tmp_path / \"test.py\"\n test_file.write_text(\"def insecure(): pass\", encoding=\"utf-8\")\n\n # Save original environment\n original_env = {\n \"OPENAI_API_KEY\": os.environ.get(\"OPENAI_API_KEY\"),\n \"DEFAULT_MODEL\": os.environ.get(\"DEFAULT_MODEL\"),\n }\n\n try:\n # Set up environment for testing\n os.environ[\"OPENAI_API_KEY\"] = \"sk-test-key-codereview-test-not-real\"\n os.environ[\"DEFAULT_MODEL\"] = \"o3-mini\"\n\n # Clear other provider keys\n for key in [\"GEMINI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n import config\n\n importlib.reload(config)\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry._instance = None\n\n # Test with real provider resolution - expect it to fail at API level\n try:\n result = await tool.execute(\n {\n \"step\": \"Review for security issues\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Initial security review\",\n \"relevant_files\": [str(test_file)],\n \"model\": \"o3-mini\",\n }\n )\n # If we somehow get here, that's fine too\n assert result is not None\n\n except Exception as e:\n # Expected: API call will fail with fake key\n error_msg = str(e)\n # Should NOT be a mock-related error\n assert \"MagicMock\" not in error_msg\n assert \"'<' not supported between instances\" not in error_msg\n\n # Should be a real provider error\n assert any(\n phrase in error_msg\n for phrase in [\"API\", \"key\", \"authentication\", \"provider\", \"network\", \"connection\"]\n )\n\n finally:\n # Restore environment\n for key, value in original_env.items():\n if value is not None:\n os.environ[key] = value\n else:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n importlib.reload(config)\n ModelProviderRegistry._instance = None\n\n\nclass TestAnalyzeTool:\n \"\"\"Test the analyze tool\"\"\"\n\n @pytest.fixture\n def tool(self):\n return AnalyzeTool()\n\n def test_tool_metadata(self, tool):\n \"\"\"Test tool metadata\"\"\"\n assert tool.get_name() == \"analyze\"\n assert \"code analysis\" in tool.get_description()\n assert tool.get_default_temperature() == 1.0\n\n schema = tool.get_input_schema()\n # New workflow tool requires step-based fields\n assert \"step\" in schema[\"properties\"]\n assert \"step_number\" in schema[\"properties\"]\n assert \"total_steps\" in schema[\"properties\"]\n assert \"next_step_required\" in schema[\"properties\"]\n assert \"findings\" in schema[\"properties\"]\n # Workflow tools use relevant_files instead of files\n assert \"relevant_files\" in schema[\"properties\"]\n\n # Required fields for workflow\n expected_required = {\"step\", \"step_number\", \"total_steps\", \"next_step_required\", \"findings\"}\n assert expected_required.issubset(set(schema[\"required\"]))\n\n @pytest.mark.asyncio\n async def test_execute_with_analysis_type(self, tool, tmp_path):\n \"\"\"Test execution with specific analysis type using real provider resolution\"\"\"\n import importlib\n import os\n\n # Create test file\n test_file = tmp_path / \"module.py\"\n test_file.write_text(\"class Service: pass\", encoding=\"utf-8\")\n\n # Save original environment\n original_env = {\n \"OPENAI_API_KEY\": os.environ.get(\"OPENAI_API_KEY\"),\n \"DEFAULT_MODEL\": os.environ.get(\"DEFAULT_MODEL\"),\n }\n\n try:\n # Set up environment for testing\n os.environ[\"OPENAI_API_KEY\"] = \"sk-test-key-analyze-test-not-real\"\n os.environ[\"DEFAULT_MODEL\"] = \"o3-mini\"\n\n # Clear other provider keys\n for key in [\"GEMINI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n import config\n\n importlib.reload(config)\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry._instance = None\n\n # Test with real provider resolution - expect it to fail at API level\n try:\n result = await tool.execute(\n {\n \"step\": \"Analyze the structure of this code\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Initial analysis of code structure\",\n \"relevant_files\": [str(test_file)],\n \"analysis_type\": \"architecture\",\n \"output_format\": \"summary\",\n \"model\": \"o3-mini\",\n }\n )\n # If we somehow get here, that's fine too\n assert result is not None\n\n except Exception as e:\n # Expected: API call will fail with fake key\n error_msg = str(e)\n # Should NOT be a mock-related error\n assert \"MagicMock\" not in error_msg\n assert \"'<' not supported between instances\" not in error_msg\n\n # Should be a real provider error\n assert any(\n phrase in error_msg\n for phrase in [\"API\", \"key\", \"authentication\", \"provider\", \"network\", \"connection\"]\n )\n\n finally:\n # Restore environment\n for key, value in original_env.items():\n if value is not None:\n os.environ[key] = value\n else:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n importlib.reload(config)\n ModelProviderRegistry._instance = None\n\n\nclass TestAbsolutePathValidation:\n \"\"\"Test absolute path validation across all tools\"\"\"\n\n # Removed: test_analyze_tool_relative_path_rejected - workflow tool handles validation differently\n\n # NOTE: CodeReview tool test has been commented out because the codereview tool has been\n # refactored to use a workflow-based pattern. The workflow tools handle path validation\n # differently and may accept relative paths in step 1 since validation happens at the\n # file reading stage. See simulator_tests/test_codereview_validation.py for comprehensive\n # workflow testing of the new codereview tool.\n\n @pytest.mark.asyncio\n async def test_thinkdeep_tool_relative_path_rejected(self):\n \"\"\"Test that thinkdeep tool rejects relative paths\"\"\"\n tool = ThinkDeepTool()\n with pytest.raises(ToolExecutionError) as exc_info:\n await tool.execute(\n {\n \"step\": \"My analysis\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Initial analysis\",\n \"files_checked\": [\"./local/file.py\"],\n }\n )\n\n response = json.loads(exc_info.value.payload)\n assert response[\"status\"] == \"error\"\n assert \"must be FULL absolute paths\" in response[\"content\"]\n assert \"./local/file.py\" in response[\"content\"]\n\n @pytest.mark.asyncio\n async def test_chat_tool_relative_path_rejected(self):\n \"\"\"Test that chat tool rejects relative paths\"\"\"\n tool = ChatTool()\n temp_dir = tempfile.mkdtemp()\n try:\n with pytest.raises(ToolExecutionError) as exc_info:\n await tool.execute(\n {\n \"prompt\": \"Explain this code\",\n \"absolute_file_paths\": [\"code.py\"], # relative path without ./\n \"working_directory_absolute_path\": temp_dir,\n }\n )\n finally:\n shutil.rmtree(temp_dir, ignore_errors=True)\n\n response = json.loads(exc_info.value.payload)\n assert response[\"status\"] == \"error\"\n assert \"must be FULL absolute paths\" in response[\"content\"]\n assert \"code.py\" in response[\"content\"]\n\n @pytest.mark.asyncio\n async def test_analyze_tool_accepts_absolute_paths(self):\n \"\"\"Test that analyze tool accepts absolute paths using real provider resolution\"\"\"\n import importlib\n import os\n\n tool = AnalyzeTool()\n\n # Save original environment\n original_env = {\n \"OPENAI_API_KEY\": os.environ.get(\"OPENAI_API_KEY\"),\n \"DEFAULT_MODEL\": os.environ.get(\"DEFAULT_MODEL\"),\n }\n\n try:\n # Set up environment for testing\n os.environ[\"OPENAI_API_KEY\"] = \"sk-test-key-absolute-path-test-not-real\"\n os.environ[\"DEFAULT_MODEL\"] = \"o3-mini\"\n\n # Clear other provider keys\n for key in [\"GEMINI_API_KEY\", \"XAI_API_KEY\", \"OPENROUTER_API_KEY\"]:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n import config\n\n importlib.reload(config)\n from providers.registry import ModelProviderRegistry\n\n ModelProviderRegistry._instance = None\n\n # Test with real provider resolution - expect it to fail at API level\n try:\n result = await tool.execute(\n {\n \"step\": \"Analyze this code file\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Initial code analysis\",\n \"relevant_files\": [\"/absolute/path/file.py\"],\n \"model\": \"o3-mini\",\n }\n )\n # If we somehow get here, that's fine too\n assert result is not None\n\n except Exception as e:\n # Expected: API call will fail with fake key\n error_msg = str(e)\n # Should NOT be a mock-related error\n assert \"MagicMock\" not in error_msg\n assert \"'<' not supported between instances\" not in error_msg\n\n # Should be a real provider error\n assert any(\n phrase in error_msg\n for phrase in [\"API\", \"key\", \"authentication\", \"provider\", \"network\", \"connection\"]\n )\n\n finally:\n # Restore environment\n for key, value in original_env.items():\n if value is not None:\n os.environ[key] = value\n else:\n os.environ.pop(key, None)\n\n # Reload config and clear registry\n importlib.reload(config)\n ModelProviderRegistry._instance = None\n\n\nclass TestSpecialStatusModels:\n \"\"\"Test SPECIAL_STATUS_MODELS registry and structured response handling\"\"\"\n\n def test_trace_complete_status_in_registry(self):\n \"\"\"Test that trace_complete status is properly registered\"\"\"\n from tools.models import SPECIAL_STATUS_MODELS, TraceComplete\n\n assert \"trace_complete\" in SPECIAL_STATUS_MODELS\n assert SPECIAL_STATUS_MODELS[\"trace_complete\"] == TraceComplete\n\n def test_trace_complete_model_validation(self):\n \"\"\"Test TraceComplete model validation\"\"\"\n from tools.models import TraceComplete\n\n # Test precision mode\n precision_data = {\n \"status\": \"trace_complete\",\n \"trace_type\": \"precision\",\n \"entry_point\": {\n \"file\": \"/path/to/file.py\",\n \"class_or_struct\": \"MyClass\",\n \"method\": \"myMethod\",\n \"signature\": \"def myMethod(self, param1: str) -> bool\",\n \"parameters\": {\"param1\": \"test\"},\n },\n \"call_path\": [\n {\n \"from\": {\"file\": \"/path/to/file.py\", \"class\": \"MyClass\", \"method\": \"myMethod\", \"line\": 10},\n \"to\": {\"file\": \"/path/to/other.py\", \"class\": \"OtherClass\", \"method\": \"otherMethod\", \"line\": 20},\n \"reason\": \"direct call\",\n \"condition\": None,\n \"ambiguous\": False,\n }\n ],\n }\n\n model = TraceComplete(**precision_data)\n assert model.status == \"trace_complete\"\n assert model.trace_type == \"precision\"\n assert model.entry_point.file == \"/path/to/file.py\"\n assert len(model.call_path) == 1\n\n # Test dependencies mode\n dependencies_data = {\n \"status\": \"trace_complete\",\n \"trace_type\": \"dependencies\",\n \"target\": {\n \"file\": \"/path/to/file.py\",\n \"class_or_struct\": \"MyClass\",\n \"method\": \"myMethod\",\n \"signature\": \"def myMethod(self, param1: str) -> bool\",\n },\n \"incoming_dependencies\": [\n {\n \"from_file\": \"/path/to/caller.py\",\n \"from_class\": \"CallerClass\",\n \"from_method\": \"callerMethod\",\n \"line\": 15,\n \"type\": \"direct_call\",\n }\n ],\n \"outgoing_dependencies\": [\n {\n \"to_file\": \"/path/to/dependency.py\",\n \"to_class\": \"DepClass\",\n \"to_method\": \"depMethod\",\n \"line\": 25,\n \"type\": \"method_call\",\n }\n ],\n }\n\n model = TraceComplete(**dependencies_data)\n assert model.status == \"trace_complete\"\n assert model.trace_type == \"dependencies\"\n assert model.target.file == \"/path/to/file.py\"\n assert len(model.incoming_dependencies) == 1\n assert len(model.outgoing_dependencies) == 1\n" }, { "path": "tests/test_tracer.py", "content": "\"\"\"\nTests for the tracer tool functionality\n\"\"\"\n\nimport pytest\n\nfrom tools.models import ToolModelCategory\nfrom tools.tracer import TracerRequest, TracerTool\n\n\nclass TestTracerTool:\n \"\"\"Test suite for the Tracer tool\"\"\"\n\n @pytest.fixture\n def tracer_tool(self):\n \"\"\"Create a tracer tool instance for testing\"\"\"\n return TracerTool()\n\n def test_get_name(self, tracer_tool):\n \"\"\"Test that the tool returns the correct name\"\"\"\n assert tracer_tool.get_name() == \"tracer\"\n\n def test_get_description(self, tracer_tool):\n \"\"\"Test that the tool returns a comprehensive description\"\"\"\n description = tracer_tool.get_description()\n assert \"code tracing\" in description\n assert \"precision\" in description\n assert \"dependencies\" in description\n assert \"systematic\" in description\n\n def test_get_input_schema(self, tracer_tool):\n \"\"\"Test that the input schema includes required fields\"\"\"\n schema = tracer_tool.get_input_schema()\n\n assert schema[\"type\"] == \"object\"\n assert \"target_description\" in schema[\"properties\"]\n assert \"trace_mode\" in schema[\"properties\"]\n assert \"step\" in schema[\"properties\"]\n assert \"step_number\" in schema[\"properties\"]\n\n # Check trace_mode enum values\n trace_enum = schema[\"properties\"][\"trace_mode\"][\"enum\"]\n assert \"precision\" in trace_enum\n assert \"dependencies\" in trace_enum\n\n # Check required fields include workflow fields\n required_fields = set(schema[\"required\"])\n assert \"target_description\" in required_fields\n assert \"trace_mode\" in required_fields\n\n def test_get_model_category(self, tracer_tool):\n \"\"\"Test that the tracer tool uses EXTENDED_REASONING category\"\"\"\n category = tracer_tool.get_model_category()\n assert category == ToolModelCategory.EXTENDED_REASONING\n\n def test_request_model_validation(self, tracer_tool):\n \"\"\"Test TracerRequest model validation\"\"\"\n # Valid request\n request = TracerRequest(\n step=\"Analyze BookingManager finalizeInvoice method execution flow\",\n step_number=1,\n total_steps=3,\n next_step_required=True,\n findings=\"Initial investigation of booking finalization process\",\n target_description=\"BookingManager finalizeInvoice method\",\n trace_mode=\"precision\",\n )\n assert request.target_description == \"BookingManager finalizeInvoice method\"\n assert request.trace_mode == \"precision\"\n assert request.step_number == 1\n\n # Test invalid trace_mode\n with pytest.raises(ValueError):\n TracerRequest(\n step=\"Test step\",\n step_number=1,\n total_steps=1,\n next_step_required=False,\n findings=\"Test findings\",\n trace_mode=\"invalid_mode\",\n )\n\n def test_get_required_actions(self, tracer_tool):\n \"\"\"Test that required actions are provided for each step\"\"\"\n # Step 1 - initial investigation (in ask mode by default)\n actions = tracer_tool.get_required_actions(1, \"exploring\", \"Initial findings\", 3)\n assert len(actions) > 0\n # Default is ask mode, so should ask for mode selection\n if tracer_tool.get_trace_mode() == \"ask\":\n assert any(\"ask user\" in action.lower() for action in actions)\n assert any(\"precision mode\" in action.lower() for action in actions)\n\n # Test with initialized trace_config for non-ask mode\n tracer_tool.trace_config = {\"trace_mode\": \"precision\"}\n actions = tracer_tool.get_required_actions(1, \"exploring\", \"Initial findings\", 3)\n assert len(actions) > 0\n assert any(\"search\" in action.lower() for action in actions)\n assert any(\"locate\" in action.lower() for action in actions)\n\n # Later steps with low confidence\n actions = tracer_tool.get_required_actions(2, \"low\", \"Some findings\", 3)\n assert len(actions) > 0\n assert any(\"trace\" in action.lower() for action in actions)\n\n # High confidence steps\n actions = tracer_tool.get_required_actions(3, \"high\", \"Strong findings\", 3)\n assert len(actions) > 0\n assert any(\"verify\" in action.lower() for action in actions)\n\n def test_workflow_tool_characteristics(self, tracer_tool):\n \"\"\"Test that tracer has proper workflow tool characteristics\"\"\"\n # Should not require external expert analysis\n assert not tracer_tool.requires_expert_analysis()\n\n # Should return TracerRequest as the workflow model\n assert tracer_tool.get_workflow_request_model() == TracerRequest\n\n # Should not require AI model at MCP boundary\n assert not tracer_tool.requires_model()\n\n def test_get_rendering_instructions_precision(self, tracer_tool):\n \"\"\"Test rendering instructions for precision mode\"\"\"\n instructions = tracer_tool._get_rendering_instructions(\"precision\")\n\n assert \"PRECISION TRACE\" in instructions\n assert \"CALL FLOW DIAGRAM\" in instructions\n assert \"ADDITIONAL ANALYSIS VIEWS\" in instructions\n assert \"ClassName::MethodName\" in instructions\n assert \"↓\" in instructions\n\n def test_get_rendering_instructions_dependencies(self, tracer_tool):\n \"\"\"Test rendering instructions for dependencies mode\"\"\"\n instructions = tracer_tool._get_rendering_instructions(\"dependencies\")\n\n assert \"DEPENDENCIES TRACE\" in instructions\n assert \"DEPENDENCY FLOW DIAGRAM\" in instructions\n assert \"DEPENDENCY TABLE\" in instructions\n assert \"INCOMING DEPENDENCIES\" in instructions\n assert \"OUTGOING DEPENDENCIES\" in instructions\n assert \"←\" in instructions\n assert \"β†’\" in instructions\n\n def test_rendering_instructions_consistency(self, tracer_tool):\n \"\"\"Test that rendering instructions are consistent between modes\"\"\"\n precision_instructions = tracer_tool._get_precision_rendering_instructions()\n dependencies_instructions = tracer_tool._get_dependencies_rendering_instructions()\n\n # Both should have mandatory instructions\n assert \"MANDATORY RENDERING INSTRUCTIONS\" in precision_instructions\n assert \"MANDATORY RENDERING INSTRUCTIONS\" in dependencies_instructions\n\n # Both should have specific styling requirements\n assert \"ONLY\" in precision_instructions\n assert \"ONLY\" in dependencies_instructions\n\n # Both should have absolute requirements\n assert \"ABSOLUTE REQUIREMENTS\" in precision_instructions\n assert \"ABSOLUTE REQUIREMENTS\" in dependencies_instructions\n\n def test_mode_selection_guidance(self, tracer_tool):\n \"\"\"Test that the schema provides clear guidance on when to use each mode\"\"\"\n schema = tracer_tool.get_input_schema()\n trace_mode_desc = schema[\"properties\"][\"trace_mode\"][\"description\"]\n\n # Should clearly indicate precision is for methods/functions\n assert \"execution flow\" in trace_mode_desc\n\n # Should clearly indicate dependencies is for structural relationships\n assert \"structural relationships\" in trace_mode_desc\n" }, { "path": "tests/test_utf8_localization.py", "content": "\"\"\"\nUnit tests to validate UTF-8 localization and encoding\nof French characters.\n\nThese tests check:\n1. Language instruction generation according to LOCALE\n2. UTF-8 encoding with json.dumps(ensure_ascii=False)\n3. French characters and emojis are displayed correctly\n4. MCP tools return localized content\n\"\"\"\n\nimport asyncio\nimport json\nimport os\nimport tempfile\nimport unittest\nfrom unittest.mock import Mock\n\nfrom tools.shared.base_tool import BaseTool\n\n\nclass MockTestTool(BaseTool):\n \"\"\"Concrete implementation of BaseTool for testing.\"\"\"\n\n def __init__(self):\n super().__init__()\n\n def get_name(self) -> str:\n return \"test_tool\"\n\n def get_description(self) -> str:\n return \"A test tool for localization testing\"\n\n def get_input_schema(self) -> dict:\n return {\"type\": \"object\", \"properties\": {}}\n\n def get_system_prompt(self) -> str:\n return \"You are a test assistant.\"\n\n def get_request_model(self):\n from tools.shared.base_models import ToolRequest\n\n return ToolRequest\n\n async def prepare_prompt(self, request) -> str:\n return \"Test prompt\"\n\n async def execute(self, arguments: dict) -> list:\n return [Mock(text=\"test response\")]\n\n\nclass TestUTF8Localization(unittest.TestCase):\n \"\"\"Tests for UTF-8 localization and French character encoding.\"\"\"\n\n def setUp(self):\n \"\"\"Test setup.\"\"\"\n self.original_locale = os.getenv(\"LOCALE\")\n\n def tearDown(self):\n \"\"\"Cleanup after tests.\"\"\"\n if self.original_locale is not None:\n os.environ[\"LOCALE\"] = self.original_locale\n else:\n os.environ.pop(\"LOCALE\", None)\n\n def test_language_instruction_generation_french(self):\n \"\"\"Test language instruction generation for French.\"\"\"\n # Set LOCALE to French\n os.environ[\"LOCALE\"] = \"fr-FR\"\n\n # Test get_language_instruction method\n tool = MockTestTool()\n instruction = tool.get_language_instruction() # Checks\n self.assertIsInstance(instruction, str)\n self.assertIn(\"fr-FR\", instruction)\n self.assertTrue(instruction.endswith(\"\\n\\n\"))\n\n def test_language_instruction_generation_english(self):\n \"\"\"Test language instruction generation for English.\"\"\"\n # Set LOCALE to English\n os.environ[\"LOCALE\"] = \"en-US\"\n\n tool = MockTestTool()\n instruction = tool.get_language_instruction() # Checks\n self.assertIsInstance(instruction, str)\n self.assertIn(\"en-US\", instruction)\n self.assertTrue(instruction.endswith(\"\\n\\n\"))\n\n def test_language_instruction_empty_locale(self):\n \"\"\"Test with empty LOCALE.\"\"\"\n # Set LOCALE to empty\n os.environ[\"LOCALE\"] = \"\"\n\n tool = MockTestTool()\n instruction = tool.get_language_instruction()\n\n # Should return empty string\n self.assertEqual(instruction, \"\")\n\n def test_language_instruction_no_locale(self):\n \"\"\"Test with no LOCALE variable set.\"\"\"\n # Remove LOCALE\n os.environ.pop(\"LOCALE\", None)\n\n tool = MockTestTool()\n instruction = tool.get_language_instruction()\n\n # Should return empty string\n self.assertEqual(instruction, \"\")\n\n def test_json_dumps_utf8_encoding(self):\n \"\"\"Test that json.dumps uses ensure_ascii=False for UTF-8.\"\"\"\n # Test data with French characters and emojis\n test_data = {\n \"status\": \"succΓ¨s\",\n \"message\": \"TΓ’che terminΓ©e avec succΓ¨s\",\n \"details\": {\n \"créé\": \"2024-01-01\",\n \"dΓ©veloppeur\": \"Jean Dupont\",\n \"prΓ©fΓ©rences\": [\"franΓ§ais\", \"dΓ©veloppement\"],\n \"emojis\": \"πŸ”΄ 🟠 🟑 🟒 βœ… ❌\",\n },\n }\n\n # Test with ensure_ascii=False (correct)\n json_correct = json.dumps(test_data, ensure_ascii=False, indent=2)\n\n # Check that UTF-8 characters are preserved\n self.assertIn(\"succΓ¨s\", json_correct)\n self.assertIn(\"terminΓ©e\", json_correct)\n self.assertIn(\"créé\", json_correct)\n self.assertIn(\"dΓ©veloppeur\", json_correct)\n self.assertIn(\"prΓ©fΓ©rences\", json_correct)\n self.assertIn(\"franΓ§ais\", json_correct)\n self.assertIn(\"dΓ©veloppement\", json_correct)\n self.assertIn(\"πŸ”΄\", json_correct)\n self.assertIn(\"🟒\", json_correct)\n self.assertIn(\"βœ…\", json_correct)\n\n # Check that characters are NOT escaped\n self.assertNotIn(\"\\\\u\", json_correct)\n self.assertNotIn(\"\\\\ud83d\", json_correct)\n\n def test_json_dumps_ascii_encoding_comparison(self):\n \"\"\"Test comparison between ensure_ascii=True and False.\"\"\"\n test_data = {\"message\": \"DΓ©veloppement rΓ©ussi! πŸŽ‰\"}\n\n # With ensure_ascii=True (old, incorrect behavior)\n json_escaped = json.dumps(test_data, ensure_ascii=True)\n\n # With ensure_ascii=False (new, correct behavior)\n json_utf8 = json.dumps(test_data, ensure_ascii=False) # Checks\n self.assertIn(\"\\\\u\", json_escaped) # Characters are escaped\n self.assertNotIn(\"Γ©\", json_escaped) # UTF-8 characters are escaped\n\n self.assertNotIn(\"\\\\u\", json_utf8) # No escaped characters\n self.assertIn(\"Γ©\", json_utf8) # UTF-8 characters preserved\n self.assertIn(\"πŸŽ‰\", json_utf8) # Emojis preserved\n\n def test_french_characters_in_file_content(self):\n \"\"\"Test reading and writing files with French characters.\"\"\"\n # Test content with French characters\n test_content = \"\"\"\n# System configuration\n# Created by: Lead Developer\n# Creation date: December 15, 2024\n\ndef process_data(preferences, parameters):\n \"\"\\\"\n Processes data according to user preferences.\n\n Args:\n preferences: User preferences dictionary\n parameters: Configuration parameters\n\n Returns:\n Processing result\n \"\"\\\"\n return \"Processing completed successfully! βœ…\"\n\n# Helper functions\ndef generate_report():\n \"\"\\\"Generates a summary report.\"\"\\\"\n return {\n \"status\": \"success\",\n \"data\": \"Report generated\",\n \"emojis\": \"πŸ“Š πŸ“ˆ πŸ“‰\"\n }\n\"\"\"\n\n # Test writing and reading\n with tempfile.NamedTemporaryFile(mode=\"w+\", encoding=\"utf-8\", delete=False) as f:\n f.write(test_content)\n temp_file = f.name\n\n try:\n # Read file\n with open(temp_file, encoding=\"utf-8\") as f:\n read_content = f.read()\n\n # Checks\n self.assertEqual(read_content, test_content)\n self.assertIn(\"Lead Developer\", read_content)\n self.assertIn(\"Creation\", read_content)\n self.assertIn(\"preferences\", read_content)\n self.assertIn(\"parameters\", read_content)\n self.assertIn(\"completed\", read_content)\n self.assertIn(\"successfully\", read_content)\n self.assertIn(\"βœ…\", read_content)\n self.assertIn(\"success\", read_content)\n self.assertIn(\"generated\", read_content)\n self.assertIn(\"πŸ“Š\", read_content)\n\n finally:\n # Cleanup\n os.unlink(temp_file)\n\n def test_unicode_normalization(self):\n \"\"\"Test Unicode normalization for accented characters.\"\"\"\n # Test with different Unicode encodings\n test_cases = [\n \"cafΓ©\", # e + acute accent combined\n \"cafΓ©\", # e with precomposed acute accent\n \"naΓ―f\", # i + diaeresis\n \"coeur\", # oe ligature\n \"Γ©tΓ©\", # e + acute accent\n ]\n\n for text in test_cases:\n # Test that json.dumps preserves characters\n json_output = json.dumps({\"text\": text}, ensure_ascii=False)\n self.assertIn(text, json_output)\n\n # Parse and check\n parsed = json.loads(json_output)\n self.assertEqual(parsed[\"text\"], text)\n\n def test_emoji_preservation(self):\n \"\"\"Test emoji preservation in JSON encoding.\"\"\"\n # Emojis used in PAL MCP tools\n emojis = [\n \"πŸ”΄\", # Critical\n \"🟠\", # High\n \"🟑\", # Medium\n \"🟒\", # Low\n \"βœ…\", # Success\n \"❌\", # Error\n \"⚠️\", # Warning\n \"πŸ“Š\", # Charts\n \"πŸŽ‰\", # Celebration\n \"πŸš€\", # Rocket\n \"πŸ‡«πŸ‡·\", # French flag\n ]\n\n test_data = {\"emojis\": emojis, \"message\": \" \".join(emojis)}\n\n # Test with ensure_ascii=False\n json_output = json.dumps(test_data, ensure_ascii=False)\n\n # Checks\n for emoji in emojis:\n self.assertIn(emoji, json_output) # No escaped characters\n self.assertNotIn(\"\\\\u\", json_output)\n\n # Test parsing\n parsed = json.loads(json_output)\n self.assertEqual(parsed[\"emojis\"], emojis)\n self.assertEqual(parsed[\"message\"], \" \".join(emojis))\n\n\nclass TestLocalizationIntegration(unittest.TestCase):\n \"\"\"Integration tests for localization with real tools.\"\"\"\n\n def setUp(self):\n \"\"\"Integration test setup.\"\"\"\n self.original_locale = os.getenv(\"LOCALE\")\n\n def tearDown(self):\n \"\"\"Cleanup after integration tests.\"\"\"\n if self.original_locale is not None:\n os.environ[\"LOCALE\"] = self.original_locale\n else:\n os.environ.pop(\"LOCALE\", None)\n\n def test_codereview_tool_french_locale_simple(self):\n \"\"\"Test that the codereview tool correctly handles French locale configuration.\"\"\"\n # Set to French\n original_locale = os.environ.get(\"LOCALE\")\n os.environ[\"LOCALE\"] = \"fr-FR\"\n\n try:\n # Test language instruction generation\n from tools.codereview import CodeReviewTool\n\n codereview_tool = CodeReviewTool()\n\n # Test that the tool correctly gets language instruction for French\n language_instruction = codereview_tool.get_language_instruction()\n\n # Should contain French locale\n self.assertIn(\"fr-FR\", language_instruction)\n\n # Should contain language instruction format\n self.assertIn(\"respond in\", language_instruction.lower())\n\n finally:\n # Restore original locale\n if original_locale is not None:\n os.environ[\"LOCALE\"] = original_locale\n else:\n os.environ.pop(\"LOCALE\", None)\n\n def test_multiple_locales_switching(self):\n \"\"\"Test switching locales during execution.\"\"\"\n tool = MockTestTool()\n\n # French\n os.environ[\"LOCALE\"] = \"fr-FR\"\n instruction_fr = tool.get_language_instruction()\n self.assertIn(\"fr-FR\", instruction_fr)\n\n # English\n os.environ[\"LOCALE\"] = \"en-US\"\n instruction_en = tool.get_language_instruction()\n self.assertIn(\"en-US\", instruction_en)\n\n # Spanish\n os.environ[\"LOCALE\"] = \"es-ES\"\n instruction_es = tool.get_language_instruction()\n self.assertIn(\"es-ES\", instruction_es)\n\n # Chinese\n os.environ[\"LOCALE\"] = \"zh-CN\"\n instruction_zh = tool.get_language_instruction()\n self.assertIn(\"zh-CN\", instruction_zh)\n\n # Check that all instructions are different\n instructions = [\n instruction_fr,\n instruction_en,\n instruction_es,\n instruction_zh,\n ]\n for i, inst1 in enumerate(instructions):\n for j, inst2 in enumerate(instructions):\n if i != j:\n self.assertNotEqual(inst1, inst2)\n\n\n# Helper function to run async tests\ndef run_async_test(test_func):\n \"\"\"Helper to run async test functions.\"\"\"\n return asyncio.run(test_func())\n\n\nif __name__ == \"__main__\":\n unittest.main(verbosity=2)\n" }, { "path": "tests/test_utils.py", "content": "\"\"\"\nTests for utility functions\n\"\"\"\n\nfrom utils import check_token_limit, estimate_tokens, read_file_content, read_files\n\n\nclass TestFileUtils:\n \"\"\"Test file reading utilities\"\"\"\n\n def test_read_file_content_success(self, project_path):\n \"\"\"Test successful file reading\"\"\"\n test_file = project_path / \"test.py\"\n test_file.write_text(\"def hello():\\n return 'world'\", encoding=\"utf-8\")\n\n content, tokens = read_file_content(str(test_file))\n assert \"--- BEGIN FILE:\" in content\n assert \"--- END FILE:\" in content\n assert \"def hello():\" in content\n assert \"return 'world'\" in content\n assert tokens > 0 # Should have estimated tokens\n\n def test_read_file_content_not_found(self, project_path):\n \"\"\"Test reading non-existent file\"\"\"\n # Use a non-existent file within the project path\n nonexistent = project_path / \"nonexistent\" / \"file.py\"\n content, tokens = read_file_content(str(nonexistent))\n assert \"--- FILE NOT FOUND:\" in content\n assert \"Error: File does not exist\" in content\n assert tokens > 0\n\n def test_read_file_content_dangerous_files_blocked(self):\n \"\"\"Test that dangerous system files are blocked\"\"\"\n # /etc/passwd should be blocked as it's under /etc (dangerous path)\n content, tokens = read_file_content(\"/etc/passwd\")\n assert \"--- ERROR ACCESSING FILE:\" in content\n assert \"Access to system directory denied\" in content\n assert tokens > 0\n\n def test_read_file_content_relative_path_rejected(self):\n \"\"\"Test that relative paths are rejected\"\"\"\n # Try to use a relative path\n content, tokens = read_file_content(\"./some/relative/path.py\")\n assert \"--- ERROR ACCESSING FILE:\" in content\n assert \"Relative paths are not supported\" in content\n assert tokens > 0\n\n def test_read_file_content_directory(self, project_path):\n \"\"\"Test reading a directory\"\"\"\n content, tokens = read_file_content(str(project_path))\n assert \"--- NOT A FILE:\" in content\n assert \"Error: Path is not a file\" in content\n assert tokens > 0\n\n def test_read_files_multiple(self, project_path):\n \"\"\"Test reading multiple files\"\"\"\n file1 = project_path / \"file1.py\"\n file1.write_text(\"print('file1')\", encoding=\"utf-8\")\n file2 = project_path / \"file2.py\"\n file2.write_text(\"print('file2')\", encoding=\"utf-8\")\n\n content = read_files([str(file1), str(file2)])\n\n assert \"--- BEGIN FILE:\" in content\n assert \"file1.py\" in content\n assert \"file2.py\" in content\n assert \"print('file1')\" in content\n assert \"print('file2')\" in content\n\n # Check that both files are included\n assert \"file1.py\" in content and \"file2.py\" in content\n\n def test_read_files_with_code(self):\n \"\"\"Test reading with direct code\"\"\"\n code = \"def test():\\n pass\"\n content = read_files([], code)\n\n assert \"--- BEGIN DIRECT CODE ---\" in content\n assert \"--- END DIRECT CODE ---\" in content\n assert code in content\n\n # Check that direct code is included\n assert code in content\n\n def test_read_files_directory_support(self, project_path):\n \"\"\"Test reading all files from a directory\"\"\"\n # Create directory structure\n (project_path / \"file1.py\").write_text(\"print('file1')\", encoding=\"utf-8\")\n (project_path / \"file2.js\").write_text(\"console.log('file2')\", encoding=\"utf-8\")\n (project_path / \"readme.md\").write_text(\"# README\", encoding=\"utf-8\")\n\n # Create subdirectory\n subdir = project_path / \"src\"\n subdir.mkdir()\n (subdir / \"module.py\").write_text(\"class Module: pass\", encoding=\"utf-8\")\n\n # Create hidden file (should be skipped)\n (project_path / \".hidden\").write_text(\"secret\", encoding=\"utf-8\")\n\n # Read the directory\n content = read_files([str(project_path)])\n\n # Check files are included\n assert \"file1.py\" in content\n assert \"file2.js\" in content\n assert \"readme.md\" in content\n # Handle both forward and backslashes for cross-platform compatibility\n assert \"module.py\" in content\n assert \"class Module: pass\" in content\n\n # Check content\n assert \"print('file1')\" in content\n assert \"console.log('file2')\" in content\n assert \"# README\" in content\n assert \"class Module: pass\" in content\n\n # Hidden file should not be included\n assert \".hidden\" not in content\n assert \"secret\" not in content\n\n # Check that all files are included\n assert all(filename in content for filename in [\"file1.py\", \"file2.js\", \"readme.md\", \"module.py\"])\n\n def test_read_files_mixed_paths(self, project_path):\n \"\"\"Test reading mix of files and directories\"\"\"\n # Create files\n file1 = project_path / \"direct.py\"\n file1.write_text(\"# Direct file\", encoding=\"utf-8\")\n\n # Create directory with files\n subdir = project_path / \"subdir\"\n subdir.mkdir()\n (subdir / \"sub1.py\").write_text(\"# Sub file 1\", encoding=\"utf-8\")\n (subdir / \"sub2.py\").write_text(\"# Sub file 2\", encoding=\"utf-8\")\n\n # Read mix of direct file and directory\n content = read_files([str(file1), str(subdir)])\n\n assert \"direct.py\" in content\n assert \"sub1.py\" in content\n assert \"sub2.py\" in content\n assert \"# Direct file\" in content\n assert \"# Sub file 1\" in content\n assert \"# Sub file 2\" in content\n\n # Check that all files are included\n assert all(filename in content for filename in [\"direct.py\", \"sub1.py\", \"sub2.py\"])\n\n def test_read_files_token_limit(self, project_path):\n \"\"\"Test token limit handling\"\"\"\n # Create files with known token counts\n # ~250 tokens each (1000 chars)\n large_content = \"x\" * 1000\n\n for i in range(5):\n (project_path / f\"file{i}.txt\").write_text(large_content, encoding=\"utf-8\")\n\n # Read with small token limit (should skip some files)\n # Reserve 50k tokens, limit to 51k total = 1k available\n # Each file ~250 tokens, so should read ~3-4 files\n content = read_files([str(project_path)], max_tokens=51_000)\n\n # Check that token limit handling is present\n assert \"--- SKIPPED FILES (TOKEN LIMIT) ---\" in content\n\n # Count how many files were read\n read_count = content.count(\"--- BEGIN FILE:\")\n assert 2 <= read_count <= 4 # Should read some but not all\n\n def test_read_files_large_file(self, project_path):\n \"\"\"Test handling of large files\"\"\"\n # Create a file larger than max_size (1MB)\n large_file = project_path / \"large.txt\"\n large_file.write_text(\"x\" * 2_000_000, encoding=\"utf-8\") # 2MB\n\n content = read_files([str(large_file)])\n\n assert \"--- FILE TOO LARGE:\" in content\n assert \"2,000,000 bytes\" in content\n # File too large message should be present\n assert \"--- FILE TOO LARGE:\" in content\n\n def test_read_files_file_extensions(self, project_path):\n \"\"\"Test file extension filtering\"\"\"\n # Create various file types\n (project_path / \"code.py\").write_text(\"python\", encoding=\"utf-8\")\n (project_path / \"style.css\").write_text(\"css\", encoding=\"utf-8\")\n (project_path / \"binary.exe\").write_text(\"exe\", encoding=\"utf-8\")\n (project_path / \"image.jpg\").write_text(\"jpg\", encoding=\"utf-8\")\n\n content = read_files([str(project_path)])\n\n # Code files should be included\n assert \"code.py\" in content\n assert \"style.css\" in content\n\n # Binary files should not be included (not in CODE_EXTENSIONS)\n assert \"binary.exe\" not in content\n assert \"image.jpg\" not in content\n\n\nclass TestTokenUtils:\n \"\"\"Test token counting utilities\"\"\"\n\n def test_estimate_tokens(self):\n \"\"\"Test token estimation\"\"\"\n # Rough estimate: 1 token β‰ˆ 4 characters\n text = \"a\" * 400 # 400 characters\n assert estimate_tokens(text) == 100\n\n def test_check_token_limit_within(self):\n \"\"\"Test token limit check - within limit\"\"\"\n text = \"a\" * 4000 # 1000 tokens\n within_limit, tokens = check_token_limit(text)\n assert within_limit is True\n assert tokens == 1000\n\n def test_check_token_limit_exceeded(self):\n \"\"\"Test token limit check - exceeded\"\"\"\n text = \"a\" * 5_000_000 # 1.25M tokens\n within_limit, tokens = check_token_limit(text)\n assert within_limit is False\n assert tokens == 1_250_000\n" }, { "path": "tests/test_uvx_resource_packaging.py", "content": "\"\"\"Tests for uvx path resolution functionality.\"\"\"\n\nimport json\nimport tempfile\nfrom pathlib import Path\nfrom unittest.mock import patch\n\nfrom providers.registries.openrouter import OpenRouterModelRegistry\n\n\nclass TestUvxPathResolution:\n \"\"\"Test uvx path resolution for OpenRouter model registry.\"\"\"\n\n def test_normal_operation(self):\n \"\"\"Test that normal operation works in development environment.\"\"\"\n registry = OpenRouterModelRegistry()\n assert len(registry.list_models()) > 0\n assert len(registry.list_aliases()) > 0\n\n def test_config_path_resolution(self):\n \"\"\"Test that the config path resolution finds the config file in multiple locations.\"\"\"\n # Check that the config file exists in the development location\n config_file = Path(__file__).parent.parent / \"conf\" / \"openrouter_models.json\"\n assert config_file.exists(), \"Config file should exist in conf/openrouter_models.json\"\n\n # Test that a registry can find and use the config\n registry = OpenRouterModelRegistry()\n\n # When using resources, config_path is None; when using file system, it should exist\n if registry.use_resources:\n assert registry.config_path is None, \"When using resources, config_path should be None\"\n else:\n assert registry.config_path.exists(), \"When using file system, config path should exist\"\n\n assert len(registry.list_models()) > 0, \"Registry should load models from config\"\n\n def test_explicit_config_path_override(self):\n \"\"\"Test that explicit config path works correctly.\"\"\"\n config_path = Path(__file__).parent.parent / \"conf\" / \"openrouter_models.json\"\n\n registry = OpenRouterModelRegistry(config_path=str(config_path))\n\n # Should use the provided file path\n assert registry.config_path == config_path\n assert len(registry.list_models()) > 0\n\n def test_environment_variable_override(self):\n \"\"\"Test that CUSTOM_MODELS_CONFIG_PATH environment variable works.\"\"\"\n config_path = Path(__file__).parent.parent / \"conf\" / \"openrouter_models.json\"\n\n with patch.dict(\"os.environ\", {\"OPENROUTER_MODELS_CONFIG_PATH\": str(config_path)}):\n registry = OpenRouterModelRegistry()\n\n # Should use environment path\n assert registry.config_path == config_path\n assert len(registry.list_models()) > 0\n\n @patch(\"providers.registries.base.importlib.resources.files\")\n def test_multiple_path_fallback(self, mock_files):\n \"\"\"Test that file-system fallback works when resource loading fails.\"\"\"\n mock_files.side_effect = Exception(\"Resource loading failed\")\n\n with tempfile.TemporaryDirectory() as tmpdir:\n temp_dir = Path(tmpdir)\n conf_dir = temp_dir / \"conf\"\n conf_dir.mkdir(parents=True, exist_ok=True)\n config_path = conf_dir / \"openrouter_models.json\"\n config_path.write_text(\n json.dumps(\n {\n \"models\": [\n {\n \"model_name\": \"test/model\",\n \"aliases\": [\"testalias\"],\n \"context_window\": 1024,\n \"max_output_tokens\": 512,\n }\n ]\n },\n indent=2,\n )\n )\n\n original_exists = Path.exists\n\n def fake_exists(path_self):\n if str(path_self).endswith(\"conf/openrouter_models.json\") and path_self != config_path:\n return False\n if path_self == config_path:\n return True\n return original_exists(path_self)\n\n with patch(\"pathlib.Path.cwd\", return_value=temp_dir), patch(\"pathlib.Path.exists\", fake_exists):\n registry = OpenRouterModelRegistry()\n\n assert not registry.use_resources\n assert registry.config_path == config_path\n assert \"test/model\" in registry.list_models()\n\n def test_missing_config_handling(self):\n \"\"\"Test behavior when config file is missing.\"\"\"\n # Use a non-existent path\n with patch.dict(\"os.environ\", {}, clear=True):\n registry = OpenRouterModelRegistry(config_path=\"/nonexistent/path/config.json\")\n\n # Should gracefully handle missing config\n assert len(registry.list_models()) == 0\n assert len(registry.list_aliases()) == 0\n\n def test_resource_loading_success(self):\n \"\"\"Test successful resource loading via importlib.resources.\"\"\"\n # Just test that the registry works normally in our environment\n # This validates the resource loading mechanism indirectly\n registry = OpenRouterModelRegistry()\n\n # Should load successfully using either resources or file system fallback\n assert len(registry.list_models()) > 0\n assert len(registry.list_aliases()) > 0\n\n def test_use_resources_attribute(self):\n \"\"\"Test that the use_resources attribute is properly set.\"\"\"\n registry = OpenRouterModelRegistry()\n\n # Should have the use_resources attribute\n assert hasattr(registry, \"use_resources\")\n assert isinstance(registry.use_resources, bool)\n" }, { "path": "tests/test_uvx_support.py", "content": "\"\"\"\nTest cases for uvx support and environment handling.\n\"\"\"\n\nimport os\nimport sys\nimport tempfile\nfrom pathlib import Path\nfrom unittest import mock\n\nimport pytest\n\n\nclass TestUvxEnvironmentHandling:\n \"\"\"Test uvx-specific environment handling features.\"\"\"\n\n def test_dotenv_import_success(self):\n \"\"\"Test that dotenv is imported successfully when available.\"\"\"\n # Mock successful dotenv import\n mock_load = mock.MagicMock()\n mock_values = mock.MagicMock(return_value={})\n fake_dotenv = mock.MagicMock(load_dotenv=mock_load, dotenv_values=mock_values)\n\n with mock.patch.dict(\"sys.modules\", {\"dotenv\": fake_dotenv}):\n if \"utils.env\" in sys.modules:\n del sys.modules[\"utils.env\"]\n if \"server\" in sys.modules:\n del sys.modules[\"server\"]\n\n import importlib\n\n import utils.env as env_config\n\n with tempfile.NamedTemporaryFile(\"w\", delete=False) as tmp_env:\n temp_env_path = Path(tmp_env.name)\n tmp_env.write(\"PAL_MCP_FORCE_ENV_OVERRIDE=false\\n\")\n\n try:\n importlib.reload(env_config)\n env_config._ENV_PATH = temp_env_path\n env_config.reload_env()\n import server # noqa: F401\n\n assert mock_load.call_count >= 1\n _, kwargs = mock_load.call_args\n assert \"dotenv_path\" in kwargs\n finally:\n temp_env_path.unlink(missing_ok=True)\n\n def test_dotenv_import_failure_graceful_handling(self):\n \"\"\"Test that ImportError for dotenv is handled gracefully (uvx scenario).\"\"\"\n # Mock only the dotenv import to fail\n original_import = __builtins__[\"__import__\"]\n\n def mock_import(name, *args, **kwargs):\n if name == \"dotenv\":\n raise ImportError(\"No module named 'dotenv'\")\n return original_import(name, *args, **kwargs)\n\n with mock.patch(\"builtins.__import__\", side_effect=mock_import):\n # This should not raise an exception when trying to import dotenv\n try:\n from dotenv import load_dotenv # noqa: F401\n\n pytest.fail(\"Should have raised ImportError for dotenv\")\n except ImportError:\n # Expected behavior - ImportError should be caught gracefully in server.py\n pass\n\n def test_env_file_path_resolution(self):\n \"\"\"Test that .env file path is correctly resolved relative to server.py.\"\"\"\n import server\n\n # Test that the server module correctly resolves .env path\n script_dir = Path(server.__file__).parent\n expected_env_file = script_dir / \".env\"\n\n # The logic should create a path relative to server.py\n assert expected_env_file.name == \".env\"\n assert expected_env_file.parent == script_dir\n\n def test_environment_variables_still_work_without_dotenv(self):\n \"\"\"Test that environment variables work even when dotenv is not available.\"\"\"\n # Set a test environment variable\n test_key = \"TEST_PAL_MCP_VAR\"\n test_value = \"test_value_123\"\n\n with mock.patch.dict(os.environ, {test_key: test_value}):\n # Environment variable should still be accessible regardless of dotenv\n assert os.getenv(test_key) == test_value\n\n def test_dotenv_graceful_fallback_behavior(self):\n \"\"\"Test the actual graceful fallback behavior in server module.\"\"\"\n # Test that server module handles missing dotenv gracefully\n # This is tested by the fact that the server can be imported even if dotenv fails\n import server\n\n # If we can import server, the graceful handling works\n assert hasattr(server, \"run\")\n\n # Test that environment variables still work\n test_key = \"TEST_FALLBACK_VAR\"\n test_value = \"fallback_test_123\"\n\n with mock.patch.dict(os.environ, {test_key: test_value}):\n assert os.getenv(test_key) == test_value\n\n\nclass TestUvxProjectConfiguration:\n \"\"\"Test uvx-specific project configuration features.\"\"\"\n\n def test_pyproject_toml_has_required_uvx_fields(self):\n \"\"\"Test that pyproject.toml has all required fields for uvx support.\"\"\"\n try:\n import tomllib\n except ImportError:\n # tomllib is only available in Python 3.11+\n # For older versions, use tomli or skip the test\n try:\n import tomli as tomllib\n except ImportError:\n pytest.skip(\"tomllib/tomli not available for TOML parsing\")\n\n pyproject_path = Path(__file__).parent.parent / \"pyproject.toml\"\n assert pyproject_path.exists(), \"pyproject.toml should exist\"\n\n with open(pyproject_path, \"rb\") as f:\n pyproject_data = tomllib.load(f)\n\n # Check required uvx fields\n assert \"project\" in pyproject_data\n project = pyproject_data[\"project\"]\n\n # Essential fields for uvx\n assert \"name\" in project\n assert project[\"name\"] == \"pal-mcp-server\"\n assert \"dependencies\" in project\n assert \"requires-python\" in project\n\n # Script entry point for uvx\n assert \"scripts\" in project\n assert \"pal-mcp-server\" in project[\"scripts\"]\n assert project[\"scripts\"][\"pal-mcp-server\"] == \"server:run\"\n\n def test_pyproject_dependencies_match_requirements(self):\n \"\"\"Test that pyproject.toml dependencies align with requirements.txt.\"\"\"\n try:\n import tomllib\n except ImportError:\n # tomllib is only available in Python 3.11+\n try:\n import tomli as tomllib\n except ImportError:\n pytest.skip(\"tomllib/tomli not available for TOML parsing\")\n\n # Read pyproject.toml\n pyproject_path = Path(__file__).parent.parent / \"pyproject.toml\"\n with open(pyproject_path, \"rb\") as f:\n pyproject_data = tomllib.load(f)\n\n pyproject_deps = set(pyproject_data[\"project\"][\"dependencies\"])\n\n # Read requirements.txt\n requirements_path = Path(__file__).parent.parent / \"requirements.txt\"\n if requirements_path.exists():\n # Note: We primarily validate pyproject.toml has core dependencies\n # requirements.txt might have additional dev dependencies\n\n # Core dependencies should be present in both\n core_packages = {\"mcp\", \"openai\", \"google-genai\", \"pydantic\", \"python-dotenv\"}\n\n for pkg in core_packages:\n pyproject_has = any(pkg in dep for dep in pyproject_deps)\n\n assert pyproject_has, f\"{pkg} should be in pyproject.toml dependencies\"\n # requirements.txt might have additional dev dependencies\n\n def test_uvx_entry_point_callable(self):\n \"\"\"Test that the uvx entry point (server:run) is callable.\"\"\"\n import server\n\n # The entry point should reference a callable function\n assert hasattr(server, \"run\"), \"server module should have a 'run' function\"\n assert callable(server.run), \"server.run should be callable\"\n" }, { "path": "tests/test_workflow_file_embedding.py", "content": "\"\"\"\nUnit tests for workflow file embedding behavior\n\nTests the critical file embedding logic for workflow tools:\n- Intermediate steps: Only reference file names (save Claude's context)\n- Final steps: Embed full file content for expert analysis\n\"\"\"\n\nimport os\nimport tempfile\nfrom unittest.mock import Mock, patch\n\nimport pytest\n\nfrom tools.workflow.workflow_mixin import BaseWorkflowMixin\n\n\nclass TestWorkflowFileEmbedding:\n \"\"\"Test workflow file embedding behavior\"\"\"\n\n def setup_method(self):\n \"\"\"Set up test fixtures\"\"\"\n # Create a mock workflow tool\n self.mock_tool = Mock()\n self.mock_tool.get_name.return_value = \"test_workflow\"\n\n # Bind the methods we want to test - use bound methods\n self.mock_tool._should_embed_files_in_workflow_step = (\n BaseWorkflowMixin._should_embed_files_in_workflow_step.__get__(self.mock_tool)\n )\n self.mock_tool._force_embed_files_for_expert_analysis = (\n BaseWorkflowMixin._force_embed_files_for_expert_analysis.__get__(self.mock_tool)\n )\n\n # Create test files\n self.test_files = []\n for i in range(2):\n fd, path = tempfile.mkstemp(suffix=f\"_test_{i}.py\")\n with os.fdopen(fd, \"w\") as f:\n f.write(f\"# Test file {i}\\nprint('hello world {i}')\\n\")\n self.test_files.append(path)\n\n def teardown_method(self):\n \"\"\"Clean up test files\"\"\"\n for file_path in self.test_files:\n try:\n os.unlink(file_path)\n except OSError:\n pass\n\n def test_intermediate_step_no_embedding(self):\n \"\"\"Test that intermediate steps only reference files, don't embed\"\"\"\n # Intermediate step: step_number=1, next_step_required=True\n step_number = 1\n continuation_id = None # New conversation\n is_final_step = False # next_step_required=True\n\n should_embed = self.mock_tool._should_embed_files_in_workflow_step(step_number, continuation_id, is_final_step)\n\n assert should_embed is False, \"Intermediate steps should NOT embed files\"\n\n def test_intermediate_step_with_continuation_no_embedding(self):\n \"\"\"Test that intermediate steps with continuation only reference files\"\"\"\n # Intermediate step with continuation: step_number=2, next_step_required=True\n step_number = 2\n continuation_id = \"test-thread-123\" # Continuing conversation\n is_final_step = False # next_step_required=True\n\n should_embed = self.mock_tool._should_embed_files_in_workflow_step(step_number, continuation_id, is_final_step)\n\n assert should_embed is False, \"Intermediate steps with continuation should NOT embed files\"\n\n def test_final_step_embeds_files(self):\n \"\"\"Test that final steps embed full file content for expert analysis\"\"\"\n # Final step: any step_number, next_step_required=False\n step_number = 3\n continuation_id = \"test-thread-123\"\n is_final_step = True # next_step_required=False\n\n should_embed = self.mock_tool._should_embed_files_in_workflow_step(step_number, continuation_id, is_final_step)\n\n assert should_embed is True, \"Final steps SHOULD embed files for expert analysis\"\n\n def test_final_step_new_conversation_embeds_files(self):\n \"\"\"Test that final steps in new conversations embed files\"\"\"\n # Final step in new conversation (rare but possible): step_number=1, next_step_required=False\n step_number = 1\n continuation_id = None # New conversation\n is_final_step = True # next_step_required=False (one-step workflow)\n\n should_embed = self.mock_tool._should_embed_files_in_workflow_step(step_number, continuation_id, is_final_step)\n\n assert should_embed is True, \"Final steps in new conversations SHOULD embed files\"\n\n @patch(\"utils.file_utils.read_files\")\n @patch(\"utils.file_utils.expand_paths\")\n @patch(\"utils.conversation_memory.get_thread\")\n @patch(\"utils.conversation_memory.get_conversation_file_list\")\n def test_comprehensive_file_collection_for_expert_analysis(\n self, mock_get_conversation_file_list, mock_get_thread, mock_expand_paths, mock_read_files\n ):\n \"\"\"Test that expert analysis collects relevant files from current workflow and conversation history\"\"\"\n # Setup test files for different sources\n conversation_files = [self.test_files[0]] # relevant_files from conversation history\n current_relevant_files = [\n self.test_files[0],\n self.test_files[1],\n ] # current step's relevant_files (overlap with conversation)\n\n # Setup mocks\n mock_thread_context = Mock()\n mock_get_thread.return_value = mock_thread_context\n mock_get_conversation_file_list.return_value = conversation_files\n mock_expand_paths.return_value = self.test_files\n mock_read_files.return_value = \"# File content\\nprint('test')\"\n\n # Mock model context for token allocation\n mock_model_context = Mock()\n mock_token_allocation = Mock()\n mock_token_allocation.file_tokens = 100000\n mock_model_context.calculate_token_allocation.return_value = mock_token_allocation\n\n # Set up the tool methods and state\n self.mock_tool.get_current_model_context.return_value = mock_model_context\n self.mock_tool.wants_line_numbers_by_default.return_value = True\n self.mock_tool.get_name.return_value = \"test_workflow\"\n\n # Set up consolidated findings\n self.mock_tool.consolidated_findings = Mock()\n self.mock_tool.consolidated_findings.relevant_files = set(current_relevant_files)\n\n # Set up current arguments with continuation\n self.mock_tool._current_arguments = {\"continuation_id\": \"test-thread-123\"}\n self.mock_tool.get_current_arguments.return_value = {\"continuation_id\": \"test-thread-123\"}\n\n # Bind the method we want to test\n self.mock_tool._prepare_files_for_expert_analysis = (\n BaseWorkflowMixin._prepare_files_for_expert_analysis.__get__(self.mock_tool)\n )\n self.mock_tool._force_embed_files_for_expert_analysis = (\n BaseWorkflowMixin._force_embed_files_for_expert_analysis.__get__(self.mock_tool)\n )\n\n # Call the method\n file_content = self.mock_tool._prepare_files_for_expert_analysis()\n\n # Verify it collected files from conversation history\n mock_get_thread.assert_called_once_with(\"test-thread-123\")\n mock_get_conversation_file_list.assert_called_once_with(mock_thread_context)\n\n # Verify it called read_files with ALL unique relevant files\n # Should include files from: conversation_files + current_relevant_files\n # But deduplicated: [test_files[0], test_files[1]] (unique set)\n expected_unique_files = list(set(conversation_files + current_relevant_files))\n\n # The actual call will be with whatever files were collected and deduplicated\n mock_read_files.assert_called_once()\n call_args = mock_read_files.call_args\n called_files = call_args[0][0] # First positional argument\n\n # Verify all expected files are included\n for expected_file in expected_unique_files:\n assert expected_file in called_files, f\"Expected file {expected_file} not found in {called_files}\"\n\n # Verify return value\n assert file_content == \"# File content\\nprint('test')\"\n\n @patch(\"utils.file_utils.read_files\")\n @patch(\"utils.file_utils.expand_paths\")\n def test_force_embed_bypasses_conversation_history(self, mock_expand_paths, mock_read_files):\n \"\"\"Test that _force_embed_files_for_expert_analysis bypasses conversation filtering\"\"\"\n # Setup mocks\n mock_expand_paths.return_value = self.test_files\n mock_read_files.return_value = \"# File content\\nprint('test')\"\n\n # Mock model context for token allocation\n mock_model_context = Mock()\n mock_token_allocation = Mock()\n mock_token_allocation.file_tokens = 100000\n mock_model_context.calculate_token_allocation.return_value = mock_token_allocation\n\n # Set up the tool methods\n self.mock_tool.get_current_model_context.return_value = mock_model_context\n self.mock_tool.wants_line_numbers_by_default.return_value = True\n\n # Call the method\n file_content, processed_files = self.mock_tool._force_embed_files_for_expert_analysis(self.test_files)\n\n # Verify it called read_files directly (bypassing conversation history filtering)\n mock_read_files.assert_called_once_with(\n self.test_files,\n max_tokens=100000,\n reserve_tokens=1000,\n include_line_numbers=True,\n )\n\n # Verify it expanded paths to get individual files\n mock_expand_paths.assert_called_once_with(self.test_files)\n\n # Verify return values\n assert file_content == \"# File content\\nprint('test')\"\n assert processed_files == self.test_files\n\n def test_embedding_decision_logic_comprehensive(self):\n \"\"\"Comprehensive test of the embedding decision logic\"\"\"\n test_cases = [\n # (step_number, continuation_id, is_final_step, expected_embed, description)\n (1, None, False, False, \"Step 1 new conversation, intermediate\"),\n (1, None, True, True, \"Step 1 new conversation, final (one-step workflow)\"),\n (2, \"thread-123\", False, False, \"Step 2 with continuation, intermediate\"),\n (2, \"thread-123\", True, True, \"Step 2 with continuation, final\"),\n (5, \"thread-456\", False, False, \"Step 5 with continuation, intermediate\"),\n (5, \"thread-456\", True, True, \"Step 5 with continuation, final\"),\n ]\n\n for step_number, continuation_id, is_final_step, expected_embed, description in test_cases:\n should_embed = self.mock_tool._should_embed_files_in_workflow_step(\n step_number, continuation_id, is_final_step\n )\n\n assert should_embed == expected_embed, f\"Failed for: {description}\"\n\n\nif __name__ == \"__main__\":\n pytest.main([__file__])\n" }, { "path": "tests/test_workflow_metadata.py", "content": "\"\"\"\nTests for workflow tool metadata functionality.\n\nThis test ensures that workflow tools include metadata (provider_used and model_used)\nin their responses, similar to regular tools, for consistent tracking across all tool types.\n\"\"\"\n\nimport json\nimport os\n\nimport pytest\n\nfrom providers.registry import ModelProviderRegistry\nfrom providers.shared import ProviderType\nfrom tools.debug import DebugIssueTool\nfrom tools.shared.exceptions import ToolExecutionError\n\n\nclass TestWorkflowMetadata:\n \"\"\"Test cases for workflow tool metadata functionality.\"\"\"\n\n def setup_method(self):\n \"\"\"Set up clean state before each test.\"\"\"\n # Clear restriction service cache\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n # Clear provider registry\n registry = ModelProviderRegistry()\n registry._providers.clear()\n registry._initialized_providers.clear()\n\n def teardown_method(self):\n \"\"\"Clean up after each test.\"\"\"\n # Clear restriction service cache\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n @pytest.mark.no_mock_provider\n def test_workflow_metadata_in_response(self):\n \"\"\"\n Test that workflow tools include metadata in their responses.\n\n This test verifies that workflow tools (like debug) include provider_used\n and model_used metadata in their responses, ensuring consistency with\n regular tools for tracking purposes.\n \"\"\"\n # Save original environment\n original_env = {}\n for key in [\n \"GEMINI_API_KEY\",\n \"OPENAI_API_KEY\",\n \"XAI_API_KEY\",\n \"OPENROUTER_API_KEY\",\n \"OPENROUTER_ALLOWED_MODELS\",\n ]:\n original_env[key] = os.environ.get(key)\n\n try:\n # Set up test environment with OpenRouter API key\n os.environ.pop(\"GEMINI_API_KEY\", None)\n os.environ.pop(\"OPENAI_API_KEY\", None)\n os.environ.pop(\"XAI_API_KEY\", None)\n os.environ.pop(\"OPENROUTER_ALLOWED_MODELS\", None) # Clear any restrictions\n os.environ[\"OPENROUTER_API_KEY\"] = \"test-openrouter-key\"\n\n # Register OpenRouter provider\n from providers.openrouter import OpenRouterProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENROUTER, OpenRouterProvider)\n\n # Create debug tool\n debug_tool = DebugIssueTool()\n\n # Create mock model context like server.py does\n from utils.model_context import ModelContext\n\n model_name = \"flash\"\n model_context = ModelContext(model_name)\n\n # Create arguments with model context (like server.py provides)\n arguments = {\n \"step\": \"Investigating the test issue to check metadata functionality\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": False, # Final step to trigger completion\n \"findings\": \"Initial findings for test\",\n \"model\": model_name,\n \"confidence\": \"high\",\n \"_model_context\": model_context,\n \"_resolved_model_name\": model_name,\n }\n\n # Execute the workflow tool\n import asyncio\n\n result = asyncio.run(debug_tool.execute_workflow(arguments))\n\n # Parse the JSON response\n assert len(result) == 1\n response_text = result[0].text\n response_data = json.loads(response_text)\n\n # Verify metadata is present\n assert \"metadata\" in response_data, \"Workflow response should include metadata\"\n metadata = response_data[\"metadata\"]\n\n # Verify required metadata fields\n assert \"tool_name\" in metadata, \"Metadata should include tool_name\"\n assert \"model_used\" in metadata, \"Metadata should include model_used\"\n assert \"provider_used\" in metadata, \"Metadata should include provider_used\"\n\n # Verify metadata values\n assert metadata[\"tool_name\"] == \"debug\", \"tool_name should be 'debug'\"\n assert metadata[\"model_used\"] == model_name, f\"model_used should be '{model_name}'\"\n assert metadata[\"provider_used\"] == \"openrouter\", \"provider_used should be 'openrouter'\"\n\n finally:\n # Restore original environment\n for key, value in original_env.items():\n if value is None:\n os.environ.pop(key, None)\n else:\n os.environ[key] = value\n\n @pytest.mark.no_mock_provider\n def test_workflow_metadata_in_error_response(self):\n \"\"\"\n Test that workflow tools include metadata even in error responses.\n \"\"\"\n # Save original environment\n original_env = {}\n for key in [\n \"GEMINI_API_KEY\",\n \"OPENAI_API_KEY\",\n \"XAI_API_KEY\",\n \"OPENROUTER_API_KEY\",\n \"OPENROUTER_ALLOWED_MODELS\",\n ]:\n original_env[key] = os.environ.get(key)\n\n try:\n # Set up test environment with OpenRouter API key\n os.environ.pop(\"GEMINI_API_KEY\", None)\n os.environ.pop(\"OPENAI_API_KEY\", None)\n os.environ.pop(\"XAI_API_KEY\", None)\n os.environ.pop(\"OPENROUTER_ALLOWED_MODELS\", None) # Clear any restrictions\n os.environ[\"OPENROUTER_API_KEY\"] = \"test-openrouter-key\"\n\n # Register OpenRouter provider\n from providers.openrouter import OpenRouterProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENROUTER, OpenRouterProvider)\n\n # Create debug tool\n debug_tool = DebugIssueTool()\n\n # Create arguments with invalid data to trigger error\n model_name = \"flash\"\n arguments = {\n \"step\": \"Test step\",\n \"step_number\": \"invalid\", # This should cause an error during validation\n \"_resolved_model_name\": model_name,\n }\n\n # Execute the workflow tool - should fail gracefully\n import asyncio\n\n with pytest.raises(ToolExecutionError) as exc_info:\n asyncio.run(debug_tool.execute(arguments))\n\n response_data = json.loads(exc_info.value.payload)\n\n # Verify it's an error response with metadata\n assert \"status\" in response_data\n assert \"error\" in response_data or \"content\" in response_data\n assert \"metadata\" in response_data, \"Error responses should include metadata\"\n\n metadata = response_data[\"metadata\"]\n assert \"tool_name\" in metadata, \"Error metadata should include tool_name\"\n assert metadata[\"tool_name\"] == \"debug\", \"tool_name should be 'debug'\"\n\n finally:\n # Restore original environment\n for key, value in original_env.items():\n if value is None:\n os.environ.pop(key, None)\n else:\n os.environ[key] = value\n\n @pytest.mark.no_mock_provider\n def test_workflow_metadata_fallback_handling(self):\n \"\"\"\n Test that workflow tools handle metadata gracefully when model context is missing.\n \"\"\"\n # Save original environment\n original_env = {}\n for key in [\"OPENROUTER_ALLOWED_MODELS\"]:\n original_env[key] = os.environ.get(key)\n\n try:\n # Clear any restrictions\n os.environ.pop(\"OPENROUTER_ALLOWED_MODELS\", None)\n\n # Create debug tool\n debug_tool = DebugIssueTool()\n\n # Create arguments without model context (fallback scenario)\n arguments = {\n \"step\": \"Test step without model context\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Test findings\",\n \"model\": \"flash\",\n \"confidence\": \"low\",\n # No _model_context or _resolved_model_name\n }\n\n # Execute the workflow tool\n import asyncio\n\n result = asyncio.run(debug_tool.execute_workflow(arguments))\n\n # Parse the JSON response\n assert len(result) == 1\n response_text = result[0].text\n response_data = json.loads(response_text)\n\n # Verify metadata is still present with fallback values\n assert \"metadata\" in response_data, \"Workflow response should include metadata even in fallback\"\n metadata = response_data[\"metadata\"]\n\n # Verify fallback metadata\n assert \"tool_name\" in metadata, \"Fallback metadata should include tool_name\"\n assert \"model_used\" in metadata, \"Fallback metadata should include model_used\"\n assert \"provider_used\" in metadata, \"Fallback metadata should include provider_used\"\n\n assert metadata[\"tool_name\"] == \"debug\", \"tool_name should be 'debug'\"\n assert metadata[\"model_used\"] == \"flash\", \"model_used should be from request\"\n assert metadata[\"provider_used\"] == \"unknown\", \"provider_used should be 'unknown' in fallback\"\n\n finally:\n # Restore original environment\n for key, value in original_env.items():\n if value is None:\n os.environ.pop(key, None)\n else:\n os.environ[key] = value\n\n @pytest.mark.no_mock_provider\n def test_workflow_metadata_preserves_existing_response_fields(self):\n \"\"\"\n Test that adding metadata doesn't interfere with existing workflow response fields.\n \"\"\"\n # Save original environment\n original_env = {}\n for key in [\n \"GEMINI_API_KEY\",\n \"OPENAI_API_KEY\",\n \"XAI_API_KEY\",\n \"OPENROUTER_API_KEY\",\n \"OPENROUTER_ALLOWED_MODELS\",\n ]:\n original_env[key] = os.environ.get(key)\n\n try:\n # Set up test environment\n os.environ.pop(\"GEMINI_API_KEY\", None)\n os.environ.pop(\"OPENAI_API_KEY\", None)\n os.environ.pop(\"XAI_API_KEY\", None)\n os.environ.pop(\"OPENROUTER_ALLOWED_MODELS\", None) # Clear any restrictions\n os.environ[\"OPENROUTER_API_KEY\"] = \"test-openrouter-key\"\n\n # Register OpenRouter provider\n from providers.openrouter import OpenRouterProvider\n\n ModelProviderRegistry.register_provider(ProviderType.OPENROUTER, OpenRouterProvider)\n\n # Create debug tool\n debug_tool = DebugIssueTool()\n\n # Create mock model context\n from utils.model_context import ModelContext\n\n model_name = \"flash\"\n model_context = ModelContext(model_name)\n\n # Create arguments for intermediate step\n arguments = {\n \"step\": \"Testing intermediate step for metadata preservation\",\n \"step_number\": 1,\n \"total_steps\": 3,\n \"next_step_required\": True, # Intermediate step\n \"findings\": \"Intermediate findings\",\n \"model\": model_name,\n \"confidence\": \"medium\",\n \"_model_context\": model_context,\n \"_resolved_model_name\": model_name,\n }\n\n # Execute the workflow tool\n import asyncio\n\n result = asyncio.run(debug_tool.execute_workflow(arguments))\n\n # Parse the JSON response\n assert len(result) == 1\n response_text = result[0].text\n response_data = json.loads(response_text)\n\n # Verify standard workflow fields are preserved\n assert \"status\" in response_data, \"Standard workflow status should be preserved\"\n assert \"step_number\" in response_data, \"Standard workflow step_number should be preserved\"\n assert \"total_steps\" in response_data, \"Standard workflow total_steps should be preserved\"\n assert \"next_step_required\" in response_data, \"Standard workflow next_step_required should be preserved\"\n\n # Verify metadata was added without breaking existing fields\n assert \"metadata\" in response_data, \"Metadata should be added\"\n metadata = response_data[\"metadata\"]\n assert metadata[\"tool_name\"] == \"debug\"\n assert metadata[\"model_used\"] == model_name\n assert metadata[\"provider_used\"] == \"openrouter\"\n\n # Verify specific intermediate step fields\n assert response_data[\"next_step_required\"] is True, \"next_step_required should be preserved\"\n assert response_data[\"step_number\"] == 1, \"step_number should be preserved\"\n\n finally:\n # Restore original environment\n for key, value in original_env.items():\n if value is None:\n os.environ.pop(key, None)\n else:\n os.environ[key] = value\n" }, { "path": "tests/test_workflow_prompt_size_validation_simple.py", "content": "\"\"\"Integration tests for workflow step size validation.\n\nThese tests exercise the debug workflow tool end-to-end to ensure that step size\nvalidation operates on the real execution path rather than mocked helpers.\n\"\"\"\n\nfrom __future__ import annotations\n\nimport json\n\nimport pytest\n\nfrom config import MCP_PROMPT_SIZE_LIMIT\nfrom tools.debug import DebugIssueTool\nfrom tools.shared.exceptions import ToolExecutionError\n\n\ndef build_debug_arguments(**overrides) -> dict[str, object]:\n \"\"\"Create a minimal set of workflow arguments for DebugIssueTool.\"\"\"\n\n base_arguments: dict[str, object] = {\n \"step\": \"Investigate the authentication issue in the login module\",\n \"step_number\": 1,\n \"total_steps\": 3,\n \"next_step_required\": True,\n \"findings\": \"Initial observations about the login failure\",\n \"files_checked\": [],\n \"relevant_files\": [],\n \"relevant_context\": [],\n \"issues_found\": [],\n \"confidence\": \"low\",\n \"use_assistant_model\": False,\n # WorkflowRequest accepts optional fields; leave hypothesis/continuation unset\n }\n\n base_arguments.update(overrides)\n return base_arguments\n\n\n@pytest.mark.asyncio\nasync def test_workflow_tool_accepts_normal_step_content() -> None:\n \"\"\"Verify a typical step executes through the real workflow path.\"\"\"\n\n tool = DebugIssueTool()\n arguments = build_debug_arguments()\n\n responses = await tool.execute(arguments)\n assert len(responses) == 1\n\n payload = json.loads(responses[0].text)\n assert payload[\"status\"] == \"pause_for_investigation\"\n assert payload[\"step_number\"] == 1\n assert \"error\" not in payload\n\n\n@pytest.mark.asyncio\nasync def test_workflow_tool_rejects_oversized_step_with_guidance() -> None:\n \"\"\"Large step content should trigger the size safeguard with helpful guidance.\"\"\"\n\n oversized_step = \"Investigate this issue: \" + (\"A\" * (MCP_PROMPT_SIZE_LIMIT + 1000))\n tool = DebugIssueTool()\n arguments = build_debug_arguments(step=oversized_step)\n\n with pytest.raises(ToolExecutionError) as exc_info:\n await tool.execute(arguments)\n\n output_payload = json.loads(exc_info.value.payload)\n\n assert output_payload[\"status\"] == \"resend_prompt\"\n assert output_payload[\"metadata\"][\"prompt_size\"] > MCP_PROMPT_SIZE_LIMIT\n\n guidance = output_payload[\"content\"].lower()\n assert \"shorter instructions\" in guidance\n assert \"file paths\" in guidance\n" }, { "path": "tests/test_workflow_utf8.py", "content": "\"\"\"\nUnit tests to validate UTF-8 encoding in workflow tools\nand the generation of properly encoded JSON responses.\n\"\"\"\n\nimport json\nimport os\nimport unittest\nfrom unittest.mock import AsyncMock, Mock, patch\n\nfrom tools.analyze import AnalyzeTool\nfrom tools.codereview import CodeReviewTool\nfrom tools.debug import DebugIssueTool\n\n\nclass TestWorkflowToolsUTF8(unittest.IsolatedAsyncioTestCase):\n \"\"\"Tests for UTF-8 encoding in workflow tools.\"\"\"\n\n def setUp(self):\n \"\"\"Test setup.\"\"\"\n self.original_locale = os.getenv(\"LOCALE\")\n # Default to French for tests\n os.environ[\"LOCALE\"] = \"fr-FR\"\n\n def tearDown(self):\n \"\"\"Cleanup after tests.\"\"\"\n if self.original_locale is not None:\n os.environ[\"LOCALE\"] = self.original_locale\n else:\n os.environ.pop(\"LOCALE\", None)\n\n def test_workflow_json_response_structure(self):\n \"\"\"Test the structure of JSON responses from workflow tools.\"\"\"\n # Mock response with UTF-8 characters\n test_response = {\n \"status\": \"pause_for_analysis\",\n \"step_number\": 1,\n \"total_steps\": 3,\n \"next_step_required\": True,\n \"findings\": \"Code analysis reveals performance issues πŸ”\",\n \"files_checked\": [\"/src/main.py\"],\n \"relevant_files\": [\"/src/main.py\"],\n \"issues_found\": [{\"severity\": \"high\", \"description\": \"Function too complex - refactoring needed\"}],\n \"investigation_required\": True,\n \"required_actions\": [\"Review code dependencies\", \"Analyze architectural patterns\"],\n }\n\n # Test JSON serialization with ensure_ascii=False\n json_str = json.dumps(test_response, indent=2, ensure_ascii=False)\n\n # Check UTF-8 characters are preserved\n self.assertIn(\"πŸ”\", json_str)\n # No escaped characters\n self.assertNotIn(\"\\\\u\", json_str)\n\n # Test parsing\n parsed = json.loads(json_str)\n self.assertEqual(parsed[\"findings\"], test_response[\"findings\"])\n self.assertEqual(len(parsed[\"issues_found\"]), 1)\n\n @patch(\"tools.shared.base_tool.BaseTool.get_model_provider\")\n @patch(\"utils.model_context.ModelContext\")\n async def test_analyze_tool_utf8_response(self, mock_model_context, mock_get_provider):\n \"\"\"Test that the analyze tool returns correct UTF-8 responses.\"\"\"\n\n # Mock ModelContext to bypass model validation\n mock_context_instance = Mock()\n\n # Mock token allocation for file processing\n mock_token_allocation = Mock()\n mock_token_allocation.file_tokens = 1000\n mock_token_allocation.total_tokens = 2000\n mock_context_instance.calculate_token_allocation.return_value = mock_token_allocation\n\n # Mock provider with more complete setup (same as codereview test)\n mock_provider = Mock()\n mock_provider.get_provider_type.return_value = Mock(value=\"test\")\n mock_provider.get_capabilities.return_value = Mock(supports_extended_thinking=False)\n mock_provider.generate_content = AsyncMock(\n return_value=Mock(\n content=json.dumps(\n {\n \"status\": \"analysis_complete\",\n \"raw_analysis\": \"Analysis completed successfully\",\n },\n ensure_ascii=False,\n ),\n usage={},\n model_name=\"flash\",\n metadata={},\n )\n )\n # Use the same provider for both contexts\n mock_get_provider.return_value = mock_provider\n mock_context_instance.provider = mock_provider\n mock_context_instance.capabilities = Mock(supports_extended_thinking=False)\n mock_model_context.return_value = mock_context_instance\n\n # Test the tool\n analyze_tool = AnalyzeTool()\n result = await analyze_tool.execute(\n {\n \"step\": \"Analyze system architecture to identify issues\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Starting architectural analysis of Python code\",\n \"relevant_files\": [\"/test/main.py\"],\n \"model\": \"flash\",\n }\n )\n\n # Checks\n self.assertIsNotNone(result)\n self.assertEqual(len(result), 1)\n\n # Parse the response - must be valid UTF-8 JSON\n response_text = result[0].text\n response_data = json.loads(response_text)\n\n # Structure checks\n self.assertIn(\"status\", response_data)\n\n # Check that the French instruction was added\n # The mock provider's generate_content should be called\n mock_provider.generate_content.assert_called()\n # The call was successful, which means our fix worked\n\n @patch(\"tools.shared.base_tool.BaseTool.get_model_provider\")\n async def test_codereview_tool_french_findings(self, mock_get_provider):\n \"\"\"Test that the codereview tool produces findings in French.\"\"\"\n # Mock with analysis in French\n mock_provider = Mock()\n mock_provider.get_provider_type.return_value = Mock(value=\"test\")\n mock_provider.get_capabilities.return_value = Mock(supports_extended_thinking=False)\n mock_provider.generate_content = AsyncMock(\n return_value=Mock(\n content=json.dumps(\n {\n \"status\": \"analysis_complete\",\n \"raw_analysis\": \"\"\"\nπŸ”΄ CRITIQUE: Aucun problΓ¨me critique trouvΓ©.\n\n🟠 Γ‰LEVΓ‰: Fichier example.py:42 - Fonction trop complexe\nβ†’ ProblΓ¨me: La fonction process_data() contient trop de responsabilitΓ©s\nβ†’ Solution: DΓ©composer en fonctions plus petites et spΓ©cialisΓ©es\n\n🟑 MOYEN: Gestion d'erreurs insuffisante\nβ†’ ProblΓ¨me: Plusieurs fonctions n'ont pas de gestion d'erreurs appropriΓ©e\nβ†’ Solution: Ajouter des try-catch et validation des paramΓ¨tres\n\nβœ… Points positifs:\nβ€’ Code bien commentΓ© et lisible\nβ€’ Nomenclature cohΓ©rente\nβ€’ Tests unitaires prΓ©sents\n\"\"\",\n },\n ensure_ascii=False,\n ),\n usage={},\n model_name=\"test-model\",\n metadata={},\n )\n )\n mock_get_provider.return_value = mock_provider\n\n # Test the tool\n codereview_tool = CodeReviewTool()\n result = await codereview_tool.execute(\n {\n \"step\": \"Complete review of Python code\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Code review complete\",\n \"relevant_files\": [\"/test/example.py\"],\n \"model\": \"test-model\",\n }\n )\n\n # Checks\n self.assertIsNotNone(result)\n response_text = result[0].text\n response_data = json.loads(response_text)\n\n # Check UTF-8 characters in analysis\n if \"expert_analysis\" in response_data:\n analysis = response_data[\"expert_analysis\"][\"raw_analysis\"]\n # Check for French characters\n self.assertIn(\"Γ‰LEVΓ‰\", analysis)\n self.assertIn(\"problΓ¨me\", analysis)\n self.assertIn(\"spΓ©cialisΓ©es\", analysis)\n self.assertIn(\"appropriΓ©e\", analysis)\n self.assertIn(\"paramΓ¨tres\", analysis)\n self.assertIn(\"prΓ©sents\", analysis)\n # Check for emojis\n self.assertIn(\"πŸ”΄\", analysis)\n self.assertIn(\"🟠\", analysis)\n self.assertIn(\"🟑\", analysis)\n self.assertIn(\"βœ…\", analysis)\n\n @patch(\"tools.shared.base_tool.BaseTool.get_model_provider\")\n async def test_debug_tool_french_error_analysis(self, mock_get_provider):\n \"\"\"Test that the debug tool analyzes errors in French.\"\"\"\n # Mock provider\n mock_provider = Mock()\n mock_provider.get_provider_type.return_value = Mock(value=\"test\")\n mock_provider.get_capabilities.return_value = Mock(supports_extended_thinking=False)\n mock_provider.generate_content = AsyncMock(\n return_value=Mock(\n content=json.dumps(\n {\n \"status\": \"pause_for_investigation\",\n \"step_number\": 1,\n \"total_steps\": 2,\n \"next_step_required\": True,\n \"findings\": (\n \"Erreur analysΓ©e: variable 'donnΓ©es' non dΓ©finie. \" \"Cause probable: import manquant.\"\n ),\n \"files_checked\": [\"/src/data_processor.py\"],\n \"relevant_files\": [\"/src/data_processor.py\"],\n \"hypothesis\": (\"Variable 'donnΓ©es' not defined - missing import\"),\n \"confidence\": \"medium\",\n \"investigation_status\": \"in_progress\",\n \"error_analysis\": (\"L'erreur concerne la variable 'donnΓ©es' qui \" \"n'est pas dΓ©finie.\"),\n },\n ensure_ascii=False,\n ),\n usage={},\n model_name=\"test-model\",\n metadata={},\n )\n )\n mock_get_provider.return_value = mock_provider\n\n # Test the debug tool\n debug_tool = DebugIssueTool()\n result = await debug_tool.execute(\n {\n \"step\": \"Analyze NameError in data processing file\",\n \"step_number\": 1,\n \"total_steps\": 1,\n \"next_step_required\": False,\n \"findings\": \"Error detected during script execution\",\n \"files_checked\": [\"/src/data_processor.py\"],\n \"relevant_files\": [\"/src/data_processor.py\"],\n \"hypothesis\": (\"Variable 'donnΓ©es' not defined - missing import\"),\n \"confidence\": \"medium\",\n \"model\": \"test-model\",\n }\n )\n\n # Checks\n self.assertIsNotNone(result)\n response_text = result[0].text\n response_data = json.loads(response_text)\n\n # Check response structure\n self.assertIn(\"status\", response_data)\n self.assertIn(\"investigation_status\", response_data)\n\n # Check that UTF-8 characters are preserved\n response_str = json.dumps(response_data, ensure_ascii=False)\n self.assertIn(\"donnΓ©es\", response_str)\n\n def test_utf8_emoji_preservation_in_workflow_responses(self):\n \"\"\"Test that emojis are preserved in workflow tool responses.\"\"\"\n # Mock workflow response with various emojis\n test_data = {\n \"status\": \"analysis_complete\",\n \"severity_indicators\": {\n \"critical\": \"πŸ”΄\",\n \"high\": \"🟠\",\n \"medium\": \"🟑\",\n \"low\": \"🟒\",\n \"success\": \"βœ…\",\n \"error\": \"❌\",\n \"warning\": \"⚠️\",\n },\n \"progress\": \"Analysis completed πŸŽ‰\",\n \"recommendations\": [\n \"Optimize performance πŸš€\",\n \"Improve documentation πŸ“š\",\n \"Add unit tests πŸ§ͺ\",\n ],\n }\n\n # Test JSON encoding with ensure_ascii=False\n json_str = json.dumps(test_data, ensure_ascii=False, indent=2)\n\n # Check emojis are preserved\n self.assertIn(\"πŸ”΄\", json_str)\n self.assertIn(\"🟠\", json_str)\n self.assertIn(\"🟑\", json_str)\n self.assertIn(\"🟒\", json_str)\n self.assertIn(\"βœ…\", json_str)\n self.assertIn(\"❌\", json_str)\n self.assertIn(\"⚠️\", json_str)\n self.assertIn(\"πŸŽ‰\", json_str)\n self.assertIn(\"πŸš€\", json_str)\n self.assertIn(\"πŸ“š\", json_str)\n self.assertIn(\"πŸ§ͺ\", json_str)\n\n # No escaped Unicode\n self.assertNotIn(\"\\\\u\", json_str)\n\n # Test parsing preserves emojis\n parsed = json.loads(json_str)\n self.assertEqual(parsed[\"severity_indicators\"][\"critical\"], \"πŸ”΄\")\n self.assertEqual(parsed[\"progress\"], \"Analysis completed πŸŽ‰\")\n\n\nif __name__ == \"__main__\":\n unittest.main(verbosity=2)\n" }, { "path": "tests/test_xai_provider.py", "content": "\"\"\"Tests for X.AI provider implementation.\"\"\"\n\nimport os\nfrom unittest.mock import MagicMock, patch\n\nimport pytest\n\nfrom providers.shared import ProviderType\nfrom providers.xai import XAIModelProvider\n\n\nclass TestXAIProvider:\n \"\"\"Test X.AI provider functionality.\"\"\"\n\n def setup_method(self):\n \"\"\"Set up clean state before each test.\"\"\"\n # Clear restriction service cache before each test\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n def teardown_method(self):\n \"\"\"Clean up after each test to avoid singleton issues.\"\"\"\n # Clear restriction service cache after each test\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n @patch.dict(os.environ, {\"XAI_API_KEY\": \"test-key\"})\n def test_initialization(self):\n \"\"\"Test provider initialization.\"\"\"\n provider = XAIModelProvider(\"test-key\")\n assert provider.api_key == \"test-key\"\n assert provider.get_provider_type() == ProviderType.XAI\n assert provider.base_url == \"https://api.x.ai/v1\"\n\n def test_initialization_with_custom_url(self):\n \"\"\"Test provider initialization with custom base URL.\"\"\"\n provider = XAIModelProvider(\"test-key\", base_url=\"https://custom.x.ai/v1\")\n assert provider.api_key == \"test-key\"\n assert provider.base_url == \"https://custom.x.ai/v1\"\n\n def test_model_validation(self):\n \"\"\"Test model name validation.\"\"\"\n provider = XAIModelProvider(\"test-key\")\n\n # Test valid models\n assert provider.validate_model_name(\"grok-4\") is True\n assert provider.validate_model_name(\"grok4\") is True\n assert provider.validate_model_name(\"grok\") is True\n assert provider.validate_model_name(\"grok-4.1-fast\") is True\n assert provider.validate_model_name(\"grok-4.1-fast-reasoning\") is True\n assert provider.validate_model_name(\"grok-4.1-fast-reasoning-latest\") is True\n assert provider.validate_model_name(\"grok-4.1-fast\") is True\n assert provider.validate_model_name(\"grok-4.1-fast-reasoning\") is True\n assert provider.validate_model_name(\"grok-4.1-fast-reasoning-latest\") is True\n\n # Test invalid model\n assert provider.validate_model_name(\"invalid-model\") is False\n assert provider.validate_model_name(\"gpt-4\") is False\n assert provider.validate_model_name(\"gemini-pro\") is False\n assert provider.validate_model_name(\"grok-3\") is False\n assert provider.validate_model_name(\"grok-3-fast\") is False\n assert provider.validate_model_name(\"grokfast\") is False\n\n def test_resolve_model_name(self):\n \"\"\"Test model name resolution.\"\"\"\n provider = XAIModelProvider(\"test-key\")\n\n # Test shorthand resolution\n assert provider._resolve_model_name(\"grok\") == \"grok-4\"\n assert provider._resolve_model_name(\"grok4\") == \"grok-4\"\n assert provider._resolve_model_name(\"grok-4.1-fast-reasoning\") == \"grok-4-1-fast-reasoning\"\n assert provider._resolve_model_name(\"grok-4.1-fast-reasoning-latest\") == \"grok-4-1-fast-reasoning\"\n\n # Test full name passthrough\n assert provider._resolve_model_name(\"grok-4\") == \"grok-4\"\n assert provider._resolve_model_name(\"grok-4.1-fast\") == \"grok-4-1-fast-reasoning\"\n\n def test_get_capabilities_grok4(self):\n \"\"\"Test getting model capabilities for GROK-4.\"\"\"\n provider = XAIModelProvider(\"test-key\")\n\n capabilities = provider.get_capabilities(\"grok-4\")\n assert capabilities.model_name == \"grok-4\"\n assert capabilities.friendly_name == \"X.AI (Grok 4)\"\n assert capabilities.context_window == 256_000\n assert capabilities.provider == ProviderType.XAI\n assert capabilities.supports_extended_thinking is True\n assert capabilities.supports_system_prompts is True\n assert capabilities.supports_streaming is True\n assert capabilities.supports_function_calling is True\n assert capabilities.supports_json_mode is True\n assert capabilities.supports_images is True\n\n # Test temperature range\n assert capabilities.temperature_constraint.min_temp == 0.0\n assert capabilities.temperature_constraint.max_temp == 2.0\n assert capabilities.temperature_constraint.default_temp == 0.3\n\n def test_get_capabilities_grok4_1_fast(self):\n \"\"\"Test getting model capabilities for GROK-4.1 Fast Reasoning.\"\"\"\n provider = XAIModelProvider(\"test-key\")\n\n capabilities = provider.get_capabilities(\"grok-4.1-fast\")\n assert capabilities.model_name == \"grok-4-1-fast-reasoning\"\n assert capabilities.friendly_name == \"X.AI (Grok 4.1 Fast Reasoning)\"\n assert capabilities.context_window == 2_000_000\n assert capabilities.provider == ProviderType.XAI\n assert capabilities.supports_extended_thinking is True\n assert capabilities.supports_function_calling is True\n assert capabilities.supports_json_mode is True\n assert capabilities.supports_images is True\n\n def test_get_capabilities_with_shorthand(self):\n \"\"\"Test getting model capabilities with shorthand.\"\"\"\n provider = XAIModelProvider(\"test-key\")\n\n capabilities = provider.get_capabilities(\"grok\")\n assert capabilities.model_name == \"grok-4\" # Should resolve to full name\n assert capabilities.context_window == 256_000\n\n capabilities_fast = provider.get_capabilities(\"grok-4.1-fast-reasoning\")\n assert capabilities_fast.model_name == \"grok-4-1-fast-reasoning\" # Should resolve to full name\n\n def test_unsupported_model_capabilities(self):\n \"\"\"Test error handling for unsupported models.\"\"\"\n provider = XAIModelProvider(\"test-key\")\n\n with pytest.raises(ValueError, match=\"Unsupported model 'invalid-model' for provider xai\"):\n provider.get_capabilities(\"invalid-model\")\n\n def test_extended_thinking_flags(self):\n \"\"\"X.AI capabilities should expose extended thinking support correctly.\"\"\"\n provider = XAIModelProvider(\"test-key\")\n\n thinking_aliases = [\n \"grok-4\",\n \"grok\",\n \"grok4\",\n \"grok-4.1-fast\",\n \"grok-4.1-fast-reasoning\",\n \"grok-4.1-fast-reasoning-latest\",\n ]\n for alias in thinking_aliases:\n assert provider.get_capabilities(alias).supports_extended_thinking is True\n\n def test_provider_type(self):\n \"\"\"Test provider type identification.\"\"\"\n provider = XAIModelProvider(\"test-key\")\n assert provider.get_provider_type() == ProviderType.XAI\n\n @patch.dict(os.environ, {\"XAI_ALLOWED_MODELS\": \"grok-4\"})\n def test_model_restrictions(self):\n \"\"\"Test model restrictions functionality.\"\"\"\n # Clear cached restriction service\n import utils.model_restrictions\n from providers.registry import ModelProviderRegistry\n\n utils.model_restrictions._restriction_service = None\n ModelProviderRegistry.reset_for_testing()\n\n provider = XAIModelProvider(\"test-key\")\n\n # grok-4 should be allowed (including alias)\n assert provider.validate_model_name(\"grok-4\") is True\n assert provider.validate_model_name(\"grok\") is True\n\n # grok-4.1-fast should be blocked by restrictions\n assert provider.validate_model_name(\"grok-4.1-fast\") is False\n assert provider.validate_model_name(\"grok-4.1-fast-reasoning\") is False\n\n @patch.dict(os.environ, {\"XAI_ALLOWED_MODELS\": \"grok-4.1-fast-reasoning\"})\n def test_multiple_model_restrictions(self):\n \"\"\"Restrictions should allow aliases for Grok 4.1 Fast.\"\"\"\n # Clear cached restriction service\n import utils.model_restrictions\n from providers.registry import ModelProviderRegistry\n\n utils.model_restrictions._restriction_service = None\n ModelProviderRegistry.reset_for_testing()\n\n provider = XAIModelProvider(\"test-key\")\n\n # Alias should be allowed (resolves to grok-4.1-fast)\n assert provider.validate_model_name(\"grok-4.1-fast-reasoning\") is True\n\n # Canonical name is not allowed unless explicitly listed\n assert provider.validate_model_name(\"grok-4.1-fast\") is False\n\n # grok-4 should NOT be allowed\n assert provider.validate_model_name(\"grok-4\") is False\n\n @patch.dict(os.environ, {\"XAI_ALLOWED_MODELS\": \"grok,grok-4,grok-4.1-fast,grok-4-1-fast-reasoning\"})\n def test_both_shorthand_and_full_name_allowed(self):\n \"\"\"Test that aliases and canonical names can be allowed together.\"\"\"\n # Clear cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n provider = XAIModelProvider(\"test-key\")\n\n # Both shorthand and full name should be allowed when explicitly listed\n assert provider.validate_model_name(\"grok\") is True # Alias explicitly allowed\n assert provider.validate_model_name(\"grok-4\") is True # Canonical name explicitly allowed\n assert provider.validate_model_name(\"grok-4.1-fast\") is True # Alias explicitly allowed\n assert provider.validate_model_name(\"grok-4-1-fast-reasoning\") is True # Canonical name explicitly allowed\n\n @patch.dict(os.environ, {\"XAI_ALLOWED_MODELS\": \"\"})\n def test_empty_restrictions_allows_all(self):\n \"\"\"Test that empty restrictions allow all models.\"\"\"\n # Clear cached restriction service\n import utils.model_restrictions\n\n utils.model_restrictions._restriction_service = None\n\n provider = XAIModelProvider(\"test-key\")\n\n assert provider.validate_model_name(\"grok-4\") is True\n assert provider.validate_model_name(\"grok-4.1-fast\") is True\n assert provider.validate_model_name(\"grok-4.1-fast-reasoning\") is True\n assert provider.validate_model_name(\"grok\") is True\n assert provider.validate_model_name(\"grok4\") is True\n\n def test_friendly_name(self):\n \"\"\"Test friendly name constant.\"\"\"\n provider = XAIModelProvider(\"test-key\")\n assert provider.FRIENDLY_NAME == \"X.AI\"\n\n capabilities = provider.get_capabilities(\"grok-4\")\n assert capabilities.friendly_name == \"X.AI (Grok 4)\"\n\n def test_supported_models_structure(self):\n \"\"\"Test that MODEL_CAPABILITIES has the correct structure.\"\"\"\n provider = XAIModelProvider(\"test-key\")\n\n # Check that all expected base models are present\n assert \"grok-4\" in provider.MODEL_CAPABILITIES\n assert \"grok-4-1-fast-reasoning\" in provider.MODEL_CAPABILITIES\n\n # Check model configs have required fields\n from providers.shared import ModelCapabilities\n\n grok4_config = provider.MODEL_CAPABILITIES[\"grok-4\"]\n assert isinstance(grok4_config, ModelCapabilities)\n assert hasattr(grok4_config, \"context_window\")\n assert hasattr(grok4_config, \"supports_extended_thinking\")\n assert hasattr(grok4_config, \"aliases\")\n assert grok4_config.context_window == 256_000\n assert grok4_config.supports_extended_thinking is True\n\n # Check aliases are correctly structured\n assert \"grok\" in grok4_config.aliases\n assert \"grok-4\" in grok4_config.aliases\n assert \"grok4\" in grok4_config.aliases\n\n grok41fast_config = provider.MODEL_CAPABILITIES[\"grok-4-1-fast-reasoning\"]\n assert grok41fast_config.context_window == 2_000_000\n assert grok41fast_config.supports_extended_thinking is True\n assert \"grok-4.1-fast\" in grok41fast_config.aliases\n assert \"grok-4.1-fast-reasoning\" in grok41fast_config.aliases\n\n @patch(\"providers.openai_compatible.OpenAI\")\n def test_generate_content_resolves_alias_before_api_call(self, mock_openai_class):\n \"\"\"Test that generate_content resolves aliases before making API calls.\n\n This is the CRITICAL test that ensures aliases like 'grok' get resolved\n to 'grok-4' before being sent to X.AI API.\n \"\"\"\n # Set up mock OpenAI client\n mock_client = MagicMock()\n mock_openai_class.return_value = mock_client\n\n # Mock the completion response\n mock_response = MagicMock()\n mock_response.choices = [MagicMock()]\n mock_response.choices[0].message.content = \"Test response\"\n mock_response.choices[0].finish_reason = \"stop\"\n mock_response.model = \"grok-4\" # API returns the resolved model name\n mock_response.id = \"test-id\"\n mock_response.created = 1234567890\n mock_response.usage = MagicMock()\n mock_response.usage.prompt_tokens = 10\n mock_response.usage.completion_tokens = 5\n mock_response.usage.total_tokens = 15\n\n mock_client.chat.completions.create.return_value = mock_response\n\n provider = XAIModelProvider(\"test-key\")\n\n # Call generate_content with alias 'grok'\n result = provider.generate_content(\n prompt=\"Test prompt\", model_name=\"grok\", temperature=0.7 # This should be resolved to \"grok-4\"\n )\n\n # Verify the API was called with the RESOLVED model name\n mock_client.chat.completions.create.assert_called_once()\n call_kwargs = mock_client.chat.completions.create.call_args[1]\n\n # CRITICAL ASSERTION: The API should receive \"grok-4\", not \"grok\"\n assert call_kwargs[\"model\"] == \"grok-4\", f\"Expected 'grok-4' but API received '{call_kwargs['model']}'\"\n\n # Verify other parameters\n assert call_kwargs[\"temperature\"] == 0.7\n assert len(call_kwargs[\"messages\"]) == 1\n assert call_kwargs[\"messages\"][0][\"role\"] == \"user\"\n assert call_kwargs[\"messages\"][0][\"content\"] == \"Test prompt\"\n\n # Verify response\n assert result.content == \"Test response\"\n assert result.model_name == \"grok-4\" # Should be the resolved name\n\n @patch(\"providers.openai_compatible.OpenAI\")\n def test_generate_content_other_aliases(self, mock_openai_class):\n \"\"\"Test other alias resolutions in generate_content.\"\"\"\n from unittest.mock import MagicMock\n\n # Set up mock\n mock_client = MagicMock()\n mock_openai_class.return_value = mock_client\n mock_response = MagicMock()\n mock_response.choices = [MagicMock()]\n mock_response.choices[0].message.content = \"Test response\"\n mock_response.choices[0].finish_reason = \"stop\"\n mock_response.usage = MagicMock()\n mock_response.usage.prompt_tokens = 10\n mock_response.usage.completion_tokens = 5\n mock_response.usage.total_tokens = 15\n mock_client.chat.completions.create.return_value = mock_response\n\n provider = XAIModelProvider(\"test-key\")\n\n # Test grok4 -> grok-4\n mock_response.model = \"grok-4\"\n provider.generate_content(prompt=\"Test\", model_name=\"grok4\", temperature=0.7)\n call_kwargs = mock_client.chat.completions.create.call_args[1]\n assert call_kwargs[\"model\"] == \"grok-4\"\n\n # Test grok-4 -> grok-4\n provider.generate_content(prompt=\"Test\", model_name=\"grok-4\", temperature=0.7)\n call_kwargs = mock_client.chat.completions.create.call_args[1]\n assert call_kwargs[\"model\"] == \"grok-4\"\n\n # Test grok-4.1-fast-reasoning -> grok-4-1-fast-reasoning\n mock_response.model = \"grok-4-1-fast-reasoning\"\n provider.generate_content(prompt=\"Test\", model_name=\"grok-4.1-fast-reasoning\", temperature=0.7)\n call_kwargs = mock_client.chat.completions.create.call_args[1]\n assert call_kwargs[\"model\"] == \"grok-4-1-fast-reasoning\"\n\n # Test grok-4.1-fast -> grok-4-1-fast-reasoning\n provider.generate_content(prompt=\"Test\", model_name=\"grok-4.1-fast\", temperature=0.7)\n call_kwargs = mock_client.chat.completions.create.call_args[1]\n assert call_kwargs[\"model\"] == \"grok-4-1-fast-reasoning\"\n" }, { "path": "tests/transport_helpers.py", "content": "\"\"\"Helper functions for HTTP transport injection in tests.\"\"\"\n\nfrom tests.http_transport_recorder import TransportFactory\n\n\ndef inject_transport(monkeypatch, cassette_path: str):\n \"\"\"Inject HTTP transport into OpenAICompatibleProvider for testing.\n\n This helper simplifies the monkey patching pattern used across tests\n to inject custom HTTP transports for recording/replaying API calls.\n\n Also ensures OpenAI provider is properly registered for tests that need it.\n\n Args:\n monkeypatch: pytest monkeypatch fixture\n cassette_path: Path to cassette file for recording/replay\n\n Returns:\n The created transport instance\n\n Example:\n transport = inject_transport(monkeypatch, \"path/to/cassette.json\")\n \"\"\"\n # Ensure OpenAI provider is registered - always needed for transport injection\n from providers.openai import OpenAIModelProvider\n from providers.registry import ModelProviderRegistry\n from providers.shared import ProviderType\n\n # Always register OpenAI provider for transport tests (API key might be dummy)\n ModelProviderRegistry.register_provider(ProviderType.OPENAI, OpenAIModelProvider)\n\n # Create transport\n transport = TransportFactory.create_transport(str(cassette_path))\n\n # Inject transport using the established pattern\n from providers.openai_compatible import OpenAICompatibleProvider\n\n original_client_property = OpenAICompatibleProvider.client\n\n def patched_client_getter(self):\n if self._client is None:\n self._test_transport = transport\n return original_client_property.fget(self)\n\n monkeypatch.setattr(OpenAICompatibleProvider, \"client\", property(patched_client_getter))\n\n return transport\n" }, { "path": "tools/__init__.py", "content": "\"\"\"\nTool implementations for PAL MCP Server\n\"\"\"\n\nfrom .analyze import AnalyzeTool\nfrom .apilookup import LookupTool\nfrom .challenge import ChallengeTool\nfrom .chat import ChatTool\nfrom .clink import CLinkTool\nfrom .codereview import CodeReviewTool\nfrom .consensus import ConsensusTool\nfrom .debug import DebugIssueTool\nfrom .docgen import DocgenTool\nfrom .listmodels import ListModelsTool\nfrom .planner import PlannerTool\nfrom .precommit import PrecommitTool\nfrom .refactor import RefactorTool\nfrom .secaudit import SecauditTool\nfrom .testgen import TestGenTool\nfrom .thinkdeep import ThinkDeepTool\nfrom .tracer import TracerTool\nfrom .version import VersionTool\n\n__all__ = [\n \"ThinkDeepTool\",\n \"CodeReviewTool\",\n \"DebugIssueTool\",\n \"DocgenTool\",\n \"AnalyzeTool\",\n \"LookupTool\",\n \"ChatTool\",\n \"CLinkTool\",\n \"ConsensusTool\",\n \"ListModelsTool\",\n \"PlannerTool\",\n \"PrecommitTool\",\n \"ChallengeTool\",\n \"RefactorTool\",\n \"SecauditTool\",\n \"TestGenTool\",\n \"TracerTool\",\n \"VersionTool\",\n]\n" }, { "path": "tools/analyze.py", "content": "\"\"\"\nAnalyzeWorkflow tool - Step-by-step code analysis with systematic investigation\n\nThis tool provides a structured workflow for comprehensive code and file analysis.\nIt guides the CLI agent through systematic investigation steps with forced pauses between each step\nto ensure thorough code examination, pattern identification, and architectural assessment before proceeding.\nThe tool supports complex analysis scenarios including architectural review, performance analysis,\nsecurity assessment, and maintainability evaluation.\n\nKey features:\n- Step-by-step analysis workflow with progress tracking\n- Context-aware file embedding (references during investigation, full content for analysis)\n- Automatic pattern and insight tracking with categorization\n- Expert analysis integration with external models\n- Support for focused analysis (architecture, performance, security, quality)\n- Confidence-based workflow optimization\n\"\"\"\n\nimport logging\nfrom typing import TYPE_CHECKING, Any, Literal, Optional\n\nfrom pydantic import Field, model_validator\n\nif TYPE_CHECKING:\n from tools.models import ToolModelCategory\n\nfrom config import TEMPERATURE_ANALYTICAL\nfrom systemprompts import ANALYZE_PROMPT\nfrom tools.shared.base_models import WorkflowRequest\n\nfrom .workflow.base import WorkflowTool\n\nlogger = logging.getLogger(__name__)\n\n# Tool-specific field descriptions for analyze workflow\nANALYZE_WORKFLOW_FIELD_DESCRIPTIONS = {\n \"step\": (\n \"The analysis plan. Step 1: State your strategy, including how you will map the codebase structure, \"\n \"understand business logic, and assess code quality, performance implications, and architectural patterns. \"\n \"Later steps: Report findings and adapt the approach as new insights emerge.\"\n ),\n \"step_number\": (\n \"The index of the current step in the analysis sequence, beginning at 1. Each step should build upon or \"\n \"revise the previous one.\"\n ),\n \"total_steps\": (\n \"Your current estimate for how many steps will be needed to complete the analysis. \"\n \"Adjust as new findings emerge.\"\n ),\n \"next_step_required\": (\n \"Set to true if you plan to continue the investigation with another step. False means you believe the \"\n \"analysis is complete and ready for expert validation.\"\n ),\n \"findings\": (\n \"Summary of discoveries from this step, including architectural patterns, tech stack assessment, scalability characteristics, \"\n \"performance implications, maintainability factors, and strategic improvement opportunities. \"\n \"IMPORTANT: Document both strengths (good patterns, solid architecture) and concerns (tech debt, overengineering, unnecessary complexity). \"\n \"In later steps, confirm or update past findings with additional evidence.\"\n ),\n \"files_checked\": (\n \"List all files examined (absolute paths). Include even ruled-out files to track exploration path.\"\n ),\n \"relevant_files\": (\n \"Subset of files_checked directly relevant to analysis findings (absolute paths). Include files with \"\n \"significant patterns, architectural decisions, or strategic improvement opportunities.\"\n ),\n \"relevant_context\": (\n \"List methods/functions central to analysis findings, in 'ClassName.methodName' or 'functionName' format. \"\n \"Prioritize those demonstrating key patterns, architectural decisions, or improvement opportunities.\"\n ),\n \"images\": (\n \"Optional absolute paths to architecture diagrams or visual references that help with analysis context.\"\n ),\n \"confidence\": (\n \"Your confidence in the analysis: exploring, low, medium, high, very_high, almost_certain, or certain. \"\n \"'certain' indicates the analysis is complete and ready for validation.\"\n ),\n \"analysis_type\": \"Type of analysis to perform (architecture, performance, security, quality, general)\",\n \"output_format\": \"How to format the output (summary, detailed, actionable)\",\n}\n\n\nclass AnalyzeWorkflowRequest(WorkflowRequest):\n \"\"\"Request model for analyze workflow investigation steps\"\"\"\n\n # Required fields for each investigation step\n step: str = Field(..., description=ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"step\"])\n step_number: int = Field(..., description=ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"step_number\"])\n total_steps: int = Field(..., description=ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"total_steps\"])\n next_step_required: bool = Field(..., description=ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"next_step_required\"])\n\n # Investigation tracking fields\n findings: str = Field(..., description=ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"findings\"])\n files_checked: list[str] = Field(\n default_factory=list, description=ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"files_checked\"]\n )\n relevant_files: list[str] = Field(\n default_factory=list, description=ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_files\"]\n )\n relevant_context: list[str] = Field(\n default_factory=list, description=ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_context\"]\n )\n\n # Issues found during analysis (structured with severity)\n issues_found: list[dict] = Field(\n default_factory=list,\n description=\"Issues or concerns identified during analysis, each with severity level (critical, high, medium, low)\",\n )\n\n # Optional images for visual context\n images: Optional[list[str]] = Field(default=None, description=ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"images\"])\n\n # Analyze-specific fields (only used in step 1 to initialize)\n # Note: Use relevant_files field instead of files for consistency across workflow tools\n analysis_type: Optional[Literal[\"architecture\", \"performance\", \"security\", \"quality\", \"general\"]] = Field(\n \"general\", description=ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"analysis_type\"]\n )\n output_format: Optional[Literal[\"summary\", \"detailed\", \"actionable\"]] = Field(\n \"detailed\", description=ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"output_format\"]\n )\n\n # Keep thinking_mode from original analyze tool; temperature is inherited from WorkflowRequest\n\n @model_validator(mode=\"after\")\n def validate_step_one_requirements(self):\n \"\"\"Ensure step 1 has required relevant_files.\"\"\"\n if self.step_number == 1:\n if not self.relevant_files:\n raise ValueError(\"Step 1 requires 'relevant_files' field to specify files or directories to analyze\")\n return self\n\n\nclass AnalyzeTool(WorkflowTool):\n \"\"\"\n Analyze workflow tool for step-by-step code analysis and expert validation.\n\n This tool implements a structured analysis workflow that guides users through\n methodical investigation steps, ensuring thorough code examination, pattern identification,\n and architectural assessment before reaching conclusions. It supports complex analysis scenarios\n including architectural review, performance analysis, security assessment, and maintainability evaluation.\n \"\"\"\n\n def __init__(self):\n super().__init__()\n self.initial_request = None\n self.analysis_config = {}\n\n def get_name(self) -> str:\n return \"analyze\"\n\n def get_description(self) -> str:\n return (\n \"Performs comprehensive code analysis with systematic investigation and expert validation. \"\n \"Use for architecture, performance, maintainability, and pattern analysis. \"\n \"Guides through structured code review and strategic planning.\"\n )\n\n def get_system_prompt(self) -> str:\n return ANALYZE_PROMPT\n\n def get_default_temperature(self) -> float:\n return TEMPERATURE_ANALYTICAL\n\n def get_model_category(self) -> \"ToolModelCategory\":\n \"\"\"Analyze workflow requires thorough analysis and reasoning\"\"\"\n from tools.models import ToolModelCategory\n\n return ToolModelCategory.EXTENDED_REASONING\n\n def get_workflow_request_model(self):\n \"\"\"Return the analyze workflow-specific request model.\"\"\"\n return AnalyzeWorkflowRequest\n\n def get_input_schema(self) -> dict[str, Any]:\n \"\"\"Generate input schema using WorkflowSchemaBuilder with analyze-specific overrides.\"\"\"\n from .workflow.schema_builders import WorkflowSchemaBuilder\n\n # Fields to exclude from analyze workflow (inherited from WorkflowRequest but not used)\n excluded_fields = {\"hypothesis\", \"confidence\"}\n\n # Analyze workflow-specific field overrides\n analyze_field_overrides = {\n \"step\": {\n \"type\": \"string\",\n \"description\": ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"step\"],\n },\n \"step_number\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"step_number\"],\n },\n \"total_steps\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"total_steps\"],\n },\n \"next_step_required\": {\n \"type\": \"boolean\",\n \"description\": ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"next_step_required\"],\n },\n \"findings\": {\n \"type\": \"string\",\n \"description\": ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"findings\"],\n },\n \"files_checked\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"files_checked\"],\n },\n \"relevant_files\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_files\"],\n },\n \"confidence\": {\n \"type\": \"string\",\n \"enum\": [\"exploring\", \"low\", \"medium\", \"high\", \"very_high\", \"almost_certain\", \"certain\"],\n \"description\": ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"confidence\"],\n },\n \"images\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"images\"],\n },\n \"issues_found\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"object\"},\n \"description\": \"Issues or concerns identified during analysis, each with severity level (critical, high, medium, low)\",\n },\n \"analysis_type\": {\n \"type\": \"string\",\n \"enum\": [\"architecture\", \"performance\", \"security\", \"quality\", \"general\"],\n \"default\": \"general\",\n \"description\": ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"analysis_type\"],\n },\n \"output_format\": {\n \"type\": \"string\",\n \"enum\": [\"summary\", \"detailed\", \"actionable\"],\n \"default\": \"detailed\",\n \"description\": ANALYZE_WORKFLOW_FIELD_DESCRIPTIONS[\"output_format\"],\n },\n }\n\n # Use WorkflowSchemaBuilder with analyze-specific tool fields\n return WorkflowSchemaBuilder.build_schema(\n tool_specific_fields=analyze_field_overrides,\n model_field_schema=self.get_model_field_schema(),\n auto_mode=self.is_effective_auto_mode(),\n tool_name=self.get_name(),\n excluded_workflow_fields=list(excluded_fields),\n )\n\n def get_required_actions(\n self, step_number: int, confidence: str, findings: str, total_steps: int, request=None\n ) -> list[str]:\n \"\"\"Define required actions for each investigation phase.\"\"\"\n if step_number == 1:\n # Initial analysis investigation tasks\n return [\n \"Read and understand the code files specified for analysis\",\n \"Map the tech stack, frameworks, and overall architecture\",\n \"Identify the main components, modules, and their relationships\",\n \"Understand the business logic and intended functionality\",\n \"Examine architectural patterns and design decisions used\",\n \"Look for strengths, risks, and strategic improvement areas\",\n ]\n elif step_number < total_steps:\n # Need deeper investigation\n return [\n \"Examine specific architectural patterns and design decisions in detail\",\n \"Analyze scalability characteristics and performance implications\",\n \"Assess maintainability factors: module cohesion, coupling, tech debt\",\n \"Identify security posture and potential systemic vulnerabilities\",\n \"Look for overengineering, unnecessary complexity, or missing abstractions\",\n \"Evaluate how well the architecture serves business and scaling goals\",\n ]\n else:\n # Close to completion - need final verification\n return [\n \"Verify all significant architectural insights have been documented\",\n \"Confirm strategic improvement opportunities are comprehensively captured\",\n \"Ensure both strengths and risks are properly identified with evidence\",\n \"Validate that findings align with the analysis type and goals specified\",\n \"Check that recommendations are actionable and proportional to the codebase\",\n \"Confirm the analysis provides clear guidance for strategic decisions\",\n ]\n\n def should_call_expert_analysis(self, consolidated_findings, request=None) -> bool:\n \"\"\"\n Always call expert analysis for comprehensive validation.\n\n Analysis benefits from a second opinion to ensure completeness.\n \"\"\"\n # Check if user explicitly requested to skip assistant model\n if request and not self.get_request_use_assistant_model(request):\n return False\n\n # For analysis, we always want expert validation if we have any meaningful data\n return len(consolidated_findings.relevant_files) > 0 or len(consolidated_findings.findings) >= 1\n\n def prepare_expert_analysis_context(self, consolidated_findings) -> str:\n \"\"\"Prepare context for external model call for final analysis validation.\"\"\"\n context_parts = [\n f\"=== ANALYSIS REQUEST ===\\\\n{self.initial_request or 'Code analysis workflow initiated'}\\\\n=== END REQUEST ===\"\n ]\n\n # Add investigation summary\n investigation_summary = self._build_analysis_summary(consolidated_findings)\n context_parts.append(\n f\"\\\\n=== AGENT'S ANALYSIS INVESTIGATION ===\\\\n{investigation_summary}\\\\n=== END INVESTIGATION ===\"\n )\n\n # Add analysis configuration context if available\n if self.analysis_config:\n config_text = \"\\\\n\".join(f\"- {key}: {value}\" for key, value in self.analysis_config.items() if value)\n context_parts.append(f\"\\\\n=== ANALYSIS CONFIGURATION ===\\\\n{config_text}\\\\n=== END CONFIGURATION ===\")\n\n # Add relevant code elements if available\n if consolidated_findings.relevant_context:\n methods_text = \"\\\\n\".join(f\"- {method}\" for method in consolidated_findings.relevant_context)\n context_parts.append(f\"\\\\n=== RELEVANT CODE ELEMENTS ===\\\\n{methods_text}\\\\n=== END CODE ELEMENTS ===\")\n\n # Add assessment evolution if available\n if consolidated_findings.hypotheses:\n assessments_text = \"\\\\n\".join(\n f\"Step {h['step']}: {h['hypothesis']}\" for h in consolidated_findings.hypotheses\n )\n context_parts.append(f\"\\\\n=== ASSESSMENT EVOLUTION ===\\\\n{assessments_text}\\\\n=== END ASSESSMENTS ===\")\n\n # Add images if available\n if consolidated_findings.images:\n images_text = \"\\\\n\".join(f\"- {img}\" for img in consolidated_findings.images)\n context_parts.append(\n f\"\\\\n=== VISUAL ANALYSIS INFORMATION ===\\\\n{images_text}\\\\n=== END VISUAL INFORMATION ===\"\n )\n\n return \"\\\\n\".join(context_parts)\n\n def _build_analysis_summary(self, consolidated_findings) -> str:\n \"\"\"Prepare a comprehensive summary of the analysis investigation.\"\"\"\n summary_parts = [\n \"=== SYSTEMATIC ANALYSIS INVESTIGATION SUMMARY ===\",\n f\"Total steps: {len(consolidated_findings.findings)}\",\n f\"Files examined: {len(consolidated_findings.files_checked)}\",\n f\"Relevant files identified: {len(consolidated_findings.relevant_files)}\",\n f\"Code elements analyzed: {len(consolidated_findings.relevant_context)}\",\n \"\",\n \"=== INVESTIGATION PROGRESSION ===\",\n ]\n\n for finding in consolidated_findings.findings:\n summary_parts.append(finding)\n\n return \"\\\\n\".join(summary_parts)\n\n def should_include_files_in_expert_prompt(self) -> bool:\n \"\"\"Include files in expert analysis for comprehensive validation.\"\"\"\n return True\n\n def should_embed_system_prompt(self) -> bool:\n \"\"\"Embed system prompt in expert analysis for proper context.\"\"\"\n return True\n\n def get_expert_thinking_mode(self) -> str:\n \"\"\"Use high thinking mode for thorough analysis.\"\"\"\n return \"high\"\n\n def get_expert_analysis_instruction(self) -> str:\n \"\"\"Get specific instruction for analysis expert validation.\"\"\"\n return (\n \"Please provide comprehensive analysis validation based on the investigation findings. \"\n \"Focus on identifying any remaining architectural insights, validating the completeness of the analysis, \"\n \"and providing final strategic recommendations following the structured format specified in the system prompt.\"\n )\n\n # Hook method overrides for analyze-specific behavior\n\n def prepare_step_data(self, request) -> dict:\n \"\"\"\n Map analyze-specific fields for internal processing.\n \"\"\"\n step_data = {\n \"step\": request.step,\n \"step_number\": request.step_number,\n \"findings\": request.findings,\n \"files_checked\": request.files_checked,\n \"relevant_files\": request.relevant_files,\n \"relevant_context\": request.relevant_context,\n \"issues_found\": request.issues_found, # Analyze workflow uses issues_found for structured problem tracking\n \"confidence\": \"medium\", # Fixed value for workflow compatibility\n \"hypothesis\": request.findings, # Map findings to hypothesis for compatibility\n \"images\": request.images or [],\n }\n return step_data\n\n def should_skip_expert_analysis(self, request, consolidated_findings) -> bool:\n \"\"\"\n Analyze workflow always uses expert analysis for comprehensive validation.\n\n Analysis benefits from a second opinion to ensure completeness and catch\n any missed insights or alternative perspectives.\n \"\"\"\n return False\n\n def store_initial_issue(self, step_description: str):\n \"\"\"Store initial request for expert analysis.\"\"\"\n self.initial_request = step_description\n\n # Override inheritance hooks for analyze-specific behavior\n\n def get_completion_status(self) -> str:\n \"\"\"Analyze tools use analysis-specific status.\"\"\"\n return \"analysis_complete_ready_for_implementation\"\n\n def get_completion_data_key(self) -> str:\n \"\"\"Analyze uses 'complete_analysis' key.\"\"\"\n return \"complete_analysis\"\n\n def get_final_analysis_from_request(self, request):\n \"\"\"Analyze tools use 'findings' field.\"\"\"\n return request.findings\n\n def get_confidence_level(self, request) -> str:\n \"\"\"Analyze tools use fixed confidence for consistency.\"\"\"\n return \"medium\"\n\n def get_completion_message(self) -> str:\n \"\"\"Analyze-specific completion message.\"\"\"\n return (\n \"Analysis complete. You have identified all significant patterns, \"\n \"architectural insights, and strategic opportunities. MANDATORY: Present the user with the complete \"\n \"analysis results organized by strategic impact, and IMMEDIATELY proceed with implementing the \"\n \"highest priority recommendations or provide specific guidance for improvements. Focus on actionable \"\n \"strategic insights.\"\n )\n\n def get_skip_reason(self) -> str:\n \"\"\"Analyze-specific skip reason.\"\"\"\n return \"Completed comprehensive analysis locally\"\n\n def get_skip_expert_analysis_status(self) -> str:\n \"\"\"Analyze-specific expert analysis skip status.\"\"\"\n return \"skipped_due_to_complete_analysis\"\n\n def prepare_work_summary(self) -> str:\n \"\"\"Analyze-specific work summary.\"\"\"\n return self._build_analysis_summary(self.consolidated_findings)\n\n def get_completion_next_steps_message(self, expert_analysis_used: bool = False) -> str:\n \"\"\"\n Analyze-specific completion message.\n \"\"\"\n base_message = (\n \"ANALYSIS IS COMPLETE. You MUST now summarize and present ALL analysis findings organized by \"\n \"strategic impact (Critical β†’ High β†’ Medium β†’ Low), specific architectural insights with code references, \"\n \"and exact recommendations for improvement. Clearly prioritize the top 3 strategic opportunities that need \"\n \"immediate attention. Provide concrete, actionable guidance for each findingβ€”make it easy for a developer \"\n \"to understand exactly what strategic improvements to implement and how to approach them.\"\n )\n\n # Add expert analysis guidance only when expert analysis was actually used\n if expert_analysis_used:\n expert_guidance = self.get_expert_analysis_guidance()\n if expert_guidance:\n return f\"{base_message}\\n\\n{expert_guidance}\"\n\n return base_message\n\n def get_expert_analysis_guidance(self) -> str:\n \"\"\"\n Provide specific guidance for handling expert analysis in code analysis.\n \"\"\"\n return (\n \"IMPORTANT: Analysis from an assistant model has been provided above. You MUST thoughtfully evaluate and validate \"\n \"the expert insights rather than treating them as definitive conclusions. Cross-reference the expert \"\n \"analysis with your own systematic investigation, verify that architectural recommendations are \"\n \"appropriate for this codebase's scale and context, and ensure suggested improvements align with \"\n \"the project's goals and constraints. Present a comprehensive synthesis that combines your detailed \"\n \"analysis with validated expert perspectives, clearly distinguishing between patterns you've \"\n \"independently identified and additional strategic insights from expert validation.\"\n )\n\n def get_step_guidance_message(self, request) -> str:\n \"\"\"\n Analyze-specific step guidance with detailed investigation instructions.\n \"\"\"\n step_guidance = self.get_analyze_step_guidance(request.step_number, request)\n return step_guidance[\"next_steps\"]\n\n def get_analyze_step_guidance(self, step_number: int, request) -> dict[str, Any]:\n \"\"\"\n Provide step-specific guidance for analyze workflow.\n \"\"\"\n # Generate the next steps instruction based on required actions\n required_actions = self.get_required_actions(step_number, \"medium\", request.findings, request.total_steps)\n\n if step_number == 1:\n next_steps = (\n f\"MANDATORY: DO NOT call the {self.get_name()} tool again immediately. You MUST first examine \"\n f\"the code files thoroughly using appropriate tools. CRITICAL AWARENESS: You need to understand \"\n f\"the architectural patterns, assess scalability and performance characteristics, identify strategic \"\n f\"improvement areas, and look for systemic risks, overengineering, and missing abstractions. \"\n f\"Use file reading tools, code analysis, and systematic examination to gather comprehensive information. \"\n f\"Only call {self.get_name()} again AFTER completing your investigation. When you call \"\n f\"{self.get_name()} next time, use step_number: {step_number + 1} and report specific \"\n f\"files examined, architectural insights found, and strategic assessment discoveries.\"\n )\n elif step_number < request.total_steps:\n next_steps = (\n f\"STOP! Do NOT call {self.get_name()} again yet. Based on your findings, you've identified areas that need \"\n f\"deeper analysis. MANDATORY ACTIONS before calling {self.get_name()} step {step_number + 1}:\\\\n\"\n + \"\\\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\\\n\\\\nOnly call {self.get_name()} again with step_number: {step_number + 1} AFTER \"\n + \"completing these analysis tasks.\"\n )\n else:\n next_steps = (\n f\"WAIT! Your analysis needs final verification. DO NOT call {self.get_name()} immediately. REQUIRED ACTIONS:\\\\n\"\n + \"\\\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\\\n\\\\nREMEMBER: Ensure you have identified all significant architectural insights and strategic \"\n f\"opportunities across all areas. Document findings with specific file references and \"\n f\"code examples where applicable, then call {self.get_name()} with step_number: {step_number + 1}.\"\n )\n\n return {\"next_steps\": next_steps}\n\n def customize_workflow_response(self, response_data: dict, request) -> dict:\n \"\"\"\n Customize response to match analyze workflow format.\n \"\"\"\n # Store initial request on first step\n if request.step_number == 1:\n self.initial_request = request.step\n # Store analysis configuration for expert analysis\n if request.relevant_files:\n self.analysis_config = {\n \"relevant_files\": request.relevant_files,\n \"analysis_type\": request.analysis_type,\n \"output_format\": request.output_format,\n }\n\n # Convert generic status names to analyze-specific ones\n tool_name = self.get_name()\n status_mapping = {\n f\"{tool_name}_in_progress\": \"analysis_in_progress\",\n f\"pause_for_{tool_name}\": \"pause_for_analysis\",\n f\"{tool_name}_required\": \"analysis_required\",\n f\"{tool_name}_complete\": \"analysis_complete\",\n }\n\n if response_data[\"status\"] in status_mapping:\n response_data[\"status\"] = status_mapping[response_data[\"status\"]]\n\n # Rename status field to match analyze workflow\n if f\"{tool_name}_status\" in response_data:\n response_data[\"analysis_status\"] = response_data.pop(f\"{tool_name}_status\")\n # Add analyze-specific status fields\n response_data[\"analysis_status\"][\"insights_by_severity\"] = {}\n for insight in self.consolidated_findings.issues_found:\n severity = insight.get(\"severity\", \"unknown\")\n if severity not in response_data[\"analysis_status\"][\"insights_by_severity\"]:\n response_data[\"analysis_status\"][\"insights_by_severity\"][severity] = 0\n response_data[\"analysis_status\"][\"insights_by_severity\"][severity] += 1\n response_data[\"analysis_status\"][\"analysis_confidence\"] = self.get_request_confidence(request)\n\n # Map complete_analyze to complete_analysis\n if f\"complete_{tool_name}\" in response_data:\n response_data[\"complete_analysis\"] = response_data.pop(f\"complete_{tool_name}\")\n\n # Map the completion flag to match analyze workflow\n if f\"{tool_name}_complete\" in response_data:\n response_data[\"analysis_complete\"] = response_data.pop(f\"{tool_name}_complete\")\n\n return response_data\n\n # Required abstract methods from BaseTool\n def get_request_model(self):\n \"\"\"Return the analyze workflow-specific request model.\"\"\"\n return AnalyzeWorkflowRequest\n\n async def prepare_prompt(self, request) -> str:\n \"\"\"Not used - workflow tools use execute_workflow().\"\"\"\n return \"\" # Workflow tools use execute_workflow() directly\n" }, { "path": "tools/apilookup.py", "content": "\"\"\"API lookup tool - quickly gather the latest API/SDK information.\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nfrom typing import TYPE_CHECKING, Any\n\nfrom pydantic import Field\n\nfrom config import TEMPERATURE_ANALYTICAL\nfrom tools.shared.base_models import ToolRequest\nfrom tools.simple.base import SimpleTool\n\nif TYPE_CHECKING:\n from tools.models import ToolModelCategory\n\n\nLOOKUP_FIELD_DESCRIPTIONS = {\n \"prompt\": \"The API, SDK, library, framework, or technology you need current documentation, version info, breaking changes, or migration guidance for.\",\n}\n\n\nclass LookupRequest(ToolRequest):\n prompt: str = Field(..., description=LOOKUP_FIELD_DESCRIPTIONS[\"prompt\"])\n\n\nLOOKUP_PROMPT = \"\"\"\nMANDATORY: You MUST perform this research in a SEPARATE SUB-TASK using your web search tool.\n\nCRITICAL RULES - READ CAREFULLY:\n- Launch your environment's dedicated web search capability (for example `websearch`, `web_search`, or another native\nweb-search tool such as the one you use to perform a web search online) to gather sources - do NOT call this `apilookup` tool again\nduring the same lookup, this is ONLY an orchestration tool to guide you and has NO web search capability of its own.\n- ALWAYS run the search from a separate sub-task/sub-process so the research happens outside this tool invocation.\n- If the environment does not expose a web search tool, immediately report that limitation instead of invoking `apilookup` again.\n\nMISSION:\nResearch the latest, most authoritative documentation for the requested API, SDK, library, framework, programming language feature, or tool to answer the user's question accurately using a SUB-AGENT in a separate process.\n\nSEARCH STRATEGY (MAXIMUM 2-4 SEARCHES TOTAL FOR THIS MISSION - THEN STOP):\n- IMPORTANT: Begin by determining today's date and current year\n- MANDATORY FOR OS-TIED APIS/SDKs: If the request involves iOS, macOS, Windows, Linux, Android, watchOS, tvOS, or any OS-specific framework/API:\n * FIRST perform a web search to determine \"what is the latest [OS name] version [current year]\"\n * If the search is around a specific tool or an IDE, confirm the latest version \"latest version [tool name]\"\n * DO NOT rely on your training data or knowledge cutoff for OS versions - you MUST search for current information\n * ONLY AFTER confirming the current OS version, search for APIs/SDKs/frameworks for that specific version\n * Example workflow: Search \"latest iOS version [current year]\" β†’ Find current version β†’ Then search \"[current iOS version] SwiftUI glass effect button [current year]\"\n- MANDATORY FOR MAJOR FRAMEWORKS/LANGUAGES: For rapidly-evolving ecosystems, verify current stable version:\n * Languages: Node.js, Python, Ruby, Rust, Go, Java, .NET/C#, PHP, Kotlin, Swift\n * Web frameworks: React, Vue, Angular, Next.js, Nuxt, Svelte, SvelteKit, Remix, Astro, SolidJS\n * Backend frameworks: Django, Flask, FastAPI, Rails, Laravel, Spring Boot, Express, NestJS, Axum\n * Mobile: Flutter, React Native, Jetpack Compose, SwiftUI\n * Build tools: Vite, Webpack, esbuild, Turbopack, Rollup\n * Package managers: npm, pnpm, yarn, pip, cargo, go modules, maven, gradle\n * Search pattern: \"latest [framework/language/SDK] version [current year]\" BEFORE searching for specific APIs\n * ONLY consider articles, documentation, and resources dated within the current year or most recent release cycle\n * Ignore or deprioritize results from previous years unless they are still the current official documentation\n- ALWAYS find current official documentation, release notes, changelogs, migration guides, and authoritative blog posts. Newest APIs / SDKs released or updated in the current year trump older ones.\n- Prioritize official sources: project documentation sites, GitHub repositories, package registries (npm, PyPI, crates.io, Maven Central, NuGet, RubyGems, Packagist, etc.), and official blogs\n- Check version-specific documentation when relevant and add current year to ensure latest docs are retrieved (e.g., \"React docs [current year]\", \"Python what's new [current year]\", \"TypeScript breaking changes [current year]\", \"Next.js app router [current year]\")\n- Look for recent Stack Overflow discussions, GitHub issues, RFC documents, or official discussion forums when official docs are incomplete\n- Cross-reference multiple sources to validate syntax, method signatures, configuration options, and best practices\n- Search for deprecation warnings, security advisories, or migration paths between major versions\n- STOP IMMEDIATELY after 2-4 searches maximum - DO NOT continue exploring tangential topics, examples, tutorials, or supplementary material\n- If latest, more current, authoritative information has been found: STOP looking further\n- ALWAYS cite authoritative sources with links (official docs, changelogs, GitHub releases, package registry pages)\n\"\"\".strip()\n\n\nclass LookupTool(SimpleTool):\n \"\"\"Simple tool that wraps user queries with API lookup instructions.\"\"\"\n\n def get_name(self) -> str:\n return \"apilookup\"\n\n def get_description(self) -> str:\n return (\n \"Use this tool automatically when you need current API/SDK documentation, latest version info, breaking changes, deprecations, migration guides, or official release notes. \"\n \"This tool searches authoritative sources (official docs, GitHub, package registries) to ensure up-to-date accuracy.\"\n )\n\n def get_system_prompt(self) -> str:\n return \"\"\n\n def get_default_temperature(self) -> float:\n return TEMPERATURE_ANALYTICAL\n\n def requires_model(self) -> bool:\n return False\n\n def get_model_category(self) -> ToolModelCategory:\n from tools.models import ToolModelCategory\n\n return ToolModelCategory.FAST_RESPONSE\n\n def get_request_model(self):\n return LookupRequest\n\n def get_tool_fields(self) -> dict[str, dict[str, Any]]:\n return {\n \"prompt\": {\n \"type\": \"string\",\n \"description\": LOOKUP_FIELD_DESCRIPTIONS[\"prompt\"],\n }\n }\n\n async def prepare_prompt(self, request) -> str: # pragma: no cover - not used\n return \"\"\n\n def get_input_schema(self) -> dict[str, Any]:\n return {\n \"type\": \"object\",\n \"properties\": {\n \"prompt\": {\n \"type\": \"string\",\n \"description\": LOOKUP_FIELD_DESCRIPTIONS[\"prompt\"],\n },\n },\n \"required\": [\"prompt\"],\n }\n\n async def execute(self, arguments: dict[str, Any]) -> list:\n from mcp.types import TextContent\n\n request = self.get_request_model()(**arguments)\n response = {\n \"status\": \"web_lookup_needed\",\n \"instructions\": LOOKUP_PROMPT,\n \"user_prompt\": request.prompt,\n }\n return [TextContent(type=\"text\", text=json.dumps(response, ensure_ascii=False, indent=2))]\n" }, { "path": "tools/challenge.py", "content": "\"\"\"\nChallenge tool - Encourages critical thinking and thoughtful disagreement\n\nThis tool takes a user's statement and returns it wrapped in instructions that\nencourage the CLI agent to challenge ideas and think critically before agreeing. It helps\navoid reflexive agreement by prompting deeper analysis and genuine evaluation.\n\nThis is a simple, self-contained tool that doesn't require AI model access.\n\"\"\"\n\nfrom typing import TYPE_CHECKING, Any, Optional\n\nfrom pydantic import Field\n\nif TYPE_CHECKING:\n from tools.models import ToolModelCategory\n\nfrom config import TEMPERATURE_ANALYTICAL\nfrom tools.shared.base_models import ToolRequest\nfrom tools.shared.exceptions import ToolExecutionError\n\nfrom .simple.base import SimpleTool\n\n# Field descriptions for the Challenge tool\nCHALLENGE_FIELD_DESCRIPTIONS = {\n \"prompt\": (\n \"Statement to scrutinize. If you invoke `challenge` manually, strip the word 'challenge' and pass just the statement. \"\n \"Automatic invocations send the full user message as-is; do not modify it.\"\n ),\n}\n\n\nclass ChallengeRequest(ToolRequest):\n \"\"\"Request model for Challenge tool\"\"\"\n\n prompt: str = Field(..., description=CHALLENGE_FIELD_DESCRIPTIONS[\"prompt\"])\n\n\nclass ChallengeTool(SimpleTool):\n \"\"\"\n Challenge tool for encouraging critical thinking and avoiding automatic agreement.\n\n This tool wraps user statements in instructions that encourage the CLI agent to:\n - Challenge ideas and think critically before responding\n - Evaluate whether they actually agree or disagree\n - Provide thoughtful analysis rather than reflexive agreement\n\n The tool is self-contained and doesn't require AI model access - it simply\n transforms the input prompt into a structured critical thinking challenge.\n \"\"\"\n\n def get_name(self) -> str:\n return \"challenge\"\n\n def get_description(self) -> str:\n return (\n \"Prevents reflexive agreement by forcing critical thinking and reasoned analysis when a statement is challenged. \"\n \"Trigger automatically when a user critically questions, disagrees or appears to push back on earlier answers, and use it manually to sanity-check contentious claims.\"\n )\n\n def get_system_prompt(self) -> str:\n # Challenge tool doesn't need a system prompt since it doesn't call AI\n return \"\"\n\n def get_default_temperature(self) -> float:\n return TEMPERATURE_ANALYTICAL\n\n def get_model_category(self) -> \"ToolModelCategory\":\n \"\"\"Challenge doesn't need a model category since it doesn't use AI\"\"\"\n from tools.models import ToolModelCategory\n\n return ToolModelCategory.FAST_RESPONSE # Default, but not used\n\n def requires_model(self) -> bool:\n \"\"\"\n Challenge tool doesn't require model resolution at the MCP boundary.\n\n Like the planner tool, this is a pure data processing tool that transforms\n the input without calling external AI models.\n\n Returns:\n bool: False - challenge doesn't need AI model access\n \"\"\"\n return False\n\n def get_request_model(self):\n \"\"\"Return the Challenge-specific request model\"\"\"\n return ChallengeRequest\n\n def get_input_schema(self) -> dict[str, Any]:\n \"\"\"\n Generate input schema for the challenge tool.\n\n Since this tool doesn't require a model, we exclude model-related fields.\n \"\"\"\n schema = {\n \"type\": \"object\",\n \"properties\": {\n \"prompt\": {\n \"type\": \"string\",\n \"description\": CHALLENGE_FIELD_DESCRIPTIONS[\"prompt\"],\n },\n },\n \"required\": [\"prompt\"],\n }\n\n return schema\n\n async def execute(self, arguments: dict[str, Any]) -> list:\n \"\"\"\n Execute the challenge tool by wrapping the prompt in critical thinking instructions.\n\n This is the main execution method that transforms the user's statement into\n a structured challenge that encourages thoughtful re-evaluation.\n \"\"\"\n import json\n\n from mcp.types import TextContent\n\n try:\n # Validate request\n request = self.get_request_model()(**arguments)\n\n # Wrap the prompt in challenge instructions\n wrapped_prompt = self._wrap_prompt_for_challenge(request.prompt)\n\n # Return the wrapped prompt as the response\n response_data = {\n \"status\": \"challenge_accepted\",\n \"original_statement\": request.prompt,\n \"challenge_prompt\": wrapped_prompt,\n \"instructions\": (\n \"Present the challenge_prompt to yourself and follow its instructions. \"\n \"Reassess the statement carefully and critically before responding. \"\n \"If, after reflection, you find reasons to disagree or qualify it, explain your reasoning. \"\n \"Likewise, if you find reasons to agree, articulate them clearly and justify your agreement.\"\n ),\n }\n\n return [TextContent(type=\"text\", text=json.dumps(response_data, indent=2, ensure_ascii=False))]\n\n except ToolExecutionError:\n raise\n except Exception as e:\n import logging\n\n logger = logging.getLogger(__name__)\n logger.error(f\"Error in challenge tool execution: {e}\", exc_info=True)\n\n error_data = {\n \"status\": \"error\",\n \"error\": str(e),\n \"content\": f\"Failed to create challenge prompt: {str(e)}\",\n }\n\n raise ToolExecutionError(json.dumps(error_data, ensure_ascii=False)) from e\n\n def _wrap_prompt_for_challenge(self, prompt: str) -> str:\n \"\"\"\n Wrap the user's statement in instructions that encourage critical challenge.\n\n Args:\n prompt: The original user statement to wrap\n\n Returns:\n The statement wrapped in challenge instructions\n \"\"\"\n return (\n f\"CRITICAL REASSESSMENT – Do not automatically agree:\\n\\n\"\n f'\"{prompt}\"\\n\\n'\n f\"Carefully evaluate the statement above. Is it accurate, complete, and well-reasoned? \"\n f\"Investigate if needed before replying, and stay focused. If you identify flaws, gaps, or misleading \"\n f\"points, explain them clearly. Likewise, if you find the reasoning sound, explain why it holds up. \"\n f\"Respond with thoughtful analysisβ€”stay to the point and avoid reflexive agreement.\"\n )\n\n # Required method implementations from SimpleTool\n\n async def prepare_prompt(self, request: ChallengeRequest) -> str:\n \"\"\"Not used since challenge doesn't call AI models\"\"\"\n return \"\"\n\n def format_response(self, response: str, request: ChallengeRequest, model_info: Optional[dict] = None) -> str:\n \"\"\"Not used since challenge doesn't call AI models\"\"\"\n return response\n\n def get_tool_fields(self) -> dict[str, dict[str, Any]]:\n \"\"\"Tool-specific field definitions for Challenge\"\"\"\n return {\n \"prompt\": {\n \"type\": \"string\",\n \"description\": CHALLENGE_FIELD_DESCRIPTIONS[\"prompt\"],\n },\n }\n\n def get_required_fields(self) -> list[str]:\n \"\"\"Required fields for Challenge tool\"\"\"\n return [\"prompt\"]\n" }, { "path": "tools/chat.py", "content": "\"\"\"\nChat tool - General development chat and collaborative thinking\n\nThis tool provides a conversational interface for general development assistance,\nbrainstorming, problem-solving, and collaborative thinking. It supports file context,\nimages, and conversation continuation for seamless multi-turn interactions.\n\"\"\"\n\nimport logging\nimport os\nimport re\nfrom pathlib import Path\nfrom typing import TYPE_CHECKING, Any, Optional\n\nfrom pydantic import Field\n\nif TYPE_CHECKING:\n from providers.shared import ModelCapabilities\n from tools.models import ToolModelCategory\n\nfrom config import TEMPERATURE_BALANCED\nfrom systemprompts import CHAT_PROMPT, GENERATE_CODE_PROMPT\nfrom tools.shared.base_models import COMMON_FIELD_DESCRIPTIONS, ToolRequest\n\nfrom .simple.base import SimpleTool\n\n# Field descriptions matching the original Chat tool exactly\nCHAT_FIELD_DESCRIPTIONS = {\n \"prompt\": (\n \"Your question or idea for collaborative thinking to be sent to the external model. Provide detailed context, \"\n \"including your goal, what you've tried, and any specific challenges. \"\n \"WARNING: Large inline code must NOT be shared in prompt. Provide full-path to files on disk as separate parameter.\"\n ),\n \"absolute_file_paths\": (\"Full, absolute file paths to relevant code in order to share with external model\"),\n \"images\": \"Image paths (absolute) or base64 strings for optional visual context.\",\n \"working_directory_absolute_path\": (\n \"Absolute path to an existing directory where generated code artifacts can be saved.\"\n ),\n}\n\n\nclass ChatRequest(ToolRequest):\n \"\"\"Request model for Chat tool\"\"\"\n\n prompt: str = Field(..., description=CHAT_FIELD_DESCRIPTIONS[\"prompt\"])\n absolute_file_paths: Optional[list[str]] = Field(\n default_factory=list,\n description=CHAT_FIELD_DESCRIPTIONS[\"absolute_file_paths\"],\n )\n images: Optional[list[str]] = Field(default_factory=list, description=CHAT_FIELD_DESCRIPTIONS[\"images\"])\n working_directory_absolute_path: str = Field(\n ...,\n description=CHAT_FIELD_DESCRIPTIONS[\"working_directory_absolute_path\"],\n )\n\n\nclass ChatTool(SimpleTool):\n \"\"\"\n General development chat and collaborative thinking tool using SimpleTool architecture.\n\n This tool provides identical functionality to the original Chat tool but uses the new\n SimpleTool architecture for cleaner code organization and better maintainability.\n\n Migration note: This tool is designed to be a drop-in replacement for the original\n Chat tool with 100% behavioral compatibility.\n \"\"\"\n\n def __init__(self) -> None:\n super().__init__()\n self._last_recordable_response: Optional[str] = None\n\n def get_name(self) -> str:\n return \"chat\"\n\n def get_description(self) -> str:\n return (\n \"General chat and collaborative thinking partner for brainstorming, development discussion, \"\n \"getting second opinions, and exploring ideas. Use for ideas, validations, questions, and thoughtful explanations.\"\n )\n\n def get_annotations(self) -> Optional[dict[str, Any]]:\n \"\"\"Chat writes generated artifacts when code-generation is enabled.\"\"\"\n\n return {\"readOnlyHint\": False}\n\n def get_system_prompt(self) -> str:\n return CHAT_PROMPT\n\n def get_capability_system_prompts(self, capabilities: Optional[\"ModelCapabilities\"]) -> list[str]:\n prompts = list(super().get_capability_system_prompts(capabilities))\n if capabilities and capabilities.allow_code_generation:\n prompts.append(GENERATE_CODE_PROMPT)\n return prompts\n\n def get_default_temperature(self) -> float:\n return TEMPERATURE_BALANCED\n\n def get_model_category(self) -> \"ToolModelCategory\":\n \"\"\"Chat prioritizes fast responses and cost efficiency\"\"\"\n from tools.models import ToolModelCategory\n\n return ToolModelCategory.FAST_RESPONSE\n\n def get_request_model(self):\n \"\"\"Return the Chat-specific request model\"\"\"\n return ChatRequest\n\n # === Schema Generation Utilities ===\n\n def get_input_schema(self) -> dict[str, Any]:\n \"\"\"Generate input schema matching the original Chat tool expectations.\"\"\"\n\n required_fields = [\"prompt\", \"working_directory_absolute_path\"]\n if self.is_effective_auto_mode():\n required_fields.append(\"model\")\n\n schema = {\n \"type\": \"object\",\n \"properties\": {\n \"prompt\": {\n \"type\": \"string\",\n \"description\": CHAT_FIELD_DESCRIPTIONS[\"prompt\"],\n },\n \"absolute_file_paths\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": CHAT_FIELD_DESCRIPTIONS[\"absolute_file_paths\"],\n },\n \"images\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": CHAT_FIELD_DESCRIPTIONS[\"images\"],\n },\n \"working_directory_absolute_path\": {\n \"type\": \"string\",\n \"description\": CHAT_FIELD_DESCRIPTIONS[\"working_directory_absolute_path\"],\n },\n \"model\": self.get_model_field_schema(),\n \"temperature\": {\n \"type\": \"number\",\n \"description\": COMMON_FIELD_DESCRIPTIONS[\"temperature\"],\n \"minimum\": 0,\n \"maximum\": 1,\n },\n \"thinking_mode\": {\n \"type\": \"string\",\n \"enum\": [\"minimal\", \"low\", \"medium\", \"high\", \"max\"],\n \"description\": COMMON_FIELD_DESCRIPTIONS[\"thinking_mode\"],\n },\n \"continuation_id\": {\n \"type\": \"string\",\n \"description\": COMMON_FIELD_DESCRIPTIONS[\"continuation_id\"],\n },\n },\n \"required\": required_fields,\n \"additionalProperties\": False,\n }\n\n return schema\n\n def get_tool_fields(self) -> dict[str, dict[str, Any]]:\n \"\"\"Tool-specific field definitions used by SimpleTool scaffolding.\"\"\"\n\n return {\n \"prompt\": {\n \"type\": \"string\",\n \"description\": CHAT_FIELD_DESCRIPTIONS[\"prompt\"],\n },\n \"absolute_file_paths\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": CHAT_FIELD_DESCRIPTIONS[\"absolute_file_paths\"],\n },\n \"images\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": CHAT_FIELD_DESCRIPTIONS[\"images\"],\n },\n \"working_directory_absolute_path\": {\n \"type\": \"string\",\n \"description\": CHAT_FIELD_DESCRIPTIONS[\"working_directory_absolute_path\"],\n },\n }\n\n def get_required_fields(self) -> list[str]:\n \"\"\"Required fields for ChatSimple tool\"\"\"\n return [\"prompt\", \"working_directory_absolute_path\"]\n\n # === Hook Method Implementations ===\n\n async def prepare_prompt(self, request: ChatRequest) -> str:\n \"\"\"\n Prepare the chat prompt with optional context files.\n\n This implementation matches the original Chat tool exactly while using\n SimpleTool convenience methods for cleaner code.\n \"\"\"\n # Use SimpleTool's Chat-style prompt preparation\n return self.prepare_chat_style_prompt(request)\n\n def _validate_file_paths(self, request) -> Optional[str]:\n \"\"\"Extend validation to cover the working directory path.\"\"\"\n\n files = self.get_request_files(request)\n if files:\n expanded_files: list[str] = []\n for file_path in files:\n expanded = os.path.expanduser(file_path)\n if not os.path.isabs(expanded):\n return (\n \"Error: All file paths must be FULL absolute paths to real files / folders - DO NOT SHORTEN. \"\n f\"Received: {file_path}\"\n )\n expanded_files.append(expanded)\n self.set_request_files(request, expanded_files)\n\n error = super()._validate_file_paths(request)\n if error:\n return error\n\n working_directory = request.working_directory_absolute_path\n if working_directory:\n expanded = os.path.expanduser(working_directory)\n if not os.path.isabs(expanded):\n return (\n \"Error: 'working_directory_absolute_path' must be an absolute path (you may use '~' which will be expanded). \"\n f\"Received: {working_directory}\"\n )\n if not os.path.isdir(expanded):\n return (\n \"Error: 'working_directory_absolute_path' must reference an existing directory. \"\n f\"Received: {working_directory}\"\n )\n return None\n\n def format_response(self, response: str, request: ChatRequest, model_info: Optional[dict] = None) -> str:\n \"\"\"\n Format the chat response to match the original Chat tool exactly.\n \"\"\"\n self._last_recordable_response = None\n body = response\n recordable_override: Optional[str] = None\n\n if self._model_supports_code_generation():\n block, remainder, _ = self._extract_generated_code_block(response)\n if block:\n sanitized_text = remainder.strip()\n target_directory = request.working_directory_absolute_path\n try:\n artifact_path = self._persist_generated_code_block(block, target_directory)\n except Exception as exc: # pragma: no cover - rare filesystem failures\n logger.error(\"Failed to persist generated code block: %s\", exc, exc_info=True)\n warning = (\n f\"WARNING: Unable to write pal_generated.code inside '{target_directory}'. \"\n \"Check the path permissions and re-run. The generated code block is included below for manual handling.\"\n )\n\n history_copy_base = sanitized_text\n history_copy = self._join_sections(history_copy_base, warning) if history_copy_base else warning\n recordable_override = history_copy\n\n sanitized_warning = history_copy.strip()\n body = f\"{sanitized_warning}\\n\\n{block.strip()}\".strip()\n else:\n if not sanitized_text:\n base_message = (\n \"Generated code saved to pal_generated.code.\\n\"\n \"\\n\"\n \"CRITICAL: Contains mixed instructions + partial snippets - NOT complete code to copy as-is!\\n\"\n \"\\n\"\n \"You MUST:\\n\"\n \" 1. Read as a proposal from partial context - you may need to read the file in sections\\n\"\n \" 2. Implement ideas using YOUR complete codebase context and understanding\\n\"\n \" 3. Never paste wholesale - snippets may be partial with missing lines, pasting will corrupt your code!\\n\"\n \" 4. Adapt to fit your actual structure and style\\n\"\n \" 5. Build/lint/test after implementation to verify correctness\\n\"\n \"\\n\"\n \"Treat as guidance to implement thoughtfully, not ready-to-paste code.\"\n )\n sanitized_text = base_message\n\n instruction = self._build_agent_instruction(artifact_path)\n body = self._join_sections(sanitized_text, instruction)\n\n final_output = (\n f\"{body}\\n\\n---\\n\\nAGENT'S TURN: Evaluate this perspective alongside your analysis to \"\n \"form a comprehensive solution and continue with the user's request and task at hand.\"\n )\n\n if recordable_override is not None:\n self._last_recordable_response = (\n f\"{recordable_override}\\n\\n---\\n\\nAGENT'S TURN: Evaluate this perspective alongside your analysis to \"\n \"form a comprehensive solution and continue with the user's request and task at hand.\"\n )\n else:\n self._last_recordable_response = final_output\n\n return final_output\n\n def _record_assistant_turn(\n self, continuation_id: str, response_text: str, request, model_info: Optional[dict]\n ) -> None:\n recordable = self._last_recordable_response if self._last_recordable_response is not None else response_text\n try:\n super()._record_assistant_turn(continuation_id, recordable, request, model_info)\n finally:\n self._last_recordable_response = None\n\n def _model_supports_code_generation(self) -> bool:\n context = getattr(self, \"_model_context\", None)\n if not context:\n return False\n\n try:\n capabilities = context.capabilities\n except Exception: # pragma: no cover - defensive fallback\n return False\n\n return bool(capabilities.allow_code_generation)\n\n def _extract_generated_code_block(self, text: str) -> tuple[Optional[str], str, int]:\n matches = list(re.finditer(r\".*?\", text, flags=re.DOTALL | re.IGNORECASE))\n if not matches:\n return None, text, 0\n\n last_match = matches[-1]\n block = last_match.group(0).strip()\n\n # Merge the text before and after the final block while trimming excess whitespace\n before = text[: last_match.start()]\n after = text[last_match.end() :]\n remainder = self._join_sections(before, after)\n\n return block, remainder, len(matches)\n\n def _persist_generated_code_block(self, block: str, working_directory: str) -> Path:\n expanded = os.path.expanduser(working_directory)\n target_dir = Path(expanded).resolve()\n if not target_dir.is_dir():\n raise FileNotFoundError(f\"Absolute working directory path '{working_directory}' does not exist\")\n\n target_file = target_dir / \"pal_generated.code\"\n if target_file.exists():\n try:\n target_file.unlink()\n except OSError as exc:\n logger.warning(\"Unable to remove existing pal_generated.code: %s\", exc)\n\n content = block if block.endswith(\"\\n\") else f\"{block}\\n\"\n target_file.write_text(content, encoding=\"utf-8\")\n logger.info(\"Generated code artifact written to %s\", target_file)\n return target_file\n\n @staticmethod\n def _build_agent_instruction(artifact_path: Path) -> str:\n return (\n f\"CONTINUING FROM PREVIOUS DISCUSSION: Implementation plan saved to `{artifact_path}`.\\n\"\n \"\\n\"\n f\"CRITICAL WARNING: `{artifact_path}` may contain partial code snippets from another AI with limited context. \"\n \"Wholesale copy-pasting MAY CORRUPT your codebase with incomplete logic and missing lines.\\n\"\n \"\\n\"\n \"Required workflow:\\n\"\n \"1. For blocks: Partial excerpts only. Understand the intent and implement using YOUR full context. \"\n \"DO NOT copy wholesale - adapt ideas to fit actual structure.\\n\"\n \"2. For blocks: Understand proposal and create properly. Verify completeness (imports, syntax, logic).\\n\"\n \"3. Validation: After ALL changes, verify correctness using available tools (build/compile, linters, tests, type checks, etc.).\\n\"\n f\"4. Cleanup: After you're done reading and applying changes, delete `{artifact_path}` once verified to prevent stale instructions.\\n\"\n \"\\n\"\n \"Treat this as a patch-set requiring manual integration, not ready-to-paste code. You have full codebase context - use it.\"\n )\n\n @staticmethod\n def _join_sections(*sections: str) -> str:\n chunks: list[str] = []\n for section in sections:\n if section:\n trimmed = section.strip()\n if trimmed:\n chunks.append(trimmed)\n return \"\\n\\n\".join(chunks)\n\n def get_websearch_guidance(self) -> str:\n \"\"\"\n Return Chat tool-style web search guidance.\n \"\"\"\n return self.get_chat_style_websearch_guidance()\n\n\nlogger = logging.getLogger(__name__)\n" }, { "path": "tools/clink.py", "content": "\"\"\"clink tool - bridge PAL MCP requests to external AI CLIs.\"\"\"\n\nfrom __future__ import annotations\n\nimport logging\nimport re\nfrom datetime import datetime, timezone\nfrom pathlib import Path\nfrom typing import Any\n\nfrom mcp.types import TextContent\nfrom pydantic import BaseModel, Field\n\nfrom clink import get_registry\nfrom clink.agents import AgentOutput, CLIAgentError, create_agent\nfrom clink.models import ResolvedCLIClient, ResolvedCLIRole\nfrom config import TEMPERATURE_BALANCED\nfrom tools.models import ToolModelCategory, ToolOutput\nfrom tools.shared.base_models import COMMON_FIELD_DESCRIPTIONS\nfrom tools.shared.exceptions import ToolExecutionError\nfrom tools.simple.base import SchemaBuilder, SimpleTool\n\nlogger = logging.getLogger(__name__)\n\nMAX_RESPONSE_CHARS = 20_000\nSUMMARY_PATTERN = re.compile(r\"(.*?)\", re.IGNORECASE | re.DOTALL)\n\n\nclass CLinkRequest(BaseModel):\n \"\"\"Request model for clink tool.\"\"\"\n\n prompt: str = Field(..., description=\"Prompt forwarded to the target CLI.\")\n cli_name: str | None = Field(\n default=None,\n description=\"Configured CLI client name to invoke. Defaults to the first configured CLI if omitted.\",\n )\n role: str | None = Field(\n default=None,\n description=\"Optional role preset defined in the CLI configuration (defaults to 'default').\",\n )\n absolute_file_paths: list[str] = Field(\n default_factory=list,\n description=COMMON_FIELD_DESCRIPTIONS[\"absolute_file_paths\"],\n )\n images: list[str] = Field(\n default_factory=list,\n description=COMMON_FIELD_DESCRIPTIONS[\"images\"],\n )\n continuation_id: str | None = Field(\n default=None,\n description=COMMON_FIELD_DESCRIPTIONS[\"continuation_id\"],\n )\n\n\nclass CLinkTool(SimpleTool):\n \"\"\"Bridge MCP requests to configured CLI agents.\n\n Schema metadata is cached at construction time and execution relies on the shared\n SimpleTool hooks for conversation memory. Prompt preparation is customised so we\n pass instructions and file references suitable for another CLI agent.\n \"\"\"\n\n def __init__(self) -> None:\n # Cache registry metadata so the schema surfaces concrete enum values.\n self._registry = get_registry()\n self._cli_names = self._registry.list_clients()\n self._role_map: dict[str, list[str]] = {name: self._registry.list_roles(name) for name in self._cli_names}\n self._all_roles: list[str] = sorted({role for roles in self._role_map.values() for role in roles})\n if \"gemini\" in self._cli_names:\n self._default_cli_name = \"gemini\"\n else:\n self._default_cli_name = self._cli_names[0] if self._cli_names else None\n self._active_system_prompt: str = \"\"\n super().__init__()\n\n def get_name(self) -> str:\n return \"clink\"\n\n def get_description(self) -> str:\n return (\n \"Link a request to an external AI CLI (Gemini CLI, Qwen CLI, etc.) through PAL MCP to reuse \"\n \"their capabilities inside existing workflows.\"\n )\n\n def get_annotations(self) -> dict[str, Any]:\n return {\"readOnlyHint\": True}\n\n def requires_model(self) -> bool:\n return False\n\n def get_model_category(self) -> ToolModelCategory:\n return ToolModelCategory.BALANCED\n\n def get_default_temperature(self) -> float:\n return TEMPERATURE_BALANCED\n\n def get_system_prompt(self) -> str:\n return self._active_system_prompt or \"\"\n\n def get_request_model(self):\n return CLinkRequest\n\n def get_input_schema(self) -> dict[str, Any]:\n # Surface configured CLI names and roles directly in the schema so MCP clients\n # (and downstream agents) can discover available options without consulting\n # a separate registry call.\n role_descriptions = []\n for name in self._cli_names:\n roles = \", \".join(sorted(self._role_map.get(name, [\"default\"]))) or \"default\"\n role_descriptions.append(f\"{name}: {roles}\")\n\n if role_descriptions:\n cli_available = \", \".join(self._cli_names) if self._cli_names else \"(none configured)\"\n default_text = (\n f\" Default: {self._default_cli_name}.\" if self._default_cli_name and len(self._cli_names) <= 1 else \"\"\n )\n cli_description = (\n \"Configured CLI client name (from conf/cli_clients). Available: \" + cli_available + default_text\n )\n role_description = (\n \"Optional role preset defined for the selected CLI (defaults to 'default'). Roles per CLI: \"\n + \"; \".join(role_descriptions)\n )\n else:\n cli_description = \"Configured CLI client name (from conf/cli_clients).\"\n role_description = \"Optional role preset defined for the selected CLI (defaults to 'default').\"\n\n properties = {\n \"prompt\": {\n \"type\": \"string\",\n \"description\": \"User request forwarded to the CLI (conversation context is pre-applied).\",\n },\n \"cli_name\": {\n \"type\": \"string\",\n \"enum\": self._cli_names,\n \"description\": cli_description,\n },\n \"role\": {\n \"type\": \"string\",\n \"enum\": self._all_roles or [\"default\"],\n \"description\": role_description,\n },\n \"absolute_file_paths\": SchemaBuilder.SIMPLE_FIELD_SCHEMAS[\"absolute_file_paths\"],\n \"images\": SchemaBuilder.COMMON_FIELD_SCHEMAS[\"images\"],\n \"continuation_id\": SchemaBuilder.COMMON_FIELD_SCHEMAS[\"continuation_id\"],\n }\n\n schema = {\n \"type\": \"object\",\n \"properties\": properties,\n \"required\": [\"prompt\"],\n \"additionalProperties\": False,\n }\n\n if len(self._cli_names) > 1:\n schema[\"required\"].append(\"cli_name\")\n\n return schema\n\n def get_tool_fields(self) -> dict[str, dict[str, Any]]:\n \"\"\"Unused by clink because we override the schema end-to-end.\"\"\"\n return {}\n\n async def execute(self, arguments: dict[str, Any]) -> list[TextContent]:\n self._current_arguments = arguments\n request = self.get_request_model()(**arguments)\n\n path_error = self._validate_file_paths(request)\n if path_error:\n self._raise_tool_error(path_error)\n\n selected_cli = request.cli_name or self._default_cli_name\n if not selected_cli:\n self._raise_tool_error(\"No CLI clients are configured for clink.\")\n\n try:\n client_config = self._registry.get_client(selected_cli)\n except KeyError as exc:\n self._raise_tool_error(str(exc))\n\n try:\n role_config = client_config.get_role(request.role)\n except KeyError as exc:\n self._raise_tool_error(str(exc))\n\n absolute_file_paths = self.get_request_files(request)\n images = self.get_request_images(request)\n continuation_id = self.get_request_continuation_id(request)\n\n self._model_context = arguments.get(\"_model_context\")\n\n system_prompt_text = role_config.prompt_path.read_text(encoding=\"utf-8\")\n include_system_prompt = not self._use_external_system_prompt(client_config)\n\n try:\n prompt_text = await self._prepare_prompt_for_role(\n request,\n role_config,\n system_prompt=system_prompt_text,\n include_system_prompt=include_system_prompt,\n )\n except Exception as exc:\n logger.exception(\"Failed to prepare clink prompt\")\n self._raise_tool_error(f\"Failed to prepare prompt: {exc}\")\n\n agent = create_agent(client_config)\n try:\n result = await agent.run(\n role=role_config,\n prompt=prompt_text,\n system_prompt=system_prompt_text if system_prompt_text.strip() else None,\n files=absolute_file_paths,\n images=images,\n )\n except CLIAgentError as exc:\n metadata = self._build_error_metadata(client_config, exc)\n self._raise_tool_error(\n f\"CLI '{client_config.name}' execution failed: {exc}\",\n metadata=metadata,\n )\n\n metadata = self._build_success_metadata(client_config, role_config, result)\n metadata = self._prune_metadata(metadata, client_config, reason=\"normal\")\n\n content, metadata = self._apply_output_limit(\n client_config,\n result.parsed.content,\n metadata,\n )\n\n model_info = {\n \"provider\": client_config.name,\n \"model_name\": result.parsed.metadata.get(\"model_used\"),\n }\n\n if continuation_id:\n try:\n self._record_assistant_turn(continuation_id, content, request, model_info)\n except Exception:\n logger.debug(\"Failed to record assistant turn for continuation %s\", continuation_id, exc_info=True)\n\n continuation_offer = self._create_continuation_offer(request, model_info)\n if continuation_offer:\n tool_output = self._create_continuation_offer_response(\n content,\n continuation_offer,\n request,\n model_info,\n )\n tool_output.metadata = self._merge_metadata(tool_output.metadata, metadata)\n else:\n tool_output = ToolOutput(\n status=\"success\",\n content=content,\n content_type=\"text\",\n metadata=metadata,\n )\n\n return [TextContent(type=\"text\", text=tool_output.model_dump_json())]\n\n async def prepare_prompt(self, request) -> str:\n client_config = self._registry.get_client(request.cli_name)\n role_config = client_config.get_role(request.role)\n system_prompt_text = role_config.prompt_path.read_text(encoding=\"utf-8\")\n include_system_prompt = not self._use_external_system_prompt(client_config)\n return await self._prepare_prompt_for_role(\n request,\n role_config,\n system_prompt=system_prompt_text,\n include_system_prompt=include_system_prompt,\n )\n\n async def _prepare_prompt_for_role(\n self,\n request: CLinkRequest,\n role: ResolvedCLIRole,\n *,\n system_prompt: str,\n include_system_prompt: bool,\n ) -> str:\n \"\"\"Load the role prompt and assemble the final user message.\"\"\"\n self._active_system_prompt = system_prompt\n try:\n user_content = self.handle_prompt_file_with_fallback(request).strip()\n guidance = self._agent_capabilities_guidance()\n file_section = self._format_file_references(self.get_request_files(request))\n\n sections: list[str] = []\n active_prompt = self.get_system_prompt().strip()\n if include_system_prompt and active_prompt:\n sections.append(active_prompt)\n sections.append(guidance)\n sections.append(\"=== USER REQUEST ===\\n\" + user_content)\n if file_section:\n sections.append(\"=== FILE REFERENCES ===\\n\" + file_section)\n sections.append(\"Provide your response below using your own CLI tools as needed:\")\n return \"\\n\\n\".join(sections)\n finally:\n self._active_system_prompt = \"\"\n\n def _use_external_system_prompt(self, client: ResolvedCLIClient) -> bool:\n runner_name = (client.runner or client.name).lower()\n return runner_name == \"claude\"\n\n def _build_success_metadata(\n self,\n client: ResolvedCLIClient,\n role: ResolvedCLIRole,\n result: AgentOutput,\n ) -> dict[str, Any]:\n \"\"\"Capture execution metadata for successful CLI calls.\"\"\"\n metadata: dict[str, Any] = {\n \"cli_name\": client.name,\n \"role\": role.name,\n \"command\": result.sanitized_command,\n \"duration_seconds\": round(result.duration_seconds, 3),\n \"parser\": result.parser_name,\n \"return_code\": result.returncode,\n }\n metadata.update(result.parsed.metadata)\n\n if result.stderr.strip():\n metadata.setdefault(\"stderr\", result.stderr.strip())\n if result.output_file_content and \"raw\" not in metadata:\n metadata[\"raw_output_file\"] = result.output_file_content\n return metadata\n\n def _merge_metadata(self, base: dict[str, Any] | None, extra: dict[str, Any]) -> dict[str, Any]:\n merged = dict(base or {})\n merged.update(extra)\n return merged\n\n def _apply_output_limit(\n self,\n client: ResolvedCLIClient,\n content: str,\n metadata: dict[str, Any],\n ) -> tuple[str, dict[str, Any]]:\n if len(content) <= MAX_RESPONSE_CHARS:\n return content, metadata\n\n summary = self._extract_summary(content)\n if summary:\n summary_text = summary\n if len(summary_text) > MAX_RESPONSE_CHARS:\n logger.debug(\n \"Clink summary from %s exceeded %d chars; truncating summary to fit.\",\n client.name,\n MAX_RESPONSE_CHARS,\n )\n summary_text = summary_text[:MAX_RESPONSE_CHARS]\n summary_metadata = self._prune_metadata(metadata, client, reason=\"summary\")\n summary_metadata.update(\n {\n \"output_summarized\": True,\n \"output_original_length\": len(content),\n \"output_summary_length\": len(summary_text),\n \"output_limit\": MAX_RESPONSE_CHARS,\n }\n )\n logger.info(\n \"Clink compressed %s output via : original=%d chars, summary=%d chars\",\n client.name,\n len(content),\n len(summary_text),\n )\n return summary_text, summary_metadata\n\n truncated_metadata = self._prune_metadata(metadata, client, reason=\"truncated\")\n truncated_metadata.update(\n {\n \"output_truncated\": True,\n \"output_original_length\": len(content),\n \"output_limit\": MAX_RESPONSE_CHARS,\n }\n )\n\n excerpt_limit = min(4000, MAX_RESPONSE_CHARS // 2)\n excerpt = content[:excerpt_limit]\n truncated_metadata[\"output_excerpt_length\"] = len(excerpt)\n\n logger.warning(\n \"Clink truncated %s output: original=%d chars exceeds limit=%d; excerpt_length=%d\",\n client.name,\n len(content),\n MAX_RESPONSE_CHARS,\n len(excerpt),\n )\n\n message = (\n f\"CLI '{client.name}' produced {len(content)} characters, exceeding the configured clink limit \"\n f\"({MAX_RESPONSE_CHARS} characters). The full output was suppressed to stay within MCP response caps. \"\n \"Please narrow the request (review fewer files, summarize results) or run the CLI directly for the full log.\\n\\n\"\n f\"--- Begin excerpt ({len(excerpt)} of {len(content)} chars) ---\\n{excerpt}\\n--- End excerpt ---\"\n )\n\n return message, truncated_metadata\n\n def _extract_summary(self, content: str) -> str | None:\n match = SUMMARY_PATTERN.search(content)\n if not match:\n return None\n summary = match.group(1).strip()\n return summary or None\n\n def _prune_metadata(\n self,\n metadata: dict[str, Any],\n client: ResolvedCLIClient,\n *,\n reason: str,\n ) -> dict[str, Any]:\n cleaned = dict(metadata)\n events = cleaned.pop(\"events\", None)\n if events is not None:\n cleaned[f\"events_removed_for_{reason}\"] = True\n logger.debug(\n \"Clink dropped %s events metadata for %s response (%s)\",\n client.name,\n reason,\n type(events).__name__,\n )\n return cleaned\n\n def _build_error_metadata(self, client: ResolvedCLIClient, exc: CLIAgentError) -> dict[str, Any]:\n \"\"\"Assemble metadata for failed CLI calls.\"\"\"\n metadata: dict[str, Any] = {\n \"cli_name\": client.name,\n \"return_code\": exc.returncode,\n }\n if exc.stdout:\n metadata[\"stdout\"] = exc.stdout.strip()\n if exc.stderr:\n metadata[\"stderr\"] = exc.stderr.strip()\n return metadata\n\n def _raise_tool_error(self, message: str, metadata: dict[str, Any] | None = None) -> None:\n error_output = ToolOutput(status=\"error\", content=message, content_type=\"text\", metadata=metadata)\n raise ToolExecutionError(error_output.model_dump_json())\n\n def _agent_capabilities_guidance(self) -> str:\n return (\n \"You are operating through the Gemini CLI agent. You have access to your full suite of \"\n \"CLI capabilitiesβ€”including launching web searches, reading files, and using any other \"\n \"available tools. Gather current information yourself and deliver the final answer without \"\n \"asking the PAL MCP host to perform searches or file reads.\"\n )\n\n def _format_file_references(self, files: list[str]) -> str:\n if not files:\n return \"\"\n\n references: list[str] = []\n for file_path in files:\n try:\n path = Path(file_path)\n stat = path.stat()\n modified = datetime.fromtimestamp(stat.st_mtime, tz=timezone.utc).isoformat()\n size = stat.st_size\n references.append(f\"- {file_path} (last modified {modified}, {size} bytes)\")\n except OSError:\n references.append(f\"- {file_path} (unavailable)\")\n return \"\\n\".join(references)\n" }, { "path": "tools/codereview.py", "content": "\"\"\"\nCodeReview Workflow tool - Systematic code review with step-by-step analysis\n\nThis tool provides a structured workflow for comprehensive code review and analysis.\nIt guides the CLI agent through systematic investigation steps with forced pauses between each step\nto ensure thorough code examination, issue identification, and quality assessment before proceeding.\nThe tool supports complex review scenarios including security analysis, performance evaluation,\nand architectural assessment.\n\nKey features:\n- Step-by-step code review workflow with progress tracking\n- Context-aware file embedding (references during investigation, full content for analysis)\n- Automatic issue tracking with severity classification\n- Expert analysis integration with external models\n- Support for focused reviews (security, performance, architecture)\n- Confidence-based workflow optimization\n\"\"\"\n\nimport logging\nfrom typing import TYPE_CHECKING, Any, Literal, Optional\n\nfrom pydantic import Field, model_validator\n\nif TYPE_CHECKING:\n from tools.models import ToolModelCategory\n\nfrom config import TEMPERATURE_ANALYTICAL\nfrom systemprompts import CODEREVIEW_PROMPT\nfrom tools.shared.base_models import WorkflowRequest\n\nfrom .workflow.base import WorkflowTool\n\nlogger = logging.getLogger(__name__)\n\n# Tool-specific field descriptions for code review workflow\nCODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS = {\n \"step\": (\n \"Review narrative. Step 1: outline the review strategy. Later steps: report findings. MUST cover quality, security, \"\n \"performance, and architecture. Reference code via `relevant_files`; avoid dumping large snippets.\"\n ),\n \"step_number\": \"Current review step (starts at 1) – each step should build on the last.\",\n \"total_steps\": (\n \"Number of review steps planned. External validation: two steps (analysis + summary). Internal validation: one step. \"\n \"Use the same limits when continuing an existing review via continuation_id.\"\n ),\n \"next_step_required\": (\n \"True when another review step follows. External validation: step 1 β†’ True, step 2 β†’ False. Internal validation: set False immediately. \"\n \"Apply the same rule on continuation flows.\"\n ),\n \"findings\": \"Capture findings (positive and negative) across quality, security, performance, and architecture; update each step.\",\n \"files_checked\": \"Absolute paths of every file reviewed, including those ruled out.\",\n \"relevant_files\": \"Step 1: list all files/dirs under review. Must be absolute full non-abbreviated paths. Final step: narrow to files tied to key findings.\",\n \"relevant_context\": \"Functions or methods central to findings (e.g. 'Class.method' or 'function_name').\",\n \"issues_found\": \"Issues with severity (critical/high/medium/low) and descriptions.\",\n \"review_validation_type\": \"Set 'external' (default) for expert follow-up or 'internal' for local-only review.\",\n \"images\": \"Optional diagram or screenshot paths that clarify review context.\",\n \"review_type\": \"Review focus: full, security, performance, or quick.\",\n \"focus_on\": \"Optional note on areas to emphasise (e.g. 'threading', 'auth flow').\",\n \"standards\": \"Coding standards or style guides to enforce.\",\n \"severity_filter\": \"Lowest severity to include when reporting issues (critical/high/medium/low/all).\",\n}\n\n\nclass CodeReviewRequest(WorkflowRequest):\n \"\"\"Request model for code review workflow investigation steps\"\"\"\n\n # Required fields for each investigation step\n step: str = Field(..., description=CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"step\"])\n step_number: int = Field(..., description=CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"step_number\"])\n total_steps: int = Field(..., description=CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"total_steps\"])\n next_step_required: bool = Field(..., description=CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"next_step_required\"])\n\n # Investigation tracking fields\n findings: str = Field(..., description=CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"findings\"])\n files_checked: list[str] = Field(\n default_factory=list, description=CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"files_checked\"]\n )\n relevant_files: list[str] = Field(\n default_factory=list, description=CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_files\"]\n )\n relevant_context: list[str] = Field(\n default_factory=list, description=CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_context\"]\n )\n issues_found: list[dict] = Field(\n default_factory=list, description=CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"issues_found\"]\n )\n # Deprecated confidence field kept for backward compatibility only\n confidence: Optional[str] = Field(\"low\", exclude=True)\n review_validation_type: Optional[Literal[\"external\", \"internal\"]] = Field(\n \"external\", description=CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS.get(\"review_validation_type\", \"\")\n )\n\n # Optional images for visual context\n images: Optional[list[str]] = Field(default=None, description=CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"images\"])\n\n # Code review-specific fields (only used in step 1 to initialize)\n review_type: Optional[Literal[\"full\", \"security\", \"performance\", \"quick\"]] = Field(\n \"full\", description=CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"review_type\"]\n )\n focus_on: Optional[str] = Field(None, description=CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"focus_on\"])\n standards: Optional[str] = Field(None, description=CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"standards\"])\n severity_filter: Optional[Literal[\"critical\", \"high\", \"medium\", \"low\", \"all\"]] = Field(\n \"all\", description=CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"severity_filter\"]\n )\n\n # Override inherited fields to exclude them from schema (except model which needs to be available)\n temperature: Optional[float] = Field(default=None, exclude=True)\n thinking_mode: Optional[str] = Field(default=None, exclude=True)\n\n @model_validator(mode=\"after\")\n def validate_step_one_requirements(self):\n \"\"\"Ensure step 1 has required relevant_files field.\"\"\"\n if self.step_number == 1 and not self.relevant_files:\n raise ValueError(\"Step 1 requires 'relevant_files' field to specify code files or directories to review\")\n return self\n\n\nclass CodeReviewTool(WorkflowTool):\n \"\"\"\n Code Review workflow tool for step-by-step code review and expert analysis.\n\n This tool implements a structured code review workflow that guides users through\n methodical investigation steps, ensuring thorough code examination, issue identification,\n and quality assessment before reaching conclusions. It supports complex review scenarios\n including security audits, performance analysis, architectural review, and maintainability assessment.\n \"\"\"\n\n def __init__(self):\n super().__init__()\n self.initial_request = None\n self.review_config = {}\n\n def get_name(self) -> str:\n return \"codereview\"\n\n def get_description(self) -> str:\n return (\n \"Performs systematic, step-by-step code review with expert validation. \"\n \"Use for comprehensive analysis covering quality, security, performance, and architecture. \"\n \"Guides through structured investigation to ensure thoroughness.\"\n )\n\n def get_system_prompt(self) -> str:\n return CODEREVIEW_PROMPT\n\n def get_default_temperature(self) -> float:\n return TEMPERATURE_ANALYTICAL\n\n def get_model_category(self) -> \"ToolModelCategory\":\n \"\"\"Code review requires thorough analysis and reasoning\"\"\"\n from tools.models import ToolModelCategory\n\n return ToolModelCategory.EXTENDED_REASONING\n\n def get_workflow_request_model(self):\n \"\"\"Return the code review workflow-specific request model.\"\"\"\n return CodeReviewRequest\n\n def get_input_schema(self) -> dict[str, Any]:\n \"\"\"Generate input schema using WorkflowSchemaBuilder with code review-specific overrides.\"\"\"\n from .workflow.schema_builders import WorkflowSchemaBuilder\n\n # Code review workflow-specific field overrides\n codereview_field_overrides = {\n \"step\": {\n \"type\": \"string\",\n \"description\": CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"step\"],\n },\n \"step_number\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"step_number\"],\n },\n \"total_steps\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"total_steps\"],\n },\n \"next_step_required\": {\n \"type\": \"boolean\",\n \"description\": CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"next_step_required\"],\n },\n \"findings\": {\n \"type\": \"string\",\n \"description\": CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"findings\"],\n },\n \"files_checked\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"files_checked\"],\n },\n \"relevant_files\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_files\"],\n },\n \"review_validation_type\": {\n \"type\": \"string\",\n \"enum\": [\"external\", \"internal\"],\n \"default\": \"external\",\n \"description\": CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS.get(\"review_validation_type\", \"\"),\n },\n \"issues_found\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"object\"},\n \"description\": CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"issues_found\"],\n },\n \"images\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"images\"],\n },\n # Code review-specific fields (for step 1)\n \"review_type\": {\n \"type\": \"string\",\n \"enum\": [\"full\", \"security\", \"performance\", \"quick\"],\n \"default\": \"full\",\n \"description\": CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"review_type\"],\n },\n \"focus_on\": {\n \"type\": \"string\",\n \"description\": CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"focus_on\"],\n },\n \"standards\": {\n \"type\": \"string\",\n \"description\": CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"standards\"],\n },\n \"severity_filter\": {\n \"type\": \"string\",\n \"enum\": [\"critical\", \"high\", \"medium\", \"low\", \"all\"],\n \"default\": \"all\",\n \"description\": CODEREVIEW_WORKFLOW_FIELD_DESCRIPTIONS[\"severity_filter\"],\n },\n }\n\n # Use WorkflowSchemaBuilder with code review-specific tool fields\n return WorkflowSchemaBuilder.build_schema(\n tool_specific_fields=codereview_field_overrides,\n model_field_schema=self.get_model_field_schema(),\n auto_mode=self.is_effective_auto_mode(),\n tool_name=self.get_name(),\n )\n\n def get_required_actions(\n self, step_number: int, confidence: str, findings: str, total_steps: int, request=None\n ) -> list[str]:\n \"\"\"Define required actions for each investigation phase.\n\n Now includes request parameter for continuation-aware decisions.\n \"\"\"\n # Check for continuation - fast track mode\n if request:\n continuation_id = self.get_request_continuation_id(request)\n validation_type = self.get_review_validation_type(request)\n if continuation_id and validation_type == \"external\":\n if step_number == 1:\n return [\n \"Quickly review the code files to understand context\",\n \"Identify any critical issues that need immediate attention\",\n \"Note main architectural patterns and design decisions\",\n \"Prepare summary of key findings for expert validation\",\n ]\n else:\n return [\"Complete review and proceed to expert analysis\"]\n\n if step_number == 1:\n # Initial code review investigation tasks\n return [\n \"Read and understand the code files specified for review\",\n \"Examine the overall structure, architecture, and design patterns used\",\n \"Identify the main components, classes, and functions in the codebase\",\n \"Understand the business logic and intended functionality\",\n \"Look for obvious issues: bugs, security concerns, performance problems\",\n \"Note any code smells, anti-patterns, or areas of concern\",\n ]\n elif step_number == 2:\n # Deeper investigation for step 2\n return [\n \"Examine specific code sections you've identified as concerning\",\n \"Analyze security implications: input validation, authentication, authorization\",\n \"Check for performance issues: algorithmic complexity, resource usage, inefficiencies\",\n \"Look for architectural problems: tight coupling, missing abstractions, scalability issues\",\n \"Identify code quality issues: readability, maintainability, error handling\",\n \"Search for over-engineering, unnecessary complexity, or design patterns that could be simplified\",\n ]\n elif step_number >= 3:\n # Final verification for later steps\n return [\n \"Verify all identified issues have been properly documented with severity levels\",\n \"Check for any missed critical security vulnerabilities or performance bottlenecks\",\n \"Confirm that architectural concerns and code quality issues are comprehensively captured\",\n \"Ensure positive aspects and well-implemented patterns are also noted\",\n \"Validate that your assessment aligns with the review type and focus areas specified\",\n \"Double-check that findings are actionable and provide clear guidance for improvements\",\n ]\n else:\n # General investigation needed\n return [\n \"Continue examining the codebase for additional patterns and potential issues\",\n \"Gather more evidence using appropriate code analysis techniques\",\n \"Test your assumptions about code behavior and design decisions\",\n \"Look for patterns that confirm or refute your current assessment\",\n \"Focus on areas that haven't been thoroughly examined yet\",\n ]\n\n def should_call_expert_analysis(self, consolidated_findings, request=None) -> bool:\n \"\"\"\n Decide when to call external model based on investigation completeness.\n\n For continuations with external type, always proceed with expert analysis.\n \"\"\"\n # Check if user requested to skip assistant model\n if request and not self.get_request_use_assistant_model(request):\n return False\n\n # For continuations with external type, always proceed with expert analysis\n continuation_id = self.get_request_continuation_id(request)\n validation_type = self.get_review_validation_type(request)\n if continuation_id and validation_type == \"external\":\n return True # Always perform expert analysis for external continuations\n\n # Check if we have meaningful investigation data\n return (\n len(consolidated_findings.relevant_files) > 0\n or len(consolidated_findings.findings) >= 2\n or len(consolidated_findings.issues_found) > 0\n )\n\n def prepare_expert_analysis_context(self, consolidated_findings) -> str:\n \"\"\"Prepare context for external model call for final code review validation.\"\"\"\n context_parts = [\n f\"=== CODE REVIEW REQUEST ===\\\\n{self.initial_request or 'Code review workflow initiated'}\\\\n=== END REQUEST ===\"\n ]\n\n # Add investigation summary\n investigation_summary = self._build_code_review_summary(consolidated_findings)\n context_parts.append(\n f\"\\\\n=== AGENT'S CODE REVIEW INVESTIGATION ===\\\\n{investigation_summary}\\\\n=== END INVESTIGATION ===\"\n )\n\n # Add review configuration context if available\n if self.review_config:\n config_text = \"\\\\n\".join(f\"- {key}: {value}\" for key, value in self.review_config.items() if value)\n context_parts.append(f\"\\\\n=== REVIEW CONFIGURATION ===\\\\n{config_text}\\\\n=== END CONFIGURATION ===\")\n\n # Add relevant code elements if available\n if consolidated_findings.relevant_context:\n methods_text = \"\\\\n\".join(f\"- {method}\" for method in consolidated_findings.relevant_context)\n context_parts.append(f\"\\\\n=== RELEVANT CODE ELEMENTS ===\\\\n{methods_text}\\\\n=== END CODE ELEMENTS ===\")\n\n # Add issues found if available\n if consolidated_findings.issues_found:\n issues_text = \"\\\\n\".join(\n f\"[{issue.get('severity', 'unknown').upper()}] {issue.get('description', 'No description')}\"\n for issue in consolidated_findings.issues_found\n )\n context_parts.append(f\"\\\\n=== ISSUES IDENTIFIED ===\\\\n{issues_text}\\\\n=== END ISSUES ===\")\n\n # Add assessment evolution if available\n if consolidated_findings.hypotheses:\n assessments_text = \"\\\\n\".join(\n f\"Step {h['step']} ({h['confidence']} confidence): {h['hypothesis']}\"\n for h in consolidated_findings.hypotheses\n )\n context_parts.append(f\"\\\\n=== ASSESSMENT EVOLUTION ===\\\\n{assessments_text}\\\\n=== END ASSESSMENTS ===\")\n\n # Add images if available\n if consolidated_findings.images:\n images_text = \"\\\\n\".join(f\"- {img}\" for img in consolidated_findings.images)\n context_parts.append(\n f\"\\\\n=== VISUAL REVIEW INFORMATION ===\\\\n{images_text}\\\\n=== END VISUAL INFORMATION ===\"\n )\n\n return \"\\\\n\".join(context_parts)\n\n def _build_code_review_summary(self, consolidated_findings) -> str:\n \"\"\"Prepare a comprehensive summary of the code review investigation.\"\"\"\n summary_parts = [\n \"=== SYSTEMATIC CODE REVIEW INVESTIGATION SUMMARY ===\",\n f\"Total steps: {len(consolidated_findings.findings)}\",\n f\"Files examined: {len(consolidated_findings.files_checked)}\",\n f\"Relevant files identified: {len(consolidated_findings.relevant_files)}\",\n f\"Code elements analyzed: {len(consolidated_findings.relevant_context)}\",\n f\"Issues identified: {len(consolidated_findings.issues_found)}\",\n \"\",\n \"=== INVESTIGATION PROGRESSION ===\",\n ]\n\n for finding in consolidated_findings.findings:\n summary_parts.append(finding)\n\n return \"\\\\n\".join(summary_parts)\n\n def should_include_files_in_expert_prompt(self) -> bool:\n \"\"\"Include files in expert analysis for comprehensive code review.\"\"\"\n return True\n\n def should_embed_system_prompt(self) -> bool:\n \"\"\"Embed system prompt in expert analysis for proper context.\"\"\"\n return True\n\n def get_expert_thinking_mode(self) -> str:\n \"\"\"Use high thinking mode for thorough code review analysis.\"\"\"\n return \"high\"\n\n def get_expert_analysis_instruction(self) -> str:\n \"\"\"Get specific instruction for code review expert analysis.\"\"\"\n return (\n \"Please provide comprehensive code review analysis based on the investigation findings. \"\n \"Focus on identifying any remaining issues, validating the completeness of the analysis, \"\n \"and providing final recommendations for code improvements, following the severity-based \"\n \"format specified in the system prompt.\"\n )\n\n # Hook method overrides for code review-specific behavior\n\n def prepare_step_data(self, request) -> dict:\n \"\"\"\n Map code review-specific fields for internal processing.\n \"\"\"\n step_data = {\n \"step\": request.step,\n \"step_number\": request.step_number,\n \"findings\": request.findings,\n \"files_checked\": request.files_checked,\n \"relevant_files\": request.relevant_files,\n \"relevant_context\": request.relevant_context,\n \"issues_found\": request.issues_found,\n \"review_validation_type\": self.get_review_validation_type(request),\n \"hypothesis\": request.findings, # Map findings to hypothesis for compatibility\n \"images\": request.images or [],\n \"confidence\": \"high\", # Dummy value for workflow_mixin compatibility\n }\n return step_data\n\n def should_skip_expert_analysis(self, request, consolidated_findings) -> bool:\n \"\"\"\n Code review workflow skips expert analysis only when review_validation_type is \"internal\".\n Default is always to use expert analysis (external).\n For continuations with external type, always perform expert analysis immediately.\n \"\"\"\n # If it's a continuation and review_validation_type is external, don't skip\n continuation_id = self.get_request_continuation_id(request)\n validation_type = self.get_review_validation_type(request)\n if continuation_id and validation_type != \"internal\":\n return False # Always do expert analysis for external continuations\n\n # Only skip if explicitly set to internal AND review is complete\n return validation_type == \"internal\" and not request.next_step_required\n\n def store_initial_issue(self, step_description: str):\n \"\"\"Store initial request for expert analysis.\"\"\"\n self.initial_request = step_description\n\n # Override inheritance hooks for code review-specific behavior\n\n def get_review_validation_type(self, request) -> str:\n \"\"\"Get review validation type from request. Hook method for clean inheritance.\"\"\"\n try:\n return request.review_validation_type or \"external\"\n except AttributeError:\n return \"external\" # Default to external validation\n\n def get_completion_status(self) -> str:\n \"\"\"Code review tools use review-specific status.\"\"\"\n return \"code_review_complete_ready_for_implementation\"\n\n def get_completion_data_key(self) -> str:\n \"\"\"Code review uses 'complete_code_review' key.\"\"\"\n return \"complete_code_review\"\n\n def get_final_analysis_from_request(self, request):\n \"\"\"Code review tools use 'findings' field.\"\"\"\n return request.findings\n\n def get_confidence_level(self, request) -> str:\n \"\"\"Code review tools use 'certain' for high confidence.\"\"\"\n return \"certain\"\n\n def get_completion_message(self) -> str:\n \"\"\"Code review-specific completion message.\"\"\"\n return (\n \"Code review complete. You have identified all significant issues \"\n \"and provided comprehensive analysis. MANDATORY: Present the user with the complete review results \"\n \"categorized by severity, and IMMEDIATELY proceed with implementing the highest priority fixes \"\n \"or provide specific guidance for improvements. Focus on actionable recommendations.\"\n )\n\n def get_skip_reason(self) -> str:\n \"\"\"Code review-specific skip reason.\"\"\"\n return \"Completed comprehensive code review with internal analysis only (no external model validation)\"\n\n def get_skip_expert_analysis_status(self) -> str:\n \"\"\"Code review-specific expert analysis skip status.\"\"\"\n return \"skipped_due_to_internal_analysis_type\"\n\n def prepare_work_summary(self) -> str:\n \"\"\"Code review-specific work summary.\"\"\"\n return self._build_code_review_summary(self.consolidated_findings)\n\n def get_completion_next_steps_message(self, expert_analysis_used: bool = False) -> str:\n \"\"\"\n Code review-specific completion message.\n \"\"\"\n base_message = (\n \"CODE REVIEW IS COMPLETE. You MUST now summarize and present ALL review findings organized by \"\n \"severity (Critical β†’ High β†’ Medium β†’ Low), specific code locations with line numbers, and exact \"\n \"recommendations for improvement. Clearly prioritize the top 3 issues that need immediate attention. \"\n \"Provide concrete, actionable guidance for each issueβ€”make it easy for a developer to understand \"\n \"exactly what needs to be fixed and how to implement the improvements.\"\n )\n\n # Add expert analysis guidance only when expert analysis was actually used\n if expert_analysis_used:\n expert_guidance = self.get_expert_analysis_guidance()\n if expert_guidance:\n return f\"{base_message}\\n\\n{expert_guidance}\"\n\n return base_message\n\n def get_expert_analysis_guidance(self) -> str:\n \"\"\"\n Provide specific guidance for handling expert analysis in code reviews.\n \"\"\"\n return (\n \"IMPORTANT: Analysis from an assistant model has been provided above. You MUST critically evaluate and validate \"\n \"the expert findings rather than accepting them blindly. Cross-reference the expert analysis with \"\n \"your own investigation findings, verify that suggested improvements are appropriate for this \"\n \"codebase's context and patterns, and ensure recommendations align with the project's standards. \"\n \"Present a synthesis that combines your systematic review with validated expert insights, clearly \"\n \"distinguishing between findings you've independently confirmed and additional insights from expert analysis.\"\n )\n\n def get_step_guidance_message(self, request) -> str:\n \"\"\"\n Code review-specific step guidance with detailed investigation instructions.\n \"\"\"\n step_guidance = self.get_code_review_step_guidance(request.step_number, request)\n return step_guidance[\"next_steps\"]\n\n def get_code_review_step_guidance(self, step_number: int, request) -> dict[str, Any]:\n \"\"\"\n Provide step-specific guidance for code review workflow.\n Uses get_required_actions to determine what needs to be done,\n then formats those actions into appropriate guidance messages.\n \"\"\"\n # Get the required actions from the single source of truth\n required_actions = self.get_required_actions(\n step_number,\n \"medium\", # Dummy value for backward compatibility\n request.findings or \"\",\n request.total_steps,\n request, # Pass request for continuation-aware decisions\n )\n\n # Check if this is a continuation to provide context-aware guidance\n continuation_id = self.get_request_continuation_id(request)\n validation_type = self.get_review_validation_type(request)\n is_external_continuation = continuation_id and validation_type == \"external\"\n is_internal_continuation = continuation_id and validation_type == \"internal\"\n\n # Step 1 handling\n if step_number == 1:\n if is_external_continuation:\n # Fast-track for external continuations\n return {\n \"next_steps\": (\n \"You are on step 1 of MAXIMUM 2 steps for continuation. CRITICAL: Quickly review the code NOW. \"\n \"MANDATORY ACTIONS:\\\\n\"\n + \"\\\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + \"\\\\n\\\\nSet next_step_required=True and step_number=2 for the next call to trigger expert analysis.\"\n )\n }\n elif is_internal_continuation:\n # Internal validation mode\n next_steps = (\n \"Continuing previous conversation with internal validation only. The analysis will build \"\n \"upon the prior findings without external model validation. REQUIRED ACTIONS:\\\\n\"\n + \"\\\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n )\n else:\n # Normal flow for new reviews\n next_steps = (\n f\"MANDATORY: DO NOT call the {self.get_name()} tool again immediately. You MUST first examine \"\n f\"the code files thoroughly using appropriate tools. CRITICAL AWARENESS: You need to:\\\\n\"\n + \"\\\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\\\n\\\\nOnly call {self.get_name()} again AFTER completing your investigation. \"\n f\"When you call {self.get_name()} next time, use step_number: {step_number + 1} \"\n f\"and report specific files examined, issues found, and code quality assessments discovered.\"\n )\n\n elif step_number == 2:\n # CRITICAL: Check if violating minimum step requirement\n if (\n request.total_steps >= 3\n and request.step_number < request.total_steps\n and not request.next_step_required\n ):\n next_steps = (\n f\"ERROR: You set total_steps={request.total_steps} but next_step_required=False on step {request.step_number}. \"\n f\"This violates the minimum step requirement. You MUST set next_step_required=True until you reach the final step. \"\n f\"Call {self.get_name()} again with next_step_required=True and continue your investigation.\"\n )\n elif is_external_continuation or (not request.next_step_required and validation_type == \"external\"):\n # Fast-track completion or about to complete for external validation\n next_steps = (\n \"Proceeding immediately to expert analysis. \"\n f\"MANDATORY: call {self.get_name()} tool immediately again, and set next_step_required=False to \"\n f\"trigger external validation NOW.\"\n )\n else:\n # Normal flow - deeper analysis needed\n next_steps = (\n f\"STOP! Do NOT call {self.get_name()} again yet. You are on step 2 of {request.total_steps} minimum required steps. \"\n f\"MANDATORY ACTIONS before calling {self.get_name()} step {step_number + 1}:\\\\n\"\n + \"\\\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\\\n\\\\nRemember: You MUST set next_step_required=True until step {request.total_steps}. \"\n + f\"Only call {self.get_name()} again with step_number: {step_number + 1} AFTER completing these code review tasks.\"\n )\n\n elif step_number >= 3:\n if not request.next_step_required and validation_type == \"external\":\n # About to complete - ready for expert analysis\n next_steps = (\n \"Completing review and proceeding to expert analysis. \"\n \"Ensure all findings are documented with specific file references and line numbers.\"\n )\n else:\n # Later steps - final verification\n next_steps = (\n f\"WAIT! Your code review needs final verification. DO NOT call {self.get_name()} immediately. REQUIRED ACTIONS:\\\\n\"\n + \"\\\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\\\n\\\\nREMEMBER: Ensure you have identified all significant issues across all severity levels and \"\n f\"verified the completeness of your review. Document findings with specific file references and \"\n f\"line numbers where applicable, then call {self.get_name()} with step_number: {step_number + 1}.\"\n )\n else:\n # Fallback for any other case - check minimum step violation first\n if (\n request.total_steps >= 3\n and request.step_number < request.total_steps\n and not request.next_step_required\n ):\n next_steps = (\n f\"ERROR: You set total_steps={request.total_steps} but next_step_required=False on step {request.step_number}. \"\n f\"This violates the minimum step requirement. You MUST set next_step_required=True until step {request.total_steps}.\"\n )\n elif not request.next_step_required and validation_type == \"external\":\n next_steps = (\n \"Completing review. \"\n \"Ensure all findings are documented with specific file references and severity levels.\"\n )\n else:\n next_steps = (\n f\"PAUSE REVIEW. Before calling {self.get_name()} step {step_number + 1}, you MUST examine more code thoroughly. \"\n + \"Required: \"\n + \", \".join(required_actions[:2])\n + \". \"\n + f\"Your next {self.get_name()} call (step_number: {step_number + 1}) must include \"\n f\"NEW evidence from actual code analysis, not just theories. NO recursive {self.get_name()} calls \"\n f\"without investigation work!\"\n )\n\n return {\"next_steps\": next_steps}\n\n def customize_workflow_response(self, response_data: dict, request) -> dict:\n \"\"\"\n Customize response to match code review workflow format.\n \"\"\"\n # Store initial request on first step\n if request.step_number == 1:\n self.initial_request = request.step\n # Store review configuration for expert analysis\n if request.relevant_files:\n self.review_config = {\n \"relevant_files\": request.relevant_files,\n \"review_type\": request.review_type,\n \"focus_on\": request.focus_on,\n \"standards\": request.standards,\n \"severity_filter\": request.severity_filter,\n }\n\n # Convert generic status names to code review-specific ones\n tool_name = self.get_name()\n status_mapping = {\n f\"{tool_name}_in_progress\": \"code_review_in_progress\",\n f\"pause_for_{tool_name}\": \"pause_for_code_review\",\n f\"{tool_name}_required\": \"code_review_required\",\n f\"{tool_name}_complete\": \"code_review_complete\",\n }\n\n if response_data[\"status\"] in status_mapping:\n response_data[\"status\"] = status_mapping[response_data[\"status\"]]\n\n # Rename status field to match code review workflow\n if f\"{tool_name}_status\" in response_data:\n response_data[\"code_review_status\"] = response_data.pop(f\"{tool_name}_status\")\n # Add code review-specific status fields\n response_data[\"code_review_status\"][\"issues_by_severity\"] = {}\n for issue in self.consolidated_findings.issues_found:\n severity = issue.get(\"severity\", \"unknown\")\n if severity not in response_data[\"code_review_status\"][\"issues_by_severity\"]:\n response_data[\"code_review_status\"][\"issues_by_severity\"][severity] = 0\n response_data[\"code_review_status\"][\"issues_by_severity\"][severity] += 1\n response_data[\"code_review_status\"][\"review_validation_type\"] = self.get_review_validation_type(request)\n\n # Map complete_codereviewworkflow to complete_code_review\n if f\"complete_{tool_name}\" in response_data:\n response_data[\"complete_code_review\"] = response_data.pop(f\"complete_{tool_name}\")\n\n # Map the completion flag to match code review workflow\n if f\"{tool_name}_complete\" in response_data:\n response_data[\"code_review_complete\"] = response_data.pop(f\"{tool_name}_complete\")\n\n return response_data\n\n # Required abstract methods from BaseTool\n def get_request_model(self):\n \"\"\"Return the code review workflow-specific request model.\"\"\"\n return CodeReviewRequest\n\n async def prepare_prompt(self, request) -> str:\n \"\"\"Not used - workflow tools use execute_workflow().\"\"\"\n return \"\" # Workflow tools use execute_workflow() directly\n" }, { "path": "tools/consensus.py", "content": "\"\"\"\nConsensus tool - Step-by-step multi-model consensus with expert analysis\n\nThis tool provides a structured workflow for gathering consensus from multiple models.\nIt guides the CLI agent through systematic steps where the CLI agent first provides its own analysis,\nthen consults each requested model one by one, and finally synthesizes all perspectives.\n\nKey features:\n- Step-by-step consensus workflow with progress tracking\n- The CLI agent's initial neutral analysis followed by model-specific consultations\n- Context-aware file embedding\n- Support for stance-based analysis (for/against/neutral)\n- Final synthesis combining all perspectives\n\"\"\"\n\nfrom __future__ import annotations\n\nimport json\nimport logging\nfrom typing import TYPE_CHECKING, Any\n\nfrom pydantic import Field, model_validator\n\nif TYPE_CHECKING:\n from tools.models import ToolModelCategory\n\nfrom mcp.types import TextContent\n\nfrom config import TEMPERATURE_ANALYTICAL\nfrom systemprompts import CONSENSUS_PROMPT\nfrom tools.shared.base_models import ConsolidatedFindings, WorkflowRequest\nfrom utils.conversation_memory import MAX_CONVERSATION_TURNS, create_thread, get_thread\n\nfrom .workflow.base import WorkflowTool\n\nlogger = logging.getLogger(__name__)\n\n# Tool-specific field descriptions for consensus workflow\nCONSENSUS_WORKFLOW_FIELD_DESCRIPTIONS = {\n \"step\": (\n \"Consensus prompt. Step 1: write the exact proposal/question every model will see (use 'Evaluate…', not meta commentary). \"\n \"Steps 2+: capture internal notes about the latest model responseβ€”these notes are NOT sent to other models.\"\n ),\n \"step_number\": \"Current step index (starts at 1). Step 1 is your analysis; steps 2+ handle each model response.\",\n \"total_steps\": \"Total steps = number of models consulted plus the final synthesis step.\",\n \"next_step_required\": \"True if more model consultations remain; set false when ready to synthesize.\",\n \"findings\": (\n \"Step 1: your independent analysis for later synthesis (not shared with other models). Steps 2+: summarize the newest model response.\"\n ),\n \"relevant_files\": \"Optional supporting files that help the consensus analysis. Must be absolute full, non-abbreviated paths.\",\n \"models\": (\n \"User-specified list of models to consult (provide at least two entries). \"\n \"Each entry may include model, stance (for/against/neutral), and stance_prompt. \"\n \"Each (model, stance) pair must be unique, e.g. [{'model':'gpt5','stance':'for'}, {'model':'pro','stance':'against'}].\"\n ),\n \"current_model_index\": \"0-based index of the next model to consult (managed internally).\",\n \"model_responses\": \"Internal log of responses gathered so far.\",\n \"images\": \"Optional absolute image paths or base64 references that add helpful visual context.\",\n}\n\n\nclass ConsensusRequest(WorkflowRequest):\n \"\"\"Request model for consensus workflow steps\"\"\"\n\n # Required fields for each step\n step: str = Field(..., description=CONSENSUS_WORKFLOW_FIELD_DESCRIPTIONS[\"step\"])\n step_number: int = Field(..., description=CONSENSUS_WORKFLOW_FIELD_DESCRIPTIONS[\"step_number\"])\n total_steps: int = Field(..., description=CONSENSUS_WORKFLOW_FIELD_DESCRIPTIONS[\"total_steps\"])\n next_step_required: bool = Field(..., description=CONSENSUS_WORKFLOW_FIELD_DESCRIPTIONS[\"next_step_required\"])\n\n # Investigation tracking fields\n findings: str = Field(..., description=CONSENSUS_WORKFLOW_FIELD_DESCRIPTIONS[\"findings\"])\n confidence: str = Field(default=\"exploring\", exclude=True, description=\"Not used\")\n\n # Consensus-specific fields (only needed in step 1)\n models: list[dict] | None = Field(None, description=CONSENSUS_WORKFLOW_FIELD_DESCRIPTIONS[\"models\"])\n relevant_files: list[str] | None = Field(\n default_factory=list,\n description=CONSENSUS_WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_files\"],\n )\n\n # Internal tracking fields\n current_model_index: int | None = Field(\n 0,\n description=CONSENSUS_WORKFLOW_FIELD_DESCRIPTIONS[\"current_model_index\"],\n )\n model_responses: list[dict] | None = Field(\n default_factory=list,\n description=CONSENSUS_WORKFLOW_FIELD_DESCRIPTIONS[\"model_responses\"],\n )\n\n # Optional images for visual debugging\n images: list[str] | None = Field(default=None, description=CONSENSUS_WORKFLOW_FIELD_DESCRIPTIONS[\"images\"])\n\n # Override inherited fields to exclude them from schema\n temperature: float | None = Field(default=None, exclude=True)\n thinking_mode: str | None = Field(default=None, exclude=True)\n\n # Not used in consensus workflow\n files_checked: list[str] | None = Field(default_factory=list, exclude=True)\n relevant_context: list[str] | None = Field(default_factory=list, exclude=True)\n issues_found: list[dict] | None = Field(default_factory=list, exclude=True)\n hypothesis: str | None = Field(None, exclude=True)\n\n @model_validator(mode=\"after\")\n def validate_step_one_requirements(self):\n \"\"\"Ensure step 1 has required models field and unique model+stance combinations.\"\"\"\n if self.step_number == 1:\n if not self.models:\n raise ValueError(\"Step 1 requires 'models' field to specify which models to consult\")\n\n # Check for unique model + stance combinations\n seen_combinations = set()\n for model_config in self.models:\n model_name = model_config.get(\"model\", \"\")\n stance = model_config.get(\"stance\", \"neutral\")\n combination = f\"{model_name}:{stance}\"\n\n if combination in seen_combinations:\n raise ValueError(\n f\"Duplicate model + stance combination found: {model_name} with stance '{stance}'. \"\n f\"Each model + stance combination must be unique.\"\n )\n seen_combinations.add(combination)\n\n return self\n\n\nclass ConsensusTool(WorkflowTool):\n \"\"\"\n Consensus workflow tool for step-by-step multi-model consensus gathering.\n\n This tool implements a structured consensus workflow where the CLI agent first provides\n its own neutral analysis, then consults each specified model individually,\n and finally synthesizes all perspectives into a unified recommendation.\n \"\"\"\n\n def __init__(self):\n super().__init__()\n self.initial_prompt: str | None = None\n self.original_proposal: str | None = None # Store the original proposal separately\n self.models_to_consult: list[dict] = []\n self.accumulated_responses: list[dict] = []\n self._current_arguments: dict[str, Any] = {}\n\n def get_name(self) -> str:\n return \"consensus\"\n\n def get_description(self) -> str:\n return (\n \"Builds multi-model consensus through systematic analysis and structured debate. \"\n \"Use for complex decisions, architectural choices, feature proposals, and technology evaluations. \"\n \"Consults multiple models with different stances to synthesize comprehensive recommendations.\"\n )\n\n def get_system_prompt(self) -> str:\n # For the CLI agent's initial analysis, use a neutral version of the consensus prompt\n return CONSENSUS_PROMPT.replace(\n \"{stance_prompt}\",\n \"\"\"BALANCED PERSPECTIVE\n\nProvide objective analysis considering both positive and negative aspects. However, if there is overwhelming evidence\nthat the proposal clearly leans toward being exceptionally good or particularly problematic, you MUST accurately\nreflect this reality. Being \"balanced\" means being truthful about the weight of evidence, not artificially creating\n50/50 splits when the reality is 90/10.\n\nYour analysis should:\n- Present all significant pros and cons discovered\n- Weight them according to actual impact and likelihood\n- If evidence strongly favors one conclusion, clearly state this\n- Provide proportional coverage based on the strength of arguments\n- Help the questioner see the true balance of considerations\n\nRemember: Artificial balance that misrepresents reality is not helpful. True balance means accurate representation\nof the evidence, even when it strongly points in one direction.\"\"\",\n )\n\n def get_default_temperature(self) -> float:\n return TEMPERATURE_ANALYTICAL\n\n def get_model_category(self) -> ToolModelCategory:\n \"\"\"Consensus workflow requires extended reasoning\"\"\"\n from tools.models import ToolModelCategory\n\n return ToolModelCategory.EXTENDED_REASONING\n\n def get_workflow_request_model(self):\n \"\"\"Return the consensus workflow-specific request model.\"\"\"\n return ConsensusRequest\n\n def get_input_schema(self) -> dict[str, Any]:\n \"\"\"Generate input schema for consensus workflow.\"\"\"\n from .workflow.schema_builders import WorkflowSchemaBuilder\n\n # Consensus tool-specific field definitions\n consensus_field_overrides = {\n # Override standard workflow fields that need consensus-specific descriptions\n \"step\": {\n \"type\": \"string\",\n \"description\": CONSENSUS_WORKFLOW_FIELD_DESCRIPTIONS[\"step\"],\n },\n \"step_number\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": CONSENSUS_WORKFLOW_FIELD_DESCRIPTIONS[\"step_number\"],\n },\n \"total_steps\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": CONSENSUS_WORKFLOW_FIELD_DESCRIPTIONS[\"total_steps\"],\n },\n \"next_step_required\": {\n \"type\": \"boolean\",\n \"description\": CONSENSUS_WORKFLOW_FIELD_DESCRIPTIONS[\"next_step_required\"],\n },\n \"findings\": {\n \"type\": \"string\",\n \"description\": CONSENSUS_WORKFLOW_FIELD_DESCRIPTIONS[\"findings\"],\n },\n \"relevant_files\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": CONSENSUS_WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_files\"],\n },\n # consensus-specific fields (not in base workflow)\n \"models\": {\n \"type\": \"array\",\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"model\": {\"type\": \"string\"},\n \"stance\": {\"type\": \"string\", \"enum\": [\"for\", \"against\", \"neutral\"], \"default\": \"neutral\"},\n \"stance_prompt\": {\"type\": \"string\"},\n },\n \"required\": [\"model\"],\n },\n \"description\": (\n \"User-specified roster of models to consult (provide at least two entries). \"\n + CONSENSUS_WORKFLOW_FIELD_DESCRIPTIONS[\"models\"]\n ),\n \"minItems\": 2,\n },\n \"current_model_index\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"description\": CONSENSUS_WORKFLOW_FIELD_DESCRIPTIONS[\"current_model_index\"],\n },\n \"model_responses\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"object\"},\n \"description\": CONSENSUS_WORKFLOW_FIELD_DESCRIPTIONS[\"model_responses\"],\n },\n \"images\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": CONSENSUS_WORKFLOW_FIELD_DESCRIPTIONS[\"images\"],\n },\n }\n\n # Provide guidance on available models similar to single-model tools\n model_description = (\n \"When the user names a model, you MUST use that exact value or report the \"\n \"provider errorβ€”never swap in another option. Use the `listmodels` tool for the full roster.\"\n )\n\n summaries, total, restricted = self._get_ranked_model_summaries()\n remainder = max(0, total - len(summaries))\n if summaries:\n label = \"Allowed models\" if restricted else \"Top models\"\n top_line = \"; \".join(summaries)\n if remainder > 0:\n top_line = f\"{label}: {top_line}; +{remainder} more via `listmodels`.\"\n else:\n top_line = f\"{label}: {top_line}.\"\n model_description = f\"{model_description} {top_line}\"\n else:\n model_description = (\n f\"{model_description} No models detectedβ€”configure provider credentials or use the `listmodels` tool \"\n \"to inspect availability.\"\n )\n\n restriction_note = self._get_restriction_note()\n if restriction_note and (remainder > 0 or not summaries):\n model_description = f\"{model_description} {restriction_note}.\"\n\n existing_models_desc = consensus_field_overrides[\"models\"][\"description\"]\n consensus_field_overrides[\"models\"][\"description\"] = f\"{existing_models_desc} {model_description}\"\n\n # Define excluded fields for consensus workflow\n excluded_workflow_fields = [\n \"files_checked\", # Not used in consensus workflow\n \"relevant_context\", # Not used in consensus workflow\n \"issues_found\", # Not used in consensus workflow\n \"hypothesis\", # Not used in consensus workflow\n \"confidence\", # Not used in consensus workflow\n ]\n\n excluded_common_fields = [\n \"model\", # Consensus uses 'models' field instead\n \"temperature\", # Not used in consensus workflow\n \"thinking_mode\", # Not used in consensus workflow\n ]\n\n requires_model = self.requires_model()\n model_field_schema = self.get_model_field_schema() if requires_model else None\n auto_mode = self.is_effective_auto_mode() if requires_model else False\n\n return WorkflowSchemaBuilder.build_schema(\n tool_specific_fields=consensus_field_overrides,\n model_field_schema=model_field_schema,\n auto_mode=auto_mode,\n tool_name=self.get_name(),\n excluded_workflow_fields=excluded_workflow_fields,\n excluded_common_fields=excluded_common_fields,\n require_model=requires_model,\n )\n\n def get_required_actions(\n self, step_number: int, confidence: str, findings: str, total_steps: int, request=None\n ) -> list[str]: # noqa: ARG002\n \"\"\"Define required actions for each consensus phase.\n\n Now includes request parameter for continuation-aware decisions.\n Note: confidence parameter is kept for compatibility with base class but not used.\n \"\"\"\n if step_number == 1:\n # CLI Agent's initial analysis\n return [\n \"You've provided your initial analysis. The tool will now consult other models.\",\n \"Wait for the next step to receive the first model's response.\",\n ]\n elif step_number < total_steps - 1:\n # Processing individual model responses\n return [\n \"Review the model response provided in this step\",\n \"Note key agreements and disagreements with previous analyses\",\n \"Wait for the next model's response\",\n ]\n else:\n # Ready for final synthesis\n return [\n \"All models have been consulted\",\n \"Synthesize all perspectives into a comprehensive recommendation\",\n \"Identify key points of agreement and disagreement\",\n \"Provide clear, actionable guidance based on the consensus\",\n ]\n\n def should_call_expert_analysis(self, consolidated_findings, request=None) -> bool:\n \"\"\"Consensus workflow doesn't use traditional expert analysis - it consults models step by step.\"\"\"\n return False\n\n def prepare_expert_analysis_context(self, consolidated_findings) -> str:\n \"\"\"Not used in consensus workflow.\"\"\"\n return \"\"\n\n def requires_expert_analysis(self) -> bool:\n \"\"\"Consensus workflow handles its own model consultations.\"\"\"\n return False\n\n def requires_model(self) -> bool:\n \"\"\"\n Consensus tool doesn't require model resolution at the MCP boundary.\n\n Uses it's own set of models\n\n Returns:\n bool: False\n \"\"\"\n return False\n\n # Hook method overrides for consensus-specific behavior\n\n def prepare_step_data(self, request) -> dict:\n \"\"\"Prepare consensus-specific step data.\"\"\"\n step_data = {\n \"step\": request.step,\n \"step_number\": request.step_number,\n \"findings\": request.findings,\n \"files_checked\": [], # Not used\n \"relevant_files\": request.relevant_files or [],\n \"relevant_context\": [], # Not used\n \"issues_found\": [], # Not used\n \"confidence\": \"exploring\", # Not used, kept for compatibility\n \"hypothesis\": None, # Not used\n \"images\": request.images or [], # Now used for visual context\n }\n return step_data\n\n async def handle_work_completion(self, response_data: dict, request, arguments: dict) -> dict: # noqa: ARG002\n \"\"\"Handle consensus workflow completion - no expert analysis, just final synthesis.\"\"\"\n response_data[\"consensus_complete\"] = True\n response_data[\"status\"] = \"consensus_workflow_complete\"\n\n # Prepare final synthesis data\n response_data[\"complete_consensus\"] = {\n \"initial_prompt\": self.original_proposal if self.original_proposal else self.initial_prompt,\n \"models_consulted\": [m[\"model\"] + \":\" + m.get(\"stance\", \"neutral\") for m in self.accumulated_responses],\n \"total_responses\": len(self.accumulated_responses),\n \"consensus_confidence\": \"high\", # Consensus complete\n }\n\n response_data[\"next_steps\"] = (\n \"CONSENSUS GATHERING IS COMPLETE. You MUST now synthesize all perspectives and present:\\n\"\n \"1. Key points of AGREEMENT across models\\n\"\n \"2. Key points of DISAGREEMENT and why they differ\\n\"\n \"3. Your final consolidated recommendation\\n\"\n \"4. Specific, actionable next steps for implementation\\n\"\n \"5. Critical risks or concerns that must be addressed\"\n )\n\n return response_data\n\n def handle_work_continuation(self, response_data: dict, request) -> dict:\n \"\"\"Handle continuation between consensus steps.\"\"\"\n current_idx = request.current_model_index or 0\n\n if request.step_number == 1:\n # After CLI Agent's initial analysis, prepare to consult first model\n response_data[\"status\"] = \"consulting_models\"\n response_data[\"next_model\"] = self.models_to_consult[0] if self.models_to_consult else None\n response_data[\"next_steps\"] = (\n \"Your initial analysis is complete. The tool will now consult the specified models.\"\n )\n elif current_idx < len(self.models_to_consult):\n next_model = self.models_to_consult[current_idx]\n response_data[\"status\"] = \"consulting_next_model\"\n response_data[\"next_model\"] = next_model\n response_data[\"models_remaining\"] = len(self.models_to_consult) - current_idx\n response_data[\"next_steps\"] = f\"Model consultation in progress. Next: {next_model['model']}\"\n else:\n response_data[\"status\"] = \"ready_for_synthesis\"\n response_data[\"next_steps\"] = \"All models consulted. Ready for final synthesis.\"\n\n return response_data\n\n async def execute_workflow(self, arguments: dict[str, Any]) -> list:\n \"\"\"Override execute_workflow to handle model consultations between steps.\"\"\"\n\n # Store arguments\n self._current_arguments = arguments\n\n # Validate request\n request = self.get_workflow_request_model()(**arguments)\n\n # Resolve existing continuation_id or create a new one on first step\n continuation_id = request.continuation_id\n\n if request.step_number == 1:\n if not continuation_id:\n clean_args = {k: v for k, v in arguments.items() if k not in [\"_model_context\", \"_resolved_model_name\"]}\n continuation_id = create_thread(self.get_name(), clean_args)\n request.continuation_id = continuation_id\n arguments[\"continuation_id\"] = continuation_id\n self.work_history = []\n self.consolidated_findings = ConsolidatedFindings()\n\n # Store the original proposal from step 1 - this is what all models should see\n self.store_initial_issue(request.step)\n self.initial_request = request.step\n self.models_to_consult = request.models or []\n self.accumulated_responses = []\n # Set total steps: len(models) (each step includes consultation + response)\n request.total_steps = len(self.models_to_consult)\n\n # For all steps (1 through total_steps), consult the corresponding model\n if request.step_number <= request.total_steps:\n # Calculate which model to consult for this step\n model_idx = request.step_number - 1 # 0-based index\n\n if model_idx < len(self.models_to_consult):\n # Track workflow state for conversation memory\n step_data = self.prepare_step_data(request)\n self.work_history.append(step_data)\n self._update_consolidated_findings(step_data)\n\n # Consult the model for this step\n model_response = await self._consult_model(self.models_to_consult[model_idx], request)\n\n # Add to accumulated responses\n self.accumulated_responses.append(model_response)\n\n # Include the model response in the step data\n response_data = {\n \"status\": \"model_consulted\",\n \"step_number\": request.step_number,\n \"total_steps\": request.total_steps,\n \"model_consulted\": model_response[\"model\"],\n \"model_stance\": model_response.get(\"stance\", \"neutral\"),\n \"model_response\": model_response,\n \"current_model_index\": model_idx + 1,\n \"next_step_required\": request.step_number < request.total_steps,\n }\n\n # Add CLAI Agent's analysis to step 1\n if request.step_number == 1:\n response_data[\"agent_analysis\"] = {\n \"initial_analysis\": request.step,\n \"findings\": request.findings,\n }\n response_data[\"status\"] = \"analysis_and_first_model_consulted\"\n\n # Check if this is the final step\n if request.step_number == request.total_steps:\n response_data[\"status\"] = \"consensus_workflow_complete\"\n response_data[\"consensus_complete\"] = True\n response_data[\"complete_consensus\"] = {\n \"initial_prompt\": self.original_proposal if self.original_proposal else self.initial_prompt,\n \"models_consulted\": [\n f\"{m['model']}:{m.get('stance', 'neutral')}\" for m in self.accumulated_responses\n ],\n \"total_responses\": len(self.accumulated_responses),\n \"consensus_confidence\": \"high\",\n }\n response_data[\"next_steps\"] = (\n \"CONSENSUS GATHERING IS COMPLETE. Synthesize all perspectives and present:\\n\"\n \"1. Key points of AGREEMENT across models\\n\"\n \"2. Key points of DISAGREEMENT and why they differ\\n\"\n \"3. Your final consolidated recommendation\\n\"\n \"4. Specific, actionable next steps for implementation\\n\"\n \"5. Critical risks or concerns that must be addressed\"\n )\n else:\n response_data[\"next_steps\"] = (\n f\"Model {model_response['model']} has provided its {model_response.get('stance', 'neutral')} \"\n f\"perspective. Please analyze this response and call {self.get_name()} again with:\\n\"\n f\"- step_number: {request.step_number + 1}\\n\"\n f\"- findings: Summarize key points from this model's response\"\n )\n\n # Add continuation information and workflow customization\n response_data = self.customize_workflow_response(response_data, request)\n\n # Ensure consensus-specific metadata is attached\n self._add_workflow_metadata(response_data, arguments)\n\n if continuation_id:\n self.store_conversation_turn(continuation_id, response_data, request)\n continuation_offer = self._build_continuation_offer(continuation_id)\n if continuation_offer:\n response_data[\"continuation_offer\"] = continuation_offer\n\n return [TextContent(type=\"text\", text=json.dumps(response_data, indent=2, ensure_ascii=False))]\n\n # Otherwise, use standard workflow execution\n return await super().execute_workflow(arguments)\n\n def _build_continuation_offer(self, continuation_id: str) -> dict[str, Any] | None:\n \"\"\"Create a continuation offer without exposing prior model responses.\"\"\"\n try:\n from tools.models import ContinuationOffer\n\n thread = get_thread(continuation_id)\n if thread and thread.turns:\n remaining_turns = max(0, MAX_CONVERSATION_TURNS - len(thread.turns))\n else:\n remaining_turns = MAX_CONVERSATION_TURNS - 1\n\n # Provide a neutral note specific to consensus workflow\n note = (\n f\"Consensus workflow can continue for {remaining_turns} more exchanges.\"\n if remaining_turns > 0\n else \"Consensus workflow continuation limit reached.\"\n )\n\n continuation_offer = ContinuationOffer(\n continuation_id=continuation_id,\n note=note,\n remaining_turns=remaining_turns,\n )\n return continuation_offer.model_dump()\n except Exception:\n return None\n\n async def _consult_model(self, model_config: dict, request) -> dict:\n \"\"\"Consult a single model and return its response.\"\"\"\n try:\n # Import and create ModelContext once at the beginning\n from utils.model_context import ModelContext\n\n # Get the provider for this model\n model_name = model_config[\"model\"]\n provider = self.get_model_provider(model_name)\n\n # Create model context once and reuse for both file processing and temperature validation\n model_context = ModelContext(model_name=model_name)\n\n # Prepare the prompt with any relevant files\n # Use continuation_id=None for blinded consensus - each model should only see\n # original prompt + files, not conversation history or other model responses\n # CRITICAL: Use the original proposal from step 1, NOT what's in request.step for steps 2+!\n # Steps 2+ contain summaries/notes that must NEVER be sent to other models\n prompt = self.original_proposal if self.original_proposal else self.initial_prompt\n if request.relevant_files:\n file_content, _ = self._prepare_file_content_for_prompt(\n request.relevant_files,\n None, # Use None instead of request.continuation_id for blinded consensus\n \"Context files\",\n model_context=model_context,\n )\n if file_content:\n prompt = f\"{prompt}\\n\\n=== CONTEXT FILES ===\\n{file_content}\\n=== END CONTEXT ===\"\n\n # Get stance-specific system prompt\n stance = model_config.get(\"stance\", \"neutral\")\n stance_prompt = model_config.get(\"stance_prompt\")\n system_prompt = self._get_stance_enhanced_prompt(stance, stance_prompt)\n\n # Validate temperature against model constraints (respects supports_temperature)\n validated_temperature, temp_warnings = self.validate_and_correct_temperature(\n self.get_default_temperature(), model_context\n )\n\n # Log any temperature corrections\n for warning in temp_warnings:\n logger.warning(warning)\n\n # Call the model with validated temperature\n response = provider.generate_content(\n prompt=prompt,\n model_name=model_name,\n system_prompt=system_prompt,\n temperature=validated_temperature,\n thinking_mode=\"medium\",\n images=request.images if request.images else None,\n )\n\n return {\n \"model\": model_name,\n \"stance\": stance,\n \"status\": \"success\",\n \"verdict\": response.content,\n \"metadata\": {\n \"provider\": provider.get_provider_type().value,\n \"model_name\": model_name,\n },\n }\n\n except Exception as e:\n logger.exception(\"Error consulting model %s\", model_config)\n return {\n \"model\": model_config.get(\"model\", \"unknown\"),\n \"stance\": model_config.get(\"stance\", \"neutral\"),\n \"status\": \"error\",\n \"error\": str(e),\n }\n\n def _get_stance_enhanced_prompt(self, stance: str, custom_stance_prompt: str | None = None) -> str:\n \"\"\"Get the system prompt with stance injection.\"\"\"\n base_prompt = CONSENSUS_PROMPT\n\n if custom_stance_prompt:\n return base_prompt.replace(\"{stance_prompt}\", custom_stance_prompt)\n\n stance_prompts = {\n \"for\": \"\"\"SUPPORTIVE PERSPECTIVE WITH INTEGRITY\n\nYou are tasked with advocating FOR this proposal, but with CRITICAL GUARDRAILS:\n\nMANDATORY ETHICAL CONSTRAINTS:\n- This is NOT a debate for entertainment. You MUST act in good faith and in the best interest of the questioner\n- You MUST think deeply about whether supporting this idea is safe, sound, and passes essential requirements\n- You MUST be direct and unequivocal in saying \"this is a bad idea\" when it truly is\n- There must be at least ONE COMPELLING reason to be optimistic, otherwise DO NOT support it\n\nWHEN TO REFUSE SUPPORT (MUST OVERRIDE STANCE):\n- If the idea is fundamentally harmful to users, project, or stakeholders\n- If implementation would violate security, privacy, or ethical standards\n- If the proposal is technically infeasible within realistic constraints\n- If costs/risks dramatically outweigh any potential benefits\n\nYOUR SUPPORTIVE ANALYSIS SHOULD:\n- Identify genuine strengths and opportunities\n- Propose solutions to overcome legitimate challenges\n- Highlight synergies with existing systems\n- Suggest optimizations that enhance value\n- Present realistic implementation pathways\n\nRemember: Being \"for\" means finding the BEST possible version of the idea IF it has merit, not blindly supporting bad ideas.\"\"\",\n \"against\": \"\"\"CRITICAL PERSPECTIVE WITH RESPONSIBILITY\n\nYou are tasked with critiquing this proposal, but with ESSENTIAL BOUNDARIES:\n\nMANDATORY FAIRNESS CONSTRAINTS:\n- You MUST NOT oppose genuinely excellent, common-sense ideas just to be contrarian\n- You MUST acknowledge when a proposal is fundamentally sound and well-conceived\n- You CANNOT give harmful advice or recommend against beneficial changes\n- If the idea is outstanding, say so clearly while offering constructive refinements\n\nWHEN TO MODERATE CRITICISM (MUST OVERRIDE STANCE):\n- If the proposal addresses critical user needs effectively\n- If it follows established best practices with good reason\n- If benefits clearly and substantially outweigh risks\n- If it's the obvious right solution to the problem\n\nYOUR CRITICAL ANALYSIS SHOULD:\n- Identify legitimate risks and failure modes\n- Point out overlooked complexities\n- Suggest more efficient alternatives\n- Highlight potential negative consequences\n- Question assumptions that may be flawed\n\nRemember: Being \"against\" means rigorous scrutiny to ensure quality, not undermining good ideas that deserve support.\"\"\",\n \"neutral\": \"\"\"BALANCED PERSPECTIVE\n\nProvide objective analysis considering both positive and negative aspects. However, if there is overwhelming evidence\nthat the proposal clearly leans toward being exceptionally good or particularly problematic, you MUST accurately\nreflect this reality. Being \"balanced\" means being truthful about the weight of evidence, not artificially creating\n50/50 splits when the reality is 90/10.\n\nYour analysis should:\n- Present all significant pros and cons discovered\n- Weight them according to actual impact and likelihood\n- If evidence strongly favors one conclusion, clearly state this\n- Provide proportional coverage based on the strength of arguments\n- Help the questioner see the true balance of considerations\n\nRemember: Artificial balance that misrepresents reality is not helpful. True balance means accurate representation\nof the evidence, even when it strongly points in one direction.\"\"\",\n }\n\n stance_prompt = stance_prompts.get(stance, stance_prompts[\"neutral\"])\n return base_prompt.replace(\"{stance_prompt}\", stance_prompt)\n\n def customize_workflow_response(self, response_data: dict, request) -> dict:\n \"\"\"Customize response for consensus workflow.\"\"\"\n # Store model responses in the response for tracking\n if self.accumulated_responses:\n response_data[\"accumulated_responses\"] = self.accumulated_responses\n\n # Add consensus-specific fields\n if request.step_number == 1:\n response_data[\"consensus_workflow_status\"] = \"initial_analysis_complete\"\n elif request.step_number < request.total_steps - 1:\n response_data[\"consensus_workflow_status\"] = \"consulting_models\"\n else:\n response_data[\"consensus_workflow_status\"] = \"ready_for_synthesis\"\n\n # Customize metadata for consensus workflow\n self._customize_consensus_metadata(response_data, request)\n\n return response_data\n\n def _customize_consensus_metadata(self, response_data: dict, request) -> None:\n \"\"\"\n Customize metadata for consensus workflow to accurately reflect multi-model nature.\n\n The default workflow metadata shows the model running Agent's analysis steps,\n but consensus is a multi-model tool that consults different models. We need\n to provide accurate metadata that reflects this.\n \"\"\"\n if \"metadata\" not in response_data:\n response_data[\"metadata\"] = {}\n\n metadata = response_data[\"metadata\"]\n\n # Always preserve tool_name\n metadata[\"tool_name\"] = self.get_name()\n\n if request.step_number == request.total_steps:\n # Final step - show comprehensive consensus metadata\n models_consulted = []\n if self.models_to_consult:\n models_consulted = [f\"{m['model']}:{m.get('stance', 'neutral')}\" for m in self.models_to_consult]\n\n metadata.update(\n {\n \"workflow_type\": \"multi_model_consensus\",\n \"models_consulted\": models_consulted,\n \"consensus_complete\": True,\n \"total_models\": len(self.models_to_consult) if self.models_to_consult else 0,\n }\n )\n\n # Remove the misleading single model metadata\n metadata.pop(\"model_used\", None)\n metadata.pop(\"provider_used\", None)\n\n else:\n # Intermediate steps - show consensus workflow in progress\n models_to_consult = []\n if self.models_to_consult:\n models_to_consult = [f\"{m['model']}:{m.get('stance', 'neutral')}\" for m in self.models_to_consult]\n\n metadata.update(\n {\n \"workflow_type\": \"multi_model_consensus\",\n \"models_to_consult\": models_to_consult,\n \"consultation_step\": request.step_number,\n \"total_consultation_steps\": request.total_steps,\n }\n )\n\n # Remove the misleading single model metadata that shows Agent's execution model\n # instead of the models being consulted\n metadata.pop(\"model_used\", None)\n metadata.pop(\"provider_used\", None)\n\n def _add_workflow_metadata(self, response_data: dict, arguments: dict[str, Any]) -> None:\n \"\"\"\n Override workflow metadata addition for consensus tool.\n\n The consensus tool doesn't use single model metadata because it's a multi-model\n workflow. Instead, we provide consensus-specific metadata that accurately\n reflects the models being consulted.\n \"\"\"\n # Initialize metadata if not present\n if \"metadata\" not in response_data:\n response_data[\"metadata\"] = {}\n\n # Add basic tool metadata\n response_data[\"metadata\"][\"tool_name\"] = self.get_name()\n\n # The consensus-specific metadata is already added by _customize_consensus_metadata\n # which is called from customize_workflow_response. We don't add the standard\n # single-model metadata (model_used, provider_used) because it's misleading\n # for a multi-model consensus workflow.\n\n logger.debug(\n f\"[CONSENSUS_METADATA] {self.get_name()}: Using consensus-specific metadata instead of single-model metadata\"\n )\n\n def store_initial_issue(self, step_description: str):\n \"\"\"Store initial prompt for model consultations.\"\"\"\n self.original_proposal = step_description\n self.initial_prompt = step_description # Keep for backward compatibility\n\n # Required abstract methods from BaseTool\n def get_request_model(self):\n \"\"\"Return the consensus workflow-specific request model.\"\"\"\n return ConsensusRequest\n\n async def prepare_prompt(self, request) -> str: # noqa: ARG002\n \"\"\"Not used - workflow tools use execute_workflow().\"\"\"\n return \"\" # Workflow tools use execute_workflow() directly\n" }, { "path": "tools/debug.py", "content": "\"\"\"\nDebug tool - Systematic root cause analysis and debugging assistance\n\nThis tool provides a structured workflow for investigating complex bugs and issues.\nIt guides you through systematic investigation steps with forced pauses between each step\nto ensure thorough code examination before proceeding. The tool supports hypothesis evolution\nand expert analysis integration for comprehensive debugging.\n\nKey features:\n- Step-by-step investigation workflow with progress tracking\n- Context-aware file embedding (references during investigation, full content for analysis)\n- Automatic conversation threading and history preservation\n- Expert analysis integration with external models\n- Support for visual debugging with image context\n- Confidence-based workflow optimization\n\"\"\"\n\nimport logging\nfrom typing import TYPE_CHECKING, Any, Optional\n\nfrom pydantic import Field\n\nif TYPE_CHECKING:\n from tools.models import ToolModelCategory\n\nfrom config import TEMPERATURE_ANALYTICAL\nfrom systemprompts import DEBUG_ISSUE_PROMPT\nfrom tools.shared.base_models import WorkflowRequest\n\nfrom .workflow.base import WorkflowTool\n\nlogger = logging.getLogger(__name__)\n\n# Tool-specific field descriptions matching original debug tool\nDEBUG_INVESTIGATION_FIELD_DESCRIPTIONS = {\n \"step\": (\n \"Investigation step. Step 1: State issue+direction. \"\n \"Symptoms misleading; 'no bug' valid. Trace dependencies, verify hypotheses. \"\n \"Use relevant_files for code; this for text only.\"\n ),\n \"step_number\": \"Current step index (starts at 1). Build upon previous steps.\",\n \"total_steps\": (\n \"Estimated total steps needed to complete the investigation. Adjust as new findings emerge. \"\n \"IMPORTANT: When continuation_id is provided (continuing a previous conversation), set this to 1 as we're not starting a new multi-step investigation.\"\n ),\n \"next_step_required\": (\n \"True if you plan to continue the investigation with another step. False means root cause is known or investigation is complete. \"\n \"IMPORTANT: When continuation_id is provided (continuing a previous conversation), set this to False to immediately proceed with expert analysis.\"\n ),\n \"findings\": (\n \"Discoveries: clues, code/log evidence, disproven theories. Be specific. \"\n \"If no bug found, document clearly as valid.\"\n ),\n \"files_checked\": \"All examined files (absolute paths), including ruled-out ones.\",\n \"relevant_files\": \"Files directly relevant to issue (absolute paths). Cause, trigger, or manifestation locations.\",\n \"relevant_context\": \"Methods/functions central to issue: 'Class.method' or 'function'. Focus on inputs/branching/state.\",\n \"hypothesis\": (\n \"Concrete root cause theory from evidence. Can revise. \"\n \"Valid: 'No bug found - user misunderstanding' or 'Symptoms unrelated to code' if supported.\"\n ),\n \"confidence\": (\n \"Your confidence in the hypothesis: exploring (starting out), low (early idea), medium (some evidence), \"\n \"high (strong evidence), very_high (very strong evidence), almost_certain (nearly confirmed), \"\n \"certain (100% confidence - root cause and fix are both confirmed locally with no need for external validation). \"\n \"WARNING: Do NOT use 'certain' unless the issue can be fully resolved with a fix, use 'very_high' or 'almost_certain' instead when not 100% sure. \"\n \"Using 'certain' means you have ABSOLUTE confidence locally and PREVENTS external model validation.\"\n ),\n \"images\": \"Optional screenshots/visuals clarifying issue (absolute paths).\",\n}\n\n\nclass DebugInvestigationRequest(WorkflowRequest):\n \"\"\"Request model for debug investigation steps matching original debug tool exactly\"\"\"\n\n # Required fields for each investigation step\n step: str = Field(..., description=DEBUG_INVESTIGATION_FIELD_DESCRIPTIONS[\"step\"])\n step_number: int = Field(..., description=DEBUG_INVESTIGATION_FIELD_DESCRIPTIONS[\"step_number\"])\n total_steps: int = Field(..., description=DEBUG_INVESTIGATION_FIELD_DESCRIPTIONS[\"total_steps\"])\n next_step_required: bool = Field(..., description=DEBUG_INVESTIGATION_FIELD_DESCRIPTIONS[\"next_step_required\"])\n\n # Investigation tracking fields\n findings: str = Field(..., description=DEBUG_INVESTIGATION_FIELD_DESCRIPTIONS[\"findings\"])\n files_checked: list[str] = Field(\n default_factory=list, description=DEBUG_INVESTIGATION_FIELD_DESCRIPTIONS[\"files_checked\"]\n )\n relevant_files: list[str] = Field(\n default_factory=list, description=DEBUG_INVESTIGATION_FIELD_DESCRIPTIONS[\"relevant_files\"]\n )\n relevant_context: list[str] = Field(\n default_factory=list, description=DEBUG_INVESTIGATION_FIELD_DESCRIPTIONS[\"relevant_context\"]\n )\n hypothesis: Optional[str] = Field(None, description=DEBUG_INVESTIGATION_FIELD_DESCRIPTIONS[\"hypothesis\"])\n confidence: Optional[str] = Field(\"low\", description=DEBUG_INVESTIGATION_FIELD_DESCRIPTIONS[\"confidence\"])\n\n # Optional images for visual debugging\n images: Optional[list[str]] = Field(default=None, description=DEBUG_INVESTIGATION_FIELD_DESCRIPTIONS[\"images\"])\n\n # Override inherited fields to exclude them from schema (except model which needs to be available)\n temperature: Optional[float] = Field(default=None, exclude=True)\n thinking_mode: Optional[str] = Field(default=None, exclude=True)\n\n\nclass DebugIssueTool(WorkflowTool):\n \"\"\"\n Debug tool for systematic root cause analysis and issue investigation.\n\n This tool implements a structured debugging workflow that guides users through\n methodical investigation steps, ensuring thorough code examination and evidence\n gathering before reaching conclusions. It supports complex debugging scenarios\n including race conditions, memory leaks, performance issues, and integration problems.\n \"\"\"\n\n def __init__(self):\n super().__init__()\n self.initial_issue = None\n\n def get_name(self) -> str:\n return \"debug\"\n\n def get_description(self) -> str:\n return (\n \"Performs systematic debugging and root cause analysis for any type of issue. \"\n \"Use for complex bugs, mysterious errors, performance issues, race conditions, memory leaks, and integration problems. \"\n \"Guides through structured investigation with hypothesis testing and expert analysis.\"\n )\n\n def get_system_prompt(self) -> str:\n return DEBUG_ISSUE_PROMPT\n\n def get_default_temperature(self) -> float:\n return TEMPERATURE_ANALYTICAL\n\n def get_model_category(self) -> \"ToolModelCategory\":\n \"\"\"Debug requires deep analysis and reasoning\"\"\"\n from tools.models import ToolModelCategory\n\n return ToolModelCategory.EXTENDED_REASONING\n\n def get_workflow_request_model(self):\n \"\"\"Return the debug-specific request model.\"\"\"\n return DebugInvestigationRequest\n\n def get_input_schema(self) -> dict[str, Any]:\n \"\"\"Generate input schema using WorkflowSchemaBuilder with debug-specific overrides.\"\"\"\n from .workflow.schema_builders import WorkflowSchemaBuilder\n\n # Debug-specific field overrides\n debug_field_overrides = {\n \"step\": {\n \"type\": \"string\",\n \"description\": DEBUG_INVESTIGATION_FIELD_DESCRIPTIONS[\"step\"],\n },\n \"step_number\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": DEBUG_INVESTIGATION_FIELD_DESCRIPTIONS[\"step_number\"],\n },\n \"total_steps\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": DEBUG_INVESTIGATION_FIELD_DESCRIPTIONS[\"total_steps\"],\n },\n \"next_step_required\": {\n \"type\": \"boolean\",\n \"description\": DEBUG_INVESTIGATION_FIELD_DESCRIPTIONS[\"next_step_required\"],\n },\n \"findings\": {\n \"type\": \"string\",\n \"description\": DEBUG_INVESTIGATION_FIELD_DESCRIPTIONS[\"findings\"],\n },\n \"files_checked\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": DEBUG_INVESTIGATION_FIELD_DESCRIPTIONS[\"files_checked\"],\n },\n \"relevant_files\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": DEBUG_INVESTIGATION_FIELD_DESCRIPTIONS[\"relevant_files\"],\n },\n \"confidence\": {\n \"type\": \"string\",\n \"enum\": [\"exploring\", \"low\", \"medium\", \"high\", \"very_high\", \"almost_certain\", \"certain\"],\n \"description\": DEBUG_INVESTIGATION_FIELD_DESCRIPTIONS[\"confidence\"],\n },\n \"hypothesis\": {\n \"type\": \"string\",\n \"description\": DEBUG_INVESTIGATION_FIELD_DESCRIPTIONS[\"hypothesis\"],\n },\n \"images\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": DEBUG_INVESTIGATION_FIELD_DESCRIPTIONS[\"images\"],\n },\n }\n\n # Use WorkflowSchemaBuilder with debug-specific tool fields\n return WorkflowSchemaBuilder.build_schema(\n tool_specific_fields=debug_field_overrides,\n model_field_schema=self.get_model_field_schema(),\n auto_mode=self.is_effective_auto_mode(),\n tool_name=self.get_name(),\n )\n\n def get_required_actions(\n self, step_number: int, confidence: str, findings: str, total_steps: int, request=None\n ) -> list[str]:\n \"\"\"Define required actions for each investigation phase.\"\"\"\n if step_number == 1:\n # Initial investigation tasks\n return [\n \"Search for code related to the reported issue or symptoms\",\n \"Examine relevant files and understand the current implementation\",\n \"Understand the project structure and locate relevant modules\",\n \"Identify how the affected functionality is supposed to work\",\n ]\n elif confidence in [\"exploring\", \"low\"]:\n # Need deeper investigation\n return [\n \"Examine the specific files you've identified as relevant\",\n \"Trace method calls and data flow through the system\",\n \"Check for edge cases, boundary conditions, and assumptions in the code\",\n \"Look for related configuration, dependencies, or external factors\",\n ]\n elif confidence in [\"medium\", \"high\", \"very_high\"]:\n # Close to root cause - need confirmation\n return [\n \"Examine the exact code sections where you believe the issue occurs\",\n \"Trace the execution path that leads to the failure\",\n \"Verify your hypothesis with concrete code evidence\",\n \"Check for any similar patterns elsewhere in the codebase\",\n ]\n elif confidence == \"almost_certain\":\n # Almost certain - final verification before conclusion\n return [\n \"Finalize your root cause analysis with specific evidence\",\n \"Document the complete chain of causation from symptom to root cause\",\n \"Verify the minimal fix approach is correct\",\n \"Consider if expert analysis would provide additional insights\",\n ]\n else:\n # General investigation needed\n return [\n \"Continue examining the code paths identified in your hypothesis\",\n \"Gather more evidence using appropriate investigation tools\",\n \"Test edge cases and boundary conditions\",\n \"Look for patterns that confirm or refute your theory\",\n ]\n\n def should_call_expert_analysis(self, consolidated_findings, request=None) -> bool:\n \"\"\"\n Decide when to call external model based on investigation completeness.\n\n Don't call expert analysis if the CLI agent has certain confidence - trust their judgment.\n \"\"\"\n # Check if user requested to skip assistant model\n if request and not self.get_request_use_assistant_model(request):\n return False\n\n # Check if we have meaningful investigation data\n return (\n len(consolidated_findings.relevant_files) > 0\n or len(consolidated_findings.findings) >= 2\n or len(consolidated_findings.issues_found) > 0\n )\n\n def prepare_expert_analysis_context(self, consolidated_findings) -> str:\n \"\"\"Prepare context for external model call matching original debug tool format.\"\"\"\n context_parts = [\n f\"=== ISSUE DESCRIPTION ===\\n{self.initial_issue or 'Investigation initiated'}\\n=== END DESCRIPTION ===\"\n ]\n\n # Add special note if confidence is almost_certain\n if consolidated_findings.confidence == \"almost_certain\":\n context_parts.append(\n \"\\n=== IMPORTANT: ALMOST CERTAIN CONFIDENCE ===\\n\"\n \"The agent has reached 'almost_certain' confidence but has NOT confirmed the bug with 100% certainty. \"\n \"Your role is to:\\n\"\n \"1. Validate the agent's hypothesis and investigation\\n\"\n \"2. Identify any missing evidence or overlooked aspects\\n\"\n \"3. Provide additional insights that could confirm or refute the hypothesis\\n\"\n \"4. Help finalize the root cause analysis with complete certainty\\n\"\n \"=== END IMPORTANT ===\"\n )\n\n # Add investigation summary\n investigation_summary = self._build_investigation_summary(consolidated_findings)\n context_parts.append(f\"\\n=== AGENT'S INVESTIGATION FINDINGS ===\\n{investigation_summary}\\n=== END FINDINGS ===\")\n\n # Add error context if available\n error_context = self._extract_error_context(consolidated_findings)\n if error_context:\n context_parts.append(f\"\\n=== ERROR CONTEXT/STACK TRACE ===\\n{error_context}\\n=== END CONTEXT ===\")\n\n # Add relevant methods/functions if available\n if consolidated_findings.relevant_context:\n methods_text = \"\\n\".join(f\"- {method}\" for method in consolidated_findings.relevant_context)\n context_parts.append(f\"\\n=== RELEVANT METHODS/FUNCTIONS ===\\n{methods_text}\\n=== END METHODS ===\")\n\n # Add hypothesis evolution if available\n if consolidated_findings.hypotheses:\n hypotheses_text = \"\\n\".join(\n f\"Step {h['step']} ({h['confidence']} confidence): {h['hypothesis']}\"\n for h in consolidated_findings.hypotheses\n )\n context_parts.append(f\"\\n=== HYPOTHESIS EVOLUTION ===\\n{hypotheses_text}\\n=== END HYPOTHESES ===\")\n\n # Add images if available\n if consolidated_findings.images:\n images_text = \"\\n\".join(f\"- {img}\" for img in consolidated_findings.images)\n context_parts.append(\n f\"\\n=== VISUAL DEBUGGING INFORMATION ===\\n{images_text}\\n=== END VISUAL INFORMATION ===\"\n )\n\n # Add file content if we have relevant files\n if consolidated_findings.relevant_files:\n file_content, _ = self._prepare_file_content_for_prompt(\n list(consolidated_findings.relevant_files), None, \"Essential debugging files\"\n )\n if file_content:\n context_parts.append(\n f\"\\n=== ESSENTIAL FILES FOR DEBUGGING ===\\n{file_content}\\n=== END ESSENTIAL FILES ===\"\n )\n\n return \"\\n\".join(context_parts)\n\n def _build_investigation_summary(self, consolidated_findings) -> str:\n \"\"\"Prepare a comprehensive summary of the investigation.\"\"\"\n summary_parts = [\n \"=== SYSTEMATIC INVESTIGATION SUMMARY ===\",\n f\"Total steps: {len(consolidated_findings.findings)}\",\n f\"Files examined: {len(consolidated_findings.files_checked)}\",\n f\"Relevant files identified: {len(consolidated_findings.relevant_files)}\",\n f\"Methods/functions involved: {len(consolidated_findings.relevant_context)}\",\n \"\",\n \"=== INVESTIGATION PROGRESSION ===\",\n ]\n\n for finding in consolidated_findings.findings:\n summary_parts.append(finding)\n\n return \"\\n\".join(summary_parts)\n\n def _extract_error_context(self, consolidated_findings) -> Optional[str]:\n \"\"\"Extract error context from investigation findings.\"\"\"\n error_patterns = [\"error\", \"exception\", \"stack trace\", \"traceback\", \"failure\"]\n error_context_parts = []\n\n for finding in consolidated_findings.findings:\n if any(pattern in finding.lower() for pattern in error_patterns):\n error_context_parts.append(finding)\n\n return \"\\n\".join(error_context_parts) if error_context_parts else None\n\n def get_step_guidance(self, step_number: int, confidence: str, request) -> dict[str, Any]:\n \"\"\"\n Provide step-specific guidance matching original debug tool behavior.\n\n This method generates debug-specific guidance that's used by get_step_guidance_message().\n \"\"\"\n # Generate the next steps instruction based on required actions\n required_actions = self.get_required_actions(step_number, confidence, request.findings, request.total_steps)\n\n if step_number == 1:\n next_steps = (\n f\"MANDATORY: DO NOT call the {self.get_name()} tool again immediately. You MUST first investigate \"\n f\"the codebase using appropriate tools. CRITICAL AWARENESS: The reported symptoms might be \"\n f\"caused by issues elsewhere in the code, not where symptoms appear. Also, after thorough \"\n f\"investigation, it's possible NO BUG EXISTS - the issue might be a misunderstanding or \"\n f\"user expectation mismatch. Search broadly, examine implementations, understand the logic flow. \"\n f\"Only call {self.get_name()} again AFTER gathering concrete evidence. When you call \"\n f\"{self.get_name()} next time, \"\n f\"use step_number: {step_number + 1} and report specific files examined and findings discovered.\"\n )\n elif confidence in [\"exploring\", \"low\"]:\n next_steps = (\n f\"STOP! Do NOT call {self.get_name()} again yet. Based on your findings, you've identified potential areas \"\n f\"but need concrete evidence. MANDATORY ACTIONS before calling {self.get_name()} step {step_number + 1}:\\n\"\n + \"\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\n\\nOnly call {self.get_name()} again with step_number: {step_number + 1} AFTER \"\n + \"completing these investigations.\"\n )\n elif confidence in [\"medium\", \"high\", \"very_high\"]:\n next_steps = (\n f\"WAIT! Your hypothesis needs verification. DO NOT call {self.get_name()} immediately. REQUIRED ACTIONS:\\n\"\n + \"\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\n\\nREMEMBER: If you cannot find concrete evidence of a bug causing the reported symptoms, \"\n f\"'no bug found' is a valid conclusion. Consider suggesting discussion with your thought partner \"\n f\"or engineering assistant for clarification. Document findings with specific file:line references, \"\n f\"then call {self.get_name()} with step_number: {step_number + 1}.\"\n )\n elif confidence == \"almost_certain\":\n next_steps = (\n \"ALMOST CERTAIN - Prepare for final analysis. REQUIRED ACTIONS:\\n\"\n + \"\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + \"\\n\\nIMPORTANT: You're almost certain about the root cause. If you have NOT found the bug with \"\n \"100% certainty, consider setting next_step_required=false to invoke expert analysis. The expert \"\n \"can validate your hypotheses and provide additional insights. If you ARE 100% certain and have \"\n \"identified the exact bug and fix, proceed to confidence='certain'. Otherwise, let expert analysis \"\n \"help finalize the investigation.\"\n )\n else:\n next_steps = (\n f\"PAUSE INVESTIGATION. Before calling {self.get_name()} step {step_number + 1}, you MUST examine code. \"\n + \"Required: \"\n + \", \".join(required_actions[:2])\n + \". \"\n + f\"Your next {self.get_name()} call (step_number: {step_number + 1}) must include \"\n f\"NEW evidence from actual code examination, not just theories. If no bug evidence \"\n f\"is found, suggesting \"\n f\"collaboration with thought partner is valuable. NO recursive {self.get_name()} calls \"\n f\"without investigation work!\"\n )\n\n return {\"next_steps\": next_steps}\n\n # Hook method overrides for debug-specific behavior\n\n def prepare_step_data(self, request) -> dict:\n \"\"\"\n Prepare debug-specific step data for processing.\n \"\"\"\n step_data = {\n \"step\": request.step,\n \"step_number\": request.step_number,\n \"findings\": request.findings,\n \"files_checked\": request.files_checked,\n \"relevant_files\": request.relevant_files,\n \"relevant_context\": request.relevant_context,\n \"issues_found\": [], # Debug tool doesn't use issues_found field\n \"confidence\": request.confidence,\n \"hypothesis\": request.hypothesis,\n \"images\": request.images or [],\n }\n return step_data\n\n def should_skip_expert_analysis(self, request, consolidated_findings) -> bool:\n \"\"\"\n Debug tool skips expert analysis when agent has \"certain\" confidence.\n \"\"\"\n return request.confidence == \"certain\" and not request.next_step_required\n\n # Override inheritance hooks for debug-specific behavior\n\n def get_completion_status(self) -> str:\n \"\"\"Debug tools use debug-specific status.\"\"\"\n return \"certain_confidence_proceed_with_fix\"\n\n def get_completion_data_key(self) -> str:\n \"\"\"Debug uses 'complete_investigation' key.\"\"\"\n return \"complete_investigation\"\n\n def get_final_analysis_from_request(self, request):\n \"\"\"Debug tools use 'hypothesis' field.\"\"\"\n return request.hypothesis\n\n def get_confidence_level(self, request) -> str:\n \"\"\"Debug tools use 'certain' for high confidence.\"\"\"\n return \"certain\"\n\n def get_completion_message(self) -> str:\n \"\"\"Debug-specific completion message.\"\"\"\n return (\n \"Investigation complete with CERTAIN confidence. You have identified the exact \"\n \"root cause and a minimal fix. MANDATORY: Present the user with the root cause analysis \"\n \"and IMMEDIATELY proceed with implementing the simple fix without requiring further \"\n \"consultation. Focus on the precise, minimal change needed.\"\n )\n\n def get_skip_reason(self) -> str:\n \"\"\"Debug-specific skip reason.\"\"\"\n return \"Identified exact root cause with minimal fix requirement locally\"\n\n def get_request_relevant_context(self, request) -> list:\n \"\"\"Get relevant_context for debug tool.\"\"\"\n try:\n return request.relevant_context or []\n except AttributeError:\n return []\n\n def get_skip_expert_analysis_status(self) -> str:\n \"\"\"Debug-specific expert analysis skip status.\"\"\"\n return \"skipped_due_to_certain_confidence\"\n\n def prepare_work_summary(self) -> str:\n \"\"\"Debug-specific work summary.\"\"\"\n return self._build_investigation_summary(self.consolidated_findings)\n\n def get_completion_next_steps_message(self, expert_analysis_used: bool = False) -> str:\n \"\"\"\n Debug-specific completion message.\n\n Args:\n expert_analysis_used: True if expert analysis was successfully executed\n \"\"\"\n base_message = (\n \"INVESTIGATION IS COMPLETE. YOU MUST now summarize and present ALL key findings, confirmed \"\n \"hypotheses, and exact recommended fixes. Clearly identify the most likely root cause and \"\n \"provide concrete, actionable implementation guidance. Highlight affected code paths and display \"\n \"reasoning that led to this conclusionβ€”make it easy for a developer to understand exactly where \"\n \"the problem lies. Where necessary, show cause-and-effect / bug-trace call graph.\"\n )\n\n # Add expert analysis guidance only when expert analysis was actually used\n if expert_analysis_used:\n expert_guidance = self.get_expert_analysis_guidance()\n if expert_guidance:\n return f\"{base_message}\\n\\n{expert_guidance}\"\n\n return base_message\n\n def get_expert_analysis_guidance(self) -> str:\n \"\"\"\n Get additional guidance for handling expert analysis results in debug context.\n\n Returns:\n Additional guidance text for validating and using expert analysis findings\n \"\"\"\n return (\n \"IMPORTANT: Expert debugging analysis has been provided above. You MUST validate \"\n \"the expert's root cause analysis and proposed fixes against your own investigation. \"\n \"Ensure the expert's findings align with the evidence you've gathered and that the \"\n \"recommended solutions address the actual problem, not just symptoms. If the expert \"\n \"suggests a different root cause than you identified, carefully consider both perspectives \"\n \"and present a balanced assessment to the user.\"\n )\n\n def get_step_guidance_message(self, request) -> str:\n \"\"\"\n Debug-specific step guidance with detailed investigation instructions.\n \"\"\"\n step_guidance = self.get_step_guidance(request.step_number, request.confidence, request)\n return step_guidance[\"next_steps\"]\n\n def customize_workflow_response(self, response_data: dict, request) -> dict:\n \"\"\"\n Customize response to match original debug tool format.\n \"\"\"\n # Store initial issue on first step\n if request.step_number == 1:\n self.initial_issue = request.step\n\n # Convert generic status names to debug-specific ones\n tool_name = self.get_name()\n status_mapping = {\n f\"{tool_name}_in_progress\": \"investigation_in_progress\",\n f\"pause_for_{tool_name}\": \"pause_for_investigation\",\n f\"{tool_name}_required\": \"investigation_required\",\n f\"{tool_name}_complete\": \"investigation_complete\",\n }\n\n if response_data[\"status\"] in status_mapping:\n response_data[\"status\"] = status_mapping[response_data[\"status\"]]\n\n # Rename status field to match debug tool\n if f\"{tool_name}_status\" in response_data:\n response_data[\"investigation_status\"] = response_data.pop(f\"{tool_name}_status\")\n # Add debug-specific status fields\n response_data[\"investigation_status\"][\"hypotheses_formed\"] = len(self.consolidated_findings.hypotheses)\n\n # Rename complete investigation data\n if f\"complete_{tool_name}\" in response_data:\n response_data[\"complete_investigation\"] = response_data.pop(f\"complete_{tool_name}\")\n\n # Map the completion flag to match original debug tool\n if f\"{tool_name}_complete\" in response_data:\n response_data[\"investigation_complete\"] = response_data.pop(f\"{tool_name}_complete\")\n\n # Map the required flag to match original debug tool\n if f\"{tool_name}_required\" in response_data:\n response_data[\"investigation_required\"] = response_data.pop(f\"{tool_name}_required\")\n\n return response_data\n\n # Required abstract methods from BaseTool\n def get_request_model(self):\n \"\"\"Return the debug-specific request model.\"\"\"\n return DebugInvestigationRequest\n\n async def prepare_prompt(self, request) -> str:\n \"\"\"Not used - workflow tools use execute_workflow().\"\"\"\n return \"\" # Workflow tools use execute_workflow() directly\n" }, { "path": "tools/docgen.py", "content": "\"\"\"\nDocumentation Generation tool - Automated code documentation with complexity analysis\n\nThis tool provides a structured workflow for adding comprehensive documentation to codebases.\nIt guides you through systematic code analysis to generate modern documentation with:\n- Function/method parameter documentation\n- Big O complexity analysis\n- Call flow and dependency documentation\n- Inline comments for complex logic\n- Smart updating of existing documentation\n\nKey features:\n- Step-by-step documentation workflow with progress tracking\n- Context-aware file embedding (references during analysis, full content for documentation)\n- Automatic conversation threading and history preservation\n- Expert analysis integration with external models\n- Support for multiple programming languages and documentation styles\n- Configurable documentation features via parameters\n\"\"\"\n\nimport logging\nfrom typing import TYPE_CHECKING, Any, Optional\n\nfrom pydantic import Field\n\nif TYPE_CHECKING:\n from tools.models import ToolModelCategory\n\nfrom config import TEMPERATURE_ANALYTICAL\nfrom systemprompts import DOCGEN_PROMPT\nfrom tools.shared.base_models import WorkflowRequest\n\nfrom .workflow.base import WorkflowTool\n\nlogger = logging.getLogger(__name__)\n\n# Tool-specific field descriptions for documentation generation\nDOCGEN_FIELD_DESCRIPTIONS = {\n \"step\": (\n \"Step 1 (Discovery): list every file that needs documentation and record the total. Do not write docs yet. \"\n \"Steps 2+: document exactly one file per step. Never change code logic; log bugs separately. Keep the counters accurate.\"\n ),\n \"step_number\": \"Current documentation step (starts at 1).\",\n \"total_steps\": \"1 discovery step + one step per file documented (tracks via `total_files_to_document`).\",\n \"next_step_required\": \"True while more files still need documentation; False once everything is complete.\",\n \"findings\": \"Summarize documentation gaps, complexity, call flows, and well-documented areas. Stop and report immediately if you uncover a bug.\",\n \"relevant_files\": \"Absolute paths for the file(s) you are documenting this stepβ€”stick to a single file per step.\",\n \"relevant_context\": \"Functions or methods needing documentation (e.g. 'Class.method', 'function_name'), especially complex or user-facing areas.\",\n \"num_files_documented\": \"Count of files finished so far. Increment only when a file is fully documented.\",\n \"total_files_to_document\": \"Total files identified in discovery; completion requires matching this count.\",\n \"document_complexity\": \"Include algorithmic complexity (Big O) analysis when True (default).\",\n \"document_flow\": \"Include call flow/dependency notes when True (default).\",\n \"update_existing\": \"True (default) to polish inaccurate or outdated docs instead of leaving them untouched.\",\n \"comments_on_complex_logic\": \"True (default) to add inline comments around non-obvious logic.\",\n}\n\n\nclass DocgenRequest(WorkflowRequest):\n \"\"\"Request model for documentation generation steps\"\"\"\n\n # Required workflow fields\n step: str = Field(..., description=DOCGEN_FIELD_DESCRIPTIONS[\"step\"])\n step_number: int = Field(..., description=DOCGEN_FIELD_DESCRIPTIONS[\"step_number\"])\n total_steps: int = Field(..., description=DOCGEN_FIELD_DESCRIPTIONS[\"total_steps\"])\n next_step_required: bool = Field(..., description=DOCGEN_FIELD_DESCRIPTIONS[\"next_step_required\"])\n\n # Documentation analysis tracking fields\n findings: str = Field(..., description=DOCGEN_FIELD_DESCRIPTIONS[\"findings\"])\n relevant_files: list[str] = Field(default_factory=list, description=DOCGEN_FIELD_DESCRIPTIONS[\"relevant_files\"])\n relevant_context: list[str] = Field(default_factory=list, description=DOCGEN_FIELD_DESCRIPTIONS[\"relevant_context\"])\n\n # Critical completion tracking counters\n num_files_documented: int = Field(0, description=DOCGEN_FIELD_DESCRIPTIONS[\"num_files_documented\"])\n total_files_to_document: int = Field(0, description=DOCGEN_FIELD_DESCRIPTIONS[\"total_files_to_document\"])\n\n # Documentation generation configuration parameters\n document_complexity: Optional[bool] = Field(True, description=DOCGEN_FIELD_DESCRIPTIONS[\"document_complexity\"])\n document_flow: Optional[bool] = Field(True, description=DOCGEN_FIELD_DESCRIPTIONS[\"document_flow\"])\n update_existing: Optional[bool] = Field(True, description=DOCGEN_FIELD_DESCRIPTIONS[\"update_existing\"])\n comments_on_complex_logic: Optional[bool] = Field(\n True, description=DOCGEN_FIELD_DESCRIPTIONS[\"comments_on_complex_logic\"]\n )\n\n\nclass DocgenTool(WorkflowTool):\n \"\"\"\n Documentation generation tool for automated code documentation with complexity analysis.\n\n This tool implements a structured documentation workflow that guides users through\n methodical code analysis to generate comprehensive documentation including:\n - Function/method signatures and parameter descriptions\n - Algorithmic complexity (Big O) analysis\n - Call flow and dependency documentation\n - Inline comments for complex logic\n - Modern documentation style appropriate for the language/platform\n \"\"\"\n\n def __init__(self):\n super().__init__()\n self.initial_request = None\n\n def get_name(self) -> str:\n return \"docgen\"\n\n def get_description(self) -> str:\n return (\n \"Generates comprehensive code documentation with systematic analysis of functions, classes, and complexity. \"\n \"Use for documentation generation, code analysis, complexity assessment, and API documentation. \"\n \"Analyzes code structure and patterns to create thorough documentation.\"\n )\n\n def get_system_prompt(self) -> str:\n return DOCGEN_PROMPT\n\n def get_default_temperature(self) -> float:\n return TEMPERATURE_ANALYTICAL\n\n def get_model_category(self) -> \"ToolModelCategory\":\n \"\"\"Docgen requires analytical and reasoning capabilities\"\"\"\n from tools.models import ToolModelCategory\n\n return ToolModelCategory.EXTENDED_REASONING\n\n def requires_model(self) -> bool:\n \"\"\"\n Docgen tool doesn't require model resolution at the MCP boundary.\n\n The docgen tool is a self-contained workflow tool that guides the CLI agent through\n systematic documentation generation without calling external AI models.\n\n Returns:\n bool: False - docgen doesn't need external AI model access\n \"\"\"\n return False\n\n def requires_expert_analysis(self) -> bool:\n \"\"\"Docgen is self-contained and doesn't need expert analysis.\"\"\"\n return False\n\n def get_workflow_request_model(self):\n \"\"\"Return the docgen-specific request model.\"\"\"\n return DocgenRequest\n\n def get_tool_fields(self) -> dict[str, dict[str, Any]]:\n \"\"\"Return the tool-specific fields for docgen.\"\"\"\n return {\n \"document_complexity\": {\n \"type\": \"boolean\",\n \"default\": True,\n \"description\": DOCGEN_FIELD_DESCRIPTIONS[\"document_complexity\"],\n },\n \"document_flow\": {\n \"type\": \"boolean\",\n \"default\": True,\n \"description\": DOCGEN_FIELD_DESCRIPTIONS[\"document_flow\"],\n },\n \"update_existing\": {\n \"type\": \"boolean\",\n \"default\": True,\n \"description\": DOCGEN_FIELD_DESCRIPTIONS[\"update_existing\"],\n },\n \"comments_on_complex_logic\": {\n \"type\": \"boolean\",\n \"default\": True,\n \"description\": DOCGEN_FIELD_DESCRIPTIONS[\"comments_on_complex_logic\"],\n },\n \"num_files_documented\": {\n \"type\": \"integer\",\n \"default\": 0,\n \"minimum\": 0,\n \"description\": DOCGEN_FIELD_DESCRIPTIONS[\"num_files_documented\"],\n },\n \"total_files_to_document\": {\n \"type\": \"integer\",\n \"default\": 0,\n \"minimum\": 0,\n \"description\": DOCGEN_FIELD_DESCRIPTIONS[\"total_files_to_document\"],\n },\n }\n\n def get_required_fields(self) -> list[str]:\n \"\"\"Return additional required fields beyond the standard workflow requirements.\"\"\"\n return [\n \"document_complexity\",\n \"document_flow\",\n \"update_existing\",\n \"comments_on_complex_logic\",\n \"num_files_documented\",\n \"total_files_to_document\",\n ]\n\n def get_input_schema(self) -> dict[str, Any]:\n \"\"\"Generate input schema using WorkflowSchemaBuilder with field exclusions.\"\"\"\n from .workflow.schema_builders import WorkflowSchemaBuilder\n\n # Exclude workflow fields that documentation generation doesn't need\n excluded_workflow_fields = [\n \"confidence\", # Documentation doesn't use confidence levels\n \"hypothesis\", # Documentation doesn't use hypothesis\n \"files_checked\", # Documentation uses doc_files and doc_methods instead for better tracking\n ]\n\n # Exclude common fields that documentation generation doesn't need\n excluded_common_fields = [\n \"model\", # Documentation doesn't need external model selection\n \"temperature\", # Documentation doesn't need temperature control\n \"thinking_mode\", # Documentation doesn't need thinking mode\n \"images\", # Documentation doesn't use images\n ]\n\n return WorkflowSchemaBuilder.build_schema(\n tool_specific_fields=self.get_tool_fields(),\n required_fields=self.get_required_fields(), # Include docgen-specific required fields\n model_field_schema=None, # Exclude model field - docgen doesn't need external model selection\n auto_mode=False, # Force non-auto mode to prevent model field addition\n tool_name=self.get_name(),\n excluded_workflow_fields=excluded_workflow_fields,\n excluded_common_fields=excluded_common_fields,\n )\n\n def get_required_actions(\n self, step_number: int, confidence: str, findings: str, total_steps: int, request=None\n ) -> list[str]:\n \"\"\"Define required actions for comprehensive documentation analysis with step-by-step file focus.\"\"\"\n if step_number == 1:\n # Initial discovery ONLY - no documentation yet\n return [\n \"CRITICAL: DO NOT ALTER ANY CODE LOGIC! Only add documentation (docstrings, comments)\",\n \"Discover ALL files in the current directory (not nested) that need documentation\",\n \"COUNT the exact number of files that need documentation\",\n \"LIST all the files you found that need documentation by name\",\n \"IDENTIFY the programming language(s) to use MODERN documentation style (/// for Objective-C, /** */ for Java/JavaScript, etc.)\",\n \"DO NOT start documenting any files yet - this is discovery phase only\",\n \"Report the total count and file list clearly to the user\",\n \"IMMEDIATELY call docgen step 2 after discovery to begin documentation phase\",\n \"WHEN CALLING DOCGEN step 2: Set total_files_to_document to the exact count you found\",\n \"WHEN CALLING DOCGEN step 2: Set num_files_documented to 0 (haven't started yet)\",\n ]\n elif step_number == 2:\n # Start documentation phase with first file\n return [\n \"CRITICAL: DO NOT ALTER ANY CODE LOGIC! Only add documentation (docstrings, comments)\",\n \"Choose the FIRST file from your discovered list to start documentation\",\n \"For the chosen file: identify ALL functions, classes, and methods within it\",\n 'USE MODERN documentation style for the programming language (/// for Objective-C, /** */ for Java/JavaScript, \"\"\" for Python, etc.)',\n \"Document ALL functions/methods in the chosen file - don't skip any - DOCUMENTATION ONLY\",\n \"When file is 100% documented, increment num_files_documented from 0 to 1\",\n \"Note any dependencies this file has (what it imports/calls) and what calls into it\",\n \"CRITICAL: If you find ANY bugs/logic errors, STOP documenting and report to user immediately\",\n \"Report which specific functions you documented in this step for accountability\",\n \"Report progress: num_files_documented (1) out of total_files_to_document\",\n ]\n elif step_number <= 4:\n # Continue with focused file-by-file approach\n return [\n \"CRITICAL: DO NOT ALTER ANY CODE LOGIC! Only add documentation (docstrings, comments)\",\n \"Choose the NEXT undocumented file from your discovered list\",\n \"For the chosen file: identify ALL functions, classes, and methods within it\",\n \"USE MODERN documentation style for the programming language (NEVER use legacy /* */ style for languages with modern alternatives)\",\n \"Document ALL functions/methods in the chosen file - don't skip any - DOCUMENTATION ONLY\",\n \"When file is 100% documented, increment num_files_documented by 1\",\n \"Verify that EVERY function in the current file has proper documentation (no skipping)\",\n \"CRITICAL: If you find ANY bugs/logic errors, STOP documenting and report to user immediately\",\n \"Report specific function names you documented for verification\",\n \"Report progress: current num_files_documented out of total_files_to_document\",\n ]\n else:\n # Continue systematic file-by-file coverage\n return [\n \"CRITICAL: DO NOT ALTER ANY CODE LOGIC! Only add documentation (docstrings, comments)\",\n \"Check counters: num_files_documented vs total_files_to_document\",\n \"If num_files_documented < total_files_to_document: choose NEXT undocumented file\",\n \"USE MODERN documentation style appropriate for each programming language (NEVER legacy styles)\",\n \"Document every function, method, and class in current file with no exceptions\",\n \"When file is 100% documented, increment num_files_documented by 1\",\n \"CRITICAL: If you find ANY bugs/logic errors, STOP documenting and report to user immediately\",\n \"Report progress: current num_files_documented out of total_files_to_document\",\n \"If num_files_documented < total_files_to_document: RESTART docgen with next step\",\n \"ONLY set next_step_required=false when num_files_documented equals total_files_to_document\",\n \"For nested dependencies: check if functions call into subdirectories and document those too\",\n \"CRITICAL: If ANY bugs/logic errors were found, STOP and ask user before proceeding\",\n ]\n\n def should_call_expert_analysis(self, consolidated_findings, request=None) -> bool:\n \"\"\"Docgen is self-contained and doesn't need expert analysis.\"\"\"\n return False\n\n def prepare_expert_analysis_context(self, consolidated_findings) -> str:\n \"\"\"Docgen doesn't use expert analysis.\"\"\"\n return \"\"\n\n def get_step_guidance(self, step_number: int, confidence: str, request) -> dict[str, Any]:\n \"\"\"\n Provide step-specific guidance for documentation generation workflow.\n\n This method generates docgen-specific guidance used by get_step_guidance_message().\n \"\"\"\n # Generate the next steps instruction based on required actions\n # Calculate dynamic total_steps based on files to document\n total_files_to_document = self.get_request_total_files_to_document(request)\n calculated_total_steps = 1 + total_files_to_document if total_files_to_document > 0 else request.total_steps\n\n required_actions = self.get_required_actions(step_number, confidence, request.findings, calculated_total_steps)\n\n if step_number == 1:\n next_steps = (\n f\"DISCOVERY PHASE ONLY - DO NOT START DOCUMENTING YET!\\n\"\n f\"MANDATORY: DO NOT call the {self.get_name()} tool again immediately. You MUST first perform \"\n f\"FILE DISCOVERY step by step. DO NOT DOCUMENT ANYTHING YET. \"\n f\"MANDATORY ACTIONS before calling {self.get_name()} step {step_number + 1}:\\n\"\n + \"\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\n\\nCRITICAL: When you call {self.get_name()} step 2, set total_files_to_document to the exact count \"\n f\"of files needing documentation and set num_files_documented to 0 (haven't started documenting yet). \"\n f\"Your total_steps will be automatically calculated as 1 (discovery) + number of files to document. \"\n f\"Step 2 will BEGIN the documentation phase. Report the count clearly and then IMMEDIATELY \"\n f\"proceed to call {self.get_name()} step 2 to start documenting the first file.\"\n )\n elif step_number == 2:\n next_steps = (\n f\"DOCUMENTATION PHASE BEGINS! ABSOLUTE RULE: DO NOT ALTER ANY CODE LOGIC! DOCUMENTATION ONLY!\\n\"\n f\"START FILE-BY-FILE APPROACH! Focus on ONE file until 100% complete. \"\n f\"MANDATORY ACTIONS before calling {self.get_name()} step {step_number + 1}:\\n\"\n + \"\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\n\\nREPORT your progress: which specific functions did you document? Update num_files_documented from 0 to 1 when first file complete. \"\n f\"REPORT counters: current num_files_documented out of total_files_to_document. \"\n f\"CRITICAL: If you found ANY bugs/logic errors, STOP documenting and ask user what to do before continuing. \"\n f\"Do NOT move to a new file until the current one is completely documented. \"\n f\"When ready for step {step_number + 1}, report completed work with updated counters.\"\n )\n elif step_number <= 4:\n next_steps = (\n f\"ABSOLUTE RULE: DO NOT ALTER ANY CODE LOGIC! DOCUMENTATION ONLY!\\n\"\n f\"CONTINUE FILE-BY-FILE APPROACH! Focus on ONE file until 100% complete. \"\n f\"MANDATORY ACTIONS before calling {self.get_name()} step {step_number + 1}:\\n\"\n + \"\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\n\\nREPORT your progress: which specific functions did you document? Update num_files_documented when file complete. \"\n f\"REPORT counters: current num_files_documented out of total_files_to_document. \"\n f\"CRITICAL: If you found ANY bugs/logic errors, STOP documenting and ask user what to do before continuing. \"\n f\"Do NOT move to a new file until the current one is completely documented. \"\n f\"When ready for step {step_number + 1}, report completed work with updated counters.\"\n )\n else:\n next_steps = (\n f\"ABSOLUTE RULE: DO NOT ALTER ANY CODE LOGIC! DOCUMENTATION ONLY!\\n\"\n f\"CRITICAL: Check if MORE FILES need documentation before finishing! \"\n f\"REQUIRED ACTIONS before calling {self.get_name()} step {step_number + 1}:\\n\"\n + \"\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\n\\nREPORT which functions you documented and update num_files_documented when file complete. \"\n f\"CHECK: If num_files_documented < total_files_to_document, RESTART {self.get_name()} with next step! \"\n f\"CRITICAL: Only set next_step_required=false when num_files_documented equals total_files_to_document! \"\n f\"REPORT counters: current num_files_documented out of total_files_to_document. \"\n f\"CRITICAL: If ANY bugs/logic errors were found during documentation, STOP and ask user before proceeding. \"\n f\"NO recursive {self.get_name()} calls without actual documentation work!\"\n )\n\n return {\"next_steps\": next_steps}\n\n # Hook method overrides for docgen-specific behavior\n\n async def handle_work_completion(self, response_data: dict, request, arguments: dict) -> dict:\n \"\"\"\n Override work completion to enforce counter validation.\n\n The docgen tool MUST complete ALL files before finishing. If counters don't match,\n force continuation regardless of next_step_required setting.\n \"\"\"\n # CRITICAL VALIDATION: Check if all files have been documented using proper inheritance hooks\n num_files_documented = self.get_request_num_files_documented(request)\n total_files_to_document = self.get_request_total_files_to_document(request)\n\n if num_files_documented < total_files_to_document:\n # Counters don't match - force continuation!\n logger.warning(\n f\"Docgen stopping early: {num_files_documented} < {total_files_to_document}. \"\n f\"Forcing continuation to document remaining files.\"\n )\n\n # Override to continuation mode\n response_data[\"status\"] = \"documentation_analysis_required\"\n response_data[f\"pause_for_{self.get_name()}\"] = True\n response_data[\"next_steps\"] = (\n f\"CRITICAL ERROR: You attempted to finish documentation with only {num_files_documented} \"\n f\"out of {total_files_to_document} files documented! You MUST continue documenting \"\n f\"the remaining {total_files_to_document - num_files_documented} files. \"\n f\"Call {self.get_name()} again with step {request.step_number + 1} and continue documentation \"\n f\"of the next undocumented file. DO NOT set next_step_required=false until ALL files are documented!\"\n )\n return response_data\n\n # If counters match, proceed with normal completion\n return await super().handle_work_completion(response_data, request, arguments)\n\n def prepare_step_data(self, request) -> dict:\n \"\"\"\n Prepare docgen-specific step data for processing.\n\n Calculates total_steps dynamically based on number of files to document:\n - Step 1: Discovery phase\n - Steps 2+: One step per file to document\n \"\"\"\n # Calculate dynamic total_steps based on files to document\n total_files_to_document = self.get_request_total_files_to_document(request)\n if total_files_to_document > 0:\n # Discovery step (1) + one step per file\n calculated_total_steps = 1 + total_files_to_document\n else:\n # Fallback to request total_steps if no file count available\n calculated_total_steps = request.total_steps\n\n step_data = {\n \"step\": request.step,\n \"step_number\": request.step_number,\n \"total_steps\": calculated_total_steps, # Use calculated value\n \"findings\": request.findings,\n \"relevant_files\": request.relevant_files,\n \"relevant_context\": request.relevant_context,\n \"num_files_documented\": request.num_files_documented,\n \"total_files_to_document\": request.total_files_to_document,\n \"issues_found\": [], # Docgen uses this for documentation gaps\n \"confidence\": \"medium\", # Default confidence for docgen\n \"hypothesis\": \"systematic_documentation_needed\", # Default hypothesis\n \"images\": [], # Docgen doesn't typically use images\n # CRITICAL: Include documentation configuration parameters so the model can see them\n \"document_complexity\": request.document_complexity,\n \"document_flow\": request.document_flow,\n \"update_existing\": request.update_existing,\n \"comments_on_complex_logic\": request.comments_on_complex_logic,\n }\n return step_data\n\n def should_skip_expert_analysis(self, request, consolidated_findings) -> bool:\n \"\"\"\n Docgen tool skips expert analysis when the CLI agent has \"certain\" confidence.\n \"\"\"\n return request.confidence == \"certain\" and not request.next_step_required\n\n # Override inheritance hooks for docgen-specific behavior\n\n def get_completion_status(self) -> str:\n \"\"\"Docgen tools use docgen-specific status.\"\"\"\n return \"documentation_analysis_complete\"\n\n def get_completion_data_key(self) -> str:\n \"\"\"Docgen uses 'complete_documentation_analysis' key.\"\"\"\n return \"complete_documentation_analysis\"\n\n def get_final_analysis_from_request(self, request):\n \"\"\"Docgen tools use 'hypothesis' field for documentation strategy.\"\"\"\n return request.hypothesis\n\n def get_confidence_level(self, request) -> str:\n \"\"\"Docgen tools use 'certain' for high confidence.\"\"\"\n return request.confidence or \"high\"\n\n def get_completion_message(self) -> str:\n \"\"\"Docgen-specific completion message.\"\"\"\n return (\n \"Documentation analysis complete with high confidence. You have identified the comprehensive \"\n \"documentation needs and strategy. MANDATORY: Present the user with the documentation plan \"\n \"and IMMEDIATELY proceed with implementing the documentation without requiring further \"\n \"consultation. Focus on the precise documentation improvements needed.\"\n )\n\n def get_skip_reason(self) -> str:\n \"\"\"Docgen-specific skip reason.\"\"\"\n return \"Completed comprehensive documentation analysis locally\"\n\n def get_request_relevant_context(self, request) -> list:\n \"\"\"Get relevant_context for docgen tool.\"\"\"\n try:\n return request.relevant_context or []\n except AttributeError:\n return []\n\n def get_request_num_files_documented(self, request) -> int:\n \"\"\"Get num_files_documented from request. Override for custom handling.\"\"\"\n try:\n return request.num_files_documented or 0\n except AttributeError:\n return 0\n\n def get_request_total_files_to_document(self, request) -> int:\n \"\"\"Get total_files_to_document from request. Override for custom handling.\"\"\"\n try:\n return request.total_files_to_document or 0\n except AttributeError:\n return 0\n\n def get_skip_expert_analysis_status(self) -> str:\n \"\"\"Docgen-specific expert analysis skip status.\"\"\"\n return \"skipped_due_to_complete_analysis\"\n\n def prepare_work_summary(self) -> str:\n \"\"\"Docgen-specific work summary.\"\"\"\n try:\n return f\"Completed {len(self.work_history)} documentation analysis steps\"\n except AttributeError:\n return \"Completed documentation analysis\"\n\n def get_completion_next_steps_message(self, expert_analysis_used: bool = False) -> str:\n \"\"\"\n Docgen-specific completion message.\n \"\"\"\n return (\n \"DOCUMENTATION ANALYSIS IS COMPLETE FOR ALL FILES (num_files_documented equals total_files_to_document). \"\n \"MANDATORY FINAL VERIFICATION: Before presenting your summary, you MUST perform a final verification scan. \"\n \"Read through EVERY file you documented and check EVERY function, method, class, and property to confirm \"\n \"it has proper documentation including complexity analysis and call flow information. If ANY items lack \"\n \"documentation, document them immediately before finishing. \"\n \"THEN present a clear summary showing: 1) Final counters: num_files_documented out of total_files_to_document, \"\n \"2) Complete accountability list of ALL files you documented with verification status, \"\n \"3) Detailed list of EVERY function/method you documented in each file (proving complete coverage), \"\n \"4) Any dependency relationships you discovered between files, 5) Recommended documentation improvements with concrete examples including \"\n \"complexity analysis and call flow information. 6) **CRITICAL**: List any bugs or logic issues you found \"\n \"during documentation but did NOT fix - present these to the user and ask what they'd like to do about them. \"\n \"Make it easy for a developer to see the complete documentation status across the entire codebase with full accountability.\"\n )\n\n def get_step_guidance_message(self, request) -> str:\n \"\"\"\n Docgen-specific step guidance with detailed analysis instructions.\n \"\"\"\n step_guidance = self.get_step_guidance(request.step_number, request.confidence, request)\n return step_guidance[\"next_steps\"]\n\n def customize_workflow_response(self, response_data: dict, request) -> dict:\n \"\"\"\n Customize response to match docgen tool format.\n \"\"\"\n # Store initial request on first step\n if request.step_number == 1:\n self.initial_request = request.step\n\n # Convert generic status names to docgen-specific ones\n tool_name = self.get_name()\n status_mapping = {\n f\"{tool_name}_in_progress\": \"documentation_analysis_in_progress\",\n f\"pause_for_{tool_name}\": \"pause_for_documentation_analysis\",\n f\"{tool_name}_required\": \"documentation_analysis_required\",\n f\"{tool_name}_complete\": \"documentation_analysis_complete\",\n }\n\n if response_data[\"status\"] in status_mapping:\n response_data[\"status\"] = status_mapping[response_data[\"status\"]]\n\n # Rename status field to match docgen tool\n if f\"{tool_name}_status\" in response_data:\n response_data[\"documentation_analysis_status\"] = response_data.pop(f\"{tool_name}_status\")\n # Add docgen-specific status fields\n response_data[\"documentation_analysis_status\"][\"documentation_strategies\"] = len(\n self.consolidated_findings.hypotheses\n )\n\n # Rename complete documentation analysis data\n if f\"complete_{tool_name}\" in response_data:\n response_data[\"complete_documentation_analysis\"] = response_data.pop(f\"complete_{tool_name}\")\n\n # Map the completion flag to match docgen tool\n if f\"{tool_name}_complete\" in response_data:\n response_data[\"documentation_analysis_complete\"] = response_data.pop(f\"{tool_name}_complete\")\n\n # Map the required flag to match docgen tool\n if f\"{tool_name}_required\" in response_data:\n response_data[\"documentation_analysis_required\"] = response_data.pop(f\"{tool_name}_required\")\n\n return response_data\n\n # Required abstract methods from BaseTool\n def get_request_model(self):\n \"\"\"Return the docgen-specific request model.\"\"\"\n return DocgenRequest\n\n async def prepare_prompt(self, request) -> str:\n \"\"\"Not used - workflow tools use execute_workflow().\"\"\"\n return \"\" # Workflow tools use execute_workflow() directly\n" }, { "path": "tools/listmodels.py", "content": "\"\"\"\nList Models Tool - Display all available models organized by provider\n\nThis tool provides a comprehensive view of all AI models available in the system,\norganized by their provider (Gemini, OpenAI, X.AI, OpenRouter, Custom).\nIt shows which providers are configured and what models can be used.\n\"\"\"\n\nimport logging\nfrom typing import Any, Optional\n\nfrom mcp.types import TextContent\n\nfrom providers.registries.custom import CustomEndpointModelRegistry\nfrom providers.registries.openrouter import OpenRouterModelRegistry\nfrom tools.models import ToolModelCategory, ToolOutput\nfrom tools.shared.base_models import ToolRequest\nfrom tools.shared.base_tool import BaseTool\nfrom utils.env import get_env\n\nlogger = logging.getLogger(__name__)\n\n\nclass ListModelsTool(BaseTool):\n \"\"\"\n Tool for listing all available AI models organized by provider.\n\n This tool helps users understand:\n - Which providers are configured (have API keys)\n - What models are available from each provider\n - Model aliases and their full names\n - Context window sizes and capabilities\n \"\"\"\n\n def get_name(self) -> str:\n return \"listmodels\"\n\n def get_description(self) -> str:\n return \"Shows which AI model providers are configured, available model names, their aliases and capabilities.\"\n\n def get_input_schema(self) -> dict[str, Any]:\n \"\"\"Return the JSON schema for the tool's input\"\"\"\n return {\n \"type\": \"object\",\n \"properties\": {},\n \"required\": [],\n \"additionalProperties\": False,\n }\n\n def get_annotations(self) -> Optional[dict[str, Any]]:\n \"\"\"Return tool annotations indicating this is a read-only tool\"\"\"\n return {\"readOnlyHint\": True}\n\n def get_system_prompt(self) -> str:\n \"\"\"No AI model needed for this tool\"\"\"\n return \"\"\n\n def get_request_model(self):\n \"\"\"Return the Pydantic model for request validation.\"\"\"\n return ToolRequest\n\n def requires_model(self) -> bool:\n return False\n\n async def prepare_prompt(self, request: ToolRequest) -> str:\n \"\"\"Not used for this utility tool\"\"\"\n return \"\"\n\n def format_response(self, response: str, request: ToolRequest, model_info: Optional[dict] = None) -> str:\n \"\"\"Not used for this utility tool\"\"\"\n return response\n\n async def execute(self, arguments: dict[str, Any]) -> list[TextContent]:\n \"\"\"\n List all available models organized by provider.\n\n This overrides the base class execute to provide direct output without AI model calls.\n\n Args:\n arguments: Standard tool arguments (none required)\n\n Returns:\n Formatted list of models by provider\n \"\"\"\n from providers.registry import ModelProviderRegistry\n from providers.shared import ProviderType\n from utils.model_restrictions import get_restriction_service\n\n output_lines = [\"# Available AI Models\\n\"]\n\n restriction_service = get_restriction_service()\n restricted_models_by_provider: dict[ProviderType, list[str]] = {}\n\n if restriction_service:\n restricted_map = ModelProviderRegistry.get_available_models(respect_restrictions=True)\n for model_name, provider_type in restricted_map.items():\n restricted_models_by_provider.setdefault(provider_type, []).append(model_name)\n\n # Map provider types to friendly names and their models\n provider_info = {\n ProviderType.GOOGLE: {\"name\": \"Google Gemini\", \"env_key\": \"GEMINI_API_KEY\"},\n ProviderType.OPENAI: {\"name\": \"OpenAI\", \"env_key\": \"OPENAI_API_KEY\"},\n ProviderType.AZURE: {\"name\": \"Azure OpenAI\", \"env_key\": \"AZURE_OPENAI_API_KEY\"},\n ProviderType.XAI: {\"name\": \"X.AI (Grok)\", \"env_key\": \"XAI_API_KEY\"},\n ProviderType.DIAL: {\"name\": \"AI DIAL\", \"env_key\": \"DIAL_API_KEY\"},\n }\n\n def format_model_entry(provider, display_name: str) -> list[str]:\n try:\n capabilities = provider.get_capabilities(display_name)\n except ValueError:\n return [f\"- `{display_name}` *(not recognized by provider)*\"]\n\n canonical = capabilities.model_name\n if canonical.lower() == display_name.lower():\n header = f\"- `{canonical}`\"\n else:\n header = f\"- `{display_name}` β†’ `{canonical}`\"\n\n try:\n context_value = capabilities.context_window or 0\n except AttributeError:\n context_value = 0\n try:\n context_value = int(context_value)\n except (TypeError, ValueError):\n context_value = 0\n\n if context_value >= 1_000_000:\n context_str = f\"{context_value // 1_000_000}M context\"\n elif context_value >= 1_000:\n context_str = f\"{context_value // 1_000}K context\"\n elif context_value > 0:\n context_str = f\"{context_value} context\"\n else:\n context_str = \"unknown context\"\n\n try:\n description = capabilities.description or \"No description available\"\n except AttributeError:\n description = \"No description available\"\n lines = [header, f\" - {context_str}\", f\" - {description}\"]\n if capabilities.allow_code_generation:\n lines.append(\" - Supports structured code generation\")\n return lines\n\n # Check each native provider type\n for provider_type, info in provider_info.items():\n # Check if provider is enabled\n provider = ModelProviderRegistry.get_provider(provider_type)\n is_configured = provider is not None\n\n output_lines.append(f\"## {info['name']} {'βœ…' if is_configured else '❌'}\")\n\n if is_configured:\n output_lines.append(\"**Status**: Configured and available\")\n has_restrictions = bool(restriction_service and restriction_service.has_restrictions(provider_type))\n\n if has_restrictions:\n restricted_names = sorted(set(restricted_models_by_provider.get(provider_type, [])))\n\n if restricted_names:\n output_lines.append(\"\\n**Models (policy restricted)**:\")\n for model_name in restricted_names:\n output_lines.extend(format_model_entry(provider, model_name))\n else:\n output_lines.append(\"\\n*No models are currently allowed by restriction policy.*\")\n else:\n output_lines.append(\"\\n**Models**:\")\n\n aliases = []\n for model_name, capabilities in provider.get_capabilities_by_rank():\n try:\n description = capabilities.description or \"No description available\"\n except AttributeError:\n description = \"No description available\"\n\n try:\n context_window = capabilities.context_window or 0\n except AttributeError:\n context_window = 0\n\n if context_window >= 1_000_000:\n context_str = f\"{context_window // 1_000_000}M context\"\n elif context_window >= 1_000:\n context_str = f\"{context_window // 1_000}K context\"\n else:\n context_str = f\"{context_window} context\" if context_window > 0 else \"unknown context\"\n\n output_lines.append(f\"- `{model_name}` - {context_str}\")\n output_lines.append(f\" - {description}\")\n if capabilities.allow_code_generation:\n output_lines.append(\" - Supports structured code generation\")\n\n for alias in capabilities.aliases or []:\n if alias != model_name:\n aliases.append(f\"- `{alias}` β†’ `{model_name}`\")\n\n if aliases:\n output_lines.append(\"\\n**Aliases**:\")\n output_lines.extend(sorted(aliases))\n else:\n output_lines.append(f\"**Status**: Not configured (set {info['env_key']})\")\n\n output_lines.append(\"\")\n\n # Check OpenRouter\n openrouter_key = get_env(\"OPENROUTER_API_KEY\")\n is_openrouter_configured = openrouter_key and openrouter_key != \"your_openrouter_api_key_here\"\n\n output_lines.append(f\"## OpenRouter {'βœ…' if is_openrouter_configured else '❌'}\")\n\n if is_openrouter_configured:\n output_lines.append(\"**Status**: Configured and available\")\n output_lines.append(\"**Description**: Access to multiple cloud AI providers via unified API\")\n\n try:\n provider = ModelProviderRegistry.get_provider(ProviderType.OPENROUTER)\n if provider:\n registry = OpenRouterModelRegistry()\n\n def _format_context(tokens: int) -> str:\n if not tokens:\n return \"?\"\n if tokens >= 1_000_000:\n return f\"{tokens // 1_000_000}M\"\n if tokens >= 1_000:\n return f\"{tokens // 1_000}K\"\n return str(tokens)\n\n has_restrictions = bool(\n restriction_service and restriction_service.has_restrictions(ProviderType.OPENROUTER)\n )\n\n if has_restrictions:\n restricted_names = sorted(set(restricted_models_by_provider.get(ProviderType.OPENROUTER, [])))\n\n output_lines.append(\"\\n**Models (policy restricted)**:\")\n if restricted_names:\n for model_name in restricted_names:\n try:\n caps = provider.get_capabilities(model_name)\n except ValueError:\n output_lines.append(f\"- `{model_name}` *(not recognized by provider)*\")\n continue\n\n context_value = int(caps.context_window or 0)\n context_str = _format_context(context_value)\n suffix_parts = [f\"{context_str} context\"]\n if caps.supports_extended_thinking:\n suffix_parts.append(\"thinking\")\n suffix = \", \".join(suffix_parts)\n\n arrow = \"\"\n if caps.model_name.lower() != model_name.lower():\n arrow = f\" β†’ `{caps.model_name}`\"\n\n score = caps.get_effective_capability_rank()\n output_lines.append(f\"- `{model_name}`{arrow} (score {score}, {suffix})\")\n\n allowed_set = restriction_service.get_allowed_models(ProviderType.OPENROUTER) or set()\n if allowed_set:\n output_lines.append(\n f\"\\n*OpenRouter models restricted by OPENROUTER_ALLOWED_MODELS: {', '.join(sorted(allowed_set))}*\"\n )\n else:\n output_lines.append(\"- *No models allowed by current restriction policy.*\")\n else:\n available_models = provider.list_models(respect_restrictions=True)\n providers_models: dict[str, list[tuple[int, str, Optional[Any]]]] = {}\n\n for model_name in available_models:\n config = registry.resolve(model_name)\n provider_name = \"other\"\n if config and \"/\" in config.model_name:\n provider_name = config.model_name.split(\"/\")[0]\n elif \"/\" in model_name:\n provider_name = model_name.split(\"/\")[0]\n\n providers_models.setdefault(provider_name, [])\n\n rank = config.get_effective_capability_rank() if config else 0\n providers_models[provider_name].append((rank, model_name, config))\n\n output_lines.append(\"\\n**Available Models**:\")\n for provider_name, models in sorted(providers_models.items()):\n output_lines.append(f\"\\n*{provider_name.title()}:*\")\n for rank, alias, config in sorted(models, key=lambda item: (-item[0], item[1])):\n if config:\n context_str = _format_context(getattr(config, \"context_window\", 0))\n suffix_parts = [f\"{context_str} context\"]\n if getattr(config, \"supports_extended_thinking\", False):\n suffix_parts.append(\"thinking\")\n suffix = \", \".join(suffix_parts)\n\n arrow = \"\"\n if config.model_name.lower() != alias.lower():\n arrow = f\" β†’ `{config.model_name}`\"\n\n output_lines.append(f\"- `{alias}`{arrow} (score {rank}, {suffix})\")\n else:\n output_lines.append(f\"- `{alias}` (score {rank})\")\n else:\n output_lines.append(\"**Error**: Could not load OpenRouter provider\")\n\n except Exception as e:\n logger.exception(\"Error listing OpenRouter models: %s\", e)\n output_lines.append(f\"**Error loading models**: {str(e)}\")\n else:\n output_lines.append(\"**Status**: Not configured (set OPENROUTER_API_KEY)\")\n output_lines.append(\"**Note**: Provides access to GPT-5, O3, Mistral, and many more\")\n\n output_lines.append(\"\")\n\n # Check Custom API\n custom_url = get_env(\"CUSTOM_API_URL\")\n\n output_lines.append(f\"## Custom/Local API {'βœ…' if custom_url else '❌'}\")\n\n if custom_url:\n output_lines.append(\"**Status**: Configured and available\")\n output_lines.append(f\"**Endpoint**: {custom_url}\")\n output_lines.append(\"**Description**: Local models via Ollama, vLLM, LM Studio, etc.\")\n\n try:\n registry = CustomEndpointModelRegistry()\n custom_models = []\n\n for alias in registry.list_aliases():\n config = registry.resolve(alias)\n if config:\n custom_models.append((alias, config))\n\n if custom_models:\n output_lines.append(\"\\n**Custom Models**:\")\n for alias, config in custom_models:\n context_str = f\"{config.context_window // 1000}K\" if config.context_window else \"?\"\n output_lines.append(f\"- `{alias}` β†’ `{config.model_name}` ({context_str} context)\")\n if config.description:\n output_lines.append(f\" - {config.description}\")\n\n except Exception as e:\n output_lines.append(f\"**Error loading custom models**: {str(e)}\")\n else:\n output_lines.append(\"**Status**: Not configured (set CUSTOM_API_URL)\")\n output_lines.append(\"**Example**: CUSTOM_API_URL=http://localhost:11434 (for Ollama)\")\n\n output_lines.append(\"\")\n\n # Add summary\n output_lines.append(\"## Summary\")\n\n # Count configured providers\n configured_count = sum(\n [\n 1\n for provider_type, info in provider_info.items()\n if ModelProviderRegistry.get_provider(provider_type) is not None\n ]\n )\n if is_openrouter_configured:\n configured_count += 1\n if custom_url:\n configured_count += 1\n\n output_lines.append(f\"**Configured Providers**: {configured_count}\")\n\n # Get total available models\n try:\n from providers.registry import ModelProviderRegistry\n\n # Get all available models respecting restrictions\n available_models = ModelProviderRegistry.get_available_models(respect_restrictions=True)\n total_models = len(available_models)\n output_lines.append(f\"**Total Available Models**: {total_models}\")\n except Exception as e:\n logger.warning(f\"Error getting total available models: {e}\")\n\n # Add usage tips\n output_lines.append(\"\\n**Usage Tips**:\")\n output_lines.append(\"- Use model aliases (e.g., 'flash', 'gpt5', 'opus') for convenience\")\n output_lines.append(\"- In auto mode, the CLI Agent will select the best model for each task\")\n output_lines.append(\"- Custom models are only available when CUSTOM_API_URL is set\")\n output_lines.append(\"- OpenRouter provides access to many cloud models with one API key\")\n\n # Format output\n content = \"\\n\".join(output_lines)\n\n tool_output = ToolOutput(\n status=\"success\",\n content=content,\n content_type=\"text\",\n metadata={\n \"tool_name\": self.name,\n \"configured_providers\": configured_count,\n },\n )\n\n return [TextContent(type=\"text\", text=tool_output.model_dump_json())]\n\n def get_model_category(self) -> ToolModelCategory:\n \"\"\"Return the model category for this tool.\"\"\"\n return ToolModelCategory.FAST_RESPONSE # Simple listing, no AI needed\n" }, { "path": "tools/models.py", "content": "\"\"\"\nData models for tool responses and interactions\n\"\"\"\n\nfrom enum import Enum\nfrom typing import Any, Literal, Optional\n\nfrom pydantic import BaseModel, Field\n\n\nclass ToolModelCategory(Enum):\n \"\"\"Categories for tool model selection based on requirements.\"\"\"\n\n EXTENDED_REASONING = \"extended_reasoning\" # Requires deep thinking capabilities\n FAST_RESPONSE = \"fast_response\" # Speed and cost efficiency preferred\n BALANCED = \"balanced\" # Balance of capability and performance\n\n\nclass ContinuationOffer(BaseModel):\n \"\"\"Offer for CLI agent to continue conversation when Gemini doesn't ask follow-up\"\"\"\n\n continuation_id: str = Field(\n ..., description=\"Thread continuation ID for multi-turn conversations across different tools\"\n )\n note: str = Field(..., description=\"Message explaining continuation opportunity to CLI agent\")\n remaining_turns: int = Field(..., description=\"Number of conversation turns remaining\")\n\n\nclass ToolOutput(BaseModel):\n \"\"\"Standardized output format for all tools\"\"\"\n\n status: Literal[\n \"success\",\n \"error\",\n \"files_required_to_continue\",\n \"full_codereview_required\",\n \"focused_review_required\",\n \"test_sample_needed\",\n \"more_tests_required\",\n \"refactor_analysis_complete\",\n \"trace_complete\",\n \"resend_prompt\",\n \"code_too_large\",\n \"continuation_available\",\n \"no_bug_found\",\n ] = \"success\"\n content: Optional[str] = Field(None, description=\"The main content/response from the tool\")\n content_type: Literal[\"text\", \"markdown\", \"json\"] = \"text\"\n metadata: Optional[dict[str, Any]] = Field(default_factory=dict)\n continuation_offer: Optional[ContinuationOffer] = Field(\n None, description=\"Optional offer for Agent to continue conversation\"\n )\n\n\nclass FilesNeededRequest(BaseModel):\n \"\"\"Request for missing files / code to continue\"\"\"\n\n status: Literal[\"files_required_to_continue\"] = \"files_required_to_continue\"\n mandatory_instructions: str = Field(..., description=\"Critical instructions for Agent regarding required context\")\n files_needed: Optional[list[str]] = Field(\n default_factory=list, description=\"Specific files that are needed for analysis\"\n )\n suggested_next_action: Optional[dict[str, Any]] = Field(\n None,\n description=\"Suggested tool call with parameters after getting clarification\",\n )\n\n\nclass FullCodereviewRequired(BaseModel):\n \"\"\"Request for full code review when scope is too large for quick review\"\"\"\n\n status: Literal[\"full_codereview_required\"] = \"full_codereview_required\"\n important: Optional[str] = Field(None, description=\"Important message about escalation\")\n reason: Optional[str] = Field(None, description=\"Reason why full review is needed\")\n\n\nclass FocusedReviewRequired(BaseModel):\n \"\"\"Request for Agent to provide smaller, focused subsets of code for review\"\"\"\n\n status: Literal[\"focused_review_required\"] = \"focused_review_required\"\n reason: str = Field(..., description=\"Why the current scope is too large for effective review\")\n suggestion: str = Field(\n ..., description=\"Suggested approach for breaking down the review into smaller, focused parts\"\n )\n\n\nclass TestSampleNeeded(BaseModel):\n \"\"\"Request for additional test samples to determine testing framework\"\"\"\n\n status: Literal[\"test_sample_needed\"] = \"test_sample_needed\"\n reason: str = Field(..., description=\"Reason why additional test samples are required\")\n\n\nclass MoreTestsRequired(BaseModel):\n \"\"\"Request for continuation to generate additional tests\"\"\"\n\n status: Literal[\"more_tests_required\"] = \"more_tests_required\"\n pending_tests: str = Field(..., description=\"List of pending tests to be generated\")\n\n\nclass RefactorOpportunity(BaseModel):\n \"\"\"A single refactoring opportunity with precise targeting information\"\"\"\n\n id: str = Field(..., description=\"Unique identifier for this refactoring opportunity\")\n type: Literal[\"decompose\", \"codesmells\", \"modernize\", \"organization\"] = Field(\n ..., description=\"Type of refactoring\"\n )\n severity: Literal[\"critical\", \"high\", \"medium\", \"low\"] = Field(..., description=\"Severity level\")\n file: str = Field(..., description=\"Absolute path to the file\")\n start_line: int = Field(..., description=\"Starting line number\")\n end_line: int = Field(..., description=\"Ending line number\")\n context_start_text: str = Field(..., description=\"Exact text from start line for verification\")\n context_end_text: str = Field(..., description=\"Exact text from end line for verification\")\n issue: str = Field(..., description=\"Clear description of what needs refactoring\")\n suggestion: str = Field(..., description=\"Specific refactoring action to take\")\n rationale: str = Field(..., description=\"Why this improves the code\")\n code_to_replace: str = Field(..., description=\"Original code that should be changed\")\n replacement_code_snippet: str = Field(..., description=\"Refactored version of the code\")\n new_code_snippets: Optional[list[dict]] = Field(\n default_factory=list, description=\"Additional code snippets to be added\"\n )\n\n\nclass RefactorAction(BaseModel):\n \"\"\"Next action for Agent to implement refactoring\"\"\"\n\n action_type: Literal[\"EXTRACT_METHOD\", \"SPLIT_CLASS\", \"MODERNIZE_SYNTAX\", \"REORGANIZE_CODE\", \"DECOMPOSE_FILE\"] = (\n Field(..., description=\"Type of action to perform\")\n )\n target_file: str = Field(..., description=\"Absolute path to target file\")\n source_lines: str = Field(..., description=\"Line range (e.g., '45-67')\")\n description: str = Field(..., description=\"Step-by-step action description for CLI Agent\")\n\n\nclass RefactorAnalysisComplete(BaseModel):\n \"\"\"Complete refactor analysis with prioritized opportunities\"\"\"\n\n status: Literal[\"refactor_analysis_complete\"] = \"refactor_analysis_complete\"\n refactor_opportunities: list[RefactorOpportunity] = Field(..., description=\"List of refactoring opportunities\")\n priority_sequence: list[str] = Field(..., description=\"Recommended order of refactoring IDs\")\n next_actions: list[RefactorAction] = Field(..., description=\"Specific actions for the agent to implement\")\n\n\nclass CodeTooLargeRequest(BaseModel):\n \"\"\"Request to reduce file selection due to size constraints\"\"\"\n\n status: Literal[\"code_too_large\"] = \"code_too_large\"\n content: str = Field(..., description=\"Message explaining the size constraint\")\n content_type: Literal[\"text\"] = \"text\"\n metadata: dict[str, Any] = Field(default_factory=dict)\n\n\nclass ResendPromptRequest(BaseModel):\n \"\"\"Request to resend prompt via file due to size limits\"\"\"\n\n status: Literal[\"resend_prompt\"] = \"resend_prompt\"\n content: str = Field(..., description=\"Instructions for handling large prompt\")\n content_type: Literal[\"text\"] = \"text\"\n metadata: dict[str, Any] = Field(default_factory=dict)\n\n\nclass TraceEntryPoint(BaseModel):\n \"\"\"Entry point information for trace analysis\"\"\"\n\n file: str = Field(..., description=\"Absolute path to the file\")\n class_or_struct: str = Field(..., description=\"Class or module name\")\n method: str = Field(..., description=\"Method or function name\")\n signature: str = Field(..., description=\"Full method signature\")\n parameters: Optional[dict[str, Any]] = Field(default_factory=dict, description=\"Parameter values used in analysis\")\n\n\nclass TraceTarget(BaseModel):\n \"\"\"Target information for dependency analysis\"\"\"\n\n file: str = Field(..., description=\"Absolute path to the file\")\n class_or_struct: str = Field(..., description=\"Class or module name\")\n method: str = Field(..., description=\"Method or function name\")\n signature: str = Field(..., description=\"Full method signature\")\n\n\nclass CallPathStep(BaseModel):\n \"\"\"A single step in the call path trace\"\"\"\n\n from_info: dict[str, Any] = Field(..., description=\"Source location information\", alias=\"from\")\n to: dict[str, Any] = Field(..., description=\"Target location information\")\n reason: str = Field(..., description=\"Reason for the call or dependency\")\n condition: Optional[str] = Field(None, description=\"Conditional logic if applicable\")\n ambiguous: bool = Field(False, description=\"Whether this call is ambiguous\")\n\n\nclass BranchingPoint(BaseModel):\n \"\"\"A branching point in the execution flow\"\"\"\n\n file: str = Field(..., description=\"File containing the branching point\")\n method: str = Field(..., description=\"Method containing the branching point\")\n line: int = Field(..., description=\"Line number of the branching point\")\n condition: str = Field(..., description=\"Branching condition\")\n branches: list[str] = Field(..., description=\"Possible execution branches\")\n ambiguous: bool = Field(False, description=\"Whether the branching is ambiguous\")\n\n\nclass SideEffect(BaseModel):\n \"\"\"A side effect detected in the trace\"\"\"\n\n type: str = Field(..., description=\"Type of side effect\")\n description: str = Field(..., description=\"Description of the side effect\")\n file: str = Field(..., description=\"File where the side effect occurs\")\n method: str = Field(..., description=\"Method where the side effect occurs\")\n line: int = Field(..., description=\"Line number of the side effect\")\n\n\nclass UnresolvedDependency(BaseModel):\n \"\"\"An unresolved dependency in the trace\"\"\"\n\n reason: str = Field(..., description=\"Reason why the dependency is unresolved\")\n affected_file: str = Field(..., description=\"File affected by the unresolved dependency\")\n line: int = Field(..., description=\"Line number of the unresolved dependency\")\n\n\nclass IncomingDependency(BaseModel):\n \"\"\"An incoming dependency (what calls this target)\"\"\"\n\n from_file: str = Field(..., description=\"Source file of the dependency\")\n from_class: str = Field(..., description=\"Source class of the dependency\")\n from_method: str = Field(..., description=\"Source method of the dependency\")\n line: int = Field(..., description=\"Line number of the dependency\")\n type: str = Field(..., description=\"Type of dependency\")\n\n\nclass OutgoingDependency(BaseModel):\n \"\"\"An outgoing dependency (what this target calls)\"\"\"\n\n to_file: str = Field(..., description=\"Target file of the dependency\")\n to_class: str = Field(..., description=\"Target class of the dependency\")\n to_method: str = Field(..., description=\"Target method of the dependency\")\n line: int = Field(..., description=\"Line number of the dependency\")\n type: str = Field(..., description=\"Type of dependency\")\n\n\nclass TypeDependency(BaseModel):\n \"\"\"A type-level dependency (inheritance, imports, etc.)\"\"\"\n\n dependency_type: str = Field(..., description=\"Type of dependency\")\n source_file: str = Field(..., description=\"Source file of the dependency\")\n source_entity: str = Field(..., description=\"Source entity (class, module)\")\n target: str = Field(..., description=\"Target entity\")\n\n\nclass StateAccess(BaseModel):\n \"\"\"State access information\"\"\"\n\n file: str = Field(..., description=\"File where state is accessed\")\n method: str = Field(..., description=\"Method accessing the state\")\n access_type: str = Field(..., description=\"Type of access (reads, writes, etc.)\")\n state_entity: str = Field(..., description=\"State entity being accessed\")\n\n\nclass TraceComplete(BaseModel):\n \"\"\"Complete trace analysis response\"\"\"\n\n status: Literal[\"trace_complete\"] = \"trace_complete\"\n trace_type: Literal[\"precision\", \"dependencies\"] = Field(..., description=\"Type of trace performed\")\n\n # Precision mode fields\n entry_point: Optional[TraceEntryPoint] = Field(None, description=\"Entry point for precision trace\")\n call_path: Optional[list[CallPathStep]] = Field(default_factory=list, description=\"Call path for precision trace\")\n branching_points: Optional[list[BranchingPoint]] = Field(default_factory=list, description=\"Branching points\")\n side_effects: Optional[list[SideEffect]] = Field(default_factory=list, description=\"Side effects detected\")\n unresolved: Optional[list[UnresolvedDependency]] = Field(\n default_factory=list, description=\"Unresolved dependencies\"\n )\n\n # Dependencies mode fields\n target: Optional[TraceTarget] = Field(None, description=\"Target for dependency analysis\")\n incoming_dependencies: Optional[list[IncomingDependency]] = Field(\n default_factory=list, description=\"Incoming dependencies\"\n )\n outgoing_dependencies: Optional[list[OutgoingDependency]] = Field(\n default_factory=list, description=\"Outgoing dependencies\"\n )\n type_dependencies: Optional[list[TypeDependency]] = Field(default_factory=list, description=\"Type dependencies\")\n state_access: Optional[list[StateAccess]] = Field(default_factory=list, description=\"State access information\")\n\n\nclass DiagnosticHypothesis(BaseModel):\n \"\"\"A debugging hypothesis with context and next steps\"\"\"\n\n rank: int = Field(..., description=\"Ranking of this hypothesis (1 = most likely)\")\n confidence: Literal[\"high\", \"medium\", \"low\"] = Field(..., description=\"Confidence level\")\n hypothesis: str = Field(..., description=\"Description of the potential root cause\")\n reasoning: str = Field(..., description=\"Why this hypothesis is plausible\")\n next_step: str = Field(..., description=\"Suggested action to test/validate this hypothesis\")\n\n\nclass StructuredDebugResponse(BaseModel):\n \"\"\"Enhanced debug response with multiple hypotheses\"\"\"\n\n summary: str = Field(..., description=\"Brief summary of the issue\")\n hypotheses: list[DiagnosticHypothesis] = Field(..., description=\"Ranked list of potential causes\")\n immediate_actions: list[str] = Field(\n default_factory=list,\n description=\"Immediate steps to take regardless of root cause\",\n )\n additional_context_needed: Optional[list[str]] = Field(\n default_factory=list,\n description=\"Additional files or information that would help with analysis\",\n )\n\n\nclass DebugHypothesis(BaseModel):\n \"\"\"A debugging hypothesis with detailed analysis\"\"\"\n\n name: str = Field(..., description=\"Name/title of the hypothesis\")\n confidence: Literal[\"High\", \"Medium\", \"Low\"] = Field(..., description=\"Confidence level\")\n root_cause: str = Field(..., description=\"Technical explanation of the root cause\")\n evidence: str = Field(..., description=\"Logs or code clues supporting this hypothesis\")\n correlation: str = Field(..., description=\"How symptoms map to the cause\")\n validation: str = Field(..., description=\"Quick test to confirm the hypothesis\")\n minimal_fix: str = Field(..., description=\"Smallest change to resolve the issue\")\n regression_check: str = Field(..., description=\"Why this fix is safe\")\n file_references: list[str] = Field(default_factory=list, description=\"File:line format for exact locations\")\n\n\nclass DebugAnalysisComplete(BaseModel):\n \"\"\"Complete debugging analysis with systematic investigation tracking\"\"\"\n\n status: Literal[\"analysis_complete\"] = \"analysis_complete\"\n investigation_id: str = Field(..., description=\"Auto-generated unique ID for this investigation\")\n summary: str = Field(..., description=\"Brief description of the problem and its impact\")\n investigation_steps: list[str] = Field(..., description=\"Steps taken during the investigation\")\n hypotheses: list[DebugHypothesis] = Field(..., description=\"Ranked hypotheses with detailed analysis\")\n key_findings: list[str] = Field(..., description=\"Important discoveries made during analysis\")\n immediate_actions: list[str] = Field(..., description=\"Steps to take regardless of which hypothesis is correct\")\n recommended_tools: list[str] = Field(default_factory=list, description=\"Additional tools recommended for analysis\")\n prevention_strategy: Optional[str] = Field(\n None, description=\"Targeted measures to prevent this exact issue from recurring\"\n )\n investigation_summary: str = Field(\n ..., description=\"Comprehensive summary of the complete investigation process and conclusions\"\n )\n\n\nclass NoBugFound(BaseModel):\n \"\"\"Response when thorough investigation finds no concrete evidence of a bug\"\"\"\n\n status: Literal[\"no_bug_found\"] = \"no_bug_found\"\n summary: str = Field(..., description=\"Summary of what was thoroughly investigated\")\n investigation_steps: list[str] = Field(..., description=\"Steps taken during the investigation\")\n areas_examined: list[str] = Field(..., description=\"Code areas and potential failure points examined\")\n confidence_level: Literal[\"High\", \"Medium\", \"Low\"] = Field(\n ..., description=\"Confidence level in the no-bug finding\"\n )\n alternative_explanations: list[str] = Field(\n ..., description=\"Possible alternative explanations for reported symptoms\"\n )\n recommended_questions: list[str] = Field(..., description=\"Questions to clarify the issue with the user\")\n next_steps: list[str] = Field(..., description=\"Suggested actions to better understand the reported issue\")\n\n\n# Registry mapping status strings to their corresponding Pydantic models\nSPECIAL_STATUS_MODELS = {\n \"files_required_to_continue\": FilesNeededRequest,\n \"full_codereview_required\": FullCodereviewRequired,\n \"focused_review_required\": FocusedReviewRequired,\n \"test_sample_needed\": TestSampleNeeded,\n \"more_tests_required\": MoreTestsRequired,\n \"refactor_analysis_complete\": RefactorAnalysisComplete,\n \"trace_complete\": TraceComplete,\n \"resend_prompt\": ResendPromptRequest,\n \"code_too_large\": CodeTooLargeRequest,\n \"analysis_complete\": DebugAnalysisComplete,\n \"no_bug_found\": NoBugFound,\n}\n" }, { "path": "tools/planner.py", "content": "\"\"\"\nInteractive Sequential Planner - Break down complex tasks through step-by-step planning\n\nThis tool enables structured planning through an interactive, step-by-step process that builds\nplans incrementally with the ability to revise, branch, and adapt as understanding deepens.\n\nThe planner guides users through sequential thinking with forced pauses between steps to ensure\nthorough consideration of alternatives, dependencies, and strategic decisions before moving to\ntactical implementation details.\n\nKey features:\n- Sequential planning with full context awareness\n- Forced deep reflection for complex plans (β‰₯5 steps) in early stages\n- Branching capabilities for exploring alternative approaches\n- Revision capabilities to update earlier decisions\n- Dynamic step count adjustment as plans evolve\n- Self-contained completion without external expert analysis\n\nPerfect for: complex project planning, system design with unknowns, migration strategies,\narchitectural decisions, and breaking down large problems into manageable steps.\n\"\"\"\n\nimport logging\nfrom typing import TYPE_CHECKING, Any\n\nfrom pydantic import Field, field_validator\n\nif TYPE_CHECKING:\n from tools.models import ToolModelCategory\n\nfrom config import TEMPERATURE_BALANCED\nfrom systemprompts import PLANNER_PROMPT\nfrom tools.shared.base_models import WorkflowRequest\n\nfrom .workflow.base import WorkflowTool\n\nlogger = logging.getLogger(__name__)\n\n# Tool-specific field descriptions matching original planner tool\nPLANNER_FIELD_DESCRIPTIONS = {\n \"step\": (\n \"Planning content for this step. Step 1: describe the task, problem and scope. Later steps: capture updates, \"\n \"revisions, branches, or open questions that shape the plan.\"\n ),\n \"step_number\": \"Current planning step number (starts at 1).\",\n \"total_steps\": \"Estimated number of planning steps; adjust as the plan evolves.\",\n \"next_step_required\": \"Set true when another planning step will follow after this one.\",\n \"is_step_revision\": \"Set true when you are replacing a previously recorded step.\",\n \"revises_step_number\": \"Step number being replaced when revising.\",\n \"is_branch_point\": \"True when this step creates a new branch to explore an alternative path.\",\n \"branch_from_step\": \"If branching, the step number that this branch starts from.\",\n \"branch_id\": \"Name for this branch (e.g. 'approach-A', 'migration-path').\",\n \"more_steps_needed\": \"True when you now expect to add additional steps beyond the prior estimate.\",\n}\n\n\nclass PlannerRequest(WorkflowRequest):\n \"\"\"Request model for planner workflow tool matching original planner exactly\"\"\"\n\n # Required fields for each planning step\n step: str = Field(..., description=PLANNER_FIELD_DESCRIPTIONS[\"step\"])\n step_number: int = Field(..., description=PLANNER_FIELD_DESCRIPTIONS[\"step_number\"])\n total_steps: int = Field(..., description=PLANNER_FIELD_DESCRIPTIONS[\"total_steps\"])\n next_step_required: bool = Field(..., description=PLANNER_FIELD_DESCRIPTIONS[\"next_step_required\"])\n\n # Optional revision/branching fields (planning-specific)\n is_step_revision: bool | None = Field(False, description=PLANNER_FIELD_DESCRIPTIONS[\"is_step_revision\"])\n revises_step_number: int | None = Field(None, description=PLANNER_FIELD_DESCRIPTIONS[\"revises_step_number\"])\n is_branch_point: bool | None = Field(False, description=PLANNER_FIELD_DESCRIPTIONS[\"is_branch_point\"])\n branch_from_step: int | None = Field(None, description=PLANNER_FIELD_DESCRIPTIONS[\"branch_from_step\"])\n branch_id: str | None = Field(None, description=PLANNER_FIELD_DESCRIPTIONS[\"branch_id\"])\n more_steps_needed: bool | None = Field(False, description=PLANNER_FIELD_DESCRIPTIONS[\"more_steps_needed\"])\n\n # Exclude all investigation/analysis fields that aren't relevant to planning\n findings: str = Field(\n default=\"\", exclude=True, description=\"Not used for planning - step content serves as findings\"\n )\n files_checked: list[str] = Field(default_factory=list, exclude=True, description=\"Planning doesn't examine files\")\n relevant_files: list[str] = Field(default_factory=list, exclude=True, description=\"Planning doesn't use files\")\n relevant_context: list[str] = Field(\n default_factory=list, exclude=True, description=\"Planning doesn't track code context\"\n )\n issues_found: list[dict] = Field(default_factory=list, exclude=True, description=\"Planning doesn't find issues\")\n confidence: str = Field(default=\"planning\", exclude=True, description=\"Planning uses different confidence model\")\n hypothesis: str | None = Field(default=None, exclude=True, description=\"Planning doesn't use hypothesis\")\n\n # Exclude other non-planning fields\n temperature: float | None = Field(default=None, exclude=True)\n thinking_mode: str | None = Field(default=None, exclude=True)\n use_assistant_model: bool | None = Field(default=False, exclude=True, description=\"Planning is self-contained\")\n images: list | None = Field(default=None, exclude=True, description=\"Planning doesn't use images\")\n\n @field_validator(\"step_number\")\n @classmethod\n def validate_step_number(cls, v):\n if v < 1:\n raise ValueError(\"step_number must be at least 1\")\n return v\n\n @field_validator(\"total_steps\")\n @classmethod\n def validate_total_steps(cls, v):\n if v < 1:\n raise ValueError(\"total_steps must be at least 1\")\n return v\n\n\nclass PlannerTool(WorkflowTool):\n \"\"\"\n Planner workflow tool for step-by-step planning using the workflow architecture.\n\n This tool provides the same planning capabilities as the original planner tool\n but uses the new workflow architecture for consistency with other workflow tools.\n It maintains all the original functionality including:\n - Sequential step-by-step planning\n - Branching and revision capabilities\n - Deep thinking pauses for complex plans\n - Conversation memory integration\n - Self-contained operation (no expert analysis)\n \"\"\"\n\n def __init__(self):\n super().__init__()\n self.branches = {}\n\n def get_name(self) -> str:\n return \"planner\"\n\n def get_description(self) -> str:\n return (\n \"Breaks down complex tasks through interactive, sequential planning with revision and branching capabilities. \"\n \"Use for complex project planning, system design, migration strategies, and architectural decisions. \"\n \"Builds plans incrementally with deep reflection for complex scenarios.\"\n )\n\n def get_system_prompt(self) -> str:\n return PLANNER_PROMPT\n\n def get_default_temperature(self) -> float:\n return TEMPERATURE_BALANCED\n\n def get_model_category(self) -> \"ToolModelCategory\":\n \"\"\"Planner requires deep analysis and reasoning\"\"\"\n from tools.models import ToolModelCategory\n\n return ToolModelCategory.EXTENDED_REASONING\n\n def requires_model(self) -> bool:\n \"\"\"\n Planner tool doesn't require model resolution at the MCP boundary.\n\n The planner is a pure data processing tool that organizes planning steps\n and provides structured guidance without calling external AI models.\n\n Returns:\n bool: False - planner doesn't need AI model access\n \"\"\"\n return False\n\n def get_workflow_request_model(self):\n \"\"\"Return the planner-specific request model.\"\"\"\n return PlannerRequest\n\n def get_input_schema(self) -> dict[str, Any]:\n \"\"\"Generate input schema for planner workflow using override pattern.\"\"\"\n from .workflow.schema_builders import WorkflowSchemaBuilder\n\n # Planner tool-specific field definitions\n planner_field_overrides = {\n # Override standard workflow fields that need planning-specific descriptions\n \"step\": {\n \"type\": \"string\",\n \"description\": PLANNER_FIELD_DESCRIPTIONS[\"step\"], # Very planning-specific instructions\n },\n # NEW planning-specific fields (not in base workflow)\n \"is_step_revision\": {\n \"type\": \"boolean\",\n \"description\": PLANNER_FIELD_DESCRIPTIONS[\"is_step_revision\"],\n },\n \"revises_step_number\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": PLANNER_FIELD_DESCRIPTIONS[\"revises_step_number\"],\n },\n \"is_branch_point\": {\n \"type\": \"boolean\",\n \"description\": PLANNER_FIELD_DESCRIPTIONS[\"is_branch_point\"],\n },\n \"branch_from_step\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": PLANNER_FIELD_DESCRIPTIONS[\"branch_from_step\"],\n },\n \"branch_id\": {\n \"type\": \"string\",\n \"description\": PLANNER_FIELD_DESCRIPTIONS[\"branch_id\"],\n },\n \"more_steps_needed\": {\n \"type\": \"boolean\",\n \"description\": PLANNER_FIELD_DESCRIPTIONS[\"more_steps_needed\"],\n },\n }\n\n # Define excluded fields for planner workflow\n excluded_workflow_fields = [\n \"findings\", # Planning uses step content instead\n \"files_checked\", # Planning doesn't examine files\n \"relevant_files\", # Planning doesn't use files\n \"relevant_context\", # Planning doesn't track code context\n \"issues_found\", # Planning doesn't find issues\n \"confidence\", # Planning uses different confidence model\n \"hypothesis\", # Planning doesn't use hypothesis\n ]\n\n excluded_common_fields = [\n \"temperature\", # Planning doesn't need temperature control\n \"thinking_mode\", # Planning doesn't need thinking mode\n \"images\", # Planning doesn't use images\n \"absolute_file_paths\", # Planning doesn't use file attachments\n ]\n\n # Build schema with proper field exclusion (following consensus pattern)\n return WorkflowSchemaBuilder.build_schema(\n tool_specific_fields=planner_field_overrides,\n required_fields=[], # No additional required fields beyond workflow defaults\n model_field_schema=self.get_model_field_schema(),\n auto_mode=self.is_effective_auto_mode(),\n tool_name=self.get_name(),\n excluded_workflow_fields=excluded_workflow_fields,\n excluded_common_fields=excluded_common_fields,\n )\n\n # ================================================================================\n # Abstract Methods - Required Implementation from BaseWorkflowMixin\n # ================================================================================\n\n def get_required_actions(\n self, step_number: int, confidence: str, findings: str, total_steps: int, request=None\n ) -> list[str]:\n \"\"\"Define required actions for each planning phase.\"\"\"\n if step_number == 1:\n # Initial planning tasks\n return [\n \"Think deeply about the complete scope and complexity of what needs to be planned\",\n \"Consider multiple approaches and their trade-offs\",\n \"Identify key constraints, dependencies, and potential challenges\",\n \"Think about stakeholders, success criteria, and critical requirements\",\n ]\n elif step_number <= 3 and total_steps >= 5:\n # Complex plan early stages - force deep thinking\n if step_number == 2:\n return [\n \"Evaluate the approach from step 1 - are there better alternatives?\",\n \"Break down the major phases and identify critical decision points\",\n \"Consider resource requirements and potential bottlenecks\",\n \"Think about how different parts interconnect and affect each other\",\n ]\n else: # step_number == 3\n return [\n \"Validate that the emerging plan addresses the original requirements\",\n \"Identify any gaps or assumptions that need clarification\",\n \"Consider how to validate progress and adjust course if needed\",\n \"Think about what the first concrete steps should be\",\n ]\n else:\n # Later steps or simple plans\n return [\n \"Continue developing the plan with concrete, actionable steps\",\n \"Consider implementation details and practical considerations\",\n \"Think about how to sequence and coordinate different activities\",\n \"Prepare for execution planning and resource allocation\",\n ]\n\n def should_call_expert_analysis(self, consolidated_findings, request=None) -> bool:\n \"\"\"Planner is self-contained and doesn't need expert analysis.\"\"\"\n return False\n\n def prepare_expert_analysis_context(self, consolidated_findings) -> str:\n \"\"\"Planner doesn't use expert analysis.\"\"\"\n return \"\"\n\n def requires_expert_analysis(self) -> bool:\n \"\"\"Planner is self-contained like the original planner tool.\"\"\"\n return False\n\n # ================================================================================\n # Workflow Customization - Match Original Planner Behavior\n # ================================================================================\n\n def prepare_step_data(self, request) -> dict:\n \"\"\"\n Prepare step data from request with planner-specific fields.\n \"\"\"\n step_data = {\n \"step\": request.step,\n \"step_number\": request.step_number,\n \"findings\": f\"Planning step {request.step_number}: {request.step}\", # Use step content as findings\n \"files_checked\": [], # Planner doesn't check files\n \"relevant_files\": [], # Planner doesn't use files\n \"relevant_context\": [], # Planner doesn't track context like debug\n \"issues_found\": [], # Planner doesn't track issues\n \"confidence\": \"planning\", # Planning confidence is different from investigation\n \"hypothesis\": None, # Planner doesn't use hypothesis\n \"images\": [], # Planner doesn't use images\n # Planner-specific fields\n \"is_step_revision\": request.is_step_revision or False,\n \"revises_step_number\": request.revises_step_number,\n \"is_branch_point\": request.is_branch_point or False,\n \"branch_from_step\": request.branch_from_step,\n \"branch_id\": request.branch_id,\n \"more_steps_needed\": request.more_steps_needed or False,\n }\n return step_data\n\n def build_base_response(self, request, continuation_id: str = None) -> dict:\n \"\"\"\n Build the base response structure with planner-specific fields.\n \"\"\"\n # Use work_history from workflow mixin for consistent step tracking\n # Add 1 to account for current step being processed\n current_step_count = len(self.work_history) + 1\n\n response_data = {\n \"status\": f\"{self.get_name()}_in_progress\",\n \"step_number\": request.step_number,\n \"total_steps\": request.total_steps,\n \"next_step_required\": request.next_step_required,\n \"step_content\": request.step,\n f\"{self.get_name()}_status\": {\n \"files_checked\": len(self.consolidated_findings.files_checked),\n \"relevant_files\": len(self.consolidated_findings.relevant_files),\n \"relevant_context\": len(self.consolidated_findings.relevant_context),\n \"issues_found\": len(self.consolidated_findings.issues_found),\n \"images_collected\": len(self.consolidated_findings.images),\n \"current_confidence\": self.get_request_confidence(request),\n \"step_history_length\": current_step_count, # Use work_history + current step\n },\n \"metadata\": {\n \"branches\": list(self.branches.keys()),\n \"step_history_length\": current_step_count, # Use work_history + current step\n \"is_step_revision\": request.is_step_revision or False,\n \"revises_step_number\": request.revises_step_number,\n \"is_branch_point\": request.is_branch_point or False,\n \"branch_from_step\": request.branch_from_step,\n \"branch_id\": request.branch_id,\n \"more_steps_needed\": request.more_steps_needed or False,\n },\n }\n\n if continuation_id:\n response_data[\"continuation_id\"] = continuation_id\n\n return response_data\n\n def handle_work_continuation(self, response_data: dict, request) -> dict:\n \"\"\"\n Handle work continuation with planner-specific deep thinking pauses.\n \"\"\"\n response_data[\"status\"] = f\"pause_for_{self.get_name()}\"\n response_data[f\"{self.get_name()}_required\"] = True\n\n # Get planner-specific required actions\n required_actions = self.get_required_actions(request.step_number, \"planning\", request.step, request.total_steps)\n response_data[\"required_actions\"] = required_actions\n\n # Enhanced deep thinking pauses for complex plans\n if request.total_steps >= 5 and request.step_number <= 3:\n response_data[\"status\"] = \"pause_for_deep_thinking\"\n response_data[\"thinking_required\"] = True\n response_data[\"required_thinking\"] = required_actions\n\n if request.step_number == 1:\n response_data[\"next_steps\"] = (\n f\"MANDATORY: DO NOT call the {self.get_name()} tool again immediately. This is a complex plan ({request.total_steps} steps) \"\n f\"that requires deep thinking. You MUST first spend time reflecting on the planning challenge:\\n\\n\"\n f\"REQUIRED DEEP THINKING before calling {self.get_name()} step {request.step_number + 1}:\\n\"\n f\"1. Analyze the FULL SCOPE: What exactly needs to be accomplished?\\n\"\n f\"2. Consider MULTIPLE APPROACHES: What are 2-3 different ways to tackle this?\\n\"\n f\"3. Identify CONSTRAINTS & DEPENDENCIES: What limits our options?\\n\"\n f\"4. Think about SUCCESS CRITERIA: How will we know we've succeeded?\\n\"\n f\"5. Consider RISKS & MITIGATION: What could go wrong early vs late?\\n\\n\"\n f\"Only call {self.get_name()} again with step_number: {request.step_number + 1} AFTER this deep analysis.\"\n )\n elif request.step_number == 2:\n response_data[\"next_steps\"] = (\n f\"STOP! Complex planning requires reflection between steps. DO NOT call {self.get_name()} immediately.\\n\\n\"\n f\"MANDATORY REFLECTION before {self.get_name()} step {request.step_number + 1}:\\n\"\n f\"1. EVALUATE YOUR APPROACH: Is the direction from step 1 still the best?\\n\"\n f\"2. IDENTIFY MAJOR PHASES: What are the 3-5 main chunks of work?\\n\"\n f\"3. SPOT DEPENDENCIES: What must happen before what?\\n\"\n f\"4. CONSIDER RESOURCES: What skills, tools, or access do we need?\\n\"\n f\"5. FIND CRITICAL PATHS: Where could delays hurt the most?\\n\\n\"\n f\"Think deeply about these aspects, then call {self.get_name()} with step_number: {request.step_number + 1}.\"\n )\n elif request.step_number == 3:\n response_data[\"next_steps\"] = (\n f\"PAUSE for final strategic reflection. DO NOT call {self.get_name()} yet.\\n\\n\"\n f\"FINAL DEEP THINKING before {self.get_name()} step {request.step_number + 1}:\\n\"\n f\"1. VALIDATE COMPLETENESS: Does this plan address all original requirements?\\n\"\n f\"2. CHECK FOR GAPS: What assumptions need validation? What's unclear?\\n\"\n f\"3. PLAN FOR ADAPTATION: How will we know if we need to change course?\\n\"\n f\"4. DEFINE FIRST STEPS: What are the first 2-3 concrete actions?\\n\"\n f\"5. TRANSITION MINDSET: Ready to shift from strategic to tactical planning?\\n\\n\"\n f\"After this reflection, call {self.get_name()} with step_number: {request.step_number + 1} to continue with tactical details.\"\n )\n else:\n # Normal flow for simple plans or later steps\n remaining_steps = request.total_steps - request.step_number\n response_data[\"next_steps\"] = (\n f\"Continue with step {request.step_number + 1}. Approximately {remaining_steps} steps remaining.\"\n )\n\n return response_data\n\n def customize_workflow_response(self, response_data: dict, request) -> dict:\n \"\"\"\n Customize response to match original planner tool format.\n \"\"\"\n # No need to append to step_history since workflow mixin already manages work_history\n # and we calculate step counts from work_history\n\n # Handle branching like original planner\n if request.is_branch_point and request.branch_from_step and request.branch_id:\n if request.branch_id not in self.branches:\n self.branches[request.branch_id] = []\n step_data = self.prepare_step_data(request)\n self.branches[request.branch_id].append(step_data)\n\n # Ensure metadata exists and preserve existing metadata from build_base_response\n if \"metadata\" not in response_data:\n response_data[\"metadata\"] = {}\n\n # Store planner-specific metadata that should persist through workflow metadata addition\n planner_metadata = {\n \"branches\": list(self.branches.keys()),\n \"is_step_revision\": request.is_step_revision or False,\n \"revises_step_number\": request.revises_step_number,\n \"is_branch_point\": request.is_branch_point or False,\n \"branch_from_step\": request.branch_from_step,\n \"branch_id\": request.branch_id,\n \"more_steps_needed\": request.more_steps_needed or False,\n }\n\n # Update metadata while preserving existing values\n response_data[\"metadata\"].update(planner_metadata)\n\n # Add planner-specific output instructions for final steps\n if not request.next_step_required:\n response_data[\"planning_complete\"] = True\n response_data[\"plan_summary\"] = (\n f\"COMPLETE PLAN: {request.step} (Total {request.total_steps} steps completed)\"\n )\n response_data[\"output\"] = {\n \"instructions\": \"This is a structured planning response. Present the step_content as the main planning analysis. If next_step_required is true, continue with the next step. If planning_complete is true, present the complete plan in a well-structured format with clear sections, headings, numbered steps, and visual elements like ASCII charts for phases/dependencies. Use bullet points, sub-steps, sequences, and visual organization to make complex plans easy to understand and follow. IMPORTANT: Do NOT use emojis - use clear text formatting and ASCII characters only. Do NOT mention time estimates or costs unless explicitly requested.\",\n \"format\": \"step_by_step_planning\",\n \"presentation_guidelines\": {\n \"completed_plans\": \"Use clear headings, numbered phases, ASCII diagrams for workflows/dependencies, bullet points for sub-tasks, and visual sequences where helpful. No emojis. No time/cost estimates unless requested.\",\n \"step_content\": \"Present as main analysis with clear structure and actionable insights. No emojis. No time/cost estimates unless requested.\",\n \"continuation\": \"Use continuation_id for related planning sessions or implementation planning\",\n },\n }\n response_data[\"next_steps\"] = (\n \"Planning complete. Present the complete plan to the user in a well-structured format with clear sections, \"\n \"numbered steps, visual elements (ASCII charts/diagrams where helpful), sub-step breakdowns, and implementation guidance. \"\n \"Use headings, bullet points, and visual organization to make the plan easy to follow. \"\n \"If there are phases, dependencies, or parallel tracks, show these relationships visually. \"\n \"IMPORTANT: Do NOT use emojis - use clear text formatting and ASCII characters only. \"\n \"Do NOT mention time estimates or costs unless explicitly requested. \"\n \"After presenting the plan, offer to either help implement specific parts or use the continuation_id to start related planning sessions.\"\n )\n\n # Convert generic status names to planner-specific ones\n tool_name = self.get_name()\n status_mapping = {\n f\"{tool_name}_in_progress\": \"planning_in_progress\",\n f\"pause_for_{tool_name}\": \"pause_for_planning\",\n f\"{tool_name}_required\": \"planning_required\",\n f\"{tool_name}_complete\": \"planning_complete\",\n }\n\n if response_data[\"status\"] in status_mapping:\n response_data[\"status\"] = status_mapping[response_data[\"status\"]]\n\n return response_data\n\n # ================================================================================\n # Hook Method Overrides for Planner-Specific Behavior\n # ================================================================================\n\n def get_completion_status(self) -> str:\n \"\"\"Planner uses planning-specific status.\"\"\"\n return \"planning_complete\"\n\n def get_completion_data_key(self) -> str:\n \"\"\"Planner uses 'complete_planning' key.\"\"\"\n return \"complete_planning\"\n\n def get_completion_message(self) -> str:\n \"\"\"Planner-specific completion message.\"\"\"\n return (\n \"Planning complete. Present the complete plan to the user in a well-structured format \"\n \"and offer to help implement specific parts or start related planning sessions.\"\n )\n\n def get_skip_reason(self) -> str:\n \"\"\"Planner-specific skip reason.\"\"\"\n return \"Planner is self-contained and completes planning without external analysis\"\n\n def get_skip_expert_analysis_status(self) -> str:\n \"\"\"Planner-specific expert analysis skip status.\"\"\"\n return \"skipped_by_tool_design\"\n\n def store_initial_issue(self, step_description: str):\n \"\"\"Store initial planning description.\"\"\"\n self.initial_planning_description = step_description\n\n def get_initial_request(self, fallback_step: str) -> str:\n \"\"\"Get initial planning description.\"\"\"\n try:\n return self.initial_planning_description\n except AttributeError:\n return fallback_step\n\n # Required abstract methods from BaseTool\n def get_request_model(self):\n \"\"\"Return the planner-specific request model.\"\"\"\n return PlannerRequest\n\n async def prepare_prompt(self, request) -> str:\n \"\"\"Not used - workflow tools use execute_workflow().\"\"\"\n return \"\" # Workflow tools use execute_workflow() directly\n" }, { "path": "tools/precommit.py", "content": "\"\"\"\nPrecommit Workflow tool - Step-by-step pre-commit validation with expert analysis\n\nThis tool provides a structured workflow for comprehensive pre-commit validation.\nIt guides the CLI agent through systematic investigation steps with forced pauses between each step\nto ensure thorough code examination, git change analysis, and issue detection before proceeding.\nThe tool supports finding updates and expert analysis integration.\n\nKey features:\n- Step-by-step pre-commit investigation workflow with progress tracking\n- Context-aware file embedding (references during investigation, full content for analysis)\n- Automatic git repository discovery and change analysis\n- Expert analysis integration with external models (default)\n- Support for multiple repositories and change types\n- Configurable validation type (external with expert model or internal only)\n\"\"\"\n\nimport logging\nfrom typing import TYPE_CHECKING, Any, Literal, Optional\n\nfrom pydantic import Field, model_validator\n\nif TYPE_CHECKING:\n from tools.models import ToolModelCategory\n\nfrom config import TEMPERATURE_ANALYTICAL\nfrom systemprompts import PRECOMMIT_PROMPT\nfrom tools.shared.base_models import WorkflowRequest\n\nfrom .workflow.base import WorkflowTool\n\nlogger = logging.getLogger(__name__)\n\n# Tool-specific field descriptions for precommit workflow\nPRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS = {\n \"step\": (\n \"Step 1: outline how you'll validate the git changes. Later steps: report findings. Review diffs and impacts, use `relevant_files`, and avoid pasting large snippets.\"\n ),\n \"step_number\": \"Current pre-commit step number (starts at 1).\",\n \"total_steps\": (\n \"Planned number of validation steps. External validation: use at most three (analysis β†’ follow-ups β†’ summary). Internal validation: a single step. Honour these limits when resuming via continuation_id.\"\n ),\n \"next_step_required\": (\n \"True to continue with another step, False when validation is complete. \"\n \"CRITICAL: If total_steps>=3 or when `precommit_type = external`, set to True until the final step. \"\n \"When continuation_id is provided: Follow the same validation rules based on precommit_type.\"\n ),\n \"findings\": \"Record git diff insights, risks, missing tests, security concerns, and positives; update previous notes as you go.\",\n \"files_checked\": \"Absolute paths for every file examined, including ruled-out candidates.\",\n \"relevant_files\": \"Absolute paths of files involved in the change or validation (code, configs, tests, docs). Must be absolute full non-abbreviated paths.\",\n \"relevant_context\": \"Key functions/methods touched by the change (e.g. 'Class.method', 'function_name').\",\n \"issues_found\": \"List issues with severity (critical/high/medium/low) plus descriptions (bugs, security, performance, coverage).\",\n \"precommit_type\": \"'external' (default, triggers expert model) or 'internal' (local-only validation).\",\n \"images\": \"Optional absolute paths to screenshots or diagrams that aid validation.\",\n \"path\": \"Absolute path to the repository root. Required in step 1.\",\n \"compare_to\": \"Optional git ref (branch/tag/commit) to diff against; falls back to staged/unstaged changes.\",\n \"include_staged\": \"Whether to inspect staged changes (ignored when `compare_to` is set).\",\n \"include_unstaged\": \"Whether to inspect unstaged changes (ignored when `compare_to` is set).\",\n \"focus_on\": \"Optional emphasis areas such as security, performance, or test coverage.\",\n \"severity_filter\": \"Lowest severity to include when reporting issues.\",\n}\n\n\nclass PrecommitRequest(WorkflowRequest):\n \"\"\"Request model for precommit workflow investigation steps\"\"\"\n\n # Required fields for each investigation step\n step: str = Field(..., description=PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"step\"])\n step_number: int = Field(..., description=PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"step_number\"])\n total_steps: int = Field(..., description=PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"total_steps\"])\n next_step_required: bool = Field(..., description=PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"next_step_required\"])\n\n # Investigation tracking fields\n findings: str = Field(..., description=PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"findings\"])\n files_checked: list[str] = Field(\n default_factory=list, description=PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"files_checked\"]\n )\n relevant_files: list[str] = Field(\n default_factory=list, description=PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_files\"]\n )\n relevant_context: list[str] = Field(\n default_factory=list, description=PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_context\"]\n )\n issues_found: list[dict] = Field(\n default_factory=list, description=PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"issues_found\"]\n )\n precommit_type: Optional[Literal[\"external\", \"internal\"]] = Field(\n \"external\", description=PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"precommit_type\"]\n )\n\n # Optional images for visual validation\n images: Optional[list[str]] = Field(default=None, description=PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"images\"])\n\n # Precommit-specific fields (only used in step 1 to initialize)\n # Required for step 1, validated in model_validator\n path: Optional[str] = Field(None, description=PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"path\"])\n compare_to: Optional[str] = Field(None, description=PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"compare_to\"])\n include_staged: Optional[bool] = Field(True, description=PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"include_staged\"])\n include_unstaged: Optional[bool] = Field(\n True, description=PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"include_unstaged\"]\n )\n focus_on: Optional[str] = Field(None, description=PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"focus_on\"])\n severity_filter: Optional[Literal[\"critical\", \"high\", \"medium\", \"low\", \"all\"]] = Field(\n \"all\", description=PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"severity_filter\"]\n )\n\n # Override inherited fields to exclude them from schema (except model which needs to be available)\n temperature: Optional[float] = Field(default=None, exclude=True)\n thinking_mode: Optional[str] = Field(default=None, exclude=True)\n\n @model_validator(mode=\"after\")\n def validate_step_one_requirements(self):\n \"\"\"Ensure step 1 has required path field.\"\"\"\n if self.step_number == 1 and not self.path:\n raise ValueError(\"Step 1 requires 'path' field to specify git repository location\")\n return self\n\n\nclass PrecommitTool(WorkflowTool):\n \"\"\"\n Precommit workflow tool for step-by-step pre-commit validation and expert analysis.\n\n This tool implements a structured pre-commit validation workflow that guides users through\n methodical investigation steps, ensuring thorough change examination, issue identification,\n and validation before reaching conclusions. It supports complex validation scenarios including\n multi-repository analysis, security review, performance validation, and integration testing.\n \"\"\"\n\n def __init__(self):\n super().__init__()\n self.initial_request = None\n self.git_config = {}\n\n def get_name(self) -> str:\n return \"precommit\"\n\n def get_description(self) -> str:\n return (\n \"Validates git changes and repository state before committing with systematic analysis. \"\n \"Use for multi-repository validation, security review, change impact assessment, and completeness verification. \"\n \"Guides through structured investigation with expert analysis.\"\n )\n\n def get_system_prompt(self) -> str:\n return PRECOMMIT_PROMPT\n\n def get_default_temperature(self) -> float:\n return TEMPERATURE_ANALYTICAL\n\n def get_model_category(self) -> \"ToolModelCategory\":\n \"\"\"Precommit requires thorough analysis and reasoning\"\"\"\n from tools.models import ToolModelCategory\n\n return ToolModelCategory.EXTENDED_REASONING\n\n def get_workflow_request_model(self):\n \"\"\"Return the precommit workflow-specific request model.\"\"\"\n return PrecommitRequest\n\n def get_input_schema(self) -> dict[str, Any]:\n \"\"\"Generate input schema using WorkflowSchemaBuilder with precommit-specific overrides.\"\"\"\n from .workflow.schema_builders import WorkflowSchemaBuilder\n\n # Precommit workflow-specific field overrides\n precommit_field_overrides = {\n \"step\": {\n \"type\": \"string\",\n \"description\": PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"step\"],\n },\n \"step_number\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"step_number\"],\n },\n \"total_steps\": {\n \"type\": \"integer\",\n \"minimum\": 3,\n \"description\": PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"total_steps\"],\n },\n \"next_step_required\": {\n \"type\": \"boolean\",\n \"description\": PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"next_step_required\"],\n },\n \"findings\": {\n \"type\": \"string\",\n \"description\": PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"findings\"],\n },\n \"files_checked\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"files_checked\"],\n },\n \"relevant_files\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_files\"],\n },\n \"precommit_type\": {\n \"type\": \"string\",\n \"enum\": [\"external\", \"internal\"],\n \"default\": \"external\",\n \"description\": PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"precommit_type\"],\n },\n \"issues_found\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"object\"},\n \"description\": PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"issues_found\"],\n },\n \"images\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"images\"],\n },\n # Precommit-specific fields (for step 1)\n \"path\": {\n \"type\": \"string\",\n \"description\": PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"path\"],\n },\n \"compare_to\": {\n \"type\": \"string\",\n \"description\": PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"compare_to\"],\n },\n \"include_staged\": {\n \"type\": \"boolean\",\n \"default\": True,\n \"description\": PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"include_staged\"],\n },\n \"include_unstaged\": {\n \"type\": \"boolean\",\n \"default\": True,\n \"description\": PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"include_unstaged\"],\n },\n \"focus_on\": {\n \"type\": \"string\",\n \"description\": PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"focus_on\"],\n },\n \"severity_filter\": {\n \"type\": \"string\",\n \"enum\": [\"critical\", \"high\", \"medium\", \"low\", \"all\"],\n \"default\": \"all\",\n \"description\": PRECOMMIT_WORKFLOW_FIELD_DESCRIPTIONS[\"severity_filter\"],\n },\n }\n\n # Use WorkflowSchemaBuilder with precommit-specific tool fields\n return WorkflowSchemaBuilder.build_schema(\n tool_specific_fields=precommit_field_overrides,\n model_field_schema=self.get_model_field_schema(),\n auto_mode=self.is_effective_auto_mode(),\n tool_name=self.get_name(),\n )\n\n def get_required_actions(\n self, step_number: int, confidence: str, findings: str, total_steps: int, request=None\n ) -> list[str]:\n \"\"\"Define required actions for each investigation phase.\n\n Now includes request parameter for continuation-aware decisions.\n \"\"\"\n # Check for continuation - fast track mode\n if request:\n continuation_id = self.get_request_continuation_id(request)\n precommit_type = self.get_precommit_type(request)\n if continuation_id and precommit_type == \"external\":\n if step_number == 1:\n return [\n \"Execute git status to see all changes\",\n \"Execute git diff --cached for staged changes (exclude binary files)\",\n \"Execute git diff for unstaged changes (exclude binary files)\",\n \"List any relevant untracked files as well.\",\n ]\n else:\n return [\"Complete validation and proceed to expert analysis with changeset file\"]\n\n # Extract counts for normal flow\n findings_count = len(findings.split(\"\\n\")) if findings else 0\n issues_count = self.get_consolidated_issues_count()\n\n if step_number == 1:\n # Initial pre-commit investigation tasks\n return [\n \"Search for all git repositories in the specified path using appropriate tools\",\n \"Check git status to identify staged, unstaged, and untracked changes as required\",\n \"Execute git status to see all changes\",\n \"Execute git diff --cached for staged changes (exclude binary files)\",\n \"Execute git diff for unstaged changes (exclude binary files)\",\n \"List any relevant untracked files as well.\",\n \"Understand what functionality was added, modified, or removed\",\n \"Identify the scope and intent of the changes being committed\",\n \"CRITICAL: You are on step 1 - you MUST set next_step_required=True and continue to at least step 3 minimum\",\n ]\n elif step_number == 2:\n # Need deeper investigation\n actions = [\n \"Examine the specific files you've identified as changed or relevant\",\n \"Analyze the logic and implementation details of modifications\",\n \"Check for potential issues: bugs, security risks, performance problems\",\n \"Verify that changes align with good coding practices and patterns\",\n \"Look for missing tests, documentation, or configuration updates\",\n ]\n\n # Add step validation reminder\n if request and request.total_steps >= 3:\n actions.append(\n f\"CRITICAL: You are on step 2 of {request.total_steps} minimum steps - you MUST set next_step_required=True unless this is the final step\"\n )\n\n return actions\n elif step_number >= 2 and (findings_count > 2 or issues_count > 0):\n # Close to completion - need final verification\n actions = [\n \"Verify all identified issues have been properly documented\",\n \"Check for any missed dependencies or related files that need review\",\n \"Confirm the completeness and correctness of your assessment\",\n \"Ensure all security, performance, and quality concerns are captured\",\n \"Validate that your findings are comprehensive and actionable\",\n ]\n\n # Add step validation reminder\n if request and request.total_steps >= 3 and step_number < request.total_steps:\n actions.append(\n f\"CRITICAL: You are on step {step_number} of {request.total_steps} minimum steps - set next_step_required=True to continue\"\n )\n elif request and request.total_steps >= 3 and step_number >= request.total_steps:\n actions.append(\n f\"You are on final step {step_number} - you may now set next_step_required=False to complete\"\n )\n\n return actions\n else:\n # General investigation needed\n actions = [\n \"Continue examining the changes and their potential impact\",\n \"Gather more evidence using appropriate investigation tools\",\n \"Test your assumptions about the changes and their effects\",\n \"Look for patterns that confirm or refute your current assessment\",\n ]\n\n # Add step validation reminder for all other cases\n if request and request.total_steps >= 3:\n if step_number < request.total_steps:\n actions.append(\n f\"CRITICAL: You are on step {step_number} of {request.total_steps} minimum steps - set next_step_required=True to continue\"\n )\n else:\n actions.append(\n f\"You are on final step {step_number} - you may now set next_step_required=False to complete\"\n )\n\n return actions\n\n def should_call_expert_analysis(self, consolidated_findings, request=None) -> bool:\n \"\"\"\n Decide when to call external model based on investigation completeness.\n\n For continuations with external type, always proceed with expert analysis.\n \"\"\"\n # Check if user requested to skip assistant model\n if request and not self.get_request_use_assistant_model(request):\n return False\n\n # For continuations with external type, always proceed with expert analysis\n continuation_id = self.get_request_continuation_id(request)\n if continuation_id and request.precommit_type == \"external\":\n return True # Always perform expert analysis for external continuations\n\n # Check if we have meaningful investigation data\n return (\n len(consolidated_findings.relevant_files) > 0\n or len(consolidated_findings.findings) >= 2\n or len(consolidated_findings.issues_found) > 0\n )\n\n def prepare_expert_analysis_context(self, consolidated_findings) -> str:\n \"\"\"Prepare context for external model call for final pre-commit validation.\"\"\"\n context_parts = [\n f\"=== PRE-COMMIT ANALYSIS REQUEST ===\\\\n{self.initial_request or 'Pre-commit validation initiated'}\\\\n=== END REQUEST ===\"\n ]\n\n # Add investigation summary\n investigation_summary = self._build_precommit_summary(consolidated_findings)\n context_parts.append(\n f\"\\\\n=== AGENT'S PRE-COMMIT INVESTIGATION ===\\\\n{investigation_summary}\\\\n=== END INVESTIGATION ===\"\n )\n\n # Add git configuration context if available\n if self.git_config:\n config_text = \"\\\\n\".join(f\"- {key}: {value}\" for key, value in self.git_config.items())\n context_parts.append(f\"\\\\n=== GIT CONFIGURATION ===\\\\n{config_text}\\\\n=== END CONFIGURATION ===\")\n\n # Add relevant methods/functions if available\n if consolidated_findings.relevant_context:\n methods_text = \"\\\\n\".join(f\"- {method}\" for method in consolidated_findings.relevant_context)\n context_parts.append(f\"\\\\n=== RELEVANT CODE ELEMENTS ===\\\\n{methods_text}\\\\n=== END CODE ELEMENTS ===\")\n\n # Add issues found evolution if available\n if consolidated_findings.issues_found:\n issues_text = \"\\\\n\".join(\n f\"[{issue.get('severity', 'unknown').upper()}] {issue.get('description', 'No description')}\"\n for issue in consolidated_findings.issues_found\n )\n context_parts.append(f\"\\\\n=== ISSUES IDENTIFIED ===\\\\n{issues_text}\\\\n=== END ISSUES ===\")\n\n # Add assessment evolution if available\n if consolidated_findings.hypotheses:\n assessments_text = \"\\\\n\".join(\n f\"Step {h['step']}: {h['hypothesis']}\" for h in consolidated_findings.hypotheses\n )\n context_parts.append(f\"\\\\n=== ASSESSMENT EVOLUTION ===\\\\n{assessments_text}\\\\n=== END ASSESSMENTS ===\")\n\n # Add images if available\n if consolidated_findings.images:\n images_text = \"\\\\n\".join(f\"- {img}\" for img in consolidated_findings.images)\n context_parts.append(\n f\"\\\\n=== VISUAL VALIDATION INFORMATION ===\\\\n{images_text}\\\\n=== END VISUAL INFORMATION ===\"\n )\n\n return \"\\\\n\".join(context_parts)\n\n def _build_precommit_summary(self, consolidated_findings) -> str:\n \"\"\"Prepare a comprehensive summary of the pre-commit investigation.\"\"\"\n summary_parts = [\n \"=== SYSTEMATIC PRE-COMMIT INVESTIGATION SUMMARY ===\",\n f\"Total steps: {len(consolidated_findings.findings)}\",\n f\"Files examined: {len(consolidated_findings.files_checked)}\",\n f\"Relevant files identified: {len(consolidated_findings.relevant_files)}\",\n f\"Code elements analyzed: {len(consolidated_findings.relevant_context)}\",\n f\"Issues identified: {len(consolidated_findings.issues_found)}\",\n \"\",\n \"=== INVESTIGATION PROGRESSION ===\",\n ]\n\n for finding in consolidated_findings.findings:\n summary_parts.append(finding)\n\n return \"\\\\n\".join(summary_parts)\n\n def should_include_files_in_expert_prompt(self) -> bool:\n \"\"\"Include files in expert analysis for comprehensive validation.\"\"\"\n return True\n\n def should_embed_system_prompt(self) -> bool:\n \"\"\"Embed system prompt in expert analysis for proper context.\"\"\"\n return True\n\n def get_expert_thinking_mode(self) -> str:\n \"\"\"Use high thinking mode for thorough pre-commit analysis.\"\"\"\n return \"high\"\n\n def get_expert_analysis_instruction(self) -> str:\n \"\"\"Get specific instruction for pre-commit expert analysis.\"\"\"\n return (\n \"Please provide comprehensive pre-commit validation based on the investigation findings. \"\n \"Focus on identifying any remaining issues, validating the completeness of the analysis, \"\n \"and providing final recommendations for commit readiness.\"\n )\n\n # Hook method overrides for precommit-specific behavior\n\n def prepare_step_data(self, request) -> dict:\n \"\"\"\n Map precommit-specific fields for internal processing.\n \"\"\"\n step_data = {\n \"step\": request.step,\n \"step_number\": request.step_number,\n \"findings\": request.findings,\n \"files_checked\": request.files_checked,\n \"relevant_files\": request.relevant_files,\n \"relevant_context\": request.relevant_context,\n \"issues_found\": request.issues_found,\n \"precommit_type\": request.precommit_type,\n \"hypothesis\": request.findings, # Map findings to hypothesis for compatibility\n \"images\": request.images or [],\n \"confidence\": \"high\", # Dummy value for workflow_mixin compatibility\n }\n return step_data\n\n def should_skip_expert_analysis(self, request, consolidated_findings) -> bool:\n \"\"\"\n Precommit workflow skips expert analysis only when precommit_type is \"internal\".\n Default is always to use expert analysis (external).\n For continuations with external type, always perform expert analysis immediately.\n \"\"\"\n # If it's a continuation and precommit_type is external, don't skip\n continuation_id = self.get_request_continuation_id(request)\n if continuation_id and request.precommit_type != \"internal\":\n return False # Always do expert analysis for external continuations\n\n return request.precommit_type == \"internal\" and not request.next_step_required\n\n def store_initial_issue(self, step_description: str):\n \"\"\"Store initial request for expert analysis.\"\"\"\n self.initial_request = step_description\n\n # Override inheritance hooks for precommit-specific behavior\n\n def get_completion_status(self) -> str:\n \"\"\"Precommit tools use precommit-specific status.\"\"\"\n return \"validation_complete_ready_for_commit\"\n\n def get_completion_data_key(self) -> str:\n \"\"\"Precommit uses 'complete_validation' key.\"\"\"\n return \"complete_validation\"\n\n def get_final_analysis_from_request(self, request):\n \"\"\"Precommit tools use 'findings' field.\"\"\"\n return request.findings\n\n def get_precommit_type(self, request) -> str:\n \"\"\"Get precommit type from request. Hook method for clean inheritance.\"\"\"\n try:\n return request.precommit_type or \"external\"\n except AttributeError:\n return \"external\" # Default to external validation\n\n def get_consolidated_issues_count(self) -> int:\n \"\"\"Get count of issues from consolidated findings. Hook method for clean access.\"\"\"\n try:\n return len(self.consolidated_findings.issues_found)\n except AttributeError:\n return 0\n\n def get_completion_message(self) -> str:\n \"\"\"Precommit-specific completion message.\"\"\"\n return (\n \"Pre-commit validation complete. You have identified all issues \"\n \"and verified commit readiness. MANDATORY: Present the user with the complete validation results \"\n \"and IMMEDIATELY proceed with commit if no critical issues found, or provide specific fix guidance \"\n \"if issues need resolution. Focus on actionable next steps.\"\n )\n\n def get_skip_reason(self) -> str:\n \"\"\"Precommit-specific skip reason.\"\"\"\n return (\n \"Completed comprehensive pre-commit validation with internal analysis only (no external model validation)\"\n )\n\n def get_skip_expert_analysis_status(self) -> str:\n \"\"\"Precommit-specific expert analysis skip status.\"\"\"\n return \"skipped_due_to_internal_analysis_type\"\n\n def prepare_work_summary(self) -> str:\n \"\"\"Precommit-specific work summary.\"\"\"\n return self._build_precommit_summary(self.consolidated_findings)\n\n def get_completion_next_steps_message(self, expert_analysis_used: bool = False) -> str:\n \"\"\"\n Precommit-specific completion message.\n\n Args:\n expert_analysis_used: True if expert analysis was successfully executed\n \"\"\"\n base_message = (\n \"PRE-COMMIT VALIDATION IS COMPLETE. You may delete any `pal_precommit.changeset` created. You MUST now summarize \"\n \"and present ALL validation results, identified issues with their severity levels, and exact commit recommendations. \"\n \"Clearly state whether the changes are ready for commit or require fixes first. Provide concrete, actionable guidance for \"\n \"any issues that need resolutionβ€”make it easy for a developer to understand exactly what needs to be \"\n \"done before committing.\"\n )\n\n # Add expert analysis guidance only when expert analysis was actually used\n if expert_analysis_used:\n expert_guidance = self.get_expert_analysis_guidance()\n if expert_guidance:\n return f\"{base_message}\\n\\n{expert_guidance}\"\n\n return base_message\n\n def get_expert_analysis_guidance(self) -> str:\n \"\"\"\n Get additional guidance for handling expert analysis results in pre-commit context.\n\n Returns:\n Additional guidance text for validating and using expert analysis findings\n \"\"\"\n return (\n \"IMPORTANT: Expert analysis has been provided above. You MUST carefully review \"\n \"the expert's validation findings and security assessments. Cross-reference the \"\n \"expert's analysis with your own investigation to ensure all critical issues are \"\n \"addressed. Pay special attention to any security vulnerabilities, performance \"\n \"concerns, or architectural issues identified by the expert review.\"\n )\n\n def get_step_guidance_message(self, request) -> str:\n \"\"\"\n Precommit-specific step guidance with detailed investigation instructions.\n \"\"\"\n step_guidance = self.get_precommit_step_guidance(request.step_number, request)\n return step_guidance[\"next_steps\"]\n\n def get_precommit_step_guidance(self, step_number: int, request) -> dict[str, Any]:\n \"\"\"\n Provide step-specific guidance for precommit workflow.\n Uses get_required_actions to determine what needs to be done,\n then formats those actions into appropriate guidance messages.\n \"\"\"\n # Get the required actions from the single source of truth\n required_actions = self.get_required_actions(\n step_number,\n request.precommit_type or \"external\", # Using precommit_type as confidence proxy\n request.findings or \"\",\n request.total_steps,\n request, # Pass request for continuation-aware decisions\n )\n\n # Check if this is a continuation to provide context-aware guidance\n continuation_id = self.get_request_continuation_id(request)\n is_external_continuation = continuation_id and request.precommit_type == \"external\"\n is_internal_continuation = continuation_id and request.precommit_type == \"internal\"\n\n # Format the guidance based on step number and continuation status\n if step_number == 1:\n if is_external_continuation:\n # Fast-track mode for external continuations\n next_steps = (\n \"You are on step 1 of MAXIMUM 2 steps. CRITICAL: Gather and save the complete git changeset NOW. \"\n \"MANDATORY ACTIONS:\\\\n\"\n + \"\\\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + \"\\\\n\\\\nMANDATORY: The changeset may be large. You MUST save the required changeset as a 'pal_precommit.changeset' file \"\n \"(replacing any existing one) in your work directory and include the FULL absolute path in relevant_files (exclude any \"\n \"binary files). ONLY include the code changes, no extra commentary.\"\n \"Set next_step_required=True and step_number=2 for the next call.\"\n )\n elif is_internal_continuation:\n # Internal validation mode\n next_steps = (\n \"Continuing previous conversation with internal validation only. The analysis will build \"\n \"upon the prior findings without external model validation. REQUIRED ACTIONS:\\\\n\"\n + \"\\\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n )\n else:\n # Normal flow for new validations\n next_steps = (\n f\"MANDATORY: DO NOT call the {self.get_name()} tool again immediately. You MUST first investigate \"\n f\"the git repositories and changes using appropriate tools. CRITICAL AWARENESS: You need to:\\\\n\"\n + \"\\\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\\\n\\\\nOnly call {self.get_name()} again AFTER completing your investigation. \"\n f\"When you call {self.get_name()} next time, use step_number: {step_number + 1} \"\n f\"and report specific files examined, changes analyzed, and validation findings discovered.\"\n )\n\n elif step_number == 2:\n # CRITICAL: Check if violating minimum step requirement\n if (\n request.total_steps >= 3\n and request.step_number < request.total_steps\n and not request.next_step_required\n ):\n next_steps = (\n f\"ERROR: You set total_steps={request.total_steps} but next_step_required=False on step {request.step_number}. \"\n f\"This violates the minimum step requirement. You MUST set next_step_required=True until you reach the final step. \"\n f\"Call {self.get_name()} again with next_step_required=True and continue your investigation.\"\n )\n elif is_external_continuation or (not request.next_step_required and request.precommit_type == \"external\"):\n # Fast-track completion or about to complete - ensure changeset is saved\n next_steps = (\n \"Proceeding immediately to expert analysis. \"\n f\"MANDATORY: call {self.get_name()} tool immediately again, and set next_step_required=False to \"\n f\"trigger external validation NOW. \"\n f\"MANDATORY: Include the entire changeset! The changeset may be large. You MUST save the required \"\n f\"changeset as a 'pal_precommit.changeset' file (replacing any existing one) in your work directory \"\n f\"and include the FULL absolute path in relevant_files so the expert can access the complete changeset. \"\n f\"ONLY include the code changes, no extra commentary.\"\n )\n else:\n # Normal flow - deeper analysis needed\n next_steps = (\n f\"STOP! Do NOT call {self.get_name()} again yet. You are on step 2 of {request.total_steps} minimum required steps. \"\n f\"MANDATORY ACTIONS before calling {self.get_name()} step {step_number + 1}:\\\\n\"\n + \"\\\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\\\n\\\\nRemember: You MUST set next_step_required=True until step {request.total_steps}. \"\n + f\"Only call {self.get_name()} again with step_number: {step_number + 1} AFTER completing these validations.\"\n )\n\n elif step_number >= 3:\n if not request.next_step_required and request.precommit_type == \"external\":\n # About to complete - ensure changeset is saved\n next_steps = (\n \"Completing validation and proceeding to expert analysis. \"\n \"MANDATORY: Save the complete git changeset as a 'pal_precommit.changeset' file \"\n \"in your work directory and include the FULL absolute path in relevant_files.\"\n )\n else:\n # Later steps - final verification\n next_steps = (\n f\"WAIT! Your validation needs final verification. DO NOT call {self.get_name()} immediately. REQUIRED ACTIONS:\\\\n\"\n + \"\\\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\\\n\\\\nREMEMBER: Ensure you have identified all potential issues and verified commit readiness. \"\n f\"Document findings with specific file references and issue descriptions, then call {self.get_name()} \"\n f\"with step_number: {step_number + 1}.\"\n )\n else:\n # Fallback for any other case - check minimum step violation first\n if (\n request.total_steps >= 3\n and request.step_number < request.total_steps\n and not request.next_step_required\n ):\n next_steps = (\n f\"ERROR: You set total_steps={request.total_steps} but next_step_required=False on step {request.step_number}. \"\n f\"This violates the minimum step requirement. You MUST set next_step_required=True until step {request.total_steps}.\"\n )\n elif not request.next_step_required and request.precommit_type == \"external\":\n next_steps = (\n \"Completing validation. \"\n \"MANDATORY: Save complete git changeset as 'pal_precommit.changeset' file and include path in relevant_files, \"\n \"excluding any binary files.\"\n )\n else:\n next_steps = (\n f\"PAUSE VALIDATION. Before calling {self.get_name()} step {step_number + 1}, you MUST examine more code and changes. \"\n + \"Required: \"\n + \", \".join(required_actions[:2])\n + \". \"\n + f\"Your next {self.get_name()} call (step_number: {step_number + 1}) must include \"\n f\"NEW evidence from actual change analysis, not just theories. NO recursive {self.get_name()} calls \"\n f\"without investigation work!\"\n )\n\n return {\"next_steps\": next_steps}\n\n def customize_workflow_response(self, response_data: dict, request) -> dict:\n \"\"\"\n Customize response to match precommit workflow format.\n \"\"\"\n # Store initial request on first step\n if request.step_number == 1:\n self.initial_request = request.step\n # Store git configuration for expert analysis\n if request.path:\n self.git_config = {\n \"path\": request.path,\n \"compare_to\": request.compare_to,\n \"include_staged\": request.include_staged,\n \"include_unstaged\": request.include_unstaged,\n \"severity_filter\": request.severity_filter,\n }\n\n # Convert generic status names to precommit-specific ones\n tool_name = self.get_name()\n status_mapping = {\n f\"{tool_name}_in_progress\": \"validation_in_progress\",\n f\"pause_for_{tool_name}\": \"pause_for_validation\",\n f\"{tool_name}_required\": \"validation_required\",\n f\"{tool_name}_complete\": \"validation_complete\",\n }\n\n if response_data[\"status\"] in status_mapping:\n response_data[\"status\"] = status_mapping[response_data[\"status\"]]\n\n # Rename status field to match precommit workflow\n if f\"{tool_name}_status\" in response_data:\n response_data[\"validation_status\"] = response_data.pop(f\"{tool_name}_status\")\n # Add precommit-specific status fields\n response_data[\"validation_status\"][\"issues_identified\"] = len(self.consolidated_findings.issues_found)\n response_data[\"validation_status\"][\"precommit_type\"] = request.precommit_type or \"external\"\n\n # Map complete_precommitworkflow to complete_validation\n if f\"complete_{tool_name}\" in response_data:\n response_data[\"complete_validation\"] = response_data.pop(f\"complete_{tool_name}\")\n\n # Map the completion flag to match precommit workflow\n if f\"{tool_name}_complete\" in response_data:\n response_data[\"validation_complete\"] = response_data.pop(f\"{tool_name}_complete\")\n\n return response_data\n\n # Required abstract methods from BaseTool\n def get_request_model(self):\n \"\"\"Return the precommit workflow-specific request model.\"\"\"\n return PrecommitRequest\n\n async def prepare_prompt(self, request) -> str:\n \"\"\"Not used - workflow tools use execute_workflow().\"\"\"\n return \"\" # Workflow tools use execute_workflow() directly\n" }, { "path": "tools/refactor.py", "content": "\"\"\"\nRefactor tool - Step-by-step refactoring analysis with expert validation\n\nThis tool provides a structured workflow for comprehensive code refactoring analysis.\nIt guides CLI agent through systematic investigation steps with forced pauses between each step\nto ensure thorough code examination, refactoring opportunity identification, and quality\nassessment before proceeding. The tool supports complex refactoring scenarios including\ncode smell detection, decomposition planning, modernization opportunities, and organization improvements.\n\nKey features:\n- Step-by-step refactoring investigation workflow with progress tracking\n- Context-aware file embedding (references during investigation, full content for analysis)\n- Automatic refactoring opportunity tracking with type and severity classification\n- Expert analysis integration with external models\n- Support for focused refactoring types (codesmells, decompose, modernize, organization)\n- Confidence-based workflow optimization with refactor completion tracking\n\"\"\"\n\nimport logging\nfrom typing import TYPE_CHECKING, Any, Literal, Optional\n\nfrom pydantic import Field, model_validator\n\nif TYPE_CHECKING:\n from tools.models import ToolModelCategory\n\nfrom config import TEMPERATURE_ANALYTICAL\nfrom systemprompts import REFACTOR_PROMPT\nfrom tools.shared.base_models import WorkflowRequest\n\nfrom .workflow.base import WorkflowTool\n\nlogger = logging.getLogger(__name__)\n\n# Tool-specific field descriptions for refactor tool\nREFACTOR_FIELD_DESCRIPTIONS = {\n \"step\": (\n \"The refactoring plan. Step 1: State strategy. Later steps: Report findings. \"\n \"CRITICAL: Examine code for smells, and opportunities for decomposition, modernization, and organization. \"\n \"Use 'relevant_files' for code. FORBIDDEN: Large code snippets.\"\n ),\n \"step_number\": (\n \"The index of the current step in the refactoring investigation sequence, beginning at 1. Each step should \"\n \"build upon or revise the previous one.\"\n ),\n \"total_steps\": (\n \"Your current estimate for how many steps will be needed to complete the refactoring investigation. \"\n \"Adjust as new opportunities emerge.\"\n ),\n \"next_step_required\": (\n \"Set to true if you plan to continue the investigation with another step. False means you believe the \"\n \"refactoring analysis is complete and ready for expert validation.\"\n ),\n \"findings\": (\n \"Summary of discoveries from this step, including code smells and opportunities for decomposition, modernization, or organization. \"\n \"Document both strengths and weaknesses. In later steps, confirm or update past findings.\"\n ),\n \"files_checked\": (\n \"List all files examined (absolute paths). Include even ruled-out files to track exploration path.\"\n ),\n \"relevant_files\": (\n \"Subset of files_checked with code requiring refactoring (absolute paths). Include files with \"\n \"code smells, decomposition needs, or improvement opportunities.\"\n ),\n \"relevant_context\": (\n \"List methods/functions central to refactoring opportunities, in 'ClassName.methodName' or 'functionName' format. \"\n \"Prioritize those with code smells or needing improvement.\"\n ),\n \"issues_found\": (\n \"Refactoring opportunities as dictionaries with 'severity' (critical/high/medium/low), \"\n \"'type' (codesmells/decompose/modernize/organization), and 'description'. \"\n \"Include all improvement opportunities found.\"\n ),\n \"confidence\": (\n \"Your confidence in refactoring analysis: exploring (starting), incomplete (significant work remaining), \"\n \"partial (some opportunities found, more analysis needed), complete (comprehensive analysis finished, \"\n \"all major opportunities identified). \"\n \"WARNING: Use 'complete' ONLY when fully analyzed and can provide recommendations without expert help. \"\n \"'complete' PREVENTS expert validation. Use 'partial' for large files or uncertain analysis.\"\n ),\n \"images\": (\n \"Optional list of absolute paths to architecture diagrams, UI mockups, design documents, or visual references \"\n \"that help with refactoring context. Only include if they materially assist understanding or assessment.\"\n ),\n \"refactor_type\": \"Type of refactoring analysis to perform (codesmells, decompose, modernize, organization)\",\n \"focus_areas\": \"Specific areas to focus on (e.g., 'performance', 'readability', 'maintainability', 'security')\",\n \"style_guide_examples\": (\n \"Optional existing code files to use as style/pattern reference (must be FULL absolute paths to real files / \"\n \"folders - DO NOT SHORTEN). These files represent the target coding style and patterns for the project.\"\n ),\n}\n\n\nclass RefactorRequest(WorkflowRequest):\n \"\"\"Request model for refactor workflow investigation steps\"\"\"\n\n # Required fields for each investigation step\n step: str = Field(..., description=REFACTOR_FIELD_DESCRIPTIONS[\"step\"])\n step_number: int = Field(..., description=REFACTOR_FIELD_DESCRIPTIONS[\"step_number\"])\n total_steps: int = Field(..., description=REFACTOR_FIELD_DESCRIPTIONS[\"total_steps\"])\n next_step_required: bool = Field(..., description=REFACTOR_FIELD_DESCRIPTIONS[\"next_step_required\"])\n\n # Investigation tracking fields\n findings: str = Field(..., description=REFACTOR_FIELD_DESCRIPTIONS[\"findings\"])\n files_checked: list[str] = Field(default_factory=list, description=REFACTOR_FIELD_DESCRIPTIONS[\"files_checked\"])\n relevant_files: list[str] = Field(default_factory=list, description=REFACTOR_FIELD_DESCRIPTIONS[\"relevant_files\"])\n relevant_context: list[str] = Field(\n default_factory=list, description=REFACTOR_FIELD_DESCRIPTIONS[\"relevant_context\"]\n )\n issues_found: list[dict] = Field(default_factory=list, description=REFACTOR_FIELD_DESCRIPTIONS[\"issues_found\"])\n confidence: Optional[Literal[\"exploring\", \"incomplete\", \"partial\", \"complete\"]] = Field(\n \"incomplete\", description=REFACTOR_FIELD_DESCRIPTIONS[\"confidence\"]\n )\n\n # Optional images for visual context\n images: Optional[list[str]] = Field(default=None, description=REFACTOR_FIELD_DESCRIPTIONS[\"images\"])\n\n # Refactor-specific fields (only used in step 1 to initialize)\n refactor_type: Optional[Literal[\"codesmells\", \"decompose\", \"modernize\", \"organization\"]] = Field(\n \"codesmells\", description=REFACTOR_FIELD_DESCRIPTIONS[\"refactor_type\"]\n )\n focus_areas: Optional[list[str]] = Field(None, description=REFACTOR_FIELD_DESCRIPTIONS[\"focus_areas\"])\n style_guide_examples: Optional[list[str]] = Field(\n None, description=REFACTOR_FIELD_DESCRIPTIONS[\"style_guide_examples\"]\n )\n\n # Override inherited fields to exclude them from schema (except model which needs to be available)\n temperature: Optional[float] = Field(default=None, exclude=True)\n thinking_mode: Optional[str] = Field(default=None, exclude=True)\n\n @model_validator(mode=\"after\")\n def validate_step_one_requirements(self):\n \"\"\"Ensure step 1 has required relevant_files field.\"\"\"\n if self.step_number == 1 and not self.relevant_files:\n raise ValueError(\n \"Step 1 requires 'relevant_files' field to specify code files or directories to analyze for refactoring\"\n )\n return self\n\n\nclass RefactorTool(WorkflowTool):\n \"\"\"\n Refactor tool for step-by-step refactoring analysis and expert validation.\n\n This tool implements a structured refactoring workflow that guides users through\n methodical investigation steps, ensuring thorough code examination, refactoring opportunity\n identification, and improvement assessment before reaching conclusions. It supports complex\n refactoring scenarios including code smell detection, decomposition planning, modernization\n opportunities, and organization improvements.\n \"\"\"\n\n def __init__(self):\n super().__init__()\n self.initial_request = None\n self.refactor_config = {}\n\n def get_name(self) -> str:\n return \"refactor\"\n\n def get_description(self) -> str:\n return (\n \"Analyzes code for refactoring opportunities with systematic investigation. \"\n \"Use for code smell detection, decomposition planning, modernization, and maintainability improvements. \"\n \"Guides through structured analysis with expert validation.\"\n )\n\n def get_system_prompt(self) -> str:\n return REFACTOR_PROMPT\n\n def get_default_temperature(self) -> float:\n return TEMPERATURE_ANALYTICAL\n\n def get_model_category(self) -> \"ToolModelCategory\":\n \"\"\"Refactor workflow requires thorough analysis and reasoning\"\"\"\n from tools.models import ToolModelCategory\n\n return ToolModelCategory.EXTENDED_REASONING\n\n def get_workflow_request_model(self):\n \"\"\"Return the refactor workflow-specific request model.\"\"\"\n return RefactorRequest\n\n def get_input_schema(self) -> dict[str, Any]:\n \"\"\"Generate input schema using WorkflowSchemaBuilder with refactor-specific overrides.\"\"\"\n from .workflow.schema_builders import WorkflowSchemaBuilder\n\n # Refactor workflow-specific field overrides\n refactor_field_overrides = {\n \"step\": {\n \"type\": \"string\",\n \"description\": REFACTOR_FIELD_DESCRIPTIONS[\"step\"],\n },\n \"step_number\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": REFACTOR_FIELD_DESCRIPTIONS[\"step_number\"],\n },\n \"total_steps\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": REFACTOR_FIELD_DESCRIPTIONS[\"total_steps\"],\n },\n \"next_step_required\": {\n \"type\": \"boolean\",\n \"description\": REFACTOR_FIELD_DESCRIPTIONS[\"next_step_required\"],\n },\n \"findings\": {\n \"type\": \"string\",\n \"description\": REFACTOR_FIELD_DESCRIPTIONS[\"findings\"],\n },\n \"files_checked\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": REFACTOR_FIELD_DESCRIPTIONS[\"files_checked\"],\n },\n \"relevant_files\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": REFACTOR_FIELD_DESCRIPTIONS[\"relevant_files\"],\n },\n \"confidence\": {\n \"type\": \"string\",\n \"enum\": [\"exploring\", \"incomplete\", \"partial\", \"complete\"],\n \"default\": \"incomplete\",\n \"description\": REFACTOR_FIELD_DESCRIPTIONS[\"confidence\"],\n },\n \"issues_found\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"object\"},\n \"description\": REFACTOR_FIELD_DESCRIPTIONS[\"issues_found\"],\n },\n \"images\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": REFACTOR_FIELD_DESCRIPTIONS[\"images\"],\n },\n # Refactor-specific fields (for step 1)\n # Note: Use relevant_files field instead of files for consistency\n \"refactor_type\": {\n \"type\": \"string\",\n \"enum\": [\"codesmells\", \"decompose\", \"modernize\", \"organization\"],\n \"default\": \"codesmells\",\n \"description\": REFACTOR_FIELD_DESCRIPTIONS[\"refactor_type\"],\n },\n \"focus_areas\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": REFACTOR_FIELD_DESCRIPTIONS[\"focus_areas\"],\n },\n \"style_guide_examples\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": REFACTOR_FIELD_DESCRIPTIONS[\"style_guide_examples\"],\n },\n }\n\n # Use WorkflowSchemaBuilder with refactor-specific tool fields\n return WorkflowSchemaBuilder.build_schema(\n tool_specific_fields=refactor_field_overrides,\n model_field_schema=self.get_model_field_schema(),\n auto_mode=self.is_effective_auto_mode(),\n tool_name=self.get_name(),\n )\n\n def get_required_actions(\n self, step_number: int, confidence: str, findings: str, total_steps: int, request=None\n ) -> list[str]:\n \"\"\"Define required actions for each investigation phase.\"\"\"\n if step_number == 1:\n # Initial refactoring investigation tasks\n return [\n \"Read and understand the code files specified for refactoring analysis\",\n \"Examine the overall structure, architecture, and design patterns used\",\n \"Identify potential code smells: long methods, large classes, duplicate code, complex conditionals\",\n \"Look for decomposition opportunities: oversized components that could be broken down\",\n \"Check for modernization opportunities: outdated patterns, deprecated features, newer language constructs\",\n \"Assess organization: logical grouping, file structure, naming conventions, module boundaries\",\n \"Document specific refactoring opportunities with file locations and line numbers\",\n ]\n elif confidence in [\"exploring\", \"incomplete\"]:\n # Need deeper investigation\n return [\n \"Examine specific code sections you've identified as needing refactoring\",\n \"Analyze code smells in detail: complexity, coupling, cohesion issues\",\n \"Investigate decomposition opportunities: identify natural breaking points for large components\",\n \"Look for modernization possibilities: language features, patterns, libraries that could improve the code\",\n \"Check organization issues: related functionality that could be better grouped or structured\",\n \"Trace dependencies and relationships between components to understand refactoring impact\",\n \"Prioritize refactoring opportunities by impact and effort required\",\n ]\n elif confidence == \"partial\":\n # Close to completion - need final verification\n return [\n \"Verify all identified refactoring opportunities have been properly documented with locations\",\n \"Check for any missed opportunities in areas not yet thoroughly examined\",\n \"Confirm that refactoring suggestions align with the specified refactor_type and focus_areas\",\n \"Ensure refactoring opportunities are prioritized by severity and impact\",\n \"Validate that proposed changes would genuinely improve code quality without breaking functionality\",\n \"Double-check that all relevant files and code elements are captured in your analysis\",\n ]\n else:\n # General investigation needed\n return [\n \"Continue examining the codebase for additional refactoring opportunities\",\n \"Gather more evidence using appropriate code analysis techniques\",\n \"Test your assumptions about code quality and improvement possibilities\",\n \"Look for patterns that confirm or refute your current refactoring assessment\",\n \"Focus on areas that haven't been thoroughly examined for refactoring potential\",\n ]\n\n def should_call_expert_analysis(self, consolidated_findings, request=None) -> bool:\n \"\"\"\n Decide when to call external model based on investigation completeness.\n\n Don't call expert analysis if the CLI agent has certain confidence and complete refactoring - trust their judgment.\n \"\"\"\n # Check if user requested to skip assistant model\n if request and not self.get_request_use_assistant_model(request):\n return False\n\n # Check if refactoring work is complete\n if request and request.confidence == \"complete\":\n return False\n\n # Check if we have meaningful investigation data\n return (\n len(consolidated_findings.relevant_files) > 0\n or len(consolidated_findings.findings) >= 2\n or len(consolidated_findings.issues_found) > 0\n )\n\n def prepare_expert_analysis_context(self, consolidated_findings) -> str:\n \"\"\"Prepare context for external model call for final refactoring validation.\"\"\"\n context_parts = [\n f\"=== REFACTORING ANALYSIS REQUEST ===\\\\n{self.initial_request or 'Refactoring workflow initiated'}\\\\n=== END REQUEST ===\"\n ]\n\n # Add investigation summary\n investigation_summary = self._build_refactoring_summary(consolidated_findings)\n context_parts.append(\n f\"\\\\n=== AGENT'S REFACTORING INVESTIGATION ===\\\\n{investigation_summary}\\\\n=== END INVESTIGATION ===\"\n )\n\n # Add refactor configuration context if available\n if self.refactor_config:\n config_text = \"\\\\n\".join(f\"- {key}: {value}\" for key, value in self.refactor_config.items() if value)\n context_parts.append(f\"\\\\n=== REFACTOR CONFIGURATION ===\\\\n{config_text}\\\\n=== END CONFIGURATION ===\")\n\n # Add relevant code elements if available\n if consolidated_findings.relevant_context:\n methods_text = \"\\\\n\".join(f\"- {method}\" for method in consolidated_findings.relevant_context)\n context_parts.append(f\"\\\\n=== RELEVANT CODE ELEMENTS ===\\\\n{methods_text}\\\\n=== END CODE ELEMENTS ===\")\n\n # Add refactoring opportunities found if available\n if consolidated_findings.issues_found:\n opportunities_text = \"\\\\n\".join(\n f\"[{issue.get('severity', 'unknown').upper()}] {issue.get('type', 'unknown').upper()}: {issue.get('description', 'No description')}\"\n for issue in consolidated_findings.issues_found\n )\n context_parts.append(\n f\"\\\\n=== REFACTORING OPPORTUNITIES ===\\\\n{opportunities_text}\\\\n=== END OPPORTUNITIES ===\"\n )\n\n # Add assessment evolution if available\n if consolidated_findings.hypotheses:\n assessments_text = \"\\\\n\".join(\n f\"Step {h['step']} ({h['confidence']} confidence): {h['hypothesis']}\"\n for h in consolidated_findings.hypotheses\n )\n context_parts.append(f\"\\\\n=== ASSESSMENT EVOLUTION ===\\\\n{assessments_text}\\\\n=== END ASSESSMENTS ===\")\n\n # Add images if available\n if consolidated_findings.images:\n images_text = \"\\\\n\".join(f\"- {img}\" for img in consolidated_findings.images)\n context_parts.append(\n f\"\\\\n=== VISUAL REFACTORING INFORMATION ===\\\\n{images_text}\\\\n=== END VISUAL INFORMATION ===\"\n )\n\n return \"\\\\n\".join(context_parts)\n\n def _build_refactoring_summary(self, consolidated_findings) -> str:\n \"\"\"Prepare a comprehensive summary of the refactoring investigation.\"\"\"\n summary_parts = [\n \"=== SYSTEMATIC REFACTORING INVESTIGATION SUMMARY ===\",\n f\"Total steps: {len(consolidated_findings.findings)}\",\n f\"Files examined: {len(consolidated_findings.files_checked)}\",\n f\"Relevant files identified: {len(consolidated_findings.relevant_files)}\",\n f\"Code elements analyzed: {len(consolidated_findings.relevant_context)}\",\n f\"Refactoring opportunities identified: {len(consolidated_findings.issues_found)}\",\n \"\",\n \"=== INVESTIGATION PROGRESSION ===\",\n ]\n\n for finding in consolidated_findings.findings:\n summary_parts.append(finding)\n\n return \"\\\\n\".join(summary_parts)\n\n def should_include_files_in_expert_prompt(self) -> bool:\n \"\"\"Include files in expert analysis for comprehensive refactoring validation.\"\"\"\n return True\n\n def should_embed_system_prompt(self) -> bool:\n \"\"\"Embed system prompt in expert analysis for proper context.\"\"\"\n return True\n\n def get_expert_thinking_mode(self) -> str:\n \"\"\"Use high thinking mode for thorough refactoring analysis.\"\"\"\n return \"high\"\n\n def get_expert_analysis_instruction(self) -> str:\n \"\"\"Get specific instruction for refactoring expert analysis.\"\"\"\n return (\n \"Please provide comprehensive refactoring analysis based on the investigation findings. \"\n \"Focus on validating the identified opportunities, ensuring completeness of the analysis, \"\n \"and providing final recommendations for refactoring implementation, following the structured \"\n \"format specified in the system prompt.\"\n )\n\n # Hook method overrides for refactor-specific behavior\n\n def prepare_step_data(self, request) -> dict:\n \"\"\"\n Map refactor workflow-specific fields for internal processing.\n \"\"\"\n step_data = {\n \"step\": request.step,\n \"step_number\": request.step_number,\n \"findings\": request.findings,\n \"files_checked\": request.files_checked,\n \"relevant_files\": request.relevant_files,\n \"relevant_context\": request.relevant_context,\n \"issues_found\": request.issues_found,\n \"confidence\": request.confidence,\n \"hypothesis\": request.findings, # Map findings to hypothesis for compatibility\n \"images\": request.images or [],\n }\n return step_data\n\n def should_skip_expert_analysis(self, request, consolidated_findings) -> bool:\n \"\"\"\n Refactor workflow skips expert analysis when the CLI agent has \"complete\" confidence.\n \"\"\"\n return request.confidence == \"complete\" and not request.next_step_required\n\n def store_initial_issue(self, step_description: str):\n \"\"\"Store initial request for expert analysis.\"\"\"\n self.initial_request = step_description\n\n # Inheritance hook methods for refactor-specific behavior\n\n # Override inheritance hooks for refactor-specific behavior\n\n def get_completion_status(self) -> str:\n \"\"\"Refactor tools use refactor-specific status.\"\"\"\n return \"refactoring_analysis_complete_ready_for_implementation\"\n\n def get_completion_data_key(self) -> str:\n \"\"\"Refactor uses 'complete_refactoring' key.\"\"\"\n return \"complete_refactoring\"\n\n def get_final_analysis_from_request(self, request):\n \"\"\"Refactor tools use 'findings' field.\"\"\"\n return request.findings\n\n def get_confidence_level(self, request) -> str:\n \"\"\"Refactor tools use 'complete' for high confidence.\"\"\"\n return \"complete\"\n\n def get_completion_message(self) -> str:\n \"\"\"Refactor-specific completion message.\"\"\"\n return (\n \"Refactoring analysis complete with COMPLETE confidence. You have identified all significant \"\n \"refactoring opportunities and provided comprehensive analysis. MANDATORY: Present the user with \"\n \"the complete refactoring results organized by type and severity, and IMMEDIATELY proceed with \"\n \"implementing the highest priority refactoring opportunities or provide specific guidance for \"\n \"improvements. Focus on actionable refactoring steps.\"\n )\n\n def get_skip_reason(self) -> str:\n \"\"\"Refactor-specific skip reason.\"\"\"\n return \"Completed comprehensive refactoring analysis with full confidence locally\"\n\n def get_skip_expert_analysis_status(self) -> str:\n \"\"\"Refactor-specific expert analysis skip status.\"\"\"\n return \"skipped_due_to_complete_refactoring_confidence\"\n\n def prepare_work_summary(self) -> str:\n \"\"\"Refactor-specific work summary.\"\"\"\n return self._build_refactoring_summary(self.consolidated_findings)\n\n def get_completion_next_steps_message(self, expert_analysis_used: bool = False) -> str:\n \"\"\"\n Refactor-specific completion message.\n\n Args:\n expert_analysis_used: True if expert analysis was successfully executed\n \"\"\"\n base_message = (\n \"REFACTORING ANALYSIS IS COMPLETE. You MUST now summarize and present ALL refactoring opportunities \"\n \"organized by type (codesmells β†’ decompose β†’ modernize β†’ organization) and severity (Critical β†’ High β†’ \"\n \"Medium β†’ Low), specific code locations with line numbers, and exact recommendations for improvement. \"\n \"Clearly prioritize the top 3 refactoring opportunities that need immediate attention. Provide concrete, \"\n \"actionable guidance for each opportunityβ€”make it easy for a developer to understand exactly what needs \"\n \"to be refactored and how to implement the improvements.\"\n )\n\n # Add expert analysis guidance only when expert analysis was actually used\n if expert_analysis_used:\n expert_guidance = self.get_expert_analysis_guidance()\n if expert_guidance:\n return f\"{base_message}\\n\\n{expert_guidance}\"\n\n return base_message\n\n def get_expert_analysis_guidance(self) -> str:\n \"\"\"\n Get additional guidance for handling expert analysis results in refactor context.\n\n Returns:\n Additional guidance text for validating and using expert analysis findings\n \"\"\"\n return (\n \"IMPORTANT: Expert refactoring analysis has been provided above. You MUST review \"\n \"the expert's architectural insights and refactoring recommendations. Consider whether \"\n \"the expert's suggestions align with the codebase's evolution trajectory and current \"\n \"team priorities. Pay special attention to any breaking changes, migration complexity, \"\n \"or performance implications highlighted by the expert. Present a balanced view that \"\n \"considers both immediate benefits and long-term maintainability.\"\n )\n\n def get_step_guidance_message(self, request) -> str:\n \"\"\"\n Refactor-specific step guidance with detailed investigation instructions.\n \"\"\"\n step_guidance = self.get_refactor_step_guidance(request.step_number, request.confidence, request)\n return step_guidance[\"next_steps\"]\n\n def get_refactor_step_guidance(self, step_number: int, confidence: str, request) -> dict[str, Any]:\n \"\"\"\n Provide step-specific guidance for refactor workflow.\n \"\"\"\n # Generate the next steps instruction based on required actions\n required_actions = self.get_required_actions(step_number, confidence, request.findings, request.total_steps)\n\n if step_number == 1:\n next_steps = (\n f\"MANDATORY: DO NOT call the {self.get_name()} tool again immediately. You MUST first examine \"\n f\"the code files thoroughly for refactoring opportunities using appropriate tools. CRITICAL AWARENESS: \"\n f\"You need to identify code smells, decomposition opportunities, modernization possibilities, and \"\n f\"organization improvements across the specified refactor_type. Look for complexity issues, outdated \"\n f\"patterns, oversized components, and structural problems. Use file reading tools, code analysis, and \"\n f\"systematic examination to gather comprehensive refactoring information. Only call {self.get_name()} \"\n f\"again AFTER completing your investigation. When you call {self.get_name()} next time, use \"\n f\"step_number: {step_number + 1} and report specific files examined, refactoring opportunities found, \"\n f\"and improvement assessments discovered.\"\n )\n elif confidence in [\"exploring\", \"incomplete\"]:\n next_steps = (\n f\"STOP! Do NOT call {self.get_name()} again yet. Based on your findings, you've identified areas that need \"\n f\"deeper refactoring analysis. MANDATORY ACTIONS before calling {self.get_name()} step {step_number + 1}:\\\\n\"\n + \"\\\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\\\n\\\\nOnly call {self.get_name()} again with step_number: {step_number + 1} AFTER \"\n + \"completing these refactoring analysis tasks.\"\n )\n elif confidence == \"partial\":\n next_steps = (\n f\"WAIT! Your refactoring analysis needs final verification. DO NOT call {self.get_name()} immediately. REQUIRED ACTIONS:\\\\n\"\n + \"\\\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\\\n\\\\nREMEMBER: Ensure you have identified all significant refactoring opportunities across all types and \"\n f\"verified the completeness of your analysis. Document opportunities with specific file references and \"\n f\"line numbers where applicable, then call {self.get_name()} with step_number: {step_number + 1}.\"\n )\n else:\n next_steps = (\n f\"PAUSE REFACTORING ANALYSIS. Before calling {self.get_name()} step {step_number + 1}, you MUST examine more code thoroughly. \"\n + \"Required: \"\n + \", \".join(required_actions[:2])\n + \". \"\n + f\"Your next {self.get_name()} call (step_number: {step_number + 1}) must include \"\n f\"NEW evidence from actual refactoring analysis, not just theories. NO recursive {self.get_name()} calls \"\n f\"without investigation work!\"\n )\n\n return {\"next_steps\": next_steps}\n\n def customize_workflow_response(self, response_data: dict, request) -> dict:\n \"\"\"\n Customize response to match refactor workflow format.\n \"\"\"\n # Store initial request on first step\n if request.step_number == 1:\n self.initial_request = request.step\n # Store refactor configuration for expert analysis\n if request.relevant_files:\n self.refactor_config = {\n \"relevant_files\": request.relevant_files,\n \"refactor_type\": request.refactor_type,\n \"focus_areas\": request.focus_areas,\n \"style_guide_examples\": request.style_guide_examples,\n }\n\n # Convert generic status names to refactor-specific ones\n tool_name = self.get_name()\n status_mapping = {\n f\"{tool_name}_in_progress\": \"refactoring_analysis_in_progress\",\n f\"pause_for_{tool_name}\": \"pause_for_refactoring_analysis\",\n f\"{tool_name}_required\": \"refactoring_analysis_required\",\n f\"{tool_name}_complete\": \"refactoring_analysis_complete\",\n }\n\n if response_data[\"status\"] in status_mapping:\n response_data[\"status\"] = status_mapping[response_data[\"status\"]]\n\n # Rename status field to match refactor workflow\n if f\"{tool_name}_status\" in response_data:\n response_data[\"refactoring_status\"] = response_data.pop(f\"{tool_name}_status\")\n # Add refactor-specific status fields\n refactor_types = {}\n for issue in self.consolidated_findings.issues_found:\n issue_type = issue.get(\"type\", \"unknown\")\n if issue_type not in refactor_types:\n refactor_types[issue_type] = 0\n refactor_types[issue_type] += 1\n response_data[\"refactoring_status\"][\"opportunities_by_type\"] = refactor_types\n response_data[\"refactoring_status\"][\"refactor_confidence\"] = request.confidence\n\n # Map complete_refactor to complete_refactoring\n if f\"complete_{tool_name}\" in response_data:\n response_data[\"complete_refactoring\"] = response_data.pop(f\"complete_{tool_name}\")\n\n # Map the completion flag to match refactor workflow\n if f\"{tool_name}_complete\" in response_data:\n response_data[\"refactoring_complete\"] = response_data.pop(f\"{tool_name}_complete\")\n\n return response_data\n\n # Required abstract methods from BaseTool\n def get_request_model(self):\n \"\"\"Return the refactor workflow-specific request model.\"\"\"\n return RefactorRequest\n\n async def prepare_prompt(self, request) -> str:\n \"\"\"Not used - workflow tools use execute_workflow().\"\"\"\n return \"\" # Workflow tools use execute_workflow() directly\n" }, { "path": "tools/secaudit.py", "content": "\"\"\"\nSECAUDIT Workflow tool - Comprehensive security audit with systematic investigation\n\nThis tool provides a structured workflow for comprehensive security assessment and analysis.\nIt guides the CLI agent through systematic investigation steps with forced pauses between each step\nto ensure thorough security examination, vulnerability identification, and compliance assessment\nbefore proceeding. The tool supports complex security scenarios including OWASP Top 10 coverage,\ncompliance framework mapping, and technology-specific security patterns.\n\nKey features:\n- Step-by-step security audit workflow with progress tracking\n- Context-aware file embedding (references during investigation, full content for analysis)\n- Automatic security issue tracking with severity classification\n- Expert analysis integration with external models\n- Support for focused security audits (OWASP, compliance, technology-specific)\n- Confidence-based workflow optimization\n- Risk-based prioritization and remediation planning\n\"\"\"\n\nimport logging\nfrom typing import TYPE_CHECKING, Any, Literal, Optional\n\nfrom pydantic import Field, model_validator\n\nif TYPE_CHECKING:\n from tools.models import ToolModelCategory\n\nfrom config import TEMPERATURE_ANALYTICAL\nfrom systemprompts import SECAUDIT_PROMPT\nfrom tools.shared.base_models import WorkflowRequest\n\nfrom .workflow.base import WorkflowTool\n\nlogger = logging.getLogger(__name__)\n\n# Tool-specific field descriptions for security audit workflow\nSECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS = {\n \"step\": (\n \"Step 1: outline the audit strategy (OWASP Top 10, auth, validation, etc.). Later steps: report findings. MANDATORY: use `relevant_files` for code references and avoid large snippets.\"\n ),\n \"step_number\": \"Current security-audit step number (starts at 1).\",\n \"total_steps\": \"Expected number of audit steps; adjust as new risks surface.\",\n \"next_step_required\": \"True while additional threat analysis remains; set False once you are ready to hand off for validation.\",\n \"findings\": \"Summarize vulnerabilities, auth issues, validation gaps, compliance notes, and positives; update prior findings as needed.\",\n \"files_checked\": \"Absolute paths for every file inspected, including rejected candidates.\",\n \"relevant_files\": \"Absolute paths for security-relevant files (auth modules, configs, sensitive code).\",\n \"relevant_context\": \"Security-critical classes/methods (e.g. 'AuthService.login', 'encryption_helper').\",\n \"issues_found\": \"Security issues with severity (critical/high/medium/low) and descriptions (vulns, auth flaws, injection, crypto, config).\",\n \"confidence\": \"exploring/low/medium/high/very_high/almost_certain/certain. 'certain' blocks external validationβ€”use only when fully complete.\",\n \"images\": \"Optional absolute paths to diagrams or threat models that inform the audit.\",\n \"security_scope\": \"Security context (web, mobile, API, cloud, etc.) including stack, user types, data sensitivity, and threat landscape.\",\n \"threat_level\": \"Assess the threat level: low (internal/low-risk), medium (customer-facing/business data), high (regulated or sensitive), critical (financial/healthcare/PII).\",\n \"compliance_requirements\": \"Applicable compliance frameworks or standards (SOC2, PCI DSS, HIPAA, GDPR, ISO 27001, NIST, etc.).\",\n \"audit_focus\": \"Primary focus area: owasp, compliance, infrastructure, dependencies, or comprehensive.\",\n \"severity_filter\": \"Minimum severity to include when reporting security issues.\",\n}\n\n\nclass SecauditRequest(WorkflowRequest):\n \"\"\"Request model for security audit workflow investigation steps\"\"\"\n\n # Required fields for each investigation step\n step: str = Field(..., description=SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"step\"])\n step_number: int = Field(..., description=SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"step_number\"])\n total_steps: int = Field(..., description=SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"total_steps\"])\n next_step_required: bool = Field(..., description=SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"next_step_required\"])\n\n # Investigation tracking fields\n findings: str = Field(..., description=SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"findings\"])\n files_checked: list[str] = Field(\n default_factory=list, description=SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"files_checked\"]\n )\n relevant_files: list[str] = Field(\n default_factory=list, description=SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_files\"]\n )\n relevant_context: list[str] = Field(\n default_factory=list, description=SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_context\"]\n )\n issues_found: list[dict] = Field(\n default_factory=list, description=SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"issues_found\"]\n )\n confidence: Optional[str] = Field(\"low\", description=SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"confidence\"])\n\n # Optional images for visual context\n images: Optional[list[str]] = Field(default=None, description=SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"images\"])\n\n # Security audit-specific fields\n security_scope: Optional[str] = Field(None, description=SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"security_scope\"])\n threat_level: Optional[Literal[\"low\", \"medium\", \"high\", \"critical\"]] = Field(\n \"medium\", description=SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"threat_level\"]\n )\n compliance_requirements: Optional[list[str]] = Field(\n default_factory=list, description=SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"compliance_requirements\"]\n )\n audit_focus: Optional[Literal[\"owasp\", \"compliance\", \"infrastructure\", \"dependencies\", \"comprehensive\"]] = Field(\n \"comprehensive\", description=SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"audit_focus\"]\n )\n severity_filter: Optional[Literal[\"critical\", \"high\", \"medium\", \"low\", \"all\"]] = Field(\n \"all\", description=SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"severity_filter\"]\n )\n\n @model_validator(mode=\"after\")\n def validate_security_audit_request(self):\n \"\"\"Validate security audit request parameters\"\"\"\n # Ensure security scope is provided for comprehensive audits\n if self.step_number == 1 and not self.security_scope:\n logger.warning(\"Security scope not provided for security audit - defaulting to general application\")\n\n # Validate compliance requirements format\n if self.compliance_requirements:\n valid_compliance = {\"SOC2\", \"PCI DSS\", \"HIPAA\", \"GDPR\", \"ISO 27001\", \"NIST\", \"FedRAMP\", \"FISMA\"}\n for req in self.compliance_requirements:\n if req not in valid_compliance:\n logger.warning(f\"Unknown compliance requirement: {req}\")\n\n return self\n\n\nclass SecauditTool(WorkflowTool):\n \"\"\"\n Comprehensive security audit workflow tool.\n\n Provides systematic security assessment through multi-step investigation\n covering OWASP Top 10, compliance requirements, and technology-specific\n security patterns. Follows established WorkflowTool patterns while adding\n security-specific capabilities.\n \"\"\"\n\n def __init__(self):\n super().__init__()\n self.initial_request = None\n self.security_config = {}\n\n def get_name(self) -> str:\n \"\"\"Return the unique name of the tool.\"\"\"\n return \"secaudit\"\n\n def get_description(self) -> str:\n \"\"\"Return a description of the tool.\"\"\"\n return (\n \"Performs comprehensive security audit with systematic vulnerability assessment. \"\n \"Use for OWASP Top 10 analysis, compliance evaluation, threat modeling, and security architecture review. \"\n \"Guides through structured security investigation with expert validation.\"\n )\n\n def get_system_prompt(self) -> str:\n \"\"\"Return the system prompt for expert security analysis.\"\"\"\n return SECAUDIT_PROMPT\n\n def get_default_temperature(self) -> float:\n \"\"\"Return the temperature for security audit analysis\"\"\"\n return TEMPERATURE_ANALYTICAL\n\n def get_model_category(self) -> \"ToolModelCategory\":\n \"\"\"Return the model category for security audit\"\"\"\n from tools.models import ToolModelCategory\n\n return ToolModelCategory.EXTENDED_REASONING\n\n def get_workflow_request_model(self) -> type:\n \"\"\"Return the workflow request model class\"\"\"\n return SecauditRequest\n\n def get_tool_fields(self) -> dict[str, dict[str, Any]]:\n \"\"\"\n Get security audit tool field definitions.\n\n Returns comprehensive field definitions including security-specific\n parameters while maintaining compatibility with existing workflow patterns.\n \"\"\"\n return SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS\n\n def get_required_actions(\n self, step_number: int, confidence: str, findings: str, total_steps: int, request=None\n ) -> list[str]:\n \"\"\"\n Provide step-specific guidance for systematic security analysis.\n\n Each step focuses on specific security domains to ensure comprehensive\n coverage without missing critical security aspects.\n \"\"\"\n if step_number == 1:\n return [\n \"Identify application type, technology stack, and security scope\",\n \"Map attack surface, entry points, and data flows\",\n \"Determine relevant security standards and compliance requirements\",\n \"Establish threat landscape and risk context for the application\",\n ]\n elif step_number == 2:\n return [\n \"Analyze authentication mechanisms and session management\",\n \"Check authorization controls, access patterns, and privilege escalation risks\",\n \"Assess multi-factor authentication, password policies, and account security\",\n \"Review identity and access management implementations\",\n ]\n elif step_number == 3:\n return [\n \"Examine input validation and sanitization mechanisms across all entry points\",\n \"Check for injection vulnerabilities (SQL, XSS, Command, LDAP, NoSQL)\",\n \"Review data encryption, sensitive data handling, and cryptographic implementations\",\n \"Analyze API input validation, rate limiting, and request/response security\",\n ]\n elif step_number == 4:\n return [\n \"Conduct OWASP Top 10 (2021) systematic review across all categories\",\n \"Check each OWASP category methodically with specific findings and evidence\",\n \"Cross-reference findings with application context and technology stack\",\n \"Prioritize vulnerabilities based on exploitability and business impact\",\n ]\n elif step_number == 5:\n return [\n \"Analyze third-party dependencies for known vulnerabilities and outdated versions\",\n \"Review configuration security, default settings, and hardening measures\",\n \"Check for hardcoded secrets, credentials, and sensitive information exposure\",\n \"Assess logging, monitoring, incident response, and security observability\",\n ]\n elif step_number == 6:\n return [\n \"Evaluate compliance requirements and identify gaps in controls\",\n \"Assess business impact and risk levels of all identified findings\",\n \"Create prioritized remediation roadmap with timeline and effort estimates\",\n \"Document comprehensive security posture and recommendations\",\n ]\n else:\n return [\n \"Continue systematic security investigation based on emerging findings\",\n \"Deep-dive into specific security concerns identified in previous steps\",\n \"Validate security hypotheses and confirm vulnerability assessments\",\n ]\n\n def should_call_expert_analysis(self, consolidated_findings, request=None) -> bool:\n \"\"\"\n Determine when to call expert security analysis.\n\n Expert analysis is triggered when the security audit has meaningful findings\n unless the user requested to skip assistant model.\n \"\"\"\n # Check if user requested to skip assistant model\n if request and not self.get_request_use_assistant_model(request):\n return False\n\n # Check if we have meaningful investigation data\n return (\n len(consolidated_findings.relevant_files) > 0\n or len(consolidated_findings.findings) >= 2\n or len(consolidated_findings.issues_found) > 0\n )\n\n def prepare_expert_analysis_context(self, consolidated_findings) -> str:\n \"\"\"\n Prepare comprehensive context for expert security model analysis.\n\n Provides security-specific context including scope, threat level,\n compliance requirements, and systematic findings for expert validation.\n \"\"\"\n context_parts = [\n f\"=== SECURITY AUDIT REQUEST ===\\n{self.initial_request or 'Security audit workflow initiated'}\\n=== END REQUEST ===\"\n ]\n\n # Add investigation summary\n investigation_summary = self._build_security_audit_summary(consolidated_findings)\n context_parts.append(\n f\"\\n=== AGENT'S SECURITY INVESTIGATION ===\\n{investigation_summary}\\n=== END INVESTIGATION ===\"\n )\n\n # Add security configuration context if available\n if self.security_config:\n config_text = \"\\n\".join(f\"- {key}: {value}\" for key, value in self.security_config.items() if value)\n context_parts.append(f\"\\n=== SECURITY CONFIGURATION ===\\n{config_text}\\n=== END CONFIGURATION ===\")\n\n # Add relevant files if available\n if consolidated_findings.relevant_files:\n files_text = \"\\n\".join(f\"- {file}\" for file in consolidated_findings.relevant_files)\n context_parts.append(f\"\\n=== RELEVANT FILES ===\\n{files_text}\\n=== END FILES ===\")\n\n # Add relevant security elements if available\n if consolidated_findings.relevant_context:\n methods_text = \"\\n\".join(f\"- {method}\" for method in consolidated_findings.relevant_context)\n context_parts.append(\n f\"\\n=== SECURITY-CRITICAL CODE ELEMENTS ===\\n{methods_text}\\n=== END CODE ELEMENTS ===\"\n )\n\n # Add security issues found if available\n if consolidated_findings.issues_found:\n issues_text = self._format_security_issues(consolidated_findings.issues_found)\n context_parts.append(f\"\\n=== SECURITY ISSUES IDENTIFIED ===\\n{issues_text}\\n=== END ISSUES ===\")\n\n # Add assessment evolution if available\n if consolidated_findings.hypotheses:\n assessments_text = \"\\n\".join(\n f\"Step {h['step']} ({h['confidence']} confidence): {h['hypothesis']}\"\n for h in consolidated_findings.hypotheses\n )\n context_parts.append(f\"\\n=== ASSESSMENT EVOLUTION ===\\n{assessments_text}\\n=== END ASSESSMENTS ===\")\n\n # Add images if available\n if consolidated_findings.images:\n images_text = \"\\n\".join(f\"- {img}\" for img in consolidated_findings.images)\n context_parts.append(\n f\"\\n=== VISUAL SECURITY INFORMATION ===\\n{images_text}\\n=== END VISUAL INFORMATION ===\"\n )\n\n return \"\\n\".join(context_parts)\n\n def _format_security_issues(self, issues_found: list[dict]) -> str:\n \"\"\"\n Format security issues for expert analysis.\n\n Organizes security findings by severity for clear expert review.\n \"\"\"\n if not issues_found:\n return \"No security issues identified during systematic investigation.\"\n\n # Group issues by severity\n severity_groups = {\"critical\": [], \"high\": [], \"medium\": [], \"low\": []}\n\n for issue in issues_found:\n severity = issue.get(\"severity\", \"low\").lower()\n description = issue.get(\"description\", \"No description provided\")\n if severity in severity_groups:\n severity_groups[severity].append(description)\n else:\n severity_groups[\"low\"].append(f\"[{severity.upper()}] {description}\")\n\n formatted_issues = []\n for severity in [\"critical\", \"high\", \"medium\", \"low\"]:\n if severity_groups[severity]:\n formatted_issues.append(f\"\\n{severity.upper()} SEVERITY:\")\n for issue in severity_groups[severity]:\n formatted_issues.append(f\" β€’ {issue}\")\n\n return \"\\n\".join(formatted_issues) if formatted_issues else \"No security issues identified.\"\n\n def _build_security_audit_summary(self, consolidated_findings) -> str:\n \"\"\"Prepare a comprehensive summary of the security audit investigation.\"\"\"\n summary_parts = [\n \"=== SYSTEMATIC SECURITY AUDIT INVESTIGATION SUMMARY ===\",\n f\"Total steps: {len(consolidated_findings.findings)}\",\n f\"Files examined: {len(consolidated_findings.files_checked)}\",\n f\"Relevant files identified: {len(consolidated_findings.relevant_files)}\",\n f\"Security-critical elements analyzed: {len(consolidated_findings.relevant_context)}\",\n f\"Security issues identified: {len(consolidated_findings.issues_found)}\",\n \"\",\n \"=== INVESTIGATION PROGRESSION ===\",\n ]\n\n for finding in consolidated_findings.findings:\n summary_parts.append(finding)\n\n return \"\\n\".join(summary_parts)\n\n def get_input_schema(self) -> dict[str, Any]:\n \"\"\"Generate input schema using WorkflowSchemaBuilder with security audit-specific overrides.\"\"\"\n from .workflow.schema_builders import WorkflowSchemaBuilder\n\n # Security audit workflow-specific field overrides\n secaudit_field_overrides = {\n \"step\": {\n \"type\": \"string\",\n \"description\": SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"step\"],\n },\n \"step_number\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"step_number\"],\n },\n \"total_steps\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"total_steps\"],\n },\n \"next_step_required\": {\n \"type\": \"boolean\",\n \"description\": SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"next_step_required\"],\n },\n \"findings\": {\n \"type\": \"string\",\n \"description\": SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"findings\"],\n },\n \"files_checked\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"files_checked\"],\n },\n \"relevant_files\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_files\"],\n },\n \"confidence\": {\n \"type\": \"string\",\n \"enum\": [\"exploring\", \"low\", \"medium\", \"high\", \"very_high\", \"almost_certain\", \"certain\"],\n \"description\": SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"confidence\"],\n },\n \"issues_found\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"object\"},\n \"description\": SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"issues_found\"],\n },\n \"images\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"images\"],\n },\n # Security audit-specific fields (for step 1)\n \"security_scope\": {\n \"type\": \"string\",\n \"description\": SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"security_scope\"],\n },\n \"threat_level\": {\n \"type\": \"string\",\n \"enum\": [\"low\", \"medium\", \"high\", \"critical\"],\n \"default\": \"medium\",\n \"description\": SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"threat_level\"],\n },\n \"compliance_requirements\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"compliance_requirements\"],\n },\n \"audit_focus\": {\n \"type\": \"string\",\n \"enum\": [\"owasp\", \"compliance\", \"infrastructure\", \"dependencies\", \"comprehensive\"],\n \"default\": \"comprehensive\",\n \"description\": SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"audit_focus\"],\n },\n \"severity_filter\": {\n \"type\": \"string\",\n \"enum\": [\"critical\", \"high\", \"medium\", \"low\", \"all\"],\n \"default\": \"all\",\n \"description\": SECAUDIT_WORKFLOW_FIELD_DESCRIPTIONS[\"severity_filter\"],\n },\n }\n\n # Use WorkflowSchemaBuilder with security audit-specific tool fields\n return WorkflowSchemaBuilder.build_schema(\n tool_specific_fields=secaudit_field_overrides,\n model_field_schema=self.get_model_field_schema(),\n auto_mode=self.is_effective_auto_mode(),\n tool_name=self.get_name(),\n )\n\n # Hook method overrides for security audit-specific behavior\n\n def prepare_step_data(self, request) -> dict:\n \"\"\"Map security audit-specific fields for internal processing.\"\"\"\n step_data = {\n \"step\": request.step,\n \"step_number\": request.step_number,\n \"findings\": request.findings,\n \"files_checked\": request.files_checked,\n \"relevant_files\": request.relevant_files,\n \"relevant_context\": request.relevant_context,\n \"issues_found\": request.issues_found,\n \"confidence\": request.confidence,\n \"hypothesis\": request.findings, # Map findings to hypothesis for compatibility\n \"images\": request.images or [],\n }\n\n # Store security-specific configuration on first step\n if request.step_number == 1:\n self.security_config = {\n \"security_scope\": request.security_scope,\n \"threat_level\": request.threat_level,\n \"compliance_requirements\": request.compliance_requirements,\n \"audit_focus\": request.audit_focus,\n \"severity_filter\": request.severity_filter,\n }\n\n return step_data\n\n def should_skip_expert_analysis(self, request, consolidated_findings) -> bool:\n \"\"\"Security audit workflow skips expert analysis when the CLI agent has \"certain\" confidence.\"\"\"\n return request.confidence == \"certain\" and not request.next_step_required\n\n def store_initial_issue(self, step_description: str):\n \"\"\"Store initial request for expert analysis.\"\"\"\n self.initial_request = step_description\n\n def should_include_files_in_expert_prompt(self) -> bool:\n \"\"\"Include files in expert analysis for comprehensive security audit.\"\"\"\n return True\n\n def should_embed_system_prompt(self) -> bool:\n \"\"\"Embed system prompt in expert analysis for proper context.\"\"\"\n return True\n\n def get_expert_thinking_mode(self) -> str:\n \"\"\"Use high thinking mode for thorough security analysis.\"\"\"\n return \"high\"\n\n def get_expert_analysis_instruction(self) -> str:\n \"\"\"Get specific instruction for security audit expert analysis.\"\"\"\n return (\n \"Please provide comprehensive security analysis based on the investigation findings. \"\n \"Focus on identifying any remaining vulnerabilities, validating the completeness of the analysis, \"\n \"and providing final recommendations for security improvements, following the OWASP-based \"\n \"format specified in the system prompt.\"\n )\n\n def get_completion_next_steps_message(self, expert_analysis_used: bool = False) -> str:\n \"\"\"\n Security audit-specific completion message.\n \"\"\"\n base_message = (\n \"SECURITY AUDIT IS COMPLETE. You MUST now summarize and present ALL security findings organized by \"\n \"severity (Critical β†’ High β†’ Medium β†’ Low), specific code locations with line numbers, and exact \"\n \"remediation steps for each vulnerability. Clearly prioritize the top 3 security issues that need \"\n \"immediate attention. Provide concrete, actionable guidance for each vulnerabilityβ€”make it easy for \"\n \"developers to understand exactly what needs to be fixed and how to implement the security improvements.\"\n )\n\n # Add expert analysis guidance only when expert analysis was actually used\n if expert_analysis_used:\n expert_guidance = self.get_expert_analysis_guidance()\n if expert_guidance:\n return f\"{base_message}\\n\\n{expert_guidance}\"\n\n return base_message\n\n def get_expert_analysis_guidance(self) -> str:\n \"\"\"\n Provide specific guidance for handling expert analysis in security audits.\n \"\"\"\n return (\n \"IMPORTANT: Analysis from an assistant model has been provided above. You MUST critically evaluate and validate \"\n \"the expert security findings rather than accepting them blindly. Cross-reference the expert analysis with \"\n \"your own investigation findings, verify that suggested security improvements are appropriate for this \"\n \"application's context and threat model, and ensure recommendations align with the project's security requirements. \"\n \"Present a synthesis that combines your systematic security review with validated expert insights, clearly \"\n \"distinguishing between vulnerabilities you've independently confirmed and additional insights from expert analysis.\"\n )\n\n def get_step_guidance_message(self, request) -> str:\n \"\"\"\n Security audit-specific step guidance with detailed investigation instructions.\n \"\"\"\n step_guidance = self.get_security_audit_step_guidance(request.step_number, request.confidence, request)\n return step_guidance[\"next_steps\"]\n\n def get_security_audit_step_guidance(self, step_number: int, confidence: str, request) -> dict[str, Any]:\n \"\"\"\n Provide step-specific guidance for security audit workflow.\n \"\"\"\n # Generate the next steps instruction based on required actions\n required_actions = self.get_required_actions(step_number, confidence, request.findings, request.total_steps)\n\n if step_number == 1:\n next_steps = (\n f\"MANDATORY: DO NOT call the {self.get_name()} tool again immediately. You MUST first examine \"\n f\"the code files thoroughly using appropriate tools. CRITICAL AWARENESS: You need to understand \"\n f\"the security landscape, identify potential vulnerabilities across OWASP Top 10 categories, \"\n f\"and look for authentication flaws, injection points, cryptographic issues, and authorization bypasses. \"\n f\"Use file reading tools, security analysis, and systematic examination to gather comprehensive information. \"\n f\"Only call {self.get_name()} again AFTER completing your security investigation. When you call \"\n f\"{self.get_name()} next time, use step_number: {step_number + 1} and report specific \"\n f\"files examined, vulnerabilities found, and security assessments discovered.\"\n )\n elif confidence in [\"exploring\", \"low\"]:\n next_steps = (\n f\"STOP! Do NOT call {self.get_name()} again yet. Based on your findings, you've identified areas that need \"\n f\"deeper security analysis. MANDATORY ACTIONS before calling {self.get_name()} step {step_number + 1}:\\n\"\n + \"\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\n\\nOnly call {self.get_name()} again with step_number: {step_number + 1} AFTER \"\n + \"completing these security audit tasks.\"\n )\n elif confidence in [\"medium\", \"high\"]:\n next_steps = (\n f\"WAIT! Your security audit needs final verification. DO NOT call {self.get_name()} immediately. REQUIRED ACTIONS:\\n\"\n + \"\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\n\\nREMEMBER: Ensure you have identified all significant vulnerabilities across all severity levels and \"\n f\"verified the completeness of your security review. Document findings with specific file references and \"\n f\"line numbers where applicable, then call {self.get_name()} with step_number: {step_number + 1}.\"\n )\n else:\n next_steps = (\n f\"PAUSE SECURITY AUDIT. Before calling {self.get_name()} step {step_number + 1}, you MUST examine more code thoroughly. \"\n + \"Required: \"\n + \", \".join(required_actions[:2])\n + \". \"\n + f\"Your next {self.get_name()} call (step_number: {step_number + 1}) must include \"\n f\"NEW evidence from actual security analysis, not just theories. NO recursive {self.get_name()} calls \"\n f\"without investigation work!\"\n )\n\n return {\"next_steps\": next_steps}\n\n def customize_workflow_response(self, response_data: dict, request) -> dict:\n \"\"\"\n Customize response to match security audit workflow format.\n \"\"\"\n # Store initial request on first step\n if request.step_number == 1:\n self.initial_request = request.step\n # Store security configuration for expert analysis\n if request.relevant_files:\n self.security_config = {\n \"relevant_files\": request.relevant_files,\n \"security_scope\": request.security_scope,\n \"threat_level\": request.threat_level,\n \"compliance_requirements\": request.compliance_requirements,\n \"audit_focus\": request.audit_focus,\n \"severity_filter\": request.severity_filter,\n }\n\n # Convert generic status names to security audit-specific ones\n tool_name = self.get_name()\n status_mapping = {\n f\"{tool_name}_in_progress\": \"security_audit_in_progress\",\n f\"pause_for_{tool_name}\": \"pause_for_security_audit\",\n f\"{tool_name}_required\": \"security_audit_required\",\n f\"{tool_name}_complete\": \"security_audit_complete\",\n }\n\n if response_data[\"status\"] in status_mapping:\n response_data[\"status\"] = status_mapping[response_data[\"status\"]]\n\n # Rename status field to match security audit workflow\n if f\"{tool_name}_status\" in response_data:\n response_data[\"security_audit_status\"] = response_data.pop(f\"{tool_name}_status\")\n # Add security audit-specific status fields\n response_data[\"security_audit_status\"][\"vulnerabilities_by_severity\"] = {}\n for issue in self.consolidated_findings.issues_found:\n severity = issue.get(\"severity\", \"unknown\")\n if severity not in response_data[\"security_audit_status\"][\"vulnerabilities_by_severity\"]:\n response_data[\"security_audit_status\"][\"vulnerabilities_by_severity\"][severity] = 0\n response_data[\"security_audit_status\"][\"vulnerabilities_by_severity\"][severity] += 1\n response_data[\"security_audit_status\"][\"audit_confidence\"] = self.get_request_confidence(request)\n\n # Map complete_secaudit to complete_security_audit\n if f\"complete_{tool_name}\" in response_data:\n response_data[\"complete_security_audit\"] = response_data.pop(f\"complete_{tool_name}\")\n\n # Map the completion flag to match security audit workflow\n if f\"{tool_name}_complete\" in response_data:\n response_data[\"security_audit_complete\"] = response_data.pop(f\"{tool_name}_complete\")\n\n return response_data\n\n # Override inheritance hooks for security audit-specific behavior\n\n def get_completion_status(self) -> str:\n \"\"\"Security audit tools use audit-specific status.\"\"\"\n return \"security_analysis_complete\"\n\n def get_completion_data_key(self) -> str:\n \"\"\"Security audit uses 'complete_security_audit' key.\"\"\"\n return \"complete_security_audit\"\n\n def get_final_analysis_from_request(self, request):\n \"\"\"Security audit tools use 'findings' field.\"\"\"\n return request.findings\n\n def get_confidence_level(self, request) -> str:\n \"\"\"Security audit tools use 'certain' for high confidence.\"\"\"\n return \"certain\"\n\n def get_completion_message(self) -> str:\n \"\"\"Security audit-specific completion message.\"\"\"\n return (\n \"Security audit complete with CERTAIN confidence. You have identified all significant vulnerabilities \"\n \"and provided comprehensive security analysis. MANDATORY: Present the user with the complete security audit results \"\n \"categorized by severity, and IMMEDIATELY proceed with implementing the highest priority security fixes \"\n \"or provide specific guidance for vulnerability remediation. Focus on actionable security recommendations.\"\n )\n\n def get_skip_reason(self) -> str:\n \"\"\"Security audit-specific skip reason.\"\"\"\n return \"Completed comprehensive security audit with full confidence locally\"\n\n def get_skip_expert_analysis_status(self) -> str:\n \"\"\"Security audit-specific expert analysis skip status.\"\"\"\n return \"skipped_due_to_certain_audit_confidence\"\n\n def prepare_work_summary(self) -> str:\n \"\"\"Security audit-specific work summary.\"\"\"\n return self._build_security_audit_summary(self.consolidated_findings)\n\n def get_request_model(self):\n \"\"\"Return the request model for this tool\"\"\"\n return SecauditRequest\n\n async def prepare_prompt(self, request: SecauditRequest) -> str:\n \"\"\"Not used - workflow tools use execute_workflow().\"\"\"\n return \"\" # Workflow tools use execute_workflow() directly\n" }, { "path": "tools/shared/__init__.py", "content": "\"\"\"\nShared infrastructure for PAL MCP tools.\n\nThis module contains the core base classes and utilities that are shared\nacross all tool types. It provides the foundation for the tool architecture.\n\"\"\"\n\nfrom .base_models import BaseWorkflowRequest, ConsolidatedFindings, ToolRequest, WorkflowRequest\nfrom .base_tool import BaseTool\nfrom .schema_builders import SchemaBuilder\n\n__all__ = [\n \"BaseTool\",\n \"ToolRequest\",\n \"BaseWorkflowRequest\",\n \"WorkflowRequest\",\n \"ConsolidatedFindings\",\n \"SchemaBuilder\",\n]\n" }, { "path": "tools/shared/base_models.py", "content": "\"\"\"\nBase models for PAL MCP tools.\n\nThis module contains the shared Pydantic models used across all tools,\nextracted to avoid circular imports and promote code reuse.\n\nKey Models:\n- ToolRequest: Base request model for all tools\n- WorkflowRequest: Extended request model for workflow-based tools\n- ConsolidatedFindings: Model for tracking workflow progress\n\"\"\"\n\nimport logging\nfrom typing import Optional\n\nfrom pydantic import BaseModel, Field, field_validator\n\nlogger = logging.getLogger(__name__)\n\n\n# Shared field descriptions to avoid duplication\nCOMMON_FIELD_DESCRIPTIONS = {\n \"model\": \"Model to run. Supply a name if requested by the user or stay in auto mode. When in auto mode, use `listmodels` tool for model discovery.\",\n \"temperature\": \"0 = deterministic Β· 1 = creative.\",\n \"thinking_mode\": \"Reasoning depth: minimal, low, medium, high, or max.\",\n \"continuation_id\": (\n \"Unique thread continuation ID for multi-turn conversations. Works across different tools. \"\n \"ALWAYS reuse the last continuation_id you were givenβ€”this preserves full conversation context, \"\n \"files, and findings so the agent can resume seamlessly.\"\n ),\n \"images\": \"Optional absolute image paths or base64 blobs for visual context.\",\n \"absolute_file_paths\": \"Full paths to relevant code\",\n}\n\n# Workflow-specific field descriptions\nWORKFLOW_FIELD_DESCRIPTIONS = {\n \"step\": \"Current work step content and findings from your overall work\",\n \"step_number\": \"Current step number in work sequence (starts at 1)\",\n \"total_steps\": \"Estimated total steps needed to complete work\",\n \"next_step_required\": \"Whether another work step is needed. When false, aim to reduce total_steps to match step_number to avoid mismatch.\",\n \"findings\": \"Important findings, evidence and insights discovered in this step\",\n \"files_checked\": \"List of files examined during this work step\",\n \"relevant_files\": \"Files identified as relevant to issue/goal (FULL absolute paths to real files/folders - DO NOT SHORTEN)\",\n \"relevant_context\": \"Methods/functions identified as involved in the issue\",\n \"issues_found\": \"Issues identified with severity levels during work\",\n \"confidence\": (\n \"Confidence level: exploring (just starting), low (early investigation), \"\n \"medium (some evidence), high (strong evidence), very_high (comprehensive understanding), \"\n \"almost_certain (near complete confidence), certain (100% confidence locally - no external validation needed)\"\n ),\n \"hypothesis\": \"Current theory about issue/goal based on work\",\n \"use_assistant_model\": (\n \"Use assistant model for expert analysis after workflow steps. \"\n \"False skips expert analysis, relies solely on your personal investigation. \"\n \"Defaults to True for comprehensive validation.\"\n ),\n}\n\n\nclass ToolRequest(BaseModel):\n \"\"\"\n Base request model for all PAL MCP tools.\n\n This model defines common fields that all tools accept, including\n model selection, temperature control, and conversation threading.\n Tool-specific request models should inherit from this class.\n \"\"\"\n\n # Model configuration\n model: Optional[str] = Field(None, description=COMMON_FIELD_DESCRIPTIONS[\"model\"])\n temperature: Optional[float] = Field(None, ge=0.0, le=1.0, description=COMMON_FIELD_DESCRIPTIONS[\"temperature\"])\n thinking_mode: Optional[str] = Field(None, description=COMMON_FIELD_DESCRIPTIONS[\"thinking_mode\"])\n\n # Conversation support\n continuation_id: Optional[str] = Field(None, description=COMMON_FIELD_DESCRIPTIONS[\"continuation_id\"])\n\n # Visual context\n images: Optional[list[str]] = Field(None, description=COMMON_FIELD_DESCRIPTIONS[\"images\"])\n\n\nclass BaseWorkflowRequest(ToolRequest):\n \"\"\"\n Minimal base request model for workflow tools.\n\n This provides only the essential fields that ALL workflow tools need,\n allowing for maximum flexibility in tool-specific implementations.\n \"\"\"\n\n # Core workflow fields that ALL workflow tools need\n step: str = Field(..., description=WORKFLOW_FIELD_DESCRIPTIONS[\"step\"])\n step_number: int = Field(..., ge=1, description=WORKFLOW_FIELD_DESCRIPTIONS[\"step_number\"])\n total_steps: int = Field(..., ge=1, description=WORKFLOW_FIELD_DESCRIPTIONS[\"total_steps\"])\n next_step_required: bool = Field(..., description=WORKFLOW_FIELD_DESCRIPTIONS[\"next_step_required\"])\n\n\nclass WorkflowRequest(BaseWorkflowRequest):\n \"\"\"\n Extended request model for workflow-based tools.\n\n This model extends ToolRequest with fields specific to the workflow\n pattern, where tools perform multi-step work with forced pauses between steps.\n\n Used by: debug, precommit, codereview, refactor, thinkdeep, analyze\n \"\"\"\n\n # Required workflow fields\n step: str = Field(..., description=WORKFLOW_FIELD_DESCRIPTIONS[\"step\"])\n step_number: int = Field(..., ge=1, description=WORKFLOW_FIELD_DESCRIPTIONS[\"step_number\"])\n total_steps: int = Field(..., ge=1, description=WORKFLOW_FIELD_DESCRIPTIONS[\"total_steps\"])\n next_step_required: bool = Field(..., description=WORKFLOW_FIELD_DESCRIPTIONS[\"next_step_required\"])\n\n # Work tracking fields\n findings: str = Field(..., description=WORKFLOW_FIELD_DESCRIPTIONS[\"findings\"])\n files_checked: list[str] = Field(default_factory=list, description=WORKFLOW_FIELD_DESCRIPTIONS[\"files_checked\"])\n relevant_files: list[str] = Field(default_factory=list, description=WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_files\"])\n relevant_context: list[str] = Field(\n default_factory=list, description=WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_context\"]\n )\n issues_found: list[dict] = Field(default_factory=list, description=WORKFLOW_FIELD_DESCRIPTIONS[\"issues_found\"])\n confidence: str = Field(\"low\", description=WORKFLOW_FIELD_DESCRIPTIONS[\"confidence\"])\n\n # Optional workflow fields\n hypothesis: Optional[str] = Field(None, description=WORKFLOW_FIELD_DESCRIPTIONS[\"hypothesis\"])\n use_assistant_model: Optional[bool] = Field(True, description=WORKFLOW_FIELD_DESCRIPTIONS[\"use_assistant_model\"])\n\n @field_validator(\"files_checked\", \"relevant_files\", \"relevant_context\", mode=\"before\")\n @classmethod\n def convert_string_to_list(cls, v):\n \"\"\"Convert string inputs to empty lists to handle malformed inputs gracefully.\"\"\"\n if isinstance(v, str):\n logger.warning(f\"Field received string '{v}' instead of list, converting to empty list\")\n return []\n return v\n\n\nclass ConsolidatedFindings(BaseModel):\n \"\"\"\n Model for tracking consolidated findings across workflow steps.\n\n This model accumulates findings, files, methods, and issues\n discovered during multi-step work. It's used by\n BaseWorkflowMixin to track progress across workflow steps.\n \"\"\"\n\n files_checked: set[str] = Field(default_factory=set, description=\"All files examined across all steps\")\n relevant_files: set[str] = Field(\n default_factory=set,\n description=\"Subset of files_checked identified as relevant for work at hand\",\n )\n relevant_context: set[str] = Field(\n default_factory=set, description=\"All methods/functions identified during overall work\"\n )\n findings: list[str] = Field(default_factory=list, description=\"Chronological findings from each work step\")\n hypotheses: list[dict] = Field(default_factory=list, description=\"Evolution of hypotheses across steps\")\n issues_found: list[dict] = Field(default_factory=list, description=\"All issues with severity levels\")\n images: list[str] = Field(default_factory=list, description=\"Images collected during work\")\n confidence: str = Field(\"low\", description=\"Latest confidence level from steps\")\n\n\n# Tool-specific field descriptions are now declared in each tool file\n# This keeps concerns separated and makes each tool self-contained\n" }, { "path": "tools/shared/base_tool.py", "content": "\"\"\"\nCore Tool Infrastructure for PAL MCP Tools\n\nThis module provides the fundamental base class for all tools:\n- BaseTool: Abstract base class defining the tool interface\n\nThe BaseTool class defines the core contract that tools must implement and provides\ncommon functionality for request validation, error handling, model management,\nconversation handling, file processing, and response formatting.\n\"\"\"\n\nimport logging\nimport os\nfrom abc import ABC, abstractmethod\nfrom typing import TYPE_CHECKING, Any, Optional\n\nfrom mcp.types import TextContent\n\nif TYPE_CHECKING:\n from providers.shared import ModelCapabilities\n from tools.models import ToolModelCategory\n\nfrom config import MCP_PROMPT_SIZE_LIMIT\nfrom providers import ModelProvider, ModelProviderRegistry\nfrom utils import estimate_tokens\nfrom utils.conversation_memory import (\n ConversationTurn,\n get_conversation_file_list,\n get_thread,\n)\nfrom utils.env import get_env\nfrom utils.file_utils import read_file_content, read_files\n\n# Import models from tools.models for compatibility\ntry:\n from tools.models import SPECIAL_STATUS_MODELS, ContinuationOffer, ToolOutput\nexcept ImportError:\n # Fallback in case models haven't been set up yet\n SPECIAL_STATUS_MODELS = {}\n ContinuationOffer = None\n ToolOutput = None\n\nlogger = logging.getLogger(__name__)\n\n\nclass BaseTool(ABC):\n \"\"\"\n Abstract base class for all PAL MCP tools.\n\n This class defines the interface that all tools must implement and provides\n common functionality for request handling, model creation, and response formatting.\n\n CONVERSATION-AWARE FILE PROCESSING:\n This base class implements the sophisticated dual prioritization strategy for\n conversation-aware file handling across all tools:\n\n 1. FILE DEDUPLICATION WITH NEWEST-FIRST PRIORITY:\n - When same file appears in multiple conversation turns, newest reference wins\n - Prevents redundant file embedding while preserving most recent file state\n - Cross-tool file tracking ensures consistent behavior across analyze β†’ codereview β†’ debug\n\n 2. CONVERSATION CONTEXT INTEGRATION:\n - All tools receive enhanced prompts with conversation history via reconstruct_thread_context()\n - File references from previous turns are preserved and accessible\n - Cross-tool knowledge transfer maintains full context without manual file re-specification\n\n 3. TOKEN-AWARE FILE EMBEDDING:\n - Respects model-specific token allocation budgets from ModelContext\n - Prioritizes conversation history, then newest files, then remaining content\n - Graceful degradation when token limits are approached\n\n 4. STATELESS-TO-STATEFUL BRIDGING:\n - Tools operate on stateless MCP requests but access full conversation state\n - Conversation memory automatically injected via continuation_id parameter\n - Enables natural AI-to-AI collaboration across tool boundaries\n\n To create a new tool:\n 1. Create a new class that inherits from BaseTool\n 2. Implement all abstract methods\n 3. Define a request model that inherits from ToolRequest\n 4. Register the tool in server.py's TOOLS dictionary\n \"\"\"\n\n # Class-level cache for OpenRouter registry to avoid multiple loads\n _openrouter_registry_cache = None\n _custom_registry_cache = None\n\n @classmethod\n def _get_openrouter_registry(cls):\n \"\"\"Get cached OpenRouter registry instance, creating if needed.\"\"\"\n # Use BaseTool class directly to ensure cache is shared across all subclasses\n if BaseTool._openrouter_registry_cache is None:\n from providers.registries.openrouter import OpenRouterModelRegistry\n\n BaseTool._openrouter_registry_cache = OpenRouterModelRegistry()\n logger.debug(\"Created cached OpenRouter registry instance\")\n return BaseTool._openrouter_registry_cache\n\n @classmethod\n def _get_custom_registry(cls):\n \"\"\"Get cached custom-endpoint registry instance.\"\"\"\n if BaseTool._custom_registry_cache is None:\n from providers.registries.custom import CustomEndpointModelRegistry\n\n BaseTool._custom_registry_cache = CustomEndpointModelRegistry()\n logger.debug(\"Created cached Custom registry instance\")\n return BaseTool._custom_registry_cache\n\n def __init__(self):\n # Cache tool metadata at initialization to avoid repeated calls\n self.name = self.get_name()\n self.description = self.get_description()\n self.default_temperature = self.get_default_temperature()\n # Tool initialization complete\n\n @abstractmethod\n def get_name(self) -> str:\n \"\"\"\n Return the unique name identifier for this tool.\n\n This name is used by MCP clients to invoke the tool and must be\n unique across all registered tools.\n\n Returns:\n str: The tool's unique name (e.g., \"review_code\", \"analyze\")\n \"\"\"\n pass\n\n @abstractmethod\n def get_description(self) -> str:\n \"\"\"\n Return a detailed description of what this tool does.\n\n This description is shown to MCP clients (like Claude / Codex / Gemini) to help them\n understand when and how to use the tool. It should be comprehensive\n and include trigger phrases.\n\n Returns:\n str: Detailed tool description with usage examples\n \"\"\"\n pass\n\n @abstractmethod\n def get_input_schema(self) -> dict[str, Any]:\n \"\"\"\n Return the JSON Schema that defines this tool's parameters.\n\n This schema is used by MCP clients to validate inputs before\n sending requests. It should match the tool's request model.\n\n Returns:\n Dict[str, Any]: JSON Schema object defining required and optional parameters\n \"\"\"\n pass\n\n @abstractmethod\n def get_system_prompt(self) -> str:\n \"\"\"\n Return the system prompt that configures the AI model's behavior.\n\n This prompt sets the context and instructions for how the model\n should approach the task. It's prepended to the user's request.\n\n Returns:\n str: System prompt with role definition and instructions\n \"\"\"\n pass\n\n def get_capability_system_prompts(self, capabilities: Optional[\"ModelCapabilities\"]) -> list[str]:\n \"\"\"Return additional system prompt snippets gated on model capabilities.\n\n Subclasses can override this hook to append capability-specific\n instructions (for example, enabling code-generation exports when a\n model advertises support). The default implementation returns an empty\n list so no extra instructions are appended.\n\n Args:\n capabilities: The resolved capabilities for the active model.\n\n Returns:\n List of prompt fragments to append after the base system prompt.\n \"\"\"\n\n return []\n\n def _augment_system_prompt_with_capabilities(\n self, base_prompt: str, capabilities: Optional[\"ModelCapabilities\"]\n ) -> str:\n \"\"\"Merge capability-driven prompt addenda with the base system prompt.\"\"\"\n\n additions: list[str] = []\n if capabilities is not None:\n additions = [fragment.strip() for fragment in self.get_capability_system_prompts(capabilities) if fragment]\n\n if not additions:\n return base_prompt\n\n addition_text = \"\\n\\n\".join(additions)\n if not base_prompt:\n return addition_text\n\n suffix = \"\" if base_prompt.endswith(\"\\n\\n\") else \"\\n\\n\"\n return f\"{base_prompt}{suffix}{addition_text}\"\n\n def get_annotations(self) -> Optional[dict[str, Any]]:\n \"\"\"\n Return optional annotations for this tool.\n\n Annotations provide hints about tool behavior without being security-critical.\n They help MCP clients make better decisions about tool usage.\n\n Returns:\n Optional[dict]: Dictionary with annotation fields like readOnlyHint, destructiveHint, etc.\n Returns None if no annotations are needed.\n \"\"\"\n return None\n\n def requires_model(self) -> bool:\n \"\"\"\n Return whether this tool requires AI model access.\n\n Tools that override execute() to do pure data processing (like planner)\n should return False to skip model resolution at the MCP boundary.\n\n Returns:\n bool: True if tool needs AI model access (default), False for data-only tools\n \"\"\"\n return True\n\n def is_effective_auto_mode(self) -> bool:\n \"\"\"\n Check if we're in effective auto mode for schema generation.\n\n This determines whether the model parameter should be required in the tool schema.\n Used at initialization time when schemas are generated.\n\n Returns:\n bool: True if model parameter should be required in the schema\n \"\"\"\n from config import DEFAULT_MODEL\n from providers.registry import ModelProviderRegistry\n\n # Case 1: Explicit auto mode\n if DEFAULT_MODEL.lower() == \"auto\":\n return True\n\n # Case 2: Model not available (fallback to auto mode)\n if DEFAULT_MODEL.lower() != \"auto\":\n provider = ModelProviderRegistry.get_provider_for_model(DEFAULT_MODEL)\n if not provider:\n return True\n\n return False\n\n def _should_require_model_selection(self, model_name: str) -> bool:\n \"\"\"\n Check if we should require the CLI to select a model at runtime.\n\n This is called during request execution to determine if we need\n to return an error asking the CLI to provide a model parameter.\n\n Args:\n model_name: The model name from the request or DEFAULT_MODEL\n\n Returns:\n bool: True if we should require model selection\n \"\"\"\n # Case 1: Model is explicitly \"auto\"\n if model_name.lower() == \"auto\":\n return True\n\n # Case 2: Requested model is not available\n from providers.registry import ModelProviderRegistry\n\n provider = ModelProviderRegistry.get_provider_for_model(model_name)\n if not provider:\n logger = logging.getLogger(f\"tools.{self.name}\")\n logger.warning(f\"Model '{model_name}' is not available with current API keys. Requiring model selection.\")\n return True\n\n return False\n\n def _get_available_models(self) -> list[str]:\n \"\"\"\n Get list of models available from enabled providers.\n\n Only returns models from providers that have valid API keys configured.\n This fixes the namespace collision bug where models from disabled providers\n were shown to the CLI, causing routing conflicts.\n\n Returns:\n List of model names from enabled providers only\n \"\"\"\n from providers.registry import ModelProviderRegistry\n\n # Get models from enabled providers only (those with valid API keys)\n all_models = ModelProviderRegistry.get_available_model_names()\n\n # Add OpenRouter models if OpenRouter is configured\n openrouter_key = get_env(\"OPENROUTER_API_KEY\")\n if openrouter_key and openrouter_key != \"your_openrouter_api_key_here\":\n try:\n registry = self._get_openrouter_registry()\n # Add all aliases from the registry (includes OpenRouter cloud models)\n for alias in registry.list_aliases():\n if alias not in all_models:\n all_models.append(alias)\n except Exception as e:\n import logging\n\n logging.debug(f\"Failed to add OpenRouter models to enum: {e}\")\n\n # Add custom models if custom API is configured\n custom_url = get_env(\"CUSTOM_API_URL\")\n if custom_url:\n try:\n registry = self._get_custom_registry()\n for alias in registry.list_aliases():\n if alias not in all_models:\n all_models.append(alias)\n except Exception as e:\n import logging\n\n logging.debug(f\"Failed to add custom models to enum: {e}\")\n\n # Remove duplicates while preserving order\n seen = set()\n unique_models = []\n for model in all_models:\n if model not in seen:\n seen.add(model)\n unique_models.append(model)\n\n return unique_models\n\n def _format_available_models_list(self) -> str:\n \"\"\"Return a human-friendly list of available models or guidance when none found.\"\"\"\n\n summaries, total, has_restrictions = self._get_ranked_model_summaries()\n if not summaries:\n return (\n \"No models detected. Configure provider credentials or set DEFAULT_MODEL to a valid option. \"\n \"If the user requested a specific model, respond with this notice instead of substituting another model.\"\n )\n display = \"; \".join(summaries)\n remainder = total - len(summaries)\n if remainder > 0:\n display = f\"{display}; +{remainder} more (use the `listmodels` tool for the full roster)\"\n return display\n\n @staticmethod\n def _format_context_window(tokens: int) -> Optional[str]:\n \"\"\"Convert a raw context window into a short display string.\"\"\"\n\n if not tokens or tokens <= 0:\n return None\n\n if tokens >= 1_000_000:\n if tokens % 1_000_000 == 0:\n return f\"{tokens // 1_000_000}M ctx\"\n return f\"{tokens / 1_000_000:.1f}M ctx\"\n\n if tokens >= 1_000:\n if tokens % 1_000 == 0:\n return f\"{tokens // 1_000}K ctx\"\n return f\"{tokens / 1_000:.1f}K ctx\"\n\n return f\"{tokens} ctx\"\n\n def _collect_ranked_capabilities(self) -> list[tuple[int, str, Any]]:\n \"\"\"Gather available model capabilities sorted by capability rank.\"\"\"\n\n from providers.registry import ModelProviderRegistry\n\n ranked: list[tuple[int, str, Any]] = []\n available = ModelProviderRegistry.get_available_models(respect_restrictions=True)\n\n for model_name, provider_type in available.items():\n provider = ModelProviderRegistry.get_provider(provider_type)\n if not provider:\n continue\n\n try:\n capabilities = provider.get_capabilities(model_name)\n except ValueError:\n continue\n\n rank = capabilities.get_effective_capability_rank()\n ranked.append((rank, model_name, capabilities))\n\n ranked.sort(key=lambda item: (-item[0], item[1]))\n return ranked\n\n @staticmethod\n def _normalize_model_identifier(name: str) -> str:\n \"\"\"Normalize model names for deduplication across providers.\"\"\"\n\n normalized = name.lower()\n if \":\" in normalized:\n normalized = normalized.split(\":\", 1)[0]\n if \"/\" in normalized:\n normalized = normalized.split(\"/\", 1)[-1]\n return normalized\n\n def _get_ranked_model_summaries(self, limit: int = 5) -> tuple[list[str], int, bool]:\n \"\"\"Return formatted, ranked model summaries and restriction status.\"\"\"\n\n ranked = self._collect_ranked_capabilities()\n\n # Build allowlist map (provider -> lowercase names) when restrictions are active\n allowed_map: dict[Any, set[str]] = {}\n try:\n from utils.model_restrictions import get_restriction_service\n\n restriction_service = get_restriction_service()\n if restriction_service:\n from providers.shared import ProviderType\n\n for provider_type in ProviderType:\n allowed = restriction_service.get_allowed_models(provider_type)\n if allowed:\n allowed_map[provider_type] = {name.lower() for name in allowed if name}\n except Exception:\n allowed_map = {}\n\n filtered: list[tuple[int, str, Any]] = []\n seen_normalized: set[str] = set()\n\n for rank, model_name, capabilities in ranked:\n canonical_name = getattr(capabilities, \"model_name\", model_name)\n canonical_lower = canonical_name.lower()\n alias_lower = model_name.lower()\n provider_type = getattr(capabilities, \"provider\", None)\n\n if allowed_map:\n if provider_type not in allowed_map:\n continue\n allowed_set = allowed_map[provider_type]\n if canonical_lower not in allowed_set and alias_lower not in allowed_set:\n continue\n\n normalized = self._normalize_model_identifier(canonical_name)\n if normalized in seen_normalized:\n continue\n\n seen_normalized.add(normalized)\n filtered.append((rank, canonical_name, capabilities))\n\n summaries: list[str] = []\n for rank, canonical_name, capabilities in filtered[:limit]:\n details: list[str] = []\n\n context_str = self._format_context_window(capabilities.context_window)\n if context_str:\n details.append(context_str)\n\n if capabilities.supports_extended_thinking:\n details.append(\"thinking\")\n\n if capabilities.allow_code_generation:\n details.append(\"code-gen\")\n\n base = f\"{canonical_name} (score {rank}\"\n if details:\n base = f\"{base}, {', '.join(details)}\"\n summaries.append(f\"{base})\")\n\n return summaries, len(filtered), bool(allowed_map)\n\n def _get_restriction_note(self) -> Optional[str]:\n \"\"\"Return a string describing active per-provider allowlists, if any.\"\"\"\n\n env_labels = {\n \"OPENAI_ALLOWED_MODELS\": \"OpenAI\",\n \"GOOGLE_ALLOWED_MODELS\": \"Google\",\n \"XAI_ALLOWED_MODELS\": \"X.AI\",\n \"OPENROUTER_ALLOWED_MODELS\": \"OpenRouter\",\n \"DIAL_ALLOWED_MODELS\": \"DIAL\",\n }\n\n notes: list[str] = []\n for env_var, label in env_labels.items():\n raw = get_env(env_var)\n if not raw:\n continue\n\n models = sorted({token.strip() for token in raw.split(\",\") if token.strip()})\n if not models:\n continue\n\n notes.append(f\"{label}: {', '.join(models)}\")\n\n if not notes:\n return None\n\n return \"Policy allows only β†’ \" + \"; \".join(notes)\n\n def _build_model_unavailable_message(self, model_name: str) -> str:\n \"\"\"Compose a consistent error message for unavailable model scenarios.\"\"\"\n\n tool_category = self.get_model_category()\n suggested_model = ModelProviderRegistry.get_preferred_fallback_model(tool_category)\n available_models_text = self._format_available_models_list()\n\n return (\n f\"Model '{model_name}' is not available with current API keys. \"\n f\"Available models: {available_models_text}. \"\n f\"Suggested model for {self.get_name()}: '{suggested_model}' \"\n f\"(category: {tool_category.value}). If the user explicitly requested a model, you MUST use that exact name or report this error backβ€”do not substitute another model.\"\n )\n\n def _build_auto_mode_required_message(self) -> str:\n \"\"\"Compose the auto-mode prompt when an explicit model selection is required.\"\"\"\n\n tool_category = self.get_model_category()\n suggested_model = ModelProviderRegistry.get_preferred_fallback_model(tool_category)\n available_models_text = self._format_available_models_list()\n\n return (\n \"Model parameter is required in auto mode. \"\n f\"Available models: {available_models_text}. \"\n f\"Suggested model for {self.get_name()}: '{suggested_model}' \"\n f\"(category: {tool_category.value}). When the user names a model, relay that exact nameβ€”never swap in another option.\"\n )\n\n def get_model_field_schema(self) -> dict[str, Any]:\n \"\"\"\n Generate the model field schema based on auto mode configuration.\n\n When auto mode is enabled, the model parameter becomes required\n and includes detailed descriptions of each model's capabilities.\n\n Returns:\n Dict containing the model field JSON schema\n \"\"\"\n\n from config import DEFAULT_MODEL\n\n # Use the centralized effective auto mode check\n if self.is_effective_auto_mode():\n description = (\n \"Currently in auto model selection mode. CRITICAL: When the user names a model, you MUST use that exact name unless the server rejects it. \"\n \"If no model is provided, you may use the `listmodels` tool to review options and select an appropriate match.\"\n )\n summaries, total, restricted = self._get_ranked_model_summaries()\n remainder = max(0, total - len(summaries))\n if summaries:\n top_line = \"; \".join(summaries)\n if remainder > 0:\n label = \"Allowed models\" if restricted else \"Top models\"\n top_line = f\"{label}: {top_line}; +{remainder} more via `listmodels`.\"\n else:\n label = \"Allowed models\" if restricted else \"Top models\"\n top_line = f\"{label}: {top_line}.\"\n description = f\"{description} {top_line}\"\n\n restriction_note = self._get_restriction_note()\n if restriction_note and (remainder > 0 or not summaries):\n description = f\"{description} {restriction_note}.\"\n return {\n \"type\": \"string\",\n \"description\": description,\n }\n\n description = (\n f\"The default model is '{DEFAULT_MODEL}'. Override only when the user explicitly requests a different model, and use that exact name. \"\n \"If the requested model fails validation, surface the server error instead of substituting another model. When unsure, use the `listmodels` tool for details.\"\n )\n summaries, total, restricted = self._get_ranked_model_summaries()\n remainder = max(0, total - len(summaries))\n if summaries:\n top_line = \"; \".join(summaries)\n if remainder > 0:\n label = \"Allowed models\" if restricted else \"Preferred alternatives\"\n top_line = f\"{label}: {top_line}; +{remainder} more via `listmodels`.\"\n else:\n label = \"Allowed models\" if restricted else \"Preferred alternatives\"\n top_line = f\"{label}: {top_line}.\"\n description = f\"{description} {top_line}\"\n\n restriction_note = self._get_restriction_note()\n if restriction_note and (remainder > 0 or not summaries):\n description = f\"{description} {restriction_note}.\"\n\n return {\n \"type\": \"string\",\n \"description\": description,\n }\n\n def get_default_temperature(self) -> float:\n \"\"\"\n Return the default temperature setting for this tool.\n\n Override this method to set tool-specific temperature defaults.\n Lower values (0.0-0.3) for analytical tasks, higher (0.7-1.0) for creative tasks.\n\n Returns:\n float: Default temperature between 0.0 and 1.0\n \"\"\"\n return 0.5\n\n def wants_line_numbers_by_default(self) -> bool:\n \"\"\"\n Return whether this tool wants line numbers added to code files by default.\n\n By default, ALL tools get line numbers for precise code references.\n Line numbers are essential for accurate communication about code locations.\n\n Returns:\n bool: True if line numbers should be added by default for this tool\n \"\"\"\n return True # All tools get line numbers by default for consistency\n\n def get_default_thinking_mode(self) -> str:\n \"\"\"\n Return the default thinking mode for this tool.\n\n Thinking mode controls computational budget for reasoning.\n Override for tools that need more or less reasoning depth.\n\n Returns:\n str: One of \"minimal\", \"low\", \"medium\", \"high\", \"max\"\n \"\"\"\n return \"medium\" # Default to medium thinking for better reasoning\n\n def get_model_category(self) -> \"ToolModelCategory\":\n \"\"\"\n Return the model category for this tool.\n\n Model category influences which model is selected in auto mode.\n Override to specify whether your tool needs extended reasoning,\n fast response, or balanced capabilities.\n\n Returns:\n ToolModelCategory: Category that influences model selection\n \"\"\"\n from tools.models import ToolModelCategory\n\n return ToolModelCategory.BALANCED\n\n @abstractmethod\n def get_request_model(self):\n \"\"\"\n Return the Pydantic model class used for validating requests.\n\n This model should inherit from ToolRequest and define all\n parameters specific to this tool.\n\n Returns:\n Type[ToolRequest]: The request model class\n \"\"\"\n pass\n\n def validate_file_paths(self, request) -> Optional[str]:\n \"\"\"\n Validate that all file paths in the request are absolute.\n\n This is a critical security function that prevents path traversal attacks\n and ensures all file access is properly controlled. All file paths must\n be absolute to avoid ambiguity and security issues.\n\n Args:\n request: The validated request object\n\n Returns:\n Optional[str]: Error message if validation fails, None if all paths are valid\n \"\"\"\n # Only validate files/paths if they exist in the request\n file_fields = [\n \"absolute_file_paths\",\n \"file\",\n \"path\",\n \"directory\",\n \"notebooks\",\n \"test_examples\",\n \"style_guide_examples\",\n \"files_checked\",\n \"relevant_files\",\n ]\n\n for field_name in file_fields:\n if hasattr(request, field_name):\n field_value = getattr(request, field_name)\n if field_value is None:\n continue\n\n # Handle both single paths and lists of paths\n paths_to_check = field_value if isinstance(field_value, list) else [field_value]\n\n for path in paths_to_check:\n if path and not os.path.isabs(path):\n return f\"All file paths must be FULL absolute paths. Invalid path: '{path}'\"\n\n return None\n\n def _validate_token_limit(self, content: str, content_type: str = \"Content\") -> None:\n \"\"\"\n Validate that user-provided content doesn't exceed the MCP prompt size limit.\n\n This enforcement is strictly for text crossing the MCP transport boundary\n (i.e., user input). Internal prompt construction may exceed this size and is\n governed by model-specific token limits.\n\n Args:\n content: The user-originated content to validate\n content_type: Description of the content type for error messages\n\n Raises:\n ValueError: If content exceeds the character size limit\n \"\"\"\n if not content:\n logger.debug(f\"{self.name} tool {content_type.lower()} validation skipped (no content)\")\n return\n\n char_count = len(content)\n if char_count > MCP_PROMPT_SIZE_LIMIT:\n token_estimate = estimate_tokens(content)\n error_msg = (\n f\"{char_count:,} characters (~{token_estimate:,} tokens). \"\n f\"Maximum is {MCP_PROMPT_SIZE_LIMIT:,} characters.\"\n )\n logger.error(f\"{self.name} tool {content_type.lower()} validation failed: {error_msg}\")\n raise ValueError(f\"{content_type} too large: {error_msg}\")\n\n token_estimate = estimate_tokens(content)\n logger.debug(\n f\"{self.name} tool {content_type.lower()} validation passed: \"\n f\"{char_count:,} characters (~{token_estimate:,} tokens)\"\n )\n\n def get_model_provider(self, model_name: str) -> ModelProvider:\n \"\"\"\n Get the appropriate model provider for the given model name.\n\n This method performs runtime validation to ensure the requested model\n is actually available with the current API key configuration.\n\n Args:\n model_name: Name of the model to get provider for\n\n Returns:\n ModelProvider: The provider instance for the model\n\n Raises:\n ValueError: If the model is not available or provider not found\n \"\"\"\n try:\n provider = ModelProviderRegistry.get_provider_for_model(model_name)\n if not provider:\n logger.error(f\"No provider found for model '{model_name}' in {self.name} tool\")\n raise ValueError(self._build_model_unavailable_message(model_name))\n\n return provider\n except Exception as e:\n logger.error(f\"Failed to get provider for model '{model_name}' in {self.name} tool: {e}\")\n raise\n\n # === CONVERSATION AND FILE HANDLING METHODS ===\n\n def get_conversation_embedded_files(self, continuation_id: Optional[str]) -> list[str]:\n \"\"\"\n Get list of files already embedded in conversation history.\n\n This method returns the list of files that have already been embedded\n in the conversation history for a given continuation thread. Tools can\n use this to avoid re-embedding files that are already available in the\n conversation context.\n\n Args:\n continuation_id: Thread continuation ID, or None for new conversations\n\n Returns:\n list[str]: List of file paths already embedded in conversation history\n \"\"\"\n if not continuation_id:\n # New conversation, no files embedded yet\n return []\n\n thread_context = get_thread(continuation_id)\n if not thread_context:\n # Thread not found, no files embedded\n return []\n\n embedded_files = get_conversation_file_list(thread_context)\n logger.debug(f\"[FILES] {self.name}: Found {len(embedded_files)} embedded files\")\n return embedded_files\n\n def filter_new_files(self, requested_files: list[str], continuation_id: Optional[str]) -> list[str]:\n \"\"\"\n Filter out files that are already embedded in conversation history.\n\n This method prevents duplicate file embeddings by filtering out files that have\n already been embedded in the conversation history. This optimizes token usage\n while ensuring tools still have logical access to all requested files through\n conversation history references.\n\n Args:\n requested_files: List of files requested for current tool execution\n continuation_id: Thread continuation ID, or None for new conversations\n\n Returns:\n list[str]: List of files that need to be embedded (not already in history)\n \"\"\"\n logger.debug(f\"[FILES] {self.name}: Filtering {len(requested_files)} requested files\")\n\n if not continuation_id:\n # New conversation, all files are new\n logger.debug(f\"[FILES] {self.name}: New conversation, all {len(requested_files)} files are new\")\n return requested_files\n\n try:\n embedded_files = set(self.get_conversation_embedded_files(continuation_id))\n logger.debug(f\"[FILES] {self.name}: Found {len(embedded_files)} embedded files in conversation\")\n\n # Safety check: If no files are marked as embedded but we have a continuation_id,\n # this might indicate an issue with conversation history. Be conservative.\n if not embedded_files:\n logger.debug(f\"{self.name} tool: No files found in conversation history for thread {continuation_id}\")\n logger.debug(\n f\"[FILES] {self.name}: No embedded files found, returning all {len(requested_files)} requested files\"\n )\n return requested_files\n\n # Return only files that haven't been embedded yet\n new_files = [f for f in requested_files if f not in embedded_files]\n logger.debug(\n f\"[FILES] {self.name}: After filtering: {len(new_files)} new files, {len(requested_files) - len(new_files)} already embedded\"\n )\n logger.debug(f\"[FILES] {self.name}: New files to embed: {new_files}\")\n\n # Log filtering results for debugging\n if len(new_files) < len(requested_files):\n skipped = [f for f in requested_files if f in embedded_files]\n logger.debug(\n f\"{self.name} tool: Filtering {len(skipped)} files already in conversation history: {', '.join(skipped)}\"\n )\n logger.debug(f\"[FILES] {self.name}: Skipped (already embedded): {skipped}\")\n\n return new_files\n\n except Exception as e:\n # If there's any issue with conversation history lookup, be conservative\n # and include all files rather than risk losing access to needed files\n logger.warning(f\"{self.name} tool: Error checking conversation history for {continuation_id}: {e}\")\n logger.warning(f\"{self.name} tool: Including all requested files as fallback\")\n logger.debug(\n f\"[FILES] {self.name}: Exception in filter_new_files, returning all {len(requested_files)} files as fallback\"\n )\n return requested_files\n\n def format_conversation_turn(self, turn: ConversationTurn) -> list[str]:\n \"\"\"\n Format a conversation turn for display in conversation history.\n\n Tools can override this to provide custom formatting for their responses\n while maintaining the standard structure for cross-tool compatibility.\n\n This method is called by build_conversation_history when reconstructing\n conversation context, allowing each tool to control how its responses\n appear in subsequent conversation turns.\n\n Args:\n turn: The conversation turn to format (from utils.conversation_memory)\n\n Returns:\n list[str]: Lines of formatted content for this turn\n\n Example:\n Default implementation returns:\n [\"Files used in this turn: file1.py, file2.py\", \"\", \"Response content...\"]\n\n Tools can override to add custom sections, formatting, or metadata display.\n \"\"\"\n parts = []\n\n # Add files context if present\n if turn.files:\n parts.append(f\"Files used in this turn: {', '.join(turn.files)}\")\n parts.append(\"\") # Empty line for readability\n\n # Add the actual content\n parts.append(turn.content)\n\n return parts\n\n def handle_prompt_file(self, files: Optional[list[str]]) -> tuple[Optional[str], Optional[list[str]]]:\n \"\"\"\n Check for and handle prompt.txt in the absolute file paths list.\n\n If prompt.txt is found, reads its content and removes it from the files list.\n This file is treated specially as the main prompt, not as an embedded file.\n\n This mechanism allows us to work around MCP's ~25K token limit by having\n the CLI save large prompts to a file, effectively using the file transfer\n mechanism to bypass token constraints while preserving response capacity.\n\n Args:\n files: List of absolute file paths (will be translated for current environment)\n\n Returns:\n tuple: (prompt_content, updated_files_list)\n \"\"\"\n if not files:\n return None, files\n\n prompt_content = None\n updated_files = []\n\n for file_path in files:\n\n # Check if the filename is exactly \"prompt.txt\"\n # This ensures we don't match files like \"myprompt.txt\" or \"prompt.txt.bak\"\n if os.path.basename(file_path) == \"prompt.txt\":\n try:\n # Read prompt.txt content and extract just the text\n content, _ = read_file_content(file_path)\n # Extract the content between the file markers\n if \"--- BEGIN FILE:\" in content and \"--- END FILE:\" in content:\n lines = content.split(\"\\n\")\n in_content = False\n content_lines = []\n for line in lines:\n if line.startswith(\"--- BEGIN FILE:\"):\n in_content = True\n continue\n elif line.startswith(\"--- END FILE:\"):\n break\n elif in_content:\n content_lines.append(line)\n prompt_content = \"\\n\".join(content_lines)\n else:\n # Fallback: if it's already raw content (from tests or direct input)\n # and doesn't have error markers, use it directly\n if not content.startswith(\"\\n--- ERROR\"):\n prompt_content = content\n else:\n prompt_content = None\n except Exception:\n # If we can't read the file, we'll just skip it\n # The error will be handled elsewhere\n pass\n else:\n # Keep the original path in the files list (will be translated later by read_files)\n updated_files.append(file_path)\n\n return prompt_content, updated_files if updated_files else None\n\n def get_prompt_content_for_size_validation(self, user_content: str) -> str:\n \"\"\"\n Get the content that should be validated for MCP prompt size limits.\n\n This hook method allows tools to specify what content should be checked\n against the MCP transport size limit. By default, it returns the user content,\n but can be overridden to exclude conversation history when needed.\n\n Args:\n user_content: The user content that would normally be validated\n\n Returns:\n The content that should actually be validated for size limits\n \"\"\"\n # Default implementation: validate the full user content\n return user_content\n\n def check_prompt_size(self, text: str) -> Optional[dict[str, Any]]:\n \"\"\"\n Check if USER INPUT text is too large for MCP transport boundary.\n\n IMPORTANT: This method should ONLY be used to validate user input that crosses\n the CLI ↔ MCP Server transport boundary. It should NOT be used to limit\n internal MCP Server operations.\n\n Args:\n text: The user input text to check (NOT internal prompt content)\n\n Returns:\n Optional[Dict[str, Any]]: Response asking for file handling if too large, None otherwise\n \"\"\"\n if text and len(text) > MCP_PROMPT_SIZE_LIMIT:\n return {\n \"status\": \"resend_prompt\",\n \"content\": (\n f\"MANDATORY ACTION REQUIRED: The prompt is too large for MCP's token limits (>{MCP_PROMPT_SIZE_LIMIT:,} characters). \"\n \"YOU MUST IMMEDIATELY save the prompt text to a temporary file named 'prompt.txt' in the working directory. \"\n \"DO NOT attempt to shorten or modify the prompt. SAVE IT AS-IS to 'prompt.txt'. \"\n \"Then resend the request, passing the absolute file path to 'prompt.txt' as part of the tool call, \"\n \"along with any other files you wish to share as context. Leave the prompt text itself empty or very brief in the new request. \"\n \"This is the ONLY way to handle large prompts - you MUST follow these exact steps.\"\n ),\n \"content_type\": \"text\",\n \"metadata\": {\n \"prompt_size\": len(text),\n \"limit\": MCP_PROMPT_SIZE_LIMIT,\n \"instructions\": \"MANDATORY: Save prompt to 'prompt.txt' in current folder and provide full path when recalling this tool.\",\n },\n }\n return None\n\n def _prepare_file_content_for_prompt(\n self,\n request_files: list[str],\n continuation_id: Optional[str],\n context_description: str = \"New files\",\n max_tokens: Optional[int] = None,\n reserve_tokens: int = 1_000,\n remaining_budget: Optional[int] = None,\n arguments: Optional[dict] = None,\n model_context: Optional[Any] = None,\n ) -> tuple[str, list[str]]:\n \"\"\"\n Centralized file processing implementing dual prioritization strategy.\n\n This method is the heart of conversation-aware file processing across all tools.\n\n Args:\n request_files: List of files requested for current tool execution\n continuation_id: Thread continuation ID, or None for new conversations\n context_description: Description for token limit validation (e.g. \"Code\", \"New files\")\n max_tokens: Maximum tokens to use (defaults to remaining budget or model-specific content allocation)\n reserve_tokens: Tokens to reserve for additional prompt content (default 1K)\n remaining_budget: Remaining token budget after conversation history (from server.py)\n arguments: Original tool arguments (used to extract _remaining_tokens if available)\n model_context: Model context object with all model information including token allocation\n\n Returns:\n tuple[str, list[str]]: (formatted_file_content, actually_processed_files)\n - formatted_file_content: Formatted file content string ready for prompt inclusion\n - actually_processed_files: List of individual file paths that were actually read and embedded\n (directories are expanded to individual files)\n \"\"\"\n if not request_files:\n return \"\", []\n\n # Extract remaining budget from arguments if available\n if remaining_budget is None:\n # Use provided arguments or fall back to stored arguments from execute()\n args_to_use = arguments or getattr(self, \"_current_arguments\", {})\n remaining_budget = args_to_use.get(\"_remaining_tokens\")\n\n # Use remaining budget if provided, otherwise fall back to max_tokens or model-specific default\n if remaining_budget is not None:\n effective_max_tokens = remaining_budget - reserve_tokens\n elif max_tokens is not None:\n effective_max_tokens = max_tokens - reserve_tokens\n else:\n # Use model_context for token allocation\n if not model_context:\n # Try to get from stored attributes as fallback\n model_context = getattr(self, \"_model_context\", None)\n if not model_context:\n logger.error(\n f\"[FILES] {self.name}: _prepare_file_content_for_prompt called without model_context. \"\n \"This indicates an incorrect call sequence in the tool's implementation.\"\n )\n raise RuntimeError(\"Model context not provided for file preparation.\")\n\n # This is now the single source of truth for token allocation.\n try:\n token_allocation = model_context.calculate_token_allocation()\n # Standardize on `file_tokens` for consistency and correctness.\n effective_max_tokens = token_allocation.file_tokens - reserve_tokens\n logger.debug(\n f\"[FILES] {self.name}: Using model context for {model_context.model_name}: \"\n f\"{token_allocation.file_tokens:,} file tokens from {token_allocation.total_tokens:,} total\"\n )\n except Exception as e:\n logger.error(\n f\"[FILES] {self.name}: Failed to calculate token allocation from model context: {e}\", exc_info=True\n )\n # If the context exists but calculation fails, we still need to prevent a crash.\n # A loud error is logged, and we fall back to a safe default.\n effective_max_tokens = 100_000 - reserve_tokens\n\n # Ensure we have a reasonable minimum budget\n effective_max_tokens = max(1000, effective_max_tokens)\n\n files_to_embed = self.filter_new_files(request_files, continuation_id)\n logger.debug(f\"[FILES] {self.name}: Will embed {len(files_to_embed)} files after filtering\")\n\n # Log the specific files for debugging/testing\n if files_to_embed:\n logger.info(\n f\"[FILE_PROCESSING] {self.name} tool will embed new files: {', '.join([os.path.basename(f) for f in files_to_embed])}\"\n )\n else:\n logger.info(\n f\"[FILE_PROCESSING] {self.name} tool: No new files to embed (all files already in conversation history)\"\n )\n\n content_parts = []\n actually_processed_files = []\n\n # Read content of new files only\n if files_to_embed:\n logger.debug(f\"{self.name} tool embedding {len(files_to_embed)} new files: {', '.join(files_to_embed)}\")\n logger.debug(\n f\"[FILES] {self.name}: Starting file embedding with token budget {effective_max_tokens + reserve_tokens:,}\"\n )\n try:\n # Before calling read_files, expand directories to get individual file paths\n from utils.file_utils import expand_paths\n\n expanded_files = expand_paths(files_to_embed)\n logger.debug(\n f\"[FILES] {self.name}: Expanded {len(files_to_embed)} paths to {len(expanded_files)} individual files\"\n )\n\n file_content = read_files(\n files_to_embed,\n max_tokens=effective_max_tokens + reserve_tokens,\n reserve_tokens=reserve_tokens,\n include_line_numbers=self.wants_line_numbers_by_default(),\n )\n # Note: No need to validate against MCP_PROMPT_SIZE_LIMIT here\n # read_files already handles token-aware truncation based on model's capabilities\n content_parts.append(file_content)\n\n # Track the expanded files as actually processed\n actually_processed_files.extend(expanded_files)\n\n # Estimate tokens for debug logging\n from utils.token_utils import estimate_tokens\n\n content_tokens = estimate_tokens(file_content)\n logger.debug(\n f\"{self.name} tool successfully embedded {len(files_to_embed)} files ({content_tokens:,} tokens)\"\n )\n logger.debug(f\"[FILES] {self.name}: Successfully embedded files - {content_tokens:,} tokens used\")\n logger.debug(\n f\"[FILES] {self.name}: Actually processed {len(actually_processed_files)} individual files\"\n )\n except Exception as e:\n logger.error(f\"{self.name} tool failed to embed files {files_to_embed}: {type(e).__name__}: {e}\")\n logger.debug(f\"[FILES] {self.name}: File embedding failed - {type(e).__name__}: {e}\")\n raise\n else:\n logger.debug(f\"[FILES] {self.name}: No files to embed after filtering\")\n\n # Generate note about files already in conversation history\n if continuation_id and len(files_to_embed) < len(request_files):\n embedded_files = self.get_conversation_embedded_files(continuation_id)\n skipped_files = [f for f in request_files if f in embedded_files]\n if skipped_files:\n logger.debug(\n f\"{self.name} tool skipping {len(skipped_files)} files already in conversation history: {', '.join(skipped_files)}\"\n )\n logger.debug(f\"[FILES] {self.name}: Adding note about {len(skipped_files)} skipped files\")\n if content_parts:\n content_parts.append(\"\\n\\n\")\n note_lines = [\n \"--- NOTE: Additional files referenced in conversation history ---\",\n \"The following files are already available in our conversation context:\",\n \"\\n\".join(f\" - {f}\" for f in skipped_files),\n \"--- END NOTE ---\",\n ]\n content_parts.append(\"\\n\".join(note_lines))\n else:\n logger.debug(f\"[FILES] {self.name}: No skipped files to note\")\n\n result = \"\".join(content_parts) if content_parts else \"\"\n logger.debug(\n f\"[FILES] {self.name}: _prepare_file_content_for_prompt returning {len(result)} chars, {len(actually_processed_files)} processed files\"\n )\n return result, actually_processed_files\n\n def get_websearch_instruction(self, tool_specific: Optional[str] = None) -> str:\n \"\"\"\n Generate standardized web search instruction.\n\n Args:\n tool_specific: Optional tool-specific search guidance\n\n Returns:\n str: Web search instruction to append to prompt\n \"\"\"\n\n base_instruction = \"\"\"\n\nWEB SEARCH CAPABILITY: You can request the calling agent to perform web searches to enhance your analysis with current information!\n\nIMPORTANT: When you identify areas where web searches would significantly improve your response (such as checking current documentation, finding recent solutions, verifying best practices, or gathering community insights), you MUST explicitly instruct the agent to perform specific web searches and then respond back using the continuation_id from this response to continue the analysis.\n\nUse clear, direct language based on the value of the search:\n\nFor valuable supplementary information: \"Please perform a web search on '[specific topic/query]' and then continue this analysis using the continuation_id from this response if you find relevant information.\"\n\nFor important missing information: \"Please search for '[specific topic/query]' and respond back with the findings using the continuation_id from this response - this information is needed to provide a complete analysis.\"\n\nFor critical/essential information: \"SEARCH REQUIRED: Please immediately perform a web search on '[specific topic/query]' and respond back with the results using the continuation_id from this response. Cannot provide accurate analysis without this current information.\"\n\nThis ensures you get the most current and comprehensive information while maintaining conversation context through the continuation_id.\"\"\"\n\n if tool_specific:\n return f\"\"\"{base_instruction}\n\n{tool_specific}\n\nWhen recommending searches, be specific about what information you need and why it would improve your analysis.\"\"\"\n\n # Default instruction for all tools\n return f\"\"\"{base_instruction}\n\nConsider requesting searches for:\n- Current documentation and API references\n- Recent best practices and patterns\n- Known issues and community solutions\n- Framework updates and compatibility\n- Security advisories and patches\n- Performance benchmarks and optimizations\n\nWhen recommending searches, be specific about what information you need and why it would improve your analysis. Always remember to instruct agent to use the continuation_id from this response when providing search results.\"\"\"\n\n def get_language_instruction(self) -> str:\n \"\"\"\n Generate language instruction based on LOCALE configuration.\n\n Returns:\n str: Language instruction to prepend to prompt, or empty string if\n no locale set\n \"\"\"\n # Read LOCALE directly from environment to support dynamic changes\n # Tests can monkeypatch LOCALE via the environment helper (or .env when override is enforced)\n\n locale = (get_env(\"LOCALE\", \"\") or \"\").strip()\n\n if not locale:\n return \"\"\n\n # Simple language instruction\n return f\"Always respond in {locale}.\\n\\n\"\n\n # === ABSTRACT METHODS FOR SIMPLE TOOLS ===\n\n @abstractmethod\n async def prepare_prompt(self, request) -> str:\n \"\"\"\n Prepare the complete prompt for the AI model.\n\n This method should construct the full prompt by combining:\n - System prompt from get_system_prompt()\n - File content from _prepare_file_content_for_prompt()\n - Conversation history from reconstruct_thread_context()\n - User's request and any tool-specific context\n\n Args:\n request: The validated request object\n\n Returns:\n str: Complete prompt ready for the AI model\n \"\"\"\n pass\n\n def format_response(self, response: str, request, model_info: dict = None) -> str:\n \"\"\"\n Format the AI model's response for the user.\n\n This method allows tools to post-process the model's response,\n adding structure, validation, or additional context.\n\n The default implementation returns the response unchanged.\n Tools can override this method to add custom formatting.\n\n Args:\n response: Raw response from the AI model\n request: The original request object\n model_info: Optional model information and metadata\n\n Returns:\n str: Formatted response ready for the user\n \"\"\"\n return response\n\n # === IMPLEMENTATION METHODS ===\n # These will be provided in a full implementation but are inherited from current base.py\n # for now to maintain compatibility.\n\n async def execute(self, arguments: dict[str, Any]) -> list[TextContent]:\n \"\"\"Execute the tool - will be inherited from existing base.py for now.\"\"\"\n # This will be implemented by importing from the current base.py\n # for backward compatibility during the migration\n raise NotImplementedError(\"Subclasses must implement execute method\")\n\n def _should_require_model_selection(self, model_name: str) -> bool:\n \"\"\"\n Check if we should require the CLI to select a model at runtime.\n\n This is called during request execution to determine if we need\n to return an error asking the CLI to provide a model parameter.\n\n Args:\n model_name: The model name from the request or DEFAULT_MODEL\n\n Returns:\n bool: True if we should require model selection\n \"\"\"\n # Case 1: Model is explicitly \"auto\"\n if model_name.lower() == \"auto\":\n return True\n\n # Case 2: Requested model is not available\n from providers.registry import ModelProviderRegistry\n\n provider = ModelProviderRegistry.get_provider_for_model(model_name)\n if not provider:\n logger.warning(f\"Model '{model_name}' is not available with current API keys. Requiring model selection.\")\n return True\n\n return False\n\n def _get_available_models(self) -> list[str]:\n \"\"\"\n Get list of models available from enabled providers.\n\n Only returns models from providers that have valid API keys configured.\n This fixes the namespace collision bug where models from disabled providers\n were shown to the CLI, causing routing conflicts.\n\n Returns:\n List of model names from enabled providers only\n \"\"\"\n from providers.registry import ModelProviderRegistry\n\n # Get models from enabled providers only (those with valid API keys)\n all_models = ModelProviderRegistry.get_available_model_names()\n\n # Add OpenRouter models and their aliases when OpenRouter is configured\n openrouter_key = get_env(\"OPENROUTER_API_KEY\")\n if openrouter_key and openrouter_key != \"your_openrouter_api_key_here\":\n try:\n registry = self._get_openrouter_registry()\n\n for alias in registry.list_aliases():\n if alias not in all_models:\n all_models.append(alias)\n except Exception as exc: # pragma: no cover - logged for observability\n import logging\n\n logging.debug(f\"Failed to add OpenRouter models to enum: {exc}\")\n\n # Add custom models (and their aliases) when a custom endpoint is available\n custom_url = get_env(\"CUSTOM_API_URL\")\n if custom_url:\n try:\n registry = self._get_custom_registry()\n for alias in registry.list_aliases():\n if alias not in all_models:\n all_models.append(alias)\n except Exception as exc: # pragma: no cover - logged for observability\n import logging\n\n logging.debug(f\"Failed to add custom models to enum: {exc}\")\n\n # Remove duplicates while preserving insertion order\n seen: set[str] = set()\n unique_models: list[str] = []\n for model in all_models:\n if model not in seen:\n seen.add(model)\n unique_models.append(model)\n\n return unique_models\n\n def _resolve_model_context(self, arguments: dict, request) -> tuple[str, Any]:\n \"\"\"\n Resolve model context and name using centralized logic.\n\n This method extracts the model resolution logic from execute() so it can be\n reused by tools that override execute() (like debug tool) without duplicating code.\n\n Args:\n arguments: Dictionary of arguments from the MCP client\n request: The validated request object\n\n Returns:\n tuple[str, ModelContext]: (resolved_model_name, model_context)\n\n Raises:\n ValueError: If model resolution fails or model selection is required\n \"\"\"\n # MODEL RESOLUTION NOW HAPPENS AT MCP BOUNDARY\n # Extract pre-resolved model context from server.py\n model_context = arguments.get(\"_model_context\")\n resolved_model_name = arguments.get(\"_resolved_model_name\")\n\n if model_context and resolved_model_name:\n # Model was already resolved at MCP boundary\n model_name = resolved_model_name\n logger.debug(f\"Using pre-resolved model '{model_name}' from MCP boundary\")\n else:\n # Fallback for direct execute calls\n model_name = getattr(request, \"model\", None)\n if not model_name:\n from config import DEFAULT_MODEL\n\n model_name = DEFAULT_MODEL\n logger.debug(f\"Using fallback model resolution for '{model_name}' (test mode)\")\n\n # For tests: Check if we should require model selection (auto mode)\n if self._should_require_model_selection(model_name):\n # Build error message based on why selection is required\n if model_name.lower() == \"auto\":\n error_message = self._build_auto_mode_required_message()\n else:\n error_message = self._build_model_unavailable_message(model_name)\n raise ValueError(error_message)\n\n # Create model context for tests\n from utils.model_context import ModelContext\n\n model_context = ModelContext(model_name)\n\n return model_name, model_context\n\n def validate_and_correct_temperature(self, temperature: float, model_context: Any) -> tuple[float, list[str]]:\n \"\"\"\n Validate and correct temperature for the specified model.\n\n This method ensures that the temperature value is within the valid range\n for the specific model being used. Different models have different temperature\n constraints (e.g., o1 models require temperature=1.0, GPT models support 0-2).\n\n Args:\n temperature: Temperature value to validate\n model_context: Model context object containing model name, provider, and capabilities\n\n Returns:\n Tuple of (corrected_temperature, warning_messages)\n \"\"\"\n try:\n # Use model context capabilities directly - clean OOP approach\n capabilities = model_context.capabilities\n constraint = capabilities.temperature_constraint\n\n warnings = []\n if not constraint.validate(temperature):\n corrected = constraint.get_corrected_value(temperature)\n warning = (\n f\"Temperature {temperature} invalid for {model_context.model_name}. \"\n f\"{constraint.get_description()}. Using {corrected} instead.\"\n )\n warnings.append(warning)\n return corrected, warnings\n\n return temperature, warnings\n\n except Exception as e:\n # If validation fails for any reason, use the original temperature\n # and log a warning (but don't fail the request)\n logger.warning(f\"Temperature validation failed for {model_context.model_name}: {e}\")\n return temperature, [f\"Temperature validation failed: {e}\"]\n\n def _validate_image_limits(\n self, images: Optional[list[str]], model_context: Optional[Any] = None, continuation_id: Optional[str] = None\n ) -> Optional[dict]:\n \"\"\"\n Validate image size and count against model capabilities.\n\n This performs strict validation to ensure we don't exceed model-specific\n image limits. Uses capability-based validation with actual model\n configuration rather than hard-coded limits.\n\n Args:\n images: List of image paths/data URLs to validate\n model_context: Model context object containing model name, provider, and capabilities\n continuation_id: Optional continuation ID for conversation context\n\n Returns:\n Optional[dict]: Error response if validation fails, None if valid\n \"\"\"\n if not images:\n return None\n\n # Import here to avoid circular imports\n import base64\n from pathlib import Path\n\n if not model_context:\n # Get from tool's stored context as fallback\n model_context = getattr(self, \"_model_context\", None)\n if not model_context:\n logger.warning(\"No model context available for image validation\")\n return None\n\n try:\n # Use model context capabilities directly - clean OOP approach\n capabilities = model_context.capabilities\n model_name = model_context.model_name\n except Exception as e:\n logger.warning(f\"Failed to get capabilities from model_context for image validation: {e}\")\n # Generic error response when capabilities cannot be accessed\n model_name = getattr(model_context, \"model_name\", \"unknown\")\n return {\n \"status\": \"error\",\n \"content\": self._build_model_unavailable_message(model_name),\n \"content_type\": \"text\",\n \"metadata\": {\n \"error_type\": \"validation_error\",\n \"model_name\": model_name,\n \"supports_images\": None, # Unknown since model capabilities unavailable\n \"image_count\": len(images) if images else 0,\n },\n }\n\n # Check if model supports images\n if not capabilities.supports_images:\n return {\n \"status\": \"error\",\n \"content\": (\n f\"Image support not available: Model '{model_name}' does not support image processing. \"\n f\"Please use a vision-capable model such as 'gemini-2.5-flash', 'o3', \"\n f\"or 'claude-opus-4.1' for image analysis tasks.\"\n ),\n \"content_type\": \"text\",\n \"metadata\": {\n \"error_type\": \"validation_error\",\n \"model_name\": model_name,\n \"supports_images\": False,\n \"image_count\": len(images),\n },\n }\n\n # Get model image limits from capabilities\n max_images = 5 # Default max number of images\n max_size_mb = capabilities.max_image_size_mb\n\n # Check image count\n if len(images) > max_images:\n return {\n \"status\": \"error\",\n \"content\": (\n f\"Too many images: Model '{model_name}' supports a maximum of {max_images} images, \"\n f\"but {len(images)} were provided. Please reduce the number of images.\"\n ),\n \"content_type\": \"text\",\n \"metadata\": {\n \"error_type\": \"validation_error\",\n \"model_name\": model_name,\n \"image_count\": len(images),\n \"max_images\": max_images,\n },\n }\n\n # Calculate total size of all images\n total_size_mb = 0.0\n for image_path in images:\n try:\n if image_path.startswith(\"data:image/\"):\n # Handle data URL: data:image/png;base64,iVBORw0...\n _, data = image_path.split(\",\", 1)\n # Base64 encoding increases size by ~33%, so decode to get actual size\n actual_size = len(base64.b64decode(data))\n total_size_mb += actual_size / (1024 * 1024)\n else:\n # Handle file path\n path = Path(image_path)\n if path.exists():\n file_size = path.stat().st_size\n total_size_mb += file_size / (1024 * 1024)\n else:\n logger.warning(f\"Image file not found: {image_path}\")\n # Assume a reasonable size for missing files to avoid breaking validation\n total_size_mb += 1.0 # 1MB assumption\n except Exception as e:\n logger.warning(f\"Failed to get size for image {image_path}: {e}\")\n # Assume a reasonable size for problematic files\n total_size_mb += 1.0 # 1MB assumption\n\n # Apply 40MB cap for custom models if needed\n effective_limit_mb = max_size_mb\n try:\n from providers.shared import ProviderType\n\n # ModelCapabilities dataclass has provider field defined\n if capabilities.provider == ProviderType.CUSTOM:\n effective_limit_mb = min(max_size_mb, 40.0)\n except Exception:\n pass\n\n # Validate against size limit\n if total_size_mb > effective_limit_mb:\n return {\n \"status\": \"error\",\n \"content\": (\n f\"Image size limit exceeded: Model '{model_name}' supports maximum {effective_limit_mb:.1f}MB \"\n f\"for all images combined, but {total_size_mb:.1f}MB was provided. \"\n f\"Please reduce image sizes or count and try again.\"\n ),\n \"content_type\": \"text\",\n \"metadata\": {\n \"error_type\": \"validation_error\",\n \"model_name\": model_name,\n \"total_size_mb\": round(total_size_mb, 2),\n \"limit_mb\": round(effective_limit_mb, 2),\n \"image_count\": len(images),\n \"supports_images\": True,\n },\n }\n\n # All validations passed\n logger.debug(f\"Image validation passed: {len(images)} images, {total_size_mb:.1f}MB total\")\n return None\n\n def _parse_response(self, raw_text: str, request, model_info: Optional[dict] = None):\n \"\"\"Parse response - will be inherited for now.\"\"\"\n # Implementation inherited from current base.py\n raise NotImplementedError(\"Subclasses must implement _parse_response method\")\n" }, { "path": "tools/shared/exceptions.py", "content": "\"\"\"\nCustom exceptions for PAL MCP tools.\n\nThese exceptions allow tools to signal protocol-level errors that should be surfaced\nto MCP clients using the `isError` flag on `CallToolResult`. Raising one of these\nexceptions ensures the low-level server adapter marks the result as an error while\npreserving the structured payload we pass through the exception message.\n\"\"\"\n\n\nclass ToolExecutionError(RuntimeError):\n \"\"\"Raised to indicate a tool-level failure that must set `isError=True`.\"\"\"\n\n def __init__(self, payload: str):\n \"\"\"\n Args:\n payload: Serialized error payload (typically JSON) to return to the client.\n \"\"\"\n super().__init__(payload)\n self.payload = payload\n" }, { "path": "tools/shared/schema_builders.py", "content": "\"\"\"\nCore schema building functionality for PAL MCP tools.\n\nThis module provides base schema generation functionality for simple tools.\nWorkflow-specific schema building is located in workflow/schema_builders.py\nto maintain proper separation of concerns.\n\"\"\"\n\nfrom typing import Any\n\nfrom .base_models import COMMON_FIELD_DESCRIPTIONS\n\n\nclass SchemaBuilder:\n \"\"\"\n Base schema builder for simple MCP tools.\n\n This class provides static methods to build consistent schemas for simple tools.\n Workflow tools use WorkflowSchemaBuilder in workflow/schema_builders.py.\n \"\"\"\n\n # Common field schemas that can be reused across all tool types\n COMMON_FIELD_SCHEMAS = {\n \"temperature\": {\n \"type\": \"number\",\n \"description\": COMMON_FIELD_DESCRIPTIONS[\"temperature\"],\n \"minimum\": 0.0,\n \"maximum\": 1.0,\n },\n \"thinking_mode\": {\n \"type\": \"string\",\n \"enum\": [\"minimal\", \"low\", \"medium\", \"high\", \"max\"],\n \"description\": COMMON_FIELD_DESCRIPTIONS[\"thinking_mode\"],\n },\n \"continuation_id\": {\n \"type\": \"string\",\n \"description\": COMMON_FIELD_DESCRIPTIONS[\"continuation_id\"],\n },\n \"images\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": COMMON_FIELD_DESCRIPTIONS[\"images\"],\n },\n }\n\n # Simple tool-specific field schemas (workflow tools use relevant_files instead)\n SIMPLE_FIELD_SCHEMAS = {\n \"absolute_file_paths\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": COMMON_FIELD_DESCRIPTIONS[\"absolute_file_paths\"],\n },\n }\n\n @staticmethod\n def build_schema(\n tool_specific_fields: dict[str, dict[str, Any]] = None,\n required_fields: list[str] = None,\n model_field_schema: dict[str, Any] = None,\n auto_mode: bool = False,\n require_model: bool = False,\n ) -> dict[str, Any]:\n \"\"\"\n Build complete schema for simple tools.\n\n Args:\n tool_specific_fields: Additional fields specific to the tool\n required_fields: List of required field names\n model_field_schema: Schema for the model field\n auto_mode: Whether the tool is in auto mode (affects model requirement)\n\n Returns:\n Complete JSON schema for the tool\n \"\"\"\n properties = {}\n\n # Add common fields (temperature, thinking_mode, etc.)\n properties.update(SchemaBuilder.COMMON_FIELD_SCHEMAS)\n\n # Add simple tool-specific fields (files field for simple tools)\n properties.update(SchemaBuilder.SIMPLE_FIELD_SCHEMAS)\n\n # Add model field if provided\n if model_field_schema:\n properties[\"model\"] = model_field_schema\n\n # Add tool-specific fields if provided\n if tool_specific_fields:\n properties.update(tool_specific_fields)\n\n # Build required fields list\n required = list(required_fields) if required_fields else []\n if (auto_mode or require_model) and \"model\" not in required:\n required.append(\"model\")\n\n # Build the complete schema\n schema = {\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": properties,\n \"additionalProperties\": False,\n }\n\n if required:\n schema[\"required\"] = required\n\n return schema\n\n @staticmethod\n def get_common_fields() -> dict[str, dict[str, Any]]:\n \"\"\"Get the standard field schemas for simple tools.\"\"\"\n return SchemaBuilder.COMMON_FIELD_SCHEMAS.copy()\n\n @staticmethod\n def create_field_schema(\n field_type: str,\n description: str,\n enum_values: list[str] = None,\n minimum: float = None,\n maximum: float = None,\n items_type: str = None,\n default: Any = None,\n ) -> dict[str, Any]:\n \"\"\"\n Helper method to create field schemas with common patterns.\n\n Args:\n field_type: JSON schema type (\"string\", \"number\", \"array\", etc.)\n description: Human-readable description of the field\n enum_values: For enum fields, list of allowed values\n minimum: For numeric fields, minimum value\n maximum: For numeric fields, maximum value\n items_type: For array fields, type of array items\n default: Default value for the field\n\n Returns:\n JSON schema object for the field\n \"\"\"\n schema = {\n \"type\": field_type,\n \"description\": description,\n }\n\n if enum_values:\n schema[\"enum\"] = enum_values\n\n if minimum is not None:\n schema[\"minimum\"] = minimum\n\n if maximum is not None:\n schema[\"maximum\"] = maximum\n\n if items_type and field_type == \"array\":\n schema[\"items\"] = {\"type\": items_type}\n\n if default is not None:\n schema[\"default\"] = default\n\n return schema\n" }, { "path": "tools/simple/__init__.py", "content": "\"\"\"\nSimple tools for PAL MCP.\n\nSimple tools follow a basic request β†’ AI model β†’ response pattern.\nThey inherit from SimpleTool which provides streamlined functionality\nfor tools that don't need multi-step workflows.\n\nAvailable simple tools:\n- chat: General chat and collaborative thinking\n- consensus: Multi-perspective analysis\n- listmodels: Model listing and information\n- testgen: Test generation\n- tracer: Execution tracing\n\"\"\"\n\nfrom .base import SimpleTool\n\n__all__ = [\"SimpleTool\"]\n" }, { "path": "tools/simple/base.py", "content": "\"\"\"\nBase class for simple MCP tools.\n\nSimple tools follow a straightforward pattern:\n1. Receive request\n2. Prepare prompt (with absolute file paths, context, etc.)\n3. Call AI model\n4. Format and return response\n\nThey use the shared SchemaBuilder for consistent schema generation\nand inherit all the conversation, file processing, and model handling\ncapabilities from BaseTool.\n\"\"\"\n\nfrom abc import abstractmethod\nfrom typing import Any, Optional\n\nfrom tools.shared.base_models import ToolRequest\nfrom tools.shared.base_tool import BaseTool\nfrom tools.shared.exceptions import ToolExecutionError\nfrom tools.shared.schema_builders import SchemaBuilder\n\n\nclass SimpleTool(BaseTool):\n \"\"\"\n Base class for simple (non-workflow) tools.\n\n Simple tools are request/response tools that don't require multi-step workflows.\n They benefit from:\n - Automatic schema generation using SchemaBuilder\n - Inherited conversation handling and file processing\n - Standardized model integration\n - Consistent error handling and response formatting\n\n To create a simple tool:\n 1. Inherit from SimpleTool\n 2. Implement get_tool_fields() to define tool-specific fields\n 3. Implement prepare_prompt() for prompt preparation\n 4. Optionally override format_response() for custom formatting\n 5. Optionally override get_required_fields() for custom requirements\n\n Example:\n class ChatTool(SimpleTool):\n def get_name(self) -> str:\n return \"chat\"\n\n def get_tool_fields(self) -> Dict[str, Dict[str, Any]]:\n return {\n \"prompt\": {\n \"type\": \"string\",\n \"description\": \"Your question or idea...\",\n },\n \"absolute_file_paths\": SimpleTool.FILES_FIELD,\n }\n\n def get_required_fields(self) -> List[str]:\n return [\"prompt\"]\n \"\"\"\n\n # Common field definitions that simple tools can reuse\n FILES_FIELD = SchemaBuilder.SIMPLE_FIELD_SCHEMAS[\"absolute_file_paths\"]\n IMAGES_FIELD = SchemaBuilder.COMMON_FIELD_SCHEMAS[\"images\"]\n\n @abstractmethod\n def get_tool_fields(self) -> dict[str, dict[str, Any]]:\n \"\"\"\n Return tool-specific field definitions.\n\n This method should return a dictionary mapping field names to their\n JSON schema definitions. Common fields (model, temperature, etc.)\n are added automatically by the base class.\n\n Returns:\n Dict mapping field names to JSON schema objects\n\n Example:\n return {\n \"prompt\": {\n \"type\": \"string\",\n \"description\": \"The user's question or request\",\n },\n \"absolute_file_paths\": SimpleTool.FILES_FIELD, # Reuse common field\n \"max_tokens\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": \"Maximum tokens for response\",\n }\n }\n \"\"\"\n pass\n\n def get_required_fields(self) -> list[str]:\n \"\"\"\n Return list of required field names.\n\n Override this to specify which fields are required for your tool.\n The model field is automatically added if in auto mode.\n\n Returns:\n List of required field names\n \"\"\"\n return []\n\n def get_annotations(self) -> Optional[dict[str, Any]]:\n \"\"\"\n Return tool annotations. Simple tools are read-only by default.\n\n All simple tools perform operations without modifying the environment.\n They may call external AI models for analysis or conversation, but they\n don't write files or make system changes.\n\n Override this method if your simple tool needs different annotations.\n\n Returns:\n Dictionary with readOnlyHint set to True\n \"\"\"\n return {\"readOnlyHint\": True}\n\n def format_response(self, response: str, request, model_info: Optional[dict] = None) -> str:\n \"\"\"\n Format the AI response before returning to the client.\n\n This is a hook method that subclasses can override to customize\n response formatting. The default implementation returns the response as-is.\n\n Args:\n response: The raw response from the AI model\n request: The validated request object\n model_info: Optional model information dictionary\n\n Returns:\n Formatted response string\n \"\"\"\n return response\n\n def get_input_schema(self) -> dict[str, Any]:\n \"\"\"\n Generate the complete input schema using SchemaBuilder.\n\n This method automatically combines:\n - Tool-specific fields from get_tool_fields()\n - Common fields (temperature, thinking_mode, etc.)\n - Model field with proper auto-mode handling\n - Required fields from get_required_fields()\n\n Tools can override this method for custom schema generation while\n still benefiting from SimpleTool's convenience methods.\n\n Returns:\n Complete JSON schema for the tool\n \"\"\"\n required_fields = list(self.get_required_fields())\n return SchemaBuilder.build_schema(\n tool_specific_fields=self.get_tool_fields(),\n required_fields=required_fields,\n model_field_schema=self.get_model_field_schema(),\n auto_mode=self.is_effective_auto_mode(),\n )\n\n def get_request_model(self):\n \"\"\"\n Return the request model class.\n\n Simple tools use the base ToolRequest by default.\n Override this if your tool needs a custom request model.\n \"\"\"\n return ToolRequest\n\n # Hook methods for safe attribute access without hasattr/getattr\n\n def get_request_model_name(self, request) -> Optional[str]:\n \"\"\"Get model name from request. Override for custom model name handling.\"\"\"\n try:\n return request.model\n except AttributeError:\n return None\n\n def get_request_images(self, request) -> list:\n \"\"\"Get images from request. Override for custom image handling.\"\"\"\n try:\n return request.images if request.images is not None else []\n except AttributeError:\n return []\n\n def get_request_continuation_id(self, request) -> Optional[str]:\n \"\"\"Get continuation_id from request. Override for custom continuation handling.\"\"\"\n try:\n return request.continuation_id\n except AttributeError:\n return None\n\n def get_request_prompt(self, request) -> str:\n \"\"\"Get prompt from request. Override for custom prompt handling.\"\"\"\n try:\n return request.prompt\n except AttributeError:\n return \"\"\n\n def get_request_temperature(self, request) -> Optional[float]:\n \"\"\"Get temperature from request. Override for custom temperature handling.\"\"\"\n try:\n return request.temperature\n except AttributeError:\n return None\n\n def get_validated_temperature(self, request, model_context: Any) -> tuple[float, list[str]]:\n \"\"\"\n Get temperature from request and validate it against model constraints.\n\n This is a convenience method that combines temperature extraction and validation\n for simple tools. It ensures temperature is within valid range for the model.\n\n Args:\n request: The request object containing temperature\n model_context: Model context object containing model info\n\n Returns:\n Tuple of (validated_temperature, warning_messages)\n \"\"\"\n temperature = self.get_request_temperature(request)\n if temperature is None:\n temperature = self.get_default_temperature()\n return self.validate_and_correct_temperature(temperature, model_context)\n\n def get_request_thinking_mode(self, request) -> Optional[str]:\n \"\"\"Get thinking_mode from request. Override for custom thinking mode handling.\"\"\"\n try:\n return request.thinking_mode\n except AttributeError:\n return None\n\n def get_request_files(self, request) -> list:\n \"\"\"Get absolute file paths from request. Override for custom file handling.\"\"\"\n try:\n files = request.absolute_file_paths\n except AttributeError:\n files = None\n if files is None:\n return []\n return files\n\n def get_request_as_dict(self, request) -> dict:\n \"\"\"Convert request to dictionary. Override for custom serialization.\"\"\"\n try:\n # Try Pydantic v2 method first\n return request.model_dump()\n except AttributeError:\n try:\n # Fall back to Pydantic v1 method\n return request.dict()\n except AttributeError:\n # Last resort - convert to dict manually\n return {\"prompt\": self.get_request_prompt(request)}\n\n def set_request_files(self, request, files: list) -> None:\n \"\"\"Set absolute file paths on request. Override for custom file setting.\"\"\"\n try:\n request.absolute_file_paths = files\n except AttributeError:\n pass\n\n def get_actually_processed_files(self) -> list:\n \"\"\"Get actually processed files. Override for custom file tracking.\"\"\"\n try:\n return self._actually_processed_files\n except AttributeError:\n return []\n\n async def execute(self, arguments: dict[str, Any]) -> list:\n \"\"\"\n Execute the simple tool using the comprehensive flow from old base.py.\n\n This method replicates the proven execution pattern while using SimpleTool hooks.\n \"\"\"\n import logging\n\n from mcp.types import TextContent\n\n from tools.models import ToolOutput\n\n logger = logging.getLogger(f\"tools.{self.get_name()}\")\n\n try:\n # Store arguments for access by helper methods\n self._current_arguments = arguments\n\n logger.info(f\"πŸ”§ {self.get_name()} tool called with arguments: {list(arguments.keys())}\")\n\n # Validate request using the tool's Pydantic model\n request_model = self.get_request_model()\n request = request_model(**arguments)\n logger.debug(f\"Request validation successful for {self.get_name()}\")\n\n # Validate file paths for security\n # This prevents path traversal attacks and ensures proper access control\n path_error = self._validate_file_paths(request)\n if path_error:\n error_output = ToolOutput(\n status=\"error\",\n content=path_error,\n content_type=\"text\",\n )\n logger.error(\"Path validation failed for %s: %s\", self.get_name(), path_error)\n raise ToolExecutionError(error_output.model_dump_json())\n\n # Handle model resolution like old base.py\n model_name = self.get_request_model_name(request)\n if not model_name:\n from config import DEFAULT_MODEL\n\n model_name = DEFAULT_MODEL\n\n # Store the current model name for later use\n self._current_model_name = model_name\n\n # Handle model context from arguments (for in-process testing)\n if \"_model_context\" in arguments:\n self._model_context = arguments[\"_model_context\"]\n logger.debug(f\"{self.get_name()}: Using model context from arguments\")\n else:\n # Create model context if not provided\n from utils.model_context import ModelContext\n\n self._model_context = ModelContext(model_name)\n logger.debug(f\"{self.get_name()}: Created model context for {model_name}\")\n\n # Get images if present\n images = self.get_request_images(request)\n continuation_id = self.get_request_continuation_id(request)\n\n # Handle conversation history and prompt preparation\n if continuation_id:\n # Check if conversation history is already embedded\n field_value = self.get_request_prompt(request)\n if \"=== CONVERSATION HISTORY ===\" in field_value:\n # Use pre-embedded history\n prompt = field_value\n logger.debug(f\"{self.get_name()}: Using pre-embedded conversation history\")\n else:\n # No embedded history - reconstruct it (for in-process calls)\n logger.debug(f\"{self.get_name()}: No embedded history found, reconstructing conversation\")\n\n # Get thread context\n from utils.conversation_memory import add_turn, build_conversation_history, get_thread\n\n thread_context = get_thread(continuation_id)\n\n if thread_context:\n # Add user's new input to conversation\n user_prompt = self.get_request_prompt(request)\n user_files = self.get_request_files(request)\n if user_prompt:\n add_turn(continuation_id, \"user\", user_prompt, files=user_files)\n\n # Get updated thread context after adding the turn\n thread_context = get_thread(continuation_id)\n logger.debug(\n f\"{self.get_name()}: Retrieved updated thread with {len(thread_context.turns)} turns\"\n )\n\n # Build conversation history with updated thread context\n conversation_history, conversation_tokens = build_conversation_history(\n thread_context, self._model_context\n )\n\n # Get the base prompt from the tool\n base_prompt = await self.prepare_prompt(request)\n\n # Combine with conversation history\n if conversation_history:\n prompt = f\"{conversation_history}\\n\\n=== NEW USER INPUT ===\\n{base_prompt}\"\n else:\n prompt = base_prompt\n else:\n # Thread not found, prepare normally\n logger.warning(f\"Thread {continuation_id} not found, preparing prompt normally\")\n prompt = await self.prepare_prompt(request)\n else:\n # New conversation, prepare prompt normally\n prompt = await self.prepare_prompt(request)\n\n # Add follow-up instructions for new conversations\n from server import get_follow_up_instructions\n\n follow_up_instructions = get_follow_up_instructions(0)\n prompt = f\"{prompt}\\n\\n{follow_up_instructions}\"\n logger.debug(\n f\"Added follow-up instructions for new {self.get_name()} conversation\"\n ) # Validate images if any were provided\n if images:\n image_validation_error = self._validate_image_limits(\n images, model_context=self._model_context, continuation_id=continuation_id\n )\n if image_validation_error:\n error_output = ToolOutput(\n status=image_validation_error.get(\"status\", \"error\"),\n content=image_validation_error.get(\"content\"),\n content_type=image_validation_error.get(\"content_type\", \"text\"),\n metadata=image_validation_error.get(\"metadata\"),\n )\n payload = error_output.model_dump_json()\n logger.error(\"Image validation failed for %s: %s\", self.get_name(), payload)\n raise ToolExecutionError(payload)\n\n # Get and validate temperature against model constraints\n temperature, temp_warnings = self.get_validated_temperature(request, self._model_context)\n\n # Log any temperature corrections\n for warning in temp_warnings:\n # Get thinking mode with defaults\n logger.warning(warning)\n thinking_mode = self.get_request_thinking_mode(request)\n if thinking_mode is None:\n thinking_mode = self.get_default_thinking_mode()\n\n # Get the provider from model context (clean OOP - no re-fetching)\n provider = self._model_context.provider\n capabilities = self._model_context.capabilities\n\n # Get system prompt for this tool\n base_system_prompt = self.get_system_prompt()\n capability_augmented_prompt = self._augment_system_prompt_with_capabilities(\n base_system_prompt, capabilities\n )\n language_instruction = self.get_language_instruction()\n system_prompt = language_instruction + capability_augmented_prompt\n\n # Generate AI response using the provider\n logger.info(f\"Sending request to {provider.get_provider_type().value} API for {self.get_name()}\")\n logger.info(\n f\"Using model: {self._model_context.model_name} via {provider.get_provider_type().value} provider\"\n )\n\n # Estimate tokens for logging\n from utils.token_utils import estimate_tokens\n\n estimated_tokens = estimate_tokens(prompt)\n logger.debug(f\"Prompt length: {len(prompt)} characters (~{estimated_tokens:,} tokens)\")\n\n # Resolve model capabilities for feature gating\n supports_thinking = capabilities.supports_extended_thinking\n\n # Generate content with provider abstraction\n model_response = provider.generate_content(\n prompt=prompt,\n model_name=self._current_model_name,\n system_prompt=system_prompt,\n temperature=temperature,\n thinking_mode=thinking_mode if supports_thinking else None,\n images=images if images else None,\n )\n\n logger.info(f\"Received response from {provider.get_provider_type().value} API for {self.get_name()}\")\n\n # Process the model's response\n if model_response.content:\n raw_text = model_response.content\n\n # Create model info for conversation tracking\n model_info = {\n \"provider\": provider,\n \"model_name\": self._current_model_name,\n \"model_response\": model_response,\n }\n\n # Parse response using the same logic as old base.py\n tool_output = self._parse_response(raw_text, request, model_info)\n logger.info(f\"βœ… {self.get_name()} tool completed successfully\")\n\n else:\n # Handle cases where the model couldn't generate a response\n metadata = model_response.metadata or {}\n finish_reason = metadata.get(\"finish_reason\", \"Unknown\")\n\n if metadata.get(\"is_blocked_by_safety\"):\n # Specific handling for content safety blocks\n safety_details = metadata.get(\"safety_feedback\") or \"details not provided\"\n logger.warning(\n f\"Response blocked by content safety policy for {self.get_name()}. \"\n f\"Reason: {finish_reason}, Details: {safety_details}\"\n )\n tool_output = ToolOutput(\n status=\"error\",\n content=\"Your request was blocked by the content safety policy. \"\n \"Please try modifying your prompt.\",\n content_type=\"text\",\n )\n else:\n # Handle other empty responses - could be legitimate completion or unclear blocking\n if finish_reason == \"STOP\":\n # Model completed normally but returned empty content - retry with clarification\n logger.info(\n f\"Model completed with empty response for {self.get_name()}, retrying with clarification\"\n )\n\n # Retry the same request with modified prompt asking for explicit response\n original_prompt = prompt\n retry_prompt = f\"{original_prompt}\\n\\nIMPORTANT: Please provide a substantive response. If you cannot respond to the above request, please explain why and suggest alternatives.\"\n\n try:\n retry_response = provider.generate_content(\n prompt=retry_prompt,\n model_name=self._current_model_name,\n system_prompt=system_prompt,\n temperature=temperature,\n thinking_mode=thinking_mode if supports_thinking else None,\n images=images if images else None,\n )\n\n if retry_response.content:\n # Successful retry - use the retry response\n logger.info(f\"Retry successful for {self.get_name()}\")\n raw_text = retry_response.content\n\n # Update model info for the successful retry\n model_info = {\n \"provider\": provider,\n \"model_name\": self._current_model_name,\n \"model_response\": retry_response,\n }\n\n # Parse the retry response\n tool_output = self._parse_response(raw_text, request, model_info)\n logger.info(f\"βœ… {self.get_name()} tool completed successfully after retry\")\n else:\n # Retry also failed - inspect metadata to find out why\n retry_metadata = retry_response.metadata or {}\n if retry_metadata.get(\"is_blocked_by_safety\"):\n # The retry was blocked by safety filters\n safety_details = retry_metadata.get(\"safety_feedback\") or \"details not provided\"\n logger.warning(\n f\"Retry for {self.get_name()} was blocked by content safety policy. \"\n f\"Details: {safety_details}\"\n )\n tool_output = ToolOutput(\n status=\"error\",\n content=\"Your request was also blocked by the content safety policy after a retry. \"\n \"Please try rephrasing your prompt significantly.\",\n content_type=\"text\",\n )\n else:\n # Retry failed for other reasons (e.g., another STOP)\n tool_output = ToolOutput(\n status=\"error\",\n content=\"The model repeatedly returned empty responses. This may indicate content filtering or a model issue.\",\n content_type=\"text\",\n )\n except Exception as retry_error:\n logger.warning(f\"Retry failed for {self.get_name()}: {retry_error}\")\n tool_output = ToolOutput(\n status=\"error\",\n content=f\"Model returned empty response and retry failed: {str(retry_error)}\",\n content_type=\"text\",\n )\n else:\n # Non-STOP finish reasons are likely actual errors\n logger.warning(\n f\"Response blocked or incomplete for {self.get_name()}. Finish reason: {finish_reason}\"\n )\n tool_output = ToolOutput(\n status=\"error\",\n content=f\"Response blocked or incomplete. Finish reason: {finish_reason}\",\n content_type=\"text\",\n )\n\n # Return the tool output as TextContent, marking protocol errors appropriately\n payload = tool_output.model_dump_json()\n if tool_output.status == \"error\":\n logger.error(\"%s reported error status - raising ToolExecutionError\", self.get_name())\n raise ToolExecutionError(payload)\n return [TextContent(type=\"text\", text=payload)]\n\n except ToolExecutionError:\n raise\n except Exception as e:\n # Special handling for MCP size check errors\n if str(e).startswith(\"MCP_SIZE_CHECK:\"):\n # Extract the JSON content after the prefix\n json_content = str(e)[len(\"MCP_SIZE_CHECK:\") :]\n raise ToolExecutionError(json_content)\n\n logger.error(f\"Error in {self.get_name()}: {str(e)}\")\n error_output = ToolOutput(\n status=\"error\",\n content=f\"Error in {self.get_name()}: {str(e)}\",\n content_type=\"text\",\n )\n raise ToolExecutionError(error_output.model_dump_json()) from e\n\n def _parse_response(self, raw_text: str, request, model_info: Optional[dict] = None):\n \"\"\"\n Parse the raw response and format it using the hook method.\n\n This simplified version focuses on the SimpleTool pattern: format the response\n using the format_response hook, then handle conversation continuation.\n \"\"\"\n from tools.models import ToolOutput\n\n # Format the response using the hook method\n formatted_response = self.format_response(raw_text, request, model_info)\n\n # Handle conversation continuation like old base.py\n continuation_id = self.get_request_continuation_id(request)\n if continuation_id:\n self._record_assistant_turn(continuation_id, raw_text, request, model_info)\n\n # Create continuation offer like old base.py\n continuation_data = self._create_continuation_offer(request, model_info)\n if continuation_data:\n return self._create_continuation_offer_response(formatted_response, continuation_data, request, model_info)\n else:\n # Build metadata with model and provider info for success response\n metadata = {}\n if model_info:\n model_name = model_info.get(\"model_name\")\n if model_name:\n metadata[\"model_used\"] = model_name\n provider = model_info.get(\"provider\")\n if provider:\n # Handle both provider objects and string values\n if isinstance(provider, str):\n metadata[\"provider_used\"] = provider\n else:\n try:\n metadata[\"provider_used\"] = provider.get_provider_type().value\n except AttributeError:\n # Fallback if provider doesn't have get_provider_type method\n metadata[\"provider_used\"] = str(provider)\n\n return ToolOutput(\n status=\"success\",\n content=formatted_response,\n content_type=\"text\",\n metadata=metadata if metadata else None,\n )\n\n def _create_continuation_offer(self, request, model_info: Optional[dict] = None):\n \"\"\"Create continuation offer following old base.py pattern\"\"\"\n continuation_id = self.get_request_continuation_id(request)\n\n try:\n from utils.conversation_memory import create_thread, get_thread\n\n if continuation_id:\n # Existing conversation\n thread_context = get_thread(continuation_id)\n if thread_context and thread_context.turns:\n turn_count = len(thread_context.turns)\n from utils.conversation_memory import MAX_CONVERSATION_TURNS\n\n if turn_count >= MAX_CONVERSATION_TURNS - 1:\n return None # No more turns allowed\n\n remaining_turns = MAX_CONVERSATION_TURNS - turn_count - 1\n return {\n \"continuation_id\": continuation_id,\n \"remaining_turns\": remaining_turns,\n \"note\": f\"You can continue this conversation for {remaining_turns} more exchanges.\",\n }\n else:\n # New conversation - create thread and offer continuation\n # Convert request to dict for initial_context\n initial_request_dict = self.get_request_as_dict(request)\n\n new_thread_id = create_thread(tool_name=self.get_name(), initial_request=initial_request_dict)\n\n # Add the initial user turn to the new thread\n from utils.conversation_memory import MAX_CONVERSATION_TURNS, add_turn\n\n user_prompt = self.get_request_prompt(request)\n user_files = self.get_request_files(request)\n user_images = self.get_request_images(request)\n\n # Add user's initial turn\n add_turn(\n new_thread_id, \"user\", user_prompt, files=user_files, images=user_images, tool_name=self.get_name()\n )\n\n return {\n \"continuation_id\": new_thread_id,\n \"remaining_turns\": MAX_CONVERSATION_TURNS - 1,\n \"note\": f\"You can continue this conversation for {MAX_CONVERSATION_TURNS - 1} more exchanges.\",\n }\n except Exception:\n return None\n\n def _create_continuation_offer_response(\n self, content: str, continuation_data: dict, request, model_info: Optional[dict] = None\n ):\n \"\"\"Create response with continuation offer following old base.py pattern\"\"\"\n from tools.models import ContinuationOffer, ToolOutput\n\n try:\n if not self.get_request_continuation_id(request):\n self._record_assistant_turn(\n continuation_data[\"continuation_id\"],\n content,\n request,\n model_info,\n )\n\n continuation_offer = ContinuationOffer(\n continuation_id=continuation_data[\"continuation_id\"],\n note=continuation_data[\"note\"],\n remaining_turns=continuation_data[\"remaining_turns\"],\n )\n\n # Build metadata with model and provider info\n metadata = {\"tool_name\": self.get_name(), \"conversation_ready\": True}\n if model_info:\n model_name = model_info.get(\"model_name\")\n if model_name:\n metadata[\"model_used\"] = model_name\n provider = model_info.get(\"provider\")\n if provider:\n # Handle both provider objects and string values\n if isinstance(provider, str):\n metadata[\"provider_used\"] = provider\n else:\n try:\n metadata[\"provider_used\"] = provider.get_provider_type().value\n except AttributeError:\n # Fallback if provider doesn't have get_provider_type method\n metadata[\"provider_used\"] = str(provider)\n\n return ToolOutput(\n status=\"continuation_available\",\n content=content,\n content_type=\"text\",\n continuation_offer=continuation_offer,\n metadata=metadata,\n )\n except Exception:\n # Fallback to simple success if continuation offer fails\n return ToolOutput(status=\"success\", content=content, content_type=\"text\")\n\n def _record_assistant_turn(\n self, continuation_id: str, response_text: str, request, model_info: Optional[dict]\n ) -> None:\n \"\"\"Persist an assistant response in conversation memory.\"\"\"\n\n if not continuation_id:\n return\n\n from utils.conversation_memory import add_turn\n\n model_provider = None\n model_name = None\n model_metadata = None\n\n if model_info:\n provider = model_info.get(\"provider\")\n if provider:\n if isinstance(provider, str):\n model_provider = provider\n else:\n try:\n model_provider = provider.get_provider_type().value\n except AttributeError:\n model_provider = str(provider)\n model_name = model_info.get(\"model_name\")\n model_response = model_info.get(\"model_response\")\n if model_response:\n model_metadata = {\"usage\": model_response.usage, \"metadata\": model_response.metadata}\n\n add_turn(\n continuation_id,\n \"assistant\",\n response_text,\n files=self.get_request_files(request),\n images=self.get_request_images(request),\n tool_name=self.get_name(),\n model_provider=model_provider,\n model_name=model_name,\n model_metadata=model_metadata,\n )\n\n # Convenience methods for common tool patterns\n\n def build_standard_prompt(\n self, system_prompt: str, user_content: str, request, file_context_title: str = \"CONTEXT FILES\"\n ) -> str:\n \"\"\"\n Build a standard prompt with system prompt, user content, and optional files.\n\n This is a convenience method that handles the common pattern of:\n 1. Adding file content if present\n 2. Checking token limits\n 3. Adding web search instructions\n 4. Combining everything into a well-formatted prompt\n\n Args:\n system_prompt: The system prompt for the tool\n user_content: The main user request/content\n request: The validated request object\n file_context_title: Title for the file context section\n\n Returns:\n Complete formatted prompt ready for the AI model\n \"\"\"\n # Check size limits against raw user input before enriching with internal context\n content_to_validate = self.get_prompt_content_for_size_validation(user_content)\n self._validate_token_limit(content_to_validate, \"Content\")\n\n # Add context files if provided (does not affect MCP boundary enforcement)\n files = self.get_request_files(request)\n if files:\n file_content, processed_files = self._prepare_file_content_for_prompt(\n files,\n self.get_request_continuation_id(request),\n \"Context files\",\n model_context=getattr(self, \"_model_context\", None),\n )\n self._actually_processed_files = processed_files\n if file_content:\n user_content = f\"{user_content}\\n\\n=== {file_context_title} ===\\n{file_content}\\n=== END CONTEXT ====\"\n\n # Add standardized web search guidance\n websearch_instruction = self.get_websearch_instruction(self.get_websearch_guidance())\n\n # Combine system prompt with user content\n full_prompt = f\"\"\"{system_prompt}{websearch_instruction}\n\n=== USER REQUEST ===\n{user_content}\n=== END REQUEST ===\n\nPlease provide a thoughtful, comprehensive response:\"\"\"\n\n return full_prompt\n\n def get_prompt_content_for_size_validation(self, user_content: str) -> str:\n \"\"\"\n Override to use original user prompt for size validation when conversation history is embedded.\n\n When server.py embeds conversation history into the prompt field, it also stores\n the original user prompt in _original_user_prompt. We use that for size validation\n to avoid incorrectly triggering size limits due to conversation history.\n\n Args:\n user_content: The user content (may include conversation history)\n\n Returns:\n The original user prompt if available, otherwise the full user content\n \"\"\"\n # Check if we have the current arguments from execute() method\n current_args = getattr(self, \"_current_arguments\", None)\n if current_args:\n # If server.py embedded conversation history, it stores original prompt separately\n original_user_prompt = current_args.get(\"_original_user_prompt\")\n if original_user_prompt is not None:\n # Use original user prompt for size validation (excludes conversation history)\n return original_user_prompt\n\n # Fallback to default behavior (validate full user content)\n return user_content\n\n def get_websearch_guidance(self) -> Optional[str]:\n \"\"\"\n Return tool-specific web search guidance.\n\n Override this to provide tool-specific guidance for when web searches\n would be helpful. Return None to use the default guidance.\n\n Returns:\n Tool-specific web search guidance or None for default\n \"\"\"\n return None\n\n def handle_prompt_file_with_fallback(self, request) -> str:\n \"\"\"\n Handle prompt.txt files with fallback to request field.\n\n This is a convenience method for tools that accept prompts either\n as a field or as a prompt.txt file. It handles the extraction\n and validation automatically.\n\n Args:\n request: The validated request object\n\n Returns:\n The effective prompt content\n\n Raises:\n ValueError: If prompt is too large for MCP transport\n \"\"\"\n # Check for prompt.txt in provided absolute file paths\n files = self.get_request_files(request)\n if files:\n prompt_content, updated_files = self.handle_prompt_file(files)\n\n # Update request files list if needed\n if updated_files is not None:\n self.set_request_files(request, updated_files)\n else:\n prompt_content = None\n\n # Use prompt.txt content if available, otherwise use the prompt field\n user_content = prompt_content if prompt_content else self.get_request_prompt(request)\n\n # Check user input size at MCP transport boundary (excluding conversation history)\n validation_content = self.get_prompt_content_for_size_validation(user_content)\n size_check = self.check_prompt_size(validation_content)\n if size_check:\n from tools.models import ToolOutput\n\n raise ValueError(f\"MCP_SIZE_CHECK:{ToolOutput(**size_check).model_dump_json()}\")\n\n return user_content\n\n def get_chat_style_websearch_guidance(self) -> str:\n \"\"\"\n Get Chat tool-style web search guidance.\n\n Returns web search guidance that matches the original Chat tool pattern.\n This is useful for tools that want to maintain the same search behavior.\n\n Returns:\n Web search guidance text\n \"\"\"\n return \"\"\"When discussing topics, consider if searches for these would help:\n- Documentation for any technologies or concepts mentioned\n- Current best practices and patterns\n- Recent developments or updates\n- Community discussions and solutions\"\"\"\n\n def supports_custom_request_model(self) -> bool:\n \"\"\"\n Indicate whether this tool supports custom request models.\n\n Simple tools support custom request models by default. Tools that override\n get_request_model() to return something other than ToolRequest should\n return True here.\n\n Returns:\n True if the tool uses a custom request model\n \"\"\"\n return self.get_request_model() != ToolRequest\n\n def _validate_file_paths(self, request) -> Optional[str]:\n \"\"\"\n Validate that all file paths in the request are absolute paths.\n\n This is a security measure to prevent path traversal attacks and ensure\n proper access control. All file paths must be absolute (starting with '/').\n\n Args:\n request: The validated request object\n\n Returns:\n Optional[str]: Error message if validation fails, None if all paths are valid\n \"\"\"\n import os\n\n # Check if request has absolute file paths attribute (legacy tools may still provide 'files')\n files = self.get_request_files(request)\n if files:\n for file_path in files:\n if not os.path.isabs(file_path):\n return (\n f\"Error: All file paths must be FULL absolute paths to real files / folders - DO NOT SHORTEN. \"\n f\"Received relative path: {file_path}\\n\"\n f\"Please provide the full absolute path starting with '/' (must be FULL absolute paths to real files / folders - DO NOT SHORTEN)\"\n )\n\n return None\n\n def prepare_chat_style_prompt(self, request, system_prompt: str = None) -> str:\n \"\"\"\n Prepare a prompt using Chat tool-style patterns.\n\n This convenience method replicates the Chat tool's prompt preparation logic:\n 1. Handle prompt.txt file if present\n 2. Add file context with specific formatting\n 3. Add web search guidance\n 4. Format with system prompt\n\n Args:\n request: The validated request object\n system_prompt: System prompt to use (uses get_system_prompt() if None)\n\n Returns:\n Complete formatted prompt\n \"\"\"\n # Use provided system prompt or get from tool\n if system_prompt is None:\n system_prompt = self.get_system_prompt()\n\n # Get user content (handles prompt.txt files)\n user_content = self.handle_prompt_file_with_fallback(request)\n\n # Build standard prompt with Chat-style web search guidance\n websearch_guidance = self.get_chat_style_websearch_guidance()\n\n # Override the websearch guidance temporarily\n original_guidance = self.get_websearch_guidance\n self.get_websearch_guidance = lambda: websearch_guidance\n\n try:\n full_prompt = self.build_standard_prompt(system_prompt, user_content, request, \"CONTEXT FILES\")\n finally:\n # Restore original guidance method\n self.get_websearch_guidance = original_guidance\n\n if system_prompt:\n marker = \"\\n\\n=== USER REQUEST ===\\n\"\n if marker in full_prompt:\n _, user_section = full_prompt.split(marker, 1)\n return f\"=== USER REQUEST ===\\n{user_section}\"\n\n return full_prompt\n" }, { "path": "tools/testgen.py", "content": "\"\"\"\nTestGen Workflow tool - Step-by-step test generation with expert validation\n\nThis tool provides a structured workflow for comprehensive test generation.\nIt guides the CLI agent through systematic investigation steps with forced pauses between each step\nto ensure thorough code examination, test planning, and pattern identification before proceeding.\nThe tool supports finding updates and expert analysis integration for comprehensive test suite generation.\n\nKey features:\n- Step-by-step test generation workflow with progress tracking\n- Context-aware file embedding (references during investigation, full content for analysis)\n- Automatic test pattern detection and framework identification\n- Expert analysis integration with external models for additional test suggestions\n- Support for edge case identification and comprehensive coverage\n- Confidence-based workflow optimization\n\"\"\"\n\nimport logging\nfrom typing import TYPE_CHECKING, Any, Optional\n\nfrom pydantic import Field, model_validator\n\nif TYPE_CHECKING:\n from tools.models import ToolModelCategory\n\nfrom config import TEMPERATURE_ANALYTICAL\nfrom systemprompts import TESTGEN_PROMPT\nfrom tools.shared.base_models import WorkflowRequest\n\nfrom .workflow.base import WorkflowTool\n\nlogger = logging.getLogger(__name__)\n\n# Tool-specific field descriptions for test generation workflow\nTESTGEN_WORKFLOW_FIELD_DESCRIPTIONS = {\n \"step\": (\n \"Test plan for this step. Step 1: outline how you'll analyse structure, business logic, critical paths, and edge cases. Later steps: record findings and new scenarios as they emerge.\"\n ),\n \"step_number\": \"Current test-generation step (starts at 1) β€” each step should build on prior work.\",\n \"total_steps\": \"Estimated number of steps needed for test planning; adjust as new scenarios appear.\",\n \"next_step_required\": \"True while more investigation or planning remains; set False when test planning is ready for expert validation.\",\n \"findings\": \"Summarise functionality, critical paths, edge cases, boundary conditions, error handling, and existing test patterns. Cover both happy and failure paths.\",\n \"files_checked\": \"Absolute paths of every file examined, including those ruled out.\",\n \"relevant_files\": \"Absolute paths of code that requires new or updated tests (implementation, dependencies, existing test fixtures).\",\n \"relevant_context\": \"Functions/methods needing coverage (e.g. 'Class.method', 'function_name'), with emphasis on critical paths and error-prone code.\",\n \"confidence\": (\n \"Indicate your current confidence in the test generation assessment. Use: 'exploring' (starting analysis), \"\n \"'low' (early investigation), 'medium' (some patterns identified), 'high' (strong understanding), \"\n \"'very_high' (very strong understanding), 'almost_certain' (nearly complete test plan), 'certain' \"\n \"(100% confidence - test plan is thoroughly complete and all test scenarios are identified with no need for external model validation). \"\n \"Do NOT use 'certain' unless the test generation analysis is comprehensively complete, use 'very_high' or 'almost_certain' instead if not 100% sure. \"\n \"Using 'certain' means you have complete confidence locally and prevents external model validation.\"\n ),\n \"images\": \"Optional absolute paths to diagrams or visuals that clarify the system under test.\",\n}\n\n\nclass TestGenRequest(WorkflowRequest):\n \"\"\"Request model for test generation workflow investigation steps\"\"\"\n\n # Required fields for each investigation step\n step: str = Field(..., description=TESTGEN_WORKFLOW_FIELD_DESCRIPTIONS[\"step\"])\n step_number: int = Field(..., description=TESTGEN_WORKFLOW_FIELD_DESCRIPTIONS[\"step_number\"])\n total_steps: int = Field(..., description=TESTGEN_WORKFLOW_FIELD_DESCRIPTIONS[\"total_steps\"])\n next_step_required: bool = Field(..., description=TESTGEN_WORKFLOW_FIELD_DESCRIPTIONS[\"next_step_required\"])\n\n # Investigation tracking fields\n findings: str = Field(..., description=TESTGEN_WORKFLOW_FIELD_DESCRIPTIONS[\"findings\"])\n files_checked: list[str] = Field(\n default_factory=list, description=TESTGEN_WORKFLOW_FIELD_DESCRIPTIONS[\"files_checked\"]\n )\n relevant_files: list[str] = Field(\n default_factory=list, description=TESTGEN_WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_files\"]\n )\n relevant_context: list[str] = Field(\n default_factory=list, description=TESTGEN_WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_context\"]\n )\n confidence: Optional[str] = Field(\"low\", description=TESTGEN_WORKFLOW_FIELD_DESCRIPTIONS[\"confidence\"])\n\n # Optional images for visual context\n images: Optional[list[str]] = Field(default=None, description=TESTGEN_WORKFLOW_FIELD_DESCRIPTIONS[\"images\"])\n\n # Override inherited fields to exclude them from schema (except model which needs to be available)\n temperature: Optional[float] = Field(default=None, exclude=True)\n thinking_mode: Optional[str] = Field(default=None, exclude=True)\n\n @model_validator(mode=\"after\")\n def validate_step_one_requirements(self):\n \"\"\"Ensure step 1 has required relevant_files field.\"\"\"\n if self.step_number == 1 and not self.relevant_files:\n raise ValueError(\"Step 1 requires 'relevant_files' field to specify code files to generate tests for\")\n return self\n\n\nclass TestGenTool(WorkflowTool):\n \"\"\"\n Test Generation workflow tool for step-by-step test planning and expert validation.\n\n This tool implements a structured test generation workflow that guides users through\n methodical investigation steps, ensuring thorough code examination, pattern identification,\n and test scenario planning before reaching conclusions. It supports complex testing scenarios\n including edge case identification, framework detection, and comprehensive coverage planning.\n \"\"\"\n\n __test__ = False # Prevent pytest from collecting this class as a test\n\n def __init__(self):\n super().__init__()\n self.initial_request = None\n\n def get_name(self) -> str:\n return \"testgen\"\n\n def get_description(self) -> str:\n return (\n \"Creates comprehensive test suites with edge case coverage for specific functions, classes, or modules. \"\n \"Analyzes code paths, identifies failure modes, and generates framework-specific tests. \"\n \"Be specific about scope - target particular components rather than testing everything.\"\n )\n\n def get_system_prompt(self) -> str:\n return TESTGEN_PROMPT\n\n def get_default_temperature(self) -> float:\n return TEMPERATURE_ANALYTICAL\n\n def get_model_category(self) -> \"ToolModelCategory\":\n \"\"\"Test generation requires thorough analysis and reasoning\"\"\"\n from tools.models import ToolModelCategory\n\n return ToolModelCategory.EXTENDED_REASONING\n\n def get_workflow_request_model(self):\n \"\"\"Return the test generation workflow-specific request model.\"\"\"\n return TestGenRequest\n\n def get_input_schema(self) -> dict[str, Any]:\n \"\"\"Generate input schema using WorkflowSchemaBuilder with test generation-specific overrides.\"\"\"\n from .workflow.schema_builders import WorkflowSchemaBuilder\n\n # Test generation workflow-specific field overrides\n testgen_field_overrides = {\n \"step\": {\n \"type\": \"string\",\n \"description\": TESTGEN_WORKFLOW_FIELD_DESCRIPTIONS[\"step\"],\n },\n \"step_number\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": TESTGEN_WORKFLOW_FIELD_DESCRIPTIONS[\"step_number\"],\n },\n \"total_steps\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": TESTGEN_WORKFLOW_FIELD_DESCRIPTIONS[\"total_steps\"],\n },\n \"next_step_required\": {\n \"type\": \"boolean\",\n \"description\": TESTGEN_WORKFLOW_FIELD_DESCRIPTIONS[\"next_step_required\"],\n },\n \"findings\": {\n \"type\": \"string\",\n \"description\": TESTGEN_WORKFLOW_FIELD_DESCRIPTIONS[\"findings\"],\n },\n \"files_checked\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": TESTGEN_WORKFLOW_FIELD_DESCRIPTIONS[\"files_checked\"],\n },\n \"relevant_files\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": TESTGEN_WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_files\"],\n },\n \"confidence\": {\n \"type\": \"string\",\n \"enum\": [\"exploring\", \"low\", \"medium\", \"high\", \"very_high\", \"almost_certain\", \"certain\"],\n \"description\": TESTGEN_WORKFLOW_FIELD_DESCRIPTIONS[\"confidence\"],\n },\n \"images\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": TESTGEN_WORKFLOW_FIELD_DESCRIPTIONS[\"images\"],\n },\n }\n\n # Use WorkflowSchemaBuilder with test generation-specific tool fields\n return WorkflowSchemaBuilder.build_schema(\n tool_specific_fields=testgen_field_overrides,\n model_field_schema=self.get_model_field_schema(),\n auto_mode=self.is_effective_auto_mode(),\n tool_name=self.get_name(),\n )\n\n def get_required_actions(\n self, step_number: int, confidence: str, findings: str, total_steps: int, request=None\n ) -> list[str]:\n \"\"\"Define required actions for each investigation phase.\"\"\"\n if step_number == 1:\n # Initial test generation investigation tasks\n return [\n \"Read and understand the code files specified for test generation\",\n \"Analyze the overall structure, public APIs, and main functionality\",\n \"Identify critical business logic and complex algorithms that need testing\",\n \"Look for existing test patterns or examples if provided\",\n \"Understand dependencies, external interactions, and integration points\",\n \"Note any potential testability issues or areas that might be hard to test\",\n ]\n elif confidence in [\"exploring\", \"low\"]:\n # Need deeper investigation\n return [\n \"Examine specific functions and methods to understand their behavior\",\n \"Trace through code paths to identify all possible execution flows\",\n \"Identify edge cases, boundary conditions, and error scenarios\",\n \"Check for async operations, state management, and side effects\",\n \"Look for non-deterministic behavior or external dependencies\",\n \"Analyze error handling and exception cases that need testing\",\n ]\n elif confidence in [\"medium\", \"high\"]:\n # Close to completion - need final verification\n return [\n \"Verify all critical paths have been identified for testing\",\n \"Confirm edge cases and boundary conditions are comprehensive\",\n \"Check that test scenarios cover both success and failure cases\",\n \"Ensure async behavior and concurrency issues are addressed\",\n \"Validate that the testing strategy aligns with code complexity\",\n \"Double-check that findings include actionable test scenarios\",\n ]\n else:\n # General investigation needed\n return [\n \"Continue examining the codebase for additional test scenarios\",\n \"Gather more evidence about code behavior and dependencies\",\n \"Test your assumptions about how the code should be tested\",\n \"Look for patterns that confirm your testing strategy\",\n \"Focus on areas that haven't been thoroughly examined yet\",\n ]\n\n def should_call_expert_analysis(self, consolidated_findings, request=None) -> bool:\n \"\"\"\n Decide when to call external model based on investigation completeness.\n\n Always call expert analysis for test generation to get additional test ideas.\n \"\"\"\n # Check if user requested to skip assistant model\n if request and not self.get_request_use_assistant_model(request):\n return False\n\n # Always benefit from expert analysis for comprehensive test coverage\n return len(consolidated_findings.relevant_files) > 0 or len(consolidated_findings.findings) >= 1\n\n def prepare_expert_analysis_context(self, consolidated_findings) -> str:\n \"\"\"Prepare context for external model call for test generation validation.\"\"\"\n context_parts = [\n f\"=== TEST GENERATION REQUEST ===\\n{self.initial_request or 'Test generation workflow initiated'}\\n=== END REQUEST ===\"\n ]\n\n # Add investigation summary\n investigation_summary = self._build_test_generation_summary(consolidated_findings)\n context_parts.append(\n f\"\\n=== AGENT'S TEST PLANNING INVESTIGATION ===\\n{investigation_summary}\\n=== END INVESTIGATION ===\"\n )\n\n # Add relevant code elements if available\n if consolidated_findings.relevant_context:\n methods_text = \"\\n\".join(f\"- {method}\" for method in consolidated_findings.relevant_context)\n context_parts.append(f\"\\n=== CODE ELEMENTS TO TEST ===\\n{methods_text}\\n=== END CODE ELEMENTS ===\")\n\n # Add images if available\n if consolidated_findings.images:\n images_text = \"\\n\".join(f\"- {img}\" for img in consolidated_findings.images)\n context_parts.append(f\"\\n=== VISUAL DOCUMENTATION ===\\n{images_text}\\n=== END VISUAL DOCUMENTATION ===\")\n\n return \"\\n\".join(context_parts)\n\n def _build_test_generation_summary(self, consolidated_findings) -> str:\n \"\"\"Prepare a comprehensive summary of the test generation investigation.\"\"\"\n summary_parts = [\n \"=== SYSTEMATIC TEST GENERATION INVESTIGATION SUMMARY ===\",\n f\"Total steps: {len(consolidated_findings.findings)}\",\n f\"Files examined: {len(consolidated_findings.files_checked)}\",\n f\"Relevant files identified: {len(consolidated_findings.relevant_files)}\",\n f\"Code elements to test: {len(consolidated_findings.relevant_context)}\",\n \"\",\n \"=== INVESTIGATION PROGRESSION ===\",\n ]\n\n for finding in consolidated_findings.findings:\n summary_parts.append(finding)\n\n return \"\\\\n\".join(summary_parts)\n\n def should_include_files_in_expert_prompt(self) -> bool:\n \"\"\"Include files in expert analysis for comprehensive test generation.\"\"\"\n return True\n\n def should_embed_system_prompt(self) -> bool:\n \"\"\"Embed system prompt in expert analysis for proper context.\"\"\"\n return True\n\n def get_expert_thinking_mode(self) -> str:\n \"\"\"Use high thinking mode for thorough test generation analysis.\"\"\"\n return \"high\"\n\n def get_expert_analysis_instruction(self) -> str:\n \"\"\"Get specific instruction for test generation expert analysis.\"\"\"\n return (\n \"Please provide comprehensive test generation guidance based on the investigation findings. \"\n \"Focus on identifying additional test scenarios, edge cases not yet covered, framework-specific \"\n \"best practices, and providing concrete test implementation examples following the multi-agent \"\n \"workflow specified in the system prompt.\"\n )\n\n # Hook method overrides for test generation-specific behavior\n\n def prepare_step_data(self, request) -> dict:\n \"\"\"\n Map test generation-specific fields for internal processing.\n \"\"\"\n step_data = {\n \"step\": request.step,\n \"step_number\": request.step_number,\n \"findings\": request.findings,\n \"files_checked\": request.files_checked,\n \"relevant_files\": request.relevant_files,\n \"relevant_context\": request.relevant_context,\n \"confidence\": request.confidence,\n \"images\": request.images or [],\n }\n return step_data\n\n def should_skip_expert_analysis(self, request, consolidated_findings) -> bool:\n \"\"\"\n Test generation workflow skips expert analysis when the CLI agent has \"certain\" confidence.\n \"\"\"\n return request.confidence == \"certain\" and not request.next_step_required\n\n def store_initial_issue(self, step_description: str):\n \"\"\"Store initial request for expert analysis.\"\"\"\n self.initial_request = step_description\n\n # Override inheritance hooks for test generation-specific behavior\n\n def get_completion_status(self) -> str:\n \"\"\"Test generation tools use test-specific status.\"\"\"\n return \"test_generation_complete_ready_for_implementation\"\n\n def get_completion_data_key(self) -> str:\n \"\"\"Test generation uses 'complete_test_generation' key.\"\"\"\n return \"complete_test_generation\"\n\n def get_final_analysis_from_request(self, request):\n \"\"\"Test generation tools use findings for final analysis.\"\"\"\n return request.findings\n\n def get_confidence_level(self, request) -> str:\n \"\"\"Test generation tools use 'certain' for high confidence.\"\"\"\n return \"certain\"\n\n def get_completion_message(self) -> str:\n \"\"\"Test generation-specific completion message.\"\"\"\n return (\n \"Test generation analysis complete with CERTAIN confidence. You have identified all test scenarios \"\n \"and provided comprehensive coverage strategy. MANDATORY: Present the user with the complete test plan \"\n \"and IMMEDIATELY proceed with creating the test files following the identified patterns and framework. \"\n \"Focus on implementing concrete, runnable tests with proper assertions.\"\n )\n\n def get_skip_reason(self) -> str:\n \"\"\"Test generation-specific skip reason.\"\"\"\n return \"Completed comprehensive test planning with full confidence locally\"\n\n def get_skip_expert_analysis_status(self) -> str:\n \"\"\"Test generation-specific expert analysis skip status.\"\"\"\n return \"skipped_due_to_certain_test_confidence\"\n\n def prepare_work_summary(self) -> str:\n \"\"\"Test generation-specific work summary.\"\"\"\n return self._build_test_generation_summary(self.consolidated_findings)\n\n def get_completion_next_steps_message(self, expert_analysis_used: bool = False) -> str:\n \"\"\"\n Test generation-specific completion message.\n \"\"\"\n base_message = (\n \"TEST GENERATION ANALYSIS IS COMPLETE. You MUST now implement ALL identified test scenarios, \"\n \"creating comprehensive test files that cover happy paths, edge cases, error conditions, and \"\n \"boundary scenarios. Organize tests by functionality, use appropriate assertions, and follow \"\n \"the identified framework patterns. Provide concrete, executable test codeβ€”make it easy for \"\n \"a developer to run the tests and understand what each test validates.\"\n )\n\n # Add expert analysis guidance only when expert analysis was actually used\n if expert_analysis_used:\n expert_guidance = self.get_expert_analysis_guidance()\n if expert_guidance:\n return f\"{base_message}\\\\n\\\\n{expert_guidance}\"\n\n return base_message\n\n def get_expert_analysis_guidance(self) -> str:\n \"\"\"\n Provide specific guidance for handling expert analysis in test generation.\n \"\"\"\n return (\n \"IMPORTANT: Additional test scenarios and edge cases have been provided by the expert analysis above. \"\n \"You MUST incorporate these suggestions into your test implementation, ensuring comprehensive coverage. \"\n \"Validate that the expert's test ideas are practical and align with the codebase structure. Combine \"\n \"your systematic investigation findings with the expert's additional scenarios to create a thorough \"\n \"test suite that catches real-world bugs before they reach production.\"\n )\n\n def get_step_guidance_message(self, request) -> str:\n \"\"\"\n Test generation-specific step guidance with detailed investigation instructions.\n \"\"\"\n step_guidance = self.get_test_generation_step_guidance(request.step_number, request.confidence, request)\n return step_guidance[\"next_steps\"]\n\n def get_test_generation_step_guidance(self, step_number: int, confidence: str, request) -> dict[str, Any]:\n \"\"\"\n Provide step-specific guidance for test generation workflow.\n \"\"\"\n # Generate the next steps instruction based on required actions\n required_actions = self.get_required_actions(step_number, confidence, request.findings, request.total_steps)\n\n if step_number == 1:\n next_steps = (\n f\"MANDATORY: DO NOT call the {self.get_name()} tool again immediately. You MUST first analyze \"\n f\"the code thoroughly using appropriate tools. CRITICAL AWARENESS: You need to understand \"\n f\"the code structure, identify testable behaviors, find edge cases and boundary conditions, \"\n f\"and determine the appropriate testing strategy. Use file reading tools, code analysis, and \"\n f\"systematic examination to gather comprehensive information about what needs to be tested. \"\n f\"Only call {self.get_name()} again AFTER completing your investigation. When you call \"\n f\"{self.get_name()} next time, use step_number: {step_number + 1} and report specific \"\n f\"code paths examined, test scenarios identified, and testing patterns discovered.\"\n )\n elif confidence in [\"exploring\", \"low\"]:\n next_steps = (\n f\"STOP! Do NOT call {self.get_name()} again yet. Based on your findings, you've identified areas that need \"\n f\"deeper analysis for test generation. MANDATORY ACTIONS before calling {self.get_name()} step {step_number + 1}:\\\\n\"\n + \"\\\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\\\n\\\\nOnly call {self.get_name()} again with step_number: {step_number + 1} AFTER \"\n + \"completing these test planning tasks.\"\n )\n elif confidence in [\"medium\", \"high\"]:\n next_steps = (\n f\"WAIT! Your test generation analysis needs final verification. DO NOT call {self.get_name()} immediately. REQUIRED ACTIONS:\\\\n\"\n + \"\\\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\\\n\\\\nREMEMBER: Ensure you have identified all test scenarios including edge cases and error conditions. \"\n f\"Document findings with specific test cases to implement, then call {self.get_name()} \"\n f\"with step_number: {step_number + 1}.\"\n )\n else:\n next_steps = (\n f\"PAUSE ANALYSIS. Before calling {self.get_name()} step {step_number + 1}, you MUST examine more code thoroughly. \"\n + \"Required: \"\n + \", \".join(required_actions[:2])\n + \". \"\n + f\"Your next {self.get_name()} call (step_number: {step_number + 1}) must include \"\n f\"NEW test scenarios from actual code analysis, not just theories. NO recursive {self.get_name()} calls \"\n f\"without investigation work!\"\n )\n\n return {\"next_steps\": next_steps}\n\n def customize_workflow_response(self, response_data: dict, request) -> dict:\n \"\"\"\n Customize response to match test generation workflow format.\n \"\"\"\n # Store initial request on first step\n if request.step_number == 1:\n self.initial_request = request.step\n\n # Convert generic status names to test generation-specific ones\n tool_name = self.get_name()\n status_mapping = {\n f\"{tool_name}_in_progress\": \"test_generation_in_progress\",\n f\"pause_for_{tool_name}\": \"pause_for_test_analysis\",\n f\"{tool_name}_required\": \"test_analysis_required\",\n f\"{tool_name}_complete\": \"test_generation_complete\",\n }\n\n if response_data[\"status\"] in status_mapping:\n response_data[\"status\"] = status_mapping[response_data[\"status\"]]\n\n # Rename status field to match test generation workflow\n if f\"{tool_name}_status\" in response_data:\n response_data[\"test_generation_status\"] = response_data.pop(f\"{tool_name}_status\")\n # Add test generation-specific status fields\n response_data[\"test_generation_status\"][\"test_scenarios_identified\"] = len(\n self.consolidated_findings.relevant_context\n )\n response_data[\"test_generation_status\"][\"analysis_confidence\"] = self.get_request_confidence(request)\n\n # Map complete_testgen to complete_test_generation\n if f\"complete_{tool_name}\" in response_data:\n response_data[\"complete_test_generation\"] = response_data.pop(f\"complete_{tool_name}\")\n\n # Map the completion flag to match test generation workflow\n if f\"{tool_name}_complete\" in response_data:\n response_data[\"test_generation_complete\"] = response_data.pop(f\"{tool_name}_complete\")\n\n return response_data\n\n # Required abstract methods from BaseTool\n def get_request_model(self):\n \"\"\"Return the test generation workflow-specific request model.\"\"\"\n return TestGenRequest\n\n async def prepare_prompt(self, request) -> str:\n \"\"\"Not used - workflow tools use execute_workflow().\"\"\"\n return \"\" # Workflow tools use execute_workflow() directly\n" }, { "path": "tools/thinkdeep.py", "content": "\"\"\"\nThinkDeep Workflow Tool - Extended Reasoning with Systematic Investigation\n\nThis tool provides step-by-step deep thinking capabilities using a systematic workflow approach.\nIt enables comprehensive analysis of complex problems with expert validation at completion.\n\nKey Features:\n- Systematic step-by-step thinking process\n- Multi-step analysis with evidence gathering\n- Confidence-based investigation flow\n- Expert analysis integration with external models\n- Support for focused analysis areas (architecture, performance, security, etc.)\n- Confidence-based workflow optimization\n\"\"\"\n\nimport logging\nfrom typing import TYPE_CHECKING, Any, Optional\n\nfrom pydantic import Field\n\nif TYPE_CHECKING:\n from tools.models import ToolModelCategory\n\nfrom config import TEMPERATURE_CREATIVE\nfrom systemprompts import THINKDEEP_PROMPT\nfrom tools.shared.base_models import WorkflowRequest\n\nfrom .workflow.base import WorkflowTool\n\nlogger = logging.getLogger(__name__)\n\n\nclass ThinkDeepWorkflowRequest(WorkflowRequest):\n \"\"\"Request model for thinkdeep workflow tool with comprehensive investigation capabilities\"\"\"\n\n # Core workflow parameters\n step: str = Field(description=\"Current work step content and findings\")\n step_number: int = Field(description=\"Current step number (starts at 1)\", ge=1)\n total_steps: int = Field(description=\"Estimated total steps needed\", ge=1)\n next_step_required: bool = Field(description=\"Whether another step is needed\")\n findings: str = Field(\n description=\"Discoveries: insights, connections, implications, evidence. \"\n \"Document contradictions to earlier assumptions. Update past findings.\"\n )\n\n # Investigation tracking\n files_checked: list[str] = Field(\n default_factory=list,\n description=\"All files examined (absolute paths). Include ruled-out files.\",\n )\n relevant_files: list[str] = Field(\n default_factory=list,\n description=\"Files relevant to problem/goal (absolute paths). Include root cause, solution, key insights.\",\n )\n relevant_context: list[str] = Field(\n default_factory=list,\n description=\"Key concepts/methods: 'concept_name' or 'ClassName.methodName'. Focus on core insights, decision points.\",\n )\n hypothesis: Optional[str] = Field(\n default=None,\n description=\"Current theory based on evidence. Revise in later steps.\",\n )\n\n # Analysis metadata\n issues_found: list[dict] = Field(\n default_factory=list,\n description=\"Issues with dict: 'severity' (critical/high/medium/low), 'description'.\",\n )\n confidence: str = Field(\n default=\"low\",\n description=\"exploring/low/medium/high/very_high/almost_certain/certain. CRITICAL: 'certain' PREVENTS external validation.\",\n )\n\n # Expert analysis configuration - keep these fields available for configuring the final assistant model\n # in expert analysis (commented out exclude=True)\n temperature: Optional[float] = Field(\n default=None,\n description=\"Creative thinking temp (0-1, default 0.7)\",\n ge=0.0,\n le=1.0,\n )\n thinking_mode: Optional[str] = Field(\n default=None,\n description=\"Depth: minimal/low/medium/high/max. Default 'high'.\",\n )\n # Context files and investigation scope\n problem_context: Optional[str] = Field(\n default=None,\n description=\"Additional context about problem/goal. Be expressive.\",\n )\n focus_areas: Optional[list[str]] = Field(\n default=None,\n description=\"Focus aspects (architecture, performance, security, etc.)\",\n )\n\n\nclass ThinkDeepTool(WorkflowTool):\n \"\"\"\n ThinkDeep Workflow Tool - Systematic Deep Thinking Analysis\n\n Provides comprehensive step-by-step thinking capabilities with expert validation.\n Uses workflow architecture for systematic investigation and analysis.\n \"\"\"\n\n name = \"thinkdeep\"\n description = (\n \"Performs multi-stage investigation and reasoning for complex problem analysis. \"\n \"Use for architecture decisions, complex bugs, performance challenges, and security analysis. \"\n \"Provides systematic hypothesis testing, evidence-based investigation, and expert validation.\"\n )\n\n def __init__(self):\n \"\"\"Initialize the ThinkDeep workflow tool\"\"\"\n super().__init__()\n # Storage for request parameters to use in expert analysis\n self.stored_request_params = {}\n\n def get_name(self) -> str:\n \"\"\"Return the tool name\"\"\"\n return self.name\n\n def get_description(self) -> str:\n \"\"\"Return the tool description\"\"\"\n return self.description\n\n def get_model_category(self) -> \"ToolModelCategory\":\n \"\"\"Return the model category for this tool\"\"\"\n from tools.models import ToolModelCategory\n\n return ToolModelCategory.EXTENDED_REASONING\n\n def get_workflow_request_model(self):\n \"\"\"Return the workflow request model for this tool\"\"\"\n return ThinkDeepWorkflowRequest\n\n def get_input_schema(self) -> dict[str, Any]:\n \"\"\"Generate input schema using WorkflowSchemaBuilder with thinkdeep-specific overrides.\"\"\"\n from .workflow.schema_builders import WorkflowSchemaBuilder\n\n # ThinkDeep workflow-specific field overrides\n thinkdeep_field_overrides = {\n \"problem_context\": {\n \"type\": \"string\",\n \"description\": \"Additional context about problem/goal. Be expressive.\",\n },\n \"focus_areas\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": \"Focus aspects (architecture, performance, security, etc.)\",\n },\n }\n\n # Use WorkflowSchemaBuilder with thinkdeep-specific tool fields\n return WorkflowSchemaBuilder.build_schema(\n tool_specific_fields=thinkdeep_field_overrides,\n model_field_schema=self.get_model_field_schema(),\n auto_mode=self.is_effective_auto_mode(),\n tool_name=self.get_name(),\n )\n\n def get_system_prompt(self) -> str:\n \"\"\"Return the system prompt for this workflow tool\"\"\"\n return THINKDEEP_PROMPT\n\n def get_default_temperature(self) -> float:\n \"\"\"Return default temperature for deep thinking\"\"\"\n return TEMPERATURE_CREATIVE\n\n def get_default_thinking_mode(self) -> str:\n \"\"\"Return default thinking mode for thinkdeep\"\"\"\n from config import DEFAULT_THINKING_MODE_THINKDEEP\n\n return DEFAULT_THINKING_MODE_THINKDEEP\n\n def customize_workflow_response(self, response_data: dict, request, **kwargs) -> dict:\n \"\"\"\n Customize the workflow response for thinkdeep-specific needs\n \"\"\"\n # Store request parameters for later use in expert analysis\n self.stored_request_params = {}\n try:\n self.stored_request_params[\"temperature\"] = request.temperature\n except AttributeError:\n self.stored_request_params[\"temperature\"] = None\n\n try:\n self.stored_request_params[\"thinking_mode\"] = request.thinking_mode\n except AttributeError:\n self.stored_request_params[\"thinking_mode\"] = None\n\n # Add thinking-specific context to response\n response_data.update(\n {\n \"thinking_status\": {\n \"current_step\": request.step_number,\n \"total_steps\": request.total_steps,\n \"files_checked\": len(request.files_checked),\n \"relevant_files\": len(request.relevant_files),\n \"thinking_confidence\": request.confidence,\n \"analysis_focus\": request.focus_areas or [\"general\"],\n }\n }\n )\n\n # Add thinking_complete field for final steps (test expects this)\n if not request.next_step_required:\n response_data[\"thinking_complete\"] = True\n\n # Add complete_thinking summary (test expects this)\n response_data[\"complete_thinking\"] = {\n \"steps_completed\": len(self.work_history),\n \"final_confidence\": request.confidence,\n \"relevant_context\": list(self.consolidated_findings.relevant_context),\n \"key_findings\": self.consolidated_findings.findings,\n \"issues_identified\": self.consolidated_findings.issues_found,\n \"files_analyzed\": list(self.consolidated_findings.relevant_files),\n }\n\n # Add thinking-specific completion message based on confidence\n if request.confidence == \"certain\":\n response_data[\"completion_message\"] = (\n \"Deep thinking analysis is complete with high certainty. \"\n \"All aspects have been thoroughly considered and conclusions are definitive.\"\n )\n elif not request.next_step_required:\n response_data[\"completion_message\"] = (\n \"Deep thinking analysis phase complete. Expert validation will provide additional insights and recommendations.\"\n )\n\n return response_data\n\n def should_skip_expert_analysis(self, request, consolidated_findings) -> bool:\n \"\"\"\n ThinkDeep tool skips expert analysis when the CLI agent has \"certain\" confidence.\n \"\"\"\n return request.confidence == \"certain\" and not request.next_step_required\n\n def get_completion_status(self) -> str:\n \"\"\"ThinkDeep tools use thinking-specific status.\"\"\"\n return \"deep_thinking_complete_ready_for_implementation\"\n\n def get_completion_data_key(self) -> str:\n \"\"\"ThinkDeep uses 'complete_thinking' key.\"\"\"\n return \"complete_thinking\"\n\n def get_final_analysis_from_request(self, request):\n \"\"\"ThinkDeep tools use 'findings' field.\"\"\"\n return request.findings\n\n def get_skip_expert_analysis_status(self) -> str:\n \"\"\"Status when skipping expert analysis for certain confidence.\"\"\"\n return \"skipped_due_to_certain_thinking_confidence\"\n\n def get_skip_reason(self) -> str:\n \"\"\"Reason for skipping expert analysis.\"\"\"\n return \"Expressed 'certain' confidence in the deep thinking analysis - no additional validation needed\"\n\n def get_completion_message(self) -> str:\n \"\"\"Message for completion without expert analysis.\"\"\"\n return \"Deep thinking analysis complete with certain confidence. Proceed with implementation based on the analysis.\"\n\n def customize_expert_analysis_prompt(self, base_prompt: str, request, file_content: str = \"\") -> str:\n \"\"\"\n Customize the expert analysis prompt for deep thinking validation\n \"\"\"\n thinking_context = f\"\"\"\nDEEP THINKING ANALYSIS VALIDATION\n\nYou are reviewing a comprehensive deep thinking analysis completed through systematic investigation.\nYour role is to validate the thinking process, identify any gaps, challenge assumptions, and provide\nadditional insights or alternative perspectives.\n\nANALYSIS SCOPE:\n- Problem Context: {self._get_problem_context(request)}\n- Focus Areas: {', '.join(self._get_focus_areas(request))}\n- Investigation Confidence: {request.confidence}\n- Steps Completed: {request.step_number} of {request.total_steps}\n\nTHINKING SUMMARY:\n{request.findings}\n\nKEY INSIGHTS AND CONTEXT:\n{', '.join(request.relevant_context) if request.relevant_context else 'No specific context identified'}\n\nVALIDATION OBJECTIVES:\n1. Assess the depth and quality of the thinking process\n2. Identify any logical gaps, missing considerations, or flawed assumptions\n3. Suggest alternative approaches or perspectives not considered\n4. Validate the conclusions and recommendations\n5. Provide actionable next steps for implementation\n\nBe thorough but constructive in your analysis. Challenge the thinking where appropriate,\nbut also acknowledge strong insights and valid conclusions.\n\"\"\"\n\n if file_content:\n thinking_context += f\"\\n\\nFILE CONTEXT:\\n{file_content}\"\n\n return f\"{thinking_context}\\n\\n{base_prompt}\"\n\n def get_expert_analysis_instructions(self) -> str:\n \"\"\"\n Return instructions for expert analysis specific to deep thinking validation\n \"\"\"\n return (\n \"DEEP THINKING ANALYSIS IS COMPLETE. You MUST now summarize and present ALL thinking insights, \"\n \"alternative approaches considered, risks and trade-offs identified, and final recommendations. \"\n \"Clearly prioritize the top solutions or next steps that emerged from the analysis. \"\n \"Provide concrete, actionable guidance based on the deep thinkingβ€”make it easy for the user to \"\n \"understand exactly what to do next and how to implement the best solution.\"\n )\n\n # Override hook methods to use stored request parameters for expert analysis\n\n def get_request_temperature(self, request) -> float:\n \"\"\"Use stored temperature from initial request.\"\"\"\n try:\n stored_params = self.stored_request_params\n if stored_params and stored_params.get(\"temperature\") is not None:\n return stored_params[\"temperature\"]\n except AttributeError:\n pass\n return super().get_request_temperature(request)\n\n def get_request_thinking_mode(self, request) -> str:\n \"\"\"Use stored thinking mode from initial request.\"\"\"\n try:\n stored_params = self.stored_request_params\n if stored_params and stored_params.get(\"thinking_mode\") is not None:\n return stored_params[\"thinking_mode\"]\n except AttributeError:\n pass\n return super().get_request_thinking_mode(request)\n\n def _get_problem_context(self, request) -> str:\n \"\"\"Get problem context from request. Override for custom context handling.\"\"\"\n try:\n return request.problem_context or \"General analysis\"\n except AttributeError:\n return \"General analysis\"\n\n def _get_focus_areas(self, request) -> list[str]:\n \"\"\"Get focus areas from request. Override for custom focus area handling.\"\"\"\n try:\n return request.focus_areas or [\"comprehensive analysis\"]\n except AttributeError:\n return [\"comprehensive analysis\"]\n\n def get_required_actions(\n self, step_number: int, confidence: str, findings: str, total_steps: int, request=None\n ) -> list[str]:\n \"\"\"\n Return required actions for the current thinking step.\n \"\"\"\n actions = []\n\n if step_number == 1:\n actions.extend(\n [\n \"Begin systematic thinking analysis\",\n \"Identify key aspects and assumptions to explore\",\n \"Establish initial investigation approach\",\n ]\n )\n elif confidence == \"low\":\n actions.extend(\n [\n \"Continue gathering evidence and insights\",\n \"Test initial hypotheses\",\n \"Explore alternative perspectives\",\n ]\n )\n elif confidence == \"medium\":\n actions.extend(\n [\n \"Deepen analysis of promising approaches\",\n \"Validate key assumptions\",\n \"Consider implementation challenges\",\n ]\n )\n elif confidence == \"high\":\n actions.extend(\n [\n \"Refine and validate key findings\",\n \"Explore edge cases and limitations\",\n \"Document assumptions and trade-offs\",\n ]\n )\n elif confidence == \"very_high\":\n actions.extend(\n [\n \"Synthesize findings into cohesive recommendations\",\n \"Validate conclusions against all evidence\",\n \"Prepare comprehensive implementation guidance\",\n ]\n )\n elif confidence == \"almost_certain\":\n actions.extend(\n [\n \"Finalize recommendations with high confidence\",\n \"Document any remaining minor uncertainties\",\n \"Prepare for expert analysis or implementation\",\n ]\n )\n else: # certain\n actions.append(\"Analysis complete - ready for implementation\")\n\n return actions\n\n def should_call_expert_analysis(self, consolidated_findings, request=None) -> bool:\n \"\"\"\n Determine if expert analysis should be called based on confidence and completion.\n \"\"\"\n if request:\n try:\n # Don't call expert analysis if confidence is \"certain\"\n if request.confidence == \"certain\":\n return False\n except AttributeError:\n pass\n\n # Call expert analysis if investigation is complete (when next_step_required is False)\n if request:\n try:\n return not request.next_step_required\n except AttributeError:\n pass\n\n # Fallback: call expert analysis if we have meaningful findings\n return (\n len(consolidated_findings.relevant_files) > 0\n or len(consolidated_findings.findings) >= 2\n or len(consolidated_findings.issues_found) > 0\n )\n\n def prepare_expert_analysis_context(self, consolidated_findings) -> str:\n \"\"\"\n Prepare context for expert analysis specific to deep thinking.\n \"\"\"\n context_parts = []\n\n context_parts.append(\"DEEP THINKING ANALYSIS SUMMARY:\")\n context_parts.append(f\"Steps completed: {len(consolidated_findings.findings)}\")\n context_parts.append(f\"Final confidence: {consolidated_findings.confidence}\")\n\n if consolidated_findings.findings:\n context_parts.append(\"\\nKEY FINDINGS:\")\n for i, finding in enumerate(consolidated_findings.findings, 1):\n context_parts.append(f\"{i}. {finding}\")\n\n if consolidated_findings.relevant_context:\n context_parts.append(f\"\\nRELEVANT CONTEXT:\\n{', '.join(consolidated_findings.relevant_context)}\")\n\n # Get hypothesis from latest hypotheses entry if available\n if consolidated_findings.hypotheses:\n latest_hypothesis = consolidated_findings.hypotheses[-1].get(\"hypothesis\", \"\")\n if latest_hypothesis:\n context_parts.append(f\"\\nFINAL HYPOTHESIS:\\n{latest_hypothesis}\")\n\n if consolidated_findings.issues_found:\n context_parts.append(f\"\\nISSUES IDENTIFIED: {len(consolidated_findings.issues_found)} issues\")\n for issue in consolidated_findings.issues_found:\n context_parts.append(\n f\"- {issue.get('severity', 'unknown')}: {issue.get('description', 'No description')}\"\n )\n\n return \"\\n\".join(context_parts)\n\n def get_step_guidance_message(self, request) -> str:\n \"\"\"\n Generate guidance for the next step in thinking analysis\n \"\"\"\n if request.next_step_required:\n next_step_number = request.step_number + 1\n\n if request.confidence == \"certain\":\n guidance = (\n f\"Your thinking analysis confidence is CERTAIN. Consider if you truly need step {next_step_number} \"\n f\"or if you should complete the analysis now with expert validation.\"\n )\n elif request.confidence == \"almost_certain\":\n guidance = (\n f\"Your thinking analysis confidence is ALMOST_CERTAIN. For step {next_step_number}, consider: \"\n f\"finalizing recommendations, documenting any minor uncertainties, or preparing for implementation.\"\n )\n elif request.confidence == \"very_high\":\n guidance = (\n f\"Your thinking analysis confidence is VERY_HIGH. For step {next_step_number}, consider: \"\n f\"synthesis of all findings, comprehensive validation, or creating implementation roadmap.\"\n )\n elif request.confidence == \"high\":\n guidance = (\n f\"Your thinking analysis confidence is HIGH. For step {next_step_number}, consider: \"\n f\"exploring edge cases, documenting trade-offs, or stress-testing key assumptions.\"\n )\n elif request.confidence == \"medium\":\n guidance = (\n f\"Your thinking analysis confidence is MEDIUM. For step {next_step_number}, focus on: \"\n f\"deepening insights, exploring alternative approaches, or gathering additional evidence.\"\n )\n else: # low or exploring\n guidance = (\n f\"Your thinking analysis confidence is {request.confidence.upper()}. For step {next_step_number}, \"\n f\"continue investigating: gather more evidence, test hypotheses, or explore different angles.\"\n )\n\n # Add specific thinking guidance based on progress\n if request.step_number == 1:\n guidance += (\n \" Consider: What are the key assumptions? What evidence supports or contradicts initial theories? \"\n \"What alternative approaches exist?\"\n )\n elif request.step_number >= request.total_steps // 2:\n guidance += (\n \" Consider: Synthesis of findings, validation of conclusions, identification of implementation \"\n \"challenges, and preparation for expert analysis.\"\n )\n\n return guidance\n else:\n return \"Thinking analysis is ready for expert validation and final recommendations.\"\n\n def format_final_response(self, assistant_response: str, request, **kwargs) -> dict:\n \"\"\"\n Format the final response from the assistant for thinking analysis\n \"\"\"\n response_data = {\n \"thinking_analysis\": assistant_response,\n \"analysis_metadata\": {\n \"total_steps_completed\": request.step_number,\n \"final_confidence\": request.confidence,\n \"files_analyzed\": len(request.relevant_files),\n \"key_insights\": len(request.relevant_context),\n \"issues_identified\": len(request.issues_found),\n },\n }\n\n # Add completion status\n if request.confidence == \"certain\":\n response_data[\"completion_status\"] = \"analysis_complete_with_certainty\"\n else:\n response_data[\"completion_status\"] = \"analysis_complete_pending_validation\"\n\n return response_data\n\n def format_step_response(\n self,\n assistant_response: str,\n request,\n status: str = \"pause_for_thinkdeep\",\n continuation_id: Optional[str] = None,\n **kwargs,\n ) -> dict:\n \"\"\"\n Format intermediate step responses for thinking workflow\n \"\"\"\n response_data = super().format_step_response(assistant_response, request, status, continuation_id, **kwargs)\n\n # Add thinking-specific step guidance\n step_guidance = self.get_step_guidance_message(request)\n response_data[\"thinking_guidance\"] = step_guidance\n\n # Add analysis progress indicators\n response_data[\"analysis_progress\"] = {\n \"step_completed\": request.step_number,\n \"remaining_steps\": max(0, request.total_steps - request.step_number),\n \"confidence_trend\": request.confidence,\n \"investigation_depth\": \"expanding\" if request.next_step_required else \"finalizing\",\n }\n\n return response_data\n\n # Required abstract methods from BaseTool\n def get_request_model(self):\n \"\"\"Return the thinkdeep workflow-specific request model.\"\"\"\n return ThinkDeepWorkflowRequest\n\n async def prepare_prompt(self, request) -> str:\n \"\"\"Not used - workflow tools use execute_workflow().\"\"\"\n return \"\" # Workflow tools use execute_workflow() directly\n" }, { "path": "tools/tracer.py", "content": "\"\"\"\nTracer Workflow tool - Step-by-step code tracing and dependency analysis\n\nThis tool provides a structured workflow for comprehensive code tracing and analysis.\nIt guides the CLI agent through systematic investigation steps with forced pauses between each step\nto ensure thorough code examination, dependency mapping, and execution flow analysis before proceeding.\n\nThe tracer guides users through sequential code analysis with full context awareness and\nthe ability to revise and adapt as understanding deepens.\n\nKey features:\n- Sequential tracing with systematic investigation workflow\n- Support for precision tracing (execution flow) and dependencies tracing (structural relationships)\n- Self-contained completion with detailed output formatting instructions\n- Context-aware analysis that builds understanding step by step\n- No external expert analysis needed - provides comprehensive guidance internally\n\nPerfect for: method/function execution flow analysis, dependency mapping, call chain tracing,\nstructural relationship analysis, architectural understanding, and code comprehension.\n\"\"\"\n\nimport logging\nfrom typing import TYPE_CHECKING, Any, Literal, Optional\n\nfrom pydantic import Field, field_validator\n\nif TYPE_CHECKING:\n from tools.models import ToolModelCategory\n\nfrom config import TEMPERATURE_ANALYTICAL\nfrom systemprompts import TRACER_PROMPT\nfrom tools.shared.base_models import WorkflowRequest\n\nfrom .workflow.base import WorkflowTool\n\nlogger = logging.getLogger(__name__)\n\n# Tool-specific field descriptions for tracer workflow\nTRACER_WORKFLOW_FIELD_DESCRIPTIONS = {\n \"step\": (\n \"The plan for the current tracing step. Step 1: State the tracing strategy. Later steps: Report findings and adapt the plan. \"\n \"CRITICAL: For 'precision' mode, focus on execution flow and call chains. For 'dependencies' mode, focus on structural relationships. \"\n \"If trace_mode is 'ask' in step 1, you MUST prompt the user to choose a mode.\"\n ),\n \"step_number\": (\n \"The index of the current step in the tracing sequence, beginning at 1. Each step should build upon or \"\n \"revise the previous one.\"\n ),\n \"total_steps\": (\n \"Your current estimate for how many steps will be needed to complete the tracing analysis. \"\n \"Adjust as new findings emerge.\"\n ),\n \"next_step_required\": (\n \"Set to true if you plan to continue the investigation with another step. False means you believe the \"\n \"tracing analysis is complete and ready for final output formatting.\"\n ),\n \"findings\": (\n \"Summary of discoveries from this step, including execution paths, dependency relationships, call chains, and structural patterns. \"\n \"IMPORTANT: Document both direct (immediate calls) and indirect (transitive, side effects) relationships.\"\n ),\n \"files_checked\": (\n \"List all files examined (absolute paths). Include even ruled-out files to track exploration path.\"\n ),\n \"relevant_files\": (\n \"Subset of files_checked directly relevant to the tracing target (absolute paths). Include implementation files, \"\n \"dependencies, or files demonstrating key relationships.\"\n ),\n \"relevant_context\": (\n \"List methods/functions central to the tracing analysis, in 'ClassName.methodName' or 'functionName' format. \"\n \"Prioritize those in the execution flow or dependency chain.\"\n ),\n \"confidence\": (\n \"Your confidence in the tracing analysis. Use: 'exploring', 'low', 'medium', 'high', 'very_high', 'almost_certain', 'certain'. \"\n \"CRITICAL: 'certain' implies the analysis is 100% complete locally and PREVENTS external model validation.\"\n ),\n \"trace_mode\": \"Type of tracing: 'ask' (default - prompts user to choose mode), 'precision' (execution flow) or 'dependencies' (structural relationships)\",\n \"target_description\": (\n \"Description of what to trace and WHY. Include context about what you're trying to understand or analyze.\"\n ),\n \"images\": (\"Optional paths to architecture diagrams or flow charts that help understand the tracing context.\"),\n}\n\n\nclass TracerRequest(WorkflowRequest):\n \"\"\"Request model for tracer workflow investigation steps\"\"\"\n\n # Required fields for each investigation step\n step: str = Field(..., description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS[\"step\"])\n step_number: int = Field(..., description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS[\"step_number\"])\n total_steps: int = Field(..., description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS[\"total_steps\"])\n next_step_required: bool = Field(..., description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS[\"next_step_required\"])\n\n # Investigation tracking fields\n findings: str = Field(..., description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS[\"findings\"])\n files_checked: list[str] = Field(\n default_factory=list, description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS[\"files_checked\"]\n )\n relevant_files: list[str] = Field(\n default_factory=list, description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_files\"]\n )\n relevant_context: list[str] = Field(\n default_factory=list, description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_context\"]\n )\n confidence: Optional[str] = Field(\"exploring\", description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS[\"confidence\"])\n\n # Tracer-specific fields (used in step 1 to initialize)\n trace_mode: Optional[Literal[\"precision\", \"dependencies\", \"ask\"]] = Field(\n \"ask\", description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS[\"trace_mode\"]\n )\n target_description: Optional[str] = Field(\n None, description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS[\"target_description\"]\n )\n images: Optional[list[str]] = Field(default=None, description=TRACER_WORKFLOW_FIELD_DESCRIPTIONS[\"images\"])\n\n # Exclude fields not relevant to tracing workflow\n issues_found: list[dict] = Field(default_factory=list, exclude=True, description=\"Tracing doesn't track issues\")\n hypothesis: Optional[str] = Field(default=None, exclude=True, description=\"Tracing doesn't use hypothesis\")\n # Exclude other non-tracing fields\n temperature: Optional[float] = Field(default=None, exclude=True)\n thinking_mode: Optional[str] = Field(default=None, exclude=True)\n use_assistant_model: Optional[bool] = Field(default=False, exclude=True, description=\"Tracing is self-contained\")\n\n @field_validator(\"step_number\")\n @classmethod\n def validate_step_number(cls, v):\n if v < 1:\n raise ValueError(\"step_number must be at least 1\")\n return v\n\n @field_validator(\"total_steps\")\n @classmethod\n def validate_total_steps(cls, v):\n if v < 1:\n raise ValueError(\"total_steps must be at least 1\")\n return v\n\n\nclass TracerTool(WorkflowTool):\n \"\"\"\n Tracer workflow tool for step-by-step code tracing and dependency analysis.\n\n This tool implements a structured tracing workflow that guides users through\n methodical investigation steps, ensuring thorough code examination, dependency\n mapping, and execution flow analysis before reaching conclusions. It supports\n both precision tracing (execution flow) and dependencies tracing (structural relationships).\n \"\"\"\n\n def __init__(self):\n super().__init__()\n self.initial_request = None\n self.trace_config = {}\n\n def get_name(self) -> str:\n return \"tracer\"\n\n def get_description(self) -> str:\n return (\n \"Performs systematic code tracing with modes for execution flow or dependency mapping. \"\n \"Use for method execution analysis, call chain tracing, dependency mapping, and architectural understanding. \"\n \"Supports precision mode (execution flow) and dependencies mode (structural relationships).\"\n )\n\n def get_system_prompt(self) -> str:\n return TRACER_PROMPT\n\n def get_default_temperature(self) -> float:\n return TEMPERATURE_ANALYTICAL\n\n def get_model_category(self) -> \"ToolModelCategory\":\n \"\"\"Tracer requires analytical reasoning for code analysis\"\"\"\n from tools.models import ToolModelCategory\n\n return ToolModelCategory.EXTENDED_REASONING\n\n def requires_model(self) -> bool:\n \"\"\"\n Tracer tool doesn't require model resolution at the MCP boundary.\n\n The tracer is a structured workflow tool that organizes tracing steps\n and provides detailed output formatting guidance without calling external AI models.\n\n Returns:\n bool: False - tracer doesn't need AI model access\n \"\"\"\n return False\n\n def get_workflow_request_model(self):\n \"\"\"Return the tracer-specific request model.\"\"\"\n return TracerRequest\n\n def get_tool_fields(self) -> dict[str, dict[str, Any]]:\n \"\"\"Return tracing-specific field definitions beyond the standard workflow fields.\"\"\"\n return {\n # Tracer-specific fields\n \"trace_mode\": {\n \"type\": \"string\",\n \"enum\": [\"precision\", \"dependencies\", \"ask\"],\n \"description\": TRACER_WORKFLOW_FIELD_DESCRIPTIONS[\"trace_mode\"],\n },\n \"target_description\": {\n \"type\": \"string\",\n \"description\": TRACER_WORKFLOW_FIELD_DESCRIPTIONS[\"target_description\"],\n },\n \"images\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": TRACER_WORKFLOW_FIELD_DESCRIPTIONS[\"images\"],\n },\n }\n\n def get_input_schema(self) -> dict[str, Any]:\n \"\"\"Generate input schema using WorkflowSchemaBuilder with field exclusion.\"\"\"\n from .workflow.schema_builders import WorkflowSchemaBuilder\n\n # Exclude investigation-specific fields that tracing doesn't need\n excluded_workflow_fields = [\n \"issues_found\", # Tracing doesn't track issues\n \"hypothesis\", # Tracing doesn't use hypothesis\n ]\n\n # Exclude common fields that tracing doesn't need\n excluded_common_fields = [\n \"temperature\", # Tracing doesn't need temperature control\n \"thinking_mode\", # Tracing doesn't need thinking mode\n \"absolute_file_paths\", # Tracing uses relevant_files instead\n ]\n\n return WorkflowSchemaBuilder.build_schema(\n tool_specific_fields=self.get_tool_fields(),\n required_fields=[\"target_description\", \"trace_mode\"], # Step 1 requires these\n model_field_schema=self.get_model_field_schema(),\n auto_mode=self.is_effective_auto_mode(),\n tool_name=self.get_name(),\n excluded_workflow_fields=excluded_workflow_fields,\n excluded_common_fields=excluded_common_fields,\n )\n\n # ================================================================================\n # Abstract Methods - Required Implementation from BaseWorkflowMixin\n # ================================================================================\n\n def get_required_actions(\n self, step_number: int, confidence: str, findings: str, total_steps: int, request=None\n ) -> list[str]:\n \"\"\"Define required actions for each tracing phase.\"\"\"\n if step_number == 1:\n # Check if we're in ask mode and need to prompt for mode selection\n if self.get_trace_mode() == \"ask\":\n return [\n \"MUST ask user to choose between precision or dependencies mode\",\n \"Explain precision mode: traces execution flow, call chains, and usage patterns (best for methods/functions)\",\n \"Explain dependencies mode: maps structural relationships and bidirectional dependencies (best for classes/modules)\",\n \"Wait for user's mode selection before proceeding with investigation\",\n ]\n\n # Initial tracing investigation tasks (when mode is already selected)\n return [\n \"Search for and locate the target method/function/class/module in the codebase\",\n \"Read and understand the implementation of the target code\",\n \"Identify the file location, complete signature, and basic structure\",\n \"Begin mapping immediate relationships (what it calls, what calls it)\",\n \"Understand the context and purpose of the target code\",\n ]\n elif confidence in [\"exploring\", \"low\"]:\n # Need deeper investigation\n return [\n \"Trace deeper into the execution flow or dependency relationships\",\n \"Examine how the target code is used throughout the codebase\",\n \"Map additional layers of dependencies or call chains\",\n \"Look for conditional execution paths, error handling, and edge cases\",\n \"Understand the broader architectural context and patterns\",\n ]\n elif confidence in [\"medium\", \"high\"]:\n # Close to completion - need final verification\n return [\n \"Verify completeness of the traced relationships and execution paths\",\n \"Check for any missed dependencies, usage patterns, or execution branches\",\n \"Confirm understanding of side effects, state changes, and external interactions\",\n \"Validate that the tracing covers all significant code relationships\",\n \"Prepare comprehensive findings for final output formatting\",\n ]\n else:\n # General investigation needed\n return [\n \"Continue systematic tracing of code relationships and execution paths\",\n \"Gather more evidence using appropriate code analysis techniques\",\n \"Test assumptions about code behavior and dependency relationships\",\n \"Look for patterns that enhance understanding of the code structure\",\n \"Focus on areas that haven't been thoroughly traced yet\",\n ]\n\n def should_call_expert_analysis(self, consolidated_findings, request=None) -> bool:\n \"\"\"Tracer is self-contained and doesn't need expert analysis.\"\"\"\n return False\n\n def prepare_expert_analysis_context(self, consolidated_findings) -> str:\n \"\"\"Tracer doesn't use expert analysis.\"\"\"\n return \"\"\n\n def requires_expert_analysis(self) -> bool:\n \"\"\"Tracer is self-contained like the planner tool.\"\"\"\n return False\n\n # ================================================================================\n # Workflow Customization - Match Planner Behavior\n # ================================================================================\n\n def prepare_step_data(self, request) -> dict:\n \"\"\"\n Prepare step data from request with tracer-specific fields.\n \"\"\"\n step_data = {\n \"step\": request.step,\n \"step_number\": request.step_number,\n \"findings\": request.findings,\n \"files_checked\": request.files_checked,\n \"relevant_files\": request.relevant_files,\n \"relevant_context\": request.relevant_context,\n \"issues_found\": [], # Tracer doesn't track issues\n \"confidence\": request.confidence or \"exploring\",\n \"hypothesis\": None, # Tracer doesn't use hypothesis\n \"images\": request.images or [],\n # Tracer-specific fields\n \"trace_mode\": request.trace_mode,\n \"target_description\": request.target_description,\n }\n return step_data\n\n def build_base_response(self, request, continuation_id: str = None) -> dict:\n \"\"\"\n Build the base response structure with tracer-specific fields.\n \"\"\"\n # Use work_history from workflow mixin for consistent step tracking\n current_step_count = len(self.work_history) + 1\n\n response_data = {\n \"status\": f\"{self.get_name()}_in_progress\",\n \"step_number\": request.step_number,\n \"total_steps\": request.total_steps,\n \"next_step_required\": request.next_step_required,\n \"step_content\": request.step,\n f\"{self.get_name()}_status\": {\n \"files_checked\": len(self.consolidated_findings.files_checked),\n \"relevant_files\": len(self.consolidated_findings.relevant_files),\n \"relevant_context\": len(self.consolidated_findings.relevant_context),\n \"issues_found\": len(self.consolidated_findings.issues_found),\n \"images_collected\": len(self.consolidated_findings.images),\n \"current_confidence\": self.get_request_confidence(request),\n \"step_history_length\": current_step_count,\n },\n \"metadata\": {\n \"trace_mode\": self.trace_config.get(\"trace_mode\", \"unknown\"),\n \"target_description\": self.trace_config.get(\"target_description\", \"\"),\n \"step_history_length\": current_step_count,\n },\n }\n\n if continuation_id:\n response_data[\"continuation_id\"] = continuation_id\n\n return response_data\n\n def handle_work_continuation(self, response_data: dict, request) -> dict:\n \"\"\"\n Handle work continuation with tracer-specific guidance.\n \"\"\"\n response_data[\"status\"] = f\"pause_for_{self.get_name()}\"\n response_data[f\"{self.get_name()}_required\"] = True\n\n # Get tracer-specific required actions\n required_actions = self.get_required_actions(\n request.step_number, request.confidence or \"exploring\", request.findings, request.total_steps\n )\n response_data[\"required_actions\"] = required_actions\n\n # Generate step-specific guidance\n if request.step_number == 1:\n # Check if we're in ask mode and need to prompt for mode selection\n if self.get_trace_mode() == \"ask\":\n response_data[\"next_steps\"] = (\n f\"STOP! You MUST ask the user to choose a tracing mode before proceeding. \"\n f\"Present these options clearly:\\\\n\\\\n\"\n f\"**PRECISION MODE**: Traces execution flow, call chains, and usage patterns. \"\n f\"Best for understanding how a specific method or function works, what it calls, \"\n f\"and how data flows through the execution path.\\\\n\\\\n\"\n f\"**DEPENDENCIES MODE**: Maps structural relationships and bidirectional dependencies. \"\n f\"Best for understanding how a class or module relates to other components, \"\n f\"what depends on it, and what it depends on.\\\\n\\\\n\"\n f\"After the user selects a mode, call {self.get_name()} again with step_number: 1 \"\n f\"but with the chosen trace_mode (either 'precision' or 'dependencies').\"\n )\n else:\n response_data[\"next_steps\"] = (\n f\"MANDATORY: DO NOT call the {self.get_name()} tool again immediately. You MUST first investigate \"\n f\"the codebase to understand the target code. CRITICAL AWARENESS: You need to find and understand \"\n f\"the target method/function/class/module, examine its implementation, and begin mapping its \"\n f\"relationships. Use file reading tools, code search, and systematic examination to gather \"\n f\"comprehensive information about the target. Only call {self.get_name()} again AFTER completing \"\n f\"your investigation. When you call {self.get_name()} next time, use step_number: {request.step_number + 1} \"\n f\"and report specific files examined, code structure discovered, and initial relationship findings.\"\n )\n elif request.confidence in [\"exploring\", \"low\"]:\n next_step = request.step_number + 1\n response_data[\"next_steps\"] = (\n f\"STOP! Do NOT call {self.get_name()} again yet. Based on your findings, you've identified areas that need \"\n f\"deeper tracing analysis. MANDATORY ACTIONS before calling {self.get_name()} step {next_step}:\\\\n\"\n + \"\\\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\\\n\\\\nOnly call {self.get_name()} again with step_number: {next_step} AFTER \"\n + \"completing these tracing investigations.\"\n )\n elif request.confidence in [\"medium\", \"high\"]:\n next_step = request.step_number + 1\n response_data[\"next_steps\"] = (\n f\"WAIT! Your tracing analysis needs final verification. DO NOT call {self.get_name()} immediately. \"\n f\"REQUIRED ACTIONS:\\\\n\"\n + \"\\\\n\".join(f\"{i+1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\\\n\\\\nREMEMBER: Ensure you have traced all significant relationships and execution paths. \"\n f\"Document findings with specific file references and method signatures, then call {self.get_name()} \"\n f\"with step_number: {next_step}.\"\n )\n else:\n # General investigation needed\n next_step = request.step_number + 1\n remaining_steps = request.total_steps - request.step_number\n response_data[\"next_steps\"] = (\n f\"Continue systematic tracing with step {next_step}. Approximately {remaining_steps} steps remaining. \"\n f\"Focus on deepening your understanding of the code relationships and execution patterns.\"\n )\n\n return response_data\n\n def customize_workflow_response(self, response_data: dict, request) -> dict:\n \"\"\"\n Customize response to match tracer tool format with output instructions.\n \"\"\"\n # Store trace configuration on first step\n if request.step_number == 1:\n self.initial_request = request.step\n self.trace_config = {\n \"trace_mode\": request.trace_mode,\n \"target_description\": request.target_description,\n }\n\n # Update metadata with trace configuration\n if \"metadata\" in response_data:\n response_data[\"metadata\"][\"trace_mode\"] = request.trace_mode or \"unknown\"\n response_data[\"metadata\"][\"target_description\"] = request.target_description or \"\"\n\n # If in ask mode, mark this as mode selection phase\n if request.trace_mode == \"ask\":\n response_data[\"mode_selection_required\"] = True\n response_data[\"status\"] = \"mode_selection_required\"\n\n # Add tracer-specific output instructions for final steps\n if not request.next_step_required:\n response_data[\"tracing_complete\"] = True\n response_data[\"trace_summary\"] = f\"TRACING COMPLETE: {request.step}\"\n\n # Get mode-specific output instructions\n trace_mode = self.trace_config.get(\"trace_mode\", \"precision\")\n rendering_instructions = self._get_rendering_instructions(trace_mode)\n\n response_data[\"output\"] = {\n \"instructions\": (\n \"This is a structured tracing analysis response. Present the comprehensive tracing findings \"\n \"using the specific rendering format for the trace mode. Follow the exact formatting guidelines \"\n \"provided in rendering_instructions. Include all discovered relationships, execution paths, \"\n \"and dependencies with precise file references and line numbers.\"\n ),\n \"format\": f\"{trace_mode}_trace_analysis\",\n \"rendering_instructions\": rendering_instructions,\n \"presentation_guidelines\": {\n \"completed_trace\": (\n \"Use the exact rendering format specified for the trace mode. Include comprehensive \"\n \"diagrams, tables, and structured analysis. Reference specific file paths and line numbers. \"\n \"Follow formatting rules precisely.\"\n ),\n \"step_content\": \"Present as main analysis with clear structure and actionable insights.\",\n \"continuation\": \"Use continuation_id for related tracing sessions or follow-up analysis\",\n },\n }\n response_data[\"next_steps\"] = (\n f\"Tracing analysis complete. Present the comprehensive {trace_mode} trace analysis to the user \"\n f\"using the exact rendering format specified in the output instructions. Follow the formatting \"\n f\"guidelines precisely, including diagrams, tables, and file references. After presenting the \"\n f\"analysis, offer to help with related tracing tasks or use the continuation_id for follow-up analysis.\"\n )\n\n # Convert generic status names to tracer-specific ones\n tool_name = self.get_name()\n status_mapping = {\n f\"{tool_name}_in_progress\": \"tracing_in_progress\",\n f\"pause_for_{tool_name}\": \"pause_for_tracing\",\n f\"{tool_name}_required\": \"tracing_required\",\n f\"{tool_name}_complete\": \"tracing_complete\",\n }\n\n if response_data[\"status\"] in status_mapping:\n response_data[\"status\"] = status_mapping[response_data[\"status\"]]\n\n return response_data\n\n def _get_rendering_instructions(self, trace_mode: str) -> str:\n \"\"\"\n Get mode-specific rendering instructions for the CLI agent.\n\n Args:\n trace_mode: Either \"precision\" or \"dependencies\"\n\n Returns:\n str: Complete rendering instructions for the specified mode\n \"\"\"\n if trace_mode == \"precision\":\n return self._get_precision_rendering_instructions()\n else: # dependencies mode\n return self._get_dependencies_rendering_instructions()\n\n def _get_precision_rendering_instructions(self) -> str:\n \"\"\"Get rendering instructions for precision trace mode.\"\"\"\n return \"\"\"\n## MANDATORY RENDERING INSTRUCTIONS FOR PRECISION TRACE\n\nYou MUST render the trace analysis using ONLY the Vertical Indented Flow Style:\n\n### CALL FLOW DIAGRAM - Vertical Indented Style\n\n**EXACT FORMAT TO FOLLOW:**\n```\n[ClassName::MethodName] (file: /complete/file/path.ext, line: ##)\n↓\n[AnotherClass::calledMethod] (file: /path/to/file.ext, line: ##)\n↓\n[ThirdClass::nestedMethod] (file: /path/file.ext, line: ##)\n ↓\n [DeeperClass::innerCall] (file: /path/inner.ext, line: ##) ? if some_condition\n ↓\n [ServiceClass::processData] (file: /services/service.ext, line: ##)\n ↓\n [RepositoryClass::saveData] (file: /data/repo.ext, line: ##)\n ↓\n [ClientClass::sendRequest] (file: /clients/client.ext, line: ##)\n ↓\n [EmailService::sendEmail] (file: /email/service.ext, line: ##) ⚠️ ambiguous branch\n β†’\n [SMSService::sendSMS] (file: /sms/service.ext, line: ##) ⚠️ ambiguous branch\n```\n\n**CRITICAL FORMATTING RULES:**\n\n1. **Method Names**: Use the actual naming convention of the project language you're analyzing. Automatically detect and adapt to the project's conventions (camelCase, snake_case, PascalCase, etc.) based on the codebase structure and file extensions.\n\n2. **Vertical Flow Arrows**:\n - Use `↓` for standard sequential calls (vertical flow)\n - Use `β†’` for parallel/alternative calls (horizontal branch)\n - NEVER use other arrow types\n\n3. **Indentation Logic**:\n - Start at column 0 for entry point\n - Indent 2 spaces for each nesting level\n - Maintain consistent indentation for same call depth\n - Sibling calls at same level should have same indentation\n\n4. **Conditional Calls**:\n - Add `? if condition_description` after method for conditional execution\n - Use actual condition names from code when possible\n\n5. **Ambiguous Branches**:\n - Mark with `⚠️ ambiguous branch` when execution path is uncertain\n - Use `β†’` to show alternative paths at same indentation level\n\n6. **File Path Format**:\n - Use complete relative paths from project root\n - Include actual file extensions from the project\n - Show exact line numbers where method is defined\n\n### ADDITIONAL ANALYSIS VIEWS\n\n**1. BRANCHING & SIDE EFFECT TABLE**\n\n| Location | Condition | Branches | Uncertain |\n|----------|-----------|----------|-----------|\n| CompleteFileName.ext:## | if actual_condition_from_code | method1(), method2(), else skip | No |\n| AnotherFile.ext:## | if boolean_check | callMethod(), else return | No |\n| ThirdFile.ext:## | if validation_passes | processData(), else throw | Yes |\n\n**2. SIDE EFFECTS**\n```\nSide Effects:\n- [database] Specific database operation description (CompleteFileName.ext:##)\n- [network] Specific network call description (CompleteFileName.ext:##)\n- [filesystem] Specific file operation description (CompleteFileName.ext:##)\n- [state] State changes or property modifications (CompleteFileName.ext:##)\n- [memory] Memory allocation or cache operations (CompleteFileName.ext:##)\n```\n\n**3. USAGE POINTS**\n```\nUsage Points:\n1. FileName.ext:## - Context description of where/why it's called\n2. AnotherFile.ext:## - Context description of usage scenario\n3. ThirdFile.ext:## - Context description of calling pattern\n4. FourthFile.ext:## - Context description of integration point\n```\n\n**4. ENTRY POINTS**\n```\nEntry Points:\n- ClassName::methodName (context: where this flow typically starts)\n- AnotherClass::entryMethod (context: alternative entry scenario)\n- ThirdClass::triggerMethod (context: event-driven entry point)\n```\n\n**ABSOLUTE REQUIREMENTS:**\n- Use ONLY the vertical indented style for the call flow diagram\n- Present ALL FOUR additional analysis views (Branching Table, Side Effects, Usage Points, Entry Points)\n- Adapt method naming to match the project's programming language conventions\n- Use exact file paths and line numbers from the actual codebase\n- DO NOT invent or guess method names or locations\n- Follow indentation rules precisely for call hierarchy\n- Mark uncertain execution paths clearly\n- Provide contextual descriptions in Usage Points and Entry Points sections\n- Include comprehensive side effects categorization (database, network, filesystem, state, memory)\"\"\"\n\n def _get_dependencies_rendering_instructions(self) -> str:\n \"\"\"Get rendering instructions for dependencies trace mode.\"\"\"\n return \"\"\"\n## MANDATORY RENDERING INSTRUCTIONS FOR DEPENDENCIES TRACE\n\nYou MUST render the trace analysis using ONLY the Bidirectional Arrow Flow Style:\n\n### DEPENDENCY FLOW DIAGRAM - Bidirectional Arrow Style\n\n**EXACT FORMAT TO FOLLOW:**\n```\nINCOMING DEPENDENCIES β†’ [TARGET_CLASS/MODULE] β†’ OUTGOING DEPENDENCIES\n\nCallerClass::callerMethod ←────┐\nAnotherCaller::anotherMethod ←──\nThirdCaller::thirdMethod ←──────\n β”‚\n [TARGET_CLASS/MODULE]\n β”‚\n β”œβ”€β”€β”€β”€β†’ FirstDependency::method\n β”œβ”€β”€β”€β”€β†’ SecondDependency::method\n └────→ ThirdDependency::method\n\nTYPE RELATIONSHIPS:\nInterfaceName ──implements──→ [TARGET_CLASS] ──extends──→ BaseClass\nDTOClass ──uses──→ [TARGET_CLASS] ──uses──→ EntityClass\n```\n\n**CRITICAL FORMATTING RULES:**\n\n1. **Target Placement**: Always place the target class/module in square brackets `[TARGET_NAME]` at the center\n2. **Incoming Dependencies**: Show on the left side with `←` arrows pointing INTO the target\n3. **Outgoing Dependencies**: Show on the right side with `β†’` arrows pointing OUT FROM the target\n4. **Arrow Alignment**: Use consistent spacing and alignment for visual clarity\n5. **Method Naming**: Use the project's actual naming conventions detected from the codebase\n6. **File References**: Include complete file paths and line numbers\n\n**VISUAL LAYOUT RULES:**\n\n1. **Header Format**: Always start with the flow direction indicator\n2. **Left Side (Incoming)**:\n - List all callers with `←` arrows\n - Use `┐`, `─`, `β”˜` box drawing characters for clean connection lines\n - Align arrows consistently\n\n3. **Center (Target)**:\n - Enclose target in square brackets\n - Position centrally between incoming and outgoing\n\n4. **Right Side (Outgoing)**:\n - List all dependencies with `β†’` arrows\n - Use `β”œ`, `β””` box drawing characters for branching\n - Maintain consistent spacing\n\n5. **Type Relationships Section**:\n - Use `──relationship──→` format with double hyphens\n - Show inheritance, implementation, and usage relationships\n - Place below the main flow diagram\n\n**DEPENDENCY TABLE:**\n\n| Type | From/To | Method | File | Line |\n|------|---------|--------|------|------|\n| incoming_call | From: CallerClass | callerMethod | /complete/path/file.ext | ## |\n| outgoing_call | To: TargetClass | targetMethod | /complete/path/file.ext | ## |\n| implements | Self: ThisClass | β€” | /complete/path/file.ext | β€” |\n| extends | Self: ThisClass | β€” | /complete/path/file.ext | β€” |\n| uses_type | Self: ThisClass | β€” | /complete/path/file.ext | β€” |\n\n**ABSOLUTE REQUIREMENTS:**\n- Use ONLY the bidirectional arrow flow style shown above\n- Automatically detect and use the project's naming conventions\n- Use exact file paths and line numbers from the actual codebase\n- DO NOT invent or guess method/class names\n- Maintain visual alignment and consistent spacing\n- Include type relationships section when applicable\n- Show clear directional flow with proper arrows\"\"\"\n\n # ================================================================================\n # Hook Method Overrides for Tracer-Specific Behavior\n # ================================================================================\n\n def get_completion_status(self) -> str:\n \"\"\"Tracer uses tracing-specific status.\"\"\"\n return \"tracing_complete\"\n\n def get_completion_data_key(self) -> str:\n \"\"\"Tracer uses 'complete_tracing' key.\"\"\"\n return \"complete_tracing\"\n\n def get_completion_message(self) -> str:\n \"\"\"Tracer-specific completion message.\"\"\"\n return (\n \"Tracing analysis complete. Present the comprehensive trace analysis to the user \"\n \"using the specified rendering format and offer to help with related tracing tasks.\"\n )\n\n def get_skip_reason(self) -> str:\n \"\"\"Tracer-specific skip reason.\"\"\"\n return \"Tracer is self-contained and completes analysis without external assistance\"\n\n def get_skip_expert_analysis_status(self) -> str:\n \"\"\"Tracer-specific expert analysis skip status.\"\"\"\n return \"skipped_by_tool_design\"\n\n def store_initial_issue(self, step_description: str):\n \"\"\"Store initial tracing description.\"\"\"\n self.initial_tracing_description = step_description\n\n def get_initial_request(self, fallback_step: str) -> str:\n \"\"\"Get initial tracing description.\"\"\"\n try:\n return self.initial_tracing_description\n except AttributeError:\n return fallback_step\n\n def get_request_confidence(self, request) -> str:\n \"\"\"Get confidence from request for tracer workflow.\"\"\"\n try:\n return request.confidence or \"exploring\"\n except AttributeError:\n return \"exploring\"\n\n def get_trace_mode(self) -> str:\n \"\"\"Get current trace mode. Override for custom trace mode handling.\"\"\"\n try:\n return self.trace_config.get(\"trace_mode\", \"ask\")\n except AttributeError:\n return \"ask\"\n\n # Required abstract methods from BaseTool\n def get_request_model(self):\n \"\"\"Return the tracer-specific request model.\"\"\"\n return TracerRequest\n\n async def prepare_prompt(self, request) -> str:\n \"\"\"Not used - workflow tools use execute_workflow().\"\"\"\n return \"\" # Workflow tools use execute_workflow() directly\n" }, { "path": "tools/version.py", "content": "\"\"\"\nVersion Tool - Display PAL MCP Server version and system information\n\nThis tool provides version information about the PAL MCP Server including\nversion number, last update date, author, and basic system information.\nIt also checks for updates from the GitHub repository.\n\"\"\"\n\nimport logging\nimport platform\nimport re\nimport sys\nfrom pathlib import Path\nfrom typing import Any, Optional\n\ntry:\n from urllib.error import HTTPError, URLError\n from urllib.request import urlopen\n\n HAS_URLLIB = True\nexcept ImportError:\n HAS_URLLIB = False\n\nfrom mcp.types import TextContent\n\nfrom config import __author__, __updated__, __version__\nfrom tools.models import ToolModelCategory, ToolOutput\nfrom tools.shared.base_models import ToolRequest\nfrom tools.shared.base_tool import BaseTool\n\nlogger = logging.getLogger(__name__)\n\n\ndef parse_version(version_str: str) -> tuple[int, int, int]:\n \"\"\"\n Parse version string to tuple of integers for comparison.\n\n Args:\n version_str: Version string like \"5.5.5\"\n\n Returns:\n Tuple of (major, minor, patch) as integers\n \"\"\"\n try:\n parts = version_str.strip().split(\".\")\n if len(parts) >= 3:\n return (int(parts[0]), int(parts[1]), int(parts[2]))\n elif len(parts) == 2:\n return (int(parts[0]), int(parts[1]), 0)\n elif len(parts) == 1:\n return (int(parts[0]), 0, 0)\n else:\n return (0, 0, 0)\n except (ValueError, IndexError):\n return (0, 0, 0)\n\n\ndef compare_versions(current: str, remote: str) -> int:\n \"\"\"\n Compare two version strings.\n\n Args:\n current: Current version string\n remote: Remote version string\n\n Returns:\n -1 if current < remote (update available)\n 0 if current == remote (up to date)\n 1 if current > remote (ahead of remote)\n \"\"\"\n current_tuple = parse_version(current)\n remote_tuple = parse_version(remote)\n\n if current_tuple < remote_tuple:\n return -1\n elif current_tuple > remote_tuple:\n return 1\n else:\n return 0\n\n\ndef fetch_github_version() -> Optional[tuple[str, str]]:\n \"\"\"\n Fetch the latest version information from GitHub repository.\n\n Returns:\n Tuple of (version, last_updated) if successful, None if failed\n \"\"\"\n if not HAS_URLLIB:\n logger.warning(\"urllib not available, cannot check for updates\")\n return None\n\n github_url = \"https://raw.githubusercontent.com/BeehiveInnovations/pal-mcp-server/main/config.py\"\n\n try:\n # Set a 10-second timeout\n with urlopen(github_url, timeout=10) as response:\n if response.status != 200:\n logger.warning(f\"HTTP error while checking GitHub: {response.status}\")\n return None\n\n content = response.read().decode(\"utf-8\")\n\n # Extract version using regex\n version_match = re.search(r'__version__\\s*=\\s*[\"\\']([^\"\\']+)[\"\\']', content)\n updated_match = re.search(r'__updated__\\s*=\\s*[\"\\']([^\"\\']+)[\"\\']', content)\n\n if version_match:\n remote_version = version_match.group(1)\n remote_updated = updated_match.group(1) if updated_match else \"Unknown\"\n return (remote_version, remote_updated)\n else:\n logger.warning(\"Could not parse version from GitHub config.py\")\n return None\n\n except HTTPError as e:\n logger.warning(f\"HTTP error while checking GitHub: {e.code}\")\n return None\n except URLError as e:\n logger.warning(f\"URL error while checking GitHub: {e.reason}\")\n return None\n except Exception as e:\n logger.warning(f\"Error checking GitHub for updates: {e}\")\n return None\n\n\nclass VersionTool(BaseTool):\n \"\"\"\n Tool for displaying PAL MCP Server version and system information.\n\n This tool provides:\n - Current server version\n - Last update date\n - Author information\n - Python version\n - Platform information\n \"\"\"\n\n def get_name(self) -> str:\n return \"version\"\n\n def get_description(self) -> str:\n return \"Get server version, configuration details, and list of available tools.\"\n\n def get_input_schema(self) -> dict[str, Any]:\n \"\"\"Return the JSON schema for the tool's input\"\"\"\n return {\n \"type\": \"object\",\n \"properties\": {},\n \"required\": [],\n \"additionalProperties\": False,\n }\n\n def get_annotations(self) -> Optional[dict[str, Any]]:\n \"\"\"Return tool annotations indicating this is a read-only tool\"\"\"\n return {\"readOnlyHint\": True}\n\n def get_system_prompt(self) -> str:\n \"\"\"No AI model needed for this tool\"\"\"\n return \"\"\n\n def get_request_model(self):\n \"\"\"Return the Pydantic model for request validation.\"\"\"\n return ToolRequest\n\n def requires_model(self) -> bool:\n return False\n\n async def prepare_prompt(self, request: ToolRequest) -> str:\n \"\"\"Not used for this utility tool\"\"\"\n return \"\"\n\n def format_response(self, response: str, request: ToolRequest, model_info: dict = None) -> str:\n \"\"\"Not used for this utility tool\"\"\"\n return response\n\n async def execute(self, arguments: dict[str, Any]) -> list[TextContent]:\n \"\"\"\n Display PAL MCP Server version and system information.\n\n This overrides the base class execute to provide direct output without AI model calls.\n\n Args:\n arguments: Standard tool arguments (none required)\n\n Returns:\n Formatted version and system information\n \"\"\"\n output_lines = [\"# PAL MCP Server Version\\n\"]\n\n # Server version information\n output_lines.append(\"## Server Information\")\n output_lines.append(f\"**Current Version**: {__version__}\")\n output_lines.append(f\"**Last Updated**: {__updated__}\")\n output_lines.append(f\"**Author**: {__author__}\")\n\n model_selection_metadata = {\"mode\": \"unknown\", \"default_model\": None}\n model_selection_display = \"Model selection status unavailable\"\n\n # Model selection configuration\n try:\n from config import DEFAULT_MODEL\n from tools.shared.base_tool import BaseTool\n\n auto_mode = BaseTool.is_effective_auto_mode(self)\n if auto_mode:\n output_lines.append(\n \"**Model Selection**: Auto model selection mode (call `listmodels` to inspect options)\"\n )\n model_selection_metadata = {\"mode\": \"auto\", \"default_model\": DEFAULT_MODEL}\n model_selection_display = \"Auto model selection (use `listmodels` for options)\"\n else:\n output_lines.append(f\"**Model Selection**: Default model set to `{DEFAULT_MODEL}`\")\n model_selection_metadata = {\"mode\": \"default\", \"default_model\": DEFAULT_MODEL}\n model_selection_display = f\"Default model: `{DEFAULT_MODEL}`\"\n except Exception as exc:\n logger.debug(f\"Could not determine model selection mode: {exc}\")\n\n output_lines.append(\"\")\n output_lines.append(\"## Quick Summary β€” relay everything below\")\n output_lines.append(f\"- Version `{__version__}` (updated {__updated__})\")\n output_lines.append(f\"- {model_selection_display}\")\n output_lines.append(\"- Run `listmodels` for the complete model catalog and capabilities\")\n output_lines.append(\"\")\n\n # Try to get client information\n try:\n # We need access to the server instance\n # This is a bit hacky but works for now\n import server as server_module\n from utils.client_info import format_client_info, get_client_info_from_context\n\n client_info = get_client_info_from_context(server_module.server)\n if client_info:\n formatted = format_client_info(client_info)\n output_lines.append(f\"**Connected Client**: {formatted}\")\n except Exception as e:\n logger.debug(f\"Could not get client info: {e}\")\n\n # Get the current working directory (MCP server location)\n current_path = Path.cwd()\n output_lines.append(f\"**Installation Path**: `{current_path}`\")\n output_lines.append(\"\")\n output_lines.append(\"## Agent Reporting Guidance\")\n output_lines.append(\n \"Agents MUST report: version, model-selection status, configured providers, and available-model count.\"\n )\n output_lines.append(\"Repeat the quick-summary bullets verbatim in your reply.\")\n output_lines.append(\"Reference `listmodels` when users ask about model availability or capabilities.\")\n output_lines.append(\"\")\n\n # Check for updates from GitHub\n output_lines.append(\"## Update Status\")\n\n try:\n github_info = fetch_github_version()\n\n if github_info:\n remote_version, remote_updated = github_info\n comparison = compare_versions(__version__, remote_version)\n\n output_lines.append(f\"**Latest Version (GitHub)**: {remote_version}\")\n output_lines.append(f\"**Latest Updated**: {remote_updated}\")\n\n if comparison < 0:\n # Update available\n output_lines.append(\"\")\n output_lines.append(\"πŸš€ **UPDATE AVAILABLE!**\")\n output_lines.append(\n f\"Your version `{__version__}` is older than the latest version `{remote_version}`\"\n )\n output_lines.append(\"\")\n output_lines.append(\"**To update:**\")\n output_lines.append(\"```bash\")\n output_lines.append(f\"cd {current_path}\")\n output_lines.append(\"git pull\")\n output_lines.append(\"```\")\n output_lines.append(\"\")\n output_lines.append(\"*Note: Restart your session after updating to use the new version.*\")\n elif comparison == 0:\n # Up to date\n output_lines.append(\"\")\n output_lines.append(\"βœ… **UP TO DATE**\")\n output_lines.append(\"You are running the latest version.\")\n else:\n # Ahead of remote (development version)\n output_lines.append(\"\")\n output_lines.append(\"πŸ”¬ **DEVELOPMENT VERSION**\")\n output_lines.append(\n f\"Your version `{__version__}` is ahead of the published version `{remote_version}`\"\n )\n output_lines.append(\"You may be running a development or custom build.\")\n else:\n output_lines.append(\"❌ **Could not check for updates**\")\n output_lines.append(\"Unable to connect to GitHub or parse version information.\")\n output_lines.append(\"Check your internet connection or try again later.\")\n\n except Exception as e:\n logger.error(f\"Error during version check: {e}\")\n output_lines.append(\"❌ **Error checking for updates**\")\n output_lines.append(f\"Error: {str(e)}\")\n\n output_lines.append(\"\")\n\n # Configuration information\n output_lines.append(\"## Configuration\")\n\n # Check for configured providers\n try:\n from providers.registry import ModelProviderRegistry\n from providers.shared import ProviderType\n\n provider_status = []\n\n # Check each provider type\n provider_types = [\n ProviderType.GOOGLE,\n ProviderType.OPENAI,\n ProviderType.XAI,\n ProviderType.DIAL,\n ProviderType.OPENROUTER,\n ProviderType.CUSTOM,\n ]\n provider_names = [\"Google Gemini\", \"OpenAI\", \"X.AI\", \"DIAL\", \"OpenRouter\", \"Custom/Local\"]\n\n for provider_type, provider_name in zip(provider_types, provider_names):\n provider = ModelProviderRegistry.get_provider(provider_type)\n status = \"βœ… Configured\" if provider is not None else \"❌ Not configured\"\n provider_status.append(f\"- **{provider_name}**: {status}\")\n\n output_lines.append(\"**Providers**:\")\n output_lines.extend(provider_status)\n\n # Get total available models\n try:\n available_models = ModelProviderRegistry.get_available_models(respect_restrictions=True)\n output_lines.append(f\"\\n\\n**Available Models**: {len(available_models)}\")\n except Exception:\n output_lines.append(\"\\n\\n**Available Models**: Unknown\")\n\n except Exception as e:\n logger.warning(f\"Error checking provider configuration: {e}\")\n output_lines.append(\"\\n\\n**Providers**: Error checking configuration\")\n\n output_lines.append(\"\")\n\n # Format output\n content = \"\\n\".join(output_lines)\n\n tool_output = ToolOutput(\n status=\"success\",\n content=content,\n content_type=\"text\",\n metadata={\n \"tool_name\": self.name,\n \"server_version\": __version__,\n \"last_updated\": __updated__,\n \"python_version\": f\"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}\",\n \"platform\": f\"{platform.system()} {platform.release()}\",\n \"model_selection_mode\": model_selection_metadata[\"mode\"],\n \"default_model\": model_selection_metadata[\"default_model\"],\n },\n )\n\n return [TextContent(type=\"text\", text=tool_output.model_dump_json())]\n\n def get_model_category(self) -> ToolModelCategory:\n \"\"\"Return the model category for this tool.\"\"\"\n return ToolModelCategory.FAST_RESPONSE # Simple version info, no AI needed\n" }, { "path": "tools/workflow/__init__.py", "content": "\"\"\"\nWorkflow tools for PAL MCP.\n\nWorkflow tools follow a multi-step pattern with forced pauses between steps\nto encourage thorough investigation and analysis. They inherit from WorkflowTool\nwhich combines BaseTool with BaseWorkflowMixin.\n\nAvailable workflow tools:\n- debug: Systematic investigation and root cause analysis\n- planner: Sequential planning (special case - no AI calls)\n- analyze: Code analysis workflow\n- codereview: Code review workflow\n- precommit: Pre-commit validation workflow\n- refactor: Refactoring analysis workflow\n- thinkdeep: Deep thinking workflow\n\"\"\"\n\nfrom .base import WorkflowTool\nfrom .schema_builders import WorkflowSchemaBuilder\nfrom .workflow_mixin import BaseWorkflowMixin\n\n__all__ = [\"WorkflowTool\", \"WorkflowSchemaBuilder\", \"BaseWorkflowMixin\"]\n" }, { "path": "tools/workflow/base.py", "content": "\"\"\"\nBase class for workflow MCP tools.\n\nWorkflow tools follow a multi-step pattern:\n1. CLI calls tool with work step data\n2. Tool tracks findings and progress\n3. Tool forces the CLI to pause and investigate between steps\n4. Once work is complete, tool calls external AI model for expert analysis\n5. Tool returns structured response combining investigation + expert analysis\n\nThey combine BaseTool's capabilities with BaseWorkflowMixin's workflow functionality\nand use SchemaBuilder for consistent schema generation.\n\"\"\"\n\nfrom abc import abstractmethod\nfrom typing import Any, Optional\n\nfrom tools.shared.base_models import WorkflowRequest\nfrom tools.shared.base_tool import BaseTool\n\nfrom .schema_builders import WorkflowSchemaBuilder\nfrom .workflow_mixin import BaseWorkflowMixin\n\n\nclass WorkflowTool(BaseTool, BaseWorkflowMixin):\n \"\"\"\n Base class for workflow (multi-step) tools.\n\n Workflow tools perform systematic multi-step work with expert analysis.\n They benefit from:\n - Automatic workflow orchestration from BaseWorkflowMixin\n - Automatic schema generation using SchemaBuilder\n - Inherited conversation handling and file processing from BaseTool\n - Progress tracking with ConsolidatedFindings\n - Expert analysis integration\n\n To create a workflow tool:\n 1. Inherit from WorkflowTool\n 2. Tool name is automatically provided by get_name() method\n 3. Implement get_required_actions() for step guidance\n 4. Implement should_call_expert_analysis() for completion criteria\n 5. Implement prepare_expert_analysis_context() for expert prompts\n 6. Optionally implement get_tool_fields() for additional fields\n 7. Optionally override workflow behavior methods\n\n Example:\n class DebugTool(WorkflowTool):\n # get_name() is inherited from BaseTool\n\n def get_tool_fields(self) -> Dict[str, Dict[str, Any]]:\n return {\n \"hypothesis\": {\n \"type\": \"string\",\n \"description\": \"Current theory about the issue\",\n }\n }\n\n def get_required_actions(\n self, step_number: int, confidence: str, findings: str, total_steps: int\n ) -> List[str]:\n return [\"Examine relevant code files\", \"Trace execution flow\", \"Check error logs\"]\n\n def should_call_expert_analysis(self, consolidated_findings) -> bool:\n return len(consolidated_findings.relevant_files) > 0\n \"\"\"\n\n def __init__(self):\n \"\"\"Initialize WorkflowTool with proper multiple inheritance.\"\"\"\n BaseTool.__init__(self)\n BaseWorkflowMixin.__init__(self)\n\n def get_tool_fields(self) -> dict[str, dict[str, Any]]:\n \"\"\"\n Return tool-specific field definitions beyond the standard workflow fields.\n\n Workflow tools automatically get all standard workflow fields:\n - step, step_number, total_steps, next_step_required\n - findings, files_checked, relevant_files, relevant_context\n - issues_found, confidence, hypothesis\n - plus common fields (model, temperature, etc.)\n\n Override this method to add additional tool-specific fields.\n\n Returns:\n Dict mapping field names to JSON schema objects\n\n Example:\n return {\n \"severity_filter\": {\n \"type\": \"string\",\n \"enum\": [\"low\", \"medium\", \"high\"],\n \"description\": \"Minimum severity level to report\",\n }\n }\n \"\"\"\n return {}\n\n def get_required_fields(self) -> list[str]:\n \"\"\"\n Return additional required fields beyond the standard workflow requirements.\n\n Workflow tools automatically require:\n - step, step_number, total_steps, next_step_required, findings\n - model (if in auto mode)\n\n Override this to add additional required fields.\n\n Returns:\n List of additional required field names\n \"\"\"\n return []\n\n def get_annotations(self) -> Optional[dict[str, Any]]:\n \"\"\"\n Return tool annotations. Workflow tools are read-only by default.\n\n All workflow tools perform analysis and investigation without modifying\n the environment. They may call external AI models for expert analysis,\n but they don't write files or make system changes.\n\n Override this method if your workflow tool needs different annotations.\n\n Returns:\n Dictionary with readOnlyHint set to True\n \"\"\"\n return {\"readOnlyHint\": True}\n\n def get_input_schema(self) -> dict[str, Any]:\n \"\"\"\n Generate the complete input schema using SchemaBuilder.\n\n This method automatically combines:\n - Standard workflow fields (step, findings, etc.)\n - Common fields (temperature, thinking_mode, etc.)\n - Model field with proper auto-mode handling\n - Tool-specific fields from get_tool_fields()\n - Required fields from get_required_fields()\n\n Returns:\n Complete JSON schema for the workflow tool\n \"\"\"\n requires_model = self.requires_model()\n model_field_schema = self.get_model_field_schema() if requires_model else None\n auto_mode = self.is_effective_auto_mode() if requires_model else False\n return WorkflowSchemaBuilder.build_schema(\n tool_specific_fields=self.get_tool_fields(),\n required_fields=self.get_required_fields(),\n model_field_schema=model_field_schema,\n auto_mode=auto_mode,\n tool_name=self.get_name(),\n require_model=requires_model,\n )\n\n def get_workflow_request_model(self):\n \"\"\"\n Return the workflow request model class.\n\n Workflow tools use WorkflowRequest by default, which includes\n all the standard workflow fields. Override this if your tool\n needs a custom request model.\n \"\"\"\n return WorkflowRequest\n\n # Implement the abstract method from BaseWorkflowMixin\n def get_work_steps(self, request) -> list[str]:\n \"\"\"\n Default implementation - workflow tools typically don't need predefined steps.\n\n The workflow is driven by the CLI's investigation process rather than\n predefined steps. Override this if your tool needs specific step guidance.\n \"\"\"\n return []\n\n # Default implementations for common workflow patterns\n\n def get_standard_required_actions(self, step_number: int, confidence: str, base_actions: list[str]) -> list[str]:\n \"\"\"\n Helper method to generate standard required actions based on confidence and step.\n\n This provides common patterns that most workflow tools can use:\n - Early steps: broad exploration\n - Low confidence: deeper investigation\n - Medium/high confidence: verification and confirmation\n\n Args:\n step_number: Current step number\n confidence: Current confidence level\n base_actions: Tool-specific base actions\n\n Returns:\n List of required actions appropriate for the current state\n \"\"\"\n if step_number == 1:\n # Initial investigation\n return [\n \"Search for code related to the reported issue or symptoms\",\n \"Examine relevant files and understand the current implementation\",\n \"Understand the project structure and locate relevant modules\",\n \"Identify how the affected functionality is supposed to work\",\n ]\n elif confidence in [\"exploring\", \"low\"]:\n # Need deeper investigation\n return base_actions + [\n \"Trace method calls and data flow through the system\",\n \"Check for edge cases, boundary conditions, and assumptions in the code\",\n \"Look for related configuration, dependencies, or external factors\",\n ]\n elif confidence in [\"medium\", \"high\"]:\n # Close to solution - need confirmation\n return base_actions + [\n \"Examine the exact code sections where you believe the issue occurs\",\n \"Trace the execution path that leads to the failure\",\n \"Verify your hypothesis with concrete code evidence\",\n \"Check for any similar patterns elsewhere in the codebase\",\n ]\n else:\n # General continued investigation\n return base_actions + [\n \"Continue examining the code paths identified in your hypothesis\",\n \"Gather more evidence using appropriate investigation tools\",\n \"Test edge cases and boundary conditions\",\n \"Look for patterns that confirm or refute your theory\",\n ]\n\n def should_call_expert_analysis_default(self, consolidated_findings) -> bool:\n \"\"\"\n Default implementation for expert analysis decision.\n\n This provides a reasonable default that most workflow tools can use:\n - Call expert analysis if we have relevant files or significant findings\n - Skip if confidence is \"certain\" (handled by the workflow mixin)\n\n Override this for tool-specific logic.\n\n Args:\n consolidated_findings: The consolidated findings from all work steps\n\n Returns:\n True if expert analysis should be called\n \"\"\"\n # Call expert analysis if we have relevant files or substantial findings\n return (\n len(consolidated_findings.relevant_files) > 0\n or len(consolidated_findings.findings) >= 2\n or len(consolidated_findings.issues_found) > 0\n )\n\n def prepare_standard_expert_context(\n self, consolidated_findings, initial_description: str, context_sections: dict[str, str] = None\n ) -> str:\n \"\"\"\n Helper method to prepare standard expert analysis context.\n\n This provides a common structure that most workflow tools can use,\n with the ability to add tool-specific sections.\n\n Args:\n consolidated_findings: The consolidated findings from all work steps\n initial_description: Description of the initial request/issue\n context_sections: Optional additional sections to include\n\n Returns:\n Formatted context string for expert analysis\n \"\"\"\n context_parts = [f\"=== ISSUE DESCRIPTION ===\\n{initial_description}\\n=== END DESCRIPTION ===\"]\n\n # Add work progression\n if consolidated_findings.findings:\n findings_text = \"\\n\".join(consolidated_findings.findings)\n context_parts.append(f\"\\n=== INVESTIGATION FINDINGS ===\\n{findings_text}\\n=== END FINDINGS ===\")\n\n # Add relevant methods if available\n if consolidated_findings.relevant_context:\n methods_text = \"\\n\".join(f\"- {method}\" for method in consolidated_findings.relevant_context)\n context_parts.append(f\"\\n=== RELEVANT METHODS/FUNCTIONS ===\\n{methods_text}\\n=== END METHODS ===\")\n\n # Add hypothesis evolution if available\n if consolidated_findings.hypotheses:\n hypotheses_text = \"\\n\".join(\n f\"Step {h['step']} ({h['confidence']} confidence): {h['hypothesis']}\"\n for h in consolidated_findings.hypotheses\n )\n context_parts.append(f\"\\n=== HYPOTHESIS EVOLUTION ===\\n{hypotheses_text}\\n=== END HYPOTHESES ===\")\n\n # Add issues found if available\n if consolidated_findings.issues_found:\n issues_text = \"\\n\".join(\n f\"[{issue.get('severity', 'unknown').upper()}] {issue.get('description', 'No description')}\"\n for issue in consolidated_findings.issues_found\n )\n context_parts.append(f\"\\n=== ISSUES IDENTIFIED ===\\n{issues_text}\\n=== END ISSUES ===\")\n\n # Add tool-specific sections\n if context_sections:\n for section_title, section_content in context_sections.items():\n context_parts.append(\n f\"\\n=== {section_title.upper()} ===\\n{section_content}\\n=== END {section_title.upper()} ===\"\n )\n\n return \"\\n\".join(context_parts)\n\n def handle_completion_without_expert_analysis(\n self, request, consolidated_findings, initial_description: str = None\n ) -> dict[str, Any]:\n \"\"\"\n Generic handler for completion when expert analysis is not needed.\n\n This provides a standard response format for when the tool determines\n that external expert analysis is not required. All workflow tools\n can use this generic implementation or override for custom behavior.\n\n Args:\n request: The workflow request object\n consolidated_findings: The consolidated findings from all work steps\n initial_description: Optional initial description (defaults to request.step)\n\n Returns:\n Dictionary with completion response data\n \"\"\"\n # Prepare work summary using inheritance hook\n work_summary = self.prepare_work_summary()\n\n return {\n \"status\": self.get_completion_status(),\n self.get_completion_data_key(): {\n \"initial_request\": initial_description or request.step,\n \"steps_taken\": len(consolidated_findings.findings),\n \"files_examined\": list(consolidated_findings.files_checked),\n \"relevant_files\": list(consolidated_findings.relevant_files),\n \"relevant_context\": list(consolidated_findings.relevant_context),\n \"work_summary\": work_summary,\n \"final_analysis\": self.get_final_analysis_from_request(request),\n \"confidence_level\": self.get_confidence_level(request),\n },\n \"next_steps\": self.get_completion_message(),\n \"skip_expert_analysis\": True,\n \"expert_analysis\": {\n \"status\": self.get_skip_expert_analysis_status(),\n \"reason\": self.get_skip_reason(),\n },\n }\n\n # Inheritance hooks for customization\n\n def prepare_work_summary(self) -> str:\n \"\"\"\n Prepare a summary of the work performed. Override for custom summaries.\n Default implementation provides a basic summary.\n \"\"\"\n try:\n return self._prepare_work_summary()\n except AttributeError:\n try:\n return f\"Completed {len(self.work_history)} work steps\"\n except AttributeError:\n return \"Completed 0 work steps\"\n\n def get_completion_status(self) -> str:\n \"\"\"Get the status to use when completing without expert analysis.\"\"\"\n return \"high_confidence_completion\"\n\n def get_completion_data_key(self) -> str:\n \"\"\"Get the key name for completion data in the response.\"\"\"\n return f\"complete_{self.get_name()}\"\n\n def get_final_analysis_from_request(self, request) -> Optional[str]:\n \"\"\"Extract final analysis from request. Override for tool-specific extraction.\"\"\"\n try:\n return request.hypothesis\n except AttributeError:\n return None\n\n def get_confidence_level(self, request) -> str:\n \"\"\"Get confidence level from request. Override for tool-specific logic.\"\"\"\n try:\n return request.confidence or \"high\"\n except AttributeError:\n return \"high\"\n\n def get_completion_message(self) -> str:\n \"\"\"Get completion message. Override for tool-specific messaging.\"\"\"\n return (\n f\"{self.get_name().capitalize()} complete with high confidence. You have identified the exact \"\n \"analysis and solution. MANDATORY: Present the user with the results \"\n \"and proceed with implementing the solution without requiring further \"\n \"consultation. Focus on the precise, actionable steps needed.\"\n )\n\n def get_skip_reason(self) -> str:\n \"\"\"Get reason for skipping expert analysis. Override for tool-specific reasons.\"\"\"\n return f\"{self.get_name()} completed with sufficient confidence\"\n\n def get_skip_expert_analysis_status(self) -> str:\n \"\"\"Get status for skipped expert analysis. Override for tool-specific status.\"\"\"\n return \"skipped_by_tool_design\"\n\n def is_continuation_workflow(self, request) -> bool:\n \"\"\"\n Check if this is a continuation workflow that should skip multi-step investigation.\n\n When continuation_id is provided, the workflow typically continues from a previous\n conversation and should go directly to expert analysis rather than starting a new\n multi-step investigation.\n\n Args:\n request: The workflow request object\n\n Returns:\n True if this is a continuation that should skip multi-step workflow\n \"\"\"\n continuation_id = self.get_request_continuation_id(request)\n return bool(continuation_id)\n\n # Abstract methods that must be implemented by specific workflow tools\n # (These are inherited from BaseWorkflowMixin and must be implemented)\n\n @abstractmethod\n def get_required_actions(\n self, step_number: int, confidence: str, findings: str, total_steps: int, request=None\n ) -> list[str]:\n \"\"\"Define required actions for each work phase.\n\n Args:\n step_number: Current step number\n confidence: Current confidence level\n findings: Current findings text\n total_steps: Total estimated steps\n request: Optional request object for continuation-aware decisions\n\n Returns:\n List of required actions for the current step\n \"\"\"\n pass\n\n @abstractmethod\n def should_call_expert_analysis(self, consolidated_findings) -> bool:\n \"\"\"Decide when to call external model based on tool-specific criteria\"\"\"\n pass\n\n @abstractmethod\n def prepare_expert_analysis_context(self, consolidated_findings) -> str:\n \"\"\"Prepare context for external model call\"\"\"\n pass\n\n # Default execute method - delegates to workflow\n async def execute(self, arguments: dict[str, Any]) -> list:\n \"\"\"Execute the workflow tool - delegates to BaseWorkflowMixin.\"\"\"\n return await self.execute_workflow(arguments)\n" }, { "path": "tools/workflow/schema_builders.py", "content": "\"\"\"\nSchema builders for workflow MCP tools.\n\nThis module provides workflow-specific schema generation functionality,\nkeeping workflow concerns separated from simple tool concerns.\n\"\"\"\n\nfrom typing import Any\n\nfrom ..shared.base_models import WORKFLOW_FIELD_DESCRIPTIONS\nfrom ..shared.schema_builders import SchemaBuilder\n\n\nclass WorkflowSchemaBuilder:\n \"\"\"\n Schema builder for workflow MCP tools.\n\n This class extends the base SchemaBuilder with workflow-specific fields\n and schema generation logic, maintaining separation of concerns.\n \"\"\"\n\n # Workflow-specific field schemas\n WORKFLOW_FIELD_SCHEMAS = {\n \"step\": {\n \"type\": \"string\",\n \"description\": WORKFLOW_FIELD_DESCRIPTIONS[\"step\"],\n },\n \"step_number\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": WORKFLOW_FIELD_DESCRIPTIONS[\"step_number\"],\n },\n \"total_steps\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"description\": WORKFLOW_FIELD_DESCRIPTIONS[\"total_steps\"],\n },\n \"next_step_required\": {\n \"type\": \"boolean\",\n \"description\": WORKFLOW_FIELD_DESCRIPTIONS[\"next_step_required\"],\n },\n \"findings\": {\n \"type\": \"string\",\n \"description\": WORKFLOW_FIELD_DESCRIPTIONS[\"findings\"],\n },\n \"files_checked\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": WORKFLOW_FIELD_DESCRIPTIONS[\"files_checked\"],\n },\n \"relevant_files\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_files\"],\n },\n \"relevant_context\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"string\"},\n \"description\": WORKFLOW_FIELD_DESCRIPTIONS[\"relevant_context\"],\n },\n \"issues_found\": {\n \"type\": \"array\",\n \"items\": {\"type\": \"object\"},\n \"description\": WORKFLOW_FIELD_DESCRIPTIONS[\"issues_found\"],\n },\n \"confidence\": {\n \"type\": \"string\",\n \"enum\": [\"exploring\", \"low\", \"medium\", \"high\", \"very_high\", \"almost_certain\", \"certain\"],\n \"description\": WORKFLOW_FIELD_DESCRIPTIONS[\"confidence\"],\n },\n \"hypothesis\": {\n \"type\": \"string\",\n \"description\": WORKFLOW_FIELD_DESCRIPTIONS[\"hypothesis\"],\n },\n \"use_assistant_model\": {\n \"type\": \"boolean\",\n \"default\": True,\n \"description\": WORKFLOW_FIELD_DESCRIPTIONS[\"use_assistant_model\"],\n },\n }\n\n @staticmethod\n def build_schema(\n tool_specific_fields: dict[str, dict[str, Any]] = None,\n required_fields: list[str] = None,\n model_field_schema: dict[str, Any] = None,\n auto_mode: bool = False,\n tool_name: str = None,\n excluded_workflow_fields: list[str] = None,\n excluded_common_fields: list[str] = None,\n require_model: bool = False,\n ) -> dict[str, Any]:\n \"\"\"\n Build complete schema for workflow tools.\n\n Args:\n tool_specific_fields: Additional fields specific to the tool\n required_fields: List of required field names (beyond workflow defaults)\n model_field_schema: Schema for the model field\n auto_mode: Whether the tool is in auto mode (affects model requirement)\n tool_name: Name of the tool (for schema title)\n excluded_workflow_fields: Workflow fields to exclude from schema (e.g., for planning tools)\n excluded_common_fields: Common fields to exclude from schema\n\n Returns:\n Complete JSON schema for the workflow tool\n \"\"\"\n properties = {}\n\n # Add workflow fields first, excluding any specified fields\n workflow_fields = WorkflowSchemaBuilder.WORKFLOW_FIELD_SCHEMAS.copy()\n if excluded_workflow_fields:\n for field in excluded_workflow_fields:\n workflow_fields.pop(field, None)\n properties.update(workflow_fields)\n\n # Add common fields (temperature, thinking_mode, etc.) from base builder, excluding any specified fields\n common_fields = SchemaBuilder.COMMON_FIELD_SCHEMAS.copy()\n if excluded_common_fields:\n for field in excluded_common_fields:\n common_fields.pop(field, None)\n properties.update(common_fields)\n\n # Add model field if provided\n if model_field_schema:\n properties[\"model\"] = model_field_schema\n\n # Add tool-specific fields if provided\n if tool_specific_fields:\n properties.update(tool_specific_fields)\n\n # Build required fields list - workflow tools have standard required fields\n standard_required = [\"step\", \"step_number\", \"total_steps\", \"next_step_required\", \"findings\"]\n\n # Filter out excluded fields from required fields\n if excluded_workflow_fields:\n standard_required = [field for field in standard_required if field not in excluded_workflow_fields]\n\n required = standard_required + (required_fields or [])\n\n if (auto_mode or require_model) and \"model\" not in required:\n required.append(\"model\")\n\n # Build the complete schema\n schema = {\n \"$schema\": \"http://json-schema.org/draft-07/schema#\",\n \"type\": \"object\",\n \"properties\": properties,\n \"required\": required,\n \"additionalProperties\": False,\n }\n\n if tool_name:\n schema[\"title\"] = f\"{tool_name.capitalize()}Request\"\n\n return schema\n\n @staticmethod\n def get_workflow_fields() -> dict[str, dict[str, Any]]:\n \"\"\"Get the standard field schemas for workflow tools.\"\"\"\n combined = {}\n combined.update(WorkflowSchemaBuilder.WORKFLOW_FIELD_SCHEMAS)\n combined.update(SchemaBuilder.COMMON_FIELD_SCHEMAS)\n return combined\n\n @staticmethod\n def get_workflow_only_fields() -> dict[str, dict[str, Any]]:\n \"\"\"Get only the workflow-specific field schemas.\"\"\"\n return WorkflowSchemaBuilder.WORKFLOW_FIELD_SCHEMAS.copy()\n" }, { "path": "tools/workflow/workflow_mixin.py", "content": "\"\"\"\nWorkflow Mixin for PAL MCP Tools\n\nThis module provides a sophisticated workflow-based pattern that enables tools to\nperform multi-step work with structured findings and expert analysis.\n\nKey Components:\n- BaseWorkflowMixin: Abstract base class providing comprehensive workflow functionality\n\nThe workflow pattern enables tools like debug, precommit, and codereview to perform\nsystematic multi-step work with pause/resume capabilities, context-aware file embedding,\nand seamless integration with external AI models for expert analysis.\n\nFeatures:\n- Multi-step workflow orchestration with pause/resume\n- Context-aware file embedding optimization\n- Expert analysis integration with token budgeting\n- Conversation memory and threading support\n- Proper inheritance-based architecture (no hasattr/getattr)\n- Comprehensive type annotations for IDE support\n\"\"\"\n\nimport json\nimport logging\nimport os\nimport re\nfrom abc import ABC, abstractmethod\nfrom typing import Any, Optional\n\nfrom mcp.types import TextContent\n\nfrom config import MCP_PROMPT_SIZE_LIMIT\nfrom utils.conversation_memory import add_turn, create_thread\n\nfrom ..shared.base_models import ConsolidatedFindings\nfrom ..shared.exceptions import ToolExecutionError\n\nlogger = logging.getLogger(__name__)\n\n\nclass BaseWorkflowMixin(ABC):\n \"\"\"\n Abstract base class providing guided workflow functionality for tools.\n\n This class implements a sophisticated workflow pattern where the CLI performs\n systematic local work before calling external models for expert analysis.\n Tools can inherit from this class to gain comprehensive workflow capabilities.\n\n Architecture:\n - Uses proper inheritance patterns instead of hasattr/getattr\n - Provides hook methods with default implementations\n - Requires abstract methods to be implemented by subclasses\n - Fully type-annotated for excellent IDE support\n\n Context-Aware File Embedding:\n - Intermediate steps: Only reference file names (saves the CLI's context)\n - Final steps: Embed full file content for expert analysis\n - Integrates with existing token budgeting infrastructure\n\n Requirements:\n This class expects to be used with BaseTool and requires implementation of:\n - get_model_provider(model_name)\n - _resolve_model_context(arguments, request)\n - get_system_prompt()\n - get_default_temperature()\n - _prepare_file_content_for_prompt()\n \"\"\"\n\n def __init__(self) -> None:\n super().__init__()\n self.work_history: list[dict[str, Any]] = []\n self.consolidated_findings: ConsolidatedFindings = ConsolidatedFindings()\n self.initial_request: Optional[str] = None\n\n # ================================================================================\n # Abstract Methods - Required Implementation by BaseTool or Subclasses\n # ================================================================================\n\n @abstractmethod\n def get_name(self) -> str:\n \"\"\"Return the name of this tool. Usually provided by BaseTool.\"\"\"\n pass\n\n @abstractmethod\n def get_workflow_request_model(self) -> type:\n \"\"\"Return the request model class for this workflow tool.\"\"\"\n pass\n\n @abstractmethod\n def get_system_prompt(self) -> str:\n \"\"\"Return the system prompt for this tool. Usually provided by BaseTool.\"\"\"\n pass\n\n @abstractmethod\n def get_language_instruction(self) -> str:\n \"\"\"Return the language instruction for localization. Usually provided by BaseTool.\"\"\"\n pass\n\n @abstractmethod\n def get_default_temperature(self) -> float:\n \"\"\"Return the default temperature for this tool. Usually provided by BaseTool.\"\"\"\n pass\n\n @abstractmethod\n def get_model_provider(self, model_name: str) -> Any:\n \"\"\"Get model provider for the given model. Usually provided by BaseTool.\"\"\"\n pass\n\n @abstractmethod\n def _resolve_model_context(self, arguments: dict[str, Any], request: Any) -> tuple[str, Any]:\n \"\"\"Resolve model context from arguments. Usually provided by BaseTool.\"\"\"\n pass\n\n @abstractmethod\n def _prepare_file_content_for_prompt(\n self,\n request_files: list[str],\n continuation_id: Optional[str],\n context_description: str = \"New files\",\n max_tokens: Optional[int] = None,\n reserve_tokens: int = 1_000,\n remaining_budget: Optional[int] = None,\n arguments: Optional[dict[str, Any]] = None,\n model_context: Optional[Any] = None,\n ) -> tuple[str, list[str]]:\n \"\"\"Prepare file content for prompts. Usually provided by BaseTool.\"\"\"\n pass\n\n # ================================================================================\n # Abstract Methods - Tool-Specific Implementation Required\n # ================================================================================\n\n @abstractmethod\n def get_work_steps(self, request: Any) -> list[str]:\n \"\"\"Define tool-specific work steps and criteria\"\"\"\n pass\n\n @abstractmethod\n def get_required_actions(\n self, step_number: int, confidence: str, findings: str, total_steps: int, request=None\n ) -> list[str]:\n \"\"\"Define required actions for each work phase.\n\n Args:\n step_number: Current step (1-based)\n confidence: Current confidence level (exploring, low, medium, high, certain)\n findings: Current findings text\n total_steps: Total estimated steps for this work\n request: Optional request object for continuation-aware decisions\n\n Returns:\n List of specific actions the CLI should take before calling tool again\n \"\"\"\n pass\n\n # ================================================================================\n # Hook Methods - Default Implementations with Override Capability\n # ================================================================================\n\n def should_call_expert_analysis(self, consolidated_findings: ConsolidatedFindings, request=None) -> bool:\n \"\"\"\n Decide when to call external model based on tool-specific criteria.\n\n Default implementation for tools that don't use expert analysis.\n Override this for tools that do use expert analysis.\n\n Args:\n consolidated_findings: Findings from workflow steps\n request: Current request object (optional for backwards compatibility)\n \"\"\"\n if not self.requires_expert_analysis():\n return False\n\n # Check if user requested to skip assistant model\n if request and not self.get_request_use_assistant_model(request):\n return False\n\n # Default logic for tools that support expert analysis\n return (\n len(consolidated_findings.relevant_files) > 0\n or len(consolidated_findings.findings) >= 2\n or len(consolidated_findings.issues_found) > 0\n )\n\n def prepare_expert_analysis_context(self, consolidated_findings: ConsolidatedFindings) -> str:\n \"\"\"\n Prepare context for external model call.\n\n Default implementation for tools that don't use expert analysis.\n Override this for tools that do use expert analysis.\n \"\"\"\n if not self.requires_expert_analysis():\n return \"\"\n\n # Default context preparation\n context_parts = [\n f\"=== {self.get_name().upper()} WORK SUMMARY ===\",\n f\"Total steps: {len(consolidated_findings.findings)}\",\n f\"Files examined: {len(consolidated_findings.files_checked)}\",\n f\"Relevant files: {len(consolidated_findings.relevant_files)}\",\n \"\",\n \"=== WORK PROGRESSION ===\",\n ]\n\n for finding in consolidated_findings.findings:\n context_parts.append(finding)\n\n return \"\\n\".join(context_parts)\n\n def requires_expert_analysis(self) -> bool:\n \"\"\"\n Override this to completely disable expert analysis for the tool.\n\n Returns True if the tool supports expert analysis (default).\n Returns False if the tool is self-contained (like planner).\n \"\"\"\n return True\n\n def should_include_files_in_expert_prompt(self) -> bool:\n \"\"\"\n Whether to include file content in the expert analysis prompt.\n Override this to return True if your tool needs files in the prompt.\n \"\"\"\n return False\n\n def should_embed_system_prompt(self) -> bool:\n \"\"\"\n Whether to embed the system prompt in the main prompt.\n Override this to return True if your tool needs the system prompt embedded.\n \"\"\"\n return False\n\n def get_expert_thinking_mode(self) -> str:\n \"\"\"\n Get the thinking mode for expert analysis.\n Override this to customize the thinking mode.\n \"\"\"\n return \"high\"\n\n def get_request_temperature(self, request) -> float:\n \"\"\"Get temperature from request. Override for custom temperature handling.\"\"\"\n try:\n return request.temperature if request.temperature is not None else self.get_default_temperature()\n except AttributeError:\n return self.get_default_temperature()\n\n def get_validated_temperature(self, request, model_context: Any) -> tuple[float, list[str]]:\n \"\"\"\n Get temperature from request and validate it against model constraints.\n\n This is a convenience method that combines temperature extraction and validation\n for workflow tools. It ensures temperature is within valid range for the model.\n\n Args:\n request: The request object containing temperature\n model_context: Model context object containing model info\n\n Returns:\n Tuple of (validated_temperature, warning_messages)\n \"\"\"\n temperature = self.get_request_temperature(request)\n return self.validate_and_correct_temperature(temperature, model_context)\n\n def get_request_thinking_mode(self, request) -> str:\n \"\"\"Get thinking mode from request. Override for custom thinking mode handling.\"\"\"\n try:\n return request.thinking_mode if request.thinking_mode is not None else self.get_expert_thinking_mode()\n except AttributeError:\n return self.get_expert_thinking_mode()\n\n def get_expert_analysis_instruction(self) -> str:\n \"\"\"\n Get the instruction to append after the expert context.\n Override this to provide tool-specific instructions.\n \"\"\"\n return \"Please provide expert analysis based on the investigation findings.\"\n\n def get_request_use_assistant_model(self, request) -> bool:\n \"\"\"\n Get use_assistant_model from request. Override for custom assistant model handling.\n\n Args:\n request: Current request object\n\n Returns:\n True if assistant model should be used, False otherwise\n \"\"\"\n try:\n return request.use_assistant_model if request.use_assistant_model is not None else True\n except AttributeError:\n return True\n\n def get_step_guidance_message(self, request) -> str:\n \"\"\"\n Get step guidance message. Override for tool-specific guidance.\n Default implementation uses required actions.\n \"\"\"\n required_actions = self.get_required_actions(\n request.step_number, self.get_request_confidence(request), request.findings, request.total_steps, request\n )\n\n next_step_number = request.step_number + 1\n return (\n f\"MANDATORY: DO NOT call the {self.get_name()} tool again immediately. \"\n f\"You MUST first work using appropriate tools. \"\n f\"REQUIRED ACTIONS before calling {self.get_name()} step {next_step_number}:\\n\"\n + \"\\n\".join(f\"{i + 1}. {action}\" for i, action in enumerate(required_actions))\n + f\"\\n\\nOnly call {self.get_name()} again with step_number: {next_step_number} \"\n f\"AFTER completing this work.\"\n )\n\n def _prepare_files_for_expert_analysis(self) -> str:\n \"\"\"\n Prepare file content for expert analysis.\n\n EXPERT ANALYSIS REQUIRES ACTUAL FILE CONTENT:\n Expert analysis needs actual file content of all unique files marked as relevant\n throughout the workflow, regardless of conversation history optimization.\n\n SIMPLIFIED LOGIC:\n Expert analysis gets all unique files from relevant_files across the entire workflow.\n This includes:\n - Current step's relevant_files (consolidated_findings.relevant_files)\n - Plus any additional relevant_files from conversation history (if continued workflow)\n\n This ensures expert analysis has complete context without including irrelevant files.\n \"\"\"\n all_relevant_files = set()\n\n # 1. Get files from current consolidated relevant_files\n all_relevant_files.update(self.consolidated_findings.relevant_files)\n\n # 2. Get additional relevant_files from conversation history (if continued workflow)\n try:\n current_arguments = self.get_current_arguments()\n if current_arguments:\n continuation_id = current_arguments.get(\"continuation_id\")\n\n if continuation_id:\n from utils.conversation_memory import get_conversation_file_list, get_thread\n\n thread_context = get_thread(continuation_id)\n if thread_context:\n # Get all files from conversation (these were relevant_files in previous steps)\n conversation_files = get_conversation_file_list(thread_context)\n all_relevant_files.update(conversation_files)\n logger.debug(\n f\"[WORKFLOW_FILES] {self.get_name()}: Added {len(conversation_files)} files from conversation history\"\n )\n except Exception as e:\n logger.warning(f\"[WORKFLOW_FILES] {self.get_name()}: Could not get conversation files: {e}\")\n\n # Convert to list and remove any empty/None values\n files_for_expert = [f for f in all_relevant_files if f and f.strip()]\n\n if not files_for_expert:\n logger.debug(f\"[WORKFLOW_FILES] {self.get_name()}: No relevant files found for expert analysis\")\n return \"\"\n\n # Expert analysis needs actual file content, bypassing conversation optimization\n try:\n file_content, processed_files = self._force_embed_files_for_expert_analysis(files_for_expert)\n\n logger.info(\n f\"[WORKFLOW_FILES] {self.get_name()}: Prepared {len(processed_files)} unique relevant files for expert analysis \"\n f\"(from {len(self.consolidated_findings.relevant_files)} current relevant files)\"\n )\n\n return file_content\n\n except Exception as e:\n logger.error(f\"[WORKFLOW_FILES] {self.get_name()}: Failed to prepare files for expert analysis: {e}\")\n return \"\"\n\n def _force_embed_files_for_expert_analysis(self, files: list[str]) -> tuple[str, list[str]]:\n \"\"\"\n Force embed files for expert analysis, bypassing conversation history filtering.\n\n Expert analysis has different requirements than normal workflow steps:\n - Normal steps: Optimize tokens by skipping files in conversation history\n - Expert analysis: Needs actual file content regardless of conversation history\n\n Args:\n files: List of file paths to embed\n\n Returns:\n tuple[str, list[str]]: (file_content, processed_files)\n \"\"\"\n # Use read_files directly with token budgeting, bypassing filter_new_files\n from utils.file_utils import expand_paths, read_files\n\n # Get token budget for files\n current_model_context = self.get_current_model_context()\n if current_model_context:\n try:\n token_allocation = current_model_context.calculate_token_allocation()\n max_tokens = token_allocation.file_tokens\n logger.debug(\n f\"[WORKFLOW_FILES] {self.get_name()}: Using {max_tokens:,} tokens for expert analysis files\"\n )\n except Exception as e:\n logger.warning(f\"[WORKFLOW_FILES] {self.get_name()}: Failed to get token allocation: {e}\")\n max_tokens = 100_000 # Fallback\n else:\n max_tokens = 100_000 # Fallback\n\n # Read files directly without conversation history filtering\n logger.debug(f\"[WORKFLOW_FILES] {self.get_name()}: Force embedding {len(files)} files for expert analysis\")\n file_content = read_files(\n files,\n max_tokens=max_tokens,\n reserve_tokens=1000,\n include_line_numbers=self.wants_line_numbers_by_default(),\n )\n\n # Expand paths to get individual files for tracking\n processed_files = expand_paths(files)\n\n logger.debug(\n f\"[WORKFLOW_FILES] {self.get_name()}: Expert analysis embedding: {len(processed_files)} files, \"\n f\"{len(file_content):,} characters\"\n )\n\n return file_content, processed_files\n\n def wants_line_numbers_by_default(self) -> bool:\n \"\"\"\n Whether this tool wants line numbers in file content by default.\n Override this to customize line number behavior.\n \"\"\"\n return True # Most workflow tools benefit from line numbers for analysis\n\n def _add_files_to_expert_context(self, expert_context: str, file_content: str) -> str:\n \"\"\"\n Add file content to the expert context.\n Override this to customize how files are added to the context.\n \"\"\"\n return f\"{expert_context}\\n\\n=== ESSENTIAL FILES ===\\n{file_content}\\n=== END ESSENTIAL FILES ===\"\n\n # ================================================================================\n # Context-Aware File Embedding - Core Implementation\n # ================================================================================\n\n def _handle_workflow_file_context(self, request: Any, arguments: dict[str, Any]) -> None:\n \"\"\"\n Handle file context appropriately based on workflow phase.\n\n CONTEXT-AWARE FILE EMBEDDING STRATEGY:\n 1. Intermediate steps + continuation: Only reference file names (save the CLI's context)\n 2. Final step: Embed full file content for expert analysis\n 3. Expert analysis: Always embed relevant files with token budgeting\n\n This prevents wasting the CLI's limited context on intermediate steps while ensuring\n the final expert analysis has complete file context.\n \"\"\"\n continuation_id = self.get_request_continuation_id(request)\n is_final_step = not self.get_request_next_step_required(request)\n step_number = self.get_request_step_number(request)\n\n # Extract model context for token budgeting\n model_context = arguments.get(\"_model_context\")\n self._model_context = model_context\n\n # Clear any previous file context to ensure clean state\n self._embedded_file_content = \"\"\n self._file_reference_note = \"\"\n self._actually_processed_files = []\n\n # Determine if we should embed files or just reference them\n should_embed_files = self._should_embed_files_in_workflow_step(step_number, continuation_id, is_final_step)\n\n if should_embed_files:\n # Final step or expert analysis - embed full file content\n logger.debug(f\"[WORKFLOW_FILES] {self.get_name()}: Embedding files for final step/expert analysis\")\n self._embed_workflow_files(request, arguments)\n else:\n # Intermediate step with continuation - only reference file names\n logger.debug(f\"[WORKFLOW_FILES] {self.get_name()}: Only referencing file names for intermediate step\")\n self._reference_workflow_files(request)\n\n def _should_embed_files_in_workflow_step(\n self, step_number: int, continuation_id: Optional[str], is_final_step: bool\n ) -> bool:\n \"\"\"\n Determine whether to embed file content based on workflow context.\n\n CORRECT LOGIC:\n - NEVER embed files when the CLI is getting the next step (next_step_required=True)\n - ONLY embed files when sending to external model (next_step_required=False)\n\n Args:\n step_number: Current step number\n continuation_id: Thread continuation ID (None for new conversations)\n is_final_step: Whether this is the final step (next_step_required == False)\n\n Returns:\n bool: True if files should be embedded, False if only referenced\n \"\"\"\n # RULE 1: Final steps (no more steps needed) - embed files for expert analysis\n if is_final_step:\n logger.debug(\"[WORKFLOW_FILES] Final step - will embed files for expert analysis\")\n return True\n\n # RULE 2: Any intermediate step (more steps needed) - NEVER embed files\n # This includes:\n # - New conversations with next_step_required=True\n # - Steps with continuation_id and next_step_required=True\n logger.debug(\"[WORKFLOW_FILES] Intermediate step (more work needed) - will only reference files\")\n return False\n\n def _embed_workflow_files(self, request: Any, arguments: dict[str, Any]) -> None:\n \"\"\"\n Embed full file content for final steps and expert analysis.\n Uses proper token budgeting like existing debug.py.\n \"\"\"\n # Use relevant_files as the standard field for workflow tools\n request_files = self.get_request_relevant_files(request)\n if not request_files:\n logger.debug(f\"[WORKFLOW_FILES] {self.get_name()}: No relevant_files to embed\")\n return\n\n try:\n # Model context should be available from early validation, but might be deferred for tests\n current_model_context = self.get_current_model_context()\n if not current_model_context:\n # Try to resolve model context now (deferred from early validation)\n try:\n model_name, model_context = self._resolve_model_context(arguments, request)\n self._model_context = model_context\n self._current_model_name = model_name\n except Exception as e:\n logger.error(f\"[WORKFLOW_FILES] {self.get_name()}: Failed to resolve model context: {e}\")\n # Create fallback model context (preserves existing test behavior)\n from utils.model_context import ModelContext\n\n model_name = self.get_request_model_name(request)\n self._model_context = ModelContext(model_name)\n self._current_model_name = model_name\n\n # Use the same file preparation logic as BaseTool with token budgeting\n continuation_id = self.get_request_continuation_id(request)\n remaining_tokens = arguments.get(\"_remaining_tokens\")\n\n file_content, processed_files = self._prepare_file_content_for_prompt(\n request_files,\n continuation_id,\n \"Workflow files for analysis\",\n remaining_budget=remaining_tokens,\n arguments=arguments,\n model_context=self._model_context,\n )\n\n # Store for use in expert analysis\n self._embedded_file_content = file_content\n self._actually_processed_files = processed_files\n\n logger.info(\n f\"[WORKFLOW_FILES] {self.get_name()}: Embedded {len(processed_files)} relevant_files for final analysis\"\n )\n\n except Exception as e:\n logger.error(f\"[WORKFLOW_FILES] {self.get_name()}: Failed to embed files: {e}\")\n # Continue without file embedding rather than failing\n self._embedded_file_content = \"\"\n self._actually_processed_files = []\n\n def _reference_workflow_files(self, request: Any) -> None:\n \"\"\"\n Reference file names without embedding content for intermediate steps.\n Saves the CLI's context while still providing file awareness.\n \"\"\"\n # Workflow tools use relevant_files, not files\n request_files = self.get_request_relevant_files(request)\n logger.debug(\n f\"[WORKFLOW_FILES] {self.get_name()}: _reference_workflow_files called with {len(request_files)} relevant_files\"\n )\n\n if not request_files:\n logger.debug(f\"[WORKFLOW_FILES] {self.get_name()}: No files to reference, skipping\")\n return\n\n # Store file references for conversation context\n self._referenced_files = request_files\n\n # Create a simple reference note\n file_names = [os.path.basename(f) for f in request_files]\n reference_note = f\"Files referenced in this step: {', '.join(file_names)}\\n\"\n\n self._file_reference_note = reference_note\n logger.debug(f\"[WORKFLOW_FILES] {self.get_name()}: Set _file_reference_note: {self._file_reference_note}\")\n\n logger.info(\n f\"[WORKFLOW_FILES] {self.get_name()}: Referenced {len(request_files)} files without embedding content\"\n )\n\n # ================================================================================\n # Main Workflow Orchestration\n # ================================================================================\n\n async def execute_workflow(self, arguments: dict[str, Any]) -> list[TextContent]:\n \"\"\"\n Main workflow orchestration following debug tool pattern.\n\n Comprehensive workflow implementation that handles all common patterns:\n 1. Request validation and step management\n 2. Continuation and backtracking support\n 3. Step data processing and consolidation\n 4. Tool-specific field mapping and customization\n 5. Completion logic with optional expert analysis\n 6. Generic \"certain confidence\" handling\n 7. Step guidance and required actions\n 8. Conversation memory integration\n \"\"\"\n from mcp.types import TextContent\n\n try:\n # Store arguments for access by helper methods\n self._current_arguments = arguments\n\n # Validate request using tool-specific model\n request = self.get_workflow_request_model()(**arguments)\n\n # Validate step field size (basic validation for workflow instructions)\n # If step is too large, user should use shorter instructions and put details in files\n step_content = request.step\n if step_content and len(step_content) > MCP_PROMPT_SIZE_LIMIT:\n from tools.models import ToolOutput\n\n error_output = ToolOutput(\n status=\"resend_prompt\",\n content=\"Step instructions are too long. Please use shorter instructions and provide detailed context via file paths instead.\",\n content_type=\"text\",\n metadata={\"prompt_size\": len(step_content), \"limit\": MCP_PROMPT_SIZE_LIMIT},\n )\n raise ValueError(f\"MCP_SIZE_CHECK:{error_output.model_dump_json()}\")\n\n # Validate file paths for security (same as base tool)\n # Use try/except instead of hasattr as per coding standards\n try:\n path_error = self.validate_file_paths(request)\n if path_error:\n from tools.models import ToolOutput\n\n error_output = ToolOutput(\n status=\"error\",\n content=path_error,\n content_type=\"text\",\n )\n logger.error(\"Path validation failed for %s: %s\", self.get_name(), path_error)\n raise ToolExecutionError(error_output.model_dump_json())\n except AttributeError:\n # validate_file_paths method not available - skip validation\n pass\n\n # Try to validate model availability early for production scenarios\n # For tests, defer model validation to later to allow mocks to work\n try:\n model_name, model_context = self._resolve_model_context(arguments, request)\n # Store for later use\n self._current_model_name = model_name\n self._model_context = model_context\n except ValueError as e:\n # Model resolution failed - in production this would be an error,\n # but for tests we defer to allow mocks to handle model resolution\n logger.debug(f\"Early model validation failed, deferring to later: {e}\")\n self._current_model_name = None\n self._model_context = None\n\n # Handle continuation\n continuation_id = request.continuation_id\n\n # Restore workflow state on continuation\n if continuation_id:\n from utils.conversation_memory import get_thread\n\n thread = get_thread(continuation_id)\n if thread and thread.turns:\n # Find the most recent assistant turn from this tool with workflow state\n for turn in reversed(thread.turns):\n if turn.role == \"assistant\" and turn.tool_name == self.get_name() and turn.model_metadata:\n state = turn.model_metadata\n if isinstance(state, dict) and \"work_history\" in state:\n self.work_history = state.get(\"work_history\", [])\n self.initial_request = state.get(\"initial_request\")\n # Rebuild consolidated findings from restored history\n self._reprocess_consolidated_findings()\n logger.debug(\n f\"[{self.get_name()}] Restored workflow state with {len(self.work_history)} history items\"\n )\n break # State restored, exit loop\n\n # Adjust total steps if needed\n if request.step_number > request.total_steps:\n request.total_steps = request.step_number\n\n # Create thread for first step\n if not continuation_id and request.step_number == 1:\n clean_args = {k: v for k, v in arguments.items() if k not in [\"_model_context\", \"_resolved_model_name\"]}\n continuation_id = create_thread(self.get_name(), clean_args)\n self.initial_request = request.step\n # Allow tools to store initial description for expert analysis\n self.store_initial_issue(request.step)\n\n # Process work step - allow tools to customize field mapping\n step_data = self.prepare_step_data(request)\n\n # Store in history\n self.work_history.append(step_data)\n\n # Update consolidated findings\n self._update_consolidated_findings(step_data)\n\n # Handle file context appropriately based on workflow phase\n self._handle_workflow_file_context(request, arguments)\n\n # Build response with tool-specific customization\n response_data = self.build_base_response(request, continuation_id)\n\n # If work is complete, handle completion logic\n if not request.next_step_required:\n response_data = await self.handle_work_completion(response_data, request, arguments)\n else:\n # Force CLI to work before calling tool again\n response_data = self.handle_work_continuation(response_data, request)\n\n # Allow tools to customize the final response\n response_data = self.customize_workflow_response(response_data, request)\n\n # Add metadata (provider_used and model_used) to workflow response\n self._add_workflow_metadata(response_data, arguments)\n\n # Store in conversation memory\n if continuation_id:\n self.store_conversation_turn(continuation_id, response_data, request)\n\n return [TextContent(type=\"text\", text=json.dumps(response_data, indent=2, ensure_ascii=False))]\n\n except ToolExecutionError:\n raise\n except Exception as e:\n if str(e).startswith(\"MCP_SIZE_CHECK:\"):\n payload = str(e)[len(\"MCP_SIZE_CHECK:\") :]\n raise ToolExecutionError(payload)\n\n logger.error(f\"Error in {self.get_name()} work: {e}\", exc_info=True)\n error_data = {\n \"status\": f\"{self.get_name()}_failed\",\n \"error\": str(e),\n \"step_number\": arguments.get(\"step_number\", 0),\n }\n\n # Add metadata to error responses too\n self._add_workflow_metadata(error_data, arguments)\n\n raise ToolExecutionError(json.dumps(error_data, indent=2, ensure_ascii=False)) from e\n\n # Hook methods for tool customization\n\n def prepare_step_data(self, request) -> dict:\n \"\"\"\n Prepare step data from request. Tools can override to customize field mapping.\n \"\"\"\n step_data = {\n \"step\": request.step,\n \"step_number\": request.step_number,\n \"findings\": request.findings,\n \"files_checked\": self.get_request_files_checked(request),\n \"relevant_files\": self.get_request_relevant_files(request),\n \"relevant_context\": self.get_request_relevant_context(request),\n \"issues_found\": self.get_request_issues_found(request),\n \"confidence\": self.get_request_confidence(request),\n \"hypothesis\": self.get_request_hypothesis(request),\n \"images\": self.get_request_images(request),\n }\n return step_data\n\n def build_base_response(self, request, continuation_id: str = None) -> dict:\n \"\"\"\n Build the base response structure. Tools can override for custom response fields.\n \"\"\"\n response_data = {\n \"status\": f\"{self.get_name()}_in_progress\",\n \"step_number\": request.step_number,\n \"total_steps\": request.total_steps,\n \"next_step_required\": request.next_step_required,\n f\"{self.get_name()}_status\": {\n \"files_checked\": len(self.consolidated_findings.files_checked),\n \"relevant_files\": len(self.consolidated_findings.relevant_files),\n \"relevant_context\": len(self.consolidated_findings.relevant_context),\n \"issues_found\": len(self.consolidated_findings.issues_found),\n \"images_collected\": len(self.consolidated_findings.images),\n \"current_confidence\": self.get_request_confidence(request),\n },\n }\n\n if continuation_id:\n response_data[\"continuation_id\"] = continuation_id\n\n # Add file context information based on workflow phase\n embedded_content = self.get_embedded_file_content()\n reference_note = self.get_file_reference_note()\n processed_files = self.get_actually_processed_files()\n\n logger.debug(\n f\"[WORKFLOW_FILES] {self.get_name()}: Building response - has embedded_content: {bool(embedded_content)}, has reference_note: {bool(reference_note)}\"\n )\n\n # Prioritize embedded content over references for final steps\n if embedded_content:\n # Final step - include embedded file information\n logger.debug(f\"[WORKFLOW_FILES] {self.get_name()}: Adding fully_embedded file context\")\n response_data[\"file_context\"] = {\n \"type\": \"fully_embedded\",\n \"files_embedded\": len(processed_files),\n \"context_optimization\": \"Full file content embedded for expert analysis\",\n }\n elif reference_note:\n # Intermediate step - include file reference note\n logger.debug(f\"[WORKFLOW_FILES] {self.get_name()}: Adding reference_only file context\")\n response_data[\"file_context\"] = {\n \"type\": \"reference_only\",\n \"note\": reference_note,\n \"context_optimization\": \"Files referenced but not embedded to preserve the context window\",\n }\n\n return response_data\n\n def should_skip_expert_analysis(self, request, consolidated_findings) -> bool:\n \"\"\"\n Determine if expert analysis should be skipped due to high certainty.\n\n Default: False (always call expert analysis)\n Override in tools like debug to check for \"certain\" confidence.\n \"\"\"\n return False\n\n def handle_completion_without_expert_analysis(self, request, consolidated_findings) -> dict:\n \"\"\"\n Handle completion when skipping expert analysis.\n\n Tools can override this for custom high-confidence completion handling.\n Default implementation provides generic response.\n \"\"\"\n work_summary = self.prepare_work_summary()\n continuation_id = self.get_request_continuation_id(request)\n\n response_data = {\n \"status\": self.get_completion_status(),\n f\"complete_{self.get_name()}\": {\n \"initial_request\": self.get_initial_request(request.step),\n \"steps_taken\": len(consolidated_findings.findings),\n \"files_examined\": list(consolidated_findings.files_checked),\n \"relevant_files\": list(consolidated_findings.relevant_files),\n \"relevant_context\": list(consolidated_findings.relevant_context),\n \"work_summary\": work_summary,\n \"final_analysis\": self.get_final_analysis_from_request(request),\n \"confidence_level\": self.get_confidence_level(request),\n },\n \"next_steps\": self.get_completion_message(),\n \"skip_expert_analysis\": True,\n \"expert_analysis\": {\n \"status\": self.get_skip_expert_analysis_status(),\n \"reason\": self.get_skip_reason(),\n },\n }\n\n if continuation_id:\n response_data[\"continuation_id\"] = continuation_id\n\n return response_data\n\n # ================================================================================\n # Inheritance Hook Methods - Replace hasattr/getattr Anti-patterns\n # ================================================================================\n\n def get_request_confidence(self, request: Any) -> str:\n \"\"\"Get confidence from request. Override for custom confidence handling.\"\"\"\n try:\n return request.confidence or \"low\"\n except AttributeError:\n return \"low\"\n\n def get_request_relevant_context(self, request: Any) -> list[str]:\n \"\"\"Get relevant context from request. Override for custom field mapping.\"\"\"\n try:\n return request.relevant_context or []\n except AttributeError:\n return []\n\n def get_request_issues_found(self, request: Any) -> list[str]:\n \"\"\"Get issues found from request. Override for custom field mapping.\"\"\"\n try:\n return request.issues_found or []\n except AttributeError:\n return []\n\n def get_request_hypothesis(self, request: Any) -> Optional[str]:\n \"\"\"Get hypothesis from request. Override for custom field mapping.\"\"\"\n try:\n return request.hypothesis\n except AttributeError:\n return None\n\n def get_request_images(self, request: Any) -> list[str]:\n \"\"\"Get images from request. Override for custom field mapping.\"\"\"\n try:\n return request.images or []\n except AttributeError:\n return []\n\n # File Context Access Methods\n\n def get_embedded_file_content(self) -> str:\n \"\"\"Get embedded file content. Returns empty string if not available.\"\"\"\n try:\n return self._embedded_file_content or \"\"\n except AttributeError:\n return \"\"\n\n def get_file_reference_note(self) -> str:\n \"\"\"Get file reference note. Returns empty string if not available.\"\"\"\n try:\n return self._file_reference_note or \"\"\n except AttributeError:\n return \"\"\n\n def get_actually_processed_files(self) -> list[str]:\n \"\"\"Get list of actually processed files. Returns empty list if not available.\"\"\"\n try:\n return self._actually_processed_files or []\n except AttributeError:\n return []\n\n def get_current_model_context(self):\n \"\"\"Get current model context. Returns None if not available.\"\"\"\n try:\n return self._model_context\n except AttributeError:\n return None\n\n def get_request_model_name(self, request: Any) -> str:\n \"\"\"Get model name from request. Override for custom model handling.\"\"\"\n try:\n return request.model or \"flash\"\n except AttributeError:\n return \"flash\"\n\n def get_request_continuation_id(self, request: Any) -> Optional[str]:\n \"\"\"Get continuation ID from request. Override for custom continuation handling.\"\"\"\n try:\n return request.continuation_id\n except AttributeError:\n return None\n\n def get_request_next_step_required(self, request: Any) -> bool:\n \"\"\"Get next step required from request. Override for custom step handling.\"\"\"\n try:\n return request.next_step_required\n except AttributeError:\n return True\n\n def get_request_step_number(self, request: Any) -> int:\n \"\"\"Get step number from request. Override for custom step handling.\"\"\"\n try:\n return request.step_number or 1\n except AttributeError:\n return 1\n\n def get_request_relevant_files(self, request: Any) -> list[str]:\n \"\"\"Get relevant files from request. Override for custom file handling.\"\"\"\n try:\n return request.relevant_files or []\n except AttributeError:\n return []\n\n def get_request_files_checked(self, request: Any) -> list[str]:\n \"\"\"Get files checked from request. Override for custom file handling.\"\"\"\n try:\n return request.files_checked or []\n except AttributeError:\n return []\n\n def get_current_arguments(self) -> dict[str, Any]:\n \"\"\"Get current arguments. Returns empty dict if not available.\"\"\"\n try:\n return self._current_arguments or {}\n except AttributeError:\n return {}\n\n def store_initial_issue(self, step_description: str):\n \"\"\"Store initial issue description. Override for custom storage.\"\"\"\n # Default implementation - tools can override to store differently\n self.initial_issue = step_description\n\n def get_initial_request(self, fallback_step: str) -> str:\n \"\"\"Get initial request description. Override for custom retrieval.\"\"\"\n try:\n return self.initial_request or fallback_step\n except AttributeError:\n return fallback_step\n\n # Default implementations for inheritance hooks\n\n def prepare_work_summary(self) -> str:\n \"\"\"Prepare work summary. Override for custom implementation.\"\"\"\n return f\"Completed {len(self.consolidated_findings.findings)} work steps\"\n\n def get_completion_status(self) -> str:\n \"\"\"Get completion status. Override for tool-specific status.\"\"\"\n return \"high_confidence_completion\"\n\n def get_final_analysis_from_request(self, request):\n \"\"\"Extract final analysis from request. Override for tool-specific fields.\"\"\"\n return self.get_request_hypothesis(request)\n\n def get_confidence_level(self, request) -> str:\n \"\"\"Get confidence level. Override for tool-specific confidence handling.\"\"\"\n return self.get_request_confidence(request) or \"high\"\n\n def get_completion_message(self) -> str:\n \"\"\"Get completion message. Override for tool-specific messaging.\"\"\"\n return (\n f\"{self.get_name().capitalize()} complete with high confidence. Present results \"\n \"and proceed with implementation without requiring further consultation.\"\n )\n\n def get_skip_reason(self) -> str:\n \"\"\"Get reason for skipping expert analysis. Override for tool-specific reasons.\"\"\"\n return f\"{self.get_name()} completed with sufficient confidence\"\n\n def get_skip_expert_analysis_status(self) -> str:\n \"\"\"Get status for skipped expert analysis. Override for tool-specific status.\"\"\"\n return \"skipped_by_tool_design\"\n\n def get_completion_next_steps_message(self, expert_analysis_used: bool = False) -> str:\n \"\"\"\n Get the message to show when work is complete.\n Tools can override for custom messaging.\n\n Args:\n expert_analysis_used: True if expert analysis was successfully executed\n \"\"\"\n base_message = (\n f\"{self.get_name().upper()} IS COMPLETE. You MUST now summarize and present ALL key findings, confirmed \"\n \"hypotheses, and exact recommended solutions. Clearly identify the most likely root cause and \"\n \"provide concrete, actionable implementation guidance. Highlight affected code paths and display \"\n \"reasoning that led to this conclusionβ€”make it easy for a developer to understand exactly where \"\n \"the problem lies.\"\n )\n\n # Add expert analysis guidance only when expert analysis was actually used\n if expert_analysis_used:\n expert_guidance = self.get_expert_analysis_guidance()\n if expert_guidance:\n return f\"{base_message}\\n\\n{expert_guidance}\"\n\n return base_message\n\n def get_expert_analysis_guidance(self) -> str:\n \"\"\"\n Get additional guidance for handling expert analysis results.\n\n Subclasses can override this to provide specific instructions about how\n to validate and use expert analysis findings. Returns empty string by default.\n\n When expert analysis is called, this guidance will be:\n 1. Appended to the completion next steps message\n 2. Added as \"important_considerations\" field in the response data\n\n Example implementation:\n ```python\n def get_expert_analysis_guidance(self) -> str:\n return (\n \"IMPORTANT: Expert analysis provided above. You MUST validate \"\n \"the expert findings rather than accepting them blindly. \"\n \"Cross-reference with your own investigation and ensure \"\n \"recommendations align with the codebase context.\"\n )\n ```\n\n Returns:\n Additional guidance text or empty string if no guidance needed\n \"\"\"\n return \"\"\n\n def customize_workflow_response(self, response_data: dict, request) -> dict:\n \"\"\"\n Allow tools to customize the workflow response before returning.\n\n Tools can override this to add tool-specific fields, modify status names,\n customize field mapping, etc. Default implementation returns unchanged.\n \"\"\"\n # Ensure file context information is preserved in all response paths\n if not response_data.get(\"file_context\"):\n embedded_content = self.get_embedded_file_content()\n reference_note = self.get_file_reference_note()\n processed_files = self.get_actually_processed_files()\n\n # Prioritize embedded content over references for final steps\n if embedded_content:\n response_data[\"file_context\"] = {\n \"type\": \"fully_embedded\",\n \"files_embedded\": len(processed_files),\n \"context_optimization\": \"Full file content embedded for expert analysis\",\n }\n elif reference_note:\n response_data[\"file_context\"] = {\n \"type\": \"reference_only\",\n \"note\": reference_note,\n \"context_optimization\": \"Files referenced but not embedded to preserve the context window\",\n }\n\n return response_data\n\n def store_conversation_turn(self, continuation_id: str, response_data: dict, request):\n \"\"\"\n Store the conversation turn. Tools can override for custom memory storage.\n \"\"\"\n # CRITICAL: Extract clean content for conversation history (exclude internal workflow metadata)\n clean_content = self._extract_clean_workflow_content_for_history(response_data)\n\n # Serialize workflow state for persistence across stateless tool calls\n workflow_state = {\"work_history\": self.work_history, \"initial_request\": getattr(self, \"initial_request\", None)}\n\n add_turn(\n thread_id=continuation_id,\n role=\"assistant\",\n content=clean_content, # Use cleaned content instead of full response_data\n tool_name=self.get_name(),\n files=self.get_request_relevant_files(request),\n images=self.get_request_images(request),\n model_metadata=workflow_state, # Persist the state\n )\n\n def _add_workflow_metadata(self, response_data: dict, arguments: dict[str, Any]) -> None:\n \"\"\"\n Add metadata (provider_used and model_used) to workflow response.\n\n This ensures workflow tools have the same metadata as regular tools,\n making it consistent across all tool types for tracking which provider\n and model were used for the response.\n\n Args:\n response_data: The response data dictionary to modify\n arguments: The original arguments containing model context\n \"\"\"\n try:\n # Get model information from arguments (set by server.py)\n resolved_model_name = arguments.get(\"_resolved_model_name\")\n model_context = arguments.get(\"_model_context\")\n\n if resolved_model_name and model_context:\n # Extract provider information from model context\n provider = model_context.provider\n provider_name = provider.get_provider_type().value if provider else \"unknown\"\n\n # Create metadata dictionary\n metadata = {\n \"tool_name\": self.get_name(),\n \"model_used\": resolved_model_name,\n \"provider_used\": provider_name,\n }\n\n # Preserve existing metadata and add workflow metadata\n if \"metadata\" not in response_data:\n response_data[\"metadata\"] = {}\n response_data[\"metadata\"].update(metadata)\n\n logger.debug(\n f\"[WORKFLOW_METADATA] {self.get_name()}: Added metadata - \"\n f\"model: {resolved_model_name}, provider: {provider_name}\"\n )\n else:\n # Fallback - try to get model info from request\n request = self.get_workflow_request_model()(**arguments)\n model_name = self.get_request_model_name(request)\n\n # Basic metadata without provider info\n metadata = {\n \"tool_name\": self.get_name(),\n \"model_used\": model_name,\n \"provider_used\": \"unknown\",\n }\n\n # Preserve existing metadata and add workflow metadata\n if \"metadata\" not in response_data:\n response_data[\"metadata\"] = {}\n response_data[\"metadata\"].update(metadata)\n\n logger.debug(\n f\"[WORKFLOW_METADATA] {self.get_name()}: Added fallback metadata - \"\n f\"model: {model_name}, provider: unknown\"\n )\n\n except Exception as e:\n # Don't fail the workflow if metadata addition fails\n logger.warning(f\"[WORKFLOW_METADATA] {self.get_name()}: Failed to add metadata: {e}\")\n # Still add basic metadata with tool name\n response_data[\"metadata\"] = {\"tool_name\": self.get_name()}\n\n def _extract_clean_workflow_content_for_history(self, response_data: dict) -> str:\n \"\"\"\n Extract clean content from workflow response suitable for conversation history.\n\n This method removes internal workflow metadata, continuation offers, and\n status information that should not appear when the conversation is\n reconstructed for expert models or other tools.\n\n Args:\n response_data: The full workflow response data\n\n Returns:\n str: Clean content suitable for conversation history storage\n \"\"\"\n # Create a clean copy with only essential content for conversation history\n clean_data = {}\n\n # Include core content if present\n if \"content\" in response_data:\n clean_data[\"content\"] = response_data[\"content\"]\n\n # Include expert analysis if present (but clean it)\n if \"expert_analysis\" in response_data:\n expert_analysis = response_data[\"expert_analysis\"]\n if isinstance(expert_analysis, dict):\n # Only include the actual analysis content, not metadata\n clean_expert = {}\n if \"raw_analysis\" in expert_analysis:\n clean_expert[\"analysis\"] = expert_analysis[\"raw_analysis\"]\n elif \"content\" in expert_analysis:\n clean_expert[\"analysis\"] = expert_analysis[\"content\"]\n if clean_expert:\n clean_data[\"expert_analysis\"] = clean_expert\n\n # Include findings/issues if present (core workflow output)\n if \"complete_analysis\" in response_data:\n complete_analysis = response_data[\"complete_analysis\"]\n if isinstance(complete_analysis, dict):\n clean_complete = {}\n # Include essential analysis data without internal metadata\n for key in [\"findings\", \"issues_found\", \"relevant_context\", \"insights\"]:\n if key in complete_analysis:\n clean_complete[key] = complete_analysis[key]\n if clean_complete:\n clean_data[\"analysis_summary\"] = clean_complete\n\n # Include step information for context but remove internal workflow metadata\n if \"step_number\" in response_data:\n clean_data[\"step_info\"] = {\n \"step\": response_data.get(\"step\", \"\"),\n \"step_number\": response_data.get(\"step_number\", 1),\n \"total_steps\": response_data.get(\"total_steps\", 1),\n }\n\n # Exclude problematic fields that should never appear in conversation history:\n # - continuation_id (confuses LLMs with old IDs)\n # - status (internal workflow state)\n # - next_step_required (internal control flow)\n # - analysis_status (internal tracking)\n # - file_context (internal optimization info)\n # - required_actions (internal workflow instructions)\n\n return json.dumps(clean_data, indent=2, ensure_ascii=False)\n\n # Core workflow logic methods\n\n async def handle_work_completion(self, response_data: dict, request, arguments: dict) -> dict:\n \"\"\"\n Handle work completion logic - expert analysis decision and response building.\n \"\"\"\n response_data[f\"{self.get_name()}_complete\"] = True\n\n # Check if tool wants to skip expert analysis due to high certainty\n if self.should_skip_expert_analysis(request, self.consolidated_findings):\n # Handle completion without expert analysis\n completion_response = self.handle_completion_without_expert_analysis(request, self.consolidated_findings)\n response_data.update(completion_response)\n elif self.requires_expert_analysis() and self.should_call_expert_analysis(self.consolidated_findings, request):\n # Standard expert analysis path\n response_data[\"status\"] = \"calling_expert_analysis\"\n\n # Call expert analysis\n expert_analysis = await self._call_expert_analysis(arguments, request)\n response_data[\"expert_analysis\"] = expert_analysis\n\n # Handle special expert analysis statuses\n if isinstance(expert_analysis, dict) and expert_analysis.get(\"status\") in [\n \"files_required_to_continue\",\n \"investigation_paused\",\n \"refactoring_paused\",\n ]:\n # Promote the special status to the main response\n special_status = expert_analysis[\"status\"]\n response_data[\"status\"] = special_status\n response_data[\"content\"] = expert_analysis.get(\n \"raw_analysis\", json.dumps(expert_analysis, ensure_ascii=False)\n )\n del response_data[\"expert_analysis\"]\n\n # Update next steps for special status\n if special_status == \"files_required_to_continue\":\n response_data[\"next_steps\"] = \"Provide the requested files and continue the analysis.\"\n else:\n response_data[\"next_steps\"] = expert_analysis.get(\n \"next_steps\", \"Continue based on expert analysis.\"\n )\n elif isinstance(expert_analysis, dict) and expert_analysis.get(\"status\") == \"analysis_error\":\n # Expert analysis failed - promote error status\n response_data[\"status\"] = \"error\"\n response_data[\"content\"] = expert_analysis.get(\"error\", \"Expert analysis failed\")\n response_data[\"content_type\"] = \"text\"\n del response_data[\"expert_analysis\"]\n else:\n # Expert analysis was successfully executed - include expert guidance\n response_data[\"next_steps\"] = self.get_completion_next_steps_message(expert_analysis_used=True)\n\n # Add expert analysis guidance as important considerations\n expert_guidance = self.get_expert_analysis_guidance()\n if expert_guidance:\n response_data[\"important_considerations\"] = expert_guidance\n\n # Prepare complete work summary\n work_summary = self._prepare_work_summary()\n response_data[f\"complete_{self.get_name()}\"] = {\n \"initial_request\": self.get_initial_request(request.step),\n \"steps_taken\": len(self.work_history),\n \"files_examined\": list(self.consolidated_findings.files_checked),\n \"relevant_files\": list(self.consolidated_findings.relevant_files),\n \"relevant_context\": list(self.consolidated_findings.relevant_context),\n \"issues_found\": self.consolidated_findings.issues_found,\n \"work_summary\": work_summary,\n }\n else:\n # Tool doesn't require expert analysis or local work was sufficient\n if not self.requires_expert_analysis():\n # Tool is self-contained (like planner)\n response_data[\"status\"] = f\"{self.get_name()}_complete\"\n response_data[\"next_steps\"] = (\n f\"{self.get_name().capitalize()} work complete. Present results to the user.\"\n )\n else:\n # Local work was sufficient for tools that support expert analysis\n response_data[\"status\"] = \"local_work_complete\"\n response_data[\"next_steps\"] = (\n f\"Local {self.get_name()} complete with sufficient confidence. Present findings \"\n \"and recommendations to the user based on the work results.\"\n )\n\n return response_data\n\n def handle_work_continuation(self, response_data: dict, request) -> dict:\n \"\"\"\n Handle work continuation - force pause and provide guidance.\n \"\"\"\n response_data[\"status\"] = f\"pause_for_{self.get_name()}\"\n response_data[f\"{self.get_name()}_required\"] = True\n\n # Get tool-specific required actions\n required_actions = self.get_required_actions(\n request.step_number, self.get_request_confidence(request), request.findings, request.total_steps, request\n )\n response_data[\"required_actions\"] = required_actions\n\n # Generate step guidance\n response_data[\"next_steps\"] = self.get_step_guidance_message(request)\n\n return response_data\n\n def _update_consolidated_findings(self, step_data: dict):\n \"\"\"Update consolidated findings with new step data\"\"\"\n self.consolidated_findings.files_checked.update(step_data.get(\"files_checked\", []))\n self.consolidated_findings.relevant_files.update(step_data.get(\"relevant_files\", []))\n self.consolidated_findings.relevant_context.update(step_data.get(\"relevant_context\", []))\n self.consolidated_findings.findings.append(f\"Step {step_data['step_number']}: {step_data['findings']}\")\n if step_data.get(\"hypothesis\"):\n self.consolidated_findings.hypotheses.append(\n {\n \"step\": step_data[\"step_number\"],\n \"hypothesis\": step_data[\"hypothesis\"],\n \"confidence\": step_data[\"confidence\"],\n }\n )\n if step_data.get(\"issues_found\"):\n self.consolidated_findings.issues_found.extend(step_data[\"issues_found\"])\n if step_data.get(\"images\"):\n self.consolidated_findings.images.extend(step_data[\"images\"])\n # Update confidence to latest value from this step\n if step_data.get(\"confidence\"):\n self.consolidated_findings.confidence = step_data[\"confidence\"]\n\n def _reprocess_consolidated_findings(self):\n \"\"\"Reprocess consolidated findings after backtracking\"\"\"\n self.consolidated_findings = ConsolidatedFindings()\n for step in self.work_history:\n self._update_consolidated_findings(step)\n\n def _prepare_work_summary(self) -> str:\n \"\"\"Prepare a comprehensive summary of the work\"\"\"\n summary_parts = [\n f\"=== {self.get_name().upper()} WORK SUMMARY ===\",\n f\"Total steps: {len(self.work_history)}\",\n f\"Files examined: {len(self.consolidated_findings.files_checked)}\",\n f\"Relevant files identified: {len(self.consolidated_findings.relevant_files)}\",\n f\"Methods/functions involved: {len(self.consolidated_findings.relevant_context)}\",\n f\"Issues found: {len(self.consolidated_findings.issues_found)}\",\n \"\",\n \"=== WORK PROGRESSION ===\",\n ]\n\n for finding in self.consolidated_findings.findings:\n summary_parts.append(finding)\n\n if self.consolidated_findings.hypotheses:\n summary_parts.extend(\n [\n \"\",\n \"=== HYPOTHESIS EVOLUTION ===\",\n ]\n )\n for hyp in self.consolidated_findings.hypotheses:\n summary_parts.append(f\"Step {hyp['step']} ({hyp['confidence']} confidence): {hyp['hypothesis']}\")\n\n if self.consolidated_findings.issues_found:\n summary_parts.extend(\n [\n \"\",\n \"=== ISSUES IDENTIFIED ===\",\n ]\n )\n for issue in self.consolidated_findings.issues_found:\n severity = issue.get(\"severity\", \"unknown\")\n description = issue.get(\"description\", \"No description\")\n summary_parts.append(f\"[{severity.upper()}] {description}\")\n\n return \"\\n\".join(summary_parts)\n\n async def _call_expert_analysis(self, arguments: dict, request) -> dict:\n \"\"\"Call external model for expert analysis\"\"\"\n try:\n # Model context should be resolved from early validation, but handle fallback for tests\n if not self._model_context:\n # Try to resolve model context for expert analysis (deferred from early validation)\n try:\n model_name, model_context = self._resolve_model_context(arguments, request)\n self._model_context = model_context\n self._current_model_name = model_name\n except Exception as e:\n logger.error(f\"Failed to resolve model context for expert analysis: {e}\")\n # Use request model as fallback (preserves existing test behavior)\n model_name = self.get_request_model_name(request)\n from utils.model_context import ModelContext\n\n model_context = ModelContext(model_name)\n self._model_context = model_context\n self._current_model_name = model_name\n else:\n model_name = self._current_model_name\n\n provider = self._model_context.provider\n\n # Prepare expert analysis context\n expert_context = self.prepare_expert_analysis_context(self.consolidated_findings)\n\n # Check if tool wants to include files in prompt\n if self.should_include_files_in_expert_prompt():\n file_content = self._prepare_files_for_expert_analysis()\n if file_content:\n expert_context = self._add_files_to_expert_context(expert_context, file_content)\n\n # Get system prompt for this tool with localization support\n base_system_prompt = self.get_system_prompt()\n capability_augmented_prompt = self._augment_system_prompt_with_capabilities(\n base_system_prompt, getattr(self._model_context, \"capabilities\", None)\n )\n language_instruction = self.get_language_instruction()\n system_prompt = language_instruction + capability_augmented_prompt\n\n # Check if tool wants system prompt embedded in main prompt\n if self.should_embed_system_prompt():\n prompt = f\"{system_prompt}\\n\\n{expert_context}\\n\\n{self.get_expert_analysis_instruction()}\"\n system_prompt = \"\" # Clear it since we embedded it\n else:\n prompt = expert_context\n\n # Validate temperature against model constraints\n validated_temperature, temp_warnings = self.get_validated_temperature(request, self._model_context)\n\n # Log any temperature corrections\n for warning in temp_warnings:\n logger.warning(warning)\n\n # Generate AI response - use request parameters if available\n model_response = provider.generate_content(\n prompt=prompt,\n model_name=model_name,\n system_prompt=system_prompt,\n temperature=validated_temperature,\n thinking_mode=self.get_request_thinking_mode(request),\n images=list(set(self.consolidated_findings.images)) if self.consolidated_findings.images else None,\n )\n\n if model_response.content:\n content = model_response.content.strip()\n\n # Try to extract JSON from markdown code blocks if present\n if \"```json\" in content or \"```\" in content:\n json_match = re.search(r\"```(?:json)?\\s*(.*?)\\s*```\", content, re.DOTALL)\n if json_match:\n content = json_match.group(1).strip()\n\n try:\n # Try to parse as JSON\n analysis_result = json.loads(content)\n return analysis_result\n except json.JSONDecodeError as e:\n # Log the parse error with more details but don't fail\n logger.info(\n f\"[{self.get_name()}] Expert analysis returned non-JSON response (this is OK for smaller models). \"\n f\"Parse error: {str(e)}. Response length: {len(model_response.content)} chars.\"\n )\n logger.debug(f\"First 500 chars of response: {model_response.content[:500]!r}\")\n\n # Still return the analysis as plain text - this is valid\n return {\n \"status\": \"analysis_complete\",\n \"raw_analysis\": model_response.content,\n \"format\": \"text\", # Indicate it's plain text, not an error\n \"note\": \"Analysis provided in plain text format\",\n }\n else:\n return {\"error\": \"No response from model\", \"status\": \"empty_response\"}\n\n except Exception as e:\n logger.error(f\"Error calling expert analysis: {e}\", exc_info=True)\n return {\"error\": str(e), \"status\": \"analysis_error\"}\n\n def _process_work_step(self, step_data: dict):\n \"\"\"\n Process a single work step and update internal state.\n\n This method is useful for testing and manual step processing.\n It adds the step to work history and updates consolidated findings.\n\n Args:\n step_data: Dictionary containing step information including:\n step, step_number, findings, files_checked, etc.\n \"\"\"\n # Store in history\n self.work_history.append(step_data)\n\n # Update consolidated findings\n self._update_consolidated_findings(step_data)\n\n # Common execute method for workflow-based tools\n\n async def execute(self, arguments: dict[str, Any]) -> list[TextContent]:\n \"\"\"\n Common execute logic for workflow-based tools.\n\n This method provides common validation and delegates to execute_workflow.\n Tools that need custom execute logic can override this method.\n \"\"\"\n try:\n # Common validation\n if not arguments:\n error_data = {\"status\": \"error\", \"content\": \"No arguments provided\"}\n # Add basic metadata even for validation errors\n error_data[\"metadata\"] = {\"tool_name\": self.get_name()}\n raise ToolExecutionError(json.dumps(error_data, ensure_ascii=False))\n\n # Delegate to execute_workflow\n return await self.execute_workflow(arguments)\n\n except ToolExecutionError:\n raise\n except Exception as e:\n logger.error(f\"Error in {self.get_name()} tool execution: {e}\", exc_info=True)\n error_data = {\n \"status\": \"error\",\n \"content\": f\"Error in {self.get_name()}: {str(e)}\",\n } # Add metadata to error responses\n self._add_workflow_metadata(error_data, arguments)\n raise ToolExecutionError(json.dumps(error_data, ensure_ascii=False)) from e\n\n # Default implementations for methods that workflow-based tools typically don't need\n\n async def prepare_prompt(self, request) -> str:\n \"\"\"\n Base implementation for workflow tools - compatible with BaseTool signature.\n\n Workflow tools typically don't need to return a prompt since they handle\n their own prompt preparation internally through the workflow execution.\n\n Args:\n request: The validated request object\n\n Returns:\n Empty string since workflow tools manage prompts internally\n \"\"\"\n # Workflow tools handle their prompts internally during workflow execution\n return \"\"\n\n def format_response(self, response: str, request, model_info=None):\n \"\"\"\n Workflow tools handle their own response formatting.\n The BaseWorkflowMixin formats responses internally.\n \"\"\"\n return response\n" }, { "path": "utils/__init__.py", "content": "\"\"\"\nUtility functions for PAL MCP Server\n\"\"\"\n\nfrom .file_types import CODE_EXTENSIONS, FILE_CATEGORIES, PROGRAMMING_EXTENSIONS, TEXT_EXTENSIONS\nfrom .file_utils import expand_paths, read_file_content, read_files\nfrom .security_config import EXCLUDED_DIRS\nfrom .token_utils import check_token_limit, estimate_tokens\n\n__all__ = [\n \"read_files\",\n \"read_file_content\",\n \"expand_paths\",\n \"CODE_EXTENSIONS\",\n \"PROGRAMMING_EXTENSIONS\",\n \"TEXT_EXTENSIONS\",\n \"FILE_CATEGORIES\",\n \"EXCLUDED_DIRS\",\n \"estimate_tokens\",\n \"check_token_limit\",\n]\n" }, { "path": "utils/client_info.py", "content": "\"\"\"\nClient Information Utility for MCP Server\n\nThis module provides utilities to extract and format client information\nfrom the MCP protocol's clientInfo sent during initialization.\n\nIt also provides friendly name mapping and caching for consistent client\nidentification across the application.\n\"\"\"\n\nimport logging\nfrom typing import Any, Optional\n\nlogger = logging.getLogger(__name__)\n\n# Global cache for client information\n_client_info_cache: Optional[dict[str, Any]] = None\n\n# Mapping of known client names to friendly names\n# This is case-insensitive and checks if the key is contained in the client name\nCLIENT_NAME_MAPPINGS = {\n # Claude variants\n \"claude-ai\": \"Claude\",\n \"claude\": \"Claude\",\n \"claude-desktop\": \"Claude\",\n \"claude-code\": \"Claude\",\n \"anthropic\": \"Claude\",\n # Gemini variants\n \"gemini-cli-mcp-client\": \"Gemini\",\n \"gemini-cli\": \"Gemini\",\n \"gemini\": \"Gemini\",\n \"google\": \"Gemini\",\n # Other known clients\n \"cursor\": \"Cursor\",\n \"vscode\": \"VS Code\",\n \"codeium\": \"Codeium\",\n \"copilot\": \"GitHub Copilot\",\n # Generic MCP clients\n \"mcp-client\": \"MCP Client\",\n \"test-client\": \"Test Client\",\n}\n\n# Default friendly name when no match is found\nDEFAULT_FRIENDLY_NAME = \"Claude\"\n\n\ndef get_friendly_name(client_name: str) -> str:\n \"\"\"\n Map a client name to a friendly name.\n\n Args:\n client_name: The raw client name from clientInfo\n\n Returns:\n A friendly name for display (e.g., \"Claude\", \"Gemini\")\n \"\"\"\n if not client_name:\n return DEFAULT_FRIENDLY_NAME\n\n # Convert to lowercase for case-insensitive matching\n client_name_lower = client_name.lower()\n\n # Check each mapping - using 'in' to handle partial matches\n for key, friendly_name in CLIENT_NAME_MAPPINGS.items():\n if key.lower() in client_name_lower:\n return friendly_name\n\n # If no match found, return the default\n return DEFAULT_FRIENDLY_NAME\n\n\ndef get_cached_client_info() -> Optional[dict[str, Any]]:\n \"\"\"\n Get cached client information if available.\n\n Returns:\n Cached client info dictionary or None\n \"\"\"\n global _client_info_cache\n return _client_info_cache\n\n\ndef get_client_info_from_context(server: Any) -> Optional[dict[str, Any]]:\n \"\"\"\n Extract client information from the MCP server's request context.\n\n The MCP protocol sends clientInfo during initialization containing:\n - name: The client application name (e.g., \"Claude Code\", \"Claude Desktop\")\n - version: The client version string\n\n This function also adds a friendly_name field and caches the result.\n\n Args:\n server: The MCP server instance\n\n Returns:\n Dictionary with client info or None if not available:\n {\n \"name\": \"claude-ai\",\n \"version\": \"1.0.0\",\n \"friendly_name\": \"Claude\"\n }\n \"\"\"\n global _client_info_cache\n\n # Return cached info if available\n if _client_info_cache is not None:\n return _client_info_cache\n\n try:\n # Try to access the request context and session\n if not server:\n return None\n\n # Check if server has request_context property\n request_context = None\n try:\n request_context = server.request_context\n except AttributeError:\n logger.debug(\"Server does not have request_context property\")\n return None\n\n if not request_context:\n logger.debug(\"Request context is None\")\n return None\n\n # Try to access session from request context\n session = None\n try:\n session = request_context.session\n except AttributeError:\n logger.debug(\"Request context does not have session property\")\n return None\n\n if not session:\n logger.debug(\"Session is None\")\n return None\n\n # Try to access client params from session\n client_params = None\n try:\n # The clientInfo is stored in _client_params.clientInfo\n client_params = session._client_params\n except AttributeError:\n logger.debug(\"Session does not have _client_params property\")\n return None\n\n if not client_params:\n logger.debug(\"Client params is None\")\n return None\n\n # Try to extract clientInfo\n client_info = None\n try:\n client_info = client_params.clientInfo\n except AttributeError:\n logger.debug(\"Client params does not have clientInfo property\")\n return None\n\n if not client_info:\n logger.debug(\"Client info is None\")\n return None\n\n # Extract name and version\n result = {}\n\n try:\n result[\"name\"] = client_info.name\n except AttributeError:\n logger.debug(\"Client info does not have name property\")\n\n try:\n result[\"version\"] = client_info.version\n except AttributeError:\n logger.debug(\"Client info does not have version property\")\n\n if not result:\n return None\n\n # Add friendly name\n raw_name = result.get(\"name\", \"\")\n result[\"friendly_name\"] = get_friendly_name(raw_name)\n\n # Cache the result\n _client_info_cache = result\n logger.debug(f\"Cached client info: {result}\")\n\n return result\n\n except Exception as e:\n logger.debug(f\"Error extracting client info: {e}\")\n return None\n\n\ndef format_client_info(client_info: Optional[dict[str, Any]], use_friendly_name: bool = True) -> str:\n \"\"\"\n Format client information for display.\n\n Args:\n client_info: Dictionary with client info or None\n use_friendly_name: If True, use the friendly name instead of raw name\n\n Returns:\n Formatted string like \"Claude v1.0.0\" or \"Claude\"\n \"\"\"\n if not client_info:\n return DEFAULT_FRIENDLY_NAME\n\n if use_friendly_name:\n name = client_info.get(\"friendly_name\", client_info.get(\"name\", DEFAULT_FRIENDLY_NAME))\n else:\n name = client_info.get(\"name\", \"Unknown\")\n\n version = client_info.get(\"version\", \"\")\n\n if version and not use_friendly_name:\n return f\"{name} v{version}\"\n else:\n # For friendly names, we just return the name without version\n return name\n\n\ndef get_client_friendly_name() -> str:\n \"\"\"\n Get the cached client's friendly name.\n\n This is a convenience function that returns just the friendly name\n from the cached client info, defaulting to \"Claude\" if not available.\n\n Returns:\n The friendly name (e.g., \"Claude\", \"Gemini\")\n \"\"\"\n cached_info = get_cached_client_info()\n if cached_info:\n return cached_info.get(\"friendly_name\", DEFAULT_FRIENDLY_NAME)\n return DEFAULT_FRIENDLY_NAME\n\n\ndef log_client_info(server: Any, logger_instance: Optional[logging.Logger] = None) -> None:\n \"\"\"\n Log client information extracted from the server.\n\n Args:\n server: The MCP server instance\n logger_instance: Optional logger to use (defaults to module logger)\n \"\"\"\n log = logger_instance or logger\n\n client_info = get_client_info_from_context(server)\n if client_info:\n # Log with both raw and friendly names for debugging\n raw_name = client_info.get(\"name\", \"Unknown\")\n friendly_name = client_info.get(\"friendly_name\", DEFAULT_FRIENDLY_NAME)\n version = client_info.get(\"version\", \"\")\n\n if raw_name != friendly_name:\n log.info(f\"MCP Client Connected: {friendly_name} (raw: {raw_name} v{version})\")\n else:\n log.info(f\"MCP Client Connected: {friendly_name} v{version}\")\n\n # Log to activity logger as well\n try:\n activity_logger = logging.getLogger(\"mcp_activity\")\n activity_logger.info(f\"CLIENT_IDENTIFIED: {friendly_name} (name={raw_name}, version={version})\")\n except Exception:\n pass\n else:\n log.debug(\"Could not extract client info from MCP protocol\")\n\n\n# Example usage in tools:\n#\n# from utils.client_info import get_client_friendly_name, get_cached_client_info\n#\n# # In a tool's execute method:\n# def execute(self, arguments: dict[str, Any]) -> list[TextContent]:\n# # Get the friendly name of the connected client\n# client_name = get_client_friendly_name() # Returns \"Claude\" or \"Gemini\" etc.\n#\n# # Or get full cached info if needed\n# client_info = get_cached_client_info()\n# if client_info:\n# raw_name = client_info['name'] # e.g., \"claude-ai\"\n# version = client_info['version'] # e.g., \"1.0.0\"\n# friendly = client_info['friendly_name'] # e.g., \"Claude\"\n#\n# # Customize response based on client\n# if client_name == \"Claude\":\n# response = f\"Hello from PAL MCP Server to {client_name}!\"\n# elif client_name == \"Gemini\":\n# response = f\"Greetings {client_name}, welcome to PAL MCP Server!\"\n# else:\n# response = f\"Welcome {client_name}!\"\n" }, { "path": "utils/conversation_memory.py", "content": "\"\"\"\nConversation Memory for AI-to-AI Multi-turn Discussions\n\nThis module provides conversation persistence and context reconstruction for\nstateless MCP (Model Context Protocol) environments. It enables multi-turn\nconversations between the agent and downstream models by storing conversation\nstate in memory across independent request cycles.\n\nCRITICAL ARCHITECTURAL REQUIREMENT:\nThis conversation memory system is designed for PERSISTENT MCP SERVER PROCESSES.\nIt uses in-memory storage that persists only within a single Python process.\n\n⚠️ IMPORTANT: This system will NOT work correctly if MCP tool calls are made\n as separate subprocess invocations (each subprocess starts with empty memory).\n\n WORKING SCENARIO: Claude Desktop with persistent MCP server process\n FAILING SCENARIO: Simulator tests calling server.py as individual subprocesses\n\n Root cause of test failures: Each subprocess call loses the conversation\n state from previous calls because memory is process-specific, not shared\n across subprocess boundaries.\n\nARCHITECTURE OVERVIEW:\nThe MCP protocol is inherently stateless - each tool request is independent\nwith no memory of previous interactions. This module bridges that gap by:\n\n1. Creating persistent conversation threads with unique UUIDs\n2. Storing complete conversation context (turns, files, metadata) in memory\n3. Reconstructing conversation history when tools are called with continuation_id\n4. Supporting cross-tool continuation - seamlessly switch between different tools\n while maintaining full conversation context and file references\n\nCROSS-TOOL CONTINUATION:\nA conversation started with one tool (e.g., 'analyze') can be continued with\nany other tool (e.g., 'codereview', 'debug', 'chat') using the same continuation_id.\nThe second tool will have access to:\n- All previous conversation turns and responses\n- File context from previous tools (preserved in conversation history)\n- Original thread metadata and timing information\n- Accumulated knowledge from the entire conversation\n\nKey Features:\n- UUID-based conversation thread identification with security validation\n- Turn-by-turn conversation history storage with tool attribution\n- Cross-tool continuation support - switch tools while preserving context\n- File context preservation - files shared in earlier turns remain accessible\n- NEWEST-FIRST FILE PRIORITIZATION - when the same file appears in multiple turns,\n references from newer turns take precedence over older ones. This ensures the\n most recent file context is preserved when token limits require exclusions.\n- Automatic turn limiting (20 turns max) to prevent runaway conversations\n- Context reconstruction for stateless request continuity\n- In-memory persistence with automatic expiration (3 hour TTL)\n- Thread-safe operations for concurrent access\n- Graceful degradation when storage is unavailable\n\nDUAL PRIORITIZATION STRATEGY (Files & Conversations):\nThe conversation memory system implements sophisticated prioritization for both files and\nconversation turns, using a consistent \"newest-first\" approach during collection but\npresenting information in the optimal format for LLM consumption:\n\nFILE PRIORITIZATION (Newest-First Throughout):\n1. When collecting files across conversation turns, the system walks BACKWARDS through\n turns (newest to oldest) and builds a unique file list\n2. If the same file path appears in multiple turns, only the reference from the\n NEWEST turn is kept in the final list\n3. This \"newest-first\" ordering is preserved throughout the entire pipeline:\n - get_conversation_file_list() establishes the order\n - build_conversation_history() maintains it during token budgeting\n - When token limits are hit, OLDER files are excluded first\n4. This strategy works across conversation chains - files from newer turns in ANY\n thread take precedence over files from older turns in ANY thread\n\nCONVERSATION TURN PRIORITIZATION (Newest-First Collection, Chronological Presentation):\n1. COLLECTION PHASE: Processes turns newest-to-oldest to prioritize recent context\n - When token budget is tight, OLDER turns are excluded first\n - Ensures most contextually relevant recent exchanges are preserved\n2. PRESENTATION PHASE: Reverses collected turns to chronological order (oldest-first)\n - LLM sees natural conversation flow: \"Turn 1 β†’ Turn 2 β†’ Turn 3...\"\n - Maintains proper sequential understanding while preserving recency prioritization\n\nThis dual approach ensures optimal context preservation (newest-first) with natural\nconversation flow (chronological) for maximum LLM comprehension and relevance.\n\nUSAGE EXAMPLE:\n1. Tool A creates thread: create_thread(\"analyze\", request_data) β†’ returns UUID\n2. Tool A adds response: add_turn(UUID, \"assistant\", response, files=[...], tool_name=\"analyze\")\n3. Tool B continues thread: get_thread(UUID) β†’ retrieves full context\n4. Tool B sees conversation history via build_conversation_history()\n5. Tool B adds its response: add_turn(UUID, \"assistant\", response, tool_name=\"codereview\")\n\nDUAL STRATEGY EXAMPLE:\nConversation has 5 turns, token budget allows only 3 turns:\n\nCollection Phase (Newest-First Priority):\n- Evaluates: Turn 5 β†’ Turn 4 β†’ Turn 3 β†’ Turn 2 β†’ Turn 1\n- Includes: Turn 5, Turn 4, Turn 3 (newest 3 fit in budget)\n- Excludes: Turn 2, Turn 1 (oldest, dropped due to token limits)\n\nPresentation Phase (Chronological Order):\n- LLM sees: \"--- Turn 3 (Agent) ---\", \"--- Turn 4 (Model) ---\", \"--- Turn 5 (Agent) ---\"\n- Natural conversation flow maintained despite prioritizing recent context\n\nThis enables true AI-to-AI collaboration across the entire tool ecosystem with optimal\ncontext preservation and natural conversation understanding.\n\"\"\"\n\nimport logging\nimport os\nimport uuid\nfrom datetime import datetime, timezone\nfrom typing import Any, Optional\n\nfrom pydantic import BaseModel\n\nfrom utils.env import get_env\n\nlogger = logging.getLogger(__name__)\n\n# Configuration constants\n# Get max conversation turns from environment, default to 20 turns (10 exchanges)\ntry:\n max_turns_raw = (get_env(\"MAX_CONVERSATION_TURNS\", \"50\") or \"50\").strip()\n MAX_CONVERSATION_TURNS = int(max_turns_raw)\n if MAX_CONVERSATION_TURNS <= 0:\n logger.warning(f\"Invalid MAX_CONVERSATION_TURNS value ({MAX_CONVERSATION_TURNS}), using default of 50 turns\")\n MAX_CONVERSATION_TURNS = 50\nexcept ValueError:\n logger.warning(\n f\"Invalid MAX_CONVERSATION_TURNS value ('{get_env('MAX_CONVERSATION_TURNS')}'), using default of 50 turns\"\n )\n MAX_CONVERSATION_TURNS = 50\n\n# Get conversation timeout from environment (in hours), default to 3 hours\ntry:\n timeout_raw = (get_env(\"CONVERSATION_TIMEOUT_HOURS\", \"3\") or \"3\").strip()\n CONVERSATION_TIMEOUT_HOURS = int(timeout_raw)\n if CONVERSATION_TIMEOUT_HOURS <= 0:\n logger.warning(\n f\"Invalid CONVERSATION_TIMEOUT_HOURS value ({CONVERSATION_TIMEOUT_HOURS}), using default of 3 hours\"\n )\n CONVERSATION_TIMEOUT_HOURS = 3\nexcept ValueError:\n logger.warning(\n f\"Invalid CONVERSATION_TIMEOUT_HOURS value ('{get_env('CONVERSATION_TIMEOUT_HOURS')}'), using default of 3 hours\"\n )\n CONVERSATION_TIMEOUT_HOURS = 3\n\nCONVERSATION_TIMEOUT_SECONDS = CONVERSATION_TIMEOUT_HOURS * 3600\n\n\nclass ConversationTurn(BaseModel):\n \"\"\"\n Single turn in a conversation\n\n Represents one exchange in the AI-to-AI conversation, tracking both\n the content and metadata needed for cross-tool continuation.\n\n Attributes:\n role: \"user\" (Agent request) or \"assistant\" (model response)\n content: The actual message content/response\n timestamp: ISO timestamp when this turn was created\n files: List of file paths referenced in this specific turn\n images: List of image paths referenced in this specific turn\n tool_name: Which tool generated this turn (for cross-tool tracking)\n model_provider: Provider used (e.g., \"google\", \"openai\")\n model_name: Specific model used (e.g., \"gemini-2.5-flash\", \"o3-mini\")\n model_metadata: Additional model-specific metadata (e.g., thinking mode, token usage)\n \"\"\"\n\n role: str # \"user\" or \"assistant\"\n content: str\n timestamp: str\n files: Optional[list[str]] = None # Files referenced in this turn\n images: Optional[list[str]] = None # Images referenced in this turn\n tool_name: Optional[str] = None # Tool used for this turn\n model_provider: Optional[str] = None # Model provider (google, openai, etc)\n model_name: Optional[str] = None # Specific model used\n model_metadata: Optional[dict[str, Any]] = None # Additional model info\n\n\nclass ThreadContext(BaseModel):\n \"\"\"\n Complete conversation context for a thread\n\n Contains all information needed to reconstruct a conversation state\n across different tools and request cycles. This is the core data\n structure that enables cross-tool continuation.\n\n Attributes:\n thread_id: UUID identifying this conversation thread\n parent_thread_id: UUID of parent thread (for conversation chains)\n created_at: ISO timestamp when thread was created\n last_updated_at: ISO timestamp of last modification\n tool_name: Name of the tool that initiated this thread\n turns: List of all conversation turns in chronological order\n initial_context: Original request data that started the conversation\n \"\"\"\n\n thread_id: str\n parent_thread_id: Optional[str] = None # Parent thread for conversation chains\n created_at: str\n last_updated_at: str\n tool_name: str # Tool that created this thread (preserved for attribution)\n turns: list[ConversationTurn]\n initial_context: dict[str, Any] # Original request parameters\n\n\ndef get_storage():\n \"\"\"\n Get in-memory storage backend for conversation persistence.\n\n Returns:\n InMemoryStorage: Thread-safe in-memory storage backend\n \"\"\"\n from .storage_backend import get_storage_backend\n\n return get_storage_backend()\n\n\ndef create_thread(tool_name: str, initial_request: dict[str, Any], parent_thread_id: Optional[str] = None) -> str:\n \"\"\"\n Create new conversation thread and return thread ID\n\n Initializes a new conversation thread for AI-to-AI discussions.\n This is called when a tool wants to enable follow-up conversations\n or when Claude explicitly starts a multi-turn interaction.\n\n Args:\n tool_name: Name of the tool creating this thread (e.g., \"analyze\", \"chat\")\n initial_request: Original request parameters (will be filtered for serialization)\n parent_thread_id: Optional parent thread ID for conversation chains\n\n Returns:\n str: UUID thread identifier that can be used for continuation\n\n Note:\n - Thread expires after the configured timeout (default: 3 hours)\n - Non-serializable parameters are filtered out automatically\n - Thread can be continued by any tool using the returned UUID\n - Parent thread creates a chain for conversation history traversal\n \"\"\"\n thread_id = str(uuid.uuid4())\n now = datetime.now(timezone.utc).isoformat()\n\n # Filter out non-serializable parameters to avoid JSON encoding issues\n filtered_context = {\n k: v\n for k, v in initial_request.items()\n if k not in [\"temperature\", \"thinking_mode\", \"model\", \"continuation_id\"]\n }\n\n context = ThreadContext(\n thread_id=thread_id,\n parent_thread_id=parent_thread_id, # Link to parent for conversation chains\n created_at=now,\n last_updated_at=now,\n tool_name=tool_name, # Track which tool initiated this conversation\n turns=[], # Empty initially, turns added via add_turn()\n initial_context=filtered_context,\n )\n\n # Store in memory with configurable TTL to prevent indefinite accumulation\n storage = get_storage()\n key = f\"thread:{thread_id}\"\n storage.setex(key, CONVERSATION_TIMEOUT_SECONDS, context.model_dump_json())\n\n logger.debug(f\"[THREAD] Created new thread {thread_id} with parent {parent_thread_id}\")\n\n return thread_id\n\n\ndef get_thread(thread_id: str) -> Optional[ThreadContext]:\n \"\"\"\n Retrieve thread context from in-memory storage\n\n Fetches complete conversation context for cross-tool continuation.\n This is the core function that enables tools to access conversation\n history from previous interactions.\n\n Args:\n thread_id: UUID of the conversation thread\n\n Returns:\n ThreadContext: Complete conversation context if found\n None: If thread doesn't exist, expired, or invalid UUID\n\n Security:\n - Validates UUID format to prevent injection attacks\n - Handles storage connection failures gracefully\n - No error information leakage on failure\n \"\"\"\n if not thread_id or not _is_valid_uuid(thread_id):\n return None\n\n try:\n storage = get_storage()\n key = f\"thread:{thread_id}\"\n data = storage.get(key)\n\n if data:\n return ThreadContext.model_validate_json(data)\n return None\n except Exception:\n # Silently handle errors to avoid exposing storage details\n return None\n\n\ndef add_turn(\n thread_id: str,\n role: str,\n content: str,\n files: Optional[list[str]] = None,\n images: Optional[list[str]] = None,\n tool_name: Optional[str] = None,\n model_provider: Optional[str] = None,\n model_name: Optional[str] = None,\n model_metadata: Optional[dict[str, Any]] = None,\n) -> bool:\n \"\"\"\n Add turn to existing thread with atomic file ordering.\n\n Appends a new conversation turn to an existing thread. This is the core\n function for building conversation history and enabling cross-tool\n continuation. Each turn preserves the tool and model that generated it.\n\n Args:\n thread_id: UUID of the conversation thread\n role: \"user\" (Agent request) or \"assistant\" (model response)\n content: The actual message/response content\n files: Optional list of files referenced in this turn\n images: Optional list of images referenced in this turn\n tool_name: Name of the tool adding this turn (for attribution)\n model_provider: Provider used (e.g., \"google\", \"openai\")\n model_name: Specific model used (e.g., \"gemini-2.5-flash\", \"o3-mini\")\n model_metadata: Additional model info (e.g., thinking mode, token usage)\n\n Returns:\n bool: True if turn was successfully added, False otherwise\n\n Failure cases:\n - Thread doesn't exist or expired\n - Maximum turn limit reached\n - Storage connection failure\n\n Note:\n - Refreshes thread TTL to configured timeout on successful update\n - Turn limits prevent runaway conversations\n - File references are preserved for cross-tool access with atomic ordering\n - Image references are preserved for cross-tool visual context\n - Model information enables cross-provider conversations\n \"\"\"\n logger.debug(f\"[FLOW] Adding {role} turn to {thread_id} ({tool_name})\")\n\n context = get_thread(thread_id)\n if not context:\n logger.debug(f\"[FLOW] Thread {thread_id} not found for turn addition\")\n return False\n\n # Check turn limit to prevent runaway conversations\n if len(context.turns) >= MAX_CONVERSATION_TURNS:\n logger.debug(f\"[FLOW] Thread {thread_id} at max turns ({MAX_CONVERSATION_TURNS})\")\n return False\n\n # Create new turn with complete metadata\n turn = ConversationTurn(\n role=role,\n content=content,\n timestamp=datetime.now(timezone.utc).isoformat(),\n files=files, # Preserved for cross-tool file context\n images=images, # Preserved for cross-tool visual context\n tool_name=tool_name, # Track which tool generated this turn\n model_provider=model_provider, # Track model provider\n model_name=model_name, # Track specific model\n model_metadata=model_metadata, # Additional model info\n )\n\n context.turns.append(turn)\n context.last_updated_at = datetime.now(timezone.utc).isoformat()\n\n # Save back to storage and refresh TTL\n try:\n storage = get_storage()\n key = f\"thread:{thread_id}\"\n storage.setex(key, CONVERSATION_TIMEOUT_SECONDS, context.model_dump_json()) # Refresh TTL to configured timeout\n return True\n except Exception as e:\n logger.debug(f\"[FLOW] Failed to save turn to storage: {type(e).__name__}\")\n return False\n\n\ndef get_thread_chain(thread_id: str, max_depth: int = 20) -> list[ThreadContext]:\n \"\"\"\n Traverse the parent chain to get all threads in conversation sequence.\n\n Retrieves the complete conversation chain by following parent_thread_id\n links. Returns threads in chronological order (oldest first).\n\n Args:\n thread_id: Starting thread ID\n max_depth: Maximum chain depth to prevent infinite loops\n\n Returns:\n list[ThreadContext]: All threads in chain, oldest first\n \"\"\"\n chain = []\n current_id = thread_id\n seen_ids = set()\n\n # Build chain from current to oldest\n while current_id and len(chain) < max_depth:\n # Prevent circular references\n if current_id in seen_ids:\n logger.warning(f\"[THREAD] Circular reference detected in thread chain at {current_id}\")\n break\n\n seen_ids.add(current_id)\n\n context = get_thread(current_id)\n if not context:\n logger.debug(f\"[THREAD] Thread {current_id} not found in chain traversal\")\n break\n\n chain.append(context)\n current_id = context.parent_thread_id\n\n # Reverse to get chronological order (oldest first)\n chain.reverse()\n\n logger.debug(f\"[THREAD] Retrieved chain of {len(chain)} threads for {thread_id}\")\n return chain\n\n\ndef get_conversation_file_list(context: ThreadContext) -> list[str]:\n \"\"\"\n Extract all unique files from conversation turns with newest-first prioritization.\n\n This function implements the core file prioritization logic used throughout the\n conversation memory system. It walks backwards through conversation turns\n (from newest to oldest) and collects unique file references, ensuring that\n when the same file appears in multiple turns, the reference from the NEWEST\n turn takes precedence.\n\n PRIORITIZATION ALGORITHM:\n 1. Iterate through turns in REVERSE order (index len-1 down to 0)\n 2. For each turn, process files in the order they appear in turn.files\n 3. Add file to result list only if not already seen (newest reference wins)\n 4. Skip duplicate files that were already added from newer turns\n\n This ensures that:\n - Files from newer conversation turns appear first in the result\n - When the same file is referenced multiple times, only the newest reference is kept\n - The order reflects the most recent conversation context\n\n Example:\n Turn 1: files = [\"main.py\", \"utils.py\"]\n Turn 2: files = [\"test.py\"]\n Turn 3: files = [\"main.py\", \"config.py\"] # main.py appears again\n\n Result: [\"main.py\", \"config.py\", \"test.py\", \"utils.py\"]\n (main.py from Turn 3 takes precedence over Turn 1)\n\n Args:\n context: ThreadContext containing all conversation turns to process\n\n Returns:\n list[str]: Unique file paths ordered by newest reference first.\n Empty list if no turns exist or no files are referenced.\n\n Performance:\n - Time Complexity: O(n*m) where n=turns, m=avg files per turn\n - Space Complexity: O(f) where f=total unique files\n - Uses set for O(1) duplicate detection\n \"\"\"\n if not context.turns:\n logger.debug(\"[FILES] No turns found, returning empty file list\")\n return []\n\n # Collect files by walking backwards (newest to oldest turns)\n seen_files = set()\n file_list = []\n\n logger.debug(f\"[FILES] Collecting files from {len(context.turns)} turns (newest first)\")\n\n # Process turns in reverse order (newest first) - this is the CORE of newest-first prioritization\n # By iterating from len-1 down to 0, we encounter newer turns before older turns\n # When we find a duplicate file, we skip it because the newer version is already in our list\n for i in range(len(context.turns) - 1, -1, -1): # REVERSE: newest turn first\n turn = context.turns[i]\n if turn.files:\n logger.debug(f\"[FILES] Turn {i + 1} has {len(turn.files)} files: {turn.files}\")\n for file_path in turn.files:\n if file_path not in seen_files:\n # First time seeing this file - add it (this is the NEWEST reference)\n seen_files.add(file_path)\n file_list.append(file_path)\n logger.debug(f\"[FILES] Added new file: {file_path} (from turn {i + 1})\")\n else:\n # File already seen from a NEWER turn - skip this older reference\n logger.debug(f\"[FILES] Skipping duplicate file: {file_path} (newer version already included)\")\n\n logger.debug(f\"[FILES] Final file list ({len(file_list)}): {file_list}\")\n return file_list\n\n\ndef get_conversation_image_list(context: ThreadContext) -> list[str]:\n \"\"\"\n Extract all unique images from conversation turns with newest-first prioritization.\n\n This function implements the identical prioritization logic as get_conversation_file_list()\n to ensure consistency in how images are handled across conversation turns. It walks\n backwards through conversation turns (from newest to oldest) and collects unique image\n references, ensuring that when the same image appears in multiple turns, the reference\n from the NEWEST turn takes precedence.\n\n PRIORITIZATION ALGORITHM:\n 1. Iterate through turns in REVERSE order (index len-1 down to 0)\n 2. For each turn, process images in the order they appear in turn.images\n 3. Add image to result list only if not already seen (newest reference wins)\n 4. Skip duplicate images that were already added from newer turns\n\n This ensures that:\n - Images from newer conversation turns appear first in the result\n - When the same image is referenced multiple times, only the newest reference is kept\n - The order reflects the most recent conversation context\n\n Example:\n Turn 1: images = [\"diagram.png\", \"flow.jpg\"]\n Turn 2: images = [\"error.png\"]\n Turn 3: images = [\"diagram.png\", \"updated.png\"] # diagram.png appears again\n\n Result: [\"diagram.png\", \"updated.png\", \"error.png\", \"flow.jpg\"]\n (diagram.png from Turn 3 takes precedence over Turn 1)\n\n Args:\n context: ThreadContext containing all conversation turns to process\n\n Returns:\n list[str]: Unique image paths ordered by newest reference first.\n Empty list if no turns exist or no images are referenced.\n\n Performance:\n - Time Complexity: O(n*m) where n=turns, m=avg images per turn\n - Space Complexity: O(i) where i=total unique images\n - Uses set for O(1) duplicate detection\n \"\"\"\n if not context.turns:\n logger.debug(\"[IMAGES] No turns found, returning empty image list\")\n return []\n\n # Collect images by walking backwards (newest to oldest turns)\n seen_images = set()\n image_list = []\n\n logger.debug(f\"[IMAGES] Collecting images from {len(context.turns)} turns (newest first)\")\n\n # Process turns in reverse order (newest first) - this is the CORE of newest-first prioritization\n # By iterating from len-1 down to 0, we encounter newer turns before older turns\n # When we find a duplicate image, we skip it because the newer version is already in our list\n for i in range(len(context.turns) - 1, -1, -1): # REVERSE: newest turn first\n turn = context.turns[i]\n if turn.images:\n logger.debug(f\"[IMAGES] Turn {i + 1} has {len(turn.images)} images: {turn.images}\")\n for image_path in turn.images:\n if image_path not in seen_images:\n # First time seeing this image - add it (this is the NEWEST reference)\n seen_images.add(image_path)\n image_list.append(image_path)\n logger.debug(f\"[IMAGES] Added new image: {image_path} (from turn {i + 1})\")\n else:\n # Image already seen from a NEWER turn - skip this older reference\n logger.debug(f\"[IMAGES] Skipping duplicate image: {image_path} (newer version already included)\")\n\n logger.debug(f\"[IMAGES] Final image list ({len(image_list)}): {image_list}\")\n return image_list\n\n\ndef _plan_file_inclusion_by_size(all_files: list[str], max_file_tokens: int) -> tuple[list[str], list[str], int]:\n \"\"\"\n Plan which files to include based on size constraints.\n\n This is ONLY used for conversation history building, not MCP boundary checks.\n\n Args:\n all_files: List of files to consider for inclusion\n max_file_tokens: Maximum tokens available for file content\n\n Returns:\n Tuple of (files_to_include, files_to_skip, estimated_total_tokens)\n \"\"\"\n if not all_files:\n return [], [], 0\n\n files_to_include = []\n files_to_skip = []\n total_tokens = 0\n\n logger.debug(f\"[FILES] Planning inclusion for {len(all_files)} files with budget {max_file_tokens:,} tokens\")\n\n for file_path in all_files:\n try:\n from utils.file_utils import estimate_file_tokens\n\n if os.path.exists(file_path) and os.path.isfile(file_path):\n # Use centralized token estimation for consistency\n estimated_tokens = estimate_file_tokens(file_path)\n\n if total_tokens + estimated_tokens <= max_file_tokens:\n files_to_include.append(file_path)\n total_tokens += estimated_tokens\n logger.debug(\n f\"[FILES] Including {file_path} - {estimated_tokens:,} tokens (total: {total_tokens:,})\"\n )\n else:\n files_to_skip.append(file_path)\n logger.debug(\n f\"[FILES] Skipping {file_path} - would exceed budget (needs {estimated_tokens:,} tokens)\"\n )\n else:\n files_to_skip.append(file_path)\n # More descriptive message for missing files\n if not os.path.exists(file_path):\n logger.debug(\n f\"[FILES] Skipping {file_path} - file no longer exists (may have been moved/deleted since conversation)\"\n )\n else:\n logger.debug(f\"[FILES] Skipping {file_path} - file not accessible (not a regular file)\")\n\n except Exception as e:\n files_to_skip.append(file_path)\n logger.debug(f\"[FILES] Skipping {file_path} - error during processing: {type(e).__name__}: {e}\")\n\n logger.debug(\n f\"[FILES] Inclusion plan: {len(files_to_include)} include, {len(files_to_skip)} skip, {total_tokens:,} tokens\"\n )\n return files_to_include, files_to_skip, total_tokens\n\n\ndef build_conversation_history(context: ThreadContext, model_context=None, read_files_func=None) -> tuple[str, int]:\n \"\"\"\n Build formatted conversation history for tool prompts with embedded file contents.\n\n Creates a comprehensive conversation history that includes both conversation turns and\n file contents, with intelligent prioritization to maximize relevant context within\n token limits. This function enables stateless tools to access complete conversation\n context from previous interactions, including cross-tool continuations.\n\n FILE PRIORITIZATION BEHAVIOR:\n Files from newer conversation turns are prioritized over files from older turns.\n When the same file appears in multiple turns, the reference from the NEWEST turn\n takes precedence. This ensures the most recent file context is preserved when\n token limits require file exclusions.\n\n CONVERSATION CHAIN HANDLING:\n If the thread has a parent_thread_id, this function traverses the entire chain\n to include complete conversation history across multiple linked threads. File\n prioritization works across the entire chain, not just the current thread.\n\n CONVERSATION TURN ORDERING STRATEGY:\n The function employs a sophisticated two-phase approach for optimal token utilization:\n\n PHASE 1 - COLLECTION (Newest-First for Token Budget):\n - Processes conversation turns in REVERSE chronological order (newest to oldest)\n - Prioritizes recent turns within token constraints\n - If token budget is exceeded, OLDER turns are excluded first\n - Ensures the most contextually relevant recent exchanges are preserved\n\n PHASE 2 - PRESENTATION (Chronological for LLM Understanding):\n - Reverses the collected turns back to chronological order (oldest to newest)\n - Presents conversation flow naturally for LLM comprehension\n - Maintains \"--- Turn 1, Turn 2, Turn 3...\" sequential numbering\n - Enables LLM to follow conversation progression logically\n\n This approach balances recency prioritization with natural conversation flow.\n\n TOKEN MANAGEMENT:\n - Uses model-specific token allocation (file_tokens + history_tokens)\n - Files are embedded ONCE at the start to prevent duplication\n - Turn collection prioritizes newest-first, presentation shows chronologically\n - Stops adding turns when token budget would be exceeded\n - Gracefully handles token limits with informative notes\n\n Args:\n context: ThreadContext containing the conversation to format\n model_context: ModelContext for token allocation (optional, uses DEFAULT_MODEL fallback)\n read_files_func: Optional function to read files (primarily for testing)\n\n Returns:\n tuple[str, int]: (formatted_conversation_history, total_tokens_used)\n Returns (\"\", 0) if no conversation turns exist in the context\n\n Output Format:\n === CONVERSATION HISTORY (CONTINUATION) ===\n Thread: \n Tool: \n Turn /\n You are continuing this conversation thread from where it left off.\n\n === FILES REFERENCED IN THIS CONVERSATION ===\n The following files have been shared and analyzed during our conversation.\n [NOTE: X files omitted due to size constraints]\n Refer to these when analyzing the context and requests below:\n\n \n\n === END REFERENCED FILES ===\n\n Previous conversation turns:\n\n --- Turn 1 (Claude) ---\n Files used in this turn: file1.py, file2.py\n\n \n\n --- Turn 2 (gemini-2.5-flash using analyze via google) ---\n Files used in this turn: file3.py\n\n \n\n === END CONVERSATION HISTORY ===\n\n IMPORTANT: You are continuing an existing conversation thread...\n This is turn X of the conversation - use the conversation history above...\n\n Cross-Tool Collaboration:\n This formatted history allows any tool to \"see\" both conversation context AND\n file contents from previous tools, enabling seamless handoffs between analyze,\n codereview, debug, chat, and other tools while maintaining complete context.\n\n Performance Characteristics:\n - O(n) file collection with newest-first prioritization\n - Intelligent token budgeting prevents context window overflow\n - In-memory persistence with automatic TTL management\n - Graceful degradation when files are inaccessible or too large\n \"\"\"\n # Get the complete thread chain\n if context.parent_thread_id:\n # This thread has a parent, get the full chain\n chain = get_thread_chain(context.thread_id)\n\n # Collect all turns from all threads in chain\n all_turns = []\n total_turns = 0\n\n for thread in chain:\n all_turns.extend(thread.turns)\n total_turns += len(thread.turns)\n\n # Use centralized file collection logic for consistency across the entire chain\n # This ensures files from newer turns across ALL threads take precedence\n # over files from older turns, maintaining the newest-first prioritization\n # even when threads are chained together\n temp_context = ThreadContext(\n thread_id=\"merged_chain\",\n created_at=context.created_at,\n last_updated_at=context.last_updated_at,\n tool_name=context.tool_name,\n turns=all_turns, # All turns from entire chain in chronological order\n initial_context=context.initial_context,\n )\n all_files = get_conversation_file_list(temp_context) # Applies newest-first logic to entire chain\n logger.debug(f\"[THREAD] Built history from {len(chain)} threads with {total_turns} total turns\")\n else:\n # Single thread, no parent chain\n all_turns = context.turns\n total_turns = len(context.turns)\n all_files = get_conversation_file_list(context)\n\n if not all_turns:\n return \"\", 0\n\n logger.debug(f\"[FILES] Found {len(all_files)} unique files in conversation history\")\n\n # Get model-specific token allocation early (needed for both files and turns)\n if model_context is None:\n from config import DEFAULT_MODEL, IS_AUTO_MODE\n from utils.model_context import ModelContext\n\n # In auto mode, use an intelligent fallback model for token calculations\n # since \"auto\" is not a real model with a provider\n model_name = DEFAULT_MODEL\n if IS_AUTO_MODE and model_name.lower() == \"auto\":\n # Use intelligent fallback based on available API keys\n from providers.registry import ModelProviderRegistry\n\n model_name = ModelProviderRegistry.get_preferred_fallback_model()\n\n model_context = ModelContext(model_name)\n\n token_allocation = model_context.calculate_token_allocation()\n max_file_tokens = token_allocation.file_tokens\n max_history_tokens = token_allocation.history_tokens\n\n logger.debug(f\"[HISTORY] Using model-specific limits for {model_context.model_name}:\")\n logger.debug(f\"[HISTORY] Max file tokens: {max_file_tokens:,}\")\n logger.debug(f\"[HISTORY] Max history tokens: {max_history_tokens:,}\")\n\n history_parts = [\n \"=== CONVERSATION HISTORY (CONTINUATION) ===\",\n f\"Thread: {context.thread_id}\",\n f\"Tool: {context.tool_name}\", # Original tool that started the conversation\n f\"Turn {total_turns}/{MAX_CONVERSATION_TURNS}\",\n \"You are continuing this conversation thread from where it left off.\",\n \"\",\n ]\n\n # Embed files referenced in this conversation with size-aware selection\n if all_files:\n logger.debug(f\"[FILES] Starting embedding for {len(all_files)} files\")\n\n # Plan file inclusion based on size constraints\n # CRITICAL: all_files is already ordered by newest-first prioritization from get_conversation_file_list()\n # So when _plan_file_inclusion_by_size() hits token limits, it naturally excludes OLDER files first\n # while preserving the most recent file references - exactly what we want!\n files_to_include, files_to_skip, estimated_tokens = _plan_file_inclusion_by_size(all_files, max_file_tokens)\n\n if files_to_skip:\n logger.info(f\"[FILES] Excluding {len(files_to_skip)} files from conversation history: {files_to_skip}\")\n logger.debug(\"[FILES] Files excluded for various reasons (size constraints, missing files, access issues)\")\n\n if files_to_include:\n history_parts.extend(\n [\n \"=== FILES REFERENCED IN THIS CONVERSATION ===\",\n \"The following files have been shared and analyzed during our conversation.\",\n (\n \"\"\n if not files_to_skip\n else f\"[NOTE: {len(files_to_skip)} files omitted (size constraints, missing files, or access issues)]\"\n ),\n \"Refer to these when analyzing the context and requests below:\",\n \"\",\n ]\n )\n\n if read_files_func is None:\n from utils.file_utils import read_file_content\n\n # Process files for embedding\n file_contents = []\n total_tokens = 0\n files_included = 0\n\n for file_path in files_to_include:\n try:\n logger.debug(f\"[FILES] Processing file {file_path}\")\n formatted_content, content_tokens = read_file_content(file_path)\n if formatted_content:\n file_contents.append(formatted_content)\n total_tokens += content_tokens\n files_included += 1\n logger.debug(\n f\"File embedded in conversation history: {file_path} ({content_tokens:,} tokens)\"\n )\n else:\n logger.debug(f\"File skipped (empty content): {file_path}\")\n except Exception as e:\n # More descriptive error handling for missing files\n try:\n if not os.path.exists(file_path):\n logger.info(\n f\"File no longer accessible for conversation history: {file_path} - file was moved/deleted since conversation (marking as excluded)\"\n )\n else:\n logger.warning(\n f\"Failed to embed file in conversation history: {file_path} - {type(e).__name__}: {e}\"\n )\n except Exception:\n # Fallback if path translation also fails\n logger.warning(\n f\"Failed to embed file in conversation history: {file_path} - {type(e).__name__}: {e}\"\n )\n continue\n\n if file_contents:\n files_content = \"\".join(file_contents)\n if files_to_skip:\n files_content += (\n f\"\\n[NOTE: {len(files_to_skip)} additional file(s) were omitted due to size constraints, missing files, or access issues. \"\n f\"These were older files from earlier conversation turns.]\\n\"\n )\n history_parts.append(files_content)\n logger.debug(\n f\"Conversation history file embedding complete: {files_included} files embedded, {len(files_to_skip)} omitted, {total_tokens:,} total tokens\"\n )\n else:\n history_parts.append(\"(No accessible files found)\")\n logger.debug(f\"[FILES] No accessible files found from {len(files_to_include)} planned files\")\n else:\n # Fallback to original read_files function\n files_content = read_files_func(all_files)\n if files_content:\n # Add token validation for the combined file content\n from utils.token_utils import check_token_limit\n\n within_limit, estimated_tokens = check_token_limit(files_content)\n if within_limit:\n history_parts.append(files_content)\n else:\n # Handle token limit exceeded for conversation files\n error_message = f\"ERROR: The total size of files referenced in this conversation has exceeded the context limit and cannot be displayed.\\nEstimated tokens: {estimated_tokens}, but limit is {max_file_tokens}.\"\n history_parts.append(error_message)\n else:\n history_parts.append(\"(No accessible files found)\")\n\n history_parts.extend(\n [\n \"\",\n \"=== END REFERENCED FILES ===\",\n \"\",\n ]\n )\n\n history_parts.append(\"Previous conversation turns:\")\n\n # === PHASE 1: COLLECTION (Newest-First for Token Budget) ===\n # Build conversation turns bottom-up (most recent first) to prioritize recent context within token limits\n # This ensures we include as many recent turns as possible within the token budget by excluding\n # OLDER turns first when space runs out, preserving the most contextually relevant exchanges\n turn_entries = [] # Will store (index, formatted_turn_content) for chronological ordering later\n total_turn_tokens = 0\n file_embedding_tokens = sum(model_context.estimate_tokens(part) for part in history_parts)\n\n # CRITICAL: Process turns in REVERSE chronological order (newest to oldest)\n # This prioritization strategy ensures recent context is preserved when token budget is tight\n for idx in range(len(all_turns) - 1, -1, -1):\n turn = all_turns[idx]\n turn_num = idx + 1\n\n if turn.role == \"user\":\n role_label = \"Agent\"\n else:\n role_label = turn.model_name or \"Assistant\"\n\n # Build the complete turn content\n turn_parts = []\n\n # Add turn header with tool attribution for cross-tool tracking\n turn_header = f\"\\n--- Turn {turn_num} ({role_label}\"\n if turn.tool_name:\n turn_header += f\" using {turn.tool_name}\"\n\n # Add model info if available\n if turn.model_provider:\n provider_descriptor = turn.model_provider\n if turn.model_name and turn.model_name != role_label:\n provider_descriptor += f\"/{turn.model_name}\"\n turn_header += f\" via {provider_descriptor}\"\n elif turn.model_name and turn.model_name != role_label:\n turn_header += f\" via {turn.model_name}\"\n\n turn_header += \") ---\"\n turn_parts.append(turn_header)\n\n # Get tool-specific formatting if available\n # This includes file references and the actual content\n tool_formatted_content = _get_tool_formatted_content(turn)\n turn_parts.extend(tool_formatted_content)\n\n # Calculate tokens for this turn\n turn_content = \"\\n\".join(turn_parts)\n turn_tokens = model_context.estimate_tokens(turn_content)\n\n # Check if adding this turn would exceed history budget\n if file_embedding_tokens + total_turn_tokens + turn_tokens > max_history_tokens:\n # Stop adding turns - we've reached the limit\n logger.debug(f\"[HISTORY] Stopping at turn {turn_num} - would exceed history budget\")\n logger.debug(f\"[HISTORY] File tokens: {file_embedding_tokens:,}\")\n logger.debug(f\"[HISTORY] Turn tokens so far: {total_turn_tokens:,}\")\n logger.debug(f\"[HISTORY] This turn: {turn_tokens:,}\")\n logger.debug(f\"[HISTORY] Would total: {file_embedding_tokens + total_turn_tokens + turn_tokens:,}\")\n logger.debug(f\"[HISTORY] Budget: {max_history_tokens:,}\")\n break\n\n # Add this turn to our collection (we'll reverse it later for chronological presentation)\n # Store the original index to maintain proper turn numbering in final output\n turn_entries.append((idx, turn_content))\n total_turn_tokens += turn_tokens\n\n # === PHASE 2: PRESENTATION (Chronological for LLM Understanding) ===\n # Reverse the collected turns to restore chronological order (oldest first)\n # This gives the LLM a natural conversation flow: Turn 1 β†’ Turn 2 β†’ Turn 3...\n # while still having prioritized recent turns during the token-constrained collection phase\n turn_entries.reverse()\n\n # Add the turns in chronological order for natural LLM comprehension\n # The LLM will see: \"--- Turn 1 (Agent) ---\" followed by \"--- Turn 2 (Model) ---\" etc.\n for _, turn_content in turn_entries:\n history_parts.append(turn_content)\n\n # Log what we included\n included_turns = len(turn_entries)\n total_turns = len(all_turns)\n if included_turns < total_turns:\n logger.info(f\"[HISTORY] Included {included_turns}/{total_turns} turns due to token limit\")\n history_parts.append(f\"\\n[Note: Showing {included_turns} most recent turns out of {total_turns} total]\")\n\n history_parts.extend(\n [\n \"\",\n \"=== END CONVERSATION HISTORY ===\",\n \"\",\n \"IMPORTANT: You are continuing an existing conversation thread. Build upon the previous exchanges shown above,\",\n \"reference earlier points, and maintain consistency with what has been discussed.\",\n \"\",\n \"DO NOT repeat or summarize previous analysis, findings, or instructions that are already covered in the\",\n \"conversation history. Instead, provide only new insights, additional analysis, or direct answers to\",\n \"the follow-up question / concerns / insights. Assume the user has read the prior conversation.\",\n \"\",\n f\"This is turn {len(all_turns) + 1} of the conversation - use the conversation history above to provide a coherent continuation.\",\n ]\n )\n\n # Calculate total tokens for the complete conversation history\n complete_history = \"\\n\".join(history_parts)\n from utils.token_utils import estimate_tokens\n\n total_conversation_tokens = estimate_tokens(complete_history)\n\n # Summary log of what was built\n user_turns = len([t for t in all_turns if t.role == \"user\"])\n assistant_turns = len([t for t in all_turns if t.role == \"assistant\"])\n logger.debug(\n f\"[FLOW] Built conversation history: {user_turns} user + {assistant_turns} assistant turns, {len(all_files)} files, {total_conversation_tokens:,} tokens\"\n )\n\n return complete_history, total_conversation_tokens\n\n\ndef _get_tool_formatted_content(turn: ConversationTurn) -> list[str]:\n \"\"\"\n Get tool-specific formatting for a conversation turn.\n\n This function attempts to use the tool's custom formatting method if available,\n falling back to default formatting if the tool cannot be found or doesn't\n provide custom formatting.\n\n Args:\n turn: The conversation turn to format\n\n Returns:\n list[str]: Formatted content lines for this turn\n \"\"\"\n if turn.tool_name:\n try:\n # Dynamically import to avoid circular dependencies\n from server import TOOLS\n\n tool = TOOLS.get(turn.tool_name)\n if tool:\n # Use inheritance pattern - try to call the method directly\n # If it doesn't exist or raises AttributeError, fall back to default\n try:\n return tool.format_conversation_turn(turn)\n except AttributeError:\n # Tool doesn't implement format_conversation_turn - use default\n pass\n except Exception as e:\n # Log but don't fail - fall back to default formatting\n logger.debug(f\"[HISTORY] Could not get tool-specific formatting for {turn.tool_name}: {e}\")\n\n # Default formatting\n return _default_turn_formatting(turn)\n\n\ndef _default_turn_formatting(turn: ConversationTurn) -> list[str]:\n \"\"\"\n Default formatting for conversation turns.\n\n This provides the standard formatting when no tool-specific\n formatting is available.\n\n Args:\n turn: The conversation turn to format\n\n Returns:\n list[str]: Default formatted content lines\n \"\"\"\n parts = []\n\n # Add files context if present\n if turn.files:\n parts.append(f\"Files used in this turn: {', '.join(turn.files)}\")\n parts.append(\"\") # Empty line for readability\n\n # Add the actual content\n parts.append(turn.content)\n\n return parts\n\n\ndef _is_valid_uuid(val: str) -> bool:\n \"\"\"\n Validate UUID format for security\n\n Ensures thread IDs are valid UUIDs to prevent injection attacks\n and malformed requests.\n\n Args:\n val: String to validate as UUID\n\n Returns:\n bool: True if valid UUID format, False otherwise\n \"\"\"\n try:\n uuid.UUID(val)\n return True\n except ValueError:\n return False\n" }, { "path": "utils/env.py", "content": "\"\"\"Centralized environment variable access for PAL MCP Server.\"\"\"\n\nfrom __future__ import annotations\n\nimport os\nfrom collections.abc import Mapping\nfrom contextlib import contextmanager\nfrom pathlib import Path\n\ntry:\n from dotenv import dotenv_values, load_dotenv\nexcept ImportError: # pragma: no cover - optional dependency\n dotenv_values = None # type: ignore[assignment]\n load_dotenv = None # type: ignore[assignment]\n\n_PROJECT_ROOT = Path(__file__).resolve().parent.parent\n_ENV_PATH = _PROJECT_ROOT / \".env\"\n\n_DOTENV_VALUES: dict[str, str | None] = {}\n_FORCE_ENV_OVERRIDE = False\n\n\ndef _read_dotenv_values() -> dict[str, str | None]:\n if dotenv_values is not None and _ENV_PATH.exists():\n loaded = dotenv_values(_ENV_PATH)\n return dict(loaded)\n return {}\n\n\ndef _compute_force_override(values: Mapping[str, str | None]) -> bool:\n raw = (values.get(\"PAL_MCP_FORCE_ENV_OVERRIDE\") or \"false\").strip().lower()\n return raw == \"true\"\n\n\ndef reload_env(dotenv_mapping: Mapping[str, str | None] | None = None) -> None:\n \"\"\"Reload .env values and recompute override semantics.\n\n Args:\n dotenv_mapping: Optional mapping used instead of reading the .env file.\n Intended for tests; when provided, load_dotenv is not invoked.\n \"\"\"\n\n global _DOTENV_VALUES, _FORCE_ENV_OVERRIDE\n\n if dotenv_mapping is not None:\n _DOTENV_VALUES = dict(dotenv_mapping)\n _FORCE_ENV_OVERRIDE = _compute_force_override(_DOTENV_VALUES)\n return\n\n _DOTENV_VALUES = _read_dotenv_values()\n _FORCE_ENV_OVERRIDE = _compute_force_override(_DOTENV_VALUES)\n\n if load_dotenv is not None and _ENV_PATH.exists():\n load_dotenv(dotenv_path=_ENV_PATH, override=_FORCE_ENV_OVERRIDE)\n\n\nreload_env()\n\n\ndef env_override_enabled() -> bool:\n \"\"\"Return True when PAL_MCP_FORCE_ENV_OVERRIDE is enabled via the .env file.\"\"\"\n\n return _FORCE_ENV_OVERRIDE\n\n\ndef get_env(key: str, default: str | None = None) -> str | None:\n \"\"\"Retrieve environment variables respecting PAL_MCP_FORCE_ENV_OVERRIDE.\"\"\"\n\n if env_override_enabled():\n if key in _DOTENV_VALUES:\n value = _DOTENV_VALUES[key]\n return value if value is not None else default\n return default\n\n return os.getenv(key, default)\n\n\ndef get_env_bool(key: str, default: bool = False) -> bool:\n \"\"\"Boolean helper that respects override semantics.\"\"\"\n\n raw_default = \"true\" if default else \"false\"\n raw_value = get_env(key, raw_default)\n return (raw_value or raw_default).strip().lower() == \"true\"\n\n\ndef get_all_env() -> dict[str, str | None]:\n \"\"\"Expose the loaded .env mapping for diagnostics/logging.\"\"\"\n\n return dict(_DOTENV_VALUES)\n\n\n@contextmanager\ndef suppress_env_vars(*names: str):\n \"\"\"Temporarily remove environment variables during the context.\n\n Args:\n names: Environment variable names to remove. Empty or falsy names are ignored.\n \"\"\"\n\n removed: dict[str, str] = {}\n try:\n for name in names:\n if not name:\n continue\n if name in os.environ:\n removed[name] = os.environ[name]\n del os.environ[name]\n yield\n finally:\n for name, value in removed.items():\n os.environ[name] = value\n" }, { "path": "utils/file_types.py", "content": "\"\"\"\nFile type definitions and constants for file processing\n\nThis module centralizes all file type and extension definitions used\nthroughout the MCP server for consistent file handling.\n\"\"\"\n\n# Programming language file extensions - core code files\nPROGRAMMING_LANGUAGES = {\n \".py\", # Python\n \".js\", # JavaScript\n \".ts\", # TypeScript\n \".jsx\", # React JavaScript\n \".tsx\", # React TypeScript\n \".java\", # Java\n \".cpp\", # C++\n \".c\", # C\n \".h\", # C/C++ Header\n \".hpp\", # C++ Header\n \".cs\", # C#\n \".go\", # Go\n \".rs\", # Rust\n \".rb\", # Ruby\n \".php\", # PHP\n \".swift\", # Swift\n \".kt\", # Kotlin\n \".scala\", # Scala\n \".r\", # R\n \".m\", # Objective-C\n \".mm\", # Objective-C++\n}\n\n# Script and shell file extensions\nSCRIPTS = {\n \".sql\", # SQL\n \".sh\", # Shell\n \".bash\", # Bash\n \".zsh\", # Zsh\n \".fish\", # Fish shell\n \".ps1\", # PowerShell\n \".bat\", # Batch\n \".cmd\", # Command\n}\n\n# Configuration and data file extensions\nCONFIGS = {\n \".yml\", # YAML\n \".yaml\", # YAML\n \".json\", # JSON\n \".xml\", # XML\n \".toml\", # TOML\n \".ini\", # INI\n \".cfg\", # Config\n \".conf\", # Config\n \".properties\", # Properties\n \".env\", # Environment\n}\n\n# Documentation and markup file extensions\nDOCS = {\n \".txt\", # Text\n \".md\", # Markdown\n \".rst\", # reStructuredText\n \".tex\", # LaTeX\n}\n\n# Web development file extensions\nWEB = {\n \".html\", # HTML\n \".css\", # CSS\n \".scss\", # Sass\n \".sass\", # Sass\n \".less\", # Less\n}\n\n# Additional text file extensions for logs and data\nTEXT_DATA = {\n \".log\", # Log files\n \".csv\", # CSV\n \".tsv\", # TSV\n \".gitignore\", # Git ignore\n \".dockerfile\", # Dockerfile\n \".makefile\", # Make\n \".cmake\", # CMake\n \".gradle\", # Gradle\n \".sbt\", # SBT\n \".pom\", # Maven POM\n \".lock\", # Lock files\n \".changeset\", # Precommit changeset\n}\n\n# Image file extensions - limited to what AI models actually support\n# Based on OpenAI and Gemini supported formats: PNG, JPEG, GIF, WebP\nIMAGES = {\".jpg\", \".jpeg\", \".png\", \".gif\", \".webp\"}\n\n# Binary executable and library extensions\nBINARIES = {\n \".exe\", # Windows executable\n \".dll\", # Windows library\n \".so\", # Linux shared object\n \".dylib\", # macOS dynamic library\n \".bin\", # Binary\n \".class\", # Java class\n}\n\n# Archive and package file extensions\nARCHIVES = {\n \".jar\",\n \".war\",\n \".ear\", # Java archives\n \".zip\",\n \".tar\",\n \".gz\", # General archives\n \".7z\",\n \".rar\", # Compression\n \".deb\",\n \".rpm\", # Linux packages\n \".dmg\",\n \".pkg\", # macOS packages\n}\n\n# Derived sets for different use cases\nCODE_EXTENSIONS = PROGRAMMING_LANGUAGES | SCRIPTS | CONFIGS | DOCS | WEB\nPROGRAMMING_EXTENSIONS = PROGRAMMING_LANGUAGES # For line numbering\nTEXT_EXTENSIONS = CODE_EXTENSIONS | TEXT_DATA\nIMAGE_EXTENSIONS = IMAGES\nBINARY_EXTENSIONS = BINARIES | ARCHIVES\n\n# All extensions by category for easy access\nFILE_CATEGORIES = {\n \"programming\": PROGRAMMING_LANGUAGES,\n \"scripts\": SCRIPTS,\n \"configs\": CONFIGS,\n \"docs\": DOCS,\n \"web\": WEB,\n \"text_data\": TEXT_DATA,\n \"images\": IMAGES,\n \"binaries\": BINARIES,\n \"archives\": ARCHIVES,\n}\n\n\ndef get_file_category(file_path: str) -> str:\n \"\"\"\n Determine the category of a file based on its extension.\n\n Args:\n file_path: Path to the file\n\n Returns:\n Category name or \"unknown\" if not recognized\n \"\"\"\n from pathlib import Path\n\n extension = Path(file_path).suffix.lower()\n\n for category, extensions in FILE_CATEGORIES.items():\n if extension in extensions:\n return category\n\n return \"unknown\"\n\n\ndef is_code_file(file_path: str) -> bool:\n \"\"\"Check if a file is a code file (programming language).\"\"\"\n from pathlib import Path\n\n return Path(file_path).suffix.lower() in PROGRAMMING_LANGUAGES\n\n\ndef is_text_file(file_path: str) -> bool:\n \"\"\"Check if a file is a text file.\"\"\"\n from pathlib import Path\n\n return Path(file_path).suffix.lower() in TEXT_EXTENSIONS\n\n\ndef is_binary_file(file_path: str) -> bool:\n \"\"\"Check if a file is a binary file.\"\"\"\n from pathlib import Path\n\n return Path(file_path).suffix.lower() in BINARY_EXTENSIONS\n\n\n# File-type specific token-to-byte ratios for accurate token estimation\n# Based on empirical analysis of file compression characteristics and tokenization patterns\nTOKEN_ESTIMATION_RATIOS = {\n # Programming languages\n \".py\": 3.5, # Python - moderate verbosity\n \".js\": 3.2, # JavaScript - compact syntax\n \".ts\": 3.3, # TypeScript - type annotations add tokens\n \".jsx\": 3.1, # React JSX - JSX tags are tokenized efficiently\n \".tsx\": 3.0, # React TSX - combination of TypeScript + JSX\n \".java\": 3.6, # Java - verbose syntax, long identifiers\n \".cpp\": 3.7, # C++ - preprocessor directives, templates\n \".c\": 3.8, # C - function definitions, struct declarations\n \".go\": 3.9, # Go - explicit error handling, package names\n \".rs\": 3.5, # Rust - similar to Python in verbosity\n \".php\": 3.3, # PHP - mixed HTML/code, variable prefixes\n \".rb\": 3.6, # Ruby - descriptive method names\n \".swift\": 3.4, # Swift - modern syntax, type inference\n \".kt\": 3.5, # Kotlin - similar to modern languages\n \".scala\": 3.2, # Scala - functional programming, concise\n # Scripts and configuration\n \".sh\": 4.1, # Shell scripts - commands and paths\n \".bat\": 4.0, # Batch files - similar to shell\n \".ps1\": 3.8, # PowerShell - more structured than bash\n \".sql\": 3.8, # SQL - keywords and table/column names\n # Data and configuration formats\n \".json\": 2.5, # JSON - lots of punctuation and quotes\n \".yaml\": 3.0, # YAML - structured but readable\n \".yml\": 3.0, # YAML (alternative extension)\n \".xml\": 2.8, # XML - tags and attributes\n \".toml\": 3.2, # TOML - similar to config files\n # Documentation and text\n \".md\": 4.2, # Markdown - natural language with formatting\n \".txt\": 4.0, # Plain text - mostly natural language\n \".rst\": 4.1, # reStructuredText - documentation format\n # Web technologies\n \".html\": 2.9, # HTML - tags and attributes\n \".css\": 3.4, # CSS - properties and selectors\n # Logs and data\n \".log\": 4.5, # Log files - timestamps, messages, stack traces\n \".csv\": 3.1, # CSV - data with delimiters\n # Infrastructure files\n \".dockerfile\": 3.7, # Dockerfile - commands and paths\n \".tf\": 3.5, # Terraform - infrastructure as code\n}\n\n\ndef get_token_estimation_ratio(file_path: str) -> float:\n \"\"\"\n Get the token estimation ratio for a file based on its extension.\n\n Args:\n file_path: Path to the file\n\n Returns:\n Token-to-byte ratio for the file type (default: 3.5 for unknown types)\n \"\"\"\n from pathlib import Path\n\n extension = Path(file_path).suffix.lower()\n return TOKEN_ESTIMATION_RATIOS.get(extension, 3.5) # Conservative default\n\n\n# MIME type mappings for image files - limited to what AI models actually support\n# Based on OpenAI and Gemini supported formats: PNG, JPEG, GIF, WebP\nIMAGE_MIME_TYPES = {\n \".jpg\": \"image/jpeg\",\n \".jpeg\": \"image/jpeg\",\n \".png\": \"image/png\",\n \".gif\": \"image/gif\",\n \".webp\": \"image/webp\",\n}\n\n\ndef get_image_mime_type(extension: str) -> str:\n \"\"\"\n Get the MIME type for an image file extension.\n\n Args:\n extension: File extension (with or without leading dot)\n\n Returns:\n MIME type string (default: image/jpeg for unknown extensions)\n \"\"\"\n if not extension.startswith(\".\"):\n extension = \".\" + extension\n extension = extension.lower()\n return IMAGE_MIME_TYPES.get(extension, \"image/jpeg\")\n" }, { "path": "utils/file_utils.py", "content": "\"\"\"\nFile reading utilities with directory support and token management\n\nThis module provides secure file access functionality for the MCP server.\nIt implements critical security measures to prevent unauthorized file access\nand manages token limits to ensure efficient API usage.\n\nKey Features:\n- Path validation and sandboxing to prevent directory traversal attacks\n- Support for both individual files and recursive directory reading\n- Token counting and management to stay within API limits\n- Automatic file type detection and filtering\n- Comprehensive error handling with informative messages\n\nSecurity Model:\n- All file access is restricted to PROJECT_ROOT and its subdirectories\n- Absolute paths are required to prevent ambiguity\n- Symbolic links are resolved to ensure they stay within bounds\n\nCONVERSATION MEMORY INTEGRATION:\nThis module works with the conversation memory system to support efficient\nmulti-turn file handling:\n\n1. DEDUPLICATION SUPPORT:\n - File reading functions are called by conversation-aware tools\n - Supports newest-first file prioritization by providing accurate token estimation\n - Enables efficient file content caching and token budget management\n\n2. TOKEN BUDGET OPTIMIZATION:\n - Provides accurate token estimation for file content before reading\n - Supports the dual prioritization strategy by enabling precise budget calculations\n - Enables tools to make informed decisions about which files to include\n\n3. CROSS-TOOL FILE PERSISTENCE:\n - File reading results are used across different tools in conversation chains\n - Consistent file access patterns support conversation continuation scenarios\n - Error handling preserves conversation flow when files become unavailable\n\"\"\"\n\nimport json\nimport logging\nimport os\nfrom datetime import datetime, timezone\nfrom pathlib import Path\nfrom typing import Optional\n\nfrom .file_types import BINARY_EXTENSIONS, CODE_EXTENSIONS, IMAGE_EXTENSIONS, TEXT_EXTENSIONS\nfrom .security_config import EXCLUDED_DIRS, is_dangerous_path\nfrom .token_utils import DEFAULT_CONTEXT_WINDOW, estimate_tokens\n\n\ndef _is_builtin_custom_models_config(path_str: str) -> bool:\n \"\"\"\n Check if path points to the server's built-in custom_models.json config file.\n\n This only matches the server's internal config, not user-specified CUSTOM_MODELS_CONFIG_PATH.\n We identify the built-in config by checking if it resolves to the server's conf directory.\n\n Args:\n path_str: Path to check\n\n Returns:\n True if this is the server's built-in custom_models.json config file\n \"\"\"\n try:\n path = Path(path_str)\n\n # Get the server root by going up from this file: utils/file_utils.py -> server_root\n server_root = Path(__file__).parent.parent\n builtin_config = server_root / \"conf\" / \"custom_models.json\"\n\n # Check if the path resolves to the same file as our built-in config\n # This handles both relative and absolute paths to the same file\n return path.resolve() == builtin_config.resolve()\n\n except Exception:\n # If path resolution fails, it's not our built-in config\n return False\n\n\nlogger = logging.getLogger(__name__)\n\n\ndef is_mcp_directory(path: Path) -> bool:\n \"\"\"\n Check if a directory is the MCP server's own directory.\n\n This prevents the MCP from including its own code when scanning projects\n where the MCP has been cloned as a subdirectory.\n\n Args:\n path: Directory path to check\n\n Returns:\n True if this is the MCP server directory or a subdirectory\n \"\"\"\n if not path.is_dir():\n return False\n\n # Get the directory where the MCP server is running from\n # __file__ is utils/file_utils.py, so parent.parent is the MCP root\n mcp_server_dir = Path(__file__).parent.parent.resolve()\n\n # Check if the given path is the MCP server directory or a subdirectory\n try:\n path.resolve().relative_to(mcp_server_dir)\n logger.info(f\"Detected MCP server directory at {path}, will exclude from scanning\")\n return True\n except ValueError:\n # Not a subdirectory of MCP server\n return False\n\n\ndef get_user_home_directory() -> Optional[Path]:\n \"\"\"\n Get the user's home directory.\n\n Returns:\n User's home directory path\n \"\"\"\n return Path.home()\n\n\ndef is_home_directory_root(path: Path) -> bool:\n \"\"\"\n Check if the given path is the user's home directory root.\n\n This prevents scanning the entire home directory which could include\n sensitive data and non-project files.\n\n Args:\n path: Directory path to check\n\n Returns:\n True if this is the home directory root\n \"\"\"\n user_home = get_user_home_directory()\n if not user_home:\n return False\n\n try:\n resolved_path = path.resolve()\n resolved_home = user_home.resolve()\n\n # Check if this is exactly the home directory\n if resolved_path == resolved_home:\n logger.warning(\n f\"Attempted to scan user home directory root: {path}. Please specify a subdirectory instead.\"\n )\n return True\n\n # Also check common home directory patterns\n path_str = str(resolved_path).lower()\n home_patterns = [\n \"/users/\", # macOS\n \"/home/\", # Linux\n \"c:\\\\users\\\\\", # Windows\n \"c:/users/\", # Windows with forward slashes\n ]\n\n for pattern in home_patterns:\n if pattern in path_str:\n # Extract the user directory path\n # e.g., /Users/fahad or /home/username\n parts = path_str.split(pattern)\n if len(parts) > 1:\n # Get the part after the pattern\n after_pattern = parts[1]\n # Check if we're at the user's root (no subdirectories)\n if \"/\" not in after_pattern and \"\\\\\" not in after_pattern:\n logger.warning(\n f\"Attempted to scan user home directory root: {path}. \"\n f\"Please specify a subdirectory instead.\"\n )\n return True\n\n except Exception as e:\n logger.debug(f\"Error checking if path is home directory: {e}\")\n\n return False\n\n\ndef detect_file_type(file_path: str) -> str:\n \"\"\"\n Detect file type for appropriate processing strategy.\n\n This function is intended for specific file type handling (e.g., image processing,\n binary file analysis, or enhanced file filtering).\n\n Args:\n file_path: Path to the file to analyze\n\n Returns:\n str: \"text\", \"binary\", or \"image\"\n \"\"\"\n path = Path(file_path)\n\n # Check extension first (fast)\n extension = path.suffix.lower()\n if extension in TEXT_EXTENSIONS:\n return \"text\"\n elif extension in IMAGE_EXTENSIONS:\n return \"image\"\n elif extension in BINARY_EXTENSIONS:\n return \"binary\"\n\n # Fallback: check magic bytes for text vs binary\n # This is helpful for files without extensions or unknown extensions\n try:\n with open(path, \"rb\") as f:\n chunk = f.read(1024)\n # Simple heuristic: if we can decode as UTF-8, likely text\n chunk.decode(\"utf-8\")\n return \"text\"\n except UnicodeDecodeError:\n return \"binary\"\n except (FileNotFoundError, PermissionError) as e:\n logger.warning(f\"Could not access file {file_path} for type detection: {e}\")\n return \"unknown\"\n\n\ndef should_add_line_numbers(file_path: str, include_line_numbers: Optional[bool] = None) -> bool:\n \"\"\"\n Determine if line numbers should be added to a file.\n\n Args:\n file_path: Path to the file\n include_line_numbers: Explicit preference, or None for auto-detection\n\n Returns:\n bool: True if line numbers should be added\n \"\"\"\n if include_line_numbers is not None:\n return include_line_numbers\n\n # Default: DO NOT add line numbers\n # Tools that want line numbers must explicitly request them\n return False\n\n\ndef _normalize_line_endings(content: str) -> str:\n \"\"\"\n Normalize line endings for consistent line numbering.\n\n Args:\n content: File content with potentially mixed line endings\n\n Returns:\n str: Content with normalized LF line endings\n \"\"\"\n # Normalize all line endings to LF for consistent counting\n return content.replace(\"\\r\\n\", \"\\n\").replace(\"\\r\", \"\\n\")\n\n\ndef _add_line_numbers(content: str) -> str:\n \"\"\"\n Add line numbers to text content for precise referencing.\n\n Args:\n content: Text content to number\n\n Returns:\n str: Content with line numbers in format \" 45β”‚ actual code line\"\n Supports files up to 99,999 lines with dynamic width allocation\n \"\"\"\n # Normalize line endings first\n normalized_content = _normalize_line_endings(content)\n lines = normalized_content.split(\"\\n\")\n\n # Dynamic width allocation based on total line count\n # This supports files of any size by computing required width\n total_lines = len(lines)\n width = len(str(total_lines))\n width = max(width, 4) # Minimum padding for readability\n\n # Format with dynamic width and clear separator\n numbered_lines = [f\"{i + 1:{width}d}β”‚ {line}\" for i, line in enumerate(lines)]\n\n return \"\\n\".join(numbered_lines)\n\n\ndef resolve_and_validate_path(path_str: str) -> Path:\n \"\"\"\n Resolves and validates a path against security policies.\n\n This function ensures safe file access by:\n 1. Requiring absolute paths (no ambiguity)\n 2. Resolving symlinks to prevent deception\n 3. Blocking access to dangerous system directories\n\n Args:\n path_str: Path string (must be absolute)\n\n Returns:\n Resolved Path object that is safe to access\n\n Raises:\n ValueError: If path is not absolute or otherwise invalid\n PermissionError: If path is in a dangerous location\n \"\"\"\n # Step 1: Create a Path object\n user_path = Path(path_str)\n\n # Step 2: Security Policy - Require absolute paths\n # Relative paths could be interpreted differently depending on working directory\n if not user_path.is_absolute():\n raise ValueError(f\"Relative paths are not supported. Please provide an absolute path.\\nReceived: {path_str}\")\n\n # Step 3: Resolve the absolute path (follows symlinks, removes .. and .)\n # This is critical for security as it reveals the true destination of symlinks\n resolved_path = user_path.resolve()\n\n # Step 4: Check against dangerous paths\n if is_dangerous_path(resolved_path):\n logger.warning(f\"Access denied - dangerous path: {resolved_path}\")\n raise PermissionError(f\"Access to system directory denied: {path_str}\")\n\n # Step 5: Check if it's the home directory root\n if is_home_directory_root(resolved_path):\n raise PermissionError(\n f\"Cannot scan entire home directory: {path_str}\\n\" f\"Please specify a subdirectory within your home folder.\"\n )\n\n return resolved_path\n\n\ndef expand_paths(paths: list[str], extensions: Optional[set[str]] = None) -> list[str]:\n \"\"\"\n Expand paths to individual files, handling both files and directories.\n\n This function recursively walks directories to find all matching files.\n It automatically filters out hidden files and common non-code directories\n like __pycache__ to avoid including generated or system files.\n\n Args:\n paths: List of file or directory paths (must be absolute)\n extensions: Optional set of file extensions to include (defaults to CODE_EXTENSIONS)\n\n Returns:\n List of individual file paths, sorted for consistent ordering\n \"\"\"\n if extensions is None:\n extensions = CODE_EXTENSIONS\n\n expanded_files = []\n seen = set()\n\n for path in paths:\n try:\n # Validate each path for security before processing\n path_obj = resolve_and_validate_path(path)\n except (ValueError, PermissionError):\n # Skip invalid paths silently to allow partial success\n continue\n\n if not path_obj.exists():\n continue\n\n # Safety checks for directory scanning\n if path_obj.is_dir():\n # Check 1: Prevent scanning user's home directory root\n if is_home_directory_root(path_obj):\n logger.warning(f\"Skipping home directory root: {path}. Please specify a project subdirectory instead.\")\n continue\n\n # Check 2: Skip if this is the MCP's own directory\n if is_mcp_directory(path_obj):\n logger.info(\n f\"Skipping MCP server directory: {path}. The MCP server code is excluded from project scans.\"\n )\n continue\n\n if path_obj.is_file():\n # Add file directly\n if str(path_obj) not in seen:\n expanded_files.append(str(path_obj))\n seen.add(str(path_obj))\n\n elif path_obj.is_dir():\n # Walk directory recursively to find all files\n for root, dirs, files in os.walk(path_obj):\n # Filter directories in-place to skip hidden and excluded directories\n # This prevents descending into .git, .venv, __pycache__, node_modules, etc.\n original_dirs = dirs[:]\n dirs[:] = []\n for d in original_dirs:\n # Skip hidden directories\n if d.startswith(\".\"):\n continue\n # Skip excluded directories\n if d in EXCLUDED_DIRS:\n continue\n # Skip MCP directories found during traversal\n dir_path = Path(root) / d\n if is_mcp_directory(dir_path):\n logger.debug(f\"Skipping MCP directory during traversal: {dir_path}\")\n continue\n dirs.append(d)\n\n for file in files:\n # Skip hidden files (e.g., .DS_Store, .gitignore)\n if file.startswith(\".\"):\n continue\n\n file_path = Path(root) / file\n\n # Filter by extension if specified\n if not extensions or file_path.suffix.lower() in extensions:\n full_path = str(file_path)\n # Use set to prevent duplicates\n if full_path not in seen:\n expanded_files.append(full_path)\n seen.add(full_path)\n\n # Sort for consistent ordering across different runs\n # This makes output predictable and easier to debug\n expanded_files.sort()\n return expanded_files\n\n\ndef read_file_content(\n file_path: str, max_size: int = 1_000_000, *, include_line_numbers: Optional[bool] = None\n) -> tuple[str, int]:\n \"\"\"\n Read a single file and format it for inclusion in AI prompts.\n\n This function handles various error conditions gracefully and always\n returns formatted content, even for errors. This ensures the AI model\n gets context about what files were attempted but couldn't be read.\n\n Args:\n file_path: Path to file (must be absolute)\n max_size: Maximum file size to read (default 1MB to prevent memory issues)\n include_line_numbers: Whether to add line numbers. If None, auto-detects based on file type\n\n Returns:\n Tuple of (formatted_content, estimated_tokens)\n Content is wrapped with clear delimiters for AI parsing\n \"\"\"\n logger.debug(f\"[FILES] read_file_content called for: {file_path}\")\n try:\n # Validate path security before any file operations\n path = resolve_and_validate_path(file_path)\n logger.debug(f\"[FILES] Path validated and resolved: {path}\")\n except (ValueError, PermissionError) as e:\n # Return error in a format that provides context to the AI\n logger.debug(f\"[FILES] Path validation failed for {file_path}: {type(e).__name__}: {e}\")\n error_msg = str(e)\n content = f\"\\n--- ERROR ACCESSING FILE: {file_path} ---\\nError: {error_msg}\\n--- END FILE ---\\n\"\n tokens = estimate_tokens(content)\n logger.debug(f\"[FILES] Returning error content for {file_path}: {tokens} tokens\")\n return content, tokens\n\n try:\n # Validate file existence and type\n if not path.exists():\n logger.debug(f\"[FILES] File does not exist: {file_path}\")\n content = f\"\\n--- FILE NOT FOUND: {file_path} ---\\nError: File does not exist\\n--- END FILE ---\\n\"\n return content, estimate_tokens(content)\n\n if not path.is_file():\n logger.debug(f\"[FILES] Path is not a file: {file_path}\")\n content = f\"\\n--- NOT A FILE: {file_path} ---\\nError: Path is not a file\\n--- END FILE ---\\n\"\n return content, estimate_tokens(content)\n\n # Check file size to prevent memory exhaustion\n stat_result = path.stat()\n file_size = stat_result.st_size\n logger.debug(f\"[FILES] File size for {file_path}: {file_size:,} bytes\")\n if file_size > max_size:\n logger.debug(f\"[FILES] File too large: {file_path} ({file_size:,} > {max_size:,} bytes)\")\n modified_at = datetime.fromtimestamp(stat_result.st_mtime, tz=timezone.utc).strftime(\"%Y-%m-%d %H:%M:%S %Z\")\n content = (\n f\"\\n--- FILE TOO LARGE: {file_path} (Last modified: {modified_at}) ---\\n\"\n f\"File size: {file_size:,} bytes (max: {max_size:,})\\n\"\n \"--- END FILE ---\\n\"\n )\n return content, estimate_tokens(content)\n\n # Determine if we should add line numbers\n add_line_numbers = should_add_line_numbers(file_path, include_line_numbers)\n logger.debug(f\"[FILES] Line numbers for {file_path}: {'enabled' if add_line_numbers else 'disabled'}\")\n\n # Read the file with UTF-8 encoding, replacing invalid characters\n # This ensures we can handle files with mixed encodings\n logger.debug(f\"[FILES] Reading file content for {file_path}\")\n with open(path, encoding=\"utf-8\", errors=\"replace\") as f:\n file_content = f.read()\n\n logger.debug(f\"[FILES] Successfully read {len(file_content)} characters from {file_path}\")\n\n # Add line numbers if requested or auto-detected\n if add_line_numbers:\n file_content = _add_line_numbers(file_content)\n logger.debug(f\"[FILES] Added line numbers to {file_path}\")\n else:\n # Still normalize line endings for consistency\n file_content = _normalize_line_endings(file_content)\n\n # Format with clear delimiters that help the AI understand file boundaries\n # Using consistent markers makes it easier for the model to parse\n # NOTE: These markers (\"--- BEGIN FILE: ... ---\") are distinct from git diff markers\n # (\"--- BEGIN DIFF: ... ---\") to allow AI to distinguish between complete file content\n # vs. partial diff content when files appear in both sections\n modified_at = datetime.fromtimestamp(stat_result.st_mtime, tz=timezone.utc).strftime(\"%Y-%m-%d %H:%M:%S %Z\")\n formatted = (\n f\"\\n--- BEGIN FILE: {file_path} (Last modified: {modified_at}) ---\\n\"\n f\"{file_content}\\n\"\n f\"--- END FILE: {file_path} ---\\n\"\n )\n tokens = estimate_tokens(formatted)\n logger.debug(f\"[FILES] Formatted content for {file_path}: {len(formatted)} chars, {tokens} tokens\")\n return formatted, tokens\n\n except Exception as e:\n logger.debug(f\"[FILES] Exception reading file {file_path}: {type(e).__name__}: {e}\")\n content = f\"\\n--- ERROR READING FILE: {file_path} ---\\nError: {str(e)}\\n--- END FILE ---\\n\"\n tokens = estimate_tokens(content)\n logger.debug(f\"[FILES] Returning error content for {file_path}: {tokens} tokens\")\n return content, tokens\n\n\ndef read_files(\n file_paths: list[str],\n code: Optional[str] = None,\n max_tokens: Optional[int] = None,\n reserve_tokens: int = 50_000,\n *,\n include_line_numbers: bool = False,\n) -> str:\n \"\"\"\n Read multiple files and optional direct code with smart token management.\n\n This function implements intelligent token budgeting to maximize the amount\n of relevant content that can be included in an AI prompt while staying\n within token limits. It prioritizes direct code and reads files until\n the token budget is exhausted.\n\n Args:\n file_paths: List of file or directory paths (absolute paths required)\n code: Optional direct code to include (prioritized over files)\n max_tokens: Maximum tokens to use (defaults to DEFAULT_CONTEXT_WINDOW)\n reserve_tokens: Tokens to reserve for prompt and response (default 50K)\n include_line_numbers: Whether to add line numbers to file content\n\n Returns:\n str: All file contents formatted for AI consumption\n \"\"\"\n if max_tokens is None:\n max_tokens = DEFAULT_CONTEXT_WINDOW\n\n logger.debug(f\"[FILES] read_files called with {len(file_paths)} paths\")\n logger.debug(\n f\"[FILES] Token budget: max={max_tokens:,}, reserve={reserve_tokens:,}, available={max_tokens - reserve_tokens:,}\"\n )\n\n content_parts = []\n total_tokens = 0\n available_tokens = max_tokens - reserve_tokens\n\n files_skipped = []\n\n # Priority 1: Handle direct code if provided\n # Direct code is prioritized because it's explicitly provided by the user\n if code:\n formatted_code = f\"\\n--- BEGIN DIRECT CODE ---\\n{code}\\n--- END DIRECT CODE ---\\n\"\n code_tokens = estimate_tokens(formatted_code)\n\n if code_tokens <= available_tokens:\n content_parts.append(formatted_code)\n total_tokens += code_tokens\n available_tokens -= code_tokens\n\n # Priority 2: Process file paths\n if file_paths:\n # Expand directories to get all individual files\n logger.debug(f\"[FILES] Expanding {len(file_paths)} file paths\")\n all_files = expand_paths(file_paths)\n logger.debug(f\"[FILES] After expansion: {len(all_files)} individual files\")\n\n if not all_files and file_paths:\n # No files found but paths were provided\n logger.debug(\"[FILES] No files found from provided paths\")\n content_parts.append(f\"\\n--- NO FILES FOUND ---\\nProvided paths: {', '.join(file_paths)}\\n--- END ---\\n\")\n else:\n # Read files sequentially until token limit is reached\n logger.debug(f\"[FILES] Reading {len(all_files)} files with token budget {available_tokens:,}\")\n for i, file_path in enumerate(all_files):\n if total_tokens >= available_tokens:\n logger.debug(f\"[FILES] Token budget exhausted, skipping remaining {len(all_files) - i} files\")\n files_skipped.extend(all_files[i:])\n break\n\n file_content, file_tokens = read_file_content(file_path, include_line_numbers=include_line_numbers)\n logger.debug(f\"[FILES] File {file_path}: {file_tokens:,} tokens\")\n\n # Check if adding this file would exceed limit\n if total_tokens + file_tokens <= available_tokens:\n content_parts.append(file_content)\n total_tokens += file_tokens\n logger.debug(f\"[FILES] Added file {file_path}, total tokens: {total_tokens:,}\")\n else:\n # File too large for remaining budget\n logger.debug(\n f\"[FILES] File {file_path} too large for remaining budget ({file_tokens:,} tokens, {available_tokens - total_tokens:,} remaining)\"\n )\n files_skipped.append(file_path)\n\n # Add informative note about skipped files to help users understand\n # what was omitted and why\n if files_skipped:\n logger.debug(f\"[FILES] {len(files_skipped)} files skipped due to token limits\")\n skip_note = \"\\n\\n--- SKIPPED FILES (TOKEN LIMIT) ---\\n\"\n skip_note += f\"Total skipped: {len(files_skipped)}\\n\"\n # Show first 10 skipped files as examples\n for _i, file_path in enumerate(files_skipped[:10]):\n skip_note += f\" - {file_path}\\n\"\n if len(files_skipped) > 10:\n skip_note += f\" ... and {len(files_skipped) - 10} more\\n\"\n skip_note += \"--- END SKIPPED FILES ---\\n\"\n content_parts.append(skip_note)\n\n result = \"\\n\\n\".join(content_parts) if content_parts else \"\"\n logger.debug(f\"[FILES] read_files complete: {len(result)} chars, {total_tokens:,} tokens used\")\n return result\n\n\ndef estimate_file_tokens(file_path: str) -> int:\n \"\"\"\n Estimate tokens for a file using file-type aware ratios.\n\n Args:\n file_path: Path to the file\n\n Returns:\n Estimated token count for the file\n \"\"\"\n try:\n if not os.path.exists(file_path) or not os.path.isfile(file_path):\n return 0\n\n file_size = os.path.getsize(file_path)\n\n # Get the appropriate ratio for this file type\n from .file_types import get_token_estimation_ratio\n\n ratio = get_token_estimation_ratio(file_path)\n\n return int(file_size / ratio)\n except Exception:\n return 0\n\n\ndef check_files_size_limit(files: list[str], max_tokens: int, threshold_percent: float = 1.0) -> tuple[bool, int, int]:\n \"\"\"\n Check if a list of files would exceed token limits.\n\n Args:\n files: List of file paths to check\n max_tokens: Maximum allowed tokens\n threshold_percent: Percentage of max_tokens to use as threshold (0.0-1.0)\n\n Returns:\n Tuple of (within_limit, total_estimated_tokens, file_count)\n \"\"\"\n if not files:\n return True, 0, 0\n\n total_estimated_tokens = 0\n file_count = 0\n threshold = int(max_tokens * threshold_percent)\n\n for file_path in files:\n try:\n estimated_tokens = estimate_file_tokens(file_path)\n total_estimated_tokens += estimated_tokens\n if estimated_tokens > 0: # Only count accessible files\n file_count += 1\n except Exception:\n # Skip files that can't be accessed for size check\n continue\n\n within_limit = total_estimated_tokens <= threshold\n return within_limit, total_estimated_tokens, file_count\n\n\ndef read_json_file(file_path: str) -> Optional[dict]:\n \"\"\"\n Read and parse a JSON file with proper error handling.\n\n Args:\n file_path: Path to the JSON file\n\n Returns:\n Parsed JSON data as dict, or None if file doesn't exist or invalid\n \"\"\"\n try:\n if not os.path.exists(file_path):\n return None\n\n with open(file_path, encoding=\"utf-8\") as f:\n return json.load(f)\n except (json.JSONDecodeError, OSError):\n return None\n\n\ndef write_json_file(file_path: str, data: dict, indent: int = 2) -> bool:\n \"\"\"\n Write data to a JSON file with proper formatting.\n\n Args:\n file_path: Path to write the JSON file\n data: Dictionary data to serialize\n indent: JSON indentation level\n\n Returns:\n True if successful, False otherwise\n \"\"\"\n try:\n os.makedirs(os.path.dirname(file_path), exist_ok=True)\n\n with open(file_path, \"w\", encoding=\"utf-8\") as f:\n json.dump(data, f, indent=indent, ensure_ascii=False)\n return True\n except (OSError, TypeError):\n return False\n\n\ndef get_file_size(file_path: str) -> int:\n \"\"\"\n Get file size in bytes with proper error handling.\n\n Args:\n file_path: Path to the file\n\n Returns:\n File size in bytes, or 0 if file doesn't exist or error\n \"\"\"\n try:\n if os.path.exists(file_path) and os.path.isfile(file_path):\n return os.path.getsize(file_path)\n return 0\n except OSError:\n return 0\n\n\ndef ensure_directory_exists(file_path: str) -> bool:\n \"\"\"\n Ensure the parent directory of a file path exists.\n\n Args:\n file_path: Path to file (directory will be created for parent)\n\n Returns:\n True if directory exists or was created, False on error\n \"\"\"\n try:\n directory = os.path.dirname(file_path)\n if directory:\n os.makedirs(directory, exist_ok=True)\n return True\n except OSError:\n return False\n\n\ndef is_text_file(file_path: str) -> bool:\n \"\"\"\n Check if a file is likely a text file based on extension and content.\n\n Args:\n file_path: Path to the file\n\n Returns:\n True if file appears to be text, False otherwise\n \"\"\"\n from .file_types import is_text_file as check_text_type\n\n return check_text_type(file_path)\n\n\ndef read_file_safely(file_path: str, max_size: int = 10 * 1024 * 1024) -> Optional[str]:\n \"\"\"\n Read a file with size limits and encoding handling.\n\n Args:\n file_path: Path to the file\n max_size: Maximum file size in bytes (default 10MB)\n\n Returns:\n File content as string, or None if file too large or unreadable\n \"\"\"\n try:\n if not os.path.exists(file_path) or not os.path.isfile(file_path):\n return None\n\n file_size = os.path.getsize(file_path)\n if file_size > max_size:\n return None\n\n with open(file_path, encoding=\"utf-8\", errors=\"ignore\") as f:\n return f.read()\n except OSError:\n return None\n\n\ndef check_total_file_size(files: list[str], model_name: str) -> Optional[dict]:\n \"\"\"\n Check if total file sizes would exceed token threshold before embedding.\n\n IMPORTANT: This performs STRICT REJECTION at MCP boundary.\n No partial inclusion - either all files fit or request is rejected.\n This forces the CLI to make better file selection decisions.\n\n This function MUST be called with the effective model name (after resolution).\n It should never receive 'auto' or None - model resolution happens earlier.\n\n Args:\n files: List of file paths to check\n model_name: The resolved model name for context-aware thresholds (required)\n\n Returns:\n Dict with `code_too_large` response if too large, None if acceptable\n \"\"\"\n if not files:\n return None\n\n # Validate we have a proper model name (not auto or None)\n if not model_name or model_name.lower() == \"auto\":\n raise ValueError(\n f\"check_total_file_size called with unresolved model: '{model_name}'. \"\n \"Model must be resolved before file size checking.\"\n )\n\n logger.info(f\"File size check: Using model '{model_name}' for token limit calculation\")\n\n from utils.model_context import ModelContext\n\n model_context = ModelContext(model_name)\n token_allocation = model_context.calculate_token_allocation()\n\n # Dynamic threshold based on model capacity\n context_window = token_allocation.total_tokens\n if context_window >= 1_000_000: # Gemini-class models\n threshold_percent = 0.8 # Can be more generous\n elif context_window >= 500_000: # Mid-range models\n threshold_percent = 0.7 # Moderate\n else: # OpenAI-class models (200K)\n threshold_percent = 0.6 # Conservative\n\n max_file_tokens = int(token_allocation.file_tokens * threshold_percent)\n\n # Use centralized file size checking (threshold already applied to max_file_tokens)\n within_limit, total_estimated_tokens, file_count = check_files_size_limit(files, max_file_tokens)\n\n if not within_limit:\n return {\n \"status\": \"code_too_large\",\n \"content\": (\n f\"The selected files are too large for analysis \"\n f\"(estimated {total_estimated_tokens:,} tokens, limit {max_file_tokens:,}). \"\n f\"Please select fewer, more specific files that are most relevant \"\n f\"to your question, then invoke the tool again.\"\n ),\n \"content_type\": \"text\",\n \"metadata\": {\n \"total_estimated_tokens\": total_estimated_tokens,\n \"limit\": max_file_tokens,\n \"file_count\": file_count,\n \"threshold_percent\": threshold_percent,\n \"model_context_window\": context_window,\n \"model_name\": model_name,\n \"instructions\": \"Reduce file selection and try again - all files must fit within budget. If this persists, please use a model with a larger context window where available.\",\n },\n }\n\n return None # Proceed with ALL files\n" }, { "path": "utils/image_utils.py", "content": "\"\"\"Utility helpers for validating image inputs.\"\"\"\n\nimport base64\nimport binascii\nimport os\nfrom collections.abc import Iterable\n\nfrom utils.file_types import IMAGES, get_image_mime_type\n\nDEFAULT_MAX_IMAGE_SIZE_MB = 20.0\n\n__all__ = [\"DEFAULT_MAX_IMAGE_SIZE_MB\", \"validate_image\"]\n\n\ndef _valid_mime_types() -> Iterable[str]:\n \"\"\"Return the MIME types permitted by the IMAGES whitelist.\"\"\"\n return (get_image_mime_type(ext) for ext in IMAGES)\n\n\ndef validate_image(image_path: str, max_size_mb: float = None) -> tuple[bytes, str]:\n \"\"\"Validate a user-supplied image path or data URL.\n\n Args:\n image_path: Either a filesystem path or a data URL.\n max_size_mb: Optional size limit (defaults to ``DEFAULT_MAX_IMAGE_SIZE_MB``).\n\n Returns:\n A tuple ``(image_bytes, mime_type)`` ready for upstream providers.\n\n Raises:\n ValueError: When the image is missing, malformed, or exceeds limits.\n \"\"\"\n if max_size_mb is None:\n max_size_mb = DEFAULT_MAX_IMAGE_SIZE_MB\n\n if image_path.startswith(\"data:\"):\n return _validate_data_url(image_path, max_size_mb)\n\n return _validate_file_path(image_path, max_size_mb)\n\n\ndef _validate_data_url(image_data_url: str, max_size_mb: float) -> tuple[bytes, str]:\n \"\"\"Validate a data URL and return image bytes plus MIME type.\"\"\"\n try:\n header, data = image_data_url.split(\",\", 1)\n mime_type = header.split(\";\")[0].split(\":\")[1]\n except (ValueError, IndexError) as exc:\n raise ValueError(f\"Invalid data URL format: {exc}\")\n\n valid_mime_types = list(_valid_mime_types())\n if mime_type not in valid_mime_types:\n raise ValueError(\n \"Unsupported image type: {mime}. Supported types: {supported}\".format(\n mime=mime_type, supported=\", \".join(valid_mime_types)\n )\n )\n\n try:\n image_bytes = base64.b64decode(data)\n except binascii.Error as exc:\n raise ValueError(f\"Invalid base64 data: {exc}\")\n\n _validate_size(image_bytes, max_size_mb)\n return image_bytes, mime_type\n\n\ndef _validate_file_path(file_path: str, max_size_mb: float) -> tuple[bytes, str]:\n \"\"\"Validate an image loaded from the filesystem.\"\"\"\n try:\n with open(file_path, \"rb\") as handle:\n image_bytes = handle.read()\n except FileNotFoundError:\n raise ValueError(f\"Image file not found: {file_path}\")\n except OSError as exc:\n raise ValueError(f\"Failed to read image file: {exc}\")\n\n ext = os.path.splitext(file_path)[1].lower()\n if ext not in IMAGES:\n raise ValueError(\n \"Unsupported image format: {ext}. Supported formats: {supported}\".format(\n ext=ext, supported=\", \".join(sorted(IMAGES))\n )\n )\n\n mime_type = get_image_mime_type(ext)\n _validate_size(image_bytes, max_size_mb)\n return image_bytes, mime_type\n\n\ndef _validate_size(image_bytes: bytes, max_size_mb: float) -> None:\n \"\"\"Ensure the image does not exceed the configured size limit.\"\"\"\n size_mb = len(image_bytes) / (1024 * 1024)\n if size_mb > max_size_mb:\n raise ValueError(f\"Image too large: {size_mb:.1f}MB (max: {max_size_mb}MB)\")\n" }, { "path": "utils/model_context.py", "content": "\"\"\"\nModel context management for dynamic token allocation.\n\nThis module provides a clean abstraction for model-specific token management,\nensuring that token limits are properly calculated based on the current model\nbeing used, not global constants.\n\nCONVERSATION MEMORY INTEGRATION:\nThis module works closely with the conversation memory system to provide\noptimal token allocation for multi-turn conversations:\n\n1. DUAL PRIORITIZATION STRATEGY SUPPORT:\n - Provides separate token budgets for conversation history vs. files\n - Enables the conversation memory system to apply newest-first prioritization\n - Ensures optimal balance between context preservation and new content\n\n2. MODEL-SPECIFIC ALLOCATION:\n - Dynamic allocation based on model capabilities (context window size)\n - Conservative allocation for smaller models (O3: 200K context)\n - Generous allocation for larger models (Gemini: 1M+ context)\n - Adapts token distribution ratios based on model capacity\n\n3. CROSS-TOOL CONSISTENCY:\n - Provides consistent token budgets across different tools\n - Enables seamless conversation continuation between tools\n - Supports conversation reconstruction with proper budget management\n\"\"\"\n\nimport logging\nfrom dataclasses import dataclass\nfrom typing import Any, Optional\n\nfrom config import DEFAULT_MODEL\nfrom providers import ModelCapabilities, ModelProviderRegistry\n\nlogger = logging.getLogger(__name__)\n\n\n@dataclass\nclass TokenAllocation:\n \"\"\"Token allocation strategy for a model.\"\"\"\n\n total_tokens: int\n content_tokens: int\n response_tokens: int\n file_tokens: int\n history_tokens: int\n\n @property\n def available_for_prompt(self) -> int:\n \"\"\"Tokens available for the actual prompt after allocations.\"\"\"\n return self.content_tokens - self.file_tokens - self.history_tokens\n\n\nclass ModelContext:\n \"\"\"\n Encapsulates model-specific information and token calculations.\n\n This class provides a single source of truth for all model-related\n token calculations, ensuring consistency across the system.\n \"\"\"\n\n def __init__(self, model_name: str, model_option: Optional[str] = None):\n self.model_name = model_name\n self.model_option = model_option # Store optional model option (e.g., \"for\", \"against\", etc.)\n self._provider = None\n self._capabilities = None\n self._token_allocation = None\n\n @property\n def provider(self):\n \"\"\"Get the model provider lazily.\"\"\"\n if self._provider is None:\n self._provider = ModelProviderRegistry.get_provider_for_model(self.model_name)\n if not self._provider:\n available_models = ModelProviderRegistry.get_available_model_names()\n if available_models:\n available_text = \", \".join(available_models)\n else:\n available_text = (\n \"No models detected. Configure provider credentials or set DEFAULT_MODEL to a valid option.\"\n )\n\n raise ValueError(\n f\"Model '{self.model_name}' is not available with current API keys. Available models: {available_text}.\"\n )\n return self._provider\n\n @property\n def capabilities(self) -> ModelCapabilities:\n \"\"\"Get model capabilities lazily.\"\"\"\n if self._capabilities is None:\n self._capabilities = self.provider.get_capabilities(self.model_name)\n return self._capabilities\n\n def calculate_token_allocation(self, reserved_for_response: Optional[int] = None) -> TokenAllocation:\n \"\"\"\n Calculate token allocation based on model capacity and conversation requirements.\n\n This method implements the core token budget calculation that supports the\n dual prioritization strategy used in conversation memory and file processing:\n\n TOKEN ALLOCATION STRATEGY:\n 1. CONTENT vs RESPONSE SPLIT:\n - Smaller models (< 300K): 60% content, 40% response (conservative)\n - Larger models (β‰₯ 300K): 80% content, 20% response (generous)\n\n 2. CONTENT SUB-ALLOCATION:\n - File tokens: 30-40% of content budget for newest file versions\n - History tokens: 40-50% of content budget for conversation context\n - Remaining: Available for tool-specific prompt content\n\n 3. CONVERSATION MEMORY INTEGRATION:\n - History allocation enables conversation reconstruction in reconstruct_thread_context()\n - File allocation supports newest-first file prioritization in tools\n - Remaining budget passed to tools via _remaining_tokens parameter\n\n Args:\n reserved_for_response: Override response token reservation\n\n Returns:\n TokenAllocation with calculated budgets for dual prioritization strategy\n \"\"\"\n total_tokens = self.capabilities.context_window\n\n # Dynamic allocation based on model capacity\n if total_tokens < 300_000:\n # Smaller context models (O3): Conservative allocation\n content_ratio = 0.6 # 60% for content\n response_ratio = 0.4 # 40% for response\n file_ratio = 0.3 # 30% of content for files\n history_ratio = 0.5 # 50% of content for history\n else:\n # Larger context models (Gemini): More generous allocation\n content_ratio = 0.8 # 80% for content\n response_ratio = 0.2 # 20% for response\n file_ratio = 0.4 # 40% of content for files\n history_ratio = 0.4 # 40% of content for history\n\n # Calculate allocations\n content_tokens = int(total_tokens * content_ratio)\n response_tokens = reserved_for_response or int(total_tokens * response_ratio)\n\n # Sub-allocations within content budget\n file_tokens = int(content_tokens * file_ratio)\n history_tokens = int(content_tokens * history_ratio)\n\n allocation = TokenAllocation(\n total_tokens=total_tokens,\n content_tokens=content_tokens,\n response_tokens=response_tokens,\n file_tokens=file_tokens,\n history_tokens=history_tokens,\n )\n\n logger.debug(f\"Token allocation for {self.model_name}:\")\n logger.debug(f\" Total: {allocation.total_tokens:,}\")\n logger.debug(f\" Content: {allocation.content_tokens:,} ({content_ratio:.0%})\")\n logger.debug(f\" Response: {allocation.response_tokens:,} ({response_ratio:.0%})\")\n logger.debug(f\" Files: {allocation.file_tokens:,} ({file_ratio:.0%} of content)\")\n logger.debug(f\" History: {allocation.history_tokens:,} ({history_ratio:.0%} of content)\")\n\n return allocation\n\n def estimate_tokens(self, text: str) -> int:\n \"\"\"\n Estimate token count for text using model-specific tokenizer.\n\n For now, uses simple estimation. Can be enhanced with model-specific\n tokenizers (tiktoken for OpenAI, etc.) in the future.\n \"\"\"\n # TODO: Integrate model-specific tokenizers\n # For now, use conservative estimation\n return len(text) // 3 # Conservative estimate\n\n @classmethod\n def from_arguments(cls, arguments: dict[str, Any]) -> \"ModelContext\":\n \"\"\"Create ModelContext from tool arguments.\"\"\"\n model_name = arguments.get(\"model\") or DEFAULT_MODEL\n return cls(model_name)\n" }, { "path": "utils/model_restrictions.py", "content": "\"\"\"\nModel Restriction Service\n\nThis module provides centralized management of model usage restrictions\nbased on environment variables. It allows organizations to limit which\nmodels can be used from each provider for cost control, compliance, or\nstandardization purposes.\n\nEnvironment Variables:\n- OPENAI_ALLOWED_MODELS: Comma-separated list of allowed OpenAI models\n- GOOGLE_ALLOWED_MODELS: Comma-separated list of allowed Gemini models\n- XAI_ALLOWED_MODELS: Comma-separated list of allowed X.AI GROK models\n- OPENROUTER_ALLOWED_MODELS: Comma-separated list of allowed OpenRouter models\n- DIAL_ALLOWED_MODELS: Comma-separated list of allowed DIAL models\n\nExample:\n OPENAI_ALLOWED_MODELS=o3-mini,o4-mini\n GOOGLE_ALLOWED_MODELS=flash\n XAI_ALLOWED_MODELS=grok-4,grok-4.1-fast-reasoning\n OPENROUTER_ALLOWED_MODELS=opus,sonnet,mistral\n\"\"\"\n\nimport logging\nfrom collections import defaultdict\nfrom typing import Optional\n\nfrom providers.shared import ProviderType\nfrom utils.env import get_env\n\nlogger = logging.getLogger(__name__)\n\n\nclass ModelRestrictionService:\n \"\"\"Central authority for environment-driven model allowlists.\n\n Role\n Interpret ``*_ALLOWED_MODELS`` environment variables, keep their\n entries normalised (lowercase), and answer whether a provider/model\n pairing is permitted.\n\n Responsibilities\n * Parse, cache, and expose per-provider restriction sets\n * Validate configuration by cross-checking each entry against the\n provider’s alias-aware model list\n * Offer helper methods such as ``is_allowed`` and ``filter_models`` to\n enforce policy everywhere model names appear (tool selection, CLI\n commands, etc.).\n \"\"\"\n\n # Environment variable names\n ENV_VARS = {\n ProviderType.OPENAI: \"OPENAI_ALLOWED_MODELS\",\n ProviderType.GOOGLE: \"GOOGLE_ALLOWED_MODELS\",\n ProviderType.XAI: \"XAI_ALLOWED_MODELS\",\n ProviderType.OPENROUTER: \"OPENROUTER_ALLOWED_MODELS\",\n ProviderType.DIAL: \"DIAL_ALLOWED_MODELS\",\n }\n\n def __init__(self):\n \"\"\"Initialize the restriction service by loading from environment.\"\"\"\n self.restrictions: dict[ProviderType, set[str]] = {}\n self._alias_resolution_cache: dict[ProviderType, dict[str, str]] = defaultdict(dict)\n self._load_from_env()\n\n def _load_from_env(self) -> None:\n \"\"\"Load restrictions from environment variables.\"\"\"\n for provider_type, env_var in self.ENV_VARS.items():\n env_value = get_env(env_var)\n\n if env_value is None or env_value == \"\":\n # Not set or empty - no restrictions (allow all models)\n logger.debug(f\"{env_var} not set or empty - all {provider_type.value} models allowed\")\n continue\n\n # Parse comma-separated list\n models = set()\n for model in env_value.split(\",\"):\n cleaned = model.strip().lower()\n if cleaned:\n models.add(cleaned)\n\n if models:\n self.restrictions[provider_type] = models\n self._alias_resolution_cache[provider_type] = {}\n logger.info(f\"{provider_type.value} allowed models: {sorted(models)}\")\n else:\n # All entries were empty after cleaning - treat as no restrictions\n logger.debug(f\"{env_var} contains only whitespace - all {provider_type.value} models allowed\")\n\n def validate_against_known_models(self, provider_instances: dict[ProviderType, any]) -> None:\n \"\"\"\n Validate restrictions against known models from providers.\n\n This should be called after providers are initialized to warn about\n typos or invalid model names in the restriction lists.\n\n Args:\n provider_instances: Dictionary of provider type to provider instance\n \"\"\"\n for provider_type, allowed_models in self.restrictions.items():\n provider = provider_instances.get(provider_type)\n if not provider:\n continue\n\n # Get all supported models using the clean polymorphic interface\n try:\n # Gather canonical models and aliases with consistent formatting\n all_models = provider.list_models(\n respect_restrictions=False,\n include_aliases=True,\n lowercase=True,\n unique=True,\n )\n supported_models = set(all_models)\n except Exception as e:\n logger.debug(f\"Could not get model list from {provider_type.value} provider: {e}\")\n supported_models = set()\n\n # Check each allowed model\n for allowed_model in allowed_models:\n if allowed_model not in supported_models:\n logger.warning(\n f\"Model '{allowed_model}' in {self.ENV_VARS[provider_type]} \"\n f\"is not a recognized {provider_type.value} model. \"\n f\"Please check for typos. Known models: {sorted(supported_models)}\"\n )\n\n def is_allowed(self, provider_type: ProviderType, model_name: str, original_name: Optional[str] = None) -> bool:\n \"\"\"\n Check if a model is allowed for a specific provider.\n\n Args:\n provider_type: The provider type (OPENAI, GOOGLE, etc.)\n model_name: The canonical model name (after alias resolution)\n original_name: The original model name before alias resolution (optional)\n\n Returns:\n True if allowed (or no restrictions), False if restricted\n \"\"\"\n if provider_type not in self.restrictions:\n # No restrictions for this provider\n return True\n\n allowed_set = self.restrictions[provider_type]\n\n if len(allowed_set) == 0:\n # Empty set - allowed\n return True\n\n # Check both the resolved name and original name (if different)\n names_to_check = {model_name.lower()}\n if original_name and original_name.lower() != model_name.lower():\n names_to_check.add(original_name.lower())\n\n # If any of the names is in the allowed set, it's allowed\n if any(name in allowed_set for name in names_to_check):\n return True\n\n # Attempt to resolve canonical names for allowed aliases using provider metadata.\n try:\n from providers.registry import ModelProviderRegistry\n\n provider = ModelProviderRegistry.get_provider(provider_type)\n except Exception: # pragma: no cover - registry lookup failure shouldn't break validation\n provider = None\n\n if provider:\n cache = self._alias_resolution_cache.setdefault(provider_type, {})\n\n for allowed_entry in list(allowed_set):\n normalized_resolved = cache.get(allowed_entry)\n\n if not normalized_resolved:\n try:\n resolved = provider._resolve_model_name(allowed_entry)\n except Exception: # pragma: no cover - resolution failures are treated as non-matches\n continue\n\n if not resolved:\n continue\n\n normalized_resolved = resolved.lower()\n cache[allowed_entry] = normalized_resolved\n\n if normalized_resolved in names_to_check:\n allowed_set.add(normalized_resolved)\n cache[normalized_resolved] = normalized_resolved\n return True\n\n return False\n\n def get_allowed_models(self, provider_type: ProviderType) -> Optional[set[str]]:\n \"\"\"\n Get the set of allowed models for a provider.\n\n Args:\n provider_type: The provider type\n\n Returns:\n Set of allowed model names, or None if no restrictions\n \"\"\"\n return self.restrictions.get(provider_type)\n\n def has_restrictions(self, provider_type: ProviderType) -> bool:\n \"\"\"\n Check if a provider has any restrictions.\n\n Args:\n provider_type: The provider type\n\n Returns:\n True if restrictions exist, False otherwise\n \"\"\"\n return provider_type in self.restrictions\n\n def filter_models(self, provider_type: ProviderType, models: list[str]) -> list[str]:\n \"\"\"\n Filter a list of models based on restrictions.\n\n Args:\n provider_type: The provider type\n models: List of model names to filter\n\n Returns:\n Filtered list containing only allowed models\n \"\"\"\n if not self.has_restrictions(provider_type):\n return models\n\n return [m for m in models if self.is_allowed(provider_type, m)]\n\n def get_restriction_summary(self) -> dict[str, any]:\n \"\"\"\n Get a summary of all restrictions for logging/debugging.\n\n Returns:\n Dictionary with provider names and their restrictions\n \"\"\"\n summary = {}\n for provider_type, allowed_set in self.restrictions.items():\n if allowed_set:\n summary[provider_type.value] = sorted(allowed_set)\n else:\n summary[provider_type.value] = \"none (provider disabled)\"\n\n return summary\n\n\n# Global instance (singleton pattern)\n_restriction_service: Optional[ModelRestrictionService] = None\n\n\ndef get_restriction_service() -> ModelRestrictionService:\n \"\"\"\n Get the global restriction service instance.\n\n Returns:\n The singleton ModelRestrictionService instance\n \"\"\"\n global _restriction_service\n if _restriction_service is None:\n _restriction_service = ModelRestrictionService()\n return _restriction_service\n" }, { "path": "utils/security_config.py", "content": "\"\"\"\nSecurity configuration and path validation constants\n\nThis module contains security-related constants and configurations\nfor file access control.\n\"\"\"\n\nfrom pathlib import Path\n\n# Dangerous system paths - block these AND all their subdirectories\n# These are system directories where user code should never reside\nDANGEROUS_SYSTEM_PATHS = {\n \"/\",\n \"/etc\",\n \"/usr\",\n \"/bin\",\n \"/var\",\n \"/root\",\n \"C:\\\\Windows\",\n \"C:\\\\Program Files\",\n}\n\n# User home container paths - block ONLY the exact path, not subdirectories\n# Subdirectory access (e.g., /home/user/project) is controlled by is_home_directory_root()\n# This allows users to work in their home subdirectories while blocking overly broad access\nDANGEROUS_HOME_CONTAINERS = {\n \"/home\",\n \"C:\\\\Users\",\n}\n\n# Combined set for backward compatibility\nDANGEROUS_PATHS = DANGEROUS_SYSTEM_PATHS | DANGEROUS_HOME_CONTAINERS\n\n# Directories to exclude from recursive file search\n# These typically contain generated code, dependencies, or build artifacts\nEXCLUDED_DIRS = {\n # Python\n \"__pycache__\",\n \".venv\",\n \"venv\",\n \"env\",\n \".env\",\n \"*.egg-info\",\n \".eggs\",\n \"wheels\",\n \".Python\",\n \".mypy_cache\",\n \".pytest_cache\",\n \".tox\",\n \"htmlcov\",\n \".coverage\",\n \"coverage\",\n # Node.js / JavaScript\n \"node_modules\",\n \".next\",\n \".nuxt\",\n \"bower_components\",\n \".sass-cache\",\n # Version Control\n \".git\",\n \".svn\",\n \".hg\",\n # Build Output\n \"build\",\n \"dist\",\n \"target\",\n \"out\",\n # IDEs\n \".idea\",\n \".vscode\",\n \".sublime\",\n \".atom\",\n \".brackets\",\n # Temporary / Cache\n \".cache\",\n \".temp\",\n \".tmp\",\n \"*.swp\",\n \"*.swo\",\n \"*~\",\n # OS-specific\n \".DS_Store\",\n \"Thumbs.db\",\n # Java / JVM\n \".gradle\",\n \".m2\",\n # Documentation build\n \"_build\",\n \"site\",\n # Mobile development\n \".expo\",\n \".flutter\",\n # Package managers\n \"vendor\",\n}\n\n\ndef is_dangerous_path(path: Path) -> bool:\n \"\"\"\n Check if a path is in or under a dangerous directory.\n\n This function handles two categories of dangerous paths differently:\n\n 1. System paths (DANGEROUS_SYSTEM_PATHS): Block the path AND all subdirectories.\n Example: /etc is dangerous, so /etc/passwd is also blocked.\n\n 2. Home containers (DANGEROUS_HOME_CONTAINERS): Block ONLY the exact path.\n Example: /home is blocked, but /home/user/project is allowed.\n Subdirectory access control is delegated to is_home_directory_root().\n\n Args:\n path: Path to check\n\n Returns:\n True if the path is dangerous and should not be accessed\n\n Security:\n Fixes path traversal vulnerability (CWE-22) while preserving\n user access to home subdirectories.\n \"\"\"\n try:\n resolved = path.resolve()\n\n def _dangerous_variants(p: Path) -> set[Path]:\n variants = {p}\n # Only resolve paths that are absolute on the current platform.\n # This avoids turning Windows-style strings into nonsense absolute paths on POSIX.\n if p.is_absolute():\n try:\n variants.add(p.resolve())\n except Exception:\n pass\n return variants\n\n # Check 1: Root directory (filesystem root)\n if resolved.parent == resolved:\n return True\n\n # Check 2: System paths - block exact match AND all subdirectories\n for dangerous in DANGEROUS_SYSTEM_PATHS:\n # Skip root \"/\" - already handled above\n if dangerous == \"/\":\n continue\n\n for dangerous_path in _dangerous_variants(Path(dangerous)):\n # is_relative_to() correctly handles both exact matches and subdirectories.\n # Resolving the dangerous base path also handles platform symlinks\n # (e.g., macOS /etc -> /private/etc, /var -> /private/var).\n if resolved == dangerous_path or resolved.is_relative_to(dangerous_path):\n return True\n\n # Check 3: Home containers - block ONLY exact match\n # Subdirectories like /home/user/project should pass through here\n # and be handled by is_home_directory_root() in resolve_and_validate_path()\n for container in DANGEROUS_HOME_CONTAINERS:\n for container_path in _dangerous_variants(Path(container)):\n if resolved == container_path:\n return True\n\n return False\n\n except Exception:\n return True # If we can't resolve, consider it dangerous\n" }, { "path": "utils/storage_backend.py", "content": "\"\"\"\nIn-memory storage backend for conversation threads\n\nThis module provides a thread-safe, in-memory alternative to Redis for storing\nconversation contexts. It's designed for ephemeral MCP server sessions where\nconversations only need to persist during a single Claude session.\n\n⚠️ PROCESS-SPECIFIC STORAGE: This storage is confined to a single Python process.\n Data stored in one process is NOT accessible from other processes or subprocesses.\n This is why simulator tests that run server.py as separate subprocesses cannot\n share conversation state between tool calls.\n\nKey Features:\n- Thread-safe operations using locks\n- TTL support with automatic expiration\n- Background cleanup thread for memory management\n- Singleton pattern for consistent state within a single process\n- Drop-in replacement for Redis storage (for single-process scenarios)\n\"\"\"\n\nimport logging\nimport threading\nimport time\nfrom typing import Optional\n\nfrom utils.env import get_env\n\nlogger = logging.getLogger(__name__)\n\n\nclass InMemoryStorage:\n \"\"\"Thread-safe in-memory storage for conversation threads\"\"\"\n\n def __init__(self):\n self._store: dict[str, tuple[str, float]] = {}\n self._lock = threading.Lock()\n # Match Redis behavior: cleanup interval based on conversation timeout\n # Run cleanup at 1/10th of timeout interval (e.g., 18 mins for 3 hour timeout)\n timeout_hours = int(get_env(\"CONVERSATION_TIMEOUT_HOURS\", \"3\") or \"3\")\n self._cleanup_interval = (timeout_hours * 3600) // 10\n self._cleanup_interval = max(300, self._cleanup_interval) # Minimum 5 minutes\n self._shutdown = False\n\n # Start background cleanup thread\n self._cleanup_thread = threading.Thread(target=self._cleanup_worker, daemon=True)\n self._cleanup_thread.start()\n\n logger.info(\n f\"In-memory storage initialized with {timeout_hours}h timeout, cleanup every {self._cleanup_interval//60}m\"\n )\n\n def set_with_ttl(self, key: str, ttl_seconds: int, value: str) -> None:\n \"\"\"Store value with expiration time\"\"\"\n with self._lock:\n expires_at = time.time() + ttl_seconds\n self._store[key] = (value, expires_at)\n logger.debug(f\"Stored key {key} with TTL {ttl_seconds}s\")\n\n def get(self, key: str) -> Optional[str]:\n \"\"\"Retrieve value if not expired\"\"\"\n with self._lock:\n if key in self._store:\n value, expires_at = self._store[key]\n if time.time() < expires_at:\n logger.debug(f\"Retrieved key {key}\")\n return value\n else:\n # Clean up expired entry\n del self._store[key]\n logger.debug(f\"Key {key} expired and removed\")\n return None\n\n def setex(self, key: str, ttl_seconds: int, value: str) -> None:\n \"\"\"Redis-compatible setex method\"\"\"\n self.set_with_ttl(key, ttl_seconds, value)\n\n def _cleanup_worker(self):\n \"\"\"Background thread that periodically cleans up expired entries\"\"\"\n while not self._shutdown:\n time.sleep(self._cleanup_interval)\n self._cleanup_expired()\n\n def _cleanup_expired(self):\n \"\"\"Remove all expired entries\"\"\"\n with self._lock:\n current_time = time.time()\n expired_keys = [k for k, (_, exp) in self._store.items() if exp < current_time]\n for key in expired_keys:\n del self._store[key]\n\n if expired_keys:\n logger.debug(f\"Cleaned up {len(expired_keys)} expired conversation threads\")\n\n def shutdown(self):\n \"\"\"Graceful shutdown of background thread\"\"\"\n self._shutdown = True\n if self._cleanup_thread.is_alive():\n self._cleanup_thread.join(timeout=1)\n\n\n# Global singleton instance\n_storage_instance = None\n_storage_lock = threading.Lock()\n\n\ndef get_storage_backend() -> InMemoryStorage:\n \"\"\"Get the global storage instance (singleton pattern)\"\"\"\n global _storage_instance\n if _storage_instance is None:\n with _storage_lock:\n if _storage_instance is None:\n _storage_instance = InMemoryStorage()\n logger.info(\"Initialized in-memory conversation storage\")\n return _storage_instance\n" }, { "path": "utils/token_utils.py", "content": "\"\"\"\nToken counting utilities for managing API context limits\n\nThis module provides functions for estimating token counts to ensure\nrequests stay within the Gemini API's context window limits.\n\nNote: The estimation uses a simple character-to-token ratio which is\napproximate. For production systems requiring precise token counts,\nconsider using the actual tokenizer for the specific model.\n\"\"\"\n\n# Default fallback for token limit (conservative estimate)\nDEFAULT_CONTEXT_WINDOW = 200_000 # Conservative fallback for unknown models\n\n\ndef estimate_tokens(text: str) -> int:\n \"\"\"\n Estimate token count using a character-based approximation.\n\n This uses a rough heuristic where 1 token β‰ˆ 4 characters, which is\n a reasonable approximation for English text. The actual token count\n may vary based on:\n - Language (non-English text may have different ratios)\n - Code vs prose (code often has more tokens per character)\n - Special characters and formatting\n\n Args:\n text: The text to estimate tokens for\n\n Returns:\n int: Estimated number of tokens\n \"\"\"\n return len(text) // 4\n\n\ndef check_token_limit(text: str, context_window: int = DEFAULT_CONTEXT_WINDOW) -> tuple[bool, int]:\n \"\"\"\n Check if text exceeds the specified token limit.\n\n This function is used to validate that prepared prompts will fit\n within the model's context window, preventing API errors and ensuring\n reliable operation.\n\n Args:\n text: The text to check\n context_window: The model's context window size (defaults to conservative fallback)\n\n Returns:\n Tuple[bool, int]: (is_within_limit, estimated_tokens)\n - is_within_limit: True if the text fits within context_window\n - estimated_tokens: The estimated token count\n \"\"\"\n estimated = estimate_tokens(text)\n return estimated <= context_window, estimated\n" } ]