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

{stacklink_sdk-0.3.19/stacklink_sdk.egg-info → stacklink_sdk-0.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stacklink-sdk
-Version: 0.3.19
+Version: 0.6.2
 Summary: Python SDK for Stacklink sessions, tools, MCP, auth, workbench, logs, knowledge, and billing.
 Author: Stacklink
 License-Expression: LicenseRef-Proprietary
@@ -128,6 +128,33 @@ 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.
 
+## Workflows (0.6.2)
+
+Use `https://api.stacklink.in` for production.
+Workflow trigger changes now follow draft → publish. `workflows.triggers(id)`
+returns the draft `revision`, draft `triggers`, and active `liveTriggers`.
+Pass the required `expected_revision` keyword to `save_trigger` or
+`delete_trigger`, then publish the returned revision to apply the change.
+A stale revision returns 409; saving a trigger no longer activates it immediately.
+The async client uses the same lifecycle.
+
+Bot steps, child workflows, For each and Bot attachments accept `"live"` in place
+of a numeric revision/version. New runs resolve live references once and retain
+that setup through waits, retries and every item. Existing numeric pins remain
+supported. Pausing blocks new starts; publishing does not resume a paused workflow.
+The [Workflows guide](https://docs.stacklink.in/docs/workflows) covers definitions,
+permissions, stable job keys and recovery.
+
+Your Python backend can issue customer editor access through
+`workflows.issue_embedded_access(customer_id=..., user_id=..., origin=..., role=...)`.
+Derive those values from your authenticated application session. Mount the hosted
+editor in the frontend with the separate `@stacklink/workflow-builder` JavaScript
+package; never expose the project key. `with_embedded_access(project_id, access_token)`
+provides person-scoped lists, approvals and analytics. `for_customer(customer_id)`
+is for trusted backend administration. The async client supports the same methods.
+See the [embedded guide](https://docs.stacklink.in/docs/workflows#embed-the-builder-in-your-application)
+for the complete lifecycle.
+
 ## 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.

{stacklink_sdk-0.3.19 → stacklink_sdk-0.6.2}/README.md

@@ -107,6 +107,33 @@ 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.
 
+## Workflows (0.6.2)
+
+Use `https://api.stacklink.in` for production.
+Workflow trigger changes now follow draft → publish. `workflows.triggers(id)`
+returns the draft `revision`, draft `triggers`, and active `liveTriggers`.
+Pass the required `expected_revision` keyword to `save_trigger` or
+`delete_trigger`, then publish the returned revision to apply the change.
+A stale revision returns 409; saving a trigger no longer activates it immediately.
+The async client uses the same lifecycle.
+
+Bot steps, child workflows, For each and Bot attachments accept `"live"` in place
+of a numeric revision/version. New runs resolve live references once and retain
+that setup through waits, retries and every item. Existing numeric pins remain
+supported. Pausing blocks new starts; publishing does not resume a paused workflow.
+The [Workflows guide](https://docs.stacklink.in/docs/workflows) covers definitions,
+permissions, stable job keys and recovery.
+
+Your Python backend can issue customer editor access through
+`workflows.issue_embedded_access(customer_id=..., user_id=..., origin=..., role=...)`.
+Derive those values from your authenticated application session. Mount the hosted
+editor in the frontend with the separate `@stacklink/workflow-builder` JavaScript
+package; never expose the project key. `with_embedded_access(project_id, access_token)`
+provides person-scoped lists, approvals and analytics. `for_customer(customer_id)`
+is for trusted backend administration. The async client supports the same methods.
+See the [embedded guide](https://docs.stacklink.in/docs/workflows#embed-the-builder-in-your-application)
+for the complete lifecycle.
+
 ## 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.

{stacklink_sdk-0.3.19 → stacklink_sdk-0.6.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stacklink-sdk"
-version = "0.3.19"
+version = "0.6.2"
 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.6.2}/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]
@@ -216,8 +238,8 @@ class BotsResource:
     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 list(self, *, cursor: str | None = None, search: str | None = None, limit: int = 200):
+        return self.client.request("GET", "/v1/bots", query={"limit": limit, **({"cursor": cursor} if cursor else {}), **({"search": search} if search else {})})
 
     def delete(self, bot_id: str):
         return self.client.request("DELETE", self._path(bot_id))
@@ -253,6 +275,10 @@ class BotsResource:
     def get_run(self, bot_id: str, run_id: str):
         return self.client.request("GET", self._path(bot_id, run_id))
 
+    def continue_run(self, bot_id: str, run_id: str):
+        """Continue the same saved funding pause after its funding is resolved."""
+        return self.client.request("POST", self._path(bot_id, run_id) + "/continue", json_body={})
+
     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:
@@ -263,7 +289,7 @@ class BotsResource:
         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"):
+            if run["status"] in ("completed", "failed", "stopped", "cancelled", "waiting_for_approval", "waiting_for_connection") or (run.get("waitingOperation") or {}).get("kind") == "funding":
                 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})
@@ -272,7 +298,7 @@ class BotsResource:
         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"):
+            if run["status"] in ("completed", "failed", "stopped", "cancelled", "waiting_for_approval", "waiting_for_connection") or (run.get("waitingOperation") or {}).get("kind") == "funding":
                 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})

