agentlink-cli 0.1.0__py3-none-any.whl

connector/acp/config_options.py

@@ -0,0 +1,175 @@
+"""Helpers for ACP session configOptions → AA runtime schema options."""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def extract_model_options(config_options: list[dict[str, Any]] | None) -> list[dict[str, str]]:
+    """Return [{value, label}, ...] from ACP configOptions model category."""
+    option = find_config_option(config_options, category="model", preferred_ids=("model", "llm", "models"))
+    if option is None:
+        return []
+    values = option.get("options") if isinstance(option.get("options"), list) else []
+    out: list[dict[str, str]] = []
+    for entry in values:
+        if not isinstance(entry, dict):
+            continue
+        value = entry.get("value")
+        if value is None:
+            continue
+        label = entry.get("name") or entry.get("label") or str(value)
+        out.append({"value": str(value), "label": str(label)})
+    return out
+
+
+def extract_mode_options(config_options: list[dict[str, Any]] | None) -> list[dict[str, str]]:
+    option = find_config_option(
+        config_options,
+        category="mode",
+        preferred_ids=("mode", "permission", "permissionMode"),
+    )
+    if option is None:
+        return []
+    values = option.get("options") if isinstance(option.get("options"), list) else []
+    out: list[dict[str, str]] = []
+    for entry in values:
+        if not isinstance(entry, dict):
+            continue
+        value = entry.get("value")
+        if value is None:
+            continue
+        label = entry.get("name") or entry.get("label") or str(value)
+        out.append({"value": str(value), "label": str(label)})
+    return out
+
+
+def find_config_option(
+    config_options: list[dict[str, Any]] | None,
+    *,
+    category: str | None,
+    preferred_ids: tuple[str, ...],
+) -> dict[str, Any] | None:
+    options = [opt for opt in (config_options or []) if isinstance(opt, dict)]
+    if category:
+        for opt in options:
+            if str(opt.get("category") or "") == category:
+                return opt
+    for preferred in preferred_ids:
+        for opt in options:
+            option_id = str(opt.get("id") or "")
+            if option_id.lower() == preferred.lower():
+                return opt
+    for preferred in preferred_ids:
+        for opt in options:
+            option_id = str(opt.get("id") or "").lower()
+            name = str(opt.get("name") or "").lower()
+            if preferred.lower() in (option_id, name):
+                return opt
+    return None
+
+
+def summarize_auth_methods(auth_methods: list[dict[str, Any]] | None) -> list[dict[str, str]]:
+    out: list[dict[str, str]] = []
+    for method in auth_methods or []:
+        if not isinstance(method, dict):
+            continue
+        method_id = method.get("id") or method.get("methodId")
+        if not method_id:
+            continue
+        mid = str(method_id)
+        out.append(
+            {
+                "id": mid,
+                "name": str(method.get("name") or mid),
+                "interactive": "true" if is_interactive_auth_method(mid) else "false",
+            }
+        )
+    return out
+
+
+# Methods that open a browser / device-code flow. Calling authenticate() with these
+# is a side-effecting action — a short RPC timeout does NOT prevent the browser from opening.
+_INTERACTIVE_AUTH_METHOD_IDS = frozenset(
+    {
+        "ioa",
+        "external",
+        "internal",
+        "selfhosted",
+        "oauth",
+        "browser",
+        "web",
+        "device_code",
+        "device-code",
+        "login",  # bare "login" is usually interactive TUI/browser
+    }
+)
+
+_INTERACTIVE_AUTH_TOKENS = (
+    "oauth",
+    "browser",
+    "web_login",
+    "web-login",
+    "device_code",
+    "device-code",
+    "interactive",
+)
+
+# Known headless / cached-credential methods (tried first when advertised).
+_HEADLESS_AUTH_METHOD_IDS = (
+    "cached_token",
+    "cursor_login",
+    "xai.api_key",
+    "api_key",
+    "token",
+)
+
+
+def is_interactive_auth_method(method_id: str) -> bool:
+    """Return True if calling authenticate(methodId) is expected to open a browser/TUI."""
+    mid = (method_id or "").strip().lower()
+    if not mid:
+        return True
+    if mid in _INTERACTIVE_AUTH_METHOD_IDS:
+        return True
+    return any(tok in mid for tok in _INTERACTIVE_AUTH_TOKENS)
+
+
+def order_headless_auth_method_ids(
+    advertised: list[str],
+    *,
+    preferred: list[str] | tuple[str, ...] = (),
+) -> list[str]:
+    """Order only non-interactive auth method ids that the agent actually advertises.
+
+    Discovery and session start MUST never call interactive OAuth methods — even with
+    a short timeout the agent process still opens a browser tab.
+    """
+    advertised_set = {m for m in advertised if m}
+    ordered: list[str] = []
+    for mid in (*preferred, *_HEADLESS_AUTH_METHOD_IDS, *advertised):
+        if not mid or mid not in advertised_set:
+            continue
+        if is_interactive_auth_method(mid):
+            continue
+        if mid not in ordered:
+            ordered.append(mid)
+    return ordered
+
+
+def order_interactive_auth_method_ids(
+    advertised: list[str],
+    *,
+    preferred: list[str] | tuple[str, ...] = (),
+) -> list[str]:
+    """Order interactive OAuth/browser method ids for user-triggered login only."""
+    advertised_set = {m for m in advertised if m}
+    ordered: list[str] = []
+    for mid in (*preferred, *advertised):
+        if not mid or mid not in advertised_set:
+            continue
+        if not is_interactive_auth_method(mid):
+            continue
+        if mid not in ordered:
+            ordered.append(mid)
+    return ordered

