stacklink-sdk 0.3.7__tar.gz → 0.3.10__tar.gz

{stacklink_sdk-0.3.7/stacklink_sdk.egg-info → stacklink_sdk-0.3.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stacklink-sdk
-Version: 0.3.7
+Version: 0.3.10
 Summary: Python SDK for Stacklink sessions, tools, MCP, auth, workbench, logs, knowledge, and billing.
 Author: Stacklink
 License-Expression: LicenseRef-Proprietary
@@ -9,6 +9,8 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: httpx[http2]<1,>=0.27
+Provides-Extra: x-chat
+Requires-Dist: chatxdk==0.5.0; extra == "x-chat"
 Provides-Extra: openai
 Requires-Dist: openai<3,>=2.0; extra == "openai"
 Provides-Extra: openai-agents
@@ -19,6 +21,32 @@ Dynamic: license-file
 
 # Stacklink Python SDK
 
+## X Chat bot keys
+
+Install `stacklink-sdk[x-chat]` for the official native Chat XDK. Import
+`create_x_bot_chat`, `restore_x_bot_chat` and `XBotChatKeyState` from
+`stacklink.x_chat`. This optional module runs on your bot infrastructure and makes
+no network requests. Personal X Chat remains in the browser SDK; do not pass a
+person's PIN or private keys to this module or to Stacklink's backend.
+
+Call `create_x_bot_chat(account_id, bot_user_id, persist)` once. The `persist`
+callback must store the opaque key state in your secret manager, replacing the
+value for that exact account and bot before returning. Submit the returned
+`registration` public-key payload through X's bot bearer-token API. Fetch the
+registered public-key record, add its exact `user_id`, and call
+`bind_registered_identity(record)`. The helper checks both public keys and their
+binding before exposing `crypto`, the official native XDK for messages, groups,
+reactions, history and encrypted media. Close the session after use.
+
+On restart, call `restore_x_bot_chat(account_id, bot_user_id, stored_state,
+current_public_record, persist)`. Account, bot, key version and both keys must
+match. An uncertain registration must be reconciled using X's current public
+record; do not generate replacement keys automatically. Keep the bot bearer
+token retrieved by `x.getStoredBotToken` in the same customer-owned secret
+manager, separately from its private key blob. Bot bearer tokens are separate
+from a person's OAuth2 grant. This helper supplies local cryptography; it does
+not turn a person's Stacklink connection into a bot connection.
+
 Stacklink supplies executable, governed tools to an agent harness. The selected harness owns the model call, tool loop, and final answer.
 
 Install the public package with the harness extra you use:

{stacklink_sdk-0.3.7 → stacklink_sdk-0.3.10}/README.md

@@ -1,5 +1,31 @@
 # Stacklink Python SDK
 
+## X Chat bot keys
+
+Install `stacklink-sdk[x-chat]` for the official native Chat XDK. Import
+`create_x_bot_chat`, `restore_x_bot_chat` and `XBotChatKeyState` from
+`stacklink.x_chat`. This optional module runs on your bot infrastructure and makes
+no network requests. Personal X Chat remains in the browser SDK; do not pass a
+person's PIN or private keys to this module or to Stacklink's backend.
+
+Call `create_x_bot_chat(account_id, bot_user_id, persist)` once. The `persist`
+callback must store the opaque key state in your secret manager, replacing the
+value for that exact account and bot before returning. Submit the returned
+`registration` public-key payload through X's bot bearer-token API. Fetch the
+registered public-key record, add its exact `user_id`, and call
+`bind_registered_identity(record)`. The helper checks both public keys and their
+binding before exposing `crypto`, the official native XDK for messages, groups,
+reactions, history and encrypted media. Close the session after use.
+
+On restart, call `restore_x_bot_chat(account_id, bot_user_id, stored_state,
+current_public_record, persist)`. Account, bot, key version and both keys must
+match. An uncertain registration must be reconciled using X's current public
+record; do not generate replacement keys automatically. Keep the bot bearer
+token retrieved by `x.getStoredBotToken` in the same customer-owned secret
+manager, separately from its private key blob. Bot bearer tokens are separate
+from a person's OAuth2 grant. This helper supplies local cryptography; it does
+not turn a person's Stacklink connection into a bot connection.
+
 Stacklink supplies executable, governed tools to an agent harness. The selected harness owns the model call, tool loop, and final answer.
 
 Install the public package with the harness extra you use:

{stacklink_sdk-0.3.7 → stacklink_sdk-0.3.10}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stacklink-sdk"
-version = "0.3.7"
+version = "0.3.10"
 description = "Python SDK for Stacklink sessions, tools, MCP, auth, workbench, logs, knowledge, and billing."
 readme = "README.md"
 license = "LicenseRef-Proprietary"
@@ -17,6 +17,7 @@ dependencies = ["httpx[http2]>=0.27,<1"]
 Documentation = "https://docs.stacklink.in/docs/quickstart"
 
 [project.optional-dependencies]
+x-chat = ["chatxdk==0.5.0"]
 openai = ["openai>=2.0,<3"]
 openai-agents = ["openai-agents>=0.18,<0.19"]
 claude-agent = ["claude-agent-sdk>=0.2,<0.3"]

{stacklink_sdk-0.3.7 → stacklink_sdk-0.3.10}/stacklink/client.py

@@ -37,7 +37,7 @@ from .types import Json, Transport
 from .webhooks import WebhooksResource
 from .workbench import WorkbenchResource
 
-STACKLINK_PYTHON_SDK_VERSION = "0.3.7"
+STACKLINK_PYTHON_SDK_VERSION = "0.3.10"
 STACKLINK_PYTHON_USER_AGENT = f"stacklink-python/{STACKLINK_PYTHON_SDK_VERSION}"
 
 
@@ -191,6 +191,7 @@ class Stacklink:
         headers: Mapping[str, str] | None = None,
         total_timeout_ms: int | None = None,
         idle_timeout_ms: int = 30_000,
+        cancel_event: threading.Event | None = None,
     ) -> Iterator[dict[str, Any]]:
         timeout_seconds = _positive_timeout_seconds(total_timeout_ms or int(self.timeout * 1000))
         idle_timeout_seconds = _positive_timeout_seconds(idle_timeout_ms)
