openscript-sdk 0.1.0__py3-none-any.whl

openscript_sdk/events/approvals.py

@@ -0,0 +1,309 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import uuid
+from dataclasses import asdict, dataclass, field, replace
+from datetime import UTC, datetime, timedelta
+from enum import StrEnum
+from typing import Any, Protocol
+
+import structlog
+
+logger = structlog.get_logger(__name__)
+
+DEFAULT_TTL_SECONDS = 3600  # approvals expire back to blocked after 1h
+
+
+class ApprovalStatus(StrEnum):
+    PENDING = "pending"
+    APPROVED = "approved"
+    DENIED = "denied"
+
+
+def _typed(value: Any) -> Any:
+    """*value* as plain JSON in which every piece says what type it was.
+
+    Exact types, not isinstance: an IntEnum member is not the int it compares
+    equal to, and should not be approved as if it were. A list and a tuple are
+    deliberately the same thing here; nothing can be done with one that cannot
+    be done with the other.
+    """
+    kind = type(value)
+    if value is None:
+        return ["none"]
+    if kind is bool:
+        return ["bool", value]
+    if kind is int:
+        return ["int", str(value)]
+    if kind is float:
+        return ["float", repr(value)]
+    if kind is str:
+        return ["str", value]
+    if kind in (bytes, bytearray):
+        return ["bytes", bytes(value).hex()]
+    if kind in (list, tuple):
+        return ["list", [_typed(item) for item in value]]
+    if kind in (set, frozenset):
+        return ["set", sorted((_typed(item) for item in value), key=_order)]
+    if kind is dict:
+        pairs = ([_typed(key), _typed(item)] for key, item in value.items())
+        return ["dict", sorted(pairs, key=_order)]
+    # Anything else is named by its type as well as its text, so a Decimal, a
+    # UUID or a date cannot stand in for the string that spells it.
+    return ["object", f"{kind.__module__}.{kind.__qualname__}", str(value)]
+
+
+def _order(encoded: Any) -> str:
+    return json.dumps(encoded)
+
+
+def action_hash(action: str, input_data: dict[str, Any]) -> str:
+    """Canonical fingerprint of (action, input) for approval binding.
+
+    An approval is redeemable only against the exact action it was requested
+    for — a matching hash proves the retried call carries the same action
+    name and input/args, so a granted approval can't be replayed against a
+    different tool call.
+
+    "The same" means the same values of the same types. This used to be
+    json.dumps(default=str), and str() forgets what it was given: Decimal("10")
+    and the text "10" fingerprinted alike, as did {1: x} and {"1": x}. An
+    approval for one was an approval for the other.
+    """
+    canonical = json.dumps(["action", action, _typed(input_data)], separators=(",", ":"))
+    return hashlib.sha256(canonical.encode()).hexdigest()
+
+
+def _new_expiry(ttl_seconds: int = DEFAULT_TTL_SECONDS) -> datetime:
+    return datetime.now(UTC) + timedelta(seconds=ttl_seconds)
+
+
+@dataclass
+class ApprovalRecord:
+    session_id: str
+    agent_id: str
+    action: str
+    reason: str
+    action_hash: str
+    approval_id: str = field(default_factory=lambda: uuid.uuid4().hex)
+    status: ApprovalStatus = ApprovalStatus.PENDING
+    created_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    expires_at: datetime = field(default_factory=_new_expiry)
+    decided_by: str = ""
+    #: What the person deciding said about it. A denial with no reason sends
+    #: the requester back to guess; this is where the reason travels.
+    decision_note: str = ""
+
+    @property
+    def expired(self) -> bool:
+        return datetime.now(UTC) >= self.expires_at
+
+    def to_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        data["status"] = self.status.value
+        data["created_at"] = self.created_at.isoformat()
+        data["expires_at"] = self.expires_at.isoformat()
+        return data
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> ApprovalRecord:
+        return cls(
+            session_id=data["session_id"],
+            agent_id=data["agent_id"],
+            action=data["action"],
+            reason=data["reason"],
+            action_hash=data["action_hash"],
+            approval_id=data["approval_id"],
+            status=ApprovalStatus(data["status"]),
+            created_at=datetime.fromisoformat(data["created_at"]),
+            expires_at=datetime.fromisoformat(data["expires_at"]),
+            decided_by=data.get("decided_by", ""),
+            # Absent from records written before the field existed.
+            decision_note=data.get("decision_note", ""),
+        )
+
+
+class ApprovalStore(Protocol):
+    """Storage for pending/decided approval records.
+
+    Expired records behave as denied everywhere: they drop out of
+    list_pending, can no longer be decided, and never redeem.
+    """
+
+    async def create(self, record: ApprovalRecord) -> None: ...
+
+    async def get(self, approval_id: str) -> ApprovalRecord | None: ...
+
+    async def list_pending(self) -> list[ApprovalRecord]: ...
+
+    async def decide(
+        self, approval_id: str, approved: bool, decided_by: str = "", note: str = ""
+    ) -> ApprovalRecord | None:
+        """Resolve a pending record. Returns the updated record, or None when
+        the id is unknown. Raises ValueError when the record is no longer
+        pending (already decided or expired). *note* is the decider's reason,
+        kept on the record as ``decision_note``."""
+        ...
+
+    async def consume(self, approval_id: str, expected_hash: str) -> bool:
+        """Single-use redemption: True iff the record exists, is approved,
+        is not expired, and its action_hash matches — the record is deleted
+        so it can never redeem twice."""
+        ...
+
+
+class InMemoryApprovalStore:
+    """Dict-backed store for SINGLE-PROCESS use and tests only.
+
+    SecureAgent runs in the caller's process while /v1/approvals runs in the
+    server — an in-memory store is never visible to both. Use
+    RedisApprovalStore whenever approvals are decided over the HTTP API.
+    """
+
+    def __init__(self) -> None:
+        self._records: dict[str, ApprovalRecord] = {}
+
+    async def create(self, record: ApprovalRecord) -> None:
+        self._records[record.approval_id] = replace(record)
+
+    async def get(self, approval_id: str) -> ApprovalRecord | None:
+        record = self._records.get(approval_id)
+        return replace(record) if record is not None else None
+
+    async def list_pending(self) -> list[ApprovalRecord]:
+        self._purge_expired()
+        return [replace(r) for r in self._records.values() if r.status == ApprovalStatus.PENDING]
+
+    async def decide(
+        self, approval_id: str, approved: bool, decided_by: str = "", note: str = ""
+    ) -> ApprovalRecord | None:
+        record = self._records.get(approval_id)
+        if record is None:
+            return None
+        if record.status != ApprovalStatus.PENDING or record.expired:
+            raise ValueError(f"approval '{approval_id}' is not pending")
+        record.status = ApprovalStatus.APPROVED if approved else ApprovalStatus.DENIED
+        record.decided_by = decided_by
+        record.decision_note = note
+        return replace(record)
+
+    async def consume(self, approval_id: str, expected_hash: str) -> bool:
+        record = self._records.get(approval_id)
+        if (
+            record is None
+            or record.status != ApprovalStatus.APPROVED
+            or record.expired
+            or record.action_hash != expected_hash
+        ):
+            return False
+        del self._records[approval_id]
+        return True
+
+    def _purge_expired(self) -> None:
+        expired = [aid for aid, r in self._records.items() if r.expired]
+        for aid in expired:
+            del self._records[aid]
+
+
+class RedisApprovalStore:
+    """Redis-backed store — required whenever SecureAgent and the server run
+    in separate processes (i.e. any real deployment of the approvals API).
+
+    Records live at {prefix}:{approval_id} as JSON with a Redis TTL matching
+    expires_at; pending ids are tracked in the {prefix}:pending set. Single-use
+    redemption relies on DELETE's atomicity: only the caller whose DELETE
+    returns 1 wins a concurrent redeem race. A decision is made under WATCH,
+    so of two people deciding the same request at once, one is told it was
+    already decided.
+    """
+
+    def __init__(
+        self,
+        url: str = "redis://localhost:6379/0",
+        *,
+        key_prefix: str = "openscript:approval",
+    ) -> None:
+        import redis.asyncio as aioredis
+
+        self._redis = aioredis.from_url(url, decode_responses=True)
+        self._prefix = key_prefix
+        self._pending_key = f"{key_prefix}:pending"
+
+    def _key(self, approval_id: str) -> str:
+        return f"{self._prefix}:{approval_id}"
+
+    @staticmethod
+    def _ttl_seconds(record: ApprovalRecord) -> int:
+        return max(1, int((record.expires_at - datetime.now(UTC)).total_seconds()))
+
+    async def create(self, record: ApprovalRecord) -> None:
+        await self._redis.set(
+            self._key(record.approval_id),
+            json.dumps(record.to_dict()),
+            ex=self._ttl_seconds(record),
+        )
+        await self._redis.sadd(self._pending_key, record.approval_id)
+
+    async def get(self, approval_id: str) -> ApprovalRecord | None:
+        raw = await self._redis.get(self._key(approval_id))
+        return ApprovalRecord.from_dict(json.loads(raw)) if raw else None
+
+    async def list_pending(self) -> list[ApprovalRecord]:
+        pending: list[ApprovalRecord] = []
+        for approval_id in await self._redis.smembers(self._pending_key):
+            record = await self.get(str(approval_id))
+            if record is None or record.status != ApprovalStatus.PENDING:
+                # expired (key TTL fired) or already decided — clean the set
+                await self._redis.srem(self._pending_key, approval_id)
+                continue
+            pending.append(record)
+        return pending
+
+    async def decide(
+        self, approval_id: str, approved: bool, decided_by: str = "", note: str = ""
+    ) -> ApprovalRecord | None:
+        from redis.exceptions import WatchError
+
+        key = self._key(approval_id)
+        # Read, check and write as one step. Without the WATCH, two people
+        # deciding at the same moment both read "pending", both write, and both
+        # are told it worked — an approval and a denial of the same request,
+        # with whichever landed second quietly winning.
+        # Typed Any: redis-py leaves multi() unannotated, and whether that is
+        # an error depends on whether its types are installed where mypy runs.
+        transaction: Any = self._redis.pipeline(transaction=True)
+        async with transaction as pipe:
+            while True:
+                try:
+                    await pipe.watch(key)
+                    raw = await pipe.get(key)
+                    record = ApprovalRecord.from_dict(json.loads(raw)) if raw else None
+                    if record is None:
+                        return None
+                    if record.status != ApprovalStatus.PENDING or record.expired:
+                        raise ValueError(f"approval '{approval_id}' is not pending")
+                    record.status = ApprovalStatus.APPROVED if approved else ApprovalStatus.DENIED
+                    record.decided_by = decided_by
+                    record.decision_note = note
+                    pipe.multi()
+                    pipe.set(key, json.dumps(record.to_dict()), ex=self._ttl_seconds(record))
+                    pipe.srem(self._pending_key, approval_id)
+                    await pipe.execute()
+                    return record
+                except WatchError:
+                    # Someone else wrote the record first. Read it again: it is
+                    # no longer pending, and the check above says so.
+                    continue
+
+    async def consume(self, approval_id: str, expected_hash: str) -> bool:
+        record = await self.get(approval_id)
+        if (
+            record is None
+            or record.status != ApprovalStatus.APPROVED
+            or record.expired
+            or record.action_hash != expected_hash
+        ):
+            return False
+        # DELETE returning 1 is the atomic single-use gate under concurrency
+        return await self._redis.delete(self._key(approval_id)) == 1

