revive-sdk 0.1.0__py3-none-any.whl

revive/__init__.py

@@ -0,0 +1,45 @@
+"""Revive — agent recovery control plane SDK.
+
+Primary entrypoint (talks to the hosted control plane, stdlib-only, no deps):
+
+    from revive import ReviveClient
+    revive = ReviveClient("https://revivelabs.app", api_key="rv_live_…")
+    result = revive.protect_action(run_id=..., connection_id=..., action_key=...,
+                                   execute=lambda: do_the_side_effect())
+
+When a protected action's credential dies mid-run, Revive classifies the
+death, parks the run, routes a single-use reauthorization to the bound
+account, rotates the credential lease, and resumes the same logical run
+without duplicating a side effect that already committed.
+
+Framework adapters live under revive.adapters (OpenAI Agents, Anthropic tool
+use, LangGraph). The local self-hosted engine (Engine, CheckpointStore, …)
+remains available for running the park/resume loop in-process.
+"""
+# Hosted SDK entrypoint — the primary developer API.
+from .client import (AmbiguousCommitError, ParkedRun, ReviveClient,
+                     ReviveParkedError, idempotency_key)
+
+from .checkpoint import Checkpoint, CheckpointStore
+from .classifier import ClassifierResult, Verdict, classify
+from .engine import (AmbiguousSideEffect, Completed, Engine, NeedsApproval,
+                     Parked, StaleCredentialGeneration, Step, StepContext,
+                     WrongRecoveryIdentity)
+from .providers import AuthError, Provider, Token, TokenError
+from .rendezvous import Kind, Rendezvous, console_channel, webhook_channel
+from .postgres import PostgresCheckpointStore
+from .reporter import Reporter
+
+__all__ = [
+    "ReviveClient", "ReviveParkedError", "ParkedRun", "AmbiguousCommitError", "idempotency_key",
+    "Engine", "Step", "StepContext", "Parked", "Completed", "NeedsApproval",
+    "AmbiguousSideEffect",
+    "WrongRecoveryIdentity", "StaleCredentialGeneration",
+    "Provider", "Token", "TokenError", "AuthError",
+    "CheckpointStore", "Checkpoint",
+    "PostgresCheckpointStore",
+    "Reporter",
+    "classify", "ClassifierResult", "Verdict",
+    "Rendezvous", "Kind", "console_channel", "webhook_channel",
+]
+__version__ = "0.1.0"

revive/adapters/__init__.py

@@ -0,0 +1,5 @@
+"""Framework adapters for LangGraph and Temporal."""
+
+from .temporal import RecoveryGate, ReauthorizationSignal, TemporalRecoveryClient
+
+__all__ = ["RecoveryGate", "ReauthorizationSignal", "TemporalRecoveryClient"]

revive/adapters/anthropic_tools.py

