@browserbasehq/convex-stagehand 0.0.1

package/dist/component/_generated/server.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+import type { ActionBuilder, HttpActionBuilder, MutationBuilder, QueryBuilder, GenericActionCtx, GenericMutationCtx, GenericQueryCtx, GenericDatabaseReader, GenericDatabaseWriter } from "convex/server";
+import type { DataModel } from "./dataModel.js";
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export declare const query: QueryBuilder<DataModel, "public">;
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export declare const internalQuery: QueryBuilder<DataModel, "internal">;
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export declare const mutation: MutationBuilder<DataModel, "public">;
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export declare const internalMutation: MutationBuilder<DataModel, "internal">;
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export declare const action: ActionBuilder<DataModel, "public">;
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export declare const internalAction: ActionBuilder<DataModel, "internal">;
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export declare const httpAction: HttpActionBuilder;
+/**
+ * A set of services for use within Convex query functions.
+ *
+ * The query context is passed as the first argument to any Convex query
+ * function run on the server.
+ *
+ * If you're using code generation, use the `QueryCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type QueryCtx = GenericQueryCtx<DataModel>;
+/**
+ * A set of services for use within Convex mutation functions.
+ *
+ * The mutation context is passed as the first argument to any Convex mutation
+ * function run on the server.
+ *
+ * If you're using code generation, use the `MutationCtx` type in `convex/_generated/server.d.ts` instead.
+ */
+export type MutationCtx = GenericMutationCtx<DataModel>;
+/**
+ * A set of services for use within Convex action functions.
+ *
+ * The action context is passed as the first argument to any Convex action
+ * function run on the server.
+ */
+export type ActionCtx = GenericActionCtx<DataModel>;
+/**
+ * An interface to read from the database within Convex query functions.
+ *
+ * The two entry points are {@link DatabaseReader.get}, which fetches a single
+ * document by its {@link Id}, or {@link DatabaseReader.query}, which starts
+ * building a query.
+ */
+export type DatabaseReader = GenericDatabaseReader<DataModel>;
+/**
+ * An interface to read from and write to the database within Convex mutation
+ * functions.
+ *
+ * Convex guarantees that all writes within a single mutation are
+ * executed atomically, so you never have to worry about partial writes leaving
+ * your data in an inconsistent state. See [the Convex Guide](https://docs.convex.dev/understanding/convex-fundamentals/functions#atomicity-and-optimistic-concurrency-control)
+ * for the guarantees Convex provides your functions.
+ */
+export type DatabaseWriter = GenericDatabaseWriter<DataModel>;
+//# sourceMappingURL=server.d.ts.map

package/dist/component/_generated/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../../src/component/_generated/server.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,YAAY,EACZ,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,qBAAqB,EACrB,qBAAqB,EACtB,MAAM,eAAe,CAAC;AAUvB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD;;;;;;;GAOG;AACH,eAAO,MAAM,KAAK,EAAE,YAAY,CAAC,SAAS,EAAE,QAAQ,CAAgB,CAAC;AAErE;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa,EAAE,YAAY,CAAC,SAAS,EAAE,UAAU,CACxC,CAAC;AAEvB;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,EAAE,eAAe,CAAC,SAAS,EAAE,QAAQ,CAAmB,CAAC;AAE9E;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,eAAe,CAAC,SAAS,EAAE,UAAU,CAC3C,CAAC;AAE1B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,MAAM,EAAE,aAAa,CAAC,SAAS,EAAE,QAAQ,CAAiB,CAAC;AAExE;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,aAAa,CAAC,SAAS,EAAE,UAAU,CACzC,CAAC;AAExB;;;;;;;;;;GAUG;AACH,eAAO,MAAM,UAAU,EAAE,iBAAqC,CAAC;AAE/D;;;;;;;GAOG;AACH,MAAM,MAAM,QAAQ,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;AAElD;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,kBAAkB,CAAC,SAAS,CAAC,CAAC;AAExD;;;;;GAKG;AACH,MAAM,MAAM,SAAS,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC;AAE9D;;;;;;;;GAQG;AACH,MAAM,MAAM,cAAc,GAAG,qBAAqB,CAAC,SAAS,CAAC,CAAC"}

