@onkernel/sdk 0.110.0 → 0.112.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/browser-pools.ts

@@ -1066,6 +1066,13 @@ export interface BrowserPoolAcquireParams {
    */
   name?: string;
 
+  /**
+   * Profile selection for the browser session. Provide either id or name. If
+   * specified, the matching profile will be loaded into the browser session.
+   * Profiles must be created beforehand.
+   */
+  profile?: Shared.BrowserProfile;
+
   /**
    * Optional URL to navigate the acquired browser to. Overrides the pool's start_url
    * for this acquire only. Best-effort: failures to navigate do not fail the
@@ -1200,7 +1207,8 @@ export interface BrowserPoolReleaseParams {
    * Defaults to true. A reused browser keeps the configuration it was created with,
    * so it does not pick up pool configuration changes made while it was in use.
    * Release with `reuse: false`, or flush the pool afterward, to rebuild it with the
-   * current configuration.
+   * current configuration. Browsers loaded with an acquire-time profile are always
+   * destroyed and replaced, even when reuse is true.
    */
   reuse?: boolean;
 }

package/src/resources/browsers/browsers.ts

@@ -109,19 +109,6 @@ import {
   TelemetryStreamParams,
   TelemetryStreamResponse,
 } from './telemetry';
-import * as WebmcpAPI from './webmcp';
-import {
-  InvocationFailure,
-  InvocationResult,
-  InvokeRequest,
-  Tool,
-  ToolAnnotations,
-  ToolFrame,
-  ToolSource,
-  ToolsResponse,
-  Webmcp,
-  WebmcpInvokeToolParams,
-} from './webmcp';
 import * as FsAPI from './fs/fs';
 import {
   FCreateDirectoryParams,
@@ -140,6 +127,22 @@ import {
   FWriteFileParams,
   Fs,
 } from './fs/fs';
+import * as WebmcpAPI from './webmcp/webmcp';
+import {
+  CustomToolSource,
+  InvocationFailure,
+  InvocationResult,
+  InvokeRequest,
+  Tool,
+  ToolAnnotations,
+  ToolFrame,
+  ToolMetadata,
+  ToolSource,
+  ToolsResponse,
+  Webmcp,
+  WebmcpInvokeToolParams,
+  WebmcpListToolsParams,
+} from './webmcp/webmcp';
 import { APIPromise } from '../../core/api-promise';
 import { OffsetPagination, type OffsetPaginationParams, PagePromise } from '../../core/pagination';
 import { type Uploadable } from '../../core/uploads';
@@ -375,6 +378,52 @@ export interface BrowserNetworkConfig {
    * upstream-proxy and Kernel-managed direct egress and cannot reach into a VPN.
    */
   private_hosts?: Array<string>;
+
+  /**
+   * Per-destination proxy routes for a browser session. After setup, a destination
+   * hostname is matched against every route's hosts, regardless of port; route order
+   * does not matter. An exact hostname beats a wildcard, and a longer wildcard
+   * suffix beats a shorter one (for a.b.example.com: "a.b.example.com" >
+   * "_.b.example.com" > "_.example.com"). A host pattern may appear in only one
+   * route. "\*.example.com" matches subdomains only, not example.com. A matched
+   * request selects the route's proxy instead of the session's top-level proxy
+   * (including mode: direct); the route proxy's own bypass_hosts still apply. If the
+   * route proxy becomes unavailable, matched requests fail closed without falling
+   * back. Requests that match no route use the session's default egress from the
+   * top-level proxy field (or the browser default when proxy is omitted: stealth
+   * proxy or direct egress). Routes take effect once the session is created;
+   * start_url and other traffic during browser setup use the top-level proxy.
+   * Setting routes requires proxy v3. Not supported on browser pools.
+   */
+  proxy_routes?: Array<BrowserNetworkConfig.ProxyRoute>;
+}
+
+export namespace BrowserNetworkConfig {
+  export interface ProxyRoute {
+    /**
+     * Exact hostnames or leading \*. wildcard patterns (subdomains only); patterns
+     * cannot include ports, and matching ignores the destination port. Hosts not
+     * matched by any route use the session's top-level proxy (or the browser default
+     * when proxy is omitted).
+     */
+    hosts: Array<string>;
+
+    /**
+     * Select an active non-direct proxy by ID or name. Responses always use ID.
+     */
+    proxy: ProxyRoute.Proxy;
+  }
+
+  export namespace ProxyRoute {
+    /**
+     * Select an active non-direct proxy by ID or name. Responses always use ID.
+     */
+    export interface Proxy {
+      id?: string;
+
+      name?: string;
+    }
+  }
 }
 
 /**
@@ -2019,14 +2068,17 @@ export declare namespace Browsers {
 
   export {
     Webmcp as Webmcp,
+    type CustomToolSource as CustomToolSource,
     type InvocationFailure as InvocationFailure,
     type InvocationResult as InvocationResult,
     type InvokeRequest as InvokeRequest,
     type Tool as Tool,
     type ToolAnnotations as ToolAnnotations,
     type ToolFrame as ToolFrame,
+    type ToolMetadata as ToolMetadata,
     type ToolSource as ToolSource,
     type ToolsResponse as ToolsResponse,
     type WebmcpInvokeToolParams as WebmcpInvokeToolParams,
+    type WebmcpListToolsParams as WebmcpListToolsParams,
   };
 }

package/src/resources/browsers/index.ts

@@ -152,13 +152,16 @@ export {
 } from './telemetry';
 export {
   Webmcp,
+  type CustomToolSource,
   type InvocationFailure,
   type InvocationResult,
   type InvokeRequest,
   type Tool,
   type ToolAnnotations,
   type ToolFrame,
+  type ToolMetadata,
   type ToolSource,
   type ToolsResponse,
   type WebmcpInvokeToolParams,
-} from './webmcp';
+  type WebmcpListToolsParams,
+} from './webmcp/index';

package/src/resources/browsers/telemetry.ts

@@ -16,8 +16,9 @@ export class Telemetry extends APIResource {
   /**
    * Reads a page of telemetry events for the browser session. To page through
    * results, pass the X-Next-Offset value from the previous response as offset and
-   * repeat while X-Has-More is true. Returns an empty list when telemetry data is
-   * unavailable.
+   * repeat while X-Has-More is true. The category and type filters apply within each
+   * page, so a filtered page may be empty while X-Has-More is true. Returns an empty
+   * list when telemetry data is unavailable.
    *
    * @example
    * ```ts
@@ -2979,7 +2980,14 @@ export interface BrowserEventContext {
   /**
    * CDP target type of the page that produced the event.
    */
-  target_type?: 'page' | 'background_page' | 'service_worker' | 'shared_worker' | 'other';
+  target_type?:
+    | 'page'
+    | 'iframe'
+    | 'worker'
+    | 'background_page'
+    | 'service_worker'
+    | 'shared_worker'
+    | 'other';
 
   /**
    * URL relevant to this event — page URL for navigation and page events, request
@@ -3283,8 +3291,12 @@ export namespace BrowserLiveViewDisconnectEvent {
 
 /**
  * The CDP connection to Chrome was lost. Telemetry events may be dropped until
- * monitor_reconnected arrives. Treat any in-progress computed state (network_idle,
- * page_layout_settled) as unreliable until then.
+ * monitor_reconnected arrives. In-progress computed state is discarded rather than
+ * paused, so computed events still pending for the current navigation
+ * (network_idle, page_layout_settled, page_navigation_settled) never fire.
+ * monitor_reconnected does not restore them. After reattachment a fresh state
+ * machine starts, so computed events can resume before the next navigation and
+ * carry empty navigation context until one occurs.
  */
 export interface BrowserMonitorDisconnectedEvent {
   category: 'monitor';
@@ -3769,7 +3781,14 @@ export namespace BrowserPageCrashedEvent {
     /**
      * CDP target type of the page that produced the event.
      */
-    target_type: 'page' | 'background_page' | 'service_worker' | 'shared_worker' | 'other';
+    target_type:
+      | 'page'
+      | 'iframe'
+      | 'worker'
+      | 'background_page'
+      | 'service_worker'
+      | 'shared_worker'
+      | 'other';
 
     /**
      * URL the page was on when its renderer process crashed.
@@ -4135,7 +4154,14 @@ export namespace BrowserPageNavigationEvent {
     /**
      * CDP target type of the page that produced the event.
      */
-    target_type?: 'page' | 'background_page' | 'service_worker' | 'shared_worker' | 'other';
+    target_type?:
+      | 'page'
+      | 'iframe'
+      | 'worker'
+      | 'background_page'
+      | 'service_worker'
+      | 'shared_worker'
+      | 'other';
 
     /**
      * URL navigated to.
@@ -4222,7 +4248,14 @@ export namespace BrowserPageTabOpenedEvent {
     /**
      * CDP target type of the page that produced the event.
      */
-    target_type?: 'page' | 'background_page' | 'service_worker' | 'shared_worker' | 'other';
+    target_type?:
+      | 'page'
+      | 'iframe'
+      | 'worker'
+      | 'background_page'
+      | 'service_worker'
+      | 'shared_worker'
+      | 'other';
 
     /**
      * Initial page title of the new tab.
@@ -4337,21 +4370,27 @@ 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.
+     * the proxy emits: destination_blocked, destination_route_unavailable,
+     * provider_blacklisted, 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'
+      | 'destination_route_unavailable'
       | 'provider_blacklisted'
       | '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 +4407,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.
      */
@@ -4817,9 +4864,7 @@ export interface TelemetryEventsParams extends OffsetPaginationParams {
    * Read direction. asc (default) reads oldest first, starting from since or the
    * offset cursor. desc reads newest first: each request returns one page of up to
    * limit records ending at the offset cursor (or until, or the newest archived
-   * event); combining desc with since is rejected with a 400. In either direction
-   * the category filter applies within the page, so a filtered page may be empty
-   * while X-Has-More is true.
+   * event); combining desc with since is rejected with a 400.
    */
   order?: string;
 
@@ -4829,6 +4874,13 @@ export interface TelemetryEventsParams extends OffsetPaginationParams {
    */
   since?: string;
 
+  /**
+   * Restrict results to these event types, such as page_crashed or
+   * captcha_challenge_result. Repeat the parameter for multiple values. Combines
+   * with category: when both are set an event must match both.
+   */
+  type?: Array<string>;
+
   /**
    * End of the window (exclusive): an RFC-3339 timestamp, or a duration like 5m
    * meaning that long ago.

package/src/resources/browsers/webmcp/custom-tools.ts

@@ -0,0 +1,160 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as WebmcpAPI from './webmcp';
+import { APIPromise } from '../../../core/api-promise';
+import { buildHeaders } from '../../../internal/headers';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+/**
+ * Discover and invoke native page tools across the browser instance.
+ */
+export class CustomTools extends APIResource {
+  /**
+   * Returns every registered custom tool with its generated ID, namespace, matcher,
+   * and MCP tool metadata.
+   *
+   * @example
+   * ```ts
+   * const customToolsResponse =
+   *   await client.browsers.webmcp.customTools.list(
+   *     'id_or_name',
+   *   );
+   * ```
+   */
+  list(idOrName: string, options?: RequestOptions): APIPromise<CustomToolsResponse> {
+    return this._client.get(path`/browsers/${idOrName}/webmcp/custom-tools`, options);
+  }
+
+  /**
+   * Add a namespaced batch of custom tools. A custom tool can be page-backed or
+   * CDP-backed. Page-backed tools execute in the page via JavaScript. CDP-backed
+   * tools execute via CDP and can use all browser REPL tools (see `/repl`). The
+   * source must evaluate to a non-empty array of definitions with URL matchers, tool
+   * metadata (including an optional output schema), and execute functions. The batch
+   * is added atomically. Matchers apply to top-level documents and nested frames,
+   * including out-of-process iframes; each matching tool is exposed once on the
+   * tab's top-level document and appears in the WebMCP tool snapshot.
+   *
+   * To update one tool, list the tools, delete its ID, and add its replacement. Set
+   * force_overwrite_namespace to replace every existing tool in the namespace
+   * atomically; omitted or false adds tools without replacing existing ones.
+   * Existing invocations continue.
+   *
+   * @example
+   * ```ts
+   * const customToolsResponse =
+   *   await client.browsers.webmcp.customTools.add(
+   *     'id_or_name',
+   *     { namespace: 'namespace', source: 'source' },
+   *   );
+   * ```
+   */
+  add(
+    idOrName: string,
+    body: CustomToolAddParams,
+    options?: RequestOptions,
+  ): APIPromise<CustomToolsResponse> {
+    return this._client.post(path`/browsers/${idOrName}/webmcp/custom-tools`, { body, ...options });
+  }
+
+  /**
+   * Removes one custom tool by generated ID. An invocation already in progress is
+   * not canceled.
+   *
+   * @example
+   * ```ts
+   * await client.browsers.webmcp.customTools.remove(
+   *   'ct_n10b9798ad53ecc4y69z31e1',
+   *   { id_or_name: 'id_or_name' },
+   * );
+   * ```
+   */
+  remove(id: string, params: CustomToolRemoveParams, options?: RequestOptions): APIPromise<void> {
+    const { id_or_name } = params;
+    return this._client.delete(path`/browsers/${id_or_name}/webmcp/custom-tools/${id}`, {
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+export interface AddRequest {
+  namespace: string;
+
+  /**
+   * JavaScript expression that evaluates to a non-empty array of custom tool
+   * definitions. Limited to 8,000,000 bytes when UTF-8 encoded, so multi-byte
+   * characters reduce the allowed character count.
+   */
+  source: string;
+
+  /**
+   * Atomically replace all existing tools in this namespace with this batch when
+   * true.
+   */
+  force_overwrite_namespace?: boolean;
+}
+
+export interface CustomToolsResponse {
+  tools: Array<Definition>;
+}
+
+export interface Definition {
+  id: string;
+
+  kind: string;
+
+  match: Match;
+
+  namespace: string;
+
+  /**
+   * Tool metadata follows the
+   * [MCP Tool definition](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool)
+   * and the
+   * [WebMCP RegisteredTool definition](https://webmachinelearning.github.io/webmcp/#dictdef-registeredtool).
+   * outputSchema is optional for page and custom tools.
+   */
+  tool: WebmcpAPI.ToolMetadata;
+}
+
+export interface Match {
+  url_patterns: Array<string>;
+}
+
+export interface CustomToolAddParams {
+  namespace: string;
+
+  /**
+   * JavaScript expression that evaluates to a non-empty array of custom tool
+   * definitions. Limited to 8,000,000 bytes when UTF-8 encoded, so multi-byte
+   * characters reduce the allowed character count.
+   */
+  source: string;
+
+  /**
+   * Atomically replace all existing tools in this namespace with this batch when
+   * true.
+   */
+  force_overwrite_namespace?: boolean;
+}
+
+export interface CustomToolRemoveParams {
+  /**
+   * Browser session ID or name
+   */
+  id_or_name: string;
+}
+
+export declare namespace CustomTools {
+  export {
+    type AddRequest as AddRequest,
+    type CustomToolsResponse as CustomToolsResponse,
+    type Definition as Definition,
+    type Match as Match,
+    type CustomToolAddParams as CustomToolAddParams,
+    type CustomToolRemoveParams as CustomToolRemoveParams,
+  };
+}

package/src/resources/browsers/webmcp/index.ts

@@ -0,0 +1,26 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export {
+  CustomTools,
+  type AddRequest,
+  type CustomToolsResponse,
+  type Definition,
+  type Match,
+  type CustomToolAddParams,
+  type CustomToolRemoveParams,
+} from './custom-tools';
+export {
+  Webmcp,
+  type CustomToolSource,
+  type InvocationFailure,
+  type InvocationResult,
+  type InvokeRequest,
+  type Tool,
+  type ToolAnnotations,
+  type ToolFrame,
+  type ToolMetadata,
+  type ToolSource,
+  type ToolsResponse,
+  type WebmcpInvokeToolParams,
+  type WebmcpListToolsParams,
+} from './webmcp';