page-agent 0.0.24 → 0.2.0

package/dist/esm/PageAgent.d.ts

@@ -54,7 +54,7 @@ declare interface AgentConfig {
         getPageInstructions?: (url: string) => string | undefined | null;
     };
     onBeforeStep?: (this: PageAgent, stepCnt: number) => Promise<void> | void;
-    onAfterStep?: (this: PageAgent, stepCnt: number, history: AgentHistory[]) => Promise<void> | void;
+    onAfterStep?: (this: PageAgent, stepCnt: number, history: HistoryEvent[]) => Promise<void> | void;
     onBeforeTask?: (this: PageAgent) => Promise<void> | void;
     onAfterTask?: (this: PageAgent, result: ExecutionResult) => Promise<void> | void;
     /**
@@ -100,24 +100,11 @@ declare interface AgentConfig {
     experimentalPreventNewPage?: boolean;
 }
 
-export declare interface AgentHistory {
-    brain: Partial<AgentReflection>;
-    action: {
-        name: string;
-        input: any;
-        output: string;
-    };
-    usage: {
-        promptTokens: number;
-        completionTokens: number;
-        totalTokens: number;
-        cachedTokens?: number;
-        reasoningTokens?: number;
-    };
-}
+/** @deprecated Use AgentStep instead */
+export declare type AgentHistory = AgentStep;
 
 /**
- * Agent brain state - the reflection-before-action model
+ * Agent reflection state - the reflection-before-action model
  *
  * Every tool call must first reflect on:
  * - evaluation_previous_goal: How well did the previous action achieve its goal?
@@ -130,12 +117,37 @@ export declare interface AgentReflection {
     next_goal: string;
 }
 
+/**
+ * A single agent step with reflection and action
+ */
+export declare interface AgentStep {
+    type: 'step';
+    reflection: Partial<AgentReflection>;
+    action: {
+        name: string;
+        input: any;
+        output: string;
+    };
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        cachedTokens?: number;
+        reasoningTokens?: number;
+    };
+}
+
 export declare interface ExecutionResult {
     success: boolean;
     data: string;
-    history: AgentHistory[];
+    history: HistoryEvent[];
 }
 
