patchpilot 0.1.0__tar.gz

patchpilot-0.1.0/.env.example

@@ -0,0 +1 @@
+ANTHROPIC_API_KEY=your-key-here

patchpilot-0.1.0/.gitignore

@@ -0,0 +1,26 @@
+# Secrets
+.env
+.env.*
+!.env.example
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+
+# Agent workspaces
+workspaces/

patchpilot-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ilmee De Silva
+
+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.

patchpilot-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.5
+Name: patchpilot
+Version: 0.1.0
+Summary: An AI agent that upgrades your dependencies, fixes what breaks, and opens a PR
+Project-URL: Homepage, https://github.com/ilmeedesilva/patchpilot
+Project-URL: Issues, https://github.com/ilmeedesilva/patchpilot/issues
+Project-URL: Demo, https://github.com/ilmeedesilva/patchpilot-demo
+Author: Ilmee De Silva
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,claude,dependencies,developer-tools,llm,upgrade
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: anthropic>=2.3.0
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=9; extra == 'dev'
+Requires-Dist: ruff>=0.17; extra == 'dev'
+Requires-Dist: twine>=6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# patchpilot
+
+[![CI](https://github.com/ilmeedesilva/patchpilot/actions/workflows/ci.yml/badge.svg)](https://github.com/ilmeedesilva/patchpilot/actions/workflows/ci.yml)
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/ilmeedesilva/patchpilot/blob/main/LICENSE)
+
+**An AI agent that upgrades a dependency, fixes the code that breaks, and opens a pull request explaining what changed and why.**
+
+Dependabot and Renovate bump version numbers. When the new version breaks your build, the fix is still on you. patchpilot does that part: it upgrades the package inside a sandbox, runs your tests, reads the failures and the changelog, edits your code until the tests pass, and hands you a reviewable PR.
+
+<!-- TODO: demo GIF here: `patchpilot upgrade . pydantic --pr` → PR appears -->
+
+```console
+$ patchpilot upgrade . pydantic --pr
+• Creating an isolated copy of the repo on branch patchpilot/upgrade-pydantic
+• Starting a Docker sandbox (python:3.13-slim) and installing the project
+• Running the tests before upgrading
+• Agent is upgrading pydantic
+  → read_dependencies {}
+  → get_latest_version {"package": "pydantic"}
+  → pip_install {"requirement": "pydantic==2.14.1"}
+  → run_tests {}                      # fails: BaseSettings moved out of pydantic
+  → pip_install {"requirement": "pydantic-settings==2.16.2"}
+  → write_file {"path": "app/config.py"}
+  → write_file {"path": "app/models.py"}
+  → run_tests {}                      # passes
+• Re-running the tests to verify the agent's work
+• Pull request: https://github.com/<you>/<repo>/pull/1
+```
+
+The PR description is written by the agent, and includes:
+
+> **Breaking changes**
+> - **`BaseSettings` moved to `pydantic-settings`**: importing it from `pydantic` now fails. Installed `pydantic-settings`, added it to `requirements.txt`, and now import from `pydantic_settings`.
+> - **`@root_validator` without `skip_on_failure=True` is an error in v2**: replaced with `@model_validator(mode="after")`.
+> - …
+>
+> **Needs your attention**
+> - In v1 the password check ran even when another field had failed; in v2 it only runs once all fields are valid, so a bad email plus mismatched passwords now reports only the email error.
+
+*(Trimmed output and report from a real run on [`examples/pydantic-demo`](https://github.com/ilmeedesilva/patchpilot/tree/main/examples/pydantic-demo).)*
+
+## Quick start
+
+You need Python 3.11+, [Docker Desktop](https://www.docker.com/products/docker-desktop/) running, and an [Anthropic API key](https://console.anthropic.com/settings/keys).
+
+```bash
+pipx install git+https://github.com/ilmeedesilva/patchpilot.git   # soon: pipx install patchpilot
+export ANTHROPIC_API_KEY=sk-ant-...      # or put it in a .env file where you run patchpilot
+
+cd your-project                          # a git repo with a test suite
+patchpilot analyze .                     # read-only report: what's outdated, what's risky
+patchpilot upgrade . pydantic            # upgrade + fix, committed to a new branch
+patchpilot upgrade . pydantic --pr       # ...and open a pull request
+```
+
+Each run uses Anthropic API credit. The amount depends on the size of the project and how much breaks.
+
+## Usage
+
+### `patchpilot analyze <project>`
+
+Reads your dependency files, checks PyPI for the latest versions and runs your tests once, then prints a Markdown report. It covers what's outdated, which upgrades are major-version jumps likely to need code changes, and a suggested order. It changes nothing.
+
+### `patchpilot upgrade <project> <package>`
+
+1. Checks that `<package>` really is a dependency of `<project>`. If it's declared in a subfolder instead, it tells you which one.
+2. Makes a separate checkout of your repo (a git worktree) on a new branch, `patchpilot/upgrade-<package>`. **Your working copy is never touched.**
+3. Starts a Docker sandbox, installs your project into it, and checks that the tests pass *before* changing anything.
+4. Lets the agent work: upgrade the package, run the tests, read the failures and changelog, edit the code, and repeat.
+5. **Re-runs the tests itself** instead of trusting the agent's word, then commits to the branch with the agent's report as the commit message.
+
+Review the result with `git diff HEAD...patchpilot/upgrade-<package>`, then merge it or delete it.
+
+| Option | |
+|---|---|
+| `--pr` | Push the branch and open a GitHub pull request. If the tests still fail, it's opened as a **draft**. Uses the [GitHub CLI](https://cli.github.com/), so patchpilot never handles a GitHub token. |
+| `--test-command "..."` | How to run your tests (default: `python -m pytest -q`). |
+| `--image python:3.11-slim` | Docker image to run in. Match it to your project's Python version (default: `python:3.13-slim`). |
+| `--no-docker` | Use a local virtualenv instead of Docker. Faster, but your project's code runs directly on your machine. |
+
+## How it works
+
+```mermaid
+flowchart LR
+    subgraph host["Your machine"]
+        CLI["patchpilot CLI"] --> Loop["Agent loop"]
+        Loop <-->|"tool calls ⇄ results"| Claude["Claude API"]
+        Loop --> Files["Read / edit files<br/>in a temporary worktree"]
+    end
+    subgraph sandbox["Docker sandbox: sees only the worktree"]
+        Pip["pip install &lt;one package&gt;"]
+        Tests["your test suite"]
+    end
+    Loop --> Pip
+    Loop --> Tests
+    Loop -->|"verify, commit"| Branch["patchpilot/upgrade-&lt;pkg&gt;"]
+    Branch -->|"--pr"| PR["GitHub pull request"]
+```
+
+At the centre is a hand-written [tool-use loop](https://github.com/ilmeedesilva/patchpilot/blob/main/src/patchpilot/agent.py). patchpilot sends Claude the task and a list of tools. Claude replies with the tool it wants to call, patchpilot runs it and sends back the result, and this repeats until Claude writes its final report. Claude decides *what* to do next; patchpilot's code is the only thing that *does* anything.
+
+| Tool | Runs where | What it does |
+|---|---|---|
+| `read_dependencies` | host | Parses `requirements*.txt` and `pyproject.toml` |
+| `get_latest_version` | host | Queries PyPI, including changelog URLs |
+| `list_files`, `read_file` | host | Read-only, confined to the project folder |
+| `edit_file`, `write_file` | host | Exact-match edits; refuses `.git/` and virtualenvs |
+| `pip_install` | **sandbox** | One requirement at a time; flags, URLs and file paths are rejected |
+| `run_tests` | **sandbox** | Your test command, with a timeout |
+| `web_fetch` | Anthropic | Reads changelogs and migration guides |
+
+### Safety
+
+Upgrading means running code that isn't yours: your tests, and whatever a package runs when it installs. So that code runs inside a Docker container that:
+
+- mounts **only the temporary worktree**, not your home folder, SSH keys or other projects
+- runs as your user, not root, with all Linux capabilities dropped and `no-new-privileges`
+- is capped at 2 CPUs, 2 GB of memory and 512 processes
+- is deleted when the run ends, even if the run fails
+
+The agent loop and your API key never enter the container. These properties are checked by [integration tests](https://github.com/ilmeedesilva/patchpilot/blob/main/tests/test_sandbox.py), not just described here.
+
+### Design decisions
+
+- **Verify, don't trust.** The agent says when it's done, but patchpilot re-runs the tests itself before committing. The ✅ in the output is patchpilot's verdict, not the model's.
+- **Refuse to run when "tests pass" would mean nothing.** patchpilot stops if the tests already fail before the upgrade, or if the package isn't a dependency of the folder you pointed it at. Otherwise a green result could be meaningless.
+- **Fail before spending, not after.** Docker, GitHub login, remotes and branch names are all checked before the first API call.
+- **Leave nothing behind.** The worktree, container and virtualenv are cleaned up on success, failure or Ctrl-C. A branch only survives if it has a commit worth reviewing.
+- **A small, explicit tool surface** instead of a general shell. It's easier to reason about what the agent can do, and easier to sandbox.
+
+## Limitations
+
+- Python projects only, with `requirements*.txt` or a PEP 621 `pyproject.toml` (no Poetry or uv lockfiles yet).
+- One package per run.
+- The fix is only as good as your tests. If they don't cover what changed, patchpilot can't catch it, though the agent flags behaviour changes it notices under **Needs your attention**.
+- The sandbox needs network access to install packages, so code inside it can reach the internet.
+
+## Roadmap
+
+- [ ] Publish to PyPI (`pipx install patchpilot`)
+- [ ] GitHub Action: run weekly and open PRs automatically
+- [ ] Upgrade several packages in one run, ordered by risk
+- [ ] Turn off the sandbox's network access while tests run
+- [ ] uv and Poetry lockfile support
+
+## Development
+
+```bash
+git clone git@github.com:ilmeedesilva/patchpilot.git && cd patchpilot
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest          # Docker tests are skipped if Docker isn't running
+ruff check . && ruff format --check .
+```
+
+The test suite doesn't call the Anthropic API: the agent is replaced with a fake that makes known edits, and GitHub with a local bare repo plus a stand-in `gh`.
+
+## License
+
+[MIT](https://github.com/ilmeedesilva/patchpilot/blob/main/LICENSE)

patchpilot-0.1.0/README.md

@@ -0,0 +1,161 @@
+# patchpilot
+
+[![CI](https://github.com/ilmeedesilva/patchpilot/actions/workflows/ci.yml/badge.svg)](https://github.com/ilmeedesilva/patchpilot/actions/workflows/ci.yml)
+![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/ilmeedesilva/patchpilot/blob/main/LICENSE)
+
+**An AI agent that upgrades a dependency, fixes the code that breaks, and opens a pull request explaining what changed and why.**
+
+Dependabot and Renovate bump version numbers. When the new version breaks your build, the fix is still on you. patchpilot does that part: it upgrades the package inside a sandbox, runs your tests, reads the failures and the changelog, edits your code until the tests pass, and hands you a reviewable PR.
+
+<!-- TODO: demo GIF here: `patchpilot upgrade . pydantic --pr` → PR appears -->
+
+```console
+$ patchpilot upgrade . pydantic --pr
+• Creating an isolated copy of the repo on branch patchpilot/upgrade-pydantic
+• Starting a Docker sandbox (python:3.13-slim) and installing the project
+• Running the tests before upgrading
+• Agent is upgrading pydantic
+  → read_dependencies {}
+  → get_latest_version {"package": "pydantic"}
+  → pip_install {"requirement": "pydantic==2.14.1"}
+  → run_tests {}                      # fails: BaseSettings moved out of pydantic
+  → pip_install {"requirement": "pydantic-settings==2.16.2"}
+  → write_file {"path": "app/config.py"}
+  → write_file {"path": "app/models.py"}
+  → run_tests {}                      # passes
+• Re-running the tests to verify the agent's work
+• Pull request: https://github.com/<you>/<repo>/pull/1
+```
+
+The PR description is written by the agent, and includes:
+
+> **Breaking changes**
+> - **`BaseSettings` moved to `pydantic-settings`**: importing it from `pydantic` now fails. Installed `pydantic-settings`, added it to `requirements.txt`, and now import from `pydantic_settings`.
+> - **`@root_validator` without `skip_on_failure=True` is an error in v2**: replaced with `@model_validator(mode="after")`.
+> - …
+>
+> **Needs your attention**
+> - In v1 the password check ran even when another field had failed; in v2 it only runs once all fields are valid, so a bad email plus mismatched passwords now reports only the email error.
+
+*(Trimmed output and report from a real run on [`examples/pydantic-demo`](https://github.com/ilmeedesilva/patchpilot/tree/main/examples/pydantic-demo).)*
+
+## Quick start
+
+You need Python 3.11+, [Docker Desktop](https://www.docker.com/products/docker-desktop/) running, and an [Anthropic API key](https://console.anthropic.com/settings/keys).
+
+```bash
+pipx install git+https://github.com/ilmeedesilva/patchpilot.git   # soon: pipx install patchpilot
+export ANTHROPIC_API_KEY=sk-ant-...      # or put it in a .env file where you run patchpilot
+
+cd your-project                          # a git repo with a test suite
+patchpilot analyze .                     # read-only report: what's outdated, what's risky
+patchpilot upgrade . pydantic            # upgrade + fix, committed to a new branch
+patchpilot upgrade . pydantic --pr       # ...and open a pull request
+```
+
+Each run uses Anthropic API credit. The amount depends on the size of the project and how much breaks.
+
+## Usage
+
+### `patchpilot analyze <project>`
+
+Reads your dependency files, checks PyPI for the latest versions and runs your tests once, then prints a Markdown report. It covers what's outdated, which upgrades are major-version jumps likely to need code changes, and a suggested order. It changes nothing.
+
+### `patchpilot upgrade <project> <package>`
+
+1. Checks that `<package>` really is a dependency of `<project>`. If it's declared in a subfolder instead, it tells you which one.
+2. Makes a separate checkout of your repo (a git worktree) on a new branch, `patchpilot/upgrade-<package>`. **Your working copy is never touched.**
+3. Starts a Docker sandbox, installs your project into it, and checks that the tests pass *before* changing anything.
+4. Lets the agent work: upgrade the package, run the tests, read the failures and changelog, edit the code, and repeat.
+5. **Re-runs the tests itself** instead of trusting the agent's word, then commits to the branch with the agent's report as the commit message.
+
+Review the result with `git diff HEAD...patchpilot/upgrade-<package>`, then merge it or delete it.
+
+| Option | |
+|---|---|
+| `--pr` | Push the branch and open a GitHub pull request. If the tests still fail, it's opened as a **draft**. Uses the [GitHub CLI](https://cli.github.com/), so patchpilot never handles a GitHub token. |
+| `--test-command "..."` | How to run your tests (default: `python -m pytest -q`). |
+| `--image python:3.11-slim` | Docker image to run in. Match it to your project's Python version (default: `python:3.13-slim`). |
+| `--no-docker` | Use a local virtualenv instead of Docker. Faster, but your project's code runs directly on your machine. |
+
+## How it works
+
+```mermaid
+flowchart LR
+    subgraph host["Your machine"]
+        CLI["patchpilot CLI"] --> Loop["Agent loop"]
+        Loop <-->|"tool calls ⇄ results"| Claude["Claude API"]
+        Loop --> Files["Read / edit files<br/>in a temporary worktree"]
+    end
+    subgraph sandbox["Docker sandbox: sees only the worktree"]
+        Pip["pip install &lt;one package&gt;"]
+        Tests["your test suite"]
+    end
+    Loop --> Pip
+    Loop --> Tests
+    Loop -->|"verify, commit"| Branch["patchpilot/upgrade-&lt;pkg&gt;"]
+    Branch -->|"--pr"| PR["GitHub pull request"]
+```
+
+At the centre is a hand-written [tool-use loop](https://github.com/ilmeedesilva/patchpilot/blob/main/src/patchpilot/agent.py). patchpilot sends Claude the task and a list of tools. Claude replies with the tool it wants to call, patchpilot runs it and sends back the result, and this repeats until Claude writes its final report. Claude decides *what* to do next; patchpilot's code is the only thing that *does* anything.
+
+| Tool | Runs where | What it does |
+|---|---|---|
+| `read_dependencies` | host | Parses `requirements*.txt` and `pyproject.toml` |
+| `get_latest_version` | host | Queries PyPI, including changelog URLs |
+| `list_files`, `read_file` | host | Read-only, confined to the project folder |
+| `edit_file`, `write_file` | host | Exact-match edits; refuses `.git/` and virtualenvs |
+| `pip_install` | **sandbox** | One requirement at a time; flags, URLs and file paths are rejected |
+| `run_tests` | **sandbox** | Your test command, with a timeout |
+| `web_fetch` | Anthropic | Reads changelogs and migration guides |
+
+### Safety
+
+Upgrading means running code that isn't yours: your tests, and whatever a package runs when it installs. So that code runs inside a Docker container that:
+
+- mounts **only the temporary worktree**, not your home folder, SSH keys or other projects
+- runs as your user, not root, with all Linux capabilities dropped and `no-new-privileges`
+- is capped at 2 CPUs, 2 GB of memory and 512 processes
+- is deleted when the run ends, even if the run fails
+
+The agent loop and your API key never enter the container. These properties are checked by [integration tests](https://github.com/ilmeedesilva/patchpilot/blob/main/tests/test_sandbox.py), not just described here.
+
+### Design decisions
+
+- **Verify, don't trust.** The agent says when it's done, but patchpilot re-runs the tests itself before committing. The ✅ in the output is patchpilot's verdict, not the model's.
+- **Refuse to run when "tests pass" would mean nothing.** patchpilot stops if the tests already fail before the upgrade, or if the package isn't a dependency of the folder you pointed it at. Otherwise a green result could be meaningless.
+- **Fail before spending, not after.** Docker, GitHub login, remotes and branch names are all checked before the first API call.
+- **Leave nothing behind.** The worktree, container and virtualenv are cleaned up on success, failure or Ctrl-C. A branch only survives if it has a commit worth reviewing.
+- **A small, explicit tool surface** instead of a general shell. It's easier to reason about what the agent can do, and easier to sandbox.
+
+## Limitations
+
+- Python projects only, with `requirements*.txt` or a PEP 621 `pyproject.toml` (no Poetry or uv lockfiles yet).
+- One package per run.
+- The fix is only as good as your tests. If they don't cover what changed, patchpilot can't catch it, though the agent flags behaviour changes it notices under **Needs your attention**.
+- The sandbox needs network access to install packages, so code inside it can reach the internet.
+
+## Roadmap
+
+- [ ] Publish to PyPI (`pipx install patchpilot`)
+- [ ] GitHub Action: run weekly and open PRs automatically
+- [ ] Upgrade several packages in one run, ordered by risk
+- [ ] Turn off the sandbox's network access while tests run
+- [ ] uv and Poetry lockfile support
+
+## Development
+
+```bash
+git clone git@github.com:ilmeedesilva/patchpilot.git && cd patchpilot
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest          # Docker tests are skipped if Docker isn't running
+ruff check . && ruff format --check .
+```
+
+The test suite doesn't call the Anthropic API: the agent is replaced with a fake that makes known edits, and GitHub with a local bare repo plus a stand-in `gh`.
+
+## License
+
+[MIT](https://github.com/ilmeedesilva/patchpilot/blob/main/LICENSE)

patchpilot-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "patchpilot"
+dynamic = ["version"]
+description = "An AI agent that upgrades your dependencies, fixes what breaks, and opens a PR"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Ilmee De Silva" }]
+requires-python = ">=3.11"
+keywords = ["ai-agent", "dependencies", "upgrade", "llm", "claude", "developer-tools"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Build Tools",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "anthropic>=2.3.0",
+    "python-dotenv>=1.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=9", "ruff>=0.17", "build>=1.2", "twine>=6"]
+
+[project.urls]
+Homepage = "https://github.com/ilmeedesilva/patchpilot"
+Issues = "https://github.com/ilmeedesilva/patchpilot/issues"
+Demo = "https://github.com/ilmeedesilva/patchpilot-demo"
+
+[project.scripts]
+patchpilot = "patchpilot.cli:main"
+
+[tool.hatch.version]
+path = "src/patchpilot/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+exclude = ["examples", ".github"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/patchpilot"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP"]

patchpilot-0.1.0/src/patchpilot/__init__.py

@@ -0,0 +1,3 @@
+"""patchpilot: an AI agent that upgrades dependencies and fixes what breaks."""
+
+__version__ = "0.1.0"

patchpilot-0.1.0/src/patchpilot/agent.py

@@ -0,0 +1,90 @@
+"""The agent loop: send the conversation to Claude, run the tools it asks for, repeat."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import anthropic
+
+from patchpilot.tools import TOOL_FUNCTIONS, ToolError, Workspace
+
+MODEL = "claude-opus-5-5"
+
+# Anthropic-hosted tool: Claude fetches URLs (like changelogs) itself, no code needed on our side.
+# It only fetches URLs that already appear in the conversation, e.g. from get_latest_version.
+WEB_FETCH_TOOL = {"type": "web_fetch_20260209", "name": "web_fetch", "max_uses": 8}
+
+
+def execute_tool(ws: Workspace, name: str, tool_input: dict) -> tuple[str, bool]:
+    """Run one tool. Returns (result_text, is_error)."""
+    func = TOOL_FUNCTIONS.get(name)
+    if func is None:
+        return f"Unknown tool '{name}'.", True
+    try:
+        return func(ws, **tool_input), False
+    except ToolError as e:
+        return str(e), True
+    except TypeError as e:
+        return f"Invalid arguments for '{name}': {e}", True
+
+
+def run_agent(
+    ws: Workspace,
+    system: str,
+    task: str,
+    tools: list[dict],
+    max_turns: int = 30,
+    client: anthropic.Anthropic | None = None,
+    on_tool_call: Callable[[str, dict], None] | None = None,
+) -> str:
+    """Run the agent until it finishes and return its final text."""
+    client = client or anthropic.Anthropic()
+    allowed = {t["name"] for t in tools if "input_schema" in t}
+    messages: list[dict] = [{"role": "user", "content": task}]
+
+    for _ in range(max_turns):
+        response = client.beta.messages.create(
+            model=MODEL,
+            max_tokens=16000,
+            system=system,
+            tools=tools,
+            messages=messages,
+            output_config={"effort": "high"},
+            # If a request is declined by a safety classifier, retry on the server's default
+            # fallback model instead of failing outright.
+            betas=["server-side-fallback-2026-07-01"],
+            fallbacks="default",
+        )
+        messages.append({"role": "assistant", "content": response.content})
+
+        if response.stop_reason == "refusal":
+            raise RuntimeError("Claude declined this request.")
+        if response.stop_reason == "max_tokens":
+            raise RuntimeError("Response hit max_tokens before finishing.")
+        if response.stop_reason == "pause_turn":
+            continue
+
+        tool_uses = [b for b in response.content if b.type == "tool_use"]
+        if not tool_uses:
+            return "\n".join(b.text for b in response.content if b.type == "text")
+
+        tool_results = []
+        for block in tool_uses:
+            if on_tool_call:
+                on_tool_call(block.name, block.input)
+            if block.name in allowed:
+                result, is_error = execute_tool(ws, block.name, block.input)
+            else:
+                result, is_error = f"Tool '{block.name}' is not available here.", True
+            tool_results.append(
+                {
+                    "type": "tool_result",
+                    "tool_use_id": block.id,
+                    "content": result,
+                    "is_error": is_error,
+                }
+            )
+        # All results for one turn go back in a single user message.
+        messages.append({"role": "user", "content": tool_results})
+
+    raise RuntimeError(f"Agent did not finish within {max_turns} turns.")

patchpilot-0.1.0/src/patchpilot/analyze.py

@@ -0,0 +1,36 @@
+"""`patchpilot analyze`: a read-only report of what could be upgraded."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from patchpilot.agent import run_agent
+from patchpilot.tools import READ_TOOL_SCHEMAS, Workspace
+
+SYSTEM_PROMPT = """\
+You are patchpilot, an agent that keeps a Python project's dependencies up to date.
+
+Your job right now is to produce an upgrade report. Use the tools to:
+1. Read the project's declared dependencies.
+2. Look up the latest version of each one on PyPI.
+3. Run the test suite to establish a baseline.
+
+Then finish with a concise report in Markdown:
+- A table of dependencies: name, current specifier, latest version, and whether the
+  current specifier already allows the latest version.
+- Which upgrades look like major-version jumps that are likely to need code changes.
+- The baseline test result.
+- A recommended order to upgrade in, with one line of reasoning each.
+
+You can only read and run tests in this phase; do not suggest that you changed any files.\
+"""
+
+
+def analyze(ws: Workspace, on_tool_call: Callable[[str, dict], None] | None = None) -> str:
+    return run_agent(
+        ws,
+        system=SYSTEM_PROMPT,
+        task=f"Analyze the project at {ws.root} and write the report.",
+        tools=READ_TOOL_SCHEMAS,
+        on_tool_call=on_tool_call,
+    )