@hyperbrowser/sdk 1.0.3 → 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/computer-action.d.ts

@@ -3,13 +3,16 @@ import { ComputerActionResponse, Coordinate, ComputerActionMouseButton } from ".
 import { BaseService } from "./base";
 export declare class ComputerActionService extends BaseService {
     private executeRequest;
-    click(session: SessionDetail | string, x: number, y: number, button?: ComputerActionMouseButton, numClicks?: number, returnScreenshot?: boolean): Promise<ComputerActionResponse>;
+    click(session: SessionDetail | string, x: number, y: number, button?: ComputerActionMouseButton, numClicks?: number, returnScreenshot?: boolean, keys?: string[]): Promise<ComputerActionResponse>;
+    clickAtCursor(session: SessionDetail | string, button?: ComputerActionMouseButton, numClicks?: number, returnScreenshot?: boolean, keys?: string[]): Promise<ComputerActionResponse>;
     typeText(session: SessionDetail | string, text: string, returnScreenshot?: boolean): Promise<ComputerActionResponse>;
     screenshot(session: SessionDetail | string): Promise<ComputerActionResponse>;
+    cursorPosition(session: SessionDetail | string, returnScreenshot?: boolean): Promise<ComputerActionResponse>;
     pressKeys(session: SessionDetail | string, keys: string[], returnScreenshot?: boolean): Promise<ComputerActionResponse>;
-    drag(session: SessionDetail | string, path: Coordinate[], returnScreenshot?: boolean): Promise<ComputerActionResponse>;
+    drag(session: SessionDetail | string, path: Coordinate[], returnScreenshot?: boolean, keys?: string[]): Promise<ComputerActionResponse>;
     moveMouse(session: SessionDetail | string, x: number, y: number, returnScreenshot?: boolean): Promise<ComputerActionResponse>;
-    scroll(session: SessionDetail | string, x: number, y: number, scrollX: number, scrollY: number, returnScreenshot?: boolean): Promise<ComputerActionResponse>;
+    scroll(session: SessionDetail | string, x: number, y: number, scrollX: number, scrollY: number, returnScreenshot?: boolean, keys?: string[]): Promise<ComputerActionResponse>;
+    scrollAtCursor(session: SessionDetail | string, scrollX?: number, scrollY?: number, returnScreenshot?: boolean, keys?: string[]): Promise<ComputerActionResponse>;
     holdKey(session: SessionDetail | string, key: string, duration: number, returnScreenshot?: boolean): Promise<ComputerActionResponse>;
     mouseDown(session: SessionDetail | string, button?: ComputerActionMouseButton, returnScreenshot?: boolean): Promise<ComputerActionResponse>;
     mouseUp(session: SessionDetail | string, button?: ComputerActionMouseButton, returnScreenshot?: boolean): Promise<ComputerActionResponse>;

package/dist/services/computer-action.js

@@ -29,14 +29,24 @@ class ComputerActionService extends base_1.BaseService {
             throw new client_1.HyperbrowserError("Failed to execute computer action", undefined);
         }
     }
-    async click(session, x, y, button = "left", numClicks = 1, returnScreenshot = false) {
+    async click(session, x, y, button = "left", numClicks = 1, returnScreenshot = false, keys) {
         return this.executeRequest(session, {
             action: computer_action_1.ComputerAction.CLICK,
             x,
             y,
             button,
             numClicks,
+            keys,
+            returnScreenshot,
+        });
+    }
+    async clickAtCursor(session, button = "left", numClicks = 1, returnScreenshot = false, keys) {
+        return this.executeRequest(session, {
+            action: computer_action_1.ComputerAction.CLICK,
+            button,
+            numClicks,
             returnScreenshot,
+            keys,
         });
     }
     async typeText(session, text, returnScreenshot = false) {
@@ -51,6 +61,12 @@ class ComputerActionService extends base_1.BaseService {
             action: computer_action_1.ComputerAction.SCREENSHOT,
         });
     }
+    async cursorPosition(session, returnScreenshot = false) {
+        return this.executeRequest(session, {
+            action: computer_action_1.ComputerAction.CURSOR_POSITION,
+            returnScreenshot,
+        });
+    }
     async pressKeys(session, keys, returnScreenshot = false) {
         return this.executeRequest(session, {
             action: computer_action_1.ComputerAction.PRESS_KEYS,
@@ -58,10 +74,11 @@ class ComputerActionService extends base_1.BaseService {
             returnScreenshot,
         });
     }
-    async drag(session, path, returnScreenshot = false) {
+    async drag(session, path, returnScreenshot = false, keys) {
         return this.executeRequest(session, {
             action: computer_action_1.ComputerAction.DRAG,
             path,
+            keys,
             returnScreenshot,
         });
     }
@@ -73,16 +90,26 @@ class ComputerActionService extends base_1.BaseService {
             returnScreenshot,
         });
     }
