code-analysis-client 1.6.56__tar.gz → 1.6.58__tar.gz

{code_analysis_client-1.6.56 → code_analysis_client-1.6.58}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-analysis-client
-Version: 1.6.56
+Version: 1.6.58
 Summary: Async JSON-RPC client for the code-analysis MCP server (mcp-proxy-adapter JsonRpcClient)
 Author-email: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
 Requires-Python: >=3.10
@@ -54,7 +54,41 @@ from code_analysis_client import CodeAnalysisAsyncClient
 client = CodeAnalysisAsyncClient.from_server_config(config_dict, timeout=60.0)
 ```
 
-Queued/long commands: use `client.call_unified(..., expect_queue=True, auto_poll=True)` or the underlying `client.rpc.execute_command_unified(...)`.
+### Queued commands are handled automatically
+
+Every entry point — `call`, `call_validated`, `client.commands.<name>`, and the
+`file_sessions` / `universal_files` facades built on `call_validated` — routes
+through one queue-aware core. If the server's immediate response is a queued-job
+envelope (either deployed shape: `poll_with`/`store: "queuemgr"`, or
+`queued_after_timeout`), the client polls `queue_get_job_status` for you until
+the job reaches a terminal state, then returns the unwrapped inner result — the
+same shape you'd get from a synchronous call. You never see the raw envelope.
+
+```python
+# No special handling needed: queued or not, this returns the real result.
+out = await client.call("some_long_running_command", {...})
+```
+
+Failures raise instead of returning an error envelope:
+
+* `CommandFailedError` — the job completed but the command itself failed
+  (`inner result {"success": false}` / `command_success is False` /
+  `completed_with_error`). Carries `.command`, `.job_id`, `.error`.
+* `JobFailedError` — the job failed/stopped/cancelled, or reported `error`.
+  Carries `.job_id`, `.error`, `.status`.
+* `JobTimeoutError` — only raised when you pass an explicit `timeout` and it
+  elapses; the job keeps running server-side. By default (`timeout=None`) the
+  client polls until the job finishes, however long that takes.
+
+Optional keyword args on `call` / `call_validated` (and their `call_unified*`
+counterparts): `timeout` (seconds, default `None` = wait until terminal),
+`poll_interval` (seconds between polls, default `1.0`), `status_hook` (sync or
+async callable invoked with each poll's status dict).
+
+`call_unified` / `call_unified_validated` are kept as **deprecated aliases** of
+`call` / `call_validated` for backward compatibility — `expect_queue` and
+`auto_poll` are accepted but ignored, since queue handling is now always on.
+Prefer `call` / `call_validated` directly.
 
 ## Validation using the server schema
 
@@ -73,7 +107,7 @@ async with CodeAnalysisAsyncClient(host="127.0.0.1", port=15001) as client:
     client.clear_command_schema_cache()
 ```
 
-Use `call_unified_validated` when you need queue polling. Pass `refresh_schema=True` on a single call to bypass the in-memory schema cache.
+Pass `refresh_schema=True` on a single call to bypass the in-memory schema cache.
 
 ## High-level facades (aligned with live server registry)
 

{code_analysis_client-1.6.56 → code_analysis_client-1.6.58}/README.md

