stacklink-sdk 0.3.15__tar.gz → 0.4.0__tar.gz

{stacklink_sdk-0.3.15/stacklink_sdk.egg-info → stacklink_sdk-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stacklink-sdk
-Version: 0.3.15
+Version: 0.4.0
 Summary: Python SDK for Stacklink sessions, tools, MCP, auth, workbench, logs, knowledge, and billing.
 Author: Stacklink
 License-Expression: LicenseRef-Proprietary

{stacklink_sdk-0.3.15 → stacklink_sdk-0.4.0}/pyproject.toml

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

{stacklink_sdk-0.3.15 → stacklink_sdk-0.4.0}/stacklink/__init__.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from .bots import verify_bot_api_request, sign_bot_trigger_request, BotRun, BotConnectionAction, BotExecutionWait, BotCapabilityFact, BotRequirement
+from .bots import BotAvatar, verify_bot_api_request, sign_bot_trigger_request, BotRun, BotConnectionAction, BotExecutionWait, BotCapabilityFact, BotRequirement
 from .approvals import ApprovalDecision, ApprovalRecord, ApprovalEvent, ApprovalPermissions, CustomerApprovalGrantInput
 from .webhooks import verify_webhook_signature
 from .client import AsyncStacklink, STACKLINK_PYTHON_SDK_VERSION, Stacklink
@@ -27,7 +27,7 @@ from .types import (
 )
 
 __all__ = [
-    "BotRun", "BotConnectionAction", "BotExecutionWait", "BotCapabilityFact", "BotRequirement",
+    "BotAvatar", "BotRun", "BotConnectionAction", "BotExecutionWait", "BotCapabilityFact", "BotRequirement",
     "ApprovalDecision", "ApprovalRecord", "ApprovalEvent", "ApprovalPermissions",
     "CustomerApprovalGrantInput",
     "Stacklink",

{stacklink_sdk-0.3.15 → stacklink_sdk-0.4.0}/stacklink/bots.py

@@ -15,8 +15,15 @@ from urllib.parse import quote
 from uuid import uuid4
 
 
+class BotAvatar(TypedDict):
+    version: Literal[1]
+    style: Literal["clay", "pebble", "shapes", "letters"]
+    seed: str
+    tone: Literal["auto", "mint", "teal", "sky", "iris", "plum", "rose", "coral", "apricot", "sun", "lime", "slate", "ink"]
+
+
 class _BotCapabilityAccount(TypedDict, total=False):
-    account: Literal["project", "customer"]
+    account: Literal["project", "customer", "deployment"]
 
 
 class BotCapabilityFact(_BotCapabilityAccount):
@@ -46,6 +53,12 @@ class BotExecutionWait(TypedDict):
     kind: Literal["execution"]
     id: str
 
+class BotAttachmentPreparationWait(TypedDict):
+    kind: Literal["attachment_preparation"]
+    id: str
+    fileId: str
+
+
 
 class BotRequirement(TypedDict):
     capabilityId: str
@@ -64,6 +77,22 @@ class BotAttachment(TypedDict, total=False):
     facts: dict[str, Any]
     warnings: list[dict[str, str]]
     error: dict[str, str] | None
+    transcription: dict[Literal["state"], Literal["queued", "transcribing", "reconciling", "completed", "failed"]]
+
+
+class BotAudioPlayback(TypedDict):
+    url: str
+    expiresAt: str
+    mediaType: Literal["audio/mpeg"]
+
+
+class _BotFilePlayback(TypedDict, total=False):
+    playback: BotAudioPlayback
+
+
+class BotFileLink(_BotFilePlayback):
+    url: str
+    expiresAt: str
 
 
 class BotFileUpload(TypedDict):
@@ -107,7 +136,7 @@ class BotRun(TypedDict, total=False):
     finalText: str | None
     output: Any
     error: Any
-    waitingOperation: BotConnectionAction | BotExecutionWait | None
+    waitingOperation: BotConnectionAction | BotExecutionWait | BotAttachmentPreparationWait | None
     connection: BotConnectionAction | None
     capabilities: list[BotCapabilityFact]
     requirements: list[BotRequirement]
@@ -218,8 +247,8 @@ class BotsResource:
     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 create(self, name: str, *, public_description: str = "", icon_asset_id: str | None = None, avatar: BotAvatar | None = None):
+        return self.client.request("POST", "/v1/bots", json_body={"name": name, "publicDescription": public_description, "iconAssetId": icon_asset_id, **({"avatar": avatar} if avatar is not None else {})})
 
     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})

{stacklink_sdk-0.3.15 → stacklink_sdk-0.4.0}/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.15"
+STACKLINK_PYTHON_SDK_VERSION = "0.4.0"
 STACKLINK_PYTHON_USER_AGENT = f"stacklink-python/{STACKLINK_PYTHON_SDK_VERSION}"
 
 
