@bctrl/sdk 1.0.1

package/README.md

@@ -0,0 +1,75 @@
+# @bctrl/sdk
+
+TypeScript SDK for BCTRL workspaces, browser runtimes, and browser profile automation.
+
+## Install
+
+```bash
+npm install @bctrl/sdk
+```
+
+Node 18+ is required.
+
+## Quick start
+
+```ts
+import { Bctrl } from '@bctrl/sdk';
+
+const bctrl = new Bctrl({
+  apiKey: process.env.BCTRL_API_KEY!,
+});
+
+const workspace = await bctrl.workspaces.create({
+  name: 'my-task',
+});
+
+const browser = await workspace.runtimes.browser('web').playwright({
+  launch: { mode: 'ephemeral' },
+});
+
+await browser.run({
+  steps: [
+    { call: 'page.goto', args: ['https://example.com'] },
+  ],
+});
+
+const state = await workspace.state({ runtime: 'web' });
+console.log(state.runtimes[0]?.summary);
+```
+
+The public SDK always targets `https://api.bctrl.ai/v1`.
+
+For local development inside this repo, use the internal test helper instead of changing the public client base URL:
+
+```ts
+import { createInternalBctrl } from '../src/internal/dev-client.js';
+
+const bctrl = createInternalBctrl({
+  apiKey: process.env.BCTRL_API_KEY!,
+  apiOrigin: 'http://localhost:8787',
+});
+```
+
+## Entry points
+
+- `@bctrl/sdk`: core client, workspaces, browser profiles, AI credentials, storage, vault, updates
+- `@bctrl/sdk/playwright`: Playwright driver types and remote browser classes
+- `@bctrl/sdk/puppeteer`: Puppeteer driver types and remote browser classes
+- `@bctrl/sdk/stagehand`: Stagehand driver types and remote browser classes
+- `@bctrl/sdk/selenium`: Selenium driver types and remote browser classes
+
+## Documentation
+
+- SDK reference: https://platform.bctrl.ai/api-reference/sdk/overview
+- Product site: https://bctrl.ai
+
+## Telemetry
+
+The SDK currently contains optional error telemetry, not full usage analytics.
+
+- Error reporting is Sentry-based and only activates when `SENTRY_DSN_SDK` is present at runtime.
+- It captures SDK errors such as request timeouts and failed HTTP or automation calls.
+- Sensitive headers like `authorization`, `cookie`, and internal secrets are stripped before an event is sent.
+- Pass `telemetry: false` to `new Bctrl(...)` to disable it explicitly.
+
+If you want to measure feature adoption, successful operations, or per-method usage, that is not implemented in the published SDK today. Instrument your application around SDK calls or add explicit SDK hooks before relying on package-level usage analytics.

package/dist/agents/browser-use/index.d.ts

@@ -0,0 +1 @@
+export { BrowserUseNamespace } from './namespace.js';

package/dist/agents/browser-use/index.js

@@ -0,0 +1,9 @@
+// ============================================================================
+// Browser-use Agent - Autonomous browser automation
+// ============================================================================
+//
+// This module provides the browser-use agent integration for bctrl.
+// Browser-use agents can autonomously complete tasks using natural language.
+//
+// ============================================================================
+export { BrowserUseNamespace } from './namespace.js';

package/dist/agents/browser-use/namespace.d.ts

