getstack 0.7.0__tar.gz → 0.8.0__tar.gz

{getstack-0.7.0 → getstack-0.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: getstack
-Version: 0.7.0
+Version: 0.8.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-0.7.0 → getstack-0.8.0}/pyproject.toml

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

{getstack-0.7.0 → getstack-0.8.0}/src/getstack/__init__.py

@@ -34,6 +34,7 @@ For async usage::
 from __future__ import annotations
 
 import os
+from typing import Any
 
 from .auth import ApiKeyAuth, SessionAuth, OAuthAuth, CredentialsFileAuth
 from .agent_auth import AgentKeypairAuth
@@ -53,6 +54,8 @@ from .skills import SkillService
 from .identity import IdentityService
 from .intents import IntentsService
 from .missions import MissionsService
+from .llm import LlmService
+from .passport_session import PassportSession
 from .types import (
     Agent,
     Passport,
@@ -218,6 +221,34 @@ class Stack:
         self.identity = IdentityService(self._client)
         self.intents = IntentsService(self._client)
         self.missions = MissionsService(self._client)
+        self.llm = LlmService(self._client)
+
+    def issue_passport(
+        self,
+        *,
+        agent_id: str,
+        services: list[dict[str, Any]] | None = None,
+        intents: list[dict[str, Any]] | None = None,
+        ttl_seconds: int | None = None,
+        accountability_mode: 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::
+
+            session = stack.issue_passport(agent_id="agt_x", services=[...])
+            for i in range(1000):
+                stack.llm.anthropic.messages.create(body, passport=session)
+        """
+        issue_input: dict[str, Any] = {"agent_id": agent_id, **kwargs}
+        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
+        if accountability_mode is not None: issue_input["accountability_mode"] = accountability_mode
+        issued = self._client.post("/v1/passports/issue", json=issue_input)
+        return PassportSession(self._client, issued, issue_input)
 
     @classmethod
     def from_session(cls, session_token: str, **kwargs) -> Stack:
@@ -329,6 +360,8 @@ class AsyncStack:
         from ._async.identity import AsyncIdentityService
         from ._async.intents import AsyncIntentsService
         from ._async.missions import AsyncMissionsService
+        from ._async.llm import AsyncLlmService
+        from ._async.passport_session import AsyncPassportSession
 
         self.agents = AsyncAgentService(self._client)
         self.passports = AsyncPassportService(self._client)
@@ -345,6 +378,29 @@ class AsyncStack:
         self.identity = AsyncIdentityService(self._client)
         self.intents = AsyncIntentsService(self._client)
         self.missions = AsyncMissionsService(self._client)
+        self.llm = AsyncLlmService(self._client)
+        # Stash for issue_passport() — Python doesn't easily expose the
+        # class binding without re-importing inside the method body.
+        self._AsyncPassportSession = AsyncPassportSession
+
+    async def issue_passport(
+        self,
+        *,
+        agent_id: str,
+        services: list[dict[str, Any]] | None = None,
+        intents: list[dict[str, Any]] | None = None,
+        ttl_seconds: int | None = None,
+        accountability_mode: str | None = None,
+        **kwargs: Any,
+    ):
+        """Phase 5.2.6 — async passport issue + session wrapper."""
+        issue_input: dict[str, Any] = {"agent_id": agent_id, **kwargs}
+        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
+        if accountability_mode is not None: issue_input["accountability_mode"] = accountability_mode
+        issued = await self._client.post("/v1/passports/issue", json=issue_input)
+        return self._AsyncPassportSession(self._client, issued, issue_input)
 
     @classmethod
     def from_session(cls, session_token: str, **kwargs) -> AsyncStack:

getstack-0.8.0/src/getstack/_async/llm.py

@@ -0,0 +1,202 @@
+"""Phase 5.2.6 — async LLM gateway service mirror."""
+
+from __future__ import annotations
+
+import json
+from typing import Any, AsyncIterator, Union
+
+from ..client import AsyncHttpClient
+from .passport_session import AsyncPassportSession
+
+AsyncPassportInput = Union[str, AsyncPassportSession]
+
+
+async def _resolve_passport(p: AsyncPassportInput) -> str:
+    if isinstance(p, str):
+        return p
+    return await p.get_token()
+
+
+async def _build_headers(
+    passport: AsyncPassportInput,
+    intent_approval_id: str | None = None,
+) -> dict[str, str]:
+    headers = {"X-Passport-Token": await _resolve_passport(passport)}
+    if intent_approval_id:
+        headers["X-Intent-Approval-Id"] = intent_approval_id
+    return headers
+
+
+async def _aiterate_sse(response: Any) -> AsyncIterator[dict[str, Any]]:
+    async for line in response.aiter_lines():
+        if not line or not line.startswith("data: "):
+            continue
+        payload = line[6:].strip()
+        if payload == "[DONE]" or payload == "":
+            continue
+        try:
+            yield json.loads(payload)
+        except json.JSONDecodeError:
+            continue
+
+
+async def _stream_provider_call(
+    client: AsyncHttpClient,
+    path: str,
+    body: dict[str, Any],
+    headers: dict[str, str],
+) -> AsyncIterator[dict[str, Any]]:
+    async with client.stream_post(path, json=body, extra_headers=headers) as response:
+        if response.status_code >= 400:
+            try:
+                body_text = (await response.aread()).decode("utf-8")
+            except Exception:
+                body_text = response.reason_phrase
+            raise RuntimeError(f"LLM streaming call failed: {response.status_code} {body_text}")
+        async for event in _aiterate_sse(response):
+            yield event
+
+
+# ── Provider sub-services ────────────────────────────────────────────
+
+
+class _AsyncAnthropicMessages:
+    def __init__(self, client: AsyncHttpClient):
+        self._client = client
+
+    async def create(
+        self,
+        body: dict[str, Any],
+        *,
+        passport: AsyncPassportInput,
+        stream: bool | None = None,
+        intent_approval_id: str | None = None,
+    ) -> Any:
+        effective_stream = bool(stream if stream is not None else body.get("stream"))
+        headers = await _build_headers(passport, intent_approval_id)
+        if effective_stream:
+            body = {**body, "stream": True}
+            return _stream_provider_call(self._client, "/v1/llm/anthropic/messages", body, headers)
+        return await self._client.post("/v1/llm/anthropic/messages", json=body, extra_headers=headers)
+
+
+class _AsyncAnthropicProvider:
+    def __init__(self, client: AsyncHttpClient):
+        self.messages = _AsyncAnthropicMessages(client)
+
+
+class _AsyncOpenAIChatCompletions:
+    def __init__(self, client: AsyncHttpClient):
+        self._client = client
+
+    async def create(
+        self,
+        body: dict[str, Any],
+        *,
+        passport: AsyncPassportInput,
+        stream: bool | None = None,
+        intent_approval_id: str | None = None,
+    ) -> Any:
+        effective_stream = bool(stream if stream is not None else body.get("stream"))
+        headers = await _build_headers(passport, intent_approval_id)
+        if effective_stream:
+            body = {**body, "stream": True}
+            return _stream_provider_call(self._client, "/v1/llm/openai/chat/completions", body, headers)
+        return await self._client.post("/v1/llm/openai/chat/completions", json=body, extra_headers=headers)
+
+
+class _AsyncOpenAIChat:
+    def __init__(self, client: AsyncHttpClient):
+        self.completions = _AsyncOpenAIChatCompletions(client)
+
+
+class _AsyncOpenAIProvider:
+    def __init__(self, client: AsyncHttpClient):
+        self.chat = _AsyncOpenAIChat(client)
+
+
+class _AsyncOpenRouterChatCompletions:
+    def __init__(self, client: AsyncHttpClient):
+        self._client = client
+
+    async def create(
+        self,
+        body: dict[str, Any],
+        *,
+        passport: AsyncPassportInput,
+        stream: bool | None = None,
+        intent_approval_id: str | None = None,
+    ) -> Any:
+        effective_stream = bool(stream if stream is not None else body.get("stream"))
+        headers = await _build_headers(passport, intent_approval_id)
+        if effective_stream:
+            body = {**body, "stream": True}
+            return _stream_provider_call(self._client, "/v1/llm/openrouter/chat/completions", body, headers)
+        return await self._client.post("/v1/llm/openrouter/chat/completions", json=body, extra_headers=headers)
+
+
+class _AsyncOpenRouterChat:
+    def __init__(self, client: AsyncHttpClient):
+        self.completions = _AsyncOpenRouterChatCompletions(client)
+
+
+class _AsyncOpenRouterProvider:
+    def __init__(self, client: AsyncHttpClient):
+        self.chat = _AsyncOpenRouterChat(client)
+
+
+class _AsyncLlmUsageQuery:
+    def __init__(self, client: AsyncHttpClient):
+        self._client = client
+
+    async def list(
+        self,
+        *,
+        limit: int | None = None,
+        cursor: str | None = None,
+        provider: str | None = None,
+        passport_jti: str | None = None,
+        mission_id: str | None = None,
+        agent_id: str | None = None,
+        since: str | None = None,
+        until: str | None = None,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {}
+        if limit is not None: params["limit"] = limit
+        if cursor is not None: params["cursor"] = cursor
+        if provider is not None: params["provider"] = provider
+        if passport_jti is not None: params["passport_jti"] = passport_jti
+        if mission_id is not None: params["mission_id"] = mission_id
+        if agent_id is not None: params["agent_id"] = agent_id
+        if since is not None: params["since"] = since
+        if until is not None: params["until"] = until
+        return await self._client.get("/v1/llm/usage", params=params)
+
+    async def summary(
+        self,
+        *,
+        provider: str | None = None,
+        passport_jti: str | None = None,
+        mission_id: str | None = None,
+        agent_id: str | None = None,
+        since: str | None = None,
+        until: str | None = None,
+        group_by_model: bool | None = None,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {}
+        if provider is not None: params["provider"] = provider
+        if passport_jti is not None: params["passport_jti"] = passport_jti
+        if mission_id is not None: params["mission_id"] = mission_id
+        if agent_id is not None: params["agent_id"] = agent_id
+        if since is not None: params["since"] = since
+        if until is not None: params["until"] = until
+        if group_by_model is not None: params["group_by_model"] = str(group_by_model).lower()
+        return await self._client.get("/v1/llm/usage/summary", params=params)
+
+
+class AsyncLlmService:
+    def __init__(self, client: AsyncHttpClient):
+        self.anthropic = _AsyncAnthropicProvider(client)
+        self.openai = _AsyncOpenAIProvider(client)
+        self.openrouter = _AsyncOpenRouterProvider(client)
+        self.usage = _AsyncLlmUsageQuery(client)

getstack-0.8.0/src/getstack/_async/passport_session.py

@@ -0,0 +1,45 @@
+"""Phase 5.2.6 — async PassportSession mirror."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from ..client import AsyncHttpClient
+from ..passport_session import _decode_jwt_exp
+
+
+class AsyncPassportSession:
+    def __init__(
+        self,
+        client: AsyncHttpClient,
+        issued: dict[str, Any],
+        issue_input: dict[str, Any],
+    ):
+        self._client = client
+        self._current_token: str = issued["token"]
+        self._exp_seconds: int = _decode_jwt_exp(self._current_token)
+        self._issue_input = issue_input
+
+    async def get_token(self, grace_seconds: int = 60) -> str:
+        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"),
+            },
+        )
+        self._current_token = refreshed["token"]
+        self._exp_seconds = _decode_jwt_exp(self._current_token)
+        return self._current_token
+
+    @property
+    def token(self) -> str:
+        return self._current_token
+
+    @property
+    def expires_at_seconds(self) -> int:
+        return self._exp_seconds

