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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stacklink-sdk
-Version: 0.2.2
+Version: 0.3.7
 Summary: Python SDK for Stacklink sessions, tools, MCP, auth, workbench, logs, knowledge, and billing.
 Author: Stacklink
 License-Expression: LicenseRef-Proprietary
@@ -77,8 +77,35 @@ An execution response can be pending. Keep its `executionKind`, `executionId`, s
 
 Retry keys are case-sensitive and accept up to 240 characters. Tool and batch requests have separate key namespaces. Reuse a key only for the exact same request in the same SDK session. Changed inputs return `409 idempotency_key_reused`; an expired stored result returns `410 execution_result_expired`. Neither response authorizes submitting the write again.
 
-For `waiting_for_approval`, your backend can use the session approval read, approve and deny APIs with `platform_approvals:read` / `platform_approvals:manage` scopes. Keep the API key on your backend. A pending action must not be labelled completed. `provider_execution_result_unknown` means an external write may have happened; inspect the provider before considering another action.
+For `waiting_for_approval`, read the shared request using `client.approvals` and `platform_approvals:read`. A decision also needs `platform_approvals:manage` and the authority required by that request. A server key alone cannot approve on behalf of a company person; eligible customer confirmation uses the verified session and its scoped grant. Keep the API key on your backend. A pending action must not be labelled completed. `provider_execution_result_unknown` means an external write may have happened; inspect the provider before considering another action.
 
 Use execution cancellation for an explicit Stop request. Losing a stream only stops observation. Vercel and LangChain adapters forward their supported abort signal; other adapters keep the structured operation identity available for explicit cancellation. MCP progress reports actual stages, not invented percentages.
 
 Streaming has a total observation deadline and a separate inactivity timeout. A timeout raises `sdk_stream_timeout` without repeating the action; use its original operation ID to resume observation. Stream responses are limited to 8 MiB, including JSON responses to streaming requests. The synchronous client keeps blocking reads in a bounded reader and releases the response when that read finishes or reaches its inactivity timeout. Custom transports must honor the timeout passed to them. MCP calls return once all matching responses arrive, even if the server keeps the stream open.