+/**
+ * Union type for all history events
+ */
+export declare type HistoryEvent = AgentStep | ObservationEvent | UserTakeoverEvent;
+
 /**
  * MacroTool input structure
  *
@@ -154,6 +166,14 @@ export declare interface MacroToolResult {
     output: string;
 }
 
+/**
+ * Persistent observation event (stays in memory)
+ */
+export declare interface ObservationEvent {
+    type: 'observation';
+    content: string;
+}
+
 export declare class PageAgent extends EventTarget {
     #private;
     config: PageAgentConfig;
@@ -166,9 +186,21 @@ export declare class PageAgent extends EventTarget {
     taskId: string;
     /** PageController for DOM operations */
     pageController: PageController;
-    /** History records */
-    history: AgentHistory[];
-    constructor(config?: PageAgentConfig);
+    /** Runtime states for tracking across steps */
+    states: {
+        /** Accumulated wait time in seconds, used by wait tool */
+        totalWaitTime: number;
+        /** Last known URL for detecting navigation */
+        lastURL: string;
+    };
+    /** History event stream */
+    history: HistoryEvent[];
+    constructor(config: PageAgentConfig);
+    /**
+     * Push a persistent observation to the history event stream.
+     * This will be visible in <agent_history> and remain in memory across steps.
+     */
+    pushObservation(content: string): void;
     execute(task: string): Promise<ExecutionResult>;
     dispose(reason?: string): void;
 }
@@ -192,4 +224,11 @@ export declare function tool<TParams>(options: PageAgentTool<TParams>): PageAgen
  */
 declare const tools: Map<string, PageAgentTool<any>>;
 
+/**
+ * User takeover event
+ */
+export declare interface UserTakeoverEvent {
+    type: 'user_takeover';
+}
+
 export { }

package/dist/esm/page-agent.js

@@ -10,7 +10,7 @@ var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read fr
 var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
 var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
 var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
-var _llm, _totalWaitTime, _abortController, _llmRetryListener, _llmErrorListener, _beforeUnloadListener, _PageAgent_instances, packMacroTool_fn, getSystemPrompt_fn, getInstructions_fn, assembleUserPrompt_fn, onDone_fn, getBrowserState_fn;
+var _llm, _abortController, _llmRetryListener, _llmErrorListener, _beforeUnloadListener, _PageAgent_instances, packMacroTool_fn, getSystemPrompt_fn, getInstructions_fn, generateObservations_fn, assembleUserPrompt_fn, onDone_fn, getBrowserState_fn;
 import { LLM } from "@page-agent/llms";
 import { PageController } from "@page-agent/page-controller";
 import { Panel } from "@page-agent/ui";
@@ -191,6 +191,12 @@ tools.set(
       const actualWaitTime = Math.max(0, input.seconds - (Date.now() - lastTimeUpdate) / 1e3);
       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.`;
     }, "execute")
   })
@@ -305,7 +311,7 @@ function assert(condition, message, silent) {
 }
 __name(assert, "assert");
 const _PageAgent = class _PageAgent extends EventTarget {
-  constructor(config = {}) {
+  constructor(config) {
     super();
     __privateAdd(this, _PageAgent_instances);
     __publicField(this, "config");
@@ -317,14 +323,20 @@ const _PageAgent = class _PageAgent extends EventTarget {
     __publicField(this, "task", "");
     __publicField(this, "taskId", "");
     __privateAdd(this, _llm);
-    __privateAdd(this, _totalWaitTime, 0);
     __privateAdd(this, _abortController, new AbortController());
     __privateAdd(this, _llmRetryListener, null);
     __privateAdd(this, _llmErrorListener, null);
     __privateAdd(this, _beforeUnloadListener, null);
     /** PageController for DOM operations */
     __publicField(this, "pageController");
-    /** History records */
+    /** Runtime states for tracking across steps */
+    __publicField(this, "states", {
+      /** Accumulated wait time in seconds, used by wait tool */
+      totalWaitTime: 0,
+      /** Last known URL for detecting navigation */
+      lastURL: ""
+    });
+    /** History event stream */
     __publicField(this, "history", []);
     this.config = config;
     __privateSet(this, _llm, new LLM(this.config));
@@ -370,6 +382,13 @@ const _PageAgent = class _PageAgent extends EventTarget {
     });
     window.addEventListener("beforeunload", __privateGet(this, _beforeUnloadListener));
   }
+  /**
+   * Push a persistent observation to the history event stream.
+   * This will be visible in <agent_history> and remain in memory across steps.
+   */
+  pushObservation(content) {
+    this.history.push({ type: "observation", content });
+  }
   async execute(task) {
     if (!task) throw new Error("Task is required");
     this.task = task;
@@ -388,9 +407,14 @@ const _PageAgent = class _PageAgent extends EventTarget {
       __privateSet(this, _abortController, new AbortController());
     }
     this.history = [];
+    this.states = {
+      totalWaitTime: 0,
+      lastURL: ""
+    };
     try {
       let step = 0;
       while (true) {
+        await __privateMethod(this, _PageAgent_instances, generateObservations_fn).call(this, step);
         await onBeforeStep.call(this, step);
         console.group(`step: ${step}`);
         if (__privateGet(this, _abortController).signal.aborted) throw new Error("AbortError");
@@ -418,10 +442,10 @@ const _PageAgent = class _PageAgent extends EventTarget {
         const macroResult = result.toolResult;
         const input = macroResult.input;
         const output = macroResult.output;
-        const brain = {
-          evaluation_previous_goal: input.evaluation_previous_goal || "",
-          memory: input.memory || "",
-          next_goal: input.next_goal || ""
+        const reflection = {
+          evaluation_previous_goal: input.evaluation_previous_goal,
+          memory: input.memory,
+          next_goal: input.next_goal
         };
         const actionName = Object.keys(input.action)[0];
         const action = {
@@ -430,7 +454,8 @@ const _PageAgent = class _PageAgent extends EventTarget {
           output
         };
         this.history.push({
-          brain,
+          type: "step",
+          reflection,
           action,
           usage: result.usage
         });
@@ -497,7 +522,6 @@ const _PageAgent = class _PageAgent extends EventTarget {
   }
 };
 _llm = new WeakMap();
-_totalWaitTime = new WeakMap();
 _abortController = new WeakMap();
 _llmRetryListener = new WeakMap();
 _llmErrorListener = new WeakMap();
@@ -537,29 +561,26 @@ packMacroTool_fn = /* @__PURE__ */ __name(function() {
       const action = input.action;
       const toolName = Object.keys(action)[0];
       const toolInput = action[toolName];
-      const brain = trimLines(`✅: ${input.evaluation_previous_goal}
-						💾: ${input.memory}
-						🎯: ${input.next_goal}
-					`);
-      console.log(brain);
-      this.panel.update({ type: "thinking", text: brain });
+      const reflectionLines = [];
+      if (input.evaluation_previous_goal)
+        reflectionLines.push(`✅: ${input.evaluation_previous_goal}`);
+      if (input.memory) reflectionLines.push(`💾: ${input.memory}`);
+      if (input.next_goal) reflectionLines.push(`🎯: ${input.next_goal}`);
+      const reflectionText = reflectionLines.length > 0 ? reflectionLines.join("\n") : "";
+      if (reflectionText) {
+        console.log(reflectionText);
+        this.panel.update({ type: "thinking", text: reflectionText });
+      }
       const tool2 = tools2.get(toolName);
       assert(tool2, `Tool ${toolName} not found. (@note should have been caught before this!!!)`);
       console.log(chalk.blue.bold(`Executing tool: ${toolName}`), toolInput);
       this.panel.update({ type: "toolExecuting", toolName, args: toolInput });
       const startTime = Date.now();
-      let result = await tool2.execute.bind(this)(toolInput);
+      const result = await tool2.execute.bind(this)(toolInput);
       const duration = Date.now() - startTime;
       console.log(chalk.green.bold(`Tool (${toolName}) executed for ${duration}ms`), result);
-      if (toolName === "wait") {
-        __privateSet(this, _totalWaitTime, __privateGet(this, _totalWaitTime) + Math.round(toolInput.seconds + duration / 1e3));
-        result += `
-<sys> You have waited ${__privateGet(this, _totalWaitTime)} seconds accumulatively.`;
-        if (__privateGet(this, _totalWaitTime) >= 3)
-          result += "\nDo NOT wait any longer unless you have a good reason.\n";
-        result += "</sys>";
-      } else {
-        __privateSet(this, _totalWaitTime, 0);
+      if (toolName !== "wait") {
+        this.states.totalWaitTime = 0;
       }
       this.panel.update({
         type: "toolCompleted",
@@ -621,29 +642,57 @@ ${pageInstructions}
   result += "</instructions>\n\n";
   return result;
 }, "#getInstructions");
+generateObservations_fn = /* @__PURE__ */ __name(async function(stepCount) {
+  const currentURL = await this.pageController.getCurrentUrl();
+  if (currentURL !== this.states.lastURL) {
+    this.pushObservation(`Page navigated to → ${currentURL}`);
+    this.states.lastURL = currentURL;
+  }
+  const remaining = MAX_STEPS - stepCount;
+  if (remaining === 5) {
+    this.pushObservation(
+      `⚠️ Only ${remaining} steps remaining. Consider wrapping up or calling done with partial results.`
+    );
+  } else if (remaining === 2) {
+    this.pushObservation(
+      `⚠️ Critical: Only ${remaining} steps left! You must finish the task or call done immediately.`
+    );
+  }
+}, "#generateObservations");
 assembleUserPrompt_fn = /* @__PURE__ */ __name(async function() {
   let prompt = "";
   prompt += await __privateMethod(this, _PageAgent_instances, getInstructions_fn).call(this);
+  const stepCount = this.history.filter((e) => e.type === "step").length;
   prompt += `<agent_state>
 			<user_request>
 			${this.task}
 			</user_request>
 			<step_info>
-			Step ${this.history.length + 1} of ${MAX_STEPS} max possible steps
+			Step ${stepCount + 1} of ${MAX_STEPS} max possible steps
 			Current date and time: ${(/* @__PURE__ */ new Date()).toISOString()}
 			</step_info>
 			</agent_state>
 		`;
   prompt += "\n<agent_history>\n";
-  this.history.forEach((history, index) => {
-    prompt += `<step_${index + 1}>
-				Evaluation of Previous Step: ${history.brain.evaluation_previous_goal}
-				Memory: ${history.brain.memory}
-				Next Goal: ${history.brain.next_goal}
-				Action Results: ${history.action.output}
-				</step_${index + 1}>
+  let stepIndex = 0;
+  for (const event of this.history) {
+    if (event.type === "step") {
+      stepIndex++;
+      prompt += `<step_${stepIndex}>
+				Evaluation of Previous Step: ${event.reflection.evaluation_previous_goal}
+				Memory: ${event.reflection.memory}
+				Next Goal: ${event.reflection.next_goal}
+				Action Results: ${event.action.output}
+				</step_${stepIndex}>
 			`;
-  });
+    } else if (event.type === "observation") {
+      prompt += `<sys>${event.content}</sys>
+`;
+    } else if (event.type === "user_takeover") {
+      prompt += `<sys>User took over control and made changes to the page.</sys>
+`;
+    }
+  }
   prompt += "</agent_history>\n\n";
   prompt += await __privateMethod(this, _PageAgent_instances, getBrowserState_fn).call(this);
   return trimLines(prompt);
