ACP Support

[0xSero]

Add ACP Support with Zed Integration, Protocol Fixes, and Tool Streaming

Overview

• Adds first-class Agent Client Protocol (ACP) support to Mini‑Agent, enabling integration with ACP-compatible clients like Zed.
• Fixes protocol compliance issues (stopReason values, tool-call update shape).
• Improves reliability and security (no secrets in repo, safer logging, offline-safe token counting).
• Updates documentation with a concrete Zed setup guide.

Why

• Zed rejected invalid stopReason values ("error", "max_steps") and tool-call updates that didn’t match ACP’s SDK signature.
• A misuse of the skills loader injected a list into the tools collection, causing "'list' object has no attribute 'name'".
• Ensure consistent usage from Zed by pointing to the exact local venv install.

What’s Included

• ACP server entry and agent
  • mini_agent/acp/server.py: stdio ACP server entry (mini-agent-acp), config/bootstrap.
  • mini_agent/acp/agent.py: ACP Agent implementation with multi‑session, streaming, tool execution.
  • mini_agent/acp/session.py: Session manager.
  • mini_agent/acp/converter.py: Message/content conversion.
  • mini_agent/acp/schema_fix.py: Monkeypatch to accept string protocolVersion from some clients (e.g., “1.0.0”).
• Protocol compliance fixes
  • Stop reasons now return only ACP-allowed values: end_turn, max_tokens, max_turn_requests, refusal, cancelled.
  • Tool streaming uses start_tool_call(...) and update_tool_call(...) with status, raw_input, raw_output, and content blocks.
  • InitializeResponse uses string protocolVersion; InitializeRequest accepts string versions via monkeypatch.
• LLM/tool integration improvements
  • Pass tool schemas (tool.to_schema()) to the LLM instead of Tool objects.
• Robustness and safety
  • mini_agent/logger.py: Fallback log path in CWD when HOME is not writable.
  • mini_agent/tools/file_tools.py: Offline-safe token counting fallback if tiktoken isn’t available.
  • Config secrets avoided: repository ignores config.yaml.
• Documentation
  • README.md: Detailed Zed integration steps (using absolute venv path), version verification wrapper, and configuration search order.
  • mini_agent/acp/README.md: Expanded “With Zed” section, config locations, and explicit statement of ACP stopReason compliance.

How To Test

• Unit/Integration (without network):
  • pytest -q (44 passed, 3 skipped in local run).
• Manual ACP server:
  • mini-agent-acp and connect an ACP client over stdio.
  • Or python -m acp.examples.client mini-agent-acp.
• Zed integration (recommended):
  • Agent Panel → New External Agent → ACP
  • Command: /absolute/path/to/venv/bin/mini-agent-acp
  • Optional wrapper to confirm version:
    • Command: /bin/bash
    • Args: -lc, echo 'mini-agent:' $(python -c 'import importlib.metadata as m; print(m.version("mini-agent"))') 'at' $(python -c 'import mini_agent; print(mini_agent.__file__)') >&2; exec /absolute/path/to/venv/bin/mini-agent-acp
  • Start a thread, invoke file tools or bash. You should see tool status transitions (in_progress → completed|failed) with raw_input and raw_output.

Compatibility

• No breaking changes to the core CLI (mini-agent).
• Adds new entrypoint mini-agent-acp.
• ACP mode skips dynamic MCP tool loading for now (logged notice).

Known Limitations

• loadSession and setSessionMode not implemented.
• Permission prompts for tools are not yet included.
• ACP-mode MCP integration is stubbed (planned).

Notes For Reviewers

• Main focus is correctness of ACP handshake and streaming semantics.
• Documentation emphasizes Zed usage and avoiding version drift.
• Changes are isolated to ACP modules and small targeted fixes in shared utilities.

Changelog

• feat: ACP server + agent; Zed-ready integration.
• fix: ACP stopReason mapping; valid tool-call streaming API usage.
• fix: Skills loader misusage causing “list has no attribute 'name'”.
• fix: Logger fallback when HOME is not writable.
• fix: Token counting fallback when tiktoken encoder unavailable.
• docs: Add Zed setup steps, config guidance, and ACP compliance notes.
• chore: Remove local config file with API key; ensure secrets not tracked.

How To Roll Back

• Remove mini-agent-acp entrypoint and mini_agent/acp/*.
• Revert changes in mini_agent/acp/agent.py, mini_agent/acp/server.py, mini_agent/config.py, mini_agent/tools/file_tools.py, mini_agent/logger.py, and the README updates.

[adao-max]

Thanks for you PR, our engineer will review it soon

[AkairoDev]

Thank you @0xSero for this comprehensive PR!
However, we've decided not to merge this into Mini-Agent. This project is designed as a minimal, educational example for MCP best practices, and adding ~1,300 lines for ACP support would significantly increase complexity beyond our intended scope.
We encourage you to fork Mini-Agent and maintain an ACP-enhanced version independently where it can evolve without the constraints of keeping Mini-Agent minimal.
Thanks for your contribution!

[0xSero]

Thank you @0xSero for this comprehensive PR! However, we've decided not to merge this into Mini-Agent. This project is designed as a minimal, educational example for MCP best practices, and adding ~1,300 lines for ACP support would significantly increase complexity beyond our intended scope. We encourage you to fork Mini-Agent and maintain an ACP-enhanced version independently where it can evolve without the constraints of keeping Mini-Agent minimal. Thanks for your contribution!

Hello, I hear you it's definitely a lot.
I have slimmed this down to 200~ lines of code: #14 while maintaining all functionality.

I am not insisting feel free to close this PR, I will maintain a version of this on my repo that's more complex. However I will note Zed has 150k monthly active users, and they only support Claude, GPT, and Gemini out the box. It's currently my favorite browser.

Regardless, thank you for this example repo it's very nice to see how the agentic loop boils down.