feat: add support acp in common chat (#369)

docs/acp-agents.md

@@ -0,0 +1,114 @@
+# ACP agents
+
+QodeAssist can talk to external coding agents that speak the
+[Agent Client Protocol](https://agentclientprotocol.com) (ACP). The **QodeAssist >
+Agents** settings page lists the agents it knows about and lets you verify that one
+starts and answers the ACP handshake.
+
+## Where the list comes from
+
+The list is merged from three sources. When the same agent `id` appears in more than
+one, the higher entry wins:
+
+1. **Your JSON files** in `qodeassist/agents/` inside the Qt Creator user resource
+   directory (**Open Agents Folder...** opens it). Press **Reload** after editing.
+2. **The ACP registry**, downloaded from
+   `https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json` when you press
+   **Refresh from Registry** and cached on disk. There is no background polling: the
+   list only changes when you ask for it.
+3. **A bundled snapshot**, so the list is never empty on a fresh install or offline.
+
+If a download fails, the cached copy and the bundled snapshot stay in place.
+
+## Finding the agent's executable
+
+Qt Creator started from the Dock or a launcher does not inherit your shell's `PATH`, so
+`npx` or `uvx` installed through Homebrew, nvm or uv is often invisible to it — the agent
+then fails to start with `execve: No such file or directory`. **Extra PATH for launching
+agents** on the Agents page lists directories that are both searched for the executable
+and prepended to the agent's own `PATH`. On macOS it defaults to
+`/opt/homebrew/bin:/usr/local/bin`. An `env` entry in the agent definition still wins over
+it.
+
+## Credentials and other environment variables
+
+Some agents authenticate through an environment variable rather than the ACP handshake —
+the Claude adapter, for instance, declares no `authMethods` at all and reads
+`CLAUDE_CODE_OAUTH_TOKEN`. Since a Qt Creator started from the dock inherits no shell
+environment, that variable never reaches the agent and it fails with an expired-session
+error.
+
+**Forward these variables to agents** on the Agents page takes variable *names*, not
+values, and defaults to `CLAUDE_CODE_OAUTH_TOKEN`. For each name QodeAssist uses the value
+from its own environment when it has one — which covers Windows, and any platform when Qt
+Creator was launched from a terminal. On macOS and Linux the remaining names are read once
+per session from a login shell (`$SHELL -l -i -c env`), so a token exported in your shell
+profile works without being copied anywhere. Nothing is stored in the settings but the
+names.
+
+An `env` entry in the agent definition still wins over a forwarded variable.
+
+## Distributions
+
+An entry describes how the agent is started:
+
+- `npx` — launched as `npx -y <package> <args>`. Requires Node.js on `PATH`.
+- `uvx` — launched as `uvx <package> <args>`. Requires uv on `PATH`.
+- `command` — launched directly. This is the QodeAssist extension used by your own
+  JSON files.
+- `binary` — a downloadable platform archive. QodeAssist does not download binaries,
+  so these agents are listed but cannot be started. Install the agent yourself and add
+  a `command` entry for it.
+
+## Defining your own agent
+
+Create a `.json` file in the agents folder. A file holds either a single agent object
+or a registry-shaped `{"agents": [...]}` document.
+
+```json
+{
+  "id": "my-agent",
+  "name": "My Agent",
+  "version": "1.0.0",
+  "description": "Locally installed agent",
+  "distribution": {
+    "command": {
+      "cmd": "/usr/local/bin/my-agent",
+      "args": ["acp"],
+      "env": { "MY_AGENT_LOG": "debug" }
+    }
+  }
+}
+```
+
+Reusing an `id` from the registry overrides that entry — which is how you make a
+`binary` agent launchable after installing it manually:
+
+```json
+{
+  "id": "cursor",
+  "name": "Cursor",
+  "distribution": {
+    "command": { "cmd": "/usr/local/bin/cursor-agent", "args": ["acp"] }
+  }
+}
+```
+
+Agent definitions hold no secrets. Agents that need credentials authenticate through
+the ACP handshake.
+
+## Testing an agent
+
+Select an agent and press **Test**. QodeAssist starts the process, runs the ACP
+`initialize` handshake and reports the agent's name, version, protocol version,
+whether it supports session persistence (`loadSession`), its prompt and MCP
+capabilities, and its authentication methods. On failure it shows the error together
+with the agent's own output.
+
+## Long conversations and reopened sessions
+
+When an agent conversation grows long, the **Hand over** button in the chat bottom
+bar summarizes the transcript with your Chat Assistant configuration and continues in
+a fresh agent session seeded with that summary — see
+[chat-summarization.md](chat-summarization.md) for details. The same handover is
+offered on the read-only banner when a saved agent session can no longer be resumed.