onkernel 0.2.0__py3-none-any.whl

kernel/__init__.py

@@ -0,0 +1,85 @@
+"""Kernel SDK — deterministic governance for AI agents."""
+
+from __future__ import annotations
+
+import warnings as _warnings
+from typing import Any as _Any
+
+__version__ = "0.2.0"
+
+import contextlib as _contextlib
+
+from kernel.client import Kernel
+from kernel.errors import (
+    AuthError,
+    CircuitOpenError,
+    FeatureNotInTier,
+    KernelDeniedError,
+    KernelError,
+    PlanCeilingHit,
+    PlanLimitExceeded,
+    PlanSoftWarning,
+    PolicyDeniedError,
+    RateLimitError,
+    ScannerBlockedError,
+    WebhookError,
+)
+from kernel.types import (
+    ActionResponse,
+    ApprovalResult,
+    ExecuteResponse,
+    KernelOutcome,
+    Session,
+    TokenResponse,
+)
+
+with _contextlib.suppress(ImportError):
+    from kernel.crypto import decrypt, decrypt_json  # noqa: F401 — re-export
+
+
+def __getattr__(name: str) -> _Any:
+    """Lazy deprecation for `kernel.ApprovalRequiredError` import.
+
+    The SDK no longer raises this exception (the 202 path now returns an
+    `ActionResponse` with `outcome == KernelOutcome.REQUIRES_HUMAN`). The
+    name is kept exported for one minor version so existing
+    `from kernel import ApprovalRequiredError` keeps importing. Reading
+    the symbol emits a `DeprecationWarning`; the class is removed in v0.3.
+    """
+    if name == "ApprovalRequiredError":
+        _warnings.warn(
+            "ApprovalRequiredError is deprecated and will be removed in v0.3. "
+            "The SDK no longer raises on 202 responses; branch on "
+            "ActionResponse.outcome (KernelOutcome.REQUIRES_HUMAN) instead. "
+            "See CHANGELOG for migration.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        from kernel.errors import ApprovalRequiredError as _AR
+        return _AR
+    raise AttributeError(f"module 'kernel' has no attribute {name!r}")
+
+
+__all__ = [
+    "Kernel",
+    "KernelError",
+    "AuthError",
+    "KernelDeniedError",
+    "PolicyDeniedError",
+    "ScannerBlockedError",
+    "RateLimitError",
+    "CircuitOpenError",
+    "WebhookError",
+    "PlanLimitExceeded",
+    "PlanCeilingHit",
+    "FeatureNotInTier",
+    "PlanSoftWarning",
+    "ActionResponse",
+    "KernelOutcome",
+    "Session",
+    "TokenResponse",
+    "ExecuteResponse",
+    "ApprovalResult",
+    # Deprecated, retained one minor version:
+    "ApprovalRequiredError",
+]

kernel/client.py

@@ -0,0 +1,285 @@
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from typing import Any
+
+import httpx
+
+from kernel import errors as _errors
+from kernel.errors import (
+    AuthError,
+    CircuitOpenError,
+    KernelError,
+    PlanSoftWarning,
+    RateLimitError,
+    WebhookError,
+    _build_denied,
+)
+from kernel.types import (
+    ActionResponse,
+    ApprovalResult,
+    ExecuteResponse,
+    Session,
+    TokenResponse,
+)
+
+
+class Kernel:
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = "http://localhost:8080",
+        timeout: float = 30.0,
+        on_plan_soft_warning: Callable[[PlanSoftWarning], None] | None = None,
+    ):
+        """
+        Args:
+            api_key:               Kernel agent API key (ok_live_… / ok_sand_…).
+            base_url:              Proxy URL.
+            timeout:               Per-request timeout in seconds.
+            on_plan_soft_warning:  Optional callback invoked when the request
+                succeeds but the workspace crossed its soft warning threshold
+                this request (Pricing spec §2.4 warning envelope). The callback
+                receives a PlanSoftWarning with limit/current/cap/message. The
+                request still succeeded normally — this is a billing nudge, not
+                an error. Fires at most once per period.
+        """
+        self.api_key = api_key
+        self.base_url = base_url.rstrip("/")
+        self.on_plan_soft_warning = on_plan_soft_warning
+        self._client = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+        )
+
+    # --- SDK endpoints (agent API key auth) ---
+
+    def execute(
+        self,
+        action: str,
+        target: str = "",
+        params: dict[str, Any] | None = None,
+        reasoning_trace: str = "",
+        session_id: str = "",
+        alternatives: list[dict] | None = None,
+        parent_decision_id: str = "",
+    ) -> ActionResponse:
+        """Submit an action for governance and (on ALLOW) execution.
+
+        parent_decision_id (A2A, W4.2): when this action is delegated by another
+        agent, pass that agent's ALLOW `decision_id` here. Kernel records the
+        agent-to-agent delegation chain in the signed audit log — the child
+        decision is linked to the parent and inherits the union of their
+        regulatory anchors. See `delegate()` for the expressive form.
+        """
+        headers: dict[str, str] = {}
+        if reasoning_trace:
+            headers["X-Reasoning-Trace"] = reasoning_trace
+        if session_id:
+            headers["X-Session-Id"] = session_id
+        if parent_decision_id:
+            headers["X-Kernel-Parent-Decision-Id"] = parent_decision_id
+
+        body: dict[str, Any] = {"action": action}
+        if target:
+            body["target"] = target
+        if params:
+            body["params"] = params
+        if alternatives:
+            body["alternatives"] = alternatives
+
+        # 202 (pending_approval) is NOT an exception any more (v0.2). We pass
+        # `allow_202=True` so the HTTP layer returns the body instead of
+        # raising. The caller then branches on `resp.outcome` —
+        # KernelOutcome.REQUIRES_HUMAN — to fork into the human-approval flow.
+        data = self._request(
+            "POST",
+            "/v1/agent-action",
+            json=body,
+            headers=headers,
+            allow_202=True,
+        )
+        return ActionResponse.from_dict(data)
+
+    def delegate(
+        self,
+        parent_decision_id: str,
+        action: str,
+        target: str = "",
+        params: dict[str, Any] | None = None,
+        reasoning_trace: str = "",
+        session_id: str = "",
+        alternatives: list[dict] | None = None,
+    ) -> ActionResponse:
+        """Execute an action delegated by another agent's ALLOW decision (A2A).
+
+        Reads like the call site it documents:
+
+            decision = orchestrator.execute("triage_refund", params=…)
+            kyc.delegate(decision.decision_id, "verify_identity", params=…)
+
+        Thin wrapper over `execute(..., parent_decision_id=…)` — Kernel stamps
+        the parent linkage (parent_audit_id + parent_agent_id + delegation_depth)
+        on the child's decision row and unions the regulatory anchors, so the
+        whole delegation chain is queryable end-to-end (GET /api/audit/chain).
+        A cross-tenant or unknown parent is refused identically to a missing one
+        (raises the same denial — no existence fingerprinting).
+        """
+        if not parent_decision_id:
+            raise ValueError(
+                "delegate() requires parent_decision_id (the delegating agent's "
+                "ALLOW decision_id); use execute() for a root action"
+            )
+        return self.execute(
+            action,
+            target=target,
+            params=params,
+            reasoning_trace=reasoning_trace,
+            session_id=session_id,
+            alternatives=alternatives,
+            parent_decision_id=parent_decision_id,
+        )
+
+    def create_session(self, intent: str) -> Session:
+        data = self._request("POST", "/v1/sessions", json={"intent": intent})
+        return Session.from_dict(data)
+
+    def request_token(
+        self,
+        session_id: str,
+        action: str,
+        target: str = "",
+        params: dict[str, Any] | None = None,
+    ) -> TokenResponse:
+        body: dict[str, Any] = {
+            "session_id": session_id,
+            "action": action,
+        }
+        if target:
+            body["target"] = target
+        if params:
+            body["params"] = params
+
+        data = self._request("POST", "/v1/tokens", json=body)
+        return TokenResponse.from_dict(data)
+
+    def execute_token(self, token_id: str, agent_id: str) -> ExecuteResponse:
+        headers = {
+            "X-Token-ID": token_id,
+            "X-Agent-ID": agent_id,
+        }
+        data = self._request("POST", "/v1/execute", headers=headers)
+        return ExecuteResponse.from_dict(data)
+
+    def poll_approval(
+        self,
+        approval_id: str,
+        timeout: float = 300,
+        interval: float = 2.0,
+    ) -> ApprovalResult:
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            resp = self._client.get(f"/v1/approvals/{approval_id}")
+            data = resp.json()
+            status = data.get("status", "")
+            if status != "pending":
+                return ApprovalResult.from_dict(data)
+            time.sleep(interval)
+        raise TimeoutError(f"Approval {approval_id} still pending after {timeout}s")
+
+    # --- Dashboard endpoints (JWT auth, not agent key) ---
+
+    def register_key(self, key_id: str, public_key_pem: str) -> dict:
+        return self._request(
+            "POST",
+            "/api/customers/keys",
+            json={"key_id": key_id, "public_key_pem": public_key_pem},
+        )
+
+    # --- Lifecycle ---
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> Kernel:
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    # --- Internal ---
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        **kwargs: Any,
+    ) -> dict:
+        extra_headers = kwargs.pop("headers", None)
+        allow_202 = kwargs.pop("allow_202", False)
+        if extra_headers:
+            merged = dict(self._client.headers)
+            merged.update(extra_headers)
+            kwargs["headers"] = merged
+
+        resp = self._client.request(method, path, **kwargs)
+        body = resp.json() if resp.content else {}
+
+        # Structured-error envelope (pricing spec §2.4): if the body carries
+        # an `error.code` field, map it to a typed exception first. Falls
+        # through to legacy {reason, status} handling for older proxies and
+        # for endpoints that haven't migrated yet.
+        if 400 <= resp.status_code < 600:
+            structured = _errors.from_response(resp.status_code, body)
+            if structured is not None:
+                raise structured
+
+        if resp.status_code == 202:
+            if allow_202:
+                # Normalize the 202 body so ActionResponse.from_dict sees the
+                # canonical "pending_approval" status — older proxies may emit
+                # `{"approval_id": "..."}` with status empty.
+                if isinstance(body, dict) and not body.get("status"):
+                    body["status"] = "pending_approval"
+                return body
+            # Legacy path (kept for non-execute endpoints, defensive).
+            from kernel.errors import ApprovalRequiredError as _AR
+            raise _AR(202, "Human approval required", body)
+        if resp.status_code == 401:
+            raise AuthError(401, body.get("error", "Authentication failed"), body)
+        if resp.status_code == 403:
+            # Sprint 04 SDK polish: 403 dispatches to ScannerBlockedError
+            # (violations populated) or PolicyDeniedError (empty violations)
+            # via the shared base KernelDeniedError. Existing
+            # `except PolicyDeniedError:` still catches both in v0.x because
+            # both inherit from KernelDeniedError; aliasing is documented in
+            # the CHANGELOG.
+            raise _build_denied(403, body.get("reason", "Policy denied"), body)
+        if resp.status_code == 429:
+            raise RateLimitError(429, body.get("reason", "Rate limit exceeded"), body)
+        if resp.status_code == 503:
+            raise CircuitOpenError(503, body.get("reason", "Circuit breaker open"), body)
+        if resp.status_code >= 500:
+            raise WebhookError(resp.status_code, body.get("reason", "Server error"), body)
+        if resp.status_code >= 400:
+            raise KernelError(resp.status_code, body.get("reason", resp.text), body)
+
+        # Soft warning: the request succeeded but the proxy is telling us the
+        # workspace crossed a soft threshold. Fires the callback (if any) and
+        # strips the `warning` block from the returned body so downstream
+        # handler code doesn't have to know about it.
+        if self.on_plan_soft_warning is not None:
+            warning_block = body.get("warning") if isinstance(body, dict) else None
+            if isinstance(warning_block, dict):
+                import contextlib
+
+                # Customer callback raised — never let it break the request.
+                with contextlib.suppress(Exception):
+                    self.on_plan_soft_warning(PlanSoftWarning(warning_block))
+
+        return body

