getstack 0.1.0__tar.gz

getstack-0.1.0/.gitignore

@@ -0,0 +1,38 @@
+node_modules/
+dist/
+.turbo/
+*.tsbuildinfo
+
+# Environment / secrets
+.env
+.env.*
+*.env
+
+# Strategy docs (not sensitive, but private)
+stack-claude-code-spec-v3.md
+stack-gtm-distribution.md
+stack-platform-spec-v2.md
+
+# IDE
+.vscode/settings.json
+.idea/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Next.js
+.next/
+out/
+
+# MCP publisher
+mcp-publisher.exe
+.mcpregistry_*
+
+# Fly.io deployment config (contains app names, regions)
+**/fly.toml
+!**/fly.toml.example
+
+# Logs
+*.log
+npm-debug.log*

getstack-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 STACK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

getstack-0.1.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: getstack
+Version: 0.1.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
+Project-URL: Repository, https://github.com/getstack-run/sdk-python
+Author-email: STACK <hello@getstack.run>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,mcp,passport,stack,trust
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.25.0
+Description-Content-Type: text/markdown
+
+# getstack
+
+Python SDK for [STACK](https://getstack.run) — trust infrastructure for AI agents.
+
+## Install
+
+```bash
+pip install getstack
+```
+
+## Quick start
+
+```python
+from getstack import Stack
+
+stack = Stack(api_key="sk_live_...")
+
+# Register an agent
+agent = stack.agents.register("my-agent", accountability_mode="enforced")
+
+# Run a mission with automatic checkpoints and checkout
+with stack.passports.mission(
+    agent_id=agent.id,
+    intent="Process invoices from Slack",
+    services=["slack", "stripe"],
+    checkpoint_interval="5m",
+) as mission:
+    mission.log("slack", "read_channel", "#invoices")
+    mission.log("stripe", "create_invoice")
+    # Checkpoints are submitted automatically on schedule
+# Checkout is submitted automatically when the block exits
+```
+
+## Authentication
+
+```python
+# API key (most common)
+stack = Stack(api_key="sk_live_...")
+
+# OAuth with auto-refresh
+stack = Stack.from_oauth(
+    client_id="...",
+    client_secret="...",
+    access_token="...",
+    refresh_token="...",
+)
+
+# Session JWT (dashboard integrations)
+stack = Stack.from_session(session_token="...")
+```
+
+## Continuous missions (24/7 agents)
+
+```python
+for mission in stack.passports.continuous_mission(
+    agent_id=agent.id,
+    intent="Monitor Slack channels",
+    services=["slack"],
+    rotation_interval="4h",
+    checkpoint_interval="5m",
+):
+    while not mission.should_rotate:
+        event = wait_for_event()
+        mission.log("slack", "read_message")
+        process(event)
+    # Passport rotates automatically at the boundary
+```
+
+## Services
+
+```python
+# Agents
+stack.agents.register(name, description=None, accountability_mode="enforced")
+stack.agents.get(agent_id)
+stack.agents.list()
+stack.agents.update(agent_id, **fields)
+stack.agents.unblock(agent_id)
+
+# Passports
+stack.passports.issue(agent_id, intent=None, services=None, ...)
+stack.passports.verify(token)
+stack.passports.revoke(jti, reason=None)
+stack.passports.checkpoint(jti, services_used, actions_count, ...)
+stack.passports.checkout(jti, services_used, actions_count, ...)
+stack.passports.report(jti)
+
+# Credentials
+stack.credentials.get(provider)
+stack.credentials.get_by_connection(connection_id)
+
+# Services
+stack.services.list()
+stack.services.connect_custom(name, credential, ...)
+stack.services.verify(connection_id)
+stack.services.disconnect(connection_id)
+
+# Reviews
+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)
+
+# Notifications
+stack.notifications.list()
+stack.notifications.create(channel_type, destination, ...)
+stack.notifications.delete(channel_id)
+
+# Audit
+stack.audit.list(page=1, limit=50, action=None, agent_id=None)
+```
+
+## Links
+
+- [Documentation](https://getstack.run/docs/sdk)
+- [Dashboard](https://getstack.run)
+- [GitHub](https://github.com/getstack-run/sdk-python)

getstack-0.1.0/README.md

@@ -0,0 +1,119 @@
+# getstack
+
+Python SDK for [STACK](https://getstack.run) — trust infrastructure for AI agents.
+
+## Install
+
+```bash
+pip install getstack
+```
+
+## Quick start
+
+```python
+from getstack import Stack
+
+stack = Stack(api_key="sk_live_...")
+
+# Register an agent
+agent = stack.agents.register("my-agent", accountability_mode="enforced")
+
+# Run a mission with automatic checkpoints and checkout
+with stack.passports.mission(
+    agent_id=agent.id,
+    intent="Process invoices from Slack",
+    services=["slack", "stripe"],
+    checkpoint_interval="5m",
+) as mission:
+    mission.log("slack", "read_channel", "#invoices")
+    mission.log("stripe", "create_invoice")
+    # Checkpoints are submitted automatically on schedule
+# Checkout is submitted automatically when the block exits
+```
+
+## Authentication
+
+```python
+# API key (most common)
+stack = Stack(api_key="sk_live_...")
+
+# OAuth with auto-refresh
+stack = Stack.from_oauth(
+    client_id="...",
+    client_secret="...",
+    access_token="...",
+    refresh_token="...",
+)
+
+# Session JWT (dashboard integrations)
+stack = Stack.from_session(session_token="...")
+```
+
+## Continuous missions (24/7 agents)
+
+```python
+for mission in stack.passports.continuous_mission(
+    agent_id=agent.id,
+    intent="Monitor Slack channels",
+    services=["slack"],
+    rotation_interval="4h",
+    checkpoint_interval="5m",
+):
+    while not mission.should_rotate:
+        event = wait_for_event()
+        mission.log("slack", "read_message")
+        process(event)
+    # Passport rotates automatically at the boundary
+```
+
+## Services
+
+```python
+# Agents
+stack.agents.register(name, description=None, accountability_mode="enforced")
+stack.agents.get(agent_id)
+stack.agents.list()
+stack.agents.update(agent_id, **fields)
+stack.agents.unblock(agent_id)
+
+# Passports
+stack.passports.issue(agent_id, intent=None, services=None, ...)
+stack.passports.verify(token)
+stack.passports.revoke(jti, reason=None)
+stack.passports.checkpoint(jti, services_used, actions_count, ...)
+stack.passports.checkout(jti, services_used, actions_count, ...)
+stack.passports.report(jti)
+
+# Credentials
+stack.credentials.get(provider)
+stack.credentials.get_by_connection(connection_id)
+
+# Services
+stack.services.list()
+stack.services.connect_custom(name, credential, ...)
+stack.services.verify(connection_id)
+stack.services.disconnect(connection_id)
+
+# Reviews
+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)
+
+# Notifications
+stack.notifications.list()
+stack.notifications.create(channel_type, destination, ...)
+stack.notifications.delete(channel_id)
+
+# Audit
+stack.audit.list(page=1, limit=50, action=None, agent_id=None)
+```
+
+## Links
+
+- [Documentation](https://getstack.run/docs/sdk)
+- [Dashboard](https://getstack.run)
+- [GitHub](https://github.com/getstack-run/sdk-python)

getstack-0.1.0/pyproject.toml

@@ -0,0 +1,35 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "getstack"
+version = "0.1.0"
+description = "Python SDK for STACK — trust infrastructure for AI agents"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "STACK", email = "hello@getstack.run" }]
+keywords = ["ai", "agents", "trust", "passport", "mcp", "stack"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "httpx>=0.25.0",
+]
+
+[project.urls]
+Homepage = "https://getstack.run"
+Documentation = "https://getstack.run/docs/sdk"
+Repository = "https://github.com/getstack-run/sdk-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/getstack"]

getstack-0.1.0/src/getstack/__init__.py

@@ -0,0 +1,233 @@
+"""STACK Python SDK — trust infrastructure for AI agents.
+
+Usage::
+
+    from getstack import Stack
+
+    stack = Stack(api_key="sk_live_...")
+    agent = stack.agents.register("my-agent")
+
+    with stack.passports.mission(
+        agent_id=agent.id,
+        intent="Process invoices",
+        services=["slack", "stripe"],
+    ) as mission:
+        mission.log("slack", "read_channel", "#invoices")
+        mission.log("stripe", "create_invoice")
+
+For OAuth auth::
+
+    stack = Stack.from_oauth(
+        client_id="...",
+        client_secret="...",
+        access_token="...",
+        refresh_token="...",
+    )
+
+For async usage::
+
+    from getstack import AsyncStack
+
+    stack = AsyncStack(api_key="sk_live_...")
+"""
+
+from __future__ import annotations
+
+from .auth import ApiKeyAuth, SessionAuth, OAuthAuth
+from .client import HttpClient, AsyncHttpClient, DEFAULT_BASE_URL
+from .agents import AgentService
+from .passports import PassportService, Mission
+from .credentials import CredentialService
+from .services import ServiceService
+from .dropoffs import DropoffService
+from .reviews import ReviewService
+from .notifications import NotificationService
+from .audit import AuditService
+from .types import (
+    Agent,
+    Passport,
+    CheckpointResult,
+    CheckoutResult,
+    ReviewFlag,
+    PassportReport,
+    ReviewQueue,
+    ReviewQueueItem,
+    ReviewDecisionResult,
+    Credential,
+    NotificationChannel,
+    ToolCall,
+)
+from .errors import (
+    StackError,
+    NotFoundError,
+    UnauthorizedError,
+    ForbiddenError,
+    ValidationError,
+    PassportBlockedError,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Stack",
+    "AsyncStack",
+    "__version__",
+    # Types
+    "Agent",
+    "Passport",
+    "CheckpointResult",
+    "CheckoutResult",
+    "ReviewFlag",
+    "PassportReport",
+    "ReviewQueue",
+    "ReviewQueueItem",
+    "ReviewDecisionResult",
+    "Credential",
+    "NotificationChannel",
+    "Mission",
+    "ToolCall",
+    # Errors
+    "StackError",
+    "NotFoundError",
+    "UnauthorizedError",
+    "ForbiddenError",
+    "ValidationError",
+    "PassportBlockedError",
+]
+
+
+class Stack:
+    """Synchronous STACK client.
+
+    Args:
+        api_key: A STACK API key (``sk_live_...``).
+        base_url: Override the API base URL.
+        timeout: HTTP timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        _auth: ApiKeyAuth | SessionAuth | OAuthAuth | None = None,
+    ):
+        if _auth:
+            auth = _auth
+        elif api_key:
+            auth = ApiKeyAuth(api_key)
+        else:
+            raise ValueError("Either api_key or _auth must be provided")
+
+        self._client = HttpClient(auth, base_url=base_url, timeout=timeout)
+        self.agents = AgentService(self._client)
+        self.passports = PassportService(self._client)
+        self.credentials = CredentialService(self._client)
+        self.services = ServiceService(self._client)
+        self.dropoffs = DropoffService(self._client)
+        self.reviews = ReviewService(self._client)
+        self.notifications = NotificationService(self._client)
+        self.audit = AuditService(self._client)
+
+    @classmethod
+    def from_session(cls, session_token: str, **kwargs) -> Stack:
+        """Create a client authenticated with a session JWT."""
+        return cls(_auth=SessionAuth(session_token), **kwargs)
+
+    @classmethod
+    def from_oauth(
+        cls,
+        client_id: str,
+        client_secret: str,
+        access_token: str,
+        refresh_token: str,
+        token_endpoint: str = "https://api.getstack.run/v1/oauth/token",
+        **kwargs,
+    ) -> Stack:
+        """Create a client with OAuth tokens. Auto-refreshes when expired."""
+        auth = OAuthAuth(
+            client_id=client_id,
+            client_secret=client_secret,
+            access_token=access_token,
+            refresh_token=refresh_token,
+            token_endpoint=token_endpoint,
+        )
+        return cls(_auth=auth, **kwargs)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> Stack:
+        return self
+
+    def __exit__(self, *args) -> None:
+        self.close()
+
+
+class AsyncStack:
+    """Asynchronous STACK client.
+
+    Uses httpx.AsyncClient under the hood. All service methods are sync
+    (they use the sync HttpClient wrapper) — for true async, the async
+    client needs async service modules. This provides the async HTTP
+    transport layer for future async service implementations.
+
+    Args:
+        api_key: A STACK API key (``sk_live_...``).
+        base_url: Override the API base URL.
+        timeout: HTTP timeout in seconds.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+        _auth: ApiKeyAuth | SessionAuth | OAuthAuth | None = None,
+    ):
+        if _auth:
+            auth = _auth
+        elif api_key:
+            auth = ApiKeyAuth(api_key)
+        else:
+            raise ValueError("Either api_key or _auth must be provided")
+
+        self._client = AsyncHttpClient(auth, base_url=base_url, timeout=timeout)
+
+    @classmethod
+    def from_session(cls, session_token: str, **kwargs) -> AsyncStack:
+        """Create an async client authenticated with a session JWT."""
+        return cls(_auth=SessionAuth(session_token), **kwargs)
+
+    @classmethod
+    def from_oauth(
+        cls,
+        client_id: str,
+        client_secret: str,
+        access_token: str,
+        refresh_token: str,
+        token_endpoint: str = "https://api.getstack.run/v1/oauth/token",
+        **kwargs,
+    ) -> AsyncStack:
+        """Create an async client with OAuth tokens. Auto-refreshes when expired."""
+        auth = OAuthAuth(
+            client_id=client_id,
+            client_secret=client_secret,
+            access_token=access_token,
+            refresh_token=refresh_token,
+            token_endpoint=token_endpoint,
+        )
+        return cls(_auth=auth, **kwargs)
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.close()
+
+    async def __aenter__(self) -> AsyncStack:
+        return self
+
+    async def __aexit__(self, *args) -> None:
+        await self.close()

getstack-0.1.0/src/getstack/agents.py

@@ -0,0 +1,70 @@
+"""Agent management."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .client import HttpClient
+from .types import Agent
+
+
+def _to_agent(data: dict[str, Any]) -> Agent:
+    return Agent(
+        id=data["id"],
+        operator_id=data["operator_id"],
+        name=data["name"],
+        description=data.get("description"),
+        status=data["status"],
+        accountability_mode=data.get("accountability_mode", "standard"),
+        on_warning=data.get("on_warning", "notify"),
+        on_critical=data.get("on_critical", "notify"),
+        passport_blocked=data.get("passport_blocked", False),
+        passport_blocked_reason=data.get("passport_blocked_reason"),
+        passport_blocked_at=data.get("passport_blocked_at"),
+        created_at=data["created_at"],
+        updated_at=data["updated_at"],
+    )
+
+
+class AgentService:
+    def __init__(self, client: HttpClient):
+        self._client = client
+
+    def register(
+        self,
+        name: str,
+        description: str | None = None,
+        accountability_mode: str = "enforced",
+        on_warning: str = "notify",
+        on_critical: str = "notify",
+    ) -> Agent:
+        body: dict[str, Any] = {"name": name, "accountability_mode": accountability_mode}
+        if description:
+            body["description"] = description
+        if on_warning != "notify":
+            body["on_warning"] = on_warning
+        if on_critical != "notify":
+            body["on_critical"] = on_critical
+        return _to_agent(self._client.post("/v1/agents/register", json=body))
+
+    def get(self, agent_id: str) -> Agent:
+        return _to_agent(self._client.get(f"/v1/agents/{agent_id}"))
+
+    def list(self) -> list[Agent]:
+        data = self._client.get("/v1/agents")
+        return [_to_agent(a) for a in data]
+
+    def update(self, agent_id: str, **kwargs: Any) -> Agent:
+        return _to_agent(self._client.patch(f"/v1/agents/{agent_id}", json=kwargs))
+
+    def suspend(self, agent_id: str) -> Agent:
+        return self.update(agent_id, status="suspended")
+
+    def activate(self, agent_id: str) -> Agent:
+        return self.update(agent_id, status="active")
+
+    def delete(self, agent_id: str) -> dict[str, Any]:
+        return self._client.delete(f"/v1/agents/{agent_id}")
+
+    def unblock(self, agent_id: str) -> dict[str, Any]:
+        return self._client.post(f"/v1/agents/{agent_id}/unblock")

getstack-0.1.0/src/getstack/audit.py

@@ -0,0 +1,26 @@
+"""Audit log access."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .client import HttpClient
+
+
+class AuditService:
+    def __init__(self, client: HttpClient):
+        self._client = client
+
+    def list(
+        self,
+        page: int = 1,
+        limit: int = 50,
+        action: str | None = None,
+        agent_id: str | None = None,
+    ) -> list[dict[str, Any]]:
+        params: dict[str, str] = {"page": str(page), "limit": str(limit)}
+        if action:
+            params["action"] = action
+        if agent_id:
+            params["agent_id"] = agent_id
+        return self._client.get("/v1/audit", params=params)