feat(acp): add opt-in Coven runtime bridge

Add the opt-in Coven ACP runtime bridge as a bundled extension while keeping ACPX as the default path.

Security hardening included before merge:
- fail closed by default instead of silently falling back;
- bounded health/socket requests and daemon response sizes;
- fixed Coven socket trust anchor and symlink/path validation;
- reject untrusted harness/session/event ids before exposing them;
- sanitize daemon-controlled terminal/status/error strings;
- use incremental event polling with bounded dedupe state;
- clean up launched Coven sessions before fallback when daemon ids are invalid.

Validation:
- pnpm test extensions/coven/src/config.test.ts extensions/coven/src/client.test.ts extensions/coven/src/runtime.test.ts
- pnpm check:changed
- GitHub CI green on a64eac20b9
- Greptile Review green
This commit is contained in:
Val Alexander
2026-04-27 12:22:29 -05:00
committed by GitHub
parent fd6e1c089b
commit fc8ccde542
15 changed files with 2765 additions and 7 deletions

View File

@@ -186,6 +186,77 @@ Override the command or version in plugin config:
See [Plugins](/tools/plugin).
## Optional Coven backend
OpenClaw can also register a bundled, opt-in `coven` ACP backend for operators
who want ACP coding sessions supervised by a local [Coven](https://github.com/OpenCoven/coven)
daemon instead of launched directly through ACPX.
This is intentionally an extension, not a core runtime path:
- the default ACPX backend stays unchanged for normal installs;
- Coven has its own daemon, socket, session store, harness mapping, and project
boundary model;
- the bridge can be enabled, disabled, configured, and reviewed independently
through the plugin system; and
- OpenClaw remains responsible for ACP session routing, chat bindings, task
state, and fallback policy while Coven owns harness supervision.
Minimal opt-in config:
```json5
{
acp: {
enabled: true,
backend: "coven",
defaultAgent: "codex",
},
plugins: {
entries: {
coven: {
enabled: true,
config: {
// Optional. Defaults to ~/.coven. Environment variables are not used for this trust anchor.
covenHome: "~/.coven",
// Optional. Defaults to <covenHome>/coven.sock; overrides must resolve to that path.
socketPath: "~/.coven/coven.sock",
// Optional. Defaults to false; enable only when direct ACP fallback is acceptable.
allowFallback: false,
// Optional. Used only when allowFallback is true.
fallbackBackend: "acpx",
},
},
},
},
}
```
When selected, OpenClaw checks Coven daemon health over the configured Unix
socket before launching. A successful launch creates a Coven session and records
the Coven session id in the ACP runtime handle. If the health check or launch
fails, OpenClaw fails closed by default so `acp.backend="coven"` cannot silently
downgrade to direct ACP execution. Set `allowFallback: true` only when direct
ACP fallback is an explicit, acceptable operator choice.
For path safety, `~` in `covenHome` and `socketPath` expands to the current
user home directory, and configured Coven paths must be absolute after that
expansion. OpenClaw rejects workspace-relative Coven daemon paths because the
daemon socket is a local user trust anchor, not repository-controlled state.
`socketPath` must resolve to `<covenHome>/coven.sock`; OpenClaw does not allow
arbitrary Coven socket filenames because the daemon socket is the local trust
anchor. Keep `covenHome` owned by the OpenClaw user and private (`0700`);
OpenClaw rejects symlinked, shared-accessible, shared-writable, or non-socket
Coven socket paths before connecting. The Coven backend currently requires Unix
socket validation and fails closed on Windows rather than trusting a socket path
whose owner and permissions cannot be validated by this plugin.
The default harness mapping sends known ACP agent ids such as `codex`, `claude`,
`gemini`, and `opencode` to explicitly authorized Coven harness ids. Unknown
ACP agent ids are rejected instead of being forwarded as harness names. Override
`plugins.entries.coven.config.harnesses` only when your local Coven install uses
custom harness names, and keep `acp.allowedAgents` aligned with the intended
chat-exposed harness set.
### Automatic dependency install
When you install OpenClaw globally with `npm install -g openclaw`, the acpx