kernel 0.114.0__tar.gz → 0.116.0__tar.gz

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

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

{kernel-0.114.0 → kernel-0.116.0}/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.116.0](https://github.com/kernel/kernel-python-sdk/compare/v0.115.0...v0.116.0) (2026-10-01)
+
+
+### Features
+
+* chore(stlc): seal custom-code tracking files ([c053ce4](https://github.com/kernel/kernel-python-sdk/commit/c053ce45e5d6bfaa4577310d28b3ecf0a7c16f4e))
+
+## [0.115.0](https://github.com/kernel/kernel-python-sdk/compare/v0.114.0...v0.115.0) (2026-09-30)
+
+
+### Features
+
+* Fetch content for selected results from retained searches ([kernel/kernel#3978](https://github.com/kernel/kernel/pull/3978))
+
 ## [0.114.0](https://github.com/kernel/kernel-python-sdk/compare/v0.113.0...v0.114.0) (2026-09-30)
 
 

{kernel-0.114.0 → kernel-0.116.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: kernel
-Version: 0.114.0
+Version: 0.116.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.114.0 → kernel-0.116.0}/api.md

@@ -791,7 +791,7 @@ from kernel.types.search import FetchRequest, Response
 
 Methods:
 
-- <code title="post /search/{id}/contents">client.search.contents.<a href="./src/kernel/resources/search/contents.py">fetch</a>(id, \*\*<a href="src/kernel/types/search/content_fetch_params.py">params</a>) -> None</code>
+- <code title="post /search/{id}/contents">client.search.contents.<a href="./src/kernel/resources/search/contents.py">fetch</a>(id, \*\*<a href="src/kernel/types/search/content_fetch_params.py">params</a>) -> <a href="./src/kernel/types/search/response.py">Response</a></code>
 
 ## Providers
 

{kernel-0.114.0 → kernel-0.116.0}/pyproject.toml

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

{kernel-0.114.0 → kernel-0.116.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.114.0"  # x-release-please-version
+__version__ = "0.116.0"  # x-release-please-version

{kernel-0.114.0 → kernel-0.116.0}/src/kernel/resources/credentials.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from typing import Dict, Optional
+from typing_extensions import Literal
 
 import httpx
 
@@ -54,6 +55,9 @@ class CredentialsResource(SyncAPIResource):
         name: str,
         values: Dict[str, str],
         sso_provider: str | Omit = omit,
+        totp_algorithm: Literal["SHA1", "SHA256", "SHA512"] | Omit = omit,
+        totp_digits: int | Omit = omit,
+        totp_period: int | Omit = omit,
         totp_secret: str | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
@@ -77,8 +81,20 @@ class CredentialsResource(SyncAPIResource):
               button, it will be clicked first before filling credential values on the
               identity provider's login page.
 
-          totp_secret: Base32-encoded TOTP secret for generating one-time passwords. Used for automatic
-              2FA during login.
+          totp_algorithm: HMAC algorithm used to generate TOTP codes. Defaults to SHA1 and is ignored when
+              an `otpauth://` URI supplies the algorithm.
+
+          totp_digits: Number of digits in generated TOTP codes. Defaults to 6 and is ignored when an
+              `otpauth://` URI supplies the digit count.
+
+          totp_period: TOTP rotation period in seconds. Defaults to 30 and is ignored when an
+              `otpauth://` URI supplies the period.
+
+          totp_secret: Accepts a 16-128 character base32-encoded TOTP secret or an `otpauth://totp/...`
+              URI. The range accepts existing shorter seeds and longer seeds regardless of
+              HMAC algorithm; RFC 6238 recommends unpadded base32 lengths of 32/52/103 for
+              SHA1/SHA256/SHA512. Only URI parameters present override the corresponding
+              explicit TOTP fields. Used for automatic 2FA during login.
 
           extra_headers: Send extra headers
 
@@ -96,6 +112,9 @@ class CredentialsResource(SyncAPIResource):
                     "name": name,
                     "values": values,
                     "sso_provider": sso_provider,
+                    "totp_algorithm": totp_algorithm,
+                    "totp_digits": totp_digits,
+                    "totp_period": totp_period,
                     "totp_secret": totp_secret,
                 },
                 credential_create_params.CredentialCreateParams,
@@ -147,6 +166,9 @@ class CredentialsResource(SyncAPIResource):
         name: str | Omit = omit,
         remove_value_keys: SequenceNotStr[str] | Omit = omit,
         sso_provider: Optional[str] | Omit = omit,
+        totp_algorithm: Literal["SHA1", "SHA256", "SHA512"] | Omit = omit,
+        totp_digits: int | Omit = omit,
+        totp_period: int | Omit = omit,
         totp_secret: str | Omit = omit,
         values: Dict[str, str] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
@@ -170,8 +192,20 @@ class CredentialsResource(SyncAPIResource):
           sso_provider: If set, indicates this credential should be used with the specified SSO
               provider. Set to empty string or null to remove.
 
-          totp_secret: Base32-encoded TOTP secret for generating one-time passwords. Spaces and
-              formatting are automatically normalized. Set to empty string to remove.
+          totp_algorithm: HMAC algorithm used to generate TOTP codes. Requires totp_secret and is ignored
+              when an `otpauth://` URI supplies the algorithm.
+
+          totp_digits: Number of digits in generated TOTP codes. Requires totp_secret and is ignored
+              when an `otpauth://` URI supplies the digit count.
+
+          totp_period: TOTP rotation period in seconds. Requires totp_secret and is ignored when an
+              `otpauth://` URI supplies the period.
+
+          totp_secret: Accepts a 16-128 character base32-encoded TOTP secret or an `otpauth://totp/...`
+              URI. Only URI parameters present override the corresponding explicit TOTP
+              fields. When rotating a raw secret, omitted fields preserve their existing
+              values; a new URI defaults unspecified fields to SHA1/6/30. Set to empty string
+              to remove the secret and its metadata.
 
           values: Field name to value mapping. Values are merged with existing values (new keys
               added, existing keys overwritten).
@@ -193,6 +227,9 @@ class CredentialsResource(SyncAPIResource):
                     "name": name,
                     "remove_value_keys": remove_value_keys,
                     "sso_provider": sso_provider,
+                    "totp_algorithm": totp_algorithm,
+                    "totp_digits": totp_digits,
+                    "totp_period": totp_period,
                     "totp_secret": totp_secret,
                     "values": values,
                 },
@@ -360,6 +397,9 @@ class AsyncCredentialsResource(AsyncAPIResource):
         name: str,
         values: Dict[str, str],
         sso_provider: str | Omit = omit,
+        totp_algorithm: Literal["SHA1", "SHA256", "SHA512"] | Omit = omit,
+        totp_digits: int | Omit = omit,
+        totp_period: int | Omit = omit,
         totp_secret: str | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
         # The extra values given here take precedence over values defined on the client or passed to this method.
@@ -383,8 +423,20 @@ class AsyncCredentialsResource(AsyncAPIResource):
               button, it will be clicked first before filling credential values on the
               identity provider's login page.
 
-          totp_secret: Base32-encoded TOTP secret for generating one-time passwords. Used for automatic
-              2FA during login.
+          totp_algorithm: HMAC algorithm used to generate TOTP codes. Defaults to SHA1 and is ignored when
+              an `otpauth://` URI supplies the algorithm.
+
+          totp_digits: Number of digits in generated TOTP codes. Defaults to 6 and is ignored when an
+              `otpauth://` URI supplies the digit count.
+
+          totp_period: TOTP rotation period in seconds. Defaults to 30 and is ignored when an
+              `otpauth://` URI supplies the period.
+
+          totp_secret: Accepts a 16-128 character base32-encoded TOTP secret or an `otpauth://totp/...`
+              URI. The range accepts existing shorter seeds and longer seeds regardless of
+              HMAC algorithm; RFC 6238 recommends unpadded base32 lengths of 32/52/103 for
+              SHA1/SHA256/SHA512. Only URI parameters present override the corresponding
+              explicit TOTP fields. Used for automatic 2FA during login.
 
           extra_headers: Send extra headers
 
@@ -402,6 +454,9 @@ class AsyncCredentialsResource(AsyncAPIResource):
                     "name": name,
                     "values": values,
                     "sso_provider": sso_provider,
+                    "totp_algorithm": totp_algorithm,
+                    "totp_digits": totp_digits,
+                    "totp_period": totp_period,
                     "totp_secret": totp_secret,
                 },
                 credential_create_params.CredentialCreateParams,
@@ -453,6 +508,9 @@ class AsyncCredentialsResource(AsyncAPIResource):
         name: str | Omit = omit,
         remove_value_keys: SequenceNotStr[str] | Omit = omit,
         sso_provider: Optional[str] | Omit = omit,
+        totp_algorithm: Literal["SHA1", "SHA256", "SHA512"] | Omit = omit,
+        totp_digits: int | Omit = omit,
+        totp_period: int | Omit = omit,
         totp_secret: str | Omit = omit,
         values: Dict[str, str] | Omit = omit,
         # Use the following arguments if you need to pass additional parameters to the API that aren't available via kwargs.
@@ -476,8 +534,20 @@ class AsyncCredentialsResource(AsyncAPIResource):
           sso_provider: If set, indicates this credential should be used with the specified SSO
               provider. Set to empty string or null to remove.
 
-          totp_secret: Base32-encoded TOTP secret for generating one-time passwords. Spaces and
-              formatting are automatically normalized. Set to empty string to remove.
+          totp_algorithm: HMAC algorithm used to generate TOTP codes. Requires totp_secret and is ignored
+              when an `otpauth://` URI supplies the algorithm.
+
+          totp_digits: Number of digits in generated TOTP codes. Requires totp_secret and is ignored
+              when an `otpauth://` URI supplies the digit count.
+
+          totp_period: TOTP rotation period in seconds. Requires totp_secret and is ignored when an
+              `otpauth://` URI supplies the period.
+
+          totp_secret: Accepts a 16-128 character base32-encoded TOTP secret or an `otpauth://totp/...`
+              URI. Only URI parameters present override the corresponding explicit TOTP
+              fields. When rotating a raw secret, omitted fields preserve their existing
+              values; a new URI defaults unspecified fields to SHA1/6/30. Set to empty string
+              to remove the secret and its metadata.
 
           values: Field name to value mapping. Values are merged with existing values (new keys
               added, existing keys overwritten).
@@ -499,6 +569,9 @@ class AsyncCredentialsResource(AsyncAPIResource):
                     "name": name,
                     "remove_value_keys": remove_value_keys,
                     "sso_provider": sso_provider,
+                    "totp_algorithm": totp_algorithm,
+                    "totp_digits": totp_digits,
+                    "totp_period": totp_period,
                     "totp_secret": totp_secret,
                     "values": values,
                 },

{kernel-0.114.0 → kernel-0.116.0}/src/kernel/resources/search/contents.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import httpx
 
-from ..._types import Body, Omit, Query, Headers, NoneType, NotGiven, SequenceNotStr, omit, not_given
+from ..._types import Body, Omit, Query, Headers, NotGiven, SequenceNotStr, omit, not_given
 from ..._utils import path_template, maybe_transform, async_maybe_transform
 from ..._compat import cached_property
 from ..._resource import SyncAPIResource, AsyncAPIResource
@@ -16,6 +16,7 @@ from ..._response import (
 )
 from ..._base_client import make_request_options
 from ...types.search import content_fetch_params
+from ...types.search.response import Response
 
 __all__ = ["ContentsResource", "AsyncContentsResource"]
 
@@ -56,11 +57,18 @@ class ContentsResource(SyncAPIResource):
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
-    ) -> None:
-        """
-        Deferred result-content retrieval is reserved but not available in this release.
-        Requests return 404 until the retrieval implementation is shipped. X-Request-Id
-        identifies this request separately from the search resource.
+    ) -> Response:
+        """Retrieves selected results from a retained search.
+
+        Provide exactly one of
+        result_ids or limit; the latter fetches the top results. Content defaults to
+        source:auto. Responses preserve result_ids order. Unknown result IDs are
+        rejected before retrieval starts. Missing, expired, or inaccessible searches
+        return 404. Once retrieval begins, return one outcome per selected result,
+        including timeout entries for work unfinished at the overall deadline. Browser
+        retrievals run sequentially in result order, so later results may time out when
+        earlier pages are slow. X-Request-Id identifies this request separately from the
+        search resource.
 
         Args:
           content: Defaults to source:auto when omitted.
@@ -83,7 +91,6 @@ class ContentsResource(SyncAPIResource):
         """
         if not id:
             raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
-        extra_headers = {"Accept": "*/*", **(extra_headers or {})}
         return self._post(
             path_template("/search/{id}/contents", id=id),
             body=maybe_transform(
@@ -98,7 +105,7 @@ class ContentsResource(SyncAPIResource):
             options=make_request_options(
                 extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
             ),
-            cast_to=NoneType,
+            cast_to=Response,
         )
 
 
@@ -138,11 +145,18 @@ class AsyncContentsResource(AsyncAPIResource):
         extra_query: Query | None = None,
         extra_body: Body | None = None,
         timeout: float | httpx.Timeout | None | NotGiven = not_given,
-    ) -> None:
-        """
-        Deferred result-content retrieval is reserved but not available in this release.
-        Requests return 404 until the retrieval implementation is shipped. X-Request-Id
-        identifies this request separately from the search resource.
+    ) -> Response:
+        """Retrieves selected results from a retained search.
+
+        Provide exactly one of
+        result_ids or limit; the latter fetches the top results. Content defaults to
+        source:auto. Responses preserve result_ids order. Unknown result IDs are
+        rejected before retrieval starts. Missing, expired, or inaccessible searches
+        return 404. Once retrieval begins, return one outcome per selected result,
+        including timeout entries for work unfinished at the overall deadline. Browser
+        retrievals run sequentially in result order, so later results may time out when
+        earlier pages are slow. X-Request-Id identifies this request separately from the
+        search resource.
 
         Args:
           content: Defaults to source:auto when omitted.
@@ -165,7 +179,6 @@ class AsyncContentsResource(AsyncAPIResource):
         """
         if not id:
             raise ValueError(f"Expected a non-empty value for `id` but received {id!r}")
