ctxprotocol 0.8.4__tar.gz → 0.9.0__tar.gz

{ctxprotocol-0.8.4 → ctxprotocol-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxprotocol
-Version: 0.8.4
+Version: 0.9.0
 Summary: Official Python SDK for the Context Protocol - Discover and execute AI tools programmatically
 Project-URL: Homepage, https://ctxprotocol.com
 Project-URL: Documentation, https://docs.ctxprotocol.com
@@ -125,7 +125,7 @@ result = await client.tools.execute(
 print(result.session)  # method_price, spent, remaining, max_spend, ...
 ```
 
-**Query mode** gives you curated answers — the server handles answer-safe tool discovery, multi-tool orchestration (up to 100 MCP calls per response turn), self-healing retries, completeness checks, model-aware context budgeting, and AI synthesis for one flat fee:
+**Query mode** gives you curated answers — the server runs a discovery-first planner contract (`discover/probe -> plan-from-evidence -> execute -> bounded fallback`) with model-aware context budgeting and AI synthesis for one flat fee:
 ```python
 answer = await client.query.run(
     query="What are the top whale movements on Base?",
@@ -139,6 +139,12 @@ print(answer.tools_used)  # Which tools were used
 print(answer.cost)        # Cost breakdown
 print(answer.data_url)    # Optional blob URL with full data
 print(answer.developer_trace.summary if answer.developer_trace else None)
+print(
+    answer.developer_trace.diagnostics.selection
+    if answer.developer_trace and answer.developer_trace.diagnostics
+    else None
+)
+print(answer.orchestration_metrics)  # Optional first-pass / rediscovery metrics
 ```
 
 > Mixed listings are first-class: one listing can expose methods to both surfaces. Methods without `_meta.pricing.executeUsd` remain query-only until priced.
@@ -187,8 +193,8 @@ See a full dual-surface client script in [`examples/two-surfaces-client.py`](./e
 |--------|------|----------|---------|-------------|
 | `api_key` | `str` | Yes | — | Your Context Protocol API key |
 | `base_url` | `str` | No | `https://www.ctxprotocol.com` | API base URL (for development) |
-| `request_timeout_seconds` | `float` | No | `300.0` | Timeout for non-streaming API calls |
-| `stream_timeout_seconds` | `float` | No | `600.0` | Timeout for establishing streaming API calls |
+| `request_timeout_seconds` | `float` | No | `300.0` | Timeout for non-streaming JSON API calls |
+| `stream_timeout_seconds` | `float` | No | `600.0` | Timeout for streaming API calls; also used by `client.query.run()` |
 
 ```python
 # Production
@@ -277,15 +283,20 @@ closed = await client.tools.close_session("sess_123")
 
 ### Query (Pay-Per-Response)
 
-#### `client.query.run(query, tools?, model_id?, include_data?, include_data_url?, include_developer_trace?, query_depth?, idempotency_key?)`
+#### `client.query.run(query, tools?, model_id?, include_data?, include_data_url?, include_developer_trace?, query_depth?, debug_scout_deep_mode?, idempotency_key?)`
+
+Run an agentic query. The server applies discovery-first orchestration (`discover/probe -> plan-from-evidence -> execute -> bounded fallback`) with up to 100 MCP calls per response turn, then returns an AI-synthesized answer.
 
-Run an agentic query. The server discovers answer-safe tools, executes the full pipeline (up to 100 MCP calls per response turn), applies model-aware mediator/data budgeting, and returns an AI-synthesized answer.
+`client.query.run()` buffers the same SSE transport used by `client.query.stream()` and returns the final `done` result. This keeps Python aligned with the TypeScript SDK and the live query runtime.
 
 `query_depth` controls orchestration depth:
 - `fast`: lower-latency path for simple lookups.
 - `auto`: server routes to either `fast` or `deep` from query intent + selected tool complexity.
 - `deep`: completeness-oriented path (default when omitted).
 
+`include_developer_trace` and `orchestration_metrics` are optional diagnostics.
+`debug_scout_deep_mode` remains test-only and should not be used in production flows.
+
 ```python
 # Simple string
 answer = await client.query.run("What are the top whale movements on Base?")
@@ -308,11 +319,17 @@ print(answer.duration_ms)   # Total time
 print(answer.data)          # Optional execution data (when include_data=True)
 print(answer.data_url)      # Optional blob URL (when include_data_url=True)
 print(answer.developer_trace.summary if answer.developer_trace else None)
+print(
+    answer.developer_trace.diagnostics.selection
+    if answer.developer_trace and answer.developer_trace.diagnostics
+    else None
+)
+print(answer.orchestration_metrics)  # Optional first-pass / rediscovery metrics
 ```
 
 When retrieval-first synthesis rollout is enabled server-side, full-data or truncation-sensitive query requests can switch to retrieval-first context assembly using private stage artifacts and canonical execution data slices. `include_data` and `include_data_url` continue to reference the same canonical dataset used for synthesis.
 
-#### `client.query.stream(query, tools?, model_id?, include_data?, include_data_url?, include_developer_trace?, query_depth?, idempotency_key?)`
+#### `client.query.stream(query, tools?, model_id?, include_data?, include_data_url?, include_developer_trace?, query_depth?, debug_scout_deep_mode?, idempotency_key?)`
 
 Same as `run()` but streams events in real-time via SSE.
 
@@ -320,6 +337,7 @@ Event types:
 - `tool-status`
 - `text-delta`
 - `developer-trace` (when `include_developer_trace=True`)
+- `error`
 - `done`
 
 ```python
@@ -331,6 +349,8 @@ async for event in client.query.stream(
         print(f"Tool {event.tool.name}: {event.status}")
     elif event.type == "text-delta":
         print(event.delta, end="")
+    elif event.type == "error":
+        print(f"\nStream error: {event.error}")
     elif event.type == "done":
         print(f"\nTotal cost: {event.result.cost.total_cost_usd}")
 ```

{ctxprotocol-0.8.4 → ctxprotocol-0.9.0}/README.md

@@ -87,7 +87,7 @@ result = await client.tools.execute(
 print(result.session)  # method_price, spent, remaining, max_spend, ...
 ```
 
-**Query mode** gives you curated answers — the server handles answer-safe tool discovery, multi-tool orchestration (up to 100 MCP calls per response turn), self-healing retries, completeness checks, model-aware context budgeting, and AI synthesis for one flat fee:
+**Query mode** gives you curated answers — the server runs a discovery-first planner contract (`discover/probe -> plan-from-evidence -> execute -> bounded fallback`) with model-aware context budgeting and AI synthesis for one flat fee:
 ```python
 answer = await client.query.run(
     query="What are the top whale movements on Base?",
@@ -101,6 +101,12 @@ print(answer.tools_used)  # Which tools were used
 print(answer.cost)        # Cost breakdown
 print(answer.data_url)    # Optional blob URL with full data
 print(answer.developer_trace.summary if answer.developer_trace else None)
+print(
+    answer.developer_trace.diagnostics.selection
+    if answer.developer_trace and answer.developer_trace.diagnostics
+    else None
+)
+print(answer.orchestration_metrics)  # Optional first-pass / rediscovery metrics
 ```
 
 > Mixed listings are first-class: one listing can expose methods to both surfaces. Methods without `_meta.pricing.executeUsd` remain query-only until priced.
@@ -149,8 +155,8 @@ See a full dual-surface client script in [`examples/two-surfaces-client.py`](./e
 |--------|------|----------|---------|-------------|
 | `api_key` | `str` | Yes | — | Your Context Protocol API key |
 | `base_url` | `str` | No | `https://www.ctxprotocol.com` | API base URL (for development) |
-| `request_timeout_seconds` | `float` | No | `300.0` | Timeout for non-streaming API calls |
-| `stream_timeout_seconds` | `float` | No | `600.0` | Timeout for establishing streaming API calls |
+| `request_timeout_seconds` | `float` | No | `300.0` | Timeout for non-streaming JSON API calls |
+| `stream_timeout_seconds` | `float` | No | `600.0` | Timeout for streaming API calls; also used by `client.query.run()` |
 
 ```python
 # Production
@@ -239,15 +245,20 @@ closed = await client.tools.close_session("sess_123")
 
 ### Query (Pay-Per-Response)
 
-#### `client.query.run(query, tools?, model_id?, include_data?, include_data_url?, include_developer_trace?, query_depth?, idempotency_key?)`
+#### `client.query.run(query, tools?, model_id?, include_data?, include_data_url?, include_developer_trace?, query_depth?, debug_scout_deep_mode?, idempotency_key?)`
+
+Run an agentic query. The server applies discovery-first orchestration (`discover/probe -> plan-from-evidence -> execute -> bounded fallback`) with up to 100 MCP calls per response turn, then returns an AI-synthesized answer.
 
-Run an agentic query. The server discovers answer-safe tools, executes the full pipeline (up to 100 MCP calls per response turn), applies model-aware mediator/data budgeting, and returns an AI-synthesized answer.
+`client.query.run()` buffers the same SSE transport used by `client.query.stream()` and returns the final `done` result. This keeps Python aligned with the TypeScript SDK and the live query runtime.
 
 `query_depth` controls orchestration depth:
 - `fast`: lower-latency path for simple lookups.
 - `auto`: server routes to either `fast` or `deep` from query intent + selected tool complexity.
 - `deep`: completeness-oriented path (default when omitted).
 
+`include_developer_trace` and `orchestration_metrics` are optional diagnostics.
+`debug_scout_deep_mode` remains test-only and should not be used in production flows.
+
 ```python
 # Simple string
 answer = await client.query.run("What are the top whale movements on Base?")
@@ -270,11 +281,17 @@ print(answer.duration_ms)   # Total time
 print(answer.data)          # Optional execution data (when include_data=True)
 print(answer.data_url)      # Optional blob URL (when include_data_url=True)
 print(answer.developer_trace.summary if answer.developer_trace else None)
+print(
+    answer.developer_trace.diagnostics.selection
+    if answer.developer_trace and answer.developer_trace.diagnostics
+    else None
+)
+print(answer.orchestration_metrics)  # Optional first-pass / rediscovery metrics
 ```
 
 When retrieval-first synthesis rollout is enabled server-side, full-data or truncation-sensitive query requests can switch to retrieval-first context assembly using private stage artifacts and canonical execution data slices. `include_data` and `include_data_url` continue to reference the same canonical dataset used for synthesis.
 
-#### `client.query.stream(query, tools?, model_id?, include_data?, include_data_url?, include_developer_trace?, query_depth?, idempotency_key?)`
+#### `client.query.stream(query, tools?, model_id?, include_data?, include_data_url?, include_developer_trace?, query_depth?, debug_scout_deep_mode?, idempotency_key?)`
 
 Same as `run()` but streams events in real-time via SSE.
 
@@ -282,6 +299,7 @@ Event types:
 - `tool-status`
 - `text-delta`
 - `developer-trace` (when `include_developer_trace=True`)
+- `error`
 - `done`
 
 ```python
@@ -293,6 +311,8 @@ async for event in client.query.stream(
         print(f"Tool {event.tool.name}: {event.status}")
     elif event.type == "text-delta":
         print(event.delta, end="")
+    elif event.type == "error":
+        print(f"\nStream error: {event.error}")
     elif event.type == "done":
         print(f"\nTotal cost: {event.result.cost.total_cost_usd}")
 ```

{ctxprotocol-0.8.4 → ctxprotocol-0.9.0}/ctxprotocol/__init__.py

@@ -31,7 +31,7 @@ Example:
 For more information, visit: https://ctxprotocol.com
 """
 
-__version__ = "0.8.4"
+__version__ = "0.8.5"
 
 # Re-export everything from client module
 from ctxprotocol.client import (
@@ -61,13 +61,17 @@ from ctxprotocol.client.types import (
     # Query types (pay-per-response)
     QueryApiSuccessResponse,
     QueryCost,
+    QueryDeepMode,
     QueryDeveloperTrace,
+    QueryDeveloperTraceDiagnostics,
     QueryDeveloperTraceSummary,
     QueryDeveloperTraceStep,
     QueryDeveloperTraceToolRef,
+    QueryOrchestrationMetrics,
     QueryDeveloperTraceLoopInfo,
     QueryStreamDeveloperTraceEvent,
     QueryStreamEvent,
+    QueryStreamErrorEvent,
     QueryOptions,
     QueryResult,
     QueryStreamDoneEvent,
@@ -177,16 +181,20 @@ __all__ = [
     "QueryResult",
     "QueryToolUsage",
     "QueryCost",
+    "QueryDeepMode",
     "QueryDeveloperTrace",
+    "QueryDeveloperTraceDiagnostics",
     "QueryDeveloperTraceSummary",
     "QueryDeveloperTraceStep",
     "QueryDeveloperTraceToolRef",
+    "QueryOrchestrationMetrics",
     "QueryDeveloperTraceLoopInfo",
     "QueryApiSuccessResponse",
     "QueryStreamToolStatusEvent",
     "QueryStreamTextDeltaEvent",
     "QueryStreamDeveloperTraceEvent",
     "QueryStreamDoneEvent",
+    "QueryStreamErrorEvent",
     "QueryStreamEvent",
     "ContextErrorCode",
     # Errors

{ctxprotocol-0.8.4 → ctxprotocol-0.9.0}/ctxprotocol/client/__init__.py

@@ -29,13 +29,17 @@ from ctxprotocol.client.types import (
     # Query types (pay-per-response)
     QueryApiSuccessResponse,
     QueryCost,
+    QueryDeepMode,
     QueryDeveloperTrace,
+    QueryDeveloperTraceDiagnostics,
     QueryDeveloperTraceSummary,
     QueryDeveloperTraceStep,
     QueryDeveloperTraceToolRef,
+    QueryOrchestrationMetrics,
     QueryDeveloperTraceLoopInfo,
     QueryStreamDeveloperTraceEvent,
     QueryStreamEvent,
+    QueryStreamErrorEvent,
     QueryOptions,
     QueryResult,
     QueryStreamDoneEvent,
@@ -80,16 +84,20 @@ __all__ = [
     "QueryResult",
     "QueryToolUsage",
     "QueryCost",
+    "QueryDeepMode",
     "QueryDeveloperTrace",
+    "QueryDeveloperTraceDiagnostics",
     "QueryDeveloperTraceSummary",
     "QueryDeveloperTraceStep",
     "QueryDeveloperTraceToolRef",
+    "QueryOrchestrationMetrics",
     "QueryDeveloperTraceLoopInfo",
     "QueryApiSuccessResponse",
     "QueryStreamToolStatusEvent",
     "QueryStreamTextDeltaEvent",
     "QueryStreamDeveloperTraceEvent",
     "QueryStreamDoneEvent",
+    "QueryStreamErrorEvent",
     "QueryStreamEvent",
     "ContextErrorCode",
     # Errors

{ctxprotocol-0.8.4 → ctxprotocol-0.9.0}/ctxprotocol/client/client.py

@@ -53,8 +53,9 @@ class ContextClient:
         Args:
             api_key: Your Context Protocol API key (format: sk_live_...)
             base_url: Optional base URL override (defaults to https://www.ctxprotocol.com)
-            request_timeout_seconds: Timeout for non-streaming requests (default 300.0s)
-            stream_timeout_seconds: Timeout for establishing streaming requests (default 600.0s)
+            request_timeout_seconds: Timeout for non-streaming JSON requests (default 300.0s)
+            stream_timeout_seconds: Timeout for streaming requests (default 600.0s);
+                also used by query.run(), which follows the SSE done path for parity
 
         Raises:
             ContextError: If API key is not provided or timeout values are invalid
@@ -160,13 +161,20 @@ class ContextClient:
         """
         max_retries = 3
         timeout_seconds = self._request_timeout_seconds
+        method_upper = method.upper()
+        headers = extra_headers or {}
+        can_retry_request = method_upper in {
+            "GET",
+            "HEAD",
+            "OPTIONS",
+        } or "Idempotency-Key" in headers
         last_error: Exception | None = None
 
         for attempt in range(max_retries + 1):
             try:
-                if method == "GET":
+                if method_upper == "GET":
                     response = await self._client.get(endpoint, headers=extra_headers)
-                elif method == "POST":
+                elif method_upper == "POST":
                     response = await self._client.post(
                         endpoint,
                         json=json_body,
@@ -177,7 +185,11 @@ class ContextClient:
 
                 if not response.is_success:
                     # Retry transient 5xx errors
-                    if response.status_code >= 500 and attempt < max_retries:
+                    if (
+                        response.status_code >= 500
+                        and can_retry_request
+                        and attempt < max_retries
+                    ):
                         delay = min(2**attempt, 10)
                         await asyncio.sleep(delay)
                         continue
@@ -203,12 +215,18 @@ class ContextClient:
                         help_url=help_url,
                     )
 
-                return response.json()
+                try:
+                    return response.json()
+                except Exception as exc:
+                    raise ContextError(
+                        message=f"Failed to parse JSON response: {exc}",
+                        status_code=response.status_code,
+                    ) from exc
             except ContextError:
                 raise
             except (httpx.TimeoutException, httpx.TransportError) as exc:
                 last_error = exc
-                if attempt < max_retries:
+                if can_retry_request and attempt < max_retries:
                     delay = min(2**attempt, 10)
                     await asyncio.sleep(delay)
                     continue
@@ -251,13 +269,20 @@ class ContextClient:
         """
         max_retries = 3
         timeout_seconds = self._stream_timeout_seconds
+        method_upper = method.upper()
+        headers = extra_headers or {}
+        can_retry_request = method_upper in {
+            "GET",
+            "HEAD",
+            "OPTIONS",
+        } or "Idempotency-Key" in headers
         last_error: Exception | None = None
 
         for attempt in range(max_retries + 1):
             try:
                 response = await self._stream_client.send(
                     self._stream_client.build_request(
-                        method,
+                        method_upper,
                         endpoint,
                         json=json_body,
                         headers=extra_headers,
@@ -269,7 +294,11 @@ class ContextClient:
                     # Read body before retrying/raising
                     await response.aread()
 
-                    if response.status_code >= 500 and attempt < max_retries:
+                    if (
+                        response.status_code >= 500
+                        and can_retry_request
+                        and attempt < max_retries
+                    ):
                         delay = min(2**attempt, 10)
                         await asyncio.sleep(delay)
                         continue
@@ -299,7 +328,7 @@ class ContextClient:
                 raise
             except (httpx.TimeoutException, httpx.TransportError) as exc:
                 last_error = exc
-                if attempt < max_retries:
+                if can_retry_request and attempt < max_retries:
                     delay = min(2**attempt, 10)
                     await asyncio.sleep(delay)
                     continue

{ctxprotocol-0.8.4 → ctxprotocol-0.9.0}/ctxprotocol/client/resources/discovery.py

@@ -23,6 +23,11 @@ class Discovery:
         """
         self._client = client
 
+    async def get(self, tool_id: str) -> Tool:
+        """Fetch a single marketplace tool by its unique ID."""
+        response = await self._client.fetch(f"/api/v1/tools/{tool_id}")
+        return Tool.model_validate(response)
+
     async def search(
         self,
         query: str,

{ctxprotocol-0.8.4 → ctxprotocol-0.9.0}/ctxprotocol/client/resources/query.py

@@ -3,8 +3,8 @@ Query resource for pay-per-response agentic queries.
 
 Unlike ``tools.execute()`` which calls a single tool once (pay-per-request),
 the Query resource sends a natural-language question and lets the server
-handle tool discovery, multi-tool orchestration, self-healing retries,
-completeness checks, and AI synthesis — all for one flat fee.
+handle discovery-first orchestration (discover/probe -> plan-from-evidence ->
+execute -> bounded fallback) and AI synthesis — all for one flat fee.
 """
 
 from __future__ import annotations
@@ -14,13 +14,13 @@ from typing import TYPE_CHECKING, Any, AsyncGenerator
 
 from ctxprotocol.client.types import (
     ContextError,
-    ExecuteApiErrorResponse,
-    QueryApiSuccessResponse,
     QueryDeveloperTrace,
+    QueryDeepMode,
     QueryDepth,
     QueryResult,
     QueryStreamDeveloperTraceEvent,
     QueryStreamDoneEvent,
+    QueryStreamErrorEvent,
     QueryStreamEvent,
     QueryStreamTextDeltaEvent,
     QueryStreamToolStatusEvent,
@@ -196,14 +196,17 @@ class Query:
         include_data_url: bool | None = None,
         include_developer_trace: bool | None = None,
         query_depth: QueryDepth | None = None,
+        debug_scout_deep_mode: QueryDeepMode | None = None,
         idempotency_key: str | None = None,
     ) -> QueryResult:
         """Run an agentic query and wait for the full response.
 
         The server discovers relevant tools (or uses the ones you specify),
-        executes the full agentic pipeline (up to 100 MCP calls per tool),
+        executes the discovery-first pipeline (up to 100 MCP calls per tool),
         and returns an AI-synthesized answer. Payment is settled after
         successful execution via deferred settlement.
+        Internally this follows the same SSE `done` path as `query.stream()`
+        so Python and TypeScript observe the same query runtime behavior.
 
         Args:
             query: The natural-language question to answer
@@ -213,6 +216,7 @@ class Query:
             include_data_url: Persist execution data to blob and return URL
             include_developer_trace: Include machine-readable Developer Mode traces
             query_depth: Query orchestration depth mode (fast, auto, or deep)
+            debug_scout_deep_mode: Test-only internal deep lane override
             idempotency_key: Optional idempotency key (UUID recommended) for safe retries
 
         Returns:
@@ -237,63 +241,33 @@ class Query:
             ...     tools=["tool-uuid-1", "tool-uuid-2"],
             ... )
         """
-        request_body: dict[str, Any] = {
-            "query": query,
-            "tools": tools,
-            "stream": False,
-        }
-        if model_id is not None:
-            request_body["modelId"] = model_id
-        if include_data is not None:
-            request_body["includeData"] = include_data
-        if include_data_url is not None:
-            request_body["includeDataUrl"] = include_data_url
-        if include_developer_trace is not None:
-            request_body["includeDeveloperTrace"] = include_developer_trace
-        if query_depth is not None:
-            request_body["queryDepth"] = query_depth
+        terminal_error: QueryStreamErrorEvent | None = None
+
+        async for event in self.stream(
+            query=query,
+            tools=tools,
+            model_id=model_id,
+            include_data=include_data,
+            include_data_url=include_data_url,
+            include_developer_trace=include_developer_trace,
+            query_depth=query_depth,
+            debug_scout_deep_mode=debug_scout_deep_mode,
+            idempotency_key=idempotency_key,
+        ):
+            if event.type == "error":
+                terminal_error = event
+                continue
 
-        response = await self._client.fetch(
-            "/api/v1/query",
-            method="POST",
-            json_body=request_body,
-            extra_headers=(
-                {"Idempotency-Key": idempotency_key}
-                if idempotency_key
-                else None
-            ),
-        )
+            if event.type == "done":
+                return event.result
 
-        # Handle error response
-        if "error" in response:
-            error_response = ExecuteApiErrorResponse.model_validate(response)
+        if terminal_error is not None:
             raise ContextError(
-                message=error_response.error,
-                code=error_response.code,
-                status_code=None,
-                help_url=error_response.help_url,
-            )
-
-        # Handle success response
-        if response.get("success"):
-            success_response = QueryApiSuccessResponse.model_validate(response)
-            developer_trace = success_response.developer_trace
-            if include_developer_trace and developer_trace is None:
-                developer_trace = self._build_synthetic_trace_from_run_result(
-                    success_response.tools_used,
-                    success_response.duration_ms,
-                )
-            return QueryResult(
-                response=success_response.response,
-                tools_used=success_response.tools_used,
-                cost=success_response.cost,
-                duration_ms=success_response.duration_ms,
-                data=success_response.data,
-                data_url=success_response.data_url,
-                developer_trace=developer_trace,
+                message=terminal_error.error,
+                code=terminal_error.code,
             )
 
-        raise ContextError("Unexpected response format from query API")
+        raise ContextError("Streaming query ended before done event")
 
     async def stream(
         self,
@@ -304,6 +278,7 @@ class Query:
         include_data_url: bool | None = None,
         include_developer_trace: bool | None = None,
         query_depth: QueryDepth | None = None,
+        debug_scout_deep_mode: QueryDeepMode | None = None,
         idempotency_key: str | None = None,
     ) -> AsyncGenerator[QueryStreamEvent, None]:
         """Run an agentic query with streaming via SSE.
@@ -312,6 +287,7 @@ class Query:
         - ``tool-status`` — A tool started executing or changed status
         - ``text-delta`` — A chunk of the AI response text
         - ``developer-trace`` — Runtime trace metadata (when enabled)
+        - ``error`` — A structured query/runtime error emitted before completion
         - ``done`` — The full response is complete (includes final QueryResult)
 
         Args:
@@ -322,6 +298,7 @@ class Query:
             include_data_url: Persist execution data to blob and return URL
             include_developer_trace: Include machine-readable Developer Mode traces
             query_depth: Query orchestration depth mode (fast, auto, or deep)
+            debug_scout_deep_mode: Test-only internal deep lane override
             idempotency_key: Optional idempotency key (UUID recommended) for safe retries
 
         Yields:
@@ -331,6 +308,8 @@ class Query:
             >>> async for event in client.query.stream("What are the top whale movements?"):
             ...     if event.type == "text-delta":
             ...         print(event.delta, end="")
+            ...     elif event.type == "error":
+            ...         print(f"\\nStream error: {event.error}")
             ...     elif event.type == "done":
             ...         print(f"\\nCost: {event.result.cost.total_cost_usd}")
         """
@@ -349,6 +328,8 @@ class Query:
             request_body["includeDeveloperTrace"] = include_developer_trace
         if query_depth is not None:
             request_body["queryDepth"] = query_depth
+        if debug_scout_deep_mode is not None:
+            request_body["debugScoutDeepMode"] = debug_scout_deep_mode
 
         response = await self._client.fetch_stream(
             "/api/v1/query",
@@ -400,6 +381,8 @@ class Query:
                     trace_event.trace,
                 )
                 yield trace_event
+            elif event_type == "error":
+                yield QueryStreamErrorEvent.model_validate(parsed)
             elif event_type == "done":
                 done_event = QueryStreamDoneEvent.model_validate(parsed)
                 done_trace = self._merge_developer_trace(
@@ -407,10 +390,16 @@ class Query:
                     done_event.result.developer_trace,
                 )
                 if done_trace is None and include_developer_trace:
-                    done_trace = self._build_synthetic_trace_from_stream_status(
-                        status_timeline=status_timeline,
-                        tools_used=done_event.result.tools_used,
-                        duration_ms=done_event.result.duration_ms,
-                    )
+                    if status_timeline:
+                        done_trace = self._build_synthetic_trace_from_stream_status(
+                            status_timeline=status_timeline,
+                            tools_used=done_event.result.tools_used,
+                            duration_ms=done_event.result.duration_ms,
+                        )
+                    else:
+                        done_trace = self._build_synthetic_trace_from_run_result(
+                            done_event.result.tools_used,
+                            done_event.result.duration_ms,
+                        )
                 done_event.result.developer_trace = done_trace
                 yield done_event