From 4c5dd23fcd0786dbed90171b785fc1fc2d2dc5ee Mon Sep 17 00:00:00 2001
From: Simon <10131203+gaomeng1900@users.noreply.github.com>
Date: Mon, 19 Jan 2026 17:14:09 +0800
Subject: [PATCH] feat: decouple `PageController` from `PageAgent`

---
 packages/core/src/PageAgentCore.ts   | 13 +++----------
 packages/core/src/config/index.ts    |  7 -------
 packages/page-agent/src/PageAgent.ts |  9 ++++++++-
 3 files changed, 11 insertions(+), 18 deletions(-)

diff --git a/packages/core/src/PageAgentCore.ts b/packages/core/src/PageAgentCore.ts
index c26e4a2..f5e273c 100644
--- a/packages/core/src/PageAgentCore.ts
+++ b/packages/core/src/PageAgentCore.ts
@@ -3,7 +3,7 @@
  * All rights reserved.
  */
 import { LLM, type Tool } from '@page-agent/llms'
-import { PageController } from '@page-agent/page-controller'
+import type { PageController } from '@page-agent/page-controller'
 import chalk from 'chalk'
 import zod from 'zod'
 
@@ -83,20 +83,13 @@ export class PageAgentCore extends EventTarget {
 	/** History events */
 	history: HistoricalEvent[] = []
 
-	constructor(config: PageAgentConfig) {
+	constructor(config: PageAgentConfig & { pageController: PageController }) {
 		super()
 
 		this.config = config
 		this.#llm = new LLM(this.config)
 		this.tools = new Map(tools)
-
-		// Initialize PageController with config (mask enabled by default)
-		this.pageController =
-			this.config.pageController ??
-			new PageController({
-				...this.config,
-				enableMask: this.config.enableMask ?? true,
-			})
+		this.pageController = config.pageController
 
 		// Listen to LLM retry events
 		this.#llm.addEventListener('retry', (e) => {
diff --git a/packages/core/src/config/index.ts b/packages/core/src/config/index.ts
index 5eaf9ce..fa5ce60 100644
--- a/packages/core/src/config/index.ts
+++ b/packages/core/src/config/index.ts
@@ -104,13 +104,6 @@ export interface AgentConfig {
 	 */
 	transformPageContent?: (content: string) => Promise<string> | string
 
-	/**
-	 * @experimental
-	 * Custom PageController instance to control page navigation and actions
-	 * @note If not provided, a default PageController will be created
-	 */
-	pageController?: PageController
-
 	/**
 	 * TODO: @unimplemented
 	 * hook when action causes a new page to be opened
diff --git a/packages/page-agent/src/PageAgent.ts b/packages/page-agent/src/PageAgent.ts
index 31ef902..5b88698 100644
--- a/packages/page-agent/src/PageAgent.ts
+++ b/packages/page-agent/src/PageAgent.ts
@@ -3,6 +3,7 @@
  * All rights reserved.
  */
 import { type PageAgentConfig, PageAgentCore } from '@page-agent/core'
+import { PageController } from '@page-agent/page-controller'
 import { Panel } from '@page-agent/ui'
 
 export type { PageAgentConfig }
@@ -11,7 +12,13 @@ export class PageAgent extends PageAgentCore {
 	panel: Panel
 
 	constructor(config: PageAgentConfig) {
-		super(config)
+		const pageController = new PageController({
+			...config,
+			enableMask: config.enableMask ?? true,
+		})
+
+		super({ ...config, pageController })
+
 		this.panel = new Panel(this, {
 			language: config.language,
 		})