package/dist/component/_generated/server.js

@@ -0,0 +1,78 @@
+/* eslint-disable */
+/**
+ * Generated utilities for implementing server-side Convex query and mutation functions.
+ *
+ * THIS CODE IS AUTOMATICALLY GENERATED.
+ *
+ * To regenerate, run `npx convex dev`.
+ * @module
+ */
+import { actionGeneric, httpActionGeneric, queryGeneric, mutationGeneric, internalActionGeneric, internalMutationGeneric, internalQueryGeneric, } from "convex/server";
+/**
+ * Define a query in this Convex app's public API.
+ *
+ * This function will be allowed to read your Convex database and will be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const query = queryGeneric;
+/**
+ * Define a query that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to read from your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The query function. It receives a {@link QueryCtx} as its first argument.
+ * @returns The wrapped query. Include this as an `export` to name it and make it accessible.
+ */
+export const internalQuery = internalQueryGeneric;
+/**
+ * Define a mutation in this Convex app's public API.
+ *
+ * This function will be allowed to modify your Convex database and will be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const mutation = mutationGeneric;
+/**
+ * Define a mutation that is only accessible from other Convex functions (but not from the client).
+ *
+ * This function will be allowed to modify your Convex database. It will not be accessible from the client.
+ *
+ * @param func - The mutation function. It receives a {@link MutationCtx} as its first argument.
+ * @returns The wrapped mutation. Include this as an `export` to name it and make it accessible.
+ */
+export const internalMutation = internalMutationGeneric;
+/**
+ * Define an action in this Convex app's public API.
+ *
+ * An action is a function which can execute any JavaScript code, including non-deterministic
+ * code and code with side-effects, like calling third-party services.
+ * They can be run in Convex's JavaScript environment or in Node.js using the "use node" directive.
+ * They can interact with the database indirectly by calling queries and mutations using the {@link ActionCtx}.
+ *
+ * @param func - The action. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped action. Include this as an `export` to name it and make it accessible.
+ */
+export const action = actionGeneric;
+/**
+ * Define an action that is only accessible from other Convex functions (but not from the client).
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument.
+ * @returns The wrapped function. Include this as an `export` to name it and make it accessible.
+ */
+export const internalAction = internalActionGeneric;
+/**
+ * Define an HTTP action.
+ *
+ * The wrapped function will be used to respond to HTTP requests received
+ * by a Convex deployment if the requests matches the path and method where
+ * this action is routed. Be sure to route your httpAction in `convex/http.js`.
+ *
+ * @param func - The function. It receives an {@link ActionCtx} as its first argument
+ * and a Fetch API `Request` object as its second.
+ * @returns The wrapped function. Import this function from `convex/http.js` and route it to hook it up.
+ */
+export const httpAction = httpActionGeneric;
+//# sourceMappingURL=server.js.map

package/dist/component/_generated/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/component/_generated/server.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB;;;;;;;GAOG;AAaH,OAAO,EACL,aAAa,EACb,iBAAiB,EACjB,YAAY,EACZ,eAAe,EACf,qBAAqB,EACrB,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,eAAe,CAAC;AAGvB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,KAAK,GAAsC,YAAY,CAAC;AAErE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GACxB,oBAAoB,CAAC;AAEvB;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,QAAQ,GAAyC,eAAe,CAAC;AAE9E;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAC3B,uBAAuB,CAAC;AAE1B;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,MAAM,GAAuC,aAAa,CAAC;AAExE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GACzB,qBAAqB,CAAC;AAExB;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,UAAU,GAAsB,iBAAiB,CAAC"}

