acp-gateway 0.1.0__tar.gz

acp_gateway-0.1.0/.dockerignore

@@ -0,0 +1,9 @@
+**
+!pyproject.toml
+!uv.lock
+!README.md
+!LICENSE
+!src/
+!src/**
+src/**/__pycache__/
+src/**/*.pyc

acp_gateway-0.1.0/.env.example

@@ -0,0 +1,12 @@
+# Secrets only. Copy to .env (ignored by git), restrict access: chmod 600 .env
+# Names are referenced from config.yaml (secret_env, api_token_env, mcp_token_env).
+
+# Same value as GOOSE_SERVER__SECRET_KEY on the agent side
+AGENT_WORK_SECRET=
+
+# Bearer tokens for the local HTTP API and MCP endpoint
+ACPGW_API_TOKEN=
+ACPGW_MCP_TOKEN=
+
+# Separate Telegram bot for the gateway
+TELEGRAM_BOT_TOKEN=

acp_gateway-0.1.0/.gitattributes

@@ -0,0 +1,3 @@
+* text=auto eol=lf
+*.ps1 text eol=crlf
+*.cmd text eol=crlf

acp_gateway-0.1.0/.githooks/pre-commit

@@ -0,0 +1,6 @@
+#!/bin/sh
+# Enabled with: git config core.hooksPath .githooks
+set -e
+uv run --frozen python scripts/check_secrets.py --staged
+uv run --frozen ruff check
+uv run --frozen ruff format --check

acp_gateway-0.1.0/.github/workflows/linux-binary.yml