{getstack-0.7.0 → getstack-0.8.0}/src/getstack/client.py

@@ -45,8 +45,29 @@ class HttpClient:
     def get(self, path: str, params: dict[str, Any] | None = None, extra_headers: dict[str, str] | None = None) -> Any:
         return self.request("GET", path, params=params, extra_headers=extra_headers)
 
-    def post(self, path: str, json: Any = None) -> Any:
-        return self.request("POST", path, json=json)
+    def post(self, path: str, json: Any = None, extra_headers: dict[str, str] | None = None) -> Any:
+        return self.request("POST", path, json=json, extra_headers=extra_headers)
+
+    def stream_post(
+        self,
+        path: str,
+        json: Any = None,
+        extra_headers: dict[str, str] | None = None,
+    ):
+        """Phase 5.2.6 — streaming POST for the LLM gateway. Returns an
+        httpx Response context manager; caller iterates `.iter_lines()`
+        and yields parsed SSE events. The caller MUST use this as a
+        context manager (`with client.stream_post(...) as resp:`) so the
+        underlying connection releases on exit.
+        """
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "text/event-stream",
+            **self.auth.get_headers(),
+            **(extra_headers or {}),
+        }
+        url = f"{self.base_url}{path}"
+        return self._client.stream("POST", url, json=json, headers=headers)
 
     def patch(self, path: str, json: Any = None) -> Any:
         return self.request("PATCH", path, json=json)