package/dist/component/api.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Stagehand REST API Client
+ *
+ * Wraps the Stagehand API at https://api.stagehand.browserbase.com
+ */
+export interface ApiConfig {
+    browserbaseApiKey: string;
+    browserbaseProjectId: string;
+    modelApiKey: string;
+    modelName?: string;
+}
+export interface SessionData {
+    sessionId: string;
+    browserbaseSessionId?: string;
+    cdpUrl?: string;
+    available: boolean;
+}
+export interface StartSessionOptions {
+    browserbaseSessionId?: string;
+    domSettleTimeoutMs?: number;
+    selfHeal?: boolean;
+    systemPrompt?: string;
+}
+export interface ApiResponse<T> {
+    data: T;
+    success: boolean;
+}
+export declare function startSession(config: ApiConfig, options?: StartSessionOptions): Promise<SessionData>;
+export declare function endSession(sessionId: string, config: ApiConfig): Promise<void>;
+export interface NavigateOptions {
+    waitUntil?: "load" | "domcontentloaded" | "networkidle";
+    timeout?: number;
+}
+export declare function navigate(sessionId: string, url: string, config: ApiConfig, options?: NavigateOptions): Promise<void>;
+export interface ExtractResult<T = any> {
+    result: T;
+    actionId: string;
+}
+export declare function extract(sessionId: string, instruction: string, schema: any, config: ApiConfig): Promise<ExtractResult>;
+export interface ActResult {
+    result: {
+        actionDescription: string;
+        actions: Array<{
+            description: string;
+            selector: string;
+            arguments?: string[];
+            method: string;
+        }>;
+        message: string;
+        success: boolean;
+    };
+    actionId: string;
+}
+export declare function act(sessionId: string, action: string, config: ApiConfig): Promise<ActResult>;
+export interface ObserveResult {
+    result: Array<{
+        description: string;
+        selector: string;
+        arguments?: string[];
+        backendNodeId?: number;
+        method: string;
+    }>;
+    actionId: string;
+}
+export declare function observe(sessionId: string, instruction: string, config: ApiConfig): Promise<ObserveResult>;
+export interface AgentConfig {
+    cua?: boolean;
+    model?: string;
+    systemPrompt?: string;
+}
+export interface AgentExecuteOptions {
+    instruction: string;
+    maxSteps?: number;
+}
+export interface AgentAction {
+    type: string;
+    action?: string;
+    reasoning?: string;
+    timeMs?: number;
+}
+export interface AgentExecuteResult {
+    result: {
+        actions: AgentAction[];
+        completed: boolean;
+        message: string;
+        success: boolean;
+    };
+}
+export declare function agentExecute(sessionId: string, agentConfig: AgentConfig, executeOptions: AgentExecuteOptions, config: ApiConfig): Promise<AgentExecuteResult>;
+//# sourceMappingURL=api.d.ts.map

package/dist/component/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/component/api.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,WAAW,SAAS;IACxB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,oBAAoB,EAAE,MAAM,CAAC;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,mBAAmB;IAClC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,WAAW,CAAC,CAAC;IAC5B,IAAI,EAAE,CAAC,CAAC;IACR,OAAO,EAAE,OAAO,CAAC;CAClB;AAyBD,wBAAsB,YAAY,CAChC,MAAM,EAAE,SAAS,EACjB,OAAO,CAAC,EAAE,mBAAmB,GAC5B,OAAO,CAAC,WAAW,CAAC,CAatB;AAED,wBAAsB,UAAU,CAC9B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,IAAI,CAAC,CASf;AAED,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,EAAE,MAAM,GAAG,kBAAkB,GAAG,aAAa,CAAC;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,QAAQ,CAC5B,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,EACX,MAAM,EAAE,SAAS,EACjB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,IAAI,CAAC,CAaf;AAED,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,GAAG;IACpC,MAAM,EAAE,CAAC,CAAC;IACV,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,OAAO,CAC3B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,GAAG,EACX,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,aAAa,CAAC,CAUxB;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE;QACN,iBAAiB,EAAE,MAAM,CAAC;QAC1B,OAAO,EAAE,KAAK,CAAC;YACb,WAAW,EAAE,MAAM,CAAC;YACpB,QAAQ,EAAE,MAAM,CAAC;YACjB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;YACrB,MAAM,EAAE,MAAM,CAAC;SAChB,CAAC,CAAC;QACH,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,OAAO,CAAC;KAClB,CAAC;IACF,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,GAAG,CACvB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,SAAS,CAAC,CASpB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,KAAK,CAAC;QACZ,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,CAAC;QACjB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;QACrB,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC,CAAC;IACH,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,wBAAsB,OAAO,CAC3B,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,aAAa,CAAC,CASxB;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE;QACN,OAAO,EAAE,WAAW,EAAE,CAAC;QACvB,SAAS,EAAE,OAAO,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE,OAAO,CAAC;KAClB,CAAC;CACH;AAED,wBAAsB,YAAY,CAChC,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,WAAW,EACxB,cAAc,EAAE,mBAAmB,EACnC,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,kBAAkB,CAAC,CAkB7B"}

