@hyperbrowser/sdk 1.2.2 → 1.4.0

package/dist/services/vaults.js

@@ -0,0 +1,80 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VaultsService = void 0;
+const error_1 = require("../error");
+const base_1 = require("./base");
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Teams hold at most 100 vaults, so this covers every exact-name match. */
+const NAME_LOOKUP_LIMIT = 100;
+const vaultPath = (id) => `/vaults/${encodeURIComponent(id)}`;
+/**
+ * Vaults name a set of environment variables whose values come from stored
+ * secrets. Pass one as `vault` to a sandbox process
+ * or sandbox create, or attach it to a browser session with
+ * `credentials: [{ vault }]` and fill its entries by name.
+ *
+ * Methods that take `vault` accept its ID or its exact name. A UUID-shaped
+ * argument is tried as an ID first and then as a name.
+ */
+class VaultsService extends base_1.BaseService {
+    async list(params = {}) {
+        const { page, limit, search } = params;
+        const response = await this.request("/vaults", undefined, {
+            search,
+            page,
+            limit,
+        });
+        return { ...response, vaults: response.vaults ?? [] };
+    }
+    get(vault) {
+        return this.resolve(vault);
+    }
+    /** Create a vault. Entries name secrets, never values. */
+    create(params) {
+        return this.request("/vaults", { method: "POST", body: JSON.stringify(params) });
+    }
+    /**
+     * Change a vault's description or its entries:
+     * each entry given replaces that variable, `null` removes it, and entries
+     * not given are kept.
+     */
+    async update(vault, params) {
+        const { id } = await this.resolve(vault);
+        return await this.request(vaultPath(id), {
+            method: "PATCH",
+            body: JSON.stringify(params),
+        });
+    }
+    /** Delete a vault. The secrets its entries name are kept. */
+    async delete(vault) {
+        const { id } = await this.resolve(vault);
+        return await this.request(vaultPath(id), { method: "DELETE" });
+    }
+    async resolve(key) {
+        if (typeof key !== "string" || !key.trim()) {
+            throw (0, error_1.invalidRequest)("A vault ID or name is required");
+        }
+        key = key.trim();
+        if (UUID_PATTERN.test(key)) {
+            try {
+                return await this.request(vaultPath(key));
+            }
+            catch (error) {
+                if (!(error instanceof error_1.HyperbrowserError) || error.statusCode !== 404) {
+                    throw error;
+                }
+            }
+        }
+        const { vaults } = await this.list({ search: key, limit: NAME_LOOKUP_LIMIT });
+        const vault = vaults.find((candidate) => candidate.name === key);
+        if (!vault) {
+            throw new error_1.HyperbrowserError(`Vault ${JSON.stringify(key)} not found`, {
+                statusCode: 404,
+                code: "VAULT_NOT_FOUND",
+                service: "control",
+            });
+        }
+        return vault;
+    }
+}
+exports.VaultsService = VaultsService;

package/dist/tools/anthropic.d.ts

@@ -38,3 +38,4 @@ export declare const EXTRACT_TOOL_ANTHROPIC: Tool;
 export declare const BROWSER_USE_TOOL_ANTHROPIC: Tool;
 export declare const CLAUDE_COMPUTER_USE_TOOL_ANTHROPIC: Tool;
 export declare const OPENAI_CUA_TOOL_ANTHROPIC: Tool;
+export declare const FILL_CREDENTIAL_TOOL_ANTHROPIC: Tool;

