ctxprotocol 0.20.0__tar.gz → 0.22.0__tar.gz

{ctxprotocol-0.20.0 → ctxprotocol-0.22.0}/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.22.0
+
+- Added `bounded_explicit_empty_result_guardrail` to the query controller stop-reason literal type so strict consumers no longer fail validation when the platform returns that live stop reason.
+- Platform note (no type change): `computed_artifacts` is now capped at 4 per response by the shared artifact emission policy, so SDK/MCP consumers receive exactly the artifact list the web app displays for the identical run.
+
+## 0.21.0
+
+- `client.query.run()` is now backed by the durable job path (`start()` + `poll()`) instead of a held-open SSE connection. One call now reliably covers the full 1800s hosted compute ceiling and survives transient connection drops — the "sometimes works, sometimes times out on hard queries" failure mode is gone. `run()` accepts optional `interval_ms` / `timeout_ms` keyword arguments.
+- `run_or_poll()` is kept as an explicit alias of the same path, and now also synthesizes a fallback developer trace when `include_developer_trace` is set but the backend omits the trace (matching prior `run()` behavior).
+- `client.query.stream()` is unchanged and remains the real-time SSE surface.
+
+## 0.20.0
+
+- Poll defaults aligned with the hosted 1800s compute ceiling: `poll()`/`run_or_poll()` check status every 5 seconds over plain HTTP and wait up to 31 minutes by default.
+- Documented that HTTP polling costs no model tokens; model turns do.
+
 ## 0.19.1
 
 - Fixed `client.query.start()` returning `400 "Invalid query job request"` when called without explicit `tools`. The request body builder now omits optional fields (notably `tools`) when unset instead of serializing them as JSON `null`; the durable jobs endpoint's Zod schema rejects `null` for optional fields. `client.query.run()` and `client.query.stream()` were not failing (the `/api/v1/query` endpoint tolerates `null`), but are now consistent with the TS SDK and MCP behavior.