package/dist/component/api.js

@@ -0,0 +1,112 @@
+/**
+ * Stagehand REST API Client
+ *
+ * Wraps the Stagehand API at https://api.stagehand.browserbase.com
+ */
+const API_BASE = "https://api.stagehand.browserbase.com/v1";
+function getHeaders(config) {
+    return {
+        "Content-Type": "application/json",
+        "x-bb-api-key": config.browserbaseApiKey,
+        "x-bb-project-id": config.browserbaseProjectId,
+        "x-model-api-key": config.modelApiKey,
+    };
+}
+async function handleResponse(response) {
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`Stagehand API error (${response.status}): ${errorText}`);
+    }
+    const json = (await response.json());
+    if (!json.success) {
+        throw new Error(`Stagehand API returned success: false`);
+    }
+    return json.data;
+}
+export async function startSession(config, options) {
+    const response = await fetch(`${API_BASE}/sessions/start`, {
+        method: "POST",
+        headers: getHeaders(config),
+        body: JSON.stringify({
+            modelName: config.modelName || "openai/gpt-4o",
+            browserbaseSessionId: options?.browserbaseSessionId,
+            domSettleTimeoutMs: options?.domSettleTimeoutMs,
+            selfHeal: options?.selfHeal,
+            systemPrompt: options?.systemPrompt,
+        }),
+    });
+    return handleResponse(response);
+}
+export async function endSession(sessionId, config) {
+    try {
+        await fetch(`${API_BASE}/sessions/${sessionId}/end`, {
+            method: "POST",
+            headers: getHeaders(config),
+        });
+    }
+    catch {
+        // Ignore errors when ending session - best effort cleanup
+    }
+}
+export async function navigate(sessionId, url, config, options) {
+    const response = await fetch(`${API_BASE}/sessions/${sessionId}/navigate`, {
+        method: "POST",
+        headers: getHeaders(config),
+        body: JSON.stringify({
+            url,
+            options: {
+                waitUntil: options?.waitUntil || "networkidle",
+                timeout: options?.timeout,
+            },
+        }),
+    });
+    await handleResponse(response);
+}
+export async function extract(sessionId, instruction, schema, config) {
+    const response = await fetch(`${API_BASE}/sessions/${sessionId}/extract`, {
+        method: "POST",
+        headers: getHeaders(config),
+        body: JSON.stringify({
+            instruction,
+            schema,
+        }),
+    });
+    return handleResponse(response);
+}
+export async function act(sessionId, action, config) {
+    const response = await fetch(`${API_BASE}/sessions/${sessionId}/act`, {
+        method: "POST",
+        headers: getHeaders(config),
+        body: JSON.stringify({
+            input: action,
+        }),
+    });
+    return handleResponse(response);
+}
+export async function observe(sessionId, instruction, config) {
+    const response = await fetch(`${API_BASE}/sessions/${sessionId}/observe`, {
+        method: "POST",
+        headers: getHeaders(config),
+        body: JSON.stringify({
+            instruction,
+        }),
+    });
+    return handleResponse(response);
+}
+export async function agentExecute(sessionId, agentConfig, executeOptions, config) {
+    const response = await fetch(`${API_BASE}/sessions/${sessionId}/agent/execute`, {
+        method: "POST",
+        headers: getHeaders(config),
+        body: JSON.stringify({
+            agentConfig: {
+                cua: agentConfig.cua,
+                model: agentConfig.model,
+                systemPrompt: agentConfig.systemPrompt,
+            },
+            instruction: executeOptions.instruction,
+            maxSteps: executeOptions.maxSteps,
+        }),
+    });
+    return handleResponse(response);
+}
+//# sourceMappingURL=api.js.map

