@ddwang/magnitude-core 0.3.1-ddwang.2 → 0.3.1-ddwang.21

package/dist/index.d.ts

@@ -1,24 +1,1148 @@
-export { Agent } from "@/agent";
-export { createAction } from '@/actions';
-export { BrowserAgent, startBrowserAgent } from '@/agent/browserAgent';
-export * from "@/agent";
-export * from "@/memory";
-export * from "@/web/harness";
-export * from "@/actions";
-export * from "@/connectors";
-export * from "@/web/browserProvider";
-export * from "@/connectors/browserConnector";
-export * from "@/connectors/desktopConnector";
-export * from "@/agent/errors";
-export * from "@/types";
-export * from "@/ai/types";
-export * from "@/web/types";
-export { BrowserBlockedError } from '@/web/recovery';
-export type { BrowserBlock, BlockReason, RecoveryOptions, HttpDiagnostic } from '@/web/recovery';
-export * from "@/actions/types";
-export * from '@/common';
-export type { OperationOptions } from '@/common/operation';
-export * from "@/telemetry";
-export { buildDefaultBrowserAgentOptions } from "@/ai/util";
-export { logger } from './logger';
+import EventEmitter from 'eventemitter3';
+import z$1, { z, Schema, ZodSchema } from 'zod';
 export { z } from 'zod';