@@ -0,0 +1,39 @@
+import type { BrowserUseAgentConfig, BrowserUseCodeAgentConfig, BrowserUseAPI, BrowserUseAgent, BrowserUseCodeAgent } from '../../contracts/browser-use.js';
+import type { RpcSender } from '../../internal/transport.js';
+/**
+ * Browser-use namespace - provides agent and codeAgent factory methods.
+ */
+export declare class BrowserUseNamespace implements BrowserUseAPI {
+    private sendRpc;
+    private getActivePageId;
+    constructor(sendRpc: RpcSender, getActivePageId: () => string | undefined);
+    /**
+     * Create a reusable agent for natural language task execution.
+     * The agent can be used multiple times with different tasks.
+     *
+     * @example
+     * const agent = session.browserUse.agent({
+     *   llm: "gpt-4o",
+     *   useVision: true,
+     *   maxSteps: 20,
+     * });
+     *
+     * // Execute multiple tasks with the same agent
+     * const result1 = await agent.execute("Search for latest AI news");
+     * const result2 = await agent.execute("Find pricing information", { maxSteps: 10 });
+     */
+    agent(config?: BrowserUseAgentConfig): BrowserUseAgent;
+    /**
+     * Create a reusable code agent for code-based automation.
+     * Code agents generate and execute code to accomplish tasks.
+     *
+     * @example
+     * const codeAgent = session.browserUse.codeAgent({
+     *   llm: "gpt-4o",
+     * });
+     *
+     * // Execute tasks with the code agent
+     * const result = await codeAgent.execute("Fill out the registration form");
+     */
+    codeAgent(config?: BrowserUseCodeAgentConfig): BrowserUseCodeAgent;
+}

package/dist/agents/browser-use/namespace.js

@@ -0,0 +1,93 @@
+// ============================================================================
+// BrowserUseNamespace - Shared Browser-use agent methods for all drivers
+// ============================================================================
+//
+// This class provides the `.browserUse` namespace on driver sessions.
+// It creates Browser-use agents that can autonomously complete tasks.
+//
+// Usage (consistent with Stagehand agent pattern):
+//   const session = await bctrl.browser('my-scraper').connect.puppeteer();
+//
+//   // Create a reusable agent with configuration
+//   const agent = session.browserUse.agent({
+//     llm: "gpt-4o",
+//     useVision: true,
+//   });
+//
+//   // Execute tasks with the agent
+//   const result = await agent.execute("Search for AI news and summarize");
+//   const result2 = await agent.execute("Find pricing information", { maxSteps: 10 });
+//
+//   // Code agent works similarly
+//   const codeAgent = session.browserUse.codeAgent({ llm: "gpt-4o" });
+//   const codeResult = await codeAgent.execute("Fill out the form with test data");
+//
+// ============================================================================
+/**
+ * Browser-use namespace - provides agent and codeAgent factory methods.
+ */
+export class BrowserUseNamespace {
+    sendRpc;
+    getActivePageId;
+    constructor(sendRpc, getActivePageId) {
+        this.sendRpc = sendRpc;
+        this.getActivePageId = getActivePageId;
+    }
+    /**
+     * Create a reusable agent for natural language task execution.
+     * The agent can be used multiple times with different tasks.
+     *
+     * @example
+     * const agent = session.browserUse.agent({
+     *   llm: "gpt-4o",
+     *   useVision: true,
+     *   maxSteps: 20,
+     * });
+     *
+     * // Execute multiple tasks with the same agent
+     * const result1 = await agent.execute("Search for latest AI news");
+     * const result2 = await agent.execute("Find pricing information", { maxSteps: 10 });
+     */
+    agent(config) {
+        const agentConfig = config || {};
+        const pageId = agentConfig.pageId || this.getActivePageId();
+        const rpc = this.sendRpc;
+        return {
+            execute: async (task, options) => {
+                const executeOptions = {
+                    task,
+                    ...(options?.maxSteps !== undefined ? { maxSteps: options.maxSteps } : {}),
+                    ...(options?.tools !== undefined ? { tools: options.tools } : {}),
+                };
+                return rpc('browserUse', 'agent.execute', [agentConfig, executeOptions], { pageId });
+            },
+        };
+    }
+    /**
+     * Create a reusable code agent for code-based automation.
+     * Code agents generate and execute code to accomplish tasks.
+     *
+     * @example
+     * const codeAgent = session.browserUse.codeAgent({
+     *   llm: "gpt-4o",
+     * });
+     *
+     * // Execute tasks with the code agent
+     * const result = await codeAgent.execute("Fill out the registration form");
+     */
+    codeAgent(config) {
+        const agentConfig = config || {};
+        const pageId = agentConfig.pageId || this.getActivePageId();
+        const rpc = this.sendRpc;
+        return {
+            execute: async (task, options) => {
+                const executeOptions = {
+                    task,
+                    ...(options?.maxSteps !== undefined ? { maxSteps: options.maxSteps } : {}),
+                    ...(options?.tools !== undefined ? { tools: options.tools } : {}),
+                };
+                return rpc('browserUse', 'codeAgent.execute', [agentConfig, executeOptions], { pageId });
+            },
+        };
+    }
+}