@@ -133,5 +154,26 @@ class AsyncHttpClient:
     ) -> Any:
         return await self.request("DELETE", path, extra_headers=extra_headers)
 
+    def stream_post(
+        self,
+        path: str,
+        json: Any = None,
+        extra_headers: dict[str, str] | None = None,
+    ):
+        """Phase 5.2.6 — streaming POST for the LLM gateway (async).
+        Returns an httpx async context manager; caller uses
+        `async with client.stream_post(...) as resp:` then
+        `async for line in resp.aiter_lines():`. Connection releases on
+        exit.
+        """
+        headers = {
+            "Content-Type": "application/json",
+            "Accept": "text/event-stream",
+            **self.auth.get_headers(),
+            **(extra_headers or {}),
+        }
+        url = f"{self.base_url}{path}"
+        return self._client.stream("POST", url, json=json, headers=headers)
+
     async def close(self) -> None:
         await self._client.aclose()

getstack-0.8.0/src/getstack/llm.py

@@ -0,0 +1,265 @@
+"""Phase 5.2.6 — LLM gateway SDK service (sync).
+
+Drop-in compatible with each provider's official SDK call shape (with
+one deviation: passport per-call as a second arg, because STACK
+passport TTLs are 15 min default and would silently invalidate
+mid-session in a constructor-time pattern).
+
+Usage::
+
+    from getstack import Stack
+
+    stack = Stack(api_key="sk_live_...")
+    session = stack.issue_passport(agent_id="agt_x", services=[...])
+
+    # non-streaming
+    response = stack.llm.anthropic.messages.create(
+        body={
+            "model": "claude-opus-4-7",
+            "messages": [{"role": "user", "content": "hi"}],
+            "max_tokens": 100,
+        },
+        passport=session,
+    )
+
+    # streaming
+    for event in stack.llm.anthropic.messages.create(
+        body={...},
+        passport=session,
+        stream=True,
+    ):
+        print(event)
+
+    # observability
+    rows = stack.llm.usage.list(limit=10)
+    buckets = stack.llm.usage.summary(since="2026-05-01T00:00:00Z")
+
+Wire shapes mirror packages/shared/src/schemas/llm/usage.ts. Types
+stay loose (dicts) — same convention as missions.py.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Iterator, Union
+
+from .client import HttpClient
+from .passport_session import PassportSession
+
+PassportInput = Union[str, PassportSession]
+
+
+def _resolve_passport(p: PassportInput) -> str:
+    if isinstance(p, str):
+        return p
+    return p.get_token()
+
+
+def _build_headers(passport: PassportInput, intent_approval_id: str | None = None) -> dict[str, str]:
+    headers = {"X-Passport-Token": _resolve_passport(passport)}
+    if intent_approval_id:
+        headers["X-Intent-Approval-Id"] = intent_approval_id
+    return headers
+
+
+def _iterate_sse(response: Any) -> Iterator[dict[str, Any]]:
+    """Parse an httpx streaming Response's iter_lines into SSE events.
+    Yields each `data: { ... }` JSON payload. Skips `event:` / `id:` /
+    blank / comment lines. Terminates on `[DONE]` (OpenAI) or stream end.
+    """
+    for line in response.iter_lines():
+        if not line:
+            continue
+        # httpx returns str (text); strip the SSE `data: ` prefix.
+        if not line.startswith("data: "):
+            continue
+        payload = line[6:].strip()
+        if payload == "[DONE]" or payload == "":
+            continue
+        try:
+            yield json.loads(payload)
+        except json.JSONDecodeError:
+            continue
+
+
+# ── Provider sub-services ────────────────────────────────────────────
+
+
+class _AnthropicMessages:
+    def __init__(self, client: HttpClient):
+        self._client = client
+
+    def create(
+        self,
+        body: dict[str, Any],
+        *,
+        passport: PassportInput,
+        stream: bool | None = None,
+        intent_approval_id: str | None = None,
+    ) -> Any:
+        """If body['stream'] is True OR stream=True, returns an iterator
+        of parsed SSE events. Otherwise returns the JSON response body.
+        """
+        effective_stream = bool(stream if stream is not None else body.get("stream"))
+        if effective_stream:
+            body = {**body, "stream": True}
+            headers = _build_headers(passport, intent_approval_id)
+            return _stream_provider_call(self._client, "/v1/llm/anthropic/messages", body, headers)
+        headers = _build_headers(passport, intent_approval_id)
+        return self._client.post("/v1/llm/anthropic/messages", json=body, extra_headers=headers)
+
+
+class _AnthropicProvider:
+    def __init__(self, client: HttpClient):
+        self.messages = _AnthropicMessages(client)
+
+
+class _OpenAIChatCompletions:
+    def __init__(self, client: HttpClient):
+        self._client = client
+
+    def create(
+        self,
+        body: dict[str, Any],
+        *,
+        passport: PassportInput,
+        stream: bool | None = None,
+        intent_approval_id: str | None = None,
+    ) -> Any:
+        effective_stream = bool(stream if stream is not None else body.get("stream"))
+        if effective_stream:
+            body = {**body, "stream": True}
+            headers = _build_headers(passport, intent_approval_id)
+            return _stream_provider_call(self._client, "/v1/llm/openai/chat/completions", body, headers)
+        headers = _build_headers(passport, intent_approval_id)
+        return self._client.post("/v1/llm/openai/chat/completions", json=body, extra_headers=headers)
+
+
+class _OpenAIChat:
+    def __init__(self, client: HttpClient):
+        self.completions = _OpenAIChatCompletions(client)
+
+
+class _OpenAIProvider:
+    def __init__(self, client: HttpClient):
+        self.chat = _OpenAIChat(client)
+
+
+class _OpenRouterChatCompletions:
+    def __init__(self, client: HttpClient):
+        self._client = client
+
+    def create(
+        self,
+        body: dict[str, Any],
+        *,
+        passport: PassportInput,
+        stream: bool | None = None,
+        intent_approval_id: str | None = None,
+    ) -> Any:
+        effective_stream = bool(stream if stream is not None else body.get("stream"))
+        if effective_stream:
+            body = {**body, "stream": True}
+            headers = _build_headers(passport, intent_approval_id)
+            return _stream_provider_call(self._client, "/v1/llm/openrouter/chat/completions", body, headers)
+        headers = _build_headers(passport, intent_approval_id)
+        return self._client.post("/v1/llm/openrouter/chat/completions", json=body, extra_headers=headers)
+
+
+class _OpenRouterChat:
+    def __init__(self, client: HttpClient):
+        self.completions = _OpenRouterChatCompletions(client)
+
+
+class _OpenRouterProvider:
+    def __init__(self, client: HttpClient):
+        self.chat = _OpenRouterChat(client)
+
+
+# ── Usage query sub-service ──────────────────────────────────────────
+
+
+class _LlmUsageQuery:
+    def __init__(self, client: HttpClient):
+        self._client = client
+
+    def list(
+        self,
+        *,
+        limit: int | None = None,
+        cursor: str | None = None,
+        provider: str | None = None,
+        passport_jti: str | None = None,
+        mission_id: str | None = None,
+        agent_id: str | None = None,
+        since: str | None = None,
+        until: str | None = None,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {}
+        if limit is not None: params["limit"] = limit
+        if cursor is not None: params["cursor"] = cursor
+        if provider is not None: params["provider"] = provider
+        if passport_jti is not None: params["passport_jti"] = passport_jti
+        if mission_id is not None: params["mission_id"] = mission_id
+        if agent_id is not None: params["agent_id"] = agent_id
+        if since is not None: params["since"] = since
+        if until is not None: params["until"] = until
+        return self._client.get("/v1/llm/usage", params=params)
+
+    def summary(
+        self,
+        *,
+        provider: str | None = None,
+        passport_jti: str | None = None,
+        mission_id: str | None = None,
+        agent_id: str | None = None,
+        since: str | None = None,
+        until: str | None = None,
+        group_by_model: bool | None = None,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {}
+        if provider is not None: params["provider"] = provider
+        if passport_jti is not None: params["passport_jti"] = passport_jti
+        if mission_id is not None: params["mission_id"] = mission_id
+        if agent_id is not None: params["agent_id"] = agent_id
+        if since is not None: params["since"] = since
+        if until is not None: params["until"] = until
+        if group_by_model is not None: params["group_by_model"] = str(group_by_model).lower()
+        return self._client.get("/v1/llm/usage/summary", params=params)
+
+
+# ── Top-level service ────────────────────────────────────────────────
+
+
+class LlmService:
+    def __init__(self, client: HttpClient):
+        self.anthropic = _AnthropicProvider(client)
+        self.openai = _OpenAIProvider(client)
+        self.openrouter = _OpenRouterProvider(client)
+        self.usage = _LlmUsageQuery(client)
+
+
+# ── Streaming helper ─────────────────────────────────────────────────
+
+
+def _stream_provider_call(
+    client: HttpClient,
+    path: str,
+    body: dict[str, Any],
+    headers: dict[str, str],
+) -> Iterator[dict[str, Any]]:
+    """Open a streaming connection and yield parsed SSE events. The httpx
+    response context manager is held open across the yield — caller MUST
+    fully drain the iterator (or `break` early; the GC closes the
+    connection). Keeps the streaming UX clean: `for event in
+    stack.llm.anthropic.messages.create(..., stream=True): ...`.
+    """
+    with client.stream_post(path, json=body, extra_headers=headers) as response:
+        if response.status_code >= 400:
+            # Read the error body before yielding (no chunks to emit).
+            try:
+                body_text = response.read().decode("utf-8")
+            except Exception:
+                body_text = response.reason_phrase
+            raise RuntimeError(f"LLM streaming call failed: {response.status_code} {body_text}")
+        yield from _iterate_sse(response)

getstack-0.8.0/src/getstack/passport_session.py

@@ -0,0 +1,71 @@
+"""Phase 5.2.6 — PassportSession helper (sync).
+
+Wraps a passport token + expiry; auto-refreshes via /v1/passports/refresh
+when within `grace_seconds` of expiry. Lets operators write LLM-call
+loops without manual passport bookkeeping.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import time
+from typing import Any
+
+from .client import HttpClient
+
+
+class PassportSession:
+    def __init__(
+        self,
+        client: HttpClient,
+        issued: dict[str, Any],
+        issue_input: dict[str, Any],
+    ):
+        self._client = client
+        self._current_token: str = issued["token"]
+        self._exp_seconds: int = _decode_jwt_exp(self._current_token)
+        self._issue_input = issue_input
+
+    def get_token(self, grace_seconds: int = 60) -> str:
+        """Return the current token; auto-refresh if within grace."""
+        now_sec = int(time.time())
+        if self._exp_seconds - now_sec > grace_seconds:
+            return self._current_token
+        # Refresh — errors propagate (caller would have failed anyway with an
+        # expired token; surfacing here is the clearer signal).
+        refreshed = self._client.post(
+            "/v1/passports/refresh",
+            json={
+                "token": self._current_token,
+                "ttl_seconds": self._issue_input.get("ttl_seconds"),
+            },
+        )
+        self._current_token = refreshed["token"]
+        self._exp_seconds = _decode_jwt_exp(self._current_token)
+        return self._current_token
+
+    @property
+    def token(self) -> str:
+        """Current token (no refresh trigger)."""
+        return self._current_token
+
+    @property
+    def expires_at_seconds(self) -> int:
+        """Unix seconds since epoch."""
+        return self._exp_seconds
+
+
+def _decode_jwt_exp(token: str) -> int:
+    parts = token.split(".")
+    if len(parts) != 3:
+        raise ValueError("PassportSession: token is not a JWT (expected 3 dot-separated segments)")
+    payload_b64 = parts[1]
+    # base64url → padding
+    padded = payload_b64 + "=" * ((4 - len(payload_b64) % 4) % 4)
+    decoded = base64.urlsafe_b64decode(padded.encode("ascii"))
+    payload = json.loads(decoded)
+    exp = payload.get("exp")
+    if not isinstance(exp, int):
+        raise ValueError("PassportSession: token payload missing numeric `exp` claim")
+    return exp