terminal-agent-cli 0.1.0__tar.gz

terminal_agent_cli-0.1.0/.env.example

@@ -0,0 +1,17 @@
+# Terminal Agent Environment Variables Configuration
+# Optional: Set provider overrides
+TERMINAL_AGENT_PROVIDER=mock
+TERMINAL_AGENT_MODEL=mock-model
+
+# For Ollama Provider (Local open models)
+OLLAMA_HOST=http://localhost:11434
+
+# For OpenAI Provider
+# OPENAI_API_KEY=sk-...
+
+# For Anthropic Provider
+# ANTHROPIC_API_KEY=sk-ant-...
+
+# For Google Gemini Provider
+# GEMINI_API_KEY=AIzaSy...
+

terminal_agent_cli-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,37 @@
+---
+name: Bug Report
+about: Create a report to help us reproduce and resolve an issue
+title: "[BUG] "
+labels: ["bug"]
+assignees: ""
+---
+
+## Description
+A clear and concise description of the bug.
+
+## Steps to Reproduce
+1. Run command: `terminal-agent run "..."`
+2. Configure provider: `...`
+3. Execute step: `...`
+4. Observe failure.
+
+## Expected Behavior
+What should have occurred (e.g., successful repair, specific failure category classification, or clean rollback).
+
+## Actual Behavior
+What actually occurred (include error messages or stack traces).
+
+## Environment Details
+- **Operating System**: (e.g., Linux Ubuntu 22.04, macOS 14.4, Windows 11)
+- **Python Version**: (`python --version`, e.g., 3.11.8)
+- **Terminal Agent Version**: (`terminal-agent --version` or git commit SHA)
+- **Model Provider**: (e.g., Ollama / OpenAI / Anthropic / Gemini / Mock)
+- **Sandbox Mode**: (e.g., Local / Docker)
+
+## Logs & Trace Output
+```bash
+# Attach output of 'terminal-agent doctor' or 'terminal-agent trace <session_id>' if available
+```
+
+## Additional Context
+Add any other context, repository layout, or screenshots about the problem here.

terminal_agent_cli-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,30 @@
+---
+name: Feature Request
+about: Suggest a new feature, provider adapter, tool, or architectural improvement
+title: "[FEATURE] "
+labels: ["enhancement"]
+assignees: ""
+---
+
+## Problem & Use Case
+Is your feature request related to a specific limitation or problem? (e.g., "I want to verify Rust projects using cargo test parser...")
+
+## Proposed Solution
+A clear and concise description of what you want to happen and how it fits into the verify-first architecture.
+
+## Alternatives Considered
+Describe any alternative solutions or workarounds you have considered.
+
+## Component Affected
+- [ ] Agent Loop / Orchestrator (`src/terminal_agent/agent/`)
+- [ ] Context Engine & Ranker (`src/terminal_agent/context/`)
+- [ ] Independent Verifier (`src/terminal_agent/verifier/`)
+- [ ] Security & Sandboxing (`src/terminal_agent/security/`, `src/terminal_agent/sandbox/`)
+- [ ] Tool Registry (`src/terminal_agent/tools/`)
+- [ ] Failure Classifier & Recovery (`src/terminal_agent/recovery/`)
+- [ ] Model Providers (`src/terminal_agent/providers/`)
+- [ ] CLI & UX (`src/terminal_agent/cli/`)
+- [ ] Documentation / Benchmarks
+
+## Additional Context
+Add any other context, mockups, or references about the feature request here.

