getstack 1.4.0__tar.gz → 3.0.0__tar.gz

{getstack-1.4.0 → getstack-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: getstack
-Version: 1.4.0
+Version: 3.0.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
@@ -125,8 +125,15 @@ stack.agents.list()
 stack.agents.update(agent_id, **fields)
 stack.agents.unblock(agent_id)
 
+# Missions (every passport is issued for exactly one Mission)
+stack.missions.open(intent_summary, agent_id=None, intent_services=None, ...)
+stack.missions.start(agent_id=agent_id, mission={"intent_summary": "..."}, passport=None)
+stack.missions.complete(mission_id)  # also revokes the Mission's passports
+stack.missions.revoke(mission_id, reason="operator_initiated_clean")
+
 # Passports
-stack.passports.issue(agent_id, intent=None, services=None, ...)
+stack.passports.issue(agent_id, mission_ids=[mission_id], intent=None, services=None, ...)
+stack.passports.mission(agent_id, intent, services, ...)  # context manager: Mission + passport, closed on exit
 stack.passports.verify(token)
 stack.passports.revoke(jti, reason=None)
 stack.passports.checkpoint(jti, services_used, actions_count, ...)
@@ -148,9 +155,9 @@ stack.reviews.list(status="flagged")
 stack.reviews.decide(checkout_id, decision, notes=None, block_future=False)
 
 # Drop-offs
-stack.dropoffs.create(from_agent_id, to_agent_id, schema, ...)
-stack.dropoffs.deposit(dropoff_id, data, agent_id)
-stack.dropoffs.collect(dropoff_id, agent_id)
+stack.dropoffs.create(from_agent_id, to_agent_id, schema, ..., passport_token=None)
+stack.dropoffs.deposit(dropoff_id, data, agent_id, passport_token=None)
+stack.dropoffs.collect(dropoff_id, agent_id, passport_token=None)
 
 # Notifications
 stack.notifications.list()

{getstack-1.4.0 → getstack-3.0.0}/README.md

@@ -98,8 +98,15 @@ stack.agents.list()
 stack.agents.update(agent_id, **fields)
 stack.agents.unblock(agent_id)
 
+# Missions (every passport is issued for exactly one Mission)
+stack.missions.open(intent_summary, agent_id=None, intent_services=None, ...)
+stack.missions.start(agent_id=agent_id, mission={"intent_summary": "..."}, passport=None)
+stack.missions.complete(mission_id)  # also revokes the Mission's passports
+stack.missions.revoke(mission_id, reason="operator_initiated_clean")
+
 # Passports
-stack.passports.issue(agent_id, intent=None, services=None, ...)
+stack.passports.issue(agent_id, mission_ids=[mission_id], intent=None, services=None, ...)
+stack.passports.mission(agent_id, intent, services, ...)  # context manager: Mission + passport, closed on exit
 stack.passports.verify(token)
 stack.passports.revoke(jti, reason=None)
 stack.passports.checkpoint(jti, services_used, actions_count, ...)
@@ -121,9 +128,9 @@ stack.reviews.list(status="flagged")
 stack.reviews.decide(checkout_id, decision, notes=None, block_future=False)
 
 # Drop-offs
-stack.dropoffs.create(from_agent_id, to_agent_id, schema, ...)
-stack.dropoffs.deposit(dropoff_id, data, agent_id)
-stack.dropoffs.collect(dropoff_id, agent_id)
+stack.dropoffs.create(from_agent_id, to_agent_id, schema, ..., passport_token=None)
+stack.dropoffs.deposit(dropoff_id, data, agent_id, passport_token=None)
+stack.dropoffs.collect(dropoff_id, agent_id, passport_token=None)
 
 # Notifications
 stack.notifications.list()

{getstack-1.4.0 → getstack-3.0.0}/pyproject.toml

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

{getstack-1.4.0 → getstack-3.0.0}/src/getstack/__init__.py

@@ -52,7 +52,7 @@ from .auth import ApiKeyAuth, SessionAuth, OAuthAuth, CredentialsFileAuth
 from .agent_auth import AgentKeypairAuth
 from .client import HttpClient, AsyncHttpClient, DEFAULT_BASE_URL
 from .agents import AgentService
-from .passports import PassportService, Mission
+from .passports import PassportService, Mission, _require_one_mission
 from .credentials import CredentialService
 from .services import ServiceService
 from .dropoffs import DropoffService
@@ -119,6 +119,7 @@ from .errors import (
     ForbiddenError,
     ValidationError,
     PassportBlockedError,
+    MissionEndedError,
 )
 
 try:
@@ -222,6 +223,7 @@ __all__ = [
     "ForbiddenError",
     "ValidationError",
     "PassportBlockedError",
+    "MissionEndedError",
 ]
 
 
@@ -301,18 +303,25 @@ class Stack:
         ttl_seconds: int | None = None,
         accountability_mode: str | None = None,
         authority_binding_ids: list[str] | None = None,
+        mission_ids: list[str] | None = None,
         **kwargs: Any,
     ) -> PassportSession:
         """Phase 5.2.6 — issue a passport and return a PassportSession
         that holds the token + auto-refreshes ~60s before expiry. Pass
         the returned session to LLM calls instead of threading a raw
-        token per call::
+        token per call. ``mission_ids`` must hold exactly one Mission id;
+        once that Mission ends, refresh raises ``MissionEndedError``::
 
-            session = stack.issue_passport(agent_id="agt_x", services=[...])
+            mission = stack.missions.open("Answer support tickets", agent_id="agt_x")
+            session = stack.issue_passport(agent_id="agt_x", mission_ids=[mission["mission_id"]])
             for i in range(1000):
                 stack.llm.anthropic.messages.create(body, passport=session)
         """
