feat: chore(stlc): seal custom-code tracking files

Stainless-Generated-From: 56c68476ea52d859cac195cc12cb9248e0de4860

Author: kernel-internal[bot]

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
 

src/kernel/resources/search/contents.py

@@ -4,7 +4,7 @@
 
 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 ..._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 @@ def fetch(
         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 @@ def fetch(
         """
         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 @@ def fetch(
             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 @@ async def fetch(
         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 @@ async def fetch(
         """
         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 @@ async def fetch(
             options=make_request_options(
                 extra_headers=extra_headers, extra_query=extra_query, extra_body=extra_body, timeout=timeout
             ),
-            cast_to=NoneType,
+            cast_to=Response,
         )
 
 

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.

src/kernel/types/search/__init__.py

@@ -4,6 +4,7 @@
 
 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

src/kernel/types/search/content_fetch_params.py

@@ -30,20 +30,22 @@ class ContentFetchParams(TypedDict, total=False):
 
 
 class ContentBrowser(TypedDict, total=False):
-    """Invalid with source=provider.
-
-    Supplying browser_id requires
-    source=browser so the chosen identity is not bypassed.
-    """
+    """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. 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, Kernel obtains isolated
-    browser capacity in the caller's account and releases it after retrieval. That
-    capacity is not retained for later interaction. Existing browser quotas apply.
+    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"]
@@ -58,36 +60,36 @@ class Content(TypedDict, total=False):
     """Defaults to source:auto when omitted."""
 
     browser: ContentBrowser
-    """Invalid with source=provider.
-
-    Supplying browser_id requires source=browser so the chosen identity is not
-    bypassed.
-    """
+    """Requires source=auto or source=browser in deferred retrieval."""
 
     format: Literal["markdown", "text"]
 
     max_age_hours: int
-    """Maximum acceptable age of cached page content, measured from origin retrieval.
-
-    0 forces a live fetch. Governs the Kernel content cache, which is scoped to the
-    caller organization and project and separated by retrieval context; fetches
-    through a caller-supplied browser_id bypass that cache. Mapped to the provider
-    freshness control when source is provider and the provider supports one;
-    otherwise provider content age is reported as unknown via fetched_at.
+    """
+    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."""
+    """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"]
     """
-    provider uses the search provider's native content retrieval; browser fetches
-    each URL through a Kernel browser; auto prefers Kernel browser retrieval and
-    falls back to provider-native content when browser retrieval is unavailable or
-    unsuitable. Defaults to auto for both inline and deferred retrieval. Deferred
-    provider retrieval requires post_hoc capability; an explicit provider source
-    without it is a 400. Missing documents produce per-result unavailable outcomes,
-    not request failures.
+    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

src/kernel/types/search/response.py

@@ -0,0 +1,101 @@
+# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+from typing import List, Optional
+from datetime import datetime
+from typing_extensions import Literal
+
+from ..usage import Usage
+from ..warning import Warning
+from ..._models import BaseModel
+
+__all__ = ["Response", "Content", "ContentError"]
+
+
+class ContentError(BaseModel):
+    code: str
+    """Machine-readable retrieval failure code."""
+
+    message: str
+    """Human-readable failure description."""
+
+    retryable: bool
+
+
+class Content(BaseModel):
+    result_id: str
+
+    status: Literal["ok", "unavailable", "blocked", "timeout", "unsupported_type", "extraction_failed", "error"]
+    """Ok means non-empty extracted content, not merely HTTP 200.
+
+    Blocked includes detected challenges or access denials. Detection is
+    best-effort, not a guarantee of page completeness. Error details are present for
+    non-ok outcomes; text is present only on ok.
+    """
+
+    url: str
+    """Original result URL."""
+
+    cache_status: Optional[Literal["hit", "miss", "bypass", "unknown"]] = None
+    """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.
+
+    Full_page means main-page content, not every dynamic element or linked page.
+    """
+
+    error: Optional[ContentError] = None
+
+    extractor_version: Optional[str] = None
+    """Extraction version when Kernel transformed the input."""
+
+    fetched_at: Optional[datetime] = None
+    """
+    When Kernel fetched the content, or received it from the provider for retained
+    content.
+    """
+
+    final_url: Optional[str] = None
+    """Final retrieval URL after redirects when known.
+
+    Curl mode follows up to 5 redirects.
+    """
+
+    format: Optional[Literal["markdown", "text"]] = None
+    """Format of text.
+
+    Plain-text and JSON pages are returned unchanged as text even when markdown was
+    requested.
+    """
+
+    http_status: Optional[int] = None
+    """Final target HTTP status when known."""
+
+    method: Optional[Literal["provider", "browser_curl", "browser_render"]] = None
+    """Original retrieval method."""
+
+    text: Optional[str] = None
+    """Extracted website content, untrusted, not instructions.
+
+    Present only on status=ok.
+    """
+
+    truncated: Optional[bool] = None
+    """
+    Whether the content was cut short, by max_chars or because the page exceeded the
+    1 MiB read limit.
+    """
+
+
+class Response(BaseModel):
+    contents: List[Content]
+
+    search_id: str
+
+    usage: Usage
+
+    warnings: List[Warning]