code-analysis-client 1.6.240__tar.gz → 1.6.242__tar.gz

{code_analysis_client-1.6.240 → code_analysis_client-1.6.242}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: code-analysis-client
-Version: 1.6.240
+Version: 1.6.242
 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
 Description-Content-Type: text/markdown
-Requires-Dist: mcp-proxy-adapter>=8.11.3
+Requires-Dist: mcp-proxy-adapter>=8.11.5
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
 Requires-Dist: pytest-asyncio>=0.25.0; extra == "dev"
@@ -54,58 +54,89 @@ from code_analysis_client import CodeAnalysisAsyncClient
 client = CodeAnalysisAsyncClient.from_server_config(config_dict, timeout=60.0)
 ```
 
-### Queued commands are handled automatically
+### Every call is the adapter's standard call
 
 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.
+`file_sessions` / `universal_files` / `worktrees` / `check_chains` facades built on
+`call_validated` — goes through one core that uses `mcp-proxy-adapter`'s
+`JsonRpcClient.execute_command_unified`: the command runs in a WebSocket command
+session and the call returns when the terminal event arrives (no polling while the
+socket is up). If `/ws` is unreachable the adapter falls back to RPC polling of
+`queue_get_job_status` and logs one WARNING `WS_UNREACHABLE_RPC_POLLING_FALLBACK`;
+the result is identical. The client has no polling loop of its own.
 
 ```python
-# No special handling needed: queued or not, this returns the real result.
+# Queued or not, this waits and returns the command's own result envelope.
 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.
+* `CommandFailedError` — the command ran but its inner result is
+  `{"success": false}` (immediate and queued commands alike; a failing result is
+  never returned as a dict). Carries `.command`, `.job_id`, `.error` (the server's
+  error object, e.g. `.error["code"]`) and `.result` (the inner envelope).
+* `JobFailedError` — the job failed/stopped/cancelled. Carries `.job_id`, `.status`
+  and `.error` (always a structured error dict).
+* `JobTimeoutError` — only when a positive `timeout` elapses; the call detaches and
+  the job keeps running server-side (`websocket.on_timeout` is `detach`).
+* `ClientValidationError` — the server refused the parameters (JSON-RPC `-32602`);
+  `details` carries the server's `violation` payload.
+* `ValueError` — a negative `timeout` or a non-positive `poll_interval`, before
+  anything is sent.
 
 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` / `call_validated` also take `auto_poll` (default `True`, matching the
-behavior above exactly). Pass `auto_poll=False` to opt out of automatic
-polling: a non-queued response still comes back as the plain domain result,
-but a queued-job response comes back immediately as a `QueuedJob` handle
-instead of blocking until the job finishes.
+counterparts):
+
+* `timeout` — total wait in seconds. `None` (default) uses the client config
+  `websocket.job_wait_timeout`, shipped as `0` = no time limit, so a long queued
+  command is never cut off. A value above 0 raises `JobTimeoutError` and detaches.
+* `poll_interval` — safety-net status-poll cadence in seconds. `None` (default)
+  uses `websocket.terminal_poll_interval` (2 s); a value overrides it per call.
+* `status_hook` — sync or async callable invoked with each adapter WebSocket event
+  (at least the accepted event first and the terminal completed event last). An
+  exception raised by the hook propagates.
+
+`call` / `call_validated` also take `auto_poll` (default `True`). Pass
+`auto_poll=False` to detach as soon as the job id is known: the call returns a
+`QueuedJob` handle immediately — for every command, including ones that finish at
+once — and `timeout`, `poll_interval` and `status_hook` are ignored.
 
 ```python
 from code_analysis_client import QueuedJob
 