@@ -0,0 +1,105 @@
+name: Platform release checks
+
+on:
+  workflow_dispatch:
+    inputs:
+      publish_image:
+        description: 'Publish the tested Docker image to GHCR (manual release)'
+        required: false
+        type: boolean
+        default: false
+
+permissions:
+  contents: read
+
+jobs:
+  publish-image:
+    if: ${{ inputs.publish_image }}
+    needs: [build, native]
+    runs-on: ubuntu-22.04
+    timeout-minutes: 15
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          python-version: '3.12'
+      - run: uv sync --frozen
+      - name: Select versioned image
+        run: |
+          release_version=$(uv run --frozen python -c 'from acp_gateway import __version__; print(__version__)')
+          echo "ACPGW_RELEASE_IMAGE=ghcr.io/${GITHUB_REPOSITORY,,}:$release_version" >> "$GITHUB_ENV"
+      - run: docker build -t "$ACPGW_RELEASE_IMAGE" .
+      - run: uv run --frozen python scripts/smoke_docker.py --image "$ACPGW_RELEASE_IMAGE"
+      - name: Publish tested image
+        env:
+          GHCR_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          printf '%s' "$GHCR_TOKEN" | docker login ghcr.io --username "$GITHUB_ACTOR" --password-stdin
+          if docker manifest inspect "$ACPGW_RELEASE_IMAGE" >/dev/null 2>&1; then
+            echo 'Version tag already exists; increment the package version instead of replacing it.' >&2
+            exit 1
+          fi
+          docker push "$ACPGW_RELEASE_IMAGE"
+      - name: Clear registry credentials
+        if: ${{ always() }}
+        run: docker logout ghcr.io
+  native:
+    strategy:
+      fail-fast: false
+      matrix:
+        runner: [windows-2025, macos-15, macos-15-intel, ubuntu-24.04-arm]
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          python-version: '3.12'
+      - run: uv sync --frozen --group build
+      - run: uv build --wheel --out-dir dist/native
+      - run: uv run --frozen --group build python scripts/build_binary.py
+      - run: uv run --frozen python scripts/smoke_platform.py --wheel-dir dist/native --built-binary
+      - uses: actions/upload-artifact@v4
+        with:
+          name: acpgw-${{ matrix.runner }}
+          path: |
+            dist/*.tar.gz
+            dist/*.sha256
+            dist/*.build.json
+          if-no-files-found: error
+  build:
+    runs-on: ubuntu-22.04
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          python-version: '3.12'
+      - run: uv sync --frozen --group build
+      - run: uv run --frozen ruff check
+      - run: uv run --frozen ruff format --check
+      - run: uv run --frozen pytest
+      - run: uv run --frozen --group build python scripts/build_binary.py
+      - run: uv run --frozen python scripts/smoke_binary.py dist/acpgw-linux-x86_64/acpgw
+      - run: uv run --frozen python scripts/smoke_connector.py dist/acpgw-linux-x86_64/acpgw
+      - name: Check executable in Ubuntu without Python
+        run: >-
+          uv run --frozen python scripts/smoke_binary.py
+          dist/acpgw-linux-x86_64/acpgw --container-image ubuntu:22.04
+      - uses: actions/upload-artifact@v4
+        with:
+          name: acpgw-linux-x86_64
+          path: |
+            dist/*.tar.gz
+            dist/*.sha256
+            dist/*.build.json
+          if-no-files-found: error

acp_gateway-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Secrets — never commit
+.env
+.env.*
+!.env.example
+config.yaml
+*.pem
+*.key
+
+# Runtime data
+data/
+*.db
+*.db-journal
+*.db-wal
+*.db-shm
+*.log
+
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+build/
+dist/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Editors / OS
+.idea/
+.vscode/
+.DS_Store
+Thumbs.db
+
+# ACP spike output (may contain work data)
+spike-runs/
+
+# Private VPS deployment configuration, credentials and persistent state
+deploy/docker/runtime/
+deploy/docker/state/

acp_gateway-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

acp_gateway-0.1.0/Dockerfile

@@ -0,0 +1,19 @@
+FROM ghcr.io/astral-sh/uv:0.7.6 AS uv
+FROM python:3.12-slim-bookworm AS build
+COPY --from=uv /uv /usr/local/bin/uv
+WORKDIR /app
+ENV UV_LINK_MODE=copy UV_PYTHON_DOWNLOADS=never
+COPY pyproject.toml uv.lock README.md LICENSE ./
+COPY src ./src
+RUN uv sync --frozen --no-dev --no-editable
+
+FROM python:3.12-slim-bookworm AS runtime
+RUN groupadd --gid 10001 acpgw && useradd --uid 10001 --gid acpgw --create-home acpgw \
+    && mkdir /data /config && chown acpgw:acpgw /data /config
+COPY --from=build /app/.venv /app/.venv
+ENV PATH=/app/.venv/bin:$PATH PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1 \
+    XDG_DATA_HOME=/data
+USER 10001:10001
+WORKDIR /data
+ENTRYPOINT ["acpgw", "--config", "/config/gateway.yaml", "--env-file", "/config/gateway.env"]
+CMD ["serve"]

acp_gateway-0.1.0/LICENSE

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

acp_gateway-0.1.0/PKG-INFO

@@ -0,0 +1,309 @@
+Metadata-Version: 2.5
+Name: acp-gateway
+Version: 0.1.0
+Summary: Local gateway that routes messages from external channels (Hermes, Telegram, ...) to ACP agents
+Project-URL: Homepage, https://github.com/Lujker/acp-gateway
+Project-URL: Repository, https://github.com/Lujker/acp-gateway
+Project-URL: Issues, https://github.com/Lujker/acp-gateway/issues
+Author: Lujker
+License-Expression: MIT
+License-File: LICENSE
+Keywords: acp,agent-client-protocol,gateway,goose,hermes,mcp,telegram
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Requires-Dist: agent-client-protocol[http]>=0.12
+Requires-Dist: aiogram<4,>=3.22
+Requires-Dist: fastapi>=0.115
+Requires-Dist: filelock>=3.16
+Requires-Dist: httpx>=0.28
+Requires-Dist: mcp<2,>=1.20
+Requires-Dist: packaging>=24
+Requires-Dist: platformdirs>=4.3
+Requires-Dist: pydantic-settings[yaml]>=2.8
+Requires-Dist: pydantic>=2.10
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: structlog>=25.1
+Requires-Dist: uvicorn>=0.34
+Requires-Dist: websockets>=15
+Description-Content-Type: text/markdown
+
+# ACP Gateway
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)
+![Status: early development](https://img.shields.io/badge/status-early%20development-orange.svg)
+[![ACP](https://img.shields.io/badge/protocol-Agent%20Client%20Protocol-6f42c1.svg)](https://agentclientprotocol.com)
+
+**ACP Gateway** is a local gateway that lets chat channels and other agents —
+Hermes, Telegram, later XMPP, e-mail and a web UI — talk to a remote
+[Agent Client Protocol](https://agentclientprotocol.com) agent such as
+[goose](https://github.com/aaif-goose/goose). It delivers messages to the
+agent and returns answers and tool-approval requests to the channels, with a
+human in the loop for every risky action.
+
+The first target is **Work Goose**: `goose serve` on a work laptop. Work MCP
+servers, credentials, files and the model stay on that machine; the gateway
+only knows the agent's address, a shared secret and the fingerprint of its TLS
+certificate.
+
+```mermaid
+flowchart LR
+    subgraph home["Home host (WSL)"]
+        hermes["Hermes"] -- MCP --> gw
+        tg["Telegram"] --> gw
+        cli["CLI / Web UI"] -- HTTP --> gw
+        gw["ACP Gateway<br/>sessions · approvals · policy · audit"]
+    end
+    subgraph work["Work laptop (WSL)"]
+        goose["goose serve<br/>MCP · files · model"]
+    end
+    gw -- "ACP over WebSocket<br/>TLS pinning + X-Secret-Key" --> goose
+    desktop["Goose Desktop"] -. direct .-> goose
+```
+
+## Status
+
+Early development. The foundation is done: the connection to a real goose
+1.53.0 over the LAN is verified, along with sessions, approvals, cancellation
+and session restore. The daemon, local HTTP/SSE API and human CLI channel are
+implemented and verified against Work Goose. The Hermes MCP facade is implemented
+and checked with Hermes' installed MCP module against the recorded Goose mock.
+Linux/WSL service lifecycle and Telegram commands/approval buttons are implemented;
+actual reboot and the live human Telegram acceptance remain pending. Connector
+development includes local computer enrollment and a guarded WS/WSS ACP relay
+in `serve`, tested against the recorded agent mock. Live acceptance is next. The plan
+and the work queue are in [`road-map.md`](road-map.md) (in Russian).
+
+| Area | State |
+|---|---|
+| Scaffold, config, secret redaction, pre-commit hook | ✅ |
+| ACP over WebSocket with TLS pinning, verified on goose 1.53.0 | ✅ |
+| Agent client (`acp_gateway.agents`) and recorded-traffic mock agent | ✅ `P1.1`, `P1.2` |
+| Core: sessions in SQLite, jobs, event bus, channel contract | ✅ `P1.3` |
+| Approvals: human routing, deadlines, audit; core policy limits | ✅ `P1.4` |
+| Daemon, local API, approvals from the CLI | ✅ `P1.5` |
+| Hermes MCP facade; actions approved through the CLI | ✅ `P2.1`, `P2.2` (Hermes MCP module + mock agent) |
+| Checkout installer, setup, Linux/WSL service CLI, standalone Linux binary recipe | Binary, real user-service/crash recovery and Windows task lifecycle verified; actual reboot pending |
+| Telegram | Commands, private user allowlist and audited approval buttons implemented; live acceptance pending |
+| Runtime diagnostics | Component health/probes, private rotated JSON logs and Telegram throttling/recovery implemented |
+| [VPS connector](docs/items/connector.md) | ACP relay, Linux/WSL services and route diagnostics implemented; two-computer isolation/approvals/history mock-tested; live acceptance next |
+| Snikket/XMPP, e-mail, web UI | 🗓 `P4` |
+
+## Principles
+
+- **The agent executes, the gateway relays.** The gateway makes no decisions
+  for the agent and stores no work MCP credentials.
+- **A human approves.** Agent actions are approved in a channel with a live
+  human (CLI, Telegram). LLM channels, Hermes included, never get an "allow"
+  button. With no approver connected, the action is rejected.
+- **Secure by default.** The local API listens on loopback only. Unencrypted
+  transport to an agent is allowed only on loopback. The secret is sent only
+  after the pinned certificate is verified. ACP client capabilities (`fs`,
+  `terminal`) are disabled. Secrets are masked in logs and kept out of git.
+- **Channels are thin adapters.** A new channel implements a shared contract
+  and does not touch the core.
+
+More in [`docs/architecture.md`](docs/architecture.md).
+
+## Quick start
+
+For a VPS in Docker, two outgoing Linux/WSL connectors and Telegram, follow
+the [live acceptance runbook](docs/setup/vps-acceptance.md)
+([на русском](docs/setup/vps-acceptance.ru.md)). It starts with
+an IP/port route and then adds an exact WSS path through its own nginx without
+publishing the owner API or changing other application services.
+
+For installation without a checkout, use the wheel/deployment bundle described
+in [installation and updates](docs/setup/distribution.md). Public PyPI/registry
+publication is a separate manual release step. Internal maintenance commands
+for uv installations are `acpgw version`, `update`, `update --status`,
+`update --rollback` and `uninstall`. Updates take a private recovery snapshot
+and restore it on installation/health-check failure. Native Windows queues
+internal maintenance after the CLI exits; its PowerShell installer waits for
+the verified result. See the installation guide before rolling back a database.
+
+For the separate Git/development path, you need [uv](https://docs.astral.sh/uv/) and git; uv installs Python 3.12
+itself. Linux/WSL is the primary platform. Native Windows x86_64, macOS Intel/ARM64
+and Linux ARM64 have wheel lifecycle and binary CLI checks; native Windows/macOS
+services and full agent acceptance remain separate milestones.
+
+```bash
+git clone --branch v0.1.0 https://github.com/Lujker/acp-gateway.git
+cd acp-gateway
+uv sync --frozen
+```
+
+For an installed `acpgw` command outside the checkout, run
+`sh scripts/install.sh`, then configure the files created by `acpgw setup`.
+The installer keeps existing configuration and tokens. Installation and
+service commands: [`docs/setup/service.md`](docs/setup/service.md).
+
+Use a published, reviewed tag as above; before the first release, select the
+reviewed branch or commit explicitly. For development, create a working branch
+from that checkout.
+
+To build a standalone executable with no Python required on the runtime
+host, use `uv run --frozen --group build python scripts/build_binary.py`.
+Build artifacts, checksums, compatibility limits and installation:
+[`docs/setup/binary.md`](docs/setup/binary.md).
+Build locally and attach archives/checksums to a manually created GitHub
+release. The optional GitHub Actions build runs only on explicit manual
+dispatch; pushes, PRs, tags and releases do not consume build minutes.
+
+Telegram setup and human approvals: [`docs/setup/telegram.md`](docs/setup/telegram.md).
+Health probes and rotating logs: [`docs/setup/observability.md`](docs/setup/observability.md).
+
+### 1. Prepare the agent
+
+On the agent machine, run `goose serve` with TLS and a secret and open the
+port to the LAN. Step by step, including the Hyper-V firewall rule for WSL:
+[`docs/setup/work-goose.md`](docs/setup/work-goose.md).
+
+```bash
+GOOSE_SERVER__SECRET_KEY='<long random secret>' \
+goose serve --host 0.0.0.0 --port 3284 --tls
+# note the GOOSED_CERT_FINGERPRINT=... line
+```
+
+### 2. Configure the gateway
+
+```bash
+cp config.example.yaml config.yaml      # agents, policy, logging
+cp .env.example .env && chmod 600 .env  # secrets only
+```
+
+Set the agent address and certificate fingerprint in `config.yaml`:
+
+```yaml
+agents:
+  - alias: work
+    title: Work Goose
+    kind: goose
+    url: https://<agent-address>:3284   # /acp is appended automatically
+    secret_env: AGENT_WORK_SECRET
+    tls_fingerprint: "<GOOSED_CERT_FINGERPRINT>"   # empty = trust on first use
+    default_cwd: /home/<user>
+```
+
+In `.env`: `AGENT_WORK_SECRET=<the same secret>`.
+Also set `ACPGW_API_TOKEN` to a separate random owner token. It must differ
+from the agent secret and `ACPGW_MCP_TOKEN` (if configured).
+
+### 3. Check the connection
+
+```bash
+uv run acpgw config check                        # config is valid, secrets are present
+uv run python scripts/spike_acp.py init          # TLS + ACP handshake
+uv run python scripts/spike_acp.py ping          # a short request to the agent
+```
+
+The spike script has more scenarios: `modes`, `permission`, `cancel`, `load`,
+`all`. Traffic is recorded to `spike-runs/` (git-ignored). The scenarios
+`permission --permission allow` and `cancel` run harmless `echo` and `sleep`
+commands on the agent machine.
+
+### 4. Start the daemon and use the CLI
+
+```bash
+uv run acpgw serve                           # keep this terminal open
+```
+
+In another terminal:
+
+```bash
+uv run acpgw status
+uv run acpgw ask "Remember the code word AMBER. Answer only OK."
+uv run acpgw ask "What was the code word?"    # same active session
+uv run acpgw sessions
+uv run acpgw new                             # start a fresh session
+uv run acpgw switch 1                        # gateway session row id from sessions
+```
+
+For actions that need approval, keep a third terminal connected:
+
+```bash
+uv run acpgw approvals watch                 # allow once, reject, or skip interactively
+```
+
+The daemon alone does not count as a connected human. With no approval
+watcher, requests are rejected. `acpgw approvals` lists pending requests;
+`acpgw approvals approve <id>` and `reject <id>` decide an existing request
+once. Long jobs can be submitted with `ask --no-stream`, retrieved with
+`result <job_id> --wait 30`, and cancelled with `stop`. Ctrl+C during a
+streaming `ask` requests cancellation of that job.
+
+The CLI reads the same config and secrets as the daemon. Details and the
+HTTP/SSE contract: [`docs/setup/gateway.md`](docs/setup/gateway.md).
+
+### 5. Connect Hermes
+
+Set a separate `ACPGW_MCP_TOKEN`, restart the daemon and add its `/mcp` URL
+and bearer header to Hermes' `mcp_servers`. The six tools for each agent
+support sessions, explicit threads, asynchronous jobs and cancellation.
+Actions still require a human in `acpgw approvals watch`.
+Configuration, tool arguments and compatibility checks:
+[`docs/setup/hermes.md`](docs/setup/hermes.md).
+
+### 6. Manage autostart on Linux/WSL
+
+```bash
+acpgw service install   # install/update the user unit using the selected config
+acpgw service enable    # enable autostart and start now
+acpgw service status    # service state, including when the daemon is stopped
+acpgw service disable   # disable autostart and stop now
+acpgw service --help    # start, stop, restart and uninstall too
+```
+
+WSL also needs a Windows logon task and a user manager that starts with the
+distro. Instructions and the remaining reboot check:
+[`docs/setup/service.md`](docs/setup/service.md).
+
+## Configuration
+
+| Source | Contents |
+|---|---|
+| `config.yaml` (`--config`, `ACPGW_CONFIG`, `./`, platform config dir) | structure: `gateway`, `agents`, `policy`, `logging` |
+| `ACPGW_<SECTION>__<FIELD>` variables | overrides, e.g. `ACPGW_LOGGING__LEVEL=DEBUG` |
+| `.env` (`--env-file`, `ACPGW_ENV_FILE`, `./`, config dir) | **secrets only**, referenced by name (`secret_env`) |
+
+`uv run acpgw paths` shows the config, data and log directories on the
+current platform.
+
+## Development
+
+```bash
+uv sync                                  # environment and dependencies
+git config core.hooksPath .githooks      # pre-commit: secret scan + ruff
+uv run pytest                            # unit + integration tests
+uv run ruff check && uv run ruff format --check
+```
+
+Integration tests start a mock goose (`tests/fakes/fake_goose.py`) whose
+messages come from real goose 1.53.0 recordings in `tests/fixtures/acp/`; it
+covers TLS, the secret, session modes, approvals, cancellation, session
+loading and restarts. New recordings are cleaned with
+`scripts/sanitize_fixture.py` before committing.
+
+The development plan lives in [`road-map.md`](road-map.md) (statuses and
+queue) and [`road-notes.md`](road-notes.md) (decisions and findings); both are
+kept in Russian.
+
+## Layout
+
+```text
+src/acp_gateway/   ACP client, core, SQLite storage, daemon, HTTP/SSE API, CLI, channels
+scripts/           spike_acp.py (agent check), check_secrets.py (hook), sanitize_fixture.py
+tests/             unit, integration, fakes, fixtures/acp
+docs/              architecture.md, setup/, archive/
+```
+
+## License
+
+[MIT](LICENSE)