terminal_agent_cli-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,37 @@
+## Summary
+
+Provide a concise summary of the changes proposed in this pull request.
+
+## Motivation & Context
+
+Why is this change required? What problem does it solve or what feature does it introduce? (Link related issues with `Fixes #...` if applicable).
+
+## Changes Made
+
+- **Component A**: Description of change
+- **Component B**: Description of change
+
+## Testing Performed
+
+Describe the testing performed to ensure functionality and non-regression:
+- [ ] Automated Unit Tests: `pytest tests/ -v` (Attach output or count)
+- [ ] SWE Benchmark Suite: `python -m benchmarks.runner`
+- [ ] Manual CLI Verification: (e.g., `terminal-agent run "..."`)
+
+```text
+# Paste test execution summary here
+```
+
+## Breaking Changes
+
+Does this change introduce any breaking changes to existing CLI commands, configuration schemas, or APIs?
+- [ ] No
+- [ ] Yes (Explain migration path):
+
+## Checklist
+
+- [ ] My code follows the code style and typing standards of this repository.
+- [ ] I have verified that all existing and new tests pass locally.
+- [ ] I have updated the documentation (`README.md`, `SECURITY.md`, etc.) where relevant.
+- [ ] I have not committed any API keys, credentials, or secrets.
+- [ ] I have added appropriate test cases covering the new behavior.

terminal_agent_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+    branches: [ main, master ]
+
+jobs:
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+
+      - name: Configure Git for Testing
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run automated test suite
+        run: |
+          pytest tests/ -v
+
+      - name: Run benchmark evaluation harness
+        run: |
+          python -m benchmarks.runner

terminal_agent_cli-0.1.0/.gitignore

@@ -0,0 +1,85 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Distribution / packaging
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environments
+.venv/
+venv/
+ENV/
+env/
+ENV*/
+env*/
+
+# Testing, coverage, and linters
+.pytest_cache/
+.hypothesis/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+*.cover
+*.log
+
+# IDEs and Editors
+.idea/
+.vscode/
+*.swp
+*.swo
+*.swn
+*~
+.project
+.pydevproject
+.settings/
+
+# Operating System Files
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Secrets, Credentials, and Environment Configurations
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+*.pfx
+*.p12
+*.crt
+*.cert
+
+# Terminal Agent Session & Checkpoint Storage
+.terminal_agent/
+
+# Internal Development Scratch & Notes
+project.md
+terminal_agent_project.md
+scratch/
+benchmarks/results/

terminal_agent_cli-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,121 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the
+  overall community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or
+  advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email
+  address, without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at **picadolabs@gmail.com**.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or
+permanent ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within
+the community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.
+
+For answers to common questions about this code of conduct, see the FAQ at
+https://www.contributor-covenant.org/faq.