-result = await client.call("some_long_running_command", {...}, auto_poll=False)
-if isinstance(result, QueuedJob):
-    # do other work here, then block on it whenever you're ready
-    result = await result.wait()
-# `result` is now the same dict shape a default (auto_poll=True) call returns
+job = await client.call("some_long_running_command", {...}, auto_poll=False)
+assert isinstance(job, QueuedJob)
+# do other work here, then block on it whenever you're ready
+result = await job.wait()   # same result / errors as the default path
 ```
 
-`QueuedJob` exposes `.job_id`, `.envelope` (the raw queue-service response),
-and two async methods: `.wait(timeout=None, poll_interval=1.0, status_hook=None)`
-— polls to completion and returns/raises exactly like the default path — and
-`.status()` — a single `queue_get_job_status` fetch without polling to
-completion.
+`QueuedJob` exposes `.job_id`, `.envelope` (the adapter's acceptance envelope) and two
+async methods: `.wait(timeout=None, poll_interval=None, status_hook=None)` — reads the
+job once and, if it is still running, uses the adapter's WebSocket wait for the job id
+(public API `wait_for_job_via_websocket`), then returns/raises exactly like the default
+path; there is no RPC-polling fallback for an existing job id (a WebSocket failure
+propagates) — and `.status()` — a single `queue_get_job_status` fetch.
+
+#### Explicit adapter timeout configuration
+
+The client hands `JsonRpcClient(ws_config=...)` the explicit defaults
+`code_analysis_client.DEFAULT_CLIENT_ADAPTER_CONFIG` (a `ws_config=` keyword you pass is
+merged over them key by key), so none of the adapter's own 60 s / `cancel` defaults is
+effective:
+
+| `websocket` key | value | meaning |
+|---|---|---|
+| `job_wait_timeout` | 0 | no total bound on a call's wait |
+| `on_timeout` | `detach` | a wait timeout leaves the job running |
+| `receive_timeout` / `receive_timeout_buffer` | 60 / 5 | one receive cap (never limits the total wait) |
+| `heartbeat_interval` | 30 | WebSocket heartbeat |
+| `terminal_poll_interval` | 2 | safety-net poll cadence |
+| `close_timeout` | 5 | socket close bound |
+| `subscribe_settle_delay` / `cancel_grace_seconds` | 0.5 / 0.5 | settle delay, cancel grace |
+
+`job_push`: `on_caller_loss` `detach` (a job survives a lost client), `poll_interval` `0.1`.
+The server ships and applies the same values.
 
 `call_unified` / `call_unified_validated` are kept as **deprecated aliases** of
 `call` / `call_validated` for backward compatibility and emit

{code_analysis_client-1.6.240 → code_analysis_client-1.6.242}/README.md

@@ -42,58 +42,89 @@ from code_analysis_client import CodeAnalysisAsyncClient
 client = CodeAnalysisAsyncClient.from_server_config(config_dict, timeout=60.0)
 ```
 
-### Queued commands are handled automatically
+### Every call is the adapter's standard call
 
 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.
+`file_sessions` / `universal_files` / `worktrees` / `check_chains` facades built on
+`call_validated` — goes through one core that uses `mcp-proxy-adapter`'s
+`JsonRpcClient.execute_command_unified`: the command runs in a WebSocket command
+session and the call returns when the terminal event arrives (no polling while the
+socket is up). If `/ws` is unreachable the adapter falls back to RPC polling of
+`queue_get_job_status` and logs one WARNING `WS_UNREACHABLE_RPC_POLLING_FALLBACK`;
+the result is identical. The client has no polling loop of its own.
 
 ```python
-# No special handling needed: queued or not, this returns the real result.
+# Queued or not, this waits and returns the command's own result envelope.
 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.
+* `CommandFailedError` — the command ran but its inner result is
+  `{"success": false}` (immediate and queued commands alike; a failing result is
+  never returned as a dict). Carries `.command`, `.job_id`, `.error` (the server's
+  error object, e.g. `.error["code"]`) and `.result` (the inner envelope).
+* `JobFailedError` — the job failed/stopped/cancelled. Carries `.job_id`, `.status`
+  and `.error` (always a structured error dict).
+* `JobTimeoutError` — only when a positive `timeout` elapses; the call detaches and
+  the job keeps running server-side (`websocket.on_timeout` is `detach`).
+* `ClientValidationError` — the server refused the parameters (JSON-RPC `-32602`);
+  `details` carries the server's `violation` payload.
+* `ValueError` — a negative `timeout` or a non-positive `poll_interval`, before
+  anything is sent.
 
 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` / `call_validated` also take `auto_poll` (default `True`, matching the
-behavior above exactly). Pass `auto_poll=False` to opt out of automatic
-polling: a non-queued response still comes back as the plain domain result,
-but a queued-job response comes back immediately as a `QueuedJob` handle
-instead of blocking until the job finishes.
+counterparts):
+
+* `timeout` — total wait in seconds. `None` (default) uses the client config
+  `websocket.job_wait_timeout`, shipped as `0` = no time limit, so a long queued
+  command is never cut off. A value above 0 raises `JobTimeoutError` and detaches.
+* `poll_interval` — safety-net status-poll cadence in seconds. `None` (default)
+  uses `websocket.terminal_poll_interval` (2 s); a value overrides it per call.
+* `status_hook` — sync or async callable invoked with each adapter WebSocket event
+  (at least the accepted event first and the terminal completed event last). An
+  exception raised by the hook propagates.
+
+`call` / `call_validated` also take `auto_poll` (default `True`). Pass
+`auto_poll=False` to detach as soon as the job id is known: the call returns a
+`QueuedJob` handle immediately — for every command, including ones that finish at
+once — and `timeout`, `poll_interval` and `status_hook` are ignored.
 
 ```python
 from code_analysis_client import QueuedJob
 
-result = await client.call("some_long_running_command", {...}, auto_poll=False)
-if isinstance(result, QueuedJob):
-    # do other work here, then block on it whenever you're ready
-    result = await result.wait()
-# `result` is now the same dict shape a default (auto_poll=True) call returns
+job = await client.call("some_long_running_command", {...}, auto_poll=False)
+assert isinstance(job, QueuedJob)
+# do other work here, then block on it whenever you're ready
+result = await job.wait()   # same result / errors as the default path
 ```
 
