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

{stacklink_sdk-0.3.19/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.19
+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.19 → stacklink_sdk-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stacklink-sdk"
-version = "0.3.19"
+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.19 → stacklink_sdk-0.4.0}/stacklink/bots.py

@@ -53,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
@@ -71,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):
@@ -114,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]

{stacklink_sdk-0.3.19 → 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.19"
+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.19 → 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.19 → 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.19 → 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
 
@@ -319,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
@@ -340,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
@@ -365,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
@@ -691,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:
@@ -712,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,
@@ -746,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={
@@ -754,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)
@@ -777,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,
@@ -799,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
@@ -1010,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))
@@ -1134,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
@@ -1162,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.19 → 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.19
+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.19 → 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,52 @@ 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 = []
@@ -804,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."}
@@ -994,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", {
@@ -1009,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')",