{stacklink_sdk-0.3.19 → stacklink_sdk-0.6.2}/stacklink/client.py

@@ -20,6 +20,7 @@ from .artifacts import ArtifactsResource
 from .auth_configs import AuthConfigsResource
 from .billing import BillingResource
 from .bots import BotsResource
+from .workflows import WorkflowsResource
 from .approvals import ApprovalsResource
 from .connected_accounts import ConnectedAccountsResource
 from .errors import RateLimitError, StacklinkError
@@ -37,7 +38,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.6.2"
 STACKLINK_PYTHON_USER_AGENT = f"stacklink-python/{STACKLINK_PYTHON_SDK_VERSION}"
 
 
@@ -54,6 +55,7 @@ class Stacklink:
         max_attempts: int = 3,
         http_client: httpx.Client | None = None,
     ):
+        self.workflows = WorkflowsResource(self)
         self.bots = BotsResource(self)
         self.approvals = ApprovalsResource(self)
         self.api_key = api_key or os.getenv("STACKLINK_API_KEY")
@@ -356,18 +358,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
@@ -425,6 +421,7 @@ class AsyncStacklink:
         max_attempts: int = 3,
         http_client: httpx.AsyncClient | None = None,
     ):
+        self.workflows = WorkflowsResource(self)
         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")
@@ -671,6 +668,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 +872,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.6.2}/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.6.2}/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.6.2}/stacklink/sessions.py

@@ -134,8 +134,8 @@ class Session:
     def get_contracts(self, contract_refs: list[str]):
         return self.client.sessions.get_contracts(self.id, contract_refs)
 
-    def authorize(self, connection_ref: str, *, metadata: dict[str, Any] | None = None):
-        return self.client.sessions.authorize(self.id, connection_ref, metadata=metadata)
+    def authorize(self, connection_ref: str, *, metadata: dict[str, Any] | None = None, amazon_seller_region: str | None = None):
+        return self.client.sessions.authorize(self.id, connection_ref, metadata=metadata, amazon_seller_region=amazon_seller_region)
 
     def execute(
         self,
@@ -256,12 +256,16 @@ class SessionsResource:
         connection_ref: str,
         *,
         metadata: dict[str, Any] | None = None,
+        amazon_seller_region: str | None = None,
     ):
+        if amazon_seller_region is not None and amazon_seller_region not in ("NA", "EU", "FE"):
+            raise ValueError("amazon_seller_region must be NA, EU or FE")
         return self.client.request(
             "POST",
             f"/v1/sessions/{session_id}/connections/authorize",
             json_body={
                 "connectionRef": connection_ref,
+                **({"amazonSellerRegion": amazon_seller_region} if amazon_seller_region is not None else {}),
                 "metadata": dict(metadata or {}),
             },
         )

{stacklink_sdk-0.3.19 → stacklink_sdk-0.6.2}/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
@@ -529,10 +549,15 @@ class WorkbenchExecutionResponse(TypedDict, total=False):
     artifact: WorkbenchArtifact
 
 