-    async scroll(session, x, y, scrollX, scrollY, returnScreenshot = false) {
+    async scroll(session, x, y, scrollX, scrollY, returnScreenshot = false, keys) {
         return this.executeRequest(session, {
             action: computer_action_1.ComputerAction.SCROLL,
             x,
             y,
             scrollX,
             scrollY,
+            keys,
             returnScreenshot,
         });
     }
+    async scrollAtCursor(session, scrollX = 0, scrollY = 0, returnScreenshot = false, keys) {
+        return this.executeRequest(session, {
+            action: computer_action_1.ComputerAction.SCROLL,
+            scrollX,
+            scrollY,
+            returnScreenshot,
+            keys,
+        });
+    }
     async holdKey(session, key, duration, returnScreenshot = false) {
         return this.executeRequest(session, {
             action: computer_action_1.ComputerAction.HOLD_KEY,

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/computer-action.d.ts

@@ -10,6 +10,7 @@ export declare enum ComputerAction {
     PRESS_KEYS = "press_keys",
     MOVE_MOUSE = "move_mouse",
     SCREENSHOT = "screenshot",
+    CURSOR_POSITION = "cursor_position",
     SCROLL = "scroll",
     TYPE_TEXT = "type_text",
     GET_CLIPBOARD_TEXT = "get_clipboard_text",
@@ -33,6 +34,7 @@ export interface ClickActionParams {
     y?: number;
     button?: ComputerActionMouseButton;
     numClicks?: number;
+    keys?: string[];
     returnScreenshot?: boolean;
 }
 /**
@@ -41,6 +43,7 @@ export interface ClickActionParams {
 export interface DragActionParams {
     action: ComputerAction.DRAG;
     path: Coordinate[];
+    keys?: string[];
     returnScreenshot?: boolean;
 }
 /**
@@ -66,6 +69,11 @@ export interface MoveMouseActionParams {
 export interface ScreenshotActionParams {
     action: ComputerAction.SCREENSHOT;
 }
+/** Parameters for reading the desktop cursor position. */
+export interface CursorPositionActionParams {
+    action: ComputerAction.CURSOR_POSITION;
+    returnScreenshot?: boolean;
+}
 /**
  * Parameters for scroll action
  */
@@ -73,10 +81,13 @@ export interface ScrollActionParams {
     action: ComputerAction.SCROLL;
     x: number;
     y: number;
+    keys?: string[];
     scrollX: number;
     scrollY: number;
     returnScreenshot?: boolean;
 }
+/** Parameters for scrolling without moving the desktop cursor. */
+export type ScrollAtCursorActionParams = Omit<ScrollActionParams, "x" | "y">;
 /**
  * Parameters for type text action
  */
@@ -129,7 +140,7 @@ export interface ListWindowsActionParams {
 /**
  * Union type for all computer action parameters
  */
-export type ComputerActionParams = ClickActionParams | DragActionParams | PressKeysActionParams | MoveMouseActionParams | ScreenshotActionParams | ScrollActionParams | TypeTextActionParams | HoldKeyActionParams | MouseDownActionParams | MouseUpActionParams | GetClipboardTextActionParams | PutSelectionTextActionParams | ListWindowsActionParams;
+export type ComputerActionParams = ClickActionParams | DragActionParams | PressKeysActionParams | MoveMouseActionParams | ScreenshotActionParams | CursorPositionActionParams | ScrollActionParams | ScrollAtCursorActionParams | TypeTextActionParams | HoldKeyActionParams | MouseDownActionParams | MouseUpActionParams | GetClipboardTextActionParams | PutSelectionTextActionParams | ListWindowsActionParams;
 export interface ComputerActionResponseDataClipboardText {
     clipboardText?: string;
 }
@@ -148,7 +159,12 @@ export interface ComputerActionResponseDataListWindows {
     activeWindowId: string;
     windows: ComputerActionWindow[];
 }
-export type ComputerActionResponseData = ComputerActionResponseDataClipboardText | ComputerActionResponseDataListWindows;
+/** Desktop cursor coordinates in physical screen pixels. */
+export interface ComputerActionResponseDataCursorPosition {
+    x: number;
+    y: number;
+}
+export type ComputerActionResponseData = ComputerActionResponseDataCursorPosition | ComputerActionResponseDataClipboardText | ComputerActionResponseDataListWindows;
 /**
  * Response from computer action API
  */

package/dist/types/computer-action.js

@@ -14,6 +14,7 @@ var ComputerAction;
     ComputerAction["PRESS_KEYS"] = "press_keys";
     ComputerAction["MOVE_MOUSE"] = "move_mouse";
     ComputerAction["SCREENSHOT"] = "screenshot";
+    ComputerAction["CURSOR_POSITION"] = "cursor_position";
     ComputerAction["SCROLL"] = "scroll";
     ComputerAction["TYPE_TEXT"] = "type_text";
     ComputerAction["GET_CLIPBOARD_TEXT"] = "get_clipboard_text";

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";
@@ -17,7 +18,7 @@ export { CreateProfileParams, ForkProfileParams, ProfileResponse, CreateProfileR
 export { CreateExtensionParams, CreateExtensionResponse, ListExtensionsResponse, } from "./extension";
 export { ExtractJobStatus, BrowserUseTaskStatus, BrowserUseLlm, ClaudeComputerUseLlm, ClaudeComputerUseReasoningEffort, CuaLlm, CuaReasoningEffort, GeminiComputerUseLlm, GrokComputerUseLlm, GrokReasoningEffort, MetaComputerUseLlm, MetaReasoningEffort, JevComputerUseLlm, JevTextLlm, ScrapeScreenshotFormat, ScrapeJobStatus, CrawlJobStatus, Country, State, ISO639_1, OperatingSystem, Platform, ScrapeFormat, ScrapeWaitUntil, ScrapePageStatus, CrawlPageStatus, RecordingStatus, DownloadsStatus, HyperAgentLlm, HyperAgentTaskStatus, ClaudeComputerUseTaskStatus, CuaTaskStatus, GeminiComputerUseTaskStatus, GrokComputerUseTaskStatus, MetaComputerUseTaskStatus, JevComputerUseTaskStatus, SessionEventLogType, SessionRegion, BrowserUseVersion, HyperAgentVersion, } from "./constants";
 export { TeamCreditInfo } from "./team";
-export { ComputerAction, Coordinate, ClickActionParams, DragActionParams, PressKeysActionParams, MoveMouseActionParams, ScreenshotActionParams, ScrollActionParams, TypeTextActionParams, ComputerActionParams, ComputerActionResponse, ComputerActionMouseButton, ComputerActionResponseData, HoldKeyActionParams, MouseDownActionParams, MouseUpActionParams, GetClipboardTextActionParams, PutSelectionTextActionParams, ComputerActionResponseDataClipboardText, ListWindowsActionParams, ComputerActionWindow, ComputerActionResponseDataListWindows, } from "./computer-action";
+export { ComputerAction, Coordinate, ClickActionParams, DragActionParams, PressKeysActionParams, MoveMouseActionParams, ScreenshotActionParams, CursorPositionActionParams, ScrollAtCursorActionParams, ScrollActionParams, TypeTextActionParams, ComputerActionParams, ComputerActionResponse, ComputerActionMouseButton, ComputerActionResponseData, HoldKeyActionParams, MouseDownActionParams, MouseUpActionParams, GetClipboardTextActionParams, PutSelectionTextActionParams, ComputerActionResponseDataClipboardText, ListWindowsActionParams, ComputerActionWindow, ComputerActionResponseDataListWindows, ComputerActionResponseDataCursorPosition, } from "./computer-action";
 export { FetchParams, FetchResponse, FetchResponseData, FetchStatus } from "./web/fetch";
 export { StartBatchFetchJobParams, GetBatchFetchJobParams, StartBatchFetchJobResponse, BatchFetchJobStatusResponse, BatchFetchJobResponse, BatchFetchJobStatus, } from "./web/batch-fetch";
 export { WebSearchParams, WebSearchResponse, WebSearchResponseData, WebSearchResultItem, WebSearchFilters, WebSearchLocation, WebSearchFiletype, WebSearchStatus, } from "./web/search";

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.0.3",
+  "version": "1.2.0",
   "description": "Node SDK for Hyperbrowser API",
   "author": "",
   "repository": {