@@ -42,7 +42,41 @@ from code_analysis_client import CodeAnalysisAsyncClient
 client = CodeAnalysisAsyncClient.from_server_config(config_dict, timeout=60.0)
 ```
 
-Queued/long commands: use `client.call_unified(..., expect_queue=True, auto_poll=True)` or the underlying `client.rpc.execute_command_unified(...)`.
+### Queued commands are handled automatically
+
+Every entry point — `call`, `call_validated`, `client.commands.<name>`, and the
+`file_sessions` / `universal_files` facades built on `call_validated` — routes
+through one queue-aware core. If the server's immediate response is a queued-job
+envelope (either deployed shape: `poll_with`/`store: "queuemgr"`, or
+`queued_after_timeout`), the client polls `queue_get_job_status` for you until
+the job reaches a terminal state, then returns the unwrapped inner result — the
+same shape you'd get from a synchronous call. You never see the raw envelope.
+
+```python
+# No special handling needed: queued or not, this returns the real result.
+out = await client.call("some_long_running_command", {...})
+```
+
+Failures raise instead of returning an error envelope:
+
+* `CommandFailedError` — the job completed but the command itself failed
+  (`inner result {"success": false}` / `command_success is False` /
+  `completed_with_error`). Carries `.command`, `.job_id`, `.error`.
+* `JobFailedError` — the job failed/stopped/cancelled, or reported `error`.
+  Carries `.job_id`, `.error`, `.status`.
+* `JobTimeoutError` — only raised when you pass an explicit `timeout` and it
+  elapses; the job keeps running server-side. By default (`timeout=None`) the
+  client polls until the job finishes, however long that takes.
+
+Optional keyword args on `call` / `call_validated` (and their `call_unified*`
+counterparts): `timeout` (seconds, default `None` = wait until terminal),
+`poll_interval` (seconds between polls, default `1.0`), `status_hook` (sync or
+async callable invoked with each poll's status dict).
+
+`call_unified` / `call_unified_validated` are kept as **deprecated aliases** of
+`call` / `call_validated` for backward compatibility — `expect_queue` and
+`auto_poll` are accepted but ignored, since queue handling is now always on.
+Prefer `call` / `call_validated` directly.
 
 ## Validation using the server schema
 
@@ -61,7 +95,7 @@ async with CodeAnalysisAsyncClient(host="127.0.0.1", port=15001) as client:
     client.clear_command_schema_cache()
 ```
 
-Use `call_unified_validated` when you need queue polling. Pass `refresh_schema=True` on a single call to bypass the in-memory schema cache.
+Pass `refresh_schema=True` on a single call to bypass the in-memory schema cache.
 
 ## High-level facades (aligned with live server registry)
 

{code_analysis_client-1.6.56 → code_analysis_client-1.6.58}/code_analysis_client/__init__.py

@@ -16,7 +16,13 @@ from code_analysis_client.config import (
     adapter_settings_to_jsonrpc_kwargs,
     load_server_config,
 )