{ctxprotocol-0.20.0 → ctxprotocol-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ctxprotocol
-Version: 0.20.0
+Version: 0.22.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
@@ -149,7 +149,7 @@ print(
 print(answer.orchestration_metrics)  # Optional first-pass / rediscovery metrics
 ```
 
-For long-running questions from LLM agents, use `run_or_poll()` so the entire wait happens inside one SDK call (one model turn):
+Since 0.21.0 `run()` is backed by the durable job path (`start()` + `poll()`): one call works the same for a 5-second lookup and a 30-minute chart build, with no held-open SSE connection for proxies or client timeouts to kill. `run_or_poll()` remains as an explicit alias:
 
 ```python
 answer = await client.query.run_or_poll(
@@ -249,7 +249,7 @@ 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 JSON API calls |
-| `stream_timeout_seconds` | `float` | No | `600.0` | Timeout for streaming API calls; also used by `client.query.run()` |
+| `stream_timeout_seconds` | `float` | No | `600.0` | Timeout for streaming API calls (`client.query.stream()`) |
 
 ```python
 # Production
@@ -342,7 +342,7 @@ closed = await client.tools.close_session("sess_123")
 
 Run an agentic query. The server applies the live librarian pipeline (`discover -> select -> iterative execute -> synthesize -> settle`) with up to 100 MCP calls per response turn, then returns the selected Query response contract (`answer_with_evidence` or `evidence_only`, default `answer_with_evidence`).
 
-`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.
+Since 0.21.0, `client.query.run()` is backed by the durable job path (`start()` + `poll()`), so a single call reliably covers the full 1800s hosted compute ceiling and survives transient connection drops. This matches the TypeScript SDK. Use `client.query.stream()` when you want real-time SSE events.
 
 The query runtime now exposes a single managed executor surface.
 The server decides internal budgets, ambiguity handling, and exploration policy
@@ -383,7 +383,7 @@ When retrieval-first synthesis rollout is enabled server-side, full-data or trun
 
 #### `client.query.stream(query, tools?, agent_model_id?, include_data?, include_data_url?, include_developer_trace?, idempotency_key?)`
 
-Same as `run()` but streams events in real-time via SSE.
+Runs the same query pipeline as `run()` but over a live SSE connection, yielding events in real-time.
 
 Event types:
 - `tool-status`

{ctxprotocol-0.20.0 → ctxprotocol-0.22.0}/README.md

@@ -111,7 +111,7 @@ print(
 print(answer.orchestration_metrics)  # Optional first-pass / rediscovery metrics
 ```
 
-For long-running questions from LLM agents, use `run_or_poll()` so the entire wait happens inside one SDK call (one model turn):
+Since 0.21.0 `run()` is backed by the durable job path (`start()` + `poll()`): one call works the same for a 5-second lookup and a 30-minute chart build, with no held-open SSE connection for proxies or client timeouts to kill. `run_or_poll()` remains as an explicit alias:
 
 ```python
 answer = await client.query.run_or_poll(
@@ -211,7 +211,7 @@ 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 JSON API calls |
-| `stream_timeout_seconds` | `float` | No | `600.0` | Timeout for streaming API calls; also used by `client.query.run()` |
+| `stream_timeout_seconds` | `float` | No | `600.0` | Timeout for streaming API calls (`client.query.stream()`) |
 
 ```python
 # Production
@@ -304,7 +304,7 @@ closed = await client.tools.close_session("sess_123")
 
 Run an agentic query. The server applies the live librarian pipeline (`discover -> select -> iterative execute -> synthesize -> settle`) with up to 100 MCP calls per response turn, then returns the selected Query response contract (`answer_with_evidence` or `evidence_only`, default `answer_with_evidence`).
 
-`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.
+Since 0.21.0, `client.query.run()` is backed by the durable job path (`start()` + `poll()`), so a single call reliably covers the full 1800s hosted compute ceiling and survives transient connection drops. This matches the TypeScript SDK. Use `client.query.stream()` when you want real-time SSE events.
 
 The query runtime now exposes a single managed executor surface.
 The server decides internal budgets, ambiguity handling, and exploration policy
@@ -345,7 +345,7 @@ When retrieval-first synthesis rollout is enabled server-side, full-data or trun
 
 #### `client.query.stream(query, tools?, agent_model_id?, include_data?, include_data_url?, include_developer_trace?, idempotency_key?)`
 
-Same as `run()` but streams events in real-time via SSE.
+Runs the same query pipeline as `run()` but over a live SSE connection, yielding events in real-time.
 
 Event types:
 - `tool-status`

{ctxprotocol-0.20.0 → ctxprotocol-0.22.0}/ctxprotocol/__init__.py

@@ -31,7 +31,7 @@ Example:
 For more information, visit: https://ctxprotocol.com
 """
 
-__version__ = "0.19.1"
+__version__ = "0.22.0"
 
 # Re-export everything from client module
 from ctxprotocol.client import (

{ctxprotocol-0.20.0 → ctxprotocol-0.22.0}/ctxprotocol/client/resources/query.py

@@ -265,6 +265,8 @@ class Query:
         resume_from: QueryAttemptReference | dict[str, Any] | None = None,
         fork_from: QueryForkReference | dict[str, Any] | None = None,
         idempotency_key: str | None = None,
+        interval_ms: int = DEFAULT_QUERY_POLL_INTERVAL_MS,
+        timeout_ms: int = DEFAULT_QUERY_POLL_TIMEOUT_MS,
     ) -> QueryResult:
         """Run an agentic query and wait for the full response.
 
@@ -272,8 +274,12 @@ class Query:
         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.
+
+        Since 0.21.0 this is backed by the durable job path (``start()`` +
+        ``poll()``), so one call reliably survives the full 1800s hosted
+        compute ceiling and transient connection drops — no held-open SSE
+        connection to be killed by proxies or client timeouts. Use
+        ``stream()`` when you want real-time SSE events instead.
 
         Args:
             query: The natural-language question to answer
@@ -288,6 +294,8 @@ class Query:
             resume_from: Resume a prior durable query attempt
             fork_from: Fork a new durable query attempt from a previous attempt
             idempotency_key: Optional idempotency key (UUID recommended) for safe retries
+            interval_ms: Internal HTTP status-check cadence (costs no LLM tokens)
+            timeout_ms: Max client-side wait for the job's terminal state
 
         Returns:
             The complete query result with response text, tools used, and cost
@@ -311,9 +319,7 @@ class Query:
             ...     tools=["tool-uuid-1", "tool-uuid-2"],
             ... )
         """
-        terminal_error: QueryStreamErrorEvent | None = None
-
-        async for event in self.stream(
+        return await self.run_or_poll(
             query=query,
             tools=tools,
             favorites_only=favorites_only,
@@ -325,21 +331,9 @@ class Query:
             resume_from=resume_from,
             fork_from=fork_from,
             idempotency_key=idempotency_key,
-        ):
-            if event.type == "error":
-                terminal_error = event
-                continue
-
-            if event.type == "done":
-                return event.result
-
-        if terminal_error is not None:
-            raise ContextError(
-                message=terminal_error.error,
-                code=terminal_error.code,
-            )
-
-        raise ContextError("Streaming query ended before done event")
+            interval_ms=interval_ms,
+            timeout_ms=timeout_ms,
+        )
 
     async def start(
         self,
@@ -435,11 +429,11 @@ class Query:
     ) -> QueryResult:
         """Run a durable query job and wait internally for completion.
 
-        This is the recommended one-call helper for LLM agents: the entire
-        wait happens inside this single call (one model turn), instead of one
-        turn per ``get_status()`` check. It also avoids starting a duplicate
-        paid query after a client-side streaming timeout. The job is bounded
-        by the 1800s hosted compute ceiling.
+        ``run()`` delegates here since 0.21.0, so the two are equivalent;
+        ``run_or_poll()`` is kept as an explicit alias. The entire wait
+        happens inside this single call (one model turn for LLM agents),
+        instead of one turn per ``get_status()`` check, and the job is
+        bounded by the 1800s hosted compute ceiling.
         """
         job = await self.start(
             query=query,
@@ -460,7 +454,13 @@ class Query:
             timeout_ms=timeout_ms,
         )
         if completed.status == "completed" and completed.result is not None:
-            return completed.result
+            result = completed.result
+            if include_developer_trace and result.developer_trace is None:
+                result.developer_trace = self._build_synthetic_trace_from_run_result(
+                    result.tools_used,
+                    result.duration_ms,
+                )
+            return result
         raise ContextError(completed.error or "Context query job completed without a result")
 
     async def stream(

{ctxprotocol-0.20.0 → ctxprotocol-0.22.0}/ctxprotocol/client/types.py

@@ -47,6 +47,7 @@ DEFAULT_AGENT_MODEL_ID = "kimi-k2.6-model"
 AGENT_MODEL_IDS = (
     "kimi-k2.6-model",
     "glm-5.2-model",
+    "grok-4.5-model",
     "deepseek-v4-pro-model",
     "deepseek-v4-flash-model",
     "qwen-3.7-plus-model",
@@ -57,6 +58,7 @@ AGENT_MODEL_IDS = (
 AgentModelId = Literal[
     "kimi-k2.6-model",
     "glm-5.2-model",
+    "grok-4.5-model",
     "deepseek-v4-pro-model",
     "deepseek-v4-flash-model",
     "qwen-3.7-plus-model",
@@ -1461,6 +1463,7 @@ QueryControllerStopReason = Literal[
     "bounded_runtime_budget",
     "bounded_same_endpoint_guardrail",
     "bounded_upstream_abort_guardrail",
+    "bounded_explicit_empty_result_guardrail",
     "capability_miss",
 ]
 QueryControllerIssueClass = Literal[

{ctxprotocol-0.20.0 → ctxprotocol-0.22.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ctxprotocol"
-version = "0.20.0"
+version = "0.22.0"
 description = "Official Python SDK for the Context Protocol - Discover and execute AI tools programmatically"
 readme = "README.md"
 license = "MIT"

ctxprotocol-0.22.0/scripts/hermes-parity-sanity-check.py

@@ -0,0 +1,153 @@
+#!/usr/bin/env python3
+"""Throwaway Hermes-parity sanity check for ctxprotocol 0.21.0.
+
+Mirrors ~/.hermes/workspace/ctx-gtm/scripts/ctxprotocol-query.py:
+  - same ContextClient timeouts
+  - same query.run() kwargs (no agent_model_id)
+  - same output contract (JSON + CHART_URL + COST_USD)
+
+Reads CONTEXT_API_KEY from context-sdk/.env.local (or env).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import re
+import sys
+
+SDK_QUERY_TIMEOUT = 1860  # Hermes: 1800s ceiling + 60s grace
+FAVORITES_ONLY = os.environ.get("CTX_FAVORITES_ONLY", "true").strip().lower() in (
+    "true",
+    "1",
+    "yes",
+)
+
+DEFAULT_QUERY = (
+    "What is the current price of Bitcoin? One sentence answer, no charts needed."
+)
+
+
+def load_api_key() -> str:
+    candidates = [
+        os.environ.get("CONTEXT_API_KEY"),
+        _read_env_file(
+            os.path.join(
+                os.path.dirname(__file__),
+                "..",
+                "..",
+                "context-sdk",
+                ".env.local",
+            )
+        ),
+        _read_env_file(
+            os.path.expanduser("~/.hermes/.env"),
+        ),
+    ]
+    for value in candidates:
+        if value:
+            return value
+    print(
+        "ERROR: CONTEXT_API_KEY not found in env, context-sdk/.env.local, or ~/.hermes/.env",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+
+def _read_env_file(path: str) -> str | None:
+    try:
+        with open(os.path.abspath(path)) as handle:
+            for line in handle:
+                line = line.strip()
+                if line.startswith("CONTEXT_API_KEY="):
+                    return line.split("=", 1)[1].strip().strip('"').strip("'")
+    except OSError:
+        return None
+    return None
+
+
+def _chart_urls_from_result(ans) -> list[str]:
+    urls: list[str] = []
+    for art in getattr(ans, "computed_artifacts", None) or []:
+        if getattr(art, "kind", None) == "image":
+            url = getattr(art, "url", None)
+            if url:
+                urls.append(url)
+    if not urls:
+        for text in (getattr(ans, "response", None), getattr(ans, "summary", None)):
+            if not text:
+                continue
+            for match in re.finditer(r"!\[.*?\]\((https?://[^)\s]+)\)", text):
+                urls.append(match.group(1))
+    seen: set[str] = set()
+    deduped: list[str] = []
+    for url in urls:
+        if url not in seen:
+            seen.add(url)
+            deduped.append(url)
+    return deduped
+
+
+def emit(ans) -> None:
+    cost = getattr(ans, "cost", None)
+    total = getattr(cost, "total_cost_usd", None) if cost else None
+    payload = {
+        "response": getattr(ans, "response", None),
+        "summary": getattr(ans, "summary", None),
+        "cost_usd": total,
+        "data_url": getattr(ans, "data_url", None),
+        "tools_used": [
+            {"name": getattr(tool, "name", None), "id": getattr(tool, "id", None)}
+            for tool in (getattr(ans, "tools_used", None) or [])
+        ],
+        "outcome_type": getattr(ans, "outcome_type", None),
+        "stop_reason": getattr(ans, "stop_reason", None),
+        "duration_ms": getattr(ans, "duration_ms", None),
+    }
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+    chart_urls = _chart_urls_from_result(ans)
+    if chart_urls:
+        for index, url in enumerate(chart_urls, start=1):
+            print(f"CHART_URL_{index}: {url}")
+    else:
+        print("CHART_URL_1: none")
+    print(f"COST_USD: {total if total is not None else 'unknown'}")
+
+
+async def run_hermes_style_query(question: str) -> None:
+    from ctxprotocol import ContextClient, __version__
+
+    print(f"ctxprotocol version: {__version__}", file=sys.stderr)
+    print(f"favorites_only: {FAVORITES_ONLY}", file=sys.stderr)
+    print(f"query: {question[:120]}{'...' if len(question) > 120 else ''}", file=sys.stderr)
+
+    async with ContextClient(
+        api_key=load_api_key(),
+        request_timeout_seconds=float(SDK_QUERY_TIMEOUT),
+        stream_timeout_seconds=float(SDK_QUERY_TIMEOUT),
+    ) as client:
+        answer = await client.query.run(
+            query=question,
+            response_shape="answer_with_evidence",
+            include_data=False,
+            include_data_url=True,
+            favorites_only=FAVORITES_ONLY,
+        )
+    emit(answer)
+
+
+def main() -> None:
+    question = sys.argv[1] if len(sys.argv) > 1 else DEFAULT_QUERY
+    try:
+        asyncio.run(run_hermes_style_query(question))
+    except Exception as exc:  # noqa: BLE001
+        print(json.dumps({"error": f"{type(exc).__name__}: {exc}"}, indent=2))
+        print("CHART_URL_1: none")
+        print("COST_USD: unknown")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

ctxprotocol-0.22.0/scripts/hermes-parity-stream-check.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""Throwaway: same Hermes kwargs but via stream() (direct /api/v1/query SSE).
+
+Use to compare job-backed run() vs held-open sync path on long queries.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import os
+import sys
+import time
+
+SDK_QUERY_TIMEOUT = 1860
+FAVORITES_ONLY = True
+
+
+def load_api_key() -> str:
+    path = os.path.abspath(
+        os.path.join(os.path.dirname(__file__), "..", "..", "context-sdk", ".env.local")
+    )
+    with open(path) as handle:
+        for line in handle:
+            if line.startswith("CONTEXT_API_KEY="):
+                return line.split("=", 1)[1].strip().strip('"').strip("'")
+    raise SystemExit("CONTEXT_API_KEY missing")
+
+
+async def main() -> None:
+    query_path = sys.argv[1] if len(sys.argv) > 1 else os.path.join(
+        os.path.dirname(__file__), "saudi-oil-query.txt"
+    )
+    with open(query_path) as handle:
+        query = handle.read().strip()
+
+    from ctxprotocol import ContextClient, __version__
+
+    print(f"stream path | ctxprotocol {__version__}", file=sys.stderr)
+    started = time.time()
+    async with ContextClient(
+        api_key=load_api_key(),
+        request_timeout_seconds=float(SDK_QUERY_TIMEOUT),
+        stream_timeout_seconds=float(SDK_QUERY_TIMEOUT),
+    ) as client:
+        result = None
+        async for event in client.query.stream(
+            query=query,
+            response_shape="answer_with_evidence",
+            include_data=False,
+            include_data_url=True,
+            favorites_only=FAVORITES_ONLY,
+        ):
+            if event.type == "done":
+                result = event.result
+            elif event.type == "error":
+                raise RuntimeError(getattr(event, "message", str(event)))
+
+    elapsed = time.time() - started
+    cost = getattr(getattr(result, "cost", None), "total_cost_usd", None)
+    charts = [
+        getattr(art, "url", None)
+        for art in (getattr(result, "computed_artifacts", None) or [])
+        if getattr(art, "kind", None) == "image" and getattr(art, "url", None)
+    ]
+    print(
+        json.dumps(
+            {
+                "elapsed_s": round(elapsed, 1),
+                "stop_reason": getattr(result, "stop_reason", None),
+                "cost_usd": cost,
+                "chart_count": len(charts),
+                "tools_used": [
+                    getattr(t, "name", None)
+                    for t in (getattr(result, "tools_used", None) or [])
+                ],
+                "response_preview": (getattr(result, "response", None) or "")[:800],
+            },
+            indent=2,
+        )
+    )
+    for index, url in enumerate(charts, start=1):
+        print(f"CHART_URL_{index}: {url}")
+    if not charts:
+        print("CHART_URL_1: none")
+    print(f"COST_USD: {cost}")
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except Exception as exc:  # noqa: BLE001
+        print(json.dumps({"error": f"{type(exc).__name__}: {exc}"}, indent=2))
+        print("CHART_URL_1: none")
+        print("COST_USD: unknown")
+        sys.exit(1)

ctxprotocol-0.22.0/scripts/medium-query.txt

@@ -0,0 +1 @@
+Compare the current price and 7-day trend of Bitcoin and Ethereum, and find one prediction market related to Bitcoin's price this year with its current odds. Provide a short verdict on whether crypto positioning looks bullish or bearish. Text only, no charts needed.

ctxprotocol-0.22.0/scripts/saudi-oil-query.txt

@@ -0,0 +1,16 @@
+A news outlet reported: Saudi Arabia slashed the August price of its flagship Arab Light crude for Asia by $11 a barrel — the biggest reduction in at least 26 years. The move reflects weaker oil markets, rising global supply, and intensifying competition among Gulf producers.
+
+I'm crafting a single tweet for a data-driven Twitter account (@ctxprotocol). The tweet needs one compelling data point and a chart that makes someone stop scrolling.
+
+Search your available tools for data relevant to this story. Use whatever tools fit best — prediction markets, equities intelligence, crypto data, crypto positioning, trading intelligence, or any combination. You don't need to use every tool; pick the ones that produce the most insight for THIS specific story.
+
+For each relevant market or asset you find, I need:
+- Current key metrics (oil price, energy stock price, odds, spread, flow — whatever the tool provides)
+- How has the key metric moved over the market's lifetime or let the backend determine the meaningful time range
+- Positioning/flow: who is on which side? Is smart money aligned with or against the narrative?
+- Catalyst date: when does this market resolve, or when is the next event that could move it? Include for every market/asset found.
+- Follow-up assessment: is this worth revisiting in a future post? What event would trigger a followup?
+
+Deliver a verdict: Was the market surprised by this news, or was it already priced in? What is the single most surprising data point? If you synthesized across multiple tools, what does the combined picture reveal that no single tool shows alone?
+
+Analysis and Chart: You are a master quantitative analyst. Based on all the data you've gathered, what is the most meaningful analysis? Create the most compelling possible chart(s). When the data spans multiple distinct dimensions, splitting into focused charts often produces clearer visuals. Each chart should capture one dimension of the story clearly. Charts must have clean labels, readable legends, and professional styling. Include a labeled chart summary for EACH chart produced, describing what data it shows and the key visual takeaway.

{ctxprotocol-0.20.0 → ctxprotocol-0.22.0}/tests/test_query.py

@@ -397,57 +397,89 @@ def _make_done_stream_response(result: dict[str, Any]) -> _FakeStreamResponse:
     )
 
 
+MOCK_RUN_JOB_ID = "11111111-1111-4111-8111-111111111111"
+
+
+def _job_start_payload() -> dict[str, Any]:
+    """202 payload returned when the durable job behind run() is started."""
+    return {
+        "status": "running",
+        "jobId": MOCK_RUN_JOB_ID,
+        "pollingTool": "context_query_poll",
+        "message": "running",
+        "progress": None,
+        "querySession": None,
+        "createdAt": "2026-06-14T00:00:00.000Z",
+        "updatedAt": "2026-06-14T00:00:00.000Z",
+    }
+
+
+def _job_completed_payload(result: dict[str, Any]) -> dict[str, Any]:
+    """Completed job-status payload carrying the final query result."""
+    return {
+        "status": "completed",
+        "jobId": MOCK_RUN_JOB_ID,
+        "progress": None,
+        "querySession": None,
+        "result": result,
+        "error": None,
+        "createdAt": "2026-06-14T00:00:00.000Z",
+        "updatedAt": "2026-06-14T00:01:00.000Z",
+        "completedAt": "2026-06-14T00:01:00.000Z",
+    }
+
+
+def _job_run_side_effect(result: dict[str, Any]) -> list[dict[str, Any]]:
+    """Mock the job-start + completed-status pair backing run() since 0.21.0."""
+    return [_job_start_payload(), _job_completed_payload(result)]
+
+
 # ============================================================================
 # Tests: query.run()
 # ============================================================================
 
 
 class TestQueryRun:
-    """Tests for client.query.run() — consumes SSE and returns the final result."""
+    """Tests for client.query.run() — durable job path (start + poll) since 0.21.0."""
 
     async def test_sends_correct_request_body_string(self) -> None:
-        """String shorthand sends query with stream: true."""
+        """String shorthand starts a durable job, then polls its status."""
         client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
 
-        with patch.object(
-            client, "fetch_stream", new_callable=AsyncMock
-        ) as mock_stream:
-            mock_stream.return_value = _make_done_stream_response(MOCK_SUCCESS_RESPONSE)
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = _job_run_side_effect(MOCK_SUCCESS_RESPONSE)
             await client.query.run("What are the top whale movements?")
 
-        mock_stream.assert_called_once_with(
-            "/api/v1/query",
-            method="POST",
-            json_body={
-                "query": "What are the top whale movements?",
-                "stream": True,
-            },
-            extra_headers=None,
-        )
+        assert mock_fetch.await_count == 2
+        start_call = mock_fetch.await_args_list[0]
+        assert start_call.args[0] == "/api/v1/query/jobs"
+        assert start_call.kwargs["method"] == "POST"
+        assert start_call.kwargs["json_body"] == {
+            "query": "What are the top whale movements?",
+            "stream": False,
+        }
+        assert start_call.kwargs["extra_headers"] is None
+        status_call = mock_fetch.await_args_list[1]
+        assert status_call.args[0] == f"/api/v1/query/jobs/{MOCK_RUN_JOB_ID}"
 
     async def test_sends_correct_request_body_with_tools(self) -> None:
-        """Options dict with tools sends tool IDs."""
+        """Options dict with tools sends tool IDs to the job start endpoint."""
         client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
 
-        with patch.object(
-            client, "fetch_stream", new_callable=AsyncMock
-        ) as mock_stream:
-            mock_stream.return_value = _make_done_stream_response(MOCK_SUCCESS_RESPONSE)
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = _job_run_side_effect(MOCK_SUCCESS_RESPONSE)
             await client.query.run(
                 query="Analyze whale activity",
                 tools=["tool-uuid-1", "tool-uuid-2"],
             )
 
-        mock_stream.assert_called_once_with(
-            "/api/v1/query",
-            method="POST",
-            json_body={
-                "query": "Analyze whale activity",
-                "tools": ["tool-uuid-1", "tool-uuid-2"],
-                "stream": True,
-            },
-            extra_headers=None,
-        )
+        start_call = mock_fetch.await_args_list[0]
+        assert start_call.args[0] == "/api/v1/query/jobs"
+        assert start_call.kwargs["json_body"] == {
+            "query": "Analyze whale activity",
+            "tools": ["tool-uuid-1", "tool-uuid-2"],
+            "stream": False,
+        }
 
     async def test_forwards_model_and_data_options(self) -> None:
         """Optional model and data controls are forwarded in request body."""
@@ -461,10 +493,8 @@ class TestQueryRun:
             "orchestrationMetrics": MOCK_ORCHESTRATION_METRICS,
         }
 
-        with patch.object(
-            client, "fetch_stream", new_callable=AsyncMock
-        ) as mock_stream:
-            mock_stream.return_value = _make_done_stream_response(success_with_data)
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = _job_run_side_effect(success_with_data)
             result = await client.query.run(
                 query="Analyze whale activity",
                 agent_model_id="kimi-k2.6-model",
@@ -474,20 +504,17 @@ class TestQueryRun:
                 include_developer_trace=True,
             )
 
-        mock_stream.assert_called_once_with(
-            "/api/v1/query",
-            method="POST",
-            json_body={
-                "query": "Analyze whale activity",
-                "stream": True,
-                "agentModelId": "kimi-k2.6-model",
-                "responseShape": "answer_with_evidence",
-                "includeData": True,
-                "includeDataUrl": True,
-                "includeDeveloperTrace": True,
-            },
-            extra_headers=None,
-        )
+        start_call = mock_fetch.await_args_list[0]
+        assert start_call.args[0] == "/api/v1/query/jobs"
+        assert start_call.kwargs["json_body"] == {
+            "query": "Analyze whale activity",
+            "stream": False,
+            "agentModelId": "kimi-k2.6-model",
+            "responseShape": "answer_with_evidence",
+            "includeData": True,
+            "includeDataUrl": True,
+            "includeDeveloperTrace": True,
+        }
         assert result.data == {"summary": "tool output"}
         assert (
             result.data_url
@@ -503,10 +530,8 @@ class TestQueryRun:
         """developerTrace payload is deserialized into QueryResult."""
         client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
 
-        with patch.object(
-            client, "fetch_stream", new_callable=AsyncMock
-        ) as mock_stream:
-            mock_stream.return_value = _make_done_stream_response(
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = _job_run_side_effect(
                 {
                     **MOCK_SUCCESS_RESPONSE,
                     "developerTrace": MOCK_DEVELOPER_TRACE,
@@ -538,10 +563,8 @@ class TestQueryRun:
         """Query result keeps developer_trace unset when API omits it."""
         client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
 
-        with patch.object(
-            client, "fetch_stream", new_callable=AsyncMock
-        ) as mock_stream:
-            mock_stream.return_value = _make_done_stream_response(MOCK_SUCCESS_RESPONSE)
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = _job_run_side_effect(MOCK_SUCCESS_RESPONSE)
             result = await client.query.run("test query")
 
         assert result.developer_trace is None
@@ -550,10 +573,8 @@ class TestQueryRun:
         """When include_developer_trace is set, SDK synthesizes fallback trace if API omits it."""
         client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
 
-        with patch.object(
-            client, "fetch_stream", new_callable=AsyncMock
-        ) as mock_stream:
-            mock_stream.return_value = _make_done_stream_response(MOCK_SUCCESS_RESPONSE)
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = _job_run_side_effect(MOCK_SUCCESS_RESPONSE)
             result = await client.query.run(
                 query="test query",
                 include_developer_trace=True,
@@ -618,10 +639,8 @@ class TestQueryRun:
         """resume_from is forwarded to the query endpoint."""
         client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
 
-        with patch.object(
-            client, "fetch_stream", new_callable=AsyncMock
-        ) as mock_stream:
-            mock_stream.return_value = _make_done_stream_response(MOCK_SUCCESS_RESPONSE)
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = _job_run_side_effect(MOCK_SUCCESS_RESPONSE)
             await client.query.run(
                 query="test query",
                 resume_from={
@@ -630,7 +649,7 @@ class TestQueryRun:
                 },
             )
 
-        body = mock_stream.call_args.kwargs["json_body"]
+        body = mock_fetch.await_args_list[0].kwargs["json_body"]
         assert body["resumeFrom"] == {
             "sessionId": "11111111-1111-4111-8111-111111111111",
             "attemptId": "22222222-2222-4222-8222-222222222222",
@@ -658,10 +677,8 @@ class TestQueryRun:
             },
         }
 
-        with patch.object(
-            client, "fetch_stream", new_callable=AsyncMock
-        ) as mock_stream:
-            mock_stream.return_value = _make_done_stream_response(response)
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = _job_run_side_effect(response)
             result = await client.query.run("test query")
 
         assert result.query_session is not None
@@ -672,35 +689,31 @@ class TestQueryRun:
         """Explicit idempotency key is forwarded as request header."""
         client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
 
-        with patch.object(
-            client, "fetch_stream", new_callable=AsyncMock
-        ) as mock_stream:
-            mock_stream.return_value = _make_done_stream_response(MOCK_SUCCESS_RESPONSE)
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = _job_run_side_effect(MOCK_SUCCESS_RESPONSE)
             await client.query.run(
                 query="Analyze whale activity",
                 tools=["tool-uuid-1"],
                 idempotency_key="7b31f437-61ed-4f76-8a6e-ed2f0766ffb8",
             )
 
-        mock_stream.assert_called_once_with(
-            "/api/v1/query",
-            method="POST",
-            json_body={
-                "query": "Analyze whale activity",
-                "tools": ["tool-uuid-1"],
-                "stream": True,
-            },
-            extra_headers={"Idempotency-Key": "7b31f437-61ed-4f76-8a6e-ed2f0766ffb8"},
-        )
+        start_call = mock_fetch.await_args_list[0]
+        assert start_call.args[0] == "/api/v1/query/jobs"
+        assert start_call.kwargs["json_body"] == {
+            "query": "Analyze whale activity",
+            "tools": ["tool-uuid-1"],
+            "stream": False,
+        }
+        assert start_call.kwargs["extra_headers"] == {
+            "Idempotency-Key": "7b31f437-61ed-4f76-8a6e-ed2f0766ffb8"
+        }
 
     async def test_parses_success_response_into_query_result(self) -> None:
         """Successful API response is deserialized into QueryResult."""
         client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
 
-        with patch.object(
-            client, "fetch_stream", new_callable=AsyncMock
-        ) as mock_stream:
-            mock_stream.return_value = _make_done_stream_response(MOCK_SUCCESS_RESPONSE)
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = _job_run_side_effect(MOCK_SUCCESS_RESPONSE)
             result = await client.query.run("test query")
 
         assert isinstance(result, QueryResult)
@@ -723,10 +736,8 @@ class TestQueryRun:
         """Structured evidence fields are exposed on QueryResult."""
         client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
 
-        with patch.object(
-            client, "fetch_stream", new_callable=AsyncMock
-        ) as mock_stream:
-            mock_stream.return_value = _make_done_stream_response(MOCK_EVIDENCE_RESPONSE)
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = _job_run_side_effect(MOCK_EVIDENCE_RESPONSE)
             result = await client.query.run(
                 query="Where is BTC flowing today?",
                 response_shape="evidence_only",
@@ -746,10 +757,8 @@ class TestQueryRun:
         """Shared SDK fixture preserves computed artifacts and grounding."""
         client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
 
-        with patch.object(
-            client, "fetch_stream", new_callable=AsyncMock
-        ) as mock_stream:
-            mock_stream.return_value = _make_done_stream_response(
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = _job_run_side_effect(
                 SHARED_QUERY_FIXTURE["groundedAnswer"]
             )
             result = await client.query.run(
@@ -864,10 +873,8 @@ class TestQueryRun:
             ],
         }
 
-        with patch.object(
-            client, "fetch_stream", new_callable=AsyncMock
-        ) as mock_stream:
-            mock_stream.return_value = _make_done_stream_response(response)
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = _job_run_side_effect(response)
             result = await client.query.run("Render richer chart artifacts")
 
         assert result.computed_artifacts is not None
@@ -913,10 +920,8 @@ class TestQueryRun:
                 },
             ],
         }
-        with patch.object(
-            client, "fetch_stream", new_callable=AsyncMock
-        ) as mock_stream:
-            mock_stream.return_value = _make_done_stream_response(response)
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = _job_run_side_effect(response)
             result = await client.query.run("Render a chart image")
 
         assert result.computed_artifacts is not None
@@ -934,10 +939,8 @@ class TestQueryRun:
         """Ungrounded runtime outcomes deserialize as capability_miss."""
         client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
 
-        with patch.object(
-            client, "fetch_stream", new_callable=AsyncMock
-        ) as mock_stream:
-            mock_stream.return_value = _make_done_stream_response(
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = _job_run_side_effect(
                 SHARED_QUERY_FIXTURE["ungroundedCapabilityMiss"]
             )
             result = await client.query.run(
@@ -957,10 +960,8 @@ class TestQueryRun:
         """Structured capability miss results deserialize into QueryResult."""
         client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
 
-        with patch.object(
-            client, "fetch_stream", new_callable=AsyncMock
-        ) as mock_stream:
-            mock_stream.return_value = _make_done_stream_response(
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = _job_run_side_effect(
                 MOCK_CAPABILITY_MISS_RESULT
             )
             result = await client.query.run(
@@ -977,43 +978,50 @@ class TestQueryRun:
         ]
         assert len(result.capability_miss.suggested_rewrites) == 3
 
-    async def test_raises_if_run_stream_ends_before_done_event(self) -> None:
-        """Run raises when the stream ends without a done event."""
+    async def test_raises_if_job_completes_without_result(self) -> None:
+        """Run raises when the job completes but carries no result payload."""
         client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
 
-        with patch.object(
-            client, "fetch_stream", new_callable=AsyncMock
-        ) as mock_stream:
-            mock_stream.return_value = _FakeStreamResponse(["data: [DONE]"])
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = [
+                _job_start_payload(),
+                {
+                    **_job_completed_payload(MOCK_SUCCESS_RESPONSE),
+                    "result": None,
+                },
+            ]
 
             with pytest.raises(ContextError) as exc_info:
                 await client.query.run("test query")
 
-        assert "Streaming query ended before done event" in str(exc_info.value)
+        assert "completed without a result" in str(exc_info.value)
 
-    async def test_raises_context_error_on_stream_error_event(self) -> None:
-        """Run raises the terminal SSE error when no done event arrives."""
+    async def test_raises_context_error_when_job_fails(self) -> None:
+        """Run raises the failed job's error message."""
         client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
 
-        with patch.object(
-            client, "fetch_stream", new_callable=AsyncMock
-        ) as mock_stream:
-            mock_stream.return_value = _FakeStreamResponse(MOCK_SSE_ERROR_LINES)
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = [
+                _job_start_payload(),
+                {
+                    **_job_completed_payload(MOCK_SUCCESS_RESPONSE),
+                    "status": "failed",
+                    "result": None,
+                    "error": "Query failed before completion (query_failed)",
+                },
+            ]
 
             with pytest.raises(ContextError) as exc_info:
                 await client.query.run("test query")
 
         assert "Query failed before completion" in str(exc_info.value)
-        assert exc_info.value.code == "query_failed"
 
     async def test_raises_context_error_on_no_wallet(self) -> None:
         """no_wallet error is propagated correctly."""
         client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
 
-        with patch.object(
-            client, "fetch_stream", new_callable=AsyncMock
-        ) as mock_stream:
-            mock_stream.side_effect = ContextError(
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = ContextError(
                 message="Account not fully set up.",
                 code="no_wallet",
                 status_code=400,
@@ -1028,10 +1036,8 @@ class TestQueryRun:
         """query_failed error is propagated correctly."""
         client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
 
-        with patch.object(
-            client, "fetch_stream", new_callable=AsyncMock
-        ) as mock_stream:
-            mock_stream.side_effect = ContextError(
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = ContextError(
                 message="Query failed: Tool execution timed out",
                 code="query_failed",
                 status_code=422,
@@ -1046,10 +1052,8 @@ class TestQueryRun:
         """HTTP errors before stream setup still propagate correctly."""
         client = ContextClient(api_key="ctx_test_key_1234567890abcdef12345678")
 
-        with patch.object(
-            client, "fetch_stream", new_callable=AsyncMock
-        ) as mock_stream:
-            mock_stream.side_effect = ContextError(
+        with patch.object(client, "fetch", new_callable=AsyncMock) as mock_fetch:
+            mock_fetch.side_effect = ContextError(
                 message="Insufficient funds. Set a spending cap in the dashboard.",
                 code="insufficient_allowance",
                 status_code=402,