@omnivoice/page-agent 0.4.0 → 0.5.0

package/dist/esm/page-agent.d.ts

@@ -0,0 +1,1076 @@
+import * as z from 'zod/v4';
+
+declare interface ActionResult {
+    success: boolean;
+    message: string;
+}
+
+/**
+ * Agent activity - transient state for immediate UI feedback.
+ *
+ * Unlike historical events (which are persisted), activities are ephemeral
+ * and represent "what the agent is doing right now". UI components should
+ * listen to 'activity' events to show real-time feedback.
+ *
+ * Note: There is no 'idle' activity - absence of activity events means idle.
+ */
+export declare type AgentActivity = {
+    type: 'thinking';
+} | {
+    type: 'executing';
+    tool: string;
+    input: unknown;
+} | {
+    type: 'executed';
+    tool: string;
+    input: unknown;
+    output: string;
+    duration: number;
+} | {
+    type: 'retrying';
+    attempt: number;
+    maxAttempts: number;
+} | {
+    type: 'error';
+    message: string;
+};
+
+export declare interface AgentConfig extends LLMConfig {
+    language?: SupportedLanguage;
+    /**
+     * Maximum number of steps the agent can take per task.
+     * @default 40
+     */
+    maxSteps?: number;
+    /**
+     * Custom tools to extend PageAgent capabilities
+     * @experimental
+     * @note You can also override or remove internal tools by using the same name.
+     * @see PageAgentTool
+     *
+     * @example
+     * // override internal tool
+     * import { z } from 'zod/v4'
+     * import { tool } from 'page-agent'
+     * const customTools = {
+     * ask_user: tool({
+     * 	description:
+     * 		'Ask the user or parent model a question and wait for their answer. Use this if you need more information or clarification.',
+     * 	inputSchema: z.object({
+     * 		question: z.string(),
+     * 	}),
+     * 	execute: async function (this: PageAgent, input) {
+     * 		const answer = await do_some_thing(input.question)
+     * 		return "✅ Received user answer: " + answer
+     * 	},
+     * })
+     * }
+     *
+     * @example
+     * // remove internal tool
+     * const customTools = {
+     * 	ask_user: null // never ask user questions
+     * }
+     */
+    customTools?: Record<string, PageAgentTool | null>;
+    /**
+     * Instructions to guide the agent's behavior
+     */
+    instructions?: {
+        /**
+         * Global system-level instructions, applied to all tasks
+         */
+        system?: string;
+        /**
+         * Dynamic page-level instructions callback
+         * Called before each step to get instructions for the current page
+         * @param url - Current page URL (window.location.href)
+         * @returns Instructions string, or undefined/null to skip
+         */
+        getPageInstructions?: (url: string) => string | undefined | null;
+    };
+    /**
+     * Lifecycle hooks for task execution.
+     * @experimental API may change in future versions.
+     *
+     * All hooks receive the agent instance as first parameter.
+     */
+    /**
+     * Called before each step execution.
+     * @experimental
+     * @param agent - The PageAgentCore instance
+     * @param stepCount - Current step number (0-indexed)
+     */
+    onBeforeStep?: (agent: PageAgentCore, stepCount: number) => Promise<void> | void;
+    /**
+     * Called after each step execution.
+     * @experimental
+     * @param agent - The PageAgentCore instance
+     * @param history - Current history of events
+     */
+    onAfterStep?: (agent: PageAgentCore, history: HistoricalEvent[]) => Promise<void> | void;
+    /**
+     * Called before task execution starts.
+     * @experimental
+     * @param agent - The PageAgentCore instance
+     */
+    onBeforeTask?: (agent: PageAgentCore) => Promise<void> | void;
+    /**
+     * Called after task execution completes (success or failure).
+     * @experimental
+     * @param agent - The PageAgentCore instance
+     * @param result - The execution result
+     */
+    onAfterTask?: (agent: PageAgentCore, result: ExecutionResult) => Promise<void> | void;
+    /**
+     * Called when the agent is disposed.
+     * @experimental
+     * @note This hook can block the disposal process if it's async.
+     * @param agent - The PageAgentCore instance
+     * @param reason - Optional reason for disposal
+     */
+    onDispose?: (agent: PageAgentCore, reason?: string) => void;
+    /**
+     * @experimental
+     * Enable the experimental script execution tool that allows executing generated JavaScript code on the page.
+     * @note Can cause unpredictable side effects.
+     * @note May bypass some safe guards and data-masking mechanisms.
+     */
+    experimentalScriptExecutionTool?: boolean;
+    /**
+     * @experimental
+     * Fetch /llms.txt from current site origin and include as context.
+     * Only fetched once per origin per task.
+     * @default false
+     */
+    experimentalLlmsTxt?: boolean;
+    /**
+     * Transform page content before sending to LLM.
+     * Called after DOM extraction and simplification, before LLM invocation.
+     * Use cases: inspect extraction results, modify page info, mask sensitive data.
+     *
+     * @param content - Simplified page content that will be sent to LLM
+     * @returns Transformed content
+     *
+     * @example
+     * // Mask phone numbers
+     * transformPageContent: async (content) => {
+     *   return content.replace(/1[3-9]\d{9}/g, '***********')
+     * }
+     */
+    transformPageContent?: (content: string) => Promise<string> | string;
+    /**
+     * Completely override the default system prompt.
+     * @experimental Use with caution - incorrect prompts may break agent behavior.
+     */
+    customSystemPrompt?: string;
+    /**
+     * Delay between steps in seconds.
+     * @default 0.4
+     */
+    stepDelay?: number;
+}
+
+/**
+ * Error event - fatal error from LLM or execution
+ */
+export declare interface AgentErrorEvent {
+    type: 'error';
+    message: string;
+    rawResponse?: unknown;
+}
+
+/**
+ * Agent reflection state - the reflection-before-action model
+ *
+ * Every tool call must first reflect on:
+ * - evaluation_previous_goal: How well did the previous action achieve its goal?
+ * - memory: Key information to remember for future steps
+ * - next_goal: What should be accomplished in the next action?
+ */
+export declare interface AgentReflection {
+    evaluation_previous_goal: string;
+    memory: string;
+    next_goal: string;
+}
+
+/**
+ * Agent lifecycle status.
+ */
+export declare type AgentStatus = 'idle' | 'running' | 'completed' | 'error' | 'stopped';
+
+/**
+ * A single agent step with reflection and action
+ */
+export declare interface AgentStepEvent {
+    type: 'step';
+    stepIndex: number;
+    reflection: Partial<AgentReflection>;
+    action: {
+        name: string;
+        input: any;
+        output: string;
+    };
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        cachedTokens?: number;
+        reasoningTokens?: number;
+    };
+    /** Raw LLM response for debugging */
+    rawResponse?: unknown;
+    /** Raw LLM request for debugging */
+    rawRequest?: unknown;
+}
+
+/**
+ * Structured browser state for LLM consumption
+ */
+declare interface BrowserState {
+    url: string;
+    title: string;
+    /** Page info + scroll position hint (e.g. "Page info: 1920x1080px...\n[Start of page]") */
+    header: string;
+    /** Simplified HTML of interactive elements */
+    content: string;
+    /** Page footer hint (e.g. "... 300 pixels below ..." or "[End of page]") */
+    footer: string;
+}
+
+declare function cleanUpHighlights(): void;
+
+export declare function createVoice(options?: VoiceOptions): Voice;
+
+declare namespace dom {
+    export {
+        resolveViewportExpansion,
+        getFlatTree,
+        flatTreeToString,
+        getSelectorMap,
+        getElementTextMap,
+        cleanUpHighlights,
+        DomConfig,
+        getAllTextTillNextClickableElement
+    }
+}
+
+declare interface DomConfig {
+    viewportExpansion?: number;
+    interactiveBlacklist?: (Element | (() => Element))[];
+    interactiveWhitelist?: (Element | (() => Element))[];
+    includeAttributes?: string[];
+    highlightOpacity?: number;
+    highlightLabelOpacity?: number;
+    /**
+     * Preserve semantic landmark tags in dehydrated output even if not interactive
+     * @note maybe confusing for LLM combining with page scrolling, use with caution
+     **/
+    keepSemanticTags?: boolean;
+}
+
+declare type DomNode = TextDomNode | ElementDomNode | InteractiveElementDomNode;
+
+declare interface ElementDomNode {
+    tagName: string;
+    attributes?: Record<string, string>;
+    xpath?: string;
+    children?: string[];
+    isVisible?: boolean;
+    isTopElement?: boolean;
+    isInViewport?: boolean;
+    isNew?: boolean;
+    isInteractive?: false;
+    highlightIndex?: number;
+    extra?: Record<string, any>;
+    [key: string]: unknown;
+}
+
+export declare interface ExecutionResult {
+    success: boolean;
+    data: string;
+    history: HistoricalEvent[];
+}
+
+declare interface FlatDomTree {
+    rootId: string;
+    map: Record<string, DomNode>;
+}
+
+/**
+ * 对应 python 中的 views::clickable_elements_to_string,
+ * 将 dom 信息处理成适合 llm 阅读的文本格式
+ * @形如
+ * ``` text
+ * [0]<a aria-label=page-agent.js 首页 />
+ * [1]<div >P />
+ * [2]<div >page-agent.js
+ * UI Agent in your webpage />
+ * [3]<a >文档 />
+ * [4]<a aria-label=查看源码（在新窗口打开）>源码 />
+ * UI Agent in your webpage
+ * 用户输入需求，AI 理解页面并自动操作。
+ * [5]<a role=button>快速开始 />
+ * [6]<a role=button>查看文档 />
+ * 无需后端
+ * ```
+ * 其中可交互元素用序号标出，提示llm可以用序号操作。
+ * 缩进代表父子关系。
+ * 普通文本则直接列出来。
+ *
+ * @todo 数据脱敏过滤器
+ */
+declare function flatTreeToString(flatTree: FlatDomTree, includeAttributes?: string[], keepSemanticTags?: boolean): string;
+
+declare const getAllTextTillNextClickableElement: (node: TreeNode, maxDepth?: number) => string;
+
+declare function getElementTextMap(simplifiedHTML: string): Map<number, string>;
+
+declare function getFlatTree(config: DomConfig): FlatDomTree;
+
+declare function getSelectorMap(flatTree: FlatDomTree): Map<number, InteractiveElementDomNode>;
+
+/**
+ * Union type for all history events
+ */
+export declare type HistoricalEvent = AgentStepEvent | ObservationEvent | UserTakeoverEvent | RetryEvent | AgentErrorEvent;
+
+declare interface InteractiveElementDomNode {
+    tagName: string;
+    attributes?: Record<string, string>;
+    xpath?: string;
+    children?: string[];
+    isVisible?: boolean;
+    isTopElement?: boolean;
+    isInViewport?: boolean;
+    isInteractive: true;
+    highlightIndex: number;
+    /**
+     * 可交互元素的 dom 引用
+     */
+    ref: HTMLElement;
+    [key: string]: unknown;
+}
+
+/**
+ * LLM configuration
+ */
+declare interface LLMConfig {
+    baseURL: string;
+    model: string;
+    apiKey?: string;
+    /**
+     * @deprecated No longer a standard parameter; many models reject it outright.
+     * Use `transformRequestBody` to set it only for models you've verified.
+     */
+    temperature?: number;
+    maxRetries?: number;
+    /**
+     * Transform the final request body before sending it to the provider.
+     * Use this to implement provider-specific request tweaks such as caching hints or custom flags.
+     *
+     * Return a new object, or mutate the input object and return undefined.
+     */
+    transformRequestBody?: (requestBody: Record<string, unknown>) => Record<string, unknown> | undefined;
+    /**
+     * remove the tool_choice field from the request.
+     * @note fix "Invalid tool_choice type: 'object'" for some LLMs.
+     */
+    disableNamedToolChoice?: boolean;
+    /**
+     * Custom fetch function for LLM API requests.
+     * Use this to customize headers, credentials, proxy, etc.
+     * The response should follow OpenAI API format.
+     */
+    customFetch?: typeof globalThis.fetch;
+}
+
+declare const locales: {
+    readonly 'en-US': {
+        readonly ui: {
+            readonly panel: {
+                readonly ready: "Ready";
+                readonly thinking: "Thinking...";
+                readonly taskInput: "Enter new task, describe steps in detail, press Enter to submit";
+                readonly userAnswerPrompt: "Please answer the question above, press Enter to submit";
+                readonly taskTerminated: "Task terminated";
+                readonly taskCompleted: "Task completed";
+                readonly userAnswer: "User answer: {{input}}";
+                readonly question: "Question: {{question}}";
+                readonly waitingPlaceholder: "Waiting for task to start...";
+                readonly stop: "Stop";
+                readonly close: "Close";
+                readonly expand: "Expand history";
+                readonly collapse: "Collapse history";
+                readonly step: "Step {{number}}";
+                readonly userTakeover: "User takeover";
+                readonly retrying: "Retrying";
+                readonly errorLabel: "Error";
+                readonly reflectionEvaluation: "Assessment";
+                readonly reflectionMemory: "Memory";
+                readonly reflectionNextGoal: "Next goal";
+                readonly authorPerson: "You";
+                readonly authorAgent: "Agent";
+                readonly authorReasoning: "Reasoning";
+                readonly authorAction: "Action";
+                readonly authorResult: "Result";
+                readonly authorPage: "Page";
+                readonly authorSystem: "System";
+                readonly historyLabel: "Agent activity history";
+                readonly panelLabel: "Agent panel";
+            };
+            readonly tools: {
+                readonly clicking: "Clicking element [{{index}}]...";
+                readonly inputting: "Inputting text to element [{{index}}]...";
+                readonly selecting: "Selecting option \"{{text}}\"...";
+                readonly scrolling: "Scrolling page...";
+                readonly waiting: "Waiting {{seconds}} seconds...";
+                readonly askingUser: "Asking user...";
+                readonly done: "Task done";
+                readonly clicked: "Clicked element [{{index}}]";
+                readonly inputted: "Inputted text \"{{text}}\"";
+                readonly selected: "Selected option \"{{text}}\"";
+                readonly scrolled: "Page scrolled";
+                readonly waited: "Wait completed";
+                readonly executing: "Executing {{toolName}}...";
+                readonly resultSuccess: "success";
+                readonly resultFailure: "failed";
+                readonly resultError: "error";
+            };
+            readonly errors: {
+                readonly elementNotFound: "No interactive element found at index {{index}}";
+                readonly taskRequired: "Task description is required";
+                readonly executionFailed: "Task execution failed";
+                readonly notInputElement: "Element is not an input or textarea";
+                readonly notSelectElement: "Element is not a select element";
+                readonly optionNotFound: "Option \"{{text}}\" not found";
+            };
+        };
+    };
+    readonly 'pt-BR': {
+        readonly ui: {
+            readonly panel: {
+                readonly ready: "Pronto";
+                readonly thinking: "Pensando...";
+                readonly taskInput: "Descreva a próxima tarefa com os passos em detalhe e tecle Enter";
+                readonly userAnswerPrompt: "Responda à pergunta acima e tecle Enter";
+                readonly taskTerminated: "Tarefa interrompida";
+                readonly taskCompleted: "Tarefa concluída";
+                readonly userAnswer: "Resposta: {{input}}";
+                readonly question: "Pergunta: {{question}}";
+                readonly waitingPlaceholder: "Aguardando o início da tarefa...";
+                readonly stop: "Parar";
+                readonly close: "Fechar";
+                readonly expand: "Abrir histórico";
+                readonly collapse: "Fechar histórico";
+                readonly step: "Passo {{number}}";
+                readonly userTakeover: "A pessoa assumiu o controle";
+                readonly retrying: "Tentando de novo";
+                readonly errorLabel: "Erro";
+                readonly reflectionEvaluation: "Avaliação";
+                readonly reflectionMemory: "Memória";
+                readonly reflectionNextGoal: "Próximo passo";
+                readonly authorPerson: "Você";
+                readonly authorAgent: "Agente";
+                readonly authorReasoning: "Raciocínio";
+                readonly authorAction: "Ação";
+                readonly authorResult: "Resultado";
+                readonly authorPage: "Página";
+                readonly authorSystem: "Sistema";
+                readonly historyLabel: "Histórico de atividade do agente";
+                readonly panelLabel: "Painel do agente";
+            };
+            readonly tools: {
+                readonly clicking: "Clicando no elemento [{{index}}]...";
+                readonly inputting: "Digitando no elemento [{{index}}]...";
+                readonly selecting: "Escolhendo a opção \"{{text}}\"...";
+                readonly scrolling: "Rolando a página...";
+                readonly waiting: "Aguardando {{seconds}} segundos...";
+                readonly askingUser: "Perguntando à pessoa...";
+                readonly done: "Tarefa encerrada";
+                readonly clicked: "Elemento [{{index}}] clicado";
+                readonly inputted: "Texto \"{{text}}\" digitado";
+                readonly selected: "Opção \"{{text}}\" escolhida";
+                readonly scrolled: "Página rolada";
+                readonly waited: "Espera concluída";
+                readonly executing: "Executando {{toolName}}...";
+                readonly resultSuccess: "sucesso";
+                readonly resultFailure: "falha";
+                readonly resultError: "erro";
+            };
+            readonly errors: {
+                readonly elementNotFound: "Nenhum elemento interativo no índice {{index}}";
+                readonly taskRequired: "A descrição da tarefa é obrigatória";
+                readonly executionFailed: "A execução da tarefa falhou";
+                readonly notInputElement: "O elemento não é um campo de texto";
+                readonly notSelectElement: "O elemento não é uma lista de seleção";
+                readonly optionNotFound: "Opção \"{{text}}\" não encontrada";
+            };
+        };
+    };
+};
+
+/**
+ * MacroTool input structure
+ *
+ * This is the core abstraction that enforces the "reflection-before-action" mental model.
+ * Before executing any action, the LLM must output its reasoning state.
+ */
+export declare interface MacroToolInput extends Partial<AgentReflection> {
+    action: Record<string, any>;
+}
+
+/**
+ * MacroTool output structure
+ */
+export declare interface MacroToolResult {
+    input: MacroToolInput;
+    output: string;
+}
+
+export declare function mountWidget(options?: WidgetOptions): Widget;
+
+/**
+ * Persistent observation event (stays in memory)
+ */
+export declare interface ObservationEvent {
+    type: 'observation';
+    content: string;
+}
+
+export declare class PageAgent extends PageAgentCore {
+    panel: Panel;
+    constructor(config: PageAgentConfig);
+}
+
+export declare type PageAgentConfig = AgentConfig & PageControllerConfig & Omit<PanelConfig, 'language'>;
+
+/**
+ * AI agent for browser automation.
+ *
+ * @remarks
+ * ## Re-act Agent Loop
+ * - step
+ *    - observe (gather information about current environment and context)
+ *    - think (LLM calling)
+ *      - reflection (evaluate history, generate memory, short-term planning)
+ *      - action (give the action to approach the next goal)
+ *    - act (execute the action)
+ * - loop
+ *
+ * ## Event System
+ * - `statuschange` - Agent status transitions (idle → running → completed/error/stopped)
+ * - `historychange` - History events updated (persistent, part of agent memory)
+ * - `activity` - Real-time activity feedback (transient, for UI only)
+ * - `dispose` - Agent cleanup triggered
+ *
+ * ## Information Streams
+ * 1. **History Events** (`history` array)
+ *    - Persistent event stream that forms agent's memory
+ *    - Included in LLM context across steps
+ *    - Types: steps, observations, user takeovers, llm errors
+ *
+ * 2. **Activity Events** (via `activity` event)
+ *    - Transient UI feedback during task execution
+ *    - NOT included in LLM context
+ *    - Types: thinking, executing, executed, retrying, error
+ */
+export declare class PageAgentCore extends EventTarget {
+    #private;
+    readonly id: string;
+    readonly config: PageAgentCoreConfig & {
+        maxSteps: number;
+    };
+    readonly tools: typeof tools;
+    /** PageController for DOM operations */
+    readonly pageController: PageController;
+    task: string;
+    taskId: string;
+    /** History events */
+    history: HistoricalEvent[];
+    /** Whether this agent has been disposed */
+    disposed: boolean;
+    /**
+     * Called when the agent needs to ask the user questions.
+     * If unset, the `ask_user` tool will be disabled.
+     * Implementations should reject the promise when `signal` aborts.
+     * @example onAskUser: (q) => window.prompt(q) || ''
+     */
+    onAskUser?: (question: string, options?: {
+        signal: AbortSignal;
+    }) => Promise<string>;
+    constructor(config: PageAgentCoreConfig);
+    /** Get current agent status */
+    get status(): AgentStatus;
+    /** Result of the most recent run, or `null` before the first run completes. */
+    get lastResult(): ExecutionResult | null;
+    /* Excluded from this release type: pushObservation */
+    /**
+     * Stop the current task and wait until the run has fully settled (including lifecycle hooks).
+     * @note never await .stop() in a lifecycle hook.
+     */
+    stop(): Promise<void>;
+    /**
+     * external errors (pre-checks/config/hooks) will threw;
+     * agent errors will be caught and added to history, and return a failed result
+     */
+    execute(task: string): Promise<ExecutionResult>;
+    dispose(): void;
+}
+
+export declare type PageAgentCoreConfig = AgentConfig & {
+    pageController: PageController;
+};
+
+/** `window.PageAgent` na build IIFE (CDN): a classe com `mountWidget` e `createVoice` anexados. */
+export declare type PageAgentGlobal = typeof PageAgent & {
+    mountWidget: typeof mountWidget;
+    createVoice: typeof createVoice;
+};
+
+/**
+ * Internal tool definition that has access to PageAgent `this` context
+ */
+export declare interface PageAgentTool<TParams = any> {
+    description: string;
+    inputSchema: z.ZodType<TParams>;
+    execute: (this: PageAgentCore, args: TParams, ctx: ToolContext) => Promise<string>;
+}
+
+/**
+ * PageController manages DOM state and element interactions.
+ * It provides async methods for all DOM operations, keeping state isolated.
+ *
+ * @lifecycle
+ * - beforeUpdate: Emitted before the DOM tree is updated.
+ * - afterUpdate: Emitted after the DOM tree is updated.
+ */
+declare class PageController extends EventTarget {
+    private config;
+    /** Corresponds to eval_page in browser-use */
+    private flatTree;
+    /**
+     * All highlighted index-mapped interactive elements
+     * Corresponds to DOMState.selector_map in browser-use
+     */
+    private selectorMap;
+    /** Index -> element text description mapping */
+    private elementTextMap;
+    /**
+     * Simplified HTML for LLM consumption.
+     * Corresponds to clickable_elements_to_string in browser-use
+     */
+    private simplifiedHTML;
+    /** last time the tree was updated */
+    private lastTimeUpdate;
+    /** Whether the tree has been indexed at least once */
+    private isIndexed;
+    /** Visual mask overlay for blocking user interaction during automation */
+    private mask;
+    private maskReady;
+    constructor(config?: PageControllerConfig);
+    /**
+     * FORK: expõe, somente leitura, a árvore achatada da última `updateTree()`.
+     * O perfilador da página precisa descrever os mesmos elementos que o agente vê, e `flatTree`
+     * é privado (o pacote nem exporta o namespace `dom`). O campo continua privado: quem lê
+     * não pode substituir a árvore do agente. Ver vendor/UPSTREAM.md.
+     */
+    readFlatTree(): FlatDomTree | null;
+    /**
+     * FORK: expõe, somente leitura, o mapa índice -> elemento interativo da última `updateTree()`.
+     * Mesmo motivo de `readFlatTree()`; o tipo `ReadonlyMap` impede `set`/`delete` por quem lê.
+     */
+    readSelectorMap(): ReadonlyMap<number, InteractiveElementDomNode>;
+    /**
+     * Initialize mask asynchronously (dynamic import to avoid CSS loading in Node)
+     */
+    initMask(): void;
+    /**
+     * Get current page URL
+     */
+    getCurrentUrl(): Promise<string>;
+    /**
+     * Get last tree update timestamp
+     */
+    getLastUpdateTime(): Promise<number>;
+    /**
+     * Get structured browser state for LLM consumption.
+     * Automatically calls updateTree() to refresh the DOM state.
+     */
+    getBrowserState(): Promise<BrowserState>;
+    /**
+     * Update DOM tree, returns simplified HTML for LLM.
+     * This is the main method to refresh the page state.
+     * Automatically bypasses mask during DOM extraction if enabled.
+     */
+    updateTree(): Promise<string>;
+    /**
+     * Clean up all element highlights
+     */
+    cleanUpHighlights(): Promise<void>;
+    /**
+     * Ensure the tree has been indexed before any index-based operation.
+     * Throws if updateTree() hasn't been called yet.
+     */
+    private assertIndexed;
+    /**
+     * Click element by index
+     */
+    clickElement(index: number): Promise<ActionResult>;
+    /**
+     * Input text into element by index
+     */
+    inputText(index: number, text: string): Promise<ActionResult>;
+    /**
+     * Select dropdown option by index and option text
+     */
+    selectOption(index: number, optionText: string): Promise<ActionResult>;
+    /**
+     * Scroll vertically
+     */
+    scroll(options: {
+        down: boolean;
+        numPages: number;
+        pixels?: number;
+        index?: number;
+    }): Promise<ActionResult>;
+    /**
+     * Scroll horizontally
+     */
+    scrollHorizontally(options: {
+        right: boolean;
+        pixels: number;
+        index?: number;
+    }): Promise<ActionResult>;
+    /**
+     * Execute arbitrary JavaScript on the page.
+     * The optional `signal` is exposed to the script scope so cooperative code
+     * can abort promptly when the task is stopped.
+     */
+    executeJavascript(script: string, signal?: AbortSignal): Promise<ActionResult>;
+    /**
+     * Show the visual mask overlay.
+     * Only works after mask is setup.
+     */
+    showMask(): Promise<void>;
+    /**
+     * Hide the visual mask overlay.
+     * Only works after mask is setup.
+     */
+    hideMask(): Promise<void>;
+    /**
+     * Dispose and clean up resources
+     */
+    dispose(): void;
+}
+
+/**
+ * Configuration for PageController
+ */
+declare interface PageControllerConfig extends dom.DomConfig {
+    /** Enable visual mask overlay during operations (default: false) */
+    enableMask?: boolean;
+}
+
+/**
+ * Agent control panel
+ *
+ * Architecture:
+ * - History list: renders directly from agent.history (historical events)
+ * - Header bar: shows activity events (transient state) and agent status
+ *
+ * This separation ensures data consistency - history is the single source of truth
+ * for what has been done, while activity shows what is happening now.
+ */
+declare class Panel {
+    #private;
+    get wrapper(): HTMLElement;
+    /**
+     * Create a Panel bound to an agent
+     * @param agent - Agent instance that implements PanelAgentAdapter
+     * @param config - Optional panel configuration
+     */
+    constructor(agent: PanelAgentAdapter, config?: PanelConfig);
+    show(): void;
+    hide(): void;
+    reset(): void;
+    expand(): void;
+    collapse(): void;
+    /**
+     * Dispose panel and clean up event listeners
+     */
+    dispose(): void;
+}
+
+/**
+ * Minimal interface that Panel expects from an agent.
+ * Panel does not depend on PageAgent directly - it only requires this interface.
+ * This enables decoupling and allows any agent implementation to work with Panel.
+ *
+ * Events:
+ * - 'statuschange': Agent status changed
+ * - 'historychange': Historical events updated (persisted)
+ * - 'activity': Transient activity for immediate UI feedback (thinking/executing/etc)
+ * - 'dispose': Agent is being disposed
+ */
+declare interface PanelAgentAdapter extends EventTarget {
+    /** Current agent status */
+    readonly status: 'idle' | 'running' | 'completed' | 'error' | 'stopped';
+    /** Result of the most recent run, or `null` before the first run completes */
+    readonly lastResult: {
+        success: boolean;
+    } | null;
+    /** History of agent events */
+    readonly history: readonly {
+        type: 'step' | 'observation' | 'user_takeover' | 'retry' | 'error';
+        stepIndex?: number;
+        /** For 'step' type */
+        reflection?: {
+            evaluation_previous_goal?: string;
+            memory?: string;
+            next_goal?: string;
+        };
+        /** For 'step' type */
+        action?: {
+            name: string;
+            input: unknown;
+            output: string;
+        };
+        /** For 'observation' type */
+        content?: string;
+        /** For 'retry' type */
+        attempt?: number;
+        maxAttempts?: number;
+        /** For 'retry' and 'error' types */
+        message?: string;
+    }[];
+    /** Current task being executed */
+    readonly task: string;
+    /**
+     * Called when the agent needs to ask the user questions.
+     * If unset, the `ask_user` tool will be disabled.
+     * Panel will set this to handle user questions via its UI.
+     * The optional `signal` aborts when the task is stopped or disposed.
+     */
+    onAskUser?: (question: string, options?: {
+        signal: AbortSignal;
+    }) => Promise<string>;
+    /** Execute a task */
+    execute(task: string): Promise<unknown>;
+    /** Stop the current task (agent remains reusable) */
+    stop(): Promise<void>;
+    /** Dispose the agent (terminal, cannot be reused) */
+    dispose(): void;
+}
+
+/**
+ * Panel configuration
+ */
+declare interface PanelConfig {
+    /**
+     * FORK: aceita qualquer língua do núcleo, inclusive uma que o painel não traduza. O I18n já
+     * cai em 'en-US' nesse caso, e recusar no tipo obrigaria o chamador a converter sem ganho.
+     */
+    language?: SupportedLanguage_2 | 'en-US' | 'zh-CN' | 'pt-BR';
+    /**
+     * Whether to prompt for next task after task completion
+     * @default true
+     */
+    promptForNextTask?: boolean;
+}
+
+declare function resolveViewportExpansion(viewportExpansion?: number): number;
+
+/**
+ * Retry event - LLM call is being retried
+ */
+export declare interface RetryEvent {
+    type: 'retry';
+    message: string;
+    attempt: number;
+    maxAttempts: number;
+}
+
+/** Supported UI languages */
+export declare type SupportedLanguage = 'en-US' | 'zh-CN' | 'pt-BR';
+
+declare type SupportedLanguage_2 = keyof typeof locales;
+
+declare interface TextDomNode {
+    type: 'TEXT_NODE';
+    text: string;
+    isVisible: boolean;
+    [key: string]: unknown;
+}
+
+export declare function tool<TParams>(options: PageAgentTool<TParams>): PageAgentTool<TParams>;
+
+/**
+ * Per-invocation context passed to every tool execution.
+ * Tools MUST honor `signal` to support cooperative cancellation.
+ */
+export declare interface ToolContext {
+    signal: AbortSignal;
+}
+
+/**
+ * Internal tools for PageAgent.
+ * Note: Using any to allow different parameter types for each tool
+ */
+declare const tools: Map<string, PageAgentTool<any>>;
+
+/**
+ * elementsToString 内部使用的类型
+ */
+declare interface TreeNode {
+    type: 'text' | 'element';
+    parent: TreeNode | null;
+    children: TreeNode[];
+    isVisible: boolean;
+    text?: string;
+    tagName?: string;
+    attributes?: Record<string, string>;
+    isInteractive?: boolean;
+    isTopElement?: boolean;
+    isNew?: boolean;
+    highlightIndex?: number;
+    extra?: Record<string, any>;
+}
+
+/**
+ * User takeover event
+ */
+export declare interface UserTakeoverEvent {
+    type: 'user_takeover';
+}
+
+export declare interface Voice {
+    /** O que o navegador realmente oferece. A UI usa isto para mostrar/ocultar controles. */
+    readonly supported: {
+        input: boolean;
+        output: boolean;
+    };
+    /**
+     * Escuta uma vez e resolve com a transcrição final. Rejeita em erro real; resolve com ""
+     * quando o usuário não fala nada ('no-speech') — não é falha, é "nada foi dito".
+     */
+    listen(): Promise<string>;
+    /** Interrompe a escuta em andamento. */
+    stopListening(): void;
+    /** Fala um texto. `interrupt` corta o que estiver sendo dito antes de começar. */
+    speak(text: string, opts?: {
+        interrupt?: boolean;
+    }): void;
+    /** Para a síntese em andamento. */
+    stopSpeaking(): void;
+    /** Observa transições de estado (a UI mostra o indicador de "ouvindo/falando"). */
+    onStatus(cb: (status: VoiceStatus) => void): () => void;
+}
+
+export declare interface VoiceOptions {
+    /** Idioma BCP-47 do reconhecimento e da síntese. @default 'pt-BR' */
+    lang?: string;
+    /** Habilita o reconhecimento de fala (botão de microfone). @default true */
+    input?: boolean;
+    /** Habilita a síntese de fala (agente fala o resultado). @default false */
+    output?: boolean;
+    /** URI de uma voz específica do speechSynthesis (deixa o módulo escolher quando ausente). */
+    voiceURI?: string;
+    /** Velocidade da síntese (0.1–10). @default 1 */
+    rate?: number;
+    /** Tom da síntese (0–2). @default 1 */
+    pitch?: number;
+    /** Trava de segurança para `listen()`: ms até rejeitar se o reconhecimento não terminar. @default 30000 */
+    listenTimeoutMs?: number;
+}
+
+/**
+ * FORK: módulo de voz do widget. Zero dependências — usa apenas a Web Speech API nativa do
+ * navegador (reconhecimento + síntese), o que mantém o bundle leve e funciona offline/sem rede
+ * além das chamadas do próprio agente.
+ *
+ * Filosofia (regras do laboratório):
+ * - Degrada sem quebrar: se o navegador não tem mic nem síntese, `supported` informa e os
+ *   métodos viram no-op silenciosos — a UI decide esconder os botões, o agente segue funcionando.
+ * - Espera por condição, nunca por relógio: `listen()` resolve quando chega o resultado final;
+ *   o timeout é só uma trava de segurança contra um reconhecimento que "prende" a UI.
+ * - Nada de rede própria: o reconhecimento/síntese são do navegador (Chrome/Edge/Safari enviam
+ *   apenas o áudio necessário para o serviço de voz do SO; em rede limitada isso é mínimo).
+ */
+declare type VoiceStatus = 'idle' | 'listening' | 'speaking';
+
+export declare interface Widget {
+    /** Agente centralizado (mesma instância que o painel controla). `null` até a primeira abertura. */
+    readonly agent: PageAgent | null;
+    /** Voz centralizada (reconhecimento + síntese). `null` até a primeira abertura. */
+    readonly voice: Voice | null;
+    /** Posição do botão-lançador. */
+    readonly launcher: HTMLElement;
+    /** Garante config (busca o `configUrl`) + voz + agente prontos. Idempotente; devolve o agente. */
+    ready(): Promise<PageAgent>;
+    /** Executa uma tarefa programaticamente. */
+    run(task: string): Promise<ExecutionResult>;
+    /** Para a tarefa em andamento (o agente segue reutilizável). */
+    stop(): Promise<void>;
+    /** Abre o painel (propaga erro de config). `hide()`/`toggle()` para fechar/alternar. */
+    show(): Promise<void>;
+    hide(): void;
+    toggle(): void;
+    /** Atualiza config em runtime (recria o agente quando muda algo de LLM/agente). */
+    setConfig(patch: Partial<WidgetOptions>): void;
+    /** Remove launcher, painel e voz da página. */
+    unmount(): void;
+}
+
+export declare interface WidgetOptions {
+    /** Modelo. Ex.: "gpt-4o-mini". */
+    model?: string;
+    /** Endpoint OpenAI-compatible. */
+    baseURL?: string;
+    /**
+     * Chave da API. Só para uso local/sem gateway (ex.: laboratório). Em produção, prefira
+     * `configUrl` + gateway: a chave fica no servidor e não aparece no front-end.
+     */
+    apiKey?: string;
+    /**
+     * URL de uma config pública servida pelo gateway do projeto (ex.: "/api/agent/config").
+     * O widget busca model/idioma/passos/voz DE LÁ — o front nunca precisa da chave. O gateway
+     * é a autoridade: ele injeta a `apiKey` no servidor e força o modelo configurado.
+     */
+    configUrl?: string;
+    /** Customiza o corpo da request (providers específicos). */
+    transformRequestBody?: PageAgentConfig['transformRequestBody'];
+    /** `fetch` custom (proxy, credentials, baixa latência). */
+    customFetch?: PageAgentConfig['customFetch'];
+    maxRetries?: number;
+    /** Idioma da interface e do raciocínio. @default 'pt-BR' */
+    language?: PageAgentConfig['language'];
+    /** Máximo de passos por tarefa. @default 30 */
+    maxSteps?: number;
+    /** Instruções globais/por página. */
+    instructions?: PageAgentConfig['instructions'];
+    /** Ferramentas customizadas. */
+    customTools?: PageAgentConfig['customTools'];
+    /** Máscula sobre a página durante a execução. @default true */
+    enableMask?: boolean;
+    /** Expansão da viewport ao enumerar elementos. @default 0 (só o que está visível) */
+    viewportExpansion?: number;
+    /** Pergunta pela próxima tarefa ao concluir. @default true */
+    promptForNextTask?: boolean;
+    /** Posição do botão-lançador. @default 'bottom-right' */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** Rótulo acessível do botão-lançador. @default 'Abrir assistente da página' */
+    launcherLabel?: string;
+    /** Começa com o painel aberto (em vez de só o botão). @default false */
+    open?: boolean;
+    voice?: WidgetVoiceOptions;
+}
+
+export declare interface WidgetVoiceOptions extends VoiceOptions {
+    /** Fala o resultado quando a tarefa termina (requer `output: true`). @default true */
+    speakOnComplete?: boolean;
+    /** Fala o próximo objetivo a cada passo (mais falante; útil para mãos-livres). @default false */
+    speakSteps?: boolean;
+}
+
+export { }