connector/acp/discovery.py

@@ -0,0 +1,385 @@
+from __future__ import annotations
+
+import asyncio
+import os
+import shutil
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from connector.acp.config_options import (
+    extract_mode_options,
+    extract_model_options,
+    order_headless_auth_method_ids,
+    summarize_auth_methods,
+)
+from connector.acp.manifest import AgentManifest
+from connector.acp.rpc import AcpJsonRpcClient, AcpJsonRpcError
+from connector.launch import LaunchTarget, launch_target, path_exists_for_launch
+from connector.logging import logger
+
+
+_COMMAND_CHECK_TIMEOUT_S = 6.0
+# Full auth/model probe is expensive (spawn + session/new). Discovery stays light.
+_LIGHT_INIT_TIMEOUT_S = 10.0
+_DEEP_PROBE_TIMEOUT_S = 12.0
+_AUTH_METHOD_TIMEOUT_S = 4.0
+
+
+async def discover_acp_manifest(
+    manifest: AgentManifest,
+    *,
+    extra_candidate: str | None = None,
+    deep_probe: bool = False,
+) -> tuple[dict[str, Any], LaunchTarget | None]:
+    """Locate binary and optionally deep-probe ACP initialize/session.
+
+    Default is *light*: version check only (+ optional short initialize). Full
+    session/new auth/model probe is deferred (deep_probe=True or first use).
+    """
+    candidates = _candidate_paths(manifest, extra_candidate=extra_candidate)
+    checked: list[dict[str, Any]] = []
+    for candidate in candidates:
+        result = await _check_candidate(manifest, candidate)
+        checked.append(result)
+        if result["status"] != "ok":
+            continue
+        target = launch_target(result["source"], result["path"])
+        report: dict[str, Any] = {
+            "history": "unavailable",
+            "execution": "ok",
+            "transport": "acp",
+            "displayName": manifest.display_name,
+            "selected": {
+                "source": result["source"],
+                "path": result["path"],
+                "version": result.get("version"),
+            },
+            "checked": checked,
+            "authHint": manifest.pre_auth_hint,
+            "authStatus": "unknown",
+        }
+        if result.get("versionUnverified"):
+            report["versionUnverified"] = True
+            report["warnings"] = ["version_check_failed"]
+        if deep_probe:
+            probe = await probe_acp_agent(manifest, target)
+            report.update(probe)
+        else:
+            # Light: binary is present; auth/models filled on first real session
+            # or background deep probe for active runtimes only.
+            report["probeMode"] = "light"
+        return report, target
+    return (
+        {
+            "history": "unavailable",
+            "execution": "unavailable",
+            "transport": "acp",
+            "displayName": manifest.display_name,
+            "error": {
+                "code": f"{manifest.id}_unavailable",
+                "message": (
+                    f"{manifest.display_name} is unavailable. "
+                    f"{manifest.pre_auth_hint or 'Install the CLI and ensure it is on PATH.'}"
+                ),
+            },
+            "checked": checked,
+            "authHint": manifest.pre_auth_hint,
+            "authStatus": "unknown",
+        },
+        None,
+    )
+
+
+async def probe_acp_agent(manifest: AgentManifest, target: LaunchTarget) -> dict[str, Any]:
+    """Deep probe: initialize (+ optional session/new) for authStatus/models."""
+    command = target.command(manifest.launch_args())
+    client = AcpJsonRpcClient(command, env=dict(manifest.env) or None, cwd=None)
+    probe: dict[str, Any] = {
+        "authStatus": "unknown",
+        "authMethods": [],
+        "probeMode": "deep",
+    }
+    try:
+        await asyncio.wait_for(client.start(), timeout=_LIGHT_INIT_TIMEOUT_S)
+        init = await client.request(
+            "initialize",
+            {
+                "protocolVersion": 1,
+                "clientCapabilities": {
+                    **manifest.client_capabilities(),
+                    "session": {"configOptions": {"boolean": {}}},
+                },
+                "clientInfo": {"name": "agent-link-discovery", "version": "0.1"},
+            },
+            timeout=_LIGHT_INIT_TIMEOUT_S,
+        )
+        auth_methods = init.get("authMethods") if isinstance(init.get("authMethods"), list) else []
+        probe["authMethods"] = summarize_auth_methods(auth_methods)
+        agent_caps = init.get("agentCapabilities") if isinstance(init.get("agentCapabilities"), dict) else {}
+        if agent_caps.get("loadSession"):
+            probe["history"] = "ok_empty"
+
+        # Prefer initialize-only success: many agents are "ok enough" without session/new.
+        # session/new is slow/unreliable for Cursor cold start.
+        with tempfile.TemporaryDirectory(prefix="agent-link-acp-probe-") as tmp:
+            session, auth_err = await _probe_session_new(client, tmp)
+            if session is None and auth_err:
+                await _try_authenticate(client, manifest, auth_methods)
+                session, auth_err = await _probe_session_new(client, tmp)
+
+            if session is None:
+                if auth_err or probe["authMethods"]:
+                    probe["authStatus"] = "required"
+                    methods = probe["authMethods"]
+                    names = ", ".join(
+                        str(m.get("name") or m.get("id") or "") for m in methods
+                    ) or "login"
+                    probe["authHint"] = manifest.pre_auth_hint or (
+                        f"{manifest.display_name} requires authentication ({names}). "
+                        "Complete CLI login on the device, then refresh."
+                    )
+                    probe["execution"] = "ok"
+                else:
+                    # initialize worked — treat as attachable, auth unknown
+                    probe["authStatus"] = "unknown"
+                    probe["execution"] = "ok"
+                return probe
+
+            probe["authStatus"] = "ok"
+            config_options = (
+                session.get("configOptions") if isinstance(session.get("configOptions"), list) else []
+            )
+            config_options = [opt for opt in config_options if isinstance(opt, dict)]
+            if config_options:
+                probe["configOptions"] = config_options
+                models = extract_model_options(config_options)
+                modes = extract_mode_options(config_options)
+                if models:
+                    probe["modelOptions"] = models
+                if modes:
+                    probe["modeOptions"] = modes
+            session_id = session.get("sessionId") or session.get("session_id")
+            if isinstance(session_id, str) and session_id:
+                await _best_effort_close_session(client, session_id)
+            return probe
+    except Exception as exc:
+        logger.warning("ACP probe failed runtime={} error={}", manifest.id, exc)
+        probe["authStatus"] = "unknown"
+        probe["probeError"] = str(exc)
+        # Binary was found; keep execution ok so UI can still attach and retry on use.
+        probe["execution"] = "ok"
+        return probe
+    finally:
+        try:
+            await client.close()
+        except Exception:
+            pass
+
+
+def _looks_like_auth_error(message: str) -> bool:
+    text = (message or "").lower()
+    tokens = (
+        "auth",
+        "login",
+        "unauthor",
+        "api key",
+        "apikey",
+        "credential",
+        "not configured",
+        "missing or not",
+        "sign in",
+        "signin",
+        "token",
+        "permission denied",
+        "timeout",
+        "timed out",
+    )
+    return any(tok in text for tok in tokens)
+
+
+async def _probe_session_new(
+    client: AcpJsonRpcClient,
+    cwd: str,
+) -> tuple[dict[str, Any] | None, bool]:
+    """Return (session_result, auth_required)."""
+    try:
+        session = await client.request(
+            "session/new",
+            {"cwd": cwd, "mcpServers": []},
+            timeout=_DEEP_PROBE_TIMEOUT_S,
+        )
+        return session if isinstance(session, dict) else {}, False
+    except AcpJsonRpcError as exc:
+        message = str(exc)
+        if _looks_like_auth_error(message):
+            return None, True
+        logger.debug("ACP probe session/new failed non-auth: {}", exc)
+        return None, False
+    except Exception as exc:
+        message = str(exc)
+        if "timeout" in message.lower() or _looks_like_auth_error(message):
+            return None, True
+        logger.debug("ACP probe session/new failed: {}", exc)
+        return None, False
+
+
+async def _best_effort_close_session(client: AcpJsonRpcClient, session_id: str) -> None:
+    for method in ("session/close", "session/cancel"):
+        try:
+            if method == "session/cancel":
+                await client.notify(method, {"sessionId": session_id})
+            else:
+                await client.request(method, {"sessionId": session_id}, timeout=2.0)
+            break
+        except Exception:
+            continue
+
+
+async def _try_authenticate(
+    client: AcpJsonRpcClient,
+    manifest: AgentManifest,
+    auth_methods: list[Any],
+) -> None:
+    """Try headless-only auth during deep probe. Never call interactive OAuth."""
+    methods = [m for m in auth_methods if isinstance(m, dict)]
+    if not methods:
+        return
+    method_ids = [str(m.get("id") or m.get("methodId") or "") for m in methods]
+    method_ids = [mid for mid in method_ids if mid]
+    ordered = order_headless_auth_method_ids(
+        method_ids,
+        preferred=list(manifest.preferred_auth_method_ids),
+    )
+    if not ordered:
+        logger.debug(
+            "ACP discovery skip interactive auth runtime={} methods={}",
+            manifest.id,
+            method_ids,
+        )
+        return
+    for mid in ordered:
+        try:
+            await client.request(
+                "authenticate",
+                {"methodId": mid, "_meta": {"headless": True}},
+                timeout=_AUTH_METHOD_TIMEOUT_S,
+            )
+            logger.info("ACP discovery authenticated runtime={} method={}", manifest.id, mid)
+            return
+        except Exception:
+            continue
+
+
+def _candidate_paths(
+    manifest: AgentManifest,
+    *,
+    extra_candidate: str | None = None,
+) -> list[dict[str, str]]:
+    out: list[dict[str, str]] = []
+    if extra_candidate:
+        out.append({"source": "custom", "path": os.path.expandvars(os.path.expanduser(extra_candidate))})
+    for env_name in manifest.env_paths:
+        value = os.environ.get(env_name)
+        if value:
+            out.append({"source": "env", "path": os.path.expandvars(os.path.expanduser(value))})
+    for name in manifest.which:
+        found = shutil.which(name)
+        if found:
+            out.append({"source": "cli", "path": found})
+    if manifest.command:
+        found = shutil.which(manifest.command[0])
+        if found:
+            out.append({"source": "cli", "path": found})
+    if sys.platform == "win32":
+        home = Path.home()
+        appdata = os.environ.get("APPDATA", str(home / "AppData" / "Roaming"))
+        local = os.environ.get("LOCALAPPDATA", str(home / "AppData" / "Local"))
+        names = list(manifest.which) or ([manifest.command[0]] if manifest.command else [])
+        for name in names:
+            for path in (
+                home / ".local" / "bin" / f"{name}.exe",
+                home / ".local" / "bin" / f"{name}.cmd",
+                Path(appdata) / "npm" / name,
+                Path(appdata) / "npm" / f"{name}.cmd",
+                Path(appdata) / "npm" / f"{name}.ps1",
+                Path(local) / "Programs" / name / f"{name}.exe",
+                Path(local) / "cursor-agent" / "agent.cmd",
+                Path(local) / "cursor-agent" / "agent.exe",
+            ):
+                out.append({"source": "common", "path": str(path)})
+            found = shutil.which(name) or shutil.which(f"{name}.cmd")
+            if found:
+                out.append({"source": "cli", "path": found})
+    return _dedupe(out)
+
+
+async def _check_candidate(manifest: AgentManifest, candidate: dict[str, str]) -> dict[str, Any]:
+    path = candidate["path"]
+    source = candidate["source"]
+    base: dict[str, Any] = {"source": source, "path": path}
+    if not path:
+        return {**base, "status": "missing", "reason": "empty path"}
+    path_obj = Path(path)
+    if path_obj.is_absolute() and not path_obj.exists() and not shutil.which(path):
+        return {**base, "status": "missing", "reason": "file not found"}
+    if path_obj.is_absolute() and path_obj.is_file() and not path_exists_for_launch(path):
+        return {**base, "status": "failed", "reason": "not executable"}
+
+    target = launch_target(source, path)
+    version_cmd = target.command(list(manifest.version_args))
+    version = await _run_command(version_cmd)
+    if version["status"] != "ok":
+        if path_obj.is_file() or shutil.which(path):
+            return {
+                **base,
+                "status": "ok",
+                "version": None,
+                "versionUnverified": True,
+                "versionNote": version.get("reason") or version.get("stderr"),
+            }
+        return {**base, "status": "failed", "stage": "version", **version}
+    return {**base, "status": "ok", "version": version.get("stdout"), "versionUnverified": False}
+
+
+async def _run_command(command: list[str]) -> dict[str, Any]:
+    try:
+        process = await asyncio.create_subprocess_exec(
+            *command,
+            stdout=asyncio.subprocess.PIPE,
+            stderr=asyncio.subprocess.PIPE,
+        )
+        try:
+            stdout_b, stderr_b = await asyncio.wait_for(process.communicate(), timeout=_COMMAND_CHECK_TIMEOUT_S)
+        except TimeoutError:
+            process.kill()
+            await process.wait()
+            return {"status": "failed", "reason": "timeout"}
+        stdout = stdout_b.decode(errors="replace").strip()
+        stderr = stderr_b.decode(errors="replace").strip()
+        if process.returncode != 0:
+            return {
+                "status": "failed",
+                "reason": f"exit {process.returncode}",
+                "stdout": stdout[:500],
+                "stderr": stderr[:500],
+            }
+        return {"status": "ok", "stdout": (stdout or stderr)[:200]}
+    except FileNotFoundError:
+        return {"status": "missing", "reason": "file not found"}
+    except Exception as exc:
+        logger.exception("ACP version check failed command={}", command)
+        return {"status": "failed", "reason": str(exc)}
+
+
+def _dedupe(candidates: list[dict[str, str]]) -> list[dict[str, str]]:
+    seen: set[str] = set()
+    out: list[dict[str, str]] = []
+    for item in candidates:
+        path = item.get("path") or ""
+        if not path or path in seen:
+            continue
+        seen.add(path)
+        out.append(item)
+    return out

