acpbox 0.1.1__tar.gz

acpbox-0.1.1/.dockerignore

@@ -0,0 +1,13 @@
+.git
+docs/
+
+__pycache__
+*.pyc
+.venv
+.pytest_cache
+.mypy_cache
+config.yaml
+.env
+build/
+dist/
+.coverage

acpbox-0.1.1/.env.example

@@ -0,0 +1,28 @@
+# Gateway config via environment. Copy to .env and set values.
+# All options can be set here; they override config.yaml.
+# ACP agent runs per-request over stdio (no HTTP, no /ping).
+
+# Docker image build only. Comma-separated: opencode, cursor (case-insensitive).
+# Examples: opencode | cursor | opencode,cursor
+# Match ACP_COMMAND below to an installed binary, e.g. ["opencode","acp"] or ["agent","acp"].
+AGENTS=opencode
+
+CONFIG_PATH=config.yaml
+
+# ACP agent command (stdio). JSON array, e.g. ["opencode", "acp"]
+ACP_COMMAND=["opencode", "acp"]
+# Extra env for ACP process as JSON object
+ACP_ENV={}
+# ACP session/new project directory (relative to process cwd or absolute). Default ./workspace; Docker image and compose use /workspace (see Dockerfile, docker-compose.yaml).
+ACP_WORKSPACE=./workspace
+
+GATEWAY_HOST=0.0.0.0
+GATEWAY_PORT=8080
+# Uvicorn process workers (one ACP subprocess per worker). Not OS threads.
+GATEWAY_WORKERS=1
+# Only has effect if uvicorn.run supports threads= (current releases usually do not).
+GATEWAY_THREADS=1
+
+# Agent API keys
+# CURSOR_API_KEY=sk-xxx
+# ANTHROPIC_API_KEY=sk-xxx

acpbox-0.1.1/.github/workflows/publish-pypi.yaml

@@ -0,0 +1,78 @@
+# Build and publish acpbox to PyPI when a release tag is pushed.
+# Expects tags vMAJOR.MINOR.PATCH (same shape as tag-on-merge.yaml).
+# Version in artifacts matches the tag (v stripped). Configure PyPI Trusted Publishing
+# for this repository (publish workflow permission id-token write is required).
+
+name: Publish to PyPI
+
+on:
+  workflow_dispatch:
+  workflow_call:
+  push:
+    tags:
+      - "v*"
+
+defaults:
+  run:
+    shell: bash
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Build and upload to PyPI
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Resolve release version from tag
+        id: rel
+        run: |
+          TAG="${GITHUB_REF_NAME}"
+          VERSION="${TAG#v}"
+          if [[ ! "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+            echo "Release tag must look like vMAJOR.MINOR.PATCH, got: $TAG"
+            exit 1
+          fi
+          echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+          echo "Publishing acpbox $VERSION (tag $TAG)"
+
+      - name: Ensure tag points to main
+        run: |
+          git fetch origin main
+          if ! git merge-base --is-ancestor "${GITHUB_SHA}" origin/main; then
+            echo "Tagged commit is not on main, refusing to publish."
+            exit 1
+          fi
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          pip install "build>=1.0"
+
+      - name: Run tests
+        run: |
+          pip install -e ".[dev]"
+          pytest tests/ -v -m "not integration" --tb=short
+
+      - name: Build distributions
+        env:
+          SETUPTOOLS_SCM_PRETEND_VERSION: ${{ steps.rel.outputs.version }}
+        run: python -m build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+          password: ${{ secrets.PYPI_API_TOKEN }}

acpbox-0.1.1/.github/workflows/tag-on-merge.yaml

@@ -0,0 +1,84 @@
+# Tag a new SemVer version when a PR is merged into the default branch (not on direct push to main).
+# Starts from v0.1.0 if no tags exist; bumps patch (e.g. v0.1.0 -> v0.1.1) on each merge.
+
+name: Tag release on merge
+
+on:
+  pull_request:
+    types: [closed]
+    branches:
+      - main
+  workflow_dispatch:
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  tag-version:
+    name: Bump and push version tag
+    runs-on: ubuntu-latest
+    if: github.event_name == 'workflow_dispatch' || github.event.pull_request.merged == true
+    permissions:
+      contents: write
+      actions: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ github.event_name == 'workflow_dispatch' && github.ref || github.event.pull_request.merge_commit_sha }}
+
+      - name: Fetch all tags
+        run: git fetch --tags
+
+      - name: Check if commit already has a tag
+        id: check
+        run: |
+          if [ -n "$(git tag --points-at HEAD)" ]; then
+            echo "skip=true" >> "$GITHUB_OUTPUT"
+            echo "Commit already has a tag, skipping."
+          else
+            echo "skip=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Get latest SemVer tag and bump patch
+        id: version
+        if: steps.check.outputs.skip != 'true'
+        run: |
+          set -e
+          # Latest tag matching v* (SemVer), version-sorted; default v0.1.0
+          LATEST=$(git tag -l 'v*' | sort -V | tail -1 || true)
+          if [ -z "$LATEST" ]; then
+            LATEST="v0.1.0"
+          fi
+          VERSION="${LATEST#v}"
+          # Bump patch: 0.1.0 -> 0.1.1
+          NEW_VERSION=$(echo "$VERSION" | awk -F. '{$3=$3+1; OFS="."; print $1,$2,$3}')
+          echo "previous=$LATEST" >> "$GITHUB_OUTPUT"
+          echo "version=$NEW_VERSION" >> "$GITHUB_OUTPUT"
+          echo "tag=v${NEW_VERSION}" >> "$GITHUB_OUTPUT"
+          echo "Bumping $LATEST -> v${NEW_VERSION}"
+
+      - name: Create and push tag
+        if: steps.check.outputs.skip != 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          TAG="${{ steps.version.outputs.tag }}"
+          git tag -a "$TAG" -m "Release $TAG (auto-tag on merge)"
+          git push origin "$TAG"
+
+      - name: Trigger Docker build
+        if: steps.check.outputs.skip != 'true'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.actions.createWorkflowDispatch({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              workflow_id: 'docker-build-push.yaml',
+              ref: 'main',
+              inputs: { tag: '${{ steps.version.outputs.tag }}' }
+            });

