From 15ffc270599a456d20858c8c5207efc93b2505c1 Mon Sep 17 00:00:00 2001
From: Simon <10131203+gaomeng1900@users.noreply.github.com>
Date: Sat, 17 Jan 2026 23:30:37 +0800
Subject: [PATCH] chore: agent event docs

---
 packages/page-agent/src/PageAgent.ts | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/packages/page-agent/src/PageAgent.ts b/packages/page-agent/src/PageAgent.ts
index ef347d1..e6d0b4b 100644
--- a/packages/page-agent/src/PageAgent.ts
+++ b/packages/page-agent/src/PageAgent.ts
@@ -27,6 +27,27 @@ import { assert } from './utils/assert'
 export type { PageAgentConfig }
 export { tool, type PageAgentTool } from './tools'
 
+/**
+ * AI agent for browser DOM automation.
+ *
+ * @remarks
+ * ## Event System
+ * - `statuschange` - Agent status transitions (idle → running → completed/error)
+ * - `historychange` - History events updated (persistent, part of agent memory)
+ * - `activity` - Real-time activity feedback (transient, for UI only)
+ * - `dispose` - Agent cleanup triggered
+ *
+ * ## Information Streams
+ * 1. **History Events** (`history` array)
+ *    - Persistent event stream that forms agent's memory
+ *    - Included in LLM context across steps
+ *    - Types: steps, observations, user takeovers, llm errors
+ *
+ * 2. **Activity Events** (via `activity` event)
+ *    - Transient UI feedback during task execution
+ *    - NOT included in LLM context
+ *    - Types: thinking, executing, executed, retrying, error
+ */
 export class PageAgent extends EventTarget {
 	config: PageAgentConfig
 	id = uid()