primarypath-sdk 1.0.0rc1__py3-none-any.whl

primarypath_client/__init__.py

@@ -0,0 +1,715 @@
+"""Primary Path client SDK.
+
+The framework-agnostic side of the product: POST the approval request, then
+poll for the decision (or receive it on your callback_url). The pause is
+durable on both sides — the service holds the request in its log, and the
+caller can crash and re-wait on the same approval_id.
+
+The sync client is stdlib-only. The async client needs httpx
+(pip install primarypath-sdk[async]).
+
+Resilience, because an agent may pause for hours or days: every call
+retries transient failures (connection errors, 429, 502/503/504) with
+exponential backoff and full jitter, honouring Retry-After; the policy
+is `RetryPolicy` on the client. `wait_for_decision` keeps polling
+through outages until its own timeout, backs its poll interval off to
+`max_interval`, and stops on a `cancel` event.
+
+Retries are safe for every write because each non-idempotent call
+(annotate, incident, ingest, decide, cancel, request-changes, redeem)
+generates an `Idempotency-Key` once and sends the SAME key on every
+attempt: the server records the key with the events, so a retry after
+a lost response returns the original result and writes nothing — one
+annotation, one incident, one redeemed grant that this caller may
+dispatch on. Pass `idempotency_key=` to control the key yourself (for
+example, derive it from your own step id so a crashed-and-restarted
+agent replays too). Approval creation is idempotent by its own id.
+
+Identifiers are percent-encoded into paths; the server accepts only
+URL-safe ids (letters, digits, . _ - ~ @ + =, and : in run_id), so every
+approval that can be created can be addressed.
+
+Execution grants (the approve->execute seam): a granted approval carries
+`grant`, an Ed25519-signed, short-lived, single-use capability bound to
+the approval's action digest. The EXECUTOR — whatever holds the tool
+credentials — calls `verify_grant(...)` offline against the pinned
+public-key ring (`client.signing_keys()`), then `client.redeem_grant(...)`
+right before dispatch: the server accepts each grant exactly once and
+appends `grant_redeemed` to the chain. `verify_grant` needs
+`cryptography` (pip install primarypath-sdk[grants]).
+"""
+from __future__ import annotations
+
+import base64
+import email.utils
+import hashlib
+import json
+import random
+import threading
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import uuid
+from dataclasses import dataclass, field
+
+__all__ = ["PrimaryPathClient", "AsyncPrimaryPathClient", "ApiError",
+           "TransportError", "DecisionTimeout", "WaitCancelled", "RetryPolicy",
+           "GrantInvalid", "NotCanonicalizable", "action_digest", "jcs",
+           "verify_grant", "GRANT_SIGNED_FIELDS"]
+
+
+# -- RFC 8785 JSON Canonicalization Scheme (a copy of the server's app/jcs.py;
+#    the server's tests assert the two agree). JSON.stringify over an
+#    object with keys sorted by UTF-16 code units is the reference; this
+#    reproduces it byte for byte, ECMAScript number formatting included,
+#    so a digest computed here equals one computed in TypeScript or by
+#    the server. --------------------------------------------------------------
+
+import math
+
+# ECMAScript Number::toString thresholds
+_EXP_UPPER = 21   # >= 1e21 switches to exponent form
+_EXP_LOWER = -6   # < 1e-6 switches to exponent form
+_MAX_SAFE = 2 ** 53
+_SHORT = {8: "\\b", 9: "\\t", 10: "\\n", 12: "\\f", 13: "\\r"}
+
+
+class NotCanonicalizable(ValueError):
+    """A value JSON (and therefore JCS) cannot represent."""
+
+
+def _es_number(x: float) -> str:
+    """Number::toString for a finite double: the shortest round-trip digit
+    string (Python's repr yields the same digits as ECMAScript's
+    "shortest" rule) laid out with ECMAScript's rules."""
+    if x == 0:
+        return "0"  # -0 prints as "0"
+    sign = "-" if x < 0 else ""
+    r = repr(abs(x))  # '1.5', '1e-07', '1.2345e+21', '123.0'
+    mantissa, _, exp = r.partition("e")
+    e = int(exp) if exp else 0
+    int_part, _, frac_part = mantissa.partition(".")
+    int_digits = int_part.lstrip("0")
+    if int_digits:
+        n = len(int_digits) + e
+    else:
+        n = e - (len(frac_part) - len(frac_part.lstrip("0")))
+    digits = (int_digits + frac_part if int_digits else frac_part.lstrip("0"))
+    digits = digits.rstrip("0")
+    k = len(digits)
+    if k == 0:
+        return "0"
+    if k <= n <= _EXP_UPPER:
+        return sign + digits + "0" * (n - k)
+    if 0 < n <= _EXP_UPPER:
+        return sign + digits[:n] + "." + digits[n:]
+    if _EXP_LOWER < n <= 0:
+        return sign + "0." + "0" * (-n) + digits
+    exp10 = n - 1
+    exp_s = ("+" if exp10 >= 0 else "-") + str(abs(exp10))
+    if k == 1:
+        return sign + digits + "e" + exp_s
+    return sign + digits[0] + "." + digits[1:] + "e" + exp_s
+
+
+def _string(s: str) -> str:
+    """JSON.stringify's string form: only `"`, backslash and control
+    characters are escaped (short forms for \\b \\f \\n \\r \\t, else
+    \\u00xx lowercase); everything else, non-ASCII included, is emitted
+    as is."""
+    out = ['"']
+    for ch in s:
+        o = ord(ch)
+        if ch == '"':
+            out.append('\\"')
+        elif ch == "\\":
+            out.append("\\\\")
+        elif o < 0x20:
+            out.append(_SHORT.get(o, f"\\u{o:04x}"))
+        elif 0xD800 <= o <= 0xDFFF:
+            raise NotCanonicalizable("lone surrogate in string")
+        else:
+            out.append(ch)
+    out.append('"')
+    return "".join(out)
+
+
+def jcs(value) -> str:
+    """Serialize `value` per RFC 8785."""
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, int):
+        # JCS numbers are IEEE doubles: an integer beyond 2^53 is what a
+        # JSON parser in any language rounds it to
+        if abs(value) > _MAX_SAFE:
+            return _es_number(float(value))
+        return str(value)
+    if isinstance(value, float):
+        if math.isnan(value) or math.isinf(value):
+            raise NotCanonicalizable("NaN and Infinity are not JSON")
+        return _es_number(value)
+    if isinstance(value, str):
+        return _string(value)
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(jcs(v) for v in value) + "]"
+    if isinstance(value, dict):
+        items = []
+        for k in sorted(value, key=lambda k: str(k).encode("utf-16-be")):
+            if not isinstance(k, str):
+                raise NotCanonicalizable(f"object key is not a string: {k!r}")
+            items.append(_string(k) + ":" + jcs(value[k]))
+        return "{" + ",".join(items) + "}"
+    raise NotCanonicalizable(f"not a JSON value: {type(value).__name__}")
+
+
+def action_digest(tool: str, arguments: dict | None = None,
+                  reasoning: str | None = None, framework: str | None = None,
+                  callback_url: str | None = None) -> str:
+    """sha256 over the RFC 8785 form of the action — byte-identical to the
+    server's `action_digest` (digest_alg "jcs") stamped into
+    `approval_requested`, and to the TypeScript SDK's `actionDigest`. An
+    executor recomputes it from the exact arguments it is about to
+    dispatch."""
+    return hashlib.sha256(jcs({
+        "tool": tool, "arguments": arguments or {}, "reasoning": reasoning,
+        "framework": framework, "callback_url": callback_url,
+    }).encode("utf-8")).hexdigest()
+
+
+GRANT_SIGNED_FIELDS = ("v", "approval_id", "tenant", "agent_id", "tool",
+                       "action_digest", "issued_ms", "expires_ms", "nonce")
+
+
+class GrantInvalid(Exception):
+    """An execution grant that must not be honored, and why."""
+
+
+def verify_grant(grant: dict, keys: dict[str, str], *,
+                 tool: str | None = None, arguments: dict | None = None,
+                 reasoning: str | None = None, framework: str | None = None,
+                 callback_url: str | None = None,
+                 expected_digest: str | None = None,
+                 approval_id: str | None = None,
+                 now_ms: int | None = None) -> dict:
+    """Verify an execution grant OFFLINE and return it.
+
+    `keys` is the public-key ring (`key_id` -> base64 raw Ed25519 public
+    key) from `/api/audit/keys` — pin it out of band for authenticity.
+    Pass the action the executor is about to run (`tool` + `arguments`
+    and, if it knows them, `reasoning`/`framework`/`callback_url`) so the
+    digest is recomputed and compared; or `expected_digest` when only the
+    digest is known. Raises GrantInvalid on any failure. Single use is
+    enforced ONLINE by `redeem_grant`, not here."""
+    try:
+        from cryptography.exceptions import InvalidSignature
+        from cryptography.hazmat.primitives.asymmetric import ed25519
+    except ImportError:  # pragma: no cover - packaging
+        raise GrantInvalid("verify_grant needs `cryptography` "
+                           "(pip install primarypath-sdk[grants])") from None
+    if not isinstance(grant, dict) or grant.get("v") != 1:
+        raise GrantInvalid("unsupported grant version")
+    missing = [k for k in GRANT_SIGNED_FIELDS + ("key_id", "signature")
+               if k not in grant]
+    if missing:
+        raise GrantInvalid(f"grant is missing {', '.join(missing)}")
+    pub = keys.get(grant["key_id"])
+    if pub is None:
+        raise GrantInvalid(f"unknown signing key {grant['key_id']}: not in "
+                           f"the pinned ring")
+    message = jcs({k: grant[k] for k in GRANT_SIGNED_FIELDS})
+    try:
+        ed25519.Ed25519PublicKey.from_public_bytes(
+            base64.b64decode(pub)).verify(
+            base64.b64decode(grant["signature"]), message.encode("utf-8"))
+    except (InvalidSignature, ValueError):
+        raise GrantInvalid("signature does not verify") from None
+    now = int(time.time() * 1000) if now_ms is None else now_ms
+    if now > int(grant["expires_ms"]):
+        raise GrantInvalid(f"grant expired at {grant['expires_ms']}")
+    if approval_id is not None and grant["approval_id"] != approval_id:
+        raise GrantInvalid("grant is for a different approval")
+    if tool is not None and grant["tool"] != tool:
+        raise GrantInvalid(f"grant is for tool {grant['tool']}, not {tool}")
+    if tool is not None and expected_digest is None:
+        expected_digest = action_digest(tool, arguments, reasoning,
+                                        framework, callback_url)
+    if expected_digest is not None and grant["action_digest"] != expected_digest:
+        raise GrantInvalid("grant binds a different action than the one "
+                           "about to execute (digest mismatch)")
+    return grant
+
+
+class DecisionTimeout(TimeoutError):
+    pass
+
+
+class WaitCancelled(Exception):
+    """wait_for_decision stopped because its cancel event was set."""
+
+
+class ApiError(Exception):
+    """A non-2xx answer from the service. Raised, never returned: an agent
+    that mistakes {"detail": "..."} for an approval will poll a decision
+    that can never come."""
+
+    def __init__(self, status: int, body: object, retry_after: float | None = None):
+        detail = body.get("detail") if isinstance(body, dict) else None
+        super().__init__(f"primarypath API error {status}"
+                         + (f": {detail}" if detail else ""))
+        self.status = status
+        self.body = body
+        self.retry_after = retry_after
+
+
+class TransportError(Exception):
+    """The service could not be reached (connection refused, reset, DNS,
+    timeout) and the retry policy is exhausted."""
+
+    def __init__(self, message: str, attempts: int):
+        super().__init__(f"{message} (after {attempts} attempt(s))")
+        self.attempts = attempts
+
+
+TRANSIENT_STATUSES = frozenset({429, 502, 503, 504})
+
+
+@dataclass
+class RetryPolicy:
+    """Bounded retries with exponential backoff and full jitter. `attempts`
+    counts the first try; delays are min(max_delay, base * 2**n) times a
+    random factor in [0, 1] (full jitter), or the server's Retry-After
+    when it sends one (capped at retry_after_max)."""
+    attempts: int = 5
+    base: float = 0.5
+    max_delay: float = 30.0
+    jitter: bool = True
+    retry_after_max: float = 120.0
+    statuses: frozenset = field(default_factory=lambda: TRANSIENT_STATUSES)
+
+    def delay(self, attempt: int, retry_after: float | None = None) -> float:
+        if retry_after is not None:
+            return max(0.0, min(retry_after, self.retry_after_max))
+        d = min(self.max_delay, self.base * (2 ** attempt))
+        return random.uniform(0, d) if self.jitter else d
+
+
+def _p(segment) -> str:
+    """A path segment: percent-encode everything but unreserved characters,
+    so an id like `run:7@eu` reaches the server as sent."""
+    return urllib.parse.quote(str(segment), safe="")
+
+
+def _key(given: str | None) -> str:
+    """The Idempotency-Key for one logical write: the caller's, or a fresh
+    random one — generated ONCE per call, then repeated on every retry."""
+    return given if given is not None else uuid.uuid4().hex
+
+
+def _retry_after(value: str | None) -> float | None:
+    if not value:
+        return None
+    value = value.strip()
+    if value.isdigit():
+        return float(value)
+    try:
+        when = email.utils.parsedate_to_datetime(value)
+    except (TypeError, ValueError):
+        return None
+    return max(0.0, when.timestamp() - time.time())
+
+
+def _body_or_raise(status: int, raw: bytes,
+                   retry_after: float | None = None) -> dict | list:
+    try:
+        body = json.loads(raw.decode("utf-8")) if raw else None
+    except ValueError:
+        body = raw.decode("utf-8", "replace")
+    if status >= 400:
+        raise ApiError(status, body, retry_after)
+    return body
+
+
+def _is_transient(exc: Exception, policy: RetryPolicy) -> bool:
+    if isinstance(exc, ApiError):
+        return exc.status in policy.statuses
+    return isinstance(exc, TransportError)
+
+
+class PrimaryPathClient:
+    def __init__(self, base_url: str = "http://127.0.0.1:8123",
+                 token: str | None = None, timeout: float = 30.0,
+                 retry: RetryPolicy | None = None):
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self.retry = retry or RetryPolicy()
+
+    def _once(self, method: str, path: str, body: dict | None,
+              idem: str | None = None) -> dict | list:
+        data = json.dumps(body).encode("utf-8") if body is not None else None
+        headers = {"Content-Type": "application/json"}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        if idem is not None:
+            headers["Idempotency-Key"] = idem
+        req = urllib.request.Request(f"{self.base_url}{path}", data=data,
+                                     method=method, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                return _body_or_raise(resp.status, resp.read())
+        except urllib.error.HTTPError as e:
+            return _body_or_raise(e.code, e.read(),
+                                  _retry_after(e.headers.get("Retry-After")))
+        except (urllib.error.URLError, ConnectionError, TimeoutError) as e:
+            raise TransportError(str(getattr(e, "reason", e)), 1) from None
+
+    def _call(self, method: str, path: str, body: dict | None = None,
+              retry: bool = True, idem: str | None = None) -> dict | list:
+        """One request under the retry policy; `idem` is the
+        Idempotency-Key repeated on every attempt of a write."""
+        attempts = self.retry.attempts if retry else 1
+        for attempt in range(attempts):
+            try:
+                return self._once(method, path, body, idem)
+            except (ApiError, TransportError) as e:
+                if attempt + 1 >= attempts or not _is_transient(e, self.retry):
+                    if isinstance(e, TransportError):
+                        raise TransportError(str(e).rsplit(" (after", 1)[0],
+                                             attempt + 1) from None
+                    raise
+                time.sleep(self.retry.delay(attempt, getattr(e, "retry_after", None)))
+        raise AssertionError("unreachable")
+
+    def request_approval(self, run_id: str, call_id: str, tool: str,
+                         arguments: dict | None = None,
+                         reasoning: str | None = None,
+                         framework: str | None = None,
+                         deadline_ms: int | None = None,
+                         callback_url: str | None = None,
+                         supersedes: str | None = None) -> str:
+        body = {"run_id": run_id, "call_id": call_id, "tool": tool,
+                "arguments": arguments or {}, "reasoning": reasoning}
+        if framework is not None:
+            body["framework"] = framework
+        if supersedes is not None:
+            body["supersedes"] = supersedes
+        if deadline_ms is not None:
+            body["deadline_ms"] = deadline_ms
+        if callback_url is not None:
+            body["callback_url"] = callback_url
+        out = self._call("POST", "/api/approvals", body)
+        return out["approval_id"]
+
+    def get(self, approval_id: str) -> dict:
+        return self._call("GET", f"/api/approvals/{_p(approval_id)}")
+
+    def list(self, status: str | None = None, limit: int = 100,
+             cursor: int = 0) -> list:
+        q = f"?limit={limit}&cursor={cursor}"
+        if status:
+            q += f"&status={_p(status)}"
+        return self._call("GET", f"/api/approvals{q}")
+
+    def wait_for_decision(self, approval_id: str, interval: float = 1.0,
+                          timeout: float | None = None,
+                          cancel: threading.Event | None = None,
+                          max_interval: float | None = None) -> dict:
+        """Poll until the approval leaves `pending` (any terminal status).
+
+        Built for long pauses: transient failures (outage, 429, 5xx) are
+        tolerated and polling continues until `timeout`; the poll interval
+        backs off from `interval` toward `max_interval` (default: no
+        backoff) with jitter; `cancel` (a threading.Event) stops the wait
+        with WaitCancelled. `timeout` is the only way it gives up on its
+        own."""
+        start = time.monotonic()
+        current = interval
+        ceiling = max_interval if max_interval is not None else interval
+        while True:
+            if cancel is not None and cancel.is_set():
+                raise WaitCancelled(approval_id)
+            try:
+                a = self.get(approval_id)
+                if a.get("status") != "pending":  # any terminal status
+                    return a
+            except (ApiError, TransportError) as e:
+                if not _is_transient(e, self.retry):
+                    raise
+            if timeout is not None and time.monotonic() - start > timeout:
+                raise DecisionTimeout(f"no decision on {approval_id} in {timeout}s")
+            pause = random.uniform(current * 0.8, current * 1.2)
+            if cancel is not None:
+                if cancel.wait(pause):
+                    raise WaitCancelled(approval_id)
+            else:
+                time.sleep(pause)
+            current = min(ceiling, current * 1.5)
+
+    def decide(self, approval_id: str, approved: bool, reviewer: str,
+               reason: str = "", idempotency_key: str | None = None) -> dict:
+        return self._call("POST", f"/api/approvals/{_p(approval_id)}/decision",
+                          {"approved": approved, "reviewer": reviewer,
+                           "reason": reason}, idem=_key(idempotency_key))
+
+    def annotate(self, approval_id: str, reviewer: str, note: str,
+                 idempotency_key: str | None = None) -> dict:
+        return self._call("POST", f"/api/approvals/{_p(approval_id)}/annotate",
+                          {"reviewer": reviewer, "note": note},
+                          idem=_key(idempotency_key))
+
+    def cancel(self, approval_id: str, reason: str = "",
+               idempotency_key: str | None = None) -> dict:
+        """Withdraw a pending proposal (agent plane)."""
+        return self._call("POST", f"/api/approvals/{_p(approval_id)}/cancel",
+                          {"reason": reason}, idem=_key(idempotency_key))
+
+    def request_changes(self, approval_id: str, reviewer: str,
+                        reason: str, idempotency_key: str | None = None) -> dict:
+        """Send a proposal back for changes (human plane)."""
+        return self._call("POST",
+                          f"/api/approvals/{_p(approval_id)}/request-changes",
+                          {"reviewer": reviewer, "reason": reason},
+                          idem=_key(idempotency_key))
+
+    def report_incident(self, approval_id: str, reviewer: str, summary: str,
+                        severity: str = "sev3",
+                        idempotency_key: str | None = None) -> dict:
+        """A structured outcome event: the executed action caused an
+        incident. Counted by the rollout track record."""
+        return self._call("POST", f"/api/approvals/{_p(approval_id)}/incident",
+                          {"reviewer": reviewer, "summary": summary,
+                           "severity": severity}, idem=_key(idempotency_key))
+
+    def redeem_grant(self, approval_id: str, nonce: str,
+                     instance: str | None = None,
+                     idempotency_key: str | None = None) -> dict:
+        """Redeem the approval's execution grant — exactly once, right
+        before dispatch (agent plane). 409 (ApiError) if it was already
+        redeemed, expired, or does not match. Retried under the same
+        Idempotency-Key: if the response is lost, the retry returns the
+        result of THIS call's redemption (the grant was spent by us, so
+        dispatching is right), while a genuinely second redemption is
+        still a 409. The chain's `executor` is the presenting credential,
+        written by the server; `instance` is this executor's own name for
+        itself ("mcp-gateway@edge-1"), recorded separately as
+        self-asserted context."""
+        body = {"nonce": nonce}
+        if instance is not None:
+            body["instance"] = instance
+        return self._call("POST", f"/api/approvals/{_p(approval_id)}/redeem",
+                          body, idem=_key(idempotency_key))
+
+    def signing_keys(self) -> dict[str, str]:
+        """The public-key ring (key_id -> base64 raw Ed25519 public key)
+        grants and exports are signed with. Pin it out of band."""
+        return self._call("GET", "/api/audit/keys")["keys"]
+
+    def ingest_run_events(self, run_id: str, events: list[dict],
+                          idempotency_key: str | None = None) -> int:
+        out = self._call("POST", f"/api/runs/{_p(run_id)}/events",
+                         {"events": events}, idem=_key(idempotency_key))
+        return out.get("ingested", 0)
+
+    def run_audit(self, run_id: str) -> list:
+        return self._call("GET", f"/api/runs/{_p(run_id)}/audit")
+
+    def export_audit(self) -> dict:
+        """The whole log: {"chains": [...]}, each chain independently
+        verifiable (F24)."""
+        return self._call("GET", "/api/audit/export")
+
+    def export_agent_audit(self, agent: str) -> dict:
+        """One agent's chain, signed under its own evidence profile (F24)."""
+        return self._call("GET", f"/api/audit/export?agent={_p(agent)}")
+
+
+class AsyncPrimaryPathClient:
+    """Async twin of PrimaryPathClient (agents are async). Requires httpx.
+    Same retry policy and long-wait semantics; cancellation is the
+    natural asyncio task cancellation, or an asyncio.Event passed as
+    `cancel` to wait_for_decision."""
+
+    def __init__(self, base_url: str = "http://127.0.0.1:8123",
+                 token: str | None = None, timeout: float = 30.0,
+                 retry: RetryPolicy | None = None):
+        import httpx  # local import: optional dependency
+
+        headers = {"Content-Type": "application/json"}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        self.retry = retry or RetryPolicy()
+        self._client = httpx.AsyncClient(base_url=base_url.rstrip("/"),
+                                         headers=headers, timeout=timeout)
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncPrimaryPathClient:
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        await self.aclose()
+
+    async def _once(self, method: str, path: str, body: dict | None,
+                    idem: str | None = None) -> dict | list:
+        import httpx
+
+        headers = {"Idempotency-Key": idem} if idem is not None else None
+        try:
+            r = await self._client.request(method, path, json=body,
+                                           headers=headers)
+        except httpx.TransportError as e:
+            raise TransportError(str(e) or e.__class__.__name__, 1) from None
+        return _body_or_raise(r.status_code, r.content,
+                              _retry_after(r.headers.get("Retry-After")))
+
+    async def _call(self, method: str, path: str, body: dict | None = None,
+                    retry: bool = True, idem: str | None = None) -> dict | list:
+        import asyncio
+
+        attempts = self.retry.attempts if retry else 1
+        for attempt in range(attempts):
+            try:
+                return await self._once(method, path, body, idem)
+            except (ApiError, TransportError) as e:
+                if attempt + 1 >= attempts or not _is_transient(e, self.retry):
+                    if isinstance(e, TransportError):
+                        raise TransportError(str(e).rsplit(" (after", 1)[0],
+                                             attempt + 1) from None
+                    raise
+                await asyncio.sleep(
+                    self.retry.delay(attempt, getattr(e, "retry_after", None)))
+        raise AssertionError("unreachable")
+
+    async def request_approval(self, run_id: str, call_id: str, tool: str,
+                               arguments: dict | None = None,
+                               reasoning: str | None = None,
+                               framework: str | None = None,
+                               deadline_ms: int | None = None,
+                               callback_url: str | None = None,
+                               supersedes: str | None = None) -> str:
+        body = {"run_id": run_id, "call_id": call_id, "tool": tool,
+                "arguments": arguments or {}, "reasoning": reasoning}
+        if framework is not None:
+            body["framework"] = framework
+        if supersedes is not None:
+            body["supersedes"] = supersedes
+        if deadline_ms is not None:
+            body["deadline_ms"] = deadline_ms
+        if callback_url is not None:
+            body["callback_url"] = callback_url
+        out = await self._call("POST", "/api/approvals", body)
+        return out["approval_id"]
+
+    async def get(self, approval_id: str) -> dict:
+        return await self._call("GET", f"/api/approvals/{_p(approval_id)}")
+
+    async def list(self, status: str | None = None, limit: int = 100,
+                   cursor: int = 0) -> list:
+        q = f"?limit={limit}&cursor={cursor}"
+        if status:
+            q += f"&status={_p(status)}"
+        return await self._call("GET", f"/api/approvals{q}")
+
+    async def wait_for_decision(self, approval_id: str, interval: float = 1.0,
+                                timeout: float | None = None,
+                                cancel=None,
+                                max_interval: float | None = None) -> dict:
+        """See PrimaryPathClient.wait_for_decision. `cancel` is an
+        asyncio.Event; cancelling the awaiting task works as well."""
+        import asyncio
+
+        start = time.monotonic()
+        current = interval
+        ceiling = max_interval if max_interval is not None else interval
+        while True:
+            if cancel is not None and cancel.is_set():
+                raise WaitCancelled(approval_id)
+            try:
+                a = await self.get(approval_id)
+                if a.get("status") != "pending":  # any terminal status
+                    return a
+            except (ApiError, TransportError) as e:
+                if not _is_transient(e, self.retry):
+                    raise
+            if timeout is not None and time.monotonic() - start > timeout:
+                raise DecisionTimeout(f"no decision on {approval_id} in {timeout}s")
+            pause = random.uniform(current * 0.8, current * 1.2)
+            if cancel is not None:
+                # asyncio.wait (not wait_for): no TimeoutError to catch, and
+                # on 3.10 asyncio.TimeoutError is not the builtin one
+                waiter = asyncio.ensure_future(cancel.wait())
+                done, _ = await asyncio.wait({waiter}, timeout=pause)
+                if not done:
+                    waiter.cancel()
+                if cancel.is_set():
+                    raise WaitCancelled(approval_id)
+            else:
+                await asyncio.sleep(pause)
+            current = min(ceiling, current * 1.5)
+
+    async def decide(self, approval_id: str, approved: bool, reviewer: str,
+                     reason: str = "", idempotency_key: str | None = None) -> dict:
+        return await self._call("POST", f"/api/approvals/{_p(approval_id)}/decision",
+                                {"approved": approved, "reviewer": reviewer,
+                                 "reason": reason}, idem=_key(idempotency_key))
+
+    async def annotate(self, approval_id: str, reviewer: str, note: str,
+                       idempotency_key: str | None = None) -> dict:
+        return await self._call("POST", f"/api/approvals/{_p(approval_id)}/annotate",
+                                {"reviewer": reviewer, "note": note},
+                                idem=_key(idempotency_key))
+
+    async def cancel(self, approval_id: str, reason: str = "",
+                     idempotency_key: str | None = None) -> dict:
+        return await self._call("POST", f"/api/approvals/{_p(approval_id)}/cancel",
+                                {"reason": reason}, idem=_key(idempotency_key))
+
+    async def request_changes(self, approval_id: str, reviewer: str,
+                              reason: str, idempotency_key: str | None = None) -> dict:
+        return await self._call(
+            "POST", f"/api/approvals/{_p(approval_id)}/request-changes",
+            {"reviewer": reviewer, "reason": reason}, idem=_key(idempotency_key))
+
+    async def report_incident(self, approval_id: str, reviewer: str,
+                              summary: str, severity: str = "sev3",
+                              idempotency_key: str | None = None) -> dict:
+        return await self._call("POST", f"/api/approvals/{_p(approval_id)}/incident",
+                                {"reviewer": reviewer, "summary": summary,
+                                 "severity": severity}, idem=_key(idempotency_key))
+
+    async def redeem_grant(self, approval_id: str, nonce: str,
+                           instance: str | None = None,
+                           idempotency_key: str | None = None) -> dict:
+        """Retried under one Idempotency-Key; see PrimaryPathClient.redeem_grant."""
+        body = {"nonce": nonce}
+        if instance is not None:
+            body["instance"] = instance
+        return await self._call("POST", f"/api/approvals/{_p(approval_id)}/redeem",
+                                body, idem=_key(idempotency_key))
+
+    async def signing_keys(self) -> dict[str, str]:
+        return (await self._call("GET", "/api/audit/keys"))["keys"]
+
+    async def ingest_run_events(self, run_id: str, events: list[dict],
+                                idempotency_key: str | None = None) -> int:
+        out = await self._call("POST", f"/api/runs/{_p(run_id)}/events",
+                               {"events": events}, idem=_key(idempotency_key))
+        return out.get("ingested", 0)
+
+    async def run_audit(self, run_id: str) -> list:
+        return await self._call("GET", f"/api/runs/{_p(run_id)}/audit")
+
+    async def export_audit(self) -> dict:
+        """The whole log: {"chains": [...]}, each chain independently
+        verifiable (F24)."""
+        return await self._call("GET", "/api/audit/export")
+
+    async def export_agent_audit(self, agent: str) -> dict:
+        """One agent's chain, signed under its own evidence profile (F24)."""
+        return await self._call("GET", f"/api/audit/export?agent={_p(agent)}")

primarypath_sdk-1.0.0rc1.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: primarypath-sdk
+Version: 1.0.0rc1
+Summary: Primary Path client SDK: govern any agent that can make two HTTP calls
+License-Expression: Apache-2.0
+Requires-Python: >=3.10
+License-File: LICENSE
+Provides-Extra: async
+Requires-Dist: httpx>=0.27; extra == "async"
+Provides-Extra: grants
+Requires-Dist: cryptography>=42; extra == "grants"
+Dynamic: license-file

primarypath_sdk-1.0.0rc1.dist-info/RECORD

@@ -0,0 +1,6 @@
+primarypath_client/__init__.py,sha256=qjcHhlfsfp10J0_T9sIWf1ebPeGod8y3f-20M3d3lu4,32579
+primarypath_sdk-1.0.0rc1.dist-info/licenses/LICENSE,sha256=z8d0m5b2O9McPEK1xHG_dWgUBT6EfBDz6wA0F7xSPTA,11358
+primarypath_sdk-1.0.0rc1.dist-info/METADATA,sha256=IW48URkk4tO_L6-bItPw8oMYTq9PzgMuzuf23kvbBKA,382
+primarypath_sdk-1.0.0rc1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+primarypath_sdk-1.0.0rc1.dist-info/top_level.txt,sha256=-gR54ltpNqXYJ7g_9wlcXPh025hUHgOBWGBe5ivaXoI,19
+primarypath_sdk-1.0.0rc1.dist-info/RECORD,,

primarypath_sdk-1.0.0rc1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

primarypath_sdk-1.0.0rc1.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

primarypath_sdk-1.0.0rc1.dist-info/top_level.txt

@@ -0,0 +1 @@
+primarypath_client