chore(version): bump version to 1.2.0

chore(deps): bump the production-dependencies group with 2 updates

.gitignore

@@ -36,4 +36,11 @@ packages/page-agent/LICENSE
 
 # extension
 .output
-.wxt
+.wxt
+
+# AI
+.agent
+.claude
+.cursor
+.gemini
+CLAUDE.md

.vscode/settings.json

@@ -1,20 +1,25 @@
 {
-    "editor.fontLigatures": true,
     "cSpell.words": [
         "deepseek",
         "historychange",
         "HITL",
         "innerhtml",
+        "languagedetector",
         "llms",
+        "magicui",
         "npmmirror",
         "onwarn",
         "opensource",
         "qwen",
         "retryable",
         "shadcn",
+        "sidepanel",
         "statuschange",
         "wouter"
     ],
+    "files.exclude": {
+        "packages/*/node_modules": true,
+    },
     "markdownlint.config": {
         // "comment": "Relaxed rules",
         "default": true,

AGENTS.md

@@ -5,6 +5,7 @@
 This is a **monorepo** with npm workspaces:
 
 - **Page Agent** (`packages/page-agent/`) - Main entry with built-in UI Panel, published as `page-agent` on npm
+- **Extension** (`packages/extension/`) - Browser extension (WXT + React) 🚧 WIP
 - **Website** (`packages/website/`) - React docs and landing page. **When working on website, follow `packages/website/AGENTS.md`**
 
 Internal packages:
@@ -35,6 +36,7 @@ packages/
 ├── page-agent/              # npm: "page-agent" entry class (with UI + controller + demo builds)
 ├── website/                 # @page-agent/website (private)
 ├── llms/                    # @page-agent/llms
+├── extension/               # 🚧 WIP: Browser extension (WXT + React)
 ├── page-controller/         # @page-agent/page-controller
 └── ui/                      # @page-agent/ui
 ```
@@ -127,3 +129,5 @@ const pageInfo = await this.pageController.getPageInfo()
 - ESLint relaxes some unsafe rules for rapid iteration
 - Every change you make should not only implement the desired functionality but also improve the quality of the codebase
 - All code and comments must be in English.
+- Do not try to hide errors or risks. They are valuable feedbacks for developers and users. Make them visible and actionable.
+- Traceability and predictability is more important than success rate.

CLAUDE.md

@@ -1 +0,0 @@
-@AGENTS.md

CONTRIBUTING.md

@@ -92,10 +92,28 @@ We use a simplified monorepo solution with `native npm-workspace + ts reference
 ### Vibe coding with AI
 
 - It's **recommended** to heavily rely on AI (aka "vibe coding") when maintaining **demo pages and tests**.
-- BUT **NOT the core lib!!!** Be very careful if AI ever touched the core lib!!!
+- Be very careful if AI ever touched the core lib!!!
 - Review anything AI wrote before make a commit. You are the author of anything you commit. NOT AI.
 - Update the [AI instructions](AGENTS.md) when structure changed.
 
+If your lame AI assistant does not support [AGENTS.md](https://agents.md/). Add an alias for it:
+
+- claude-code (`CLAUDE.md`)
+
+    ```markdown
+    @AGENTS.md
+    ```
+
+- antigravity (`.agent/rules/alias.md`)
+
+    ```markdown
+    ---
+    trigger: always_on
+    ---
+
+    @../../AGENTS.md
+    ```
+
 ## 🔧 Development Workflows
 
 ### Test With Your Own LLM API
@@ -108,6 +126,16 @@ We use a simplified monorepo solution with `native npm-workspace + ts reference
     LLM_BASE_URL=https://api.your-llm-provider.com/v1
     ```
 
+- **Ollama example** (tested on 0.15 + qwen3:14b, RTX3090 24GB):
+
+    ```env
+    LLM_BASE_URL="http://localhost:11434/v1"
+    LLM_API_KEY="NA"
+    LLM_MODEL_NAME="qwen3:14b"
+    ```
+
+    > ⚠️ Add `*` to `OLLAMA_ORIGINS` (403). Models < 10B unlikely strong enough. Requires tool_call support. Set context length > 15k (default 4k will NOT work): `$env:OLLAMA_CONTEXT_LENGTH=64000; ollama serve`
+
 - Restart the dev server to load new env vars
 - If not provided, the demo will the free testing proxy by default
 

README-zh.md

@@ -28,7 +28,7 @@
 
 以及 😉
 
-- **🧪 实验性的 Chrome 扩展，支持跨页面控制** - `-b feat/ext`
+- **🧪 实验性的 Chrome 扩展，支持跨页面控制** - `packages/extension`
 
 👉 [**🗺️ Roadmap**](https://github.com/alibaba/page-agent/issues/96)
 
@@ -40,7 +40,7 @@
 
 ```html
 <script
-    src="https://registry.npmmirror.com/page-agent/1.0.0/files/dist/iife/page-agent.demo.js"
+    src="https://registry.npmmirror.com/page-agent/1.2.0/files/dist/iife/page-agent.demo.js"
     crossorigin="true"
 ></script>
 ```
@@ -48,10 +48,10 @@
 > - **⚠️ 仅用于技术评估。** Demo LLM 有速率和使用限制，可能随时变更。
 > - **🌷 建议使用自己的 LLM API。**
 
-| 镜像   | URL                                                                                       |
+| Mirrors | URL                                                                                |
-| ------ | ----------------------------------------------------------------------------------------- |
+| ------- | ---------------------------------------------------------------------------------- |
-| Global | https://cdn.jsdelivr.net/npm/page-agent@1.0.0/dist/iife/page-agent.demo.js         |
+| Global  | https://cdn.jsdelivr.net/npm/page-agent@1.2.0/dist/iife/page-agent.demo.js         |
-| China  | https://registry.npmmirror.com/page-agent/1.0.0/files/dist/iife/page-agent.demo.js |
+| China   | https://registry.npmmirror.com/page-agent/1.2.0/files/dist/iife/page-agent.demo.js |
 
 ### NPM 安装
 

README.md

@@ -28,7 +28,7 @@ The GUI Agent Living in Your Webpage. Control web interfaces with natural langua
 
 And 😉
 
-- **🧪 `cross-page` control with an experimental chrome extension** - `-b feat/ext`
+- **🧪 `cross-page` control with an experimental chrome extension** - `packages/extension`
 
 👉 [**🗺️ Roadmap**](https://github.com/alibaba/page-agent/issues/96)
 
@@ -40,7 +40,7 @@ Fastest way to try PageAgent with our free Demo LLM:
 
 ```html
 <script
-    src="https://cdn.jsdelivr.net/npm/page-agent@1.0.0/dist/iife/page-agent.demo.js"
+    src="https://cdn.jsdelivr.net/npm/page-agent@1.2.0/dist/iife/page-agent.demo.js"
     crossorigin="true"
 ></script>
 ```
@@ -48,10 +48,10 @@ Fastest way to try PageAgent with our free Demo LLM:
 > - **⚠️ For technical evaluation only.** Demo LLM has rate limits and usage restrictions. May change without notice.
 > - **🌷 Bring your own LLM API.**
 
-| Mirrors | URL                                                                                       |
+| Mirrors | URL                                                                                |
-| ------- | ----------------------------------------------------------------------------------------- |
+| ------- | ---------------------------------------------------------------------------------- |
-| Global  | https://cdn.jsdelivr.net/npm/page-agent@1.0.0/dist/iife/page-agent.demo.js         |
+| Global  | https://cdn.jsdelivr.net/npm/page-agent@1.2.0/dist/iife/page-agent.demo.js         |
-| China   | https://registry.npmmirror.com/page-agent/1.0.0/files/dist/iife/page-agent.demo.js |
+| China   | https://registry.npmmirror.com/page-agent/1.2.0/files/dist/iife/page-agent.demo.js |
 
 ### NPM Installation
 

eslint.config.js

@@ -8,7 +8,13 @@ import globals from 'globals'
 import tseslint from 'typescript-eslint'
 
 export default defineConfig([
-	globalIgnores(['**/dist', '**/node_modules', 'packages/website/src/components/ui']),
+	globalIgnores([
+		'**/dist',
+		'**/node_modules',
+		'packages/*/src/components/ui',
+		'**/.wxt',
+		'**/.output',
+	]),
 	{
 		plugins: {
 			'react-hooks': reactHooks,
@@ -69,6 +75,8 @@ export default defineConfig([
 			'react-dom/no-missing-button-type': 'off',
 			'react-x/no-nested-component-definitions': 'off',
 			'@typescript-eslint/prefer-optional-chain': 'off',
+			'@typescript-eslint/use-unknown-in-catch-callback-variable': 'off',
+			'@typescript-eslint/no-unnecessary-type-parameters': 'off',
 
 			// 'require-await': 'off',
 			'@typescript-eslint/require-await': 'off',

package.json

@@ -1,7 +1,7 @@
 {
     "name": "root",
     "private": true,
-    "version": "1.0.0",
+    "version": "1.2.0",
     "type": "module",
     "workspaces": [
         "packages/page-controller",
@@ -9,6 +9,7 @@
         "packages/llms",
         "packages/core",
         "packages/page-agent",
+        "packages/extension",
         "packages/website"
     ],
     "description": "AI-powered UI agent for web applications",
@@ -20,8 +21,7 @@
     },
     "homepage": "https://alibaba.github.io/page-agent/",
     "engines": {
-        "node": ">=20.0.0",
+        "node": "^20.19.0 || ^22.13.0 || >=24"
-        "npm": ">=10.0.0"
     },
     "scripts": {
         "cleanup": "rm -rf packages/*/dist",
@@ -38,26 +38,30 @@
         "@commitlint/cli": "^20.3.1",
         "@commitlint/config-conventional": "^20.3.1",
         "@eslint/js": "^9.39.2",
-        "@microsoft/api-extractor": "^7.55.2",
+        "@microsoft/api-extractor": "^7.56.3",
+        "@tailwindcss/vite": "^4.1.18",
         "@trivago/prettier-plugin-sort-imports": "^6.0.2",
-        "@types/node": "^25.0.9",
+        "@types/node": "^25.2.2",
+        "@vitejs/plugin-react-swc": "^4.1.0",
+        "chalk": "^5.6.2",
         "concurrently": "^9.2.1",
-        "dotenv": "^17.2.3",
+        "dotenv": "^17.2.4",
         "eslint": "^9.39.2",
         "eslint-config-prettier": "^10.1.8",
-        "eslint-plugin-react-dom": "^2.7.2",
+        "eslint-plugin-react-dom": "^2.12.2",
         "eslint-plugin-react-hooks": "^7.0.1",
-        "eslint-plugin-react-refresh": "^0.4.26",
+        "eslint-plugin-react-refresh": "^0.5.0",
-        "eslint-plugin-react-x": "^2.7.2",
+        "eslint-plugin-react-x": "^2.12.2",
         "globals": "^17.0.0",
         "husky": "^9.1.7",
         "lint-staged": "^16.2.4",
         "prettier": "^3.8.0",
         "typescript": "^5.9.3",
-        "typescript-eslint": "^8.53.1",
+        "typescript-eslint": "^8.55.0",
         "unplugin-dts": "^1.0.0-beta.6",
         "vite": "^7.3.1",
-        "vite-plugin-css-injected-by-js": "^3.5.2"
+        "vite-plugin-css-injected-by-js": "^3.5.2",
+        "vite-bundle-analyzer": "^1.3.6"
     },
     "overrides": {
         "typescript": "^5.9.3"

packages/core/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@page-agent/core",
     "private": false,
-    "version": "1.0.0",
+    "version": "1.2.0",
     "type": "module",
     "main": "./dist/esm/page-agent-core.js",
     "module": "./dist/esm/page-agent-core.js",
@@ -45,7 +45,7 @@
     "dependencies": {
         "chalk": "^5.6.2",
         "zod": "^4.3.5",
-        "@page-agent/llms": "1.0.0",
+        "@page-agent/llms": "1.2.0",
-        "@page-agent/page-controller": "1.0.0"
+        "@page-agent/page-controller": "1.2.0"
     }
 }

packages/core/src/PageAgentCore.ts

@@ -3,15 +3,15 @@
  * All rights reserved.
  */
 import { InvokeError, LLM, type Tool } from '@page-agent/llms'
-import type { PageController } from '@page-agent/page-controller'
+import type { BrowserState, PageController } from '@page-agent/page-controller'
 import chalk from 'chalk'
-import zod from 'zod'
+import * as zod from 'zod'
 
 import { type PageAgentConfig } from './config'
 import { DEFAULT_MAX_STEPS } from './config/constants'
 import SYSTEM_PROMPT from './prompts/system_prompt.md?raw'
 import { tools } from './tools'
-import {
+import type {
 	AgentActivity,
 	AgentReflection,
 	AgentStatus,
@@ -21,17 +21,25 @@ import {
 	MacroToolInput,
 	MacroToolResult,
 } from './types'
-import { normalizeResponse, trimLines, uid, waitFor } from './utils'
+import { assert, normalizeResponse, uid, waitFor } from './utils'
-import { assert } from './utils/assert'
 
 export { type PageAgentConfig }
 export { tool, type PageAgentTool } from './tools'
 export type * from './types'
 
 /**
- * AI agent for browser DOM automation.
+ * 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)
  * - `historychange` - History events updated (persistent, part of agent memory)
@@ -50,15 +58,16 @@ export type * from './types'
  *    - Types: thinking, executing, executed, retrying, error
  */
 export class PageAgentCore extends EventTarget {
-	config: PageAgentConfig & { maxSteps: number }
+	readonly id = uid()
-	id = uid()
+	readonly config: PageAgentConfig & { maxSteps: number }
-	tools: typeof tools
+	readonly tools: typeof tools
-	disposed = false
+	/** PageController for DOM operations */
+	readonly pageController: PageController
+
 	task = ''
 	taskId = ''
-
+	/** History events */
-	/** Agent execution status */
+	history: HistoricalEvent[] = []
-	#status: AgentStatus = 'idle'
 
 	/**
 	 * Callback for when agent needs user input (ask_user tool)
@@ -67,23 +76,21 @@ export class PageAgentCore extends EventTarget {
 	 */
 	onAskUser?: (question: string) => Promise<string>
 
+	#status: AgentStatus = 'idle'
 	#llm: LLM
 	#abortController = new AbortController()
+	#observations: string[] = []
 
-	/** PageController for DOM operations */
+	/** internal states during a single task execution */
-	pageController: PageController
+	#states = {
-
+		/** Accumulated wait time in seconds */
-	/** Runtime states for tracking across steps */
-	states = {
-		/** Accumulated wait time in seconds, used by wait tool */
 		totalWaitTime: 0,
-		/** Last known URL for detecting navigation */
+		/** For detecting navigation */
 		lastURL: '',
+		/** Browser state */
+		browserState: null as BrowserState | null,
 	}
 
-	/** History events */
-	history: HistoricalEvent[] = []
-
 	constructor(config: PageAgentConfig & { pageController: PageController }) {
 		super()
 
@@ -96,7 +103,7 @@ export class PageAgentCore extends EventTarget {
 		// Listen to LLM retry events
 		this.#llm.addEventListener('retry', (e) => {
 			const { attempt, maxAttempts } = (e as CustomEvent).detail
-			this.emitActivity({ type: 'retrying', attempt, maxAttempts })
+			this.#emitActivity({ type: 'retrying', attempt, maxAttempts })
 			// Also push to history for panel rendering
 			this.history.push({
 				type: 'retry',
@@ -108,8 +115,9 @@ export class PageAgentCore extends EventTarget {
 		})
 		this.#llm.addEventListener('error', (e) => {
 			const error = (e as CustomEvent).detail.error as Error | InvokeError
+			if ((error as any)?.rawError?.name === 'AbortError') return
 			const message = String(error)
-			this.emitActivity({ type: 'error', message })
+			this.#emitActivity({ type: 'error', message })
 			// Also push to history for panel rendering
 			this.history.push({
 				type: 'error',
@@ -153,7 +161,7 @@ export class PageAgentCore extends EventTarget {
 	 * Emit activity event - for transient UI feedback
 	 * @param activity - Current agent activity
 	 */
-	emitActivity(activity: AgentActivity): void {
+	#emitActivity(activity: AgentActivity): void {
 		this.dispatchEvent(new CustomEvent('activity', { detail: activity }))
 	}
 
@@ -166,12 +174,13 @@ export class PageAgentCore extends EventTarget {
 	}
 
 	/**
-	 * Push a persistent observation to the history event stream.
+	 * Push a observation message to the history event stream.
-	 * This will be visible in <agent_history> and remain in memory across steps.
+	 * This will be visible in <agent_history> and remain persistent in memory across steps.
+	 * @experimental @internal
+	 * @note history change will be emitted before next step starts
 	 */
 	pushObservation(content: string): void {
-		this.history.push({ type: 'observation', content })
+		this.#observations.push(content)
-		this.#emitHistoryChange()
 	}
 
 	async execute(task: string): Promise<ExecutionResult> {
@@ -203,47 +212,44 @@ export class PageAgentCore extends EventTarget {
 		this.#setStatus('running')
 		this.#emitHistoryChange()
 
-		// Reset states
+		// Reset internal states
-		this.states = {
+		this.#states = { totalWaitTime: 0, lastURL: '', browserState: null }
-			totalWaitTime: 0,
-			lastURL: '',
-		}
 
-		try {
+		let step = 0
-			let step = 0
 
-			while (true) {
+		while (true) {
-				await this.#generateObservations(step)
+			try {
+				console.group(`step: ${step}`)
 
 				await onBeforeStep?.(this, step)
 
-				console.group(`step: ${step}`)
+				// observe
 
-				// abort
+				console.log(chalk.blue.bold('👀 Observing...'))
-				if (this.#abortController.signal.aborted) throw new Error('AbortError')
 
-				// Thinking
+				this.#states.browserState = await this.pageController.getBrowserState()
-				console.log(chalk.blue('Thinking...'))
+				await this.#handleObservations(step)
-				this.emitActivity({ type: 'thinking' })
 
-				const result = await this.#llm.invoke(
+				// assemble prompts
-					[
+
-						{
+				const messages = [
-							role: 'system',
+					{ role: 'system' as const, content: this.#getSystemPrompt() },
-							content: this.#getSystemPrompt(),
+					{ role: 'user' as const, content: await this.#assembleUserPrompt() },
-						},
+				]
-						{
+
-							role: 'user',
+				const tools = { AgentOutput: this.#packMacroTool() }
-							content: await this.#assembleUserPrompt(),
+
-						},
+				// invoke LLM
-					],
+
-					{ AgentOutput: this.#packMacroTool() },
+				console.log(chalk.blue.bold('🧠 Thinking...'))
-					this.#abortController.signal,
+				this.#emitActivity({ type: 'thinking' })
-					{
+
-						toolChoiceName: 'AgentOutput',
+				const result = await this.#llm.invoke(messages, tools, this.#abortController.signal, {
-						normalizeResponse,
+					toolChoiceName: 'AgentOutput',
-					}
+					normalizeResponse,
-				)
+				})
+
+				// assemble history
 
 				const macroResult = result.toolResult as MacroToolResult
 				const input = macroResult.input
@@ -267,30 +273,23 @@ export class PageAgentCore extends EventTarget {
 					action,
 					usage: result.usage,
 					rawResponse: result.rawResponse,
+					rawRequest: result.rawRequest,
 				} as AgentStepEvent)
 				this.#emitHistoryChange()
 
-				console.log(chalk.green('Step finished:'), actionName)
+				//
-				console.groupEnd()
 
 				await onAfterStep?.(this, this.history)
 
-				step++
+				console.groupEnd()
-				if (step > this.config.maxSteps) {
+
-					this.#onDone('Step count exceeded maximum limit', false)
+				// finish task if done
-					const result: ExecutionResult = {
+
-						success: false,
-						data: 'Step count exceeded maximum limit',
-						history: this.history,
-					}
-					await onAfterTask?.(this, result)
-					return result
-				}
 				if (actionName === 'done') {
 					const success = action.input?.success ?? false
 					const text = action.input?.text || 'no text provided'
 					console.log(chalk.green.bold('Task completed'), success, text)
-					this.#onDone(text, success)
+					this.#onDone(success)
 					const result: ExecutionResult = {
 						success,
 						data: text,
@@ -299,19 +298,32 @@ export class PageAgentCore extends EventTarget {
 					await onAfterTask?.(this, result)
 					return result
 				}
+			} catch (error: unknown) {
+				console.groupEnd() // to prevent nested groups
+				console.error('Task failed', error)
+				const errorMessage = String(error)
+				this.#emitActivity({ type: 'error', message: errorMessage })
+				this.#onDone(false)
+				const result: ExecutionResult = {
+					success: false,
+					data: errorMessage,
+					history: this.history,
+				}
+				await onAfterTask?.(this, result)
+				return result
 			}
-		} catch (error: unknown) {
+
-			console.error('Task failed', error)
+			step++
-			const errorMessage = String(error)
+			if (step > this.config.maxSteps) {
-			this.emitActivity({ type: 'error', message: errorMessage })
+				this.#onDone(false)
-			this.#onDone(errorMessage, false)
+				const result: ExecutionResult = {
-			const result: ExecutionResult = {
+					success: false,
-				success: false,
+					data: 'Step count exceeded maximum limit',
-				data: errorMessage,
+					history: this.history,
-				history: this.history,
+				}
+				await onAfterTask?.(this, result)
+				return result
 			}
-			await onAfterTask?.(this, result)
-			return result
 		}
 	}
 
@@ -344,13 +356,13 @@ export class PageAgentCore extends EventTarget {
 		})
 
 		return {
-			description: 'You MUST call this tool every step. Outputs your reflections and next action.',
+			description: 'You MUST call this tool every step!',
 			inputSchema: macroToolSchema as zod.ZodType<MacroToolInput>,
 			execute: async (input: MacroToolInput): Promise<MacroToolResult> => {
 				// abort
 				if (this.#abortController.signal.aborted) throw new Error('AbortError')
 
-				console.log(chalk.blue.bold('MacroTool execute'), input)
+				console.log(chalk.blue.bold('MacroTool input'), input)
 				const action = input.action
 
 				const toolName = Object.keys(action)[0]
@@ -371,12 +383,12 @@ export class PageAgentCore extends EventTarget {
 
 				// Find the corresponding tool
 				const tool = tools.get(toolName)
-				assert(tool, `Tool ${toolName} not found. (@note should have been caught before this!!!)`)
+				assert(tool, `Tool ${toolName} not found`)
 
 				console.log(chalk.blue.bold(`Executing tool: ${toolName}`), toolInput)
 
 				// Emit executing activity
-				this.emitActivity({ type: 'executing', tool: toolName, input: toolInput })
+				this.#emitActivity({ type: 'executing', tool: toolName, input: toolInput })
 
 				const startTime = Date.now()
 
@@ -387,7 +399,7 @@ export class PageAgentCore extends EventTarget {
 				console.log(chalk.green.bold(`Tool (${toolName}) executed for ${duration}ms`), result)
 
 				// Emit executed activity
-				this.emitActivity({
+				this.#emitActivity({
 					type: 'executed',
 					tool: toolName,
 					input: toolInput,
@@ -395,9 +407,11 @@ export class PageAgentCore extends EventTarget {
 					duration,
 				})
 
-				// Reset wait time for non-wait tools
+				// counting wait time
-				if (toolName !== 'wait') {
+				if (toolName === 'wait') {
-					this.states.totalWaitTime = 0
+					this.#states.totalWaitTime += toolInput?.seconds || 0
+				} else {
+					this.#states.totalWaitTime = 0
 				}
 
 				// Return structured result
@@ -413,10 +427,12 @@ export class PageAgentCore extends EventTarget {
 	 * Get system prompt, dynamically replace language settings based on configured language
 	 */
 	#getSystemPrompt(): string {
-		let systemPrompt = SYSTEM_PROMPT
+		if (this.config.customSystemPrompt) {
+			return this.config.customSystemPrompt
+		}
 
 		const targetLanguage = this.config.language === 'zh-CN' ? '中文' : 'English'
-		systemPrompt = systemPrompt.replace(
+		const systemPrompt = SYSTEM_PROMPT.replace(
 			/Default working language: \*\*.*?\*\*/,
 			`Default working language: **${targetLanguage}**`
 		)
@@ -425,17 +441,17 @@ export class PageAgentCore extends EventTarget {
 	}
 
 	/**
-	 * Get instructions from config and format as XML block
+	 * Get instructions from config
 	 */
 	async #getInstructions(): Promise<string> {
 		const { instructions } = this.config
 		if (!instructions) return ''
 
 		const systemInstructions = instructions.system?.trim()
-		const url = await this.pageController.getCurrentUrl()
 		let pageInstructions: string | undefined
 
-		if (instructions.getPageInstructions) {
+		const url = this.#states.browserState?.url || ''
+		if (instructions.getPageInstructions && url) {
 			try {
 				pageInstructions = instructions.getPageInstructions(url)?.trim()
 			} catch (error) {
@@ -463,23 +479,28 @@ export class PageAgentCore extends EventTarget {
 	}
 
 	/**
-	 * Generate observations before each step
+	 * Generate system observations before each step
-	 * - URL change detection
-	 * - Too many steps warning
 	 * @todo loop detection
 	 * @todo console error
 	 */
-	async #generateObservations(stepCount: number): Promise<void> {
+	async #handleObservations(step: number): Promise<void> {
+		// Accumulated wait time warning
+		if (this.#states.totalWaitTime >= 3) {
+			this.pushObservation(
+				`You have waited ${this.#states.totalWaitTime} seconds accumulatively. DO NOT wait any longer unless you have a good reason.`
+			)
+		}
+
 		// Detect URL change
-		const currentURL = await this.pageController.getCurrentUrl()
+		const currentURL = this.#states.browserState?.url || ''
-		if (currentURL !== this.states.lastURL) {
+		if (currentURL !== this.#states.lastURL) {
 			this.pushObservation(`Page navigated to → ${currentURL}`)
-			this.states.lastURL = currentURL
+			this.#states.lastURL = currentURL
 			await waitFor(0.5) // wait for page to stabilize
 		}
 
-		// Warn about remaining steps
+		// Remaining steps warning
-		const remaining = this.config.maxSteps - stepCount
+		const remaining = this.config.maxSteps - step
 		if (remaining === 5) {
 			this.pushObservation(
 				`⚠️ Only ${remaining} steps remaining. Consider wrapping up or calling done with partial results.`
@@ -489,12 +510,25 @@ export class PageAgentCore extends EventTarget {
 				`⚠️ Critical: Only ${remaining} steps left! You must finish the task or call done immediately.`
 			)
 		}
+
+		// Push observations to history and emit
+		if (this.#observations.length > 0) {
+			for (const content of this.#observations) {
+				this.history.push({ type: 'observation', content })
+				console.log(chalk.cyan('Observation:'), content)
+			}
+			this.#observations = []
+			this.#emitHistoryChange()
+		}
 	}
 
 	async #assembleUserPrompt(): Promise<string> {
+		const browserState = this.#states.browserState!
+
 		let prompt = ''
 
 		// <instructions> (optional)
+
 		prompt += await this.#getInstructions()
 
 		// <agent_state>
@@ -504,38 +538,36 @@ export class PageAgentCore extends EventTarget {
 
 		const stepCount = this.history.filter((e) => e.type === 'step').length
 
-		prompt += `<agent_state>
+		prompt += '<agent_state>\n'
-			<user_request>
+		prompt += '<user_request>\n'
-			${this.task}
+		prompt += `${this.task}\n`
-			</user_request>
+		prompt += '</user_request>\n'
-			<step_info>
+		prompt += '<step_info>\n'
-			Step ${stepCount + 1} of ${this.config.maxSteps} max possible steps
+		prompt += `Step ${stepCount + 1} of ${this.config.maxSteps} max possible steps\n`
-			Current date and time: ${new Date().toISOString()}
+		prompt += `Current time: ${new Date().toLocaleString()}\n`
-			</step_info>
+		prompt += '</step_info>\n'
-			</agent_state>
+		prompt += '</agent_state>\n\n'
-		`
 
 		// <agent_history>
 		//  - <step_N> for steps
 		//  - <sys> for observations and system messages
 
-		prompt += '\n<agent_history>\n'
+		prompt += '<agent_history>\n'
 
 		let stepIndex = 0
 		for (const event of this.history) {
 			if (event.type === 'step') {
 				stepIndex++
-				prompt += `<step_${stepIndex}>
+				prompt += `<step_${stepIndex}>\n`
-				Evaluation of Previous Step: ${event.reflection.evaluation_previous_goal}
+				prompt += `Evaluation of Previous Step: ${event.reflection.evaluation_previous_goal}\n`
-				Memory: ${event.reflection.memory}
+				prompt += `Memory: ${event.reflection.memory}\n`
-				Next Goal: ${event.reflection.next_goal}
+				prompt += `Next Goal: ${event.reflection.next_goal}\n`
-				Action Results: ${event.action.output}
+				prompt += `Action Results: ${event.action.output}\n`
-				</step_${stepIndex}>
+				prompt += `</step_${stepIndex}>\n`
-			`
 			} else if (event.type === 'observation') {
 				prompt += `<sys>${event.content}</sys>\n`
 			} else if (event.type === 'user_takeover') {
-				prompt += `<sys>User took over control and made changes to the page.</sys>\n`
+				prompt += `<sys>User took over control and made changes to the page</sys>\n`
 			} else if (event.type === 'error') {
 				// Error events are mainly for panel rendering, not included in LLM context
 				// to avoid polluting the agent's reasoning with transient errors
@@ -546,47 +578,36 @@ export class PageAgentCore extends EventTarget {
 
 		// <browser_state>
 
-		prompt += await this.#getBrowserState()
+		let pageContent = browserState.content
+		if (this.config.transformPageContent) {
+			pageContent = await this.config.transformPageContent(pageContent)
+		}
 
-		return trimLines(prompt)
+		prompt += '<browser_state>\n'
+		prompt += browserState.header + '\n'
+		prompt += pageContent + '\n'
+		prompt += browserState.footer + '\n\n'
+		prompt += '</browser_state>\n\n'
+
+		return prompt
 	}
 
-	#onDone(text: string, success = true) {
+	#onDone(success = true) {
 		this.pageController.cleanUpHighlights()
 		this.pageController.hideMask() // No await - fire and forget
 		this.#setStatus(success ? 'completed' : 'error')
 		this.#abortController.abort()
 	}
 
-	async #getBrowserState(): Promise<string> {
+	dispose() {
-		const state = await this.pageController.getBrowserState()
-
-		let content = state.content
-		if (this.config.transformPageContent) {
-			content = await this.config.transformPageContent(content)
-		}
-
-		return trimLines(`<browser_state>
-			Current Page: [${state.title}](${state.url})
-
-			${state.header}
-			${content}
-			${state.footer}
-
-			</browser_state>
-		`)
-	}
-
-	dispose(reason?: string) {
 		console.log('Disposing PageAgent...')
-		this.disposed = true
 		this.pageController.dispose()
-		this.history = []
+		// this.history = []
-		this.#abortController.abort(reason ?? 'PageAgent disposed')
+		this.#abortController.abort()
 
 		// Emit dispose event for UI cleanup
 		this.dispatchEvent(new Event('dispose'))
 
-		this.config.onDispose?.(this, reason)
+		this.config.onDispose?.(this)
 	}
 }

packages/core/src/config/index.ts

@@ -141,6 +141,12 @@ export interface AgentConfig {
 	 * }
 	 */
 	transformPageContent?: (content: string) => Promise<string> | string
+
+	/**
+	 * Completely override the default system prompt.
+	 * @experimental Use with caution - incorrect prompts may break agent behavior.
+	 */
+	customSystemPrompt?: string
 }
 
 export type PageAgentConfig = LLMConfig & AgentConfig & PageControllerConfig

packages/core/src/prompts/system_prompt.md

@@ -10,7 +10,7 @@ You excel at following tasks:
 </intro>
 
 <language_settings>
-- Default working language: **中文**
+- Default working language: **English**
 - Use the language that user is using. Return in user's language.
 </language_settings>
 
@@ -128,7 +128,6 @@ Exhibit the following reasoning patterns to successfully achieve the <user_reque
 Here are examples of good output patterns. Use them as reference but never copy them directly.
 
 <evaluation_examples>
-- Positive Examples:
 "evaluation_previous_goal": "Successfully navigated to the product page and found the target information. Verdict: Success"
 "evaluation_previous_goal": "Clicked the login button and user authentication form appeared. Verdict: Success"
 </evaluation_examples>
@@ -139,17 +138,16 @@ Here are examples of good output patterns. Use them as reference but never copy
 
 <next_goal_examples>
 "next_goal": "Click on the 'Add to Cart' button to proceed with the purchase flow."
-"next_goal": "Extract details from the first item on the page."
 </next_goal_examples>
 </examples>
 
 <output>
-You must ALWAYS respond with a valid JSON in this exact format:
-
 {
   "evaluation_previous_goal": "Concise one-sentence analysis of your last action. Clearly state success, failure, or uncertain.",
   "memory": "1-3 concise sentences of specific memory of this step and overall progress. You should put here everything that will help you track progress in future steps. Like counting pages visited, items found, etc.",
-  "next_goal": "State the next immediate goal and action to achieve it, in one clear sentence."
+  "next_goal": "State the next immediate goal and action to achieve it, in one clear sentence.",
-  "action":{"one_action_name": {// action-specific parameter}}
+  "action":{
+    "Action name": {// Action parameters}
+  }
 }
 </output>

packages/core/src/tools/index.ts

@@ -2,7 +2,7 @@
  * Internal tools for PageAgent.
  * @note Adapted from browser-use
  */
-import zod, { type z } from 'zod'
+import * as zod from 'zod'
 
 import type { PageAgentCore } from '../PageAgentCore'
 import { waitFor } from '../utils'
@@ -13,7 +13,7 @@ import { waitFor } from '../utils'
 export interface PageAgentTool<TParams = any> {
 	// name: string
 	description: string
-	inputSchema: z.ZodType<TParams>
+	inputSchema: zod.ZodType<TParams>
 	execute: (this: PageAgentCore, args: TParams) => Promise<string>
 }
 
@@ -31,14 +31,13 @@ tools.set(
 	'done',
 	tool({
 		description:
-			'Complete task - provide a summary of results for the user. Set success=True if task completed successfully, false otherwise. Text should be your response to the user summarizing results.',
+			'Complete task. Text is your final response to the user — keep it concise unless the user explicitly asks for detail.',
 		inputSchema: zod.object({
 			text: zod.string(),
 			success: zod.boolean().default(true),
 		}),
 		execute: async function (this: PageAgentCore, input) {
 			// @note main loop will handle this one
-			// this.onDone(input.text, input.success)
 			return Promise.resolve('Task completed')
 		},
 	})
@@ -47,25 +46,17 @@ tools.set(
 tools.set(
 	'wait',
 	tool({
-		description:
+		description: 'Wait for x seconds. Can be used to wait until the page or data is fully loaded.',
-			'Wait for x seconds. default 1s (max 10 seconds, min 1 second). This can be used to wait until the page or data is fully loaded.',
 		inputSchema: zod.object({
 			seconds: zod.number().min(1).max(10).default(1),
 		}),
 		execute: async function (this: PageAgentCore, input) {
+			// try to subtract LLM calling time from the actual wait time
 			const lastTimeUpdate = await this.pageController.getLastUpdateTime()
 			const actualWaitTime = Math.max(0, input.seconds - (Date.now() - lastTimeUpdate) / 1000)
 			console.log(`actualWaitTime: ${actualWaitTime} seconds`)
 			await waitFor(actualWaitTime)
 
-			this.states.totalWaitTime += input.seconds
-
-			if (this.states.totalWaitTime >= 3) {
-				this.pushObservation(
-					`You have waited ${this.states.totalWaitTime} seconds accumulatively. Do NOT wait any longer unless you have a good reason.`
-				)
-			}
-
 			return `✅ Waited for ${input.seconds} seconds.`
 		},
 	})
@@ -106,7 +97,7 @@ tools.set(
 tools.set(
 	'input_text',
 	tool({
-		description: 'Click and input text into a input interactive element',
+		description: 'Click and type text into an interactive input element',
 		inputSchema: zod.object({
 			index: zod.int().min(0),
 			text: zod.string(),
@@ -140,8 +131,7 @@ tools.set(
 tools.set(
 	'scroll',
 	tool({
-		description:
+		description: 'Scroll the page vertically. Use index for scroll elements (dropdowns/custom UI).',
-			'Scroll the page by specified number of pages (set down=True to scroll down, down=False to scroll up, num_pages=number of pages to scroll like 0.5 for half page, 1.0 for one page, etc.). Optional index parameter to scroll within a specific element or its scroll container (works well for dropdowns and custom UI components). Optional pixels parameter to scroll by a specific number of pixels instead of pages.',
 		inputSchema: zod.object({
 			down: zod.boolean().default(true),
 			num_pages: zod.number().min(0).max(10).optional().default(0.1),
@@ -158,11 +148,14 @@ tools.set(
 	})
 )
 
+/**
+ * @todo Tables need a dedicated parser to extract structured data. This tool is useless.
+ */
 tools.set(
 	'scroll_horizontally',
 	tool({
 		description:
-			'Scroll the page or element horizontally (set right=True to scroll right, right=False to scroll left, pixels=number of pixels to scroll). Optional index parameter to scroll within a specific element or its scroll container (works well for wide tables).',
+			'Scroll the page horizontally, or within a specific element by index. Useful for wide tables.',
 		inputSchema: zod.object({
 			right: zod.boolean().default(true),
 			pixels: zod.number().int().min(0),
@@ -190,8 +183,6 @@ tools.set(
 	})
 )
 
-// @todo get_dropdown_options
-// @todo select_dropdown_option
 // @todo send_keys
 // @todo upload_file
 // @todo go_back

packages/core/src/types.ts

@@ -51,6 +51,8 @@ export interface AgentStepEvent {
 	}
 	/** Raw LLM response for debugging */
 	rawResponse?: unknown
+	/** Raw LLM request for debugging */
+	rawRequest?: unknown
 }
 
 /**

packages/core/src/utils/assert.ts

@@ -1,17 +0,0 @@
-import chalk from 'chalk'
-
-/**
- * Simple assertion function that throws an error if the condition is falsy
- * @param condition - The condition to assert
- * @param message - Optional error message
- * @throws Error if condition is falsy
- */
-export function assert(condition: unknown, message?: string, silent?: boolean): asserts condition {
-	if (!condition) {
-		const errorMessage = message ?? 'Assertion failed'
-
-		if (!silent) console.error(chalk.red(`❌ assert: ${errorMessage}`))
-
-		throw new Error(errorMessage)
-	}
-}

packages/core/src/utils/index.ts

@@ -1,27 +1,7 @@
+import chalk from 'chalk'
+
 export { normalizeResponse } from './autoFixer'
 
-/**
- * Wait until condition becomes true
- * @returns Returns when condition becomes true, throws otherwise
- * @param timeout Timeout in milliseconds, default 0 means no timeout, throws error on timeout
- */
-export async function waitUntil(check: () => boolean, timeout = 60 * 60_1000): Promise<boolean> {
-	if (check()) return true
-
-	return new Promise((resolve, reject) => {
-		const start = Date.now()
-		const interval = setInterval(() => {
-			if (check()) {
-				clearInterval(interval)
-				resolve(true)
-			} else if (Date.now() - start > timeout) {
-				clearInterval(interval)
-				reject(new Error('Timeout waiting for condition to become true'))
-			}
-		}, 100)
-	})
-}
-
 export async function waitFor(seconds: number): Promise<void> {
 	await new Promise((resolve) => setTimeout(resolve, seconds * 1000))
 }
@@ -37,15 +17,6 @@ export function truncate(text: string, maxLength: number): string {
 
 //
 
-export function trimLines(text: string): string {
-	return text
-		.split('\n')
-		.map((line) => line.trim())
-		.join('\n')
-}
-
-//
-
 export function randomID(existingIDs?: string[]): string {
 	let id = Math.random().toString(36).substring(2, 11)
 
@@ -85,3 +56,19 @@ export function uid() {
 	ids.push(id)
 	return id
 }
+
+/**
+ * Simple assertion function that throws an error if the condition is falsy
+ * @param condition - The condition to assert
+ * @param message - Optional error message
+ * @throws Error if condition is falsy
+ */
+export function assert(condition: unknown, message?: string, silent?: boolean): asserts condition {
+	if (!condition) {
+		const errorMessage = message ?? 'Assertion failed'
+
+		if (!silent) console.error(chalk.red(`❌ assert: ${errorMessage}`))
+
+		throw new Error(errorMessage)
+	}
+}

packages/extension/.prettierignore

@@ -0,0 +1,2 @@
+.wxt
+src/components/ui

packages/extension/PRIVACY.md

@@ -0,0 +1,57 @@
+# Privacy Policy for Page Agent Extension
+
+**Last updated:** January 2026
+
+## Overview
+
+Page Agent Extension is a browser automation tool that uses AI to help you interact with web pages. This policy explains what data is processed and under what circumstances.
+
+## Data Processing
+
+### Local Processing
+
+The extension performs DOM analysis and automation actions **locally in your browser**. Your browsing history, passwords, and form data are not accessed or collected by the extension itself.
+
+### Data Transmission
+
+Data is transmitted to external servers **only when you initiate an automation task**. When this occurs:
+
+- Your task instructions (natural language commands)
+- Sanitized page structure (simplified DOM, excluding sensitive form values)
+
+are sent to the LLM API endpoint configured in **your settings**.
+
+**If you configure a third-party LLM provider** (e.g., OpenAI, Anthropic, or others), data is sent directly to that provider. Their privacy policies apply.
+
+**If you use our testing endpoint**, your requests are proxied to [DeepSeek](https://deepseek.com) for AI processing. Regarding this test endpoint:
+
+- This endpoint is provided for evaluation purposes only and is not recommended for production or daily use
+- We do **not** store your task content, page content, or visited URLs
+- Minimal logging (timestamps, request metadata, IP addresses) may occur for abuse prevention and service stability
+- DeepSeek's [Privacy Policy](https://cdn.deepseek.com/policies/en-US/deepseek-privacy-policy.html) applies to their processing of your requests
+
+## Data Storage
+
+- **Local storage only**: Your configuration (API endpoint, API key, model selection) is stored in your browser via `chrome.storage.local`
+- **No cloud sync**: Configuration is not synced to any external server
+- **No analytics**: The extension does not include any analytics or tracking code
+
+## Your Control
+
+- The extension is open source and can be audited by anyone
+- You choose which LLM provider to use
+- You may configure your own API endpoint at any time
+- You can clear all stored data by removing the extension
+
+## Changes to This Policy
+
+We may update this policy as the extension evolves. Significant changes will be noted in the extension's release notes.
+
+## Contact
+
+For questions about this privacy policy:
+https://github.com/alibaba/page-agent/issues
+
+---
+
+Source code: https://github.com/alibaba/page-agent

packages/extension/components.json

@@ -0,0 +1,24 @@
+{
+    "$schema": "https://ui.shadcn.com/schema.json",
+    "style": "new-york",
+    "rsc": false,
+    "tsx": true,
+    "tailwind": {
+        "config": "",
+        "css": "src/index.css",
+        "baseColor": "neutral",
+        "cssVariables": true,
+        "prefix": ""
+    },
+    "iconLibrary": "lucide",
+    "aliases": {
+        "components": "@/components",
+        "utils": "@/lib/utils",
+        "ui": "@/components/ui",
+        "lib": "@/lib",
+        "hooks": "@/hooks"
+    },
+    "registries": {
+        "@magicui": "https://magicui.design/r/{name}.json"
+    }
+}

packages/extension/docs/extension_api.md

@@ -0,0 +1,291 @@
+# Page Agent Extension API
+
+This document describes how to integrate the Page Agent browser extension into your web application.
+
+## Installation
+
+### 1. Install the browser extension
+
+Install the Page Agent extension from the Chrome Web Store.
+
+### 2. Install type definitions (recommended)
+
+```bash
+npm install @page-agent/core --save-dev
+```
+
+### 3. Set up authentication
+
+The extension only injects APIs when it detects a valid token in `localStorage`.
+
+1. Open the extension's side panel to get your authorization token
+2. Set the token in your page:
+
+```typescript
+localStorage.setItem('PageAgentExtUserAuthToken', 'your-token')
+```
+
+## Quick Start
+
+```typescript
+import type {
+  AgentActivity,
+  AgentStatus,
+  ExecutionResult,
+  HistoricalEvent,
+} from '@page-agent/core'
+
+// Wait for extension injection (up to 1 second)
+async function waitForExtension(timeout = 1000): Promise<boolean> {
+  const start = Date.now()
+  while (Date.now() - start < timeout) {
+    if (window.PAGE_AGENT_EXT) return true
+    await new Promise((r) => setTimeout(r, 100))
+  }
+  return false
+}
+
+// Usage
+if (await waitForExtension()) {
+  const result = await window.PAGE_AGENT_EXT!.execute('Click the login button', {
+    baseURL: 'https://api.openai.com/v1',
+    apiKey: 'your-api-key',
+    model: 'gpt-5.2',
+    onStatusChange: (status) => console.log('Status:', status),
+    onActivity: (activity) => console.log('Activity:', activity),
+  })
+  console.log('Result:', result)
+}
+```
+
+## Global API
+
+The extension injects the following APIs into the `window` object:
+
+### `window.PAGE_AGENT_EXT_VERSION`
+
+Extension version string (e.g., `"1.0.0"`). This is exposed separately to allow version checking before accessing the main API object.
+
+### `window.PAGE_AGENT_EXT`
+
+Main API namespace object containing:
+
+#### `PAGE_AGENT_EXT.execute(task, config)`
+
+Execute an agent task.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `task` | `string` | Yes | Task description |
+| `config` | `ExecuteConfig` | Yes | Execution configuration (LLM settings, options, and event callbacks) |
+
+**Returns:** `Promise<ExecutionResult>`
+
+#### `PAGE_AGENT_EXT.dispose()`
+
+Stop and destroy the current running agent.
+
+## Types
+
+Install `@page-agent/core` for full type definitions:
+
+```typescript
+import type {
+  AgentActivity,
+  AgentStatus,
+  ExecutionResult,
+  HistoricalEvent,
+} from '@page-agent/core'
+
+export interface ExecuteConfig {
+  baseURL: string
+  apiKey: string
+  model: string
+
+  /**
+   * Whether to include the initial tab (that holds this main world script) in the task.
+   * @default true
+   */
+  includeInitialTab?: boolean
+
+  onStatusChange?: (status: AgentStatus) => void
+  onActivity?: (activity: AgentActivity) => void
+  onHistoryUpdate?: (history: HistoricalEvent[]) => void
+  onDispose?: () => void
+}
+
+export type Execute = (task: string, config: ExecuteConfig) => Promise<ExecutionResult>
+```
+
+### AgentStatus
+
+```typescript
+type AgentStatus = 'idle' | 'running' | 'completed' | 'error'
+```
+
+| Status | Description |
+|--------|-------------|
+| `idle` | Agent is idle, ready to execute |
+| `running` | Agent is executing a task |
+| `completed` | Task completed successfully |
+| `error` | Task failed with an error |
+
+### AgentActivity
+
+```typescript
+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 }
+```
+
+| Type | Description |
+|------|-------------|
+| `thinking` | Agent is analyzing the page and planning |
+| `executing` | Agent is executing a tool action |
+| `executed` | Tool execution completed |
+| `retrying` | Retrying after a failure |
+| `error` | An error occurred |
+
+### HistoricalEvent
+
+```typescript
+type HistoricalEvent =
+  | { type: 'step'; stepIndex: number; reflection: AgentReflection; action: Action }
+  | { type: 'observation'; content: string }
+  | { type: 'user_takeover' }
+  | { type: 'retry'; message: string; attempt: number; maxAttempts: number }
+  | { type: 'error'; message: string; rawResponse?: unknown }
+```
+
+### ExecutionResult
+
+```typescript
+interface ExecutionResult {
+  success: boolean
+  data: string
+  history: HistoricalEvent[]
+}
+```
+
+## Usage Examples
+
+### Basic Execution
+
+```typescript
+const result = await window.PAGE_AGENT_EXT!.execute(
+  'Fill in the email field with test@example.com and click Submit',
+  {
+    baseURL: 'https://api.openai.com/v1',
+    apiKey: process.env.OPENAI_API_KEY!,
+    model: 'gpt-5.2',
+  }
+)
+
+if (result.success) {
+  console.log('Task completed:', result.data)
+} else {
+  console.error('Task failed')
+}
+```
+
+### Exclude Initial Tab
+
+By default, the agent includes the initial tab (where the script runs) in the task. Set `includeInitialTab: false` to exclude it:
+
+```typescript
+const result = await window.PAGE_AGENT_EXT!.execute(
+  'Open a new tab and search for page-agent on GitHub',
+  {
+    baseURL: 'https://api.openai.com/v1',
+    apiKey: process.env.OPENAI_API_KEY!,
+    model: 'gpt-5.2',
+    includeInitialTab: false,  // Agent will open new tabs only
+  }
+)
+```
+
+### With Event Callbacks
+
+```typescript
+await window.PAGE_AGENT_EXT!.execute('Navigate to the settings page', {
+  baseURL: 'https://api.openai.com/v1',
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: 'gpt-5.2',
+  onStatusChange: (status) => {
+    updateUI({ agentStatus: status })
+  },
+  onActivity: (activity) => {
+    switch (activity.type) {
+      case 'thinking':
+        showSpinner('Agent is thinking...')
+        break
+      case 'executing':
+        showSpinner(`Executing: ${activity.tool}`)
+        break
+      case 'executed':
+        log(`${activity.tool} completed in ${activity.duration}ms`)
+        break
+      case 'error':
+        showError(activity.message)
+        break
+    }
+  },
+  onHistoryUpdate: (history) => {
+    renderHistory(history)
+  },
+})
+```
+
+### Stop Execution
+
+```typescript
+// Start a task
+window.PAGE_AGENT_EXT!.execute('Scroll through all pages', {
+  baseURL: 'https://api.openai.com/v1',
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: 'gpt-5.2',
+})
+
+// Later, stop it
+window.PAGE_AGENT_EXT!.dispose()
+```
+
+## Window Type Declaration
+
+If not using `@page-agent/core`, add this to your project:
+
+```typescript
+import type {
+  AgentActivity,
+  AgentStatus,
+  ExecutionResult,
+  HistoricalEvent,
+} from '@page-agent/core'
+
+interface ExecuteConfig {
+  baseURL: string
+  apiKey: string
+  model: string
+  includeInitialTab?: boolean
+  onStatusChange?: (status: AgentStatus) => void
+  onActivity?: (activity: AgentActivity) => void
+  onHistoryUpdate?: (history: HistoricalEvent[]) => void
+  onDispose?: () => void
+}
+
+declare global {
+  interface Window {
+    PAGE_AGENT_EXT_VERSION?: string
+    PAGE_AGENT_EXT?: {
+      version: string
+      execute: (task: string, config: ExecuteConfig) => Promise<ExecutionResult>
+      dispose: () => void
+    }
+  }
+}
+```

packages/extension/docs/extension_api_zh.md

@@ -0,0 +1,291 @@
+# Page Agent 浏览器插件 API
+
+本文档介绍如何在网页应用中接入 Page Agent 浏览器插件。
+
+## 安装
+
+### 1. 安装浏览器插件
+
+从 Chrome 应用商店安装 Page Agent 插件。
+
+### 2. 安装类型定义（推荐）
+
+```bash
+npm install @page-agent/core --save-dev
+```
+
+### 3. 配置认证
+
+插件在页面加载后检测 `localStorage` 中的 token，匹配时才会注入 API。
+
+1. 打开插件的侧边栏面板，获取授权 token
+2. 在页面中设置 token：
+
+```typescript
+localStorage.setItem('PageAgentExtUserAuthToken', 'your-token')
+```
+
+## 快速开始
+
+```typescript
+import type {
+  AgentActivity,
+  AgentStatus,
+  ExecutionResult,
+  HistoricalEvent,
+} from '@page-agent/core'
+
+// 等待插件注入（最多 1 秒）
+async function waitForExtension(timeout = 1000): Promise<boolean> {
+  const start = Date.now()
+  while (Date.now() - start < timeout) {
+    if (window.PAGE_AGENT_EXT) return true
+    await new Promise((r) => setTimeout(r, 100))
+  }
+  return false
+}
+
+// 使用
+if (await waitForExtension()) {
+  const result = await window.PAGE_AGENT_EXT!.execute('点击登录按钮', {
+    baseURL: 'https://api.openai.com/v1',
+    apiKey: 'your-api-key',
+    model: 'gpt-5.2',
+    onStatusChange: (status) => console.log('状态:', status),
+    onActivity: (activity) => console.log('活动:', activity),
+  })
+  console.log('结果:', result)
+}
+```
+
+## 全局 API
+
+插件在 `window` 对象上注入以下 API：
+
+### `window.PAGE_AGENT_EXT_VERSION`
+
+插件版本号字符串（例如 `"1.0.0"`）。单独暴露版本号，方便在访问主 API 对象前进行版本检查。
+
+### `window.PAGE_AGENT_EXT`
+
+主 API 命名空间对象，包含：
+
+#### `PAGE_AGENT_EXT.execute(task, config)`
+
+执行 Agent 任务。
+
+**参数：**
+
+| 名称 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `task` | `string` | 是 | 任务描述 |
+| `config` | `ExecuteConfig` | 是 | 执行配置（LLM 设置、选项和事件回调） |
+
+**返回：** `Promise<ExecutionResult>`
+
+#### `PAGE_AGENT_EXT.dispose()`
+
+停止并销毁当前运行的 Agent。
+
+## 类型定义
+
+安装 `@page-agent/core` 获取完整类型：
+
+```typescript
+import type {
+  AgentActivity,
+  AgentStatus,
+  ExecutionResult,
+  HistoricalEvent,
+} from '@page-agent/core'
+
+export interface ExecuteConfig {
+  baseURL: string
+  apiKey: string
+  model: string
+
+  /**
+   * 是否将初始标签页（运行此脚本的页面）包含在任务中。
+   * @default true
+   */
+  includeInitialTab?: boolean
+
+  onStatusChange?: (status: AgentStatus) => void
+  onActivity?: (activity: AgentActivity) => void
+  onHistoryUpdate?: (history: HistoricalEvent[]) => void
+  onDispose?: () => void
+}
+
+export type Execute = (task: string, config: ExecuteConfig) => Promise<ExecutionResult>
+```
+
+### AgentStatus
+
+```typescript
+type AgentStatus = 'idle' | 'running' | 'completed' | 'error'
+```
+
+| 状态 | 说明 |
+|------|------|
+| `idle` | 空闲，准备执行 |
+| `running` | 正在执行任务 |
+| `completed` | 任务成功完成 |
+| `error` | 任务执行失败 |
+
+### AgentActivity
+
+```typescript
+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 }
+```
+
+| 类型 | 说明 |
+|------|------|
+| `thinking` | Agent 正在分析页面并规划 |
+| `executing` | 正在执行工具操作 |
+| `executed` | 工具执行完成 |
+| `retrying` | 失败后重试 |
+| `error` | 发生错误 |
+
+### HistoricalEvent
+
+```typescript
+type HistoricalEvent =
+  | { type: 'step'; stepIndex: number; reflection: AgentReflection; action: Action }
+  | { type: 'observation'; content: string }
+  | { type: 'user_takeover' }
+  | { type: 'retry'; message: string; attempt: number; maxAttempts: number }
+  | { type: 'error'; message: string; rawResponse?: unknown }
+```
+
+### ExecutionResult
+
+```typescript
+interface ExecutionResult {
+  success: boolean
+  data: string
+  history: HistoricalEvent[]
+}
+```
+
+## 使用示例
+
+### 基础执行
+
+```typescript
+const result = await window.PAGE_AGENT_EXT!.execute(
+  '在邮箱输入框填入 test@example.com 然后点击提交',
+  {
+    baseURL: 'https://api.openai.com/v1',
+    apiKey: process.env.OPENAI_API_KEY!,
+    model: 'gpt-5.2',
+  }
+)
+
+if (result.success) {
+  console.log('任务完成:', result.data)
+} else {
+  console.error('任务失败')
+}
+```
+
+### 排除初始标签页
+
+默认情况下，Agent 会将初始标签页（运行脚本的页面）包含在任务中。设置 `includeInitialTab: false` 可以排除它：
+
+```typescript
+const result = await window.PAGE_AGENT_EXT!.execute(
+  '打开新标签页并在 GitHub 上搜索 page-agent',
+  {
+    baseURL: 'https://api.openai.com/v1',
+    apiKey: process.env.OPENAI_API_KEY!,
+    model: 'gpt-5.2',
+    includeInitialTab: false,  // Agent 只会打开新标签页
+  }
+)
+```
+
+### 使用事件回调
+
+```typescript
+await window.PAGE_AGENT_EXT!.execute('导航到设置页面', {
+  baseURL: 'https://api.openai.com/v1',
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: 'gpt-5.2',
+  onStatusChange: (status) => {
+    updateUI({ agentStatus: status })
+  },
+  onActivity: (activity) => {
+    switch (activity.type) {
+      case 'thinking':
+        showSpinner('Agent 正在思考...')
+        break
+      case 'executing':
+        showSpinner(`正在执行: ${activity.tool}`)
+        break
+      case 'executed':
+        log(`${activity.tool} 完成，耗时 ${activity.duration}ms`)
+        break
+      case 'error':
+        showError(activity.message)
+        break
+    }
+  },
+  onHistoryUpdate: (history) => {
+    renderHistory(history)
+  },
+})
+```
+
+### 停止执行
+
+```typescript
+// 启动任务
+window.PAGE_AGENT_EXT!.execute('滚动浏览所有页面', {
+  baseURL: 'https://api.openai.com/v1',
+  apiKey: process.env.OPENAI_API_KEY!,
+  model: 'gpt-5.2',
+})
+
+// 稍后停止
+window.PAGE_AGENT_EXT!.dispose()
+```
+
+## Window 类型声明
+
+如果不使用 `@page-agent/core`，可以添加以下声明：
+
+```typescript
+import type {
+  AgentActivity,
+  AgentStatus,
+  ExecutionResult,
+  HistoricalEvent,
+} from '@page-agent/core'
+
+interface ExecuteConfig {
+  baseURL: string
+  apiKey: string
+  model: string
+  includeInitialTab?: boolean
+  onStatusChange?: (status: AgentStatus) => void
+  onActivity?: (activity: AgentActivity) => void
+  onHistoryUpdate?: (history: HistoricalEvent[]) => void
+  onDispose?: () => void
+}
+
+declare global {
+  interface Window {
+    PAGE_AGENT_EXT_VERSION?: string
+    PAGE_AGENT_EXT?: {
+      version: string
+      execute: (task: string, config: ExecuteConfig) => Promise<ExecutionResult>
+      dispose: () => void
+    }
+  }
+}
+```

packages/extension/package.json

@@ -0,0 +1,48 @@
+{
+    "name": "@page-agent/ext",
+    "private": true,
+    "version": "0.1.4",
+    "type": "module",
+    "scripts": {
+        "dev": "wxt",
+        "build:ext": "wxt build",
+        "zip": "wxt zip",
+        "postinstall": "wxt prepare"
+    },
+    "devDependencies": {
+        "@radix-ui/react-hover-card": "^1.1.15",
+        "@radix-ui/react-icons": "^1.3.2",
+        "@radix-ui/react-label": "^2.1.8",
+        "@radix-ui/react-separator": "^1.1.8",
+        "@radix-ui/react-slot": "^1.2.4",
+        "@radix-ui/react-switch": "^1.2.6",
+        "@radix-ui/react-tooltip": "^1.2.8",
+        "@types/chrome": "^0.1.34",
+        "@types/react": "^19.2.13",
+        "@types/react-dom": "^19.2.1",
+        "@wxt-dev/module-react": "^1.1.5",
+        "class-variance-authority": "^0.7.1",
+        "clsx": "^2.1.1",
+        "idb": "^8.0.3",
+        "lucide-react": "^0.563.0",
+        "motion": "^12.34.0",
+        "next-themes": "^0.4.6",
+        "react": "^19.2.4",
+        "react-dom": "^19.2.4",
+        "rough-notation": "^0.5.1",
+        "simple-icons": "^16.8.0",
+        "sonner": "^2.0.7",
+        "tailwind-merge": "^3.4.0",
+        "tailwindcss": "^4.1.14",
+        "tw-animate-css": "^1.4.0",
+        "wxt": "^0.20.14"
+    },
+    "dependencies": {
+        "@page-agent/core": "1.2.0",
+        "@page-agent/llms": "1.2.0",
+        "@page-agent/page-controller": "1.2.0",
+        "@page-agent/ui": "1.2.0",
+        "chalk": "^5.6.2",
+        "zod": "^4.3.5"
+    }
+}

packages/extension/src/agent/.prettierignore

@@ -0,0 +1 @@
+system_prompt.md

packages/extension/src/agent/MultiPageAgent.ts

@@ -0,0 +1,97 @@
+import { type PageAgentConfig, PageAgentCore } from '@page-agent/core'
+
+import { RemotePageController } from './RemotePageController'
+import { TabsController } from './TabsController'
+import SYSTEM_PROMPT from './system_prompt.md?raw'
+import { createTabTools } from './tabTools'
+
+/** Detect user language from browser settings */
+function detectLanguage(): 'en-US' | 'zh-CN' {
+	const lang = navigator.language || navigator.languages?.[0] || 'en-US'
+	return lang.startsWith('zh') ? 'zh-CN' : 'en-US'
+}
+
+/**
+ * MultiPageAgent
+ * - use with extension
+ * - can be used from a side panel or a content script
+ */
+export class MultiPageAgent extends PageAgentCore {
+	constructor(config: Omit<PageAgentConfig, 'pageController'> & { includeInitialTab?: boolean }) {
+		// multi page controller
+		const tabsController = new TabsController()
+		const pageController = new RemotePageController(tabsController)
+		const customTools = createTabTools(tabsController)
+
+		// system prompt - auto-detect language if not specified
+		const language = config.language ?? detectLanguage()
+		const targetLanguage = language === 'zh-CN' ? '中文' : 'English'
+		const systemPrompt = SYSTEM_PROMPT.replace(
+			/Default working language: \*\*.*?\*\*/,
+			`Default working language: **${targetLanguage}**`
+		)
+
+		// include initial tab for controlling
+		const includeInitialTab = config.includeInitialTab ?? true
+
+		/**
+		 * When the agent is in side-panel and user closed the side-panel.
+		 * There is no chance for isAgentRunning to be set false.
+		 * (unload event doesn't work well in side panel.)
+		 * (I'm trying not to use long-lived connection because the lifecycle of a sw is hard to predict.)
+		 * This heartbeat mechanism acts as a backup.
+		 */
+		let heartBeatInterval: null | number = null
+
+		super({
+			...config,
+			pageController: pageController as any,
+			customTools: customTools,
+			customSystemPrompt: systemPrompt,
+
+			onBeforeTask: async (agent) => {
+				await tabsController.init(agent.task, includeInitialTab)
+
+				heartBeatInterval = window.setInterval(() => {
+					chrome.storage.local.set({
+						agentHeartbeat: Date.now(),
+					})
+				}, 1_000)
+
+				await chrome.storage.local.set({
+					isAgentRunning: true,
+				})
+			},
+
+			onAfterTask: async () => {
+				if (heartBeatInterval) {
+					window.clearInterval(heartBeatInterval)
+					heartBeatInterval = null
+				}
+
+				await chrome.storage.local.set({
+					isAgentRunning: false,
+				})
+			},
+
+			onBeforeStep: async (agent) => {
+				// make sure the current tab is loaded before the step starts
+				await tabsController.waitUntilTabLoaded(tabsController.currentTabId!)
+			},
+
+			onDispose: () => {
+				if (heartBeatInterval) {
+					window.clearInterval(heartBeatInterval)
+					heartBeatInterval = null
+				}
+
+				chrome.storage.local.set({
+					isAgentRunning: false,
+				})
+
+				// no need to dispose tabsController and pageController
+				// as they do not keep references
+			},
+		})
+	}
+}

packages/extension/src/agent/RemotePageController.background.ts

@@ -0,0 +1,44 @@
+/**
+ * background logics for RemotePageController
+ * - redirect messages from RemotePageController(Agent, extension pages) to ContentScript
+ */
+
+export function handlePageControlMessage(
+	message: { type: 'PAGE_CONTROL'; action: string; payload: any; targetTabId: number },
+	sender: chrome.runtime.MessageSender,
+	sendResponse: (response: unknown) => void
+): true | undefined {
+	const PREFIX = '[RemotePageController.background]'
+
+	function debug(...messages: any[]) {
+		console.debug(`\x1b[90m${PREFIX}\x1b[0m`, ...messages)
+	}
+
+	const { action, payload, targetTabId } = message
+
+	if (action === 'get_my_tab_id') {
+		debug('get_my_tab_id', sender.tab?.id)
+		sendResponse({ tabId: sender.tab?.id || null })
+		return
+	}
+
+	// proxy to content script
+	chrome.tabs
+		.sendMessage(targetTabId, {
+			type: 'PAGE_CONTROL',
+			action,
+			payload,
+		})
+		.then((result) => {
+			sendResponse(result)
+		})
+		.catch((error) => {
+			console.error(PREFIX, error)
+			sendResponse({
+				success: false,
+				error: error instanceof Error ? error.message : String(error),
+			})
+		})
+
+	return true // async response
+}

packages/extension/src/agent/RemotePageController.content.ts

@@ -0,0 +1,132 @@
+/**
+ * content script for RemotePageController
+ */
+import { PageController } from '@page-agent/page-controller'
+
+export function initPageController() {
+	let pageController: PageController | null = null
+	let intervalID: number | null = null
+
+	const myTabIdPromise = chrome.runtime
+		.sendMessage({ type: 'PAGE_CONTROL', action: 'get_my_tab_id' })
+		.then((response) => {
+			return (response as { tabId: number | null }).tabId
+		})
+		.catch((error) => {
+			console.error('[RemotePageController.ContentScript]: Failed to get my tab id', error)
+			return null
+		})
+
+	function getPC(): PageController {
+		if (!pageController) {
+			pageController = new PageController({ enableMask: false, viewportExpansion: 400 })
+		}
+		return pageController
+	}
+
+	intervalID = window.setInterval(async () => {
+		const agentHeartbeat = (await chrome.storage.local.get('agentHeartbeat')).agentHeartbeat
+		const now = Date.now()
+		const agentInTouch = typeof agentHeartbeat === 'number' && now - agentHeartbeat < 2_000
+
+		const isAgentRunning = (await chrome.storage.local.get('isAgentRunning')).isAgentRunning
+		const currentTabId = (await chrome.storage.local.get('currentTabId')).currentTabId
+
+		const shouldShowMask = isAgentRunning && agentInTouch && currentTabId === (await myTabIdPromise)
+
+		if (shouldShowMask) {
+			const pc = getPC()
+			pc.initMask()
+			await pc.showMask()
+		} else {
+			// await getPC().hideMask()
+			if (pageController) {
+				pageController.hideMask()
+				pageController.cleanUpHighlights()
+			}
+		}
+
+		if (!isAgentRunning && agentInTouch) {
+			if (pageController) {
+				pageController.dispose()
+				pageController = null
+			}
+		}
+	}, 500)
+
+	chrome.runtime.onMessage.addListener((message, sender, sendResponse): true | undefined => {
+		if (message.type !== 'PAGE_CONTROL') {
+			// sendResponse({
+			// 	success: false,
+			// 	error: `[RemotePageController.ContentScript]: Invalid message type: ${message.type}`,
+			// })
+			return
+		}
+
+		const { action, payload } = message
+		const methodName = getMethodName(action)
+
+		const pc = getPC() as any
+
+		switch (action) {
+			case 'get_last_update_time':
+			case 'get_browser_state':
+			case 'update_tree':
+			case 'clean_up_highlights':
+			case 'click_element':
+			case 'input_text':
+			case 'select_option':
+			case 'scroll':
+			case 'scroll_horizontally':
+			case 'execute_javascript':
+				pc[methodName](...(payload || []))
+					.then((result: any) => sendResponse(result))
+					.catch((error: any) =>
+						sendResponse({
+							success: false,
+							error: error instanceof Error ? error.message : String(error),
+						})
+					)
+				break
+
+			default:
+				sendResponse({
+					success: false,
+					error: `Unknown PAGE_CONTROL action: ${action}`,
+				})
+		}
+
+		return true
+	})
+}
+
+function getMethodName(action: string): string {
+	switch (action) {
+		case 'get_last_update_time':
+			return 'getLastUpdateTime' as const
+		case 'get_browser_state':
+			return 'getBrowserState' as const
+		case 'update_tree':
+			return 'updateTree' as const
+		case 'clean_up_highlights':
+			return 'cleanUpHighlights' as const
+
+		// DOM actions
+
+		case 'click_element':
+			return 'clickElement' as const
+		case 'input_text':
+			return 'inputText' as const
+		case 'select_option':
+			return 'selectOption' as const
+		case 'scroll':
+			return 'scroll' as const
+		case 'scroll_horizontally':
+			return 'scrollHorizontally' as const
+		case 'execute_javascript':
+			return 'executeJavascript' as const
+
+		default:
+			return action
+	}
+}

packages/extension/src/agent/RemotePageController.ts

@@ -0,0 +1,198 @@
+import type { BrowserState } from '@page-agent/page-controller'
+
+import type { TabsController } from './TabsController'
+
+const PREFIX = '[RemotePageController]'
+
+function debug(...messages: any[]) {
+	console.debug(`\x1b[90m${PREFIX}\x1b[0m`, ...messages)
+}
+
+function sendMessage(message: {
+	type: 'PAGE_CONTROL'
+	action: string
+	targetTabId: number
+	payload?: any
+}): Promise<any> {
+	return chrome.runtime.sendMessage(message).catch((error) => {
+		console.error(PREFIX, message.action, error)
+		return null
+	})
+}
+
+/**
+ * Agent side page controller.
+ * - live in the agent env (extension page or content script)
+ * - communicates with remote PageController via sw
+ */
+export class RemotePageController {
+	tabsController: TabsController
+
+	constructor(tabsController: TabsController) {
+		this.tabsController = tabsController
+	}
+
+	get currentTabId(): number | null {
+		return this.tabsController.currentTabId
+	}
+
+	private async getCurrentUrl(): Promise<string> {
+		if (!this.currentTabId) return ''
+		const { url } = await this.tabsController.getTabInfo(this.currentTabId)
+		return url || ''
+	}
+
+	private async getCurrentTitle(): Promise<string> {
+		if (!this.currentTabId) return ''
+		const { title } = await this.tabsController.getTabInfo(this.currentTabId)
+		return title || ''
+	}
+
+	async getLastUpdateTime(): Promise<number> {
+		if (!this.currentTabId) throw new Error('tabsController not initialized.')
+		return sendMessage({
+			type: 'PAGE_CONTROL',
+			action: 'get_last_update_time',
+			targetTabId: this.currentTabId,
+		})
+	}
+
+	async getBrowserState(): Promise<BrowserState> {
+		if (!this.currentTabId) throw new Error('tabsController not initialized.')
+
+		let browserState = {} as BrowserState
+		debug('getBrowserState', this.currentTabId)
+
+		const currentUrl = await this.getCurrentUrl()
+		const currentTitle = await this.getCurrentTitle()
+
+		if (!this.currentTabId || !isContentScriptAllowed(currentUrl)) {
+			browserState = {
+				url: currentUrl,
+				title: currentTitle,
+				header: '',
+				content: '(empty page. either current page is not readable or not loaded yet.)',
+				footer: '',
+			}
+		} else {
+			browserState = await sendMessage({
+				type: 'PAGE_CONTROL',
+				action: 'get_browser_state',
+				targetTabId: this.currentTabId,
+			})
+		}
+
+		const sum = await this.tabsController.summarizeTabs()
+		browserState.header = sum + '\n\n' + (browserState.header || '')
+
+		debug('getBrowserState: success', this.currentTabId, browserState)
+
+		return browserState
+	}
+
+	async updateTree(): Promise<void> {
+		if (!this.currentTabId || !isContentScriptAllowed(await this.getCurrentUrl())) {
+			return
+		}
+
+		await sendMessage({
+			type: 'PAGE_CONTROL',
+			action: 'update_tree',
+			targetTabId: this.currentTabId,
+		})
+	}
+
+	async cleanUpHighlights(): Promise<void> {
+		if (!this.currentTabId || !isContentScriptAllowed(await this.getCurrentUrl())) {
+			return
+		}
+
+		await sendMessage({
+			type: 'PAGE_CONTROL',
+			action: 'clean_up_highlights',
+			targetTabId: this.currentTabId,
+		})
+	}
+
+	async clickElement(...args: any[]): Promise<DomActionReturn> {
+		const res = await this.remoteCallDomAction('click_element', args)
+		// @note may cause page navigation, wait for 1 second to ensure the page loading started
+		await new Promise((resolve) => setTimeout(resolve, 1000))
+		return res
+	}
+
+	async inputText(...args: any[]): Promise<DomActionReturn> {
+		return this.remoteCallDomAction('input_text', args)
+	}
+
+	async selectOption(...args: any[]): Promise<DomActionReturn> {
+		return this.remoteCallDomAction('select_option', args)
+	}
+
+	async scroll(...args: any[]): Promise<DomActionReturn> {
+		return this.remoteCallDomAction('scroll', args)
+	}
+
+	async scrollHorizontally(...args: any[]): Promise<DomActionReturn> {
+		return this.remoteCallDomAction('scroll_horizontally', args)
+	}
+
+	async executeJavascript(...args: any[]): Promise<DomActionReturn> {
+		return this.remoteCallDomAction('execute_javascript', args)
+	}
+
+	/** @note Managed by content script via storage polling. */
+	async showMask(): Promise<void> {}
+	/** @note Managed by content script via storage polling. */
+	async hideMask(): Promise<void> {}
+	/** @note Managed by content script via storage polling. */
+	dispose(): void {}
+
+	private async remoteCallDomAction(action: string, payload: any[]): Promise<DomActionReturn> {
+		if (!this.currentTabId) {
+			return { success: false, message: 'RemotePageController not initialized.' }
+		}
+
+		if (!isContentScriptAllowed(await this.getCurrentUrl())) {
+			return {
+				success: false,
+				message:
+					'Operation not allowed on this page. Use open_new_tab to navigate to a web page first.',
+			}
+		}
+
+		return sendMessage({
+			type: 'PAGE_CONTROL',
+			action: action,
+			targetTabId: this.currentTabId!,
+			payload,
+		})
+	}
+}
+
+interface DomActionReturn {
+	success: boolean
+	message: string
+}
+
+/**
+ * Check if a URL can run content scripts.
+ */
+function isContentScriptAllowed(url: string | undefined): boolean {
+	if (!url) return false
+
+	const restrictedPatterns = [
+		/^chrome:\/\//,
+		/^chrome-extension:\/\//,
+		/^about:/,
+		/^edge:\/\//,
+		/^brave:\/\//,
+		/^opera:\/\//,
+		/^vivaldi:\/\//,
+		/^file:\/\//,
+		/^view-source:/,
+		/^devtools:\/\//,
+	]
+
+	return !restrictedPatterns.some((pattern) => pattern.test(url))
+}

packages/extension/src/agent/TabsController.background.ts

@@ -0,0 +1,160 @@
+/**
+ * background logics for TabsController
+ */
+import type { TabAction } from './TabsController'
+
+const PREFIX = '[TabsController.background]'
+
+function debug(...messages: any[]) {
+	console.debug(`\x1b[90m${PREFIX}\x1b[0m`, ...messages)
+}
+
+export function handleTabControlMessage(
+	message: { type: 'TAB_CONTROL'; action: TabAction; payload: any },
+	sender: chrome.runtime.MessageSender,
+	sendResponse: (response: unknown) => void
+): true | undefined {
+	const { action, payload } = message
+
+	switch (action as TabAction) {
+		case 'get_active_tab': {
+			debug('get_active_tab')
+			chrome.tabs
+				.query({ active: true, currentWindow: true })
+				.then((tabs) => {
+					const tabId = tabs.length > 0 ? tabs[0].id || null : null
+					debug('get_active_tab: success', tabId)
+					sendResponse({ success: true, tabId })
+				})
+				.catch((error) => {
+					sendResponse({ error: error instanceof Error ? error.message : String(error) })
+				})
+			return true // async response
+		}
+
+		case 'get_tab_info': {
+			debug('get_tab_info', payload)
+			chrome.tabs
+				.get(payload.tabId)
+				.then((tab) => {
+					debug('get_tab_info: success', tab)
+					sendResponse(tab)
+				})
+				.catch((error) => {
+					sendResponse({ error: error instanceof Error ? error.message : String(error) })
+				})
+			return true // async response
+		}
+
+		case 'open_new_tab': {
+			debug('open_new_tab', payload)
+			chrome.tabs
+				.create({ url: payload.url, active: false })
+				.then((newTab) => {
+					debug('open_new_tab: success', newTab)
+					sendResponse({ success: true, tabId: newTab.id, windowId: newTab.windowId })
+				})
+				.catch((error) => {
+					sendResponse({ error: error instanceof Error ? error.message : String(error) })
+				})
+			return true // async response
+		}
+
+		case 'create_tab_group': {
+			debug('create_tab_group', payload)
+			chrome.tabs
+				.group({ tabIds: payload.tabIds, createProperties: { windowId: payload.windowId } })
+				.then((groupId) => {
+					debug('create_tab_group: success', groupId)
+					sendResponse({ success: true, groupId })
+				})
+				.catch((error) => {
+					console.error(PREFIX, 'Failed to create tab group', error)
+					sendResponse({ error: error instanceof Error ? error.message : String(error) })
+				})
+			return true // async response
+		}
+
+		case 'update_tab_group': {
+			debug('update_tab_group', payload)
+			chrome.tabGroups
+				.update(payload.groupId, payload.properties)
+				.then(() => {
+					sendResponse({ success: true })
+				})
+				.catch((error) => {
+					sendResponse({ error: error instanceof Error ? error.message : String(error) })
+				})
+			return true // async response
+		}
+
+		case 'add_tab_to_group': {
+			debug('add_tab_to_group', payload)
+			chrome.tabs
+				.group({ tabIds: payload.tabId, groupId: payload.groupId })
+				.then(() => {
+					sendResponse({ success: true })
+				})
+				.catch((error) => {
+					sendResponse({ error: error instanceof Error ? error.message : String(error) })
+				})
+			return true // async response
+		}
+
+		case 'close_tab': {
+			debug('close_tab', payload)
+			chrome.tabs
+				.remove(payload.tabId)
+				.then(() => {
+					sendResponse({ success: true })
+				})
+				.catch((error) => {
+					sendResponse({ error: error instanceof Error ? error.message : String(error) })
+				})
+			return true // async response
+		}
+
+		default:
+			sendResponse({ error: `Unknown action: ${action}` })
+			return
+	}
+}
+
+export function setupTabChangeEvents() {
+	console.log('[TabsController.background] setupTabChangeEvents')
+
+	chrome.tabs.onCreated.addListener((tab) => {
+		debug('onCreated', tab)
+		chrome.runtime
+			.sendMessage({ type: 'TAB_CHANGE', action: 'created', payload: { tab } })
+			.catch((error) => {
+				debug('onCreated error:', error)
+			})
+	})
+
+	chrome.tabs.onRemoved.addListener((tabId, removeInfo) => {
+		debug('onRemoved', tabId, removeInfo)
+		chrome.runtime
+			.sendMessage({
+				type: 'TAB_CHANGE',
+				action: 'removed',
+				payload: { tabId, removeInfo },
+			})
+			.catch((error) => {
+				debug('onRemoved error:', error)
+			})
+	})
+
+	chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
+		debug('onUpdated', tabId, changeInfo)
+		chrome.runtime
+			.sendMessage({
+				type: 'TAB_CHANGE',
+				action: 'updated',
+				payload: { tabId, changeInfo, tab },
+			})
+			.catch((error) => {
+				debug('onUpdated error:', error)
+			})
+	})
+}

packages/extension/src/agent/TabsController.ts

@@ -0,0 +1,357 @@
+const PREFIX = '[TabsController]'
+
+function debug(...messages: any[]) {
+	console.debug(`\x1b[90m${PREFIX}\x1b[0m`, ...messages)
+}
+
+function sendMessage(message: {
+	type: 'TAB_CONTROL'
+	action: TabAction
+	payload?: any
+}): Promise<any> {
+	return chrome.runtime.sendMessage(message).catch((error) => {
+		console.error(PREFIX, message.action, error)
+		return null
+	})
+}
+
+/**
+ * Controller for managing browser tabs.
+ * - live in the agent env (extension page or content script)
+ * - no chrome apis. call sw for tab operations
+ */
+export class TabsController extends EventTarget {
+	currentTabId: number | null = null
+
+	private tabs: TabMeta[] = []
+	private initialTabId: number | null = null
+	private tabGroupId: number | null = null
+	private task: string = ''
+	private windowId: number | null = null
+
+	async init(task: string, includeInitialTab: boolean = true) {
+		debug('init', task, includeInitialTab)
+
+		this.task = task
+		this.tabs = []
+		this.currentTabId = null
+		this.tabGroupId = null
+		this.initialTabId = null
+		this.windowId = null
+
+		const result = await sendMessage({
+			type: 'TAB_CONTROL',
+			action: 'get_active_tab',
+		})
+
+		this.initialTabId = result.tabId
+
+		if (!this.initialTabId) {
+			throw new Error('Failed to get initial tab ID')
+		}
+
+		if (includeInitialTab) {
+			this.currentTabId = this.initialTabId
+
+			// update tab status immediately
+			const info = await sendMessage({
+				type: 'TAB_CONTROL',
+				action: 'get_tab_info',
+				payload: { tabId: this.initialTabId },
+			})
+
+			this.tabs.push({
+				id: result.tabId,
+				isInitial: true,
+				url: info.url,
+				title: info.title,
+				status: info.status,
+			})
+		}
+
+		await this.updateCurrentTabId(this.currentTabId)
+
+		const tabChangeHandler = (message: any): void => {
+			if (message.type !== 'TAB_CHANGE') {
+				// throw new Error(`[TabsController]: Invalid message type: ${message.type}`)
+				return
+			}
+
+			if (message.action === 'created') {
+				const tab = message.payload.tab as chrome.tabs.Tab
+				if (tab.groupId === this.tabGroupId && tab.id != null) {
+					// Tab created in our controlled group
+					if (!this.tabs.find((t) => t.id === tab.id)) {
+						this.tabs.push({ id: tab.id, isInitial: false })
+					}
+					this.switchToTab(tab.id)
+				}
+			} else if (message.action === 'removed') {
+				const { tabId } = message.payload as { tabId: number }
+				const targetTab = this.tabs.find((t) => t.id === tabId)
+				if (targetTab) {
+					this.tabs = this.tabs.filter((t) => t.id !== tabId)
+					if (this.currentTabId === tabId) {
+						const newCurrentTab = this.tabs[this.tabs.length - 1] || null
+						if (newCurrentTab) {
+							this.switchToTab(newCurrentTab.id)
+						} else {
+							this.updateCurrentTabId(null)
+						}
+					}
+				}
+			} else if (message.action === 'updated') {
+				const { tabId, tab } = message.payload as { tabId: number; tab: chrome.tabs.Tab }
+				const targetTab = this.tabs.find((t) => t.id === tabId)
+				if (targetTab) {
+					targetTab.url = tab.url
+					targetTab.title = tab.title
+					targetTab.status = tab.status
+				}
+			}
+		}
+
+		chrome.runtime.onMessage.addListener(tabChangeHandler)
+
+		this.addEventListener('dispose', () => {
+			chrome.runtime.onMessage.removeListener(tabChangeHandler)
+		})
+	}
+
+	async openNewTab(url: string): Promise<string> {
+		debug('openNewTab', url)
+
+		const result = await sendMessage({
+			type: 'TAB_CONTROL',
+			action: 'open_new_tab',
+			payload: { url },
+		})
+
+		if (!result.success) {
+			throw new Error(`Failed to open new tab: ${result.error}`)
+		}
+
+		const tabId = result.tabId as number
+		const windowId = result.windowId as number
+
+		this.windowId = windowId
+
+		this.tabs.push({
+			id: tabId,
+			isInitial: false,
+		})
+
+		await this.switchToTab(tabId)
+
+		if (!this.tabGroupId) {
+			const result = await sendMessage({
+				type: 'TAB_CONTROL',
+				action: 'create_tab_group',
+				payload: { tabIds: [tabId], windowId: this.windowId },
+			})
+
+			if (!result.success) {
+				throw new Error(`Failed to create tab group: ${result.error}`)
+			}
+
+			const groupId = result.groupId as number
+
+			this.tabGroupId = groupId
+
+			await sendMessage({
+				type: 'TAB_CONTROL',
+				action: 'update_tab_group',
+				payload: {
+					groupId: this.tabGroupId,
+					properties: {
+						title: `PageAgent(${this.task})`,
+						color: randomColor(),
+						collapsed: false,
+					},
+				},
+			})
+		} else {
+			await sendMessage({
+				type: 'TAB_CONTROL',
+				action: 'add_tab_to_group',
+				payload: { tabId: result.tabId, groupId: this.tabGroupId },
+			})
+		}
+
+		await this.waitUntilTabLoaded(tabId)
+
+		return `✅ Opened new tab ID ${tabId} with URL ${url}`
+	}
+
+	async switchToTab(tabId: number): Promise<string> {
+		debug('switchToTab', tabId)
+
+		const targetTab = this.tabs.find((t) => t.id === tabId)
+		if (!targetTab) {
+			throw new Error(`Tab ID ${tabId} not found in tab list.`)
+		}
+
+		await this.updateCurrentTabId(tabId)
+
+		return `✅ Switched to tab ID ${tabId}.`
+	}
+
+	async closeTab(tabId: number): Promise<string> {
+		debug('closeTab', tabId)
+
+		const targetTab = this.tabs.find((t) => t.id === tabId)
+		if (!targetTab) {
+			throw new Error(`Tab ID ${tabId} not found in tab list.`)
+		}
+		if (targetTab.isInitial) {
+			throw new Error(`Cannot close the initial tab ID ${tabId}.`)
+		}
+
+		const result = await sendMessage({
+			type: 'TAB_CONTROL',
+			action: 'close_tab',
+			payload: { tabId },
+		})
+
+		if (result.success) {
+			this.tabs = this.tabs.filter((t) => t.id !== tabId)
+			if (this.currentTabId === tabId) {
+				const newCurrentTab = this.tabs[this.tabs.length - 1] || null
+				if (newCurrentTab) {
+					await this.switchToTab(newCurrentTab.id)
+				} else {
+					await this.updateCurrentTabId(null)
+				}
+			}
+
+			return `✅ Closed tab ID ${tabId}.`
+		} else {
+			throw new Error(`Failed to close tab ID ${tabId}: ${result.error}`)
+		}
+	}
+
+	async updateCurrentTabId(tabId: number | null) {
+		debug('updateCurrentTabId', tabId)
+
+		this.currentTabId = tabId
+		await chrome.storage.local.set({ currentTabId: tabId })
+	}
+
+	async getTabInfo(tabId: number): Promise<{ title: string; url: string }> {
+		// use cached tab info if available
+		const tabMeta = this.tabs.find((t) => t.id === tabId)
+		if (tabMeta && tabMeta.url && tabMeta.title) {
+			return { title: tabMeta.title, url: tabMeta.url }
+		}
+
+		// otherwise, pull the latest tab info from the background script
+		debug('getTabInfo: pulling from background script', tabId)
+		const result = await sendMessage({
+			type: 'TAB_CONTROL',
+			action: 'get_tab_info',
+			payload: { tabId },
+		})
+
+		if (tabMeta) {
+			tabMeta.url = result.url
+			tabMeta.title = result.title
+		}
+
+		return result
+	}
+
+	async summarizeTabs(): Promise<string> {
+		const summaries = [`| Tab ID | URL | Title | Current |`, `|-----|-----|-----|-----|`]
+		for (const tab of this.tabs) {
+			const { title, url } = await this.getTabInfo(tab.id)
+			summaries.push(
+				`| ${tab.id} | ${url} | ${title} | ${this.currentTabId === tab.id ? '✅' : ''} |`
+			)
+		}
+		if (!this.tabs.length) {
+			summaries.push('\nNo tabs available. Open a tab if needed.')
+		}
+
+		return summaries.join('\n')
+	}
+
+	async waitUntilTabLoaded(tabId: number): Promise<void> {
+		const tab = this.tabs.find((t) => t.id === tabId)
+		if (!tab) throw new Error(`Tab ID ${tabId} not found in tab list.`)
+
+		if (tab.status === 'unloaded') throw new Error(`Tab ID ${tabId} is unloaded.`)
+		if (tab.status === 'complete') return
+
+		debug('waitUntilTabLoaded', tabId)
+		await waitUntil(() => tab.status === 'complete', 4_000)
+	}
+
+	dispose() {
+		this.dispatchEvent(new Event('dispose'))
+	}
+}
+
+export type TabAction =
+	| 'get_active_tab'
+	| 'get_tab_info'
+	| 'open_new_tab'
+	| 'create_tab_group'
+	| 'update_tab_group'
+	| 'add_tab_to_group'
+	| 'close_tab'
+	| 'get_tab_title'
+
+interface TabMeta {
+	id: number
+	isInitial: boolean
+	url?: string
+	title?: string
+	status?: 'loading' | 'unloaded' | 'complete'
+}
+
+const TAB_GROUP_COLORS = [
+	'grey',
+	'blue',
+	'red',
+	'yellow',
+	'green',
+	'pink',
+	'purple',
+	'cyan',
+] as const
+
+type TabGroupColor = (typeof TAB_GROUP_COLORS)[number]
+
+function randomColor(): TabGroupColor {
+	return TAB_GROUP_COLORS[Math.floor(Math.random() * TAB_GROUP_COLORS.length)]
+}
+
+/**
+ * Wait until condition becomes true
+ * @returns Returns when condition becomes true, throws otherwise
+ * @param timeoutMS Timeout in milliseconds, default 1 minutes, throws error on timeout
+ * @param error Error object to reject on timeout. If not provided, will resolve with false
+ */
+export async function waitUntil(
+	check: () => boolean | Promise<boolean>,
+	timeoutMS = 60_000,
+	error?: string
+): Promise<boolean> {
+	if (await check()) return true
+
+	return new Promise((resolve, reject) => {
+		const start = Date.now()
+		const poll = async () => {
+			if (await check()) return resolve(true)
+			if (Date.now() - start > timeoutMS) {
+				if (error) {
+					return reject(new Error(error))
+				} else {
+					return resolve(false)
+				}
+			}
+			setTimeout(poll, 100)
+		}
+		setTimeout(poll, 100)
+	})
+}

packages/extension/src/agent/constants.ts

@@ -0,0 +1,13 @@
+import type { LLMConfig } from '@page-agent/llms'
+
+// Demo LLM for testing
+export const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
+export const DEMO_BASE_URL =
+	'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
+export const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
+
+export const DEMO_CONFIG: LLMConfig = {
+	apiKey: DEMO_API_KEY,
+	baseURL: DEMO_BASE_URL,
+	model: DEMO_MODEL,
+}

packages/extension/src/agent/system_prompt.md

@@ -0,0 +1,145 @@
+You are an AI agent designed to operate in an iterative loop to automate browser tasks. Your ultimate goal is accomplishing the task provided in <user_request>.
+
+<intro>
+You excel at following tasks:
+1. Navigating complex websites and extracting precise information
+2. Automating form submissions and interactive web actions
+3. Gathering and saving information 
+4. Operate effectively in an agent loop
+5. Efficiently performing diverse web tasks
+</intro>
+
+<language_settings>
+- Default working language: **English**
+- Use the language that user is using. Return in user's language.
+</language_settings>
+
+<input>
+At every step, your input will consist of: 
+1. <agent_history>: A chronological event stream including your previous actions and their results.
+2. <agent_state>: Current <user_request> and <step_info>.
+3. <browser_state>: Tabs, Current Tab, Current URL, interactive elements indexed for actions, and visible page content.
+</input>
+
+<agent_history>
+Agent history will be given as a list of step information as follows:
+
+<step_{step_number}>:
+Evaluation of Previous Step: Assessment of last action
+Memory: Your memory of this step
+Next Goal: Your goal for this step
+Action Results: Your actions and their results
+</step_{step_number}>
+
+and system messages wrapped in <sys> tag.
+</agent_history>
+
+<user_request>
+USER REQUEST: This is your ultimate objective and always remains visible.
+- This has the highest priority. Make the user happy.
+- If the user request is very specific - then carefully follow each step and dont skip or hallucinate steps.
+- If the task is open ended you can plan yourself how to get it done.
+</user_request>
+
+<browser_state>
+1. Browser State will be given as:
+
+Open Tabs: Open tabs with their ids.
+Current Tab: The tab you are currently viewing.
+Current URL: URL of the page you are currently viewing.
+Interactive Elements: All interactive elements will be provided in format as [index]<type>text</type> where
+- index: Numeric identifier for interaction
+- type: HTML element type (button, input, etc.)
+- text: Element description
+
+Examples:
+[33]<div>User form</div>
+\t*[35]<button aria-label='Submit form'>Submit</button>
+
+Note that:
+- Only elements with numeric indexes in [] are interactive
+- (stacked) indentation (with \t) is important and means that the element is a (html) child of the element above (with a lower index)
+- Elements tagged with `*[` are the new clickable elements that appeared on the website since the last step - if url has not changed.
+- Pure text elements without [] are not interactive.
+</browser_state>
+
+<browser_rules>
+Strictly follow these rules while using the browser and navigating the web:
+- Only interact with elements that have a numeric [index] assigned.
+- Only use indexes that are explicitly provided.
+- If the page changes after, for example, an input text action, analyze if you need to interact with new elements, e.g. selecting the right option from the list.
+- By default, only elements in the visible viewport are listed. Use scrolling actions if you suspect relevant content is offscreen which you need to interact with. Scroll ONLY if there are more pixels below or above the page.
+- You can scroll by a specific number of pages using the num_pages parameter (e.g., 0.5 for half page, 2.0 for two pages).
+- All the elements that are scrollable are marked with `data-scrollable` attribute. Including the scrollable distance in every directions. You can scroll *the element* in case some area are overflowed.
+- If a captcha appears, tell user you can not solve captcha. finished the task and ask user to solve it.
+- If expected elements are missing, try scrolling, or navigating back.
+- If the page is not fully loaded, use the `wait` action.
+- Do not repeat one action for more than 3 times unless some conditions changed.
+- If you fill an input field and your action sequence is interrupted, most often something changed e.g. suggestions popped up under the field.
+- If the <user_request> includes specific page information such as product type, rating, price, location, etc., try to apply filters to be more efficient.
+- The <user_request> is the ultimate goal. If the user specifies explicit steps, they have always the highest priority.
+- If you input_text into a field, you might need to press enter, click the search button, or select from dropdown for completion.
+- Don't login into a page if you don't have to. Don't login if you don't have the credentials. 
+- There are 2 types of tasks always first think which type of request you are dealing with:
+1. Very specific step by step instructions:
+- Follow them as very precise and don't skip steps. Try to complete everything as requested.
+2. Open ended tasks. Plan yourself, be creative in achieving them.
+- If you get stuck e.g. with logins or captcha in open-ended tasks you can re-evaluate the task and try alternative ways, e.g. sometimes accidentally login pops up, even though there some part of the page is accessible or you get some information via web search.
+</browser_rules>
+
+<task_completion_rules>
+You must call the `done` action in one of three cases:
+- When you have fully completed the USER REQUEST.
+- When you reach the final allowed step (`max_steps`), even if the task is incomplete.
+- When you feel stuck or unable to solve user request. Or user request is not clear or contains inappropriate content.
+- When it is ABSOLUTELY IMPOSSIBLE to continue.
+
+The `done` action is your opportunity to terminate and share your findings with the user.
+- Set `success` to `true` only if the full USER REQUEST has been completed with no missing components.
+- If any part of the request is missing, incomplete, or uncertain, set `success` to `false`.
+- You can use the `text` field of the `done` action to communicate your findings and to provide a coherent reply to the user and fulfill the USER REQUEST.
+- You are ONLY ALLOWED to call `done` as a single action. Don't call it together with other actions.
+- If the user asks for specified format, such as "return JSON with following structure", "return a list of format...", MAKE sure to use the right format in your answer.
+- If the user asks for a structured output, your `done` action's schema may be modified. Take this schema into account when solving the task!
+</task_completion_rules>
+
+<reasoning_rules>
+Exhibit the following reasoning patterns to successfully achieve the <user_request>:
+
+- Reason about <agent_history> to track progress and context toward <user_request>.
+- Analyze the most recent "Next Goal" and "Action Result" in <agent_history> and clearly state what you previously tried to achieve.
+- Analyze all relevant items in <agent_history> and <browser_state> to understand your state.
+- Explicitly judge success/failure/uncertainty of the last action. Never assume an action succeeded just because it appears to be executed in your last step in <agent_history>. If the expected change is missing, mark the last action as failed (or uncertain) and plan a recovery.
+- Analyze whether you are stuck, e.g. when you repeat the same actions multiple times without any progress. Then consider alternative approaches e.g. scrolling for more context or ask user for help.
+- Ask user for help if you have any difficulty. Keep user in the loop.
+- If you see information relevant to <user_request>, plan saving the information to memory.
+- Always reason about the <user_request>. Make sure to carefully analyze the specific steps and information required. E.g. specific filters, specific form fields, specific information to search. Make sure to always compare the current trajectory with the user request and think carefully if thats how the user requested it.
+</reasoning_rules>
+
+<examples>
+Here are examples of good output patterns. Use them as reference but never copy them directly.
+
+<evaluation_examples>
+"evaluation_previous_goal": "Successfully navigated to the product page and found the target information. Verdict: Success"
+"evaluation_previous_goal": "Clicked the login button and user authentication form appeared. Verdict: Success"
+</evaluation_examples>
+
+<memory_examples>
+"memory": "Found many pending reports that need to be analyzed in the main page. Successfully processed the first 2 reports on quarterly sales data and moving on to inventory analysis and customer feedback reports."
+</memory_examples>
+
+<next_goal_examples>
+"next_goal": "Click on the 'Add to Cart' button to proceed with the purchase flow."
+</next_goal_examples>
+</examples>
+
+<output>
+{
+  "evaluation_previous_goal": "Concise one-sentence analysis of your last action. Clearly state success, failure, or uncertain.",
+  "memory": "1-3 concise sentences of specific memory of this step and overall progress. You should put here everything that will help you track progress in future steps. Like counting pages visited, items found, etc.",
+  "next_goal": "State the next immediate goal and action to achieve it, in one clear sentence.",
+  "action":{
+    "Action name": {// Action parameters}
+  }
+}
+</output>

packages/extension/src/agent/tabTools.ts

@@ -0,0 +1,74 @@
+/**
+ * Tab control tools for browser extension
+ *
+ * These tools allow the agent to manage multiple browser tabs:
+ * - open_new_tab: Open a new tab and set it as current
+ * - switch_to_tab: Switch to an existing tab
+ * - close_tab: Close a tab (optionally switch to another)
+ */
+import * as zod from 'zod'
+
+import type { TabsController } from './TabsController'
+
+/** Tool definition compatible with PageAgentCore customTools */
+interface TabTool {
+	description: string
+	inputSchema: zod.ZodType
+	execute: (input: unknown) => Promise<string>
+}
+
+/**
+ * Create tab control tools bound to a TabsManager instance.
+ * These tools are injected into PageAgentCore via customTools config.
+ */
+export function createTabTools(tabsController: TabsController): Record<string, TabTool> {
+	return {
+		open_new_tab: {
+			description:
+				'Open a new browser tab with the specified URL. The new tab becomes the current tab for all subsequent page operations.',
+			inputSchema: zod.object({
+				url: zod.string().describe('The URL to open in the new tab'),
+			}),
+			execute: async (input: unknown) => {
+				const { url } = input as { url: string }
+				try {
+					return await tabsController.openNewTab(url)
+				} catch (error) {
+					return `❌ Failed: ${error instanceof Error ? error.message : String(error)}`
+				}
+			},
+		},
+
+		switch_to_tab: {
+			description:
+				'Switch to an existing tab by its ID. After switching, all page operations will target the new current tab. You can only switch to tabs in the tab list shown in browser state.',
+			inputSchema: zod.object({
+				tab_id: zod.number().int().describe('The tab ID to switch to'),
+			}),
+			execute: async (input: unknown) => {
+				const { tab_id } = input as { tab_id: number }
+				try {
+					return await tabsController.switchToTab(tab_id)
+				} catch (error) {
+					return `❌ Failed: ${error instanceof Error ? error.message : String(error)}`
+				}
+			},
+		},
+
+		close_tab: {
+			description:
+				'Close a tab by its ID. Cannot close the initial tab. Optionally specify which tab to switch to after closing.',
+			inputSchema: zod.object({
+				tab_id: zod.number().int().describe('The tab ID to close'),
+			}),
+			execute: async (input: unknown) => {
+				const { tab_id } = input as { tab_id: number }
+				try {
+					return await tabsController.closeTab(tab_id)
+				} catch (error) {
+					return `❌ Failed: ${error instanceof Error ? error.message : String(error)}`
+				}
+			},
+		},
+	}
+}

packages/extension/src/agent/useAgent.ts

@@ -0,0 +1,105 @@
+/**
+ * React hook for using AgentController
+ */
+import type { AgentActivity, AgentStatus, HistoricalEvent } from '@page-agent/core'
+import type { LLMConfig } from '@page-agent/llms'
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { MultiPageAgent } from './MultiPageAgent'
+import { DEMO_CONFIG } from './constants'
+
+export interface UseAgentResult {
+	status: AgentStatus
+	history: HistoricalEvent[]
+	activity: AgentActivity | null
+	currentTask: string
+	config: LLMConfig | null
+	execute: (task: string) => Promise<void>
+	stop: () => void
+	configure: (config: LLMConfig) => Promise<void>
+}
+
+export function useAgent(): UseAgentResult {
+	const agentRef = useRef<MultiPageAgent | null>(null)
+	const [status, setStatus] = useState<AgentStatus>('idle')
+	const [history, setHistory] = useState<HistoricalEvent[]>([])
+	const [activity, setActivity] = useState<AgentActivity | null>(null)
+	const [currentTask, setCurrentTask] = useState('')
+	const [config, setConfig] = useState<LLMConfig | null>(null)
+
+	useEffect(() => {
+		chrome.storage.local.get('llmConfig').then((result) => {
+			if (result.llmConfig) {
+				setConfig(result.llmConfig as LLMConfig)
+			} else {
+				chrome.storage.local.set({ llmConfig: DEMO_CONFIG })
+				setConfig(DEMO_CONFIG)
+			}
+		})
+	}, [])
+
+	useEffect(() => {
+		if (!config) return
+
+		const agent = new MultiPageAgent(config)
+		agentRef.current = agent
+
+		const handleStatusChange = (e: Event) => {
+			const newStatus = agent.status as AgentStatus
+			setStatus(newStatus)
+			if (newStatus === 'idle' || newStatus === 'completed' || newStatus === 'error') {
+				setActivity(null)
+			}
+		}
+
+		const handleHistoryChange = (e: Event) => {
+			setHistory([...agent.history])
+		}
+
+		const handleActivity = (e: Event) => {
+			const newActivity = (e as CustomEvent).detail as AgentActivity
+			setActivity(newActivity)
+		}
+
+		agent.addEventListener('statuschange', handleStatusChange)
+		agent.addEventListener('historychange', handleHistoryChange)
+		agent.addEventListener('activity', handleActivity)
+
+		return () => {
+			agent.removeEventListener('statuschange', handleStatusChange)
+			agent.removeEventListener('historychange', handleHistoryChange)
+			agent.removeEventListener('activity', handleActivity)
+			agent.dispose()
+		}
+	}, [config])
+
+	const execute = useCallback(async (task: string) => {
+		const agent = agentRef.current
+		console.log('🚀 [useAgent] start executing task:', task)
+		if (!agent) throw new Error('Agent not initialized')
+
+		setCurrentTask(task)
+		setHistory([])
+		await agent.execute(task)
+	}, [])
+
+	const stop = useCallback(() => {
+		agentRef.current?.dispose()
+	}, [])
+
+	const configure = useCallback(async (newConfig: LLMConfig) => {
+		await chrome.storage.local.set({ llmConfig: newConfig })
+		setConfig(newConfig)
+	}, [])
+
+	return {
+		status,
+		history,
+		activity,
+		currentTask,
+		config,
+		execute,
+		stop,
+		configure,
+	}
+}

packages/extension/src/assets/index.css

@@ -0,0 +1,123 @@
+@import 'tailwindcss';
+@import 'tw-animate-css';
+
+@custom-variant dark (&:is(.dark *));
+
+:root {
+	--background: oklch(1 0 0);
+	--foreground: oklch(0.145 0 0);
+	--card: oklch(1 0 0);
+	--card-foreground: oklch(0.145 0 0);
+	--popover: oklch(1 0 0);
+	--popover-foreground: oklch(0.145 0 0);
+	--primary: oklch(0.205 0 0);
+	--primary-foreground: oklch(0.985 0 0);
+	--secondary: oklch(0.97 0 0);
+	--secondary-foreground: oklch(0.205 0 0);
+	--muted: oklch(0.97 0 0);
+	--muted-foreground: oklch(0.556 0 0);
+	--accent: oklch(0.97 0 0);
+	--accent-foreground: oklch(0.205 0 0);
+	--destructive: oklch(0.577 0.245 27.325);
+	--destructive-foreground: oklch(0.577 0.245 27.325);
+	--border: oklch(0.922 0 0);
+	--input: oklch(0.922 0 0);
+	--ring: oklch(0.708 0 0);
+	--chart-1: oklch(0.646 0.222 41.116);
+	--chart-2: oklch(0.6 0.118 184.704);
+	--chart-3: oklch(0.398 0.07 227.392);
+	--chart-4: oklch(0.828 0.189 84.429);
+	--chart-5: oklch(0.769 0.188 70.08);
+	--radius: 0.625rem;
+	--sidebar: oklch(0.985 0 0);
+	--sidebar-foreground: oklch(0.145 0 0);
+	--sidebar-primary: oklch(0.205 0 0);
+	--sidebar-primary-foreground: oklch(0.985 0 0);
+	--sidebar-accent: oklch(0.97 0 0);
+	--sidebar-accent-foreground: oklch(0.205 0 0);
+	--sidebar-border: oklch(0.922 0 0);
+	--sidebar-ring: oklch(0.708 0 0);
+}
+
+.dark {
+	--background: oklch(0.19 0 0);
+	--foreground: oklch(0.985 0 0);
+	--card: oklch(0.145 0 0);
+	--card-foreground: oklch(0.985 0 0);
+	--popover: oklch(0.145 0 0);
+	--popover-foreground: oklch(0.985 0 0);
+	--primary: oklch(0.985 0 0);
+	--primary-foreground: oklch(0.205 0 0);
+	--secondary: oklch(0.269 0 0);
+	--secondary-foreground: oklch(0.985 0 0);
+	--muted: oklch(0.269 0 0);
+	--muted-foreground: oklch(0.708 0 0);
+	--accent: oklch(0.269 0 0);
+	--accent-foreground: oklch(0.985 0 0);
+	--destructive: oklch(0.396 0.141 25.723);
+	--destructive-foreground: oklch(0.637 0.237 25.331);
+	--border: oklch(0.269 0 0);
+	--input: oklch(0.269 0 0);
+	--ring: oklch(0.439 0 0);
+	--chart-1: oklch(0.488 0.243 264.376);
+	--chart-2: oklch(0.696 0.17 162.48);
+	--chart-3: oklch(0.769 0.188 70.08);
+	--chart-4: oklch(0.627 0.265 303.9);
+	--chart-5: oklch(0.645 0.246 16.439);
+	--sidebar: oklch(0.205 0 0);
+	--sidebar-foreground: oklch(0.985 0 0);
+	--sidebar-primary: oklch(0.488 0.243 264.376);
+	--sidebar-primary-foreground: oklch(0.985 0 0);
+	--sidebar-accent: oklch(0.269 0 0);
+	--sidebar-accent-foreground: oklch(0.985 0 0);
+	--sidebar-border: oklch(0.269 0 0);
+	--sidebar-ring: oklch(0.439 0 0);
+}
+
+@theme inline {
+	--color-background: var(--background);
+	--color-foreground: var(--foreground);
+	--color-card: var(--card);
+	--color-card-foreground: var(--card-foreground);
+	--color-popover: var(--popover);
+	--color-popover-foreground: var(--popover-foreground);
+	--color-primary: var(--primary);
+	--color-primary-foreground: var(--primary-foreground);
+	--color-secondary: var(--secondary);
+	--color-secondary-foreground: var(--secondary-foreground);
+	--color-muted: var(--muted);
+	--color-muted-foreground: var(--muted-foreground);
+	--color-accent: var(--accent);
+	--color-accent-foreground: var(--accent-foreground);
+	--color-destructive: var(--destructive);
+	--color-destructive-foreground: var(--destructive-foreground);
+	--color-border: var(--border);
+	--color-input: var(--input);
+	--color-ring: var(--ring);
+	--color-chart-1: var(--chart-1);
+	--color-chart-2: var(--chart-2);
+	--color-chart-3: var(--chart-3);
+	--color-chart-4: var(--chart-4);
+	--color-chart-5: var(--chart-5);
+	--radius-sm: calc(var(--radius) - 4px);
+	--radius-md: calc(var(--radius) - 2px);
+	--radius-lg: var(--radius);
+	--radius-xl: calc(var(--radius) + 4px);
+	--color-sidebar: var(--sidebar);
+	--color-sidebar-foreground: var(--sidebar-foreground);
+	--color-sidebar-primary: var(--sidebar-primary);
+	--color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+	--color-sidebar-accent: var(--sidebar-accent);
+	--color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+	--color-sidebar-border: var(--sidebar-border);
+	--color-sidebar-ring: var(--sidebar-ring);
+}
+
+@layer base {
+	* {
+		@apply border-border outline-ring/50;
+	}
+	body {
+		@apply bg-background text-foreground;
+	}
+}

packages/extension/src/components/ui/button.tsx

@@ -0,0 +1,60 @@
+import { Slot } from '@radix-ui/react-slot'
+import { type VariantProps, cva } from 'class-variance-authority'
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+const buttonVariants = cva(
+	"inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-md text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4 shrink-0 [&_svg]:shrink-0 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px] aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive",
+	{
+		variants: {
+			variant: {
+				default: 'bg-primary text-primary-foreground hover:bg-primary/90',
+				destructive:
+					'bg-destructive text-white hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:focus-visible:ring-destructive/40 dark:bg-destructive/60',
+				outline:
+					'border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:bg-input/30 dark:border-input dark:hover:bg-input/50',
+				secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+				ghost: 'hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50',
+				link: 'text-primary underline-offset-4 hover:underline',
+			},
+			size: {
+				default: 'h-9 px-4 py-2 has-[>svg]:px-3',
+				sm: 'h-8 rounded-md gap-1.5 px-3 has-[>svg]:px-2.5',
+				lg: 'h-10 rounded-md px-6 has-[>svg]:px-4',
+				icon: 'size-9',
+				'icon-sm': 'size-8',
+				'icon-lg': 'size-10',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+			size: 'default',
+		},
+	}
+)
+
+function Button({
+	className,
+	variant = 'default',
+	size = 'default',
+	asChild = false,
+	...props
+}: React.ComponentProps<'button'> &
+	VariantProps<typeof buttonVariants> & {
+		asChild?: boolean
+	}) {
+	const Comp = asChild ? Slot : 'button'
+
+	return (
+		<Comp
+			data-slot="button"
+			data-variant={variant}
+			data-size={size}
+			className={cn(buttonVariants({ variant, size, className }))}
+			{...props}
+		/>
+	)
+}
+
+export { Button, buttonVariants }

packages/extension/src/components/ui/card.tsx

@@ -0,0 +1,75 @@
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+function Card({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="card"
+			className={cn(
+				'bg-card text-card-foreground flex flex-col gap-6 rounded-xl border py-6 shadow-sm',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+function CardHeader({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="card-header"
+			className={cn(
+				'@container/card-header grid auto-rows-min grid-rows-[auto_auto] items-start gap-2 px-6 has-data-[slot=card-action]:grid-cols-[1fr_auto] [.border-b]:pb-6',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+function CardTitle({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="card-title"
+			className={cn('leading-none font-semibold', className)}
+			{...props}
+		/>
+	)
+}
+
+function CardDescription({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="card-description"
+			className={cn('text-muted-foreground text-sm', className)}
+			{...props}
+		/>
+	)
+}
+
+function CardAction({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="card-action"
+			className={cn('col-start-2 row-span-2 row-start-1 self-start justify-self-end', className)}
+			{...props}
+		/>
+	)
+}
+
+function CardContent({ className, ...props }: React.ComponentProps<'div'>) {
+	return <div data-slot="card-content" className={cn('px-6', className)} {...props} />
+}
+
+function CardFooter({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="card-footer"
+			className={cn('flex items-center px-6 [.border-t]:pt-6', className)}
+			{...props}
+		/>
+	)
+}
+
+export { Card, CardHeader, CardFooter, CardTitle, CardAction, CardDescription, CardContent }

packages/extension/src/components/ui/field.tsx

@@ -0,0 +1,232 @@
+import { type VariantProps, cva } from 'class-variance-authority'
+import { useMemo } from 'react'
+
+import { Label } from '@/components/ui/label'
+import { Separator } from '@/components/ui/separator'
+import { cn } from '@/lib/utils'
+
+function FieldSet({ className, ...props }: React.ComponentProps<'fieldset'>) {
+	return (
+		<fieldset
+			data-slot="field-set"
+			className={cn(
+				'flex flex-col gap-6',
+				'has-[>[data-slot=checkbox-group]]:gap-3 has-[>[data-slot=radio-group]]:gap-3',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+function FieldLegend({
+	className,
+	variant = 'legend',
+	...props
+}: React.ComponentProps<'legend'> & { variant?: 'legend' | 'label' }) {
+	return (
+		<legend
+			data-slot="field-legend"
+			data-variant={variant}
+			className={cn(
+				'mb-3 font-medium',
+				'data-[variant=legend]:text-base',
+				'data-[variant=label]:text-sm',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+function FieldGroup({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="field-group"
+			className={cn(
+				'group/field-group @container/field-group flex w-full flex-col gap-7 data-[slot=checkbox-group]:gap-3 [&>[data-slot=field-group]]:gap-4',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+const fieldVariants = cva('group/field flex w-full gap-3 data-[invalid=true]:text-destructive', {
+	variants: {
+		orientation: {
+			vertical: ['flex-col [&>*]:w-full [&>.sr-only]:w-auto'],
+			horizontal: [
+				'flex-row items-center',
+				'[&>[data-slot=field-label]]:flex-auto',
+				'has-[>[data-slot=field-content]]:items-start has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px',
+			],
+			responsive: [
+				'flex-col [&>*]:w-full [&>.sr-only]:w-auto @md/field-group:flex-row @md/field-group:items-center @md/field-group:[&>*]:w-auto',
+				'@md/field-group:[&>[data-slot=field-label]]:flex-auto',
+				'@md/field-group:has-[>[data-slot=field-content]]:items-start @md/field-group:has-[>[data-slot=field-content]]:[&>[role=checkbox],[role=radio]]:mt-px',
+			],
+		},
+	},
+	defaultVariants: {
+		orientation: 'vertical',
+	},
+})
+
+function Field({
+	className,
+	orientation = 'vertical',
+	...props
+}: React.ComponentProps<'div'> & VariantProps<typeof fieldVariants>) {
+	return (
+		<div
+			role="group"
+			data-slot="field"
+			data-orientation={orientation}
+			className={cn(fieldVariants({ orientation }), className)}
+			{...props}
+		/>
+	)
+}
+
+function FieldContent({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="field-content"
+			className={cn('group/field-content flex flex-1 flex-col gap-1.5 leading-snug', className)}
+			{...props}
+		/>
+	)
+}
+
+function FieldLabel({ className, ...props }: React.ComponentProps<typeof Label>) {
+	return (
+		<Label
+			data-slot="field-label"
+			className={cn(
+				'group/field-label peer/field-label flex w-fit gap-2 leading-snug group-data-[disabled=true]/field:opacity-50',
+				'has-[>[data-slot=field]]:w-full has-[>[data-slot=field]]:flex-col has-[>[data-slot=field]]:rounded-md has-[>[data-slot=field]]:border [&>*]:data-[slot=field]:p-4',
+				'has-data-[state=checked]:bg-primary/5 has-data-[state=checked]:border-primary dark:has-data-[state=checked]:bg-primary/10',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+function FieldTitle({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="field-label"
+			className={cn(
+				'flex w-fit items-center gap-2 text-sm leading-snug font-medium group-data-[disabled=true]/field:opacity-50',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+function FieldDescription({ className, ...props }: React.ComponentProps<'p'>) {
+	return (
+		<p
+			data-slot="field-description"
+			className={cn(
+				'text-muted-foreground text-sm leading-normal font-normal group-has-[[data-orientation=horizontal]]/field:text-balance',
+				'last:mt-0 nth-last-2:-mt-1 [[data-variant=legend]+&]:-mt-1.5',
+				'[&>a:hover]:text-primary [&>a]:underline [&>a]:underline-offset-4',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+function FieldSeparator({
+	children,
+	className,
+	...props
+}: React.ComponentProps<'div'> & {
+	children?: React.ReactNode
+}) {
+	return (
+		<div
+			data-slot="field-separator"
+			data-content={!!children}
+			className={cn(
+				'relative -my-2 h-5 text-sm group-data-[variant=outline]/field-group:-mb-2',
+				className
+			)}
+			{...props}
+		>
+			<Separator className="absolute inset-0 top-1/2" />
+			{children && (
+				<span
+					className="bg-background text-muted-foreground relative mx-auto block w-fit px-2"
+					data-slot="field-separator-content"
+				>
+					{children}
+				</span>
+			)}
+		</div>
+	)
+}
+
+function FieldError({
+	className,
+	children,
+	errors,
+	...props
+}: React.ComponentProps<'div'> & {
+	errors?: Array<{ message?: string } | undefined>
+}) {
+	const content = useMemo(() => {
+		if (children) {
+			return children
+		}
+
+		if (!errors?.length) {
+			return null
+		}
+
+		const uniqueErrors = [...new Map(errors.map((error) => [error?.message, error])).values()]
+
+		if (uniqueErrors?.length == 1) {
+			return uniqueErrors[0]?.message
+		}
+
+		return (
+			<ul className="ml-4 flex list-disc flex-col gap-1">
+				{uniqueErrors.map((error, index) => error?.message && <li key={index}>{error.message}</li>)}
+			</ul>
+		)
+	}, [children, errors])
+
+	if (!content) {
+		return null
+	}
+
+	return (
+		<div
+			role="alert"
+			data-slot="field-error"
+			className={cn('text-destructive text-sm font-normal', className)}
+			{...props}
+		>
+			{content}
+		</div>
+	)
+}
+
+export {
+	Field,
+	FieldLabel,
+	FieldDescription,
+	FieldError,
+	FieldGroup,
+	FieldLegend,
+	FieldSeparator,
+	FieldSet,
+	FieldContent,
+	FieldTitle,
+}

packages/extension/src/components/ui/hover-card.tsx

@@ -0,0 +1,36 @@
+import * as HoverCardPrimitive from '@radix-ui/react-hover-card'
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+function HoverCard({ ...props }: React.ComponentProps<typeof HoverCardPrimitive.Root>) {
+	return <HoverCardPrimitive.Root data-slot="hover-card" {...props} />
+}
+
+function HoverCardTrigger({ ...props }: React.ComponentProps<typeof HoverCardPrimitive.Trigger>) {
+	return <HoverCardPrimitive.Trigger data-slot="hover-card-trigger" {...props} />
+}
+
+function HoverCardContent({
+	className,
+	align = 'center',
+	sideOffset = 4,
+	...props
+}: React.ComponentProps<typeof HoverCardPrimitive.Content>) {
+	return (
+		<HoverCardPrimitive.Portal data-slot="hover-card-portal">
+			<HoverCardPrimitive.Content
+				data-slot="hover-card-content"
+				align={align}
+				sideOffset={sideOffset}
+				className={cn(
+					'bg-popover text-popover-foreground data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0 data-[state=closed]:zoom-out-95 data-[state=open]:zoom-in-95 data-[side=bottom]:slide-in-from-top-2 data-[side=left]:slide-in-from-right-2 data-[side=right]:slide-in-from-left-2 data-[side=top]:slide-in-from-bottom-2 z-50 w-64 origin-(--radix-hover-card-content-transform-origin) rounded-md border p-4 shadow-md outline-hidden',
+					className
+				)}
+				{...props}
+			/>
+		</HoverCardPrimitive.Portal>
+	)
+}
+
+export { HoverCard, HoverCardTrigger, HoverCardContent }

packages/extension/src/components/ui/input-group.tsx

@@ -0,0 +1,156 @@
+import { type VariantProps, cva } from 'class-variance-authority'
+import * as React from 'react'
+
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+import { Textarea } from '@/components/ui/textarea'
+import { cn } from '@/lib/utils'
+
+function InputGroup({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="input-group"
+			role="group"
+			className={cn(
+				'group/input-group border-input dark:bg-input/30 relative flex w-full items-center rounded-md border shadow-xs transition-[color,box-shadow] outline-none',
+				'h-9 min-w-0 has-[>textarea]:h-auto',
+
+				// Variants based on alignment.
+				'has-[>[data-align=inline-start]]:[&>input]:pl-2',
+				'has-[>[data-align=inline-end]]:[&>input]:pr-2',
+				'has-[>[data-align=block-start]]:h-auto has-[>[data-align=block-start]]:flex-col has-[>[data-align=block-start]]:[&>input]:pb-3',
+				'has-[>[data-align=block-end]]:h-auto has-[>[data-align=block-end]]:flex-col has-[>[data-align=block-end]]:[&>input]:pt-3',
+
+				// Focus state.
+				'has-[[data-slot=input-group-control]:focus-visible]:border-ring has-[[data-slot=input-group-control]:focus-visible]:ring-ring/50 has-[[data-slot=input-group-control]:focus-visible]:ring-[3px]',
+
+				// Error state.
+				'has-[[data-slot][aria-invalid=true]]:ring-destructive/20 has-[[data-slot][aria-invalid=true]]:border-destructive dark:has-[[data-slot][aria-invalid=true]]:ring-destructive/40',
+
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+const inputGroupAddonVariants = cva(
+	"text-muted-foreground flex h-auto cursor-text items-center justify-center gap-2 py-1.5 text-sm font-medium select-none [&>svg:not([class*='size-'])]:size-4 [&>kbd]:rounded-[calc(var(--radius)-5px)] group-data-[disabled=true]/input-group:opacity-50",
+	{
+		variants: {
+			align: {
+				'inline-start': 'order-first pl-3 has-[>button]:ml-[-0.45rem] has-[>kbd]:ml-[-0.35rem]',
+				'inline-end': 'order-last pr-3 has-[>button]:mr-[-0.45rem] has-[>kbd]:mr-[-0.35rem]',
+				'block-start':
+					'order-first w-full justify-start px-3 pt-3 [.border-b]:pb-3 group-has-[>input]/input-group:pt-2.5',
+				'block-end':
+					'order-last w-full justify-start px-3 pb-3 [.border-t]:pt-3 group-has-[>input]/input-group:pb-2.5',
+			},
+		},
+		defaultVariants: {
+			align: 'inline-start',
+		},
+	}
+)
+
+function InputGroupAddon({
+	className,
+	align = 'inline-start',
+	...props
+}: React.ComponentProps<'div'> & VariantProps<typeof inputGroupAddonVariants>) {
+	return (
+		<div
+			role="group"
+			data-slot="input-group-addon"
+			data-align={align}
+			className={cn(inputGroupAddonVariants({ align }), className)}
+			onClick={(e) => {
+				if ((e.target as HTMLElement).closest('button')) {
+					return
+				}
+				e.currentTarget.parentElement?.querySelector('input')?.focus()
+			}}
+			{...props}
+		/>
+	)
+}
+
+const inputGroupButtonVariants = cva('text-sm shadow-none flex gap-2 items-center', {
+	variants: {
+		size: {
+			xs: "h-6 gap-1 px-2 rounded-[calc(var(--radius)-5px)] [&>svg:not([class*='size-'])]:size-3.5 has-[>svg]:px-2",
+			sm: 'h-8 px-2.5 gap-1.5 rounded-md has-[>svg]:px-2.5',
+			'icon-xs': 'size-6 rounded-[calc(var(--radius)-5px)] p-0 has-[>svg]:p-0',
+			'icon-sm': 'size-8 p-0 has-[>svg]:p-0',
+		},
+	},
+	defaultVariants: {
+		size: 'xs',
+	},
+})
+
+function InputGroupButton({
+	className,
+	type = 'button',
+	variant = 'ghost',
+	size = 'xs',
+	...props
+}: Omit<React.ComponentProps<typeof Button>, 'size'> &
+	VariantProps<typeof inputGroupButtonVariants>) {
+	return (
+		<Button
+			type={type}
+			data-size={size}
+			variant={variant}
+			className={cn(inputGroupButtonVariants({ size }), className)}
+			{...props}
+		/>
+	)
+}
+
+function InputGroupText({ className, ...props }: React.ComponentProps<'span'>) {
+	return (
+		<span
+			className={cn(
+				"text-muted-foreground flex items-center gap-2 text-sm [&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4",
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+function InputGroupInput({ className, ...props }: React.ComponentProps<'input'>) {
+	return (
+		<Input
+			data-slot="input-group-control"
+			className={cn(
+				'flex-1 rounded-none border-0 bg-transparent shadow-none focus-visible:ring-0 dark:bg-transparent',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+function InputGroupTextarea({ className, ...props }: React.ComponentProps<'textarea'>) {
+	return (
+		<Textarea
+			data-slot="input-group-control"
+			className={cn(
+				'flex-1 resize-none rounded-none border-0 bg-transparent py-3 shadow-none focus-visible:ring-0 dark:bg-transparent',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+export {
+	InputGroup,
+	InputGroupAddon,
+	InputGroupButton,
+	InputGroupText,
+	InputGroupInput,
+	InputGroupTextarea,
+}

packages/extension/src/components/ui/input.tsx

@@ -0,0 +1,21 @@
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+function Input({ className, type, ...props }: React.ComponentProps<'input'>) {
+	return (
+		<input
+			type={type}
+			data-slot="input"
+			className={cn(
+				'file:text-foreground placeholder:text-muted-foreground selection:bg-primary selection:text-primary-foreground dark:bg-input/30 border-input h-9 w-full min-w-0 rounded-md border bg-transparent px-3 py-1 text-base shadow-xs transition-[color,box-shadow] outline-none file:inline-flex file:h-7 file:border-0 file:bg-transparent file:text-sm file:font-medium disabled:pointer-events-none disabled:cursor-not-allowed disabled:opacity-50 md:text-sm',
+				'focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]',
+				'aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+export { Input }

packages/extension/src/components/ui/item.tsx

@@ -0,0 +1,172 @@
+import { Slot } from '@radix-ui/react-slot'
+import { type VariantProps, cva } from 'class-variance-authority'
+import * as React from 'react'
+
+import { Separator } from '@/components/ui/separator'
+import { cn } from '@/lib/utils'
+
+function ItemGroup({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			role="list"
+			data-slot="item-group"
+			className={cn('group/item-group flex flex-col', className)}
+			{...props}
+		/>
+	)
+}
+
+function ItemSeparator({ className, ...props }: React.ComponentProps<typeof Separator>) {
+	return (
+		<Separator
+			data-slot="item-separator"
+			orientation="horizontal"
+			className={cn('my-0', className)}
+			{...props}
+		/>
+	)
+}
+
+const itemVariants = cva(
+	'group/item flex items-center border border-transparent text-sm rounded-md transition-colors [a]:hover:bg-accent/50 [a]:transition-colors duration-100 flex-wrap outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]',
+	{
+		variants: {
+			variant: {
+				default: 'bg-transparent',
+				outline: 'border-border',
+				muted: 'bg-muted/50',
+			},
+			size: {
+				default: 'p-4 gap-4 ',
+				sm: 'py-3 px-4 gap-2.5',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+			size: 'default',
+		},
+	}
+)
+
+function Item({
+	className,
+	variant = 'default',
+	size = 'default',
+	asChild = false,
+	...props
+}: React.ComponentProps<'div'> & VariantProps<typeof itemVariants> & { asChild?: boolean }) {
+	const Comp = asChild ? Slot : 'div'
+	return (
+		<Comp
+			data-slot="item"
+			data-variant={variant}
+			data-size={size}
+			className={cn(itemVariants({ variant, size, className }))}
+			{...props}
+		/>
+	)
+}
+
+const itemMediaVariants = cva(
+	'flex shrink-0 items-center justify-center gap-2 group-has-[[data-slot=item-description]]/item:self-start [&_svg]:pointer-events-none group-has-[[data-slot=item-description]]/item:translate-y-0.5',
+	{
+		variants: {
+			variant: {
+				default: 'bg-transparent',
+				icon: "size-8 border rounded-sm bg-muted [&_svg:not([class*='size-'])]:size-4",
+				image: 'size-10 rounded-sm overflow-hidden [&_img]:size-full [&_img]:object-cover',
+			},
+		},
+		defaultVariants: {
+			variant: 'default',
+		},
+	}
+)
+
+function ItemMedia({
+	className,
+	variant = 'default',
+	...props
+}: React.ComponentProps<'div'> & VariantProps<typeof itemMediaVariants>) {
+	return (
+		<div
+			data-slot="item-media"
+			data-variant={variant}
+			className={cn(itemMediaVariants({ variant, className }))}
+			{...props}
+		/>
+	)
+}
+
+function ItemContent({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="item-content"
+			className={cn('flex flex-1 flex-col gap-1 [&+[data-slot=item-content]]:flex-none', className)}
+			{...props}
+		/>
+	)
+}
+
+function ItemTitle({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="item-title"
+			className={cn('flex w-fit items-center gap-2 text-sm leading-snug font-medium', className)}
+			{...props}
+		/>
+	)
+}
+
+function ItemDescription({ className, ...props }: React.ComponentProps<'p'>) {
+	return (
+		<p
+			data-slot="item-description"
+			className={cn(
+				'text-muted-foreground line-clamp-2 text-sm leading-normal font-normal text-balance',
+				'[&>a:hover]:text-primary [&>a]:underline [&>a]:underline-offset-4',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+function ItemActions({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div data-slot="item-actions" className={cn('flex items-center gap-2', className)} {...props} />
+	)
+}
+
+function ItemHeader({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="item-header"
+			className={cn('flex basis-full items-center justify-between gap-2', className)}
+			{...props}
+		/>
+	)
+}
+
+function ItemFooter({ className, ...props }: React.ComponentProps<'div'>) {
+	return (
+		<div
+			data-slot="item-footer"
+			className={cn('flex basis-full items-center justify-between gap-2', className)}
+			{...props}
+		/>
+	)
+}
+
+export {
+	Item,
+	ItemMedia,
+	ItemContent,
+	ItemActions,
+	ItemGroup,
+	ItemSeparator,
+	ItemTitle,
+	ItemDescription,
+	ItemHeader,
+	ItemFooter,
+}

packages/extension/src/components/ui/label.tsx

@@ -0,0 +1,19 @@
+import * as LabelPrimitive from '@radix-ui/react-label'
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+function Label({ className, ...props }: React.ComponentProps<typeof LabelPrimitive.Root>) {
+	return (
+		<LabelPrimitive.Root
+			data-slot="label"
+			className={cn(
+				'flex items-center gap-2 text-sm leading-none font-medium select-none group-data-[disabled=true]:pointer-events-none group-data-[disabled=true]:opacity-50 peer-disabled:cursor-not-allowed peer-disabled:opacity-50',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+export { Label }

packages/extension/src/components/ui/separator.tsx

@@ -0,0 +1,26 @@
+import * as SeparatorPrimitive from '@radix-ui/react-separator'
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+function Separator({
+	className,
+	orientation = 'horizontal',
+	decorative = true,
+	...props
+}: React.ComponentProps<typeof SeparatorPrimitive.Root>) {
+	return (
+		<SeparatorPrimitive.Root
+			data-slot="separator"
+			decorative={decorative}
+			orientation={orientation}
+			className={cn(
+				'bg-border shrink-0 data-[orientation=horizontal]:h-px data-[orientation=horizontal]:w-full data-[orientation=vertical]:h-full data-[orientation=vertical]:w-px',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+export { Separator }

packages/extension/src/components/ui/sonner.tsx

@@ -0,0 +1,38 @@
+import {
+	CircleCheckIcon,
+	InfoIcon,
+	Loader2Icon,
+	OctagonXIcon,
+	TriangleAlertIcon,
+} from 'lucide-react'
+import { useTheme } from 'next-themes'
+import { Toaster as Sonner, type ToasterProps } from 'sonner'
+
+const Toaster = ({ ...props }: ToasterProps) => {
+	const { theme = 'system' } = useTheme()
+
+	return (
+		<Sonner
+			theme={theme as ToasterProps['theme']}
+			className="toaster group"
+			icons={{
+				success: <CircleCheckIcon className="size-4" />,
+				info: <InfoIcon className="size-4" />,
+				warning: <TriangleAlertIcon className="size-4" />,
+				error: <OctagonXIcon className="size-4" />,
+				loading: <Loader2Icon className="size-4 animate-spin" />,
+			}}
+			style={
+				{
+					'--normal-bg': 'var(--popover)',
+					'--normal-text': 'var(--popover-foreground)',
+					'--normal-border': 'var(--border)',
+					'--border-radius': 'var(--radius)',
+				} as React.CSSProperties
+			}
+			{...props}
+		/>
+	)
+}
+
+export { Toaster }

packages/extension/src/components/ui/spinner.tsx

@@ -0,0 +1,16 @@
+import { Loader2Icon } from 'lucide-react'
+
+import { cn } from '@/lib/utils'
+
+function Spinner({ className, ...props }: React.ComponentProps<'svg'>) {
+	return (
+		<Loader2Icon
+			role="status"
+			aria-label="Loading"
+			className={cn('size-4 animate-spin', className)}
+			{...props}
+		/>
+	)
+}
+
+export { Spinner }

packages/extension/src/components/ui/switch.tsx

@@ -0,0 +1,26 @@
+import * as SwitchPrimitive from '@radix-ui/react-switch'
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+function Switch({ className, ...props }: React.ComponentProps<typeof SwitchPrimitive.Root>) {
+	return (
+		<SwitchPrimitive.Root
+			data-slot="switch"
+			className={cn(
+				'peer data-[state=checked]:bg-primary data-[state=unchecked]:bg-input focus-visible:border-ring focus-visible:ring-ring/50 dark:data-[state=unchecked]:bg-input/80 inline-flex h-[1.15rem] w-8 shrink-0 items-center rounded-full border border-transparent shadow-xs transition-all outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50',
+				className
+			)}
+			{...props}
+		>
+			<SwitchPrimitive.Thumb
+				data-slot="switch-thumb"
+				className={cn(
+					'bg-background dark:data-[state=unchecked]:bg-foreground dark:data-[state=checked]:bg-primary-foreground pointer-events-none block size-4 rounded-full ring-0 transition-transform data-[state=checked]:translate-x-[calc(100%-2px)] data-[state=unchecked]:translate-x-0'
+				)}
+			/>
+		</SwitchPrimitive.Root>
+	)
+}
+
+export { Switch }

packages/extension/src/components/ui/textarea.tsx

@@ -0,0 +1,18 @@
+import * as React from 'react'
+
+import { cn } from '@/lib/utils'
+
+function Textarea({ className, ...props }: React.ComponentProps<'textarea'>) {
+	return (
+		<textarea
+			data-slot="textarea"
+			className={cn(
+				'border-input placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 aria-invalid:border-destructive dark:bg-input/30 flex field-sizing-content min-h-16 w-full rounded-md border bg-transparent px-3 py-2 text-base shadow-xs transition-[color,box-shadow] outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50 md:text-sm',
+				className
+			)}
+			{...props}
+		/>
+	)
+}
+
+export { Textarea }

packages/extension/src/entrypoints/background.ts

@@ -0,0 +1,36 @@
+import { handlePageControlMessage } from '@/agent/RemotePageController.background'
+import { handleTabControlMessage, setupTabChangeEvents } from '@/agent/TabsController.background'
+
+export default defineBackground(() => {
+	console.log('[Background] Service Worker started')
+
+	// tab change events
+
+	setupTabChangeEvents()
+
+	// generate user auth token
+
+	chrome.storage.local.get('PageAgentExtUserAuthToken').then((result) => {
+		if (result.PageAgentExtUserAuthToken) return
+
+		const userAuthToken = crypto.randomUUID()
+		chrome.storage.local.set({ PageAgentExtUserAuthToken: userAuthToken })
+	})
+
+	// message proxy
+
+	chrome.runtime.onMessage.addListener((message, sender, sendResponse): true | undefined => {
+		if (message.type === 'TAB_CONTROL') {
+			return handleTabControlMessage(message, sender, sendResponse)
+		} else if (message.type === 'PAGE_CONTROL') {
+			return handlePageControlMessage(message, sender, sendResponse)
+		} else {
+			sendResponse({ error: 'Unknown message type' })
+			return
+		}
+	})
+
+	// setup
+
+	chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true }).catch(() => {})
+})

packages/extension/src/entrypoints/content.ts

@@ -0,0 +1,169 @@
+import { initPageController } from '@/agent/RemotePageController.content'
+
+// import { DEMO_CONFIG } from '@/agent/constants'
+
+const DEBUG_PREFIX = '[Content]'
+
+export default defineContentScript({
+	matches: ['<all_urls>'],
+	runAt: 'document_end',
+
+	main() {
+		console.debug(`${DEBUG_PREFIX} Loaded on ${window.location.href}`)
+		initPageController()
+
+		// if auth token matches, expose agent to page
+		chrome.storage.local.get('PageAgentExtUserAuthToken').then((result) => {
+			// extension side token.
+			// @note this is isolated world. it is safe to assume user script cannot access it
+			const extToken = result.PageAgentExtUserAuthToken
+			if (!extToken) return
+
+			// page side token
+			const pageToken = localStorage.getItem('PageAgentExtUserAuthToken')
+			if (!pageToken) return
+
+			if (pageToken !== extToken) return
+
+			console.log('[PageAgentExt]: Auth tokens match. Exposing agent to page.')
+
+			// add isolated world script
+			exposeAgentToPage().then(
+				// add main-world script
+				() => injectScript('/main-world.js')
+			)
+		})
+	},
+})
+
+async function exposeAgentToPage() {
+	const { MultiPageAgent } = await import('@/agent/MultiPageAgent')
+	console.log('[PageAgentExt]: MultiPageAgent loaded')
+
+	/**
+	 * singleton MultiPageAgent to handle requests from the page
+	 */
+	let multiPageAgent: InstanceType<typeof MultiPageAgent> | null = null
+
+	window.addEventListener('message', async (e) => {
+		const data = e.data
+		if (typeof data !== 'object' || data === null) return
+		if (data.channel !== 'PAGE_AGENT_EXT_REQUEST') return
+
+		const { action, payload, id } = data
+
+		switch (action) {
+			case 'execute': {
+				// singleton check
+				if (multiPageAgent && multiPageAgent.status === 'running') {
+					window.postMessage(
+						{
+							channel: 'PAGE_AGENT_EXT_RESPONSE',
+							id,
+							action: 'execute_result',
+							error: 'Agent is already running a task. Please wait until it finishes.',
+						},
+						'*'
+					)
+					return
+				}
+
+				try {
+					const { task, config } = payload
+
+					// create when used
+
+					multiPageAgent = new MultiPageAgent(config)
+
+					// events
+
+					multiPageAgent.addEventListener('statuschange', (event) => {
+						if (!multiPageAgent) return
+						window.postMessage(
+							{
+								channel: 'PAGE_AGENT_EXT_RESPONSE',
+								id,
+								action: 'status_change_event',
+								payload: multiPageAgent.status,
+							},
+							'*'
+						)
+					})
+
+					multiPageAgent.addEventListener('activity', (event) => {
+						if (!multiPageAgent) return
+						window.postMessage(
+							{
+								channel: 'PAGE_AGENT_EXT_RESPONSE',
+								id,
+								action: 'activity_event',
+								payload: (event as CustomEvent).detail,
+							},
+							'*'
+						)
+					})
+
+					multiPageAgent.addEventListener('historychange', (event) => {
+						if (!multiPageAgent) return
+						window.postMessage(
+							{
+								channel: 'PAGE_AGENT_EXT_RESPONSE',
+								id,
+								action: 'history_change_event',
+								payload: multiPageAgent.history,
+							},
+							'*'
+						)
+					})
+
+					multiPageAgent.addEventListener('dispose', () => {
+						window.postMessage(
+							{
+								channel: 'PAGE_AGENT_EXT_RESPONSE',
+								id,
+								action: 'dispose_event',
+							},
+							'*'
+						)
+					})
+
+					// result
+
+					const result = await multiPageAgent.execute(task)
+
+					window.postMessage(
+						{
+							channel: 'PAGE_AGENT_EXT_RESPONSE',
+							id,
+							action: 'execute_result',
+							payload: result,
+						},
+						'*'
+					)
+				} catch (error) {
+					window.postMessage(
+						{
+							channel: 'PAGE_AGENT_EXT_RESPONSE',
+							id,
+							action: 'execute_result',
+							error: (error as Error).message,
+						},
+						'*'
+					)
+				}
+
+				break
+			}
+
+			case 'dispose': {
+				// @note stop ongoing processes but can still be re-used later
+				multiPageAgent?.dispose()
+				break
+			}
+
+			default:
+				console.warn(`${DEBUG_PREFIX} Unknown action from page:`, action)
+				break
+		}
+	})
+}

packages/extension/src/entrypoints/main-world.ts

@@ -0,0 +1,126 @@
+import type { AgentActivity, AgentStatus, ExecutionResult, HistoricalEvent } from '@page-agent/core'
+
+export type Execute = (task: string, config: ExecuteConfig) => Promise<ExecutionResult>
+
+export interface ExecuteConfig {
+	baseURL: string
+	apiKey: string
+	model: string
+
+	/**
+	 * Whether to include the initial tab (that holds this main world script) in the task.
+	 * @default true
+	 */
+	includeInitialTab?: boolean
+
+	onStatusChange?: (status: AgentStatus) => void
+	onActivity?: (activity: AgentActivity) => void
+	onHistoryUpdate?: (history: HistoricalEvent[]) => void
+	onDispose?: () => void
+}
+
+export default defineUnlistedScript(() => {
+	let _lastId = 0
+	function getId() {
+		_lastId += 1
+		return _lastId
+	}
+
+	const execute: Execute = async (task, config) => {
+		if (typeof task !== 'string') throw new Error('Task must be a string')
+		if (task.trim().length === 0) throw new Error('Task cannot be empty')
+		if (!config) throw new Error('Config is required')
+		if (!config.baseURL) throw new Error('Config must have a baseURL')
+		if (!config.apiKey) throw new Error('Config must have an apiKey')
+		if (!config.model) throw new Error('Config must have a model')
+
+		const id = getId()
+
+		const promise = new Promise<ExecutionResult>((resolve, reject) => {
+			function handleMessage(e: MessageEvent) {
+				const data = e.data
+				if (typeof data !== 'object' || data === null) return
+				if (data.channel !== 'PAGE_AGENT_EXT_RESPONSE') return
+				if (data.id !== id) return
+
+				// events
+
+				if (data.action === 'status_change_event' && config.onStatusChange) {
+					config.onStatusChange(data.payload)
+					return
+				}
+
+				if (data.action === 'activity_event' && config.onActivity) {
+					config.onActivity(data.payload)
+					return
+				}
+
+				if (data.action === 'history_change_event' && config.onHistoryUpdate) {
+					config.onHistoryUpdate(data.payload)
+					return
+				}
+
+				if (data.action === 'dispose_event' && config.onDispose) {
+					config.onDispose()
+					window.removeEventListener('message', handleMessage)
+					return
+				}
+
+				if (data.action !== 'execute_result') return
+
+				// execute_result
+
+				window.removeEventListener('message', handleMessage)
+
+				if (data.error) {
+					reject(new Error(data.error))
+				} else {
+					resolve(data.payload)
+				}
+			}
+
+			// @note will be removed on dispose or result
+			window.addEventListener('message', handleMessage)
+		})
+
+		window.postMessage(
+			{
+				channel: 'PAGE_AGENT_EXT_REQUEST',
+				id,
+				action: 'execute',
+				payload: {
+					task,
+					config: {
+						baseURL: config.baseURL,
+						apiKey: config.apiKey,
+						model: config.model,
+						includeInitialTab: config.includeInitialTab,
+					},
+				},
+			},
+			'*'
+		)
+
+		return promise
+	}
+
+	const dispose = () => {
+		const id = getId()
+
+		window.postMessage(
+			{
+				channel: 'PAGE_AGENT_EXT_REQUEST',
+				id,
+				action: 'dispose',
+			},
+			'*'
+		)
+	}
+
+	;(window as any).PAGE_AGENT_EXT_VERSION = __EXT_VERSION__
+	;(window as any).PAGE_AGENT_EXT = {
+		version: __EXT_VERSION__,
+		execute,
+		dispose,
+	}
+})

packages/extension/src/entrypoints/sidepanel/App.tsx

@@ -0,0 +1,212 @@
+import { History, Send, Settings, Square } from 'lucide-react'
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+import { Button } from '@/components/ui/button'
+import {
+	InputGroup,
+	InputGroupAddon,
+	InputGroupButton,
+	InputGroupTextarea,
+} from '@/components/ui/input-group'
+import { saveSession } from '@/lib/db'
+
+import { useAgent } from '../../agent/useAgent'
+import { ConfigPanel } from './components/ConfigPanel'
+import { HistoryDetail } from './components/HistoryDetail'
+import { HistoryList } from './components/HistoryList'
+import { ActivityCard, EventCard } from './components/cards'
+import { EmptyState, Logo, StatusDot } from './components/misc'
+
+type View =
+	| { name: 'chat' }
+	| { name: 'config' }
+	| { name: 'history' }
+	| { name: 'history-detail'; sessionId: string }
+
+export default function App() {
+	const [view, setView] = useState<View>({ name: 'chat' })
+	const [inputValue, setInputValue] = useState('')
+	const historyRef = useRef<HTMLDivElement>(null)
+	const textareaRef = useRef<HTMLTextAreaElement>(null)
+
+	const { status, history, activity, currentTask, config, execute, stop, configure } = useAgent()
+
+	// Persist session when task finishes
+	const prevStatusRef = useRef(status)
+	useEffect(() => {
+		const prev = prevStatusRef.current
+		prevStatusRef.current = status
+
+		if (
+			prev === 'running' &&
+			(status === 'completed' || status === 'error') &&
+			history.length > 0 &&
+			currentTask
+		) {
+			saveSession({ task: currentTask, history, status }).catch((err) =>
+				console.error('[SidePanel] Failed to save session:', err)
+			)
+		}
+	}, [status, history, currentTask])
+
+	// Auto-scroll to bottom on new events
+	useEffect(() => {
+		if (historyRef.current) {
+			historyRef.current.scrollTop = historyRef.current.scrollHeight
+		}
+	}, [history, activity])
+
+	const handleSubmit = useCallback(
+		(e?: React.SyntheticEvent) => {
+			e?.preventDefault()
+			if (!inputValue.trim() || status === 'running') return
+
+			const taskToExecute = inputValue.trim()
+			setInputValue('')
+
+			execute(taskToExecute).catch((error) => {
+				console.error('[SidePanel] Failed to execute task:', error)
+			})
+		},
+		[inputValue, status, execute]
+	)
+
+	const handleStop = useCallback(() => {
+		console.log('[SidePanel] Stopping task...')
+		stop()
+	}, [stop])
+
+	const handleKeyDown = (e: React.KeyboardEvent) => {
+		if (e.key === 'Enter' && !e.shiftKey && !e.nativeEvent.isComposing) {
+			e.preventDefault()
+			handleSubmit()
+		}
+	}
+
+	// --- View routing ---
+
+	if (view.name === 'config') {
+		return (
+			<ConfigPanel
+				config={config}
+				onSave={async (newConfig) => {
+					await configure(newConfig)
+					setView({ name: 'chat' })
+				}}
+				onClose={() => setView({ name: 'chat' })}
+			/>
+		)
+	}
+
+	if (view.name === 'history') {
+		return (
+			<HistoryList
+				onSelect={(id) => setView({ name: 'history-detail', sessionId: id })}
+				onBack={() => setView({ name: 'chat' })}
+			/>
+		)
+	}
+
+	if (view.name === 'history-detail') {
+		return <HistoryDetail sessionId={view.sessionId} onBack={() => setView({ name: 'history' })} />
+	}
+
+	// --- Chat view ---
+
+	const isRunning = status === 'running'
+	const showEmptyState = !currentTask && history.length === 0 && !isRunning
+
+	return (
+		<div className="flex flex-col h-screen bg-background">
+			{/* Header */}
+			<header className="flex items-center justify-between border-b px-3 py-2">
+				<div className="flex items-center gap-2">
+					<Logo className="size-5" />
+					<span className="text-sm font-medium">Page Agent Ext</span>
+				</div>
+				<div className="flex items-center gap-3">
+					<StatusDot status={status} />
+					<Button
+						variant="ghost"
+						size="icon-sm"
+						onClick={() => setView({ name: 'history' })}
+						className="cursor-pointer"
+					>
+						<History className="size-3.5" />
+					</Button>
+					<Button
+						variant="ghost"
+						size="icon-sm"
+						onClick={() => setView({ name: 'config' })}
+						className="cursor-pointer"
+					>
+						<Settings className="size-3.5" />
+					</Button>
+				</div>
+			</header>
+
+			{/* Content */}
+			<main className="flex-1 overflow-hidden flex flex-col">
+				{/* Current task */}
+				{currentTask && (
+					<div className="border-b px-3 py-2 bg-muted/30">
+						<div className="text-[10px] text-muted-foreground uppercase tracking-wide">Task</div>
+						<div className="text-xs font-medium truncate" title={currentTask}>
+							{currentTask}
+						</div>
+					</div>
+				)}
+
+				{/* History */}
+				<div ref={historyRef} className="flex-1 overflow-y-auto p-3 space-y-2">
+					{showEmptyState && <EmptyState />}
+
+					{history.map((event, index) => (
+						// eslint-disable-next-line react-x/no-array-index-key
+						<EventCard key={index} event={event} />
+					))}
+
+					{/* Activity indicator at bottom */}
+					{activity && <ActivityCard activity={activity} />}
+				</div>
+			</main>
+
+			{/* Input */}
+			<footer className="border-t p-3">
+				<InputGroup className="relative rounded-lg">
+					<InputGroupTextarea
+						ref={textareaRef}
+						placeholder="Describe your task... (Enter to send)"
+						value={inputValue}
+						onChange={(e) => setInputValue(e.target.value)}
+						onKeyDown={handleKeyDown}
+						disabled={isRunning}
+						className="text-xs pr-12 min-h-10"
+					/>
+					<InputGroupAddon align="inline-end" className="absolute bottom-0 right-0">
+						{isRunning ? (
+							<InputGroupButton
+								size="icon-sm"
+								variant="destructive"
+								onClick={handleStop}
+								className="size-7"
+							>
+								<Square className="size-3" />
+							</InputGroupButton>
+						) : (
+							<InputGroupButton
+								size="icon-sm"
+								variant="default"
+								onClick={() => handleSubmit()}
+								disabled={!inputValue.trim()}
+								className="size-7 cursor-pointer"
+							>
+								<Send className="size-3" />
+							</InputGroupButton>
+						)}
+					</InputGroupAddon>
+				</InputGroup>
+			</footer>
+		</div>
+	)
+}

packages/extension/src/entrypoints/sidepanel/components/ConfigPanel.tsx

@@ -0,0 +1,243 @@
+import type { LLMConfig } from '@page-agent/llms'
+import { Copy, CornerUpLeft, Eye, EyeOff, HatGlasses, Home, Loader2, Scale } from 'lucide-react'
+import { useEffect, useState } from 'react'
+import { siGithub } from 'simple-icons'
+
+import { DEMO_API_KEY, DEMO_BASE_URL, DEMO_MODEL } from '@/agent/constants'
+import { Button } from '@/components/ui/button'
+import { Input } from '@/components/ui/input'
+
+interface ConfigPanelProps {
+	config: LLMConfig | null
+	onSave: (config: LLMConfig) => Promise<void>
+	onClose: () => void
+}
+
+export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
+	const [apiKey, setApiKey] = useState(config?.apiKey || DEMO_API_KEY)
+	const [baseURL, setBaseURL] = useState(config?.baseURL || DEMO_BASE_URL)
+	const [model, setModel] = useState(config?.model || DEMO_MODEL)
+	const [saving, setSaving] = useState(false)
+	const [userAuthToken, setUserAuthToken] = useState<string>('')
+	const [copied, setCopied] = useState(false)
+	const [showToken, setShowToken] = useState(false)
+	const [showApiKey, setShowApiKey] = useState(false)
+
+	// Update local state when config prop changes
+	useEffect(() => {
+		setApiKey(config?.apiKey || DEMO_API_KEY)
+		setBaseURL(config?.baseURL || DEMO_BASE_URL)
+		setModel(config?.model || DEMO_MODEL)
+	}, [config])
+
+	// Poll for user auth token every second until found
+	useEffect(() => {
+		let interval: NodeJS.Timeout | null = null
+
+		const fetchToken = async () => {
+			const result = await chrome.storage.local.get('PageAgentExtUserAuthToken')
+			const token = result.PageAgentExtUserAuthToken
+			if (typeof token === 'string' && token) {
+				setUserAuthToken(token)
+				if (interval) {
+					clearInterval(interval)
+					interval = null
+				}
+			}
+		}
+
+		fetchToken()
+		interval = setInterval(fetchToken, 1000)
+
+		return () => {
+			if (interval) clearInterval(interval)
+		}
+	}, [])
+
+	const handleCopyToken = async () => {
+		if (userAuthToken) {
+			await navigator.clipboard.writeText(userAuthToken)
+			setCopied(true)
+			setTimeout(() => setCopied(false), 2000)
+		}
+	}
+
+	const handleSave = async () => {
+		setSaving(true)
+		try {
+			await onSave({ apiKey, baseURL, model })
+		} finally {
+			setSaving(false)
+		}
+	}
+
+	return (
+		<div className="flex flex-col gap-4 p-4 relative">
+			<div className="flex items-center justify-between">
+				<h2 className="text-base font-semibold">Settings</h2>
+				<Button
+					variant="ghost"
+					size="icon-sm"
+					onClick={onClose}
+					className="absolute top-2 right-3 cursor-pointer"
+				>
+					<CornerUpLeft className="size-3.5" />
+				</Button>
+			</div>
+
+			{/* User Auth Token Section */}
+			<div className="flex flex-col gap-1.5 p-3 bg-muted/50 rounded-md border">
+				<label className="text-xs font-medium text-muted-foreground">User Auth Token</label>
+				<p className="text-[10px] text-muted-foreground mb-1">
+					Add this token to a website's localStorage to give it authorization to call this extension
+				</p>
+				<div className="flex gap-2 items-center">
+					<Input
+						readOnly
+						value={
+							userAuthToken
+								? showToken
+									? userAuthToken
+									: `${userAuthToken.slice(0, 4)}${'•'.repeat(userAuthToken.length - 8)}${userAuthToken.slice(-4)}`
+								: 'Loading...'
+						}
+						className="text-xs h-8 font-mono bg-background"
+					/>
+					<Button
+						variant="outline"
+						size="icon"
+						className="h-8 w-8 shrink-0 cursor-pointer"
+						onClick={() => setShowToken(!showToken)}
+						disabled={!userAuthToken}
+					>
+						{showToken ? <EyeOff className="size-3" /> : <Eye className="size-3" />}
+					</Button>
+					<Button
+						variant="outline"
+						size="icon"
+						className="h-8 w-8 shrink-0 cursor-pointer"
+						onClick={handleCopyToken}
+						disabled={!userAuthToken}
+					>
+						{copied ? <span className="">✓</span> : <Copy className="size-3" />}
+					</Button>
+				</div>
+			</div>
+
+			<div className="flex flex-col gap-1.5">
+				<label className="text-xs text-muted-foreground">Base URL</label>
+				<Input
+					placeholder="https://api.openai.com/v1"
+					value={baseURL}
+					onChange={(e) => setBaseURL(e.target.value)}
+					className="text-xs h-8"
+				/>
+			</div>
+
+			<div className="flex flex-col gap-1.5">
+				<label className="text-xs text-muted-foreground">Model</label>
+				<Input
+					placeholder="gpt-5.2"
+					value={model}
+					onChange={(e) => setModel(e.target.value)}
+					className="text-xs h-8"
+				/>
+			</div>
+
+			<div className="flex flex-col gap-1.5">
+				<label className="text-xs text-muted-foreground">API Key</label>
+				<div className="flex gap-2 items-center">
+					<Input
+						type={showApiKey ? 'text' : 'password'}
+						placeholder="sk-..."
+						value={apiKey}
+						onChange={(e) => setApiKey(e.target.value)}
+						className="text-xs h-8"
+					/>
+					<Button
+						variant="outline"
+						size="icon"
+						className="h-8 w-8 shrink-0 cursor-pointer"
+						onClick={() => setShowApiKey(!showApiKey)}
+					>
+						{showApiKey ? <EyeOff className="size-3" /> : <Eye className="size-3" />}
+					</Button>
+				</div>
+			</div>
+
+			<div className="flex gap-2 mt-2">
+				<Button variant="outline" onClick={onClose} className="flex-1 h-8 text-xs cursor-pointer">
+					Cancel
+				</Button>
+				<Button
+					onClick={handleSave}
+					disabled={saving}
+					className="flex-1 h-8 text-xs cursor-pointer"
+				>
+					{saving ? <Loader2 className="size-3 animate-spin" /> : 'Save'}
+				</Button>
+			</div>
+
+			{/* Footer */}
+			<div className="mt-4 mb-4 pt-4 border-t border-border/50 flex gap-2 justify-between text-[10px] text-muted-foreground">
+				<div className="flex flex-col justify-between">
+					<a
+						href="https://github.com/alibaba/page-agent"
+						target="_blank"
+						rel="noopener noreferrer"
+						className="flex items-center gap-1 hover:text-foreground"
+					>
+						<svg role="img" viewBox="0 0 24 24" className="size-3 fill-current">
+							<path d={siGithub.path} />
+						</svg>
+						<span>Source Code</span>
+					</a>
+
+					<a
+						href="https://alibaba.github.io/page-agent/"
+						target="_blank"
+						rel="noopener noreferrer"
+						className="flex items-center gap-1 hover:text-foreground"
+					>
+						<Home className="size-3" />
+						<span>Home Page</span>
+					</a>
+
+					<a
+						href="https://github.com/alibaba/page-agent/blob/main/packages/extension/PRIVACY.md"
+						target="_blank"
+						rel="noopener noreferrer"
+						className="flex items-center gap-1 hover:text-foreground"
+					>
+						<HatGlasses className="size-3" />
+						<span>Privacy Policy</span>
+					</a>
+				</div>
+
+				<div className="flex flex-col items-end">
+					<span>
+						Extension <span className="font-mono">v{__EXT_VERSION__}</span>
+					</span>
+					<span>
+						PageAgent <span className="font-mono">v{__CORE_VERSION__}</span>
+					</span>
+				</div>
+			</div>
+
+			{/* attribute */}
+			<div className="text-[10px] text-muted-foreground bg-background fixed bottom-0 w-full flex justify-around">
+				<span className="leading-loose">
+					Built with ♥️ by{' '}
+					<a
+						href="https://github.com/gaomeng1900"
+						target="_blank"
+						rel="noopener noreferrer"
+						className="underline hover:text-foreground"
+					>
+						@Simon
+					</a>
+				</span>
+			</div>
+		</div>
+	)
+}

packages/extension/src/entrypoints/sidepanel/components/ErrorBoundary.tsx

@@ -0,0 +1,49 @@
+import { AlertTriangle, RotateCcw } from 'lucide-react'
+import { Component, type ErrorInfo, type ReactNode } from 'react'
+
+import { Button } from '@/components/ui/button'
+
+interface Props {
+	children: ReactNode
+}
+
+interface State {
+	hasError: boolean
+	error: Error | null
+}
+
+export class ErrorBoundary extends Component<Props, State> {
+	state: State = { hasError: false, error: null }
+
+	static getDerivedStateFromError(error: Error): State {
+		return { hasError: true, error }
+	}
+
+	componentDidCatch(error: Error, errorInfo: ErrorInfo) {
+		console.error('[ErrorBoundary]', error, errorInfo.componentStack)
+	}
+
+	handleReload = () => {
+		window.location.reload()
+	}
+
+	render() {
+		if (!this.state.hasError) {
+			return this.props.children
+		}
+
+		return (
+			<div className="flex flex-col items-center justify-center h-screen bg-background p-6 text-center">
+				<AlertTriangle className="size-12 text-destructive mb-4" />
+				<h2 className="text-lg font-semibold mb-2">Something went wrong</h2>
+				<p className="text-sm text-muted-foreground mb-4 max-w-xs">
+					{this.state.error?.message || 'An unexpected error occurred'}
+				</p>
+				<Button variant="outline" size="sm" onClick={this.handleReload}>
+					<RotateCcw className="size-3.5 mr-2" />
+					Reload Panel
+				</Button>
+			</div>
+		)
+	}
+}

packages/extension/src/entrypoints/sidepanel/components/HistoryDetail.tsx

@@ -0,0 +1,51 @@
+import { ArrowLeft } from 'lucide-react'
+import { useEffect, useState } from 'react'
+
+import { Button } from '@/components/ui/button'
+import { type SessionRecord, getSession } from '@/lib/db'
+
+import { EventCard } from './cards'
+
+export function HistoryDetail({ sessionId, onBack }: { sessionId: string; onBack: () => void }) {
+	const [session, setSession] = useState<SessionRecord | null>(null)
+
+	useEffect(() => {
+		getSession(sessionId).then((s) => setSession(s ?? null))
+	}, [sessionId])
+
+	if (!session) {
+		return (
+			<div className="flex items-center justify-center h-screen text-xs text-muted-foreground">
+				Loading...
+			</div>
+		)
+	}
+
+	return (
+		<div className="flex flex-col h-screen bg-background">
+			{/* Header */}
+			<header className="flex items-center gap-2 border-b px-3 py-2">
+				<Button variant="ghost" size="icon-sm" onClick={onBack} className="cursor-pointer">
+					<ArrowLeft className="size-3.5" />
+				</Button>
+				<span className="text-sm font-medium truncate">History</span>
+			</header>
+
+			{/* Task */}
+			<div className="border-b px-3 py-2 bg-muted/30">
+				<div className="text-[10px] text-muted-foreground uppercase tracking-wide">Task</div>
+				<div className="text-xs font-medium" title={session.task}>
+					{session.task}
+				</div>
+			</div>
+
+			{/* Events (read-only) */}
+			<div className="flex-1 overflow-y-auto p-3 space-y-2">
+				{session.history.map((event, index) => (
+					// eslint-disable-next-line react-x/no-array-index-key
+					<EventCard key={index} event={event} />
+				))}
+			</div>
+		</div>
+	)
+}

packages/extension/src/entrypoints/sidepanel/components/HistoryList.tsx

@@ -0,0 +1,119 @@
+import { ArrowLeft, CheckCircle, Trash2, XCircle } from 'lucide-react'
+import { useCallback, useEffect, useState } from 'react'
+
+import { Button } from '@/components/ui/button'
+import { type SessionRecord, clearSessions, deleteSession, listSessions } from '@/lib/db'
+
+function timeAgo(ts: number): string {
+	const seconds = Math.floor((Date.now() - ts) / 1000)
+	if (seconds < 60) return 'just now'
+	const minutes = Math.floor(seconds / 60)
+	if (minutes < 60) return `${minutes}m ago`
+	const hours = Math.floor(minutes / 60)
+	if (hours < 24) return `${hours}h ago`
+	const days = Math.floor(hours / 24)
+	return `${days}d ago`
+}
+
+export function HistoryList({
+	onSelect,
+	onBack,
+}: {
+	onSelect: (id: string) => void
+	onBack: () => void
+}) {
+	const [sessions, setSessions] = useState<SessionRecord[]>([])
+	const [loading, setLoading] = useState(true)
+
+	const load = useCallback(async () => {
+		setSessions(await listSessions())
+		setLoading(false)
+	}, [])
+
+	useEffect(() => {
+		// eslint-disable-next-line react-hooks/set-state-in-effect
+		load()
+	}, [load])
+
+	const handleDelete = async (e: React.MouseEvent, id: string) => {
+		e.stopPropagation()
+		await deleteSession(id)
+		setSessions((prev) => prev.filter((s) => s.id !== id))
+	}
+
+	return (
+		<div className="flex flex-col h-screen bg-background">
+			{/* Header */}
+			<header className="flex items-center gap-2 border-b px-3 py-2">
+				<Button variant="ghost" size="icon-sm" onClick={onBack} className="cursor-pointer">
+					<ArrowLeft className="size-3.5" />
+				</Button>
+				<span className="text-sm font-medium flex-1">History</span>
+				{sessions.length > 0 && (
+					<Button
+						variant="ghost"
+						size="sm"
+						onClick={async () => {
+							await clearSessions()
+							setSessions([])
+						}}
+						className="text-[10px] text-muted-foreground hover:text-destructive cursor-pointer h-6 px-2"
+					>
+						<Trash2 className="size-3 mr-1" />
+						Clear All
+					</Button>
+				)}
+			</header>
+
+			{/* List */}
+			<div className="flex-1 overflow-y-auto">
+				{loading && (
+					<div className="flex items-center justify-center h-32 text-xs text-muted-foreground">
+						Loading...
+					</div>
+				)}
+
+				{!loading && sessions.length === 0 && (
+					<div className="flex items-center justify-center h-32 text-xs text-muted-foreground">
+						No history yet
+					</div>
+				)}
+
+				{sessions.map((session) => (
+					<div
+						key={session.id}
+						role="button"
+						tabIndex={0}
+						onClick={() => onSelect(session.id)}
+						onKeyDown={(e) => e.key === 'Enter' && onSelect(session.id)}
+						className="w-full text-left px-3 py-2.5 border-b hover:bg-muted/50 transition-colors cursor-pointer flex items-start gap-2 group"
+					>
+						{/* Status icon */}
+						{session.status === 'completed' ? (
+							<CheckCircle className="size-3.5 text-green-500 shrink-0 mt-0.5" />
+						) : (
+							<XCircle className="size-3.5 text-destructive shrink-0 mt-0.5" />
+						)}
+
+						{/* Content */}
+						<div className="flex-1 min-w-0">
+							<p className="text-xs font-medium truncate">{session.task}</p>
+							<p className="text-[10px] text-muted-foreground mt-0.5">
+								{timeAgo(session.createdAt)} · {session.history.length} steps
+							</p>
+						</div>
+
+						{/* Delete */}
+						<button
+							type="button"
+							onClick={(e) => handleDelete(e, session.id)}
+							className="opacity-0 group-hover:opacity-100 transition-opacity p-1 hover:text-destructive cursor-pointer shrink-0"
+						>
+							<Trash2 className="size-3" />
+						</button>
+					</div>
+				))}
+			</div>
+		</div>
+	)
+}

packages/extension/src/entrypoints/sidepanel/components/cards.tsx

@@ -0,0 +1,386 @@
+import type {
+	AgentActivity,
+	AgentErrorEvent,
+	AgentStepEvent,
+	HistoricalEvent,
+	ObservationEvent,
+	RetryEvent,
+} from '@page-agent/core'
+import {
+	CheckCircle,
+	Eye,
+	Globe,
+	Keyboard,
+	Mouse,
+	MoveVertical,
+	RefreshCw,
+	Sparkles,
+	XCircle,
+	Zap,
+} from 'lucide-react'
+import { Fragment, useState } from 'react'
+
+import { cn } from '@/lib/utils'
+
+// Result card for done action
+function ResultCard({
+	success,
+	text,
+	children,
+}: {
+	success: boolean
+	text: string
+	children?: React.ReactNode
+}) {
+	return (
+		<div
+			className={cn(
+				'rounded-lg border p-3',
+				success ? 'border-green-500/30 bg-green-500/10' : 'border-destructive/30 bg-destructive/10'
+			)}
+		>
+			<div className="flex items-center gap-2 mb-2">
+				{success ? (
+					<CheckCircle className="size-3.5 text-green-500" />
+				) : (
+					<XCircle className="size-3.5 text-destructive" />
+				)}
+				<span
+					className={cn(
+						'text-xs font-medium',
+						success ? 'text-green-600 dark:text-green-400' : 'text-destructive'
+					)}
+				>
+					Result: {success ? 'Success' : 'Failed'}
+				</span>
+			</div>
+			<p className="text-xs text-[11px] text-muted-foreground pl-5 whitespace-pre-wrap">{text}</p>
+			{children}
+		</div>
+	)
+}
+
+// Single reflection item with truncation
+function ReflectionItem({ icon, value }: { icon: string; value: string }) {
+	const [expanded, setExpanded] = useState(false)
+
+	return (
+		<Fragment>
+			<span className="text-xs flex justify-center">{icon}</span>
+			<span
+				className={cn(
+					'text-[11px] text-muted-foreground cursor-pointer hover:text-muted-foreground/70',
+					!expanded && 'line-clamp-1'
+				)}
+				onClick={() => setExpanded(!expanded)}
+			>
+				{value}
+			</span>
+		</Fragment>
+	)
+}
+
+// Reflection section in step card
+function ReflectionSection({
+	reflection,
+}: {
+	reflection: {
+		evaluation_previous_goal?: string
+		memory?: string
+		next_goal?: string
+	}
+}) {
+	const items = [
+		{ icon: '☑️', label: 'eval', value: reflection.evaluation_previous_goal },
+		{ icon: '🧠', label: 'memory', value: reflection.memory },
+		{ icon: '🎯', label: 'goal', value: reflection.next_goal },
+	].filter((item) => item.value)
+
+	if (items.length === 0) return null
+
+	return (
+		<div className="mb-2">
+			{/* <div className="text-[11px] font-semibold text-foreground uppercase tracking-wide mb-2">
+				Reflection
+			</div> */}
+			<div className="grid grid-cols-[14px_1fr] gap-x-2 gap-y-2">
+				{items.map((item) => (
+					<ReflectionItem key={item.label} icon={item.icon} value={item.value!} />
+				))}
+			</div>
+		</div>
+	)
+}
+
+// Get icon for action type
+function ActionIcon({ name, className }: { name: string; className?: string }) {
+	const icons: Record<string, React.ReactNode> = {
+		click_element_by_index: <Mouse className={className} />,
+		input: <Keyboard className={className} />,
+		scroll: <MoveVertical className={className} />,
+		go_to_url: <Globe className={className} />,
+	}
+	return icons[name] || <Zap className={className} />
+}
+
+// Copy button with "Copied!" feedback
+function CopyButton({ text, label }: { text: string; label: string }) {
+	const [copied, setCopied] = useState(false)
+
+	return (
+		<button
+			type="button"
+			onClick={() => {
+				navigator.clipboard.writeText(text)
+				setCopied(true)
+				setTimeout(() => setCopied(false), 1500)
+			}}
+			className="text-[9px] text-muted-foreground hover:text-foreground transition-colors border px-1 rounded shrink-0 cursor-pointer backdrop-blur-xs"
+		>
+			{copied ? 'Copied!' : label}
+		</button>
+	)
+}
+
+// Extract message content by role from raw request
+function extractPrompt(rawRequest: unknown, role: 'system' | 'user'): string | null {
+	const messages = (rawRequest as { messages?: { role: string; content?: unknown }[] })?.messages
+	if (!messages) return null
+	const msg =
+		role === 'system'
+			? messages.find((m) => m.role === role)
+			: messages.findLast((m) => m.role === role)
+	if (!msg?.content) return null
+	return typeof msg.content === 'string' ? msg.content : JSON.stringify(msg.content, null, 2)
+}
+
+// Raw request/response section (collapsible tabs, for debugging)
+function RawSection({ rawRequest, rawResponse }: { rawRequest?: unknown; rawResponse?: unknown }) {
+	const [activeTab, setActiveTab] = useState<'request' | 'response' | null>(null)
+
+	if (!rawRequest && !rawResponse) return null
+
+	const handleTabClick = (tab: 'request' | 'response') => {
+		setActiveTab(activeTab === tab ? null : tab)
+	}
+
+	const content =
+		activeTab === 'request' ? rawRequest : activeTab === 'response' ? rawResponse : null
+
+	const systemPrompt = activeTab === 'request' ? extractPrompt(rawRequest, 'system') : null
+	const userPrompt = activeTab === 'request' ? extractPrompt(rawRequest, 'user') : null
+
+	return (
+		<div className="mt-2 border-t border-dashed pt-2">
+			<div className="flex items-center gap-3 -my-1">
+				{rawRequest != null && (
+					<button
+						type="button"
+						onClick={() => handleTabClick('request')}
+						className={cn(
+							'text-[10px] mt-0.5 transition-colors border-b cursor-pointer',
+							activeTab === 'request'
+								? 'text-foreground border-foreground'
+								: 'text-muted-foreground border-transparent hover:text-foreground'
+						)}
+					>
+						Raw Request
+					</button>
+				)}
+				{rawResponse != null && (
+					<button
+						type="button"
+						onClick={() => handleTabClick('response')}
+						className={cn(
+							'text-[10px] mt-0.5 transition-colors border-b cursor-pointer',
+							activeTab === 'response'
+								? 'text-foreground border-foreground'
+								: 'text-muted-foreground border-transparent hover:text-foreground'
+						)}
+					>
+						Raw Response
+					</button>
+				)}
+			</div>
+			{content != null && (
+				<div className="relative mt-1.5">
+					<div className="absolute top-1 right-1 flex gap-1">
+						{systemPrompt && <CopyButton text={systemPrompt} label="Copy System" />}
+						{userPrompt && <CopyButton text={userPrompt} label="Copy User" />}
+						<CopyButton text={JSON.stringify(content, null, 4)} label="Copy" />
+					</div>
+					<pre className="p-2 pt-5 text-[10px] text-foreground/70 bg-muted rounded overflow-x-auto max-h-60 overflow-y-auto">
+						{JSON.stringify(content, null, 4)}
+					</pre>
+				</div>
+			)}
+		</div>
+	)
+}
+
+function StepCard({ event }: { event: AgentStepEvent }) {
+	return (
+		<div className="rounded-lg border-l-2 border-l-blue-500/50 border bg-muted/40 p-2.5">
+			<div className="text-[11px] font-semibold text-foreground tracking-wide mb-2">
+				Step #{event.stepIndex! + 1}
+			</div>
+
+			{/* Reflection */}
+			{event.reflection && <ReflectionSection reflection={event.reflection} />}
+
+			{/* Action */}
+			{event.action && (
+				<div>
+					<div className="text-[11px] font-semibold text-foreground tracking-wide mb-1">
+						Actions
+					</div>
+					<div className="flex items-start gap-2">
+						<ActionIcon
+							name={event.action.name}
+							className="size-3.5 text-blue-500 shrink-0 mt-0.5"
+						/>
+						<div className="flex-1 min-w-0">
+							<p className="text-xs text-foreground/80 mb-0.5 wrap-anywhere break-all line-clamp-1 hover:line-clamp-none">
+								<span className="font-medium text-foreground/70">{event.action.name}</span>
+								{event.action.name !== 'done' && (
+									<span className="text-muted-foreground/70 ml-1.5">
+										{JSON.stringify(event.action.input)}
+									</span>
+								)}
+							</p>
+							<p className="text-[11px] text-muted-foreground/70 grid grid-cols-[auto_1fr] gap-1.5">
+								<span className="">└</span>
+								<span className="wrap-anywhere break-all line-clamp-1 hover:line-clamp-3">
+									{event.action.output}
+								</span>
+							</p>
+						</div>
+					</div>
+				</div>
+			)}
+
+			{/* Raw Response */}
+			<RawSection rawRequest={event.rawRequest} rawResponse={event.rawResponse} />
+		</div>
+	)
+}
+
+function ObservationCard({ event }: { event: ObservationEvent }) {
+	return (
+		<div className="rounded-lg border-l-2 border-l-green-500/50 border bg-muted/40 p-2.5">
+			{/* <div className="text-[11px] font-semibold text-foreground uppercase tracking-wide mb-2">
+				Observation
+			</div> */}
+			<div className="flex items-start gap-2">
+				<Eye className="size-3.5 text-green-500 shrink-0 mt-0.5" />
+				<span className="text-[11px] text-muted-foreground">{event.content}</span>
+			</div>
+		</div>
+	)
+}
+
+function RetryCard({ event }: { event: RetryEvent }) {
+	return (
+		<div className="rounded-lg border border-amber-500/30 bg-amber-500/10 p-2.5">
+			<div className="flex items-start gap-1.5">
+				<RefreshCw className="size-3 text-amber-500 shrink-0 mt-0.5" />
+				<span className="text-xs text-amber-600 dark:text-amber-400">
+					{event.message} ({event.attempt}/{event.maxAttempts})
+				</span>
+			</div>
+		</div>
+	)
+}
+
+function ErrorCard({ event }: { event: AgentErrorEvent }) {
+	return (
+		<div className="rounded-lg border border-destructive/30 bg-destructive/10 p-2.5">
+			<div className="flex items-start gap-1.5">
+				<XCircle className="size-3 text-destructive shrink-0 mt-0.5" />
+				<span className="text-xs text-destructive">{event.message}</span>
+			</div>
+			<RawSection rawResponse={event.rawResponse} />
+		</div>
+	)
+}
+
+// History event card component
+export function EventCard({ event }: { event: HistoricalEvent }) {
+	// Done action - show as result card
+	if (event.type === 'step' && event.action?.name === 'done') {
+		const input = event.action.input as { text?: string; success?: boolean }
+		return (
+			<>
+				<StepCard event={event as AgentStepEvent} />
+				<ResultCard
+					success={input?.success ?? true}
+					text={input?.text || event.action.output || ''}
+				/>
+			</>
+		)
+	}
+
+	if (event.type === 'step') {
+		return <StepCard event={event as AgentStepEvent} />
+	}
+
+	if (event.type === 'observation') {
+		return <ObservationCard event={event as ObservationEvent} />
+	}
+
+	if (event.type === 'retry') {
+		return <RetryCard event={event as RetryEvent} />
+	}
+
+	if (event.type === 'error') {
+		return <ErrorCard event={event as AgentErrorEvent} />
+	}
+
+	return null
+}
+
+// Activity card with animation
+export function ActivityCard({ activity }: { activity: AgentActivity }) {
+	const getActivityInfo = () => {
+		switch (activity.type) {
+			case 'thinking':
+				return { text: 'Thinking...', color: 'text-blue-500' }
+			case 'executing':
+				return { text: `Executing ${activity.tool}...`, color: 'text-amber-500' }
+			case 'executed':
+				return { text: `Done: ${activity.tool}`, color: 'text-green-500' }
+			case 'retrying':
+				return {
+					text: `Retrying (${activity.attempt}/${activity.maxAttempts})...`,
+					color: 'text-amber-500',
+				}
+			case 'error':
+				return { text: activity.message, color: 'text-destructive' }
+		}
+	}
+
+	const info = getActivityInfo()
+
+	return (
+		<div className="flex items-center gap-2 rounded-lg border bg-muted/40 p-2.5 animate-pulse">
+			<div className="relative">
+				<Sparkles className={cn('size-3.5', info.color)} />
+				<span
+					className={cn(
+						'absolute -top-0.5 -right-0.5 size-1.5 rounded-full animate-ping',
+						activity.type === 'thinking'
+							? 'bg-blue-500'
+							: activity.type === 'executing'
+								? 'bg-amber-500'
+								: activity.type === 'retrying'
+									? 'bg-amber-500'
+									: activity.type === 'error'
+										? 'bg-destructive'
+										: 'bg-green-500'
+					)}
+				/>
+			</div>
+			<span className={cn('text-xs', info.color)}>{info.text}</span>
+		</div>
+	)
+}

packages/extension/src/entrypoints/sidepanel/components/misc.tsx

@@ -0,0 +1,46 @@
+import type { AgentStatus } from '@page-agent/core'
+
+import { cn } from '@/lib/utils'
+
+// Status dot indicator
+export function StatusDot({ status }: { status: AgentStatus }) {
+	const colorClass = {
+		idle: 'bg-muted-foreground',
+		running: 'bg-blue-500',
+		completed: 'bg-green-500',
+		error: 'bg-destructive',
+	}[status]
+
+	const label = {
+		idle: 'Ready',
+		running: 'Running',
+		completed: 'Done',
+		error: 'Error',
+	}[status]
+
+	return (
+		<div className="flex items-center gap-1.5">
+			<span
+				className={cn('size-2 rounded-full', colorClass, status === 'running' && 'animate-pulse')}
+			/>
+			<span className="text-xs text-muted-foreground">{label}</span>
+		</div>
+	)
+}
+
+export function Logo({ className }: { className?: string }) {
+	return <img src="/assets/page-agent-256.webp" alt="Page Agent" className={cn('', className)} />
+}
+
+// Empty state with logo
+export function EmptyState() {
+	return (
+		<div className="flex flex-col items-center justify-center h-full gap-3 text-center px-6">
+			<Logo className="size-20 opacity-80" />
+			<div>
+				<h2 className="text-sm font-medium text-foreground">Page Agent Ext</h2>
+				<p className="text-xs text-muted-foreground mt-1">Enter a task to automate this page</p>
+			</div>
+		</div>
+	)
+}

packages/extension/src/entrypoints/sidepanel/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html>
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<link rel="icon" type="image/png" href="/assets/page-agent-64.png" />
+		<title>Page Agent</title>
+	</head>
+	<body>
+		<div id="root"></div>
+		<script type="module" src="./main.tsx"></script>
+	</body>
+</html>

packages/extension/src/entrypoints/sidepanel/main.tsx

@@ -0,0 +1,25 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+
+import App from './App'
+import { ErrorBoundary } from './components/ErrorBoundary'
+
+import '@/assets/index.css'
+
+// Sync dark mode with system preference
+const syncDarkMode = () => {
+	document.documentElement.classList.toggle(
+		'dark',
+		matchMedia('(prefers-color-scheme: dark)').matches
+	)
+}
+syncDarkMode()
+matchMedia('(prefers-color-scheme: dark)').addEventListener('change', syncDarkMode)
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+	<React.StrictMode>
+		<ErrorBoundary>
+			<App />
+		</ErrorBoundary>
+	</React.StrictMode>
+)

packages/extension/src/lib/db.ts

@@ -0,0 +1,70 @@
+import type { HistoricalEvent } from '@page-agent/core'
+import { type DBSchema, type IDBPDatabase, openDB } from 'idb'
+
+const DB_NAME = 'page-agent-ext'
+const DB_VERSION = 1
+
+export interface SessionRecord {
+	id: string
+	task: string
+	history: HistoricalEvent[]
+	status: 'completed' | 'error'
+	createdAt: number
+}
+
+interface PageAgentDB extends DBSchema {
+	sessions: {
+		key: string
+		value: SessionRecord
+		indexes: { 'by-created': number }
+	}
+}
+
+let dbPromise: Promise<IDBPDatabase<PageAgentDB>> | null = null
+
+function getDB() {
+	if (!dbPromise) {
+		dbPromise = openDB<PageAgentDB>(DB_NAME, DB_VERSION, {
+			upgrade(db) {
+				const store = db.createObjectStore('sessions', { keyPath: 'id' })
+				store.createIndex('by-created', 'createdAt')
+			},
+		})
+	}
+	return dbPromise
+}
+
+export async function saveSession(
+	session: Omit<SessionRecord, 'id' | 'createdAt'>
+): Promise<SessionRecord> {
+	const db = await getDB()
+	const record: SessionRecord = {
+		...session,
+		id: crypto.randomUUID(),
+		createdAt: Date.now(),
+	}
+	await db.put('sessions', record)
+	return record
+}
+
+/** List sessions, newest first */
+export async function listSessions(): Promise<SessionRecord[]> {
+	const db = await getDB()
+	const all = await db.getAllFromIndex('sessions', 'by-created')
+	return all.reverse()
+}
+
+export async function getSession(id: string): Promise<SessionRecord | undefined> {
+	const db = await getDB()
+	return db.get('sessions', id)
+}
+
+export async function deleteSession(id: string): Promise<void> {
+	const db = await getDB()
+	await db.delete('sessions', id)
+}
+
+export async function clearSessions(): Promise<void> {
+	const db = await getDB()
+	await db.clear('sessions')
+}

packages/extension/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { type ClassValue, clsx } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+	return twMerge(clsx(inputs))
+}

packages/extension/src/types/assets.d.ts

@@ -0,0 +1,25 @@
+// Asset type declarations
+declare module '*.webp' {
+	const src: string
+	export default src
+}
+
+declare module '*.png' {
+	const src: string
+	export default src
+}
+
+declare module '*.jpg' {
+	const src: string
+	export default src
+}
+
+declare module '*.jpeg' {
+	const src: string
+	export default src
+}
+
+declare module '*.svg' {
+	const src: string
+	export default src
+}

packages/extension/src/types/globals.d.ts

@@ -0,0 +1,2 @@
+declare const __EXT_VERSION__: string
+declare const __CORE_VERSION__: string

packages/extension/src/types/markdown.d.ts

@@ -0,0 +1,4 @@
+declare module '*.md?raw' {
+	const content: string
+	export default content
+}

packages/extension/tsconfig.json

@@ -0,0 +1,28 @@
+{
+    "extends": "./.wxt/tsconfig.json",
+    "compilerOptions": {
+        "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo",
+        "useDefineForClassFields": true,
+        "noEmit": false,
+        "allowImportingTsExtensions": false,
+        "strictNullChecks": true,
+        "jsx": "react-jsx",
+        "baseUrl": ".",
+        "paths": {
+            // Self root
+            "@/*": ["src/*"],
+
+            "@page-agent/llms": ["../llms/src/index.ts"],
+            "@page-agent/page-controller": ["../page-controller/src/PageController.ts"],
+            "@page-agent/core": ["../core/src/PageAgentCore.ts"],
+            "@page-agent/ui": ["../ui/src/index.ts"]
+        }
+    },
+    "references": [
+        //
+        { "path": "../llms" },
+        { "path": "../page-controller" },
+        { "path": "../core" },
+        { "path": "../ui" }
+    ]
+}

packages/extension/wxt.config.js

@@ -0,0 +1,63 @@
+import tailwindcss from '@tailwindcss/vite'
+import { mkdirSync, readFileSync } from 'node:fs'
+import { defineConfig } from 'wxt'
+
+const chromeProfile = '.wxt/chrome-data'
+mkdirSync(chromeProfile, { recursive: true })
+
+const pkg = JSON.parse(readFileSync('./package.json', 'utf-8'))
+
+// See https://wxt.dev/api/config.html
+export default defineConfig({
+	srcDir: 'src',
+	modules: ['@wxt-dev/module-react'],
+	webExt: {
+		chromiumProfile: chromeProfile,
+		keepProfileChanges: true,
+		chromiumArgs: ['--hide-crash-restore-bubble'],
+	},
+	vite: () => ({
+		plugins: [tailwindcss()],
+		define: {
+			__EXT_VERSION__: JSON.stringify(pkg.version),
+			__CORE_VERSION__: JSON.stringify(pkg.dependencies['@page-agent/core']),
+		},
+		optimizeDeps: {
+			force: true,
+		},
+		build: {
+			minify: false,
+			chunkSizeWarningLimit: 2000,
+			cssCodeSplit: true,
+			rollupOptions: {
+				onwarn: function (message, handler) {
+					if (message.code === 'EVAL') return
+					handler(message)
+				},
+			},
+		},
+	}),
+	manifest: {
+		name: 'Page Agent Ext',
+		description:
+			'AI-powered browser automation assistant. Control web pages with natural language.',
+		homepage_url: 'https://alibaba.github.io/page-agent/',
+		permissions: ['tabs', 'tabGroups', 'sidePanel', 'storage'],
+		host_permissions: ['<all_urls>'],
+		icons: {
+			64: 'assets/page-agent-64.png',
+		},
+		action: {
+			default_title: 'Open Page Agent',
+		},
+		web_accessible_resources: [
+			{
+				resources: ['main-world.js'],
+				matches: ['*://*/*'],
+			},
+		],
+		side_panel: {
+			default_path: 'sidepanel/index.html',
+		},
+	},
+})

packages/llms/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@page-agent/llms",
-    "version": "1.0.0",
+    "version": "1.2.0",
     "type": "module",
     "main": "./dist/lib/page-agent-llms.js",
     "module": "./dist/lib/page-agent-llms.js",

packages/llms/src/OpenAIClient.ts

@@ -39,6 +39,8 @@ export class OpenAIClient implements LLMClient {
 				: 'required',
 		}
 
+		modelPatch(requestBody)
+
 		// 2. Call API
 		let response: Response
 		try {
@@ -48,7 +50,7 @@ export class OpenAIClient implements LLMClient {
 					'Content-Type': 'application/json',
 					Authorization: `Bearer ${this.config.apiKey}`,
 				},
-				body: JSON.stringify(modelPatch(requestBody)),
+				body: JSON.stringify(requestBody),
 				signal: abortSignal,
 			})
 		} catch (error: unknown) {
@@ -216,6 +218,7 @@ export class OpenAIClient implements LLMClient {
 				reasoningTokens: data.usage?.completion_tokens_details?.reasoning_tokens,
 			},
 			rawResponse: data,
+			rawRequest: requestBody,
 		}
 	}
 }

packages/llms/src/index.ts

@@ -49,6 +49,9 @@ export class LLM extends EventTarget {
 	): Promise<InvokeResult> {
 		return await withRetry(
 			async () => {
+				// in case user aborted before invoking
+				if (abortSignal.aborted) throw new Error('AbortError')
+
 				const result = await this.client.invoke(messages, tools, abortSignal, options)
 
 				return result
@@ -88,12 +91,12 @@ async function withRetry<T>(
 		try {
 			return await fn()
 		} catch (error: unknown) {
+			// do not retry if aborted by user
+			if ((error as any)?.rawError?.name === 'AbortError') throw error
+
 			console.error(error)
 			settings.onError(error as Error)
 
-			// do not retry if aborted by user
-			if ((error as { name?: string })?.name === 'AbortError') throw error
-
 			// do not retry if error is not retryable (InvokeError)
 			if (error instanceof InvokeError && !error.retryable) throw error
 

packages/llms/src/types.ts

@@ -81,6 +81,7 @@ export interface InvokeResult<TResult = unknown> {
 		reasoningTokens?: number // OpenAI o1 series reasoning tokens
 	}
 	rawResponse?: unknown // Raw response for debugging
+	rawRequest?: unknown // Raw request for debugging
 }
 
 /**

packages/llms/src/utils.ts

@@ -2,7 +2,7 @@
  * Utility functions for LLM integration
  */
 import chalk from 'chalk'
-import { z } from 'zod'
+import * as z from 'zod'
 
 import type { Tool } from './types'
 
@@ -27,6 +27,7 @@ export function zodToOpenAITool(name: string, tool: Tool) {
 
 /**
  * Patch model specific parameters
+ * @note in-place modification
  */
 export function modelPatch(body: Record<string, any>) {
 	const model: string = body.model || ''
@@ -73,6 +74,10 @@ export function modelPatch(body: Record<string, any>) {
 		} else if (modelName.startsWith('gpt-51')) {
 			debug('Applying GPT-51 patch: disable reasoning')
 			body.reasoning_effort = 'none'
+		} else if (modelName.startsWith('gpt-5-mini')) {
+			debug('Applying GPT-5-mini patch: set reasoning effort to low, temperature to 1')
+			body.reasoning_effort = 'low'
+			body.temperature = 1
 		} else if (modelName.startsWith('gpt-5')) {
 			debug('Applying GPT-5 patch: set reasoning effort to low')
 			body.reasoning_effort = 'low'

packages/page-agent/package.json

@@ -1,7 +1,7 @@
 {
     "name": "page-agent",
     "private": false,
-    "version": "1.0.0",
+    "version": "1.2.0",
     "type": "module",
     "main": "./dist/esm/page-agent.js",
     "module": "./dist/esm/page-agent.js",
@@ -44,11 +44,11 @@
         "postpublish": "node -e \"['README.md','LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
     },
     "dependencies": {
+        "@page-agent/core": "1.2.0",
+        "@page-agent/llms": "1.2.0",
+        "@page-agent/page-controller": "1.2.0",
+        "@page-agent/ui": "1.2.0",
         "chalk": "^5.6.2",
-        "zod": "^4.3.5",
+        "zod": "^4.3.5"
-        "@page-agent/llms": "1.0.0",
-        "@page-agent/page-controller": "1.0.0",
-        "@page-agent/core": "1.0.0",
-        "@page-agent/ui": "1.0.0"
     }
 }

packages/page-agent/vite.iife.config.js

@@ -3,6 +3,7 @@ import { config as dotenvConfig } from 'dotenv'
 import { dirname, resolve } from 'path'
 import { fileURLToPath } from 'url'
 import { defineConfig } from 'vite'
+// import { analyzer } from 'vite-bundle-analyzer'
 import cssInjectedByJsPlugin from 'vite-plugin-css-injected-by-js'
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
@@ -14,8 +15,11 @@ dotenvConfig({ path: resolve(__dirname, '../../.env') })
 // - alias all local packages so that they can be build in
 // - no external
 // - no d.ts. dts does not work with monorepo aliasing
-export default defineConfig(({ mode }) => ({
+export default defineConfig(() => ({
-	plugins: [cssInjectedByJsPlugin({ relativeCSSInjection: true })],
+	plugins: [
+		cssInjectedByJsPlugin({ relativeCSSInjection: true }),
+		// analyzer()
+	],
 	publicDir: false,
 	esbuild: {
 		keepNames: true,

packages/page-controller/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@page-agent/page-controller",
-    "version": "1.0.0",
+    "version": "1.2.0",
     "type": "module",
     "main": "./dist/lib/page-controller.js",
     "module": "./dist/lib/page-controller.js",

packages/page-controller/src/PageController.ts

@@ -94,17 +94,18 @@ export class PageController extends EventTarget {
 
 		patchReact(this)
 
-		if (config.enableMask) {
+		if (config.enableMask) this.initMask()
-			this.maskReady = this.initMask()
-		}
 	}
 
 	/**
 	 * Initialize mask asynchronously (dynamic import to avoid CSS loading in Node)
 	 */
-	private async initMask(): Promise<void> {
+	initMask() {
-		const { SimulatorMask } = await import('./mask/SimulatorMask')
+		if (this.maskReady !== null) return
-		this.mask = new SimulatorMask()
+		this.maskReady = (async () => {
+			const { SimulatorMask } = await import('./mask/SimulatorMask')
+			this.mask = new SimulatorMask()
+		})()
 	}
 	// ======= State Queries =======
 
@@ -137,6 +138,8 @@ export class PageController extends EventTarget {
 		const content = this.simplifiedHTML
 
 		// Build header: page info + scroll position hint
+		const titleLine = `Current Page: [${title}](${url})`
+
 		const pageInfoLine = `Page info: ${pi.viewport_width}x${pi.viewport_height}px viewport, ${pi.page_width}x${pi.page_height}px total page size, ${pi.pages_above.toFixed(1)} pages above, ${pi.pages_below.toFixed(1)} pages below, ${pi.total_pages.toFixed(1)} total pages, at ${(pi.current_page_position * 100).toFixed(0)}% of page`
 
 		const elementsLabel =
@@ -150,7 +153,7 @@ export class PageController extends EventTarget {
 				? `... ${pi.pixels_above} pixels above (${pi.pages_above.toFixed(1)} pages) - scroll to see more ...`
 				: '[Start of page]'
 
-		const header = `${pageInfoLine}\n\n${elementsLabel}\n\n${scrollHintAbove}`
+		const header = `${titleLine}\n${pageInfoLine}\n\n${elementsLabel}\n\n${scrollHintAbove}`
 
 		// Build footer: scroll position hint
 		const hasContentBelow = pi.pixels_below > 4
@@ -191,7 +194,7 @@ export class PageController extends EventTarget {
 			interactiveBlacklist: blacklist,
 		})
 
-		this.simplifiedHTML = dom.flatTreeToString(this.flatTree, this.config.include_attributes)
+		this.simplifiedHTML = dom.flatTreeToString(this.flatTree, this.config.includeAttributes)
 
 		this.selectorMap.clear()
 		this.selectorMap = dom.getSelectorMap(this.flatTree)
@@ -227,7 +230,7 @@ export class PageController extends EventTarget {
 	 */
 	private assertIndexed(): void {
 		if (!this.isIndexed) {
-			throw new Error('DOM tree not indexed. Can not perform actions on elements.')
+			throw new Error('DOM tree not indexed yet. Can not perform actions on elements.')
 		}
 	}
 
@@ -245,7 +248,7 @@ export class PageController extends EventTarget {
 			if (element instanceof HTMLAnchorElement && element.target === '_blank') {
 				return {
 					success: true,
-					message: `✅ Clicked element (${elemText ?? index}). ⚠️ Link opens in a new tab. You are not capable of reading new tabs.`,
+					message: `✅ Clicked element (${elemText ?? index}). ⚠️ Link opened in a new tab.`,
 				}
 			}
 
@@ -392,7 +395,7 @@ export class PageController extends EventTarget {
 
 	/**
 	 * Show the visual mask overlay.
-	 * Only works if enableMask was set to true in config.
+	 * Only works after mask is setup.
 	 */
 	async showMask(): Promise<void> {
 		await this.maskReady
@@ -401,7 +404,7 @@ export class PageController extends EventTarget {
 
 	/**
 	 * Hide the visual mask overlay.
-	 * Only works if enableMask was set to true in config.
+	 * Only works after mask is setup.
 	 */
 	async hideMask(): Promise<void> {
 		await this.maskReady

packages/page-controller/src/dom/index.ts

@@ -10,7 +10,7 @@ import {
 export interface DomConfig {
 	interactiveBlacklist?: (Element | (() => Element))[]
 	interactiveWhitelist?: (Element | (() => Element))[]
-	include_attributes?: string[]
+	includeAttributes?: string[]
 	highlightOpacity?: number
 	highlightLabelOpacity?: number
 }
@@ -117,7 +117,7 @@ interface TreeNode {
  *
  * @todo 数据脱敏过滤器
  */
-export function flatTreeToString(flatTree: FlatDomTree, include_attributes?: string[]): string {
+export function flatTreeToString(flatTree: FlatDomTree, includeAttributes?: string[]): string {
 	const DEFAULT_INCLUDE_ATTRIBUTES = [
 		'title',
 		'type',
@@ -146,7 +146,7 @@ export function flatTreeToString(flatTree: FlatDomTree, include_attributes?: str
 		'aria-owns',
 	]
 
-	const includeAttrs = [...(include_attributes || []), ...DEFAULT_INCLUDE_ATTRIBUTES]
+	const includeAttrs = [...(includeAttributes || []), ...DEFAULT_INCLUDE_ATTRIBUTES]
 
 	// Helper function to cap text length
 	const capTextLength = (text: string, maxLength: number): string => {

packages/page-controller/src/mask/SimulatorMask.module.css

@@ -2,8 +2,7 @@
 	position: fixed;
 	inset: 0;
 	z-index: 2147483641; /* 确保在所有元素之上，除了 panel */
-	/* pointer-events: none; */
+	cursor: wait;
-	cursor: not-allowed;
 	overflow: hidden;
 
 	display: none;

packages/page-controller/src/mask/SimulatorMask.ts

@@ -6,6 +6,7 @@ import styles from './SimulatorMask.module.css'
 import cursorStyles from './cursor.module.css'
 
 export class SimulatorMask {
+	shown: boolean = false
 	wrapper = document.createElement('div')
 	motion = new Motion({
 		mode: isPageDark() ? 'dark' : 'light',
@@ -140,6 +141,9 @@ export class SimulatorMask {
 	}
 
 	show() {
+		if (this.shown) return
+
+		this.shown = true
 		this.motion.start()
 		this.motion.fadeIn()
 
@@ -155,6 +159,9 @@ export class SimulatorMask {
 	}
 
 	hide() {
+		if (!this.shown) return
+
+		this.shown = false
 		this.motion.fadeOut()
 		this.motion.pause()
 

packages/page-controller/src/mask/cursor-border.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100" fill="none">
+  <g><path d="M 15 42 L 15 36.99 Q 15 31.99 23.7 31.99 L 28.05 31.99 Q 32.41 31.99 32.41 21.99 L 32.41 17 Q 32.41 12 41.09 16.95 L 76.31 37.05 Q 85 42 76.31 46.95 L 41.09 67.05 Q 32.41 72 32.41 62.01 L 32.41 57.01 Q 32.41 52.01 23.7 52.01 L 19.35 52.01 Q 15 52.01 15 47.01 Z" fill="none" stroke="#000000" stroke-width="6" stroke-miterlimit="10" style="stroke: light-dark(rgb(0, 0, 0), rgb(255, 255, 255));"/></g>
+</svg>

packages/page-controller/src/mask/cursor-fill.svg

@@ -0,0 +1,5 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100">
+  <defs>
+  </defs>
+  <g xmlns="http://www.w3.org/2000/svg" style="filter: drop-shadow(light-dark(rgba(0, 0, 0, 0.4), rgba(237, 237, 237, 0.4)) 3px 4px 4px);"><path d="M 15 42 L 15 36.99 Q 15 31.99 23.7 31.99 L 28.05 31.99 Q 32.41 31.99 32.41 21.99 L 32.41 17 Q 32.41 12 41.09 16.95 L 76.31 37.05 Q 85 42 76.31 46.95 L 41.09 67.05 Q 32.41 72 32.41 62.01 L 32.41 57.01 Q 32.41 52.01 23.7 52.01 L 19.35 52.01 Q 15 52.01 15 47.01 Z" fill="#ffffff" stroke="none" style="fill: #ffffff;"/></g>
+</svg>

packages/page-controller/src/mask/cursor.module.css

@@ -5,80 +5,59 @@
 	height: var(--cursor-size, 75px);
 	pointer-events: none;
 	z-index: 10000;
-	transform: translate(-30%, -30%);
-
-	animation: cursor-enter 300ms ease-out forwards;
 }
 
 .cursorBorder {
 	position: absolute;
-	inset: 0;
+	width: 100%;
+	height: 100%;
 	background: linear-gradient(45deg, rgb(57, 182, 255), rgb(189, 69, 251));
-	mask-image: url(https://img.alicdn.com/imgextra/i1/O1CN01YHLVYR1LvqWIyo5kH_!!6000000001362-2-tps-202-202.png);
+	mask-image: url(./cursor-border.svg);
 	mask-size: 100% 100%;
 	mask-repeat: no-repeat;
-	animation: cursor-breathe 2s ease-in-out infinite;
+
+	transform-origin: center;
+	transform: rotate(-135deg) scale(1.2);
+	margin-left: -10px;
+	margin-top: -18px;
 }
 
 .cursorFilling {
 	position: absolute;
-	inset: 0;
+	width: 100%;
-	background: url(https://img.alicdn.com/imgextra/i3/O1CN01JZOqOS1Tu1sIKbPLW_!!6000000002441-2-tps-202-202.png);
+	height: 100%;
+	background: url(./cursor-fill.svg);
 	background-size: 100% 100%;
 	background-repeat: no-repeat;
+
+	transform-origin: center;
+	transform: rotate(-135deg) scale(1.2);
+	margin-left: -10px;
+	margin-top: -18px;
 }
 
 .cursorRipple {
 	position: absolute;
-	inset: 0;
+	width: 100%;
+	height: 100%;
 	pointer-events: none;
+	margin-left: -50%;
+	margin-top: -50%;
+
+	&::after {
+		content: '';
+		opacity: 0;
+		position: absolute;
+		inset: 0;
+		border: 4px solid rgba(57, 182, 255, 1);
+		border-radius: 50%;
+	}
 }
 
 .cursor.clicking .cursorRipple::after {
-	content: '';
-	position: absolute;
-	width: 100%;
-	height: 100%;
-	left: -30%;
-	top: -30%;
-	border: 4px solid rgba(57, 182, 255, 1);
-	border-radius: 50%;
 	animation: cursor-ripple 300ms ease-out forwards;
 }
 
-/* 光标动画关键帧 */
-@keyframes cursor-breathe {
-	0%,
-	100% {
-		transform: scale(1);
-		opacity: 0.9;
-	}
-	50% {
-		transform: scale(1.05);
-		opacity: 1;
-	}
-}
-
-@keyframes cursor-rotate {
-	0% {
-		transform: rotate(0deg);
-	}
-	100% {
-		transform: rotate(360deg);
-	}
-}
-
-@keyframes cursor-enter {
-	0% {
-		transform: translate(-30%, -30%) scale(0.5);
-		opacity: 0;
-	}
-	100% {
-		transform: translate(-30%, -30%) scale(1);
-		opacity: 1;
-	}
-}
-
 @keyframes cursor-ripple {
 	0% {
 		transform: scale(0);

packages/ui/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@page-agent/ui",
-    "version": "1.0.0",
+    "version": "1.2.0",
     "type": "module",
     "main": "./dist/lib/page-agent-ui.js",
     "module": "./dist/lib/page-agent-ui.js",

packages/ui/src/index.ts

@@ -1,3 +1,2 @@
 export { Panel, type PanelConfig } from './panel/Panel'
-export type { AgentActivity, PanelAgentAdapter } from './panel/types'
 export { I18n, type SupportedLanguage, type TranslationKey } from './i18n'

packages/website/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@page-agent/website",
     "private": true,
-    "version": "1.0.0",
+    "version": "1.2.0",
     "type": "module",
     "scripts": {
         "dev": "vite --host 0.0.0.0",
@@ -10,33 +10,26 @@
         "typecheck": "tsc --noEmit"
     },
     "devDependencies": {
-        "@tailwindcss/vite": "^4.1.18",
-        "@types/react": "^19.2.8",
-        "@types/react-dom": "^19.2.1",
-        "@vitejs/plugin-react-swc": "^4.1.0",
-        "i18next": "^25.7.4",
-        "i18next-browser-languagedetector": "^8.2.0",
-        "react": "^19.2.3",
-        "react-dom": "^19.2.3",
-        "react-i18next": "^16.5.3",
-        "tailwindcss": "^4.1.14",
-        "tw-animate-css": "^1.4.0",
-        "wouter": "^3.9.0"
-    },
-    "dependencies": {
         "@radix-ui/react-icons": "^1.3.2",
         "@radix-ui/react-separator": "^1.1.8",
         "@radix-ui/react-slot": "^1.2.4",
         "@radix-ui/react-switch": "^1.2.6",
         "@radix-ui/react-tooltip": "^1.2.8",
+        "@types/react": "^19.2.13",
+        "@types/react-dom": "^19.2.1",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
-        "lucide-react": "^0.562.0",
+        "lucide-react": "^0.563.0",
-        "motion": "^12.27.1",
+        "motion": "^12.34.0",
         "next-themes": "^0.4.6",
+        "react": "^19.2.4",
+        "react-dom": "^19.2.4",
         "rough-notation": "^0.5.1",
-        "simple-icons": "^16.6.0",
+        "simple-icons": "^16.8.0",
         "sonner": "^2.0.7",
-        "tailwind-merge": "^3.4.0"
+        "tailwind-merge": "^3.4.0",
+        "tailwindcss": "^4.1.14",
+        "tw-animate-css": "^1.4.0",
+        "wouter": "^3.9.0"
     }
 }

packages/website/src/components/BetaNotice.tsx

@@ -1,7 +1,7 @@
-import { useTranslation } from 'react-i18next'
+import { useLanguage } from '@/i18n/context'
 
 export default function BetaNotice() {
-	const { t } = useTranslation('common')
+	const { isZh } = useLanguage()
 
 	return (
 		<div className="bg-orange-50 dark:bg-orange-900/20 border border-orange-200 dark:border-orange-800 rounded-lg p-4 mb-8">
@@ -11,9 +11,13 @@ export default function BetaNotice() {
 				</div>
 				<div className="ml-3">
 					<h3 className="text-sm font-medium text-orange-800 dark:text-orange-200 mb-1">
-						{t('beta_notice.title')}
+						{isZh ? 'Beta 阶段' : 'Beta Stage'}
 					</h3>
-					<p className="text-sm text-orange-700 dark:text-orange-300">{t('beta_notice.content')}</p>
+					<p className="text-sm text-orange-700 dark:text-orange-300">
+						{isZh
+							? '当前功能未完成，接口可能随时变更。正式版本发布前请勿用于生产环境。'
+							: 'Current features are incomplete and the API may change at any time. Please do not use in production environments before the official release.'}
+					</p>
 				</div>
 			</div>
 		</div>

packages/website/src/components/Footer.tsx

@@ -1,8 +1,9 @@
-import { useTranslation } from 'react-i18next'
 import { siGithub } from 'simple-icons'
 
+import { useLanguage } from '@/i18n/context'
+
 export default function Footer() {
-	const { t } = useTranslation('common')
+	const { isZh } = useLanguage()
 
 	return (
 		<footer
@@ -11,14 +12,16 @@ export default function Footer() {
 		>
 			<div className="max-w-7xl mx-auto px-6 py-6">
 				<div className="flex flex-col md:flex-row justify-between items-center space-y-4 md:space-y-0">
-					<p className="text-gray-600 dark:text-gray-300 text-sm">{t('footer.copyright')}</p>
+					<p className="text-gray-600 dark:text-gray-300 text-sm">
+						© 2026 page-agent. All rights reserved.
+					</p>
 					<div className="flex items-center space-x-6">
 						<a
 							href="https://github.com/alibaba/page-agent"
 							target="_blank"
 							rel="noopener noreferrer"
 							className="text-gray-600 dark:text-gray-300 hover:text-gray-900 dark:hover:text-white transition-colors duration-200"
-							aria-label={t('footer.github_label')}
+							aria-label={isZh ? '访问 GitHub 仓库' : 'Visit GitHub repository'}
 						>
 							<svg
 								role="img"

packages/website/src/components/Header.tsx

@@ -1,15 +1,16 @@
 import { BookOpen, Menu, X } from 'lucide-react'
 import { useState } from 'react'
-import { useTranslation } from 'react-i18next'
 import { siGithub } from 'simple-icons'
 import { Link } from 'wouter'
 
+import { useLanguage } from '@/i18n/context'
+
 import LanguageSwitcher from './LanguageSwitcher'
 import ThemeSwitcher from './ThemeSwitcher'
 import { HyperText } from './ui/hyper-text'
 
 export default function Header() {
-	const { t } = useTranslation('common')
+	const { isZh } = useLanguage()
 	const [mobileMenuOpen, setMobileMenuOpen] = useState(false)
 
 	return (
@@ -24,7 +25,7 @@ export default function Header() {
 						<Link
 							href="~/"
 							className="flex items-center gap-2 sm:gap-3 group shrink-0"
-							aria-label={t('header.logo_alt')}
+							aria-label={isZh ? 'page-agent 首页' : 'page-agent home'}
 							onClick={() => setMobileMenuOpen(false)}
 						>
 							<img
@@ -43,7 +44,7 @@ export default function Header() {
 									animateOnHover={true}
 									aria-hidden="true"
 								>
-									{t('header.slogan')}
+									GUI Agent in your webpage
 								</HyperText>
 							</div>
 						</Link>
@@ -57,7 +58,7 @@ export default function Header() {
 							<Link
 								href="~/docs/introduction/overview"
 								className="p-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200 shrink-0"
-								aria-label={t('header.nav_docs')}
+								aria-label={isZh ? '文档' : 'Docs'}
 							>
 								<BookOpen className="w-5 h-5" />
 							</Link>
@@ -66,7 +67,7 @@ export default function Header() {
 								target="_blank"
 								rel="noopener noreferrer"
 								className="p-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200 shrink-0"
-								aria-label={t('header.nav_source')}
+								aria-label="GitHub"
 							>
 								<svg
 									role="img"
@@ -83,7 +84,7 @@ export default function Header() {
 						<nav
 							className="hidden md:flex items-center space-x-6"
 							role="navigation"
-							aria-label={t('header.nav_docs')}
+							aria-label={isZh ? '文档' : 'Docs'}
 						>
 							<span className="text-xs font-mono text-gray-400 dark:text-gray-500 tabular-nums before:content-['v']">
 								{import.meta.env.VERSION}
@@ -93,14 +94,14 @@ export default function Header() {
 								className="flex items-center gap-1.5 text-gray-600 dark:text-gray-300 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200"
 							>
 								<BookOpen className="w-4 h-4" />
-								{t('header.nav_docs')}
+								{isZh ? '文档' : 'Docs'}
 							</Link>
 							<a
 								href="https://github.com/alibaba/page-agent"
 								target="_blank"
 								rel="noopener noreferrer"
 								className="flex items-center gap-1.5 text-gray-600 dark:text-gray-300 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200"
-								aria-label={t('header.nav_source')}
+								aria-label="GitHub"
 							>
 								<svg
 									role="img"
@@ -110,7 +111,7 @@ export default function Header() {
 								>
 									<path d={siGithub.path} />
 								</svg>
-								{t('header.nav_source')}
+								GitHub
 							</a>
 							<ThemeSwitcher />
 							<LanguageSwitcher />
@@ -120,7 +121,7 @@ export default function Header() {
 						<button
 							type="button"
 							className="md:hidden p-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 transition-colors duration-200 shrink-0"
-							aria-label={t('header.mobile_menu')}
+							aria-label={isZh ? '打开导航栏' : 'Open navigation'}
 							aria-expanded={mobileMenuOpen}
 							aria-controls="mobile-menu"
 							onClick={() => setMobileMenuOpen(!mobileMenuOpen)}
@@ -142,14 +143,14 @@ export default function Header() {
 								onClick={() => setMobileMenuOpen(false)}
 							>
 								<BookOpen className="w-5 h-5" />
-								{t('header.nav_docs')}
+								{isZh ? '文档' : 'Docs'}
 							</Link>
 							<a
 								href="https://github.com/alibaba/page-agent"
 								target="_blank"
 								rel="noopener noreferrer"
 								className="flex items-center gap-2 px-3 py-2 rounded-lg text-gray-600 dark:text-gray-300 hover:bg-gray-100 dark:hover:bg-gray-800 hover:text-blue-600 dark:hover:text-blue-400 transition-colors duration-200"
-								aria-label={t('header.nav_source')}
+								aria-label="GitHub"
 							>
 								<svg
 									role="img"
@@ -159,7 +160,7 @@ export default function Header() {
 								>
 									<path d={siGithub.path} />
 								</svg>
-								{t('header.nav_source')}
+								GitHub
 							</a>
 							<div className="flex items-center gap-3 px-3 py-2">
 								<ThemeSwitcher />

packages/website/src/components/HighlightSyntax.module.css

@@ -3,6 +3,8 @@
 	word-break: break-word;
 	overflow-wrap: break-word;
 	font-family: monospace;
+	font-size: 13px;
+	line-height: 1;
 	color: #171717;
 }
 

packages/website/src/components/LanguageSwitcher.tsx

@@ -1,22 +1,21 @@
 import { useEffect, useRef, useState } from 'react'
-import { useTranslation } from 'react-i18next'
+
+import { useLanguage } from '@/i18n/context'
 
 export default function LanguageSwitcher() {
-	const { i18n, t } = useTranslation('common')
+	const { language, isZh, setLanguage } = useLanguage()
 	const [isOpen, setIsOpen] = useState(false)
 	const dropdownRef = useRef<HTMLDivElement>(null)
 
-	const currentLang = i18n.language
-
 	const languages = [
-		{ code: 'zh-CN', label: '中文' },
+		{ code: 'zh-CN' as const, label: '中文' },
-		{ code: 'en-US', label: 'English' },
+		{ code: 'en-US' as const, label: 'English' },
 	]
 
-	const currentLanguage = languages.find((lang) => lang.code === currentLang) || languages[0]
+	const currentLanguage = languages.find((lang) => lang.code === language) || languages[0]
 
-	const handleLanguageChange = (langCode: string) => {
+	const handleLanguageChange = (langCode: 'zh-CN' | 'en-US') => {
-		i18n.changeLanguage(langCode)
+		setLanguage(langCode)
 		setIsOpen(false)
 	}
 
@@ -42,7 +41,7 @@ export default function LanguageSwitcher() {
 			<button
 				onClick={() => setIsOpen(!isOpen)}
 				className="flex items-center gap-2 px-3 py-1.5 rounded-lg bg-gray-100 dark:bg-gray-800 hover:bg-gray-200 dark:hover:bg-gray-700 transition-colors text-sm font-medium border border-gray-200 dark:border-gray-700 text-gray-700 dark:text-gray-300"
-				aria-label={t('language.switch_label')}
+				aria-label={isZh ? '切换语言' : 'Switch language'}
 				aria-expanded={isOpen}
 				aria-haspopup="true"
 			>
@@ -83,14 +82,14 @@ export default function LanguageSwitcher() {
 							key={lang.code}
 							onClick={() => handleLanguageChange(lang.code)}
 							className={`w-full flex items-center gap-2 px-4 py-2 text-sm text-left hover:bg-gray-100 dark:hover:bg-gray-700 transition-colors ${
-								currentLang === lang.code
+								language === lang.code
 									? 'bg-blue-50 dark:bg-blue-900/20 text-blue-700 dark:text-blue-300'
 									: 'text-gray-700 dark:text-gray-300'
 							}`}
 							role="menuitem"
 						>
 							<span>{lang.label}</span>
-							{currentLang === lang.code && (
+							{language === lang.code && (
 								<svg
 									className="w-4 h-4 ml-auto"
 									fill="none"

packages/website/src/constants.ts

@@ -1,8 +1,8 @@
 // Demo build (auto-init with demo LLM, for quick testing)
 export const CDN_DEMO_URL =
-	'https://cdn.jsdelivr.net/npm/page-agent@1.0.0/dist/iife/page-agent.demo.js'
+	'https://cdn.jsdelivr.net/npm/page-agent@1.2.0/dist/iife/page-agent.demo.js'
 export const CDN_DEMO_CN_URL =
-	'https://registry.npmmirror.com/page-agent/1.0.0/files/dist/iife/page-agent.demo.js'
+	'https://registry.npmmirror.com/page-agent/1.2.0/files/dist/iife/page-agent.demo.js'
 
 // Demo LLM for website testing
 export const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'

packages/website/src/i18n/README.md

@@ -1,73 +0,0 @@
-# 国际化配置说明
-
-本项目使用 `react-i18next` 实现国际化支持。
-
-## 目录结构
-
-```
-pages/i18n/
-├── config.ts              # i18next 配置和初始化
-├── types.ts               # TypeScript 类型声明
-├── locales/
-│   ├── zh-CN/             # 中文翻译
-│   │   ├── common.json    # 通用组件（Header, Footer等）
-│   │   ├── home.json      # 首页
-│   │   └── docs.json      # 文档页（待完善）
-│   └── en-US/             # 英文翻译
-│       ├── common.json
-│       ├── home.json
-│       └── docs.json
-└── README.md              # 本文件
-```
-
-## 使用方法
-
-### 在组件中使用
-
-```tsx
-import { useTranslation } from 'react-i18next'
-
-function MyComponent() {
-    const { t } = useTranslation('common') // 指定命名空间
-
-    return <h1>{t('header.nav_docs')}</h1>
-}
-```
-
-### 使用多个命名空间
-
-```tsx
-const { t } = useTranslation(['home', 'common'])
-
-// 使用时指定命名空间
-t('home:hero.title')
-t('common:header.nav_docs')
-```
-
-## 语言切换
-
-用户可以通过以下方式切换语言：
-
-1. **自动检测**：首次访问根据浏览器语言自动选择
-2. **手动切换**：点击页面右上角的语言切换按钮
-3. **持久化**：语言选择保存在 `localStorage` 中，刷新后保持
-
-## 添加新翻译
-
-1. 在对应的 JSON 文件中添加翻译条目（如 `zh-CN/home.json`）
-2. 在对应的英文文件中添加翻译（如 `en-US/home.json`）
-3. 在组件中使用 `t('namespace:key')` 获取翻译
-
-## TypeScript 支持
-
-`types.ts` 文件提供了类型声明，使得翻译 key 具有：
-
-- 自动补全
-- 编译期类型检查
-- 防止拼写错误
-
-## 待完成
-
-- [ ] 文档页翻译（`docs.json`）
-- [ ] DocsLayout 导航结构国际化
-- [ ] 404 页面国际化

packages/website/src/i18n/config.ts

@@ -1,45 +0,0 @@
-import i18n from 'i18next'
-import LanguageDetector from 'i18next-browser-languagedetector'
-import { initReactI18next } from 'react-i18next'
-
-import commonEn from './locales/en-US/common'
-import docsEn from './locales/en-US/docs'
-import homeEn from './locales/en-US/home'
-import commonZh from './locales/zh-CN/common'
-import docsZh from './locales/zh-CN/docs'
-import homeZh from './locales/zh-CN/home'
-
-const resources = {
-	'zh-CN': {
-		common: commonZh,
-		home: homeZh,
-		docs: docsZh,
-	},
-	'en-US': {
-		common: commonEn,
-		home: homeEn,
-		docs: docsEn,
-	},
-}
-
-i18n
-	.use(LanguageDetector)
-	.use(initReactI18next)
-	.init({
-		resources,
-		fallbackLng: 'en-US',
-		defaultNS: 'common',
-
-		// 语言检测配置
-		detection: {
-			// localStorage 优先（用户手动选择），其次检测浏览器语言
-			order: ['localStorage', 'navigator'],
-			caches: ['localStorage'],
-		},
-
-		interpolation: {
-			escapeValue: false, // React 已经做了 XSS 防护
-		},
-	})
-
-export default i18n

packages/website/src/i18n/context.tsx

@@ -0,0 +1,35 @@
+import { ReactNode, createContext, use, useState } from 'react'
+
+type Lang = 'en-US' | 'zh-CN'
+
+const LanguageContext = createContext<{
+	language: Lang
+	isZh: boolean
+	setLanguage: (lang: Lang) => void
+} | null>(null)
+
+export function LanguageProvider({ children }: { children: ReactNode }) {
+	const [language, setLang] = useState<Lang>(() => {
+		const stored = localStorage.getItem('language') as Lang
+		if (stored === 'zh-CN' || stored === 'en-US') return stored
+		return navigator.language.startsWith('zh') ? 'zh-CN' : 'en-US'
+	})
+
+	const setLanguage = (lang: Lang) => {
+		setLang(lang)
+		localStorage.setItem('language', lang)
+	}
+
+	return (
+		<LanguageContext value={{ language, isZh: language === 'zh-CN', setLanguage }}>
+			{children}
+		</LanguageContext>
+	)
+}
+
+// eslint-disable-next-line react-refresh/only-export-components
+export function useLanguage() {
+	const ctx = use(LanguageContext)
+	if (!ctx) throw new Error('useLanguage must be used within LanguageProvider')
+	return ctx
+}

packages/website/src/i18n/locales/en-US/common.ts

@@ -1,42 +0,0 @@
-export default {
-	header: {
-		logo_alt: 'page-agent home',
-		slogan: 'GUI Agent in your webpage',
-		nav_docs: 'Docs',
-		nav_source: 'GitHub',
-		mobile_menu: 'Open navigation',
-	},
-	footer: {
-		copyright: '© 2025 page-agent. All rights reserved.',
-		github_label: 'Visit GitHub repository',
-	},
-	beta_notice: {
-		title: 'Beta Stage',
-		content:
-			'Current features are incomplete and the API may change at any time. Please do not use in production environments before the official release.',
-	},
-	language: {
-		zh: '中文',
-		en: 'English',
-		switch_label: 'Switch language',
-	},
-	nav: {
-		introduction: 'Introduction',
-		features: 'Features',
-		integration: 'Integration',
-		advanced: 'Advanced',
-		overview: 'Overview',
-		quick_start: 'Quick Start',
-		limitations: 'Limitations',
-		models: 'Models',
-		custom_tools: 'Custom Tools',
-		knowledge_injection: 'Instructions',
-		data_masking: 'Data Masking',
-		cdn_setup: 'CDN Setup',
-		best_practices: 'Best Practices',
-		third_party_agent: 'Third-party Agent',
-		security_permissions: 'Security & Permissions',
-		page_agent: 'PageAgent',
-		page_agent_core: 'PageAgentCore',
-	},
-}

packages/website/src/i18n/locales/en-US/docs.ts

@@ -1,157 +0,0 @@
-export default {
-	overview: {
-		title: 'Overview',
-		subtitle:
-			'page-agent is a purely web-based GUI Agent. Gives your website an AI operator in simple steps.',
-		what_is: 'What is page-agent?',
-		what_is_desc:
-			'page-agent is an embedded GUI Agent. Unlike traditional browser automation tools, page-agent is built for web developers and web applications first. Integrate it into your site to let users interact with pages through natural language.',
-		features_title: 'Core Features',
-		feature_dom: {
-			title: '🧠 Smart DOM Analysis',
-			desc: 'DOM-based analysis with high-intensity dehydration. No visual recognition needed. Pure text for fast and precise operations.',
-		},
-		feature_secure: {
-			title: '🔒 Secure & Controllable',
-			desc: 'Supports operation allowlists, data masking protection. Inject custom knowledge to make AI work by your rules.',
-		},
-		feature_backend: {
-			title: '⚡ Zero Backend',
-			desc: 'CDN or NPM import with custom LLM endpoints.',
-		},
-		feature_accessible: {
-			title: '♿ Accessible Intelligence',
-			desc: 'Provides natural language interface for complex B2B systems and admin panels. Makes software easy for everyone.',
-		},
-		vs_browser_use: 'vs. browser-use',
-		table_feature: 'Feature',
-		table_deployment: 'Deployment',
-		table_deployment_pa: 'Embedded component',
-		table_deployment_bu: 'External tool',
-		table_scope: 'Scope',
-		table_scope_pa: 'Current page',
-		table_scope_bu: 'Entire browser',
-		table_user: 'Target Users',
-		table_user_pa: 'Web developers',
-		table_user_bu: 'Scraper/Agent developers',
-		table_scenario: 'Use Case',
-		table_scenario_pa: 'UX enhancement',
-		table_scenario_bu: 'Automation tasks',
-		use_cases_title: 'Use Cases',
-		use_case1_title: 'Connect Support Bots:',
-		use_case1_desc:
-			"Turn your support assistant into a full agent. Customer service bots no longer just say 'Please click the settings button then click...'—they operate for users directly.",
-		use_case2_title: 'Modernize Legacy Apps:',
-		use_case2_desc:
-			'One line of code transforms old apps into agents. Product experts help users navigate complex B2B software. Reduce support costs and improve satisfaction.',
-		use_case3_title: 'Interactive Training:',
-		use_case3_desc:
-			"Demonstrate workflows in real-time. Let AI show the complete process of 'how to submit an expense report.'",
-		use_case4_title: 'Accessibility:',
-		use_case4_desc:
-			'Provide natural language interaction for visually impaired and elderly users. Connect screen readers or voice assistants to make software accessible to everyone.',
-		get_started_title: '🚀 Get Started',
-		get_started_desc:
-			'Ready to add an AI operator to your website? Check our quick start guide for integration in minutes.',
-		get_started_button: 'Quick Start →',
-	},
-	quick_start: {
-		title: 'Quick Start',
-		subtitle: 'Integrate page-agent in minutes.',
-		installation: 'Installation Steps',
-		step1_title: '1. Import Options',
-		step1_cdn: 'CDN Import',
-		step1_npm: 'NPM Install',
-		step2_title: '2. Initialize Configuration',
-		step3_title: '3. Start Using',
-	},
-	limitations: {
-		title: 'Limitations',
-		subtitle: "Understand page-agent's current capabilities and technical constraints",
-		page_support: 'Page Support Limitations',
-		spa_limit_title: 'Single Page Application Limits',
-		spa_limit_1: '• SPA only: Currently operates within a single page',
-		spa_limit_2: '• Multi-page relay in design: Cannot execute continuous tasks across pages yet',
-		spa_limit_3: '• Requires integration: Cannot operate on sites without page-agent',
-		interaction_limits: 'Interaction Limitations',
-		supported_ops: 'Supported Operations',
-		op_click: 'Click',
-		op_input: 'Text input',
-		op_scroll: 'Scroll',
-		op_submit: 'Form submit',
-		op_select: 'Select',
-		op_focus: 'Focus',
-		unsupported_ops: 'Unsupported Operations',
-		op_hover: 'Mouse hover',
-		op_drag: 'Drag & drop',
-		op_context: 'Right-click menu',
-		op_draw: 'Drawing',
-		op_keyboard: 'Keyboard shortcuts',
-		op_position: 'Position-based control',
-		understanding_limits: 'Understanding Limitations',
-		no_vision_title: 'No Visual Recognition',
-		no_vision_desc:
-			'page-agent operates based on DOM structure with no visual recognition. Cannot understand:',
-		no_vision_1: '• Image content: Cannot recognize text, icons, or visual elements in images',
-		no_vision_2: '• Canvas: Cannot understand graphics drawn on Canvas',
-		no_vision_3: '• WebGL 3D: Cannot operate elements in 3D scenes',
-		no_vision_4: '• SVG graphics: Cannot understand visual content and paths in SVG',
-		website_requirements: 'Website Requirements',
-		req_semantic_title: 'Semantic & Usability',
-		req_semantic_desc:
-			'All operations rely on semantic tags and attributes. Poor semantic structure or lack of accessibility features may affect AI understanding accuracy.',
-		req_ux_title: 'UI/UX',
-		req_ux_desc:
-			'Counter-intuitive interaction rules, visual-only operation hints, complex mouse interactions, or rapidly appearing/disappearing elements can affect AI understanding and operation.',
-		req_env_title: 'Environment',
-		req_env_desc: 'modern browser',
-		future: 'Future Plans',
-		future_title: 'Coming Soon',
-		future_1: '• Multi-page relay capabilities',
-		future_2: '• Richer mouse interaction support',
-		future_3: '• Basic visual understanding',
-		future_4: '• Smarter error recovery',
-	},
-	models: {
-		title: 'Models',
-		subtitle:
-			'Supports models that comply with OpenAI API specification and support tool calls, including public cloud services and private deployments.',
-		recommendation_logic: 'Recommended: Lightweight models with strong ToolCall capabilities.',
-		recommended: 'Recommended Models',
-		available: 'Tested Models',
-		available_verified: 'Verified Working Models',
-		tips: 'Tips',
-		tip_1: 'Reasoning models (like GPT-5) are slower with no advantage',
-		tip_2:
-			'Models with weaker ToolCall capabilities may return incorrect formats. Common errors usually auto-recover. Higher temperature recommended',
-		tip_3:
-			'Small models or those unable to handle complex tool definitions typically perform poorly',
-		security: '🔐 Production Authentication',
-		security_warning: '⚠️ Never commit real LLM API Keys to your frontend code',
-		security_desc:
-			'In production environments, to hide the real LLM API Keys, we recommend the following architecture:',
-		security_backend_proxy: 'Backend Proxy Pattern',
-		security_backend_desc:
-			'Set up a backend LLM proxy endpoint that uses the same authentication method as other APIs in your website, such as:',
-		security_method_1: '• Session/Cookie-based authentication',
-		security_method_2: '• OIDC (OpenID Connect) single sign-on',
-		security_method_3: '• Temporary Access Key or JWT Token',
-		configuration: 'Configuration',
-	},
-	custom_tools: {
-		title: 'Custom Tools',
-		subtitle:
-			'Extend AI Agent capabilities by registering custom tools. Use Zod to define strict input schemas for safe business logic calls.',
-		registration: 'Tool Registration',
-		registration_desc:
-			'Each custom tool requires four core properties: name, description, input schema, and execute function.',
-		page_filter: 'Page Filter',
-		page_filter_desc:
-			'Control tool visibility on specific pages via the pageFilter property to enhance security and UX.',
-		best_practices: 'Best Practices',
-		bp_performance: '⚡ Performance Optimization',
-		bp_1: '• Use pageFilter to reduce unnecessary tool loading',
-		bp_2: '• Implement appropriate caching in execute functions',
-		bp_3: '• Avoid long-running sync operations in tools',
-	},
-}