diff --git a/backend/docs/CONFIGURATION.md b/backend/docs/CONFIGURATION.md index 635f23ebc6..ec04cdb3fe 100644 --- a/backend/docs/CONFIGURATION.md +++ b/backend/docs/CONFIGURATION.md @@ -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 diff --git a/backend/packages/harness/deerflow/tools/builtins/invoke_acp_agent_tool.py b/backend/packages/harness/deerflow/tools/builtins/invoke_acp_agent_tool.py index c7577d50fb..5d09f32959 100644 --- a/backend/packages/harness/deerflow/tools/builtins/invoke_acp_agent_tool.py +++ b/backend/packages/harness/deerflow/tools/builtins/invoke_acp_agent_tool.py @@ -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." diff --git a/backend/tests/test_invoke_acp_agent_tool.py b/backend/tests/test_invoke_acp_agent_tool.py index 9292f68a72..02abd999c7 100644 --- a/backend/tests/test_invoke_acp_agent_tool.py +++ b/backend/tests/test_invoke_acp_agent_tool.py @@ -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( diff --git a/config.example.yaml b/config.example.yaml index 65b091a110..64192c5d19 100644 --- a/config.example.yaml +++ b/config.example.yaml @@ -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 diff --git a/docs/guide/configuration.md b/docs/guide/configuration.md index d5801a8e1c..57b33324a1 100644 --- a/docs/guide/configuration.md +++ b/docs/guide/configuration.md @@ -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