feat(acp): add Pi coding agent configuration (#8293)

* feat(acp): add Pi coding agent configuration

* fix(acp): address Pi configuration review feedback

* docs(acp): document Pi prerequisites and isolation

* docs(acp): use Pi interactive login in setup examples

---------

Co-authored-by: 30bef100w <30bef100w@users.noreply.github.com>
Co-authored-by: 30bef100w <314075793+30bef100w@users.noreply.github.com>
This commit is contained in:
30bef100w 2026-11-18 11:49:44 +08:00 committed by GitHub
parent c18df580f6
commit 32dafbe2fe
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
5 changed files with 130 additions and 0 deletions

View File

@ -2296,6 +2296,45 @@ Leave `auto_approve_permissions` disabled for untrusted tasks, and enable it
only when the agent is expected to edit files or run commands for a trusted
task.
Pi can run as an external coding agent through the community `pi-acp` adapter.
The adapter launches the separate `pi` executable, so install both packages in
the Gateway environment before starting DeerFlow. `pi-acp` currently requires
Node.js 22+ and pi 0.81.0+:
```bash
npm install --global @earendil-works/pi-coding-agent
npm install --global pi-acp
```
Configure pi's model provider and API key separately for the user that runs the
Gateway. For interactive providers, start `pi` in that same environment, then run
`/login` in Pi's terminal UI and select your provider. Alternatively, provide the
provider's documented environment variables. The `pi` executable and its credentials must
be available inside the Gateway container; installing or authenticating them
only on the Docker host is not sufficient.
```yaml
acp_agents:
pi:
command: pi-acp
args: []
description: Pi coding agent for repository tasks and code generation
auto_approve_permissions: false
```
Node.js, `pi-acp`, and `pi` must be available on the Gateway process's `PATH`. When
the Gateway runs in Docker, install them inside the Gateway image or container.
Pi executes its filesystem and shell tools directly in its working environment.
`auto_approve_permissions` only controls permission requests sent through ACP;
leaving it disabled does not sandbox these direct operations. Run untrusted Pi
tasks in an independently isolated process, container, or VM with only the
required files, credentials, and network access. Keep
`auto_approve_permissions` disabled for untrusted tasks. Alternatively,
set `command: npx` and `args: ["-y", "pi-acp"]` to fetch the adapter on demand;
this requires `npx` on the Gateway's `PATH` and may require network access at
startup. Preinstalling the adapter lets deployment tooling control its version
without fetching it during an invocation.
## HITL Tool Approval

View File

@ -269,6 +269,19 @@ def _format_invocation_error(agent: str, cmd: str, exc: Exception) -> str:
f"{message} Install it with `npm install --global @minimax-ai/code`, run `mcode login`, and restart DeerFlow so it inherits the updated PATH. "
"If the Gateway runs in Docker, ensure `mcode` is installed and authenticated inside the Gateway container/image."
)
if agent == "pi" or cmd == "pi-acp":
if cmd == "npx":
return (
f"{message} Install Node.js (which includes npm and `npx`) in the Gateway environment, "
"then restart DeerFlow so it inherits the updated Gateway PATH. "
"If the Gateway runs in Docker, install Node.js inside the Gateway container/image."
)
return (
f"{message} Install the Pi ACP adapter with `npm install --global pi-acp`, "
"or configure the agent to use `npx -y pi-acp`. Ensure Node.js and "
"`npx` are available on the Gateway PATH (inside the Gateway "
"container when running Docker)."
)
return f"{message} Install the agent binary or update `acp_agents.{agent}.command` in config.yaml."

View File

