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

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

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

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

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

{stacklink_sdk-0.3.14 → stacklink_sdk-0.3.19}/stacklink/__init__.py

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

{stacklink_sdk-0.3.14 → stacklink_sdk-0.3.19}/stacklink/billing.py

@@ -1,6 +1,45 @@
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, TypedDict, cast
+
+
+class ResourceAllowanceAdjustment(TypedDict, total=False):
+    credited: int
+
+
+class ResourceUsage(ResourceAllowanceAdjustment):
+    key: str
+    label: str
+    unit: str
+    included: int
+    used: int
+    reserved: int
+    remaining: int
+    additional: int
+    additionalCents: int
+    priceMicros: str
+    unitQuantity: int
+    rateVersion: str
+
+
+class AdditionalSpending(TypedDict):
+    approvedCents: int
+    usedCents: int
+    reservedCents: int
+    availableCents: int
+    currency: str
+
+
+class UsageSummary(TypedDict, total=False):
+    agreementVersion: str
+    resources: list[ResourceUsage]
+    spending: dict[str, AdditionalSpending]
+    workspace: dict[str, Any]
+    subscription: dict[str, Any]
+    plan: dict[str, Any]
+    period: dict[str, str]
+    usage: dict[str, Any]
+    overagePending: bool
 
 
 class BillingResource:
@@ -16,8 +55,8 @@ class BillingResource:
     def subscription(self):
         return self.client.request("GET", "/v1/subscription")
 
-    def usage(self, **query):
-        return self.client.request("GET", "/v1/usage", query=query)
+    def usage(self, **query) -> UsageSummary:
+        return cast(UsageSummary, self.client.request("GET", "/v1/usage", query=query))
 
     def usage_events(self, **query):
         return self.client.request("GET", "/v1/usage/events", query=query)

{stacklink_sdk-0.3.14 → stacklink_sdk-0.3.19}/stacklink/bots.py

@@ -15,8 +15,15 @@ from urllib.parse import quote
 from uuid import uuid4
 
 
+class BotAvatar(TypedDict):
+    version: Literal[1]
+    style: Literal["clay", "pebble", "shapes", "letters"]
+    seed: str
+    tone: Literal["auto", "mint", "teal", "sky", "iris", "plum", "rose", "coral", "apricot", "sun", "lime", "slate", "ink"]
+
+
 class _BotCapabilityAccount(TypedDict, total=False):
-    account: Literal["project", "customer"]
+    account: Literal["project", "customer", "deployment"]
 
 
 class BotCapabilityFact(_BotCapabilityAccount):
@@ -218,8 +225,8 @@ class BotsResource:
     def set_state(self, bot_id: str, state: str, *, pause_for: str = "manual", reason: str = ""):
         return self.client.request("POST", self._path(bot_id) + "/state", json_body={"state": state, "pauseFor": pause_for, "reason": reason})
 
-    def create(self, name: str):
-        return self.client.request("POST", "/v1/bots", json_body={"name": name})
+    def create(self, name: str, *, public_description: str = "", icon_asset_id: str | None = None, avatar: BotAvatar | None = None):
+        return self.client.request("POST", "/v1/bots", json_body={"name": name, "publicDescription": public_description, "iconAssetId": icon_asset_id, **({"avatar": avatar} if avatar is not None else {})})
 
     def set_customer_credential(self, bot_id: str, *, api_id: str, session_id: str, secret: str):
         return self.client.request("POST", self._path(bot_id) + "/credentials", json_body={"apiId": api_id, "sessionId": session_id, "secret": secret})

{stacklink_sdk-0.3.14 → stacklink_sdk-0.3.19}/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.14"
+STACKLINK_PYTHON_SDK_VERSION = "0.3.19"
 STACKLINK_PYTHON_USER_AGENT = f"stacklink-python/{STACKLINK_PYTHON_SDK_VERSION}"
 
 

{stacklink_sdk-0.3.14 → stacklink_sdk-0.3.19}/stacklink/workbench.py