-`QueuedJob` exposes `.job_id`, `.envelope` (the raw queue-service response),
-and two async methods: `.wait(timeout=None, poll_interval=1.0, status_hook=None)`
-— polls to completion and returns/raises exactly like the default path — and
-`.status()` — a single `queue_get_job_status` fetch without polling to
-completion.
+`QueuedJob` exposes `.job_id`, `.envelope` (the adapter's acceptance envelope) and two
+async methods: `.wait(timeout=None, poll_interval=None, status_hook=None)` — reads the
+job once and, if it is still running, uses the adapter's WebSocket wait for the job id
+(public API `wait_for_job_via_websocket`), then returns/raises exactly like the default
+path; there is no RPC-polling fallback for an existing job id (a WebSocket failure
+propagates) — and `.status()` — a single `queue_get_job_status` fetch.
+
+#### Explicit adapter timeout configuration
+
+The client hands `JsonRpcClient(ws_config=...)` the explicit defaults
+`code_analysis_client.DEFAULT_CLIENT_ADAPTER_CONFIG` (a `ws_config=` keyword you pass is
+merged over them key by key), so none of the adapter's own 60 s / `cancel` defaults is
+effective:
+
+| `websocket` key | value | meaning |
+|---|---|---|
+| `job_wait_timeout` | 0 | no total bound on a call's wait |
+| `on_timeout` | `detach` | a wait timeout leaves the job running |
+| `receive_timeout` / `receive_timeout_buffer` | 60 / 5 | one receive cap (never limits the total wait) |
+| `heartbeat_interval` | 30 | WebSocket heartbeat |
+| `terminal_poll_interval` | 2 | safety-net poll cadence |
+| `close_timeout` | 5 | socket close bound |
+| `subscribe_settle_delay` / `cancel_grace_seconds` | 0.5 / 0.5 | settle delay, cancel grace |
+
+`job_push`: `on_caller_loss` `detach` (a job survives a lost client), `poll_interval` `0.1`.
+The server ships and applies the same values.
 
 `call_unified` / `call_unified_validated` are kept as **deprecated aliases** of
 `call` / `call_validated` for backward compatibility and emit

{code_analysis_client-1.6.240 → code_analysis_client-1.6.242}/code_analysis_client/__init__.py

@@ -12,6 +12,7 @@ from pathlib import Path
 from code_analysis_client.client import CodeAnalysisAsyncClient
 from code_analysis_client.commands_proxy import ValidatedCommandsProxy
 from code_analysis_client.config import (
+    DEFAULT_CLIENT_ADAPTER_CONFIG,
     adapter_settings_from_server_config,
     adapter_settings_to_jsonrpc_kwargs,
     load_server_config,
@@ -38,13 +39,7 @@ from code_analysis_client.check_chain import (
     FileCheckAndPromoteResult,
 )
 from code_analysis_client.worktree import WorktreeClient, WorktreeConflictError
-from code_analysis_client.queue_wait import (
-    QueuedJob,
-    extract_job_id,
-    is_queued_envelope,
-    unwrap_job_result,
-    wait_for_job,
-)
+from code_analysis_client.queue_wait import QueuedJob
 from code_analysis_client.server_api import (
     CLIENT_FACADE_COMMANDS,
     CST_REMOVED_COMMANDS,
@@ -76,6 +71,7 @@ from code_analysis_client.vectorizer_state import (
 )
 
 __all__ = [
+    "DEFAULT_CLIENT_ADAPTER_CONFIG",
     "CLIENT_FACADE_COMMANDS",
     "CST_REMOVED_COMMANDS",
     "ClientValidationError",
@@ -114,19 +110,15 @@ __all__ = [
     "WorktreeConflictError",
     "adapter_settings_from_server_config",
     "adapter_settings_to_jsonrpc_kwargs",
-    "extract_job_id",
     "extract_vectorizer_state_from_response",
     "fetch_command_schema_from_server",
-    "is_queued_envelope",
     "load_server_config",
     "parse_schema_from_help_payload",
     "prepare_params_for_schema",
     "safe_get_vectorizer_state",
     "safe_get_warnings",
     "safe_get_vectorization_worker",
-    "unwrap_job_result",
     "validate_params_against_schema",
-    "wait_for_job",
 ]
 
 

{code_analysis_client-1.6.240 → code_analysis_client-1.6.242}/code_analysis_client/check_chain.py

@@ -17,7 +17,7 @@ from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any, Dict, List, Optional
 
 from code_analysis_client.exceptions import ClientValidationError
-from code_analysis_client.responses import command_error_code
+from code_analysis_client.responses import command_error_code, FacadeCaller
 from code_analysis_client.worktree import WorktreeConflictError
 
 if TYPE_CHECKING:
@@ -252,7 +252,7 @@ class CheckChainClient:
 
     def __init__(self, client: CodeAnalysisAsyncClient) -> None:
         """Store the underlying async client."""
-        self._client = client
+        self._client = FacadeCaller(client)  # type: ignore[assignment]
 
     async def list(self, project_id: str) -> CheckChainListResult:
         """Return the resolved chain of every configured extension.