package/dist/agents/index.d.ts

@@ -0,0 +1,2 @@
+export { StagehandNamespace, StagehandAgent } from './stagehand/index.js';
+export { BrowserUseNamespace } from './browser-use/index.js';

package/dist/agents/index.js

@@ -0,0 +1,17 @@
+// ============================================================================
+// AI Agents - Unified AI-powered browser automation
+// ============================================================================
+//
+// This module provides all AI agent integrations for bctrl:
+//
+// - Stagehand: AI-powered browser automation with act, extract, observe
+// - Browser-use: Autonomous agents for natural language task execution
+//
+// These agents work across all drivers (Puppeteer, Playwright, Selenium, Stagehand)
+// through the `.stagehand` and `.browserUse` namespaces on sessions.
+//
+// ============================================================================
+// Stagehand AI exports
+export { StagehandNamespace, StagehandAgent } from './stagehand/index.js';
+// Browser-use exports
+export { BrowserUseNamespace } from './browser-use/index.js';

package/dist/agents/stagehand/core.d.ts

@@ -0,0 +1,93 @@
+import type { ZodType, infer as ZodInfer } from 'zod';
+import type { ActOptions, ActResult, StagehandAction, ExtractOptions, StagehandExtractResult, StagehandObserveResult, ObserveOptions, StagehandAgentConfig, StagehandAgentExecuteOptions, StagehandAgentResult, StagehandMetrics, StagehandHistoryEntry } from '../../contracts/stagehand.js';
+import type { RpcSender } from '../../internal/transport.js';
+/** Page resolver - converts driver-specific page object to pageId */
+export type PageResolver<TPage> = (page?: TPage) => string | undefined;
+/** Options with page parameter (replaces pageId for SDK usage) */
+export type WithPage<TPage, TOptions = {}> = Omit<TOptions, 'pageId'> & {
+    page?: TPage;
+};
+export type ActOptionsWithPage<TPage> = WithPage<TPage, ActOptions>;
+export type ExtractOptionsWithPage<TPage> = WithPage<TPage, ExtractOptions>;
+export type ObserveOptionsWithPage<TPage> = WithPage<TPage, ObserveOptions>;
+export type AgentExecuteOptionsWithPage<TPage> = WithPage<TPage, StagehandAgentExecuteOptions> & {
+    instruction: string;
+};
+export type AgentExecuteCallOptionsWithPage<TPage> = WithPage<TPage, Omit<StagehandAgentExecuteOptions, 'instruction'>>;
+/**
+ * Core Stagehand AI methods implementation.
+ * Generic TPage allows each driver to specify its own page type.
+ */
+export declare class StagehandCore<TPage = unknown> {
+    private sendRpc;
+    private getContextId;
+    private getActivePageId;
+    private resolvePage;
+    constructor(sendRpc: RpcSender, getContextId: () => string | undefined, getActivePageId: () => string | undefined, resolvePage: PageResolver<TPage>);
+    /** Resolve page object to pageId, falling back to active page */
+    private resolvePageId;
+    /** Strip page property from options before sending over RPC */
+    private stripPage;
+    /** Get RPC routing IDs */
+    private rpcIds;
+    /**
+     * Execute an AI action on a page.
+     * @example await session.act("click the login button", { page });
+     */
+    act(instruction: string, options?: ActOptionsWithPage<TPage>): Promise<ActResult>;
+    act(action: StagehandAction, options?: ActOptionsWithPage<TPage>): Promise<ActResult>;
+    /**
+     * Extract data from a page using AI.
+     * Supports Zod schemas for type-safe extraction.
+     *
+     * @example
+     * // Get page text
+     * const { pageText } = await session.extract({ page });
+     *
+     * // Extract with schema
+     * const schema = z.object({ title: z.string(), price: z.number() });
+     * const data = await session.extract("get product info", schema, { page });
+     * // data is typed as { title: string; price: number }
+     */
+    extract(options?: ExtractOptionsWithPage<TPage>): Promise<StagehandExtractResult<{
+        pageText: string;
+    }>>;
+    extract<T extends ZodType>(instruction: string, schema: T, options?: ExtractOptionsWithPage<TPage>): Promise<StagehandExtractResult<ZodInfer<T>>>;
+    /**
+     * Observe available actions on a page using AI.
+     * @example const actions = await session.observe("find clickable elements", { page });
+     */
+    observe(options?: ObserveOptionsWithPage<TPage>): Promise<StagehandObserveResult>;
+    observe(instruction: string, options?: ObserveOptionsWithPage<TPage>): Promise<StagehandObserveResult>;
+    /**
+     * Create a Stagehand agent for autonomous task execution.
+     * @example
+     * const agent = session.agent({ model: 'gpt-4o' });
+     * await agent.execute("Find and click the login button", { page });
+     */
+    agent(config?: StagehandAgentConfig): StagehandAgent<TPage>;
+    /**
+     * Get Stagehand usage metrics.
+     */
+    getMetrics(): Promise<StagehandMetrics>;
+    /**
+     * Get Stagehand operation history.
+     */
+    getHistory(): Promise<StagehandHistoryEntry[]>;
+}
+/**
+ * Stagehand agent for autonomous task execution.
+ */
+export declare class StagehandAgent<TPage = unknown> {
+    private sendRpc;
+    private getContextId;
+    private resolvePageId;
+    private config?;
+    constructor(sendRpc: RpcSender, getContextId: () => string | undefined, resolvePageId: (page?: TPage) => string | undefined, config?: StagehandAgentConfig | undefined);
+    /**
+     * Execute an autonomous task.
+     * @example await agent.execute("Find and book a flight to Tokyo", { page });
+     */
+    execute(instruction: string, options?: AgentExecuteCallOptionsWithPage<TPage>): Promise<StagehandAgentResult>;
+    execute(options: AgentExecuteOptionsWithPage<TPage>): Promise<StagehandAgentResult>;
+}