acpbox-0.1.1/.github/workflows/tests-on-pr.yaml

@@ -0,0 +1,34 @@
+# Run tests on every pull request (opened, updated, reopened).
+
+name: Tests on PR
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+  workflow_dispatch:
+
+defaults:
+  run:
+    shell: bash
+
+jobs:
+  test:
+    name: Test suite
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+
+      - name: Run tests
+        run: pytest tests/ -v -m "not integration" --cov=acpbox --cov-report=term-missing

acpbox-0.1.1/.gitignore

@@ -0,0 +1,11 @@
+__pycache__
+*.pyc
+*.egg-info
+.venv
+.pytest_cache
+.mypy_cache
+config.yaml
+.env
+build/
+dist/
+.coverage

acpbox-0.1.1/Dockerfile

@@ -0,0 +1,53 @@
+FROM python:3.11-slim
+
+# Comma-separated, case-insensitive: opencode, cursor. Pass at build time (e.g. docker compose build.args from .env).
+ARG AGENTS=
+
+RUN groupadd --gid 1000 user \
+ && useradd --uid 1000 --gid 1000 --create-home --home-dir /home/user user
+
+WORKDIR /app
+
+ENV DEBIAN_FRONTEND=noninteractive
+ENV HOME=/home/user
+ENV PATH="/home/user/.local/bin:/home/user/.opencode/bin:${PATH}"
+
+RUN set -eux; \
+    agents="$(printf '%s' "${AGENTS}" | tr '[:upper:]' '[:lower:]' | tr -d '[:space:]')"; \
+    agents=",${agents},"; \
+    install_opencode=0; \
+    install_cursor=0; \
+    case "${agents}" in (*,opencode,*) install_opencode=1 ;; esac; \
+    case "${agents}" in (*,cursor,*) install_cursor=1 ;; esac; \
+    if [ "${install_opencode}" = "0" ] && [ "${install_cursor}" = "0" ]; then \
+      echo "AGENTS build-arg empty or without opencode|cursor; image contains acpbox only. Install an ACP agent in a derived image or mount a binary."; \
+    else \
+      apt-get update; \
+      apt-get install -y --no-install-recommends curl ca-certificates bash; \
+      if [ "${install_opencode}" = "1" ]; then \
+        su user -s /bin/bash -c 'curl -fsSL https://opencode.ai/install | bash'; \
+        su user -s /bin/bash -c 'command -v opencode'; \
+      fi; \
+      if [ "${install_cursor}" = "1" ]; then \
+        su user -s /bin/bash -c 'curl -fsSL https://cursor.com/install | bash'; \
+        su user -s /bin/bash -c 'command -v agent'; \
+      fi; \
+      apt-get purge -y curl; \
+      apt-get autoremove -y; \
+      rm -rf /var/lib/apt/lists/*; \
+    fi
+
+COPY . .
+RUN pip install --no-cache-dir . \
+ && chown -R user:user /app \
+ && mkdir -p /workspace \
+ && chown user:user /workspace
+
+ENV ACP_WORKSPACE=/workspace
+ENV CONFIG_PATH=/app/config.yaml
+
+EXPOSE 8080
+
+USER user
+
+CMD ["acpbox"]

acpbox-0.1.1/LICENSE

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

acpbox-0.1.1/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: acpbox
+Version: 0.1.1
+Summary: OpenAI-compatible HTTP API gateway for Agent Client Protocol (ACP) over stdio
+Author: acpbox contributors
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn[standard]>=0.32.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: agent-client-protocol>=0.8.1
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Dynamic: license-file
+
+# ACPBox
+
+OpenAI-compatible HTTP API that acts as a **gateway to the Agent Client Protocol (ACP)**. Clients use the usual OpenAI endpoints (`/v1/models`, `/v1/chat/completions`, `/v1/responses`); the gateway runs the API with **uvicorn** and keeps **one ACP agent process per worker** over **stdio** (JSON-RPC), not HTTP.
+
+## Problem
+
+Many tools and SDKs expect an OpenAI-style API. ACP agents (e.g. [OpenCode](https://github.com/sst/opencode) via `opencode acp`, or **Cursor Agent** via `agent acp`) speak the [Agent Client Protocol](https://agentclientprotocol.com) over stdin/stdout. This gateway provides a single HTTP entry point: one base URL, OpenAI-shaped API, with one ACP binary instance per uvicorn worker.
+
+## How it works
+
+1. **Config** – YAML and env define the agent command, env vars, and **workspace** (`ACP_WORKSPACE`, default `./workspace`; Docker `/workspace`) passed as ACP `session/new` `cwd`.
+2. **One ACP process per worker** – The app runs under **uvicorn**. In lifespan each worker starts **one** ACP agent subprocess and keeps it for the worker's lifetime. With 8 workers you get 8 ACP binary instances. ACP uses **stdio** only (JSON-RPC, newline-delimited).
+3. **Reuse per request** – Each request in that worker uses the same process: `session/new` -> optional `session/set_mode` -> `session/prompt`, then the response is returned. The process is not terminated after each request.
+4. **Translation** – OpenAI requests are converted to ACP JSON-RPC; ACP content (e.g. `session/update` agent_message_chunk) is converted back to OpenAI chat/responses format.
+   - `GET /v1/models` – Uses the worker's ACP process: `initialize` (once) and `session/new`, returns **modes** (`modes.availableModes[].id`, e.g. OpenCode's `plan`, `build`) as the list of models.
+   - `POST /v1/chat/completions` – Uses the worker's ACP process; `model` selects the ACP mode. Reply as chat completion, or **Server-Sent Events** when `"stream": true` (OpenAI-style `chat.completion.chunk` lines and `data: [DONE]`). With `stream: false`, optional **`acp`** is `{ "steps": [ reasoning + command summaries ] }` (no raw chunks). With `stream: true`, each chunk may still carry raw **`acp`** from the wire (see `docs/api-mapping.md`).
+   - `POST /v1/responses` – Same; optional `chat_id` for client-side continuity (non-streaming only); **`acp.steps`** when present, like chat.
+
+See [docs/spec.md](docs/spec.md) and [docs/agent-client-protocol/docs/protocol/transports.mdx](docs/agent-client-protocol/docs/protocol/transports.mdx) for details.
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Gateway
+    participant AgentProcess
+
+    Note over Gateway,AgentProcess: One ACP process per uvicorn worker (started in lifespan)
+    Client->>Gateway: GET /v1/models
+    Gateway->>AgentProcess: initialize, session/new (reuse process)
+    AgentProcess-->>Gateway: modes (e.g. plan, build)
+    Gateway-->>Client: list of models
+
+    Client->>Gateway: POST /v1/chat/completions
+    Gateway->>AgentProcess: session/new, session/prompt (same process)
+    AgentProcess-->>Gateway: session/update, session/prompt result
+    Gateway-->>Client: chat completion
+```
+
+## Quick setup
+
+1. **Config** – Copy `config.example.yaml` to `config.yaml` and adjust. Every option can also be set via environment (see `.env.example`).
+
+2. **Env** – Copy `.env.example` to `.env` and set values. All options (`CONFIG_PATH`, `ACP_*`, `GATEWAY_*`) can be configured via env.
+
+   **Agent command (OpenCode vs Cursor)** – set `acp.command` in `config.yaml` or `ACP_COMMAND` as a JSON array of strings.
+
+   | Backend | `config.yaml` | Shell (env) |
+   |---------|---------------|-------------|
+   | OpenCode | `command: ["opencode", "acp"]` | `export ACP_COMMAND='["opencode","acp"]'` |
+   | Cursor Agent | `command: ["agent", "acp"]` | `export ACP_COMMAND='["agent","acp"]'` |
+
+   Use an absolute path if the binary is not on `PATH` (e.g. `["/home/you/.local/bin/agent","acp"]`). Cursor Agent must be installed and logged in (`agent login`) so the subprocess can reach your account.
+
+3. **Run** – Install the package (adds the **`acpbox`** CLI). The process manager is **uvicorn** (see `pyproject.toml`). Use **`gateway.workers`** in YAML or **`GATEWAY_WORKERS`** in the environment for process count (one ACP subprocess per worker). **`GATEWAY_THREADS`** is forwarded into **`uvicorn.run`** only if your installed uvicorn exposes a matching `threads=` argument (current releases usually do not; ASGI uses **asyncio** per process).
+
+```bash
+pip install .
+CONFIG_PATH=config.yaml acpbox
+# Or from a checkout without installing the script:
+pip install -r requirements.txt
+CONFIG_PATH=config.yaml python -m acpbox.main
+```
+
+Or with Docker Compose (reads `.env` and runs the **`acpbox`** service). Set **`AGENTS`** in `.env` for the image build (comma-separated `opencode`, `cursor`); the compose file passes it as a build-arg. After changing `AGENTS`, run `docker compose build --no-cache acpbox` so installers run again. Runtime **`ACP_COMMAND`** must match the installed binary (see Agent command table above). The image **CMD** is **`acpbox`** (uvicorn inside **`acpbox.main.run`**), with **`GATEWAY_WORKERS`** and **`GATEWAY_THREADS`** passed through the environment.
+
+4. **Use** – Point any OpenAI client at `http://localhost:8080/v1` (or your host/port). List models, call chat completions or responses; the gateway translates to ACP and back.
+
+## Tests
+
+Tests use a mock ACP over stdio (fake subprocess that responds with JSON-RPC). Route tests: `tests/test_models.py`, `tests/test_chat.py`, `tests/test_responses.py`, `tests/test_sessions.py`. Unit tests for mapping, errors, session_store, config, and stdio client in `tests/unit/`. Fixtures in `tests/conftest.py`.
+
+From repo root:
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## Adding your own ACP in Docker
+
+Build an image that includes **acpbox** and your ACP agent binary (e.g. `opencode acp`). Set `acp.command` and `acp.env` in config or `.env`. The server runs with **uvicorn** via **`acpbox`**; each worker starts one ACP process in lifespan. To run 8 ACP instances, set **`GATEWAY_WORKERS=8`** (or **`gateway.workers`** in YAML). See [docs/deployment.md](docs/deployment.md).
+
+## Specifications
+
+- [docs/spec.md](docs/spec.md) – This gateway: OpenAI HTTP API to Agent Client Protocol (stdio).
+- [OpenAI API OpenAPI spec](https://github.com/openai/openai-openapi/tree/manual_spec) – OpenAI REST API specification (OpenAPI).
+- [Agent Client Protocol](https://agentclientprotocol.com) – Protocol for agent-client communication over stdio (JSON-RPC); see `docs/agent-client-protocol/`.
+
+## License
+
+This project is licensed under the MIT License, see the [LICENSE](LICENSE) file in the repository root for details.

acpbox-0.1.1/README.md

@@ -0,0 +1,91 @@
+# ACPBox
+
+OpenAI-compatible HTTP API that acts as a **gateway to the Agent Client Protocol (ACP)**. Clients use the usual OpenAI endpoints (`/v1/models`, `/v1/chat/completions`, `/v1/responses`); the gateway runs the API with **uvicorn** and keeps **one ACP agent process per worker** over **stdio** (JSON-RPC), not HTTP.
+
+## Problem
+
+Many tools and SDKs expect an OpenAI-style API. ACP agents (e.g. [OpenCode](https://github.com/sst/opencode) via `opencode acp`, or **Cursor Agent** via `agent acp`) speak the [Agent Client Protocol](https://agentclientprotocol.com) over stdin/stdout. This gateway provides a single HTTP entry point: one base URL, OpenAI-shaped API, with one ACP binary instance per uvicorn worker.
+
+## How it works
+
+1. **Config** – YAML and env define the agent command, env vars, and **workspace** (`ACP_WORKSPACE`, default `./workspace`; Docker `/workspace`) passed as ACP `session/new` `cwd`.
+2. **One ACP process per worker** – The app runs under **uvicorn**. In lifespan each worker starts **one** ACP agent subprocess and keeps it for the worker's lifetime. With 8 workers you get 8 ACP binary instances. ACP uses **stdio** only (JSON-RPC, newline-delimited).
+3. **Reuse per request** – Each request in that worker uses the same process: `session/new` -> optional `session/set_mode` -> `session/prompt`, then the response is returned. The process is not terminated after each request.
+4. **Translation** – OpenAI requests are converted to ACP JSON-RPC; ACP content (e.g. `session/update` agent_message_chunk) is converted back to OpenAI chat/responses format.
+   - `GET /v1/models` – Uses the worker's ACP process: `initialize` (once) and `session/new`, returns **modes** (`modes.availableModes[].id`, e.g. OpenCode's `plan`, `build`) as the list of models.
+   - `POST /v1/chat/completions` – Uses the worker's ACP process; `model` selects the ACP mode. Reply as chat completion, or **Server-Sent Events** when `"stream": true` (OpenAI-style `chat.completion.chunk` lines and `data: [DONE]`). With `stream: false`, optional **`acp`** is `{ "steps": [ reasoning + command summaries ] }` (no raw chunks). With `stream: true`, each chunk may still carry raw **`acp`** from the wire (see `docs/api-mapping.md`).
+   - `POST /v1/responses` – Same; optional `chat_id` for client-side continuity (non-streaming only); **`acp.steps`** when present, like chat.
+
+See [docs/spec.md](docs/spec.md) and [docs/agent-client-protocol/docs/protocol/transports.mdx](docs/agent-client-protocol/docs/protocol/transports.mdx) for details.
+
+```mermaid
+sequenceDiagram
+    participant Client
+    participant Gateway
+    participant AgentProcess
+
+    Note over Gateway,AgentProcess: One ACP process per uvicorn worker (started in lifespan)
+    Client->>Gateway: GET /v1/models
+    Gateway->>AgentProcess: initialize, session/new (reuse process)
+    AgentProcess-->>Gateway: modes (e.g. plan, build)
+    Gateway-->>Client: list of models
+
+    Client->>Gateway: POST /v1/chat/completions
+    Gateway->>AgentProcess: session/new, session/prompt (same process)
+    AgentProcess-->>Gateway: session/update, session/prompt result
+    Gateway-->>Client: chat completion
+```
+
+## Quick setup
+
+1. **Config** – Copy `config.example.yaml` to `config.yaml` and adjust. Every option can also be set via environment (see `.env.example`).
+
+2. **Env** – Copy `.env.example` to `.env` and set values. All options (`CONFIG_PATH`, `ACP_*`, `GATEWAY_*`) can be configured via env.
+
+   **Agent command (OpenCode vs Cursor)** – set `acp.command` in `config.yaml` or `ACP_COMMAND` as a JSON array of strings.
+
+   | Backend | `config.yaml` | Shell (env) |
+   |---------|---------------|-------------|
+   | OpenCode | `command: ["opencode", "acp"]` | `export ACP_COMMAND='["opencode","acp"]'` |
+   | Cursor Agent | `command: ["agent", "acp"]` | `export ACP_COMMAND='["agent","acp"]'` |
+
+   Use an absolute path if the binary is not on `PATH` (e.g. `["/home/you/.local/bin/agent","acp"]`). Cursor Agent must be installed and logged in (`agent login`) so the subprocess can reach your account.
+
+3. **Run** – Install the package (adds the **`acpbox`** CLI). The process manager is **uvicorn** (see `pyproject.toml`). Use **`gateway.workers`** in YAML or **`GATEWAY_WORKERS`** in the environment for process count (one ACP subprocess per worker). **`GATEWAY_THREADS`** is forwarded into **`uvicorn.run`** only if your installed uvicorn exposes a matching `threads=` argument (current releases usually do not; ASGI uses **asyncio** per process).
+
+```bash
+pip install .
+CONFIG_PATH=config.yaml acpbox
+# Or from a checkout without installing the script:
+pip install -r requirements.txt
+CONFIG_PATH=config.yaml python -m acpbox.main
+```
+
+Or with Docker Compose (reads `.env` and runs the **`acpbox`** service). Set **`AGENTS`** in `.env` for the image build (comma-separated `opencode`, `cursor`); the compose file passes it as a build-arg. After changing `AGENTS`, run `docker compose build --no-cache acpbox` so installers run again. Runtime **`ACP_COMMAND`** must match the installed binary (see Agent command table above). The image **CMD** is **`acpbox`** (uvicorn inside **`acpbox.main.run`**), with **`GATEWAY_WORKERS`** and **`GATEWAY_THREADS`** passed through the environment.
+
+4. **Use** – Point any OpenAI client at `http://localhost:8080/v1` (or your host/port). List models, call chat completions or responses; the gateway translates to ACP and back.
+
+## Tests
+
+Tests use a mock ACP over stdio (fake subprocess that responds with JSON-RPC). Route tests: `tests/test_models.py`, `tests/test_chat.py`, `tests/test_responses.py`, `tests/test_sessions.py`. Unit tests for mapping, errors, session_store, config, and stdio client in `tests/unit/`. Fixtures in `tests/conftest.py`.
+
+From repo root:
+
+```bash
+pip install -e ".[dev]"
+pytest tests/ -v
+```
+
+## Adding your own ACP in Docker
+
+Build an image that includes **acpbox** and your ACP agent binary (e.g. `opencode acp`). Set `acp.command` and `acp.env` in config or `.env`. The server runs with **uvicorn** via **`acpbox`**; each worker starts one ACP process in lifespan. To run 8 ACP instances, set **`GATEWAY_WORKERS=8`** (or **`gateway.workers`** in YAML). See [docs/deployment.md](docs/deployment.md).
+
+## Specifications
+
+- [docs/spec.md](docs/spec.md) – This gateway: OpenAI HTTP API to Agent Client Protocol (stdio).
+- [OpenAI API OpenAPI spec](https://github.com/openai/openai-openapi/tree/manual_spec) – OpenAI REST API specification (OpenAPI).
+- [Agent Client Protocol](https://agentclientprotocol.com) – Protocol for agent-client communication over stdio (JSON-RPC); see `docs/agent-client-protocol/`.
+
+## License
+
+This project is licensed under the MIT License, see the [LICENSE](LICENSE) file in the repository root for details.

acpbox-0.1.1/acpbox/__init__.py

@@ -0,0 +1 @@
+# ACP OpenAI API Gateway