package/dist/component/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/component/api.ts"],"names":[],"mappings":"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"}

package/dist/component/convex.config.d.ts

@@ -0,0 +1,3 @@
+declare const _default: import("convex/server").ComponentDefinition<any>;
+export default _default;
+//# sourceMappingURL=convex.config.d.ts.map

package/dist/component/convex.config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"convex.config.d.ts","sourceRoot":"","sources":["../../src/component/convex.config.ts"],"names":[],"mappings":";AAEA,wBAA4C"}

package/dist/component/convex.config.js

@@ -0,0 +1,3 @@
+import { defineComponent } from "convex/server";
+export default defineComponent("stagehand");
+//# sourceMappingURL=convex.config.js.map

package/dist/component/convex.config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"convex.config.js","sourceRoot":"","sources":["../../src/component/convex.config.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEhD,eAAe,eAAe,CAAC,WAAW,CAAC,CAAC"}

package/dist/component/lib.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Stagehand Component Library
+ *
+ * AI-powered browser automation actions using the Stagehand REST API.
+ * Supports both automatic session management and manual session control.
+ */
+import * as api from "./api.js";
+/**
+ * Start a new browser session.
+ * Returns session info including cdpUrl for direct Playwright/Puppeteer connection.
+ */
+export declare const startSession: import("convex/server").RegisteredAction<"public", any, Promise<{
+    sessionId: string;
+    browserbaseSessionId: string | undefined;
+    cdpUrl: string | undefined;
+}>>;
+/**
+ * End a browser session.
+ */
+export declare const endSession: import("convex/server").RegisteredAction<"public", any, Promise<{
+    success: boolean;
+}>>;
+/**
+ * Extract structured data from a web page using AI.
+ * If sessionId is provided, uses existing session (doesn't end it).
+ * Otherwise, handles full session lifecycle: start -> navigate -> extract -> end
+ */
+export declare const extract: import("convex/server").RegisteredAction<"public", any, Promise<any>>;
+/**
+ * Execute browser actions using natural language instructions.
+ * If sessionId is provided, uses existing session (doesn't end it).
+ * Otherwise, handles full session lifecycle: start -> navigate -> act -> end
+ */
+export declare const act: import("convex/server").RegisteredAction<"public", any, Promise<{
+    success: boolean;
+    message: string;
+    actionDescription: string;
+}>>;
+/**
+ * Find available actions on a web page matching an instruction.
+ * If sessionId is provided, uses existing session (doesn't end it).
+ * Otherwise, handles full session lifecycle: start -> navigate -> observe -> end
+ */
+export declare const observe: import("convex/server").RegisteredAction<"public", any, Promise<{
+    description: string;
+    selector: string;
+    method: string;
+    arguments: string[] | undefined;
+}[]>>;
+/**
+ * Execute autonomous multi-step browser automation using an AI agent.
+ * The agent interprets the instruction and decides what actions to take.
+ * If sessionId is provided, uses existing session (doesn't end it).
+ * Otherwise, handles full session lifecycle.
+ */
+export declare const agent: import("convex/server").RegisteredAction<"public", any, Promise<{
+    actions: api.AgentAction[];
+    completed: boolean;
+    message: string;
+    success: boolean;
+}>>;
+//# sourceMappingURL=lib.d.ts.map

package/dist/component/lib.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../../src/component/lib.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,GAAG,MAAM,UAAU,CAAC;AAsBhC;;;GAGG;AACH,eAAO,MAAM,YAAY;;;;GAsDvB,CAAC;AAEH;;GAEG;AACH,eAAO,MAAM,UAAU;;GAkBrB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,OAAO,uEAiElB,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,GAAG;;;;GAmEd,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,OAAO;;;;;KAgElB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,KAAK;;;;;GA8EhB,CAAC"}