package/dist/agents/stagehand/core.js

@@ -0,0 +1,144 @@
+// ============================================================================
+// StagehandCore - Centralized Stagehand AI methods
+// ============================================================================
+//
+// This module provides the core implementation of Stagehand AI methods
+// (act, extract, observe, agent) that can be used by:
+//
+// 1. Stagehand browser runtime clients - expose methods directly
+// 2. StagehandNamespace - wraps the same RPC surface for other runtime clients
+//
+// The API mirrors the real Stagehand SDK where AI methods take { page } option.
+//
+// ============================================================================
+import { toJsonSchema } from '../../utils/schema.js';
+// ============================================================================
+// StagehandCore
+// ============================================================================
+/**
+ * Core Stagehand AI methods implementation.
+ * Generic TPage allows each driver to specify its own page type.
+ */
+export class StagehandCore {
+    sendRpc;
+    getContextId;
+    getActivePageId;
+    resolvePage;
+    constructor(sendRpc, getContextId, getActivePageId, resolvePage) {
+        this.sendRpc = sendRpc;
+        this.getContextId = getContextId;
+        this.getActivePageId = getActivePageId;
+        this.resolvePage = resolvePage;
+    }
+    /** Resolve page object to pageId, falling back to active page */
+    resolvePageId(page) {
+        if (page) {
+            const id = this.resolvePage(page);
+            if (id)
+                return id;
+        }
+        return this.getActivePageId();
+    }
+    /** Strip page property from options before sending over RPC */
+    stripPage(options) {
+        if (!options)
+            return undefined;
+        const { page, ...rest } = options;
+        return Object.keys(rest).length > 0 ? rest : undefined;
+    }
+    /** Get RPC routing IDs */
+    rpcIds(page) {
+        return {
+            contextId: this.getContextId(),
+            pageId: this.resolvePageId(page),
+        };
+    }
+    act(instructionOrAction, options) {
+        return this.sendRpc('stagehand', 'act', [instructionOrAction, this.stripPage(options)], this.rpcIds(options?.page));
+    }
+    extract(instructionOrOptions, schema, options) {
+        // No args or options only - extract page text
+        if (instructionOrOptions === undefined || typeof instructionOrOptions === 'object') {
+            const opts = instructionOrOptions;
+            return this.sendRpc('stagehand', 'extract', [null, null, this.stripPage(opts)], this.rpcIds(opts?.page));
+        }
+        // Instruction + schema + options
+        const jsonSchema = schema ? toJsonSchema(schema) : null;
+        return this.sendRpc('stagehand', 'extract', [instructionOrOptions, jsonSchema, this.stripPage(options)], this.rpcIds(options?.page));
+    }
+    observe(instructionOrOptions, options) {
+        // Options only
+        if (instructionOrOptions === undefined || typeof instructionOrOptions === 'object') {
+            const opts = instructionOrOptions;
+            return this.sendRpc('stagehand', 'observe', [null, this.stripPage(opts)], this.rpcIds(opts?.page));
+        }
+        // Instruction + options
+        return this.sendRpc('stagehand', 'observe', [instructionOrOptions, this.stripPage(options)], this.rpcIds(options?.page));
+    }
+    // ==========================================================================
+    // agent
+    // ==========================================================================
+    /**
+     * Create a Stagehand agent for autonomous task execution.
+     * @example
+     * const agent = session.agent({ model: 'gpt-4o' });
+     * await agent.execute("Find and click the login button", { page });
+     */
+    agent(config) {
+        return new StagehandAgent(this.sendRpc, () => this.getContextId(), (page) => this.resolvePageId(page), config);
+    }
+    // ==========================================================================
+    // Metrics & History
+    // ==========================================================================
+    /**
+     * Get Stagehand usage metrics.
+     */
+    getMetrics() {
+        return this.sendRpc('stagehand', 'getMetrics', []);
+    }
+    /**
+     * Get Stagehand operation history.
+     */
+    getHistory() {
+        return this.sendRpc('stagehand', 'getHistory', []);
+    }
+}
+// ============================================================================
+// StagehandAgent
+// ============================================================================
+/**
+ * Stagehand agent for autonomous task execution.
+ */
+export class StagehandAgent {
+    sendRpc;
+    getContextId;
+    resolvePageId;
+    config;
+    constructor(sendRpc, getContextId, resolvePageId, config) {
+        this.sendRpc = sendRpc;
+        this.getContextId = getContextId;
+        this.resolvePageId = resolvePageId;
+        this.config = config;
+    }
+    execute(instructionOrOptions, options) {
+        const isString = typeof instructionOrOptions === 'string';
+        const page = isString ? options?.page : instructionOrOptions.page;
+        // Build clean options without page
+        let cleanOptions;
+        if (isString) {
+            const { page: _, ...rest } = options ?? {};
+            cleanOptions = {
+                instruction: instructionOrOptions,
+                ...rest,
+            };
+        }
+        else {
+            const { page: _, ...rest } = instructionOrOptions;
+            cleanOptions = rest;
+        }
+        return this.sendRpc('stagehand', 'agent.execute', [this.config, cleanOptions], {
+            contextId: this.getContextId(),
+            pageId: this.resolvePageId(page),
+        });
+    }
+}

