agentlink-cli 0.1.0__py3-none-any.whl

connector/json_rpc.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+import asyncio
+import inspect
+import json
+import sys
+import threading
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+
+JsonRpcHandler = Callable[[Any], Any | Awaitable[Any]]
+
+
+class JsonRpcError(RuntimeError):
+    def __init__(self, code: int, message: str, data: Any = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.data = data
+
+
+class JsonRpcStdioServer:
+    def __init__(
+        self,
+        reader: asyncio.StreamReader,
+        writer: asyncio.StreamWriter,
+        handlers: dict[str, JsonRpcHandler],
+    ) -> None:
+        self.reader = reader
+        self.writer = writer
+        self.handlers = handlers
+        self._write_lock = asyncio.Lock()
+
+    async def serve_forever(self) -> None:
+        while line := await self.reader.readline():
+            await self.handle_line(line)
+
+    async def handle_line(self, line: bytes) -> None:
+        try:
+            payload = json.loads(line)
+        except json.JSONDecodeError as exc:
+            await self._write_error(None, -32700, "Parse error", {"detail": str(exc)})
+            return
+
+        if not isinstance(payload, dict):
+            await self._write_error(None, -32600, "Invalid Request")
+            return
+
+        request_id = payload.get("id")
+        method = payload.get("method")
+        if payload.get("jsonrpc") != "2.0" or not isinstance(method, str):
+            if request_id is not None:
+                await self._write_error(request_id, -32600, "Invalid Request")
+            return
+
+        handler = self.handlers.get(method)
+        if handler is None:
+            if request_id is not None:
+                await self._write_error(request_id, -32601, "Method not found")
+            return
+
+        try:
+            result = handler(payload.get("params"))
+            if inspect.isawaitable(result):
+                result = await result
+        except JsonRpcError as exc:
+            if request_id is not None:
+                await self._write_error(request_id, exc.code, exc.message, exc.data)
+            return
+        except Exception as exc:
+            if request_id is not None:
+                await self._write_error(request_id, -32000, str(exc) or exc.__class__.__name__)
+            return
+
+        if request_id is not None:
+            await self.write({"jsonrpc": "2.0", "id": request_id, "result": result})
+
+    async def notify(self, method: str, params: Any = None) -> None:
+        payload: dict[str, Any] = {"jsonrpc": "2.0", "method": method}
+        if params is not None:
+            payload["params"] = params
+        await self.write(payload)
+
+    async def write(self, payload: dict[str, Any]) -> None:
+        data = json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8") + b"\n"
+        async with self._write_lock:
+            self.writer.write(data)
+            await self.writer.drain()
+
+    async def _write_error(self, request_id: Any, code: int, message: str, data: Any = None) -> None:
+        error: dict[str, Any] = {"code": code, "message": message}
+        if data is not None:
+            error["data"] = data
+        await self.write({"jsonrpc": "2.0", "id": request_id, "error": error})
+
+
+class ThreadedStdioWriter:
+    def __init__(self, stream: Any) -> None:
+        self._stream = stream
+        self._lock = threading.Lock()
+
+    def write(self, data: bytes) -> None:
+        self._data = data
+
+    async def drain(self) -> None:
+        data = self._data
+        await asyncio.to_thread(self._write_sync, data)
+
+    def _write_sync(self, data: bytes) -> None:
+        with self._lock:
+            self._stream.write(data)
+            self._stream.flush()
+
+
+def _start_threaded_stdin_reader(reader: asyncio.StreamReader, stream: Any) -> None:
+    loop = asyncio.get_running_loop()
+
+    def read_stdin() -> None:
+        try:
+            while line := stream.readline():
+                loop.call_soon_threadsafe(reader.feed_data, line)
+        except BaseException as exc:  # noqa: BLE001 - forward fatal pipe failures into the async reader.
+            loop.call_soon_threadsafe(reader.set_exception, exc)
+            return
+        loop.call_soon_threadsafe(reader.feed_eof)
+
+    thread = threading.Thread(target=read_stdin, name="json-rpc-stdio-reader", daemon=True)
+    thread.start()
+
+
+async def open_stdio_server(handlers: dict[str, JsonRpcHandler]) -> JsonRpcStdioServer:
+    loop = asyncio.get_running_loop()
+    reader = asyncio.StreamReader()
+    if sys.platform == "win32":
+        _start_threaded_stdin_reader(reader, sys.stdin.buffer)
+        return JsonRpcStdioServer(reader, ThreadedStdioWriter(sys.stdout.buffer), handlers)  # type: ignore[arg-type]
+
+    reader_protocol = asyncio.StreamReaderProtocol(reader)
+    await loop.connect_read_pipe(lambda: reader_protocol, sys.stdin.buffer)
+    writer_transport, writer_protocol = await loop.connect_write_pipe(asyncio.streams.FlowControlMixin, sys.stdout.buffer)
+    writer = asyncio.StreamWriter(writer_transport, writer_protocol, None, loop)
+    return JsonRpcStdioServer(reader, writer, handlers)

connector/launch.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import re
+import shlex
+import shutil
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal
+
+Launcher = Literal["direct", "powershell", "cmd"]
+
+
+@dataclass(frozen=True, slots=True)
+class LaunchTarget:
+    """How to spawn a CLI agent binary on this host.
+
+    ``path`` is the user-facing / discovery path (agent.cmd, gemini.cmd, …).
+    ``exec_argv`` when set is the *actual* argv prefix used for CreateProcess
+    (e.g. resolved ``node.exe`` + ``index.js`` for Cursor), avoiding slow
+    shell wrappers on Windows.
+    """
+
+    source: str
+    path: str
+    launcher: Launcher = "direct"
+    exec_argv: tuple[str, ...] | None = None
+
+    def command(self, args: list[str] | tuple[str, ...] = ()) -> list[str]:
+        argv = list(args)
+        if self.exec_argv is not None:
+            return [*self.exec_argv, *argv]
+        if self.launcher == "powershell":
+            return [
+                _powershell_bin(),
+                "-NoProfile",
+                "-ExecutionPolicy",
+                "Bypass",
+                "-File",
+                self.path,
+                *argv,
+            ]
+        if self.launcher == "cmd":
+            # Prefer cmd.exe over PowerShell for .cmd/.bat — ~0.5–1s faster cold
+            # start, and avoids nested PowerShell when the script itself invokes PS.
+            return [_cmd_bin(), "/d", "/c", self.path, *argv]
+        return [self.path, *argv]
+
+    def report_path(self) -> str:
+        return self.path
+
+
+@dataclass(frozen=True, slots=True)
+class LaunchCommand:
+    """A user-selected executable plus arguments, without shell evaluation."""
+
+    raw: str
+    target: LaunchTarget
+    args: tuple[str, ...] = ()
+
+    def command(self, managed_args: list[str] | tuple[str, ...] = ()) -> list[str]:
+        return self.target.command([*self.args, *managed_args])
+
+    @property
+    def launch_id(self) -> str:
+        payload = json.dumps(
+            [self.target.report_path(), *self.args],
+            ensure_ascii=False,
+            separators=(",", ":"),
+        ).encode("utf-8")
+        return "codex:" + hashlib.sha256(payload).hexdigest()[:24]
+
+    def report(self, *, mode: str = "command") -> dict[str, str]:
+        return {
+            "mode": mode,
+            "command": self.raw,
+            "launchId": self.launch_id,
+            "resolvedExecutable": self.target.report_path(),
+        }
+
+
+_UNSUPPORTED_SHELL_TOKENS = {"|", "||", "&", "&&", ";", ">", ">>", "<", "<<"}
+_CMD_METACHARACTERS = frozenset('&|<>^()%!"')
+
+
+def parse_launch_command(value: str) -> LaunchCommand:
+    """Parse a frontend command as argv and resolve its executable locally.
+
+    Shell operators are deliberately rejected.  The resulting command is
+    always passed to ``create_subprocess_exec`` as an argv list.
+    """
+
+    raw = value.strip()
+    if not raw:
+        raise ValueError("launch command is empty")
+    if "\n" in raw or "\r" in raw:
+        raise ValueError("launch command must be a single line")
+    try:
+        argv = _split_command_line(raw)
+    except ValueError as exc:
+        raise ValueError(f"invalid launch command: {exc}") from exc
+    if not argv:
+        raise ValueError("launch command is empty")
+    if any(token in _UNSUPPORTED_SHELL_TOKENS for token in argv):
+        raise ValueError("shell operators are not supported; enter an executable and arguments only")
+
+    executable = expand_vars(argv[0])
+    resolved = shutil.which(executable)
+    if resolved is None and Path(executable).is_file():
+        resolved = executable
+    if resolved is None:
+        raise ValueError(f"executable not found: {argv[0]}")
+    target = launch_target("custom", resolved)
+    if target.launcher == "cmd" and any(
+        character in _CMD_METACHARACTERS
+        for token in argv[1:]
+        for character in token
+    ):
+        raise ValueError(
+            "shell metacharacters are not supported in Windows .cmd/.bat commands"
+        )
+    return LaunchCommand(raw=raw, target=target, args=tuple(argv[1:]))
+
+
+def launch_command_from_target(target: LaunchTarget, *, raw: str | None = None) -> LaunchCommand:
+    return LaunchCommand(raw=raw or target.report_path(), target=target)
+
+
+def _split_command_line(value: str) -> list[str]:
+    if sys.platform != "win32":
+        return shlex.split(value, posix=True)
+
+    # Match the parsing used by CreateProcess/CommandLineToArgvW so quoted
+    # Windows paths round-trip exactly.  Import lazily to keep Unix clean.
+    import ctypes
+    from ctypes import wintypes
+
+    argc = ctypes.c_int()
+    command_line_to_argv = ctypes.windll.shell32.CommandLineToArgvW
+    command_line_to_argv.argtypes = [wintypes.LPCWSTR, ctypes.POINTER(ctypes.c_int)]
+    command_line_to_argv.restype = ctypes.POINTER(wintypes.LPWSTR)
+    argv_ptr = command_line_to_argv(value, ctypes.byref(argc))
+    if not argv_ptr:
+        raise ValueError("Windows could not parse the command line")
+    try:
+        return [argv_ptr[index] for index in range(argc.value)]
+    finally:
+        ctypes.windll.kernel32.LocalFree(argv_ptr)
+
+
+def launch_target(source: str, path: str) -> LaunchTarget:
+    path = expand_vars(path)
+    # Cursor agent.cmd → powershell → node is extremely slow. Prefer direct node.
+    cursor_argv = _resolve_cursor_agent_exec(path)
+    if cursor_argv is not None:
+        return LaunchTarget(
+            source=source,
+            path=path,
+            launcher="direct",
+            exec_argv=cursor_argv,
+        )
+
+    launcher: Launcher = "direct"
+    if sys.platform == "win32":
+        suffix = Path(path).suffix.lower()
+        if suffix == ".ps1":
+            launcher = "powershell"
+        elif suffix in {".cmd", ".bat"}:
+            launcher = "cmd"
+    return LaunchTarget(source=source, path=path, launcher=launcher)
+
+
+def command_name(name: str) -> LaunchTarget | None:
+    found = shutil.which(name)
+    if not found:
+        return None
+    return launch_target("cli", found)
+
+
+def existing_launch_targets(candidates: list[tuple[str, str]]) -> list[LaunchTarget]:
+    seen: set[str] = set()
+    out: list[LaunchTarget] = []
+    for source, raw in candidates:
+        path = expand_vars(raw)
+        if not path or path in seen:
+            continue
+        seen.add(path)
+        out.append(launch_target(source, path))
+    return out
+
+
+def expand_vars(value: str) -> str:
+    return os.path.expandvars(os.path.expanduser(value))
+
+
+def path_exists_for_launch(path: str) -> bool:
+    if not Path(path).is_file():
+        return False
+    if sys.platform == "win32":
+        return True
+    return os.access(path, os.X_OK)
+
+
+def _resolve_cursor_agent_exec(path: str) -> tuple[str, ...] | None:
+    """If *path* is a Cursor agent shim, return ``(node.exe, index.js)``.
+
+    Official Windows install layout::
+
+        %LOCALAPPDATA%/cursor-agent/agent.cmd
+          → powershell → cursor-agent.ps1
+            → versions/<ver>/node.exe versions/<ver>/index.js
+
+    Spawning node directly cuts multi-second PowerShell cold-start cost that
+    previously caused ACP ``initialize`` timeouts.
+    """
+    try:
+        p = Path(path)
+    except Exception:
+        return None
+    name = p.name.lower()
+    if name not in {"agent.cmd", "agent.ps1", "cursor-agent.cmd", "cursor-agent.ps1", "agent.exe"}:
+        # Only resolve known Cursor install shims / paths under cursor-agent.
+        if "cursor-agent" not in str(p).lower().replace("\\", "/"):
+            return None
+        if name not in {"agent", "cursor-agent"} and not name.startswith("agent"):
+            return None
+
+    # Locate install root (directory containing versions/ or node.exe).
+    candidates: list[Path] = []
+    if p.is_file():
+        candidates.append(p.parent)
+        candidates.append(p.parent.parent)
+    elif p.is_dir():
+        candidates.append(p)
+
+    local = os.environ.get("LOCALAPPDATA")
+    if local:
+        candidates.append(Path(local) / "cursor-agent")
+
+    for root in candidates:
+        resolved = _cursor_node_from_root(root)
+        if resolved is not None:
+            return resolved
+    return None
+
+
+_CURSOR_VERSION_RE = re.compile(r"^\d{4}\.\d{1,2}\.\d{1,2}-.+$")
+
+
+def _cursor_node_from_root(root: Path) -> tuple[str, ...] | None:
+    if not root.is_dir():
+        return None
+    # Same-dir layout (dev / unpacked)
+    local_node = root / "node.exe"
+    local_index = root / "index.js"
+    if local_node.is_file() and local_index.is_file():
+        return (str(local_node), str(local_index))
+
+    versions = root / "versions"
+    if not versions.is_dir():
+        return None
+
+    version_dirs = [
+        d
+        for d in versions.iterdir()
+        if d.is_dir() and _CURSOR_VERSION_RE.match(d.name)
+    ]
+    if not version_dirs:
+        return None
+
+    def _sort_key(d: Path) -> tuple[int, str]:
+        # YYYY.MM.DD-... → integer date for newest-first
+        date_part = d.name.split("-", 1)[0]
+        parts = date_part.split(".")
+        try:
+            y, m, day = int(parts[0]), int(parts[1]), int(parts[2])
+            return (y * 10000 + m * 100 + day, d.name)
+        except (ValueError, IndexError):
+            return (0, d.name)
+
+    latest = max(version_dirs, key=_sort_key)
+    node = latest / "node.exe"
+    index = latest / "index.js"
+    if node.is_file() and index.is_file():
+        return (str(node), str(index))
+    return None
+
+
+def _cmd_quote(value: str) -> str:
+    escaped = value.replace('"', r'\"')
+    return f'"{escaped}"'
+
+
+def _powershell_quote(value: str) -> str:
+    return "'" + value.replace("'", "''") + "'"
+
+
+def _powershell_bin() -> str:
+    return shutil.which("powershell.exe") or shutil.which("powershell") or "powershell.exe"
+
+
+def _cmd_bin() -> str:
+    return (
+        shutil.which("cmd.exe")
+        or shutil.which("cmd")
+        or os.path.join(os.environ.get("SystemRoot", r"C:\Windows"), "System32", "cmd.exe")
+    )

connector/local/__init__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from connector.local.common import StaleFileError
+from connector.local.ops import LocalOps, create_local_ops
+
+__all__ = ["LocalOps", "StaleFileError", "create_local_ops"]

connector/local/common.py

@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+import time
+from pathlib import Path
+from typing import Any, Awaitable, Callable
+
+
+MAX_DIR_ENTRIES = 500
+MAX_OUTPUT_CHARS = 64_000
+MAX_READ_TEXT_BYTES = 4 * 1024 * 1024
+
+Notify = Callable[[str, dict[str, Any]], Awaitable[None]]
+
+
+class StaleFileError(Exception):
+    """Raised when fs.writeFile's ifMatch check fails."""
+
+    code = "stale"
+
+
+def workspace_root(params: dict[str, Any]) -> Path:
+    raw_root = params.get("root") or params.get("cwd")
+    if not isinstance(raw_root, str) or not raw_root.strip():
+        raise ValueError("root is required")
+    return Path(raw_root).expanduser().resolve(strict=False)
+
+
+def resolve_path(root: Path, raw_path: str) -> Path:
+    path = Path(raw_path).expanduser()
+    if not path.is_absolute():
+        path = root / path
+    return path.resolve(strict=False)
+
+
+def nearest_existing_dir(path: Path, *, fallback: Path | None = None) -> Path:
+    """Return `path` if it is a directory, otherwise the closest existing parent.
+
+    Workspace paths can point at projects that were deleted or moved after a
+    session was recorded. Runtime panels should still open somewhere useful
+    instead of failing on a stale cwd/path.
+    """
+    current = path
+    while True:
+        if current.is_dir():
+            return current
+        parent = current.parent
+        if parent == current:
+            break
+        current = parent
+    if fallback is not None:
+        fallback_current = fallback
+        while True:
+            if fallback_current.is_dir():
+                return fallback_current
+            parent = fallback_current.parent
+            if parent == fallback_current:
+                break
+            fallback_current = parent
+    return Path.cwd()
+
+
+def required_string(params: dict[str, Any], key: str) -> str:
+    value = params.get(key)
+    if not isinstance(value, str) or not value:
+        raise ValueError(f"{key} is required")
+    return value
+
+
+def required_text(params: dict[str, Any], key: str) -> str:
+    value = params.get(key)
+    if not isinstance(value, str):
+        raise ValueError(f"{key} is required")
+    return value
+
+
+def required_int(params: dict[str, Any], key: str) -> int:
+    value = params.get(key)
+    if not isinstance(value, int):
+        raise ValueError(f"{key} is required")
+    return value
+
+
+def encoding(params: dict[str, Any]) -> str:
+    value = params.get("encoding", "utf8")
+    if value not in {"utf8", "utf-8"}:
+        raise ValueError("only utf8 encoding is supported")
+    return "utf-8"
+
+
+def decode_output(output: bytes) -> tuple[str, bool]:
+    text = output.decode("utf-8", errors="replace")
+    if len(text) <= MAX_OUTPUT_CHARS:
+        return text, False
+    return text[:MAX_OUTPUT_CHARS], True
+
+
+def shell_result(
+    cwd: Path,
+    command: str,
+    exit_code: int | None,
+    timed_out: bool,
+    start: float,
+    stdout: bytes,
+    stderr: bytes,
+) -> dict[str, Any]:
+    stdout_text, stdout_truncated = decode_output(stdout)
+    stderr_text, stderr_truncated = decode_output(stderr)
+    return {
+        "cwd": str(cwd),
+        "command": command,
+        "exitCode": exit_code,
+        "timedOut": timed_out,
+        "durationMs": int((time.monotonic() - start) * 1000),
+        "stdout": stdout_text,
+        "stderr": stderr_text,
+        "stdoutTruncated": stdout_truncated,
+        "stderrTruncated": stderr_truncated,
+    }