+def _execution_session_id(response: Mapping[str, Any], fallback: str | None) -> str | None:
+    workspace = response.get("workbenchSession")
+    return workspace["platformSessionId"] if isinstance(workspace, dict) and isinstance(workspace.get("platformSessionId"), str) else fallback
+
+
 class WorkbenchRun:
     def __init__(self, client, platform_session_id: str, response: WorkbenchExecutionResponse):
         self.client = client
-        self.platform_session_id = platform_session_id
+        self.platform_session_id = _execution_session_id(response, platform_session_id)
         self.response = response
         self.execution_id = str(response["executionId"])
         self.execution_kind = str(response["executionKind"])
@@ -631,7 +656,7 @@ def _wait_for_workbench_response(
     request: Mapping[str, Any],
     accepted: WorkbenchExecutionResponse,
 ) -> WorkbenchExecutionResponse:
-    session_id = request.get("sessionId")
+    session_id = _execution_session_id(accepted, request.get("sessionId"))
     execution_id = accepted.get("executionId")
     execution_kind = accepted.get("executionKind")
     if (
@@ -691,11 +716,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 +737,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 +780,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 +788,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 +821,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 +846,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 +1057,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))
@@ -1089,10 +1145,11 @@ class SessionSandbox:
             "workbenchSessionId": body.get("workbenchSessionId") or self.ensure_session_id(),
             "operation": "run_code",
         }
-        response: WorkbenchExecutionResponse = self.client.request("POST", "/v1/workbench/run", json_body=request)
+        response: WorkbenchExecutionResponse = self.client.request("POST", "/v1/workbench/run", json_body=request, idempotency_key=request.get("idempotencyKey"))
         if body.get("background") is not True:
             response = _wait_for_workbench_response(self.client, request, response)
-        self.workbench_session_id = str(response["workbenchSession"]["id"])
+        if _execution_session_id(response, self.platform_session_id) == self.platform_session_id:
+            self.workbench_session_id = str(response["workbenchSession"]["id"])
         return WorkbenchRun(self.client, self.platform_session_id, response)
 
     def bash(self, body: WorkbenchBashInput) -> WorkbenchRun:
@@ -1101,10 +1158,11 @@ class SessionSandbox:
             "sessionId": self.platform_session_id,
             "workbenchSessionId": body.get("workbenchSessionId") or self.ensure_session_id(),
         }
-        response: WorkbenchExecutionResponse = self.client.request("POST", "/v1/workbench/bash", json_body=request)
+        response: WorkbenchExecutionResponse = self.client.request("POST", "/v1/workbench/bash", json_body=request, idempotency_key=request.get("idempotencyKey"))
         if body.get("background") is not True:
             response = _wait_for_workbench_response(self.client, request, response)
-        self.workbench_session_id = str(response["workbenchSession"]["id"])
+        if _execution_session_id(response, self.platform_session_id) == self.platform_session_id:
+            self.workbench_session_id = str(response["workbenchSession"]["id"])
         return WorkbenchRun(self.client, self.platform_session_id, response)
 
     def destroy(self) -> WorkbenchSessionDestroyResponse:
@@ -1133,13 +1191,17 @@ class WorkbenchResource:
         return self.client.request("GET", "/v1/workbench/models")
 
     def run(self, body: dict[str, Any]):
-        response = cast(WorkbenchExecutionResponse, self.client.request("POST", "/v1/workbench/run", json_body=body))
+        response = cast(WorkbenchExecutionResponse, self.client.request("POST", "/v1/workbench/run", json_body=body, idempotency_key=body.get("idempotencyKey")))
+        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
 
     def bash(self, body: dict[str, Any]):
-        response = cast(WorkbenchExecutionResponse, self.client.request("POST", "/v1/workbench/bash", json_body=body))
+        response = cast(WorkbenchExecutionResponse, self.client.request("POST", "/v1/workbench/bash", json_body=body, idempotency_key=body.get("idempotencyKey")))
         if body.get("background") is not True:
             return _wait_for_workbench_response(self.client, body, response)
         return response