package/dist/agents/stagehand/index.d.ts

@@ -0,0 +1,3 @@
+export { StagehandCore, StagehandAgent } from './core.js';
+export { StagehandNamespace } from './namespace.js';
+export type { ActOptionsWithPage, ExtractOptionsWithPage, ObserveOptionsWithPage, AgentExecuteOptionsWithPage, PageResolver, } from './core.js';

package/dist/agents/stagehand/index.js

@@ -0,0 +1,24 @@
+// ============================================================================
+// Stagehand AI Agent - AI-powered browser automation
+// ============================================================================
+//
+// This module provides the Stagehand AI integration for bctrl.
+//
+// - StagehandCore: Centralized implementation of act, extract, observe, agent
+// - StagehandNamespace: Wraps core for .stagehand namespace on other drivers
+// - StagehandAgent: Agent wrapper for autonomous task execution
+//
+// Usage:
+//   // For Playwright/Puppeteer/Selenium - via namespace
+//   const session = await bctrl.browser('my-scraper').connect.puppeteer();
+//   await session.stagehand.act("click button", { page });
+//
+//   // For Stagehand driver - directly on session (matches real Stagehand SDK)
+//   const session = await bctrl.browser('my-scraper').connect.stagehand();
+//   await session.act("click button", { page });
+//
+// ============================================================================
+// Core implementation
+export { StagehandCore, StagehandAgent } from './core.js';
+// Namespace wrapper for other drivers
+export { StagehandNamespace } from './namespace.js';