-        issue_input: dict[str, Any] = {"agent_id": agent_id, **kwargs}
+        issue_input: dict[str, Any] = {
+            "agent_id": agent_id,
+            **kwargs,
+            "mission_ids": _require_one_mission(mission_ids),
+        }
         if services is not None: issue_input["services"] = services
         if intents is not None: issue_input["intents"] = intents
         if ttl_seconds is not None: issue_input["ttl_seconds"] = ttl_seconds
@@ -483,10 +492,16 @@ class AsyncStack:
         ttl_seconds: int | None = None,
         accountability_mode: str | None = None,
         authority_binding_ids: list[str] | None = None,
+        mission_ids: list[str] | None = None,
         **kwargs: Any,
     ):
-        """Phase 5.2.6 — async passport issue + session wrapper."""
-        issue_input: dict[str, Any] = {"agent_id": agent_id, **kwargs}
+        """Phase 5.2.6 — async passport issue + session wrapper.
+        ``mission_ids`` must hold exactly one Mission id."""
+        issue_input: dict[str, Any] = {
+            "agent_id": agent_id,
+            **kwargs,
+            "mission_ids": _require_one_mission(mission_ids),
+        }
         if services is not None: issue_input["services"] = services
         if intents is not None: issue_input["intents"] = intents
         if ttl_seconds is not None: issue_input["ttl_seconds"] = ttl_seconds

{getstack-1.4.0 → getstack-3.0.0}/src/getstack/_async/dropoffs.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from typing import Any
 
 from ..client import AsyncHttpClient
+from ..dropoffs import _passport_header
 
 
 class AsyncDropoffService:
@@ -18,7 +19,9 @@ class AsyncDropoffService:
         schema: dict[str, Any],
         ttl_seconds: int | None = None,
         on_expire: str | None = None,
+        passport_token: str | None = None,
     ) -> dict[str, Any]:
+        """Create a drop-off. An agent caller passes the producer's Mission Passport as passport_token."""
         body: dict[str, Any] = {
             "from_agent": from_agent_id,
             "to_agent": to_agent_id,
@@ -28,7 +31,7 @@ class AsyncDropoffService:
             body["ttl_seconds"] = ttl_seconds
         if on_expire:
             body["on_expire"] = on_expire
-        return await self._client.post("/v1/dropoffs", json=body)
+        return await self._client.post("/v1/dropoffs", json=body, extra_headers=_passport_header(passport_token))
 
     async def deposit(
         self,
@@ -37,7 +40,9 @@ class AsyncDropoffService:
         agent_id: str,
         passport_jti: str | None = None,
         mission_id: str | None = None,
+        passport_token: str | None = None,
     ) -> dict[str, Any]:
+        """Deposit as the producer. An agent caller passes its Mission Passport as passport_token (or passport_jti)."""
         body: dict[str, Any] = {"agent_id": agent_id, "payload": data}
         if passport_jti is not None:
             body["passport_jti"] = passport_jti
@@ -46,12 +51,15 @@ class AsyncDropoffService:
         return await self._client.post(
             f"/v1/dropoffs/{dropoff_id}/deposit",
             json=body,
+            extra_headers=_passport_header(passport_token),
         )
 
-    async def collect(self, dropoff_id: str, agent_id: str) -> dict[str, Any]:
+    async def collect(self, dropoff_id: str, agent_id: str, passport_token: str | None = None) -> dict[str, Any]:
+        """Collect as the consumer. An agent caller passes its Mission Passport as passport_token."""
         return await self._client.post(
             f"/v1/dropoffs/{dropoff_id}/collect",
             json={"agent_id": agent_id},
+            extra_headers=_passport_header(passport_token),
         )
 
     async def expire(self, dropoff_id: str) -> dict[str, Any]:

{getstack-1.4.0 → getstack-3.0.0}/src/getstack/_async/missions.py

@@ -1,4 +1,8 @@
-"""Async mirror of MissionsService. Same surface, async/await."""
+"""Async mirror of MissionsService. Same surface, async/await.
+
+Completing or revoking a Mission (any reason) revokes every passport
+bound to it.
+"""
 
 from __future__ import annotations
 
@@ -6,14 +10,26 @@ from typing import Any
 from urllib.parse import quote
 
 from ..client import AsyncHttpClient
+from ..missions import _start_body
 
 
 class AsyncMissionsService:
     def __init__(self, client: AsyncHttpClient):
         self._client = client
 
-    async def start(self, request: dict[str, Any]) -> dict[str, Any]:
-        return await self._client.request("POST", "/v1/missions/start", json=request)
+    async def start(
+        self,
+        request: dict[str, Any] | None = None,
+        *,
+        agent_id: str | None = None,
+        mission: dict[str, Any] | None = None,
+        passport: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Open a Mission and issue its passport in one call. Operator form:
+        ``await stack.missions.start(agent_id=..., mission={...}, passport={...})``.
+        Fleet form (unchanged): ``await stack.missions.start({"fleet_policy_id": ...})``."""
+        body = _start_body(request, agent_id, mission, passport)
+        return await self._client.request("POST", "/v1/missions/start", json=body)
 
     async def renew(self, mission_id: str) -> dict[str, Any]:
         return await self._client.request("POST", f"/v1/missions/{quote(mission_id, safe='')}/renew", json={})
@@ -41,8 +57,12 @@ class AsyncMissionsService:
         requested_operations: list[dict[str, Any]] | None = None,
         limits: dict[str, Any] | None = None,
         authority_binding_ids: list[str] | None = None,
+        agent_id: str | None = None,
     ) -> dict[str, Any]:
+        """Open a new mission. ``agent_id`` assigns it to that agent."""
         body: dict[str, Any] = {"intent_summary": intent_summary}
+        if agent_id is not None:
+            body["agent_id"] = agent_id
         if intent_services is not None:
             body["intent_services"] = intent_services
         if expected_counterparties is not None:

{getstack-1.4.0 → getstack-3.0.0}/src/getstack/_async/partner_tenants.py

@@ -1,4 +1,4 @@
-"""Async mirror of PartnerTenantsService (Phase 5.6)."""
+"""Async mirror of PartnerTenantsService (white-label tenants)."""
 
 from __future__ import annotations
 
@@ -6,10 +6,9 @@ from typing import Any, Literal, Optional
 from urllib.parse import quote
 
 from ..client import AsyncHttpClient
+from ..passports import _require_one_mission
 
 
-Tier = Literal["free", "developer", "pro", "business", "enterprise"]
-
 
 class AsyncPartnerTenantsService:
     def __init__(self, client: AsyncHttpClient):
@@ -18,23 +17,36 @@ class AsyncPartnerTenantsService:
     async def create(
         self,
         external_customer_id: Optional[str] = None,
-        tier: Optional[Tier] = None,
     ) -> dict[str, Any]:
+        """Create a white-label tenant.
+
+        Tenants have no plan of their own; they draw from your allowance
+        and wallet. Returns operator_id, api_key (shown once — store it),
+        external_customer_id, tier ('partner'), billing ('partner') and
+        created_at. Raises with code TENANT_LIMIT_REACHED (409) when your
+        deal caps the tenant count.
+        """
         body: dict[str, Any] = {}
         if external_customer_id is not None:
             body["external_customer_id"] = external_customer_id
-        if tier is not None:
-            body["tier"] = tier
         return await self._client.post("/v1/partner/tenants", json=body)
 
     async def list(self) -> list[dict[str, Any]]:
+        """List your tenants. Each carries ``usage`` ({period, actions}):
+        its month-to-date share of your action pool, when available."""
         res = await self._client.get("/v1/partner/tenants")
         return list(res.get("tenants", []))
 
     async def get(self, tenant_id: str) -> dict[str, Any]:
+        """Fetch one tenant (same shape as a ``list`` entry)."""
         return await self._client.get(f"/v1/partner/tenants/{tenant_id}")
 
     async def revoke(self, tenant_id: str) -> dict[str, Any]:
+        """Revoke a tenant. Cascades to its inbound webhooks and passports.
+
+        Returns {transitioned, webhooks_revoked, passports_revoked}.
+        Idempotent: a retry finishes a cascade that failed part-way.
+        """
         return await self._client.delete(f"/v1/partner/tenants/{tenant_id}")
 
     async def create_inbound_webhook(
@@ -76,8 +88,12 @@ class AsyncPartnerTenantsService:
         services: Optional[list[dict[str, Any]]] = None,
         named_intents: Optional[list[str]] = None,
         accountability_mode: Optional[Literal["enforced", "logged", "standard"]] = None,
+        mission_ids: Optional[list[str]] = None,
     ) -> dict[str, Any]:
-        body: dict[str, Any] = {"agent_id": agent_id}
+        """Issue a passport under the tenant. ``mission_ids`` must hold exactly
+        one Mission id the tenant's agent may use; anything else raises
+        ``ValueError`` before any request."""
+        body: dict[str, Any] = {"agent_id": agent_id, "mission_ids": _require_one_mission(mission_ids)}
         if ttl_seconds is not None:
             body["ttl_seconds"] = ttl_seconds
         if services is not None:
@@ -99,6 +115,8 @@ class AsyncPartnerTenantsService:
         ttl_seconds: int = 900,
         accountability_mode: Literal["enforced", "logged", "standard"] = "enforced",
         named_intents: Optional[list[str]] = None,
+        *,
+        mission_id: str,
     ) -> dict[str, Any]:
         """Phase 5.7 — convenience helper for the MIME-stamping pattern.
 
@@ -112,6 +130,7 @@ class AsyncPartnerTenantsService:
             accountability_mode=accountability_mode,
             services=services,
             named_intents=named_intents,
+            mission_ids=[mission_id],
         )
         token = issued.get("token") or issued.get("passport")
         passport_id = issued.get("passport_id") or issued.get("jti")

{getstack-1.4.0 → getstack-3.0.0}/src/getstack/_async/passport_session.py

@@ -6,6 +6,7 @@ import time
 from typing import Any
 
 from ..client import AsyncHttpClient
+from ..errors import StackError, mission_ended_error
 from ..passport_session import _decode_jwt_exp
 
 
@@ -25,13 +26,19 @@ class AsyncPassportSession:
         now_sec = int(time.time())
         if self._exp_seconds - now_sec > grace_seconds:
             return self._current_token
-        refreshed = await self._client.post(
-            "/v1/passports/refresh",
-            json={
-                "token": self._current_token,
-                "ttl_seconds": self._issue_input.get("ttl_seconds"),
-            },
-        )
+        try:
+            refreshed = await self._client.post(
+                "/v1/passports/refresh",
+                json={
+                    "token": self._current_token,
+                    "ttl_seconds": self._issue_input.get("ttl_seconds"),
+                },
+            )
+        except StackError as exc:
+            ended = mission_ended_error(exc)
+            if ended is not None:
+                raise ended from exc
+            raise
         self._current_token = refreshed["token"]
         self._exp_seconds = _decode_jwt_exp(self._current_token)
         return self._current_token