@@ -1162,12 +1224,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.6.2/stacklink/workflows.py

@@ -0,0 +1,129 @@
+"""Durable workflow definitions and runs. Reuse job_key after a timeout."""
+from typing import Any
+from urllib.parse import quote
+
+
+class WorkflowsResource:
+    def __init__(self, client, *, customer_id=None, project_id=None, access_token=None):
+        self.client = client
+        self.customer_id = customer_id
+        self.project_id = project_id
+        self.access_token = access_token
+
+    def for_customer(self, customer_id: str):
+        return WorkflowsResource(self.client, customer_id=customer_id)
+
+    def with_embedded_access(self, project_id: str, access_token: str):
+        return WorkflowsResource(self.client, project_id=project_id, access_token=access_token)
+
+    def _request(self, method, path, **options):
+        headers = dict(options.pop('headers', {}) or {})
+        if self.customer_id:
+            headers['X-Stacklink-Customer'] = self.customer_id
+        if self.access_token:
+            headers['authorization'] = 'Bearer ' + self.access_token
+        return self.client.request(method, path, headers=headers, **options)
+
+    def _path(self, workflow_id: str | None = None) -> str:
+        return ('/embedded/api/projects/' + quote(self.project_id, safe='') + '/workflows' if self.project_id else '/v1/workflows') + ('/' + quote(workflow_id, safe='') if workflow_id else '')
+
+    def list(self, *, cursor: str | None = None, search: str | None = None, limit: int = 200):
+        return self._request('GET', self._path(), query={'limit': limit, **({'cursor': cursor} if cursor else {}), **({'search': search} if search else {})})
+
+    def create(self, name: str, definition: dict[str, Any], *, source: str = 'code', description: str = '', deployment: dict[str, str] | None = None):
+        return self._request('POST', self._path(), json_body={'name': name, 'definition': definition, 'source': source, 'description': description, **({'deployment': deployment} if deployment is not None else {})})
+
+    def get(self, workflow_id: str):
+        return self._request('GET', self._path(workflow_id))
+
+    def update(self, workflow_id: str, revision: int, **changes):
+        return self._request('PATCH', self._path(workflow_id), json_body={**changes, 'revision': revision})
+
+    def validate(self, definition: dict[str, Any]):
+        return self._request('POST', self._path() + '/validate', json_body={'definition': definition})
+
+    def publish(self, workflow_id: str, revision: int):
+        return self._request('POST', self._path(workflow_id) + '/publish', json_body={'revision': revision})
+
+    def set_state(self, workflow_id: str, paused: bool):
+        return self._request('POST', self._path(workflow_id) + '/state', json_body={'paused': paused})
+
+    def versions(self, workflow_id: str):
+        return self._request('GET', self._path(workflow_id) + '/versions')
+
+    def run(self, workflow_id: str, session_id: str, job_key: str, *, input: dict[str, Any] | None = None, **options):
+        return self._request('POST', self._path(workflow_id) + '/runs', json_body={**options, 'sessionId': session_id, 'jobKey': job_key, 'input': input or {}}, idempotency_key=job_key)
+
+    def runs(self, workflow_id: str, *, cursor: str | None = None, limit: int = 50):
+        return self._request('GET', self._path(workflow_id) + '/runs', query={'limit': limit, **({'cursor': cursor} if cursor else {})})
+
+    def get_run(self, workflow_id: str, run_id: str):
+        return self._request('GET', self._path(workflow_id) + '/runs/' + quote(run_id, safe=''))
+
+    def events(self, workflow_id: str, run_id: str, *, before: str | None = None, limit: int = 200):
+        return self._request('GET', self._path(workflow_id) + '/runs/' + quote(run_id, safe='') + '/events', query={'limit': limit, **({'before': before} if before else {})})
+
+    def action(self, workflow_id: str, run_id: str, action: str, **options):
+        return self._request('POST', self._path(workflow_id) + '/runs/' + quote(run_id, safe='') + '/actions', json_body={**options, 'action': action})
+
+    def triggers(self, workflow_id: str):
+        return self._request('GET', self._path(workflow_id) + '/triggers')
+
+    def save_trigger(self, workflow_id: str, configuration: dict[str, Any], *, expected_revision: int):
+        """Save a draft trigger. Publish the returned revision to activate it."""
+        return self._request('POST', self._path(workflow_id) + '/triggers', json_body={**configuration, 'expectedRevision': expected_revision})
+
+    def delete_trigger(self, workflow_id: str, trigger_id: str, *, expected_revision: int):
+        return self._request('DELETE', self._path(workflow_id) + '/triggers/' + quote(trigger_id, safe=''), query={'expectedRevision': expected_revision})
+
+    def invoke_trigger(self, workflow_id: str, trigger_id: str, request_id: str, input: dict[str, Any]):
+        return self._request('POST', self._path(workflow_id) + '/triggers/' + quote(trigger_id, safe='') + '/invoke', json_body={'requestId': request_id, 'input': input}, idempotency_key=request_id)
+
+    def preview_schedule(self, cron: str, timezone: str = 'UTC'):
+        return self._request('POST', self._path() + '/schedule/preview', json_body={'cron': cron, 'timezone': timezone})
+
+    def suggest(self, workflow_id: str, description: str, revision: int, session_id: str):
+        return self._request('POST', self._path(workflow_id) + '/suggest', json_body={'description': description, 'revision': revision, 'sessionId': session_id}, timeout_ms=60_000)
+
+
+    def issue_embedded_access(self, customer_id: str, user_id: str, origin: str, role: str, *, decide_approvals: bool = False, view_usage: bool = False, workflow_id: str | None = None, customer_name: str | None = None, user_name: str | None = None):
+        return self.client.request('POST', '/v1/workflows/embed/access', json_body={
+            'customerId': customer_id, 'userId': user_id, 'origin': origin, 'role': role,
+            'decideApprovals': decide_approvals, 'viewUsage': view_usage,
+            **({'workflowId': workflow_id} if workflow_id else {}),
+            **({'customerName': customer_name} if customer_name else {}),
+            **({'userName': user_name} if user_name else {}),
+        })
+
+    def exchange_embedded_access(self, bootstrap_token: str, origin: str):
+        return self.client.request('POST', '/v1/workflows/embed/exchange', json_body={'bootstrapToken': bootstrap_token, 'origin': origin})
+
+    def embed_settings(self):
+        return self._request('GET', self._path() + '/embed')
+
+    def save_embed_settings(self, revision: int, config: dict):
+        return self._request('PUT', self._path() + '/embed', json_body={'revision': revision, 'config': config})
+
+    def customers(self, **query):
+        return self._request('GET', self._path() + '/embed/customers', query=query)
+
+    def customer(self, customer_id: str):
+        return self._request('GET', self._path() + '/embed/customers/' + quote(customer_id, safe=''))
+
+    def set_customer_automations(self, customer_id: str, enabled: bool):
+        return self._request('POST', self._path() + '/embed/customers/' + quote(customer_id, safe='') + '/automations', json_body={'enabled': enabled})
+
+    def set_customer_person_access(self, customer_id: str, person_id: str, action: str):
+        return self._request('POST', self._path() + '/embed/customers/' + quote(customer_id, safe='') + '/people/' + quote(person_id, safe='') + '/access', json_body={'action': action})
+
+    def analytics(self, *, days: int = 30, customer_id: str | None = None):
+        return self._request('GET', self._path() + '/analytics', query={'days': days, **({'customerId': customer_id} if customer_id else {})})
+
+    def activity(self, **query):
+        return self._request('GET', self._path() + '/activity', query=query)
+
+    def approvals(self, *, view: str = 'inbox', cursor: str | None = None, limit: int = 50):
+        return self._request('GET', self._path() + '/approvals', query={'view': view, 'limit': limit, **({'cursor': cursor} if cursor else {})})
+
+    def decide_approval(self, approval_id: str, decision: dict):
+        return self._request('POST', self._path() + '/approvals/' + quote(approval_id, safe='') + '/decide', json_body=decision)