package/dist/agents/stagehand/namespace.d.ts

@@ -0,0 +1,51 @@
+import type { ZodType, infer as ZodInfer } from 'zod';
+import { StagehandAgent, type ActOptionsWithPage, type ExtractOptionsWithPage, type ObserveOptionsWithPage, type PageResolver } from './core.js';
+import type { ActResult, StagehandAction, StagehandAgentConfig, StagehandExtractResult, StagehandMetrics, StagehandHistoryEntry, StagehandObserveResult } from '../../contracts/stagehand.js';
+import type { RpcSender } from '../../internal/transport.js';
+/**
+ * Stagehand AI namespace - wraps StagehandCore for driver sessions.
+ * Generic TPage allows each driver to specify its own page type.
+ */
+export declare class StagehandNamespace<TPage = unknown> {
+    private core;
+    constructor(sendRpc: RpcSender, getContextId: () => string | undefined, getActivePageId: () => string | undefined, resolvePageFromDriver: PageResolver<TPage>);
+    /**
+     * Execute an AI action on a page.
+     * @example await stagehand.act("click the login button", { page });
+     */
+    act(instruction: string, options?: ActOptionsWithPage<TPage>): Promise<ActResult>;
+    act(action: StagehandAction, options?: ActOptionsWithPage<TPage>): Promise<ActResult>;
+    /**
+     * Extract data from a page using AI.
+     * @example
+     * const schema = z.object({ title: z.string(), price: z.number() });
+     * const data = await stagehand.extract("get product info", schema, { page });
+     */
+    extract(options?: ExtractOptionsWithPage<TPage>): Promise<StagehandExtractResult<{
+        pageText: string;
+    }>>;
+    extract<T extends ZodType>(instruction: string, schema: T, options?: ExtractOptionsWithPage<TPage>): Promise<StagehandExtractResult<ZodInfer<T>>>;
+    /**
+     * Observe available actions on a page using AI.
+     * @example const actions = await stagehand.observe("find clickable elements", { page });
+     */
+    observe(options?: ObserveOptionsWithPage<TPage>): Promise<StagehandObserveResult>;
+    observe(instruction: string, options?: ObserveOptionsWithPage<TPage>): Promise<StagehandObserveResult>;
+    /**
+     * Create a Stagehand agent for autonomous task execution.
+     * @example
+     * const agent = stagehand.agent({ model: 'gpt-4o' });
+     * await agent.execute("Find and click the login button", { page });
+     */
+    agent(config?: StagehandAgentConfig): StagehandAgent<TPage>;
+    /**
+     * Get Stagehand usage metrics.
+     */
+    getMetrics(): Promise<StagehandMetrics>;
+    /**
+     * Get Stagehand operation history.
+     */
+    getHistory(): Promise<StagehandHistoryEntry[]>;
+}
+export { StagehandCore, StagehandAgent } from './core.js';
+export type { ActOptionsWithPage, ExtractOptionsWithPage, ObserveOptionsWithPage, AgentExecuteOptionsWithPage, PageResolver, } from './core.js';

