tsugite-acp 0.14.1__tar.gz

tsugite_acp-0.14.1/.gitignore

@@ -0,0 +1,183 @@
+# ---> Python
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+.env
+.env
+benchmark_results/
+test_output/
+.claude/settings.local.json
+std*.txt
+secrets/*
+
+
+# TODO: temp - I need to clean up the docs
+docs-old/
+examples/*
+!examples/tsugite-example-plugin/
+agents/
+.claude/
+.tsugite/
+benchmarks/
+docker-compose.test.yml
+#### TODO ^^^

tsugite_acp-0.14.1/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.4
+Name: tsugite-acp
+Version: 0.14.1
+Summary: Tsugite plugin: ACP provider routing through claude-agent-acp
+Requires-Python: >=3.11
+Requires-Dist: agent-client-protocol>=0.9.0
+Requires-Dist: tsugite-cli==0.14.1

tsugite_acp-0.14.1/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "tsugite-acp"
+version = "0.14.1"
+description = "Tsugite plugin: ACP provider routing through claude-agent-acp"
+requires-python = ">=3.11"
+dependencies = [
+  "tsugite-cli==0.14.1",
+  "agent-client-protocol>=0.9.0",
+]
+
+[project.entry-points."tsugite.providers"]
+acp = "tsugite_acp:create_provider"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["tsugite_acp"]
+
+[tool.hatch.build.targets.sdist]
+include = [
+  "/tsugite_acp",
+  "/pyproject.toml",
+]
+
+[tool.uv.sources]
+tsugite-cli = { workspace = true }

tsugite_acp-0.14.1/tsugite_acp/__init__.py

@@ -0,0 +1,5 @@
+"""Tsugite plugin: ACP provider routing through claude-agent-acp."""
+
+from tsugite_acp.provider import ACPProvider, create_provider
+
+__all__ = ["ACPProvider", "create_provider"]

tsugite_acp-0.14.1/tsugite_acp/client.py

@@ -0,0 +1,328 @@
+"""ACPClientSession: handshake + prompt-turn loop bridging an ACP agent to tsugite.
+
+The Client implementation captures session_update notifications onto an asyncio.Queue.
+ACPClientSession.prompt() runs the agent's prompt() as a background task while draining
+the queue, so the caller sees text/thought chunks as an async iterator and a final
+"done" event with the stop reason and usage.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import shutil
+from collections import deque
+from dataclasses import dataclass
+from importlib.metadata import PackageNotFoundError, version
+from typing import Any, AsyncIterator, Literal, get_args
+
+from acp import PROTOCOL_VERSION, connect_to_agent
+from acp.schema import (
+    AgentCapabilities,
+    AgentMessageChunk,
+    AgentThoughtChunk,
+    AllowedOutcome,
+    ClientCapabilities,
+    FileSystemCapabilities,
+    Implementation,
+    RequestPermissionResponse,
+    StopReason,
+)
+
+from tsugite.exceptions import AgentExecutionError
+from tsugite_acp.policy import PermissionPolicy
+
+logger = logging.getLogger(__name__)
+
+_STDERR_BUFFER_LINES = 200
+_FATAL_STOP_REASONS = frozenset(get_args(StopReason)) - {"end_turn", "cancelled"}
+
+
+def _plugin_version() -> str:
+    try:
+        return version("tsugite-acp")
+    except PackageNotFoundError:
+        return "0.0.0"
+
+
+@dataclass
+class ACPEvent:
+    """Yielded from ACPClientSession.prompt(). One of text/thought/done."""
+
+    kind: Literal["text", "thought", "done"]
+    text: str = ""
+    stop_reason: str | None = None
+    usage: dict | None = None
+
+
+class ACPClientHandler:
+    """Implementation of acp.Client. Bridges agent notifications onto a queue.
+
+    Capabilities advertised by ACPClientSession declare fs/terminal as unsupported,
+    so the corresponding callbacks should never fire - they raise NotImplementedError
+    if they do.
+    """
+
+    def __init__(self, policy: PermissionPolicy | None = None) -> None:
+        self._queue: asyncio.Queue = asyncio.Queue()
+        self._policy = policy or PermissionPolicy()
+
+    async def session_update(self, session_id: str, update, **_: Any) -> None:
+        await self._queue.put(update)
+
+    async def request_permission(self, options, session_id: str, tool_call, **_: Any) -> RequestPermissionResponse:
+        if not options:
+            raise AgentExecutionError("agent requested permission with no options")
+
+        tool_name = self._tool_name_from_call(tool_call)
+        params = self._tool_params_from_call(tool_call)
+        action = self._policy.evaluate(tool_name, params)
+
+        if action == "deny":
+            chosen = self._first_option_of_kinds(options, ("reject_once", "reject_always"))
+            if chosen is None:
+                logger.warning("policy denied %s but no reject option offered; passing first option", tool_name)
+                chosen = options[0]
+            else:
+                logger.warning("policy denied %s(%s)", tool_name, params)
+        else:
+            chosen = self._first_option_of_kinds(options, ("allow_once", "allow_always")) or options[0]
+
+        return RequestPermissionResponse(outcome=AllowedOutcome(option_id=chosen.option_id, outcome="selected"))
+
+    @staticmethod
+    def _first_option_of_kinds(options, kinds: tuple[str, ...]):
+        for opt in options:
+            if opt.kind in kinds:
+                return opt
+        return None
+
+    @staticmethod
+    def _tool_name_from_call(tool_call) -> str:
+        # ToolCallUpdate doesn't carry a tool name; the title is the closest proxy
+        # used by claude-agent-acp (e.g. "Read foo", "Bash git status").
+        title = getattr(tool_call, "title", "") or ""
+        return title.split(" ", 1)[0] if title else ""
+
+    @staticmethod
+    def _tool_params_from_call(tool_call) -> dict:
+        raw = getattr(tool_call, "raw_input", None)
+        return dict(raw) if isinstance(raw, dict) else {}
+
+    async def write_text_file(self, *_a: Any, **_kw: Any):  # pragma: no cover - unsupported
+        raise NotImplementedError("write_text_file capability is unsupported")
+
+    async def read_text_file(self, *_a: Any, **_kw: Any):  # pragma: no cover - unsupported
+        raise NotImplementedError("read_text_file capability is unsupported")
+
+    async def create_terminal(self, *_a: Any, **_kw: Any):  # pragma: no cover - unsupported
+        raise NotImplementedError("terminal capability is unsupported")
+
+    async def terminal_output(self, *_a: Any, **_kw: Any):  # pragma: no cover - unsupported
+        raise NotImplementedError("terminal capability is unsupported")
+
+    async def release_terminal(self, *_a: Any, **_kw: Any):  # pragma: no cover - unsupported
+        raise NotImplementedError("terminal capability is unsupported")
+
+    async def wait_for_terminal_exit(self, *_a: Any, **_kw: Any):  # pragma: no cover - unsupported
+        raise NotImplementedError("terminal capability is unsupported")
+
+    async def kill_terminal(self, *_a: Any, **_kw: Any):  # pragma: no cover - unsupported
+        raise NotImplementedError("terminal capability is unsupported")
+
+    async def ext_method(self, method: str, params: dict) -> dict:
+        return {}
+
+    async def ext_notification(self, method: str, params: dict) -> None:
+        return None
+
+    def on_connect(self, conn) -> None:  # noqa: ARG002
+        return None
+
+
+class ACPClientSession:
+    """Lifecycle wrapper around an ACP ClientSideConnection.
+
+    Constructor takes the connection + handler so tests can inject mocks. Production
+    code uses a factory (see :func:`spawn_acp_session`) that wraps acp.spawn_agent_process.
+    """
+
+    def __init__(self, handler: ACPClientHandler, conn: Any) -> None:
+        self._handler = handler
+        self._conn = conn
+        self._session_id: str | None = None
+        self.agent_capabilities: AgentCapabilities | None = None
+        self._process: asyncio.subprocess.Process | None = None  # set by spawn_acp_session
+        self._stderr_task: asyncio.Task | None = None
+        self._stderr_lines: deque[str] = deque(maxlen=_STDERR_BUFFER_LINES)
+
+    @property
+    def session_id(self) -> str | None:
+        return self._session_id
+
+    async def start(
+        self,
+        *,
+        cwd: str,
+        resume_session_id: str | None = None,
+        mcp_servers: list | None = None,
+    ) -> str:
+        init_resp = await self._conn.initialize(
+            protocol_version=PROTOCOL_VERSION,
+            client_capabilities=ClientCapabilities(
+                fs=FileSystemCapabilities(read_text_file=False, write_text_file=False),
+                terminal=False,
+            ),
+            client_info=Implementation(name="tsugite-acp", version=_plugin_version()),
+        )
+        self.agent_capabilities = init_resp.agent_capabilities
+
+        if resume_session_id:
+            await self._conn.load_session(
+                cwd=cwd,
+                session_id=resume_session_id,
+                mcp_servers=mcp_servers,
+            )
+            self._session_id = resume_session_id
+        else:
+            new_resp = await self._conn.new_session(cwd=cwd, mcp_servers=mcp_servers)
+            self._session_id = new_resp.session_id
+        return self._session_id
+
+    async def prompt(self, blocks: list) -> AsyncIterator[ACPEvent]:
+        if self._session_id is None:
+            raise RuntimeError("ACPClientSession.start() must be called before prompt()")
+
+        sentinel = object()
+        prompt_task = asyncio.create_task(self._conn.prompt(prompt=blocks, session_id=self._session_id))
+
+        async def signal_done() -> None:
+            try:
+                await prompt_task
+            except BaseException:  # noqa: BLE001 - propagate via prompt_task.exception()
+                pass
+            finally:
+                await self._handler._queue.put(sentinel)
+
+        signal_task = asyncio.create_task(signal_done())
+
+        try:
+            while True:
+                item = await self._handler._queue.get()
+                if item is sentinel:
+                    break
+                event = self._convert_update(item)
+                if event is not None:
+                    yield event
+        except BaseException:
+            prompt_task.cancel()
+            signal_task.cancel()
+            raise
+        finally:
+            try:
+                await signal_task
+            except (asyncio.CancelledError, Exception):
+                pass
+
+        exc = prompt_task.exception()
+        if exc is not None:
+            raise exc
+
+        resp = prompt_task.result()
+        stop = resp.stop_reason
+        if stop in _FATAL_STOP_REASONS:
+            raise AgentExecutionError(f"ACP agent stopped: {stop}")
+
+        yield ACPEvent(
+            kind="done",
+            stop_reason=stop,
+            usage=resp.usage.model_dump() if getattr(resp, "usage", None) else None,
+        )
+
+    @staticmethod
+    def _convert_update(update) -> ACPEvent | None:
+        if isinstance(update, AgentMessageChunk):
+            return ACPEvent(kind="text", text=update.content.text)
+        if isinstance(update, AgentThoughtChunk):
+            return ACPEvent(kind="thought", text=update.content.text)
+        return None
+
+    async def cancel(self) -> None:
+        if self._session_id is not None:
+            await self._conn.cancel(session_id=self._session_id)
+
+    async def close(self) -> None:
+        session_caps = getattr(self.agent_capabilities, "session_capabilities", None)
+        if self._session_id is not None and getattr(session_caps, "close", None) is not None:
+            try:
+                await self._conn.close_session(session_id=self._session_id)
+            except Exception as e:  # pragma: no cover - best effort shutdown
+                logger.debug("close_session failed (continuing): %s", e)
+        try:
+            await self._conn.close()
+        except Exception as e:  # pragma: no cover
+            logger.debug("conn.close failed (continuing): %s", e)
+
+        if self._stderr_task is not None:
+            self._stderr_task.cancel()
+            self._stderr_task = None
+
+        if self._process is not None:
+            try:
+                self._process.terminate()
+                await asyncio.wait_for(self._process.wait(), timeout=2.0)
+            except (ProcessLookupError, asyncio.TimeoutError):
+                try:
+                    self._process.kill()
+                except ProcessLookupError:
+                    pass
+            self._process = None
+
+
+async def spawn_acp_session(
+    *,
+    command: str,
+    args: list[str] | None = None,
+    env: dict[str, str] | None = None,
+    cwd: str | None = None,
+    policy: PermissionPolicy | None = None,
+) -> ACPClientSession:
+    """Spawn an ACP agent subprocess and wire up an ACPClientSession.
+
+    Caller is responsible for awaiting :meth:`ACPClientSession.start` to perform the
+    initialize/new_session handshake, and :meth:`ACPClientSession.close` to terminate.
+    """
+    if shutil.which(command) is None and "/" not in command:
+        raise RuntimeError(
+            f"ACP agent command {command!r} not found on PATH. "
+            "Install Node.js + npm and verify `npx --version`, or set TSUGITE_ACP_COMMAND."
+        )
+
+    process = await asyncio.create_subprocess_exec(
+        command,
+        *(args or []),
+        stdin=asyncio.subprocess.PIPE,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+        env=env,
+        cwd=cwd,
+    )
+
+    handler = ACPClientHandler(policy=policy)
+    conn = connect_to_agent(handler, process.stdin, process.stdout)
+    session = ACPClientSession(handler=handler, conn=conn)
+    session._process = process
+    session._stderr_task = asyncio.create_task(_drain_stream(process.stderr, session._stderr_lines))
+    return session
+
+
+async def _drain_stream(stream, sink: deque[str]) -> None:
+    """Read lines from a stream into a bounded sink to keep the pipe from blocking."""
+    try:
+        while True:
+            line = await stream.readline()
+            if not line:
+                break
+            sink.append(line.decode(errors="replace").rstrip())
+    except Exception:
+        pass

tsugite_acp-0.14.1/tsugite_acp/config.py

@@ -0,0 +1,65 @@
+"""Resolve the ACP agent command, env, and cwd."""
+
+from __future__ import annotations
+
+import os
+import shlex
+from dataclasses import dataclass
+from pathlib import Path
+
+DEFAULT_COMMAND: list[str] = ["npx", "-y", "@agentclientprotocol/claude-agent-acp"]
+
+
+@dataclass(frozen=True)
+class ACPCommandConfig:
+    """Resolved command, env, and cwd for spawning an ACP agent subprocess."""
+
+    command: str
+    args: list[str]
+    env: dict[str, str]
+    cwd: str | None
+
+    def argv(self) -> list[str]:
+        return [self.command, *self.args]
+
+
+def resolve_command(env_override: str | None = None, config: dict | None = None) -> ACPCommandConfig:
+    """Resolve the ACP command using this precedence:
+
+    1. `env_override` (or `TSUGITE_ACP_COMMAND`) parsed via shlex
+    2. `config["command"]` from a workspace/user config dict
+    3. `DEFAULT_COMMAND` (npx claude-agent-acp)
+    """
+    raw = env_override if env_override is not None else os.environ.get("TSUGITE_ACP_COMMAND")
+    if raw:
+        parts = shlex.split(raw)
+    elif config and config.get("command"):
+        c = config["command"]
+        parts = shlex.split(c) if isinstance(c, str) else list(c)
+    else:
+        parts = list(DEFAULT_COMMAND)
+
+    if not parts:
+        raise ValueError("ACP command resolved to empty argv")
+
+    cwd = (config or {}).get("cwd")
+    env = _build_env((config or {}).get("env"))
+    return ACPCommandConfig(command=parts[0], args=parts[1:], env=env, cwd=cwd)
+
+
+def _build_env(extra: dict | None) -> dict[str, str]:
+    """Inherit current env, then layer in any explicit entries from config."""
+    env = dict(os.environ)
+    if extra:
+        env.update({str(k): str(v) for k, v in extra.items()})
+    return env
+
+
+def workspace_cwd() -> str:
+    """Best-effort cwd: tsugite workspace dir if set, else process cwd."""
+    try:
+        from tsugite.cli.helpers import get_workspace_dir
+    except ImportError:
+        return str(Path.cwd())
+    ws = get_workspace_dir()
+    return str(ws) if ws is not None else str(Path.cwd())

tsugite_acp-0.14.1/tsugite_acp/models.py

@@ -0,0 +1,44 @@
+"""Model catalog and alias resolution for the ACP provider."""
+
+from __future__ import annotations
+
+from tsugite.providers.base import ModelInfo
+from tsugite.providers.model_registry import register_models
+
+_ACP_EFFORT_LEVELS = ["low", "medium", "high", "xhigh", "max"]
+
+
+def _model(max_input_tokens: int) -> ModelInfo:
+    return ModelInfo(
+        max_input_tokens=max_input_tokens,
+        supports_vision=True,
+        supported_effort_levels=_ACP_EFFORT_LEVELS,
+    )
+
+
+_ACP_MODELS: dict[str, ModelInfo] = {
+    "acp/claude-opus-4-7": _model(1_000_000),
+    "acp/claude-opus-4-6": _model(1_000_000),
+    "acp/claude-sonnet-4-6": _model(1_000_000),
+    "acp/claude-haiku-4-5-20251001": _model(200_000),
+}
+
+_ALIASES: dict[str, str] = {
+    "opus": "claude-opus-4-7",
+    "opus-4-7": "claude-opus-4-7",
+    "opus-4-6": "claude-opus-4-6",
+    "sonnet": "claude-sonnet-4-6",
+    "haiku": "claude-haiku-4-5-20251001",
+}
+
+
+def resolve_model_alias(model: str) -> str:
+    """Map a short alias (`opus`, `sonnet`) to a full model id; pass full ids through."""
+    if not model:
+        raise ValueError("model must be a non-empty string")
+    return _ALIASES.get(model, model)
+
+
+def register_acp_models() -> None:
+    """Register the ACP catalog into tsugite's shared model registry."""
+    register_models(_ACP_MODELS)

tsugite_acp-0.14.1/tsugite_acp/policy.py

@@ -0,0 +1,74 @@
+"""Permission policy for ACP request_permission callbacks.
+
+Rules are simple strings: ``ToolName`` for an exact match, ``ToolName(glob)`` to
+match the tool's primary string argument against a shell glob (fnmatch). For
+Bash, the primary argument is the ``command`` key; for other tools it falls back
+to the full params repr.
+"""
+
+from __future__ import annotations
+
+import fnmatch
+import logging
+import re
+from dataclasses import dataclass, field
+from typing import Literal
+
+logger = logging.getLogger(__name__)
+
+Action = Literal["allow", "deny"]
+
+_RULE_RE = re.compile(r"^(?P<tool>[A-Za-z_][A-Za-z0-9_]*)(?:\((?P<glob>.*)\))?$")
+
+
+@dataclass(frozen=True)
+class _Rule:
+    tool: str
+    glob: str | None  # None = match the tool name alone
+    action: Action
+
+
+def _parse_rule(rule: str, action: Action) -> _Rule:
+    m = _RULE_RE.match(rule.strip())
+    if not m:
+        raise ValueError(f"invalid permission rule: {rule!r}")
+    return _Rule(tool=m.group("tool"), glob=m.group("glob"), action=action)
+
+
+def _stringify_params(params: dict) -> str:
+    if "command" in params:
+        return str(params["command"])
+    return str(params)
+
+
+@dataclass
+class PermissionPolicy:
+    default: Action = "allow"
+    allow: list[str] = field(default_factory=list)
+    deny: list[str] = field(default_factory=list)
+    _rules: list[_Rule] = field(default_factory=list, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        # Deny rules evaluated first so they can override an allow.
+        self._rules = [_parse_rule(r, "deny") for r in self.deny] + [_parse_rule(r, "allow") for r in self.allow]
+
+    @classmethod
+    def from_config(cls, config: dict | None) -> "PermissionPolicy":
+        if not config:
+            return cls()
+        return cls(
+            default=config.get("default", "allow"),
+            allow=list(config.get("allow", [])),
+            deny=list(config.get("deny", [])),
+        )
+
+    def evaluate(self, tool: str, params: dict) -> Action:
+        arg_str = _stringify_params(params)
+        for rule in self._rules:
+            if rule.tool != tool:
+                continue
+            if rule.glob is None:
+                return rule.action
+            if fnmatch.fnmatchcase(arg_str, rule.glob):
+                return rule.action
+        return self.default

tsugite_acp-0.14.1/tsugite_acp/provider.py

@@ -0,0 +1,201 @@
+"""ACPProvider: routes tsugite completions through an ACP-compatible agent subprocess."""
+
+from __future__ import annotations
+
+from typing import Any, AsyncIterator, Callable
+
+from acp.schema import TextContentBlock
+
+from tsugite.providers.base import CompletionResponse, ModelInfo, StreamChunk, Usage, default_count_tokens
+from tsugite.providers.model_registry import get_model_info as _registry_get
+from tsugite_acp.client import ACPClientSession
+from tsugite_acp.config import workspace_cwd
+from tsugite_acp.models import _ALIASES, register_acp_models, resolve_model_alias
+
+register_acp_models()
+
+
+class ACPProvider:
+    """Provider backed by an ACP agent process (default: claude-agent-acp).
+
+    Stateful: the agent subprocess persists across acompletion() calls within a
+    session. First acompletion spawns and handshakes; subsequent calls reuse the
+    session. Call stop() to release the subprocess.
+    """
+
+    cacheable = False
+
+    def __init__(self, name: str = "acp", session_factory: Callable[[], ACPClientSession] | None = None):
+        self.name = name
+        self._session: ACPClientSession | None = None
+        self._session_factory = session_factory
+
+        self._attachments: list = []
+        self._skills: list = []
+        self._previous_messages: list[dict] = []
+        self._resume_session: str | None = None
+        self._resume_after_compaction: bool = False
+
+        self._session_id: str | None = None
+        self._cache_creation_tokens: int = 0
+        self._cache_read_tokens: int = 0
+        self._context_window: int | None = None
+
+    def set_context(self, **kwargs: Any) -> None:
+        self._attachments = kwargs.get("attachments", [])
+        self._skills = kwargs.get("skills", [])
+        self._previous_messages = kwargs.get("previous_messages", [])
+        self._resume_session = kwargs.get("resume_session")
+        self._resume_after_compaction = kwargs.get("resume_after_compaction", False)
+
+    def get_state(self) -> dict | None:
+        return {
+            "session_id": self._session_id,
+            "cache_creation_tokens": self._cache_creation_tokens,
+            "cache_read_tokens": self._cache_read_tokens,
+            "context_window": self._context_window,
+        }
+
+    async def stop(self) -> None:
+        if self._session is not None:
+            await self._session.close()
+            self._session = None
+
+    async def acompletion(
+        self,
+        messages: list[dict],
+        model: str,
+        stream: bool = False,
+        **_kwargs: Any,
+    ) -> CompletionResponse | AsyncIterator[StreamChunk]:
+        resolve_model_alias(model)  # validate non-empty
+
+        if self._session is None:
+            await self._spawn_session()
+            blocks = self._build_first_prompt(messages)
+        else:
+            blocks = self._latest_user_blocks(messages)
+
+        if stream:
+            return self._stream_turn(blocks)
+        return await self._collect_turn(blocks)
+
+    async def _spawn_session(self) -> None:
+        if self._session_factory is not None:
+            self._session = self._session_factory()
+        else:
+            from tsugite_acp.client import spawn_acp_session
+            from tsugite_acp.config import resolve_command
+
+            cmd = resolve_command()
+            self._session = await spawn_acp_session(
+                command=cmd.command,
+                args=cmd.args,
+                env=cmd.env,
+                cwd=cmd.cwd or workspace_cwd(),
+            )
+
+        await self._session.start(cwd=workspace_cwd(), resume_session_id=self._resume_session)
+
+    def _build_first_prompt(self, messages: list[dict]) -> list[TextContentBlock]:
+        from tsugite.attachments.base import AttachmentContentType, format_attachment_open_tag
+
+        parts: list[str] = []
+
+        include_context = not self._resume_session or self._resume_after_compaction
+        if include_context and (self._attachments or self._skills):
+            ctx: list[str] = []
+            for att in self._attachments:
+                if getattr(att, "content_type", None) != AttachmentContentType.TEXT:
+                    continue
+                ctx.append(format_attachment_open_tag(att))
+                ctx.append(att.content)
+                ctx.append("</attachment>")
+            for skill in self._skills:
+                content = getattr(skill, "content", "")
+                if len(content) > 4000:
+                    content = content[:4000] + "\n... (truncated)"
+                ctx.append(f'<skill_content name="{skill.name}">\n{content}\n</skill_content>')
+            if ctx:
+                parts.append("<context>\n" + "\n".join(ctx) + "\n</context>")
+
+        if self._previous_messages and not self._resume_session:
+            history = "\n\n".join(
+                f"{m.get('role', 'unknown').capitalize()}: {m.get('content', '')}" for m in self._previous_messages
+            )
+            parts.append(f"<conversation_history>\n{history}\n</conversation_history>")
+
+        parts.append(_extract_latest_user_text(messages))
+        text = "\n".join(p for p in parts if p)
+        return [TextContentBlock(type="text", text=text)]
+
+    @staticmethod
+    def _latest_user_blocks(messages: list[dict]) -> list[TextContentBlock]:
+        return [TextContentBlock(type="text", text=_extract_latest_user_text(messages))]
+
+    async def _collect_turn(self, blocks: list[TextContentBlock]) -> CompletionResponse:
+        accumulated = ""
+        usage = Usage()
+        async for ev in self._session.prompt(blocks):
+            if ev.kind == "text":
+                accumulated += ev.text
+            elif ev.kind == "done":
+                usage = self._extract_usage(ev.usage)
+                self._session_id = self._session.session_id
+        return CompletionResponse(content=accumulated, usage=usage, cost=0.0)
+
+    async def _stream_turn(self, blocks: list[TextContentBlock]) -> AsyncIterator[StreamChunk]:
+        usage = Usage()
+        async for ev in self._session.prompt(blocks):
+            if ev.kind == "text":
+                yield StreamChunk(content=ev.text)
+            elif ev.kind == "thought":
+                yield StreamChunk(reasoning_content=ev.text)
+            elif ev.kind == "done":
+                usage = self._extract_usage(ev.usage)
+                self._session_id = self._session.session_id
+        yield StreamChunk(content="", done=True, usage=usage, cost=0.0)
+
+    def _extract_usage(self, raw_usage: dict | None) -> Usage:
+        if not raw_usage:
+            return Usage()
+        prompt_tokens = int(raw_usage.get("input_tokens") or 0)
+        completion_tokens = int(raw_usage.get("output_tokens") or 0)
+        cache_creation = int(raw_usage.get("cache_creation_input_tokens") or 0)
+        cache_read = int(raw_usage.get("cache_read_input_tokens") or 0)
+        self._cache_creation_tokens += cache_creation
+        self._cache_read_tokens += cache_read
+        return Usage(
+            prompt_tokens=prompt_tokens,
+            completion_tokens=completion_tokens,
+            total_tokens=prompt_tokens + completion_tokens + cache_creation + cache_read,
+            cache_creation_input_tokens=cache_creation,
+            cache_read_input_tokens=cache_read,
+        )
+
+    def count_tokens(self, text: str, model: str) -> int:
+        return default_count_tokens(text, model)
+
+    def get_model_info(self, model: str) -> ModelInfo | None:
+        return _registry_get(self.name, resolve_model_alias(model))
+
+    async def list_models(self) -> list[str]:
+        return list(_ALIASES.keys())
+
+
+def _extract_latest_user_text(messages: list[dict]) -> str:
+    """Return the text of the most recent user message, flattening list-of-blocks content."""
+    for msg in reversed(messages):
+        if msg.get("role") != "user":
+            continue
+        content = msg["content"]
+        if isinstance(content, list):
+            return "\n".join(
+                b if isinstance(b, str) else b.get("text", "") for b in content if isinstance(b, (str, dict))
+            )
+        return content
+    return ""
+
+
+def create_provider(name: str = "acp", **_kwargs: Any) -> ACPProvider:
+    return ACPProvider(name=name)