openscript_sdk/events/models.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from sqlalchemy import DateTime, Index, Integer, String
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class EventRow(Base):
+    __tablename__ = "events"
+
+    id: Mapped[str] = mapped_column(String, primary_key=True)
+    session_id: Mapped[str] = mapped_column(String, nullable=False, index=True)
+    agent_id: Mapped[str] = mapped_column(String, nullable=False)
+    event_type: Mapped[str] = mapped_column(String, nullable=False)
+    payload: Mapped[dict[str, Any]] = mapped_column(JSONB, nullable=False, server_default="{}")
+    timestamp: Mapped[datetime] = mapped_column(DateTime, nullable=False)
+    sequence_num: Mapped[int] = mapped_column(Integer, nullable=False)
+
+    __table_args__ = (Index("ix_events_session_sequence", "session_id", "sequence_num"),)

openscript_sdk/events/store.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+
+import structlog
+from sqlalchemy import and_, select
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker
+
+from openscript_sdk.contracts.server_types import Event, EventType
+from openscript_sdk.events.models import EventRow
+
+logger = structlog.get_logger(__name__)
+
+
+class EventStore:
+    """Read/write interface for the append-only events table."""
+
+    def __init__(self, engine: AsyncEngine) -> None:
+        self._engine = engine
+        self._session_factory = async_sessionmaker(
+            engine, class_=AsyncSession, expire_on_commit=False
+        )
+
+    async def insert_events(self, events: list[Event]) -> None:
+        async with self._session_factory() as session:
+            for event in events:
+                row = EventRow(
+                    id=event.id,
+                    session_id=event.session_id,
+                    agent_id=event.agent_id,
+                    event_type=event.event_type.value,
+                    payload=event.payload,
+                    timestamp=event.timestamp,
+                    sequence_num=event.sequence_num,
+                )
+                session.add(row)
+            await session.commit()
+        logger.debug("events_inserted", count=len(events))
+
+    async def get_events(
+        self,
+        session_id: str,
+        event_types: list[EventType] | None = None,
+        after_sequence: int | None = None,
+        limit: int = 1000,
+    ) -> list[Event]:
+        async with self._session_factory() as session:
+            conditions = [EventRow.session_id == session_id]
+            if event_types:
+                conditions.append(EventRow.event_type.in_([et.value for et in event_types]))
+            if after_sequence is not None:
+                conditions.append(EventRow.sequence_num > after_sequence)
+
+            stmt = (
+                select(EventRow)
+                .where(and_(*conditions))
+                .order_by(EventRow.sequence_num)
+                .limit(limit)
+            )
+            result = await session.execute(stmt)
+            rows = result.scalars().all()
+
+        return [
+            Event(
+                id=row.id,
+                session_id=row.session_id,
+                agent_id=row.agent_id,
+                event_type=EventType(row.event_type),
+                payload=row.payload,
+                timestamp=row.timestamp,
+                sequence_num=row.sequence_num,
+            )
+            for row in rows
+        ]
+
+    async def stream_events(self, session_id: str) -> AsyncIterator[Event]:
+        events = await self.get_events(session_id=session_id)
+        for event in events:
+            yield event

