489a287d6f
Wires the ACP runtime plugin into the published CLI (RUNTIME_PLUGIN_IDS in tsup.config) and the on-demand BUILTIN_PLUGINS catalog (experimental), matching the untrusted-subprocess security posture. Adds the Risk S1 default-policy safety: an acpAllowUnrestricted acknowledgement (default false) — without it, a blanket allow on a sensitive category is escalated to approval rather than auto-approved under the allow-all default policy, applied in both the permission floor and fs write gating. Adds docs/acp-contract.md (launch/readiness + failure taxonomy), a README with the AGENTS.md-required upstream evidence (SDK repo/docs/release/integrity), a bundle-output test for the staged plugin, and a @runfusion/fusion minor changeset. Package green at 179 tests. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
67 lines
3.7 KiB
Markdown
67 lines
3.7 KiB
Markdown
# @fusion-plugin-examples/acp-runtime
|
|
|
|
A Fusion runtime plugin that drives **any** external [Agent Client Protocol
|
|
(ACP)](https://agentclientprotocol.com) agent over JSON-RPC/stdio. One
|
|
integration unlocks every ACP-compatible agent (Gemini CLI, the Claude Code ACP
|
|
adapter, and any future agent that speaks the protocol) through the standard
|
|
protocol instead of a bespoke per-CLI integration.
|
|
|
|
Selected via `runtimeId: "acp"`. Installed on demand (`experimental`) — see the
|
|
Fusion plugin catalog (`fn plugin install fusion-plugin-acp-runtime`).
|
|
|
|
## Security posture
|
|
|
|
The ACP agent is an **untrusted subprocess** that calls back into Fusion for
|
|
permissions and filesystem access. This plugin enforces a defense-in-depth floor:
|
|
|
|
- **Per-category permission gating.** Each `session/request_permission` is
|
|
classified by tool kind into a Fusion action category and checked against the
|
|
live permission policy — never a preset shortcut. `allow_once` only (never a
|
|
persisted blanket grant). Unmappable kinds and missing policy default-deny.
|
|
- **Unrestricted-risk acknowledgement (`acpAllowUnrestricted`).** Because the
|
|
shipped default policy is `unrestricted` (allow-all), a blanket `allow` on a
|
|
*sensitive* category is escalated to approval unless the user explicitly sets
|
|
`acpAllowUnrestricted: true`. Prefer running the ACP runtime under an
|
|
`approval-required` policy.
|
|
- **Filesystem jail.** `fs/read_text_file` / `fs/write_text_file` are opt-in
|
|
(`acpFsRead` / `acpFsWrite`, writes default OFF), confined to the session
|
|
`cwd` by a real symlink-resolving jail (realpath + `O_NOFOLLOW`), with a
|
|
deny-list for secrets (`.env`, `*.pem`, …) and git internals (`.git/**`).
|
|
Writes are gated through the `file_write_delete` permission category.
|
|
- **Untrusted-input bounds.** Streamed output is sanitized (ANSI/control strip)
|
|
and bounded (per-turn + per-chunk caps; bounded tool-call correlation map).
|
|
- **Subprocess isolation.** The agent env is built from an allow-list
|
|
(`acpEnvAllowList`) — inherited `process.env` is **not** forwarded.
|
|
|
|
Not sandboxed in v1: the agent's own process/network syscalls run with Fusion's
|
|
user privileges (OS-level sandboxing is recommended future work).
|
|
|
|
## Settings
|
|
|
|
| Key | Default | Meaning |
|
|
| --- | --- | --- |
|
|
| `acpBinaryPath` | `acp-agent` | Agent binary to spawn |
|
|
| `acpArgs` | `[]` | Args that launch the agent in ACP/stdio mode (e.g. `["--acp"]`) |
|
|
| `acpModel` | — | Optional model identifier reported via `describeModel` |
|
|
| `acpFsRead` | `false` | Advertise/register `fs/read_text_file` |
|
|
| `acpFsWrite` | `false` | Advertise/register `fs/write_text_file` (gated) |
|
|
| `acpEnvAllowList` | `[]` | Env var names forwarded to the agent subprocess |
|
|
| `acpAllowUnrestricted` | `false` | Acknowledge the untrusted-agent risk under an allow-all policy |
|
|
|
|
## Upstream / third-party integration evidence
|
|
|
|
Per `AGENTS.md` (External-integration evidence):
|
|
|
|
- **Protocol homepage / docs:** https://agentclientprotocol.com
|
|
- **Upstream protocol repo:** https://github.com/agentclientprotocol/agent-client-protocol
|
|
- **TypeScript SDK repo:** https://github.com/agentclientprotocol/typescript-sdk
|
|
- **Dependency (npm):** `@agentclientprotocol/sdk` — https://www.npmjs.com/package/@agentclientprotocol/sdk
|
|
- **Pinned release:** `0.24.0` (Apache-2.0)
|
|
- **Tarball:** https://registry.npmjs.org/@agentclientprotocol/sdk/-/sdk-0.24.0.tgz
|
|
- **Integrity (sha512):** `sha512-vvu9appvGvfYstBj19C6NCepV6SvUhY5VRv60KUZ4XzhTah/olOYul5Zo4C+x2enyshMSvgB2mm/OEmrsHaSmA==`
|
|
- **Agent binaries driven:** user-supplied ACP agents (e.g. `gemini --acp`, the
|
|
`@agentclientprotocol/claude-agent-acp` adapter). These are configured by the
|
|
user at runtime, not bundled — `upstream-pending-verification` per agent.
|
|
|
|
See `docs/acp-contract.md` for the launch/readiness contract and failure taxonomy.
|