@hyperbrowser/sdk 1.1.0 → 1.2.0

package/README.md

@@ -16,6 +16,40 @@ or
 yarn add @hyperbrowser/sdk
 ```
 
+## WebMCP page tools
+
+Create a session with `enableWebMcp: true` (default: false), then navigate to a page
+that exposes WebMCP tools using Playwright or Puppeteer. With that session open:
+
+```typescript
+const discovery = await client.sessions.webmcp.listTools(session.id);
+// Select a tool using its name, source page/frame, and input schema.
+const tool = discovery.tools.find((tool) => tool.name === "search");
+if (!tool) throw new Error("The page has no search tool");
+const result = await client.sessions.webmcp.invoke(session.id, {
+  toolRef: tool.toolRef,
+  input: { query: "flights to Tokyo" }, // Match the selected tool's schema.
+});
+console.log(result.status, result.output);
+```
+
+For long-running tools or forms awaiting human submission, use
+`sessions.webmcp.start(sessionId, params)`, then
+`sessions.webmcp.getResult(sessionId, invocationId, { waitSeconds: 30 })` until the
+status is terminal. `sessions.webmcp.cancel(sessionId, invocationId)` requests
+best-effort cancellation. Blocking invocation defaults to 60 seconds (maximum
+120); `start` defaults to 300 seconds (maximum 3,600) via `timeoutSeconds`.
+
+Discover tools again after navigation. Invocations never automatically retry;
+losing a response can leave an unknown outcome. Handles are ephemeral and
+terminal results expire after 10 minutes or earlier eviction. Check result
+status and truncation metadata before using output. Public types, including
+`WebMCPTool`, `WebMCPInvocation`, and the request types, are exported from
+`@hyperbrowser/sdk/types`.
+
+See the [WebMCP guide](https://hyperbrowser.ai/docs/sessions/webmcp) for complete
+examples, cancellation behavior, human submission, and limits.
+
 ## Usage
 
 ### Playwright

package/dist/services/sessions.d.ts

@@ -1,5 +1,6 @@
 import { BasicResponse, CaptchaEvaluationParams, CaptchaEvaluationResponse, CreateSessionParams, CreateSessionSnapshotResponse, GetActiveSessionsCountResponse, GetSessionDownloadsUrlResponse, GetSessionRecordingUrlResponse, GetSessionVideoRecordingUrlResponse, SessionDetail, SessionListParams, SessionListResponse, SessionRecording, UploadFileOptions, UploadFileResponse, SessionEventLogListParams, SessionEventLogListResponse, UpdateSessionProfileParams, UpdateSessionProxyParams, UpdateSessionScreenParams, UpdateSessionSolveCaptchasParams, UpdateSessionSolveCaptchasResponse, SessionGetParams } from "../types/session";
 import { BaseService } from "./base";
+import { WebMCPService } from "./webmcp";
 /**
  * Service for managing session event logs
  */
@@ -13,6 +14,7 @@ declare class SessionEventLogsService extends BaseService {
 }
 export declare class SessionsService extends BaseService {
     readonly eventLogs: SessionEventLogsService;
+    readonly webmcp: WebMCPService;
     constructor(apiKey: string, baseUrl: string, timeout: number);
     /**
      * Create a new browser session

package/dist/services/sessions.js

@@ -31,6 +31,7 @@ const fs_1 = require("fs");
 const path = __importStar(require("path"));
 const form_data_1 = __importDefault(require("form-data"));
 const base_1 = require("./base");
+const webmcp_1 = require("./webmcp");
 const client_1 = require("../client");
 const CAPTCHA_EVALUATION_REQUEST_TIMEOUT_MS = 185000;
 /**
@@ -61,6 +62,7 @@ class SessionsService extends base_1.BaseService {
     constructor(apiKey, baseUrl, timeout) {
         super(apiKey, baseUrl, timeout);
         this.eventLogs = new SessionEventLogsService(apiKey, baseUrl, timeout);
+        this.webmcp = new webmcp_1.WebMCPService(apiKey, baseUrl, timeout);
     }
     /**
      * Create a new browser session

package/dist/services/webmcp.d.ts

@@ -0,0 +1,16 @@
+import { BaseService } from "./base";
+import { WebMCPInvocation, WebMCPInvokeParams, WebMCPInvokeResult, WebMCPResultParams, WebMCPStartParams, WebMCPToolsResponse } from "../types/webmcp";
+/** Page tools for sessions created with enableWebMcp: true. */
+export declare class WebMCPService extends BaseService {
+    private path;
+    /** Discover current tools across the session's tabs and frames. */
+    listTools(sessionId: string): Promise<WebMCPToolsResponse>;
+    /** Invoke once. Transport failures never cause an automatic retry. */
+    invoke(sessionId: string, params: WebMCPInvokeParams): Promise<WebMCPInvokeResult>;
+    /** Start once and return a handle. A lost response may mean the tool already ran. */
+    start(sessionId: string, params: WebMCPStartParams): Promise<WebMCPInvocation>;
+    /** Read or long-poll a handle. Pending responses do not cancel or restart the tool. */
+    getResult(sessionId: string, invocationId: string, params?: WebMCPResultParams): Promise<WebMCPInvocation>;
+    /** Request cancellation; completion can win the race. Read getResult for the outcome. */
+    cancel(sessionId: string, invocationId: string): Promise<WebMCPInvocation>;
+}

package/dist/services/webmcp.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.WebMCPService = void 0;
+const base_1 = require("./base");
+function seconds(value, min, max, name) {
+    if (!Number.isInteger(value) || value < min || value > max) {
+        throw new RangeError(`${name} must be an integer between ${min} and ${max}`);
+    }
+    return value;
+}
+function invocationBody(params) {
+    if (typeof params.toolRef !== "string" || !params.toolRef.trim()) {
+        throw new TypeError("toolRef must be a non-empty string from listTools");
+    }
+    if (params.input !== undefined &&
+        (params.input === null || typeof params.input !== "object" || Array.isArray(params.input))) {
+        throw new TypeError("input must be a JSON object");
+    }
+    return JSON.stringify(params);
+}
+/** Page tools for sessions created with enableWebMcp: true. */
+class WebMCPService extends base_1.BaseService {
+    path(sessionId) {
+        return `/session/${encodeURIComponent(sessionId)}/webmcp`;
+    }
+    /** Discover current tools across the session's tabs and frames. */
+    async listTools(sessionId) {
+        return this.request(`${this.path(sessionId)}/tools`, {
+            timeout: Math.max(this.timeout, 40000),
+        });
+    }
+    /** Invoke once. Transport failures never cause an automatic retry. */
+    async invoke(sessionId, params) {
+        const timeout = seconds(params.timeoutSeconds ?? 60, 1, 120, "timeoutSeconds");
+        return this.request(`${this.path(sessionId)}/invoke`, {
+            method: "POST",
+            body: invocationBody(params),
+            timeout: Math.max(this.timeout, (timeout + 35) * 1000),
+        });
+    }
+    /** Start once and return a handle. A lost response may mean the tool already ran. */
+    async start(sessionId, params) {
+        seconds(params.timeoutSeconds ?? 300, 1, 3600, "timeoutSeconds");
+        return this.request(`${this.path(sessionId)}/invocations`, {
+            method: "POST",
+            body: invocationBody(params),
+            timeout: Math.max(this.timeout, 40000),
+        });
+    }
+    /** Read or long-poll a handle. Pending responses do not cancel or restart the tool. */
+    async getResult(sessionId, invocationId, params = {}) {
+        const wait = seconds(params.waitSeconds ?? 0, 0, 30, "waitSeconds");
+        return this.request(`${this.path(sessionId)}/invocations/${encodeURIComponent(invocationId)}`, { timeout: Math.max(this.timeout, (wait + 20) * 1000) }, { waitSeconds: params.waitSeconds });
+    }
+    /** Request cancellation; completion can win the race. Read getResult for the outcome. */
+    async cancel(sessionId, invocationId) {
+        return this.request(`${this.path(sessionId)}/invocations/${encodeURIComponent(invocationId)}/cancel`, { method: "POST", timeout: Math.max(this.timeout, 20000) });
+    }
+}
+exports.WebMCPService = WebMCPService;

package/dist/types/index.d.ts

@@ -1,4 +1,5 @@
 export { HyperbrowserConfig } from "./config";
+export * from "./webmcp";
 export { StartCrawlJobParams, StartCrawlJobResponse, CrawledPage, CrawlJobResponse, GetCrawlJobParams, CrawlJobStatusResponse, } from "./crawl";
 export { StartScrapeJobParams, StartScrapeJobResponse, ScrapeJobData, ScrapeJobResponse, ScrapeOptions, ScrapeJobStatusResponse, BatchScrapeJobStatusResponse, StorageStateOptions, } from "./scrape";
 export { StartExtractJobParams, StartExtractJobResponse, ExtractJobResponse, ExtractJobStatusResponse, ExtractJobMetadata, } from "./extract";

package/dist/types/index.js

@@ -1,5 +1,20 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ComputerAction = void 0;
+__exportStar(require("./webmcp"), exports);
 var computer_action_1 = require("./computer-action");
 Object.defineProperty(exports, "ComputerAction", { enumerable: true, get: function () { return computer_action_1.ComputerAction; } });

package/dist/types/session.d.ts

@@ -10,6 +10,7 @@ export interface SessionProfile {
     persistChanges?: boolean;
 }
 export interface SessionLaunchState {
+    enableWebMcp?: boolean;
     useUltraStealth?: boolean;
     useStealth?: boolean;
     useProxy?: boolean;
@@ -128,6 +129,8 @@ export interface StartSessionFromSnapshotParams {
     snapshotId: string;
 }
 export interface CreateSessionParams {
+    /** Enable page-provided WebMCP tools. Defaults to false on the server. */
+    enableWebMcp?: boolean;
     useUltraStealth?: boolean;
     useStealth?: boolean;
     useProxy?: boolean;

package/dist/types/webmcp.d.ts

@@ -0,0 +1,84 @@
+/** Page-provided hints; these are not browser-enforced guarantees. */
+export interface WebMCPAnnotations {
+    readOnly: boolean;
+    untrustedContent: boolean;
+    consequential: boolean;
+    autosubmit: boolean;
+    destructive?: boolean;
+    idempotent?: boolean;
+    openWorld?: boolean;
+}
+export interface WebMCPFrame {
+    id: string;
+    url: string;
+    isMainFrame: boolean;
+}
+export interface WebMCPSource {
+    provider: "native" | "polyfill";
+    tabId: string;
+    pageUrl: string;
+    pageTitle: string;
+    frame: WebMCPFrame;
+}
+export interface WebMCPTool {
+    /** Opaque reference to this document. Discover tools again after navigation. */
+    toolRef: string;
+    name: string;
+    title?: string;
+    description: string;
+    inputSchema?: Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
+    annotations: WebMCPAnnotations;
+    declarative: boolean;
+    /** Native DOM node identifier, when available, in the source target/frame. */
+    backendNodeId?: number;
+    source: WebMCPSource;
+}
+export interface WebMCPToolsResponse {
+    tools: WebMCPTool[];
+    nativeSupported: boolean;
+    truncated: boolean;
+}
+export interface WebMCPInvokeParams {
+    toolRef: string;
+    /** Page-defined keys are passed through unchanged. Defaults to {}. */
+    input?: Record<string, unknown>;
+    /** Execution deadline in seconds: 1–120, default 60. */
+    timeoutSeconds?: number;
+}
+export interface WebMCPStartParams extends WebMCPInvokeParams {
+    /** Execution deadline including human submission: 1–3600 seconds, default 300. */
+    timeoutSeconds?: number;
+}
+export interface WebMCPResultParams {
+    /** Wait 0–30 seconds, default 0. A pending response does not cancel the tool. */
+    waitSeconds?: number;
+}
+export type WebMCPInvokeStatus = "completed" | "error" | "canceled" | "awaiting_submission";
+export type WebMCPInvocationStatus = WebMCPInvokeStatus | "running" | "outcome_unknown";
+export interface WebMCPInvokeResult {
+    invocationId?: string;
+    status: WebMCPInvokeStatus;
+    output?: unknown;
+    errorText?: string;
+    outputBytes: number;
+    outputTruncated?: boolean;
+    outputPreview?: string;
+    untrustedContent: boolean;
+    durationMs: number;
+}
+export interface WebMCPInvocationError {
+    code: string;
+    message: string;
+}
+/** Session-local record; results expire and do not survive receiver restarts. */
+export interface WebMCPInvocation {
+    invocationId: string;
+    toolRef: string;
+    status: WebMCPInvocationStatus;
+    cancellationRequested: boolean;
+    createdAt: string;
+    expiresAt?: string;
+    result?: WebMCPInvokeResult;
+    error?: WebMCPInvocationError;
+}

package/dist/types/webmcp.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperbrowser/sdk",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Node SDK for Hyperbrowser API",
   "author": "",
   "repository": {