openscript-sdk 0.1.0__py3-none-any.whl

openscript_sdk/policies/toxicity.py

@@ -0,0 +1,247 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import structlog
+
+from openscript_sdk.contracts.interceptor import BasePolicy
+from openscript_sdk.contracts.server_types import Event, EventType
+from openscript_sdk.contracts.types import ActionContext, FailureMode, InterceptorDecision
+from openscript_sdk.interceptors.threat import _extract_text
+from openscript_sdk.policies import normalize
+
+if TYPE_CHECKING:
+    from openscript_sdk.events.writer import EventWriter
+
+logger = structlog.get_logger(__name__)
+
+# ---------------------------------------------------------------------------
+# Pattern bank
+# Each entry: (compiled_regex, category_name, weight)
+# Weights are additive within a category, capped at _CATEGORY_CAP; the total
+# is the cross-category sum capped at 1.0 — same scoring model as
+# PromptInjectionPolicy. Patterns are structural (verb + target constructs)
+# rather than word lists, to keep false positives on quoted or reported
+# speech manageable.
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class _Pattern:
+    regex: re.Pattern[str]
+    category: str
+    weight: float
+
+
+def _p(pattern: str, category: str, weight: float) -> _Pattern:
+    return _Pattern(re.compile(pattern, re.IGNORECASE | re.MULTILINE), category, weight)
+
+
+# Weight tiers, on the same scale PromptInjectionPolicy uses. Where a line
+# sits is a product decision as much as a detection one: a direct threat is
+# refused, while intimidation and insult are recorded and passed on, because a
+# gateway that blocks every unkind sentence stops being used. The evals in
+# evals/toxicity.jsonl name which rows are meant to land in which band.
+_DECISIVE = 0.60  # blocks on its own
+_STRONG = 0.50  # blocks on its own, at the line
+_MODERATE = 0.45  # recorded, needs a second signal to block
+_WEAK = 0.30  # recorded only
+
+_PATTERNS: list[_Pattern] = [
+    # Threatening / violent content directed at a person
+    _p(
+        r"\bi\s*(?:'|a)?m\s+going\s+to\s+(kill|hurt|shoot|stab|beat)\s+(you|him|her|them)\b",
+        "violence",
+        _DECISIVE,
+    ),
+    _p(r"\bi\s+will\s+(kill|hurt|murder|shoot|stab)\s+(you|him|her|them)\b", "violence", _DECISIVE),
+    _p(r"\byou\s+(all\s+)?deserve\s+to\s+(die|suffer)\b", "violence", _STRONG),
+    # Intimidation: a threat in context, an ordinary sentence out of it.
+    _p(r"\bi\s+know\s+where\s+you\s+live\b", "violence", _MODERATE),
+    _p(r"\bwatch\s+your\s+back\b", "violence", _WEAK),
+    # Hate speech — dehumanizing constructs aimed at groups
+    _p(
+        r"\b(those|these)\s+people\s+are\s+(all\s+)?(vermin|subhuman|animals|cockroaches|a\s+disease)\b",
+        "hate_speech",
+        _STRONG,
+    ),
+    _p(
+        r"\bshould\s+(all\s+)?be\s+(exterminated|eradicated|wiped\s+out)\b",
+        "hate_speech",
+        _DECISIVE,
+    ),
+    _p(r"\bgo\s+back\s+to\s+(your|their)\s+country\b", "hate_speech", _MODERATE),
+    _p(
+        r"\b(immigrants?|foreigners?|refugees?|migrants?)\b.{0,40}?"
+        r"\b(ruining|destroying|infesting|invading|overrunning)\b.{0,40}?"
+        r"\b(this|our|the)\s+(country|nation|society)\b",
+        "hate_speech",
+        _STRONG,
+    ),
+    _p(r"\bneed\s+to\s+be\s+dealt\s+with\b", "hate_speech", _MODERATE),
+    _p(
+        r"\b(people|they|those)\s+like\s+(that|them|those|him|her)\s+are\s+(a\s+)?"
+        r"(plague|disease|cancer|vermin|scum|parasites?|infestation)\b",
+        "hate_speech",
+        _STRONG,
+    ),
+    _p(
+        r"\bshould\s+(all\s+)?be\s+(removed|purged|cleansed|driven\s+out)\s+from\s+"
+        r"(society|the\s+country|here)\b",
+        "hate_speech",
+        _DECISIVE,
+    ),
+    _p(r"\bdon'?t\s+deserve\s+to\s+(live|exist)\b", "hate_speech", _STRONG),
+    # Harassment directed at the reader
+    _p(
+        r"\byou\s+are\s+(a\s+)?(worthless|pathetic|disgusting)(\s+(person|human|being))?\b",
+        "harassment",
+        _STRONG,
+    ),
+    _p(r"\bnobody\s+(likes|loves|wants)\s+you\b", "harassment", _WEAK),
+    _p(
+        r"\bdo\s+(everyone|us\s+all|the\s+world)\s+a\s+favou?r\s+and\s+"
+        r"(disappear|die|leave\s+forever|kill)\b",
+        "harassment",
+        _DECISIVE,
+    ),
+    _p(r"\bkill\s+yourself\b|\bkys\b", "harassment", 0.65),
+    _p(
+        r"\bbetter\s+off\s+(not\s+existing|dead|without\s+(you|him|her|them))\b",
+        "harassment",
+        _DECISIVE,
+    ),
+    _p(r"\bregrets?\s+ever\s+(meeting|crossing|knowing)\s+me\b", "violence", _STRONG),
+    # Self-harm expressions. Deliberately below the block line: the answer to
+    # someone saying this is not a refusal, it is the crisis resources the demo
+    # surfaces off the signal. See site/public/pipeline.py.
+    _p(r"\b(kill|hurt|harm)\s+myself\b", "self_harm", _STRONG),
+    _p(r"\bend\s+my\s+(own\s+)?life\b", "self_harm", _STRONG),
+    _p(r"\bi\s+want\s+to\s+die\b", "self_harm", _MODERATE),
+    _p(r"\bsuicide\s+(note|plan|method)\b", "self_harm", _STRONG),
+]
+
+
+_CATEGORY_CAP = 0.7  # max a single category can contribute to the total score
+
+
+def score_patterns(text: str) -> tuple[float, dict[str, float]]:
+    """Score one string, exactly as written.
+
+    signals maps category → capped contribution (violence, hate_speech,
+    harassment, self_harm).
+    """
+    category_totals: dict[str, float] = {}
+    for pat in _PATTERNS:
+        if pat.regex.search(text):
+            current = category_totals.get(pat.category, 0.0)
+            category_totals[pat.category] = min(_CATEGORY_CAP, current + pat.weight)
+
+    total = min(1.0, sum(category_totals.values()))
+    return total, category_totals
+
+
+def score_toxicity(text: str) -> tuple[float, dict[str, float]]:
+    """Return (total_score, signals) for the strongest view of the given text.
+
+    Normalized views are scored too: a threat written with look-alike letters
+    is still a threat. See openscript_sdk/policies/normalize.py.
+    """
+    result = normalize.scan(text, score_patterns)
+    return result.risk, result.signals
+
+
+class ToxicityPolicy(BasePolicy):
+    """Scores input text for toxic content and blocks on threshold breach.
+
+    Detects threatening/violent content, dehumanizing hate speech,
+    harassment, and self-harm expressions via a structural pattern bank.
+    Runs in before_action; after_action is a pass-through. A local model
+    backend arrives with the [ml] extra (roadmap §14); pattern scoring is
+    the only backend today.
+
+    Results land in context.metadata["toxicity"] using the standardized
+    shape:
+      {"risk": float, "category": "toxicity", "signals": {...},
+       "flagged": bool, "threshold": float}
+    """
+
+    failure_mode: FailureMode = FailureMode.FAIL_CLOSED
+
+    def __init__(
+        self,
+        threshold: float = 0.5,
+        writer: EventWriter | None = None,
+    ) -> None:
+        if not 0.0 <= threshold <= 1.0:
+            raise ValueError(f"threshold must be in [0, 1], got {threshold}")
+        self._threshold = threshold
+        self._writer = writer
+        self._sequence_counters: dict[str, int] = {}
+
+    async def before_action(self, context: ActionContext) -> ActionContext:
+        text = _extract_text(context.input_data)
+        result = normalize.scan(text, score_patterns)
+        score, signals = result.risk, result.signals
+        flagged = score >= self._threshold
+
+        context.metadata["toxicity"] = {
+            "risk": round(score, 4),
+            "category": "toxicity",
+            "signals": {k: round(v, 4) for k, v in signals.items()},
+            "flagged": flagged,
+            "threshold": self._threshold,
+            "obfuscation": result.markers,
+            "matched_view": result.view,
+        }
+
+        if flagged:
+            top_signal = max(signals, key=lambda k: signals[k]) if signals else "unknown"
+            reason = (
+                f"toxicity score {score:.2f} >= threshold {self._threshold} "
+                f"(top signal: {top_signal})"
+            )
+            context.decision = InterceptorDecision.DENY
+            context.decision_reason = reason
+            logger.warning(
+                "toxicity_detected",
+                session_id=context.session_id,
+                agent_id=context.agent_id,
+                score=round(score, 4),
+                signals=list(signals.keys()),
+            )
+            if self._writer is not None:
+                await self._emit_toxicity_event(context, score, signals, reason)
+
+        return context
+
+    async def _emit_toxicity_event(
+        self,
+        context: ActionContext,
+        score: float,
+        signals: dict[str, float],
+        reason: str,
+    ) -> None:
+        seq = self._next_sequence(context.session_id)
+        event = Event(
+            session_id=context.session_id,
+            agent_id=context.agent_id,
+            event_type=EventType.POLICY_EVALUATED,
+            payload={
+                "policy": "toxicity_check",
+                "score": round(score, 4),
+                "signals": signals,
+                "reason": reason,
+                "action": context.action,
+                "threshold": self._threshold,
+            },
+            sequence_num=seq,
+        )
+        await self._writer.write(event)  # type: ignore[union-attr]
+
+    def _next_sequence(self, session_id: str) -> int:
+        count = self._sequence_counters.get(session_id, 0) + 1
+        self._sequence_counters[session_id] = count
+        return count

