- Add agent cancellation support and update version to 0.5.0

- feat: enhance proxy handling with AuthorizationRequiredError for unauthenticated requests
- Add blueprint_id to TaskFetchResponse, TaskUpdateRequest, and TaskCreateRequest for enhanced task management
- Clarify comments on message handling in main function for better understanding of execute behavior

Author: pdparchitect

CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to the ChatBotKit Python SDK are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.0] - 2026-07-22
+
+### Added
+
+- Agent cancellation. `agent.execute(...)` and `agent.complete(...)` now accept
+  an `abort_signal` (`asyncio.Event`); setting it stops the loop from the outside
+  (timeout, shutdown, user stop) and exits with code `1` at the next event
+  boundary. The built-in `abort` tool's `hard=True` option now cancels the
+  in-flight iteration immediately instead of being a no-op, bringing the Python
+  agent to parity with the Node and Go SDKs.
+
+### Changed
+
+- The agent system instruction now includes the "Be Responsive" guideline
+  (prioritise new user input mid-run), matching the Node and Go SDKs.
+
 ## [0.4.0] - 2026-06-27
 
 ### Added
@@ -13,8 +29,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   (`oauth`/`jwt` secrets only; owner-only) and return `{ token, expiresAt }`.
   `client.secret.proxy(...)` / `client.contact.secret.proxy(...)` proxy a request
   through a secret — the credential is injected server-side (it never leaves the
-  platform) and the raw upstream `httpx.Response` is returned verbatim. A non-2xx
-  status (including `409 authorization_required`) is returned, not raised.
+  platform) and the upstream `httpx.Response` is returned as-is, success or error.
+- `AuthorizationRequiredError` (exported from `chatbotkit`; a subclass of
+  `APIError`) carrying the `url` the user must visit to authorize. It is raised
+  when a secret or connection has not been authenticated yet
+  (`409 authorization_required`) — by `mint`, by any normal route, and by `proxy`
+  (which otherwise passes every genuine upstream response through untouched).
+  `APIError` now also carries `status_code` and the parsed `data` body.
 
 ## [0.3.0] - 2026-06-26
 

chatbotkit/__init__.py

@@ -1,12 +1,19 @@
 from ._client import ChatBotKit
-from ._transport import APIError, Client, ClientOptions, Response
+from ._transport import (
+    APIError,
+    AuthorizationRequiredError,
+    Client,
+    ClientOptions,
+    Response,
+)
 
 __all__ = [
     "APIError",
+    "AuthorizationRequiredError",
     "ChatBotKit",
     "Client",
     "ClientOptions",
     "Response",
 ]
 
-__version__ = "0.4.0"
+__version__ = "0.5.0"

chatbotkit/_transport.py

@@ -88,12 +88,66 @@ def __init__(
         code: str | None = None,
         status_code: int | None = None,
         url: str | None = None,
+        data: Any = None,
     ) -> None:
         super().__init__(message)
         self.message = message
         self.code = code
         self.status_code = status_code
         self.url = url
+        self.data = data
+
+
+class AuthorizationRequiredError(APIError):
+    """Raised when a secret or connection has not been authenticated yet.
+
+    ``url`` is the address the user must visit to authorize.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: int | None = None,
+        url: str | None = None,
+        data: Any = None,
+    ) -> None:
+        super().__init__(
+            message,
+            code="AUTHORIZATION_REQUIRED",
+            status_code=status_code,
+            url=url,
+            data=data,
+        )
+
+
+def _handle_proxy_response(response: httpx.Response) -> httpx.Response:
+    """Surface a CBK control response from a proxied request.
+
+    Successful and non-JSON error responses are returned untouched; a CBK
+    ``authorization_required`` signal is raised as an AuthorizationRequiredError
+    carrying the authorize URL, while a genuine upstream error is returned as-is.
+    """
+    if response.status_code < 400:
+        return response
+
+    if "application/json" not in response.headers.get("content-type", ""):
+        return response
+
+    try:
+        data = response.json()
+    except ValueError:
+        return response
+
+    if isinstance(data, dict) and data.get("error") == "authorization_required":
+        raise AuthorizationRequiredError(
+            data.get("message") or "authorization required",
+            status_code=response.status_code,
+            url=data.get("url"),
+            data=data,
+        )
+
+    return response
 
 
 class Response(Generic[T, U]):
@@ -272,6 +326,34 @@ async def request(
 
         return response
 
+    async def proxy(
+        self,
+        path: str,
+        *,
+        method: str | None = None,
+        query: Any = None,
+        record: Any = None,
+        headers: Mapping[str, str] | None = None,
+        endpoint: str | None = None,
+    ) -> httpx.Response:
+        """Proxy a request and return the upstream response.
+
+        Successful and upstream-error responses pass through untouched; a CBK
+        ``authorization_required`` signal is raised as an
+        AuthorizationRequiredError carrying the URL the user must visit.
+        """
+        response = await self.request(
+            path,
+            method=method,
+            query=query,
+            record=record,
+            headers=headers,
+            endpoint=endpoint,
+            raw=True,
+        )
+
+        return _handle_proxy_response(response)
+
     def stream(
         self,
         path: str,
@@ -371,18 +453,29 @@ async def raise_for_status(self, response: httpx.Response) -> None:
 
         message = f"HTTP Error: {response.reason_phrase}"
         code = f"ERROR_{response.status_code}"
+        data: Any = None
 
         try:
             data = response.json()
-            message = data.get("message") or message
-            code = data.get("code") or code
+            if isinstance(data, dict):
+                message = data.get("message") or message
+                code = data.get("code") or code
         except ValueError:
             body = await response.aread()
             message = body.decode() or f"HTTP Error: {response.status_code}"
 
+        if isinstance(data, dict) and data.get("error") == "authorization_required":
+            raise AuthorizationRequiredError(
+                message,
+                status_code=response.status_code,
+                url=data.get("url"),
+                data=data,
+            )
+
         raise APIError(
             message,
             code=code,
             status_code=response.status_code,
             url=str(response.url),
+            data=data,
         )