@@ -356,18 +356,12 @@ class Stacklink:
             "user-agent": STACKLINK_PYTHON_USER_AGENT,
             "x-stacklink-client-channel": "python_sdk",
             "x-stacklink-client-name": "stacklink-python",
+            "x-stacklink-workbench-protocol": "2",
             "x-stacklink-client-version": STACKLINK_PYTHON_SDK_VERSION,
         }
 
     def _handle_response(self, status: int, headers: Mapping[str, str], body: Json) -> Json:
-        if status < 400:
-            return body
-        message = body.get("message") if isinstance(body, dict) else None
-        code = body.get("code") if isinstance(body, dict) else None
-        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, headers=headers)
+        return _handle_response(status, headers, body)
 
     def _parse_sse_lines(self, lines) -> Iterator[dict[str, Any]]:
         event_id = None
@@ -671,6 +665,7 @@ class AsyncStacklink:
             "user-agent": STACKLINK_PYTHON_USER_AGENT,
             "x-stacklink-client-channel": "python_sdk",
             "x-stacklink-client-name": "stacklink-python",
+            "x-stacklink-workbench-protocol": "2",
             "x-stacklink-client-version": STACKLINK_PYTHON_SDK_VERSION,
         }
 
@@ -874,9 +869,11 @@ def _handle_response(status: int, headers: Mapping[str, str], body: Json) -> Jso
     message = body.get("message") if isinstance(body, dict) else None
     code = body.get("code") if isinstance(body, dict) else None
     details = body.get("details") if isinstance(body, dict) else None
+    failure_id = body.get("failureId") if isinstance(body, dict) else None
+    failure_id = failure_id or headers.get("x-stacklink-failure-id")
     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, headers=headers)
+        raise RateLimitError(message or "Stacklink rate limit exceeded.", status_code=status, code=code, details=details, headers=headers, failure_id=failure_id)
+    raise StacklinkError(message or "Stacklink request failed.", status_code=status, code=code, details=details, headers=headers, failure_id=failure_id)
 
 
 def _timeout_error(timeout_seconds: float, request_id: str) -> StacklinkError:

{stacklink_sdk-0.3.15 → stacklink_sdk-0.4.0}/stacklink/errors.py

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

{stacklink_sdk-0.3.15 → stacklink_sdk-0.4.0}/stacklink/mcp.py

@@ -77,6 +77,7 @@ def unwrap_tool_result(response: Any):
             status_code=400,
             code=str(error.get("code")) if error.get("code") is not None else None,
             details=error.get("data"),
+            failure_id=error["data"].get("failureId") if isinstance(error.get("data"), dict) else None,
         )
     result = response.get("result")
     if not isinstance(result, dict):
@@ -87,7 +88,9 @@ def unwrap_tool_result(response: Any):
             for item in result.get("content", [])
             if isinstance(item, dict) and item.get("type") == "text" and isinstance(item.get("text"), str)
         )
-        raise StacklinkError(text or "Stacklink MCP tool call failed.", status_code=400, code="mcp_tool_error", details=result)
+        structured = result.get("structuredContent")
+        failure = structured.get("error") if isinstance(structured, dict) else None
+        raise StacklinkError(text or "Stacklink MCP tool call failed.", status_code=400, code="mcp_tool_error", details=result, failure_id=failure.get("failureId") if isinstance(failure, dict) else None)
     if "structuredContent" in result:
         return result["structuredContent"]
     content = result.get("content")

{stacklink_sdk-0.3.15 → stacklink_sdk-0.4.0}/stacklink/workbench.py

@@ -3,9 +3,10 @@ from __future__ import annotations
 import base64
 import time
 import threading
+from uuid import uuid4
 from email.utils import parsedate_to_datetime
 import httpx
-from typing import Any, Iterator, Literal, Mapping, TypedDict, cast
+from typing import Any, BinaryIO, Iterator, Literal, Mapping, TypedDict, cast
 from urllib.error import HTTPError
 from urllib.request import Request, urlopen
 