openscript_sdk/server/__init__.py

@@ -0,0 +1 @@
+"""OpenScript Server -- FastAPI application"""

openscript_sdk/server/app.py

@@ -0,0 +1,153 @@
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator
+
+from dotenv import load_dotenv
+
+load_dotenv()
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+import structlog
+from fastapi import Depends, FastAPI, Query, Response
+from fastapi.staticfiles import StaticFiles
+from prometheus_client import CONTENT_TYPE_LATEST, generate_latest
+from sqlalchemy.ext.asyncio import create_async_engine
+
+from openscript_sdk.contracts.server_types import EventType
+from openscript_sdk.contracts.session_graph import SessionGraph
+from openscript_sdk.events.approvals import ApprovalStore, InMemoryApprovalStore, RedisApprovalStore
+from openscript_sdk.events.store import EventStore
+from openscript_sdk.events.writer import EventWriter
+from openscript_sdk.server.auth import require_api_key
+from openscript_sdk.server.guard import load_checkpoints
+from openscript_sdk.server.routers import approvals as approvals_router
+from openscript_sdk.server.routers import guard as guard_router
+from openscript_sdk.server.routers import sessions as sessions_router
+from openscript_sdk.server.routers import sse as sse_router
+from openscript_sdk.server.routers import threat as threat_router
+
+logger = structlog.get_logger(__name__)
+
+_STATIC_DIR = Path(__file__).parent / "static" / "dashboard"
+
+
+def _database_url() -> str:
+    return os.environ.get(
+        "DATABASE_URL", "postgresql+asyncpg://openscript:openscript@localhost:5432/openscript"
+    )
+
+
+def _approval_store() -> ApprovalStore:
+    redis_url = os.environ.get("REDIS_URL", "")
+    if redis_url:
+        return RedisApprovalStore(redis_url)
+    logger.warning(
+        "approval_store_in_memory",
+        hint="set REDIS_URL so SDK clients in other processes share this store",
+    )
+    return InMemoryApprovalStore()
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    db_url = _database_url()
+    engine = create_async_engine(db_url, pool_size=10, max_overflow=20)
+    app.state.engine = engine
+    app.state.event_store = EventStore(engine)
+    app.state.approval_store = _approval_store()
+    # The policies behind /v1/guard. Unset, the endpoint answers 503; set and
+    # invalid, the server does not start. The pipeline shares the approval
+    # store with /v1/approvals, so an approval it asks for is decided there.
+    guard_config = os.environ.get("OPENSCRIPT_GUARD_CONFIG", "")
+    writer: EventWriter | None = None
+    app.state.guard = None
+    if guard_config:
+        writer = EventWriter(app.state.event_store)
+        await writer.start()
+        app.state.guard = load_checkpoints(
+            guard_config, writer=writer, approval_store=app.state.approval_store
+        )
+        logger.info("guard_configured", config=guard_config, actions=sorted(app.state.guard))
+    logger.info("server_started", database=db_url.split("@")[-1])
+    yield
+    if writer is not None:
+        await writer.stop()
+    await engine.dispose()
+    logger.info("server_stopped")
+
+
+app = FastAPI(title="OpenScript Server", version="0.1.0", lifespan=lifespan)
+
+# Routers
+app.include_router(threat_router.router)
+app.include_router(sessions_router.router)
+app.include_router(sse_router.router)
+app.include_router(approvals_router.router)
+app.include_router(guard_router.router)
+
+# Dashboard static files — served at /dashboard/
+if _STATIC_DIR.exists():
+    app.mount(
+        "/dashboard",
+        StaticFiles(directory=str(_STATIC_DIR), html=True),
+        name="dashboard",
+    )
+
+
+def _get_event_store() -> EventStore:
+    return app.state.event_store
+
+
+@app.get("/health")
+async def health() -> dict[str, str]:
+    return {"status": "ok"}
+
+
+# Auth-gated like /v1/reports — scrapers present the API key
+@app.get("/metrics", dependencies=[Depends(require_api_key)])
+async def metrics() -> Response:
+    return Response(generate_latest(), media_type=CONTENT_TYPE_LATEST)
+
+
+@app.get("/events/{session_id}", dependencies=[Depends(require_api_key)])
+async def get_events(
+    session_id: str,
+    event_type: EventType | None = None,
+    after_sequence: int | None = None,
+    limit: int = Query(default=1000, le=10_000),
+    store: EventStore = Depends(_get_event_store),
+) -> dict:
+    event_types = [event_type] if event_type else None
+    events = await store.get_events(
+        session_id=session_id,
+        event_types=event_types,
+        after_sequence=after_sequence,
+        limit=limit,
+    )
+    return {
+        "session_id": session_id,
+        "count": len(events),
+        "events": [e.model_dump(mode="json") for e in events],
+    }
+
+
+@app.get("/sessions/{session_id}/graph", dependencies=[Depends(require_api_key)])
+async def get_session_graph(
+    session_id: str,
+    store: EventStore = Depends(_get_event_store),
+) -> dict:
+    graph = await SessionGraph.from_store(session_id, store)
+    return {
+        "session_id": session_id,
+        "node_count": len(graph.nodes),
+        "edge_count": len(graph.edges),
+        "nodes": [
+            {"id": n.id, "node_type": n.node_type, "sequence_num": n.event.sequence_num}
+            for n in sorted(graph.nodes.values(), key=lambda n: n.event.sequence_num)
+        ],
+        "edges": [
+            {"source": e.source_id, "target": e.target_id, "type": e.edge_type} for e in graph.edges
+        ],
+    }