@@ -0,0 +1,60 @@
+"""Anthropic tool-use adapter (adapter preview).
+
+Guard the tool-execution side of an Anthropic agent loop (Claude API tool use
+or the Claude Agent SDK): each tool_use block that mutates an external system
+becomes a protected action in the Revive ledger.
+
+    from revive.client import ReviveClient
+    from revive.adapters.anthropic_tools import ReviveToolGuard
+
+    revive = ReviveClient(base_url="https://console.revivelabs.app", api_key="rv_live_…")
+    guard = ReviveToolGuard(revive, connection_id="conn_…", protected={"send_email", "create_ticket"})
+
+    # inside the agent loop, for each tool_use content block:
+    result = guard.run(run_id=thread_id, tool_name=block.name, tool_input=block.input,
+                       execute=lambda: dispatch_tool(block.name, block.input))
+
+Committed replays return the stored result without re-dispatching; a dead
+credential raises ReviveParkedError carrying the recovery URL, which the loop
+should return to the model/user as the tool result.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, Callable, Iterable, Optional
+
+from revive.client import ReviveClient
+
+
+class ReviveToolGuard:
+    def __init__(
+        self,
+        client: ReviveClient,
+        *,
+        connection_id: str,
+        protected: Optional[Iterable[str]] = None,
+        lease_generation: Optional[int] = None,
+    ):
+        self.client = client
+        self.connection_id = connection_id
+        self.protected = set(protected) if protected is not None else None
+        self.lease_generation = lease_generation
+
+    def is_protected(self, tool_name: str) -> bool:
+        return self.protected is None or tool_name in self.protected
+
+    def run(self, *, run_id: str, tool_name: str, tool_input: Any, execute: Callable[[], Any]) -> Any:
+        if not self.is_protected(tool_name):
+            return execute()
+        payload = json.dumps(tool_input, sort_keys=True, default=repr)
+        derived = hashlib.sha256(f"{run_id}:{tool_name}:{payload}".encode()).hexdigest()
+        return self.client.protect_action(
+            run_id=run_id,
+            connection_id=self.connection_id,
+            action_key=tool_name,
+            idem_key=derived,
+            lease_generation=self.lease_generation,
+            execute=execute,
+        )

revive/adapters/langgraph.py

@@ -0,0 +1,89 @@
+"""LangGraph adapter.
+
+LangGraph already ships durable checkpointing and `interrupt()` / `Command(resume=)`
+for human-in-the-loop. What it lacks is the auth-death TRIGGER and the re-consent
++ credential rotation. This adapter supplies that trigger, reusing LangGraph's own durable
+pause/resume — so an existing LangGraph agent gains dead-reauth-resume with a
+single call inside its nodes.
+
+    from revive.adapters.langgraph import revive_refresh
+
+    def files_node(state):
+        try:
+            data = call_graph_api(state["access_token"])
+        except Unauthorized:
+            tok = revive_refresh(provider, state["refresh_token"], SCOPES)  # pauses if dead
+            state.update(access_token=tok.access_token, refresh_token=tok.refresh_token)
+            data = call_graph_api(tok.access_token)
+        ...
+
+When the refresh token is dead, `revive_refresh` calls LangGraph's `interrupt()`,
+which durably parks the run via the configured checkpointer. The driver routes
+the re-consent and resumes with `Command(resume={"refresh_token": <new>})`; the
+node re-executes, `interrupt()` returns that payload, and the fresh credential
+generation is used by the same logical thread.
+"""
+from __future__ import annotations
+
+from ..classifier import ClassifierResult, classify
+from ..providers import Provider, Token, TokenError
+
+try:
+    from langgraph.types import interrupt  # type: ignore
+    HAS_LANGGRAPH = True
+except Exception:  # pragma: no cover - optional dependency
+    HAS_LANGGRAPH = False
+
+    def interrupt(value):  # type: ignore
+        raise RuntimeError("langgraph is not installed: pip install langgraph")
+
+
+def reconsent_payload(result: ClassifierResult, scopes) -> dict:
+    return {
+        "kind": "reconsent",
+        "code": result.code,
+        "title": result.title,
+        "reason": result.reason,
+        "remediation": result.remediation,
+        "scopes": list(scopes),
+        "confidence": result.confidence,
+    }
+
+
+def revive_refresh(provider: Provider, refresh_token: str, scopes=(),
+                   credential_resolver=None) -> Token:
+    """Refresh; on a truly-dead refresh token, durably pause for re-consent and
+    resume with the rotated credential. A still-refreshable error refreshes
+    silently; a transient error is re-raised for the framework's retry policy.
+
+    Resume payload contract — the Command payload is persisted in LangGraph's
+    checkpoint history, so it must stay OPAQUE:
+
+        Command(resume={"connection_id": "...", "lease_generation": 2})
+
+    `credential_resolver(connection_id, lease_generation)` is supplied by the
+    host process and returns the refresh token from the credential store; the
+    raw token never enters workflow history. Passing a raw ``refresh_token`` in
+    the resume payload is supported for local sandbox drills only.
+    """
+    try:
+        return provider.refresh(refresh_token)
+    except TokenError as te:
+        result = classify(te.payload)
+        if not result.needs_human:
+            raise
+        # durable pause via LangGraph's checkpointer
+        reply = interrupt(reconsent_payload(result, scopes))
+        if isinstance(reply, dict) and reply.get("connection_id"):
+            if credential_resolver is None:
+                raise RuntimeError(
+                    "resume payload references a connection, but no "
+                    "credential_resolver was configured"
+                )
+            new_refresh = credential_resolver(
+                reply["connection_id"], int(reply.get("lease_generation") or 1)
+            )
+        else:
+            # Sandbox-only fallback: raw token in the resume payload.
+            new_refresh = reply["refresh_token"] if isinstance(reply, dict) else reply
+        return provider.refresh(new_refresh)

revive/adapters/openai_agents.py

@@ -0,0 +1,63 @@
+"""OpenAI Agents SDK adapter (adapter preview).
+
+Wrap a function tool so every invocation is a protected action in the Revive
+ledger: replays of committed calls return the stored result, uncertain calls
+demand reconciliation, and credential failures park the run with a recovery
+case instead of crashing the agent.
+
+    from agents import function_tool
+    from revive.client import ReviveClient
+    from revive.adapters.openai_agents import revive_tool
+
+    revive = ReviveClient(base_url="https://console.revivelabs.app", api_key="rv_live_…")
+
+    @function_tool
+    @revive_tool(revive, connection_id="conn_…", run_id_from="run_id")
+    def send_followup_email(run_id: str, to: str, subject: str) -> dict:
+        ...  # real provider call
+
+The wrapped function raises ReviveParkedError when the credential dies; the
+agent loop should surface parked.recovery_url to the account owner.
+"""
+
+from __future__ import annotations
+
+import functools
+import json
+from typing import Any, Callable, Optional
+
+from revive.client import ReviveClient
+
+
+def revive_tool(
+    client: ReviveClient,
+    *,
+    connection_id: str,
+    run_id_from: str = "run_id",
+    action_key: Optional[str] = None,
+    lease_generation: Optional[int] = None,
+):
+    """Decorator: one exactly-once ledger entry per (run, tool, arguments)."""
+
+    def decorate(func: Callable[..., Any]) -> Callable[..., Any]:
+        @functools.wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            run_id = str(kwargs.get(run_id_from) or "")
+            if not run_id:
+                raise ValueError(f"revive_tool requires the '{run_id_from}' keyword argument")
+            key_material = json.dumps({"args": [repr(a) for a in args], "kwargs": {k: repr(v) for k, v in sorted(kwargs.items())}}, sort_keys=True)
+            import hashlib
+
+            derived = hashlib.sha256(f"{run_id}:{func.__name__}:{key_material}".encode()).hexdigest()
+            return client.protect_action(
+                run_id=run_id,
+                connection_id=connection_id,
+                action_key=action_key or func.__name__,
+                idem_key=derived,
+                lease_generation=lease_generation,
+                execute=lambda: func(*args, **kwargs),
+            )
+
+        return wrapper
+
+    return decorate

revive/adapters/temporal.py

@@ -0,0 +1,67 @@
+"""Temporal signal adapter for Revive recovery rendezvous.
+
+Activities detect/classify credential failures. A workflow parks by waiting on a
+RecoveryGate. The OAuth callback signals the existing workflow ID with a new
+opaque lease reference; raw refresh tokens do not enter workflow history.
+"""
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any, Optional
+
+SIGNAL_NAME = "revive_reauthorized"
+
+try:
+    from temporalio import workflow  # type: ignore
+    HAS_TEMPORAL = True
+except ImportError:  # pragma: no cover - optional dependency
+    HAS_TEMPORAL = False
+
+    class _WorkflowFallback:
+        @staticmethod
+        def signal(*args, **kwargs):
+            def decorate(fn):
+                return fn
+            return decorate
+
+        @staticmethod
+        async def wait_condition(predicate):
+            raise RuntimeError("temporalio is not installed: pip install 'revive-sidecar[temporal]'")
+
+    workflow = _WorkflowFallback()  # type: ignore
+
+
+@dataclass(frozen=True)
+class ReauthorizationSignal:
+    recovery_case_id: str
+    connection_id: str
+    lease_generation: int
+    provider: str
+
+
+class RecoveryGate:
+    """Mixin/state holder for a Temporal workflow that can wait for reauthorization."""
+
+    def __init__(self) -> None:
+        self._revive_signals: dict[str, dict[str, Any]] = {}
+
+    @workflow.signal(name=SIGNAL_NAME)
+    def revive_reauthorized(self, payload: dict[str, Any]) -> None:
+        case_id = str(payload["recovery_case_id"])
+        self._revive_signals[case_id] = dict(payload)
+
+    async def wait_for_reauthorization(self, recovery_case_id: str) -> dict[str, Any]:
+        await workflow.wait_condition(lambda: recovery_case_id in self._revive_signals)
+        return self._revive_signals.pop(recovery_case_id)
+
+
+class TemporalRecoveryClient:
+    def __init__(self, client: Any, signal_name: str = SIGNAL_NAME):
+        self.client = client
+        self.signal_name = signal_name
+
+    async def resume(self, workflow_id: str, signal: ReauthorizationSignal,
+                     run_id: Optional[str] = None) -> None:
+        kwargs = {"run_id": run_id} if run_id else {}
+        handle = self.client.get_workflow_handle(workflow_id, **kwargs)
+        await handle.signal(self.signal_name, asdict(signal))

revive/checkpoint.py

@@ -0,0 +1,199 @@
+"""Durable, step-accurate checkpoints — real SQLite persistence.
+
+A checkpoint is captured the instant a run parks (dead token, or any rendezvous).
+Because it is durable, the run survives a process restart: a worker can pick the
+run back up and resume it from the exact step after the human responds.
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from dataclasses import asdict, dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class Checkpoint:
+    run_id: str
+    step_index: int
+    step_id: str
+    cursor: dict[str, Any]
+    token_fingerprint: str
+    scopes: list[str]
+    status: str = "parked"          # parked | running | done | dead
+    taken_at: float = field(default_factory=time.time)
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+class CheckpointStore:
+    def __init__(self, path: str = "revive.db"):
+        self.path = path
+        self._conn = sqlite3.connect(path, check_same_thread=False)
+        self._conn.execute(
+            """CREATE TABLE IF NOT EXISTS checkpoints (
+                run_id TEXT PRIMARY KEY,
+                step_index INTEGER, step_id TEXT, cursor TEXT,
+                token_fingerprint TEXT, scopes TEXT, status TEXT, taken_at REAL
+            )"""
+        )
+        self._conn.execute(
+            """CREATE TABLE IF NOT EXISTS rendezvous (
+                id TEXT PRIMARY KEY, run_id TEXT UNIQUE, kind TEXT, prompt TEXT,
+                url TEXT, context TEXT, status TEXT, reply TEXT,
+                created_at REAL, expires_at REAL
+            )"""
+        )
+        self._conn.execute(
+            """CREATE TABLE IF NOT EXISTS action_attempts (
+                action_id TEXT PRIMARY KEY, run_id TEXT, step_id TEXT,
+                state TEXT, attempts INTEGER, updated_at REAL
+            )"""
+        )
+        self._conn.execute(
+            """CREATE TABLE IF NOT EXISTS credential_leases (
+                lease_id TEXT PRIMARY KEY, generation INTEGER NOT NULL,
+                updated_at REAL NOT NULL
+            )"""
+        )
+        self._conn.commit()
+
+    def save(self, cp: Checkpoint) -> None:
+        self._conn.execute(
+            """INSERT INTO checkpoints
+               (run_id, step_index, step_id, cursor, token_fingerprint, scopes, status, taken_at)
+               VALUES (?,?,?,?,?,?,?,?)
+               ON CONFLICT(run_id) DO UPDATE SET
+                 step_index=excluded.step_index, step_id=excluded.step_id,
+                 cursor=excluded.cursor, token_fingerprint=excluded.token_fingerprint,
+                 scopes=excluded.scopes, status=excluded.status, taken_at=excluded.taken_at""",
+            (cp.run_id, cp.step_index, cp.step_id, json.dumps(cp.cursor),
+             cp.token_fingerprint, json.dumps(cp.scopes), cp.status, cp.taken_at),
+        )
+        self._conn.commit()
+
+    def load(self, run_id: str) -> Optional[Checkpoint]:
+        row = self._conn.execute(
+            "SELECT run_id, step_index, step_id, cursor, token_fingerprint, scopes, status, taken_at "
+            "FROM checkpoints WHERE run_id=?", (run_id,)
+        ).fetchone()
+        if not row:
+            return None
+        return Checkpoint(
+            run_id=row[0], step_index=row[1], step_id=row[2], cursor=json.loads(row[3]),
+            token_fingerprint=row[4], scopes=json.loads(row[5]), status=row[6], taken_at=row[7],
+        )
+
+    def set_status(self, run_id: str, status: str) -> None:
+        self._conn.execute("UPDATE checkpoints SET status=? WHERE run_id=?", (status, run_id))
+        self._conn.commit()
+
+    def save_rendezvous(self, data: dict[str, Any]) -> None:
+        self._conn.execute(
+            """INSERT INTO rendezvous
+               (id, run_id, kind, prompt, url, context, status, reply, created_at, expires_at)
+               VALUES (?,?,?,?,?,?,?,?,?,?)
+               ON CONFLICT(run_id) DO UPDATE SET
+                 id=excluded.id, kind=excluded.kind, prompt=excluded.prompt,
+                 url=excluded.url, context=excluded.context, status=excluded.status,
+                 reply=excluded.reply, created_at=excluded.created_at,
+                 expires_at=excluded.expires_at""",
+            (data["id"], data["run_id"], data["kind"], data["prompt"], data["url"],
+             json.dumps(data.get("context", {})), data.get("status", "open"),
+             json.dumps(data.get("reply")), data["created_at"], data["expires_at"]),
+        )
+        self._conn.commit()
+
+    def load_rendezvous(self, run_id: str) -> Optional[dict[str, Any]]:
+        row = self._conn.execute(
+            "SELECT id, run_id, kind, prompt, url, context, status, reply, created_at, expires_at "
+            "FROM rendezvous WHERE run_id=?", (run_id,)
+        ).fetchone()
+        if not row:
+            return None
+        return {
+            "id": row[0], "run_id": row[1], "kind": row[2], "prompt": row[3],
+            "url": row[4], "context": json.loads(row[5]), "status": row[6],
+            "reply": json.loads(row[7]) if row[7] else None,
+            "created_at": row[8], "expires_at": row[9],
+        }
+
+    def consume_rendezvous(self, run_id: str, reply: dict[str, Any]) -> bool:
+        """Atomically consume one open, unexpired rendezvous."""
+        now = time.time()
+        cur = self._conn.execute(
+            "UPDATE rendezvous SET status='answered', reply=? "
+            "WHERE run_id=? AND status='open' AND expires_at>?",
+            (json.dumps(reply), run_id, now),
+        )
+        self._conn.commit()
+        return cur.rowcount == 1
+
+    def action_state(self, action_id: str) -> Optional[str]:
+        row = self._conn.execute(
+            "SELECT state FROM action_attempts WHERE action_id=?", (action_id,)
+        ).fetchone()
+        return row[0] if row else None
+
+    def start_action(self, action_id: str, run_id: str, step_id: str) -> None:
+        now = time.time()
+        self._conn.execute(
+            """INSERT INTO action_attempts
+               (action_id, run_id, step_id, state, attempts, updated_at)
+               VALUES (?,?,?,'started',1,?)
+               ON CONFLICT(action_id) DO UPDATE SET
+                 attempts=action_attempts.attempts+1, updated_at=excluded.updated_at""",
+            (action_id, run_id, step_id, now),
+        )
+        self._conn.commit()
+
+    def complete_action(self, action_id: str) -> None:
+        self._conn.execute(
+            "UPDATE action_attempts SET state='completed', updated_at=? WHERE action_id=?",
+            (time.time(), action_id),
+        )
+        self._conn.commit()
+
+    def reset_action(self, action_id: str) -> None:
+        # A provider 401 proves the protected side effect was not accepted.
+        self._conn.execute("DELETE FROM action_attempts WHERE action_id=?", (action_id,))
+        self._conn.commit()
+
+    def ensure_lease(self, lease_id: str, generation: int) -> None:
+        """Create a lease once without allowing an old worker to lower it."""
+        self._conn.execute(
+            """INSERT INTO credential_leases (lease_id, generation, updated_at)
+               VALUES (?,?,?) ON CONFLICT(lease_id) DO NOTHING""",
+            (lease_id, generation, time.time()),
+        )
+        self._conn.commit()
+
+    def assert_lease_generation(self, lease_id: str, generation: int) -> None:
+        row = self._conn.execute(
+            "SELECT generation FROM credential_leases WHERE lease_id=?", (lease_id,)
+        ).fetchone()
+        if row is None or int(row[0]) != generation:
+            current = int(row[0]) if row else None
+            raise ValueError(
+                f"stale credential generation for {lease_id}: got {generation}, current {current}"
+            )
+
+    def rotate_lease(self, lease_id: str, expected_generation: int) -> int:
+        """Atomically fence the prior generation and return the new one."""
+        next_generation = expected_generation + 1
+        cur = self._conn.execute(
+            """UPDATE credential_leases
+               SET generation=?, updated_at=?
+               WHERE lease_id=? AND generation=?""",
+            (next_generation, time.time(), lease_id, expected_generation),
+        )
+        self._conn.commit()
+        if cur.rowcount != 1:
+            self.assert_lease_generation(lease_id, expected_generation)
+            raise ValueError(f"could not rotate credential lease {lease_id}")
+        return next_generation
+
+    def close(self) -> None:
+        self._conn.close()