Metadata-Version: 2.4
Name: mycoder-harness
Version: 0.1.0
Summary: A Coding Agent Harness with governance guardrails — lightweight, auditable, extensible AI coding agent framework
Author: myCoder Team
License: MIT
Project-URL: Homepage, https://github.com/fantruekly/myCoder--coding-agent-harness
Project-URL: Repository, https://github.com/fantruekly/myCoder--coding-agent-harness
Keywords: ai,coding-agent,llm,harness,guardrails,governance
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27
Requires-Dist: keyring>=25
Requires-Dist: PyYAML>=6
Requires-Dist: textual>=0.50
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.29
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: httpx>=0.27; extra == "dev"

# myCoder

A Coding Agent Harness with governance guardrails. A lightweight, auditable, and extensible AI coding agent framework built in Python. Each component — context building, LLM abstraction, action parsing, guardrail checks, tool execution, and feedback collection — is independently testable with mock LLMs.

## Features

- **Pipeline State Machine Architecture**: ContextBuilder -> LLM Call -> ActionParser -> Guardrail -> Executor -> FeedbackCollector -> loop back
- **Governance Guardrails**: FileGuard, ScopeGuard, and ShellGuard protect against dangerous operations with configurable rules
- **Human-in-the-Loop (HITL)**: Commands like `git push` and `pip install` can be configured to require approval
- **Mock LLM Testing**: All core mechanisms are testable with deterministic mock LLM, no network dependency
- **Secure API Key Management**: Keys stored in the OS credential manager via `keyring`, with `.env` fallback

## Installation

Requires Python 3.10+.

```bash
pip install -e .
```

For development dependencies (including pytest):

```bash
pip install -e ".[dev]"
```

## Quick Start

```bash
# First-time setup: configure your API key and preferences
mycoder setup

# Check your API key status
mycoder key status

# Run a coding task
mycoder run "fix the broken test in test_user.py"

# Run with custom options
mycoder run "add type hints to all functions" --model gpt-4o --max-iterations 30
```

## Usage

### CLI Commands

| Command | Description |
|---------|-------------|
| `mycoder setup` | Interactive setup: creates default config and securely stores your API key |
| `mycoder run "<task>"` | Execute a coding task. Options: `--model`, `--base-url`, `--max-iterations`, `--verbose`, `--workspace` |
| `mycoder key status` | Check if API key is configured (never echoes the key) |
| `mycoder key set` | Update your API key |
| `mycoder key clear` | Remove your stored API key |

### Configuration

Configuration is loaded from `~/.mycoder/config.yaml` (or the platform equivalent). A default config is created on first `mycoder setup`. You can customize:

- **LLM settings**: provider, base URL, model, temperature, max tokens
- **Guardrail rules**: blocked file patterns, blocked shell commands, HITL approval list
- **Tool settings**: shell timeout, test timeout, max file read size
- **Loop settings**: max iterations, max context tokens

Configuration priority: CLI arguments > environment variables > config file > defaults.

## API Key Security

myCoder takes API key security seriously:

- **Primary storage**: `keyring` -> OS credential manager (Windows Credential Manager, macOS Keychain, Linux Secret Service)
- **Fallback**: `.env` file with `MYCODER_API_KEY` environment variable (less secure, warns on use)
- **Never hardcoded**: API keys are never written to source code, config files, or logs
- **Status checks**: `mycoder key status` shows only "configured" or "not configured" — never the plaintext key

### Threat Model

| Threat | Mitigation |
|--------|------------|
| API Key leaked to Git | Key stored in OS credential manager; `.env` and `*.key` in `.gitignore` |
| API Key in logs | Never logged; log sanitization for key patterns |
| API Key in process memory | Read from keyring on demand, held only in memory |
| Agent executes dangerous commands | ShellGuard blocks `rm -rf`, `sudo`, `chmod 777`, `curl \| bash`, etc. |
| Agent reads/writes sensitive files | FileGuard blocks `.env`, `*.key`, `*.pem`; ScopeGuard restricts to workspace |

## Directory Structure

```
myCoder/
├── pyproject.toml
├── README.md
├── .gitignore
├── .github/workflows/ci.yml
├── src/harness/
│   ├── __init__.py
│   ├── cli.py          # CLI entry point and command handlers
│   ├── config.py       # Configuration dataclasses and YAML loader
│   ├── context.py      # Context builder for LLM messages
│   ├── feedback.py     # Feedback collector for tool results
│   ├── guardrail.py    # FileGuard, ScopeGuard, ShellGuard, and orchestrator
│   ├── llm.py          # LLM abstraction (RealLLM, MockLLM)
│   ├── loop.py         # Agent main loop and stop judge
│   ├── memory.py       # Memory management (conventions, decisions, codebase knowledge)
│   ├── parser.py       # Action parser for LLM JSON responses
│   └── tools.py        # Tool executor (read_file, write_file, shell, run_tests)
└── tests/
    ├── __init__.py
    ├── test_cli.py
    ├── test_config.py
    ├── test_context.py
    ├── test_demo.py
    ├── test_feedback.py
    ├── test_guardrail.py
    ├── test_llm.py
    ├── test_loop.py
    ├── test_memory.py
    ├── test_parser.py
    └── test_tools.py
```

## Architecture

```
┌─────────────────────────────────────────────────┐
│                   CLI (cli.py)                    │
│   mycoder run | mycoder setup | mycoder key ...   │
└──────────────────────┬──────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│                Agent Loop (loop.py)               │
│                                                   │
│  ┌──────────┐  ┌──────┐  ┌────────┐  ┌────────┐ │
│  │ Context   │  │ LLM  │  │ Parser │  │ Stop   │ │
│  │ Builder  │→ │ Call │→ │        │→ │ Judge  │ │
│  └──────────┘  └──────┘  └────────┘  └────────┘ │
│       ↑                                    │      │
│       │         ┌──────────┐               │      │
│       │         │ Guardrail│←──────────────┘      │
│       │         └────┬─────┘                      │
│       │              │ allowed/approval            │
│       │         ┌────▼─────┐                      │
│       │         │ Executor │                      │
│       │         └────┬─────┘                      │
│       │              │                            │
│       │         ┌────▼──────┐                     │
│       └─────────│ Feedback   │                    │
│                 │ Collector │                     │
│                 └───────────┘                     │
└──────────────────────────────────────────────────┘
                       │
┌──────────────────────▼──────────────────────────┐
│              Infrastructure Layer                 │
│  ┌────────┐  ┌────────┐  ┌────────┐  ┌────────┐ │
│  │ Config │  │ Memory │  │Keyring │  │ Logging│ │
│  │        │  │        │  │        │  │        │ │
│  └────────┘  └────────┘  └────────┘  └────────┘ │
└──────────────────────────────────────────────────┘
```

## Running Tests

```bash
pytest tests/ -v
```

All core mechanism tests use `MockLLM` and run without network access.

## Known Limitations

- **Python 3.10+**: Requires Python 3.10 or newer.
- **keyring on headless Linux**: `keyring` may require additional configuration (e.g., `dbus` or `gnome-keyring`) on headless Linux servers. If `keyring` is unavailable, fall back to the `MYCODER_API_KEY` environment variable.
- **OpenAI-compatible API only**: Currently supports LLM providers with OpenAI-compatible chat completions API format.
- **Single task mode**: Each `mycoder run` executes one task end-to-end; no REPL or multi-turn conversation mode.

## License

MIT