kernel/crypto/__init__.py

@@ -0,0 +1,12 @@
+"""Envelope encryption utilities for decrypting Kernel responses."""
+
+from kernel.crypto.decrypt import decrypt, decrypt_json
+from kernel.crypto.keys import export_public_key_pem, generate_key_pair, load_private_key
+
+__all__ = [
+    "decrypt",
+    "decrypt_json",
+    "generate_key_pair",
+    "export_public_key_pem",
+    "load_private_key",
+]

kernel/crypto/decrypt.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+import base64
+import json
+from typing import Any
+
+from cryptography.hazmat.primitives import hashes, serialization
+from cryptography.hazmat.primitives.asymmetric import padding
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+
+def decrypt(payload: dict | Any, private_key: Any) -> bytes:
+    if isinstance(private_key, (str, bytes)):
+        private_key = _load_key(private_key)
+
+    ciphertext = base64.b64decode(payload["ciphertext"])
+    wrapped_dek = base64.b64decode(payload["wrapped_dek"])
+    nonce = base64.b64decode(payload["nonce"])
+
+    dek = private_key.decrypt(
+        wrapped_dek,
+        padding.OAEP(
+            mgf=padding.MGF1(algorithm=hashes.SHA256()),
+            algorithm=hashes.SHA256(),
+            label=None,
+        ),
+    )
+
+    return AESGCM(dek).decrypt(nonce, ciphertext, None)
+
+
+def decrypt_json(payload: dict | Any, private_key: Any) -> dict:
+    return json.loads(decrypt(payload, private_key))
+
+
+def _load_key(key_data: str | bytes) -> Any:
+    if isinstance(key_data, str):
+        key_data = key_data.encode()
+    return serialization.load_pem_private_key(key_data, password=None)