openscript_sdk/server/auth.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+import os
+
+from fastapi import HTTPException, Security
+from fastapi.security import APIKeyHeader
+
+_API_KEY_HEADER = APIKeyHeader(name="X-API-KEY", auto_error=False)
+
+
+async def require_api_key(
+    api_key: str | None = Security(_API_KEY_HEADER),
+) -> str:
+    expected = os.environ.get("OPENSCRIPT_API_KEY")
+    if not expected:
+        raise HTTPException(status_code=500, detail="OPENSCRIPT_API_KEY not configured on server")
+    if api_key != expected:
+        raise HTTPException(status_code=401, detail="Invalid or missing API key")
+    return api_key

openscript_sdk/server/guard.py

@@ -0,0 +1,126 @@
+"""The policy pipeline behind /v1/guard, for clients that are not Python.
+
+A Python caller wraps its agent in SecureAgent and its tools in SecureTool, and
+the pipeline runs before and after the call in one process. A client in another
+language cannot hand the server its agent, so the server runs the two phases as
+two requests instead: the client asks about the input, runs its agent (or tool)
+on what came back, then asks about the output. The phases are SecureAgent's own
+(``_run_before`` / ``_run_after``), so failure modes, approvals and refusals mean
+here exactly what they mean in Python.
+
+The config names two lists, because a Python program builds two: the one it
+gives SecureAgent and the one it gives each SecureTool.
+
+    agent:                 # action "invoke": the caller's input, the agent's output
+      prompt_injection: {threshold: 0.5}
+      secrets: {mode: redact}
+    tool:                  # action "tool_call": a tool's name and arguments, its result
+      tool_firewall: {rules_path: tools.yaml}   # relative to this file
+
+Each list is built once, at startup, so a policy that remembers between calls
+(SessionTaintPolicy) remembers across requests, in this process only.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+from openscript_sdk.contracts.interceptor import Policy, StreamGuard
+from openscript_sdk.contracts.types import ActionContext
+from openscript_sdk.middleware.middleware import SecureAgent
+from openscript_sdk.policies.config import load_policies
+
+#: The config's sections, by the action each one is asked about. A streamed
+#: answer is an agent's, so it is held to the agent's list, as in Python.
+SECTIONS = {"invoke": "agent", "stream": "agent", "tool_call": "tool"}
+
+
+class Checkpoint(SecureAgent):
+    """SecureAgent's two phases, run one at a time, with no agent between them."""
+
+    async def check_input(self, context: ActionContext, approval_id: str) -> ActionContext:
+        with self._trace(context):
+            context, _ = await self._run_before(context, approval_id)
+            return self._finalize(context)
+
+    async def check_output(self, context: ActionContext) -> ActionContext:
+        # No approval is redeemed here. The id was spent on the input, and none
+        # of the built-in policies asks for one on the way out; a custom policy
+        # that does gets a fresh approval, as a separate action would.
+        with self._trace(context):
+            context = await self._run_after(context)
+            return self._finalize(context)
+
+    def stream_guards(self) -> list[StreamGuard]:
+        """The incremental scanners of the policies that have one (secrets, PII)."""
+        guards: list[StreamGuard] = []
+        for policy in self._policies:
+            factory = getattr(policy, "stream_guard", None)
+            guard = factory() if callable(factory) else None
+            if guard is not None:
+                guards.append(guard)
+        return guards
+
+    async def scan_stream(self, context: ActionContext, text: str, final: bool) -> str:
+        """One pass of guarded streaming over the text a client is holding back.
+
+        SecureAgent's own _apply_guards: the guards are stateless over the
+        text they are given, so the client keeps the held tail and sends it
+        with each new chunk, and the server needs no memory of the stream.
+        A deny raises ActionBlockedError, after the audit hears of it.
+        """
+        with self._trace(context):
+            return await self._apply_guards(text, self.stream_guards(), context, final)
+
+
+def _resolve_rules_path(policies: dict[str, Any], base: Path) -> dict[str, Any]:
+    firewall = policies.get("tool_firewall")
+    if isinstance(firewall, dict) and isinstance(firewall.get("rules_path"), str):
+        path = Path(firewall["rules_path"])
+        if not path.is_absolute():
+            policies = {**policies, "tool_firewall": {**firewall, "rules_path": str(base / path)}}
+    return policies
+
+
+def load_checkpoints(
+    path: str | Path, *, writer: Any | None = None, approval_store: Any | None = None
+) -> dict[str, Checkpoint]:
+    """Build one Checkpoint per section of the config at *path*, keyed by action.
+
+    Raises ValueError on an unknown section, an empty config, or anything
+    load_policies refuses. A server that cannot build what it was told to
+    build should not start.
+    """
+    path = Path(path)
+    with open(path) as fh:
+        raw = yaml.safe_load(fh) or {}
+    if not isinstance(raw, dict):
+        raise ValueError(f"{path}: expected a mapping with 'agent' and/or 'tool'")
+    unknown = set(raw) - set(SECTIONS.values())
+    if unknown:
+        raise ValueError(f"{path}: unknown section(s) {sorted(unknown)}; expected 'agent', 'tool'")
+
+    by_section: dict[str, Checkpoint] = {}
+    for section in dict.fromkeys(SECTIONS.values()):
+        policies = raw.get(section)
+        if policies is None:
+            continue
+        if not isinstance(policies, dict) or not policies:
+            raise ValueError(f"{path}: section '{section}' names no policies")
+        built: list[Policy] = load_policies(
+            _resolve_rules_path(policies, path.parent), writer=writer
+        )
+        by_section[section] = Checkpoint(
+            agent=None, policies=built, approval_store=approval_store, writer=writer
+        )
+    # One pipeline per section, shared by the actions asked of it: what a
+    # policy remembers is remembered once.
+    checkpoints = {
+        action: by_section[section] for action, section in SECTIONS.items() if section in by_section
+    }
+    if not checkpoints:
+        raise ValueError(f"{path}: no 'agent' or 'tool' section")
+    return checkpoints

