Skip to content

Agent Zero AI framework

Bundle Agent Zero ACP

Alessandroadd781d3b3e5
diff --git a/plugins/_a0_acp/README.md b/plugins/_a0_acp/README.md
new file mode 100644
index 000000000..26a3ad9c4
--- /dev/null
+++ b/plugins/_a0_acp/README.md
@@ -0,0 +1,17 @@
+# Agent Client Protocol
+
+`_a0_acp` is the bundled Agent Client Protocol bridge. ACP-capable editors
+start the local connector with:
+
+```bash
+a0 acp --host http://localhost:32081
+```
+
+The connector owns editor-hosted files and terminal access. The Agent Zero
+runtime owns ACP session metadata, history, modes, and model settings. The
+default transport is the connector; the hidden `transport: container` setting
+is only a compatibility fallback for an already configured legacy `a0_acp`
+plugin inside the selected container.
+
+On startup, Agent Zero removes retired `usr/plugins/a0_acp` installations and
+their project or agent overrides. The bundled `_a0_acp` configuration is kept.
diff --git a/plugins/_a0_acp/api/session.py b/plugins/_a0_acp/api/session.py
new file mode 100644
index 000000000..87e98f56e
--- /dev/null
+++ b/plugins/_a0_acp/api/session.py
@@ -0,0 +1,223 @@
+"""Authenticated ACP session metadata API for the host-side A0 CLI."""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from helpers.api import Request, Response
+from plugins._a0_connector.api.v1.base import ProtectedConnectorApiHandler
+
+
+PLUGIN_NAME = "_a0_acp"
+CTX_IS_ACP = "acp_session"
+CTX_CWD = "acp_cwd"
+CTX_ADDITIONAL_DIRECTORIES = "acp_additional_directories"
+CTX_MODE = "acp_mode"
+CTX_MODEL_ID = "acp_model_id"
+CTX_CONFIG_OPTIONS = "acp_config_options"
+CTX_TRANSPORT = "acp_transport"
+CTX_WORKDIR = "workdir_path"
+_VALID_MODES = {"default", "plan", "act"}
+_MAX_PATHS = 32
+_MAX_PATH_LENGTH = 4096
+
+
+def _config() -> dict[str, Any]:
+ from helpers.plugins import get_plugin_config
+
+ return dict(get_plugin_config(PLUGIN_NAME) or {})
+
+
+def _paths(value: object) -> list[str]:
+ if not isinstance(value, list):
+ return []
+ return [
+ str(path).strip()
+ for path in value[:_MAX_PATHS]
+ if str(path).strip() and len(str(path).strip()) <= _MAX_PATH_LENGTH
+ ]
+
+
+def _mode(value: object) -> str:
+ mode = str(value or "default").strip().lower()
+ return mode if mode in _VALID_MODES else "default"
+
+
+def _timestamp(value: object) -> str:
+ if hasattr(value, "isoformat"):
+ return value.isoformat()
+ return str(value or "")
+
+
+def _session_payload(context) -> dict[str, Any]:
+ return {
+ "session_id": context.id,
+ "title": context.name or "Agent Zero ACP",
+ "cwd": str(context.get_data(CTX_CWD) or ""),
+ "additional_directories": _paths(context.get_data(CTX_ADDITIONAL_DIRECTORIES)),
+ "updated_at": _timestamp(context.last_message or context.created_at),
+ "mode": _mode(context.get_data(CTX_MODE)),
+ "model_id": str(context.get_data(CTX_MODEL_ID) or ""),
+ }
+
+
+def _mark_dirty(context_id: str, reason: str) -> None:
+ try:
+ from helpers.state_monitor_integration import mark_dirty_for_context
+
+ mark_dirty_for_context(context_id, reason=reason)
+ except Exception:
+ return
+
+
+class Session(ProtectedConnectorApiHandler):
+ async def process(self, input: dict, request: Request) -> dict | Response:
+ del request
+ action = str(input.get("action") or "config").strip().lower()
+ if action == "config":
+ return {"ok": True, "config": _config()}
+
+ if action == "list":
+ return self._list_sessions(input)
+ if action == "configure":
+ return self._configure(input)
+ if action == "fork":
+ return self._fork(input)
+ if action == "close":
+ return self._close(input)
+ if action == "set_mode":
+ return self._set_value(input, CTX_MODE, _mode(input.get("mode")))
+ if action == "set_model":
+ return self._set_value(input, CTX_MODEL_ID, str(input.get("model_id") or "").strip())
+ if action == "set_config_option":
+ return self._set_config_option(input)
+ return Response(status=400, response=f"Unknown ACP action: {action}")
+
+ def _context(self, input: dict):
+ from agent import AgentContext
+
+ context_id = str(input.get("context_id") or input.get("session_id") or "").strip()
+ if not context_id:
+ return None, Response(status=400, response="context_id is required")
+ context = AgentContext.get(context_id)
+ if context is None:
+ return None, Response(status=404, response="ACP session not found")
+ return context, None
+
+ def _list_sessions(self, input: dict) -> dict:
+ from agent import AgentContext
+ from helpers import persist_chat
+
+ persist_chat.load_tmp_chats()
+ cwd = str(input.get("cwd") or "").strip()
+ sessions = [
+ _session_payload(context)
+ for context in AgentContext.all()
+ if context.get_data(CTX_IS_ACP)
+ and (not cwd or str(context.get_data(CTX_CWD) or "") == cwd)
+ ]
+ sessions.sort(key=lambda session: str(session["updated_at"]), reverse=True)
+ return {"ok": True, "sessions": sessions}
+
+ def _configure(self, input: dict) -> dict | Response:
+ from helpers import persist_chat
+
+ config = _config()
+ if not bool(config.get("enabled", True)):
+ return Response(status=403, response="ACP is disabled in Agent Zero settings")
+ context, error = self._context(input)
+ if error:
+ return error
+
+ cwd = str(input.get("cwd") or "").strip()
+ if not cwd or len(cwd) > _MAX_PATH_LENGTH:
+ return Response(status=400, response="A valid ACP workspace path is required")
+ transport = str(config.get("transport") or "connector").strip().lower()
+ if transport not in {"connector", "container"}:
+ transport = "connector"
+
+ context.set_data(CTX_IS_ACP, True)
+ context.set_data(CTX_CWD, cwd)
+ context.set_data(CTX_ADDITIONAL_DIRECTORIES, _paths(input.get("additional_directories")))
+ context.set_data(CTX_MODE, _mode(input.get("mode")))
+ context.set_data(CTX_TRANSPORT, transport)
+ if transport == "container":
+ container_workspace = str(config.get("container_workspace_root") or "").strip()
+ if container_workspace:
+ context.set_data(CTX_WORKDIR, container_workspace)
+ if not context.name:
+ context.name = Path(cwd).name or "Agent Zero ACP"
+ persist_chat.save_tmp_chat(context)
+ _mark_dirty(context.id, "a0_acp.configure")
+ return {"ok": True, "session": _session_payload(context), "config": config}
+
+ def _fork(self, input: dict) -> dict | Response:
+ from agent import AgentContext
+ from helpers import persist_chat
+
+ context, error = self._context(input)
+ if error:
+ return error
+ if not context.get_data(CTX_IS_ACP):
+ return Response(status=400, response="Only ACP sessions can be forked through ACP")
+
+ new_ids = persist_chat.load_json_chats([persist_chat.export_json_chat(context)])
+ if not new_ids:
+ return Response(status=500, response="Could not fork ACP session")
+ fork = AgentContext.get(new_ids[0])
+ if fork is None:
+ return Response(status=500, response="Forked ACP session could not be loaded")
+
+ fork.name = f"{context.name or 'Agent Zero ACP'} (fork)"
+ fork.set_data(CTX_IS_ACP, True)
+ fork.set_data(CTX_CWD, str(input.get("cwd") or context.get_data(CTX_CWD) or ""))
+ fork.set_data(
+ CTX_ADDITIONAL_DIRECTORIES,
+ _paths(input.get("additional_directories"))
+ or _paths(context.get_data(CTX_ADDITIONAL_DIRECTORIES)),
+ )
+ fork.set_data(CTX_MODE, _mode(context.get_data(CTX_MODE)))
+ fork.set_data(CTX_TRANSPORT, context.get_data(CTX_TRANSPORT) or "connector")
+ persist_chat.save_tmp_chat(fork)
+ _mark_dirty(fork.id, "a0_acp.fork")
+ return {"ok": True, "session": _session_payload(fork)}
+
+ def _close(self, input: dict) -> dict | Response:
+ from agent import AgentContext
+ from helpers import persist_chat
+
+ context, error = self._context(input)
+ if error:
+ return error
+ context.kill_process()
+ AgentContext.remove(context.id)
+ persist_chat.remove_chat(context.id)
+ return {"ok": True}
+
+ def _set_value(self, input: dict, key: str, value: object) -> dict | Response:
+ from helpers import persist_chat
+
+ context, error = self._context(input)
+ if error:
+ return error
+ context.set_data(key, value)
+ persist_chat.save_tmp_chat(context)
+ _mark_dirty(context.id, f"a0_acp.{key}")
+ return {"ok": True, "session": _session_payload(context)}
+
+ def _set_config_option(self, input: dict) -> dict | Response:
+ from helpers import persist_chat
+
+ context, error = self._context(input)
+ if error:
+ return error
+ config_id = str(input.get("config_id") or "").strip()
+ if not config_id:
+ return Response(status=400, response="config_id is required")
+ options = context.get_data(CTX_CONFIG_OPTIONS)
+ options = dict(options) if isinstance(options, dict) else {}
+ options[config_id] = input.get("value")
+ context.set_data(CTX_CONFIG_OPTIONS, options)
+ persist_chat.save_tmp_chat(context)
+ _mark_dirty(context.id, "a0_acp.config_option")
+ return {"ok": True, "config_options": options}
diff --git a/plugins/_a0_acp/default_config.yaml b/plugins/_a0_acp/default_config.yaml
new file mode 100644
index 000000000..96f41b59c
--- /dev/null
+++ b/plugins/_a0_acp/default_config.yaml
@@ -0,0 +1,15 @@
+# The normal ACP transport is the A0 CLI running on the editor host.
+enabled: true
+agent_profile: ""
+host_file_access: read_write
+host_code_execution: true
+session_history: true
+
+# Advanced compatibility transport. These values are intentionally not exposed
+# by the standard settings UI because they require a preconfigured legacy ACP
+# plugin inside the selected container.
+transport: connector
+container_id: ""
+container_workdir: /a0
+container_python: /opt/venv-a0/bin/python
+container_workspace_root: ""
diff --git a/plugins/_a0_acp/extensions/python/message_loop_prompts_after/_50_acp_mode.py b/plugins/_a0_acp/extensions/python/message_loop_prompts_after/_50_acp_mode.py
new file mode 100644
index 000000000..ce665a3be
--- /dev/null
+++ b/plugins/_a0_acp/extensions/python/message_loop_prompts_after/_50_acp_mode.py
@@ -0,0 +1,17 @@
+from agent import LoopData
+from helpers.extension import Extension
+
+
+_MODE_PROMPTS = {
+ "plan": "ACP session mode: plan first. Prefer analysis and tradeoffs. Do not modify files unless the user explicitly asks.",
+ "act": "ACP session mode: act. Complete actionable work end-to-end with focused implementation and validation.",
+}
+
+
+class AcpMode(Extension):
+ async def execute(self, loop_data: LoopData = LoopData(), **kwargs):
+ if not self.agent or not self.agent.context.get_data("acp_session"):
+ return
+ prompt = _MODE_PROMPTS.get(str(self.agent.context.get_data("acp_mode") or ""))
+ if prompt:
+ loop_data.extras_temporary["acp_mode"] = prompt
diff --git a/plugins/_a0_acp/extensions/python/startup_migration/_10_migrate_legacy_acp.py b/plugins/_a0_acp/extensions/python/startup_migration/_10_migrate_legacy_acp.py
new file mode 100644
index 000000000..cc4d727d1
--- /dev/null
+++ b/plugins/_a0_acp/extensions/python/startup_migration/_10_migrate_legacy_acp.py
@@ -0,0 +1,53 @@
+"""Retire the former community ACP plugin after Core ships its replacement."""
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+from typing import Any
+
+from helpers import cache, files
+from helpers.extension import Extension
+from helpers.print_style import PrintStyle
+
+
+LEGACY_PLUGIN_NAME = "a0_acp"
+
+
+class LegacyAcpMigration(Extension):
+ def execute(self, **kwargs: Any) -> None:
+ result = migrate_legacy_acp()
+ if result["removed_roots"]:
+ PrintStyle.info("Removed retired ACP plugin files:", result["removed_roots"])
+
+
+def migrate_legacy_acp(base_dir: str | Path | None = None) -> dict[str, list[str]]:
+ root = Path(base_dir or files.get_abs_path("")).resolve()
+ removed_roots: list[str] = []
+ errors: list[str] = []
+
+ for plugin_root in _legacy_plugin_roots(root):
+ try:
+ if plugin_root.is_dir() and not plugin_root.is_symlink():
+ shutil.rmtree(plugin_root)
+ else:
+ plugin_root.unlink()
+ removed_roots.append(str(plugin_root))
+ except OSError as exc:
+ errors.append(f"Could not remove retired ACP plugin at {plugin_root}: {exc}")
+
+ if removed_roots:
+ cache.clear("*(plugins)*")
+ cache.clear("*(extensions)*")
+ cache.clear("*(api)*")
+
+ return {"removed_roots": removed_roots, "errors": errors}
+
+
+def _legacy_plugin_roots(root: Path) -> list[Path]:
+ candidates = [
+ root / "usr" / "plugins" / LEGACY_PLUGIN_NAME,
+ *root.glob(f"usr/projects/*/.a0proj/plugins/{LEGACY_PLUGIN_NAME}"),
+ *root.glob(f"usr/projects/*/.a0proj/agents/*/plugins/{LEGACY_PLUGIN_NAME}"),
+ *root.glob(f"usr/agents/*/plugins/{LEGACY_PLUGIN_NAME}"),
+ ]
+ return [candidate for candidate in candidates if candidate.exists() or candidate.is_symlink()]
diff --git a/plugins/_a0_acp/plugin.yaml b/plugins/_a0_acp/plugin.yaml
new file mode 100644
index 000000000..8e817c847
--- /dev/null
+++ b/plugins/_a0_acp/plugin.yaml
@@ -0,0 +1,9 @@
+name: _a0_acp
+title: Agent Client Protocol
+description: Connect ACP-capable editors through the local A0 CLI connector.
+version: "2.0"
+settings_sections:
+ - external
+per_project_config: false
+per_agent_config: false
+always_enabled: true
diff --git a/plugins/_a0_acp/tests/test_migration.py b/plugins/_a0_acp/tests/test_migration.py
new file mode 100644
index 000000000..d8faad273
--- /dev/null
+++ b/plugins/_a0_acp/tests/test_migration.py
@@ -0,0 +1,29 @@
+from pathlib import Path
+
+from plugins._a0_acp.extensions.python.startup_migration._10_migrate_legacy_acp import (
+ migrate_legacy_acp,
+)
+
+
+def test_migrate_legacy_acp_removes_all_stale_plugin_roots(tmp_path: Path) -> None:
+ stale_roots = [
+ tmp_path / "usr" / "plugins" / "a0_acp",
+ tmp_path / "usr" / "projects" / "demo" / ".a0proj" / "plugins" / "a0_acp",
+ tmp_path / "usr" / "agents" / "reviewer" / "plugins" / "a0_acp",
+ ]
+ bundled_config = tmp_path / "usr" / "plugins" / "_a0_acp" / "config.json"
+
+ for root in stale_roots:
+ (root / ".git").mkdir(parents=True)
+ (root / "plugin.yaml").write_text("name: a0_acp\n", encoding="utf-8")
+ (root / ".git" / "config").write_text("[core]\n", encoding="utf-8")
+ bundled_config.parent.mkdir(parents=True)
+ bundled_config.write_text('{"enabled": true}\n', encoding="utf-8")
+
+ result = migrate_legacy_acp(tmp_path)
+
+ assert len(result["removed_roots"]) == len(stale_roots)
+ assert result["errors"] == []
+ assert all(not root.exists() for root in stale_roots)
+ assert bundled_config.read_text(encoding="utf-8") == '{"enabled": true}\n'
+ assert migrate_legacy_acp(tmp_path) == {"removed_roots": [], "errors": []}
diff --git a/plugins/_a0_acp/tests/test_session.py b/plugins/_a0_acp/tests/test_session.py
new file mode 100644
index 000000000..0173b490f
--- /dev/null
+++ b/plugins/_a0_acp/tests/test_session.py
@@ -0,0 +1,19 @@
+from datetime import datetime, timezone
+
+from plugins._a0_acp.api.session import _session_payload
+
+
+class _Context:
+ id = "ctx-acp"
+ name = "ACP"
+ created_at = datetime(2026, 8, 16, tzinfo=timezone.utc)
+ last_message = datetime(2026, 8, 16, 12, 34, tzinfo=timezone.utc)
+
+ def get_data(self, key: str):
+ return {"acp_cwd": "/workspace", "acp_mode": "default"}.get(key)
+
+
+def test_session_payload_serializes_datetime_metadata() -> None:
+ payload = _session_payload(_Context())
+
+ assert payload["updated_at"] == "2026-08-16T12:34:00+00:00"
diff --git a/plugins/_a0_acp/webui/config.html b/plugins/_a0_acp/webui/config.html
new file mode 100644
index 000000000..4817755e9
--- /dev/null
+++ b/plugins/_a0_acp/webui/config.html
@@ -0,0 +1,81 @@
+<html>
+<head>
+ <title>Agent Client Protocol</title>
+</head>
+
+<body>
+ <div x-data>
+ <template x-if="config">
+ <div>
+ <div class="section-title">Agent Client Protocol</div>
+ <div class="section-description">Connect an ACP-capable editor through the A0 CLI running on the editor computer.</div>
+
+ <div class="field">
+ <div class="field-label">
+ <div class="field-title">Enable ACP</div>
+ <div class="field-description">Allows A0 CLI ACP sessions for this Agent Zero instance.</div>
+ </div>
+ <div class="field-control">
+ <label class="toggle">
+ <input type="checkbox" x-model="config.enabled" />
+ <span class="toggler"></span>
+ </label>
+ </div>
+ </div>
+
+ <div class="field">
+ <div class="field-label">
+ <div class="field-title">Default agent profile</div>
+ <div class="field-description">Optional profile key used for new ACP sessions.</div>
+ </div>
+ <div class="field-control"><input type="text" x-model="config.agent_profile" autocomplete="off" /></div>
+ </div>
+
+ <div class="field">
+ <div class="field-label">
+ <div class="field-title">Editor workspace access</div>
+ <div class="field-description">Controls whether Agent Zero can write through the connected A0 CLI.</div>
+ </div>
+ <div class="field-control">
+ <select x-model="config.host_file_access">
+ <option value="read_write">Read and write</option>
+ <option value="read_only">Read only</option>
+ </select>
+ </div>
+ </div>
+
+ <div class="field">
+ <div class="field-label">
+ <div class="field-title">Editor terminal access</div>
+ <div class="field-description">Allows code execution on the computer running the A0 CLI.</div>
+ </div>
+ <div class="field-control">
+ <label class="toggle">
+ <input type="checkbox" x-model="config.host_code_execution" />
+ <span class="toggler"></span>
+ </label>
+ </div>
+ </div>
+
+ <div class="field">
+ <div class="field-label">
+ <div class="field-title">Session history</div>
+ <div class="field-description">Lets ACP editors list and resume their prior Agent Zero sessions.</div>
+ </div>
+ <div class="field-control">
+ <label class="toggle">
+ <input type="checkbox" x-model="config.session_history" />
+ <span class="toggler"></span>
+ </label>
+ </div>
+ </div>
+
+ <div class="field">
+ <div class="field-label"><div class="field-title">Editor command</div></div>
+ <div class="field-control"><code>a0 acp --host &lt;agent-zero-url&gt;</code></div>
+ </div>
+ </div>
+ </template>
+ </div>
+</body>
+</html>