page-agent 0.0.2 → 0.0.3

package/README.md

@@ -1,7 +1,5 @@
 # PageAgent 🤖🪄
 
-> ⚠️ 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)
@@ -34,7 +32,11 @@ An in-page UI agent in javascript. Control web interfaces with natural language.
 
 ```html
 <!-- 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>
+<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
@@ -54,13 +56,13 @@ const DEMO_BASE_URL = 'https://hwcxiuzfylggtcktqgij.supabase.co/functions/v1/llm
 const DEMO_API_KEY = 'PAGE-AGENT-FREE-TESTING-RANDOM'
 
 const agent = new PageAgent({
-  modelName: DEMO_MODEL,
-  baseURL: DEMO_BASE_URL,
-  apiKey: DEMO_API_KEY,
-  language: 'en-US'
+	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
@@ -104,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

@@ -27,9 +27,9 @@ 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;
@@ -3333,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());
@@ -3352,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 */
@@ -3362,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?
@@ -3370,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();
@@ -3385,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);
@@ -3428,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();
@@ -3469,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();
@@ -3503,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");
@@ -3668,6 +3694,7 @@ updateTree_fn = /* @__PURE__ */ __name(function() {
 __name(_PageAgent, "PageAgent");
 let PageAgent = _PageAgent;
 export {
-  PageAgent
+  PageAgent,
+  tool
 };
 //# sourceMappingURL=page-agent.js.map