getstack 0.7.0__tar.gz → 0.9.0__tar.gz

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

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

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

{getstack-0.7.0 → getstack-0.9.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
@@ -51,8 +52,12 @@ from .scan import ScanService
 from .security_events import SecurityEventService as SecurityEventSvc
 from .skills import SkillService
 from .identity import IdentityService
+from .inbound_webhooks import InboundWebhookService
 from .intents import IntentsService
 from .missions import MissionsService
+from .evidence_packs import EvidencePacksService
+from .llm import LlmService
+from .passport_session import PassportSession
 from .types import (
     Agent,
     Passport,
@@ -218,6 +223,36 @@ class Stack:
         self.identity = IdentityService(self._client)
         self.intents = IntentsService(self._client)
         self.missions = MissionsService(self._client)
+        self.evidence_packs = EvidencePacksService(self._client)
+        self.llm = LlmService(self._client)
+        self.inbound_webhooks = InboundWebhookService(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 +364,9 @@ class AsyncStack:
         from ._async.identity import AsyncIdentityService
         from ._async.intents import AsyncIntentsService
         from ._async.missions import AsyncMissionsService
+        from ._async.llm import AsyncLlmService
+        from ._async.inbound_webhooks import AsyncInboundWebhookService
+        from ._async.passport_session import AsyncPassportSession
 
         self.agents = AsyncAgentService(self._client)
         self.passports = AsyncPassportService(self._client)
@@ -345,6 +383,30 @@ class AsyncStack:
         self.identity = AsyncIdentityService(self._client)
         self.intents = AsyncIntentsService(self._client)
         self.missions = AsyncMissionsService(self._client)
+        self.llm = AsyncLlmService(self._client)
+        self.inbound_webhooks = AsyncInboundWebhookService(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.9.0/src/getstack/_async/inbound_webhooks.py

@@ -0,0 +1,39 @@
+"""Async mirror of InboundWebhookService (Phase 5.5)."""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Optional
+
+from ..client import AsyncHttpClient
+
+
+Provider = Literal["agentmail", "generic"]
+
+
+class AsyncInboundWebhookService:
+    def __init__(self, client: AsyncHttpClient):
+        self._client = client
+
+    async def create(
+        self,
+        provider: Provider,
+        agent_id: str,
+        forward_url: Optional[str] = None,
+        generic_config: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"provider": provider, "agent_id": agent_id}
+        if forward_url is not None:
+            body["forward_url"] = forward_url
+        if generic_config is not None:
+            body["generic_config"] = generic_config
+        return await self._client.post("/v1/operator/inbound-webhooks", json=body)
+
+    async def list(self) -> list[dict[str, Any]]:
+        res = await self._client.get("/v1/operator/inbound-webhooks")
+        return list(res.get("webhooks", []))
+
+    async def get(self, webhook_id: str) -> dict[str, Any]:
+        return await self._client.get(f"/v1/operator/inbound-webhooks/{webhook_id}")
+
+    async def revoke(self, webhook_id: str) -> dict[str, Any]:
+        return await self._client.delete(f"/v1/operator/inbound-webhooks/{webhook_id}")

getstack-0.9.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.9.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.9.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.9.0/src/getstack/evidence_packs.py

@@ -0,0 +1,78 @@
+"""Evidence packs — export, get, list.
+
+Portable cryptographic bundles. Verifiable offline by any third party
+via the open-source `@getstackrun/verify` package.
+
+  export()  Export a pack for a mission / session / incident / period
+            scope. Returns the pack_id + the full canonical manifest
+            JSON inline. Persist the manifest to disk and hand it to
+            an auditor / insurer / regulator.
+  get()     Fetch one pack by id. Returns the signed claim envelope
+            bytes alongside the parsed pack_claim.
+  list()    List packs for the calling operator. Filter by scope.
+
+Enterprise-tier only at the API layer.
+
+Phase 5.4.7.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .client import HttpClient
+
+
+class EvidencePacksService:
+    def __init__(self, client: HttpClient):
+        self._client = client
+
+    def export(
+        self,
+        *,
+        scope_kind: str,
+        scope_ref: str,
+        supersedes: str | None = None,
+        air_gap: bool | None = None,
+        output_path: str | None = None,
+    ) -> dict[str, Any]:
+        """Export an evidence pack.
+
+        `scope_kind` is one of `mission` | `session` | `incident` | `period`.
+        `scope_ref` is the matching reference (ms_* / ses_* / period:YYYY-Qn /
+        incident:<id>). The pack manifest is returned inline; pass
+        `output_path` to also write it to disk in one step.
+
+        Returns a dict with `pack_id`, `claim_id`, `pack_claim`, `manifest`.
+        """
+        body: dict[str, Any] = {
+            "scope": {"kind": scope_kind, "ref": scope_ref},
+        }
+        if supersedes is not None:
+            body["supersedes"] = supersedes
+        if air_gap is not None:
+            body["air_gap"] = air_gap
+        result = self._client.request("POST", "/v1/evidence-packs", json=body)
+        if output_path is not None and "manifest" in result:
+            with open(output_path, "w", encoding="utf-8") as f:
+                json.dump(result["manifest"], f, indent=2)
+        return result
+
+    def get(self, pack_id: str) -> dict[str, Any]:
+        """Fetch one pack by id. Returns the signed envelope_cose bytes and
+        the parsed `pack_claim` for convenient introspection."""
+        return self._client.request("GET", f"/v1/evidence-packs/{pack_id}")
+
+    def list(self, *, scope: str | None = None) -> dict[str, Any]:
+        """List packs for the calling operator.
+
+        `scope` filter is `<kind>:<ref>` (e.g. `mission:ms_abc`,
+        `period:2026-Q1`). Omit to list every pack. Newest first.
+        """
+        path = "/v1/evidence-packs"
+        if scope is not None:
+            from urllib.parse import urlencode
+
+            path = f"{path}?{urlencode({'scope': scope})}"
+        return self._client.request("GET", path)

getstack-0.9.0/src/getstack/inbound_webhooks.py

@@ -0,0 +1,56 @@
+"""Hosted inbound webhook surface (Phase 5.5).
+
+Operator creates a webhook row + receives a STACK-hosted URL + HMAC
+secret. Paste both into a provider's (AgentMail / generic) webhook
+config; STACK runs the prompt-injection detector on inbound content
+before forwarding to a downstream URL.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal, Optional
+
+from .client import HttpClient
+
+
+Provider = Literal["agentmail", "generic"]
+SignatureAlgorithm = Literal["hmac-sha256", "hmac-sha1"]
+
+
+class InboundWebhookService:
+    def __init__(self, client: HttpClient):
+        self._client = client
+
+    def create(
+        self,
+        provider: Provider,
+        agent_id: str,
+        forward_url: Optional[str] = None,
+        generic_config: Optional[dict[str, Any]] = None,
+    ) -> dict[str, Any]:
+        """Create a hosted inbound webhook.
+
+        Returns a dict with keys: id, provider, slug, webhook_url,
+        webhook_secret (plaintext, returned ONLY at create), agent_id,
+        forward_url, created_at. Capture webhook_secret immediately —
+        STACK never returns it again. If lost, revoke + recreate.
+        """
+        body: dict[str, Any] = {"provider": provider, "agent_id": agent_id}
+        if forward_url is not None:
+            body["forward_url"] = forward_url
+        if generic_config is not None:
+            body["generic_config"] = generic_config
+        return self._client.post("/v1/operator/inbound-webhooks", json=body)
+
+    def list(self) -> list[dict[str, Any]]:
+        """List all inbound webhooks for the operator (active + revoked)."""
+        res = self._client.get("/v1/operator/inbound-webhooks")
+        return list(res.get("webhooks", []))
+
+    def get(self, webhook_id: str) -> dict[str, Any]:
+        """Get a single inbound webhook by id. Never returns the plaintext secret."""
+        return self._client.get(f"/v1/operator/inbound-webhooks/{webhook_id}")
+
+    def revoke(self, webhook_id: str) -> dict[str, Any]:
+        """Soft-delete an inbound webhook. Idempotent on repeat calls."""
+        return self._client.delete(f"/v1/operator/inbound-webhooks/{webhook_id}")

getstack-0.9.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.7.0 → getstack-0.9.0}/src/getstack/missions.py

@@ -128,3 +128,65 @@ class MissionsService:
 
             path = f"{path}?{urlencode(params)}"
         return self._client.request("GET", path)
+
+    # ─── Phase 5.4 — replay + dossier ────────────────────────────────
+
+    def replay(self, mission_id: str) -> dict[str, Any]:
+        """Reconstruct the forensic timeline for a mission.
+
+        Returns a dict matching the @stack/shared `ReplayedTimeline` shape:
+        events ordered chronologically, behavioral_diff (close vs baseline
+        genome), cap_usage, dossiers chain, twin_divergence. Same shape the
+        open-source verifier produces from an exported pack.
+
+        Phase 5.4.5 / 5.4.7.
+        """
+        return self._client.request(
+            "GET", f"/v1/missions/{mission_id}/replay"
+        )
+
+    def list_dossiers(self, mission_id: str) -> dict[str, Any]:
+        """List every dossier authored for a mission, ordered chronologically
+        by `authored_at_ms`. Returns dict with `items` (each carrying
+        `body.narrative`, `body.lessons_learned`, etc.). Empty list when no
+        dossier exists.
+
+        Phase 5.4.2 / 5.4.7.
+        """
+        return self._client.request(
+            "GET", f"/v1/missions/{mission_id}/dossiers"
+        )
+
+    def create_dossier(
+        self,
+        mission_id: str,
+        *,
+        narrative: str,
+        lessons_learned: str,
+        incident_classification: str,
+        decision_tree: list[dict[str, Any]] | None = None,
+        alerts_walkthrough: list[dict[str, Any]] | None = None,
+    ) -> dict[str, Any]:
+        """Author a fresh dossier for a mission. The mission must be in a
+        terminal state (completed_* or revoked_*) — 409 surfaces otherwise.
+        `authored_by_member_id` is derived from the calling auth context
+        server-side (not passed here). Enterprise-tier only.
+
+        `incident_classification` is one of:
+        `false_positive` | `true_positive_handled`
+        | `true_positive_escalated` | `inconclusive`.
+
+        Phase 5.4.2 / 5.4.7.
+        """
+        body: dict[str, Any] = {
+            "narrative": narrative,
+            "lessons_learned": lessons_learned,
+            "incident_classification": incident_classification,
+        }
+        if decision_tree is not None:
+            body["decision_tree"] = decision_tree
+        if alerts_walkthrough is not None:
+            body["alerts_walkthrough"] = alerts_walkthrough
+        return self._client.request(
+            "POST", f"/v1/missions/{mission_id}/dossier", json=body
+        )

getstack-0.9.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