Metadata-Version: 2.4
Name: acpremote
Version: 0.8.2
Summary: Generic remote WebSocket transport for ACP agents and clients.
Project-URL: Homepage, https://vcoderun.github.io/acpkit/acpremote/
Project-URL: Issues, https://github.com/vcoderun/acpkit/issues
Project-URL: Repository, https://github.com/vcoderun/acpkit
License: Apache 2.0
Requires-Python: >=3.11
Requires-Dist: agent-client-protocol>=0.9.0
Requires-Dist: typing-extensions>=4.12.0
Requires-Dist: websockets>=16.0
Provides-Extra: perf
Requires-Dist: uvloop>=0.21.0; (platform_system != 'Windows') and extra == 'perf'
Description-Content-Type: text/markdown

# acpremote

`acpremote` is the generic remote transport package for ACP.

It exposes any existing `acp.interfaces.Agent` over WebSocket and can also turn a remote ACP server
back into a local ACP agent proxy. It can also mirror any stdio ACP command by spawning it as a
child process.

Note: Used 0.8.2 as initial release for compatibility with acpkit monorepo. This is an early release and might have issues.

Docs:

- <https://vcoderun.github.io/acpkit/acpremote/> (INACTIVE)

Install:

```bash
uv add acpremote
```

```bash
pip install acpremote
```

## Server

Expose any ACP agent:

```python
from acpremote import serve_acp

server = await serve_acp(agent=my_acp_agent, host='127.0.0.1', port=8080)
await server.serve_forever()
```

Expose a stdio ACP command instead of an in-memory agent:

```python
from acpremote import serve_command

server = await serve_command(
    ['npx', '@zed-industries/codex-acp'],
    host='127.0.0.1',
    port=8080,
)
await server.serve_forever()
```

`env={...}` overrides selected variables while inheriting the parent process environment. That
keeps command lookup through `PATH` intact while still letting the caller inject tokens or runtime
flags.

Default routes:

- metadata: `http://127.0.0.1:8080/acp`
- health: `http://127.0.0.1:8080/healthz`
- websocket: `ws://127.0.0.1:8080/acp/ws`

## Client Proxy

Turn a remote ACP endpoint back into a local ACP agent:

```python
from acp import run_agent
from acpremote import connect_acp

agent = connect_acp('ws://127.0.0.1:8080/acp/ws')
await run_agent(agent)
```

That pattern is what powers a local stdio ACP façade in front of a remote ACP server.

## Transport Timing

`TransportOptions` can attach proxy-observed latency information to the ACP stream:

```python
from acpremote import TransportOptions, connect_acp

agent = connect_acp(
    'ws://127.0.0.1:8080/acp/ws',
    options=TransportOptions(
        emit_latency_meta=True,
        emit_latency_projection=True,
    ),
)
```

Available signals:

- streamed updates can carry `field_meta["acpremote"]["transport_latency"]`
- a visible `Transport Latency` ACP card can be emitted after each prompt turn

The metrics are proxy-observed timings, not synchronized end-to-end host clock measurements.

## Transport Notes

Current transport behavior:

- one WebSocket text message carries one ACP JSON message
- binary frames are rejected
- bearer-token auth is supported
- stdio ACP commands can be mirrored with `serve_command(...)`
- transport limits are configurable through `TransportOptions`

This package is transport-focused. It doesn't assume ACP Kit adapters or ACP Kit-owned runtime
semantics.