terminal_agent_cli-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,166 @@
+# Contributing to Terminal Agent
+
+Thank you for your interest in contributing to **Terminal Agent** by **PicadoLabs**!
+
+Terminal Agent is built on the **Verify-First** architectural paradigm. We welcome contributions that improve reliability, enhance provider integrations, strengthen security sandboxing, or extend autonomous verification capabilities.
+
+---
+
+## 1. Code of Conduct
+
+All contributors and participants must adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code.
+
+---
+
+## 2. Prerequisites
+
+Ensure you have the following installed on your development machine:
+- **Python**: Version `3.10`, `3.11`, or `3.12`
+- **Git**: Version `2.30+`
+- **Optional (for container sandboxing)**: Docker Engine
+- **Optional (for local LLM inference)**: [Ollama](https://ollama.com)
+
+---
+
+## 3. Local Development Setup
+
+1. **Fork and clone the repository**:
+   ```bash
+   git clone https://github.com/PicadoLabs/terminal-agent.git
+   cd terminal-agent
+   ```
+
+2. **Create and activate a virtual environment**:
+   ```bash
+   python -m venv .venv
+
+   # On Linux / macOS:
+   source .venv/bin/activate
+
+   # On Windows (PowerShell):
+   .venv\Scripts\Activate.ps1
+   ```
+
+3. **Install the package in editable mode with development dependencies**:
+   ```bash
+   python -m pip install --upgrade pip
+   pip install -e ".[dev]"
+   ```
+
+4. **Verify the installation**:
+   ```bash
+   terminal-agent --help
+   terminal-agent doctor
+   ```
+
+---
+
+## 4. Branching Strategy & Workflow
+
+1. Create a dedicated branch from `main`:
+   ```bash
+   git checkout -b feat/add-new-verifier-runner
+   # or
+   git checkout -b fix/resolve-windows-path-traversal
+   ```
+
+2. Follow semantic branch naming:
+   - `feat/<feature-name>`: New feature or capability.
+   - `fix/<bug-description>`: Bug fix or error resolution.
+   - `docs/<documentation-change>`: Documentation improvements.
+   - `test/<test-suite>`: New test cases or benchmark tasks.
+   - `refactor/<component>`: Internal refactoring with preserved functionality.
+
+---
+
+## 5. Development & Code Quality Guidelines
+
+### Architectural Principles
+- **Verify-First Autonomy**: Any code modification mechanism must be verifiable through external, objective tests. The agent must never declare completion without test confirmation.
+- **Defense in Depth**: All tool executions must route through `SecurityPolicyEnforcer` and `SecretGuard`. Never bypass sandboxing boundaries.
+- **Deterministic Context**: Keep context discovery fast, bounded by token budgets, and deterministic.
+
+### Typing & Code Style
+- Use standard Python type annotations (`typing` and Python 3.10+ union types).
+- Use Pydantic v2 models for structured schemas and configuration.
+- Preserve backward compatibility with Python 3.10+.
+
+---
+
+## 6. Testing & Validation
+
+Before submitting changes, run the full test and benchmark suite locally:
+
+### Run Automated Unit and Integration Tests
+```bash
+pytest tests/ -v
+```
+
+### Run Full SWE Benchmark Evaluation Suite
+```bash
+python -m benchmarks.runner
+```
+
+### Run Type and Syntax Sanity
+```bash
+python -m py_compile src/terminal_agent/**/*.py
+```
+
+All 37 test cases and 10 benchmark evaluation tasks must pass cleanly.
+
+---
+
+## 7. Commit Message Guidelines
+
+We follow the [Conventional Commits](https://www.conventionalcommits.org/) specification:
+
+```
+<type>(<scope>): <short description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Examples:
+- `feat(verifier): add support for rust cargo test parser`
+- `fix(sandbox): terminate child processes on local timeout`
+- `docs(readme): add docker sandboxing guide`
+- `test(security): add test for path traversal with symlinks`
+
+---
+
+## 8. Submitting a Pull Request (PR)
+
+1. Ensure your branch is rebased on the latest `main`:
+   ```bash
+   git fetch origin
+   git rebase origin/main
+   ```
+2. Push your branch to your fork:
+   ```bash
+   git push origin feat/my-feature
+   ```
+3. Open a Pull Request on GitHub against `PicadoLabs/terminal-agent:main`.
+4. Fill out the [Pull Request Template](.github/pull_request_template.md) completely:
+   - Provide a clear summary of what was changed and why.
+   - Attach test execution results and commands run.
+   - Highlight any potential breaking changes.
+
+---
+
+## 9. Reporting Issues
+
+- **Bug Reports**: Use the [Bug Report Template](.github/ISSUE_TEMPLATE/bug_report.md). Include your OS, Python version, steps to reproduce, and terminal output.
+- **Feature Requests**: Use the [Feature Request Template](.github/ISSUE_TEMPLATE/feature_request.md). Explain the problem, proposed solution, and alternatives considered.
+- **Security Vulnerabilities**: **DO NOT** file public issues. Follow the private disclosure process in [SECURITY.md](SECURITY.md) by contacting `picadolabs@gmail.com`.
+
+---
+
+## 10. Community & Organization
+
+Terminal Agent is maintained by **PicadoLabs**.
+
+- **Organization**: [https://github.com/PicadoLabs](https://github.com/PicadoLabs)
+- **Website**: [https://picadolabs.me](https://picadolabs.me)
+- **Contact**: [picadolabs@gmail.com](mailto:picadolabs@gmail.com)

terminal_agent_cli-0.1.0/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Terminal Agent Maintainers
+Copyright (c) 2026 PicadoLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+