getstack 0.1.0__py3-none-any.whl

getstack/notifications.py

@@ -0,0 +1,57 @@
+"""Notification channel management."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .client import HttpClient
+from .types import NotificationChannel
+
+
+def _to_channel(data: dict[str, Any]) -> NotificationChannel:
+    return NotificationChannel(
+        id=data["id"],
+        channel_type=data["channel_type"],
+        destination=data["destination"],
+        events=data.get("events", []),
+        min_severity=data.get("min_severity", "warning"),
+        active=data.get("active", True),
+        verified=data.get("verified", False),
+    )
+
+
+class NotificationService:
+    def __init__(self, client: HttpClient):
+        self._client = client
+
+    def list(self) -> list[NotificationChannel]:
+        data = self._client.get("/v1/notifications/channels")
+        return [_to_channel(ch) for ch in data]
+
+    def create(
+        self,
+        channel_type: str,
+        destination: str,
+        events: list[str] | None = None,
+        min_severity: str = "warning",
+    ) -> NotificationChannel:
+        body: dict[str, Any] = {
+            "channel_type": channel_type,
+            "destination": destination,
+            "min_severity": min_severity,
+        }
+        if events:
+            body["events"] = events
+        return _to_channel(self._client.post("/v1/notifications/channels", json=body))
+
+    def verify(self, channel_id: str, code: str | None = None) -> dict[str, Any]:
+        body: dict[str, Any] = {}
+        if code:
+            body["code"] = code
+        return self._client.post(f"/v1/notifications/channels/{channel_id}/verify", json=body)
+
+    def test(self, channel_id: str) -> dict[str, Any]:
+        return self._client.post(f"/v1/notifications/channels/{channel_id}/test")
+
+    def delete(self, channel_id: str) -> dict[str, Any]:
+        return self._client.delete(f"/v1/notifications/channels/{channel_id}")

getstack/passports.py

@@ -0,0 +1,359 @@
+"""Passport management with mission context manager and continuous rotation."""
+
+from __future__ import annotations
+
+import re
+import time
+import threading
+from contextlib import contextmanager
+from typing import Any, Generator
+
+from .client import HttpClient
+from .types import Passport, CheckpointResult, CheckoutResult, PassportReport, ToolCall
+
+
+def _parse_duration(s: str) -> int:
+    """Parse a duration string like '30m', '2h', '300' to seconds."""
+    match = re.match(r"^(\d+)(s|m|h)$", s)
+    if match:
+        num, unit = int(match.group(1)), match.group(2)
+        return num * {"s": 1, "m": 60, "h": 3600}[unit]
+    return int(s)
+
+
+def _to_passport(data: dict[str, Any]) -> Passport:
+    return Passport(
+        token=data["token"],
+        jti=data["jti"],
+        expires_at=data["expires_at"],
+        accountability=data.get("accountability"),
+    )
+
+
+class Mission:
+    """A bounded accountability window for an agent mission.
+
+    Tracks tool calls, submits checkpoints on schedule, and checks out
+    automatically when the context manager exits.
+    """
+
+    def __init__(
+        self,
+        service: PassportService,
+        agent_id: str,
+        intent: str,
+        services: list[str],
+        will_delegate: bool = False,
+        estimated_duration: str | None = None,
+        checkpoint_interval: str | None = None,
+    ):
+        self._service = service
+        self._agent_id = agent_id
+        self._intent = intent
+        self._declared_services = services
+        self._will_delegate = will_delegate
+        self._estimated_duration = estimated_duration
+        self._checkpoint_interval = checkpoint_interval
+
+        self.passport: Passport | None = None
+        self.review_status: str | None = None
+        self.result: CheckoutResult | None = None
+        self.rotation_count: int = 0
+
+        self._tool_calls: list[ToolCall] = []
+        self._services_used: set[str] = set()
+        self._delegated_to: list[str] = []
+        self._last_checkpoint_index: int = 0
+        self._timer: threading.Timer | None = None
+        self._timer_interval: float | None = None
+        self._rotation_start: float = 0
+        self._rotation_interval: float | None = None
+
+    @property
+    def should_rotate(self) -> bool:
+        """True when the rotation interval has elapsed. Check at natural breakpoints."""
+        if self._rotation_interval is None:
+            return False
+        return time.monotonic() - self._rotation_start >= self._rotation_interval
+
+    def log(self, service: str, method: str, target: str | None = None) -> None:
+        """Log a tool call. Call this for each action the agent takes."""
+        self._tool_calls.append(ToolCall(service=service, method=method, target=target))
+        self._services_used.add(service)
+
+    def delegate(self, child_agent_id: str) -> None:
+        """Record that delegation occurred to a child agent."""
+        self._delegated_to.append(child_agent_id)
+
+    def _enter(self) -> None:
+        """Issue passport and start checkpoint timer."""
+        self.passport = self._service.issue(
+            agent_id=self._agent_id,
+            intent=self._intent,
+            services=self._declared_services,
+            will_delegate=self._will_delegate,
+            estimated_duration=self._estimated_duration,
+            checkpoint_interval=self._checkpoint_interval,
+        )
+        self._rotation_start = time.monotonic()
+
+        # Start checkpoint timer for enforced mode
+        if self._checkpoint_interval:
+            self._timer_interval = _parse_duration(self._checkpoint_interval)
+        elif self.passport.accountability == "enforced":
+            self._timer_interval = 300  # 5 min default
+        else:
+            self._timer_interval = None
+
+        if self._timer_interval:
+            self._schedule_checkpoint()
+
+    def _schedule_checkpoint(self) -> None:
+        """Schedule the next automatic checkpoint."""
+        if self._timer_interval:
+            # Submit slightly before the interval to ensure we don't miss it
+            delay = max(self._timer_interval - 5, 10)
+            self._timer = threading.Timer(delay, self._auto_checkpoint)
+            self._timer.daemon = True
+            self._timer.start()
+
+    def _auto_checkpoint(self) -> None:
+        """Submit checkpoint and reschedule."""
+        try:
+            self._submit_checkpoint()
+        except Exception:
+            pass  # Don't crash the agent on checkpoint failure
+        self._schedule_checkpoint()
+
+    def _submit_checkpoint(self) -> None:
+        """Submit accumulated activity as a checkpoint."""
+        if not self.passport:
+            return
+
+        new_calls = self._tool_calls[self._last_checkpoint_index:]
+        self._service.checkpoint(
+            self.passport.jti,
+            services_used=list(self._services_used),
+            actions_count=len(new_calls),
+            tool_calls=[tc.to_dict() for tc in new_calls] if new_calls else None,
+            delegated_to=self._delegated_to if self._delegated_to else None,
+        )
+        self._last_checkpoint_index = len(self._tool_calls)
+
+    def _exit(self, error: Exception | None = None) -> None:
+        """Stop timer and submit checkout."""
+        if self._timer:
+            self._timer.cancel()
+            self._timer = None
+
+        if not self.passport:
+            return
+
+        summary = None
+        if error:
+            summary = f"Mission failed: {type(error).__name__}: {error}"
+
+        try:
+            self.result = self._service.checkout(
+                self.passport.jti,
+                services_used=list(self._services_used),
+                actions_count=len(self._tool_calls),
+                tool_calls=[tc.to_dict() for tc in self._tool_calls] if self._tool_calls else None,
+                summary=summary,
+                delegated_to=self._delegated_to if self._delegated_to else None,
+            )
+            self.review_status = self.result.review_status
+        except Exception:
+            pass  # Best-effort checkout
+
+    def __enter__(self) -> Mission:
+        self._enter()
+        return self
+
+    def __exit__(self, exc_type: type | None, exc_val: Exception | None, exc_tb: Any) -> bool:
+        self._exit(error=exc_val if exc_type else None)
+        return False  # Don't suppress exceptions
+
+
+class PassportService:
+    def __init__(self, client: HttpClient):
+        self._client = client
+
+    def issue(
+        self,
+        agent_id: str,
+        intent: str | None = None,
+        services: list[str] | None = None,
+        will_delegate: bool = False,
+        estimated_duration: str | None = None,
+        checkpoint_interval: str | None = None,
+        ttl_seconds: int | None = None,
+        scopes: list[dict[str, Any]] | None = None,
+    ) -> Passport:
+        body: dict[str, Any] = {"agent_id": agent_id}
+        if scopes:
+            body["scopes"] = scopes
+        if ttl_seconds:
+            body["ttl_seconds"] = ttl_seconds
+        if intent or services:
+            body["intent"] = {
+                "summary": intent or "",
+                "services": services or [],
+                "will_delegate": will_delegate,
+            }
+            if estimated_duration:
+                body["intent"]["estimated_duration_seconds"] = _parse_duration(estimated_duration)
+        if checkpoint_interval:
+            body["checkpoint_interval_seconds"] = _parse_duration(checkpoint_interval)
+        return _to_passport(self._client.post("/v1/passports/issue", json=body))
+
+    def checkpoint(
+        self,
+        passport_jti: str,
+        services_used: list[str],
+        actions_count: int,
+        tool_calls: list[dict[str, Any]] | None = None,
+        summary: str | None = None,
+        delegated_to: list[str] | None = None,
+    ) -> CheckpointResult:
+        body: dict[str, Any] = {
+            "services_used": services_used,
+            "actions_count": actions_count,
+        }
+        if tool_calls:
+            body["tool_calls"] = tool_calls
+        if summary:
+            body["summary"] = summary
+        if delegated_to:
+            body["delegated_to"] = delegated_to
+        data = self._client.post(f"/v1/passports/{passport_jti}/checkpoint", json=body)
+        return CheckpointResult(
+            checkpoint_id=data["checkpoint_id"],
+            passport_jti=data["passport_jti"],
+            new_expires_at=data.get("new_expires_at"),
+            flags=data.get("flags"),
+        )
+
+    def checkout(
+        self,
+        passport_jti: str,
+        services_used: list[str],
+        actions_count: int,
+        tool_calls: list[dict[str, Any]] | None = None,
+        summary: str | None = None,
+        delegated_to: list[str] | None = None,
+    ) -> CheckoutResult:
+        body: dict[str, Any] = {
+            "services_used": services_used,
+            "actions_count": actions_count,
+        }
+        if tool_calls:
+            body["tool_calls"] = tool_calls
+        if summary:
+            body["summary"] = summary
+        if delegated_to:
+            body["delegated_to"] = delegated_to
+        data = self._client.post(f"/v1/passports/{passport_jti}/checkout", json=body)
+        return CheckoutResult(
+            checkout_id=data["checkout_id"],
+            passport_jti=data["passport_jti"],
+            review_status=data["review_status"],
+            flags=data.get("flags"),
+        )
+
+    def report(self, passport_jti: str) -> PassportReport:
+        data = self._client.get(f"/v1/passports/{passport_jti}/report")
+        return PassportReport(**data)
+
+    def verify(self, token: str) -> dict[str, Any]:
+        return self._client.post("/v1/passports/verify", json={"token": token})
+
+    def revoke(self, jti: str, reason: str | None = None) -> dict[str, Any]:
+        return self._client.post("/v1/passports/revoke", json={"jti": jti, "reason": reason})
+
+    def refresh(self, token: str, ttl_seconds: int | None = None) -> Passport:
+        body: dict[str, Any] = {"token": token}
+        if ttl_seconds:
+            body["ttl_seconds"] = ttl_seconds
+        return _to_passport(self._client.post("/v1/passports/refresh", json=body))
+
+    def list_active(self, agent_id: str | None = None, session_id: str | None = None) -> list[dict[str, Any]]:
+        params: dict[str, str] = {}
+        if agent_id:
+            params["agent_id"] = agent_id
+        if session_id:
+            params["session_id"] = session_id
+        return self._client.get("/v1/passports/active", params=params or None)
+
+    @contextmanager
+    def mission(
+        self,
+        agent_id: str,
+        intent: str,
+        services: list[str],
+        will_delegate: bool = False,
+        estimated_duration: str | None = None,
+        checkpoint_interval: str | None = None,
+    ) -> Generator[Mission, None, None]:
+        """Context manager for a single bounded mission."""
+        m = Mission(
+            self, agent_id, intent, services,
+            will_delegate=will_delegate,
+            estimated_duration=estimated_duration,
+            checkpoint_interval=checkpoint_interval,
+        )
+        m._enter()
+        try:
+            yield m
+        except Exception as e:
+            m._exit(error=e)
+            raise
+        else:
+            m._exit()
+
+    def continuous_mission(
+        self,
+        agent_id: str,
+        intent: str,
+        services: list[str],
+        rotation_interval: str = "4h",
+        will_delegate: bool = False,
+        checkpoint_interval: str | None = None,
+    ) -> Generator[Mission, None, None]:
+        """Generator yielding successive Mission objects with automatic rotation.
+
+        Each iteration issues a new passport, runs checkpoints, and checks out
+        when the rotation interval elapses (signaled via mission.should_rotate).
+
+        Usage::
+
+            for mission in stack.passports.continuous_mission(
+                agent_id="agt_...",
+                intent="Monitor Slack",
+                services=["slack"],
+                rotation_interval="4h",
+            ):
+                while not mission.should_rotate:
+                    event = wait_for_event()
+                    mission.log("slack", "read_message")
+                    process(event)
+        """
+        rotation_secs = _parse_duration(rotation_interval)
+        rotation_count = 0
+
+        while True:
+            m = Mission(
+                self, agent_id, intent, services,
+                will_delegate=will_delegate,
+                checkpoint_interval=checkpoint_interval,
+            )
+            m.rotation_count = rotation_count
+            m._rotation_interval = rotation_secs
+
+            m._enter()
+            try:
+                yield m
+            finally:
+                m._exit()
+
+            rotation_count += 1

getstack/reviews.py

@@ -0,0 +1,54 @@
+"""Review queue management."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .client import HttpClient
+from .types import ReviewQueue, ReviewQueueItem, ReviewDecisionResult
+
+
+class ReviewService:
+    def __init__(self, client: HttpClient):
+        self._client = client
+
+    def list(self, status: str = "flagged", page: int = 1, limit: int = 20) -> ReviewQueue:
+        data = self._client.get("/v1/passports/reviews", params={
+            "status": status,
+            "page": str(page),
+            "limit": str(limit),
+        })
+        items = [
+            ReviewQueueItem(
+                checkout_id=item["checkout_id"],
+                passport_jti=item["passport_jti"],
+                agent_id=item["agent_id"],
+                agent_name=item["agent_name"],
+                intent_summary=item["intent_summary"],
+                review_status=item["review_status"],
+                flags=item.get("flags", []),
+                submitted_at=item["submitted_at"],
+            )
+            for item in data["items"]
+        ]
+        return ReviewQueue(items=items, total=data["total"])
+
+    def decide(
+        self,
+        checkout_id: str,
+        decision: str,
+        notes: str | None = None,
+        block_future: bool = False,
+    ) -> ReviewDecisionResult:
+        body: dict[str, Any] = {"decision": decision}
+        if notes:
+            body["notes"] = notes
+        if block_future:
+            body["block_future"] = True
+        data = self._client.post(f"/v1/passports/reviews/{checkout_id}/decide", json=body)
+        return ReviewDecisionResult(
+            review_id=data["review_id"],
+            agent_id=data["agent_id"],
+            decision=data["decision"],
+            passport_blocked=data["passport_blocked"],
+        )

