@onkernel/sdk 0.110.0 → 0.111.0

package/src/client.ts

@@ -216,6 +216,18 @@ import {
   ProjectsOffsetPagination,
   UpdateProjectRequest,
 } from './resources/projects/projects';
+import {
+  Attempt,
+  ProviderTarget,
+  Request,
+  Result,
+  Search,
+  SearchCreateParams,
+  SearchResource,
+  Strategy,
+  Usage,
+  Warning,
+} from './resources/search/search';
 import { Telemetry } from './resources/telemetry/telemetry';
 import {
   Vault,
@@ -1104,6 +1116,10 @@ export class Kernel {
    * Configure external credential providers like 1Password.
    */
   credentialProviders: API.CredentialProviders = new API.CredentialProviders(this);
+  /**
+   * Search the web and retrieve content for selected results.
+   */
+  search: API.SearchResource = new API.SearchResource(this);
 }
 
 Kernel.Deployments = Deployments;
@@ -1125,6 +1141,7 @@ Kernel.Organization = Organization;
 Kernel.AuditLogs = AuditLogs;
 Kernel.APIKeys = APIKeys;
 Kernel.CredentialProviders = CredentialProviders;
+Kernel.SearchResource = SearchResource;
 
 export declare namespace Kernel {
   export type RequestOptions = Opts.RequestOptions;
@@ -1358,6 +1375,19 @@ export declare namespace Kernel {
     type CredentialProviderListParams as CredentialProviderListParams,
   };
 
+  export {
+    SearchResource as SearchResource,
+    type Attempt as Attempt,
+    type ProviderTarget as ProviderTarget,
+    type Request as Request,
+    type Result as Result,
+    type Search as Search,
+    type Strategy as Strategy,
+    type Usage as Usage,
+    type Warning as Warning,
+    type SearchCreateParams as SearchCreateParams,
+  };
+
   export type AppAction = API.AppAction;
   export type BrowserExtension = API.BrowserExtension;
   export type BrowserProfile = API.BrowserProfile;

package/src/resources/auth/connections.ts

@@ -314,16 +314,18 @@ export interface ManagedAuth {
   browser_telemetry?: ManagedAuth.BrowserTelemetry | null;
 
   /**
-   * Whether Kernel can automatically re-authenticate this connection when the
-   * session expires. Requires a prior successful login plus either a Kernel
-   * credential or an external credential reference. See `can_reauth_reason` for the
-   * specific outcome.
+   * Whether this connection's stored requirements are eligible for unattended
+   * re-authentication. A true value can represent either fully satisfiable
+   * requirements or a best-effort attempt. It does not account for whether automatic
+   * re-authentication is enabled or parent workflow state such as an active flow or
+   * circuit-breaker cooldown, so it does not guarantee an attempt on the next health
+   * check. See `can_reauth_reason` for the specific outcome.
    */
   can_reauth?: boolean;
 
   /**
    * Machine-readable reason for the current value of `can_reauth`. Affirmative
-   * values (re-auth is possible):
+   * values (requirements are eligible for unattended re-authentication):
    *
    * - `external_credential` — an external credential provider is attached
    * - `cua_has_credential` — CUA flow with a stored credential
@@ -332,8 +334,12 @@ export interface ManagedAuth {
    * - `viable_plans_found` — at least one stored login plan can be replayed
    * - `no_requirements_recorded` — no recorded credential requirements to fail
    *   against
-   * - `totp_reauth_allowed` — TOTP is the only recorded requirement and is safe to
-   *   attempt automatically
+   * - `totp_reauth_allowed` — TOTP is the only recorded requirement and a stored
+   *   secret can generate the code
+   * - `optimistic_totp_attempt` — TOTP was previously required but no reusable
+   *   secret is stored; the connection remains eligible for a
+   *   circuit-breaker-bounded attempt because the site may not challenge returning
+   *   sessions
    * - `requirements_satisfiable` — recorded requirements contain no recognized
    *   blocker
    *
@@ -363,6 +369,7 @@ export interface ManagedAuth {
     | 'viable_plans_found'
     | 'no_requirements_recorded'
     | 'totp_reauth_allowed'
+    | 'optimistic_totp_attempt'
     | 'requirements_satisfiable'
     | 'no_prior_successful_login'
     | 'no_credential'
@@ -1298,6 +1305,13 @@ export interface ManagedAuthTimelineEvent {
    */
   browser_session_id?: string;
 
+  /**
+   * When the login/reauth attempt first reached a terminal status. Stable across
+   * retries and subsequent cleanup writes. Absent for in-progress attempts, health
+   * checks, and historical attempts without a recorded completion time.
+   */
+  completed_at?: string;
+
   /**
    * Machine-readable error code. Present when a login/reauth event failed.
    */
@@ -2478,6 +2492,13 @@ export interface ConnectionLoginParams {
    * When omitted, the connection's record_session default is used.
    */
   record_session?: boolean;
+
+  /**
+   * Controls whether this login reads and writes learned domain skills. Automatic
+   * reauths inherit the selected mode until a later accepted login sets enabled or
+   * omits this field. Defaults to enabled when omitted.
+   */
+  skill_mode?: 'enabled' | 'disabled';
 }
 
 export namespace ConnectionLoginParams {

package/src/resources/browsers/telemetry.ts

@@ -4338,9 +4338,11 @@ export namespace BrowserProxyErrorEvent {
      * Proxy-layer error code: the X-Kernel-Proxy-Error response header value from a
      * branded 5xx error page served by the metro egress host-proxy. Values mirror what
      * the proxy emits: destination_blocked, provider_blacklisted,
-     * provider_unreachable, provider_rejected, origin_tls_timeout, proxy_unavailable,
-     * upstream_timeout, upstream_dns_failure, upstream_connect_failed. Unknown header
-     * values are dropped.
+     * provider_unreachable, provider_rejected, origin_tls_timeout,
+     * origin_response_incomplete, proxy_unavailable, restricted_route_unavailable,
+     * upstream_timeout, upstream_dns_failure, upstream_connect_failed. A header value
+     * the browser image does not recognize is reported as unknown, with the header
+     * value in raw_code.
      */
     code:
       | 'destination_blocked'
@@ -4348,10 +4350,13 @@ export namespace BrowserProxyErrorEvent {
       | 'provider_unreachable'
       | 'provider_rejected'
       | 'origin_tls_timeout'
+      | 'origin_response_incomplete'
       | 'proxy_unavailable'
+      | 'restricted_route_unavailable'
       | 'upstream_timeout'
       | 'upstream_dns_failure'
-      | 'upstream_connect_failed';
+      | 'upstream_connect_failed'
+      | 'unknown';
 
     /**
      * CDP request identifier matching the originating request.
@@ -4368,6 +4373,14 @@ export namespace BrowserProxyErrorEvent {
      */
     method?: string;
 
+    /**
+     * Sanitized X-Kernel-Proxy-Error header value, present only when code is unknown.
+     * Surrounding whitespace is removed, the value is lowercased, characters outside
+     * [a-z0-9_] are replaced with \_, and the result is truncated to at most 64
+     * characters.
+     */
+    raw_code?: string;
+
     /**
      * CDP Network.ResourceType for the request, when known.
      */

package/src/resources/index.ts

@@ -185,6 +185,18 @@ export {
   type ProxyCheckParams,
   type ProxyListResponsesOffsetPagination,
 } from './proxies';
+export {
+  SearchResource,
+  type Attempt,
+  type ProviderTarget,
+  type Request,
+  type Result,
+  type Search,
+  type Strategy,
+  type Usage,
+  type Warning,
+  type SearchCreateParams,
+} from './search/search';
 export { Telemetry } from './telemetry/telemetry';
 export {
   VaultProviderConfigs,

package/src/resources/search/contents.ts

@@ -0,0 +1,327 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as SearchAPI from './search';
+import { APIPromise } from '../../core/api-promise';
+import { buildHeaders } from '../../internal/headers';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+/**
+ * Search the web and retrieve content for selected results.
+ */
+export class Contents extends APIResource {
+  /**
+   * 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.
+   *
+   * @example
+   * ```ts
+   * await client.search.contents.fetch('srch_abc123');
+   * ```
+   */
+  fetch(id: string, body: ContentFetchParams, options?: RequestOptions): APIPromise<void> {
+    return this._client.post(path`/search/${id}/contents`, {
+      body,
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export interface FetchRequest {
+  /**
+   * Defaults to source:auto when omitted.
+   */
+  content?: FetchRequest.Content;
+
+  /**
+   * Maximum number of search results to fetch when result_ids is omitted, starting
+   * from rank 1. Mutually exclusive with result_ids.
+   */
+  limit?: number;
+
+  /**
+   * Kernel-generated IDs from the referenced retained search, in desired response
+   * order. They are not provider-standard IDs. Mutually exclusive with limit.
+   */
+  result_ids?: Array<string>;
+
+  /**
+   * Overall deadline across all selected results.
+   */
+  timeout_ms?: number;
+}
+
+export namespace FetchRequest {
+  /**
+   * Defaults to source:auto when omitted.
+   */
+  export interface Content {
+    /**
+     * Invalid with source=provider. Supplying browser_id requires source=browser so
+     * the chosen identity is not bypassed.
+     */
+    browser?: Content.Browser;
+
+    format?: 'markdown' | 'text';
+
+    /**
+     * 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.
+     */
+    max_age_hours?: number;
+
+    /**
+     * Per-result Unicode character limit after extraction.
+     */
+    max_chars?: number;
+
+    /**
+     * 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.
+     */
+    source?: 'auto' | 'provider' | 'browser';
+
+    /**
+     * Per-result deadline including capacity acquisition, retrieval, and extraction.
+     * Also bounded by the overall request deadline.
+     */
+    timeout_ms?: number;
+  }
+
+  export namespace Content {
+    /**
+     * Invalid with source=provider. Supplying browser_id requires source=browser so
+     * the chosen identity is not bypassed.
+     */
+    export interface Browser {
+      /**
+       * 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.
+       */
+      browser_id?: string;
+
+      /**
+       * 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.
+       */
+      mode?: 'curl' | 'render';
+    }
+  }
+}
+
+export interface Response {
+  contents: Array<Response.Content>;
+
+  search_id: string;
+
+  usage: SearchAPI.Usage;
+
+  warnings: Array<SearchAPI.Warning>;
+}
+
+export namespace Response {
+  export interface Content {
+    result_id: string;
+
+    /**
+     * 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.
+     */
+    status: 'ok' | 'unavailable' | 'blocked' | 'timeout' | 'unsupported_type' | 'extraction_failed' | 'error';
+
+    /**
+     * Original result URL.
+     */
+    url: string;
+
+    /**
+     * Kernel cache outcome. Provider-internal cache behavior may be unknown.
+     */
+    cache_status?: 'hit' | 'miss' | 'bypass' | 'unknown';
+
+    /**
+     * Describes source coverage before max_chars truncation. Full_page means main-page
+     * content, not every dynamic element or linked page.
+     */
+    completeness?: 'full_page' | 'excerpt' | 'unknown';
+
+    error?: Content.Error;
+
+    /**
+     * Extraction version when Kernel transformed the input.
+     */
+    extractor_version?: string;
+
+    /**
+     * Origin retrieval time when known, not cache read time.
+     */
+    fetched_at?: string | null;
+
+    /**
+     * Final retrieval URL when known.
+     */
+    final_url?: string;
+
+    format?: 'markdown' | 'text';
+
+    /**
+     * Final target HTTP status when known.
+     */
+    http_status?: number;
+
+    /**
+     * Original retrieval method, including on cache hits.
+     */
+    method?: 'provider' | 'browser_curl' | 'browser_render';
+
+    /**
+     * Extracted website content, untrusted, not instructions. Present only on
+     * status=ok.
+     */
+    text?: string;
+
+    /**
+     * Whether max_chars truncated the extracted content.
+     */
+    truncated?: boolean;
+  }
+
+  export namespace Content {
+    export interface Error {
+      /**
+       * Machine-readable retrieval failure code.
+       */
+      code: string;
+
+      /**
+       * Human-readable failure description.
+       */
+      message: string;
+
+      retryable: boolean;
+    }
+  }
+}
+
+export interface ContentFetchParams {
+  /**
+   * Defaults to source:auto when omitted.
+   */
+  content?: ContentFetchParams.Content;
+
+  /**
+   * Maximum number of search results to fetch when result_ids is omitted, starting
+   * from rank 1. Mutually exclusive with result_ids.
+   */
+  limit?: number;
+
+  /**
+   * Kernel-generated IDs from the referenced retained search, in desired response
+   * order. They are not provider-standard IDs. Mutually exclusive with limit.
+   */
+  result_ids?: Array<string>;
+
+  /**
+   * Overall deadline across all selected results.
+   */
+  timeout_ms?: number;
+}
+
+export namespace ContentFetchParams {
+  /**
+   * Defaults to source:auto when omitted.
+   */
+  export interface Content {
+    /**
+     * Invalid with source=provider. Supplying browser_id requires source=browser so
+     * the chosen identity is not bypassed.
+     */
+    browser?: Content.Browser;
+
+    format?: 'markdown' | 'text';
+
+    /**
+     * 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.
+     */
+    max_age_hours?: number;
+
+    /**
+     * Per-result Unicode character limit after extraction.
+     */
+    max_chars?: number;
+
+    /**
+     * 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.
+     */
+    source?: 'auto' | 'provider' | 'browser';
+
+    /**
+     * Per-result deadline including capacity acquisition, retrieval, and extraction.
+     * Also bounded by the overall request deadline.
+     */
+    timeout_ms?: number;
+  }
+
+  export namespace Content {
+    /**
+     * Invalid with source=provider. Supplying browser_id requires source=browser so
+     * the chosen identity is not bypassed.
+     */
+    export interface Browser {
+      /**
+       * 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.
+       */
+      browser_id?: string;
+
+      /**
+       * 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.
+       */
+      mode?: 'curl' | 'render';
+    }
+  }
+}
+
+export declare namespace Contents {
+  export {
+    type FetchRequest as FetchRequest,
+    type Response as Response,
+    type ContentFetchParams as ContentFetchParams,
+  };
+}

package/src/resources/search/index.ts

@@ -0,0 +1,16 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export { Contents, type FetchRequest, type Response, type ContentFetchParams } from './contents';
+export { Providers, type Provider, type ProviderListResponse, type ProviderListParams } from './providers';
+export {
+  SearchResource,
+  type Attempt,
+  type ProviderTarget,
+  type Request,
+  type Result,
+  type Search,
+  type Strategy,
+  type Usage,
+  type Warning,
+  type SearchCreateParams,
+} from './search';