@@ -660,45 +709,20 @@ onDone_fn = /* @__PURE__ */ __name(function(text, success = true) {
   __privateGet(this, _abortController).abort();
 }, "#onDone");
 getBrowserState_fn = /* @__PURE__ */ __name(async function() {
-  const pageUrl = await this.pageController.getCurrentUrl();
-  const pageTitle = await this.pageController.getPageTitle();
-  const pi = await this.pageController.getPageInfo();
-  const viewportExpansion = await this.pageController.getViewportExpansion();
-  await this.pageController.updateTree();
-  let simplifiedHTML = await this.pageController.getSimplifiedHTML();
+  const state = await this.pageController.getBrowserState();
+  let content = state.content;
   if (this.config.transformPageContent) {
-    simplifiedHTML = await this.config.transformPageContent(simplifiedHTML);
+    content = await this.config.transformPageContent(content);
   }
-  let prompt = trimLines(`<browser_state>
-			Current Page: [${pageTitle}](${pageUrl})
-
-			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
+  return trimLines(`<browser_state>
+			Current Page: [${state.title}](${state.url})
 
-			${viewportExpansion === -1 ? "Interactive elements from top layer of the current page (full page):" : "Interactive elements from top layer of the current page inside the viewport:"}
+			${state.header}
+			${content}
+			${state.footer}
 
+			</browser_state>
 		`);
-  const has_content_above = pi.pixels_above > 4;
-  if (has_content_above && viewportExpansion !== -1) {
-    prompt += `... ${pi.pixels_above} pixels above (${pi.pages_above.toFixed(1)} pages) - scroll to see more ...
-`;
-  } else {
-    prompt += `[Start of page]
-`;
-  }
-  prompt += simplifiedHTML;
-  prompt += `
-`;
-  const has_content_below = pi.pixels_below > 4;
-  if (has_content_below && viewportExpansion !== -1) {
-    prompt += `... ${pi.pixels_below} pixels below (${pi.pages_below.toFixed(1)} pages) - scroll to see more ...
-`;
-  } else {
-    prompt += `[End of page]
-`;
-  }
-  prompt += `</browser_state>
-`;
-  return prompt;
 }, "#getBrowserState");
 __name(_PageAgent, "PageAgent");
 let PageAgent = _PageAgent;