+import { Image as Image$1 } from '@boundaryml/baml';
+import { Sharp, FormatEnum } from 'sharp';
+import { BrowserContext, Page, PageScreenshotOptions, Browser, BrowserContextOptions, LaunchOptions } from 'playwright';
+import { PostHog } from 'posthog-node';
+import pino from 'pino';
+
+type Base64Image = `data:image/${'jpeg' | 'png' | 'gif'};base64,${string}`;
+type WebAction = NavigateWebAction | ClickWebAction | HoverWebAction | TypeWebAction | ScrollWebAction | SwitchTabWebAction;
+interface NavigateWebAction {
+    variant: 'load';
+    url: string;
+}
+interface ClickWebAction {
+    variant: 'click';
+    x: number;
+    y: number;
+}
+interface HoverWebAction {
+    variant: 'hover';
+    x: number;
+    y: number;
+}
+interface TypeWebAction {
+    variant: 'type';
+    x: number;
+    y: number;
+    content: string;
+}
+interface ScrollWebAction {
+    variant: 'scroll';
+    x: number;
+    y: number;
+    deltaX: number;
+    deltaY: number;
+}
+type SwitchTabWebAction = {
+    variant: 'tab';
+    index: number;
+};
+interface PixelCoordinate {
+    x: number;
+    y: number;
+}
+
+/**
+ * "Intents" are natural language descriptors that align 1:1 with executable web actions.
+ * Micro converts intents into web actions.
+ */
+
+interface Action {
+    variant: string;
+    [key: string]: any;
+}
+type ActionIntent = ClickIntent | HoverIntent | TypeIntent | ScrollIntent | SwitchTabIntent;
+type Intent = ActionIntent | CheckIntent;
+interface ClickIntent {
+    variant: 'click';
+    target: string;
+}
+interface HoverIntent {
+    variant: 'hover';
+    target: string;
+}
+interface TypeIntent {
+    variant: 'type';
+    target: string;
+    content: string;
+}
+interface ScrollIntent {
+    variant: 'scroll';
+    target: string;
+    deltaX: number;
+    deltaY: number;
+}
+type SwitchTabIntent = SwitchTabWebAction;
+interface CheckIntent {
+    variant: 'check';
+    checks: string[];
+}
+
+type BrowserAgentRole = 'act' | 'extract' | 'query';
+declare const allBrowserAgentRoles: BrowserAgentRole[];
+/** Optional request budget for one model call, used for act() planning and for extract(). */
+interface TimeoutPolicy {
+    /** Includes transport retries and format correction within one invocation. */
+    timeoutMs: number;
+    /** Retries after timeout, once the previous invocation settles. Default: 1. */
+    maxRetries?: number;
+}
+/** The published name for the planner's policy, kept for existing imports. */
+type PlannerOptions = TimeoutPolicy;
+type LLMClient = (AnthropicClient | ClaudeCodeClient | BedrockClient | GoogleAIClient | GoogleVertexClient | OpenAIClient | BasetenClient | OpenAIGenericClient | AzureOpenAIClient) & {
+    roles?: BrowserAgentRole[];
+};
+interface AnthropicClient {
+    provider: 'anthropic';
+    options: {
+        model: string;
+        apiKey?: string;
+        temperature?: number;
+        promptCaching?: boolean;
+        /** Maximum output tokens, including thinking. Omitted uses the transport default. */
+        maxTokens?: number;
+        /** Default: enabled for known supporting models. False retains prompt-only JSON. */
+        structuredOutputs?: boolean;
+    };
+}
+interface ClaudeCodeClient {
+    provider: 'claude-code';
+    options: {
+        model: string;
+        temperature?: number;
+        promptCaching?: boolean;
+        /** Maximum output tokens, including thinking. Omitted uses the transport default. */
+        maxTokens?: number;
+    };
+}
+interface BedrockClient {
+    provider: 'aws-bedrock';
+    options: {
+        model: string;
+        temperature?: number;
+    };
+}
+interface GoogleAIClient {
+    provider: 'google-ai';
+    options: {
+        model: string;
+        apiKey?: string;
+        temperature?: number;
+        baseUrl?: string;
+    };
+}
+interface GoogleVertexClient {
+    provider: 'vertex-ai';
+    options: {
+        model: string;
+        location?: string;
+        baseUrl?: string;
+        projectId?: string;
+        credentials?: string | object;
+        anthropicVersion?: string;
+        temperature?: number;
+    };
+}
+interface OpenAIClient {
+    provider: 'openai';
+    options: {
+        model: string;
+        apiKey?: string;
+        baseUrl?: string;
+        /** Omitted by default: reasoning models may reject sampling parameters. */
+        temperature?: number;
+        reasoningEffort?: 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+        /** Includes both visible output and reasoning tokens. */
+        maxCompletionTokens?: number;
+    };
+}
+interface BasetenClient {
+    provider: 'baseten';
+    options: {
+        model: string;
+        /** Defaults to BASETEN_API_KEY; never falls back to OPENAI_API_KEY. */
+        apiKey?: string;
+        /** Defaults to https://inference.baseten.co/v1. */
+        baseUrl?: string;
+        /** Omitted by default to preserve model-specific sampling defaults. */
+        temperature?: number;
+        /** Model-dependent. DeepSeek V4.1 Flash accepts none, low, high, or max. */
+        reasoningEffort?: OpenAIClient['options']['reasoningEffort'];
+        /** Baseten max_tokens: includes both visible output and reasoning tokens. */
+        maxTokens?: number;
+        /** Default: enabled on the hosted Model API; custom base URLs require opt-in. */
+        structuredOutputs?: boolean;
+    };
+}
+interface AzureOpenAIClient {
+    provider: 'azure-openai';
+    options: {
+        resourceName: string;
+        deploymentId: string;
+        apiVersion: string;
+        apiKey: string;
+    };
+}
+interface OpenAIGenericClient {
+    provider: 'openai-generic';
+    options: {
+        model: string;
+        baseUrl: string;
+        apiKey?: string;
+        temperature?: number;
+        headers?: Record<string, string>;
+    };
+}
+interface LLMClientIdentifier {
+    provider: string;
+    model: string;
+}
+interface ModelUsage {
+    llm: LLMClientIdentifier;
+    inputTokens: number;
+    outputTokens: number;
+    cacheWriteInputTokens?: number;
+    cacheReadInputTokens?: number;
+    inputCost?: number;
+    outputCost?: number;
+}
+
+interface OperationOptions {
+    signal?: AbortSignal;
+    /** Absolute Unix time in milliseconds, shared by every step, retry, and wait. */
+    deadline?: number;
+}
+type OperationKind = 'act' | 'query' | 'extract' | 'nav' | 'exec';
+type OperationPhase = 'preparing' | 'context' | 'observations' | 'model' | 'action' | 'screenshot' | 'stability' | 'cooldown' | 'retry' | 'paused' | 'cursor';
+interface OperationTiming {
+    count: number;
+    totalMs: number;
+}
+interface ProviderAttemptDiagnostics {
+    operationId: string;
+    attempt: number;
+    provider: string;
+    model: string;
+    startedAt: number;
+    elapsedMs: number | null;
+    httpStatus: number | null;
+    requestId: string | null;
+    /** Local planner invocation, when this HTTP attempt belongs to act() planning. */
+    plannerCallId?: string;
+    /** HTTP outcome, not successful parsing or completion of the agent's task. */
+    outcome: 'succeeded' | 'failed' | 'unknown';
+    /** Reported input tokens, including cached input, or null when the response has no usage. */
+    promptTokens: number | null;
+    /** Reported input tokens read from the provider's cache, or null when the response has no usage. */
+    cachedPromptTokens: number | null;
+    /** Reported output tokens, including reasoning, or null when the response has no usage. */
+    outputTokens: number | null;
+}
+interface PlannerCallDiagnostics {
+    id: string;
+    /** One-based timeout attempt within a planning step. */
+    attempt: number;
+    provider: string;
+    model: string;
+    startedAt: number;
+    endedAt?: number;
+    elapsedMs: number;
+    timeoutMs?: number;
+    status: 'running' | 'draining' | 'finished';
+    outcome?: 'succeeded' | 'failed' | 'timeout' | 'cancelled' | 'deadline';
+}
+interface BrowserClickDiagnostics {
+    operationId: string;
+    actionIndex: number | null;
+    x: number;
+    y: number;
+    button: 'left' | 'right' | 'middle';
+    clickCount: number;
+    screenshot: {
+        width: number;
+        height: number;
+    } | null;
+    viewport: {
+        width: number;
+        height: number;
+    } | null;
+    hit: {
+        tag: string | null;
+        role: string | null;
+    } | null;
+}
+interface OperationDiagnostics {
+    id: string;
+    kind: OperationKind;
+    status: 'running' | 'draining' | 'finished';
+    outcome?: 'succeeded' | 'failed' | 'cancelled' | 'deadline';
+    phase: OperationPhase;
+    startedAt: number;
+    elapsedMs: number;
+    cancellationToDrainMs?: number;
+    cancellationToIdleMs?: number;
+    lastAction?: {
+        index: number;
+        name: string;
+        state: 'pending' | 'started' | 'completed' | 'failed';
+    };
+    /** Inclusive totals: nested and concurrent phases overlap and must not be summed. */
+    timings: Partial<Record<OperationPhase, OperationTiming>>;
+    /** Latest 100 SDK attempts, available after each model invocation settles. */
+    providerAttempts?: ProviderAttemptDiagnostics[];
+    providerAttemptsTruncated?: boolean;
+    /** Latest 100 planner invocations, including the currently running request. */
+    plannerCalls?: PlannerCallDiagnostics[];
+    plannerCallsTruncated?: boolean;
+    /** Pre-dispatch hit evidence for the latest submitted click, not proof of success. */
+    lastClick?: BrowserClickDiagnostics;
+}
+
+interface AgentEvents {
+    /** Payload-free snapshots. Existing action/thought events retain their original payloads. */
+    'operation': (diagnostics: OperationDiagnostics) => void;
+    'start': () => void;
+    'stop': () => void;
+    'thought': (thought: string) => void;
+    'actStarted': (task: string, options: ActOptions) => void;
+    'actDone': (task: string, options: ActOptions) => void;
+    'actionStarted': (action: Action) => void;
+    'actionDone': (action: Action) => void;
+    'observationsRecorded': () => void;
+    'planningStarted': () => void;
+    'pause': () => void;
+    'resume': () => void;
+    'tokensUsed': (usage: ModelUsage) => void;
+}
+
+/*************************************************************************************************
+
+Welcome to Baml! To use this generated code, please run one of the following:
+
+$ npm install @boundaryml/baml
+$ yarn add @boundaryml/baml
+$ pnpm add @boundaryml/baml
+
+*************************************************************************************************/
+
+interface AgentContext {
+    instructions?: string | null;
+    observationContent: MultiMediaMessage[];
+    connectorInstructions: ConnectorInstructions[];
+}
+interface ConnectorInstructions {
+    connectorId: string;
+    instructions: string;
+}
+interface MultiMediaMessage {
+    role: "user" | "assistant";
+    cacheControl: boolean;
+    content: (Image$1 | string)[];
+}
+
+type StoredMedia = {
+    type: 'media';
+    format: string;
+    storage: 'base64';
+    base64: string;
+};
+interface StoredPrimitive {
+    type: 'primitive';
+    content: string | boolean | number;
+}
+type MultiMediaPrimitive = StoredMedia | StoredPrimitive | undefined | null;
+type MultiMediaArray = Array<MultiMediaJson>;
+type MultiMediaObject = {
+    [key: string]: MultiMediaJson;
+};
+type MultiMediaJson = MultiMediaPrimitive | MultiMediaArray | MultiMediaObject;
+
+declare class Image {
+    /**
+     * Wrapper for a Sharp image with conveniences to go to/from base64, convert to BAML, or serialize as JSON
+     */
+    private img;
+    private encoded?;
+    constructor(img: Sharp);
+    static fromBase64(base64: string): Image;
+    getFormat(): Promise<keyof FormatEnum>;
+    private encode;
+    /**
+     * Convert the image to a JSON representation
+     */
+    toJson(): Promise<StoredMedia>;
+    toBase64(): Promise<string>;
+    toBaml(): Promise<Image$1>;
+    saveToFile(filepath: string): Promise<void>;
+    getDimensions(): Promise<{
+        width: number;
+        height: number;
+    }>;
+    resize(width: number, height: number): Promise<Image>;
+}
+
+type MultiMediaContentPart = Image$1 | string;
+
+type ObservableDataPrimitive = Image | string | number | boolean | null | undefined;
+type ObservableDataArray = Array<RenderableContent>;
+type ObservableDataObject = {
+    [key: string]: RenderableContent;
+};
+type RenderableContent = ObservableDataPrimitive | ObservableDataArray | ObservableDataObject;
+type ObservationRole = 'user' | 'assistant';
+interface ObservationRetentionOptions {
+    type: string;
+    limit?: number;
+    dedupe?: boolean;
+    /** Render only the latest of this type after cached history; overrides limit and dedupe. Full audit retains every entry. */
+    current?: boolean;
+}
+type ObservationSource = `connector:${string}` | `action:taken:${string}` | `action:result:${string}` | `thought`;
+declare class Observation {
+    readonly source: ObservationSource;
+    readonly role: ObservationRole;
+    readonly timestamp: number;
+    readonly content: RenderableContent;
+    readonly retention?: ObservationRetentionOptions;
+    constructor(source: ObservationSource, role: ObservationRole, content: RenderableContent, retention?: ObservationRetentionOptions, timestamp?: number);
+    static fromConnector(connectorId: string, content: RenderableContent, options?: ObservationRetentionOptions): Observation;
+    static fromActionTaken(actionId: string, content: RenderableContent, options?: ObservationRetentionOptions): Observation;
+    static fromActionResult(actionId: string, content: RenderableContent, options?: ObservationRetentionOptions): Observation;
+    static fromThought(content: RenderableContent, options?: ObservationRetentionOptions): Observation;
+    toString(): string;
+    toJson(): Promise<MultiMediaJson>;
+    render(options?: {
+        prefix?: MultiMediaContentPart[];
+        postfix?: MultiMediaContentPart[];
+        cacheControl?: boolean;
+    }): Promise<MultiMediaMessage>;
+    hash(): Promise<string>;
+    equals(obs: Observation): Promise<boolean>;
+}
+
+declare const noteSchema: z.ZodObject<{
+    key: z.ZodString;
+    text: z.ZodString;
+    sources: z.ZodArray<z.ZodNumber>;
+}, z.core.$strict>;
+type NoteInput = z.infer<typeof noteSchema>;
+declare const noteUpdateSchema: z.ZodObject<{
+    key: z.ZodString;
+    text: z.ZodString;
+    sources: z.ZodArray<z.ZodNumber>;
+    operation: z.ZodEnum<{
+        add: "add";
+        correct: "correct";
+    }>;
+    expected_text: z.ZodNullable<z.ZodString>;
+}, z.core.$strict>;
+type NoteUpdate = z.infer<typeof noteUpdateSchema>;
+
+interface SerializedAgentMemory {
+    instructions?: string;
+    notes?: NoteInput[];
+    observations: {
+        source: ObservationSource;
+        role: ObservationRole;
+        timestamp: number;
+        data: MultiMediaJson;
+        options?: ObservationRetentionOptions;
+    }[];
+}
+interface AgentMemoryOptions {
+    instructions?: string | null;
+    promptCaching?: boolean;
+    thoughtLimit?: number;
+}
+interface MemoryRenderOptions {
+    /** Full audit history bypasses actor retention without changing actor visibility or cache state. */
+    history?: 'retained' | 'full';
+}
+declare class AgentMemory {
+    private options;
+    private observations;
+    private notebook;
+    private visibleSourceIds;
+    private freezeMask?;
+    private cacheControlIndices;
+    constructor(options?: AgentMemoryOptions);
+    get instructions(): string | null;
+    /** Apply current instructions and provider caching policy without replacing task evidence. */
+    configure(options: Pick<AgentMemoryOptions, 'instructions' | 'promptCaching'>): void;
+    render(options?: MemoryRenderOptions): Promise<MultiMediaMessage[]>;
+    simpleRender(): Promise<(Image$1 | string)[]>;
+    private observationPrefix;
+    private resolveNoteSource;
+    remember(note: NoteInput, expectedText?: string): void;
+    forget(key: string): void;
+    isEmpty(): boolean;
+    recordThought(content: string): void;
+    recordObservation(obs: Observation): void;
+    getLastThoughtMessage(): string | null;
+    toJSON(): Promise<SerializedAgentMemory>;
+    /** Replace saved state atomically; runtime caching and thought limits stay with this instance. */
+    loadJSON(data: SerializedAgentMemory): Promise<void>;
+}
+
+type ActionContext<T> = {
+    input: T;
+    agent: Agent;
+    memory?: AgentMemory;
+} & OperationOptions;
+interface ActionDefinition<T> {
+    name: string;
+    description?: string;
+    schema: Schema<T>;
+    resolver: (context: ActionContext<T>) => Promise<void | RenderableContent>;
+    render: (action: T) => string;
+}
+type ActionOptions<T> = Omit<ActionDefinition<T>, 'render'> & {
+    render?: ActionDefinition<T>['render'];
+};
+type EmptyActionOptions = Omit<ActionOptions<Record<string, never>>, 'schema'> & {
+    schema?: undefined;
+};
+declare function createAction<T>(action: ActionOptions<T>): ActionDefinition<T>;
+declare function createAction(action: EmptyActionOptions): ActionDefinition<Record<string, never>>;
+type ActionPayload<A extends ActionDefinition<any>> = {
+    name: A['name'];
+} & z.infer<A['schema']>;
+
+interface AgentConnector {
+    id: string;
+    onStart?(): Promise<void>;
+    onStop?(): Promise<void>;
+    beforeAction?(action: Action, options?: OperationOptions): Promise<void>;
+    onTaskStart?(options?: OperationOptions): void;
+    /** Called before each planner request, after the observations it will see are recorded. */
+    beforePlan?(options?: OperationOptions): Promise<void>;
+    getActionSpace?(): ActionDefinition<any>[];
+    collectObservations?(options?: OperationOptions): Promise<Observation[]>;
+    getInstructions?(options?: OperationOptions): Promise<void | string>;
+}
+
+declare function mergeMessages(messages: MultiMediaMessage[]): MultiMediaMessage[];
+
+interface PlannerResponse {
+    reasoning: string;
+    memory_updates: NoteUpdate[];
+    actions: Action[];
+}
+
+interface ModelHarnessEvents {
+    'tokensUsed': (usage: ModelUsage) => {};
+}
+
+declare class MultiModelHarness {
+    /**
+     * Delegates model responsibilites to different LLMs and consolidates their usage
+     */
+    private roles;
+    private uniqueModels;
+    readonly events: EventEmitter<ModelHarnessEvents>;
+    constructor(clients: LLMClient[], policies?: {
+        planner?: TimeoutPolicy;
+        extract?: TimeoutPolicy;
+    });
+    setup(): Promise<void>;
+    describe(): string;
+    partialAct<T>(context: AgentContext, task: string, data: MultiMediaContentPart[], actionVocabulary: ActionDefinition<T>[]): Promise<PlannerResponse>;
+    extract<T extends z$1.Schema>(instructions: string, schema: T, screenshot: Image, domContent: string): Promise<z$1.infer<T>>;
+    query<T extends z$1.Schema>(context: AgentContext, query: string, schema: T): Promise<z$1.infer<T>>;
+    get numUniqueModels(): number;
+}
+
+interface AgentOptions {
+    llm?: LLMClient | LLMClient[];
+    connectors?: AgentConnector[];
+    actions?: ActionDefinition<any>[];
+    prompt?: string | null;
+    telemetry?: boolean;
+    maxActions?: number;
+    /** Omitted preserves existing planner retry behavior without a per-call timeout. */
+    planner?: TimeoutPolicy;
+    /** Omitted runs extract() without a per-call timeout. */
+    extract?: TimeoutPolicy;
+}
+interface ActOptions extends OperationOptions {
+    prompt?: string;
+    data?: RenderableContent;
+    memory?: AgentMemory;
+}
+declare class Agent {
+    private options;
+    private connectors;
+    private actions;
+    private memoryOptions;
+    readonly models: MultiModelHarness;
+    readonly events: EventEmitter<AgentEvents>;
+    private doneActing;
+    private _paused;
+    private _pauseResolve;
+    private activeOperation?;
+    private latestOperation?;
+    private idle;
+    private resolveIdle?;
+    private pendingWork;
+    private lifecycleTail;
+    private lifecycleRequest?;
+    private lifecycleState;
+    private telemetryStarted;
+    protected latestTaskMemory: AgentMemory;
+    constructor(baseConfig?: Partial<AgentOptions>);
+    getConnector<C extends AgentConnector>(connectorClass: new (...args: any[]) => C): C | undefined;
+    require<C extends AgentConnector>(connectorClass: new (...args: any[]) => C): C;
+    start(): Promise<void>;
+    get lifecycle(): 'new' | 'starting' | 'ready' | 'stopping' | 'stopped';
+    private beginWork;
+    private endWork;
+    private scheduleLifecycle;
+    identifyAction(action: Action): ActionDefinition<any>;
+    /** True until underlying work settles, including after a cancelled caller returns. */
+    get busy(): boolean;
+    whenIdle(): Promise<void>;
+    /** A payload-free snapshot of the active or most recent operation. */
+    get operation(): OperationDiagnostics | undefined;
+    protected runOperation<T>(options: OperationOptions, fn: () => Promise<T>, kind?: OperationKind): Promise<T>;
+    exec(action: Action, memory?: AgentMemory, options?: OperationOptions): Promise<unknown>;
+    private _exec;
+    protected _recordConnectorObservations(memory: AgentMemory): Promise<void>;
+    get memory(): AgentMemory;
+    act(taskOrSteps: string | string[], options?: ActOptions): Promise<void>;
+    private _runAct;
+    private _traceAct;
+    private _buildContext;
+    private _act;
+    query<T extends z$1.Schema>(query: string, schema: T, options?: MemoryRenderOptions & OperationOptions): Promise<z$1.infer<T>>;
+    queueDone(): Promise<void>;
+    private _waitIfPaused;
+    pause(): void;
+    resume(): void;
+    get paused(): boolean;
+    stop(): Promise<void>;
+    private stopConnectors;
+}
+
+interface ActionVisualizerOptions {
+    showCursor?: boolean;
+    /** Set false to skip the 300 ms movement animation. Defaults to true. */
+    animateCursor?: boolean;
+    showHoverCircle?: boolean;
+    showClickRipple?: boolean;
+    showDragLine?: boolean;
+    showTypeEffects?: boolean;
+}
+declare class ActionVisualizer {
+    private options;
+    private context;
+    private page;
+    private cursor;
+    private mouseEffects;
+    private typeEffects;
+    constructor(context: BrowserContext, options: ActionVisualizerOptions);
+    setup(): Promise<void>;
+    setActivePage(page: Page): Promise<void>;
+    moveVirtualCursor(x: number, y: number): Promise<void>;
+    hideAll(): Promise<void>;
+    showAll(): Promise<void>;
+}
+
+interface TabState {
+    activeTab: number;
+    tabs: {
+        title: string;
+        url: string;
+    }[];
+}
+
+interface WebHarnessOptions {
+    virtualScreenDimensions?: {
+        width: number;
+        height: number;
+    };
+    visuals?: ActionVisualizerOptions;
+    switchTabsOnActivity?: boolean;
+    /** Refuse to type into password and one-time-code fields; the host owns authentication. */
+    hostOnlyAuthentication?: boolean;
+}
+interface WebHarnessEvents {
+    'activePageChanged': (page: Page) => Promise<void>;
+}
+declare class WebHarness {
+    /**
+     * Executes web actions on a page
+     * Not responsible for browser lifecycle
+     */
+    readonly context: BrowserContext;
+    private options;
+    private stability;
+    readonly visualizer: ActionVisualizer;
+    private transformer;
+    private tabs;
+    private lastScreenshot?;
+    readonly events: EventEmitter<WebHarnessEvents>;
+    constructor(context: BrowserContext, options?: WebHarnessOptions);
+    setActivePage(page: Page): Promise<void>;
+    retrieveTabState(): Promise<TabState>;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    get page(): Page;
+    screenshot(options?: PageScreenshotOptions): Promise<Image>;
+    _type(content: string): Promise<void>;
+    transformCoordinates({ x, y }: {
+        x: number;
+        y: number;
+    }): Promise<{
+        x: number;
+        y: number;
+    }>;
+    click({ x, y }: {
+        x: number;
+        y: number;
+    }, options?: {
+        transform: boolean;
+    }): Promise<void>;
+    /** Recheck an observed target after hover effects, before submitting any click. */
+    clickGrounded(resolve: () => Promise<{
+        x: number;
+        y: number;
+    } | null>): Promise<boolean>;
+    private _click;
+    private dispatchClick;
+    hover({ x, y }: {
+        x: number;
+        y: number;
+    }, options?: {
+        transform: boolean;
+    }): Promise<void>;
+    rightClick({ x, y }: {
+        x: number;
+        y: number;
+    }, options?: {
+        transform: boolean;
+    }): Promise<void>;
+    doubleClick({ x, y }: {
+        x: number;
+        y: number;
+    }, options?: {
+        transform: boolean;
+    }): Promise<void>;
+    drag({ x1, y1, x2, y2 }: {
+        x1: number;
+        y1: number;
+        x2: number;
+        y2: number;
+    }, options?: {
+        transform: boolean;
+    }): Promise<void>;
+    /** Stops the operation when the focused field, in any frame, takes a password or one-time code. */
+    private refuseCredentialField;
+    type({ content }: {
+        content: string;
+    }): Promise<void>;
+    clickAndType({ x, y, content }: {
+        x: number;
+        y: number;
+        content: string;
+    }, options?: {
+        transform: boolean;
+    }): Promise<void>;
+    scroll({ x, y, deltaX, deltaY }: {
+        x: number;
+        y: number;
+        deltaX: number;
+        deltaY: number;
+    }, options?: {
+        transform: boolean;
+    }): Promise<void>;
+    switchTab({ index }: {
+        index: number;
+    }): Promise<void>;
+    newTab(): Promise<void>;
+    navigate(url: string): Promise<void>;
+    selectAll(): Promise<void>;
+    enter(): Promise<void>;
+    backspace(): Promise<void>;
+    tab(): Promise<void>;
+    goBack(): Promise<void>;
+    escape(): Promise<void>;
+    executeAction(action: WebAction): Promise<void>;
+    waitForStability(timeout?: number): Promise<void>;
+}
+
+type BrowserOptions = {
+    instance: Browser;
+    contextOptions?: BrowserContextOptions;
+} | {
+    cdp: string;
+    contextOptions?: BrowserContextOptions;
+} | {
+    launchOptions?: LaunchOptions;
+    contextOptions?: BrowserContextOptions;
+} | {
+    context: BrowserContext;
+};
+declare class BrowserProvider {
+    private activeBrowsers;
+    private logger;
+    private constructor();
+    static getInstance(): BrowserProvider;
+    static reset(): Promise<void>;
+    private _launchOrReuseBrowser;
+    _createAndTrackContext(options: BrowserOptions): Promise<BrowserContext>;
+    newContext(options?: BrowserOptions): Promise<BrowserContext>;
+    private _applyEmulationSettings;
+}
+
+type BlockReason = 'rate_limit' | 'subscription' | 'authentication' | 'no_progress';
+interface BrowserBlock {
+    reason: BlockReason;
+    evidence: string;
+    retryAt?: number;
+}
+declare class BrowserBlockedError extends Error {
+    readonly block: BrowserBlock;
+    readonly operation?: OperationDiagnostics;
+    constructor(block: BrowserBlock);
+}
+interface HttpDiagnostic {
+    timestamp: number;
+    url: string;
+    status: number;
+    retryAt?: number;
+    navigation?: boolean;
+}
+interface RecoveryOptions {
+    maxRateLimitWaitMs?: number;
+    /** Unchanged attempts before stopping; known-state cycles allow twice this many attempts. Default: 6. */
+    repeatedActionLimit?: number;
+    /** Opt in to heuristic loop warnings and automatic no-progress termination. */
+    noProgress?: boolean;
+}
+declare class BrowserRecovery {
+    block?: BrowserBlock;
+    warning?: string;
+    waitUntil?: number;
+    private rateWaitMs;
+    private blockedActions;
+    private recentStates;
+    private repetitions;
+    private knownStateAttempts;
+    private lastFingerprint?;
+    readonly maxRateLimitWaitMs: number;
+    readonly repeatedActionLimit: number;
+    readonly noProgress: boolean;
+    constructor(options?: RecoveryOptions);
+    reset(): void;
+    /** New non-page evidence, such as a browser download lifecycle transition. */
+    recordProgress(): void;
+    observe(fingerprint: string | null, action: Action | undefined, block: BrowserBlock | undefined, now?: number): void;
+    check(): void;
+    waitDuration(requestedMs: number, now?: number, deadline?: number): number;
+}
+
+interface BrowserConnectorOptions {
+    browser?: BrowserOptions;
+    url?: string;
+    virtualScreenDimensions?: {
+        width: number;
+        height: number;
+    };
+    minScreenshots?: number;
+    visuals?: ActionVisualizerOptions;
+    recovery?: RecoveryOptions | false;
+    /** Opt in to current-viewport link, button, and native field observations with browser:click, browser:select, and browser:fill references. */
+    groundedControls?: boolean;
+    /** The host owns sign-in: typing into a password or one-time-code field stops the task as blocked by authentication. */
+    hostOnlyAuthentication?: boolean;
+}
+interface BrowserConnectorStateData {
+    screenshot: Image;
+    tabs: TabState;
+}
+declare class BrowserConnector implements AgentConnector {
+    readonly id: string;
+    private harness;
+    private options;
+    private browser?;
+    private context;
+    private logger;
+    readonly recovery: BrowserRecovery;
+    readonly network: HttpDiagnostic[];
+    private responses;
+    private pendingAction?;
+    private cancelWait?;
+    private downloads?;
+    private controls?;
+    constructor(options?: BrowserConnectorOptions);
+    onStart(): Promise<void>;
+    onStop(): Promise<void>;
+    getActionSpace(): ActionDefinition<any>[];
+    private onResponse;
+    beforeAction(action: Action): Promise<void>;
+    beforePlan(): Promise<void>;
+    onTaskStart(): void;
+    wait(requestedMs: number): Promise<void>;
+    getHarness(): WebHarness;
+    private captureCurrentState;
+    transformScreenshot(screenshot: Image): Promise<Image>;
+    getLastScreenshot(): Promise<Image>;
+    collectObservations(): Promise<Observation[]>;
+    private collectCurrentObservations;
+    getInstructions(): Promise<void | string>;
+}
+
+declare function startBrowserAgent(options?: AgentOptions & BrowserConnectorOptions & {
+    narrate?: boolean;
+}): Promise<BrowserAgent>;
+type ExtractedOutput = string | number | boolean | bigint | Date | null | undefined | {
+    [key: string]: ExtractedOutput;
+} | ExtractedOutput[];
+interface BrowserAgentEvents {
+    'nav': (url: string) => void;
+    'extractStarted': (instructions: string, schema: ZodSchema) => void;
+    'extractDone': (instructions: string, data: ExtractedOutput) => void;
+}
+declare class BrowserAgent extends Agent {
+    readonly browserAgentEvents: EventEmitter<BrowserAgentEvents>;
+    constructor({ agentOptions, browserOptions }: {
+        agentOptions?: Partial<AgentOptions>;
+        browserOptions?: BrowserConnectorOptions;
+    });
+    get page(): Page;
+    get context(): BrowserContext;
+    nav(url: string, options?: OperationOptions): Promise<void>;
+    extract<T extends Schema<ExtractedOutput>>(instructions: string, schema: T, options?: OperationOptions): Promise<z$1.infer<T>>;
+    private _extract;
+}
+
+/**
+ * Generic desktop automation interface.
+ * Implementations can use any desktop automation technology
+ * (Lume, PyAutoGUI, Windows UI Automation, etc.)
+ */
+interface DesktopInterface {
+    click(x: number, y: number): Promise<void>;
+    rightClick(x: number, y: number): Promise<void>;
+    doubleClick(x: number, y: number): Promise<void>;
+    moveCursor(x: number, y: number): Promise<void>;
+    drag(fromX: number, fromY: number, toX: number, toY: number): Promise<void>;
+    scroll(x: number, y: number, deltaX: number, deltaY: number): Promise<void>;
+    type(text: string): Promise<void>;
+    key(key: string): Promise<void>;
+    hotkey(keys: string[]): Promise<void>;
+    screenshot(): Promise<Buffer>;
+    getScreenSize(): Promise<{
+        width: number;
+        height: number;
+    }>;
+    navigate?(url: string): Promise<void>;
+    getActiveWindow?(): Promise<{
+        title: string;
+        app: string;
+    }>;
+    getOpenWindows?(): Promise<Array<{
+        title: string;
+        app: string;
+        isActive: boolean;
+    }>>;
+    focusWindow?(title: string): Promise<void>;
+    openApplication?(name: string): Promise<void>;
+    closeApplication?(name: string): Promise<void>;
+}
+interface DesktopConnectorOptions {
+    desktopInterface: DesktopInterface;
+    virtualScreenDimensions?: {
+        width: number;
+        height: number;
+    };
+    minScreenshots?: number;
+}
+declare class DesktopConnector implements AgentConnector {
+    readonly id: string;
+    private desktopInterface;
+    private options;
+    private logger;
+    constructor(options: DesktopConnectorOptions);
+    onStart(): Promise<void>;
+    onStop(): Promise<void>;
+    getActionSpace(): ActionDefinition<any>[];
+    collectObservations(): Promise<Observation[]>;
+    private formatWindowInfo;
+    getInterface(): DesktopInterface;
+}
+
+interface AgentErrorOptions {
+    variant?: string;
+    adaptable?: boolean;
+}
+declare class AgentError extends Error {
+    readonly operation?: OperationDiagnostics;
+    readonly options: Required<AgentErrorOptions>;
+    constructor(message: string, options?: AgentErrorOptions);
+}
+declare class ActionLimitError extends AgentError {
+    readonly limit: number;
+    constructor(limit: number);
+}
+declare class OperationCancelledError extends AgentError {
+    constructor(reason?: unknown);
+}
+declare class OperationDeadlineError extends AgentError {
+    readonly deadline: number;
+    constructor(deadline: number);
+}
+declare class AgentBusyError extends AgentError {
+    constructor();
+}
+declare class PlannerTimeoutError extends AgentError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+declare class ExtractTimeoutError extends AgentError {
+    readonly timeoutMs: number;
+    constructor(timeoutMs: number);
+}
+
+/**
+ * Represents any reason why a test case could have failed, for example:
+ * - Step could not be completed
+ * - Check did not pass
+ * - Could not navigate to starting URL
+ * - Time or action based timeout
+ * - Operation cancelled by signal
+ * - ...
+ */
+type FailureDescriptor = BugDetectedFailure | MisalignmentFailure | NetworkFailure | BrowserFailure | RateLimitFailure | ApiKeyFailure | UnknownFailure | CancelledFailure;
+type BugSeverity = 'critical' | 'high' | 'medium' | 'low';
+/**
+ * Step and check failures are classified into one of:
+ * BugDetectedFailure: seems to be something wrong with the application itself
+ * MisalignmentFailure: seems to be a discrepency between the test case and the interface
+ *    OR the agent did not properly recognize the relationship between test case and interface
+ */
+interface BugDetectedFailure {
+    variant: 'bug';
+    title: string;
+    expectedResult: string;
+    actualResult: string;
+    severity: BugSeverity;
+}
+interface MisalignmentFailure {
+    /**
+     * Major misalignment: when a step/check fails due to:
+     * 1. Poorly written step/check that is completely unrelated to the interface
+     * 2. Or interface has changed so much that step/check no longer applicable
+     * 3. Planner did not do good enough job adjusting recipe for minor misalignment
+     * Misalignment could be due to a poorly written test case OR bad agent behavior.
+     */
+    variant: 'misalignment';
+    message: string;
+}
+interface NetworkFailure {
+    /**
+     * For example, failure to connect to starting URL, or any other network errors
+     * that would completely prevent the test from executing.
+     */
+    variant: 'network';
+    message: string;
+}
+interface BrowserFailure {
+    /**
+     * E.g. something goes wrong with playwright interactions, any DOM manipulation, etc.
+     */
+    variant: 'browser';
+    message: string;
+}
+interface RateLimitFailure {
+    variant: 'rate_limit';
+    message: string;
+}
+interface ApiKeyFailure {
+    variant: 'api_key';
+    message: string;
+}
+interface UnknownFailure {
+    variant: 'unknown';
+    message: string;
+}
+interface CancelledFailure {
+    /**
+     * Operation was cancelled, typically by an AbortSignal from a controlling process (e.g., test runner pool).
+     */
+    variant: 'cancelled';
+}
+
+type RetryMode = {
+    mode: 'retry_on_partial_message';
+    errorSubstrings: string[];
+} | {
+    mode: 'retry_all';
+};
+type RetryParams = {
+    retryLimit: number;
+    delayMs: number;
+    showWarnOnRetry: boolean;
+};
+type RetryOptions = RetryMode & RetryParams;
+declare function retryOnErrorIsSuccess<T>(fnToRetry: () => Promise<T>, retryOptions: RetryMode & Partial<RetryParams>): Promise<boolean>;
+declare function retryOnError<T>(fnToRetry: () => Promise<T>, retryOptions: RetryMode & Partial<RetryParams>): Promise<T>;
+/**
+ * Performs a deep comparison between two values to determine if they are equivalent.
+ *
+ * @param a The first value to compare.
+ * @param b The second value to compare.
+ * @param cache A WeakMap to handle circular references. Should not be provided by the caller.
+ * @returns `true` if the values are deeply equal, `false` otherwise.
+ */
+declare function deepEquals(a: any, b: any, cache?: WeakMap<object, WeakSet<object>>): boolean;
+
+interface TestDataEntry {
+    key: string;
+    value: string;
+    sensitive: boolean;
+}
+interface TestData {
+    data?: TestDataEntry[];
+    other?: string;
+}
+interface TestStepDefinition {
+    description: string;
+    checks: string[];
+    testData: TestData;
+}
+interface TestCaseDefinition {
+    url: string;
+    steps: TestStepDefinition[];
+    recipe?: Intent[];
+}
+type TestCaseResult = SuccessfulTestCaseResult | FailedTestCaseResult;
+interface SuccessfulTestCaseResult {
+    passed: true;
+    recipe: Intent[];
+}
+interface FailedTestCaseResult {
+    passed: false;
+    failure: FailureDescriptor;
+}
+
+declare const createId: () => string;
+declare const posthog: PostHog;
+declare function getMachineId(): string;
+declare function getCodebaseId(): string | undefined;
+declare function sendTelemetry(eventName: string, properties: Record<string, any>): Promise<void>;
+
+declare function buildDefaultBrowserAgentOptions({ agentOptions, browserOptions }: {
+    agentOptions: AgentOptions;
+    browserOptions: BrowserConnectorOptions;
+}): {
+    agentOptions: AgentOptions;
+    browserOptions: BrowserConnectorOptions;
+};
+
+declare const logger: pino.Logger<never, boolean>;
+
+export { type ActOptions, type Action, type ActionContext, type ActionDefinition, type ActionIntent, ActionLimitError, type ActionPayload, Agent, AgentBusyError, type AgentConnector, AgentError, type AgentErrorOptions, type AgentEvents, AgentMemory, type AgentMemoryOptions, type AgentOptions, type AnthropicClient, type ApiKeyFailure, type AzureOpenAIClient, type Base64Image, type BasetenClient, type BedrockClient, type BlockReason, BrowserAgent, type BrowserAgentRole, type BrowserBlock, BrowserBlockedError, type BrowserClickDiagnostics, BrowserConnector, type BrowserConnectorOptions, type BrowserConnectorStateData, type BrowserFailure, type BrowserOptions, BrowserProvider, type BugDetectedFailure, type BugSeverity, type CancelledFailure, type CheckIntent, type ClaudeCodeClient, type ClickIntent, type ClickWebAction, DesktopConnector, type DesktopConnectorOptions, type DesktopInterface, ExtractTimeoutError, type FailedTestCaseResult, type FailureDescriptor, type GoogleAIClient, type GoogleVertexClient, type HoverIntent, type HoverWebAction, type HttpDiagnostic, type Intent, type LLMClient, type LLMClientIdentifier, type MemoryRenderOptions, type MisalignmentFailure, type ModelUsage, type NavigateWebAction, type NetworkFailure, type ObservableDataArray, type ObservableDataObject, type ObservableDataPrimitive, Observation, type ObservationRetentionOptions, type ObservationRole, type ObservationSource, type OpenAIClient, type OpenAIGenericClient, OperationCancelledError, OperationDeadlineError, type OperationDiagnostics, type OperationKind, type OperationOptions, type OperationPhase, type OperationTiming, type PixelCoordinate, type PlannerCallDiagnostics, type PlannerOptions, PlannerTimeoutError, type ProviderAttemptDiagnostics, type RateLimitFailure, type RecoveryOptions, type RenderableContent, type RetryMode, type RetryOptions, type RetryParams, type ScrollIntent, type ScrollWebAction, type SerializedAgentMemory, type SuccessfulTestCaseResult, type SwitchTabIntent, type SwitchTabWebAction, type TestCaseDefinition, type TestCaseResult, type TestData, type TestDataEntry, type TestStepDefinition, type TimeoutPolicy, type TypeIntent, type TypeWebAction, type UnknownFailure, type WebAction, WebHarness, type WebHarnessEvents, type WebHarnessOptions, allBrowserAgentRoles, buildDefaultBrowserAgentOptions, createAction, createId, deepEquals, getCodebaseId, getMachineId, logger, mergeMessages, posthog, retryOnError, retryOnErrorIsSuccess, sendTelemetry, startBrowserAgent };