kernel/crypto/keys.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import rsa
+
+
+def generate_key_pair(key_size: int = 2048) -> tuple[Any, Any]:
+    private_key = rsa.generate_private_key(public_exponent=65537, key_size=key_size)
+    return private_key, private_key.public_key()
+
+
+def export_public_key_pem(public_key: Any) -> str:
+    return public_key.public_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    ).decode()
+
+
+def load_private_key(path_or_pem: str | Path) -> Any:
+    if isinstance(path_or_pem, str) and not path_or_pem.startswith("-----"):
+        p = Path(path_or_pem)
+        data = p.read_bytes()
+    elif isinstance(path_or_pem, Path):
+        data = path_or_pem.read_bytes()
+    else:
+        data = path_or_pem.encode() if isinstance(path_or_pem, str) else path_or_pem
+    return serialization.load_pem_private_key(data, password=None)

kernel/errors.py

@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+import warnings
+from typing import Any
+
+
+class KernelError(Exception):
+    def __init__(self, status_code: int, message: str, body: dict | None = None):
+        self.status_code = status_code
+        self.message = message
+        self.body = body or {}
+        super().__init__(f"[{status_code}] {message}")
+
+
+class AuthError(KernelError):
+    """401 — invalid or missing API key / JWT."""
+
+
+# ---------------------------------------------------------------------------
+# 403 — denied family
+#
+# Sprint 04 SDK polish: today consumers inspect `e.violations` truthiness to
+# distinguish scanner blocks from policy denies. That's a runtime sniff over
+# what should be a type-system distinction. We split the surface into two
+# sibling classes sharing a common base so existing
+#
+#     except PolicyDeniedError:
+#
+# keeps catching the same set of cases (the base IS PolicyDeniedError for
+# back-compat in v0.x), while new code can write:
+#
+#     except ScannerBlockedError as e: e.violation_type ...
+#     except PolicyDeniedError    as e: e.rule_id, e.policy_id ...
+#
+# The base class is exported as `KernelDeniedError` for callers who want to
+# catch both explicitly without subscribing to the back-compat name.
+# ---------------------------------------------------------------------------
+
+
+class PolicyDeniedError(KernelError):
+    """403 — a policy or scanner denied the action.
+
+    In v0.1, this was the SOLE 403 exception, with consumers inspecting
+    `e.violations` truthiness to distinguish scanner blocks from policy
+    denies. In v0.2 we introduce the sibling `ScannerBlockedError` so the
+    distinction is in the type system, not in field inspection.
+
+    Back-compat: `ScannerBlockedError` inherits from `PolicyDeniedError`
+    for the v0.2.x line, so existing `except PolicyDeniedError:` blocks
+    keep catching both. In v0.3, `ScannerBlockedError` will become a true
+    sibling under the shared `KernelDeniedError` base (and catching the
+    base by name will be the recommended pattern when both should be
+    handled). Use `isinstance(e, ScannerBlockedError)` (or simply
+    `except ScannerBlockedError:`) to start the migration now.
+
+    Attributes:
+        violations — list of scanner violation dicts (populated only on
+                     ScannerBlockedError; empty/None on the pure policy
+                     path)
+        reason     — human-readable proxy explanation
+        rule_id    — policy rule that denied, if surfaced (policy path)
+        policy_id  — owning policy id, if surfaced (policy path)
+    """
+
+    def __init__(self, status_code: int, message: str, body: dict | None = None):
+        super().__init__(status_code, message, body)
+        body = body or {}
+        self.violations = body.get("violations")
+        self.reason = body.get("reason", "")
+        rationale = body.get("rationale") if isinstance(body, dict) else None
+        if isinstance(rationale, dict):
+            self.rule_id: str = rationale.get("rule_id", "") or rationale.get(
+                "control_id", ""
+            )
+            self.policy_id: str = rationale.get("policy_id", "")
+        else:
+            self.rule_id = body.get("rule_id", "")
+            self.policy_id = body.get("policy_id", "")
+
+
+# Alias for callers who want to catch the whole 403-denial family by a name
+# that doesn't say "Policy". In v0.3 this becomes the actual base class and
+# `ScannerBlockedError` becomes a true sibling under it. Keeping it as an
+# alias in v0.2 means `except KernelDeniedError:` is forward-compatible.
+KernelDeniedError = PolicyDeniedError
+
+
+class ScannerBlockedError(PolicyDeniedError):
+    """403 — a scanner layer fired (PII, secrets, prompt injection, …).
+
+    Distinguishing signal: the response body carries a non-empty `violations`
+    list. The first violation drives the `violation_type` and
+    `violation_details` convenience attributes; access `violations` for the
+    full list when more than one fired.
+
+    In v0.2, this inherits from `PolicyDeniedError` so v0.1 code that catches
+    `PolicyDeniedError` keeps working. In v0.3 the two will become true
+    siblings under `KernelDeniedError`; migrate by catching them separately.
+
+    Attributes:
+        violation_type    — first violation's `type` (e.g. "pii.ssn",
+                            "secret.aws_key", "prompt_injection")
+        violation_details — first violation's full dict
+        violations        — list of all violation dicts (back-compat)
+    """
+
+    def __init__(self, status_code: int, message: str, body: dict | None = None):
+        super().__init__(status_code, message, body)
+        violations = self.violations or []
+        first: dict[str, Any] = (
+            violations[0] if violations and isinstance(violations[0], dict) else {}
+        )
+        self.violation_type: str = first.get("type", "")
+        self.violation_details: dict[str, Any] = first
+
+
+def _build_denied(status_code: int, message: str, body: dict | None) -> KernelDeniedError:
+    """Dispatch 403 bodies to the right sibling based on `violations`.
+
+    Used by the HTTP layer; also re-used by tests. Encapsulates the
+    "violations truthiness → ScannerBlockedError, else PolicyDeniedError"
+    rule so the dispatch logic lives in exactly one place.
+    """
+    violations = (body or {}).get("violations") if body else None
+    if violations:
+        return ScannerBlockedError(status_code, message, body)
+    return PolicyDeniedError(status_code, message, body)
+
+
+class RateLimitError(KernelError):
+    """429 — control group rate/spend limit exceeded."""
+
+
+class CircuitOpenError(KernelError):
+    """503 — circuit breaker is open for this agent."""
+
+
+class ApprovalRequiredError(KernelError):
+    """DEPRECATED — 202 responses no longer raise.
+
+    In v0.1.x, a 202 response (action escalated to human-in-the-loop)
+    raised this exception. Starting in v0.2, the SDK returns an
+    `ActionResponse` with `outcome == KernelOutcome.REQUIRES_HUMAN` so
+    callers can use `match/case` on `resp.outcome` instead of mixing a
+    happy-ish path into the except chain. See `KernelOutcome` in
+    `kernel.types`.
+
+    This class is retained as a deprecated alias for one minor version so
+    existing `except ApprovalRequiredError:` blocks keep importing. It is
+    NEVER raised by the SDK in v0.2+. Importing it emits a
+    `DeprecationWarning`; remove your `except ApprovalRequiredError` block
+    and branch on `resp.outcome` instead.
+    """
+
+    def __init__(self, status_code: int, message: str, body: dict | None = None):
+        super().__init__(status_code, message, body)
+        self.approval_id: str = (body or {}).get("approval_id", "")
+
+
+def __getattr__(name: str) -> Any:
+    # Lazy deprecation warning: only fires when someone actually imports
+    # ApprovalRequiredError from kernel.errors. We can't put the warning in
+    # the class body because `from kernel.errors import ApprovalRequiredError`
+    # at the top of the module doesn't trigger __getattr__; this hook fires
+    # when something accesses the attribute via getattr or a delayed import,
+    # and `kernel.__init__` re-routes the canonical re-export through here.
+    if name == "_ApprovalRequiredError_deprecation_check":
+        warnings.warn(
+            "ApprovalRequiredError is deprecated and will be removed in v0.3. "
+            "The SDK no longer raises on 202 responses; branch on "
+            "ActionResponse.outcome (KernelOutcome.REQUIRES_HUMAN) instead. "
+            "See CHANGELOG for migration.",
+            DeprecationWarning,
+            stacklevel=3,
+        )
+        return ApprovalRequiredError
+    raise AttributeError(name)
+
+
+class WebhookError(KernelError):
+    """500 — webhook call to customer backend failed."""
+
+
+# ---------------------------------------------------------------------------
+# Pricing / plan limit errors — Pricing spec §2.4 structured envelope.
+# The Go proxy returns a body shaped like
+#   {"error": {"code": "plan_limit_exceeded", "limit": "actions", ...}}
+# These classes pull the fields out so callers can route on
+#   except PlanLimitExceeded as e: ... route_to_billing(e.reset_at, e.tier)
+# ---------------------------------------------------------------------------
+
+
+class _StructuredError(KernelError):
+    """Internal base for spec-§2.4 errors: pulls the `error` sub-object out of
+    the body so subclasses can index fields directly without re-doing the
+    .get('error', {}) dance."""
+
+    def __init__(self, status_code: int, message: str, body: dict | None = None):
+        super().__init__(status_code, message, body)
+        self.error: dict = (body or {}).get("error", {})
+        self.code: str = self.error.get("code", "")
+        self.upgrade_url: str = self.error.get("upgrade_url", "")
+
+
+class PlanLimitExceeded(_StructuredError):
+    """402 — monthly action / ai_drafts quota or count limit hit.
+
+    Sales-team signal: this typically maps to an "upgrade to Pro" prompt.
+    Pair with PlanCeilingHit (which is the upgrade-to-Enterprise signal).
+
+    Attributes carry the spec-§2.4 fields:
+        limit    – which dimension hit ("actions", "agents", "seats", …)
+        tier     – the customer's current tier
+        current  – the counter value at denial
+        cap      – the cap that was hit
+        reset_at – RFC3339 timestamp for monthly quotas; empty for count limits
+    """
+
+    def __init__(self, status_code: int, message: str, body: dict | None = None):
+        super().__init__(status_code, message, body)
+        self.limit: str = self.error.get("limit", "")
+        self.tier: str = self.error.get("tier", "")
+        self.current: int = self.error.get("current", 0)
+        self.cap: int = self.error.get("cap", 0)
+        self.reset_at: str = self.error.get("reset_at", "")
+
+
+class PlanCeilingHit(PlanLimitExceeded):
+    """402 — Pro tier hit the hard ceiling (e.g. 150k actions/mo).
+
+    Distinct class from PlanLimitExceeded so customers can route the
+    upgrade-to-Enterprise signal differently from the upgrade-to-Pro signal.
+    """
+
+
+class FeatureNotInTier(_StructuredError):
+    """400 — feature gated to a higher tier (BYOK, SSO, tamper-evident, etc).
+
+    Attributes:
+        feature        – machine-readable feature name ("byok_encryption", …)
+        current_tier   – customer's current tier
+        required_tier  – the tier where this feature unlocks
+    """
+
+    def __init__(self, status_code: int, message: str, body: dict | None = None):
+        super().__init__(status_code, message, body)
+        self.feature: str = self.error.get("feature", "")
+        self.current_tier: str = self.error.get("current_tier", "")
+        self.required_tier: str = self.error.get("required_tier", "")
+
+
+class PlanSoftWarning:
+    """NOT an exception — payload of the on_plan_soft_warning callback.
+
+    When the proxy crosses the soft-warning threshold (Pro at 100k actions,
+    Sandbox at 4k), it returns the normal result PLUS:
+      - a RFC 7234 `Warning:` HTTP header
+      - a `warning` block in the JSON body alongside `result`
+    The SDK invokes the customer's optional on_plan_soft_warning(warning)
+    callback with one of these. The request still succeeded.
+
+    Attributes mirror the spec-§2.4 warning body:
+        limit    – "actions" | "ai_drafts"
+        current  – counter value after this increment
+        cap      – soft warning threshold that was crossed
+        message  – pre-rendered human-readable text
+    """
+
+    def __init__(self, body: dict):
+        self.code: str = body.get("code", "")
+        self.limit: str = body.get("limit", "")
+        self.current: int = body.get("current", 0)
+        self.cap: int = body.get("cap", 0)
+        self.message: str = body.get("message", "")
+
+
+def from_response(status_code: int, body: dict | None) -> KernelError | None:
+    """Map a structured-error response body to the right typed exception.
+
+    Returns None if the body doesn't carry an `error.code` field (caller
+    should fall back to legacy parsing or generic KernelError).
+
+    Use this in the HTTP-call layer:
+
+        if 400 <= resp.status_code < 600:
+            err = errors.from_response(resp.status_code, resp.json())
+            if err is not None:
+                raise err
+            # fall through to legacy {status, reason} body handling
+    """
+    if not body:
+        return None
+    err_block = body.get("error")
+    if not isinstance(err_block, dict):
+        return None
+    code = err_block.get("code", "")
+    message = err_block.get("message", "")
+    if code == "plan_limit_exceeded":
+        return PlanLimitExceeded(status_code, message, body)
+    if code == "plan_ceiling_hit":
+        return PlanCeilingHit(status_code, message, body)
+    if code == "feature_not_in_tier":
+        return FeatureNotInTier(status_code, message, body)
+    return None

