@onkernel/sdk 0.119.0 → 0.121.0

package/src/resources/browsers/browsers.ts

@@ -22,8 +22,6 @@ import {
 } from './computer';
 import * as LogsAPI from './logs';
 import { LogStreamParams, Logs } from './logs';
-import * as PlaywrightAPI from './playwright';
-import { Playwright, PlaywrightExecuteParams, PlaywrightExecuteResponse } from './playwright';
 import * as ProcessAPI from './process';
 import {
   Process,
@@ -128,6 +126,14 @@ import {
   FWriteFileParams,
   Fs,
 } from './fs/fs';
+import * as PlaywrightAPI from './playwright/playwright';
+import {
+  ExecutorLimitError,
+  Playwright,
+  PlaywrightExecuteParams,
+  PlaywrightExecuteResponse,
+  Tab,
+} from './playwright/playwright';
 import * as WebmcpAPI from './webmcp/webmcp';
 import {
   CustomToolSource,
@@ -354,6 +360,30 @@ export type BrowserMemoryRequest = '8GiB' | '16GiB';
  * Network configuration for a browser session or browser pool.
  */
 export interface BrowserNetworkConfig {
+  /**
+   * Egress allowlist for a browser session: the only destinations the browser may
+   * reach through Kernel-managed egress. Any other destination is refused with a 403
+   * whose X-Kernel-Proxy-Error header is network_policy_denied, so pages cannot load
+   * or send data to unlisted hosts, including with fetch() and WebSockets. Omit the
+   * field for unfiltered egress; an empty list is invalid. The allowlist applies
+   * from the browser's first request, and start_url must be allowed by it. Entries
+   * are exact hostnames ("example.com"), one leading "_." wildcard that matches
+   * subdomains at any depth but not the domain itself ("_.example.com" matches
+   * api.example.com, not example.com), public IPv4 addresses ("8.8.8.8"), bracketed
+   * public IPv6 addresses ("[2001:4860:4860::8888]"), or public CIDR ranges in
+   * canonical form ("8.8.4.0/24", "2001:4860::/32"). IP and CIDR entries only match
+   * destinations written as an IP address, never hostnames that resolve into the
+   * range. Entries cannot include ports, paths, or schemes, and match every port on
+   * their host. Wildcards over a public suffix ("_.com", "_.github.io") and private
+   * or reserved IP ranges are rejected, as are entries that overlap private_hosts.
+   * Enforced at Kernel's egress proxy only: destinations in private_hosts, and
+   * processes in the browser VM that do not use the browser's proxy, are not
+   * filtered, and Kernel's own control traffic is always allowed. Can be replaced or
+   * removed while the session runs with PATCH /browsers/{id_or_name}. Requires proxy
+   * v3. Not supported on browser pools.
+   */
+  allowed_hosts?: Array<string>;
+
   /**
    * Destinations the browser reaches directly through the session's own network
    * instead of through Kernel-managed egress — for private hosts reachable over a
@@ -427,6 +457,27 @@ export namespace BrowserNetworkConfig {
   }
 }
 
+/**
+ * Network configuration changes for a running browser session. Other network
+ * settings can only be set at creation.
+ */
+export interface BrowserNetworkUpdate {
+  /**
+   * Replaces the session's egress allowlist, using the same entry rules as
+   * network.allowed_hosts on create. Omit to leave the allowlist unchanged, or set
+   * to null to remove it and return to unfiltered egress; an empty list is invalid.
+   * The new list applies without restarting the browser: new requests to
+   * destinations it no longer allows are refused within a few seconds, and open
+   * connections to them are closed within about 30 seconds, or up to 10 minutes
+   * during a Kernel deploy. Connections to destinations it still allows, such as
+   * WebSockets, stay open. A start_url in the same request must be allowed by the
+   * updated list, and is loaded only after the list takes effect. Requires a browser
+   * created with proxy v3, and not supported on pooled browsers. If the request
+   * fails, retry it: the new list may already apply to some requests.
+   */
+  allowed_hosts?: Array<string> | null;
+}
+
 /**
  * Browser pool this session was acquired from, if any.
  */
@@ -684,7 +735,7 @@ export interface BrowserCreateResponse {
   /**
    * Geographic region of the browser session. Fixed once the session is created.
    */
-  region: 'us-east' | 'eu-west' | 'ap-southeast';
+  region: 'us-east' | 'us-west' | 'eu-west' | 'ap-southeast';
 
   /**
    * Unique identifier for the browser session
@@ -855,7 +906,7 @@ export interface BrowserRetrieveResponse {
   /**
    * Geographic region of the browser session. Fixed once the session is created.
    */
-  region: 'us-east' | 'eu-west' | 'ap-southeast';
+  region: 'us-east' | 'us-west' | 'eu-west' | 'ap-southeast';
 
   /**
    * Unique identifier for the browser session
@@ -1026,7 +1077,7 @@ export interface BrowserUpdateResponse {
   /**
    * Geographic region of the browser session. Fixed once the session is created.
    */
-  region: 'us-east' | 'eu-west' | 'ap-southeast';
+  region: 'us-east' | 'us-west' | 'eu-west' | 'ap-southeast';
 
   /**
    * Unique identifier for the browser session
@@ -1197,7 +1248,7 @@ export interface BrowserListResponse {
   /**
    * Geographic region of the browser session. Fixed once the session is created.
    */
-  region: 'us-east' | 'eu-west' | 'ap-southeast';
+  region: 'us-east' | 'us-west' | 'eu-west' | 'ap-southeast';
 
   /**
    * Unique identifier for the browser session
@@ -1419,7 +1470,8 @@ export interface BrowserCreateParams {
   name?: string;
 
   /**
-   * Network configuration for the browser session. Cannot be changed after creation.
+   * Network configuration for the browser session. Only allowed_hosts can be changed
+   * after creation, with PATCH /browsers/{id_or_name}.
    */
   network?: BrowserNetworkConfig;
 
@@ -1452,7 +1504,7 @@ export interface BrowserCreateParams {
    * created. Region selection requires a Start-Up or Enterprise plan, defaults to
    * us-east when omitted on create.
    */
-  region?: 'us-east' | 'eu-west' | 'ap-southeast';
+  region?: 'us-east' | 'us-west' | 'eu-west' | 'ap-southeast';
 
   /**
    * Optional URL to open when the browser session is created. Navigation is
@@ -1649,6 +1701,11 @@ export interface BrowserUpdateParams {
    */
   name?: string | null;
 
+  /**
+   * Network configuration changes to apply to the running browser session.
+   */
+  network?: BrowserNetworkUpdate;
+
   /**
    * Profile to load into the browser session. Only allowed if the session does not
    * already have a profile loaded.
@@ -1839,7 +1896,7 @@ export interface BrowserListParams extends OffsetPaginationParams {
   /**
    * Filter sessions by geographic region. Omit to list sessions in all regions.
    */
-  region?: 'us-east' | 'eu-west' | 'ap-southeast';
+  region?: 'us-east' | 'us-west' | 'eu-west' | 'ap-southeast';
 
   /**
    * Filter sessions by status. "active" returns only active sessions (default),
@@ -1945,6 +2002,7 @@ export declare namespace Browsers {
     type BrowserMemory as BrowserMemory,
     type BrowserMemoryRequest as BrowserMemoryRequest,
     type BrowserNetworkConfig as BrowserNetworkConfig,
+    type BrowserNetworkUpdate as BrowserNetworkUpdate,
     type BrowserPoolRef as BrowserPoolRef,
     type BrowserProxy as BrowserProxy,
     type BrowserProxyConfig as BrowserProxyConfig,
@@ -2098,6 +2156,8 @@ export declare namespace Browsers {
 
   export {
     Playwright as Playwright,
+    type ExecutorLimitError as ExecutorLimitError,
+    type Tab as Tab,
     type PlaywrightExecuteResponse as PlaywrightExecuteResponse,
     type PlaywrightExecuteParams as PlaywrightExecuteParams,
   };

package/src/resources/browsers/index.ts

@@ -5,6 +5,7 @@ export {
   type BrowserMemory,
   type BrowserMemoryRequest,
   type BrowserNetworkConfig,
+  type BrowserNetworkUpdate,
   type BrowserPoolRef,
   type BrowserProxy,
   type BrowserProxyConfig,
@@ -67,7 +68,13 @@ export {
   type FWriteFileParams,
 } from './fs/index';
 export { Logs, type LogStreamParams } from './logs';
-export { Playwright, type PlaywrightExecuteResponse, type PlaywrightExecuteParams } from './playwright';
+export {
+  Playwright,
+  type ExecutorLimitError,
+  type Tab,
+  type PlaywrightExecuteResponse,
+  type PlaywrightExecuteParams,
+} from './playwright/index';
 export {
   Process,
   type ProcessExecResponse,

package/src/resources/browsers/playwright/executors.ts

@@ -0,0 +1,123 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import { APIPromise } from '../../../core/api-promise';
+import { buildHeaders } from '../../../internal/headers';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+/**
+ * Execute Playwright code against the browser instance and manage the executors it runs in.
+ */
+export class Executors extends APIResource {
+  /**
+   * Lists the default executor first, then the named executors created by POST
+   * /browsers/{id_or_name}/playwright/execute. Each entry reports whether a call is
+   * running on it and, for named executors, the target ID and URL of the tab it
+   * owns. Returns 404 for a browser whose image predates executors.
+   *
+   * @example
+   * ```ts
+   * const executorList =
+   *   await client.browsers.playwright.executors.list(
+   *     'htzv5orfit78e1m2biiifpbv',
+   *   );
+   * ```
+   */
+  list(idOrName: string, options?: RequestOptions): APIPromise<ExecutorList> {
+    return this._client.get(path`/browsers/${idOrName}/playwright/executors`, options);
+  }
+
+  /**
+   * Stops the executor's process. A call running on it fails with an error saying
+   * the executor was deleted. By default the executor's tab is closed too. The name
+   * can be reused; the next call with it creates a new executor and tab.
+   *
+   * The default executor is restarted instead of removed: its process is stopped, a
+   * call running on it fails with an error saying the executor was restarted, and
+   * queued and later calls run on a new process. It owns no tab, so 'close_tab' has
+   * no effect on it.
+   *
+   * @example
+   * ```ts
+   * await client.browsers.playwright.executors.delete(
+   *   'checkout',
+   *   { id_or_name: 'htzv5orfit78e1m2biiifpbv' },
+   * );
+   * ```
+   */
+  delete(name: string, params: ExecutorDeleteParams, options?: RequestOptions): APIPromise<void> {
+    const { id_or_name, close_tab } = params;
+    return this._client.delete(path`/browsers/${id_or_name}/playwright/executors/${name}`, {
+      query: { close_tab },
+      ...options,
+      headers: buildHeaders([{ Accept: '*/*' }, options?.headers]),
+    });
+  }
+}
+
+/**
+ * A Playwright executor on the browser
+ */
+export interface Executor {
+  /**
+   * Whether a call is running on the executor
+   */
+  busy: boolean;
+
+  /**
+   * When the executor was created
+   */
+  created_at: string;
+
+  /**
+   * When the most recent call on the executor started
+   */
+  last_used_at: string;
+
+  /**
+   * Name of a Playwright executor. Calls with the same name run in the same
+   * executor, one at a time; the first call with a new name creates it. Calls on
+   * different executors run concurrently. 'default' names the executor that runs
+   * calls without a name.
+   */
+  name: string;
+
+  /**
+   * CDP page target ID of the executor's tab, once it has one. The default executor
+   * owns no tab.
+   */
+  target_id?: string;
+
+  /**
+   * Current URL of the executor's tab, when it is open
+   */
+  url?: string;
+}
+
+/**
+ * The default executor followed by the named executors
+ */
+export interface ExecutorList {
+  executors: Array<Executor>;
+}
+
+export interface ExecutorDeleteParams {
+  /**
+   * Path param: Browser session ID or name
+   */
+  id_or_name: string;
+
+  /**
+   * Query param: Close the executor's tab. Defaults to true.
+   */
+  close_tab?: boolean;
+}
+
+export declare namespace Executors {
+  export {
+    type Executor as Executor,
+    type ExecutorList as ExecutorList,
+    type ExecutorDeleteParams as ExecutorDeleteParams,
+  };
+}

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

@@ -0,0 +1,10 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export { Executors, type Executor, type ExecutorList, type ExecutorDeleteParams } from './executors';
+export {
+  Playwright,
+  type ExecutorLimitError,
+  type Tab,
+  type PlaywrightExecuteResponse,
+  type PlaywrightExecuteParams,
+} from './playwright';

package/src/resources/browsers/playwright/playwright.ts

@@ -0,0 +1,186 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as ExecutorsAPI from './executors';
+import { Executor, ExecutorDeleteParams, ExecutorList, Executors } from './executors';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+/**
+ * Execute Playwright code against the browser instance and manage the executors it runs in.
+ */
+export class Playwright extends APIResource {
+  executors: ExecutorsAPI.Executors = new ExecutorsAPI.Executors(this._client);
+
+  /**
+   * Execute arbitrary Playwright code in a fresh execution context against the
+   * browser. The code runs in the same VM as the browser, minimizing latency and
+   * maximizing throughput. It has access to 'page', 'context', 'browser', and
+   * 'webmcp' variables. Use 'webmcp.listTools()' to discover browser-wide WebMCP
+   * tools and 'webmcp.invokeTool(toolRef, input?, { timeoutSec? })' to invoke an
+   * exact registration. It can `return` a value, and this value is returned in the
+   * response.
+   *
+   * Every call runs in an executor: a dedicated Node.js process with its own browser
+   * connection. Calls on different executors run concurrently; calls on the same
+   * executor run one at a time. A timeout, crash, or blocked event loop in one
+   * executor does not affect other executors. After a timeout the executor keeps its
+   * process and drops its browser connection, so code abandoned by the timeout
+   * cannot keep driving the browser. After a crash or a blocked event loop, the next
+   * call on that executor starts a fresh process.
+   *
+   * Calls without 'executor' run in the executor named 'default', which always
+   * exists and is the same as passing 'executor: "default"'. In the default
+   * executor, 'page' is bound to an active tab reported by Chrome. In single-window
+   * sessions, this is the foreground tab. When multiple browser windows are open,
+   * Chrome reports one active tab per window and the selected window is unspecified.
+   * 'context' is the BrowserContext that owns the selected page. Use
+   * 'browser.contexts()' to select a context or page explicitly.
+   *
+   * Pass any other name to run the call in a named executor. The first call with a
+   * new name creates it. Each named executor owns a tab: its first call opens a new
+   * background tab in the default browser context, and 'page' is bound to that tab
+   * on every later call while it stays open. Opening it does not change the active
+   * tab of an existing window. If the tab is closed, the next call opens a new one
+   * and reports 'tab.created: true'. Executor code can still reach other tabs
+   * through 'context' and 'browser'; ownership only decides what 'page' is bound to.
+   * Use named executors to drive several tabs of one browser in parallel.
+   *
+   * A browser can have at most 8 named executors; the default executor does not
+   * count. A call that would create another returns 409 with the current executors;
+   * delete one with DELETE /browsers/{id_or_name}/playwright/executors/{name}. Named
+   * executors are not removed automatically while the browser runs; when it shuts
+   * down, they are removed and their tabs closed.
+   *
+   * A named call to a browser whose image predates executors fails with 400 instead
+   * of running on the active tab; calls without 'executor' keep working on every
+   * image.
+   *
+   * @example
+   * ```ts
+   * const response = await client.browsers.playwright.execute(
+   *   'htzv5orfit78e1m2biiifpbv',
+   *   { code: 'code' },
+   * );
+   * ```
+   */
+  execute(
+    idOrName: string,
+    body: PlaywrightExecuteParams,
+    options?: RequestOptions,
+  ): APIPromise<PlaywrightExecuteResponse> {
+    return this._client.post(path`/browsers/${idOrName}/playwright/execute`, { body, ...options });
+  }
+}
+
+/**
+ * Returned when a call would create a named executor beyond the per-browser limit
+ */
+export interface ExecutorLimitError {
+  /**
+   * The default executor and the named executors that already exist
+   */
+  executors: Array<ExecutorsAPI.Executor>;
+
+  /**
+   * Human-readable error description
+   */
+  message: string;
+}
+
+/**
+ * The tab 'page' was bound to for this call. Absent if the call failed before
+ * binding a tab.
+ */
+export interface Tab {
+  /**
+   * Whether this call opened the tab. For a named executor this happens on its first
+   * call and after its previous tab was closed. For the default executor it happens
+   * only when the browser had no open page.
+   */
+  created: boolean;
+
+  /**
+   * CDP page target ID of the tab
+   */
+  target_id: string;
+}
+
+/**
+ * Result of Playwright code execution
+ */
+export interface PlaywrightExecuteResponse {
+  /**
+   * Whether the code executed successfully
+   */
+  success: boolean;
+
+  /**
+   * Error message if execution failed
+   */
+  error?: string;
+
+  /**
+   * The value returned by the code (if any)
+   */
+  result?: unknown;
+
+  /**
+   * Standard error from the execution
+   */
+  stderr?: string;
+
+  /**
+   * Standard output from the execution
+   */
+  stdout?: string;
+
+  /**
+   * The tab 'page' was bound to for this call. Absent if the call failed before
+   * binding a tab.
+   */
+  tab?: Tab;
+}
+
+export interface PlaywrightExecuteParams {
+  /**
+   * TypeScript/JavaScript code to execute. The code has access to 'page', 'context',
+   * and 'browser' variables. It runs within a function, so you can use a return
+   * statement at the end to return a value. This value is returned as the `result`
+   * property in the response. Example: "await page.goto('https://example.com');
+   * return await page.title();"
+   */
+  code: string;
+
+  /**
+   * Name of a Playwright executor. Calls with the same name run in the same
+   * executor, one at a time; the first call with a new name creates it. Calls on
+   * different executors run concurrently. 'default' names the executor that runs
+   * calls without a name.
+   */
+  executor?: string;
+
+  /**
+   * Maximum execution time in seconds. Default is 60.
+   */
+  timeout_sec?: number;
+}
+
+Playwright.Executors = Executors;
+
+export declare namespace Playwright {
+  export {
+    type ExecutorLimitError as ExecutorLimitError,
+    type Tab as Tab,
+    type PlaywrightExecuteResponse as PlaywrightExecuteResponse,
+    type PlaywrightExecuteParams as PlaywrightExecuteParams,
+  };
+
+  export {
+    Executors as Executors,
+    type Executor as Executor,
+    type ExecutorList as ExecutorList,
+    type ExecutorDeleteParams as ExecutorDeleteParams,
+  };
+}

package/src/resources/browsers/playwright.ts

@@ -1,89 +1,3 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
-import { APIResource } from '../../core/resource';
-import { APIPromise } from '../../core/api-promise';
-import { RequestOptions } from '../../internal/request-options';
-import { path } from '../../internal/utils/path';
-
-/**
- * Execute Playwright code against the browser instance.
- */
-export class Playwright extends APIResource {
-  /**
-   * Execute arbitrary Playwright code in a fresh execution context against the
-   * browser. The code runs in the same VM as the browser, minimizing latency and
-   * maximizing throughput. It has access to 'page', 'context', 'browser', and
-   * 'webmcp' variables. Use 'webmcp.listTools()' to discover browser-wide WebMCP
-   * tools and 'webmcp.invokeTool(toolRef, input?, { timeoutSec? })' to invoke an
-   * exact registration. It can `return` a value, and this value is returned in the
-   * response.
-   *
-   * @example
-   * ```ts
-   * const response = await client.browsers.playwright.execute(
-   *   'htzv5orfit78e1m2biiifpbv',
-   *   { code: 'code' },
-   * );
-   * ```
-   */
-  execute(
-    idOrName: string,
-    body: PlaywrightExecuteParams,
-    options?: RequestOptions,
-  ): APIPromise<PlaywrightExecuteResponse> {
-    return this._client.post(path`/browsers/${idOrName}/playwright/execute`, { body, ...options });
-  }
-}
-
-/**
- * Result of Playwright code execution
- */
-export interface PlaywrightExecuteResponse {
-  /**
-   * Whether the code executed successfully
-   */
-  success: boolean;
-
-  /**
-   * Error message if execution failed
-   */
-  error?: string;
-
-  /**
-   * The value returned by the code (if any)
-   */
-  result?: unknown;
-
-  /**
-   * Standard error from the execution
-   */
-  stderr?: string;
-
-  /**
-   * Standard output from the execution
-   */
-  stdout?: string;
-}
-
-export interface PlaywrightExecuteParams {
-  /**
-   * TypeScript/JavaScript code to execute. The code has access to 'page', 'context',
-   * and 'browser' variables. It runs within a function, so you can use a return
-   * statement at the end to return a value. This value is returned as the `result`
-   * property in the response. Example: "await page.goto('https://example.com');
-   * return await page.title();"
-   */
-  code: string;
-
-  /**
-   * Maximum execution time in seconds. Default is 60.
-   */
-  timeout_sec?: number;
-}
-
-export declare namespace Playwright {
-  export {
-    type PlaywrightExecuteResponse as PlaywrightExecuteResponse,
-    type PlaywrightExecuteParams as PlaywrightExecuteParams,
-  };
-}
+export * from './playwright/index';

package/src/resources/browsers/telemetry.ts

@@ -4325,12 +4325,13 @@ export namespace BrowserPlatformAPICallEvent {
 
 /**
  * A branded proxy-layer failure observed by the browser. Emitted when the metro
- * egress host-proxy serves a branded 5xx error page whose response carries the
- * X-Kernel-Proxy-Error header. Low-volume and carries a typed code. Its value is
- * per-session and per-URL attribution for sessions that already capture the
- * network stream: proxy failures are only observable while the CDP network
- * collector is running, so this is an opt-in refinement of the raw network events
- * rather than a default-on alerting signal.
+ * egress host-proxy serves a branded error page whose response carries the
+ * X-Kernel-Proxy-Error header: a 502 for proxy-layer failures, or a 403 when the
+ * session's network policy blocks the destination. Low-volume and carries a typed
+ * code. Its value is per-session and per-URL attribution for sessions that already
+ * capture the network stream: proxy failures are only observable while the CDP
+ * network collector is running, so this is an opt-in refinement of the raw network
+ * events rather than a default-on alerting signal.
  */
 export interface BrowserProxyErrorEvent {
   category: 'network';
@@ -4369,17 +4370,18 @@ export namespace BrowserProxyErrorEvent {
   export interface Data extends TelemetryAPI.BrowserEventContext {
     /**
      * 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, 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.
+     * branded error page served by the metro egress host-proxy. Values mirror what the
+     * proxy emits: destination_blocked, destination_route_unavailable,
+     * network_policy_denied, 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'
+      | 'network_policy_denied'
       | 'provider_blacklisted'
       | 'provider_unreachable'
       | 'provider_rejected'
@@ -4398,7 +4400,8 @@ export namespace BrowserProxyErrorEvent {
     request_id: string;
 
     /**
-     * HTTP response status of the branded error page (502).
+     * HTTP response status of the branded error page (502, or 403 for
+     * network_policy_denied).
      */
     status: number;