openscript_sdk/server/guard_example.yaml

@@ -0,0 +1,55 @@
+# Example config for /v1/guard: the policies a client in another language
+# (clients/java) reaches through the server. Point the server at it with
+#
+#   OPENSCRIPT_GUARD_CONFIG=openscript_sdk/server/guard_example.yaml uvicorn openscript_sdk.server.app:app
+#
+# Two lists, as a Python program builds two. Each takes exactly what
+# load_policies() takes, in the same order-is-significant form. `audit` writes
+# to the server's event store, so the server needs its Postgres.
+
+# Action "invoke": the input a client is about to give its agent, and what the
+# agent returned. What SecureAgent(agent, policies=...) would run.
+agent:
+  prompt_injection:
+    threshold: 0.5
+  toxicity:
+    threshold: 0.5
+  harmful_request:
+    threshold: 0.5
+  secrets:
+    mode: redact          # masked before the model is given it
+  pii:
+    mode: redact          # masked before the caller gets it back
+  audit: {}               # last, so its events carry the final risk score
+
+# Action "tool_call": a tool's name and arguments, and what it returned. What
+# SecureTool(fn, policies=...) would run around each tool.
+tool:
+  tool_firewall:
+    # rules_path works too, and is read relative to this file.
+    rules:
+      default_deny: true
+      rules:
+        fetch_page:
+          allowed_roles: ["*"]
+          args:
+            # The whole URL must match. A redirect the tool follows is not
+            # something this rule sees.
+            url: {pattern: 'https://docs\.example\.com/.*'}
+        send_email:
+          allowed_roles: ["*"]
+          unlisted_args: deny
+          args:
+            to: {required: true, pattern: '[^@\s]+@example\.com'}
+            body: {}
+        wire_money:
+          allowed_roles: ["finance"]
+          requires_approval: true
+          args:
+            amount: {max: 10000}
+  # Once a session has run fetch_page, send_email waits for a person. What a
+  # session has read is remembered by the server process, per session id.
+  session_taint:
+    sources: [fetch_page]
+    sinks: [send_email, wire_money]
+  audit: {}

