Add ACP WebSocket proxy backed by acpremote

[rgarcia]

Summary

• Add an opt-in /agent/v1/acp?harness=... WebSocket route backed by unmodified acpremote expose, plus configured-harness discovery.
• Start an independent bridge/agent process tree per attachment; terminate on disconnect and retain native session files for ACP load/resume. No runtime resource, conversation REST API, or delivery journal.
• Read a trusted, bounded launch catalog through AGENT_CONFIG_PATH. Keep internal listeners on loopback with per-connection bearer tokens and explicitly selected environment inheritance.
• Add opt-in message limits and downstream ping/pong to the existing WebSocket proxy without changing its defaults for other callers.
• Add real-process interoperability tests and install the pinned bridge/official client SDK in CI.

Validation

• Passed targeted Go race tests, including independent concurrent processes, multiple ACP sessions, abrupt disconnect during a prompt/permission, native history restoration, and shutdown cleanup.
• Passed 30 race repetitions of both targeted packages on the latest commit, including the abrupt-disconnect cases.
• Passed the full non-e2e Go race suite, targeted go vet, and generated-category consistency check. All PR checks pass, including image e2e tests and Bugbot (no findings).
• Passed the unmodified acpremote mirror CLI with the official ACP Python SDK.
• Passed unmodified ACP UI 0.1.16 (cd9c3cb464a4b321bff652101953a64c07473e31) locally: initialize, new session, output, permission approval, disconnect, and exact-session restoration in a fresh process. This used a deterministic peer, not a model. UI testing is not yet in CI.

Scope / remaining milestones

Disabled by default. The image does not yet install the bridge or harness binaries. The trusted bootstrap catalog is not the planned public declarative configuration/installer API; that API, real-harness capability/MCP/media verification, and enabled-image/platform-auth integration tests remain separate milestones. No real-provider calls or local Docker image e2e tests were run for this change.

Additional CLI interoperability checks

Tested released, unmodified Toad 0.6.20 and acpx 0.13.2 through acpremote 1.7.0 mirror against the deterministic peer (no model/provider calls).

• Toad's actual terminal UI: initialization, prompt output, interactive permission approval, and agent cleanup on disconnect passed. Saved-session restoration was not verified in this UI run.
• acpx: one-shot prompting and permission approval passed. Persistent-session restoration failed: mirror rejected session/resume with -32601 before it reached the WebSocket endpoint; acpx then created a replacement session while returning success. An idle TTL of one second forced fresh connections for this test.
• Adding mirror --unstable-protocol did not fix restoration. In acpremote 1.7.0 this flag configures the upstream connection, but _handle_mirror invokes the local run_agent(agent) without enabling unstable protocol routes. Python ACP SDK 0.11.0 rejects resume on that local router.
• Diagnostic only: using the same installed libraries with run_agent(connect_acp(url), use_unstable_protocol=True) made unmodified acpx resume the identical native session ID across fresh agent processes. No production code or installed client was changed.

The existing-client gate is therefore partial, not complete. Fix and pin the mirror's local-router protocol flag wiring before expanding harness support. These manual CLI checks are not yet in CI.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	pypi/​websockets@​15.0.1
	pypi/​acpremote@​1.7.0
	pypi/​agent-client-protocol@​0.11.0

View full report