aicortexpy 0.1.0__py3-none-any.whl

aicortexpy/acp_conn.py

@@ -0,0 +1,853 @@
+"""Long-lived / one-shot ACP connections for Cursor, Kiro, Hermes, Kimi, Dsh."""
+
+from __future__ import annotations
+
+import logging
+import os
+import shutil
+import subprocess
+import sys
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Callable, Protocol
+
+from .acp_client import (
+    ACPClient,
+    PromptResult,
+    dsh_tool_name,
+    extract_session_id,
+    hermes_tool_name_from_title,
+    kimi_tool_name,
+    kiro_tool_name,
+    resolve_resumed_session_id,
+)
+from .acp_errors import ACPProviderErrorSniffer, promote_acp_result_on_provider_error
+from .procutil import kill_process_tree, popen_kwargs_for_killable_group
+
+log = logging.getLogger("aicortexpy.acp")
+
+HANDSHAKE_TIMEOUT = 120.0
+PROMPT_TIMEOUT = 20 * 60.0
+STDOUT_MAX_LINE = 10 * 1024 * 1024  # match Go scanner max token
+
+MessageCB = Callable[[dict[str, Any]], None]
+
+
+@dataclass
+class ACPPromptResult:
+    status: str
+    output: str
+    error: str = ""
+    session_id: str = ""
+    usage: dict[str, int] | None = None
+    duration_ms: int = 0
+    messages: list[dict[str, Any]] = field(default_factory=list)
+
+
+class ACPChatConn(Protocol):
+    def session_id(self) -> str: ...
+    def run_prompt(
+        self,
+        prompt: str,
+        *,
+        timeout: float = PROMPT_TIMEOUT,
+        system_prompt: str = "",
+        on_message: MessageCB | None = None,
+    ) -> ACPPromptResult: ...
+    def close(self) -> None: ...
+
+
+ACP_ONESHOT_PROVIDERS = frozenset({"kiro", "hermes", "kimi", "dsh"})
+
+
+def cursor_acp_supported(executable: str) -> bool:
+    # Go probes `acp --help` without yolo flags.
+    return _acp_help_ok(executable or "cursor-agent", extra_before=["acp", "--help"])
+
+
+def kiro_acp_supported(executable: str) -> bool:
+    return _acp_help_ok(executable or "kiro-cli", extra_before=["acp", "--help"])
+
+
+def _acp_help_ok(executable: str, *, extra_before: list[str]) -> bool:
+    path = shutil.which(executable) or executable
+    args = [path, *extra_before]
+    try:
+        proc = subprocess.run(
+            args,
+            capture_output=True,
+            timeout=5,
+            check=False,
+            **_hide_window(),
+        )
+        return proc.returncode == 0
+    except (OSError, subprocess.TimeoutExpired):
+        return False
+
+
+def _hide_window() -> dict:
+    if sys.platform != "win32":
+        return {}
+    startup = subprocess.STARTUPINFO()
+    startup.dwFlags |= subprocess.STARTF_USESHOWWINDOW
+    return {"startupinfo": startup}
+
+
+def choose_cursor_invocation(executable: str, args: list[str]) -> tuple[str, list[str]]:
+    """On Windows, route cursor-agent.cmd/.bat through powershell -File .ps1.
+
+    Matches Go chooseCursorInvocation — avoids cmd.exe %* mangling long argv.
+    """
+    path = shutil.which(executable) or executable
+    if sys.platform != "win32":
+        return path, args
+    ext = Path(path).suffix.lower()
+    if ext not in (".cmd", ".bat"):
+        return path, args
+    ps1 = Path(path).with_name("cursor-agent.ps1")
+    if not ps1.is_file():
+        return path, args
+    ps_exe = ""
+    for name in ("pwsh.exe", "powershell.exe"):
+        found = shutil.which(name)
+        if found:
+            ps_exe = found
+            break
+    if not ps_exe:
+        root = os.environ.get("SystemRoot") or r"C:\Windows"
+        candidate = Path(root) / "System32" / "WindowsPowerShell" / "v1.0" / "powershell.exe"
+        if candidate.is_file():
+            ps_exe = str(candidate)
+    if not ps_exe:
+        return path, args
+    log.info(
+        "cursor-agent: routing through powershell -File to preserve argv tokens ps1=%s",
+        ps1,
+    )
+    return ps_exe, ["-NoProfile", "-ExecutionPolicy", "Bypass", "-File", str(ps1), *args]
+
+
+def _filter_blocked(custom_args: list[str], blocked: set[str], value_flags: set[str] | None = None) -> list[str]:
+    value_flags = value_flags or set()
+    out: list[str] = []
+    skip_next = False
+    for a in custom_args:
+        if skip_next:
+            skip_next = False
+            continue
+        if a in blocked:
+            if a in value_flags or a in ("--sandbox", "--trust-tools", "--profile", "-p"):
+                skip_next = True
+            continue
+        out.append(a)
+    return out
+
+
+class _BaseACPConn:
+    provider: str = ""
+    dual_prompt_fields: bool = False  # kiro: send content + prompt
+    model_via_config_option: bool = False  # dsh
+    require_set_model: bool = False  # cursor / kiro pooled Open
+    soft_set_model: bool = False
+    resume_method: str = "session/load"  # kimi uses session/resume
+    resume_include_mcp: bool = True
+
+    def __init__(self) -> None:
+        self._proc: subprocess.Popen[bytes] | None = None
+        self._client: ACPClient | None = None
+        self._session_id = ""
+        self._model = ""
+        self._closed = False
+        self._reader_done = threading.Event()
+        self._stderr_done = threading.Event()
+        self._lock = threading.Lock()
+        self._sniffer: ACPProviderErrorSniffer | None = None
+        self._stdin_text = None
+
+    def session_id(self) -> str:
+        return self._session_id
+
+    def close(self) -> None:
+        with self._lock:
+            if self._closed:
+                return
+            self._closed = True
+            client = self._client
+            proc = self._proc
+            self._client = None
+            self._proc = None
+        if self._stdin_text is not None:
+            try:
+                self._stdin_text.close()
+            except OSError:
+                pass
+        if proc and proc.pid:
+            kill_process_tree(proc.pid)
+            try:
+                proc.wait(timeout=5)
+            except Exception:
+                pass
+        self._reader_done.wait(timeout=5)
+        self._stderr_done.wait(timeout=5)
+        if client:
+            client.close_all_pending(RuntimeError(f"{self.provider} acp connection closed"))
+
+    def run_prompt(
+        self,
+        prompt: str,
+        *,
+        timeout: float = PROMPT_TIMEOUT,
+        system_prompt: str = "",
+        on_message: MessageCB | None = None,
+        idle_watchdog: float = 0,
+        cancel_event: threading.Event | None = None,
+    ) -> ACPPromptResult:
+        if self._closed or not self._client or not self._session_id:
+            return ACPPromptResult(
+                status="failed",
+                output="",
+                error=f"{self.provider} acp connection closed",
+            )
+        client = self._client
+        output_parts: list[str] = []
+        messages: list[dict[str, Any]] = []
+        prompt_done = threading.Event()
+        done_result: list[PromptResult] = []
+        streaming = {"on": False}
+        last_activity = {"t": time.time()}
+        in_flight_tools = {"n": 0}
+
+        def emit(msg: dict[str, Any]) -> None:
+            if not streaming["on"]:
+                return
+            last_activity["t"] = time.time()
+            typ = msg.get("type")
+            if typ == "text":
+                output_parts.append(str(msg.get("content") or ""))
+            elif typ == "tool-use":
+                in_flight_tools["n"] += 1
+            elif typ == "tool-result":
+                in_flight_tools["n"] = max(0, in_flight_tools["n"] - 1)
+            messages.append(msg)
+            if on_message:
+                try:
+                    on_message(msg)
+                except Exception as e:
+                    log.debug("on_message failed: %s", e)
+
+        def on_prompt_done(pr: PromptResult) -> None:
+            if not streaming["on"]:
+                return
+            last_activity["t"] = time.time()
+            done_result.append(pr)
+            prompt_done.set()
+
+        prev_msg, prev_done, prev_accept = (
+            client.on_message,
+            client.on_prompt_done,
+            client.accept_notification,
+        )
+        client.on_message = emit
+        client.on_prompt_done = on_prompt_done
+        client.accept_notification = lambda _t: streaming["on"]
+
+        user_text = prompt
+        if system_prompt:
+            user_text = system_prompt + "\n\n---\n\n" + prompt
+        blocks = [{"type": "text", "text": user_text}]
+        params: dict[str, Any] = {
+            "sessionId": self._session_id,
+            "prompt": blocks,
+        }
+        if self.dual_prompt_fields:
+            params["content"] = blocks
+
+        # Go pooled RunPrompt caps at 20 minutes regardless of AgentTimeout.
+        if timeout <= 0 or timeout > PROMPT_TIMEOUT:
+            timeout = PROMPT_TIMEOUT
+
+        start = time.time()
+        status = "completed"
+        error = ""
+        stop_watch = threading.Event()
+
+        def _watch() -> None:
+            while not stop_watch.wait(0.25):
+                if cancel_event is not None and cancel_event.is_set():
+                    try:
+                        self.close()
+                    except Exception:
+                        pass
+                    return
+                if idle_watchdog > 0 and streaming["on"]:
+                    silent = time.time() - last_activity["t"]
+                    if silent >= idle_watchdog and in_flight_tools["n"] == 0:
+                        log.warning(
+                            "%s acp idle watchdog fired after %.0fs",
+                            self.provider,
+                            idle_watchdog,
+                        )
+                        try:
+                            self.close()
+                        except Exception:
+                            pass
+                        return
+
+        watcher = threading.Thread(target=_watch, name=f"{self.provider}-acp-watch", daemon=True)
+        watcher.start()
+
+        try:
+            with client._usage_lock:
+                client.usage.input_tokens = 0
+                client.usage.output_tokens = 0
+                client.usage.cache_read_tokens = 0
+            streaming["on"] = True
+            last_activity["t"] = time.time()
+            client.request("session/prompt", params, timeout=timeout)
+            prompt_done.wait(timeout=0.05)
+            if done_result and done_result[0].stop_reason == "cancelled":
+                status = "aborted"
+                error = f"{self.provider} acp cancelled the prompt"
+        except TimeoutError:
+            status = "timeout"
+            error = f"{self.provider} acp timed out after {timeout:.0f}s"
+        except Exception as e:
+            if cancel_event is not None and cancel_event.is_set():
+                status = "aborted"
+                error = "cancelled"
+            elif idle_watchdog > 0 and (time.time() - last_activity["t"]) >= idle_watchdog:
+                status = "idle_watchdog"
+                error = f"{self.provider} acp idle for {idle_watchdog:.0f}s"
+            else:
+                status = "failed"
+                error = f"{self.provider} acp session/prompt failed: {e}"
+        finally:
+            streaming["on"] = False
+            stop_watch.set()
+            watcher.join(timeout=1)
+            client.on_message = prev_msg
+            client.on_prompt_done = prev_done
+            client.accept_notification = prev_accept
+
+        # Drain stderr sniffer before promote (Go joins stderrDone).
+        self._stderr_done.wait(timeout=2)
+        output = "".join(output_parts)
+        status, error = promote_acp_result_on_provider_error(
+            status, error, output, self._sniffer
+        )
+
+        usage = None
+        with client._usage_lock:
+            u = client.usage
+        if done_result:
+            u.input_tokens += done_result[0].usage.input_tokens
+            u.output_tokens += done_result[0].usage.output_tokens
+            u.cache_read_tokens += done_result[0].usage.cache_read_tokens
+        if u.input_tokens or u.output_tokens or u.cache_read_tokens:
+            usage = {
+                "input_tokens": u.input_tokens,
+                "output_tokens": u.output_tokens,
+                "cache_read_tokens": u.cache_read_tokens,
+            }
+        return ACPPromptResult(
+            status=status,
+            output=output,
+            error=error,
+            session_id=self._session_id,
+            usage=usage,
+            duration_ms=int((time.time() - start) * 1000),
+            messages=messages,
+        )
+
+    def _start_process(
+        self,
+        argv: list[str],
+        cwd: str,
+        env: dict[str, str] | None,
+        *,
+        tool_name_fn: Callable[[str, str], str],
+    ) -> None:
+        kwargs = popen_kwargs_for_killable_group()
+        kwargs.update(_hide_window())
+        self._sniffer = ACPProviderErrorSniffer(self.provider)
+        # Binary pipes + manual decode so we can raise the line-size limit.
+        self._proc = subprocess.Popen(
+            argv,
+            stdin=subprocess.PIPE,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            cwd=cwd or None,
+            env=env,
+            bufsize=0,
+            **kwargs,
+        )
+        assert self._proc.stdin and self._proc.stdout and self._proc.stderr
+        import io
+
+        self._stdin_text = io.TextIOWrapper(
+            self._proc.stdin,
+            encoding="utf-8",
+            errors="replace",
+            write_through=True,
+            line_buffering=True,
+        )
+        self._client = ACPClient(self._stdin_text, tool_name_fn=tool_name_fn)
+        threading.Thread(target=self._read_stdout, name=f"{self.provider}-acp-out", daemon=True).start()
+        threading.Thread(target=self._read_stderr, name=f"{self.provider}-acp-err", daemon=True).start()
+        log.info("%s acp started pid=%s cwd=%s", self.provider, self._proc.pid, cwd)
+
+    def _read_stdout(self) -> None:
+        try:
+            assert self._proc and self._proc.stdout and self._client
+            buf = b""
+            while True:
+                chunk = self._proc.stdout.read(65536)
+                if not chunk:
+                    break
+                buf += chunk
+                while True:
+                    nl = buf.find(b"\n")
+                    if nl < 0:
+                        if len(buf) > STDOUT_MAX_LINE:
+                            log.warning(
+                                "%s acp stdout line exceeded %s bytes; dropping",
+                                self.provider,
+                                STDOUT_MAX_LINE,
+                            )
+                            buf = b""
+                        break
+                    line = buf[:nl].decode("utf-8", errors="replace")
+                    buf = buf[nl + 1 :]
+                    self._client.handle_line(line)
+        except Exception as e:
+            log.debug("%s acp stdout reader ended: %s", self.provider, e)
+        finally:
+            if self._client:
+                self._client.close_all_pending(
+                    RuntimeError(f"{self.provider} acp process exited")
+                )
+            self._reader_done.set()
+
+    def _read_stderr(self) -> None:
+        try:
+            assert self._proc and self._proc.stderr
+            while True:
+                chunk = self._proc.stderr.read(4096)
+                if not chunk:
+                    break
+                if self._sniffer:
+                    self._sniffer.write(chunk)
+                text = chunk.decode("utf-8", errors="replace")
+                for line in text.splitlines():
+                    line = line.rstrip()
+                    if line:
+                        log.info("[%s:acp:stderr] %s", self.provider, line)
+        except Exception:
+            pass
+        finally:
+            self._stderr_done.set()
+
+    def _handshake(
+        self,
+        *,
+        cwd: str,
+        model: str,
+        resume_session_id: str,
+        allow_resume: bool,
+        handshake_timeout: float,
+        hard_fail_resume: bool = False,
+    ) -> None:
+        assert self._client
+        self._client.request(
+            "initialize",
+            {
+                "protocolVersion": 1,
+                "clientInfo": {"name": "aicortex-agent-sdk", "version": "0.2.0"},
+                "clientCapabilities": {},
+            },
+            timeout=handshake_timeout,
+        )
+        session_id = ""
+        if allow_resume and resume_session_id:
+            try:
+                resume_params: dict[str, Any] = {
+                    "cwd": cwd,
+                    "sessionId": resume_session_id,
+                }
+                if self.resume_include_mcp:
+                    resume_params["mcpServers"] = []
+                result = self._client.request(
+                    self.resume_method,
+                    resume_params,
+                    timeout=handshake_timeout,
+                )
+                session_id, changed = resolve_resumed_session_id(resume_session_id, result)
+                if changed:
+                    log.warning(
+                        "%s acp resume returned different session id requested=%s actual=%s",
+                        self.provider,
+                        resume_session_id,
+                        session_id,
+                    )
+            except Exception as e:
+                if hard_fail_resume or self.provider == "kiro":
+                    self.close()
+                    raise RuntimeError(
+                        f"{self.provider} acp {self.resume_method} failed: {e}"
+                    ) from e
+                log.warning(
+                    "%s acp %s failed, opening new session: %s",
+                    self.provider,
+                    self.resume_method,
+                    e,
+                )
+                session_id = ""
+        if not session_id:
+            result = self._client.request(
+                "session/new",
+                {"cwd": cwd, "mcpServers": []},
+                timeout=handshake_timeout,
+            )
+            session_id = extract_session_id(result)
+            if not session_id:
+                self.close()
+                raise RuntimeError(f"{self.provider} acp session/new returned no session ID")
+        self._session_id = session_id
+        self._client.session_id = session_id
+        self._model = model
+        log.info("%s acp session ready session_id=%s", self.provider, session_id)
+        if not model:
+            return
+        try:
+            if self.model_via_config_option:
+                self._client.request(
+                    "session/set_config_option",
+                    {"sessionId": session_id, "configId": "model", "value": model},
+                    timeout=handshake_timeout,
+                )
+            else:
+                self._client.request(
+                    "session/set_model",
+                    {"sessionId": session_id, "modelId": model},
+                    timeout=handshake_timeout,
+                )
+        except Exception as e:
+            if self.soft_set_model:
+                log.debug("%s acp set_model skipped: %s", self.provider, e)
+                return
+            self.close()
+            raise RuntimeError(f"{self.provider} acp set model failed: {e}") from e
+
+
+class CursorACPConn(_BaseACPConn):
+    provider = "cursor"
+    require_set_model = True
+
+    @classmethod
+    def open(
+        cls,
+        executable: str,
+        *,
+        cwd: str,
+        model: str = "",
+        resume_session_id: str = "",
+        custom_args: list[str] | None = None,
+        timeout: float = 0,
+        env: dict[str, str] | None = None,
+        allow_resume: bool = False,
+    ) -> CursorACPConn:
+        path = shutil.which(executable) or executable
+        blocked = {"acp", "--yolo", "--force", "--sandbox", "--trust"}
+        filtered = _filter_blocked(list(custom_args or []), blocked, {"--sandbox"})
+        acp_args = ["--yolo", "--trust", "--sandbox", "disabled", "acp", *filtered]
+        argv0, cmd_args = choose_cursor_invocation(path, acp_args)
+        argv = [argv0, *cmd_args]
+        conn = cls()
+        work = cwd or str(Path.cwd())
+        conn._start_process(argv, work, env, tool_name_fn=hermes_tool_name_from_title)
+        hs = HANDSHAKE_TIMEOUT
+        if timeout > 0:
+            hs = min(hs, timeout)
+        try:
+            conn._handshake(
+                cwd=work,
+                model=model,
+                resume_session_id=resume_session_id,
+                allow_resume=allow_resume,
+                handshake_timeout=hs,
+            )
+        except Exception:
+            conn.close()
+            raise
+        return conn
+
+
+class KiroACPConn(_BaseACPConn):
+    provider = "kiro"
+    dual_prompt_fields = True
+    require_set_model = True
+
+    @classmethod
+    def open(
+        cls,
+        executable: str,
+        *,
+        cwd: str,
+        model: str = "",
+        resume_session_id: str = "",
+        custom_args: list[str] | None = None,
+        timeout: float = 0,
+        env: dict[str, str] | None = None,
+    ) -> KiroACPConn:
+        path = shutil.which(executable) or executable
+        blocked = {"acp", "-a", "--trust-all-tools", "--trust-tools"}
+        filtered = _filter_blocked(
+            list(custom_args or []), blocked, {"--trust-tools"}
+        )
+        argv = [path, "acp", "--trust-all-tools", *filtered]
+        conn = cls()
+        work = cwd or str(Path.cwd())
+        conn._start_process(argv, work, env, tool_name_fn=kiro_tool_name)
+        hs = timeout if timeout > 0 else HANDSHAKE_TIMEOUT
+        try:
+            conn._handshake(
+                cwd=work,
+                model=model,
+                resume_session_id=resume_session_id,
+                allow_resume=True,
+                handshake_timeout=hs,
+                hard_fail_resume=True,
+            )
+        except Exception:
+            conn.close()
+            raise
+        return conn
+
+
+class HermesACPConn(_BaseACPConn):
+    provider = "hermes"
+    soft_set_model = True
+
+    @classmethod
+    def open(
+        cls,
+        executable: str,
+        *,
+        cwd: str,
+        model: str = "",
+        resume_session_id: str = "",
+        custom_args: list[str] | None = None,
+        timeout: float = 0,
+        env: dict[str, str] | None = None,
+    ) -> HermesACPConn:
+        path = shutil.which(executable) or executable
+        filtered = _filter_blocked(list(custom_args or []), {"acp"})
+        argv = [path, "acp", *filtered]
+        conn = cls()
+        work = cwd or str(Path.cwd())
+        environ = dict(env or {})
+        environ.setdefault("HERMES_YOLO_MODE", "1")
+        conn._start_process(argv, work, environ, tool_name_fn=hermes_tool_name_from_title)
+        hs = timeout if timeout > 0 else HANDSHAKE_TIMEOUT
+        try:
+            conn._handshake(
+                cwd=work,
+                model=model,
+                resume_session_id=resume_session_id,
+                allow_resume=True,
+                handshake_timeout=hs,
+            )
+        except Exception:
+            conn.close()
+            raise
+        return conn
+
+
+class KimiACPConn(_BaseACPConn):
+    provider = "kimi"
+    soft_set_model = True
+    resume_method = "session/resume"
+    resume_include_mcp = False
+
+    @classmethod
+    def open(
+        cls,
+        executable: str,
+        *,
+        cwd: str,
+        model: str = "",
+        resume_session_id: str = "",
+        custom_args: list[str] | None = None,
+        timeout: float = 0,
+        env: dict[str, str] | None = None,
+    ) -> KimiACPConn:
+        path = shutil.which(executable) or executable
+        filtered = _filter_blocked(list(custom_args or []), {"acp"})
+        argv = [path, "acp", *filtered]
+        conn = cls()
+        work = cwd or str(Path.cwd())
+        conn._start_process(argv, work, env, tool_name_fn=kimi_tool_name)
+        hs = timeout if timeout > 0 else HANDSHAKE_TIMEOUT
+        try:
+            conn._handshake(
+                cwd=work,
+                model=model,
+                resume_session_id=resume_session_id,
+                allow_resume=True,
+                handshake_timeout=hs,
+            )
+        except Exception:
+            conn.close()
+            raise
+        return conn
+
+
+class DshACPConn(_BaseACPConn):
+    provider = "dsh"
+    model_via_config_option = True
+    require_set_model = True
+
+    @classmethod
+    def open(
+        cls,
+        executable: str,
+        *,
+        cwd: str,
+        model: str = "",
+        resume_session_id: str = "",
+        custom_args: list[str] | None = None,
+        timeout: float = 0,
+        env: dict[str, str] | None = None,
+    ) -> DshACPConn:
+        path = shutil.which(executable) or executable
+        filtered = _filter_blocked(
+            list(custom_args or []), {"--profile", "-p"}, {"--profile", "-p"}
+        )
+        argv = [path, "--profile", "acp", *filtered]
+        conn = cls()
+        work = cwd or str(Path.cwd())
+        conn._start_process(argv, work, env, tool_name_fn=dsh_tool_name)
+        hs = timeout if timeout > 0 else HANDSHAKE_TIMEOUT
+        try:
+            conn._handshake(
+                cwd=work,
+                model=model,
+                resume_session_id=resume_session_id,
+                allow_resume=True,
+                handshake_timeout=hs,
+            )
+        except Exception:
+            conn.close()
+            raise
+        return conn
+
+
+def open_acp_conn(
+    provider: str,
+    executable: str,
+    *,
+    cwd: str,
+    model: str = "",
+    resume_session_id: str = "",
+    custom_args: list[str] | None = None,
+    timeout: float = 0,
+    env: dict[str, str] | None = None,
+) -> _BaseACPConn:
+    if provider == "cursor":
+        return CursorACPConn.open(
+            executable,
+            cwd=cwd,
+            model=model,
+            resume_session_id=resume_session_id,
+            custom_args=custom_args,
+            timeout=timeout,
+            env=env,
+            allow_resume=False,
+        )
+    if provider == "kiro":
+        return KiroACPConn.open(
+            executable,
+            cwd=cwd,
+            model=model,
+            resume_session_id=resume_session_id,
+            custom_args=custom_args,
+            timeout=timeout,
+            env=env,
+        )
+    if provider == "hermes":
+        return HermesACPConn.open(
+            executable,
+            cwd=cwd,
+            model=model,
+            resume_session_id=resume_session_id,
+            custom_args=custom_args,
+            timeout=timeout,
+            env=env,
+        )
+    if provider == "kimi":
+        return KimiACPConn.open(
+            executable,
+            cwd=cwd,
+            model=model,
+            resume_session_id=resume_session_id,
+            custom_args=custom_args,
+            timeout=timeout,
+            env=env,
+        )
+    if provider == "dsh":
+        return DshACPConn.open(
+            executable,
+            cwd=cwd,
+            model=model,
+            resume_session_id=resume_session_id,
+            custom_args=custom_args,
+            timeout=timeout,
+            env=env,
+        )
+    raise RuntimeError(f"unsupported acp provider {provider!r}")
+
+
+def run_acp_oneshot(
+    provider: str,
+    executable: str,
+    *,
+    cwd: str,
+    prompt: str,
+    model: str = "",
+    resume_session_id: str = "",
+    custom_args: list[str] | None = None,
+    timeout: float = 0,
+    env: dict[str, str] | None = None,
+    system_prompt: str = "",
+    on_message: MessageCB | None = None,
+    cancel_event: threading.Event | None = None,
+    idle_watchdog: float = 0,
+) -> ACPPromptResult:
+    """One-shot ACP turn (open → prompt → close). Used for non-chat kiro/hermes/kimi/dsh."""
+    t = timeout if timeout > 0 else PROMPT_TIMEOUT
+    try:
+        conn = open_acp_conn(
+            provider,
+            executable,
+            cwd=cwd,
+            model=model,
+            resume_session_id=resume_session_id,
+            custom_args=custom_args,
+            timeout=t,
+            env=env,
+        )
+    except Exception as e:
+        return ACPPromptResult(status="failed", output="", error=f"{provider} acp open failed: {e}")
+    try:
+        return conn.run_prompt(
+            prompt,
+            timeout=t,
+            system_prompt=system_prompt,
+            on_message=on_message,
+            idle_watchdog=idle_watchdog,
+            cancel_event=cancel_event,
+        )
+    finally:
+        conn.close()