From 840162df8c8b9fbf5bc59d1a63bc3739252a5118 Mon Sep 17 00:00:00 2001
From: Simon <10131203+gaomeng1900@users.noreply.github.com>
Date: Mon, 9 Feb 2026 21:05:29 +0800
Subject: [PATCH] feat: change observation timing

---
 packages/core/src/PageAgentCore.ts            | 24 +++++++++++++------
 .../docs/advanced/page-agent-core/page.tsx    |  7 ------
 2 files changed, 17 insertions(+), 14 deletions(-)

diff --git a/packages/core/src/PageAgentCore.ts b/packages/core/src/PageAgentCore.ts
index 157f075..74ffe43 100644
--- a/packages/core/src/PageAgentCore.ts
+++ b/packages/core/src/PageAgentCore.ts
@@ -67,6 +67,7 @@ export class PageAgentCore extends EventTarget {
 
 	#llm: LLM
 	#abortController = new AbortController()
+	#observations: string[] = []
 
 	/** PageController for DOM operations */
 	pageController: PageController
@@ -165,12 +166,13 @@ export class PageAgentCore extends EventTarget {
 	}
 
 	/**
-	 * Push a persistent observation to the history event stream.
-	 * This will be visible in <agent_history> and remain in memory across steps.
+	 * Push a observation message to the history event stream.
+	 * 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.#emitHistoryChange()
+		this.#observations.push(content)
 	}
 
 	async execute(task: string): Promise<ExecutionResult> {
@@ -214,7 +216,15 @@ export class PageAgentCore extends EventTarget {
 			try {
 				console.group(`step: ${step}`)
 
-				await this.#generateObservations(step)
+				await this.#systemObservations(step)
+
+				if (this.#observations.length > 0) {
+					for (const content of this.#observations) {
+						this.history.push({ type: 'observation', content })
+					}
+					this.#observations = []
+					this.#emitHistoryChange()
+				}
 
 				await onBeforeStep?.(this, step)
 
@@ -468,13 +478,13 @@ 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 #systemObservations(stepCount: number): Promise<void> {
 		// Detect URL change
 		const currentURL = await this.pageController.getCurrentUrl()
 		if (currentURL !== this.states.lastURL) {
diff --git a/packages/website/src/pages/docs/advanced/page-agent-core/page.tsx b/packages/website/src/pages/docs/advanced/page-agent-core/page.tsx
index 998a865..e9a8961 100644
--- a/packages/website/src/pages/docs/advanced/page-agent-core/page.tsx
+++ b/packages/website/src/pages/docs/advanced/page-agent-core/page.tsx
@@ -376,13 +376,6 @@ const result = await agent.execute('Fill in the form with test data')`}
 								? '执行任务并返回结果。包含 success、data 和 history 字段。'
 								: 'Execute a task and return result. Contains success, data, and history fields.',
 						},
-						{
-							name: 'pushObservation(content: string)',
-							type: 'void',
-							description: isZh
-								? '向历史流推送一个观察事件，会在下一步时被 LLM 看到'
-								: 'Push an observation to history stream, will be seen by LLM in next step',
-						},
 						{
 							name: 'dispose(reason?: string)',
 							type: 'void',