feat: intro mini-swe-agent

Author: PsiACE

README.md

@@ -1,74 +1,52 @@
-# agent-client-protocol-python
+# Agent Client Protocol - Python SDK
 
-[![Release](https://img.shields.io/github/v/release/psiace/agent-client-protocol-python)](https://img.shields.io/github/v/release/psiace/agent-client-protocol-python)
-[![Build status](https://img.shields.io/github/actions/workflow/status/psiace/agent-client-protocol-python/main.yml?branch=main)](https://github.com/psiace/agent-client-protocol-python/actions/workflows/main.yml?query=branch%3Amain)
-[![codecov](https://codecov.io/gh/psiace/agent-client-protocol-python/branch/main/graph/badge.svg)](https://codecov.io/gh/psiace/agent-client-protocol-python)
-[![Commit activity](https://img.shields.io/github/commit-activity/m/psiace/agent-client-protocol-python)](https://img.shields.io/github/commit-activity/m/psiace/agent-client-protocol-python)
-[![License](https://img.shields.io/github/license/psiace/agent-client-protocol-python)](https://img.shields.io/github/license/psiace/agent-client-protocol-python)
+A Python implementation of the Agent Client Protocol (ACP) used by editors like Zed to talk to external agents over stdio.
 
-A Python implement of Agent Client Protocol (ACP, by Zed Industries)
+- Repository: https://github.com/psiace/agent-client-protocol-python
+- Docs: https://psiace.github.io/agent-client-protocol-python/
 
-- **Github repository**: <https://github.com/psiace/agent-client-protocol-python/>
-- **Documentation** <https://psiace.github.io/agent-client-protocol-python/>
+## What this provides
 
-## Getting started with your project
+- Typed ACP client/agent primitives (`acp` package under `src/`)
+- A runnable example: a bridge that wraps mini-swe-agent as an ACP agent
+- Reference implementations under `reference/` for learning and comparison
 
-### 1. Create a New Repository
+## Quick start
 
-First, create a repository on GitHub with the same name as this project, and then run the following commands:
-
-```bash
-git init -b main
-git add .
-git commit -m "init commit"
-git remote add origin git@github.com:psiace/agent-client-protocol-python.git
-git push -u origin main
-```
-
-### 2. Set Up Your Development Environment
-
-Then, install the environment and the pre-commit hooks with
+Install the development environment:
 
 ```bash
 make install
 ```
 
-This will also generate your `uv.lock` file
-
-### 3. Run the pre-commit hooks
-
-Initially, the CI/CD pipeline might be failing due to formatting issues. To resolve those run:
+Run quality checks:
 
 ```bash
-uv run pre-commit run -a
+make check
 ```
 
-### 4. Commit the changes
-
-Lastly, commit the changes made by the two steps above to your repository.
+Run tests:
 
 ```bash
-git add .
-git commit -m 'Fix formatting issues'
-git push origin main
+make test
 ```
 
-You are now ready to start development on your project!
-The CI/CD pipeline will be triggered when you open a pull request, merge to main, or when you create a new release.
+## Example: Mini SWE Agent bridge
+
+A minimal ACP bridge for mini-swe-agent is provided under [`examples/mini_swe_agent`](file:///Users/psiace/OSS/agent-client-protocol-python/examples/mini_swe_agent/README.md). It shows how to:
 
-To finalize the set-up for publishing to PyPI, see [here](https://fpgmaas.github.io/cookiecutter-uv/features/publishing/#set-up-for-pypi).
-For activating the automatic documentation with MkDocs, see [here](https://fpgmaas.github.io/cookiecutter-uv/features/mkdocs/#enabling-the-documentation-on-github).
-To enable the code coverage reports, see [here](https://fpgmaas.github.io/cookiecutter-uv/features/codecov/).
+- Parse a prompt from ACP content blocks
+- Stream agent output to the client with `session/update`
+- Map command execution to `tool_call` and `tool_call_update`
 
-## Releasing a new version
+See the example’s README or the docs quickstart for Zed configuration.
 
-- Create an API Token on [PyPI](https://pypi.org/).
-- Add the API Token to your projects secrets with the name `PYPI_TOKEN` by visiting [this page](https://github.com/psiace/agent-client-protocol-python/settings/secrets/actions/new).
-- Create a [new release](https://github.com/psiace/agent-client-protocol-python/releases/new) on Github.
-- Create a new tag in the form `*.*.*`.
+## Documentation
 
-For more details, see [here](https://fpgmaas.github.io/cookiecutter-uv/features/cicd/#how-to-trigger-a-release).
+- Getting started: [docs/index.md](docs/index.md)
+- Quickstart: [docs/quickstart.md](docs/quickstart.md)
+- Mini SWE Agent example details: [docs/mini-swe-agent.md](docs/mini-swe-agent.md)
 
----
+## Notes
 
-Repository initiated with [fpgmaas/cookiecutter-uv](https://github.com/fpgmaas/cookiecutter-uv).
+- The `reference/` directory contains educational examples and may include optional dependencies. These are not required to use the example bridge.

docs/index.md

@@ -1,8 +1,6 @@
 # agent-client-protocol-python
 
-[![Release](https://img.shields.io/github/v/release/psiace/agent-client-protocol-python)](https://img.shields.io/github/v/release/psiace/agent-client-protocol-python)
-[![Build status](https://img.shields.io/github/actions/workflow/status/psiace/agent-client-protocol-python/main.yml?branch=main)](https://github.com/psiace/agent-client-protocol-python/actions/workflows/main.yml?query=branch%3Amain)
-[![Commit activity](https://img.shields.io/github/commit-activity/m/psiace/agent-client-protocol-python)](https://img.shields.io/github/commit-activity/m/psiace/agent-client-protocol-python)
-[![License](https://img.shields.io/github/license/psiace/agent-client-protocol-python)](https://img.shields.io/github/license/psiace/agent-client-protocol-python)
+A Python implementation of the Agent Client Protocol (ACP) used by editors like Zed to talk to external agents over stdio.
 
-A Python implement of Agent Client Protocol (ACP, by Zed Industries)
+- Quickstart: [quickstart.md](quickstart.md)
+- Mini SWE Agent example: [mini-swe-agent.md](mini-swe-agent.md)

docs/mini-swe-agent.md

@@ -0,0 +1,28 @@
+# Mini SWE Agent bridge
+
+This example wraps mini-swe-agent behind ACP so Zed can run it as an external agent over stdio.
+
+## Behavior
+
+- Prompts: text blocks are concatenated into a single task string; referenced resources (`resource_link` / `resource`) are surfaced as hints in the task.
+- Streaming: incremental text is sent via `session/update` with `agent_message_chunk`.
+- Tool calls: when the agent executes a shell command, the bridge sends:
+  - `tool_call` with `kind=execute`, pending status, and a bash code block containing the command
+  - `tool_call_update` upon completion, including output and a `rawOutput` object with `output` and `returncode`
+- Final result: on task submission (mini-swe-agent prints `COMPLETE_TASK_AND_SUBMIT_FINAL_OUTPUT` as the first line), a final `agent_message_chunk` with the submission content is sent.
+
+Non-terminating events (e.g. user rejection or timeouts) are surfaced both as a `tool_call_update` with `status=cancelled|failed` and as a text chunk so the session can continue.
+
+## Configuration
+
+Environment variables set in the Zed server config control the model:
+
+- `MINI_SWE_MODEL`: model ID (e.g. `openrouter/openai/gpt-4o-mini`)
+- `MINI_SWE_MODEL_KWARGS`: JSON string of extra parameters (e.g. `{ "api_base": "https://openrouter.ai/api/v1" }`)
+- Vendor API keys (e.g. `OPENROUTER_API_KEY`) must be present in the environment
+
+If `mini-swe-agent` is not installed in the venv, the bridge attempts to import a vendored reference copy under `reference/mini-swe-agent/src`.
+
+## Files
+
+- Example entry: [`examples/mini_swe_agent/agent.py`](https://github.com/psiace/agent-client-protocol-python/blob/main/examples/mini_swe_agent/agent.py)

docs/quickstart.md

@@ -0,0 +1,54 @@
+# Quickstart
+
+This repository provides a Python implementation of the Agent Client Protocol (ACP) and a minimal example that bridges mini-swe-agent into an ACP agent.
+
+## Prerequisites
+
+- Python 3.10+
+- A virtual environment for this repo (`make install` will create one with uv)
+- Zed editor (for running the example agent)
+
+## Install
+
+```bash
+make install
+```
+
+Run checks:
+
+```bash
+make check
+```
+
+## Run the Mini SWE Agent bridge in Zed
+
+Install mini-swe-agent into this repo’s venv.
+
+```bash
+./.venv/bin/pip install mini-swe-agent
+```
+
+Add an agent server to Zed’s `settings.json`:
+
+```json
+{
+  "agent_servers": {
+    "Mini SWE Agent (Python)": {
+      "command": "/absolute/path/to/agent-client-protocol-python/.venv/bin/python",
+      "args": [
+        "/absolute/path/to/agent-client-protocol-python/examples/mini_swe_agent/agent.py"
+      ],
+      "env": {
+        "PYTHONPATH": "/absolute/path/to/agent-client-protocol-python/src",
+        "MINI_SWE_MODEL": "openrouter/openai/gpt-4o-mini",
+        "MINI_SWE_MODEL_KWARGS": "{\"api_base\":\"https://openrouter.ai/api/v1\"}",
+        "OPENROUTER_API_KEY": "sk-or-..."
+      }
+    }
+  }
+}
+```
+
+In Zed, open the Agents panel and select "Mini SWE Agent (Python)".
+
+For details on behavior and message mapping, see [mini-swe-agent.md](mini-swe-agent.md).

examples/mini_swe_agent/README.md

@@ -0,0 +1,60 @@
+# Mini SWE Agent (Python) — ACP Bridge
+
+A minimal Agent Client Protocol (ACP) bridge that wraps mini-swe-agent so it can be run by Zed as an external agent over stdio.
+
+## Configure in Zed (using this repo’s venv)
+
+Add an `agent_servers` entry to Zed’s `settings.json`. Point `command` to this repo’s venv Python and `args` to this example script:
+
+```json
+{
+  "agent_servers": {
+    "Mini SWE Agent (Python)": {
+      "command": "/absolute/path/to/agent-client-protocol-python/.venv/bin/python",
+      "args": [
+        "/absolute/path/to/agent-client-protocol-python/examples/mini_swe_agent/agent.py"
+      ],
+      "env": {
+        "PYTHONPATH": "/absolute/path/to/agent-client-protocol-python/src",
+        "MINI_SWE_MODEL": "openrouter/openai/gpt-4o-mini",
+        "MINI_SWE_MODEL_KWARGS": "{\"api_base\":\"https://openrouter.ai/api/v1\"}",
+        "OPENROUTER_API_KEY": "sk-or-..."
+      }
+    }
+  }
+}
+```
+
+Notes
+- `command` must be the absolute path to this repository’s venv Python.
+- `args` must point to this example script.
+- `PYTHONPATH` must point to this repository’s `src` so the `acp` package can be imported.
+- Using OpenRouter:
+  - Set `MINI_SWE_MODEL` to a model supported by OpenRouter (e.g. `openrouter/openai/gpt-4o-mini`, `openrouter/anthropic/claude-3.5-sonnet`).
+  - Set `MINI_SWE_MODEL_KWARGS` to a JSON containing `api_base`: `{ "api_base": "https://openrouter.ai/api/v1" }`.
+  - Set `OPENROUTER_API_KEY` to your API key.
+- Alternatively, you can use native OpenAI/Anthropic APIs. Set `MINI_SWE_MODEL` accordingly and provide the vendor-specific API key; `MINI_SWE_MODEL_KWARGS` is optional.
+
+## Requirements
+
+Install mini-swe-agent (or at least its core deps) into this repo’s venv:
+
+```bash
+/path/to/.venv/bin/pip install mini-swe-agent
+# or: pip install litellm jinja2 tenacity
+```
+
+Then in Zed, open the Agents panel and select "Mini SWE Agent (Python)" to start a thread.
+
+## Behavior overview
+
+- User prompt handling
+  - Text blocks are concatenated into a task and passed to mini-swe-agent.
+- Streaming updates
+  - The agent sends `session/update` with `agent_message_chunk` for incremental messages.
+- Command execution visualization
+  - Each bash execution is reported with a `tool_call` (start) and a `tool_call_update` (complete) including command and output (`returncode` in rawOutput).
+- Final result
+  - A final `agent_message_chunk` is sent at the end of the turn with the submitted output.
+
+Use Zed’s “open acp logs” command to inspect ACP traffic if needed.