getstack/services.py

@@ -0,0 +1,41 @@
+"""Service management."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .client import HttpClient
+
+
+class ServiceService:
+    def __init__(self, client: HttpClient):
+        self._client = client
+
+    def list(self) -> list[dict[str, Any]]:
+        return self._client.get("/v1/services/connections")
+
+    def list_available(self) -> list[dict[str, Any]]:
+        return self._client.get("/v1/services")
+
+    def list_templates(self) -> list[dict[str, Any]]:
+        return self._client.get("/v1/services/templates")
+
+    def connect_custom(
+        self,
+        name: str,
+        credential: str | dict[str, str],
+        description: str | None = None,
+        scopes: list[str] | None = None,
+    ) -> dict[str, Any]:
+        body: dict[str, Any] = {"name": name, "credential": credential}
+        if description:
+            body["description"] = description
+        if scopes:
+            body["scopes"] = scopes
+        return self._client.post("/v1/services/custom", json=body)
+
+    def verify(self, connection_id: str) -> dict[str, Any]:
+        return self._client.post(f"/v1/services/{connection_id}/verify")
+
+    def disconnect(self, connection_id: str) -> dict[str, Any]:
+        return self._client.delete(f"/v1/services/connections/{connection_id}")

getstack/types.py

@@ -0,0 +1,156 @@
+"""STACK SDK type definitions."""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Agent:
+    id: str
+    operator_id: str
+    name: str
+    description: str | None
+    status: str
+    accountability_mode: str
+    on_warning: str
+    on_critical: str
+    passport_blocked: bool
+    passport_blocked_reason: str | None
+    passport_blocked_at: str | None
+    created_at: str
+    updated_at: str
+
+
+@dataclass
+class Passport:
+    token: str
+    jti: str
+    expires_at: str
+    accountability: str | None = None
+
+
+@dataclass
+class CheckpointResult:
+    checkpoint_id: str
+    passport_jti: str
+    new_expires_at: str | None = None
+    flags: list[str] | None = None
+
+
+@dataclass
+class CheckoutResult:
+    checkout_id: str
+    passport_jti: str
+    review_status: str  # clean | flagged | blocked
+    flags: list[dict[str, str]] | None = None
+
+
+@dataclass
+class ReviewFlag:
+    type: str
+    severity: str
+    message: str
+
+
+@dataclass
+class PassportReport:
+    passport: dict[str, Any]
+    intent: dict[str, Any] | None
+    checkpoints: list[dict[str, Any]]
+    checkout: dict[str, Any] | None
+    review: dict[str, Any] | None
+
+
+@dataclass
+class ReviewQueueItem:
+    checkout_id: str
+    passport_jti: str
+    agent_id: str
+    agent_name: str
+    intent_summary: str
+    review_status: str
+    flags: list[dict[str, str]]
+    submitted_at: str
+
+
+@dataclass
+class ReviewQueue:
+    items: list[ReviewQueueItem]
+    total: int
+
+
+@dataclass
+class ReviewDecisionResult:
+    review_id: str
+    agent_id: str
+    decision: str
+    passport_blocked: bool
+
+
+@dataclass
+class Credential:
+    provider: str
+    credential: str | None = None
+    credentials: dict[str, str] | None = None
+
+
+@dataclass
+class Service:
+    id: str
+    provider: str
+    name: str
+    description: str
+    available: bool = True
+
+
+@dataclass
+class ServiceConnection:
+    id: str
+    provider: str
+    status: str
+    connected_at: str
+
+
+@dataclass
+class Dropoff:
+    id: str
+    from_agent_id: str
+    to_agent_id: str
+    status: str
+    created_at: str
+    expires_at: str
+
+
+@dataclass
+class NotificationChannel:
+    id: str
+    channel_type: str
+    destination: str
+    events: list[str]
+    min_severity: str
+    active: bool
+    verified: bool
+
+
+@dataclass
+class AuditEntry:
+    entry_id: str
+    action: str
+    outcome: str
+    timestamp: int
+    agent_id: str
+
+
+@dataclass
+class ToolCall:
+    """A single tool call logged during a mission."""
+    service: str
+    method: str
+    target: str | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        d: dict[str, Any] = {"service": self.service, "method": self.method}
+        if self.target:
+            d["target"] = self.target
+        return d