kernel/types.py

@@ -0,0 +1,257 @@
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class KernelOutcome(str, Enum):
+    """The four control-flow outcomes of `Kernel.execute`.
+
+    Designed so callers can write:
+
+        resp = k.execute(...)
+        match resp.outcome:
+            case KernelOutcome.ALLOWED:        ...
+            case KernelOutcome.REQUIRES_HUMAN: ...
+            case KernelOutcome.BLOCKED:        ...
+            case KernelOutcome.DENIED:         ...
+
+    instead of mixing a happy-ish "ask a human" path into the except chain.
+
+    Outcome mapping from the proxy status field:
+        "executed"         → ALLOWED
+        "pending_approval" → REQUIRES_HUMAN   (HTTP 202)
+        "blocked"          → BLOCKED  (a scanner fired; was also `ScannerBlockedError`)
+        "denied"           → DENIED   (a policy rule fired; was also `PolicyDeniedError`)
+
+    Note: BLOCKED and DENIED outcomes are emitted ONLY when the proxy returns
+    them on a 2xx response (rare today — most proxies still return 403). The
+    HTTP-error path still raises `ScannerBlockedError` / `PolicyDeniedError`;
+    `match` on `outcome` is the unified surface once the proxy converges.
+    """
+
+    ALLOWED = "allowed"
+    REQUIRES_HUMAN = "requires_human"
+    BLOCKED = "blocked"
+    DENIED = "denied"
+
+
+def _derive_result_message(
+    explicit: str | None,
+    status: str,
+    result: dict | None,
+    reason: str | None,
+    approval_id: str | None,
+) -> str:
+    """Synthesize a human-readable summary when the proxy doesn't send one.
+
+    The Kernel proxy is expected to emit `result_message` (or legacy
+    `message`) directly. Until every proxy version does so reliably, we
+    derive a short summary from what's available — same intent, no new
+    backend dependency. LLMs reason better over a non-empty string than
+    over a None result.
+    """
+    if explicit:
+        return explicit
+    if status == "pending_approval" and approval_id:
+        return f"Action escalated to human approval (approval_id={approval_id})."
+    if status == "blocked":
+        return reason or "Action blocked by a scanner."
+    if status == "denied":
+        return reason or "Action denied by policy."
+    if status == "executed":
+        if isinstance(result, dict) and result:
+            keys = ", ".join(sorted(result.keys())[:3])
+            return f"Action executed; result contains: {keys}."
+        return "Action executed."
+    return reason or "Action completed."
+
+
+_STATUS_TO_OUTCOME: dict[str, KernelOutcome] = {
+    "executed": KernelOutcome.ALLOWED,
+    "pending_approval": KernelOutcome.REQUIRES_HUMAN,
+    "blocked": KernelOutcome.BLOCKED,
+    "denied": KernelOutcome.DENIED,
+}
+
+
+@dataclass
+class ActionResponse:
+    """Result of a single `Kernel.execute` call.
+
+    Sprint 04 polish (v0.2):
+      - `outcome` is the canonical control-flow surface; branch on this
+        instead of catching `ApprovalRequiredError`. See `KernelOutcome`.
+      - `result_message` is always non-empty — either the proxy's own
+        summary or a derived one (see `_derive_result_message`). Avoids
+        the LLM-anthropomorphizes-None problem when `result is None`.
+      - `message` is retained as a deprecated alias for `result_message`.
+        Reading `.message` emits a `DeprecationWarning`.
+    """
+
+    status: str
+    outcome: KernelOutcome = KernelOutcome.ALLOWED
+    token_id: str | None = None
+    result: dict | None = None
+    result_message: str = ""
+    approval_id: str | None = None
+    reason: str | None = None
+    violations: list | None = None
+    # decision_id (Sprint 04, GOV-V-01 + A2A W4.2) — the audit-event id of the
+    # ALLOW decision. Pass it as `parent_decision_id` to a downstream agent's
+    # `delegate()` to record the agent-to-agent delegation chain. None on
+    # non-ALLOW outcomes and from proxies predating execution verification.
+    decision_id: str | None = None
+
+    @property
+    def message(self) -> str:
+        """DEPRECATED — use `result_message`. Removed in v0.3."""
+        warnings.warn(
+            "ActionResponse.message is deprecated; use .result_message instead. "
+            "Will be removed in v0.3.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.result_message
+
+    @property
+    def encrypted(self) -> bool:
+        return isinstance(self.result, dict) and self.result.get("encrypted") is True
+
+    def decrypt(self, private_key) -> dict:
+        if not self.encrypted:
+            return self.result or {}
+        try:
+            from kernel.crypto import decrypt_json
+        except ImportError as exc:
+            raise ImportError(
+                "Install the crypto extra: pip install onkernel[crypto]"
+            ) from exc
+        return decrypt_json(self.result, private_key)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> ActionResponse:
+        status = data.get("status", "")
+        result = data.get("result")
+        reason = data.get("reason")
+        approval_id = data.get("approval_id")
+        # Backend currently emits `message`; spec calls for `result_message`.
+        # Accept either; prefer the spec name. Derived fallback if neither.
+        explicit_message = data.get("result_message") or data.get("message")
+        result_message = _derive_result_message(
+            explicit_message, status, result, reason, approval_id
+        )
+        outcome = _STATUS_TO_OUTCOME.get(status, KernelOutcome.ALLOWED)
+        if not explicit_message and status in _STATUS_TO_OUTCOME:
+            # Quiet hint so customers can flag stale proxies. Not a deprecation
+            # warning — the proxy is the one behind, not the caller — but a
+            # one-shot log via `warnings` is the lightest tool that's visible
+            # to anyone who runs `python -W default`.
+            warnings.warn(
+                "Proxy response did not include `result_message`; SDK derived "
+                "one from status/result. Upgrade the Kernel proxy for richer "
+                "summaries.",
+                category=UserWarning,
+                stacklevel=4,
+            )
+        return cls(
+            status=status,
+            outcome=outcome,
+            token_id=data.get("token_id"),
+            result=result,
+            result_message=result_message,
+            approval_id=approval_id,
+            reason=reason,
+            violations=data.get("violations"),
+            decision_id=data.get("decision_id"),
+        )
+
+
+@dataclass
+class Session:
+    id: str
+    agent_id: str
+    intent: str
+    expires_at: str
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Session:
+        return cls(
+            id=data.get("id", ""),
+            agent_id=data.get("agent_id", ""),
+            intent=data.get("intent", ""),
+            expires_at=data.get("expires_at", ""),
+        )
+
+
+@dataclass
+class TokenResponse:
+    token_id: str
+    expires_at: str
+    scoped_to: dict = field(default_factory=dict)
+    status: str = ""
+
+    @classmethod
+    def from_dict(cls, data: dict) -> TokenResponse:
+        return cls(
+            token_id=data.get("token_id", ""),
+            expires_at=data.get("expires_at", ""),
+            scoped_to=data.get("scoped_to", {}),
+            status=data.get("status", ""),
+        )
+
+
+@dataclass
+class ExecuteResponse:
+    status: str
+    token_consumed: bool = False
+    action: str = ""
+    target_result: dict = field(default_factory=dict)
+
+    @property
+    def encrypted(self) -> bool:
+        return isinstance(self.target_result, dict) and self.target_result.get("encrypted") is True
+
+    def decrypt(self, private_key) -> dict:
+        if not self.encrypted:
+            return self.target_result
+        try:
+            from kernel.crypto import decrypt_json
+        except ImportError as exc:
+            raise ImportError(
+                "Install the crypto extra: pip install onkernel[crypto]"
+            ) from exc
+        return decrypt_json(self.target_result, private_key)
+
+    @classmethod
+    def from_dict(cls, data: dict) -> ExecuteResponse:
+        return cls(
+            status=data.get("status", ""),
+            token_consumed=data.get("token_consumed", False),
+            action=data.get("action", ""),
+            target_result=data.get("target_result", {}),
+        )
+
+
+@dataclass
+class ApprovalResult:
+    status: str
+    decision: str | None = None
+    token_id: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> ApprovalResult:
+        return cls(
+            status=data.get("status", ""),
+            decision=data.get("decision"),
+            token_id=data.get("token_id"),
+        )
+
+
+@dataclass
+class EncryptedPayload:
+    ciphertext: bytes
+    wrapped_dek: bytes
+    key_id: str
+    nonce: bytes

onkernel-0.2.0.dist-info/METADATA

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: onkernel
+Version: 0.2.0
+Summary: Python SDK for Kernel — deterministic governance for AI agents
+Project-URL: Homepage, https://onkernel.ai
+Project-URL: Documentation, https://github.com/onkernel-ai/kernel-python#readme
+Project-URL: Repository, https://github.com/onkernel-ai/kernel-python
+Project-URL: Issues, https://github.com/onkernel-ai/kernel-python/issues
+Project-URL: Changelog, https://github.com/onkernel-ai/kernel-python/blob/main/CHANGELOG.md
+Author-email: Kernel <engineering@onkernel.ai>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,ai,governance,guardrails,llm,policy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: crypto
+Requires-Dist: cryptography>=44.0; extra == 'crypto'
+Provides-Extra: dev
+Requires-Dist: cryptography>=44.0; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# onkernel
+
+Python SDK for [Kernel](https://onkernel.ai) — deterministic governance for AI agents.
+
+## Install
+
+```bash
+pip install onkernel
+```
+
+For encrypted response decryption:
+
+```bash
+pip install onkernel[crypto]
+```
+
+## Quick Start
+
+```python
+from kernel import Kernel, KernelOutcome
+
+k = Kernel(api_key="ok_live_acme_bot1_abc123")
+
+resp = k.execute(action="send_email", target="user@example.com", params={"body": "Hello"})
+
+match resp.outcome:
+    case KernelOutcome.ALLOWED:
+        # resp.result and resp.result_message are populated
+        print(resp.result_message)
+    case KernelOutcome.REQUIRES_HUMAN:
+        # 202 — escalate to your approval queue
+        approval_id = resp.approval_id
+    case KernelOutcome.BLOCKED:
+        # a scanner fired; resp.violations is populated
+        ...
+    case KernelOutcome.DENIED:
+        # a policy rule denied; resp.reason explains why
+        ...
+```
+
+`ActionResponse` always carries a non-empty `result_message: str` — a
+human-readable summary that's safe to surface in an LLM tool-call result.
+
+### Handling errors
+
+The denial path raises typed exceptions on 403:
+
+```python
+from kernel import (
+    Kernel,
+    ScannerBlockedError,   # scanner fired (PII, secrets, prompt injection, …)
+    PolicyDeniedError,     # policy rule denied with no scanner involvement
+    KernelDeniedError,     # base / alias — catch both
+)
+
+try:
+    k.execute(action="export_pii_report", target="customers")
+except ScannerBlockedError as e:
+    # e.violation_type, e.violation_details, e.violations
+    pass
+except PolicyDeniedError as e:
+    # e.rule_id, e.policy_id, e.reason
+    pass
+```
+
+### 3-step token flow
+
+```python
+session = k.create_session(intent="onboard new customer")
+token = k.request_token(session.id, action="create_account", target="stripe")
+result = k.execute_token(token.token_id, agent_id="bot1")
+```
+
+## Decrypting Responses
+
+When a policy has `encryption_enabled: true`, responses arrive encrypted:
+
+```python
+from kernel import Kernel
+from kernel.crypto import load_private_key
+
+k = Kernel(api_key="ok_live_acme_bot1_abc123")
+private_key = load_private_key("path/to/private_key.pem")
+
+resp = k.execute(action="fetch_records", target="db")
+if resp.encrypted:
+    data = resp.decrypt(private_key)
+```
+
+## Publishing (maintainers)
+
+The SDK is published to PyPI as `onkernel`. Releases go out via tag push;
+the `publish.yml` workflow handles build + Trusted-Publishing OIDC.
+
+**Always release to TestPyPI first.** PyPI is fussy about metadata and
+artifact integrity; a TestPyPI dry-run catches mistakes before they're
+permanent (PyPI does not allow overwriting a released version).
+
+### One-time setup
+
+1. Create the project on PyPI: `pip install build twine && python -m build && twine upload --repository testpypi dist/*` (first manual upload claims the namespace).
+2. On PyPI → project → Publishing, add a pending publisher:
+   - Owner: `onkernel-ai`
+   - Repository: `kernel-python`
+   - Workflow: `publish.yml`
+   - Environment: `pypi`
+3. Repeat the publisher binding on test.pypi.org with environment `testpypi`.
+4. In the GitHub repo Settings → Environments, create `pypi` and `testpypi`. Add required reviewers on `pypi` if you want a release gate.
+
+### Cutting a release
+
+1. Bump `pyproject.toml` `[project].version` and `src/kernel/__init__.py` `__version__` together.
+2. Update `CHANGELOG.md`.
+3. Pre-release dry-run:
+   ```bash
+   git tag v0.X.Y-rc.1
+   git push --tags
+   ```
+   The `publish.yml` workflow detects the `-rc.N` suffix and routes to TestPyPI. Validate:
+   ```bash
+   pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ onkernel==0.X.Y-rc.1
+   python -c "from kernel import Kernel, KernelOutcome; print(KernelOutcome.ALLOWED)"
+   ```
+4. Real release:
+   ```bash
+   git tag v0.X.Y
+   git push --tags
+   ```
+   The same workflow routes the un-suffixed tag to real PyPI.
+
+The workflow verifies that the tag matches `pyproject.toml [project].version`
+before building — a mismatched tag fails fast instead of publishing the
+wrong artifact.
+
+### Fallback: manual API token
+
+If Trusted Publishing isn't yet bound, set repo secret `PYPI_API_TOKEN`
+and replace the OIDC publish step with:
+
+```yaml
+- run: twine upload -u __token__ -p "$PYPI_API_TOKEN" dist/*
+```
+
+Tokens carry blast-radius risk (leak = arbitrary release). Migrate to OIDC
+as soon as the binding is approved on the PyPI side.

onkernel-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+kernel/__init__.py,sha256=TlvsQNgraNb362EU6PuClyWfTsidRIJzuV0j47iZ8-I,2315
+kernel/client.py,sha256=AblkCoZs2U4-ohRiGiEnjW_n3w6u-I_TAHLAvTVAvEg,10733
+kernel/errors.py,sha256=mdv5uD3OUfJ_FGfjDTH6a9vYx5nRlLAk2Rs02_BDmDY,12883
+kernel/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kernel/types.py,sha256=Z6sKUxF42FCdP7qgSYf9fzm3KNYaVyf9U9rFbN-jBgY,8783
+kernel/crypto/__init__.py,sha256=OSls_1Ms9423eVr6rzmi_K2_CKvPPgsU-2A0lmOgBUA,344
+kernel/crypto/decrypt.py,sha256=ZBuV19MCicVbLT9iuE9W3BF4_tw0PHp-1tifmhD6oTw,1172
+kernel/crypto/keys.py,sha256=NBnmS8v4Tm9_0rRuGHC37kBVe1mw6gQB0-ZSKUk4pYA,1048
+onkernel-0.2.0.dist-info/METADATA,sha256=W4ZVKD4AsfKBy5axqch2Zy7oSfJzF5qrxyv61iRXKmQ,6060
+onkernel-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+onkernel-0.2.0.dist-info/licenses/LICENSE,sha256=UwKLRHQWJbLJ85_qnbzpNvhsuDpAG_rE6DnhVg9ejeI,1077
+onkernel-0.2.0.dist-info/RECORD,,

onkernel-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

onkernel-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kernel (onkernel.ai)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.