kernel 0.79.0__tar.gz → 0.81.0__tar.gz

kernel-0.81.0/.release-please-manifest.json

@@ -0,0 +1,3 @@
+{
+  ".": "0.81.0"
+}

{kernel-0.79.0 → kernel-0.81.0}/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## 0.81.0 (2026-07-21)
+
+Full Changelog: [v0.80.0...v0.81.0](https://github.com/kernel/kernel-python-sdk/compare/v0.80.0...v0.81.0)
+
+### Features
+
+* add complete audit log downloads ([18aa8c9](https://github.com/kernel/kernel-python-sdk/commit/18aa8c925b3f7699c30a6202685447432df2da6c))
+
+## 0.80.0 (2026-07-19)
+
+Full Changelog: [v0.79.0...v0.80.0](https://github.com/kernel/kernel-python-sdk/compare/v0.79.0...v0.80.0)
+
+### Features
+
+* Add example to ProxyCheckRequest.url so API reference sample shows it ([2a288ca](https://github.com/kernel/kernel-python-sdk/commit/2a288ca546da7760cdc16e566260fd440ae36fb7))
+* Expose browser sessions on auth timeline events ([687b401](https://github.com/kernel/kernel-python-sdk/commit/687b401117d37d6db8e818cd08ee3983671a23f6))
+* **managed-auth:** add TS CUA worker contract (KERNEL-1456) ([de2fc59](https://github.com/kernel/kernel-python-sdk/commit/de2fc590e00152328ac6a4f5165da0fb727644bb))
+* **stlc:** configurable CI runner and private-production-repo support in workflow templates ([79f96e4](https://github.com/kernel/kernel-python-sdk/commit/79f96e4e8d8f0e04e21c37010e1faa765f17afb6))
+
 ## 0.79.0 (2026-07-15)
 
 Full Changelog: [v0.78.1...v0.79.0](https://github.com/kernel/kernel-python-sdk/compare/v0.78.1...v0.79.0)

{kernel-0.79.0 → kernel-0.81.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: kernel
-Version: 0.79.0
+Version: 0.81.0
 Summary: The official Python library for the kernel API
 Project-URL: Homepage, https://github.com/kernel/kernel-python-sdk
 Project-URL: Repository, https://github.com/kernel/kernel-python-sdk

{kernel-0.79.0 → kernel-0.81.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "kernel"
-version = "0.79.0"
+version = "0.81.0"
 description = "The official Python library for the kernel API"
 dynamic = ["readme"]
 license = "Apache-2.0"

{kernel-0.79.0 → kernel-0.81.0}/src/kernel/__init__.py

@@ -51,6 +51,11 @@ from .app_framework import (
     app_registry,
     export_registry,
 )
+from .lib.audit_log_download import (
+    AuditLogDownloadError,
+    AuditLogDownloadResult,
+    AuditLogDownloadProgress,
+)
 
 __all__ = [
     "types",
@@ -105,6 +110,9 @@ __all__ = [
     "App",
     "app_registry",
     "export_registry",
+    "AuditLogDownloadError",
+    "AuditLogDownloadProgress",
+    "AuditLogDownloadResult",
 ]
 
 if not _t.TYPE_CHECKING:

{kernel-0.79.0 → kernel-0.81.0}/src/kernel/_version.py

@@ -1,4 +1,4 @@
 # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 __title__ = "kernel"
-__version__ = "0.79.0"  # x-release-please-version
+__version__ = "0.81.0"  # x-release-please-version

kernel-0.81.0/src/kernel/lib/audit_log_download.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+import time
+import hashlib
+import inspect
+from typing import BinaryIO, Callable, Optional, Protocol, Awaitable, ContextManager, AsyncContextManager
+from dataclasses import dataclass
+
+import anyio
+import httpx
+from anyio import to_thread
+
+from .._exceptions import KernelError
+
+_DEFAULT_MAX_TRANSFER_RETRIES = 6
+_MAX_CHUNK_ROWS = 50_000
+_MAX_RETRY_DELAY = 8.0
+
+
+class AuditLogDownloadError(KernelError):
+    pass
+
+
+@dataclass(frozen=True)
+class AuditLogDownloadResult:
+    bytes_written: int
+    chunks: int
+    rows: int
+
+
+@dataclass(frozen=True)
+class AuditLogDownloadProgress(AuditLogDownloadResult):
+    chunk_rows: int
+
+
+class _SyncChunkResponse(Protocol):
+    @property
+    def headers(self) -> httpx.Headers: ...
+
+    def read(self) -> bytes: ...
+
+    def close(self) -> None: ...
+
+
+class _AsyncChunkResponse(Protocol):
+    @property
+    def headers(self) -> httpx.Headers: ...
+
+    async def read(self) -> bytes: ...
+
+    async def close(self) -> None: ...
+
+
+SyncFetchChunk = Callable[[Optional[str]], ContextManager[_SyncChunkResponse]]
+AsyncFetchChunk = Callable[[Optional[str]], AsyncContextManager[_AsyncChunkResponse]]
+ProgressCallback = Callable[[AuditLogDownloadProgress], None]
+AsyncProgressCallback = Callable[[AuditLogDownloadProgress], Optional[Awaitable[None]]]
+
+
+def download_audit_logs(
+    fetch_chunk: SyncFetchChunk,
+    destination: BinaryIO,
+    *,
+    on_progress: ProgressCallback | None = None,
+    max_transfer_retries: int = _DEFAULT_MAX_TRANSFER_RETRIES,
+) -> AuditLogDownloadResult:
+    if not callable(getattr(destination, "write", None)):
+        raise TypeError("audit log download destination must provide write()")
+    _validate_max_transfer_retries(max_transfer_retries)
+
+    cursor: str | None = None
+    result = AuditLogDownloadResult(bytes_written=0, chunks=0, rows=0)
+    seen_cursors: set[str] = set()
+    while True:
+        body, headers = _fetch_verified_chunk(fetch_chunk, cursor, max_transfer_retries)
+        chunk_rows, next_cursor, has_more = _parse_chunk_headers(headers, cursor)
+        if has_more and next_cursor is not None:
+            if next_cursor in seen_cursors:
+                raise AuditLogDownloadError("response repeated X-Next-Cursor header")
+            seen_cursors.add(next_cursor)
+        _write_chunk(destination, body)
+
+        cursor = next_cursor
+        result = AuditLogDownloadResult(
+            bytes_written=result.bytes_written + len(body),
+            chunks=result.chunks + 1,
+            rows=result.rows + chunk_rows,
+        )
+        if on_progress is not None:
+            on_progress(
+                AuditLogDownloadProgress(
+                    bytes_written=result.bytes_written,
+                    chunks=result.chunks,
+                    rows=result.rows,
+                    chunk_rows=chunk_rows,
+                )
+            )
+        if not has_more:
+            return result
+
+
+async def async_download_audit_logs(
+    fetch_chunk: AsyncFetchChunk,
+    destination: BinaryIO,
+    *,
+    on_progress: AsyncProgressCallback | None = None,
+    max_transfer_retries: int = _DEFAULT_MAX_TRANSFER_RETRIES,
+) -> AuditLogDownloadResult:
+    if not callable(getattr(destination, "write", None)):
+        raise TypeError("audit log download destination must provide write()")
+    _validate_max_transfer_retries(max_transfer_retries)
+
+    cursor: str | None = None
+    result = AuditLogDownloadResult(bytes_written=0, chunks=0, rows=0)
+    seen_cursors: set[str] = set()
+    while True:
+        body, headers = await _async_fetch_verified_chunk(fetch_chunk, cursor, max_transfer_retries)
+        chunk_rows, next_cursor, has_more = _parse_chunk_headers(headers, cursor)
+        if has_more and next_cursor is not None:
+            if next_cursor in seen_cursors:
+                raise AuditLogDownloadError("response repeated X-Next-Cursor header")
+            seen_cursors.add(next_cursor)
+        await to_thread.run_sync(_write_chunk, destination, body)
+
+        cursor = next_cursor
+        result = AuditLogDownloadResult(
+            bytes_written=result.bytes_written + len(body),
+            chunks=result.chunks + 1,
+            rows=result.rows + chunk_rows,
+        )
+        if on_progress is not None:
+            callback_result = on_progress(
+                AuditLogDownloadProgress(
+                    bytes_written=result.bytes_written,
+                    chunks=result.chunks,
+                    rows=result.rows,
+                    chunk_rows=chunk_rows,
+                )
+            )
+            if inspect.isawaitable(callback_result):
+                await callback_result
+        if not has_more:
+            return result
+
+
+def _fetch_verified_chunk(
+    fetch_chunk: SyncFetchChunk, cursor: str | None, max_transfer_retries: int
+) -> tuple[bytes, httpx.Headers]:
+    for retries in range(max_transfer_retries + 1):
+        transfer_error: Exception | None = None
+        with fetch_chunk(cursor) as response:
+            try:
+                body = response.read()
+                headers = httpx.Headers(response.headers)
+                _verify_checksum(body, headers)
+            except Exception as error:
+                transfer_error = error
+            else:
+                return body, headers
+        assert transfer_error is not None
+        if retries == max_transfer_retries:
+            raise transfer_error
+        time.sleep(min(2**retries, _MAX_RETRY_DELAY))
+    raise AssertionError("unreachable")
+
+
+async def _async_fetch_verified_chunk(
+    fetch_chunk: AsyncFetchChunk, cursor: str | None, max_transfer_retries: int
+) -> tuple[bytes, httpx.Headers]:
+    for retries in range(max_transfer_retries + 1):
+        transfer_error: Exception | None = None
+        async with fetch_chunk(cursor) as response:
+            try:
+                body = await response.read()
+                headers = httpx.Headers(response.headers)
+                await to_thread.run_sync(_verify_checksum, body, headers)
+            except Exception as error:
+                transfer_error = error
+            else:
+                return body, headers
+        assert transfer_error is not None
+        if retries == max_transfer_retries:
+            raise transfer_error
+        await anyio.sleep(min(2**retries, _MAX_RETRY_DELAY))
+    raise AssertionError("unreachable")
+
+
+def _verify_checksum(body: bytes, headers: httpx.Headers) -> None:
+    expected = headers.get("x-content-sha256")
+    if not expected:
+        raise AuditLogDownloadError("response missing X-Content-Sha256 header")
+    actual = hashlib.sha256(body).hexdigest()
+    if actual != expected:
+        raise AuditLogDownloadError(f"audit log chunk checksum mismatch (got {actual}, want {expected})")
+
+
+def _parse_chunk_headers(headers: httpx.Headers, current_cursor: str | None) -> tuple[int, str | None, bool]:
+    has_more_value = headers.get("x-has-more")
+    if has_more_value not in {"true", "false"}:
+        raise AuditLogDownloadError("response missing or invalid X-Has-More header")
+    has_more = has_more_value == "true"
+
+    row_count = headers.get("x-row-count")
+    if row_count is None or not row_count.isascii() or not row_count.isdecimal():
+        raise AuditLogDownloadError("response missing or invalid X-Row-Count header")
+    normalized_row_count = row_count.lstrip("0") or "0"
+    if len(normalized_row_count) > len(str(_MAX_CHUNK_ROWS)):
+        raise AuditLogDownloadError("response missing or invalid X-Row-Count header")
+    rows = int(normalized_row_count)
+    if rows > _MAX_CHUNK_ROWS:
+        raise AuditLogDownloadError("response missing or invalid X-Row-Count header")
+
+    next_cursor = headers.get("x-next-cursor") or None
+    if has_more and (not next_cursor or next_cursor == current_cursor):
+        raise AuditLogDownloadError("response has invalid X-Next-Cursor header")
+    if not has_more and next_cursor:
+        raise AuditLogDownloadError("response returned a cursor after the final chunk")
+    return rows, next_cursor, has_more
+
+
+def _write_chunk(destination: BinaryIO, body: bytes) -> None:
+    remaining = memoryview(body)
+    while remaining:
+        written = destination.write(remaining)
+        if type(written) is not int or written <= 0 or written > len(remaining):
+            raise AuditLogDownloadError("audit log download destination performed a short write")
+        remaining = remaining[written:]
+
+
+def _validate_max_transfer_retries(max_transfer_retries: int) -> None:
+    if type(max_transfer_retries) is not int or max_transfer_retries < 0:
+        raise ValueError("max_transfer_retries must be a non-negative integer")

{kernel-0.79.0 → kernel-0.81.0}/src/kernel/resources/audit_logs.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import Union
+from typing import Union, BinaryIO, ContextManager, AsyncContextManager
 from datetime import datetime
 from typing_extensions import Literal
 
@@ -30,6 +30,13 @@ from .._response import (
 from ..pagination import SyncPageTokenPagination, AsyncPageTokenPagination
 from .._base_client import AsyncPaginator, make_request_options
 from ..types.audit_log_entry import AuditLogEntry
+from ..lib.audit_log_download import (
+    ProgressCallback,
+    AsyncProgressCallback,
+    AuditLogDownloadResult,
+    download_audit_logs,
+    async_download_audit_logs,
+)
 
 __all__ = ["AuditLogsResource", "AsyncAuditLogsResource"]
 
@@ -222,6 +229,60 @@ class AuditLogsResource(SyncAPIResource):
             cast_to=BinaryAPIResponse,
         )
 
+    def download(
+        self,
+        *,
+        to: BinaryIO,
+        end: Union[str, datetime],
+        start: Union[str, datetime],
+        auth_strategy: str | Omit = omit,
+        exclude_method: SequenceNotStr[str] | Omit = omit,
+        limit: int | Omit = omit,
+        method: str | Omit = omit,
+        search: str | Omit = omit,
+        search_user_id: SequenceNotStr[str] | Omit = omit,
+        service: str | Omit = omit,
+        on_progress: ProgressCallback | None = None,
+        max_transfer_retries: int = 6,
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> AuditLogDownloadResult:
+        """Download a complete gzip-compressed JSON Lines audit log export.
+
+        The SDK writes the export to a writable binary destination, verifies
+        every chunk, and retries transient transfer failures. It does not close
+        the destination. If the download fails, the destination may contain a
+        partial export; use a temporary file and atomic rename when the completed
+        export must be published atomically.
+        """
+
+        def fetch_chunk(cursor: str | None) -> ContextManager[StreamedBinaryAPIResponse]:
+            return self.with_streaming_response.export_chunk(
+                end=end,
+                start=start,
+                auth_strategy=auth_strategy,
+                cursor=cursor if cursor is not None else omit,
+                exclude_method=exclude_method,
+                limit=limit,
+                method=method,
+                search=search,
+                search_user_id=search_user_id,
+                service=service,
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+            )
+
+        return download_audit_logs(
+            fetch_chunk,
+            to,
+            on_progress=on_progress,
+            max_transfer_retries=max_transfer_retries,
+        )
+
 
 class AsyncAuditLogsResource(AsyncAPIResource):
     """Read audit log records for the authenticated organization."""
@@ -411,6 +472,60 @@ class AsyncAuditLogsResource(AsyncAPIResource):
             cast_to=AsyncBinaryAPIResponse,
         )
 
+    async def download(
+        self,
+        *,
+        to: BinaryIO,
+        end: Union[str, datetime],
+        start: Union[str, datetime],
+        auth_strategy: str | Omit = omit,
+        exclude_method: SequenceNotStr[str] | Omit = omit,
+        limit: int | Omit = omit,
+        method: str | Omit = omit,
+        search: str | Omit = omit,
+        search_user_id: SequenceNotStr[str] | Omit = omit,
+        service: str | Omit = omit,
+        on_progress: AsyncProgressCallback | None = None,
+        max_transfer_retries: int = 6,
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx.Timeout | None | NotGiven = not_given,
+    ) -> AuditLogDownloadResult:
+        """Download a complete gzip-compressed JSON Lines audit log export.
+
+        The SDK writes the export to a writable binary destination, verifies
+        every chunk, and retries transient transfer failures. It does not close
+        the destination. If the download fails, the destination may contain a
+        partial export; use a temporary file and atomic rename when the completed
+        export must be published atomically.
+        """
+
+        def fetch_chunk(cursor: str | None) -> AsyncContextManager[AsyncStreamedBinaryAPIResponse]:
+            return self.with_streaming_response.export_chunk(
+                end=end,
+                start=start,
+                auth_strategy=auth_strategy,
+                cursor=cursor if cursor is not None else omit,
+                exclude_method=exclude_method,
+                limit=limit,
+                method=method,
+                search=search,
+                search_user_id=search_user_id,
+                service=service,
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+            )
+
+        return await async_download_audit_logs(
+            fetch_chunk,
+            to,
+            on_progress=on_progress,
+            max_transfer_retries=max_transfer_retries,
+        )
+
 
 class AuditLogsResourceWithRawResponse:
     def __init__(self, audit_logs: AuditLogsResource) -> None:

{kernel-0.79.0 → kernel-0.81.0}/src/kernel/resources/auth/connections.py

@@ -505,8 +505,10 @@ class ConnectionsResource(SyncAPIResource):
         self,
         id: str,
         *,
+        field_values: Dict[str, str] | Omit = omit,
         fields: Dict[str, str] | Omit = omit,
         mfa_option_id: str | Omit = omit,
+        selected_choice_id: str | Omit = omit,
         sign_in_option_id: str | Omit = omit,
         sso_button_selector: str | Omit = omit,
         sso_provider: str | Omit = omit,
@@ -523,10 +525,14 @@ class ConnectionsResource(SyncAPIResource):
         progress and get results.
 
         Args:
+          field_values: Canonical map of field ID to submitted value.
+
           fields: Map of field name to value
 
           mfa_option_id: The MFA method type to select (when mfa_options were returned)
 
+          selected_choice_id: Canonical choice ID selected by the user.
+
           sign_in_option_id: The sign-in option ID to select (when sign_in_options were returned)
 
           sso_button_selector: XPath selector for the SSO button to click (ODA). Use sso_provider instead for
@@ -549,8 +555,10 @@ class ConnectionsResource(SyncAPIResource):
             path_template("/auth/connections/{id}/submit", id=id),
             body=maybe_transform(
                 {
+                    "field_values": field_values,
                     "fields": fields,
                     "mfa_option_id": mfa_option_id,
+                    "selected_choice_id": selected_choice_id,
                     "sign_in_option_id": sign_in_option_id,
                     "sso_button_selector": sso_button_selector,
                     "sso_provider": sso_provider,
@@ -1088,8 +1096,10 @@ class AsyncConnectionsResource(AsyncAPIResource):
         self,
         id: str,
         *,
+        field_values: Dict[str, str] | Omit = omit,
         fields: Dict[str, str] | Omit = omit,
         mfa_option_id: str | Omit = omit,
+        selected_choice_id: str | Omit = omit,
         sign_in_option_id: str | Omit = omit,
         sso_button_selector: str | Omit = omit,
         sso_provider: str | Omit = omit,
@@ -1106,10 +1116,14 @@ class AsyncConnectionsResource(AsyncAPIResource):
         progress and get results.
 
         Args:
+          field_values: Canonical map of field ID to submitted value.
+
           fields: Map of field name to value
 
           mfa_option_id: The MFA method type to select (when mfa_options were returned)
 
+          selected_choice_id: Canonical choice ID selected by the user.
+
           sign_in_option_id: The sign-in option ID to select (when sign_in_options were returned)
 
           sso_button_selector: XPath selector for the SSO button to click (ODA). Use sso_provider instead for
@@ -1132,8 +1146,10 @@ class AsyncConnectionsResource(AsyncAPIResource):
             path_template("/auth/connections/{id}/submit", id=id),
             body=await async_maybe_transform(
                 {
+                    "field_values": field_values,
                     "fields": fields,
                     "mfa_option_id": mfa_option_id,
+                    "selected_choice_id": selected_choice_id,
                     "sign_in_option_id": sign_in_option_id,
                     "sso_button_selector": sso_button_selector,
                     "sso_provider": sso_provider,

{kernel-0.79.0 → kernel-0.81.0}/src/kernel/types/auth/connection_follow_response.py

@@ -12,13 +12,36 @@ from ..shared.heartbeat_event import HeartbeatEvent
 __all__ = [
     "ConnectionFollowResponse",
     "ManagedAuthStateEvent",
+    "ManagedAuthStateEventChoice",
     "ManagedAuthStateEventDiscoveredField",
+    "ManagedAuthStateEventField",
     "ManagedAuthStateEventMfaOption",
     "ManagedAuthStateEventPendingSSOButton",
     "ManagedAuthStateEventSignInOption",
 ]
 
 
+class ManagedAuthStateEventChoice(BaseModel):
+    """Canonical auth-flow choice awaiting user selection."""
+
+    id: str
+    """Stable choice identifier for canonical submit."""
+
+    label: str
+    """Human-readable choice label."""
+
+    type: Literal[
+        "mfa_method", "sso_provider", "sign_in_method", "auth_method", "identifier_method", "account", "other"
+    ]
+    """Choice type."""
+
+    description: Optional[str] = None
+    """Additional context for the choice."""
+
+    observed_selector: Optional[str] = None
+    """Selector for the visible choice, when available."""
+
+
 class ManagedAuthStateEventDiscoveredField(BaseModel):
     """A discovered form field"""
 
@@ -53,6 +76,28 @@ class ManagedAuthStateEventDiscoveredField(BaseModel):
     """Whether field is required"""
 
 
+class ManagedAuthStateEventField(BaseModel):
+    """Canonical field awaiting user input."""
+
+    id: str
+    """Stable field identifier for canonical submit."""
+
+    ref: str
+    """Credential reference name to store the submitted value under."""
+
+    type: Literal["identifier", "password", "code", "totp_code", "totp_secret", "text"]
+    """Managed-auth field type."""
+
+    label: Optional[str] = None
+    """Human-readable label shown to the user."""
+
+    observed_selector: Optional[str] = None
+    """Selector for the visible field, when available."""
+
+    required: Optional[bool] = None
+    """Whether this field is required."""
+
+
 class ManagedAuthStateEventMfaOption(BaseModel):
     """An MFA method option for verification"""
 
@@ -118,6 +163,13 @@ class ManagedAuthStateEvent(BaseModel):
     timestamp: datetime
     """Time the state was reported."""
 
+    choices: Optional[List[ManagedAuthStateEventChoice]] = None
+    """Canonical choices awaiting selection.
+
+    Prefer this over pending_sso_buttons, mfa_options, and sign_in_options when
+    present.
+    """
+
     discovered_fields: Optional[List[ManagedAuthStateEventDiscoveredField]] = None
     """
     Fields awaiting input (present when flow_step=AWAITING_INPUT; may also be
@@ -136,6 +188,12 @@ class ManagedAuthStateEvent(BaseModel):
     flow_step=AWAITING_EXTERNAL_ACTION).
     """
 
+    fields: Optional[List[ManagedAuthStateEventField]] = None
+    """Canonical fields awaiting input.
+
+    Prefer this over discovered_fields when present.
+    """
+
     flow_type: Optional[Literal["LOGIN", "REAUTH"]] = None
     """Type of the current flow."""
 

{kernel-0.79.0 → kernel-0.81.0}/src/kernel/types/auth/connection_submit_params.py

@@ -9,12 +9,18 @@ __all__ = ["ConnectionSubmitParams"]
 
 
 class ConnectionSubmitParams(TypedDict, total=False):
+    field_values: Dict[str, str]
+    """Canonical map of field ID to submitted value."""
+
     fields: Dict[str, str]
     """Map of field name to value"""
 
     mfa_option_id: str
     """The MFA method type to select (when mfa_options were returned)"""
 
+    selected_choice_id: str
+    """Canonical choice ID selected by the user."""
+
     sign_in_option_id: str
     """The sign-in option ID to select (when sign_in_options were returned)"""