openscript_sdk/server/routers/approvals.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from fastapi import APIRouter, Depends, HTTPException, Request
+from pydantic import BaseModel
+
+from openscript_sdk.contracts.server_types import Event, EventType
+from openscript_sdk.events.approvals import ApprovalStore
+from openscript_sdk.server.auth import require_api_key
+
+router = APIRouter(prefix="/v1", tags=["approvals"])
+
+
+class ApprovalDecisionRequest(BaseModel):
+    approved: bool
+    decided_by: str = ""
+    #: The decider's reason. Returned on the record and written to the event.
+    note: str = ""
+
+
+def _get_store(request: Request) -> ApprovalStore:
+    return request.app.state.approval_store
+
+
+@router.get("/approvals", dependencies=[Depends(require_api_key)])
+async def list_pending_approvals(store: ApprovalStore = Depends(_get_store)) -> dict:
+    """List approval records awaiting a human decision."""
+    pending = await store.list_pending()
+    return {
+        "count": len(pending),
+        "approvals": [record.to_dict() for record in pending],
+    }
+
+
+@router.post("/approvals/{approval_id}/decide", dependencies=[Depends(require_api_key)])
+async def decide_approval(
+    approval_id: str,
+    req: ApprovalDecisionRequest,
+    request: Request,
+    store: ApprovalStore = Depends(_get_store),
+) -> dict:
+    """Approve or deny a pending approval and emit APPROVAL_RESOLVED."""
+    try:
+        record = await store.decide(approval_id, req.approved, req.decided_by, req.note)
+    except ValueError as exc:
+        raise HTTPException(status_code=409, detail=str(exc)) from exc
+    if record is None:
+        raise HTTPException(status_code=404, detail=f"approval '{approval_id}' not found")
+
+    event_store = getattr(request.app.state, "event_store", None)
+    if event_store is not None:
+        await event_store.insert_events(
+            [
+                Event(
+                    session_id=record.session_id,
+                    agent_id=record.agent_id,
+                    event_type=EventType.APPROVAL_RESOLVED,
+                    payload={
+                        "approval_id": record.approval_id,
+                        "action": record.action,
+                        "status": record.status.value,
+                        "decided_by": record.decided_by,
+                        "note": record.decision_note,
+                    },
+                    sequence_num=0,  # decided outside the session's sequence
+                )
+            ]
+        )
+
+    return record.to_dict()