getstack 1.2.0__tar.gz → 1.3.0__tar.gz

{getstack-1.2.0 → getstack-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: getstack
-Version: 1.2.0
+Version: 1.3.0
 Summary: Python SDK for STACK — trust infrastructure for AI agents
 Project-URL: Homepage, https://getstack.run
 Project-URL: Documentation, https://getstack.run/docs/sdk

{getstack-1.2.0 → getstack-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "getstack"
-version = "1.2.0"
+version = "1.3.0"
 description = "Python SDK for STACK — trust infrastructure for AI agents"
 readme = "README.md"
 license = "MIT"

{getstack-1.2.0 → getstack-1.3.0}/src/getstack/__init__.py

@@ -47,7 +47,8 @@ from .dropoffs import DropoffService
 from .reviews import ReviewService
 from .notifications import NotificationService
 from .audit import AuditService
-from .proxy import ProxyService as ProxySvc, ProxyResponse
+from .proxy import ProxyOperation, ProxyService as ProxySvc, ProxyResponse
+from ._authority_request import create_authority_request_id
 from .scan import ScanService
 from .usage import UsageService
 from .security_events import SecurityEventService as SecurityEventSvc
@@ -169,6 +170,8 @@ __all__ = [
     "Mission",
     "ToolCall",
     "ProxyResponse",
+    "create_authority_request_id",
+    "ProxyOperation",
     "Skill",
     "SkillInvocation",
     "SkillRequest",

{getstack-1.2.0 → getstack-1.3.0}/src/getstack/_async/passports.py

@@ -11,7 +11,7 @@ from __future__ import annotations
 
 import asyncio
 from contextlib import asynccontextmanager
-from typing import Any, AsyncGenerator
+from typing import Any, AsyncGenerator, Awaitable, Callable
 
 from ..client import AsyncHttpClient
 from ..passports import _parse_duration, _to_passport
@@ -85,6 +85,8 @@ class AsyncMission:
         body: Any = None,
         query: dict[str, str] | None = None,
         approval_id: str | None = None,
+        authority_request_id: str | None = None,
+        on_operation_id: Callable[[str], None | Awaitable[None]] | None = None,
         _proxy_service: AsyncProxyService | None = None,
     ) -> ProxyResponse:
         """Async proxy call using this mission's passport.
@@ -103,6 +105,8 @@ class AsyncMission:
             headers=headers, body=body, query=query,
             passport_token=self.token,
             approval_id=approval_id,
+            authority_request_id=authority_request_id,
+            on_operation_id=on_operation_id,
         )
         self.log(service, method, url)
         return resp

{getstack-1.2.0 → getstack-1.3.0}/src/getstack/_async/proxy.py

@@ -2,11 +2,12 @@
 
 from __future__ import annotations
 
-from typing import Any
+import inspect
+from typing import Any, Awaitable, Callable
 
-from .._authority_request import authority_request_headers
+from .._authority_request import authority_request_headers, create_authority_request_id
 from ..client import AsyncHttpClient
-from ..proxy import ProxyResponse
+from ..proxy import ProxyOperation, ProxyResponse
 
 
 class AsyncProxyService:
@@ -25,13 +26,22 @@ class AsyncProxyService:
         passport_token: str | None = None,
         approval_id: str | None = None,
         authority_request_id: str | None = None,
+        on_operation_id: Callable[[str], None | Awaitable[None]] | None = None,
     ) -> ProxyResponse:
+        operation_id = authority_request_id
+        if operation_id is None and method.upper() != "GET":
+            operation_id = create_authority_request_id()
+        if operation_id is not None and on_operation_id is not None:
+            persisted = on_operation_id(operation_id)
+            if inspect.isawaitable(persisted):
+                await persisted
+
         extra_headers: dict[str, str] = {}
         if passport_token:
             extra_headers["X-Passport-Token"] = passport_token
         if approval_id:
             extra_headers["X-Intent-Approval-Id"] = approval_id
-        extra_headers.update(authority_request_headers(authority_request_id))
+        extra_headers.update(authority_request_headers(operation_id))
 
         payload: dict[str, Any] = {
             "service": service,
@@ -45,16 +55,37 @@ class AsyncProxyService:
         if query:
             payload["query"] = query
 
-        data = await self._client.request(
-            "POST",
-            "/v1/proxy",
-            json=payload,
-            extra_headers=extra_headers if extra_headers else None,
-        )
+        try:
+            data = await self._client.request(
+                "POST",
+                "/v1/proxy",
+                json=payload,
+                extra_headers=extra_headers if extra_headers else None,
+            )
+        except Exception as error:
+            if operation_id is not None:
+                setattr(error, "operation_id", operation_id)
+            raise
         return ProxyResponse(
             status=data.get("status", 0),
             headers=data.get("headers", {}),
             body=data.get("body"),
+            operation_id=operation_id,
+        )
+
+    async def get_operation(
+        self,
+        operation_id: str,
+        *,
+        passport_token: str,
+        include_response: bool = False,
+    ) -> ProxyOperation:
+        authority_request_headers(operation_id)
+        return await self._client.request(
+            "POST",
+            "/v1/proxy/operations/get",
+            json={"operation_id": operation_id, "include_response": include_response},
+            extra_headers={"X-Passport-Token": passport_token},
         )
 
     async def get(self, service: str, url: str, **kwargs: Any) -> ProxyResponse:

{getstack-1.2.0 → getstack-1.3.0}/src/getstack/_authority_request.py

@@ -3,11 +3,17 @@
 from __future__ import annotations
 
 import re
+import secrets
 
 AUTHORITY_REQUEST_ID_HEADER = "X-STACK-Authority-Request-Id"
 _AUTHORITY_REQUEST_ID_PATTERN = re.compile(r"^[A-Za-z0-9_-]{22,256}$")
 
 
+def create_authority_request_id() -> str:
+    """Create a cryptographically random 24-character base64url handle."""
+    return secrets.token_urlsafe(18)
+
+
 def authority_request_headers(authority_request_id: str | None) -> dict[str, str]:
     """Build the authority request header after validating its wire format."""
     if authority_request_id is None:

{getstack-1.2.0 → getstack-1.3.0}/src/getstack/passports.py

@@ -6,7 +6,7 @@ import re
 import time
 import threading
 from contextlib import contextmanager
-from typing import Any, Generator
+from typing import Any, Callable, Generator
 
 from .client import HttpClient
 from .proxy import ProxyService, ProxyResponse
@@ -101,6 +101,8 @@ class Mission:
         body: Any = None,
         query: dict[str, str] | None = None,
         approval_id: str | None = None,
+        authority_request_id: str | None = None,
+        on_operation_id: Callable[[str], None] | None = None,
         _proxy_service: ProxyService | None = None,
     ) -> ProxyResponse:
         """Send a request through STACK's credential proxy using this mission's passport.
@@ -117,6 +119,10 @@ class Mission:
                 is in enforced mode. Pass the approval id returned
                 from ``final.id`` after ``submit_and_wait`` reports
                 ``status='approved'``.
+            authority_request_id: Stable operation identifier to reuse only
+                for an unchanged retry.
+            on_operation_id: Called before network I/O so a durable job can
+                persist the generated operation identifier.
             _proxy_service: ProxyService instance (falls back to self._proxy).
         """
         ps = _proxy_service or getattr(self, "_proxy", None)
@@ -129,6 +135,8 @@ class Mission:
             headers=headers, body=body, query=query,
             passport_token=self.token,
             approval_id=approval_id,
+            authority_request_id=authority_request_id,
+            on_operation_id=on_operation_id,
         )
         self.log(service, method, url)
         return resp

{getstack-1.2.0 → getstack-1.3.0}/src/getstack/proxy.py

@@ -2,21 +2,28 @@
 
 from __future__ import annotations
 
-from typing import Any
+from typing import Any, Callable, Literal, TypedDict
 
-from ._authority_request import authority_request_headers
+from ._authority_request import authority_request_headers, create_authority_request_id
 from .client import HttpClient
 
 
 class ProxyResponse:
     """Response from a proxied request."""
 
-    __slots__ = ("status", "headers", "body")
+    __slots__ = ("status", "headers", "body", "operation_id")
 
-    def __init__(self, status: int, headers: dict[str, str], body: Any):
+    def __init__(
+        self,
+        status: int,
+        headers: dict[str, str],
+        body: Any,
+        operation_id: str | None = None,
+    ):
         self.status = status
         self.headers = headers
         self.body = body
+        self.operation_id = operation_id
 
     def ok(self) -> bool:
         return 200 <= self.status < 400
@@ -28,6 +35,25 @@ class ProxyResponse:
         return f"ProxyResponse(status={self.status})"
 
 
+class ProxyOperation(TypedDict, total=False):
+    """Durable delivery, replay, and accounting state for one proxy write."""
+
+    operation_id: str
+    delivery_state: Literal["admitted", "dispatching", "response_received", "outcome_unknown"]
+    replay_state: Literal["none", "screening", "available", "expired", "erased"]
+    accounting_state: Literal["reserved", "committed", "released"]
+    provider: str
+    method: Literal["POST", "PUT", "PATCH", "DELETE"]
+    created_at: str
+    dispatched_at: str | None
+    response_received_at: str | None
+    provider_outcome: Literal[
+        "not_required", "pending", "confirmed", "not_found", "contradictory", "expired"
+    ]
+    provider_status: Literal["pending", "requires_action", "succeeded", "failed", "canceled"] | None
+    response: dict[str, Any]
+
+
 class ProxyService:
     def __init__(self, client: HttpClient):
         self._client = client
@@ -44,6 +70,7 @@ class ProxyService:
         passport_token: str | None = None,
         approval_id: str | None = None,
         authority_request_id: str | None = None,
+        on_operation_id: Callable[[str], None] | None = None,
     ) -> ProxyResponse:
         """Send a request through STACK's credential proxy.
 
@@ -59,14 +86,24 @@ class ProxyService:
                 (Sub-chunk 2.4). Required when the calling passport is
                 in enforced mode. Sent as ``X-Intent-Approval-Id``.
             authority_request_id: Stable, high-entropy request identifier for
-                authority-bound replay and idempotency checks.
+                operation recovery. Non-GET calls generate one before network
+                I/O when omitted; persist ``response.operation_id`` and reuse
+                it only for an unchanged retry.
+            on_operation_id: Called before network I/O. Durable job runners
+                should persist the supplied identifier here.
         """
+        operation_id = authority_request_id
+        if operation_id is None and method.upper() != "GET":
+            operation_id = create_authority_request_id()
+        if operation_id is not None and on_operation_id is not None:
+            on_operation_id(operation_id)
+
         extra_headers: dict[str, str] = {}
         if passport_token:
             extra_headers["X-Passport-Token"] = passport_token
         if approval_id:
             extra_headers["X-Intent-Approval-Id"] = approval_id
-        extra_headers.update(authority_request_headers(authority_request_id))
+        extra_headers.update(authority_request_headers(operation_id))
 
         payload: dict[str, Any] = {
             "service": service,
@@ -80,16 +117,38 @@ class ProxyService:
         if query:
             payload["query"] = query
 
-        data = self._client.request(
-            "POST",
-            "/v1/proxy",
-            json=payload,
-            extra_headers=extra_headers if extra_headers else None,
-        )
+        try:
+            data = self._client.request(
+                "POST",
+                "/v1/proxy",
+                json=payload,
+                extra_headers=extra_headers if extra_headers else None,
+            )
+        except Exception as error:
+            if operation_id is not None:
+                setattr(error, "operation_id", operation_id)
+            raise
         return ProxyResponse(
             status=data.get("status", 0),
             headers=data.get("headers", {}),
             body=data.get("body"),
+            operation_id=operation_id,
+        )
+
+    def get_operation(
+        self,
+        operation_id: str,
+        *,
+        passport_token: str,
+        include_response: bool = False,
+    ) -> ProxyOperation:
+        """Read operation status and optionally its stored screened response."""
+        authority_request_headers(operation_id)
+        return self._client.request(
+            "POST",
+            "/v1/proxy/operations/get",
+            json={"operation_id": operation_id, "include_response": include_response},
+            extra_headers={"X-Passport-Token": passport_token},
         )
 
     def get(self, service: str, url: str, **kwargs) -> ProxyResponse:

{getstack-1.2.0 → getstack-1.3.0}/tests/test_authority.py

@@ -17,10 +17,12 @@ sys.path.insert(0, str(Path(__file__).resolve().parents[1] / "src"))
 from getstack import AsyncStack, Stack  # noqa: E402
 from getstack._async.authority import AsyncAuthorityService  # noqa: E402
 from getstack._async.llm import AsyncLlmService  # noqa: E402
+from getstack._async.passports import AsyncMission  # noqa: E402
 from getstack._async.proxy import AsyncProxyService  # noqa: E402
 from getstack._async.skills import AsyncSkillService  # noqa: E402
 from getstack.authority import AuthorityService  # noqa: E402
 from getstack.llm import LlmService  # noqa: E402
+from getstack.passports import Mission  # noqa: E402
 from getstack.proxy import ProxyService  # noqa: E402
 from getstack.skills import SkillService  # noqa: E402
 
@@ -250,6 +252,69 @@ def test_runtime_calls_thread_authority_request_id_sync():
         assert call["extra_headers"]["X-STACK-Authority-Request-Id"] == request_id
 
 
+def test_proxy_generates_exposes_and_recovers_operation_id_sync():
+    persisted: list[str] = []
+
+    class PersistenceCheckingClient(_SyncCaptureClient):
+        def request(self, *args: Any, **kwargs: Any):
+            assert persisted
+            return super().request(*args, **kwargs)
+
+    client = PersistenceCheckingClient()
+    response = ProxyService(client).request(  # type: ignore[arg-type]
+        "stripe", "https://api.stripe.test/v1/refunds", method="POST",
+        passport_token="passport", on_operation_id=persisted.append,
+    )
+    assert response.operation_id is not None
+    assert len(response.operation_id) >= 22
+    assert client.calls[0]["extra_headers"]["X-STACK-Authority-Request-Id"] == response.operation_id
+
+    result = ProxyService(client).get_operation(  # type: ignore[arg-type]
+        response.operation_id, passport_token="passport", include_response=True
+    )
+    assert result == {"ok": True}
+    assert client.calls[1]["path"] == "/v1/proxy/operations/get"
+    assert client.calls[1]["json"] == {
+        "operation_id": response.operation_id,
+        "include_response": True,
+    }
+    assert client.calls[1]["extra_headers"] == {"X-Passport-Token": "passport"}
+
+
+def test_mission_proxy_persists_operation_id_before_sync_request():
+    persisted: list[str] = []
+    client = _SyncCaptureClient()
+    mission = Mission(  # type: ignore[arg-type]
+        SimpleNamespace(), "agt_1", "Create issue", ["github"]
+    )
+    mission.passport = SimpleNamespace(token="passport")  # type: ignore[assignment]
+
+    response = mission.proxy(
+        "github",
+        "https://api.github.test/repos/acme/example/issues",
+        method="POST",
+        body={"title": "Typo"},
+        on_operation_id=persisted.append,
+        _proxy_service=ProxyService(client),  # type: ignore[arg-type]
+    )
+
+    assert persisted == [response.operation_id]
+    assert client.calls[0]["extra_headers"]["X-STACK-Authority-Request-Id"] == response.operation_id
+
+
+def test_proxy_preserves_generated_operation_id_on_error_sync():
+    class FailingClient(_SyncCaptureClient):
+        def request(self, *args: Any, **kwargs: Any):
+            raise RuntimeError("response lost")
+
+    with pytest.raises(RuntimeError) as raised:
+        ProxyService(FailingClient()).request(  # type: ignore[arg-type]
+            "stripe", "https://api.stripe.test/v1/refunds", method="POST",
+            passport_token="passport",
+        )
+    assert len(raised.value.operation_id) >= 22  # type: ignore[attr-defined]
+
+
 def test_runtime_calls_thread_authority_request_id_async():
     async def run() -> None:
         request_id = "0123456789abcdefghijkl"
@@ -280,6 +345,81 @@ def test_runtime_calls_thread_authority_request_id_async():
     asyncio.run(run())
 
 
+def test_proxy_generates_exposes_and_recovers_operation_id_async():
+    async def run() -> None:
+        persisted: list[str] = []
+
+        class PersistenceCheckingClient(_AsyncCaptureClient):
+            async def request(self, *args: Any, **kwargs: Any):
+                assert persisted
+                return await super().request(*args, **kwargs)
+
+        async def persist(operation_id: str) -> None:
+            await asyncio.sleep(0)
+            persisted.append(operation_id)
+
+        client = PersistenceCheckingClient()
+        response = await AsyncProxyService(client).request(  # type: ignore[arg-type]
+            "stripe", "https://api.stripe.test/v1/refunds", method="POST",
+            passport_token="passport", on_operation_id=persist,
+        )
+        assert response.operation_id is not None
+        assert len(response.operation_id) >= 22
+        assert client.calls[0]["extra_headers"]["X-STACK-Authority-Request-Id"] == response.operation_id
+
+        result = await AsyncProxyService(client).get_operation(  # type: ignore[arg-type]
+            response.operation_id, passport_token="passport", include_response=True
+        )
+        assert result == {"ok": True}
+        assert client.calls[1]["path"] == "/v1/proxy/operations/get"
+        assert client.calls[1]["json"]["operation_id"] == response.operation_id
+
+    asyncio.run(run())
+
+
+def test_async_mission_proxy_persists_operation_id_before_request():
+    async def run() -> None:
+        persisted: list[str] = []
+        client = _AsyncCaptureClient()
+        mission = AsyncMission(  # type: ignore[arg-type]
+            SimpleNamespace(), "agt_1", "Create issue", ["github"]
+        )
+        mission.passport = SimpleNamespace(token="passport")  # type: ignore[assignment]
+
+        async def persist(operation_id: str) -> None:
+            persisted.append(operation_id)
+
+        response = await mission.proxy(
+            "github",
+            "https://api.github.test/repos/acme/example/issues",
+            method="POST",
+            body={"title": "Typo"},
+            on_operation_id=persist,
+            _proxy_service=AsyncProxyService(client),  # type: ignore[arg-type]
+        )
+
+        assert persisted == [response.operation_id]
+        assert client.calls[0]["extra_headers"]["X-STACK-Authority-Request-Id"] == response.operation_id
+
+    asyncio.run(run())
+
+
+def test_proxy_preserves_generated_operation_id_on_error_async():
+    class FailingClient(_AsyncCaptureClient):
+        async def request(self, *args: Any, **kwargs: Any):
+            raise RuntimeError("response lost")
+
+    async def run() -> None:
+        with pytest.raises(RuntimeError) as raised:
+            await AsyncProxyService(FailingClient()).request(  # type: ignore[arg-type]
+                "stripe", "https://api.stripe.test/v1/refunds", method="POST",
+                passport_token="passport",
+            )
+        assert len(raised.value.operation_id) >= 22  # type: ignore[attr-defined]
+
+    asyncio.run(run())
+
+
 def test_runtime_calls_reject_malformed_authority_request_id_sync():
     client = _SyncCaptureClient()