openscript_sdk/events/writer.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from typing import Protocol
+
+import structlog
+
+from openscript_sdk.contracts.server_types import Event
+
+logger = structlog.get_logger(__name__)
+
+
+class EventSink(Protocol):
+    """Anything that can persist a batch of events."""
+
+    async def insert_events(self, events: list[Event]) -> None: ...
+
+
+class EventWriter:
+    """Async bounded queue that drains events to a sink in batches.
+
+    Uses DROP_OLDEST policy when the queue is full — the newest event
+    always wins. Every drop is logged with a running counter so ops
+    can alert on sustained back-pressure.
+    """
+
+    def __init__(
+        self,
+        store: EventSink,
+        max_queue_size: int = 10_000,
+        batch_size: int = 100,
+        flush_interval: float = 0.1,
+    ) -> None:
+        self._store = store
+        self._queue: asyncio.Queue[Event] = asyncio.Queue(maxsize=max_queue_size)
+        self._batch_size = batch_size
+        self._flush_interval = flush_interval
+        self._events_dropped_count: int = 0
+        self._task: asyncio.Task[None] | None = None
+        self._running = False
+
+    @property
+    def events_dropped_count(self) -> int:
+        return self._events_dropped_count
+
+    @property
+    def queue_size(self) -> int:
+        return self._queue.qsize()
+
+    async def start(self) -> None:
+        self._running = True
+        self._task = asyncio.create_task(self._drain_loop())
+
+    async def stop(self) -> None:
+        self._running = False
+        if self._task is not None:
+            await self._task
+            self._task = None
+
+    async def write(self, event: Event) -> None:
+        try:
+            self._queue.put_nowait(event)
+        except asyncio.QueueFull:
+            with contextlib.suppress(asyncio.QueueEmpty):
+                self._queue.get_nowait()
+            self._events_dropped_count += 1
+            logger.warning(
+                "event_queue_full_drop_oldest",
+                events_dropped_count=self._events_dropped_count,
+                session_id=event.session_id,
+            )
+            self._queue.put_nowait(event)
+
+    async def _drain_loop(self) -> None:
+        while self._running or not self._queue.empty():
+            batch: list[Event] = []
+
+            try:
+                event = await asyncio.wait_for(self._queue.get(), timeout=self._flush_interval)
+                batch.append(event)
+            except TimeoutError:
+                if not self._running:
+                    break
+                continue
+
+            while len(batch) < self._batch_size:
+                try:
+                    batch.append(self._queue.get_nowait())
+                except asyncio.QueueEmpty:
+                    break
+
+            if batch:
+                try:
+                    await self._store.insert_events(batch)
+                except Exception:
+                    logger.exception(
+                        "event_writer_flush_failed",
+                        batch_size=len(batch),
+                    )