page-agent 0.0.1 → 0.0.3

package/README.md

@@ -1,7 +1,5 @@
 # PageAgent 🤖🪄
 
-> Unfinished Project. See [**Roadmap**](./ROADMAP.md)
-
 ![banner](https://img.alicdn.com/imgextra/i1/O1CN01RY0Wvh26ATVeDIX7v_!!6000000007621-0-tps-1672-512.jpg)
 
 [![npm version](https://badge.fury.io/js/page-agent.svg)](https://badge.fury.io/js/page-agent) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/) [![Downloads](https://img.shields.io/npm/dt/page-agent.svg)](https://www.npmjs.com/package/page-agent) [![Bundle Size](https://img.shields.io/bundlephobia/minzip/page-agent)](https://bundlephobia.com/package/page-agent) [![GitHub stars](https://img.shields.io/github/stars/alibaba/page-agent.svg)](https://github.com/alibaba/page-agent)
@@ -32,11 +30,13 @@ An in-page UI agent in javascript. Control web interfaces with natural language.
 
 ### CDN Integration
 
-> **TODO**: CDN endpoint to be determined.
-
 ```html
-<!-- CDN script tag - URL to be updated -->
-<script src="TODO-CDN-URL"></script>
+<!-- temporary CDN URL. May change in the future -->
+<script
+	src="https://hwcxiuzfylggtcktqgij.supabase.co/storage/v1/object/public/demo-public/v0.0.2/page-agent.js"
+	crossorigin="true"
+	type="text/javascript"
+></script>
 ```
 
 ### NPM Installation
@@ -48,13 +48,21 @@ npm install page-agent
 ```javascript
 import { PageAgent } from 'page-agent'
 
+// test server
+// @note: rate limit. prompt limit. Origin limit. May change anytime. Use your own llm!
+// @note Using official DeepSeek-chat(3.2). Go to DeepSeek website for privacy policy.
+const DEMO_MODEL = 'PAGE-AGENT-FREE-TESTING-RANDOM'
+const DEMO_BASE_URL = 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy'
+const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
+
 const agent = new PageAgent({
-  modelName: 'gpt-4.1-mini',
-  baseURL: 'xxxx',
-  apiKey: 'xxxx'
+	modelName: DEMO_MODEL,
+	baseURL: DEMO_BASE_URL,
+	apiKey: DEMO_API_KEY,
+	language: 'en-US',
 })
 
-await agent.execute("Click the login button")
+await agent.execute('Click the login button')
 ```
 
 ## 🏗️ Structure
@@ -91,7 +99,6 @@ Please read our [Code of Conduct](CODE_OF_CONDUCT.md) and [Contributing Guide](C
 This project builds upon the excellent work of:
 
 - **[browser-use](https://github.com/browser-use/browser-use)**
-- **[ai-sdk](https://ai-sdk.dev/)**
 
 PageAgent is designed for **client-side web enhancement**, not server-side automation.
 
@@ -99,9 +106,8 @@ PageAgent is designed for **client-side web enhancement**, not server-side autom
 
 MIT License - see the [LICENSE](LICENSE) file for details.
 
-
 ```
-DOM processing components and prompt are derived from browser-use: 
+DOM processing components and prompt are derived from browser-use:
 
 Browser Use
 Copyright (c) 2024 Gregor Zunic

package/dist/lib/PageAgent.d.ts

@@ -7,6 +7,61 @@ export declare interface AgentBrain {
     next_goal: string;
 }
 
+declare interface AgentConfig {
+    language?: SupportedLanguage;
+    /**
+     * Custom tools to extend PageAgent capabilities
+     * @experimental
+     * @note You can also override or remove internal tools by using the same name.
+     * @see [tools](../tools/index.ts)
+     *
+     * @example
+     * // override internal tool
+     * import { tool } from 'page-agent'
+     * const customTools = {
+     * ask_user: tool({
+     * 	description:
+     * 		'Ask the user or parent model a question and wait for their answer. Use this if you need more information or clarification.',
+     * 	inputSchema: zod.object({
+     * 		question: zod.string(),
+     * 	}),
+     * 	execute: async function (this: PageAgent, input) {
+     * 		const answer = await do_some_thing(input.question)
+     * 		return "✅ Received user answer: " + answer
+     * 	},
+     * })
+     * }
+     *
+     * @example
+     * // remove internal tool
+     * const customTools = {
+     * 	ask_user: null // never ask user questions
+     * }
+     */
+    customTools?: Record<string, PageAgentTool | null>;
+    onBeforeStep?: (this: PageAgent, stepCnt: number) => Promise<void> | void;
+    onAfterStep?: (this: PageAgent, stepCnt: number, history: AgentHistory[]) => Promise<void> | void;
+    onBeforeTask?: (this: PageAgent) => Promise<void> | void;
+    onAfterTask?: (this: PageAgent, result: ExecutionResult) => Promise<void> | void;
+    /**
+     * @note this hook can block the disposal process
+     * @note when dispose caused by page unload, reason will be 'PAGE_UNLOADING'. this method CANNOT block unloading. async operations may be cut.
+     */
+    onDispose?: (this: PageAgent, reason?: string) => void;
+    /**
+     * TODO: @unimplemented
+     * hook when action causes a new page to be opened
+     * @note PageAgent will try to detect new pages and decide if it's caused by an action. But not very reliable.
+     */
+    onNewPageOpen?: (this: PageAgent, url: string) => Promise<void> | void;
+    /**
+     * TODO: @unimplemented
+     * try to navigate to a new page instead of opening a new tab/window.
+     * @note will unload the current page when a action tries to open a new page. so that things keep in the same tab/window.
+     */
+    experimentalPreventNewPage?: boolean;
+}
+
 export declare interface AgentHistory {
     brain: AgentBrain;
     action: {
@@ -303,9 +358,11 @@ export declare class PageAgent extends EventTarget {
     bus: EventBus;
     i18n: I18n;
     panel: Panel;
+    tools: typeof tools;
     paused: boolean;
     disposed: boolean;
     task: string;
+    taskId: string;
     /** Corresponds to eval_page in browser-use */
     flatTree: FlatDomTree | null;
     /**
@@ -319,8 +376,6 @@ export declare class PageAgent extends EventTarget {
     simplifiedHTML: string;
     /** last time the tree was updated */
     lastTimeUpdate: number;
-    /** Corresponds to actions in browser-use */
-    tools: Map<string, PageAgentTool<any>>;
     /** Fullscreen mask */
     mask: SimulatorMask;
     /** History records */
@@ -330,10 +385,10 @@ export declare class PageAgent extends EventTarget {
      * @todo maybe return something?
      */
     execute(task: string): Promise<ExecutionResult>;
-    dispose(): void;
+    dispose(reason?: string): void;
 }
 
-export declare type PageAgentConfig = LLMConfig & DomConfig & UIConfig;
+export declare type PageAgentConfig = LLMConfig & AgentConfig & DomConfig;
 
 /**
  * Event mapping definitions
@@ -363,7 +418,7 @@ declare interface PageAgentEventMap {
 /**
  * Internal tool definition that has access to PageAgent `this` context
  */
-declare interface PageAgentTool<TParams = any> {
+export declare interface PageAgentTool<TParams = any> {
     description: string;
     inputSchema: z.ZodType<TParams>;
     execute: (this: PageAgent, args: TParams) => Promise<string>;
@@ -422,14 +477,18 @@ declare interface TextDomNode {
     [key: string]: unknown;
 }
 
+export declare function tool<TParams>(options: PageAgentTool<TParams>): PageAgentTool<TParams>;
+
+/**
+ * Internal tools for PageAgent.
+ * Note: Using any to allow different parameter types for each tool
+ */
+declare const tools: Map<string, PageAgentTool<any>>;
+
 declare type TranslationKey = NestedKeyOf<TranslationSchema>;
 
 declare type TranslationParams = Record<string, string | number>;
 
 declare type TranslationSchema = DeepStringify<typeof enUS>;
 
-declare interface UIConfig {
-    language?: SupportedLanguage;
-}
-
 export { }

package/dist/lib/page-agent.js

@@ -22,14 +22,14 @@ 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 _bus, _wrapper, _indicator, _statusText, _historySection, _expandButton, _pauseButton, _stopButton, _inputSection, _taskInput, _bus2, _state, _isExpanded, _pageAgent, _userAnswerResolver, _isWaitingForUserAnswer, _Panel_instances, update_fn, show_fn, hide_fn, reset_fn, togglePause_fn, updatePauseButton_fn, stopAgent_fn, submitTask_fn, handleUserAnswer_fn, showInputArea_fn, hideInputArea_fn, shouldShowInputArea_fn, createWrapper_fn, setupEventListeners_fn, toggle_fn, expand_fn, collapse_fn, animateTextChange_fn, updateStatusIndicator_fn, updateHistory_fn, scrollToBottom_fn, createHistoryItem_fn, _cursor, _currentCursorX, _currentCursorY, _targetCursorX, _targetCursorY, _SimulatorMask_instances, createCursor_fn, moveCursorToTarget_fn, _llm, _totalWaitTime, _abortController, _PageAgent_instances, packMacroTool_fn, getSystemPrompt_fn, assembleUserPrompt_fn, onDone_fn, getBrowserState_fn, updateTree_fn;
+var _bus, _wrapper, _indicator, _statusText, _historySection, _expandButton, _pauseButton, _stopButton, _inputSection, _taskInput, _bus2, _state, _isExpanded, _pageAgent, _userAnswerResolver, _isWaitingForUserAnswer, _headerUpdateTimer, _pendingHeaderText, _isAnimating, _Panel_instances, update_fn, show_fn, hide_fn, reset_fn, togglePause_fn, updatePauseButton_fn, stopAgent_fn, submitTask_fn, handleUserAnswer_fn, showInputArea_fn, hideInputArea_fn, shouldShowInputArea_fn, createWrapper_fn, setupEventListeners_fn, toggle_fn, expand_fn, collapse_fn, startHeaderUpdateLoop_fn, stopHeaderUpdateLoop_fn, checkAndUpdateHeader_fn, animateTextChange_fn, updateStatusIndicator_fn, updateHistory_fn, scrollToBottom_fn, createHistoryItem_fn, _cursor, _currentCursorX, _currentCursorY, _targetCursorX, _targetCursorY, _SimulatorMask_instances, createCursor_fn, moveCursorToTarget_fn, _llm, _totalWaitTime, _abortController, _PageAgent_instances, packMacroTool_fn, getSystemPrompt_fn, assembleUserPrompt_fn, onDone_fn, getBrowserState_fn, updateTree_fn;
 import chalk from "chalk";
 import zod, { z } from "zod";
 import { Motion } from "ai-motion";
 const VIEWPORT_EXPANSION = -1;
-const DEFAULT_MODEL_NAME = "gpt-41-mini-0414-global";
-const DEFAULT_API_KEY = "not-needed";
-const DEFAULT_BASE_URL = "http://localhost:3000/api/agent";
+const DEFAULT_MODEL_NAME = "PAGE-AGENT-FREE-TESTING-RANDOM";
+const DEFAULT_API_KEY = "PAGE-AGENT-FREE-TESTING-RANDOM";
+const DEFAULT_BASE_URL = "https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm-testing-proxy";
 const LLM_MAX_RETRIES = 2;
 const MAX_STEPS = 20;
 const DEFAULT_TEMPERATURE = 0.7;
@@ -2626,6 +2626,9 @@ const _Panel = class _Panel {
     __privateAdd(this, _pageAgent);
     __privateAdd(this, _userAnswerResolver, null);
     __privateAdd(this, _isWaitingForUserAnswer, false);
+    __privateAdd(this, _headerUpdateTimer, null);
+    __privateAdd(this, _pendingHeaderText, null);
+    __privateAdd(this, _isAnimating, false);
     __privateSet(this, _pageAgent, pageAgent);
     __privateSet(this, _bus2, pageAgent.bus);
     __privateSet(this, _wrapper, __privateMethod(this, _Panel_instances, createWrapper_fn).call(this));
@@ -2638,6 +2641,7 @@ const _Panel = class _Panel {
     __privateSet(this, _inputSection, __privateGet(this, _wrapper).querySelector(`.${styles$1.inputSectionWrapper}`));
     __privateSet(this, _taskInput, __privateGet(this, _wrapper).querySelector(`.${styles$1.taskInput}`));
     __privateMethod(this, _Panel_instances, setupEventListeners_fn).call(this);
+    __privateMethod(this, _Panel_instances, startHeaderUpdateLoop_fn).call(this);
     __privateMethod(this, _Panel_instances, showInputArea_fn).call(this);
     __privateGet(this, _bus2).on("panel:show", () => __privateMethod(this, _Panel_instances, show_fn).call(this));
     __privateGet(this, _bus2).on("panel:hide", () => __privateMethod(this, _Panel_instances, hide_fn).call(this));
@@ -2671,6 +2675,7 @@ const _Panel = class _Panel {
    */
   dispose() {
     __privateSet(this, _isWaitingForUserAnswer, false);
+    __privateMethod(this, _Panel_instances, stopHeaderUpdateLoop_fn).call(this);
     this.wrapper.remove();
   }
 };
@@ -2689,13 +2694,17 @@ _isExpanded = new WeakMap();
 _pageAgent = new WeakMap();
 _userAnswerResolver = new WeakMap();
 _isWaitingForUserAnswer = new WeakMap();
+_headerUpdateTimer = new WeakMap();
+_pendingHeaderText = new WeakMap();
+_isAnimating = new WeakMap();
 _Panel_instances = new WeakSet();
-update_fn = /* @__PURE__ */ __name(async function(stepData) {
+/**
+ * Update status
+ */
+update_fn = /* @__PURE__ */ __name(function(stepData) {
   const step = __privateGet(this, _state).addStep(stepData);
   const headerText = truncate(step.displayText, 20);
-  if (__privateGet(this, _statusText).textContent !== headerText) {
-    await __privateMethod(this, _Panel_instances, animateTextChange_fn).call(this, headerText);
-  }
+  __privateSet(this, _pendingHeaderText, headerText);
   __privateMethod(this, _Panel_instances, updateStatusIndicator_fn).call(this, step.type);
   __privateMethod(this, _Panel_instances, updateHistory_fn).call(this);
   if (step.type === "completed" || step.type === "error") {
@@ -2933,19 +2942,53 @@ collapse_fn = /* @__PURE__ */ __name(function() {
   this.wrapper.classList.add(styles$1.collapsed);
   __privateGet(this, _expandButton).textContent = "▼";
 }, "#collapse");
-animateTextChange_fn = /* @__PURE__ */ __name(async function(newText) {
-  return new Promise((resolve) => {
-    __privateGet(this, _statusText).classList.add(styles$1.fadeOut);
+/**
+ * Start periodic header update loop
+ */
+startHeaderUpdateLoop_fn = /* @__PURE__ */ __name(function() {
+  __privateSet(this, _headerUpdateTimer, setInterval(() => {
+    __privateMethod(this, _Panel_instances, checkAndUpdateHeader_fn).call(this);
+  }, 450));
+}, "#startHeaderUpdateLoop");
+/**
+ * Stop periodic header update loop
+ */
+stopHeaderUpdateLoop_fn = /* @__PURE__ */ __name(function() {
+  if (__privateGet(this, _headerUpdateTimer)) {
+    clearInterval(__privateGet(this, _headerUpdateTimer));
+    __privateSet(this, _headerUpdateTimer, null);
+  }
+}, "#stopHeaderUpdateLoop");
+/**
+ * Check if header needs update and trigger animation if not currently animating
+ */
+checkAndUpdateHeader_fn = /* @__PURE__ */ __name(function() {
+  if (!__privateGet(this, _pendingHeaderText) || __privateGet(this, _isAnimating)) {
+    return;
+  }
+  if (__privateGet(this, _statusText).textContent === __privateGet(this, _pendingHeaderText)) {
+    __privateSet(this, _pendingHeaderText, null);
+    return;
+  }
+  const textToShow = __privateGet(this, _pendingHeaderText);
+  __privateSet(this, _pendingHeaderText, null);
+  __privateMethod(this, _Panel_instances, animateTextChange_fn).call(this, textToShow);
+}, "#checkAndUpdateHeader");
+/**
+ * Animate text change with fade out/in effect
+ */
+animateTextChange_fn = /* @__PURE__ */ __name(function(newText) {
+  __privateSet(this, _isAnimating, true);
+  __privateGet(this, _statusText).classList.add(styles$1.fadeOut);
+  setTimeout(() => {
+    __privateGet(this, _statusText).textContent = newText;
+    __privateGet(this, _statusText).classList.remove(styles$1.fadeOut);
+    __privateGet(this, _statusText).classList.add(styles$1.fadeIn);
     setTimeout(() => {
-      __privateGet(this, _statusText).textContent = newText;
-      __privateGet(this, _statusText).classList.remove(styles$1.fadeOut);
-      __privateGet(this, _statusText).classList.add(styles$1.fadeIn);
-      setTimeout(() => {
-        __privateGet(this, _statusText).classList.remove(styles$1.fadeIn);
-        resolve();
-      }, 300);
-    }, 150);
-  });
+      __privateGet(this, _statusText).classList.remove(styles$1.fadeIn);
+      __privateSet(this, _isAnimating, false);
+    }, 300);
+  }, 150);
 }, "#animateTextChange");
 updateStatusIndicator_fn = /* @__PURE__ */ __name(function(type) {
   __privateGet(this, _indicator).className = styles$1.indicator;
@@ -3290,9 +3333,11 @@ const _PageAgent = class _PageAgent extends EventTarget {
     __publicField(this, "bus", getEventBus(this.id));
     __publicField(this, "i18n");
     __publicField(this, "panel");
+    __publicField(this, "tools");
     __publicField(this, "paused", false);
     __publicField(this, "disposed", false);
     __publicField(this, "task", "");
+    __publicField(this, "taskId", "");
     __privateAdd(this, _llm);
     __privateAdd(this, _totalWaitTime, 0);
     __privateAdd(this, _abortController, new AbortController());
@@ -3309,8 +3354,6 @@ const _PageAgent = class _PageAgent extends EventTarget {
     __publicField(this, "simplifiedHTML", "<EMPTY>");
     /** last time the tree was updated */
     __publicField(this, "lastTimeUpdate", 0);
-    /** Corresponds to actions in browser-use */
-    __publicField(this, "tools", new Map(tools));
     /** Fullscreen mask */
     __publicField(this, "mask", new SimulatorMask());
     /** History records */
@@ -3319,7 +3362,20 @@ const _PageAgent = class _PageAgent extends EventTarget {
     __privateSet(this, _llm, new LLM(this.config, this.id));
     this.i18n = new I18n(this.config.language);
     this.panel = new Panel(this);
+    this.tools = new Map(tools);
+    if (this.config.customTools) {
+      for (const [name, tool2] of Object.entries(this.config.customTools)) {
+        if (tool2 === null) {
+          this.tools.delete(name);
+          continue;
+        }
+        this.tools.set(name, tool2);
+      }
+    }
     patchReact();
+    window.addEventListener("beforeunload", (e) => {
+      if (!this.disposed) this.dispose("PAGE_UNLOADING");
+    });
   }
   /**
    * @todo maybe return something?
@@ -3327,12 +3383,18 @@ const _PageAgent = class _PageAgent extends EventTarget {
   async execute(task) {
     if (!task) throw new Error("Task is required");
     this.task = task;
+    this.taskId = uid();
+    const onBeforeStep = this.config.onBeforeStep || (() => void 0);
+    const onAfterStep = this.config.onAfterStep || (() => void 0);
+    const onBeforeTask = this.config.onBeforeTask || (() => void 0);
+    const onAfterTask = this.config.onAfterTask || (() => void 0);
+    await onBeforeTask.call(this);
     this.mask.show();
     this.bus.emit("panel:show");
     this.bus.emit("panel:reset");
     this.bus.emit("panel:update", {
       type: "input",
-      displayText: task
+      displayText: this.task
     });
     if (__privateGet(this, _abortController)) {
       __privateGet(this, _abortController).abort();
@@ -3342,6 +3404,7 @@ const _PageAgent = class _PageAgent extends EventTarget {
     try {
       let step = 0;
       while (true) {
+        await onBeforeStep.call(this, step);
         console.group(`step: ${step + 1}`);
         if (__privateGet(this, _abortController).signal.aborted) throw new Error("AbortError");
         await waitUntil(() => !this.paused);
@@ -3385,38 +3448,45 @@ const _PageAgent = class _PageAgent extends EventTarget {
         });
         console.log(chalk.green("Step finished:"), actionName);
         console.groupEnd();
+        await onAfterStep.call(this, step, this.history);
         step++;
         if (step > MAX_STEPS) {
           __privateMethod(this, _PageAgent_instances, onDone_fn).call(this, "Step count exceeded maximum limit", false);
-          return {
+          const result2 = {
             success: false,
             data: "Step count exceeded maximum limit",
             history: this.history
           };
+          await onAfterTask.call(this, result2);
+          return result2;
         }
         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);
           __privateMethod(this, _PageAgent_instances, onDone_fn).call(this, text, success);
-          return {
+          const result2 = {
             success,
             data: text,
             history: this.history
           };
+          await onAfterTask.call(this, result2);
+          return result2;
         }
       }
     } catch (error2) {
       console.error("Task failed", error2);
       __privateMethod(this, _PageAgent_instances, onDone_fn).call(this, String(error2), false);
-      return {
+      const result = {
         success: false,
         data: String(error2),
         history: this.history
       };
+      await onAfterTask.call(this, result);
+      return result;
     }
   }
-  dispose() {
+  dispose(reason) {
     console.log("Disposing PageAgent...");
     this.disposed = true;
     cleanUpHighlights();
@@ -3426,7 +3496,8 @@ const _PageAgent = class _PageAgent extends EventTarget {
     this.panel.dispose();
     this.mask.dispose();
     this.history = [];
-    __privateGet(this, _abortController).abort("PageAgent disposed");
+    __privateGet(this, _abortController).abort(reason ?? "PageAgent disposed");
+    this.config.onDispose?.call(this, reason);
   }
 };
 _llm = new WeakMap();
@@ -3460,8 +3531,6 @@ packMacroTool_fn = /* @__PURE__ */ __name(function() {
     action: actionSchema
   });
   return {
-    // name: MACRO_TOOL_NAME,
-    // description: 'Execute agent action', // @todo remote
     inputSchema: macroToolSchema,
     execute: /* @__PURE__ */ __name(async (input2) => {
       if (__privateGet(this, _abortController).signal.aborted) throw new Error("AbortError");
@@ -3625,6 +3694,7 @@ updateTree_fn = /* @__PURE__ */ __name(function() {
 __name(_PageAgent, "PageAgent");
 let PageAgent = _PageAgent;
 export {
-  PageAgent
+  PageAgent,
+  tool
 };
 //# sourceMappingURL=page-agent.js.map