connector/acp/manifest.py

@@ -0,0 +1,110 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from importlib import resources
+from pathlib import Path
+from typing import Any, Literal
+
+
+ProcessModel = Literal["shared", "per_session"]
+CapabilityLevel = Literal["required", "optional", "unsupported"]
+
+
+@dataclass(frozen=True, slots=True)
+class AgentManifest:
+    """Declarative description of one ACP-compatible agent binary."""
+
+    id: str
+    display_name: str
+    transport: Literal["acp"] = "acp"
+    command: tuple[str, ...] = ()
+    args: tuple[str, ...] = ()
+    env: dict[str, str] = field(default_factory=dict)
+    env_paths: tuple[str, ...] = ()
+    which: tuple[str, ...] = ()
+    version_args: tuple[str, ...] = ("--version",)
+    process_model: ProcessModel = "shared"
+    preferred_auth_method_ids: tuple[str, ...] = ()
+    pre_auth_hint: str | None = None
+    capabilities_expected: dict[str, CapabilityLevel] = field(default_factory=dict)
+    client_fs_read: bool = True
+    client_fs_write: bool = False
+    client_terminal: bool = False
+    quirks: dict[str, Any] = field(default_factory=dict)
+
+    def launch_args(self) -> list[str]:
+        return list(self.args)
+
+    def client_capabilities(self) -> dict[str, Any]:
+        return {
+            "fs": {
+                "readTextFile": self.client_fs_read,
+                "writeTextFile": self.client_fs_write,
+            },
+            "terminal": self.client_terminal,
+        }
+
+
+def manifest_from_dict(raw: dict[str, Any]) -> AgentManifest:
+    discovery = raw.get("discovery") if isinstance(raw.get("discovery"), dict) else {}
+    auth = raw.get("auth") if isinstance(raw.get("auth"), dict) else {}
+    client_caps = raw.get("clientCapabilities") if isinstance(raw.get("clientCapabilities"), dict) else {}
+    fs_caps = client_caps.get("fs") if isinstance(client_caps.get("fs"), dict) else {}
+    caps_expected = raw.get("capabilitiesExpected") if isinstance(raw.get("capabilitiesExpected"), dict) else {}
+    command = raw.get("command") or []
+    args = raw.get("args") or []
+    if not isinstance(command, list) or not command:
+        raise ValueError(f"manifest {raw.get('id')!r} needs non-empty command")
+    if not isinstance(raw.get("id"), str) or not raw["id"]:
+        raise ValueError("manifest needs id")
+    return AgentManifest(
+        id=raw["id"],
+        display_name=str(raw.get("displayName") or raw["id"]),
+        transport="acp",
+        command=tuple(str(part) for part in command),
+        args=tuple(str(part) for part in args) if isinstance(args, list) else (),
+        env={str(k): str(v) for k, v in (raw.get("env") or {}).items()}
+        if isinstance(raw.get("env"), dict)
+        else {},
+        env_paths=tuple(str(x) for x in (discovery.get("envPaths") or []) if x),
+        which=tuple(str(x) for x in (discovery.get("which") or []) if x),
+        version_args=tuple(str(x) for x in (discovery.get("versionArgs") or ["--version"])),
+        process_model="per_session" if discovery.get("processModel") == "per_session" or raw.get("processModel") == "per_session" else "shared",
+        preferred_auth_method_ids=tuple(str(x) for x in (auth.get("preferredMethodIds") or []) if x),
+        pre_auth_hint=str(auth["preAuthHint"]) if auth.get("preAuthHint") else None,
+        capabilities_expected={
+            str(k): _capability_level(v) for k, v in caps_expected.items()
+        },
+        client_fs_read=bool(fs_caps.get("readTextFile", True)),
+        client_fs_write=bool(fs_caps.get("writeTextFile", False)),
+        client_terminal=bool(client_caps.get("terminal", False)),
+        quirks=dict(raw.get("quirks") or {}) if isinstance(raw.get("quirks"), dict) else {},
+    )
+
+
+def load_manifest_file(path: str | Path) -> AgentManifest:
+    data = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(data, dict):
+        raise ValueError(f"manifest file must be a JSON object: {path}")
+    return manifest_from_dict(data)
+
+
+def load_builtin_manifests() -> list[AgentManifest]:
+    manifests: list[AgentManifest] = []
+    package = resources.files("connector.acp.manifests")
+    for entry in sorted(package.iterdir()):
+        if not entry.name.endswith(".json"):
+            continue
+        with entry.open("r", encoding="utf-8") as handle:
+            data = json.load(handle)
+        if isinstance(data, dict):
+            manifests.append(manifest_from_dict(data))
+    return manifests
+
+
+def _capability_level(value: Any) -> CapabilityLevel:
+    text = str(value or "optional")
+    if text in {"required", "optional", "unsupported"}:
+        return text  # type: ignore[return-value]
+    return "optional"

connector/acp/manifests/__init__.py

@@ -0,0 +1 @@
+"""Built-in ACP agent manifests (JSON)."""