{stacklink_sdk-0.3.19 → stacklink_sdk-0.6.2/stacklink_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stacklink-sdk
-Version: 0.3.19
+Version: 0.6.2
 Summary: Python SDK for Stacklink sessions, tools, MCP, auth, workbench, logs, knowledge, and billing.
 Author: Stacklink
 License-Expression: LicenseRef-Proprietary
@@ -128,6 +128,33 @@ 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.
 
+## Workflows (0.6.2)
+
+Use `https://api.stacklink.in` for production.
+Workflow trigger changes now follow draft → publish. `workflows.triggers(id)`
+returns the draft `revision`, draft `triggers`, and active `liveTriggers`.
+Pass the required `expected_revision` keyword to `save_trigger` or
+`delete_trigger`, then publish the returned revision to apply the change.
+A stale revision returns 409; saving a trigger no longer activates it immediately.
+The async client uses the same lifecycle.
+
+Bot steps, child workflows, For each and Bot attachments accept `"live"` in place
+of a numeric revision/version. New runs resolve live references once and retain
+that setup through waits, retries and every item. Existing numeric pins remain
+supported. Pausing blocks new starts; publishing does not resume a paused workflow.
+The [Workflows guide](https://docs.stacklink.in/docs/workflows) covers definitions,
+permissions, stable job keys and recovery.
+
+Your Python backend can issue customer editor access through
+`workflows.issue_embedded_access(customer_id=..., user_id=..., origin=..., role=...)`.
+Derive those values from your authenticated application session. Mount the hosted
+editor in the frontend with the separate `@stacklink/workflow-builder` JavaScript
+package; never expose the project key. `with_embedded_access(project_id, access_token)`
+provides person-scoped lists, approvals and analytics. `for_customer(customer_id)`
+is for trusted backend administration. The async client supports the same methods.
+See the [embedded guide](https://docs.stacklink.in/docs/workflows#embed-the-builder-in-your-application)
+for the complete lifecycle.
+
 ## 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.

{stacklink_sdk-0.3.19 → stacklink_sdk-0.6.2}/stacklink_sdk.egg-info/SOURCES.txt

@@ -27,12 +27,14 @@ stacklink/triggers.py
 stacklink/types.py
 stacklink/webhooks.py
 stacklink/workbench.py
+stacklink/workflows.py
 stacklink/x_chat.py
 stacklink_sdk.egg-info/PKG-INFO
 stacklink_sdk.egg-info/SOURCES.txt
 stacklink_sdk.egg-info/dependency_links.txt
 stacklink_sdk.egg-info/requires.txt
 stacklink_sdk.egg-info/top_level.txt
+tests/test_amazon_seller_provider.py
 tests/test_client.py
 tests/test_google_docs_provider.py
 tests/test_google_drive_provider.py

stacklink_sdk-0.6.2/tests/test_amazon_seller_provider.py

@@ -0,0 +1,38 @@
+import unittest
+
+from stacklink import Stacklink
+
+
+class AmazonSellerClientTests(unittest.TestCase):
+    def test_authorization_uses_the_shared_session_route_and_exact_region(self):
+        calls = []
+
+        def transport(method, path, headers, body, query, timeout):
+            calls.append((method, path, body))
+            return 200, {}, {"authorization": {"providerKey": "amazon_seller", "status": "pending"}}
+
+        client = Stacklink(api_key="ppk_test", transport=transport)
+        client.sessions.authorize("session-owned", "opaque-ref", amazon_seller_region="EU")
+        self.assertEqual(calls, [("POST", "/v1/sessions/session-owned/connections/authorize", {
+            "connectionRef": "opaque-ref", "amazonSellerRegion": "EU", "metadata": {}
+        })])
+        with self.assertRaises(ValueError):
+            client.sessions.authorize("session-owned", "opaque-ref", amazon_seller_region="India")
+        self.assertEqual(len(calls), 1)
+
+    def test_execution_uses_existing_tool_route_without_provider_credentials(self):
+        calls = []
+
+        def transport(method, path, headers, body, query, timeout):
+            calls.append((method, path, body))
+            return 200, {}, {"status": "completed", "output": {"data": {"payload": []}}}
+
+        client = Stacklink(api_key="ppk_test", transport=transport)
+        payload = {"sessionId": "session-owned", "toolKey": "amazon_seller.seller.get_marketplace_participations", "input": {}}
+        result = client.tools.execute(payload)
+        self.assertEqual(result["status"], "completed")
+        self.assertEqual(calls, [("POST", "/v1/tools/execute", payload)])
+
+
+if __name__ == "__main__":
+    unittest.main()

{stacklink_sdk-0.3.19 → stacklink_sdk-0.6.2}/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,114 @@ def stalled_stream_server(*, final_result=False, execution_page=False):
 
 
 class StacklinkClientTests(unittest.TestCase):
+    def test_workflow_embedded_access_maps_delegated_permissions(self):
+        calls = []
+        def transport(method, path, headers, body, query, timeout):
+            calls.append((method, path, body))
+            return 200, {}, {"bootstrapToken": "one-use", "embedUrl": "https://staging.stacklink.in/embed/workflows/project"}
+        client = Stacklink(api_key="host-backend-key", transport=transport)
+        client.workflows.issue_embedded_access(
+            "fernhill", "maya", "https://acme.example", "viewer",
+            decide_approvals=True, view_usage=True, workflow_id="workflow-1",
+            customer_name="Fernhill", user_name="Maya",
+        )
+        self.assertEqual(calls, [("POST", "/v1/workflows/embed/access", {
+            "customerId": "fernhill", "userId": "maya", "origin": "https://acme.example", "role": "viewer",
+            "decideApprovals": True, "viewUsage": True, "workflowId": "workflow-1",
+            "customerName": "Fernhill", "userName": "Maya",
+        })])
+
+    def test_workflow_embedded_context_does_not_change_project_client(self):
+        calls = []
+        def transport(method, path, headers, body, query, timeout):
+            calls.append((path, dict(headers), body))
+            return 200, {}, {"workflows": [], "nextCursor": None}
+        client = Stacklink(api_key="host-backend-key", transport=transport)
+        a = client.workflows.for_customer("fernhill")
+        b = client.workflows.for_customer("larkspur")
+        a.list()
+        b.list()
+        client.workflows.list()
+        person = client.workflows.with_embedded_access("project-1", "sle_person")
+        person.approvals()
+        person.decide_approval("task-1", {"kind": "workflow", "value": "approved"})
+        self.assertEqual([row[1].get("X-Stacklink-Customer") for row in calls], ["fernhill", "larkspur", None, None, None])
+        self.assertEqual(calls[3][0], "/embedded/api/projects/project-1/workflows/approvals")
+        self.assertEqual({key.lower(): value for key, value in calls[3][1].items()}["authorization"], "Bearer sle_person")
+        self.assertEqual(calls[4][2], {"kind": "workflow", "value": "approved"})
+
+    def test_workflow_retry_and_trigger_use_stable_request_identity(self):
+        calls = []
+        def transport(method, path, headers, body, query, timeout):
+            calls.append((method, path, headers.get("Idempotency-Key"), body, query))
+            if len(calls) == 1:
+                return 503, {}, {"message": "Lost acknowledgement"}
+            return 200, {}, {"id": "same-run", "runs": [], "nextCursor": None}
+        client = Stacklink(api_key="ppk_test", transport=transport)
+        with patch("stacklink.client.time.sleep", return_value=None):
+            result = client.workflows.run("wf-1", "session-1", "upload-42", input={"recording": "चर्चा"})
+        self.assertEqual(result["id"], "same-run")
+        self.assertEqual(calls[0], calls[1])
+        self.assertEqual(calls[0][2], "upload-42")
+        client.workflows.runs("wf-1", cursor="run-1", limit=10)
+        self.assertEqual(calls[2][4], {"cursor": "run-1", "limit": 10})
+        client.workflows.invoke_trigger("wf-1", "trigger-1", "event-8", {"subject": "Ready"})
+        self.assertEqual(calls[3][1:4], ("/v1/workflows/wf-1/triggers/trigger-1/invoke", "event-8", {"requestId": "event-8", "input": {"subject": "Ready"}}))
+        client.workflows.suggest("wf-1", "Review findings", 3, "session-1")
+        self.assertEqual(calls[4][1], "/v1/workflows/wf-1/suggest")
+        self.assertEqual(calls[4][3], {"description": "Review findings", "revision": 3, "sessionId": "session-1"})
+        client.workflows.save_trigger("wf-1", {"kind": "webhook"}, expected_revision=3)
+        self.assertEqual(calls[5][3], {"kind": "webhook", "expectedRevision": 3})
+        client.workflows.delete_trigger("wf-1", "trigger-1", expected_revision=4)
+        self.assertEqual(calls[6][4], {"expectedRevision": 4})
+
+
+    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 = []
@@ -97,6 +205,48 @@ class StacklinkClientTests(unittest.TestCase):
         self.assertEqual(calls[2][2], {'revision': 2})
 
 
+    def test_workbench_replay_observes_the_original_session(self):
+        for operation in ("bash", "run_code"):
+            calls = []
+            kind = "workbench_bash" if operation == "bash" else "workbench_code"
+            def transport(method, path, headers, body, query, timeout):
+                calls.append((path, body))
+                if path in {"/v1/workbench/bash", "/v1/workbench/run"}:
+                    return 202, {}, {"executionId": "original-execution", "executionKind": kind, "status": "queued", "idempotency": {"replayed": True}, "workbenchSession": {"id": "workspace", "platformSessionId": "original-session"}}
+                self.assertEqual(body["sessionId"], "original-session")
+                return 200, {}, {"execution": {"id": "original-execution", "executionKind": kind, "status": "completed", "stdout": "saved result"}}
+            client = Stacklink(api_key="ppk_test", transport=transport)
+            payload = {"sessionId": "replacement-session", "idempotencyKey": "same-logical-job", "operation": operation, "command": "echo saved", "language": "python", "code": 'print("saved")'}
+            result = client.workbench.bash(payload) if operation == "bash" else client.workbench.run(payload)
+            self.assertEqual(result["status"], "completed")
+            self.assertEqual(len(calls), 2)
+            self.assertEqual(calls[0][1]["sessionId"], "replacement-session")
+
+    def test_replayed_run_keeps_the_replacement_sandbox_separate(self):
+        for operation in ("bash", "run_code"):
+            controls = []
+            def transport(method, path, headers, body, query, timeout):
+                if path.endswith("/files"):
+                    self.assertEqual(query["sessionId"], "replacement-session")
+                    self.assertEqual(path, "/v1/workbench/sessions/replacement-workspace/files")
+                    return 200, {}, {"files": []}
+                if path.startswith("/v1/executions/"):
+                    self.assertEqual(body["sessionId"], "original-session")
+                    controls.append(path)
+                    return 200, {}, {"execution": {"id": "original-execution", "status": "running"}}
+                if path == "/v1/workbench/sessions":
+                    return 200, {}, {"workbenchSession": {"id": "replacement-workspace", "platformSessionId": "replacement-session"}}
+                self.assertEqual(body["sessionId"], "replacement-session")
+                self.assertEqual(body["workbenchSessionId"], "replacement-workspace")
+                return 202, {}, {"executionId": "original-execution", "executionKind": "workbench_bash" if operation == "bash" else "workbench_code", "status": "running", "workbenchSession": {"id": "original-workspace", "platformSessionId": "original-session"}}
+            client = Stacklink(api_key="ppk_test", transport=transport)
+            sandbox = SessionSandbox(client, "replacement-session")
+            run = sandbox.bash({"command": "echo saved", "idempotencyKey": "same-work", "background": True}) if operation == "bash" else sandbox.run({"language": "python", "code": 'print("saved")', "idempotencyKey": "same-work", "background": True})
+            run.wait()
+            run.cancel("explicit cancellation")
+            sandbox.files.list()
+            self.assertEqual(len(controls), 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"):
@@ -804,6 +954,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 +1161,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 +1179,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')",