@ -147,6 +147,47 @@ def test_missing_mcode_command_returns_install_and_login_guidance():
assert "restart DeerFlow" in result
@pytest.mark.parametrize("agent", ["pi", "pi_coding"])
def test_missing_pi_command_returns_adapter_install_guidance(agent):
result = _format_invocation_error(agent, "pi-acp", FileNotFoundError())
assert "npm install --global pi-acp" in result
assert "npx -y pi-acp" in result
assert "Gateway PATH" in result
def test_missing_npx_for_pi_returns_node_install_guidance():
result = _format_invocation_error("pi", "npx", FileNotFoundError())
assert "Command 'npx' was not found" in result
assert "Install Node.js" in result
assert "npm" in result
assert "Gateway PATH" in result
assert "container" in result
assert "npm install --global pi-acp" not in result
@pytest.mark.anyio
async def test_pi_invocation_reports_missing_npx(monkeypatch, tmp_path):
from deerflow.config import paths as paths_module
monkeypatch.setattr(paths_module, "get_paths", lambda: paths_module.Paths(base_dir=tmp_path))
monkeypatch.setattr(
"deerflow.config.extensions_config.ExtensionsConfig.from_file",
classmethod(lambda cls: ExtensionsConfig(mcp_servers={}, skills={})),
)
empty_bin = tmp_path / "empty-bin"
empty_bin.mkdir()
monkeypatch.setenv("PATH", str(empty_bin))
tool = build_invoke_acp_agent_tool({"pi": ACPAgentConfig(command="npx", args=["-y", "pi-acp"], description="Pi coding agent")})
result = await tool.coroutine(agent="pi", prompt="Inspect the repository")
assert "Command 'npx' was not found" in result
assert "Install Node.js" in result
assert "npm install --global pi-acp" not in result
@pytest.mark.anyio
async def test_build_invoke_tool_description_and_unknown_agent_error():
tool = build_invoke_acp_agent_tool(

View File

@ -2220,6 +2220,23 @@ hitl_approval:
# # auto_approve_permissions: false # Set to true to auto-approve ACP permission requests
# # env: # Optional: inject environment variables into the agent subprocess
# # OPENAI_API_KEY: $OPENAI_API_KEY # $VAR resolves from host environment
#
# pi:
# # Pi coding agent through the community ACP adapter (`pi-acp`).
# # Requires Node.js 22+ and pi 0.81.0+. Install both in the Gateway environment:
# # npm install --global @earendil-works/pi-coding-agent pi-acp
# # Configure pi's model provider/API key for the Gateway user.
# # For interactive sign-in, start `pi` and run `/login` in its terminal UI.
# command: pi-acp
# args: []
# # Alternatively, fetch the adapter on demand (requires network access):
# # command: npx
# # args: ["-y", "pi-acp"]
# description: Pi coding agent for repository tasks and code generation
# # Pi performs filesystem and shell operations directly; auto_approve_permissions
# # only handles ACP permission requests and is not a sandbox. Isolate untrusted tasks.
# # auto_approve_permissions: false # Set to true only for trusted tasks
# # timeout_seconds: 1800 # Abort + kill the subprocess if it doesn't respond in time
# ============================================================================
# Skills Configuration

View File

@ -412,6 +412,26 @@ fences, including unclosed fences, in complete and streamed replies.
```
`mcode` must be on the Gateway process's `PATH`; installing it only on the Docker host does not make it available inside the Gateway container. DeerFlow invokes it through `invoke_acp_agent` in a per-thread ACP workspace and forwards enabled MCP servers. Keep `auto_approve_permissions: false` for untrusted tasks; enable it only when mcode must edit files or run commands and you trust the task.
Pi can be used as an external coding agent through the community `pi-acp` adapter. The adapter launches the separate `pi` executable, so install both packages in the Gateway environment before starting DeerFlow. `pi-acp` currently requires Node.js 22+ and pi 0.81.0+:
```bash
npm install --global @earendil-works/pi-coding-agent
npm install --global pi-acp
```
Configure pi's model provider and API key separately for the user that runs the Gateway. For interactive providers, start `pi` in that same environment, then run `/login` in Pi's terminal UI and select your provider. Alternatively, provide the provider's documented environment variables. The `pi` executable and its credentials must be available inside the Gateway container; installing or authenticating them only on the Docker host is not sufficient.
```yaml
acp_agents:
pi:
command: pi-acp
args: []
description: Pi coding agent for repository tasks and code generation
auto_approve_permissions: false
```
Node.js and both `pi-acp` and `pi` must be available on the Gateway process's `PATH`. When the Gateway runs in Docker, install them inside the Gateway image or container. Pi executes its filesystem and shell tools directly in its working environment. `auto_approve_permissions` only controls permission requests sent through ACP; leaving it disabled does not sandbox these direct operations. Run untrusted Pi tasks in an independently isolated process, container, or VM with only the required files, credentials, and network access. Keep `auto_approve_permissions: false` for untrusted tasks. Alternatively, set `command: npx` and `args: ["-y", "pi-acp"]` to fetch the adapter on demand; this requires `npx` on the Gateway's `PATH` and may require network access at startup. Preinstalling the adapter lets deployment tooling control its version without fetching it during an invocation.
- On macOS, export Claude Code auth explicitly if needed:
```bash