package/dist/agents/stagehand/namespace.js

@@ -0,0 +1,65 @@
+// ============================================================================
+// StagehandNamespace - Stagehand AI methods for non-stagehand drivers
+// ============================================================================
+//
+// This class provides the `.stagehand` namespace on driver sessions
+// for Playwright, Puppeteer, and Selenium drivers.
+//
+// Usage:
+//   const session = await bctrl.browser('my-scraper').connect.puppeteer();
+//   await session.stagehand.act("click button", { page });
+//   const data = await session.stagehand.extract("get info", schema, { page });
+//
+// Note: For the stagehand driver, AI methods are exposed directly on the
+// session (session.act, session.extract, etc.) to match the real Stagehand SDK.
+//
+// ============================================================================
+import { StagehandCore, } from './core.js';
+/**
+ * Stagehand AI namespace - wraps StagehandCore for driver sessions.
+ * Generic TPage allows each driver to specify its own page type.
+ */
+export class StagehandNamespace {
+    core;
+    constructor(sendRpc, getContextId, getActivePageId, resolvePageFromDriver) {
+        this.core = new StagehandCore(sendRpc, getContextId, getActivePageId, resolvePageFromDriver);
+    }
+    act(instructionOrAction, options) {
+        return this.core.act(instructionOrAction, options);
+    }
+    extract(instructionOrOptions, schema, options) {
+        if (typeof instructionOrOptions === 'string') {
+            return this.core.extract(instructionOrOptions, schema, options);
+        }
+        return this.core.extract(instructionOrOptions);
+    }
+    observe(instructionOrOptions, options) {
+        if (typeof instructionOrOptions === 'string') {
+            return this.core.observe(instructionOrOptions, options);
+        }
+        return this.core.observe(instructionOrOptions);
+    }
+    /**
+     * Create a Stagehand agent for autonomous task execution.
+     * @example
+     * const agent = stagehand.agent({ model: 'gpt-4o' });
+     * await agent.execute("Find and click the login button", { page });
+     */
+    agent(config) {
+        return this.core.agent(config);
+    }
+    /**
+     * Get Stagehand usage metrics.
+     */
+    getMetrics() {
+        return this.core.getMetrics();
+    }
+    /**
+     * Get Stagehand operation history.
+     */
+    getHistory() {
+        return this.core.getHistory();
+    }
+}
+// Re-export types and classes from core for convenience
+export { StagehandCore, StagehandAgent } from './core.js';

package/dist/ai-credentials/client.d.ts

@@ -0,0 +1,12 @@
+import type { AiCredential, AiCredentialCreateRequest, AiCredentialTestResponse, AiCredentialUpdateRequest } from '../contracts/public-api.js';
+export declare class AiCredentialsClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    list(): Promise<AiCredential[]>;
+    create(request: AiCredentialCreateRequest): Promise<AiCredential>;
+    get(id: string): Promise<AiCredential>;
+    update(id: string, request: AiCredentialUpdateRequest): Promise<AiCredential>;
+    delete(id: string): Promise<void>;
+    test(id: string): Promise<AiCredentialTestResponse>;
+}