code-analysis-client-dev 1.6.341__py3-none-any.whl

code_analysis_client/client.py

@@ -0,0 +1,728 @@
+"""
+Async façade over mcp-proxy-adapter JsonRpcClient for code-analysis-server.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+import asyncio
+import warnings
+from pathlib import Path
+from typing import Any, Dict, Literal, Mapping, Optional, Union, overload
+
+try:
+    from mcp_proxy_adapter.client.jsonrpc_client.client import JsonRpcClient
+except Exception:  # pragma: no cover - compatibility with older layouts
+    from mcp_proxy_adapter.client.jsonrpc_client import JsonRpcClient
+from mcp_proxy_adapter.client.jsonrpc_client.exceptions import (
+    ClientRemoteResponseError,
+    CommandInnerFailureError,
+    CommandSessionFailedError,
+    CommandSessionTimeoutError,
+)
+
+from code_analysis_client.commands_proxy import ValidatedCommandsProxy
+from code_analysis_client.config import (
+    adapter_settings_from_server_config,
+    adapter_settings_to_jsonrpc_kwargs,
+    load_server_config,
+    merged_client_ws_config,
+)
+from code_analysis_client.file_session import FileSessionClient
+from code_analysis_client.check_chain import CheckChainClient
+from code_analysis_client.project import ProjectClient
+from code_analysis_client.worktree import WorktreeClient
+from code_analysis_client.queue_wait import (
+    QueuedJob,
+    StatusHook,
+    check_wait_arguments,
+    invalid_params_error,
+    map_adapter_error,
+    result_from_unified,
+    validation_error_code_for_command,
+)
+from code_analysis_client.universal_file import UniversalFileClient
+from code_analysis_client.schema_disk_cache import (
+    clear_cached_schemas,
+    load_cached_schema,
+    store_cached_schema,
+)
+from code_analysis_client.server_schema import fetch_command_schema_from_server
+from code_analysis_client.exceptions import ClientValidationError
+from code_analysis_client.symbol_tree import SymbolTreeNode
+from code_analysis_client.validation import (
+    prepare_params_for_schema,
+    validate_params_against_schema,
+)
+
+_SYMBOL_TREE_OMITTED: Any = object()
+
+
+def _remote_invalid_params_as_client_validation(
+    error: ClientRemoteResponseError, command: str,
+) -> ClientValidationError | None:
+    """Convert the adapter's JSON-RPC invalid-params response for client callers.
+
+    ``JsonRpcClient.execute_command()`` raises ``ClientRemoteResponseError``
+    for every top-level JSON-RPC error.  Code-analysis validation errors use
+    the standard ``-32602`` code, however, and callers of this package already
+    handle local schema failures as ``ClientValidationError``.  Preserve the
+    adapter's complete message and the server's validation payload while
+    presenting both local and remote invalid-parameter failures through that
+    one client contract.
+    """
+    details = error.details
+    if details.get("code") != -32602:
+        return None
+
+    # Generic commands retain the long-standing client API code.  symbol_tree
+    # is the mapped exception: its public contract exposes the JSON-RPC code.
+    code = validation_error_code_for_command(command)
+    return invalid_params_error(str(error), details.get("data"), code=code)
+
+
+class CodeAnalysisAsyncClient:
+    """Async client: domain commands via :meth:`call` / :meth:`call_unified`; full adapter API on :attr:`rpc`."""
+
+    __slots__ = ("_rpc", "_command_schema_cache", "_commands_proxy")
+
+    def __init__(self, **jsonrpc_kwargs: Any) -> None:
+        """Same keyword arguments as ``JsonRpcClient`` (``protocol``, ``host``, ``port``, ``cert``, …).
+
+        ``ws_config`` (``{"websocket": {...}}``) is merged over
+        :data:`code_analysis_client.config.DEFAULT_CLIENT_ADAPTER_CONFIG` key by key, so the
+        adapter's wait timeouts and ``on_timeout`` policy are always explicit (never the adapter's
+        60 s / cancel constants).
+        """
+        jsonrpc_kwargs["ws_config"] = merged_client_ws_config(
+            jsonrpc_kwargs.get("ws_config")
+        )
+        self._rpc = JsonRpcClient(**jsonrpc_kwargs)
+        self._command_schema_cache: Dict[str, Dict[str, Any]] = {}
+        self._commands_proxy: Optional[ValidatedCommandsProxy] = None
+
+    @classmethod
+    def from_jsonrpc_kwargs(cls, **kwargs: Any) -> CodeAnalysisAsyncClient:
+        """Alias for ``CodeAnalysisAsyncClient(**kwargs)``."""
+        return cls(**kwargs)
+
+    @classmethod
+    def from_adapter_settings(
+        cls,
+        settings: Mapping[str, Any],
+        *,
+        timeout: float | None = 60.0,
+        check_hostname: bool = False,
+        token_header: str | None = None,
+        token: str | None = None,
+    ) -> CodeAnalysisAsyncClient:
+        """Build from a dict like ``PipelineConfig.generate_adapter_client_settings()``."""
+        kwargs = adapter_settings_to_jsonrpc_kwargs(
+            settings,
+            timeout=timeout,
+            check_hostname=check_hostname,
+            token_header=token_header,
+            token=token,
+        )
+        return cls(**kwargs)
+
+    @classmethod
+    def from_server_config(
+        cls,
+        config: Mapping[str, Any],
+        *,
+        timeout: float | None = 60.0,
+        check_hostname: bool = False,
+        token_header: str | None = None,
+        token: str | None = None,
+    ) -> CodeAnalysisAsyncClient:
+        """Derive connection settings from a code-analysis server config object."""
+        settings = adapter_settings_from_server_config(config)
+        return cls.from_adapter_settings(
+            settings,
+            timeout=timeout,
+            check_hostname=check_hostname,
+            token_header=token_header,
+            token=token,
+        )
+
+    @classmethod
+    def from_server_config_path(
+        cls,
+        path: str | Path,
+        *,
+        timeout: float | None = 60.0,
+        check_hostname: bool = False,
+        token_header: str | None = None,
+        token: str | None = None,
+    ) -> CodeAnalysisAsyncClient:
+        """Load ``config.json`` and connect."""
+        return cls.from_server_config(
+            load_server_config(path),
+            timeout=timeout,
+            check_hostname=check_hostname,
+            token_header=token_header,
+            token=token,
+        )
+
+    @property
+    def rpc(self) -> JsonRpcClient:
+        """Underlying mcp-proxy-adapter client (queue, transfer, ``help``, ``execute_command``, …)."""
+        return self._rpc
+
+    @property
+    def commands(self) -> ValidatedCommandsProxy:
+        """Dynamic validated wrappers: schema is loaded from the server via ``help`` (cached)."""
+        if self._commands_proxy is None:
+            self._commands_proxy = ValidatedCommandsProxy(self)
+        return self._commands_proxy
+
+    def clear_command_schema_cache(self) -> None:
+        """Drop cached command schemas (after ``reload`` or when server definitions change).
+
+        Clears both the in-memory cache and this server's on-disk schema
+        cache (:mod:`code_analysis_client.schema_disk_cache`, bug 8e6acb34) —
+        otherwise the very next call would just repopulate the in-memory
+        cache from a now-stale disk entry, defeating the point of clearing it.
+        """
+        self._command_schema_cache.clear()
+        clear_cached_schemas(self._rpc.base_url)
+
+    async def symbol_tree(
+        self,
+        *,
+        project_id: str,
+        file_path: str | None = _SYMBOL_TREE_OMITTED,
+        source: str | None = _SYMBOL_TREE_OMITTED,
+        source_name: str | None = _SYMBOL_TREE_OMITTED,
+        worktree_name: str | None = _SYMBOL_TREE_OMITTED,
+        options: dict[str, object] | None = _SYMBOL_TREE_OMITTED,
+    ) -> list[SymbolTreeNode]:
+        """Read declarations without saving raw source or changing project state.
+
+        Select exactly one of ``file_path`` and ``source``. Raw source requires
+        ``source_name``; its extension selects the plugin. Domain failures retain
+        the normal ``CommandFailedError`` result; validation uses
+        ``ClientValidationError``.
+        """
+        params: dict[str, Any] = {"project_id": project_id}
+        for key, value in (
+            ("file_path", file_path),
+            ("source", source),
+            ("source_name", source_name),
+            ("worktree_name", worktree_name),
+            ("options", options),
+        ):
+            if value is not _SYMBOL_TREE_OMITTED:
+                params[key] = value
+        result = await self.call("symbol_tree", params)
+        data = result.get("data")
+        if not isinstance(data, list):
+            raise RuntimeError("symbol_tree returned a non-list result")
+        return data
+
+    @property
+    def file_sessions(self) -> FileSessionClient:
+        """Session workflow: ``session_*``, ``subordinate_session_*``, transfer, advisory locks."""
+        return FileSessionClient(self)
+
+    @property
+    def projects(self) -> ProjectClient:
+        """Project commands outside the session workflow (documentation-server override)."""
+        return ProjectClient(self)
+
+    @property
+    def worktrees(self) -> WorktreeClient:
+        """Worktree management: ``worktree_*`` commands."""
+        return WorktreeClient(self)
+
+    @property
+    def check_chains(self) -> CheckChainClient:
+        """Check-chain registry and promote: ``check_chain_*``, ``file_check_and_promote``."""
+        return CheckChainClient(self)
+
+    @property
+    def universal_files(self) -> UniversalFileClient:
+        """Read-only structured preview (``universal_file_preview`` command)."""
+        return UniversalFileClient(self)
+
+    async def get_command_schema(
+        self, command: str, *, refresh: bool = False
+    ) -> Dict[str, Any]:
+        """Fetch input JSON schema for ``command`` using server ``help``.
+
+        Checked in order (bug 8e6acb34, Fix 1): the in-memory per-instance
+        cache, then a bounded-TTL on-disk cache shared across process
+        invocations against the same server
+        (:mod:`code_analysis_client.schema_disk_cache`) — this is what
+        removes the ~2.7ms ``help`` round trip that a fresh client instance
+        would otherwise pay on every first use of a given command, since most
+        real callers are short-lived processes that never benefit from an
+        in-memory-only cache. ``refresh=True`` skips both caches and always
+        re-fetches from the server, repopulating them afterward.
+        """
+        if not refresh and command in self._command_schema_cache:
+            return self._command_schema_cache[command]
+        if not refresh:
+            cached = load_cached_schema(self._rpc.base_url, command)
+            if cached is not None:
+                self._command_schema_cache[command] = cached
+                return cached
+        schema = await fetch_command_schema_from_server(self._rpc, command)
+        self._command_schema_cache[command] = schema
+        store_cached_schema(self._rpc.base_url, command, schema)
+        return schema
+
+    async def _execute(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        use_cmd_endpoint: bool = False,
+        auto_poll: bool = True,
+        timeout: Optional[float] = None,
+        poll_interval: Optional[float] = None,
+        status_hook: Optional[StatusHook] = None,
+    ) -> Union[Dict[str, Any], QueuedJob]:
+        """Single core every public entry point routes through: the adapter's standard call.
+
+        Runs ``command`` through ``JsonRpcClient.execute_command_unified`` (WebSocket command
+        session, event-driven wait inside the call, adapter RPC-polling fallback with a logged
+        WARNING when ``/ws`` is unreachable). Nothing here polls.
+
+        * ``auto_poll=True`` (default) - waits for the command and returns its inner result
+          envelope. ``timeout=None`` resolves to the client config
+          ``websocket.job_wait_timeout`` (shipped ``0`` = no bound); a positive ``timeout`` raises
+          :class:`~code_analysis_client.exceptions.JobTimeoutError` and detaches (the job keeps
+          running, ``websocket.on_timeout`` = ``detach``). ``poll_interval=None`` resolves to
+          ``websocket.terminal_poll_interval``. ``status_hook`` receives the adapter's WebSocket
+          events (accepted ... terminal); an exception raised by the hook propagates.
+        * ``auto_poll=False`` - detaches as soon as the job id is known and returns a
+          :class:`~code_analysis_client.queue_wait.QueuedJob` for EVERY command (also a formerly
+          immediate one); ``timeout``, ``poll_interval`` and ``status_hook`` are ignored.
+
+        An inner ``success=false`` raises
+        :class:`~code_analysis_client.exceptions.CommandFailedError` (never returned as a dict);
+        a queued job that ended failed raises
+        :class:`~code_analysis_client.exceptions.CommandFailedError` with the server error code,
+        message and data (same as an immediate error); a job that was stopped or cancelled raises
+        :class:`~code_analysis_client.exceptions.JobFailedError`; a server -32602 refusal raises
+        :class:`~code_analysis_client.exceptions.ClientValidationError`. A negative ``timeout`` or
+        a non-positive ``poll_interval`` raises ``ValueError`` before anything is sent.
+
+        ``use_cmd_endpoint`` remains accepted-and-ignored (documented no-op, kept only for
+        signature compatibility; the legacy ``/cmd`` route was removed in mcp-proxy-adapter 8.10.32).
+        """
+        check_wait_arguments(timeout, poll_interval)
+        waiting = bool(auto_poll)
+        try:
+            envelope = await self._rpc.execute_command_unified(
+                command,
+                params or {},
+                auto_poll=waiting,
+                timeout=timeout if waiting else None,
+                terminal_poll_interval=poll_interval if waiting else None,
+                status_hook=status_hook if waiting else None,
+                raise_on_inner_failure=True,
+            )
+        except (
+            ClientRemoteResponseError,
+            CommandSessionTimeoutError,
+            CommandSessionFailedError,
+            CommandInnerFailureError,
+            asyncio.TimeoutError,
+        ) as exc:
+            mapped = map_adapter_error(exc, command, timeout)
+            error: BaseException = exc if mapped is None else mapped
+            if isinstance(error, ClientRemoteResponseError):
+                validation_error = _remote_invalid_params_as_client_validation(
+                    error, command
+                )
+                if validation_error is not None:
+                    raise validation_error from exc
+            if error is exc:
+                raise
+            raise error from exc
+        if not waiting:
+            job_id = envelope.get("job_id")
+            if job_id:
+                return QueuedJob(
+                    job_id=str(job_id),
+                    envelope=envelope,
+                    rpc=self._rpc,
+                    command=command,
+                )
+            # /ws unreachable and the command ran without a job: it already executed.
+            return QueuedJob(
+                job_id="",
+                envelope=envelope,
+                rpc=self._rpc,
+                command=command,
+                resolved=result_from_unified(command, envelope),
+            )
+        return result_from_unified(command, envelope)
+
+    async def _execute_validated(
+        self,
+        command: str,
+        params: Dict[str, Any],
+        *,
+        use_cmd_endpoint: bool,
+        auto_poll: bool,
+        timeout: Optional[float],
+        poll_interval: Optional[float],
+        status_hook: Optional[StatusHook],
+    ) -> Union[Dict[str, Any], QueuedJob]:
+        """Execute after schema validation and reconcile a stale command catalog.
+
+        A cached schema can outlive a deployment that removes its command.  If
+        execution reports JSON-RPC ``-32601``, discard the cached catalog view
+        and ask live ``help`` once.  A command still present keeps the original
+        remote error; an absent command surfaces ``help``'s
+        :class:`ClientValidationError` with the remote response as its cause.
+        """
+        try:
+            return await self._execute(
+                command,
+                params,
+                use_cmd_endpoint=use_cmd_endpoint,
+                auto_poll=auto_poll,
+                timeout=timeout,
+                poll_interval=poll_interval,
+                status_hook=status_hook,
+            )
+        except ClientRemoteResponseError as exc:
+            if exc.details.get("code") != -32601:
+                raise
+            self.clear_command_schema_cache()
+            try:
+                await self.get_command_schema(command, refresh=True)
+            except ClientValidationError as schema_error:
+                raise schema_error from exc
+            raise
+
+    @overload
+    async def call_validated(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        use_cmd_endpoint: bool = False,
+        refresh_schema: bool = False,
+        auto_poll: Literal[True] = True,
+        timeout: Optional[float] = None,
+        poll_interval: Optional[float] = None,
+        status_hook: Optional[StatusHook] = None,
+    ) -> Dict[str, Any]: ...
+
+    @overload
+    async def call_validated(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        use_cmd_endpoint: bool = False,
+        refresh_schema: bool = False,
+        auto_poll: Literal[False],
+        timeout: Optional[float] = None,
+        poll_interval: Optional[float] = None,
+        status_hook: Optional[StatusHook] = None,
+    ) -> QueuedJob: ...
+
+    @overload
+    async def call_validated(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        use_cmd_endpoint: bool = False,
+        refresh_schema: bool = False,
+        auto_poll: bool,
+        timeout: Optional[float] = None,
+        poll_interval: Optional[float] = None,
+        status_hook: Optional[StatusHook] = None,
+    ) -> Union[Dict[str, Any], QueuedJob]: ...
+
+    async def call_validated(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        use_cmd_endpoint: bool = False,
+        refresh_schema: bool = False,
+        auto_poll: bool = True,
+        timeout: Optional[float] = None,
+        poll_interval: Optional[float] = None,
+        status_hook: Optional[StatusHook] = None,
+    ) -> Union[Dict[str, Any], QueuedJob]:
+        """``help`` → schema on server, shallow local validation, then the queue-aware core.
+
+        ``auto_poll`` (default ``True``) forwards to :meth:`_execute`: set it
+        to ``False`` to get a :class:`~code_analysis_client.queue_wait.QueuedJob`
+        handle back instead of blocking until a queued job completes.
+        """
+        schema = await self.get_command_schema(command, refresh=refresh_schema)
+        merged = dict(params or {})
+        prepared = prepare_params_for_schema(merged, schema)
+        validate_params_against_schema(prepared, schema, command_name=command)
+        return await self._execute_validated(
+            command,
+            prepared,
+            use_cmd_endpoint=use_cmd_endpoint,
+            auto_poll=auto_poll,
+            timeout=timeout,
+            poll_interval=poll_interval,
+            status_hook=status_hook,
+        )
+
+    @overload
+    async def call_unified_validated(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        refresh_schema: bool = False,
+        use_cmd_endpoint: bool = False,
+        expect_queue: Optional[bool] = None,
+        auto_poll: Literal[True] = True,
+        poll_interval: Optional[float] = None,
+        timeout: Optional[float] = None,
+        status_hook: Optional[StatusHook] = None,
+    ) -> Dict[str, Any]: ...
+
+    @overload
+    async def call_unified_validated(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        refresh_schema: bool = False,
+        use_cmd_endpoint: bool = False,
+        expect_queue: Optional[bool] = None,
+        auto_poll: Literal[False],
+        poll_interval: Optional[float] = None,
+        timeout: Optional[float] = None,
+        status_hook: Optional[StatusHook] = None,
+    ) -> QueuedJob: ...
+
+    @overload
+    async def call_unified_validated(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        refresh_schema: bool = False,
+        use_cmd_endpoint: bool = False,
+        expect_queue: Optional[bool] = None,
+        auto_poll: bool,
+        poll_interval: Optional[float] = None,
+        timeout: Optional[float] = None,
+        status_hook: Optional[StatusHook] = None,
+    ) -> Union[Dict[str, Any], QueuedJob]: ...
+
+    async def call_unified_validated(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        refresh_schema: bool = False,
+        use_cmd_endpoint: bool = False,
+        expect_queue: Optional[bool] = None,
+        auto_poll: bool = True,
+        poll_interval: Optional[float] = None,
+        timeout: Optional[float] = None,
+        status_hook: Optional[StatusHook] = None,
+    ) -> Union[Dict[str, Any], QueuedJob]:
+        """Deprecated alias for :meth:`call_validated`.
+
+        ``expect_queue`` remains accepted-and-ignored (documented no-op, kept
+        only for signature compatibility). ``auto_poll`` is now LIVE again and
+        forwards straight to the shared :meth:`_execute` core: ``auto_poll=False``
+        returns a :class:`~code_analysis_client.queue_wait.QueuedJob` handle
+        instead of a plain dict when the response is a queued envelope — a
+        return-type change versus the previous era where this parameter was
+        silently ignored and every path always blocked until completion.
+        Prefer :meth:`call_validated` directly; this alias emits
+        ``DeprecationWarning`` on every call.
+        """
+        warnings.warn(
+            "call_unified_validated is deprecated; use call_validated() "
+            "directly (its 'auto_poll' keyword works the same way).",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        schema = await self.get_command_schema(command, refresh=refresh_schema)
+        merged = dict(params or {})
+        prepared = prepare_params_for_schema(merged, schema)
+        validate_params_against_schema(prepared, schema, command_name=command)
+        return await self._execute_validated(
+            command,
+            prepared,
+            use_cmd_endpoint=use_cmd_endpoint,
+            auto_poll=auto_poll,
+            timeout=timeout,
+            poll_interval=poll_interval,
+            status_hook=status_hook,
+        )
+
+    @overload
+    async def call(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        use_cmd_endpoint: bool = False,
+        auto_poll: Literal[True] = True,
+        timeout: Optional[float] = None,
+        poll_interval: Optional[float] = None,
+        status_hook: Optional[StatusHook] = None,
+    ) -> Dict[str, Any]: ...
+
+    @overload
+    async def call(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        use_cmd_endpoint: bool = False,
+        auto_poll: Literal[False],
+        timeout: Optional[float] = None,
+        poll_interval: Optional[float] = None,
+        status_hook: Optional[StatusHook] = None,
+    ) -> QueuedJob: ...
+
+    @overload
+    async def call(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        use_cmd_endpoint: bool = False,
+        auto_poll: bool,
+        timeout: Optional[float] = None,
+        poll_interval: Optional[float] = None,
+        status_hook: Optional[StatusHook] = None,
+    ) -> Union[Dict[str, Any], QueuedJob]: ...
+
+    async def call(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        use_cmd_endpoint: bool = False,
+        auto_poll: bool = True,
+        timeout: Optional[float] = None,
+        poll_interval: Optional[float] = None,
+        status_hook: Optional[StatusHook] = None,
+    ) -> Union[Dict[str, Any], QueuedJob]:
+        """Run any registered server command; the adapter's standard call waits for it by default.
+
+        Pass ``auto_poll=False`` to get a
+        :class:`~code_analysis_client.queue_wait.QueuedJob` handle back
+        immediately for any command (call ``await handle.wait(...)`` when
+        you're ready to block on it). See :meth:`_execute` for the full contract.
+        """
+        return await self._execute(
+            command,
+            params,
+            use_cmd_endpoint=use_cmd_endpoint,
+            auto_poll=auto_poll,
+            timeout=timeout,
+            poll_interval=poll_interval,
+            status_hook=status_hook,
+        )
+
+    @overload
+    async def call_unified(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        use_cmd_endpoint: bool = False,
+        expect_queue: Optional[bool] = None,
+        auto_poll: Literal[True] = True,
+        poll_interval: Optional[float] = None,
+        timeout: Optional[float] = None,
+        status_hook: Optional[StatusHook] = None,
+    ) -> Dict[str, Any]: ...
+
+    @overload
+    async def call_unified(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        use_cmd_endpoint: bool = False,
+        expect_queue: Optional[bool] = None,
+        auto_poll: Literal[False],
+        poll_interval: Optional[float] = None,
+        timeout: Optional[float] = None,
+        status_hook: Optional[StatusHook] = None,
+    ) -> QueuedJob: ...
+
+    @overload
+    async def call_unified(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        use_cmd_endpoint: bool = False,
+        expect_queue: Optional[bool] = None,
+        auto_poll: bool,
+        poll_interval: Optional[float] = None,
+        timeout: Optional[float] = None,
+        status_hook: Optional[StatusHook] = None,
+    ) -> Union[Dict[str, Any], QueuedJob]: ...
+
+    async def call_unified(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        use_cmd_endpoint: bool = False,
+        expect_queue: Optional[bool] = None,
+        auto_poll: bool = True,
+        poll_interval: Optional[float] = None,
+        timeout: Optional[float] = None,
+        status_hook: Optional[StatusHook] = None,
+    ) -> Union[Dict[str, Any], QueuedJob]:
+        """Deprecated alias for :meth:`call`.
+
+        ``expect_queue`` remains accepted-and-ignored (documented no-op).
+        ``auto_poll`` is now LIVE again and forwards straight to the shared
+        :meth:`_execute` core: ``auto_poll=False`` returns a
+        :class:`~code_analysis_client.queue_wait.QueuedJob` handle instead of
+        a plain dict when the response is a queued envelope — a return-type
+        change versus the previous era where this parameter was silently
+        ignored. Prefer :meth:`call` directly; this alias emits
+        ``DeprecationWarning`` on every call.
+        """
+        warnings.warn(
+            "call_unified is deprecated; use call() directly (its "
+            "'auto_poll' keyword works the same way).",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return await self._execute(
+            command,
+            params,
+            use_cmd_endpoint=use_cmd_endpoint,
+            auto_poll=auto_poll,
+            timeout=timeout,
+            poll_interval=poll_interval,
+            status_hook=status_hook,
+        )
+
+    async def close(self) -> None:
+        """Close the underlying JSON-RPC transport."""
+        await self._rpc.close()
+
+    async def __aenter__(self) -> CodeAnalysisAsyncClient:
+        """Enter async context manager and return this client."""
+        return self
+
+    async def __aexit__(self, exc_type: Any, exc: Any, tb: Any) -> None:
+        """Close the client when leaving an async context manager block."""
+        await self.close()