@@ -18,6 +18,10 @@ WorkbenchExecutionKind = Literal["workbench_code", "workbench_bash"]
 WorkbenchReplayEnvironmentMode = Literal["require_match", "restore_snapshot", "current"]
 WorkbenchExecutionStatus = Literal[
     "waiting_for_approval",
+    "checkpointing",
+    "waiting_saved",
+    "waiting_ready",
+    "resuming",
     "queued",
     "started",
     "running",
@@ -68,6 +72,28 @@ class WorkbenchSession(TypedDict, total=False):
     updatedAt: str
 
 
+class WorkbenchComputeState(TypedDict, total=False):
+    status: str
+    stopped: bool
+    fundedThrough: int | None
+    activeExecutionCount: int
+    generation: int | None
+
+
+class WorkbenchRuntimeCapacity(TypedDict):
+    measurement: Literal["customer_active_ms", "legacy_operations"]
+    settlementStatus: Literal["pending", "acknowledgement_pending", "settled"]
+    reservedMilliseconds: int
+    workspace: dict[str, Any] | None
+    intervals: list[dict[str, Any]]
+
+
+class WorkbenchComputeStatus(TypedDict):
+    workbenchSession: WorkbenchSession
+    compute: WorkbenchComputeState
+    billing: WorkbenchRuntimeCapacity
+
+
 class WorkbenchSessionUseResponse(TypedDict):
     workbenchSession: WorkbenchSession
     reused: bool
@@ -119,7 +145,30 @@ class WorkbenchSessionDeleteReceipt(TypedDict):
     databaseDeleted: Literal[True]
 
 
+class WorkbenchWaitContinuation(TypedDict):
+    language: WorkbenchLanguage
+    code: str
+    timeoutMs: int
+
+
+class WorkbenchKeepReadyConsent(TypedDict):
+    maximumWaitMs: int
+    maximumChargeMicros: str
+    priceMicros: str
+    unitQuantity: int
+    rateVersion: str
+
+
+class WorkbenchWaitRequest(TypedDict, total=False):
+    mode: Literal["saved", "keep_ready"]
+    reason: Literal["approval", "connection", "user_input", "external_event"]
+    maximumWaitMs: int
+    continuation: WorkbenchWaitContinuation
+    keepReady: WorkbenchKeepReadyConsent
+
+
 class WorkbenchRunInput(TypedDict, total=False):
+    afterExecution: WorkbenchWaitRequest
     language: WorkbenchLanguage
     code: str
     workbenchSessionId: str
@@ -136,6 +185,7 @@ class WorkbenchRunInput(TypedDict, total=False):
 
 
 class WorkbenchBashInput(TypedDict, total=False):
+    afterExecution: WorkbenchWaitRequest
     command: str
     workbenchSessionId: str
     timeoutMs: int
@@ -151,6 +201,8 @@ class WorkbenchBashInput(TypedDict, total=False):
 
 
 class WorkbenchExecutionLog(TypedDict, total=False):
+    waitRevision: int
+    waitState: dict[str, Any] | None
     id: str
     workbenchSessionId: str
     operation: str
@@ -465,7 +517,7 @@ class WorkbenchExecutionStateResponse(TypedDict, total=False):
 class WorkbenchExecutionResponse(TypedDict, total=False):
     approvalRequestId: str
     executed: bool
-    nextAction: Literal["wait_for_approval"]
+    nextAction: Literal["wait_for_approval", "resume_saved_work"]
     workbenchSession: WorkbenchSession
     executionKind: WorkbenchExecutionKind
     executionId: str
@@ -583,7 +635,7 @@ def _wait_for_workbench_response(
     execution_id = accepted.get("executionId")
     execution_kind = accepted.get("executionKind")
     if (
-        accepted.get("status") == "waiting_for_approval"
+        accepted.get("status") in ("waiting_for_approval", "waiting_saved", "waiting_ready")
         or not isinstance(session_id, str)
         or not isinstance(execution_id, str)
         or execution_kind not in {"workbench_code", "workbench_bash"}
@@ -598,13 +650,15 @@ def _wait_for_workbench_response(
             {"waitTimeoutMs": 10_000},
         ))
         execution = waited.get("execution")
-        if not isinstance(execution, dict) or execution.get("status") not in {
+        if not isinstance(execution, dict) or (execution.get("nextAction") != "wait_for_approval" and execution.get("status") not in {
             "waiting_for_approval",
+            "waiting_saved",
+            "waiting_ready",
             "completed",
             "failed",
             "cancelled",
             "timed_out",
-        }:
+        }):
             continue
         response: WorkbenchExecutionResponse = {
             **accepted,
@@ -616,9 +670,9 @@ def _wait_for_workbench_response(
         }
         if isinstance(execution.get("approvalRequestId"), str):
             response["approvalRequestId"] = execution["approvalRequestId"]
-        if execution.get("status") == "waiting_for_approval":
+        if execution.get("status") in ("waiting_for_approval", "waiting_saved", "waiting_ready") or execution.get("nextAction") == "wait_for_approval":
             response["executed"] = False
-            response["nextAction"] = "wait_for_approval"
+            response["nextAction"] = "wait_for_approval" if execution.get("status") == "waiting_for_approval" or execution.get("nextAction") == "wait_for_approval" else "resume_saved_work"
         output_mode = execution.get("outputMode")
         if output_mode in {"inline", "preview", "events", "artifact"}:
             response["outputMode"] = cast(WorkbenchOutputMode, output_mode)
@@ -996,6 +1050,12 @@ class SessionSandbox:
         self.runs = WorkbenchRuns(self)
         self.artifacts = WorkbenchArtifacts(self)
 
+    def resume(self, execution_id: str, expected_wait_revision: int, checkpoint_id: str) -> WorkbenchExecutionResponse:
+        return self.client.request("POST", "/v1/workbench/resume", json_body={
+            "sessionId": self.platform_session_id, "executionId": execution_id,
+            "expectedWaitRevision": expected_wait_revision, "checkpointId": checkpoint_id,
+        })
+
     def use(
         self,
         workbench_session_id: str | None = None,
@@ -1084,6 +1144,17 @@ class WorkbenchResource:
             return _wait_for_workbench_response(self.client, body, response)
         return response
 
+    def resume(self, session_id: str, execution_id: str, *, expected_wait_revision: int, checkpoint_id: str):
+        return self.client.request("POST", "/v1/workbench/resume", json_body={
+            "sessionId": session_id, "executionId": execution_id,
+            "expectedWaitRevision": expected_wait_revision, "checkpointId": checkpoint_id,
+        })
+
+    def compute_status(self, session_id: str, workbench_session_id: str) -> WorkbenchComputeStatus:
+        return cast(WorkbenchComputeStatus, self.client.request("POST", "/v1/workbench/run", json_body={
+            "sessionId": session_id, "workbenchSessionId": workbench_session_id, "operation": "compute_status",
+        }))
+
     def destroy(self, session_id: str, workbench_session_id: str):
         return self.run({
             "sessionId": session_id,

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

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

{stacklink_sdk-0.3.14 → stacklink_sdk-0.3.19}/tests/test_client.py

@@ -63,6 +63,24 @@ def stalled_stream_server(*, final_result=False, execution_page=False):
 
 
 class StacklinkClientTests(unittest.TestCase):
+    def test_bot_avatar_recipe_is_preserved_for_sync_and_async_create(self):
+        recipe = {"version": 1, "style": "clay", "seed": "Sales assistant", "tone": "mint"}
+        payloads = []
+        def respond(request):
+            payload = json.loads(request.content)
+            payloads.append(payload)
+            return httpx.Response(200, json={"id": "bot", "identity": {"avatar": payload["avatar"], "pictureUrl": "https://example.test/avatar.png"}})
+        with httpx.Client(transport=httpx.MockTransport(respond)) as http:
+            client = Stacklink(api_key="test", base_url="https://example.test", http_client=http)
+            self.assertEqual(client.bots.create("Sales", avatar=recipe)["identity"]["avatar"], recipe)
+        async def check_async():
+            async with httpx.AsyncClient(transport=httpx.MockTransport(respond)) as http:
+                client = AsyncStacklink(api_key="test", base_url="https://example.test", http_client=http)
+                result = await client.bots.create("Sales", avatar=recipe)
+                self.assertEqual(result["identity"]["avatar"], recipe)
+        asyncio.run(check_async())
+        self.assertEqual([item["avatar"] for item in payloads], [recipe, recipe])
+
     def test_customer_grant_management_uses_session_identity(self):
         calls = []
         def transport(method, path, headers, body, query, timeout):
@@ -99,6 +117,30 @@ class StacklinkClientTests(unittest.TestCase):
                 self.assertFalse(result["executed"])
                 self.assertEqual(len(calls), 2 if admission_status == "queued" else 1)
 
+    def test_saved_wait_returns_to_caller_and_preserves_resume_identity(self):
+        for status in ("waiting_saved", "waiting_ready", "resuming"):
+            calls = []
+            state = {"id": "execution-1", "executionKind": "workbench_code", "status": status,
+                     "waitRevision": 2, "waitState": {"checkpointId": "checkpoint-1"}}
+            if status == "resuming":
+                state.update({"nextAction": "wait_for_approval", "approvalRequestId": "approval-2"})
+            def transport(method, path, headers, body, query, timeout):
+                calls.append((path, body))
+                if path == "/v1/workbench/run":
+                    return 202, {}, {"executionId": state["id"], "executionKind": "workbench_code", "status": "queued"}
+                if path.endswith("/wait") and len(calls) == 2:
+                    return 200, {}, {"execution": state}
+                if path == "/v1/workbench/resume":
+                    return 202, {}, {**state, "status": "resuming"}
+                raise AssertionError(f"Unexpected saved wait polling: {path}")
+            client = Stacklink(api_key="ppk_test", transport=transport)
+            result = client.workbench.run({"sessionId": "session-1", "operation": "run_code", "code": "print(1)"})
+            self.assertEqual(result["status"], status)
+            self.assertEqual(result["nextAction"], "wait_for_approval" if status == "resuming" else "resume_saved_work")
+            self.assertEqual(len(calls), 2)
+            client.workbench.resume("session-1", "execution-1", expected_wait_revision=2, checkpoint_id="checkpoint-1")
+            self.assertEqual(calls[-1], ("/v1/workbench/resume", {"sessionId": "session-1", "executionId": "execution-1", "expectedWaitRevision": 2, "checkpointId": "checkpoint-1"}))
+
     def test_approvals_observe_reconnect_and_customer_identity(self):
         calls = []
         def transport(method, path, headers, body, query, timeout):