Add the Pi reference runtime and ACP WebSocket API

[rgarcia]

Summary

• Add a protocol-transparent ACP WebSocket endpoint backed by connection-owned acpremote expose processes. Disconnect terminates the agent; native session storage remains available for discovery/load.
• Bundle Pi 0.83.0, pi-acp 0.0.33 and pi-mcp-adapter 2.32.1 in both browser images, with pinned bridge/Python/Bun dependencies and a runtime Bun lockfile.
• Implement Pi configuration GET/PUT with optimistic revisions, package preparation, atomic activation, safe credential bindings and last-ready retention on failure. Existing connections are not restarted when configuration changes.
• Support shared MCP defaults and standard session-supplied MCP overrides through a guarded Pi adapter patch. The Go proxy does not interpret ACP messages.

API and configuration

Endpoint	Behavior
GET /agent/v1/harnesses	Configured harness discovery
GET /agent/v1/harnesses/pi/config	Desired/effective configuration, preparation status and ETag
PUT /agent/v1/harnesses/pi/config	Prepare and activate a configuration; requires If-Match
WebSocket /agent/v1/acp?harness=pi	Ordinary ACP initialization, sessions, prompts, permissions and cancellation

launch configures provider, model, thinking and an operator-defined credential binding. shared configures exact-version npm extension packages and MCP servers. Session-supplied MCP definitions override shared defaults by name without writing shared files. Credential values are resolved from explicitly bound environment variables, not returned by GET or passed into preparation.

Prepared configuration activates through one symlink switch. Native session files and adapter mappings live outside replaced revisions. Shared files remain shared; existing processes are not promised complete revision isolation. The README documents the schema, failure behavior, operator setup and adapter boundary.

Validation

• Passed 10 race repetitions of agentproxy/wsproxy, the full non-e2e Go race suite, go vet ./..., and generated-category consistency checks. Added empty-PATH tests for configured Node/Bun execution and executable wrapper mode; Bugbot's path finding is fixed and its latest review reports no issues.
• Built and ran the headless image. The included opt-in real-provider gate passed using OpenRouter GLM 5.3: independent connections, shared/session-overridden MCP tools, configuration updates while connected, failed-package preparation retaining the ready revision, disconnect cleanup, and fresh-process list/load/history plus model recall.
• Tested real npm-compatible fixture package installation with the pinned runtime; an extension that throws during initialization cannot replace a working revision. Unit tests also cover concurrency, restart recovery, validation and private configuration responses/files.
• The bridge's official ACP SDK/acpremote mirror tests pass. Earlier unmodified ACP UI and Toad checks passed prompting/permissions; their session-picker behavior is distinct from the protocol gate.
• Local headful-image/media testing was not performed. CI builds both image variants and runs the existing image e2e suite. The paid-provider gate is opt-in, not an automatic CI test.

Scope and limitations

• Pi is the packaged reference. The headless image adds approximately 393 MB of uncompressed runtime/Bun layers. Other harnesses still require their own installers/configuration adapters. Gemini's planned support excludes previous-session discovery/load because its tested native ACP implementation lacks session/list.
• The required reconnect path is initialize → list → load; resume is optional. acpremote 1.7.0 mirror currently rejects resume on its local router, and acpx can respond by creating a replacement session. No new Kernel protocol works around that client/bridge behavior.
• Extensions are trusted executable code; install scripts and automatic project executable-resource trust are disabled. Configuration activation cannot roll back arbitrary extension side effects. Successful revisions are retained for existing processes, so repeated installations consume disk space; automatic GC is not implemented.
• Readiness means configuration/software preparation, not authenticated provider or remote MCP health. HTTP/SSE MCP interoperability, interactive OAuth, media and platform gateway/TLS integration require further work. There is no lossless event replay, interrupted-turn guarantee or exactly-once tool execution.

[socket-security]

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

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	npm/​@​earendil-works/​pi-coding-agent@​0.83.0
	npm/​pi-acp@​0.0.33
	pypi/​websockets@​15.0.1
	npm/​pi-mcp-adapter@​2.32.1
	pypi/​acpremote@​1.7.0
	pypi/​agent-client-protocol@​0.11.0

View full report

[socket-security]

Warning

Review the following alerts detected in dependencies.

According to your organization's Security Policy, it is recommended to resolve "Warn" alerts. Learn more about Socket for GitHub.

Action	Severity	Alert  (click "▶" to expand/collapse)
Warn		Obfuscated code: npm @protobufjs/float is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: server/runtime/acp/pi/package.json → npm/@earendil-works/pi-coding-agent@0.83.0 → npm/pi-mcp-adapter@2.32.1 → npm/@protobufjs/float@1.0.2 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/@protobufjs/float@1.0.2. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.
Warn		Obfuscated code: npm highlight.js is 90.0% likely obfuscated Confidence: 0.90 Location: Package overview From: server/runtime/acp/pi/package.json → npm/@earendil-works/pi-coding-agent@0.83.0 → npm/highlight.js@10.7.3 ℹ Read more on: This package | This alert | What is obfuscated code? Next steps: Take a moment to review the security alert above. Review the linked package source code to understand the potential risk. Ensure the package is not malicious before proceeding. If you're unsure how to proceed, reach out to your security team or ask the Socket team for help at support@socket.dev. Suggestion: Packages should not obfuscate their code. Consider not using packages with obfuscated code. Mark the package as acceptable risk. To ignore this alert only in this pull request, reply with the comment @SocketSecurity ignore npm/highlight.js@10.7.3. You can also ignore all packages with @SocketSecurity ignore-all. To ignore an alert for all future pull requests, use Socket's Dashboard to change the triage state of this alert.

View full report

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 49f8b2f. Configure here.}