-        extra_headers = {"Accept": "*/*", **(extra_headers or {})}
         return await self._post(
             path_template("/search/{id}/contents", id=id),
             body=await async_maybe_transform(
@@ -180,7 +193,7 @@ class AsyncContentsResource(AsyncAPIResource):
             options=make_request_options(
                 extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
             ),
-            cast_to=NoneType,
+            cast_to=Response,
         )
 
 

{kernel-0.114.0 → kernel-0.116.0}/src/kernel/types/credential.py

@@ -2,6 +2,7 @@
 
 from typing import List, Optional
 from datetime import datetime
+from typing_extensions import Literal
 
 from .._models import BaseModel
 
@@ -40,8 +41,14 @@ class Credential(BaseModel):
     identity provider's login page.
     """
 
+    totp_algorithm: Optional[Literal["SHA1", "SHA256", "SHA512"]] = None
+    """HMAC algorithm used to generate TOTP codes.
+
+    Defaults to SHA1 for credentials created before this metadata was stored.
+    """
+
     totp_code: Optional[str] = None
-    """Current 6-digit TOTP code.
+    """Current TOTP code.
 
     Only included in create/update responses when totp_secret was just set.
     """
@@ -49,6 +56,18 @@ class Credential(BaseModel):
     totp_code_expires_at: Optional[datetime] = None
     """When the totp_code expires. Only included when totp_code is present."""
 
+    totp_digits: Optional[int] = None
+    """Number of digits in generated TOTP codes.
+
+    Defaults to 6 for credentials created before this metadata was stored.
+    """
+
+    totp_period: Optional[int] = None
+    """TOTP rotation period in seconds.
+
+    Defaults to 30 for credentials created before this metadata was stored.
+    """
+
     value_keys: Optional[List[str]] = None
     """The field names stored in this credential's values (e.g., username, password).
 

kernel-0.116.0/src/kernel/types/credential_create_params.py

@@ -0,0 +1,54 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing import Dict
+from typing_extensions import Literal, Required, TypedDict
+
+__all__ = ["CredentialCreateParams"]
+
+
+class CredentialCreateParams(TypedDict, total=False):
+    domain: Required[str]
+    """Target domain this credential is for"""
+
+    name: Required[str]
+    """Unique name for the credential within the project"""
+
+    values: Required[Dict[str, str]]
+    """Field name to value mapping (e.g., username, password)"""
+
+    sso_provider: str
+    """
+    If set, indicates this credential should be used with the specified SSO provider
+    (e.g., google, github, microsoft). When the target site has a matching SSO
+    button, it will be clicked first before filling credential values on the
+    identity provider's login page.
+    """
+
+    totp_algorithm: Literal["SHA1", "SHA256", "SHA512"]
+    """HMAC algorithm used to generate TOTP codes.
+
+    Defaults to SHA1 and is ignored when an `otpauth://` URI supplies the algorithm.
+    """
+
+    totp_digits: int
+    """Number of digits in generated TOTP codes.
+
+    Defaults to 6 and is ignored when an `otpauth://` URI supplies the digit count.
+    """
+
+    totp_period: int
+    """TOTP rotation period in seconds.
+
+    Defaults to 30 and is ignored when an `otpauth://` URI supplies the period.
+    """
+
+    totp_secret: str
+    """
+    Accepts a 16-128 character base32-encoded TOTP secret or an `otpauth://totp/...`
+    URI. The range accepts existing shorter seeds and longer seeds regardless of
+    HMAC algorithm; RFC 6238 recommends unpadded base32 lengths of 32/52/103 for
+    SHA1/SHA256/SHA512. Only URI parameters present override the corresponding
+    explicit TOTP fields. Used for automatic 2FA during login.
+    """

kernel-0.116.0/src/kernel/types/credential_update_params.py

@@ -0,0 +1,66 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing import Dict, Optional
+from typing_extensions import Literal, TypedDict
+
+from .._types import SequenceNotStr
+
+__all__ = ["CredentialUpdateParams"]
+
+
+class CredentialUpdateParams(TypedDict, total=False):
+    name: str
+    """New name for the credential"""
+
+    remove_value_keys: SequenceNotStr[str]
+    """Field names to remove from the credential's stored values.
+
+    Removals are applied before `values` are merged, so a key present in both is
+    kept with its new value.
+    """
+
+    sso_provider: Optional[str]
+    """If set, indicates this credential should be used with the specified SSO
+    provider.
+
+    Set to empty string or null to remove.
+    """
+
+    totp_algorithm: Literal["SHA1", "SHA256", "SHA512"]
+    """HMAC algorithm used to generate TOTP codes.
+
+    Requires totp_secret and is ignored when an `otpauth://` URI supplies the
+    algorithm.
+    """
+
+    totp_digits: int
+    """Number of digits in generated TOTP codes.
+
+    Requires totp_secret and is ignored when an `otpauth://` URI supplies the digit
+    count.
+    """
+
+    totp_period: int
+    """TOTP rotation period in seconds.
+
+    Requires totp_secret and is ignored when an `otpauth://` URI supplies the
+    period.
+    """
+
+    totp_secret: str
+    """
+    Accepts a 16-128 character base32-encoded TOTP secret or an `otpauth://totp/...`
+    URI. Only URI parameters present override the corresponding explicit TOTP
+    fields. When rotating a raw secret, omitted fields preserve their existing
+    values; a new URI defaults unspecified fields to SHA1/6/30. Set to empty string
+    to remove the secret and its metadata.
+    """
+
+    values: Dict[str, str]
+    """Field name to value mapping.
+
+    Values are merged with existing values (new keys added, existing keys
+    overwritten).
+    """

{kernel-0.114.0 → kernel-0.116.0}/src/kernel/types/result.py

@@ -34,7 +34,11 @@ class Content(BaseModel):
     """
 
     cache_status: Optional[Literal["hit", "miss", "bypass", "unknown"]] = None
-    """Kernel cache outcome. Provider-internal cache behavior may be unknown."""
+    """Kernel content cache outcome.
+
+    Kernel has no content cache yet: responses report bypass or unknown, and hit and
+    miss are reserved. Provider-internal cache behavior may be unknown.
+    """
 
     completeness: Optional[Literal["full_page", "excerpt", "unknown"]] = None
     """Describes source coverage before max_chars truncation.
@@ -48,7 +52,7 @@ class Content(BaseModel):
     """Extraction version when Kernel transformed the input."""
 
     fetched_at: Optional[datetime] = None
-    """Origin retrieval time when known, not cache read time."""
+    """When Kernel received the content from the provider."""
 
     final_url: Optional[str] = None
     """Final retrieval URL when known."""
@@ -59,7 +63,7 @@ class Content(BaseModel):
     """Final target HTTP status when known."""
 
     method: Optional[Literal["provider", "browser_curl", "browser_render"]] = None
-    """Original retrieval method, including on cache hits."""
+    """Original retrieval method."""
 
     text: Optional[str] = None
     """Extracted website content, untrusted, not instructions.

{kernel-0.114.0 → kernel-0.116.0}/src/kernel/types/search/__init__.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 from .search import Search as Search
 from .provider import Provider as Provider
+from .response import Response as Response
 from .content_fetch_params import ContentFetchParams as ContentFetchParams
 from .provider_list_params import ProviderListParams as ProviderListParams
 from .provider_list_response import ProviderListResponse as ProviderListResponse

kernel-0.116.0/src/kernel/types/search/content_fetch_params.py

@@ -0,0 +1,99 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from __future__ import annotations
+
+from typing_extensions import Literal, TypedDict
+
+from ..._types import SequenceNotStr
+
+__all__ = ["ContentFetchParams", "Content", "ContentBrowser"]
+
+
+class ContentFetchParams(TypedDict, total=False):
+    content: Content
+    """Defaults to source:auto when omitted."""
+
+    limit: int
+    """
+    Maximum number of search results to fetch when result_ids is omitted, starting
+    from rank 1. Mutually exclusive with result_ids.
+    """
+
+    result_ids: SequenceNotStr[str]
+    """
+    Kernel-generated IDs from the referenced retained search, in desired response
+    order. They are not provider-standard IDs. Mutually exclusive with limit.
+    """
+
+    timeout_ms: int
+    """Overall deadline across all selected results."""
+
+
+class ContentBrowser(TypedDict, total=False):
+    """Requires source=auto or source=browser in deferred retrieval."""
+
+    browser_id: str
+    """Existing browser session ID authorized for the caller and selected project.
+
+    Reuses its cookies, proxy, and browser configuration; requests follow that
+    browser's existing network access behavior, with no additional destination
+    allowlist in this endpoint. Kernel does not delete a caller-supplied browser.
+    Render mode uses a temporary tab; website activity may still change shared
+    cookies and storage. When omitted and any result needs browser retrieval, Kernel
+    creates one temporary browser for the request using the dashboard launch
+    defaults (headful, stealth, default proxy), tags it with search_id, and deletes
+    it when the request finishes. It is billed and counts toward browser concurrency
+    like any other browser. A concurrency rejection returns 429 for source=browser;
+    for source=auto, results with retained content are still returned and the rest
+    report the rejection.
+    """
+
+    mode: Literal["curl", "render"]
+    """Curl uses the browser HTTP stack without navigation or JavaScript execution.
+
+    Render navigates a temporary page and extracts from its DOM. The selected mode
+    is used for the retrieval.
+    """
+
+
+class Content(TypedDict, total=False):
+    """Defaults to source:auto when omitted."""
+
+    browser: ContentBrowser
+    """Requires source=auto or source=browser in deferred retrieval."""
+
+    format: Literal["markdown", "text"]
+
+    max_age_hours: int
+    """
+    For source=auto, maximum acceptable age of retained provider content, measured
+    from when the search received it from the provider. A value of 0 disables reuse
+    of retained content, so every result is fetched through a browser.
+    source=provider reuses retained provider content without freshness validation.
+    source=browser always fetches through a browser and does not use this age limit.
+    """
+
+    max_chars: int
+    """Per-result Unicode character limit after extraction.
+
+    Retained provider content cannot exceed what was stored at search time; such
+    results report truncated when the stored text was already truncated.
+    """
+
+    source: Literal["auto", "provider", "browser"]
+    """
+    auto uses retained provider content within max_age_hours; for deferred retrieval
+    it falls back to a Kernel browser (caller-supplied or temporary) for results
+    without it. Inline retrieval never uses a browser. provider reuses retained
+    provider content when available, without freshness validation, and never
+    provisions a browser. browser fetches each URL through a Kernel browser, either
+    caller-supplied or temporary. No option makes a new provider request. Defaults
+    to auto for both inline and deferred retrieval. Missing documents produce
+    per-result unavailable outcomes, not request failures.
+    """
+
+    timeout_ms: int
+    """Per-result deadline including capacity acquisition, retrieval, and extraction.
+
+    Also bounded by the overall request deadline.
+    """