@@ -263,7 +264,7 @@ class Stacklink:
                     raise _stream_timeout_error() from error
                 raise StacklinkError("Stacklink stream stopped receiving data.", status_code=408, code="sdk_stream_idle_timeout") from error
 
-        yield from _observe_sync_stream(receive, deadline)
+        yield from _observe_sync_stream(receive, deadline, cancel_event)
 
     def _perform_request(
         self,
@@ -366,7 +367,7 @@ class Stacklink:
         details = body.get("details") if isinstance(body, dict) else None
         if status == 429:
             raise RateLimitError(message or "Stacklink rate limit exceeded.", status_code=status, code=code, details=details, headers=headers)
-        raise StacklinkError(message or "Stacklink request failed.", status_code=status, code=code, details=details)
+        raise StacklinkError(message or "Stacklink request failed.", status_code=status, code=code, details=details, headers=headers)
 
     def _parse_sse_lines(self, lines) -> Iterator[dict[str, Any]]:
         event_id = None
@@ -776,7 +777,7 @@ class _StreamLines:
         return lines
 
 
-def _observe_sync_stream(source: Callable[[threading.Event], Iterator[_StreamValue]], deadline: float) -> Iterator[_StreamValue]:
+def _observe_sync_stream(source: Callable[[threading.Event], Iterator[_StreamValue]], deadline: float, cancel_event: threading.Event | None = None) -> Iterator[_StreamValue]:
     # A blocking httpx read has an inactivity timeout, not a total deadline.
     # Keep it in one reader with bounded backpressure so the caller's observation
     # can end on time. The reader owns and closes the response; it never retries.
@@ -810,13 +811,15 @@ def _observe_sync_stream(source: Callable[[threading.Event], Iterator[_StreamVal
     threading.Thread(target=context.run, args=(read,), daemon=True, name="stacklink-stream-reader").start()
     try:
         while True:
+            if cancel_event is not None and cancel_event.is_set():
+                raise StacklinkError("Execution observation was cancelled.", code="sdk_stream_cancelled")
             remaining = deadline - time.monotonic()
             if remaining <= 0:
                 raise _stream_timeout_error()
             try:
-                kind, value = messages.get(timeout=remaining)
-            except queue.Empty as error:
-                raise _stream_timeout_error() from error
+                kind, value = messages.get(timeout=min(remaining, 0.05) if cancel_event is not None else remaining)
+            except queue.Empty:
+                continue
             if kind == "done":
                 return
             if kind == "error":
@@ -873,7 +876,7 @@ def _handle_response(status: int, headers: Mapping[str, str], body: Json) -> Jso
     details = body.get("details") if isinstance(body, dict) else None
     if status == 429:
         raise RateLimitError(message or "Stacklink rate limit exceeded.", status_code=status, code=code, details=details, headers=headers)
-    raise StacklinkError(message or "Stacklink request failed.", status_code=status, code=code, details=details)
+    raise StacklinkError(message or "Stacklink request failed.", status_code=status, code=code, details=details, headers=headers)
 
 
 def _timeout_error(timeout_seconds: float, request_id: str) -> StacklinkError:

{stacklink_sdk-0.3.7 → stacklink_sdk-0.3.10}/stacklink/errors.py

@@ -1,11 +1,12 @@
 from __future__ import annotations
 
 class StacklinkError(Exception):
-    def __init__(self, message: str, *, status_code: int | None = None, code: str | None = None, details=None):
+    def __init__(self, message: str, *, status_code: int | None = None, code: str | None = None, details=None, headers=None):
         super().__init__(message)
         self.status_code = status_code
         self.code = code
         self.details = details
+        self.headers = headers or {}
 
 
 class RateLimitError(StacklinkError):

{stacklink_sdk-0.3.7 → stacklink_sdk-0.3.10}/stacklink/executions.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import threading
+
 from typing import Any, TypedDict, cast
 
 
@@ -47,6 +49,7 @@ class ExecutionsResource:
         after_sequence: str | None = None,
         limit: int = 200,
         total_timeout_ms: int = 30_000,
+        cancel_event: threading.Event | None = None,
     ):
         return self.client.request_sse(
             "GET",
@@ -58,6 +61,7 @@ class ExecutionsResource:
             },
             headers={"Last-Event-ID": after_sequence} if after_sequence else None,
             total_timeout_ms=total_timeout_ms,
+            cancel_event=cancel_event,
         )
 
     def wait(self, session_id: str, execution_kind: str, execution_id: str, body: dict[str, Any] | None = None):

{stacklink_sdk-0.3.7 → stacklink_sdk-0.3.10}/stacklink/workbench.py

@@ -2,6 +2,9 @@ from __future__ import annotations
 
 import base64
 import time
+import threading
+from email.utils import parsedate_to_datetime
+import httpx
 from typing import Any, Iterator, Literal, Mapping, TypedDict, cast
 from urllib.error import HTTPError
 from urllib.request import Request, urlopen
@@ -482,41 +485,70 @@ class WorkbenchRun:
         self.execution_id = str(response["executionId"])
         self.execution_kind = str(response["executionKind"])
 
-    def events(self, *, stream_timeout_ms: int = 30_000, limit: int = 200) -> Iterator[WorkbenchExecutionEvent]:
-        after_sequence: str | None = None
-        while True:
+    def events(self, *, stream_timeout_ms: int = 30_000, limit: int = 200,
+               total_timeout_ms: int = 3_600_000, max_reconnect_attempts: int = 8,
+               after_sequence: str | None = None, cancel_event: threading.Event | None = None) -> Iterator[WorkbenchExecutionEvent]:
+        if min(stream_timeout_ms, total_timeout_ms, max_reconnect_attempts) <= 0:
+            raise ValueError("Stream timeouts and reconnect attempts must be positive.")
+        deadline = time.monotonic() + total_timeout_ms / 1000
+        cancelled = cancel_event or threading.Event()
+        failures = 0
+        while not cancelled.is_set() and time.monotonic() < deadline:
+            delay = min(1.0, 0.1 * 2 ** min(failures, 4))
             try:
                 stream = self.client.executions.stream(
-                    self.platform_session_id,
-                    self.execution_kind,
-                    self.execution_id,
-                    after_sequence=after_sequence,
-                    limit=limit,
-                    total_timeout_ms=stream_timeout_ms,
+                    self.platform_session_id, self.execution_kind, self.execution_id,
+                    after_sequence=after_sequence, limit=limit, cancel_event=cancelled,
+                    total_timeout_ms=min(stream_timeout_ms, max(1, int((deadline - time.monotonic()) * 1000))),
                 )
-                for message in stream:
-                    payload = message.get("data") if isinstance(message, dict) else None
-                    if not isinstance(payload, dict):
-                        continue
-                    events = payload.get("events")
-                    if isinstance(events, list):
-                        for raw_event in events:
-                            if not isinstance(raw_event, dict):
+                try:
+                    for message in stream:
+                        if cancelled.is_set():
+                            break
+                        payload = message.get("data") if isinstance(message, dict) else None
+                        if not isinstance(payload, dict) or not isinstance(payload.get("events"), list):
+                            raise StacklinkError("Execution stream returned an invalid event page.", code="execution_event_invalid")
+                        failures = 0
+                        for event in payload["events"]:
+                            if not isinstance(event, dict) or not isinstance(event.get("sequence"), (str, int)):
+                                raise StacklinkError("Execution event has no durable sequence.", code="execution_event_invalid")
+                            sequence = str(event["sequence"])
+                            if after_sequence is not None and int(sequence) <= int(after_sequence):
                                 continue
-                            event = cast(WorkbenchExecutionEvent, raw_event)
-                            yield event
-                            sequence = event.get("sequence")
-                            if isinstance(sequence, (str, int)):
-                                after_sequence = str(sequence)
-                    next_cursor = payload.get("nextCursor")
-                    if isinstance(next_cursor, str):
-                        after_sequence = next_cursor
-                    if payload.get("terminal") is True:
-                        return
-            except StacklinkError as error:
-                if error.code != "sdk_stream_timeout":
-                    raise
-                # A bounded connection is resumed from the last durable cursor.
+                            after_sequence = sequence
+                            yield cast(WorkbenchExecutionEvent, event)
+                        next_cursor = payload.get("nextCursor")
+                        if isinstance(next_cursor, str) and (after_sequence is None or int(next_cursor) > int(after_sequence)):
+                            after_sequence = next_cursor
+                        if payload.get("terminal") is True:
+                            return
+                finally:
+                    close = getattr(stream, "close", None)
+                    if close:
+                        close()
+            except (StacklinkError, httpx.TransportError) as error:
+                if isinstance(error, StacklinkError):
+                    if error.code not in {"sdk_stream_timeout", "sdk_stream_idle_timeout"} and error.status_code not in {408, 429, 502, 503, 504}:
+                        raise
+                    headers = getattr(error, "headers", {})
+                    retry_after = next((value for key, value in headers.items() if key.lower() == "retry-after"), None)
+                    if retry_after is not None:
+                        try:
+                            delay = max(0.0, float(retry_after))
+                        except ValueError:
+                            try:
+                                delay = max(0.0, parsedate_to_datetime(retry_after).timestamp() - time.time())
+                            except (ValueError, TypeError, OverflowError):
+                                pass
+            failures += 1
+            if failures > max_reconnect_attempts:
+                raise StacklinkError("Execution observation could not reconnect. Resume the same execution.", code="sdk_stream_reconnect_exhausted", details={"executionId": self.execution_id, "afterSequence": after_sequence})
+            if delay >= deadline - time.monotonic():
+                break
+            cancelled.wait(delay)
+        raise StacklinkError("Execution observation stopped; the operation was not resubmitted or cancelled.",
+                             code="sdk_stream_cancelled" if cancelled.is_set() else "sdk_stream_observation_timeout",
+                             details={"executionId": self.execution_id, "afterSequence": after_sequence})
 
     def wait(self, *, wait_timeout_ms: int | None = None) -> WorkbenchExecutionStateResponse:
         body = {

stacklink_sdk-0.3.10/stacklink/x_chat.py

@@ -0,0 +1,138 @@
+"""Optional native X Chat for bot-owned keys on the customer's infrastructure.
+
+This module performs no HTTP requests. It never accepts a personal Chat PIN.
+Persist key state in your secret manager, never in tool inputs or execution logs.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Callable, Mapping, Any
+
+from chat_xdk import Chat
+
+
+@dataclass(frozen=True)
+class XBotChatKeyState:
+    account_id: str
+    bot_user_id: str
+    key_version: str
+    key_blob: bytes = field(repr=False)
+
+
+class XBotChat:
+    """Binds the official native crypto engine to one bot and registered key.
+
+    ``persist`` must replace the secret for the exact (account_id, bot_user_id)
+    pair before returning. The registered version is part of its stored value.
+    """
+
+    def __init__(self, account_id: str, bot_user_id: str, chat: Chat,
+                 persist: Callable[[XBotChatKeyState], None], key_version: str,
+                 registration: dict[str, Any] | None = None):
+        if not account_id or not bot_user_id or not key_version:
+            raise ValueError("Bind bot keys to an exact account, X user and key version.")
+        self.account_id = account_id
+        self.bot_user_id = bot_user_id
+        self.registration = registration
+        self._chat = chat
+        self._persist = persist
+        self._key_version = key_version
+        self._bound = False
+        self._closed = False
+        chat.set_reject_unverified(True)
+        chat.set_cache_keys(True)
+
+    def _save(self) -> None:
+        blob = self._chat.export_keys()
+        try:
+            self._persist(XBotChatKeyState(self.account_id, self.bot_user_id,
+                                          self._key_version, bytes(blob)))
+        finally:
+            blob[:] = bytes(len(blob))
+
+    def bind_registered_identity(self, record: Mapping[str, str]) -> None:
+        """Bind a fresh public-key record returned by X for this exact bot.
+
+        The identity and signing keys must both match the locally held keys.
+        Only public metadata is passed here; secure-backup tokens are not needed.
+        """
+        if self._closed:
+            raise RuntimeError("This X bot Chat session is closed.")
+        self._bound = False
+        if record.get("user_id") != self.bot_user_id:
+            raise ValueError("The X public-key record belongs to a different bot.")
+        version = record.get("public_key_version")
+        if not version:
+            raise ValueError("X must return the registered public-key version.")
+        challenge = b"stacklink.x_bot_chat.registered_signing_key"
+        if not self._chat.matches_registered_key(record.get("public_key", "")) or not self._chat.verify(
+                record.get("signing_public_key", ""), self._chat.sign(challenge), challenge):
+            raise ValueError("The X public keys do not match this bot's stored keys.")
+        if not self._chat.verify_key_binding(record["public_key"], record["signing_public_key"],
+                                             record["identity_public_key_signature"]):
+            raise ValueError("The X public-key binding is invalid.")
+        self._key_version = version
+        self._chat.set_identity(self.bot_user_id, version)
+        self._save()
+        self._bound = True
+
+    @property
+    def crypto(self) -> Chat:
+        """The official Chat XDK, including messages, groups, events and media."""
+        if self._closed or not self._bound:
+            raise RuntimeError("Bind the registered bot identity before using Chat.")
+        return self._chat
+
+    def close(self) -> None:
+        self._closed = True
+        self._bound = False
+        self._chat.lock()
+
+    def __enter__(self) -> XBotChat:
+        return self
+
+    def __exit__(self, *_: object) -> None:
+        self.close()
+
+
+def create_x_bot_chat(account_id: str, bot_user_id: str,
+                      persist: Callable[[XBotChatKeyState], None]) -> XBotChat:
+    """Generate and persist keys before submitting ``registration`` to X.
+
+    After registration, fetch the bot's public-key record and call
+    ``bind_registered_identity``. An uncertain registration must be reconciled
+    against that record; do not generate a second set of keys automatically.
+    """
+    chat = Chat()
+    try:
+        registration = chat.generate_keypairs()
+        key = registration.public_key
+        body = {"version": registration.version, "generate_version": registration.generate_version,
+                "public_key": {name: getattr(key, name) for name in (
+                    "identity_public_key_signature", "public_key", "public_key_fingerprint",
+                    "registration_method", "signing_public_key", "signing_public_key_signature")}}
+        session = XBotChat(account_id, bot_user_id, chat, persist, str(registration.version), body)
+        session._save()
+        return session
+    except BaseException:
+        chat.lock()
+        raise
+
+
+def restore_x_bot_chat(account_id: str, bot_user_id: str, state: XBotChatKeyState,
+                       record: Mapping[str, str],
+                       persist: Callable[[XBotChatKeyState], None]) -> XBotChat:
+    """Load an exact bot key blob and verify it against the current X record."""
+    if state.account_id != account_id or state.bot_user_id != bot_user_id:
+        raise ValueError("Stored Chat keys belong to a different account or bot.")
+    if state.key_version != record.get("public_key_version"):
+        raise ValueError("The registered bot key version has changed.")
+    chat = Chat()
+    try:
+        chat.import_keys(state.key_blob, version=state.key_version)
+        session = XBotChat(account_id, bot_user_id, chat, persist, state.key_version)
+        session.bind_registered_identity(record)
+        return session
+    except BaseException:
+        chat.lock()
+        raise

{stacklink_sdk-0.3.7 → stacklink_sdk-0.3.10/stacklink_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stacklink-sdk
-Version: 0.3.7
+Version: 0.3.10
 Summary: Python SDK for Stacklink sessions, tools, MCP, auth, workbench, logs, knowledge, and billing.
 Author: Stacklink
 License-Expression: LicenseRef-Proprietary
@@ -9,6 +9,8 @@ Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: httpx[http2]<1,>=0.27
+Provides-Extra: x-chat
+Requires-Dist: chatxdk==0.5.0; extra == "x-chat"
 Provides-Extra: openai
 Requires-Dist: openai<3,>=2.0; extra == "openai"
 Provides-Extra: openai-agents
@@ -19,6 +21,32 @@ Dynamic: license-file
 
 # Stacklink Python SDK
 
+## X Chat bot keys
+
+Install `stacklink-sdk[x-chat]` for the official native Chat XDK. Import
+`create_x_bot_chat`, `restore_x_bot_chat` and `XBotChatKeyState` from
+`stacklink.x_chat`. This optional module runs on your bot infrastructure and makes
+no network requests. Personal X Chat remains in the browser SDK; do not pass a
+person's PIN or private keys to this module or to Stacklink's backend.
+
+Call `create_x_bot_chat(account_id, bot_user_id, persist)` once. The `persist`
+callback must store the opaque key state in your secret manager, replacing the
+value for that exact account and bot before returning. Submit the returned
+`registration` public-key payload through X's bot bearer-token API. Fetch the
+registered public-key record, add its exact `user_id`, and call
+`bind_registered_identity(record)`. The helper checks both public keys and their
+binding before exposing `crypto`, the official native XDK for messages, groups,
+reactions, history and encrypted media. Close the session after use.
+
+On restart, call `restore_x_bot_chat(account_id, bot_user_id, stored_state,
+current_public_record, persist)`. Account, bot, key version and both keys must
+match. An uncertain registration must be reconciled using X's current public
+record; do not generate replacement keys automatically. Keep the bot bearer
+token retrieved by `x.getStoredBotToken` in the same customer-owned secret
+manager, separately from its private key blob. Bot bearer tokens are separate
+from a person's OAuth2 grant. This helper supplies local cryptography; it does
+not turn a person's Stacklink connection into a bot connection.
+
 Stacklink supplies executable, governed tools to an agent harness. The selected harness owns the model call, tool loop, and final answer.
 
 Install the public package with the harness extra you use:

{stacklink_sdk-0.3.7 → stacklink_sdk-0.3.10}/stacklink_sdk.egg-info/SOURCES.txt

@@ -27,6 +27,7 @@ stacklink/triggers.py
 stacklink/types.py
 stacklink/webhooks.py
 stacklink/workbench.py
+stacklink/x_chat.py
 stacklink_sdk.egg-info/PKG-INFO
 stacklink_sdk.egg-info/SOURCES.txt
 stacklink_sdk.egg-info/dependency_links.txt

{stacklink_sdk-0.3.7 → stacklink_sdk-0.3.10}/stacklink_sdk.egg-info/requires.txt

@@ -8,3 +8,6 @@ openai<3,>=2.0
 
 [openai-agents]
 openai-agents<0.19,>=0.18
+
+[x-chat]
+chatxdk==0.5.0

{stacklink_sdk-0.3.7 → stacklink_sdk-0.3.10}/tests/test_client.py

@@ -24,7 +24,7 @@ from stacklink.workbench import WorkbenchRun
 
 
 @contextmanager
-def stalled_stream_server(*, final_result=False):
+def stalled_stream_server(*, final_result=False, execution_page=False):
     """A real HTTP stream that stays open after progress or a complete response."""
     stop = threading.Event()
     requests = []
@@ -43,6 +43,8 @@ def stalled_stream_server(*, final_result=False):
             self.send_header("Content-Type", "text/event-stream")
             self.end_headers()
             message = {"jsonrpc": "2.0", "id": 7, "result": {"name": "नमस्ते"}} if final_result else {"progressToken": 0, "progress": 1}
+            if execution_page:
+                message = {"events": [{"sequence": "1"}], "terminal": False}
             self.wfile.write(("data: " + json.dumps(message, ensure_ascii=False) + "\r\n\r\n").encode("utf-8"))
             self.wfile.flush()
             stop.wait(2)
@@ -1046,6 +1048,51 @@ class StacklinkClientTests(unittest.TestCase):
             {"query": "1", "header": "1"},
         ])
 
+    def test_workbench_observation_recovers_open_body_idle_and_rate_limit(self):
+        for failure in ["open", "body", "idle", "rate"]:
+            with self.subTest(failure=failure):
+                calls = []
+                def stream(*args, **kwargs):
+                    calls.append((args, kwargs))
+                    if len(calls) == 1:
+                        if failure == "open":
+                            raise httpx.ConnectError("offline")
+                        if failure == "rate":
+                            raise StacklinkError("busy", status_code=429, headers={"Retry-After": "0"})
+                        yield {"data": {"events": [{"sequence": "1"}], "terminal": False}}
+                        if failure == "idle":
+                            raise StacklinkError("idle", code="sdk_stream_idle_timeout")
+                        raise httpx.ReadError("interrupted")
+                    yield {"data": {"events": [{"sequence": "1"}, {"sequence": "2", "eventType": "completed"}], "terminal": True}}
+                run = WorkbenchRun(SimpleNamespace(executions=SimpleNamespace(stream=stream)), "session", {"executionId": "same-execution", "executionKind": "workbench_bash"})
+                self.assertEqual([e["sequence"] for e in run.events()], ["1", "2"])
+                self.assertEqual(len(calls), 2)
+                self.assertTrue(all(call[0][2] == "same-execution" for call in calls))
+                self.assertEqual(calls[1][1]["after_sequence"], "1" if failure in {"body", "idle"} else None)
+
+    def test_workbench_observation_honours_retry_after_deadline_and_cancellation(self):
+        def unavailable(*args, **kwargs):
+            raise StacklinkError("busy", status_code=503, headers={"Retry-After": "3600"})
+        run = WorkbenchRun(SimpleNamespace(executions=SimpleNamespace(stream=unavailable)), "session", {"executionId": "same-execution", "executionKind": "workbench_bash"})
+        with self.assertRaises(StacklinkError) as raised:
+            list(run.events(total_timeout_ms=100))
+        self.assertEqual(raised.exception.code, "sdk_stream_observation_timeout")
+        with stalled_stream_server(execution_page=True) as (url, _requests):
+            client = Stacklink(api_key="ppk_test", base_url=url)
+            run = WorkbenchRun(client, "session", {"executionId": "same-execution", "executionKind": "workbench_bash"})
+            cancelled = threading.Event()
+            timer = threading.Timer(0.1, cancelled.set)
+            timer.start()
+            started = time.monotonic()
+            try:
+                with self.assertRaises(StacklinkError) as raised:
+                    list(run.events(cancel_event=cancelled))
+                self.assertEqual(raised.exception.code, "sdk_stream_cancelled")
+                self.assertLess(time.monotonic() - started, 1)
+            finally:
+                timer.cancel()
+                client.close()
+
     def test_bound_workbench_exposes_reusable_run_lifecycle(self):
         calls = []