-from code_analysis_client.exceptions import ClientValidationError
+from code_analysis_client.exceptions import (
+    ClientValidationError,
+    CommandFailedError,
+    JobFailedError,
+    JobTimeoutError,
+    QueueJobError,
+)
 from code_analysis_client.file_session import FileSessionClient, SessionNotFoundError
 from code_analysis_client.server_api import (
     CLIENT_FACADE_COMMANDS,
@@ -43,10 +49,14 @@ __all__ = [
     "CST_REMOVED_COMMANDS",
     "ClientValidationError",
     "CodeAnalysisAsyncClient",
+    "CommandFailedError",
     "FILE_SESSION_COMMANDS",
     "FILE_SESSION_FACADE_METHODS",
     "FileSessionClient",
+    "JobFailedError",
+    "JobTimeoutError",
     "LEGACY_REMOVED_COMMANDS",
+    "QueueJobError",
     "REMOVED_COMMANDS",
     "SessionNotFoundError",
     "TRANSFER_FACADE_METHODS",

{code_analysis_client-1.6.56 → code_analysis_client-1.6.58}/code_analysis_client/client.py

@@ -8,7 +8,7 @@ email: vasilyvz@gmail.com
 from __future__ import annotations
 
 from pathlib import Path
-from typing import Any, Callable, Dict, Mapping, Optional
+from typing import Any, Dict, Mapping, Optional
 
 try:
     from mcp_proxy_adapter.client.jsonrpc_client.client import JsonRpcClient
@@ -22,6 +22,13 @@ from code_analysis_client.config import (
     load_server_config,
 )
 from code_analysis_client.file_session import FileSessionClient
+from code_analysis_client.queue_wait import (
+    StatusHook,
+    extract_job_id,
+    is_queued_envelope,
+    unwrap_job_result,
+    wait_for_job,
+)
 from code_analysis_client.universal_file import UniversalFileClient
 from code_analysis_client.server_schema import fetch_command_schema_from_server
 from code_analysis_client.validation import (
@@ -141,6 +148,44 @@ class CodeAnalysisAsyncClient:
         self._command_schema_cache[command] = schema
         return schema
 
+    async def _execute(
+        self,
+        command: str,
+        params: Optional[Dict[str, Any]] = None,
+        *,
+        use_cmd_endpoint: bool = False,
+        timeout: Optional[float] = None,
+        poll_interval: float = 1.0,
+        status_hook: Optional[StatusHook] = None,
+    ) -> Dict[str, Any]:
+        """Single queue-aware core every public entry point routes through.
+
+        Runs ``command`` via the raw adapter ``execute_command``. If the
+        immediate response is a queue-service envelope
+        (:func:`code_analysis_client.queue_wait.is_queued_envelope`), polls the
+        job to completion (:func:`~code_analysis_client.queue_wait.wait_for_job`)
+        and returns the unwrapped inner result
+        (:func:`~code_analysis_client.queue_wait.unwrap_job_result`), raising on
+        failure. A non-queued response is returned unchanged.
+        """
+        resp = await self._rpc.execute_command(
+            command,
+            params or {},
+            use_cmd_endpoint=use_cmd_endpoint,
+        )
+        if not is_queued_envelope(resp):
+            return resp
+
+        job_id = extract_job_id(resp)
+        status = await wait_for_job(
+            self._rpc,
+            job_id,
+            timeout=timeout,
+            poll_interval=poll_interval,
+            status_hook=status_hook,
+        )
+        return await unwrap_job_result(status, rpc=self._rpc)
+
     async def call_validated(
         self,
         command: str,
@@ -148,16 +193,22 @@ class CodeAnalysisAsyncClient:
         *,
         use_cmd_endpoint: bool = False,
         refresh_schema: bool = False,
+        timeout: Optional[float] = None,
+        poll_interval: float = 1.0,
+        status_hook: Optional[StatusHook] = None,
     ) -> Dict[str, Any]:
-        """``help`` → schema on server, shallow local validation, then ``execute_command``."""
+        """``help`` → schema on server, shallow local validation, then the queue-aware core."""
         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._rpc.execute_command(
+        return await self._execute(
             command,
             prepared,
             use_cmd_endpoint=use_cmd_endpoint,
+            timeout=timeout,
+            poll_interval=poll_interval,
+            status_hook=status_hook,
         )
 
     async def call_unified_validated(
@@ -171,21 +222,25 @@ class CodeAnalysisAsyncClient:
         auto_poll: bool = True,
         poll_interval: float = 1.0,
         timeout: Optional[float] = None,
-        status_hook: Optional[Callable[[Dict[str, Any]], Any]] = None,
+        status_hook: Optional[StatusHook] = None,
     ) -> Dict[str, Any]:
-        """Same as :meth:`call_validated` but uses ``execute_command_unified``."""
+        """Deprecated alias for :meth:`call_validated`.
+
+        ``expect_queue`` and ``auto_poll`` are accepted only for backward
+        compatibility and are ignored: every path is now queue-aware
+        unconditionally through the shared :meth:`_execute` core (no more
+        adapter ``execute_command_unified``). Prefer :meth:`call_validated`.
+        """
         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._rpc.execute_command_unified(
+        return await self._execute(
             command,
             prepared,
             use_cmd_endpoint=use_cmd_endpoint,
-            expect_queue=expect_queue,
-            auto_poll=auto_poll,
-            poll_interval=poll_interval,
             timeout=timeout,
+            poll_interval=poll_interval,
             status_hook=status_hook,
         )
 
@@ -195,12 +250,18 @@ class CodeAnalysisAsyncClient:
         params: Optional[Dict[str, Any]] = None,
         *,
         use_cmd_endpoint: bool = False,
+        timeout: Optional[float] = None,
+        poll_interval: float = 1.0,
+        status_hook: Optional[StatusHook] = None,
     ) -> Dict[str, Any]:
-        """Run any registered server command (sync completion)."""
-        return await self._rpc.execute_command(
+        """Run any registered server command; queued jobs are polled to completion."""
+        return await self._execute(
             command,
-            params or {},
+            params,
             use_cmd_endpoint=use_cmd_endpoint,
+            timeout=timeout,
+            poll_interval=poll_interval,
+            status_hook=status_hook,
         )
 
     async def call_unified(
@@ -213,17 +274,21 @@ class CodeAnalysisAsyncClient:
         auto_poll: bool = True,
         poll_interval: float = 1.0,
         timeout: Optional[float] = None,
-        status_hook: Optional[Callable[[Dict[str, Any]], Any]] = None,
+        status_hook: Optional[StatusHook] = None,
     ) -> Dict[str, Any]:
-        """Run a command with optional queue detection and polling (adapter unified path)."""
-        return await self._rpc.execute_command_unified(
+        """Deprecated alias for :meth:`call`.
+
+        ``expect_queue`` and ``auto_poll`` are accepted only for backward
+        compatibility and are ignored: every path is now queue-aware
+        unconditionally through the shared :meth:`_execute` core (no more
+        adapter ``execute_command_unified``). Prefer :meth:`call`.
+        """
+        return await self._execute(
             command,
-            params or {},
+            params,
             use_cmd_endpoint=use_cmd_endpoint,
-            expect_queue=expect_queue,
-            auto_poll=auto_poll,
-            poll_interval=poll_interval,
             timeout=timeout,
+            poll_interval=poll_interval,
             status_hook=status_hook,
         )
 

code_analysis_client-1.6.58/code_analysis_client/exceptions.py

@@ -0,0 +1,108 @@
+"""
+Client-side errors: parameter-validation failures and queued-job runtime errors.
+
+No dependency on the code_analysis server package.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+
+class ClientValidationError(ValueError):
+    """Parameters do not match the command JSON schema (from server ``help``)."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        field: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Initialize validation error with optional field and details payload."""
+        super().__init__(message)
+        self.field = field
+        self.details = details or {}
+
+
+class QueueJobError(RuntimeError):
+    """Base for queued-job runtime errors (job failure, timeout, command failure).
+
+    Deliberately does **not** inherit :class:`ClientValidationError`. That class
+    represents bad input caught before a call is even sent, and an
+    ``except ClientValidationError:`` handler written for that purpose must not
+    silently swallow a runtime failure that happened server-side after a valid
+    call was queued and polled. Catch ``QueueJobError`` (or its subclasses)
+    separately from parameter-validation errors.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        job_id: Optional[str] = None,
+        details: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Initialize with message, the job id involved, and a details payload."""
+        super().__init__(message)
+        self.job_id = job_id
+        self.details = details or {}
+
+
+class JobFailedError(QueueJobError):
+    """A queued job failed/stopped/cancelled, or reported an ``error`` status."""
+
+    def __init__(
+        self,
+        job_id: Optional[str],
+        error: Any = None,
+        *,
+        status: Optional[str] = None,
+    ) -> None:
+        """Store job id, verbatim error payload, and terminal status."""
+        message = f"Job {job_id!r} failed (status={status!r}): {error!r}"
+        super().__init__(
+            message,
+            job_id=job_id,
+            details={"job_id": job_id, "status": status, "error": error},
+        )
+        self.error = error
+        self.status = status
+
+
+class JobTimeoutError(QueueJobError):
+    """Polling exceeded ``timeout``; the job keeps running server-side."""
+
+    def __init__(self, job_id: Optional[str], timeout: Optional[float]) -> None:
+        """Store job id and the timeout that was exceeded."""
+        message = (
+            f"Timed out after {timeout}s waiting for job {job_id!r}; "
+            "the job keeps running server-side - poll queue_get_job_status "
+            "manually or retry with a longer timeout."
+        )
+        super().__init__(
+            message,
+            job_id=job_id,
+            details={"job_id": job_id, "timeout": timeout},
+        )
+        self.timeout = timeout
+
+
+class CommandFailedError(QueueJobError):
+    """A queued command completed but its inner result is an error envelope."""
+
+    def __init__(
+        self, command: Optional[str], job_id: Optional[str], error: Any
+    ) -> None:
+        """Store command name, job id, and the verbatim inner error object."""
+        message = f"Command {command!r} failed (job_id={job_id!r}): {error!r}"
+        super().__init__(
+            message,
+            job_id=job_id,
+            details={"command": command, "job_id": job_id, "error": error},
+        )
+        self.command = command
+        self.error = error

code_analysis_client-1.6.58/code_analysis_client/queue_wait.py

@@ -0,0 +1,256 @@
+"""
+Queue-aware polling core: detect queued-job envelopes, poll them to completion,
+and unwrap the inner command result.
+
+Author: Vasiliy Zdanovskiy
+email: vasilyvz@gmail.com
+"""
+
+from __future__ import annotations
+
+import asyncio
+import inspect
+import time
+from typing import Any, Awaitable, Callable, Dict, Optional, Union
+
+from code_analysis_client.exceptions import (
+    CommandFailedError,
+    JobFailedError,
+    JobTimeoutError,
+)
+
+# Keys a pure queue-service envelope may carry. A response whose keys are NOT a
+# subset of this set carries real payload data alongside job_id/status and must
+# never be mistaken for a queued placeholder (e.g. `search`, which returns both
+# `job_id` for pagination and actual result items).
+_SERVICE_ENVELOPE_KEYS = {
+    "success",
+    "job_id",
+    "jobId",
+    "status",
+    "message",
+    "store",
+    "poll_with",
+    "queued_after_timeout",
+    "data",
+}
+
+_QUEUED_STATUSES = {"pending", "queued", "running"}
+_TERMINAL_STATUSES = {"completed", "failed", "stopped", "cancelled"}
+_FAILED_JOB_STATUSES = {"failed", "stopped", "cancelled"}
+
+StatusHook = Callable[[Dict[str, Any]], Union[Any, Awaitable[Any]]]
+
+
+def is_queued_envelope(resp: Dict[str, Any]) -> bool:
+    """Return True when ``resp`` is a queue-service envelope (either deployed variant).
+
+    Detection rule: a ``job_id``/``jobId`` is present (top level or under
+    ``data``) AND one of:
+      * ``poll_with == "queue_get_job_status"``
+      * ``store == "queuemgr"``
+      * ``queued_after_timeout`` is truthy
+      * ``status`` is one of pending/queued/running AND the envelope's own keys
+        are a subset of the known queue-service key set (this subset guard is
+        what prevents false positives on commands like ``search`` whose
+        legitimate result also carries a ``job_id`` plus real payload keys).
+
+    Known out-of-scope gap: this only recognizes the two deployed variants
+    above, both of which carry an explicit marker (``poll_with``/``store``/
+    ``queued_after_timeout``) or a top-level ``status`` alongside a
+    service-only key set. An initial response whose pending status and
+    ``job_id`` live ONLY under ``data`` with no top-level marker at all (e.g.
+    ``{"success": true, "data": {"job_id": ..., "status": "pending"}}`` and
+    nothing else at top level) is NOT one of the two documented variants and
+    is therefore NOT detected as queued — it would be returned as-is instead
+    of polled. If a third server-side queueing shape ever ships in that form,
+    this function must be extended explicitly; it does not infer queuing from
+    ``data``-nested status alone, to avoid reintroducing false positives on
+    ordinary nested-data command results.
+    """
+    if not isinstance(resp, dict):
+        return False
+
+    job_id = resp.get("job_id") or resp.get("jobId")
+    if not job_id:
+        data = resp.get("data")
+        if isinstance(data, dict):
+            job_id = data.get("job_id") or data.get("jobId")
+    if not job_id:
+        return False
+
+    if resp.get("poll_with") == "queue_get_job_status":
+        return True
+    if resp.get("store") == "queuemgr":
+        return True
+    if resp.get("queued_after_timeout"):
+        return True
+
+    status = resp.get("status")
+    if status in _QUEUED_STATUSES and set(resp.keys()) <= _SERVICE_ENVELOPE_KEYS:
+        return True
+
+    return False
+
+
+def extract_job_id(resp: Dict[str, Any]) -> str:
+    """Pull the job identifier out of a queued envelope (top level or under data).
+
+    Public so callers that already confirmed :func:`is_queued_envelope` (e.g.
+    the client core's ``_execute``) reuse this instead of duplicating the
+    top-level/``data``-nested lookup inline.
+    """
+    job_id = resp.get("job_id") or resp.get("jobId")
+    if not job_id:
+        data = resp.get("data")
+        if isinstance(data, dict):
+            job_id = data.get("job_id") or data.get("jobId")
+    return str(job_id)
+
+
+async def _call_status_hook(
+    status_hook: Optional[StatusHook], data: Dict[str, Any]
+) -> None:
+    """Invoke ``status_hook`` with ``data``, awaiting it when it returns a coroutine."""
+    if status_hook is None:
+        return
+    maybe = status_hook(data)
+    if inspect.isawaitable(maybe):
+        await maybe
+
+
+async def wait_for_job(
+    rpc: Any,
+    job_id: str,
+    *,
+    timeout: Optional[float] = None,
+    poll_interval: float = 1.0,
+    status_hook: Optional[StatusHook] = None,
+) -> Dict[str, Any]:
+    """Poll ``queue_get_job_status`` via the raw adapter ``rpc`` until the job is terminal.
+
+    Uses ``rpc.execute_command`` directly (never the queue-aware core) to avoid
+    recursing back into job polling. ``timeout=None`` (default) polls until the
+    job reaches a terminal state, per the user's requirement. If ``timeout`` is
+    set and exceeded, raises :class:`JobTimeoutError` — the job keeps running
+    server-side.
+    """
+    start = time.monotonic() if timeout is not None else None
+    while True:
+        resp = await rpc.execute_command("queue_get_job_status", {"job_id": job_id})
+        data = resp.get("data") if isinstance(resp, dict) else None
+        if not isinstance(data, dict):
+            data = resp if isinstance(resp, dict) else {}
+
+        await _call_status_hook(status_hook, data)
+
+        status = str(data.get("status", "")).strip().lower()
+        if status in _TERMINAL_STATUSES:
+            return data
+
+        if timeout is not None and start is not None:
+            if (time.monotonic() - start) >= timeout:
+                raise JobTimeoutError(job_id, timeout)
+
+        await asyncio.sleep(poll_interval)
+
+
+_JOB_FAILED_REFETCH_ATTEMPTS = 4
+_JOB_FAILED_REFETCH_SLEEP_SECONDS = 0.5
+
+
+def _extract_inner_command_error(status_data: Dict[str, Any]) -> Any:
+    """Pull the failed command's own structured error out of a job status dict.
+
+    Looks at ``status_data["result"]["result"]["error"]`` first (outer
+    ``result`` is the queue wrapper, inner ``result`` is the command's own
+    result envelope), falling back to ``status_data["result"]["error"]``.
+    Returns ``None`` when neither is present.
+    """
+    result_field = status_data.get("result")
+    if not isinstance(result_field, dict):
+        return None
+    inner_result = result_field.get("result")
+    if isinstance(inner_result, dict) and inner_result.get("error") is not None:
+        return inner_result["error"]
+    if result_field.get("error") is not None:
+        return result_field["error"]
+    return None
+
+
+async def _refetch_inner_command_error(rpc: Any, job_id: str) -> Any:
+    """Re-poll ``queue_get_job_status`` hunting for the inner structured error.
+
+    Write-order gotcha: the queue store writes the job's terminal ``status``
+    slightly BEFORE it writes the ``result`` payload. A caller that reads the
+    status the instant it turns ``failed`` can therefore observe a terminal
+    status with no ``result`` (and no nested inner error) yet, even though the
+    failed command DID record a structured error - it just hasn't landed in
+    the store. Re-fetching a few times with a short sleep gives that second
+    write time to land instead of silently downgrading to ``None``.
+    """
+    for _ in range(_JOB_FAILED_REFETCH_ATTEMPTS):
+        await asyncio.sleep(_JOB_FAILED_REFETCH_SLEEP_SECONDS)
+        resp = await rpc.execute_command("queue_get_job_status", {"job_id": job_id})
+        data = resp.get("data") if isinstance(resp, dict) else None
+        if not isinstance(data, dict):
+            data = resp if isinstance(resp, dict) else {}
+        inner_error = _extract_inner_command_error(data)
+        if inner_error is not None:
+            return inner_error
+    return None
+
+
+async def unwrap_job_result(
+    status_data: Dict[str, Any], *, rpc: Any = None
+) -> Dict[str, Any]:
+    """Extract the inner command result from a terminal job status ``data`` dict.
+
+    Raises :class:`JobFailedError` when the job itself failed/stopped/cancelled
+    or reported ``error``. Raises :class:`CommandFailedError` when the job
+    completed but the inner command result is itself an error envelope.
+    Otherwise returns the inner result dict, in the same shape a sync call
+    would have returned.
+
+    On job failure, before raising, this tries to attach the failed command's
+    OWN structured error (nested at ``data.result.result.error``, falling
+    back to ``data.result.error``) to ``JobFailedError.error`` instead of the
+    bare queue-level ``error`` field. When that nested error is not yet
+    present in ``status_data`` and ``rpc`` was supplied, it re-fetches the job
+    status up to :data:`_JOB_FAILED_REFETCH_ATTEMPTS` times (see
+    :func:`_refetch_inner_command_error` for the write-order race this rides
+    out). The queue-level ``error`` field is used as a fallback when no
+    structured inner error is ever found; ``JobFailedError.error`` is ``None``
+    only when genuinely nothing was found either way.
+    """
+    job_id = status_data.get("job_id")
+    status = str(status_data.get("status", "")).strip().lower()
+    error = status_data.get("error")
+
+    if status in _FAILED_JOB_STATUSES or error:
+        inner_error = _extract_inner_command_error(status_data)
+        if inner_error is None and rpc is not None and job_id:
+            inner_error = await _refetch_inner_command_error(rpc, str(job_id))
+        raise JobFailedError(
+            job_id, inner_error if inner_error is not None else error, status=status
+        )
+
+    result_field = status_data.get("result")
+    if isinstance(result_field, dict) and "result" in result_field:
+        inner = result_field["result"]
+    else:
+        inner = result_field
+
+    inner_looks_failed = isinstance(inner, dict) and inner.get("success") is False
+    command_success_false = status_data.get("command_success") is False
+    completed_with_error = bool(status_data.get("completed_with_error")) or bool(
+        status_data.get("native_completed_with_error")
+    )
+
+    if inner_looks_failed or command_success_false or completed_with_error:
+        command = (
+            result_field.get("command") if isinstance(result_field, dict) else None
+        )
+        raise CommandFailedError(command, job_id, inner)
+
+    return inner if isinstance(inner, dict) else {"result": inner}

code_analysis_client-1.6.58/code_analysis_client/version.txt

@@ -0,0 +1 @@
+1.6.58

{code_analysis_client-1.6.56 → code_analysis_client-1.6.58}/code_analysis_client.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: code-analysis-client
-Version: 1.6.56
+Version: 1.6.58
 Summary: Async JSON-RPC client for the code-analysis MCP server (mcp-proxy-adapter JsonRpcClient)
 Author-email: Vasiliy Zdanovskiy <vasilyvz@gmail.com>
 Requires-Python: >=3.10
@@ -54,7 +54,41 @@ from code_analysis_client import CodeAnalysisAsyncClient
 client = CodeAnalysisAsyncClient.from_server_config(config_dict, timeout=60.0)
 ```
 
-Queued/long commands: use `client.call_unified(..., expect_queue=True, auto_poll=True)` or the underlying `client.rpc.execute_command_unified(...)`.
+### Queued commands are handled automatically
+
+Every entry point — `call`, `call_validated`, `client.commands.<name>`, and the
+`file_sessions` / `universal_files` facades built on `call_validated` — routes
+through one queue-aware core. If the server's immediate response is a queued-job
+envelope (either deployed shape: `poll_with`/`store: "queuemgr"`, or
+`queued_after_timeout`), the client polls `queue_get_job_status` for you until
+the job reaches a terminal state, then returns the unwrapped inner result — the
+same shape you'd get from a synchronous call. You never see the raw envelope.
+
+```python
+# No special handling needed: queued or not, this returns the real result.
+out = await client.call("some_long_running_command", {...})
+```
+
+Failures raise instead of returning an error envelope:
+
+* `CommandFailedError` — the job completed but the command itself failed
+  (`inner result {"success": false}` / `command_success is False` /
+  `completed_with_error`). Carries `.command`, `.job_id`, `.error`.
+* `JobFailedError` — the job failed/stopped/cancelled, or reported `error`.
+  Carries `.job_id`, `.error`, `.status`.
+* `JobTimeoutError` — only raised when you pass an explicit `timeout` and it
+  elapses; the job keeps running server-side. By default (`timeout=None`) the
+  client polls until the job finishes, however long that takes.
+
+Optional keyword args on `call` / `call_validated` (and their `call_unified*`
+counterparts): `timeout` (seconds, default `None` = wait until terminal),
+`poll_interval` (seconds between polls, default `1.0`), `status_hook` (sync or
+async callable invoked with each poll's status dict).
+
+`call_unified` / `call_unified_validated` are kept as **deprecated aliases** of
+`call` / `call_validated` for backward compatibility — `expect_queue` and
+`auto_poll` are accepted but ignored, since queue handling is now always on.
+Prefer `call` / `call_validated` directly.
 
 ## Validation using the server schema
 
@@ -73,7 +107,7 @@ async with CodeAnalysisAsyncClient(host="127.0.0.1", port=15001) as client:
     client.clear_command_schema_cache()
 ```
 
-Use `call_unified_validated` when you need queue polling. Pass `refresh_schema=True` on a single call to bypass the in-memory schema cache.
+Pass `refresh_schema=True` on a single call to bypass the in-memory schema cache.
 
 ## High-level facades (aligned with live server registry)
 

{code_analysis_client-1.6.56 → code_analysis_client-1.6.58}/code_analysis_client.egg-info/SOURCES.txt

@@ -7,6 +7,7 @@ code_analysis_client/config.py
 code_analysis_client/exceptions.py
 code_analysis_client/file_session.py
 code_analysis_client/py.typed
+code_analysis_client/queue_wait.py
 code_analysis_client/responses.py
 code_analysis_client/server_api.py
 code_analysis_client/server_schema.py

code_analysis_client-1.6.56/code_analysis_client/exceptions.py

@@ -1,21 +0,0 @@
-"""Client-side errors (no dependency on code_analysis server package)."""
-
-from __future__ import annotations
-
-from typing import Any, Dict, Optional
-
-
-class ClientValidationError(ValueError):
-    """Parameters do not match the command JSON schema (from server ``help``)."""
-
-    def __init__(
-        self,
-        message: str,
-        *,
-        field: Optional[str] = None,
-        details: Optional[Dict[str, Any]] = None,
-    ) -> None:
-        """Initialize validation error with optional field and details payload."""
-        super().__init__(message)
-        self.field = field
-        self.details = details or {}

code_analysis_client-1.6.56/code_analysis_client/version.txt

@@ -1 +0,0 @@
-1.6.56