@coolkiller007/my-page-agent 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,873 @@
+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;
+};
+
+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 AgentTool
+     *
+     * @example
+     * // override internal tool
+     * import { z } from 'zod/v4'
+     * import { tool } from '@coolkiller007/my-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, AgentTool | 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 AgentRuntime instance
+     * @param stepCount - Current step number (0-indexed)
+     */
+    onBeforeStep?: (agent: AgentRuntime, stepCount: number) => Promise<void> | void;
+    /**
+     * Called after each step execution.
+     * @experimental
+     * @param agent - The AgentRuntime instance
+     * @param history - Current history of events
+     */
+    onAfterStep?: (agent: AgentRuntime, history: HistoricalEvent[]) => Promise<void> | void;
+    /**
+     * Called before task execution starts.
+     * @experimental
+     * @param agent - The AgentRuntime instance
+     */
+    onBeforeTask?: (agent: AgentRuntime) => Promise<void> | void;
+    /**
+     * Called after task execution completes (success or failure).
+     * @experimental
+     * @param agent - The AgentRuntime instance
+     * @param result - The execution result
+     */
+    onAfterTask?: (agent: AgentRuntime, 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 AgentRuntime instance
+     * @param reason - Optional reason for disposal
+     */
+    onDispose?: (agent: AgentRuntime, 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
+ */
+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?
+ */
+declare interface AgentReflection {
+    evaluation_previous_goal: string;
+    memory: string;
+    next_goal: string;
+}
+
+/**
+ * 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
+ */
+declare class AgentRuntime extends EventTarget {
+    #private;
+    readonly id: string;
+    readonly config: AgentRuntimeConfig & {
+        maxSteps: number;
+    };
+    readonly tools: typeof tools;
+    /** BrowserController for DOM operations */
+    readonly browserController: BrowserController;
+    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: AgentRuntimeConfig);
+    /** 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;
+}
+
+declare type AgentRuntimeConfig = AgentConfig & {
+    browserController: BrowserController;
+};
+
+/**
+ * Agent lifecycle status.
+ */
+export declare type AgentStatus = 'idle' | 'running' | 'completed' | 'error' | 'stopped';
+
+/**
+ * A single agent step with reflection and action
+ */
+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;
+}
+
+/**
+ * Internal tool definition that has access to PageAgent `this` context
+ */
+declare interface AgentTool<TParams = any> {
+    description: string;
+    inputSchema: z.ZodType<TParams>;
+    execute: (this: AgentRuntime, args: TParams, ctx: ToolContext) => Promise<string>;
+}
+
+/**
+ * BrowserController 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 BrowserController 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;
+    private disposed;
+    constructor(config?: BrowserControllerConfig);
+    /**
+     * 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 BrowserController
+ */
+declare interface BrowserControllerConfig extends dom.DomConfig {
+    /** Enable visual mask overlay during operations (default: false) */
+    enableMask?: boolean;
+}
+
+/**
+ * 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 createAgent(config: MyPageAgentConfig): MyPageAgent;
+
+declare namespace dom {
+    export {
+        resolveViewportExpansion,
+        getFlatTree,
+        flatTreeToString,
+        getSelectorMap,
+        getElementTextMap,
+        cleanUpHighlights,
+        BrowserState,
+        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 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 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 'zh-CN': {
+        readonly ui: {
+            readonly ready: "准备就绪";
+            readonly thinking: "正在思考...";
+            readonly taskInput: "输入新任务，详细描述步骤，回车提交";
+            readonly userAnswerPrompt: "请回答上面问题，回车提交";
+            readonly taskTerminated: "任务已终止";
+            readonly taskCompleted: "任务结束";
+            readonly userAnswer: "用户回答: {{input}}";
+            readonly question: "询问: {{question}}";
+            readonly waitingPlaceholder: "等待任务开始...";
+            readonly stop: "终止";
+            readonly close: "关闭";
+            readonly expand: "展开历史";
+            readonly collapse: "收起历史";
+            readonly step: "步骤 {{number}}";
+            readonly tools: {
+                readonly clicking: "正在点击元素 [{{index}}]...";
+                readonly inputting: "正在输入文本到元素 [{{index}}]...";
+                readonly selecting: "正在选择选项 \"{{text}}\"...";
+                readonly scrolling: "正在滚动页面...";
+                readonly waiting: "等待 {{seconds}} 秒...";
+                readonly askingUser: "正在询问用户...";
+                readonly done: "结束任务";
+                readonly clicked: "🖱️ 已点击元素 [{{index}}]";
+                readonly inputted: "⌨️ 已输入文本 \"{{text}}\"";
+                readonly selected: "☑️ 已选择选项 \"{{text}}\"";
+                readonly scrolled: "🛞 页面滚动完成";
+                readonly waited: "⌛️ 等待完成";
+                readonly executing: "正在执行 {{toolName}}...";
+                readonly resultSuccess: "成功";
+                readonly resultFailure: "失败";
+                readonly resultError: "错误";
+            };
+            readonly errors: {
+                readonly elementNotFound: "未找到索引为 {{index}} 的交互元素";
+                readonly taskRequired: "任务描述不能为空";
+                readonly executionFailed: "任务执行失败";
+                readonly notInputElement: "元素不是输入框或文本域";
+                readonly notSelectElement: "元素不是选择框";
+                readonly optionNotFound: "未找到选项 \"{{text}}\"";
+            };
+        };
+    };
+};
+
+export declare class MyPageAgent extends AgentRuntime {
+    readonly ui: UI;
+    constructor(config: MyPageAgentConfig);
+}
+
+export declare type MyPageAgentConfig = Omit<AgentConfig, 'experimentalScriptExecutionTool'> & BrowserControllerConfig & Omit<UIConfig, 'language'>;
+
+/**
+ * Persistent observation event (stays in memory)
+ */
+declare interface ObservationEvent {
+    type: 'observation';
+    content: string;
+}
+
+declare function resolveViewportExpansion(viewportExpansion?: number): number;
+
+/**
+ * Retry event - LLM call is being retried
+ */
+declare interface RetryEvent {
+    type: 'retry';
+    message: string;
+    attempt: number;
+    maxAttempts: number;
+}
+
+/** Supported UI languages */
+declare type SupportedLanguage = 'en-US' | 'zh-CN';
+
+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: AgentTool<TParams>): AgentTool<TParams>;
+
+/**
+ * Per-invocation context passed to every tool execution.
+ * Tools MUST honor `signal` to support cooperative cancellation.
+ */
+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, AgentTool<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>;
+}
+
+/**
+ * Agent control UI
+ *
+ * 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 UI {
+    #private;
+    get wrapper(): HTMLElement;
+    /**
+     * Create a UI bound to an agent
+     * @param agent - Agent instance that implements UIAdapter
+     * @param config - Optional UI configuration
+     */
+    constructor(agent: UIAdapter, config?: UIConfig);
+    show(): void;
+    hide(): void;
+    reset(): void;
+    expand(): void;
+    collapse(): void;
+    /**
+     * Dispose UI and clean up event listeners
+     */
+    dispose(): void;
+}
+
+/**
+ * Minimal interface that UI expects from an agent.
+ * UI does not depend on PageAgent directly - it only requires this interface.
+ * This enables decoupling and allows any agent implementation to work with UI.
+ *
+ * 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 UIAdapter 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.
+     * UI 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;
+}
+
+/**
+ * UI configuration
+ */
+declare interface UIConfig {
+    language?: SupportedLanguage_2;
+    /**
+     * Whether to prompt for next task after task completion
+     * @default true
+     */
+    promptForNextTask?: boolean;
+}
+
+/**
+ * User takeover event
+ */
+declare interface UserTakeoverEvent {
+    type: 'user_takeover';
+}
+
+export { }