package/dist/tools/anthropic.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OPENAI_CUA_TOOL_ANTHROPIC = exports.CLAUDE_COMPUTER_USE_TOOL_ANTHROPIC = exports.BROWSER_USE_TOOL_ANTHROPIC = exports.EXTRACT_TOOL_ANTHROPIC = exports.CRAWL_TOOL_ANTHROPIC = exports.SCREENSHOT_TOOL_ANTHROPIC = exports.SCRAPE_TOOL_ANTHROPIC = void 0;
+exports.FILL_CREDENTIAL_TOOL_ANTHROPIC = exports.OPENAI_CUA_TOOL_ANTHROPIC = exports.CLAUDE_COMPUTER_USE_TOOL_ANTHROPIC = exports.BROWSER_USE_TOOL_ANTHROPIC = exports.EXTRACT_TOOL_ANTHROPIC = exports.CRAWL_TOOL_ANTHROPIC = exports.SCREENSHOT_TOOL_ANTHROPIC = exports.SCRAPE_TOOL_ANTHROPIC = void 0;
 const schema_1 = require("./schema");
 exports.SCRAPE_TOOL_ANTHROPIC = {
     input_schema: schema_1.SCRAPE_SCHEMA,
@@ -37,3 +37,8 @@ exports.OPENAI_CUA_TOOL_ANTHROPIC = {
     name: "openai_cua",
     description: schema_1.OPENAI_CUA_DESCRIPTION,
 };
+exports.FILL_CREDENTIAL_TOOL_ANTHROPIC = {
+    input_schema: schema_1.FILL_CREDENTIAL_SCHEMA,
+    name: "fill_credential",
+    description: schema_1.FILL_CREDENTIAL_DESCRIPTION,
+};

package/dist/tools/gemini.d.ts

@@ -0,0 +1,56 @@
+export declare const FILL_CREDENTIAL_TOOL_GEMINI: {
+    name: string;
+    description: string;
+    parameters: {
+        type: string;
+        properties: {
+            credential: {
+                type: string;
+                nullable: boolean;
+                description: string;
+            };
+            vault: {
+                type: string;
+                nullable: boolean;
+                description: string;
+            };
+            fields: {
+                type: string;
+                description: string;
+                minItems: string;
+                maxItems: string;
+                items: {
+                    type: string;
+                    properties: {
+                        selector: {
+                            type: string;
+                            description: string;
+                        };
+                        field: {
+                            type: string;
+                            nullable: boolean;
+                            description: string;
+                        };
+                    };
+                    required: string[];
+                };
+            };
+            page_id: {
+                type: string;
+                nullable: boolean;
+                description: string;
+            };
+            page_url: {
+                type: string;
+                nullable: boolean;
+                description: string;
+            };
+            frame_url: {
+                type: string;
+                nullable: boolean;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};

package/dist/tools/gemini.js

@@ -0,0 +1,40 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FILL_CREDENTIAL_TOOL_GEMINI = void 0;
+const schema_1 = require("./schema");
+// This declaration covers fill_credential only. General tool/schema conversion
+// belongs in a separate change rather than expanding the credentials API.
+const nullableString = (description) => ({ type: "STRING", nullable: true, description });
+const properties = schema_1.FILL_CREDENTIAL_SCHEMA.properties;
+exports.FILL_CREDENTIAL_TOOL_GEMINI = {
+    name: "fill_credential",
+    description: schema_1.FILL_CREDENTIAL_DESCRIPTION,
+    parameters: {
+        type: "OBJECT",
+        properties: {
+            credential: nullableString(properties.credential.description),
+            vault: nullableString(properties.vault.description),
+            fields: {
+                type: "ARRAY",
+                description: properties.fields.description,
+                minItems: String(properties.fields.minItems),
+                maxItems: String(properties.fields.maxItems),
+                items: {
+                    type: "OBJECT",
+                    properties: {
+                        selector: {
+                            type: "STRING",
+                            description: properties.fields.items.properties.selector.description,
+                        },
+                        field: nullableString(properties.fields.items.properties.field.description),
+                    },
+                    required: properties.fields.items.required,
+                },
+            },
+            page_id: nullableString(properties.page_id.description),
+            page_url: nullableString(properties.page_url.description),
+            frame_url: nullableString(properties.frame_url.description),
+        },
+        required: schema_1.FILL_CREDENTIAL_SCHEMA.required,
+    },
+};

package/dist/tools/index.d.ts

@@ -1,6 +1,22 @@
 import { HyperbrowserClient } from "../client";
 import { StartScrapeJobParams, StartCrawlJobParams, StartBrowserUseTaskParams, StartCuaTaskParams, StartClaudeComputerUseTaskParams } from "../types";
 import { StartExtractJobParams } from "../types/extract";
+export { FILL_CREDENTIAL_DESCRIPTION, FILL_CREDENTIAL_SCHEMA } from "./schema";
+export { FILL_CREDENTIAL_TOOL_OPENAI } from "./openai";
+export { FILL_CREDENTIAL_TOOL_ANTHROPIC } from "./anthropic";
+export * from "./gemini";
+/** What the model passes to `fill_credential`. Unused options are null. */
+export interface CredentialFillToolParams {
+    credential?: string | null;
+    vault?: string | null;
+    fields: {
+        selector: string;
+        field?: string | null;
+    }[];
+    page_id?: string | null;
+    page_url?: string | null;
+    frame_url?: string | null;
+}
 export declare class WebsiteScrapeTool {
     static openaiToolDefinition: import("./openai").ChatCompletionTool;
     static anthropicToolDefinition: import("./anthropic").Tool;
@@ -36,3 +52,79 @@ export declare class OpenAICuaTool {
     static anthropicToolDefinition: import("./anthropic").Tool;
     static runnable(hb: HyperbrowserClient, params: StartCuaTaskParams): Promise<string>;
 }
+/**
+ * Lets a model fill a secret, or a vault's entries, attached to a browser
+ * session. The application binds the session; the model chooses only names,
+ * selectors and which tab, and never sees values.
+ *
+ * It deliberately has no `onePassword`: a 1Password fill names its own
+ * allowed origins, and a model choosing them would defeat the origin check.
+ * Applications call `sessions.credentials.fill` directly for 1Password.
+ */
+export declare class CredentialFillTool {
+    static openaiToolDefinition: import("./openai").ChatCompletionTool;
+    static anthropicToolDefinition: import("./anthropic").Tool;
+    static geminiToolDefinition: {
+        name: string;
+        description: string;
+        parameters: {
+            type: string;
+            properties: {
+                credential: {
+                    type: string;
+                    nullable: boolean;
+                    description: string;
+                };
+                vault: {
+                    type: string;
+                    nullable: boolean;
+                    description: string;
+                };
+                fields: {
+                    type: string;
+                    description: string;
+                    minItems: string;
+                    maxItems: string;
+                    items: {
+                        type: string;
+                        properties: {
+                            selector: {
+                                type: string;
+                                description: string;
+                            };
+                            field: {
+                                type: string;
+                                nullable: boolean;
+                                description: string;
+                            };
+                        };
+                        required: string[];
+                    };
+                };
+                page_id: {
+                    type: string;
+                    nullable: boolean;
+                    description: string;
+                };
+                page_url: {
+                    type: string;
+                    nullable: boolean;
+                    description: string;
+                };
+                frame_url: {
+                    type: string;
+                    nullable: boolean;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+    };
+    /**
+     * Run a `fill_credential` call in `sessionId` and return the result as JSON
+     * text for the model. API and validation errors come back as
+     * `{"error": {"code", "message", "retryable", "details"}}` rather than
+     * being thrown, so the model can react to them.
+     */
+    static runnable(hb: HyperbrowserClient, sessionId: string, params: CredentialFillToolParams): Promise<string>;
+}

package/dist/tools/index.js

@@ -1,8 +1,33 @@
 "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.OpenAICuaTool = exports.ClaudeComputerUseTool = exports.BrowserUseTool = exports.WebsiteExtractTool = exports.WebsiteCrawlTool = exports.WebsiteScreenshotTool = exports.WebsiteScrapeTool = void 0;
+exports.CredentialFillTool = exports.OpenAICuaTool = exports.ClaudeComputerUseTool = exports.BrowserUseTool = exports.WebsiteExtractTool = exports.WebsiteCrawlTool = exports.WebsiteScreenshotTool = exports.WebsiteScrapeTool = exports.FILL_CREDENTIAL_TOOL_ANTHROPIC = exports.FILL_CREDENTIAL_TOOL_OPENAI = exports.FILL_CREDENTIAL_SCHEMA = exports.FILL_CREDENTIAL_DESCRIPTION = void 0;
 const openai_1 = require("./openai");
 const anthropic_1 = require("./anthropic");
+const gemini_1 = require("./gemini");
+const client_1 = require("../client");
+const secrets_envelope_1 = require("../secrets-envelope");
+var schema_1 = require("./schema");
+Object.defineProperty(exports, "FILL_CREDENTIAL_DESCRIPTION", { enumerable: true, get: function () { return schema_1.FILL_CREDENTIAL_DESCRIPTION; } });
+Object.defineProperty(exports, "FILL_CREDENTIAL_SCHEMA", { enumerable: true, get: function () { return schema_1.FILL_CREDENTIAL_SCHEMA; } });
+var openai_2 = require("./openai");
+Object.defineProperty(exports, "FILL_CREDENTIAL_TOOL_OPENAI", { enumerable: true, get: function () { return openai_2.FILL_CREDENTIAL_TOOL_OPENAI; } });
+var anthropic_2 = require("./anthropic");
+Object.defineProperty(exports, "FILL_CREDENTIAL_TOOL_ANTHROPIC", { enumerable: true, get: function () { return anthropic_2.FILL_CREDENTIAL_TOOL_ANTHROPIC; } });
+__exportStar(require("./gemini"), exports);
 class WebsiteScrapeTool {
     static async runnable(hb, params) {
         const resp = await hb.scrape.startAndWait(params);
@@ -77,3 +102,58 @@ class OpenAICuaTool {
 exports.OpenAICuaTool = OpenAICuaTool;
 OpenAICuaTool.openaiToolDefinition = openai_1.OPENAI_CUA_TOOL_OPENAI;
 OpenAICuaTool.anthropicToolDefinition = anthropic_1.OPENAI_CUA_TOOL_ANTHROPIC;
+/**
+ * Lets a model fill a secret, or a vault's entries, attached to a browser
+ * session. The application binds the session; the model chooses only names,
+ * selectors and which tab, and never sees values.
+ *
+ * It deliberately has no `onePassword`: a 1Password fill names its own
+ * allowed origins, and a model choosing them would defeat the origin check.
+ * Applications call `sessions.credentials.fill` directly for 1Password.
+ */
+class CredentialFillTool {
+    /**
+     * Run a `fill_credential` call in `sessionId` and return the result as JSON
+     * text for the model. API and validation errors come back as
+     * `{"error": {"code", "message", "retryable", "details"}}` rather than
+     * being thrown, so the model can react to them.
+     */
+    static async runnable(hb, sessionId, params) {
+        try {
+            // Model output is checked by fill; only the known keys are passed on.
+            // Null (strict mode's "not given") and "" (what Gemini tends to send
+            // for unused strings) are left out.
+            const input = (0, secrets_envelope_1.isPlainObject)(params) ? params : {};
+            const given = (value) => value === null || value === "" ? undefined : value;
+            const request = {
+                credential: given(input.credential),
+                vault: given(input.vault),
+                fields: (Array.isArray(input.fields)
+                    ? input.fields.map((entry) => (0, secrets_envelope_1.isPlainObject)(entry) ? { selector: entry.selector, field: given(entry.field) } : entry)
+                    : input.fields),
+                pageId: given(input.page_id),
+                pageUrl: given(input.page_url),
+                frameUrl: given(input.frame_url),
+            };
+            return JSON.stringify(await hb.sessions.credentials.fill(sessionId, request));
+        }
+        catch (error) {
+            if (!(error instanceof client_1.HyperbrowserError)) {
+                throw error;
+            }
+            return JSON.stringify({
+                error: {
+                    code: error.code ?? null,
+                    message: error.message.replace(/^\[Hyperbrowser\]: /, ""),
+                    retryable: error.retryable,
+                    // details is the error body; the model gets the server's own details.
+                    details: (0, secrets_envelope_1.isPlainObject)(error.details) ? (error.details.details ?? null) : null,
+                },
+            });
+        }
+    }
+}
+exports.CredentialFillTool = CredentialFillTool;
+CredentialFillTool.openaiToolDefinition = openai_1.FILL_CREDENTIAL_TOOL_OPENAI;
+CredentialFillTool.anthropicToolDefinition = anthropic_1.FILL_CREDENTIAL_TOOL_ANTHROPIC;
+CredentialFillTool.geminiToolDefinition = gemini_1.FILL_CREDENTIAL_TOOL_GEMINI;

package/dist/tools/openai.d.ts

@@ -43,3 +43,4 @@ export declare const EXTRACT_TOOL_OPENAI: ChatCompletionTool;
 export declare const BROWSER_USE_TOOL_OPENAI: ChatCompletionTool;
 export declare const CLAUDE_COMPUTER_USE_TOOL_OPENAI: ChatCompletionTool;
 export declare const OPENAI_CUA_TOOL_OPENAI: ChatCompletionTool;
+export declare const FILL_CREDENTIAL_TOOL_OPENAI: ChatCompletionTool;

package/dist/tools/openai.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OPENAI_CUA_TOOL_OPENAI = exports.CLAUDE_COMPUTER_USE_TOOL_OPENAI = exports.BROWSER_USE_TOOL_OPENAI = exports.EXTRACT_TOOL_OPENAI = exports.CRAWL_TOOL_OPENAI = exports.SCREENSHOT_TOOL_OPENAI = exports.SCRAPE_TOOL_OPENAI = void 0;
+exports.FILL_CREDENTIAL_TOOL_OPENAI = exports.OPENAI_CUA_TOOL_OPENAI = exports.CLAUDE_COMPUTER_USE_TOOL_OPENAI = exports.BROWSER_USE_TOOL_OPENAI = exports.EXTRACT_TOOL_OPENAI = exports.CRAWL_TOOL_OPENAI = exports.SCREENSHOT_TOOL_OPENAI = exports.SCRAPE_TOOL_OPENAI = void 0;
 const schema_1 = require("./schema");
 exports.SCRAPE_TOOL_OPENAI = {
     type: "function",
@@ -65,3 +65,12 @@ exports.OPENAI_CUA_TOOL_OPENAI = {
         strict: true,
     },
 };
+exports.FILL_CREDENTIAL_TOOL_OPENAI = {
+    type: "function",
+    function: {
+        name: "fill_credential",
+        description: schema_1.FILL_CREDENTIAL_DESCRIPTION,
+        parameters: schema_1.FILL_CREDENTIAL_SCHEMA,
+        strict: true,
+    },
+};

package/dist/tools/schema.d.ts

@@ -266,3 +266,52 @@ export declare const OPENAI_CUA_SCHEMA: {
     required: string[];
     additionalProperties: boolean;
 };
+export declare const FILL_CREDENTIAL_DESCRIPTION = "Fill stored login details into inputs on the browser session's page. You never see the values: you name what to fill and give a CSS selector for each input. Pass exactly one of:\n- credential: the name of one stored secret, such as a password. Each field is just {\"selector\"}.\n- vault: the name of a vault that groups a login's secrets under entry names such as USERNAME, PASSWORD or OTP. Each field is {\"selector\", \"field\"}, where field is the entry to type into that input. A one-time-code (TOTP) entry types the code that is current at the moment of the fill.\n\nThis tool only types. It does NOT submit the form: after a fill, click the login or submit button, or press Enter, with your other browser tools. For logins split over several screens (for example the username first, then the password), fill the inputs on the current screen, submit, and fill the rest on the next screen. Calling it again is safe; it replaces what is in the inputs.\n\nOn success it returns JSON with an outcome per input:\n- \"filled\": the input now holds the value.\n- \"not_found\": no input matched the selector. Look at the page again and use a selector that matches the input.\n- \"ambiguous\": several visible inputs matched. Use a more specific selector that matches exactly one.\n- \"not_editable\": the element is disabled, read-only, hidden or not a text input. Select the actual visible input, or wait until it becomes editable.\n- \"not_accepted\": the page did not keep the value (for example a length limit, or a script cleared it). Check the form, and tell the user if it keeps happening.\nSubmit only once every input you need is \"filled\".\n\nOn failure it returns JSON {\"error\": {\"code\", \"message\", \"retryable\", \"details\"}}. If the code is CREDENTIAL_PAGE_AMBIGUOUS, several tabs could be the target: call again with page_id set to the pageId of the tab with the login form from details.pages, or with page_url set to the start of that tab's URL. CREDENTIAL_ORIGIN_NOT_ALLOWED means these details may not be used on the current site; nothing was typed, so do not try to work around it, and tell the user. CREDENTIAL_NOT_ATTACHED, SECRET_NOT_FOUND, VAULT_NOT_FOUND and VAULT_ENTRY_NOT_FOUND mean the name is wrong or was not made available to this session; use a name you were given. CREDENTIAL_FRAME_NOT_FOUND means no iframe matched frame_url. If retryable is true, you may try the same call again.";
+export declare const FILL_CREDENTIAL_SCHEMA: {
+    type: "object";
+    properties: {
+        credential: {
+            type: string[];
+            description: string;
+        };
+        vault: {
+            type: string[];
+            description: string;
+        };
+        fields: {
+            type: string;
+            description: string;
+            minItems: number;
+            maxItems: number;
+            items: {
+                type: string;
+                properties: {
+                    selector: {
+                        type: string;
+                        description: string;
+                    };
+                    field: {
+                        type: string[];
+                        description: string;
+                    };
+                };
+                required: string[];
+                additionalProperties: boolean;
+            };
+        };
+        page_id: {
+            type: string[];
+            description: string;
+        };
+        page_url: {
+            type: string[];
+            description: string;
+        };
+        frame_url: {
+            type: string[];
+            description: string;
+        };
+    };
+    required: string[];
+    additionalProperties: boolean;
+};

package/dist/tools/schema.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OPENAI_CUA_SCHEMA = exports.CLAUDE_COMPUTER_USE_SCHEMA = exports.BROWSER_USE_SCHEMA = exports.EXTRACT_SCHEMA = exports.CRAWL_SCHEMA = exports.SCREENSHOT_SCHEMA = exports.SCRAPE_SCHEMA = exports.CLAUDE_COMPUTER_USE_DESCRIPTION = exports.OPENAI_CUA_DESCRIPTION = void 0;
+exports.FILL_CREDENTIAL_SCHEMA = exports.FILL_CREDENTIAL_DESCRIPTION = exports.OPENAI_CUA_SCHEMA = exports.CLAUDE_COMPUTER_USE_SCHEMA = exports.BROWSER_USE_SCHEMA = exports.EXTRACT_SCHEMA = exports.CRAWL_SCHEMA = exports.SCREENSHOT_SCHEMA = exports.SCRAPE_SCHEMA = exports.CLAUDE_COMPUTER_USE_DESCRIPTION = exports.OPENAI_CUA_DESCRIPTION = void 0;
 exports.OPENAI_CUA_DESCRIPTION = `This tool utilizes OpenAI's model to autonomously execute general-purpose browser-based tasks with balanced performance and reliability using a cloud browser. It handles complex interactions effectively with practical reasoning and clear execution.
 
 Optimal for tasks requiring:
@@ -179,9 +179,9 @@ const BROWSER_USE_LLM_SCHEMA = {
     enum: [
         "gpt-4o",
         "gpt-4o-mini",
-        "claude-3-7-sonnet-20250219",
-        "claude-3-5-sonnet-20241022",
-        "claude-3-5-haiku-20241022",
+        "claude-sonnet-5",
+        "claude-sonnet-4-6",
+        "claude-haiku-5-5",
         "gemini-2.0-flash",
         "gemini-3.8-flash",
     ],
@@ -238,3 +238,52 @@ exports.OPENAI_CUA_SCHEMA = {
     required: ["task", "sessionOptions"],
     additionalProperties: false,
 };
+exports.FILL_CREDENTIAL_DESCRIPTION = `Fill stored login details into inputs on the browser session's page. You never see the values: you name what to fill and give a CSS selector for each input. Pass exactly one of:
+- credential: the name of one stored secret, such as a password. Each field is just {"selector"}.
+- vault: the name of a vault that groups a login's secrets under entry names such as USERNAME, PASSWORD or OTP. Each field is {"selector", "field"}, where field is the entry to type into that input. A one-time-code (TOTP) entry types the code that is current at the moment of the fill.
+
+This tool only types. It does NOT submit the form: after a fill, click the login or submit button, or press Enter, with your other browser tools. For logins split over several screens (for example the username first, then the password), fill the inputs on the current screen, submit, and fill the rest on the next screen. Calling it again is safe; it replaces what is in the inputs.
+
+On success it returns JSON with an outcome per input:
+- "filled": the input now holds the value.
+- "not_found": no input matched the selector. Look at the page again and use a selector that matches the input.
+- "ambiguous": several visible inputs matched. Use a more specific selector that matches exactly one.
+- "not_editable": the element is disabled, read-only, hidden or not a text input. Select the actual visible input, or wait until it becomes editable.
+- "not_accepted": the page did not keep the value (for example a length limit, or a script cleared it). Check the form, and tell the user if it keeps happening.
+Submit only once every input you need is "filled".
+
+On failure it returns JSON {"error": {"code", "message", "retryable", "details"}}. If the code is CREDENTIAL_PAGE_AMBIGUOUS, several tabs could be the target: call again with page_id set to the pageId of the tab with the login form from details.pages, or with page_url set to the start of that tab's URL. CREDENTIAL_ORIGIN_NOT_ALLOWED means these details may not be used on the current site; nothing was typed, so do not try to work around it, and tell the user. CREDENTIAL_NOT_ATTACHED, SECRET_NOT_FOUND, VAULT_NOT_FOUND and VAULT_ENTRY_NOT_FOUND mean the name is wrong or was not made available to this session; use a name you were given. CREDENTIAL_FRAME_NOT_FOUND means no iframe matched frame_url. If retryable is true, you may try the same call again.`;
+const nullableString = (description) => ({
+    type: ["string", "null"],
+    description,
+});
+exports.FILL_CREDENTIAL_SCHEMA = {
+    type: "object",
+    properties: {
+        credential: nullableString('Name of a stored secret to type, for example "github-password". Null when you pass vault.'),
+        vault: nullableString('Name of a vault whose entries to type, for example "github-login". Null when you pass credential.'),
+        fields: {
+            type: "array",
+            description: "The inputs to fill on the page, each listed once: one entry per input, at most 16.",
+            minItems: 1,
+            maxItems: 16,
+            items: {
+                type: "object",
+                properties: {
+                    selector: {
+                        type: "string",
+                        description: 'CSS selector for the input to type into, matching exactly one visible input, for example "#login_field" or "input[name=password]".',
+                    },
+                    field: nullableString('With vault: the entry to type into this input, such as "USERNAME", "PASSWORD" or "OTP". Null with credential.'),
+                },
+                required: ["selector", "field"],
+                additionalProperties: false,
+            },
+        },
+        page_id: nullableString("Usually null. Set it only after a call failed with CREDENTIAL_PAGE_AMBIGUOUS because several tabs could be the target: the pageId of the tab with the login form, from that error's details.pages. Not with page_url."),
+        page_url: nullableString('Usually null. Instead of page_id, the URL (or the start of it) of the tab to fill, for example "https://github.com/login". Not with page_id.'),
+        frame_url: nullableString('Null unless the login form is inside an iframe. Then the URL of that iframe, or the start of it, for example "https://accounts.example.com/login".'),
+    },
+    required: ["credential", "vault", "fields", "page_id", "page_url", "frame_url"],
+    additionalProperties: false,
+};

package/dist/types/constants.d.ts

@@ -1,4 +1,4 @@
-export type SessionEventLogType = "captcha_detected" | "captcha_solved" | "captcha_error" | "file_downloaded";
+export type SessionEventLogType = "captcha_detected" | "captcha_solved" | "captcha_error" | "file_downloaded" | "tab_opened" | "credential_filled" | "credential_fill_refused";
 export type ScrapeFormat = "markdown" | "html" | "links" | "screenshot";
 export type ScrapeJobStatus = "pending" | "running" | "completed" | "failed";
 export type ExtractJobStatus = "pending" | "running" | "completed" | "failed";
@@ -19,13 +19,35 @@ export type RecordingStatus = "not_enabled" | "pending" | "in_progress" | "compl
 export type DownloadsStatus = "not_enabled" | "pending" | "in_progress" | "completed" | "failed";
 export declare const POLLING_ATTEMPTS = 5;
 export type BrowserUseVersion = "0.1.40" | "0.7.10" | "latest";
-export type BrowserUseLlm = "gpt-4o" | "gpt-4o-mini" | "gpt-4.1" | "gpt-4.1-mini" | "gpt-5" | "gpt-5-mini" | "claude-sonnet-5" | "claude-sonnet-4-5" | "claude-sonnet-4-6" | "claude-haiku-5-5" | "claude-sonnet-4-20250514" | "claude-3-7-sonnet-20250219" | "claude-3-5-sonnet-20241022" | "claude-3-5-haiku-20241022" | "gemini-2.0-flash" | "gemini-2.5-flash" | "gemini-3.8-flash";
-export type ClaudeComputerUseLlm = "claude-opus-5-5" | "claude-fable-5-1" | "claude-opus-5" | "claude-opus-4-5" | "claude-opus-4-6" | "claude-opus-4-7" | "claude-opus-4-8" | "claude-haiku-5-5" | "claude-haiku-4-5-20251001" | "claude-sonnet-5-5" | "claude-sonnet-5" | "claude-sonnet-4-5" | "claude-sonnet-4-6" | "claude-sonnet-4-20250514" | "claude-3-7-sonnet-20250219";
+export type BrowserUseLlm = "gpt-4o" | "gpt-4o-mini" | "gpt-4.1" | "gpt-4.1-mini" | "gpt-5" | "gpt-5-mini" | "claude-sonnet-5" | "claude-sonnet-4-6" | "claude-haiku-5-5"
+/** @deprecated Retires November 30, 2026; use "claude-sonnet-5". */
+ | "claude-sonnet-4-5"
+/** @deprecated Retired; the API maps this to "claude-sonnet-5". */
+ | "claude-sonnet-4-20250514"
+/** @deprecated Retired; the API maps this to "claude-sonnet-5". */
+ | "claude-3-7-sonnet-20250219"
+/** @deprecated Retired; the API maps this to "claude-sonnet-5". */
+ | "claude-3-5-sonnet-20241022"
+/** @deprecated Retired; the API maps this to "claude-sonnet-5". */
+ | "claude-3-5-haiku-20241022" | "gemini-2.0-flash" | "gemini-2.5-flash" | "gemini-3.8-flash";
+export type ClaudeComputerUseLlm = "claude-opus-5-5" | "claude-fable-5-1" | "claude-opus-5" | "claude-opus-4-8" | "claude-opus-4-7" | "claude-opus-4-6" | "claude-opus-4-5" | "claude-sonnet-5-5" | "claude-sonnet-5" | "claude-sonnet-4-6" | "claude-haiku-5-5" | "claude-haiku-4-5-20251001"
+/** @deprecated Retires November 30, 2026; use "claude-sonnet-5-5". */
+ | "claude-sonnet-4-5"
+/** @deprecated Retired; the API maps this to "claude-sonnet-4-6". */
+ | "claude-sonnet-4-20250514"
+/** @deprecated Retired; the API maps this to "claude-sonnet-4-6". */
+ | "claude-3-7-sonnet-20250219"
+/** @deprecated Retired; the API maps this to "claude-opus-4-8". */
+ | "claude-opus-4-20250514"
+/** @deprecated Retired legacy ID; the API maps this to "claude-opus-4-8". */
+ | "claude-4-opus-20250514";
 export type ClaudeComputerUseReasoningEffort = "low" | "medium" | "high" | "xhigh" | "max";
 export type CuaLlm = "computer-use-preview" | "gpt-6-astra" | "gpt-6.1-sol" | "gpt-6-sol" | "gpt-6-luna" | "gpt-5.6-sol" | "gpt-5.6-terra" | "gpt-5.6-luna" | "gpt-5.5" | "gpt-5.4" | "gpt-5.4-mini";
 export type CuaReasoningEffort = "none" | "low" | "medium" | "high" | "xhigh" | "max";
 export type HyperAgentVersion = "0.8.0" | "1.1.0";
-export type HyperAgentLlm = "gpt-5.6-luna" | "gpt-5.5" | "gpt-5.2" | "gpt-5.1" | "gpt-5" | "gpt-5-mini" | "gpt-4o" | "gpt-4o-mini" | "gpt-4.1" | "gpt-4.1-mini" | "gpt-4.1-nano" | "claude-sonnet-5" | "claude-sonnet-4-5" | "claude-sonnet-4-6" | "claude-haiku-5-5" | "gemini-2.5-flash" | "gemini-3.8-flash" | "gemini-3.7-flash" | "gemini-3-flash-preview";
+export type HyperAgentLlm = "gpt-6-luna" | "gpt-5.6-luna" | "gpt-5.5" | "gpt-5.2" | "gpt-5.1" | "gpt-5" | "gpt-5-mini" | "gpt-4o" | "gpt-4o-mini" | "gpt-4.1" | "gpt-4.1-mini" | "gpt-4.1-nano" | "claude-sonnet-5" | "claude-sonnet-4-6" | "claude-haiku-5-5"
+/** @deprecated Retires November 30, 2026; use "claude-sonnet-5". */
+ | "claude-sonnet-4-5" | "gemini-2.5-flash" | "gemini-3.8-flash" | "gemini-3.7-flash" | "gemini-3-flash-preview";
 export type GeminiComputerUseLlm = "gemini-4-argon" | "gemini-3.8-flash" | "gemini-3.7-flash" | "gemini-3.6-flash" | "gemini-3.5-flash" | "gemini-3.5-flash-lite" | "gemini-3-flash-preview" | "gemini-2.5-computer-use-preview-10-2025";
 export type GeminiComputerUseReasoningEffort = "minimal" | "low" | "medium" | "high";
 export type GrokComputerUseLlm = "grok-4.7" | "grok-4.6" | "grok-4.5";