+
+## Hosted Bots (0.3.2)
+
+Bots are saved, published agents with project-scoped configuration and durable runs. Use a server-held project API key with `bots:manage` to create/update/publish, and `bots:run` to invoke. Supply a session established from your authenticated customer; input variables do not grant identity or access. Both SDKs expose run status, replayable events, cancellation and callback delivery recovery. A callback failure does not rerun the model.
+
+```python
+bot = stacklink.bots.get(bot_id)
+run = stacklink.bots.run(bot_id, session_id=session.id, message="Where is my order?", variables={"orderNumber": "4821"})
+for event in stacklink.bots.stream(bot_id, run["id"]):
+    print(event)
+result = stacklink.bots.get_run(bot_id, run["id"])
+print(result["output"] or result["finalText"])
+```
+
+The async client provides the same operations with `await` and `async for`.
+
+Reuse the returned `conversationId` for the next message. Preserve the last event sequence to resume observation. Published invocations are available through the existing session MCP endpoint using `STACKLINK_BOTS`; no separate server per bot is needed.
+
+## Shared approvals (0.3.3)
+
+`client.approvals` lists and retrieves approvals for an authorized session, submits a permitted decision or customer correction, and observes reconnectable approval events. A project key represents an application; it cannot substitute for a required human company approver. `as_customer=True` derives the customer from the authenticated session and still requires a scoped customer grant. Continue observing the original execution after deciding; do not resubmit the action.
+
+All enabled notification channels use the same stored request. Decision, notification delivery and execution have separate states. See the [approval guide](https://docs.stacklink.in/docs/reference/sdk-python#shared-approvals) for request and lifecycle details.
+
+When project settings require Workbench code approval, a foreground code/bash call returns `waiting_for_approval`, `approvalRequestId`, and its original execution ID immediately. No runtime sandbox is allocated for that wait. After the authorized person decides, observe the original execution; do not submit the code again.
+
+Server-side customer grant management (0.3.5): `get_customer_grant`, `save_customer_grant`, and `remove_customer_grant` operate on an authenticated customer session. Save exact tool keys and resource restrictions with the returned settings revision. The server supplies identity from the session; callers cannot choose another customer in the request body. These methods never grant company approval or bypass connected-account access.

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

@@ -58,8 +58,35 @@ An execution response can be pending. Keep its `executionKind`, `executionId`, s
 
 Retry keys are case-sensitive and accept up to 240 characters. Tool and batch requests have separate key namespaces. Reuse a key only for the exact same request in the same SDK session. Changed inputs return `409 idempotency_key_reused`; an expired stored result returns `410 execution_result_expired`. Neither response authorizes submitting the write again.
 
-For `waiting_for_approval`, your backend can use the session approval read, approve and deny APIs with `platform_approvals:read` / `platform_approvals:manage` scopes. Keep the API key on your backend. A pending action must not be labelled completed. `provider_execution_result_unknown` means an external write may have happened; inspect the provider before considering another action.
+For `waiting_for_approval`, read the shared request using `client.approvals` and `platform_approvals:read`. A decision also needs `platform_approvals:manage` and the authority required by that request. A server key alone cannot approve on behalf of a company person; eligible customer confirmation uses the verified session and its scoped grant. Keep the API key on your backend. A pending action must not be labelled completed. `provider_execution_result_unknown` means an external write may have happened; inspect the provider before considering another action.
 
 Use execution cancellation for an explicit Stop request. Losing a stream only stops observation. Vercel and LangChain adapters forward their supported abort signal; other adapters keep the structured operation identity available for explicit cancellation. MCP progress reports actual stages, not invented percentages.
 
 Streaming has a total observation deadline and a separate inactivity timeout. A timeout raises `sdk_stream_timeout` without repeating the action; use its original operation ID to resume observation. Stream responses are limited to 8 MiB, including JSON responses to streaming requests. The synchronous client keeps blocking reads in a bounded reader and releases the response when that read finishes or reaches its inactivity timeout. Custom transports must honor the timeout passed to them. MCP calls return once all matching responses arrive, even if the server keeps the stream open.
+
+## Hosted Bots (0.3.2)
+
+Bots are saved, published agents with project-scoped configuration and durable runs. Use a server-held project API key with `bots:manage` to create/update/publish, and `bots:run` to invoke. Supply a session established from your authenticated customer; input variables do not grant identity or access. Both SDKs expose run status, replayable events, cancellation and callback delivery recovery. A callback failure does not rerun the model.
+
+```python
+bot = stacklink.bots.get(bot_id)
+run = stacklink.bots.run(bot_id, session_id=session.id, message="Where is my order?", variables={"orderNumber": "4821"})
+for event in stacklink.bots.stream(bot_id, run["id"]):
+    print(event)
+result = stacklink.bots.get_run(bot_id, run["id"])
+print(result["output"] or result["finalText"])
+```
+
+The async client provides the same operations with `await` and `async for`.
+
+Reuse the returned `conversationId` for the next message. Preserve the last event sequence to resume observation. Published invocations are available through the existing session MCP endpoint using `STACKLINK_BOTS`; no separate server per bot is needed.
+
+## Shared approvals (0.3.3)
+
+`client.approvals` lists and retrieves approvals for an authorized session, submits a permitted decision or customer correction, and observes reconnectable approval events. A project key represents an application; it cannot substitute for a required human company approver. `as_customer=True` derives the customer from the authenticated session and still requires a scoped customer grant. Continue observing the original execution after deciding; do not resubmit the action.
+
+All enabled notification channels use the same stored request. Decision, notification delivery and execution have separate states. See the [approval guide](https://docs.stacklink.in/docs/reference/sdk-python#shared-approvals) for request and lifecycle details.
+
+When project settings require Workbench code approval, a foreground code/bash call returns `waiting_for_approval`, `approvalRequestId`, and its original execution ID immediately. No runtime sandbox is allocated for that wait. After the authorized person decides, observe the original execution; do not submit the code again.
+
+Server-side customer grant management (0.3.5): `get_customer_grant`, `save_customer_grant`, and `remove_customer_grant` operate on an authenticated customer session. Save exact tool keys and resource restrictions with the returned settings revision. The server supplies identity from the session; callers cannot choose another customer in the request body. These methods never grant company approval or bypass connected-account access.

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stacklink-sdk"
-version = "0.2.2"
+version = "0.3.7"
 description = "Python SDK for Stacklink sessions, tools, MCP, auth, workbench, logs, knowledge, and billing."
 readme = "README.md"
 license = "LicenseRef-Proprietary"

{stacklink_sdk-0.2.2 → stacklink_sdk-0.3.7}/stacklink/__init__.py

@@ -1,5 +1,8 @@
 from __future__ import annotations
 
+from .bots import verify_bot_api_request, sign_bot_trigger_request
+from .approvals import ApprovalDecision, ApprovalRecord, ApprovalEvent, ApprovalPermissions, CustomerApprovalGrantInput
+from .webhooks import verify_webhook_signature
 from .client import AsyncStacklink, STACKLINK_PYTHON_SDK_VERSION, Stacklink
 from .claude_agent import create_stacklink_claude_agent_tool_config
 from .errors import RateLimitError, StacklinkError
@@ -24,7 +27,12 @@ from .types import (
 )
 
 __all__ = [
+    "ApprovalDecision", "ApprovalRecord", "ApprovalEvent", "ApprovalPermissions",
+    "CustomerApprovalGrantInput",
     "Stacklink",
+    "verify_bot_api_request",
+    "sign_bot_trigger_request",
+    "verify_webhook_signature",
     "AsyncStacklink",
     "STACKLINK_PYTHON_SDK_VERSION",
     "StacklinkError",

stacklink_sdk-0.3.7/stacklink/approvals.py

@@ -0,0 +1,118 @@
+"""Shared approvals. Decisions apply to the stored action; never submit that action again."""
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Literal, TypedDict, Iterator, AsyncIterator
+from urllib.parse import quote
+
+
+class ApprovalDecision(TypedDict):
+    requirement: Literal['customer', 'company']
+    decision: Literal['approve', 'decline']
+    expectedRevision: int
+
+
+class CustomerApprovalGrantInput(TypedDict):
+    revision: int
+    name: str
+    toolKeys: list[str]
+    accountIds: list[str]
+    resources: list[dict[str, str | int | float | bool]]
+
+
+class ApprovalPermissions(TypedDict):
+    canDecide: bool
+    canManage: bool
+    requirement: Literal['customer', 'company'] | None
+    reason: str | None
+
+
+class ApprovalRecord(TypedDict):
+    id: str
+    projectId: str
+    sessionId: str | None
+    revision: int
+    status: Literal['pending', 'approved', 'applying', 'applied', 'apply_failed', 'denied', 'cancelled', 'expired']
+    audience: Literal['approvers', 'customer', 'customer-approvers']
+    requirements: list[dict[str, Any]]
+    permissions: ApprovalPermissions
+    execution: dict[str, Any]
+    deliveries: list[dict[str, Any]]
+
+
+class ApprovalEvent(TypedDict):
+    sequence: str
+    approvalId: str
+    type: Literal['approval.request.updated']
+    data: dict[str, Any]
+    occurredAt: str
+
+
+class ApprovalsResource:
+    def __init__(self, client, *, async_mode: bool = False):
+        self.client = client
+        self.async_mode = async_mode
+
+    def get_customer_grant(self, *, session_id: str):
+        """Server-only: identity is resolved from this authenticated customer session."""
+        return self.client.request('GET', '/v1/approvals/customer-grant', query={'sessionId': session_id})
+
+    def save_customer_grant(self, grant: CustomerApprovalGrantInput, *, session_id: str):
+        return self.client.request('PUT', '/v1/approvals/customer-grant', query={'sessionId': session_id}, json_body=grant)
+
+    def remove_customer_grant(self, *, session_id: str, revision: int):
+        return self.client.request('DELETE', '/v1/approvals/customer-grant', query={'sessionId': session_id}, json_body={'revision': revision})
+
+    @staticmethod
+    def _query(session_id: str, as_customer: bool) -> dict[str, Any]:
+        return {'sessionId': session_id, 'asCustomer': 'true' if as_customer else 'false'}
+
+    def list(self, *, session_id: str, as_customer: bool = False, **filters):
+        return self.client.request('GET', '/v1/approvals', query={**filters, **self._query(session_id, as_customer)})
+
+    def get(self, approval_id: str, *, session_id: str, as_customer: bool = False):
+        return self.client.request('GET', '/v1/approvals/' + quote(approval_id, safe=''), query=self._query(session_id, as_customer))
+
+    def decide(self, approval_id: str, decision: ApprovalDecision, *, session_id: str, as_customer: bool = False, reason: str | None = None):
+        """Call only after a current authorized person confirms the displayed exact proposal."""
+        body = dict(decision)
+        if reason is not None:
+            body['reason'] = reason
+        return self.client.request('POST', '/v1/approvals/' + quote(approval_id, safe='') + '/decide', query=self._query(session_id, as_customer), json_body=body)
+
+    def change(self, approval_id: str, *, session_id: str, expected_revision: int, message: str, as_customer: bool = False):
+        return self.client.request('POST', '/v1/approvals/' + quote(approval_id, safe='') + '/change', query=self._query(session_id, as_customer), json_body={'expectedRevision': expected_revision, 'message': message})
+
+    def events(self, *, session_id: str, after: str = '0', as_customer: bool = False, timeout_ms: int = 15_000):
+        return self.client.request('GET', '/v1/approvals/events', query={**self._query(session_id, as_customer), 'after': after}, timeout_ms=timeout_ms)
+
+    def observe(self, *, session_id: str, after: str = '0', as_customer: bool = False, timeout_ms: int = 300_000) -> Iterator[ApprovalEvent] | AsyncIterator[ApprovalEvent]:
+        """Save each sequence and pass it back as after when reconnecting. Close the iterator to stop."""
+        if self.async_mode:
+            return self._observe_async(session_id, after, as_customer, timeout_ms)
+        return self._observe_sync(session_id, after, as_customer, timeout_ms)
+
+    def _observe_sync(self, session_id: str, cursor: str, as_customer: bool, timeout_ms: int) -> Iterator[ApprovalEvent]:
+        deadline = time.monotonic() + timeout_ms / 1000
+        while time.monotonic() < deadline:
+            page = self.events(session_id=session_id, after=cursor, as_customer=as_customer, timeout_ms=max(1, min(15_000, int((deadline - time.monotonic()) * 1000))))
+            for event in page['events']:
+                if int(event['sequence']) <= int(cursor):
+                    continue
+                cursor = event['sequence']
+                yield event
+            if len(page['events']) < 100:
+                time.sleep(max(0, min(1, deadline - time.monotonic())))
+
+    async def _observe_async(self, session_id: str, cursor: str, as_customer: bool, timeout_ms: int) -> AsyncIterator[ApprovalEvent]:
+        deadline = time.monotonic() + timeout_ms / 1000
+        while time.monotonic() < deadline:
+            page = await self.events(session_id=session_id, after=cursor, as_customer=as_customer, timeout_ms=max(1, min(15_000, int((deadline - time.monotonic()) * 1000))))
+            for event in page['events']:
+                if int(event['sequence']) <= int(cursor):
+                    continue
+                cursor = event['sequence']
+                yield event
+            if len(page['events']) < 100:
+                await asyncio.sleep(max(0, min(1, deadline - time.monotonic())))

stacklink_sdk-0.3.7/stacklink/bots.py

@@ -0,0 +1,266 @@
+"""Hosted bot management and durable runs for sync and async clients."""
+from __future__ import annotations
+from typing import Any
+from contextlib import closing, aclosing
+import asyncio
+import base64
+import hashlib
+import hmac
+import json
+import time
+from datetime import datetime
+import httpx
+from .errors import StacklinkError
+from urllib.parse import quote
+from uuid import uuid4
+
+
+def sign_bot_trigger_request(*, trigger_id: str, secret: str, body: str, request_id: str | None = None, now: float | None = None) -> dict[str, str]:
+    """Sign the exact JSON bytes. Reuse request_id when retrying the same event."""
+    timestamp = str(int(time.time() if now is None else now))
+    request_id = request_id or str(uuid4())
+    digest = hashlib.sha256(body.encode("utf-8")).hexdigest()
+    signed = json.dumps(["stacklink-trigger-v1", trigger_id, timestamp, request_id, digest], separators=(",", ":"), ensure_ascii=False)
+    signature = hmac.new(secret.encode("utf-8"), signed.encode("utf-8"), hashlib.sha256).hexdigest()
+    return {"content-type": "application/json", "stacklink-timestamp": timestamp, "stacklink-request-id": request_id, "stacklink-signature": signature}
+
+
+def verify_bot_api_request(*, method: str, url: str, body: str, headers: dict[str, str], project_id: str, keys: dict[str, str | dict], consume_request_id, now: float | None = None, tolerance_seconds: int = 300):
+    """Verify raw request content; consume_request_id(id, expires_at) must atomically reject replays."""
+    normalized = {key.lower(): value for key, value in headers.items()}
+    def get(name):
+        return normalized.get("x-stacklink-" + name, "")
+    key_id, timestamp, request_id = get("key-id"), get("timestamp"), get("request-id")
+    secret, tenant, user = keys.get(key_id), get("tenant"), get("customer")
+    current_time = time.time() if now is None else now
+    if isinstance(secret, dict):
+        expiry = secret.get("validUntil")
+        if expiry is not None:
+            try:
+                if datetime.fromisoformat(expiry[:-1] + '+00:00' if expiry.endswith('Z') else expiry).timestamp() <= current_time:
+                    return None
+            except (ValueError, TypeError):
+                return None
+        secret = secret.get("secret")
+    try:
+        seconds = int(timestamp)
+    except (ValueError, TypeError):
+        return None
+    if not isinstance(secret, str) or not secret or not tenant or not request_id or get("project") != project_id or abs(current_time - seconds) > tolerance_seconds:
+        return None
+    payload = json.dumps(["stacklink-api-v1", method.upper(), url, request_id, timestamp, key_id, project_id, tenant, user, hashlib.sha256(body.encode("utf-8")).hexdigest()], ensure_ascii=False, separators=(",", ":"))
+    expected = "v1," + base64.b64encode(hmac.new(secret.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256).digest()).decode("ascii")
+    if not hmac.compare_digest(get("signature"), expected):
+        return None
+    if not consume_request_id(request_id, seconds + tolerance_seconds):
+        return None
+    return {"tenantId": tenant, "userId": user or None, "requestId": request_id}
+
+
+class BotsResource:
+    def __init__(self, client, *, async_mode: bool = False):
+        self.client = client
+        self.async_mode = async_mode
+
+    def _path(self, bot_id: str, run_id: str | None = None) -> str:
+        path = f"/v1/bots/{quote(bot_id, safe='')}"
+        return f"{path}/runs/{quote(run_id, safe='')}" if run_id else path
+
+    def apis(self):
+        return self.client.request("GET", "/v1/bots/apis")
+
+    def update_api(self, api_id: str, revision: int, api: dict):
+        return self.client.request("PATCH", "/v1/bots/apis/" + quote(api_id, safe=""), json_body={"revision": revision, "api": api})
+
+    def delete_api(self, api_id: str):
+        return self.client.request("DELETE", "/v1/bots/apis/" + quote(api_id, safe=""))
+
+    def webhook_secret(self, bot_id: str):
+        return self.client.request("POST", self._path(bot_id) + "/webhook-secret", json_body={})
+
+    def trigger_webhook(self, bot_id: str, trigger_id: str):
+        return self.client.request("POST", self._path(bot_id) + "/triggers/" + quote(trigger_id, safe="") + "/webhook", json_body={})
+
+    def trigger_admission(self, bot_id: str, trigger_id: str, admission_id: str):
+        return self.client.request("GET", self._path(bot_id) + "/triggers/" + quote(trigger_id, safe="") + "/admissions/" + quote(admission_id, safe=""))
+
+    def delete_customer_data(self, bot_id: str, session_id: str):
+        """Erase this bot's customer data; shared Memory and API credentials remain unchanged."""
+        return self.client.request("POST", self._path(bot_id) + "/customer-data/delete", json_body={"sessionId": session_id})
+
+    def api_signing_key(self, bot_id: str, api_id: str, *, action: str = "read", overlap_seconds: int = 86400, key_id: str | None = None):
+        body: dict = {"action": action}
+        if action == "prepare":
+            body["overlapSeconds"] = overlap_seconds
+        if action in ("activate", "cancel"):
+            body["keyId"] = key_id
+        return self.client.request("POST", self._path(bot_id) + "/apis/" + quote(api_id, safe="") + "/signing-key", json_body=body)
+
+    def models(self):
+        return self.client.request("GET", "/v1/bots/models")
+
+    def set_credential(self, bot_id: str, secret: str):
+        return self.client.request("POST", self._path(bot_id) + "/credentials", json_body={"secret": secret})
+
+    def deliveries(self, bot_id: str, run_id: str):
+        return self.client.request("GET", self._path(bot_id, run_id) + "/deliveries")
+
+    def retry_delivery(self, bot_id: str, run_id: str, delivery_id: str):
+        return self.client.request("POST", self._path(bot_id, run_id) + "/deliveries/retry", json_body={"deliveryId": delivery_id})
+
+    def list(self):
+        return self.client.request("GET", "/v1/bots")
+
+    def delete(self, bot_id: str):
+        return self.client.request("DELETE", self._path(bot_id))
+
+    def set_state(self, bot_id: str, state: str, *, pause_for: str = "manual", reason: str = ""):
+        return self.client.request("POST", self._path(bot_id) + "/state", json_body={"state": state, "pauseFor": pause_for, "reason": reason})
+
+    def create(self, name: str):
+        return self.client.request("POST", "/v1/bots", json_body={"name": name})
+
+    def set_customer_credential(self, bot_id: str, *, api_id: str, session_id: str, secret: str):
+        return self.client.request("POST", self._path(bot_id) + "/credentials", json_body={"apiId": api_id, "sessionId": session_id, "secret": secret})
+
+    def get(self, bot_id: str):
+        return self.client.request("GET", self._path(bot_id))
+
+    def update(self, bot_id: str, revision: int, patch: dict[str, Any]):
+        return self.client.request("PATCH", self._path(bot_id), json_body={"revision": revision, "patch": patch})
+
+    def publish(self, bot_id: str, revision: int, channels: dict[str, bool]):
+        return self.client.request("POST", self._path(bot_id) + "/publish", json_body={"revision": revision, "channels": channels})
+
+    def run(self, bot_id: str, *, session_id: str, message: str, variables: dict[str, Any] | None = None, conversation_id: str | None = None, run_id: str | None = None):
+        body: dict[str, Any] = {"sessionId": session_id, "message": message, "variables": variables or {}, "runId": run_id or str(uuid4())}
+        if conversation_id:
+            body["conversationId"] = conversation_id
+        return self.client.request("POST", self._path(bot_id) + "/runs", json_body=body)
+
+    def get_run(self, bot_id: str, run_id: str):
+        return self.client.request("GET", self._path(bot_id, run_id))
+
+    def wait(self, bot_id: str, run_id: str, *, total_timeout_ms: int = 300_000):
+        """Return the finished run, or a run waiting for a person's approval or connection."""
+        if total_timeout_ms <= 0:
+            raise ValueError("total_timeout_ms must be positive")
+        return self._wait_async(bot_id, run_id, total_timeout_ms) if self.async_mode else self._wait_sync(bot_id, run_id, total_timeout_ms)
+
+    def _wait_sync(self, bot_id, run_id, total_timeout_ms):
+        deadline = time.monotonic() + total_timeout_ms / 1000
+        while time.monotonic() < deadline:
+            run = self.get_run(bot_id, run_id)
+            if run["status"] in ("completed", "failed", "stopped", "cancelled", "waiting_for_approval", "waiting_for_connection"):
+                return run
+            time.sleep(min(1, max(0, deadline - time.monotonic())))
+        raise StacklinkError("Bot observation timed out. Continue observing the same run.", status_code=408, code="sdk_run_timeout", details={"botId": bot_id, "runId": run_id})
+
+    async def _wait_async(self, bot_id, run_id, total_timeout_ms):
+        deadline = time.monotonic() + total_timeout_ms / 1000
+        while time.monotonic() < deadline:
+            run = await self.get_run(bot_id, run_id)
+            if run["status"] in ("completed", "failed", "stopped", "cancelled", "waiting_for_approval", "waiting_for_connection"):
+                return run
+            await asyncio.sleep(min(1, max(0, deadline - time.monotonic())))
+        raise StacklinkError("Bot observation timed out. Continue observing the same run.", status_code=408, code="sdk_run_timeout", details={"botId": bot_id, "runId": run_id})
+
+    def events(self, bot_id: str, run_id: str, *, after: str = "0"):
+        return self.client.request("GET", self._path(bot_id, run_id) + "/events", query={"after": after})
+
+    def stream(self, bot_id: str, run_id: str, *, after: str = "0", total_timeout_ms: int = 300_000):
+        method = self._stream_async if self.async_mode else self._stream_sync
+        return method(bot_id, run_id, after=after, total_timeout_ms=total_timeout_ms)
+
+    def _stream_sync(self, bot_id, run_id, *, after, total_timeout_ms):
+        deadline = time.monotonic() + total_timeout_ms / 1000
+        cursor = after
+        while True:
+            remaining = _remaining(deadline, run_id, cursor)
+            try:
+                with closing(self.client.request_sse("GET", self._path(bot_id, run_id) + "/events/stream", headers={"Last-Event-ID": cursor}, total_timeout_ms=min(remaining, 30_000))) as stream:
+                    for envelope in stream:
+                        event = envelope.get("data")
+                        if not isinstance(event, dict) or "sequence" not in event:
+                            continue
+                        _validate_event(event, run_id)
+                        if int(event["sequence"]) <= int(cursor):
+                            continue
+                        cursor = event["sequence"]
+                        yield event
+                        if _terminal(event):
+                            return
+            except (StacklinkError, httpx.TransportError) as error:
+                if not _retryable(error):
+                    raise
+            page = self.events(bot_id, run_id, after=cursor)
+            for event in page["events"]:
+                _validate_event(event, run_id)
+                if int(event["sequence"]) <= int(cursor):
+                    continue
+                cursor = event["sequence"]
+                yield event
+                if _terminal(event):
+                    return
+            if page.get("terminal") and not page["events"]:
+                return
+            if len(page["events"]) < 200:
+                time.sleep(min(1, _remaining(deadline, run_id, cursor) / 1000))
+
+    async def _stream_async(self, bot_id, run_id, *, after, total_timeout_ms):
+        deadline = time.monotonic() + total_timeout_ms / 1000
+        cursor = after
+        while True:
+            remaining = _remaining(deadline, run_id, cursor)
+            try:
+                async with aclosing(self.client.request_sse("GET", self._path(bot_id, run_id) + "/events/stream", headers={"Last-Event-ID": cursor}, total_timeout_ms=min(remaining, 30_000))) as stream:
+                    async for envelope in stream:
+                        event = envelope.get("data")
+                        if not isinstance(event, dict) or "sequence" not in event:
+                            continue
+                        _validate_event(event, run_id)
+                        if int(event["sequence"]) <= int(cursor):
+                            continue
+                        cursor = event["sequence"]
+                        yield event
+                        if _terminal(event):
+                            return
+            except (StacklinkError, httpx.TransportError) as error:
+                if not _retryable(error):
+                    raise
+            page = await self.events(bot_id, run_id, after=cursor)
+            for event in page["events"]:
+                _validate_event(event, run_id)
+                if int(event["sequence"]) <= int(cursor):
+                    continue
+                cursor = event["sequence"]
+                yield event
+                if _terminal(event):
+                    return
+            if page.get("terminal") and not page["events"]:
+                return
+            if len(page["events"]) < 200:
+                await asyncio.sleep(min(1, _remaining(deadline, run_id, cursor) / 1000))
+
+    def cancel(self, bot_id: str, run_id: str):
+        return self.client.request("POST", self._path(bot_id, run_id) + "/stop", json_body={})
+
+
+def _terminal(event):
+    return event.get("type") in ("run.completed", "run.failed", "run.stopped")
+
+
+def _validate_event(event, run_id):
+    if event.get("runId") != run_id:
+        raise StacklinkError("Bot event belongs to a different run.", status_code=502, code="bot_event_invalid")
+
+
+def _retryable(error):
+    return isinstance(error, httpx.TransportError) or (isinstance(error, StacklinkError) and error.status_code in (408, 429, 502, 503, 504) and error.code != "bot_event_invalid")
+
+
+def _remaining(deadline, run_id, cursor):
+    remaining = int((deadline - time.monotonic()) * 1000)
+    if remaining <= 0:
+        raise StacklinkError("Bot observation timed out. Resume the same run from the last sequence.", status_code=408, code="sdk_stream_timeout", details={"runId": run_id, "after": cursor})
+    return remaining

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

@@ -19,6 +19,8 @@ from .api_keys import ApiKeysResource
 from .artifacts import ArtifactsResource
 from .auth_configs import AuthConfigsResource
 from .billing import BillingResource
+from .bots import BotsResource
+from .approvals import ApprovalsResource
 from .connected_accounts import ConnectedAccountsResource
 from .errors import RateLimitError, StacklinkError
 from .executions import ExecutionsResource
@@ -35,7 +37,7 @@ from .types import Json, Transport
 from .webhooks import WebhooksResource
 from .workbench import WorkbenchResource
 
-STACKLINK_PYTHON_SDK_VERSION = "0.2.2"
+STACKLINK_PYTHON_SDK_VERSION = "0.3.7"
 STACKLINK_PYTHON_USER_AGENT = f"stacklink-python/{STACKLINK_PYTHON_SDK_VERSION}"
 
 
@@ -52,6 +54,8 @@ class Stacklink:
         max_attempts: int = 3,
         http_client: httpx.Client | None = None,
     ):
+        self.bots = BotsResource(self)
+        self.approvals = ApprovalsResource(self)
         self.api_key = api_key or os.getenv("STACKLINK_API_KEY")
         if not self.api_key:
             raise StacklinkError("STACKLINK_API_KEY is required.")
@@ -420,6 +424,8 @@ class AsyncStacklink:
         max_attempts: int = 3,
         http_client: httpx.AsyncClient | None = None,
     ):
+        self.bots = BotsResource(self, async_mode=True)
+        self.approvals = ApprovalsResource(self, async_mode=True)
         self.api_key = api_key or os.getenv("STACKLINK_API_KEY")
         if not self.api_key:
             raise StacklinkError("STACKLINK_API_KEY is required.")

{stacklink_sdk-0.2.2 → stacklink_sdk-0.3.7}/stacklink/webhooks.py

@@ -1,6 +1,26 @@
 from __future__ import annotations
 
 from typing import Any
+import base64
+import hashlib
+import hmac
+import time
+
+
+def verify_webhook_signature(*, body: str, secret: str, id: str, timestamp: str, signature: str, now: float | None = None, tolerance_seconds: int = 300) -> bool:
+    """Verify the original callback body and destination-specific signing secret."""
+    try:
+        seconds = int(timestamp)
+    except (TypeError, ValueError):
+        return False
+    if abs((time.time() if now is None else now) - seconds) > tolerance_seconds:
+        return False
+    expected = base64.b64encode(hmac.new(secret.encode("utf-8"), f"{id}.{timestamp}.{body}".encode("utf-8"), hashlib.sha256).digest()).decode("ascii")
+    for entry in signature.split(" "):
+        version, separator, candidate = entry.partition(",")
+        if separator and version == "v1" and hmac.compare_digest(candidate, expected):
+            return True
+    return False
 
 
 class WebhooksResource:

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

@@ -14,6 +14,7 @@ WorkbenchOutputMode = Literal["inline", "preview", "events", "artifact"]
 WorkbenchExecutionKind = Literal["workbench_code", "workbench_bash"]
 WorkbenchReplayEnvironmentMode = Literal["require_match", "restore_snapshot", "current"]
 WorkbenchExecutionStatus = Literal[
+    "waiting_for_approval",
     "queued",
     "started",
     "running",
@@ -459,6 +460,9 @@ class WorkbenchExecutionStateResponse(TypedDict, total=False):
 
 
 class WorkbenchExecutionResponse(TypedDict, total=False):
+    approvalRequestId: str
+    executed: bool
+    nextAction: Literal["wait_for_approval"]
     workbenchSession: WorkbenchSession
     executionKind: WorkbenchExecutionKind
     executionId: str
@@ -547,7 +551,8 @@ def _wait_for_workbench_response(
     execution_id = accepted.get("executionId")
     execution_kind = accepted.get("executionKind")
     if (
-        not isinstance(session_id, str)
+        accepted.get("status") == "waiting_for_approval"
+        or not isinstance(session_id, str)
         or not isinstance(execution_id, str)
         or execution_kind not in {"workbench_code", "workbench_bash"}
     ):
@@ -562,6 +567,7 @@ def _wait_for_workbench_response(
         ))
         execution = waited.get("execution")
         if not isinstance(execution, dict) or execution.get("status") not in {
+            "waiting_for_approval",
             "completed",
             "failed",
             "cancelled",
@@ -576,6 +582,11 @@ def _wait_for_workbench_response(
             "execution": cast(WorkbenchExecutionLog, execution),
             "executionLog": cast(WorkbenchExecutionLog, execution),
         }
+        if isinstance(execution.get("approvalRequestId"), str):
+            response["approvalRequestId"] = execution["approvalRequestId"]
+        if execution.get("status") == "waiting_for_approval":
+            response["executed"] = False
+            response["nextAction"] = "wait_for_approval"
         output_mode = execution.get("outputMode")
         if output_mode in {"inline", "preview", "events", "artifact"}:
             response["outputMode"] = cast(WorkbenchOutputMode, output_mode)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stacklink-sdk
-Version: 0.2.2
+Version: 0.3.7
 Summary: Python SDK for Stacklink sessions, tools, MCP, auth, workbench, logs, knowledge, and billing.
 Author: Stacklink
 License-Expression: LicenseRef-Proprietary
@@ -77,8 +77,35 @@ An execution response can be pending. Keep its `executionKind`, `executionId`, s
 
 Retry keys are case-sensitive and accept up to 240 characters. Tool and batch requests have separate key namespaces. Reuse a key only for the exact same request in the same SDK session. Changed inputs return `409 idempotency_key_reused`; an expired stored result returns `410 execution_result_expired`. Neither response authorizes submitting the write again.
 
-For `waiting_for_approval`, your backend can use the session approval read, approve and deny APIs with `platform_approvals:read` / `platform_approvals:manage` scopes. Keep the API key on your backend. A pending action must not be labelled completed. `provider_execution_result_unknown` means an external write may have happened; inspect the provider before considering another action.
+For `waiting_for_approval`, read the shared request using `client.approvals` and `platform_approvals:read`. A decision also needs `platform_approvals:manage` and the authority required by that request. A server key alone cannot approve on behalf of a company person; eligible customer confirmation uses the verified session and its scoped grant. Keep the API key on your backend. A pending action must not be labelled completed. `provider_execution_result_unknown` means an external write may have happened; inspect the provider before considering another action.
 
 Use execution cancellation for an explicit Stop request. Losing a stream only stops observation. Vercel and LangChain adapters forward their supported abort signal; other adapters keep the structured operation identity available for explicit cancellation. MCP progress reports actual stages, not invented percentages.
 
 Streaming has a total observation deadline and a separate inactivity timeout. A timeout raises `sdk_stream_timeout` without repeating the action; use its original operation ID to resume observation. Stream responses are limited to 8 MiB, including JSON responses to streaming requests. The synchronous client keeps blocking reads in a bounded reader and releases the response when that read finishes or reaches its inactivity timeout. Custom transports must honor the timeout passed to them. MCP calls return once all matching responses arrive, even if the server keeps the stream open.
+
+## Hosted Bots (0.3.2)
+
+Bots are saved, published agents with project-scoped configuration and durable runs. Use a server-held project API key with `bots:manage` to create/update/publish, and `bots:run` to invoke. Supply a session established from your authenticated customer; input variables do not grant identity or access. Both SDKs expose run status, replayable events, cancellation and callback delivery recovery. A callback failure does not rerun the model.
+
+```python
+bot = stacklink.bots.get(bot_id)
+run = stacklink.bots.run(bot_id, session_id=session.id, message="Where is my order?", variables={"orderNumber": "4821"})
+for event in stacklink.bots.stream(bot_id, run["id"]):
+    print(event)
+result = stacklink.bots.get_run(bot_id, run["id"])
+print(result["output"] or result["finalText"])
+```
+
+The async client provides the same operations with `await` and `async for`.
+
+Reuse the returned `conversationId` for the next message. Preserve the last event sequence to resume observation. Published invocations are available through the existing session MCP endpoint using `STACKLINK_BOTS`; no separate server per bot is needed.
+
+## Shared approvals (0.3.3)
+
+`client.approvals` lists and retrieves approvals for an authorized session, submits a permitted decision or customer correction, and observes reconnectable approval events. A project key represents an application; it cannot substitute for a required human company approver. `as_customer=True` derives the customer from the authenticated session and still requires a scoped customer grant. Continue observing the original execution after deciding; do not resubmit the action.
+
+All enabled notification channels use the same stored request. Decision, notification delivery and execution have separate states. See the [approval guide](https://docs.stacklink.in/docs/reference/sdk-python#shared-approvals) for request and lifecycle details.
+
+When project settings require Workbench code approval, a foreground code/bash call returns `waiting_for_approval`, `approvalRequestId`, and its original execution ID immediately. No runtime sandbox is allocated for that wait. After the authorized person decides, observe the original execution; do not submit the code again.
+
+Server-side customer grant management (0.3.5): `get_customer_grant`, `save_customer_grant`, and `remove_customer_grant` operate on an authenticated customer session. Save exact tool keys and resource restrictions with the returned settings revision. The server supplies identity from the session; callers cannot choose another customer in the request body. These methods never grant company approval or bypass connected-account access.

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

@@ -3,9 +3,11 @@ README.md
 pyproject.toml
 stacklink/__init__.py
 stacklink/api_keys.py
+stacklink/approvals.py
 stacklink/artifacts.py
 stacklink/auth_configs.py
 stacklink/billing.py
+stacklink/bots.py
 stacklink/claude_agent.py
 stacklink/client.py
 stacklink/connected_accounts.py

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

@@ -14,6 +14,7 @@ import httpx
 from stacklink import (
     AsyncStacklink,
     RateLimitError,
+    STACKLINK_PYTHON_SDK_VERSION,
     Stacklink,
     StacklinkError,
     create_stacklink_claude_agent_tool_config,
@@ -60,6 +61,103 @@ def stalled_stream_server(*, final_result=False):
 
 
 class StacklinkClientTests(unittest.TestCase):
+    def test_customer_grant_management_uses_session_identity(self):
+        calls = []
+        def transport(method, path, headers, body, query, timeout):
+            calls.append((method, path, body, query))
+            return 200, {}, {'revision': len(calls), 'grant': None}
+        client = Stacklink(api_key='ppk_test', transport=transport)
+        client.approvals.get_customer_grant(session_id='customer-session')
+        grant = {'revision': 1, 'name': 'Customer', 'toolKeys': ['calendar.move'], 'accountIds': [], 'resources': [{'pointer': '/appointmentId', 'value': 'appointment-1'}]}
+        client.approvals.save_customer_grant(grant, session_id='customer-session')
+        client.approvals.remove_customer_grant(session_id='customer-session', revision=2)
+        self.assertEqual([call[0] for call in calls], ['GET', 'PUT', 'DELETE'])
+        self.assertTrue(all(call[1] == '/v1/approvals/customer-grant' and call[3] == {'sessionId': 'customer-session'} for call in calls))
+        self.assertEqual(calls[1][2], grant)
+        self.assertEqual(calls[2][2], {'revision': 2})
+
+
+    def test_workbench_approval_returns_to_caller_before_decision(self):
+        for operation in ("run_code", "bash"):
+            for admission_status in ("waiting_for_approval", "queued"):
+                calls = []
+                waiting = {"id": "execution-1", "executionId": "execution-1", "executionKind": "workbench_bash" if operation == "bash" else "workbench_code", "status": "waiting_for_approval", "approvalRequestId": "approval-1"}
+                def transport(method, path, headers, body, query, timeout):
+                    calls.append(path)
+                    if path in {"/v1/workbench/run", "/v1/workbench/bash"}:
+                        return 202, {}, {**waiting, "status": admission_status, "workbenchSession": {"id": "workspace-1"}, "executed": False, "nextAction": "wait_for_approval"}
+                    if path.endswith("/wait") and len(calls) == 2:
+                        return 200, {}, {"execution": waiting}
+                    raise AssertionError(f"Unexpected polling during approval: {path}")
+                client = Stacklink(api_key="ppk_test", transport=transport)
+                payload = {"sessionId": "session-1", "workbenchSessionId": "workspace-1", "operation": operation, "language": "python", "code": "print(1)", "command": "echo 1"}
+                result = client.workbench.bash(payload) if operation == "bash" else client.workbench.run(payload)
+                self.assertEqual(result["status"], "waiting_for_approval")
+                self.assertEqual(result["approvalRequestId"], "approval-1")
+                self.assertFalse(result["executed"])
+                self.assertEqual(len(calls), 2 if admission_status == "queued" else 1)
+
+    def test_approvals_observe_reconnect_and_customer_identity(self):
+        calls = []
+        def transport(method, path, headers, body, query, timeout):
+            calls.append((method, path, body, query))
+            if path.endswith('/events'):
+                cursor = str(int(query['after']) + 1)
+                return 200, {}, {'events': [{'sequence': cursor, 'approvalId': 'approval-one', 'type': 'approval.request.updated', 'data': {'status': 'pending'}, 'occurredAt': '2026-10-14T00:00:00Z'}], 'nextCursor': cursor}
+            return 409, {}, {'code': 'approval_revision_conflict', 'message': 'Review current values.'}
+        client = Stacklink(api_key='ppk_test', base_url='https://stacklink.test', transport=transport)
+        with self.assertRaises(StacklinkError):
+            client.approvals.decide('approval-one', {'requirement': 'customer', 'decision': 'approve', 'expectedRevision': 2}, session_id='session-one', as_customer=True)
+        self.assertEqual(len(calls), 1)
+        self.assertEqual(calls[0][3]['asCustomer'], 'true')
+        events = client.approvals.observe(session_id='session-one', after='8', as_customer=True)
+        self.assertEqual(next(events)['sequence'], '9')
+        events.close()
+        events = client.approvals.observe(session_id='session-one', after='9', as_customer=True)
+        self.assertEqual(next(events)['sequence'], '10')
+        events.close()
+        self.assertEqual([call[3]['after'] for call in calls[1:]], ['8', '9'])
+        self.assertTrue(all('/v1/approvals/' in call[1] for call in calls))
+
+    def test_bot_trigger_signature_binds_original_unicode_bytes(self):
+        import hashlib, hmac
+        from stacklink import sign_bot_trigger_request
+        body = '{"message":"नमस्ते"}'
+        headers = sign_bot_trigger_request(trigger_id="trigger-one", secret="fixture", body=body, request_id="event-one", now=1000)
+        signed = json.dumps(["stacklink-trigger-v1", "trigger-one", "1000", "event-one", hashlib.sha256(body.encode()).hexdigest()], separators=(",", ":"))
+        self.assertEqual(headers["stacklink-signature"], hmac.new(b"fixture", signed.encode(), hashlib.sha256).hexdigest())
+        self.assertNotEqual(headers["stacklink-signature"], sign_bot_trigger_request(trigger_id="trigger-one", secret="fixture", body=body + " ", request_id="event-one", now=1000)["stacklink-signature"])
+
+    def test_bot_management_uses_shared_routes_and_exact_customer_session(self):
+        calls = []
+        def transport(method, path, headers, body, query, timeout):
+            calls.append((method, path, body))
+            return 200, {}, {"ok": True}
+        client = Stacklink(api_key="ppk_test", base_url="http://stacklink.test", transport=transport)
+        client.bots.trigger_webhook("bot-one", "trigger-one")
+        client.bots.trigger_admission("bot-one", "trigger-one", "admission-one")
+        client.bots.delete_customer_data("bot-one", "session-alice")
+        client.bots.api_signing_key("bot-one", "api-one", action="prepare", overlap_seconds=86400)
+        client.bots.api_signing_key("bot-one", "api-one", action="activate", key_id="key-two")
+        self.assertEqual(calls, [
+            ("POST", "/v1/bots/bot-one/triggers/trigger-one/webhook", {}),
+            ("GET", "/v1/bots/bot-one/triggers/trigger-one/admissions/admission-one", None),
+            ("POST", "/v1/bots/bot-one/customer-data/delete", {"sessionId": "session-alice"}),
+            ("POST", "/v1/bots/bot-one/apis/api-one/signing-key", {"action": "prepare", "overlapSeconds": 86400}),
+            ("POST", "/v1/bots/bot-one/apis/api-one/signing-key", {"action": "activate", "keyId": "key-two"}),
+        ])
+
+    def test_callback_signature_uses_original_body_and_expiry(self):
+        import base64, hashlib, hmac
+        from stacklink import verify_webhook_signature
+        body = '{"message":"नमस्ते"}'
+        signature = "v1," + base64.b64encode(hmac.new(b"test-secret", f"delivery.1000.{body}".encode("utf-8"), hashlib.sha256).digest()).decode("ascii")
+        values = dict(body=body, secret="test-secret", id="delivery", timestamp="1000", signature=signature, now=1001)
+        self.assertTrue(verify_webhook_signature(**values))
+        self.assertFalse(verify_webhook_signature(**{**values, "body": "{}"}))
+        self.assertFalse(verify_webhook_signature(**{**values, "now": 1301}))
+        self.assertFalse(verify_webhook_signature(**{**values, "secret": "wrong"}))
+
     def test_session_create_uses_env_contract_and_auth_header(self):
         calls = []
 
@@ -83,8 +181,8 @@ class StacklinkClientTests(unittest.TestCase):
         self.assertEqual(headers["authorization"], "Bearer ppk_test")
         self.assertEqual(headers["x-stacklink-client-channel"], "python_sdk")
         self.assertEqual(headers["x-stacklink-client-name"], "stacklink-python")
-        self.assertEqual(headers["x-stacklink-client-version"], "0.2.2")
-        self.assertEqual(headers["user-agent"], "stacklink-python/0.2.2")
+        self.assertEqual(headers["x-stacklink-client-version"], STACKLINK_PYTHON_SDK_VERSION)
+        self.assertEqual(headers["user-agent"], f"stacklink-python/{STACKLINK_PYTHON_SDK_VERSION}")
         self.assertEqual(body, {"externalTenantId": "tenant_1"})
         self.assertEqual(query, {})
         self.assertAlmostEqual(timeout, 15, places=3)
@@ -1502,3 +1600,46 @@ class StacklinkClientTests(unittest.TestCase):
 
 if __name__ == "__main__":
     unittest.main()
+
+
+class BotStreamRecoveryTests(unittest.TestCase):
+    def test_bot_wait_returns_approval_without_resubmitting(self):
+        calls = []
+        waiting = {"id": "run-one", "status": "waiting_for_approval", "waitingOperation": {"id": "execution-one"}}
+        def transport(method, path, headers, body, query, timeout):
+            calls.append((method, path))
+            return 200, {}, waiting
+        client = Stacklink(api_key="test", transport=transport)
+        self.assertEqual(client.bots.wait("bot-one", "run-one"), waiting)
+        self.assertEqual(calls, [("GET", "/v1/bots/bot-one/runs/run-one")])
+
+    def test_sync_bot_replays_missed_terminal_event(self):
+        calls = []
+        delta = {"runId": "run-one", "sequence": "1", "type": "model.text.delta", "payload": {"text": "नमस्ते"}}
+        done = {"runId": "run-one", "sequence": "2", "type": "run.completed", "payload": {"finalText": "नमस्ते"}}
+        def transport(method, path, headers, body, query, timeout):
+            calls.append((method, path, query))
+            if path.endswith("/stream"):
+                return 200, {"content-type": "text/event-stream"}, "data: " + json.dumps(delta) + "\n\n"
+            self.assertEqual(query, {"after": "1"})
+            return 200, {"content-type": "application/json"}, {"terminal": True, "events": [done]}
+        client = Stacklink(api_key="test", transport=transport)
+        self.assertEqual(list(client.bots.stream("bot-one", "run-one")), [delta, done])
+        self.assertEqual(len(calls), 2)
+
+    def test_async_bot_replays_missed_terminal_event(self):
+        async def proof():
+            calls = []
+            delta = {"runId": "run-one", "sequence": "1", "type": "model.text.delta", "payload": {"text": "नमस्ते"}}
+            done = {"runId": "run-one", "sequence": "2", "type": "run.completed", "payload": {"finalText": "नमस्ते"}}
+            async def handler(request):
+                calls.append(request.url.path)
+                if request.url.path.endswith("/stream"):
+                    return httpx.Response(200, headers={"content-type": "text/event-stream"}, text="data: " + json.dumps(delta) + "\n\n")
+                self.assertEqual(request.url.params["after"], "1")
+                return httpx.Response(200, json={"terminal": True, "events": [done]})
+            async with httpx.AsyncClient(transport=httpx.MockTransport(handler)) as http:
+                async with AsyncStacklink(api_key="test", base_url="https://stacklink.test", http_client=http) as client:
+                    self.assertEqual([event async for event in client.bots.stream("bot-one", "run-one")], [delta, done])
+            self.assertEqual(len(calls), 2)
+        asyncio.run(proof())