@@ -18,6 +19,10 @@ WorkbenchExecutionKind = Literal["workbench_code", "workbench_bash"]
 WorkbenchReplayEnvironmentMode = Literal["require_match", "restore_snapshot", "current"]
 WorkbenchExecutionStatus = Literal[
     "waiting_for_approval",
+    "checkpointing",
+    "waiting_saved",
+    "waiting_ready",
+    "resuming",
     "queued",
     "started",
     "running",
@@ -141,7 +146,30 @@ class WorkbenchSessionDeleteReceipt(TypedDict):
     databaseDeleted: Literal[True]
 
 
+class WorkbenchWaitContinuation(TypedDict):
+    language: WorkbenchLanguage
+    code: str
+    timeoutMs: int
+
+
+class WorkbenchKeepReadyConsent(TypedDict):
+    maximumWaitMs: int
+    maximumChargeMicros: str
+    priceMicros: str
+    unitQuantity: int
+    rateVersion: str
+
+
+class WorkbenchWaitRequest(TypedDict, total=False):
+    mode: Literal["saved", "keep_ready"]
+    reason: Literal["approval", "connection", "user_input", "external_event"]
+    maximumWaitMs: int
+    continuation: WorkbenchWaitContinuation
+    keepReady: WorkbenchKeepReadyConsent
+
+
 class WorkbenchRunInput(TypedDict, total=False):
+    afterExecution: WorkbenchWaitRequest
     language: WorkbenchLanguage
     code: str
     workbenchSessionId: str
@@ -158,6 +186,7 @@ class WorkbenchRunInput(TypedDict, total=False):
 
 
 class WorkbenchBashInput(TypedDict, total=False):
+    afterExecution: WorkbenchWaitRequest
     command: str
     workbenchSessionId: str
     timeoutMs: int
@@ -173,6 +202,8 @@ class WorkbenchBashInput(TypedDict, total=False):
 
 
 class WorkbenchExecutionLog(TypedDict, total=False):
+    waitRevision: int
+    waitState: dict[str, Any] | None
     id: str
     workbenchSessionId: str
     operation: str
@@ -289,8 +320,21 @@ class WorkbenchOutputPreview(TypedDict):
     preview: str
 
 
+class WorkbenchStorageOperation(TypedDict, total=False):
+    operationId: str
+    workbenchSessionId: str
+    kind: Literal["delete", "upload_finalize", "artifact_promote"]
+    status: Literal["pending", "processing", "completed", "failed"]
+    statusUrl: str
+    stage: str
+    retryAfterMs: int
+    pendingReason: str
+    result: dict[str, Any]
+    error: Any
+
+
 class WorkbenchFile(TypedDict, total=False):
-    id: str
+    id: str | None
     path: str
     contentType: str
     sizeBytes: int | str
@@ -310,9 +354,12 @@ class WorkbenchFileResponse(TypedDict):
 class WorkbenchFileListResponse(TypedDict, total=False):
     files: list[WorkbenchFile]
     runtimeFiles: list[WorkbenchFile]
+    nextCursor: str | None
+    authoritative: bool
 
 
 class WorkbenchFileMutationResponse(TypedDict, total=False):
+    operation: WorkbenchStorageOperation
     file: WorkbenchFile
     uploadId: str
     finalized: bool
@@ -335,13 +382,16 @@ class WorkbenchFileUploadPrepareResponse(TypedDict):
     upload: WorkbenchFileSignedUpload
 
 
-class WorkbenchFileSignedDownload(TypedDict):
+class WorkbenchFileSignedDownload(TypedDict, total=False):
     file: WorkbenchFile
     downloadUrl: str
     expiresAt: str
+    requiredHeaders: dict[str, str]
 
 
 class WorkbenchArtifact(TypedDict, total=False):
+    operationId: str | None
+    workbenchSessionId: str
     id: str
     artifactRef: str
     path: str
@@ -487,7 +537,7 @@ class WorkbenchExecutionStateResponse(TypedDict, total=False):
 class WorkbenchExecutionResponse(TypedDict, total=False):
     approvalRequestId: str
     executed: bool
-    nextAction: Literal["wait_for_approval"]
+    nextAction: Literal["wait_for_approval", "resume_saved_work"]
     workbenchSession: WorkbenchSession
     executionKind: WorkbenchExecutionKind
     executionId: str
@@ -605,7 +655,7 @@ def _wait_for_workbench_response(
     execution_id = accepted.get("executionId")
     execution_kind = accepted.get("executionKind")
     if (
-        accepted.get("status") == "waiting_for_approval"
+        accepted.get("status") in ("waiting_for_approval", "waiting_saved", "waiting_ready")
         or not isinstance(session_id, str)
         or not isinstance(execution_id, str)
         or execution_kind not in {"workbench_code", "workbench_bash"}
@@ -620,13 +670,15 @@ def _wait_for_workbench_response(
             {"waitTimeoutMs": 10_000},
         ))
         execution = waited.get("execution")
-        if not isinstance(execution, dict) or execution.get("status") not in {
+        if not isinstance(execution, dict) or (execution.get("nextAction") != "wait_for_approval" and execution.get("status") not in {
             "waiting_for_approval",
+            "waiting_saved",
+            "waiting_ready",
             "completed",
             "failed",
             "cancelled",
             "timed_out",
-        }:
+        }):
             continue
         response: WorkbenchExecutionResponse = {
             **accepted,
@@ -638,9 +690,9 @@ def _wait_for_workbench_response(
         }
         if isinstance(execution.get("approvalRequestId"), str):
             response["approvalRequestId"] = execution["approvalRequestId"]
-        if execution.get("status") == "waiting_for_approval":
+        if execution.get("status") in ("waiting_for_approval", "waiting_saved", "waiting_ready") or execution.get("nextAction") == "wait_for_approval":
             response["executed"] = False
-            response["nextAction"] = "wait_for_approval"
+            response["nextAction"] = "wait_for_approval" if execution.get("status") == "waiting_for_approval" or execution.get("nextAction") == "wait_for_approval" else "resume_saved_work"
         output_mode = execution.get("outputMode")
         if output_mode in {"inline", "preview", "events", "artifact"}:
             response["outputMode"] = cast(WorkbenchOutputMode, output_mode)
@@ -659,11 +711,11 @@ class WorkbenchFiles:
     def __init__(self, sandbox: "SessionSandbox"):
         self.sandbox = sandbox
 
-    def list(self) -> WorkbenchFileListResponse:
+    def list(self, *, cursor: str | None = None, limit: int = 100) -> WorkbenchFileListResponse:
         return cast(WorkbenchFileListResponse, self.sandbox.client.request(
             "GET",
             f"/v1/workbench/sessions/{self.sandbox.ensure_session_id()}/files",
-            query={"sessionId": self.sandbox.platform_session_id},
+            query={"sessionId": self.sandbox.platform_session_id, "cursor": cursor, "limit": limit},
         ))
 
     def read(self, path: str) -> WorkbenchFileResponse:
@@ -680,33 +732,42 @@ class WorkbenchFiles:
         *,
         content_type: str | None = None,
         metadata: Mapping[str, Any] | None = None,
+        upload_id: str | None = None,
     ) -> WorkbenchFileResponse:
         raw = content.encode("utf-8") if isinstance(content, str) else content
         body = {
             "sessionId": self.sandbox.platform_session_id,
             "path": path,
+            "uploadId": upload_id or str(uuid4()),
             "contentBase64": base64.b64encode(raw).decode("ascii"),
             "metadata": dict(metadata or {}),
         }
         if content_type is not None:
             body["contentType"] = content_type
-        return cast(WorkbenchFileResponse, self.sandbox.client.request(
-            "PUT",
-            f"/v1/workbench/sessions/{self.sandbox.ensure_session_id()}/files",
-            json_body=body,
-        ))
-
-    def prepare_upload(self, path: str, *, content_type: str, size_bytes: int) -> WorkbenchFileUploadPrepareResponse:
-        return cast(WorkbenchFileUploadPrepareResponse, self.sandbox.client.request(
-            "POST",
-            f"/v1/workbench/sessions/{self.sandbox.ensure_session_id()}/files/upload-url",
-            json_body={
-                "sessionId": self.sandbox.platform_session_id,
-                "path": path,
-                "contentType": content_type,
-                "sizeBytes": size_bytes,
-            },
-        ))
+        workspace_id = self.sandbox.ensure_session_id()
+        try:
+            result = self.sandbox.client.request("PUT", f"/v1/workbench/sessions/{workspace_id}/files", json_body=body)
+            return cast(WorkbenchFileResponse, self.sandbox.client.workbench.finish_operation(self.sandbox.platform_session_id, workspace_id, result))
+        except StacklinkError as error:
+            details = error.details if isinstance(error.details, dict) else {}
+            raise StacklinkError(str(error), status_code=error.status_code, code=error.code,
+                                details={**details, "uploadId": body["uploadId"], "workbenchSessionId": workspace_id, "sessionId": self.sandbox.platform_session_id},
+                                headers=error.headers, failure_id=error.failure_id) from error
+
+    def prepare_upload(self, path: str, *, content_type: str, size_bytes: int, upload_id: str | None = None) -> WorkbenchFileUploadPrepareResponse:
+        upload_id = upload_id or str(uuid4())
+        workspace_id = self.sandbox.ensure_session_id()
+        try:
+            return cast(WorkbenchFileUploadPrepareResponse, self.sandbox.client.request(
+                "POST", f"/v1/workbench/sessions/{workspace_id}/files/upload-url",
+                json_body={"sessionId": self.sandbox.platform_session_id, "path": path,
+                           "contentType": content_type, "sizeBytes": size_bytes, "uploadId": upload_id},
+            ))
+        except StacklinkError as error:
+            details = error.details if isinstance(error.details, dict) else {}
+            raise StacklinkError(str(error), status_code=error.status_code, code=error.code,
+                                details={**details, "uploadId": upload_id, "workbenchSessionId": workspace_id, "sessionId": self.sandbox.platform_session_id},
+                                headers=error.headers, failure_id=error.failure_id) from error
 
     def finalize_upload(
         self,
@@ -714,7 +775,7 @@ class WorkbenchFiles:
         *,
         metadata: Mapping[str, Any] | None = None,
     ) -> WorkbenchFileMutationResponse:
-        return cast(WorkbenchFileMutationResponse, self.sandbox.client.request(
+        result = self.sandbox.client.request(
             "POST",
             f"/v1/workbench/sessions/{self.sandbox.ensure_session_id()}/files/finalize-upload",
             json_body={
@@ -722,21 +783,31 @@ class WorkbenchFiles:
                 "uploadId": upload_id,
                 "metadata": dict(metadata or {}),
             },
-        ))
+        )
+        return cast(WorkbenchFileMutationResponse, self.sandbox.client.workbench.finish_operation(self.sandbox.platform_session_id, self.sandbox.ensure_session_id(), result))
 
     def upload_large(
         self,
         path: str,
-        content: str | bytes,
+        content: str | bytes | BinaryIO,
         *,
         content_type: str | None = None,
         metadata: Mapping[str, Any] | None = None,
+        transfer_timeout_seconds: float = 300.0,
+        upload_id: str | None = None,
     ) -> WorkbenchFileMutationResponse:
         raw = content.encode("utf-8") if isinstance(content, str) else content
         resolved_content_type = content_type or (
             "text/plain; charset=utf-8" if isinstance(content, str) else "application/octet-stream"
         )
-        prepared = self.prepare_upload(path, content_type=resolved_content_type, size_bytes=len(raw))
+        if isinstance(raw, bytes):
+            size_bytes = len(raw)
+        else:
+            position = raw.tell()
+            raw.seek(0, 2)
+            size_bytes = raw.tell() - position
+            raw.seek(position)
+        prepared = self.prepare_upload(path, content_type=resolved_content_type, size_bytes=size_bytes, upload_id=upload_id)
         upload = prepared.get("upload") if isinstance(prepared, dict) else None
         if (
             not isinstance(upload, dict)
@@ -745,13 +816,16 @@ class WorkbenchFiles:
         ):
             raise StacklinkError("Stacklink did not return a signed Workbench upload URL.")
         headers = upload.get("requiredHeaders") if isinstance(upload.get("requiredHeaders"), dict) else {}
-        request = Request(upload["uploadUrl"], data=raw, method="PUT", headers={str(key): str(value) for key, value in headers.items()})
+        request = Request(upload["uploadUrl"], data=raw, method="PUT", headers={**{str(key): str(value) for key, value in headers.items()}, "Content-Length": str(size_bytes)})
         try:
-            with urlopen(request, timeout=self.sandbox.client.timeout) as response:
+            with urlopen(request, timeout=transfer_timeout_seconds) as response:
                 if response.status >= 400:
                     raise StacklinkError(f"Workbench file upload failed with {response.status}.")
         except HTTPError as error:
-            raise StacklinkError(f"Workbench file upload failed with {error.code}.") from error
+            if error.code != 412:
+                raise StacklinkError(f"Workbench file upload failed with {error.code}.", status_code=error.code, code="workbench_file_direct_upload_failed", details={"uploadId": upload["uploadId"], "workbenchSessionId": self.sandbox.ensure_session_id(), "sessionId": self.sandbox.platform_session_id}) from error
+        except (TimeoutError, OSError) as error:
+            raise StacklinkError("Upload outcome is unknown. Finalize the same uploadId to reconcile.", code="workbench_upload_outcome_unknown", details={"uploadId": upload["uploadId"]}) from error
         return self.finalize_upload(
             upload["uploadId"],
             metadata=metadata,
@@ -767,7 +841,7 @@ class WorkbenchFiles:
         if not isinstance(download_url, str):
             raise StacklinkError("Stacklink did not return a signed Workbench download URL.")
         try:
-            with urlopen(Request(download_url, method="GET"), timeout=self.sandbox.client.timeout) as response:
+            with urlopen(Request(download_url, method="GET", headers=signed.get("requiredHeaders", {})), timeout=300.0) as response:
                 return response.read()
         except HTTPError as error:
             raise StacklinkError(f"Workbench file download failed with {error.code}.") from error
@@ -978,18 +1052,27 @@ class WorkbenchArtifacts:
         label: str | None = None,
         content_type: str | None = None,
         metadata: Mapping[str, Any] | None = None,
+        artifact_ref: str | None = None,
     ) -> WorkbenchArtifactResponse:
         body: dict[str, Any] = {
             "sessionId": self.sandbox.platform_session_id,
             "workbenchSessionId": self.sandbox.ensure_session_id(),
             "path": path,
+            "artifactRef": artifact_ref or f"wba_{uuid4()}",
             "metadata": dict(metadata or {}),
         }
         if label is not None:
             body["label"] = label
         if content_type is not None:
             body["contentType"] = content_type
-        return cast(WorkbenchArtifactResponse, self.sandbox.client.request("POST", "/v1/workbench/artifacts", json_body=body))
+        try:
+            result = self.sandbox.client.request("POST", "/v1/workbench/artifacts", json_body=body)
+            return cast(WorkbenchArtifactResponse, self.sandbox.client.workbench.finish_operation(self.sandbox.platform_session_id, self.sandbox.ensure_session_id(), result))
+        except StacklinkError as error:
+            details = error.details if isinstance(error.details, dict) else {}
+            raise StacklinkError(str(error), status_code=error.status_code, code=error.code,
+                                details={**details, "artifactRef": body["artifactRef"], "workbenchSessionId": body["workbenchSessionId"], "sessionId": body["sessionId"]},
+                                headers=error.headers, failure_id=error.failure_id) from error
 
     def download_url(self, artifact_id: str) -> WorkbenchArtifactDownloadResponse:
         return cast(WorkbenchArtifactDownloadResponse, self.sandbox.client.workbench.artifact_download_url(artifact_id))
@@ -1018,6 +1101,12 @@ class SessionSandbox:
         self.runs = WorkbenchRuns(self)
         self.artifacts = WorkbenchArtifacts(self)
 
+    def resume(self, execution_id: str, expected_wait_revision: int, checkpoint_id: str) -> WorkbenchExecutionResponse:
+        return self.client.request("POST", "/v1/workbench/resume", json_body={
+            "sessionId": self.platform_session_id, "executionId": execution_id,
+            "expectedWaitRevision": expected_wait_revision, "checkpointId": checkpoint_id,
+        })
+
     def use(
         self,
         workbench_session_id: str | None = None,
@@ -1096,6 +1185,10 @@ class WorkbenchResource:
 
     def run(self, body: dict[str, Any]):
         response = cast(WorkbenchExecutionResponse, self.client.request("POST", "/v1/workbench/run", json_body=body))
+        if isinstance(response.get("operation"), dict):
+            operation = response["operation"]
+            completed = self.wait_operation(body["sessionId"], operation["workbenchSessionId"], operation["operationId"])
+            return {**{key: value for key, value in response.items() if key != "operation"}, **completed}
         if body.get("operation") == "run_code" and body.get("background") is not True:
             return _wait_for_workbench_response(self.client, body, response)
         return response
@@ -1106,6 +1199,12 @@ class WorkbenchResource:
             return _wait_for_workbench_response(self.client, body, response)
         return response
 
+    def resume(self, session_id: str, execution_id: str, *, expected_wait_revision: int, checkpoint_id: str):
+        return self.client.request("POST", "/v1/workbench/resume", json_body={
+            "sessionId": session_id, "executionId": execution_id,
+            "expectedWaitRevision": expected_wait_revision, "checkpointId": checkpoint_id,
+        })
+
     def compute_status(self, session_id: str, workbench_session_id: str) -> WorkbenchComputeStatus:
         return cast(WorkbenchComputeStatus, self.client.request("POST", "/v1/workbench/run", json_body={
             "sessionId": session_id, "workbenchSessionId": workbench_session_id, "operation": "compute_status",
@@ -1118,12 +1217,30 @@ class WorkbenchResource:
             "operation": "destroy",
         })
 
+    def operation(self, session_id: str, workbench_session_id: str, operation_id: str):
+        return self.client.request("GET", f"/v1/workbench/sessions/{workbench_session_id}/operations/{operation_id}", query={"sessionId": session_id})
+
+    def wait_operation(self, session_id: str, workbench_session_id: str, operation_id: str, *, timeout_seconds: float = 300.0):
+        deadline = time.monotonic() + timeout_seconds
+        while time.monotonic() < deadline:
+            try:
+                value = self.operation(session_id, workbench_session_id, operation_id)["operation"]
+            except StacklinkError as error:
+                raise StacklinkError("Operation observation stopped. Resume with the same operation ID.", status_code=error.status_code, code="workbench_operation_observation_failed", details={"operationId": operation_id, "workbenchSessionId": workbench_session_id, "sessionId": session_id, "causeCode": error.code}) from error
+            if value["status"] == "completed":
+                return value["result"]
+            if value["status"] == "failed":
+                raise StacklinkError("Workbench operation needs attention.", code="workbench_operation_failed", details=value)
+            time.sleep(min(max(0.1, value.get("retryAfterMs", 1000) / 1000), max(0, deadline - time.monotonic())))
+        raise StacklinkError("Workbench operation is still running. Resume with its operation ID.", code="workbench_operation_pending", details={"operationId": operation_id, "workbenchSessionId": workbench_session_id, "sessionId": session_id})
+
+    def finish_operation(self, session_id: str, workbench_session_id: str, result):
+        operation = result.get("operation") if isinstance(result, dict) else None
+        return self.wait_operation(session_id, workbench_session_id, operation["operationId"]) if isinstance(operation, dict) else result
+
     def delete_session(self, session_id: str, workbench_session_id: str) -> WorkbenchSessionDeleteReceipt:
-        return cast(WorkbenchSessionDeleteReceipt, self.client.request(
-            "DELETE",
-            f"/v1/workbench/sessions/{workbench_session_id}",
-            query={"sessionId": session_id},
-        ))
+        result = self.client.request("DELETE", f"/v1/workbench/sessions/{workbench_session_id}", query={"sessionId": session_id})
+        return cast(WorkbenchSessionDeleteReceipt, self.finish_operation(session_id, workbench_session_id, result))
 
     def sessions(self, session_id: str):
         return self.client.request("GET", f"/v1/sessions/{session_id}/workbench")

{stacklink_sdk-0.3.15 → stacklink_sdk-0.4.0/stacklink_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stacklink-sdk
-Version: 0.3.15
+Version: 0.4.0
 Summary: Python SDK for Stacklink sessions, tools, MCP, auth, workbench, logs, knowledge, and billing.
 Author: Stacklink
 License-Expression: LicenseRef-Proprietary

{stacklink_sdk-0.3.15 → stacklink_sdk-0.4.0}/tests/test_client.py

@@ -20,7 +20,7 @@ from stacklink import (
     create_stacklink_claude_agent_tool_config,
     create_stacklink_openai_agents_tools,
 )
-from stacklink.workbench import WorkbenchRun
+from stacklink.workbench import WorkbenchRun, SessionSandbox
 
 
 @contextmanager
@@ -63,6 +63,70 @@ def stalled_stream_server(*, final_result=False, execution_page=False):
 
 
 class StacklinkClientTests(unittest.TestCase):
+    def test_workbench_lost_acknowledgement_keeps_upload_and_artifact_identity(self):
+        bodies = []
+        def transport(method, path, headers, body, query, timeout):
+            bodies.append(body)
+            return 504, {}, {"code": "outbound_http_timeout", "message": "Lost acknowledgement"}
+        client = Stacklink(api_key="test", transport=transport, max_attempts=1)
+        sandbox = SessionSandbox(client, "session-1")
+        sandbox.workbench_session_id = "workspace-1"
+        with self.assertRaises(StacklinkError) as caught:
+            sandbox.files.upload("नतीजा.bin", b"result")
+        upload_id = caught.exception.details["uploadId"]
+        with self.assertRaises(StacklinkError):
+            sandbox.files.upload("नतीजा.bin", b"result", upload_id=upload_id)
+        self.assertEqual(bodies[0]["uploadId"], bodies[1]["uploadId"])
+        with self.assertRaises(StacklinkError) as caught:
+            sandbox.artifacts.promote("नतीजा.bin")
+        artifact_ref = caught.exception.details["artifactRef"]
+        with self.assertRaises(StacklinkError):
+            sandbox.artifacts.promote("नतीजा.bin", artifact_ref=artifact_ref)
+        self.assertEqual(bodies[2]["artifactRef"], bodies[3]["artifactRef"])
+
+    def test_workbench_storage_wait_retains_identity_and_never_repeats_deletion(self):
+        calls = []
+        receipt = {"deleted": True, "databaseDeleted": True, "workbenchSessionId": "workspace-1"}
+        def transport(method, path, headers, body, query, timeout):
+            calls.append((method, path))
+            if method == "DELETE":
+                return 202, {}, {"operation": {"operationId": "operation-1"}}
+            return 200, {}, {"operation": {"operationId": "operation-1", "status": "completed", "result": receipt}}
+        client = Stacklink(api_key="test", transport=transport)
+        self.assertEqual(client.workbench.delete_session("session-1", "workspace-1"), receipt)
+        self.assertEqual([method for method, _ in calls], ["DELETE", "GET"])
+        with self.assertRaises(StacklinkError) as caught:
+            client.workbench.wait_operation("session-1", "workspace-1", "operation-1", timeout_seconds=0)
+        self.assertEqual(caught.exception.details, {"sessionId": "session-1", "workbenchSessionId": "workspace-1", "operationId": "operation-1"})
+        self.assertEqual(len(calls), 2)
+
+    def test_workbench_storage_observation_failure_keeps_resume_handle(self):
+        def transport(method, path, headers, body, query, timeout):
+            return 403, {}, {"code": "access_denied", "message": "denied"}
+        client = Stacklink(api_key="test", transport=transport)
+        with self.assertRaises(StacklinkError) as caught:
+            client.workbench.wait_operation("session-1", "workspace-1", "operation-1")
+        self.assertEqual(caught.exception.code, "workbench_operation_observation_failed")
+        self.assertEqual(caught.exception.details["operationId"], "operation-1")
+
+    def test_bot_avatar_recipe_is_preserved_for_sync_and_async_create(self):
+        recipe = {"version": 1, "style": "clay", "seed": "Sales assistant", "tone": "mint"}
+        payloads = []
+        def respond(request):
+            payload = json.loads(request.content)
+            payloads.append(payload)
+            return httpx.Response(200, json={"id": "bot", "identity": {"avatar": payload["avatar"], "pictureUrl": "https://example.test/avatar.png"}})
+        with httpx.Client(transport=httpx.MockTransport(respond)) as http:
+            client = Stacklink(api_key="test", base_url="https://example.test", http_client=http)
+            self.assertEqual(client.bots.create("Sales", avatar=recipe)["identity"]["avatar"], recipe)
+        async def check_async():
+            async with httpx.AsyncClient(transport=httpx.MockTransport(respond)) as http:
+                client = AsyncStacklink(api_key="test", base_url="https://example.test", http_client=http)
+                result = await client.bots.create("Sales", avatar=recipe)
+                self.assertEqual(result["identity"]["avatar"], recipe)
+        asyncio.run(check_async())
+        self.assertEqual([item["avatar"] for item in payloads], [recipe, recipe])
+
     def test_customer_grant_management_uses_session_identity(self):
         calls = []
         def transport(method, path, headers, body, query, timeout):
@@ -99,6 +163,30 @@ class StacklinkClientTests(unittest.TestCase):
                 self.assertFalse(result["executed"])
                 self.assertEqual(len(calls), 2 if admission_status == "queued" else 1)
 
+    def test_saved_wait_returns_to_caller_and_preserves_resume_identity(self):
+        for status in ("waiting_saved", "waiting_ready", "resuming"):
+            calls = []
+            state = {"id": "execution-1", "executionKind": "workbench_code", "status": status,
+                     "waitRevision": 2, "waitState": {"checkpointId": "checkpoint-1"}}
+            if status == "resuming":
+                state.update({"nextAction": "wait_for_approval", "approvalRequestId": "approval-2"})
+            def transport(method, path, headers, body, query, timeout):
+                calls.append((path, body))
+                if path == "/v1/workbench/run":
+                    return 202, {}, {"executionId": state["id"], "executionKind": "workbench_code", "status": "queued"}
+                if path.endswith("/wait") and len(calls) == 2:
+                    return 200, {}, {"execution": state}
+                if path == "/v1/workbench/resume":
+                    return 202, {}, {**state, "status": "resuming"}
+                raise AssertionError(f"Unexpected saved wait polling: {path}")
+            client = Stacklink(api_key="ppk_test", transport=transport)
+            result = client.workbench.run({"sessionId": "session-1", "operation": "run_code", "code": "print(1)"})
+            self.assertEqual(result["status"], status)
+            self.assertEqual(result["nextAction"], "wait_for_approval" if status == "resuming" else "resume_saved_work")
+            self.assertEqual(len(calls), 2)
+            client.workbench.resume("session-1", "execution-1", expected_wait_revision=2, checkpoint_id="checkpoint-1")
+            self.assertEqual(calls[-1], ("/v1/workbench/resume", {"sessionId": "session-1", "executionId": "execution-1", "expectedWaitRevision": 2, "checkpointId": "checkpoint-1"}))
+
     def test_approvals_observe_reconnect_and_customer_identity(self):
         calls = []
         def transport(method, path, headers, body, query, timeout):
@@ -762,6 +850,23 @@ class StacklinkClientTests(unittest.TestCase):
         lines.extend(decoder.finish())
         self.assertEqual(lines, ['data: {"value":"नमस्ते"}', ''])
 
+    def test_failure_reference_survives_http_and_mcp_errors(self):
+        from stacklink.mcp import unwrap_tool_result
+        for status, body in [(502, {"failureId": "failure-body"}), (429, {})]:
+            def transport(method, path, headers, request_body, query, timeout):
+                return status, {"x-stacklink-failure-id": "failure-header"}, body
+            client = Stacklink(api_key="ppk_test", transport=transport)
+            with self.assertRaises(StacklinkError) as caught:
+                client.tools.search({"sessionId": "session", "query": "gmail"})
+            self.assertEqual(caught.exception.failure_id, body.get("failureId", "failure-header"))
+        for response in [
+            {"error": {"code": -32603, "data": {"failureId": "failure-mcp"}}},
+            {"result": {"isError": True, "structuredContent": {"error": {"failureId": "failure-mcp"}}}},
+        ]:
+            with self.assertRaises(StacklinkError) as caught:
+                unwrap_tool_result(response)
+            self.assertEqual(caught.exception.failure_id, "failure-mcp")
+
     def test_rate_limit_error_is_typed(self):
         def transport(method, path, headers, body, query, timeout):
             return 429, {"Retry-After": "60"}, {"code": "rate_limited", "message": "Too many requests."}
@@ -952,6 +1057,9 @@ class StacklinkClientTests(unittest.TestCase):
         self.assertEqual(run.response["result"]["stdout"], "ready")
         self.assertEqual(run.response["execution"], run.response["executionLog"])
         self.assertEqual(run.response["result"], run.response["execution"]["result"])
+        upload_id = calls[2][2].pop("uploadId")
+        self.assertIsInstance(upload_id, str)
+        self.assertEqual(len(upload_id), 36)
         self.assertEqual(calls, [
             ("GET", "/v1/sessions/session-1/bootstrap", None, {}),
             ("POST", "/v1/workbench/sessions", {
@@ -967,7 +1075,7 @@ class StacklinkClientTests(unittest.TestCase):
                 "metadata": {},
                 "contentType": "text/plain",
             }, {}),
-            ("GET", "/v1/workbench/sessions/workbench-1/files", None, {"sessionId": "session-1"}),
+            ("GET", "/v1/workbench/sessions/workbench-1/files", None, {"sessionId": "session-1", "limit": 100}),
             ("POST", "/v1/workbench/run", {
                 "language": "python",
                 "code": "print('ready')",