page-agent 0.2.5 → 0.3.0-beta.2

package/README.md

@@ -37,7 +37,7 @@ Fastest way to try PageAgent:
 
 ```html
 <script
-    src="https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.demo.js"
+    src="https://cdn.jsdelivr.net/npm/page-agent/dist/iife/page-agent.demo.js"
     crossorigin="true"
 ></script>
 ```
@@ -46,8 +46,8 @@ Fastest way to try PageAgent:
 
 | Mirrors | URL                                                                                 |
 | ------- | ----------------------------------------------------------------------------------- |
-| Global  | https://cdn.jsdelivr.net/npm/@page-agent/cdn/dist/page-agent.demo.js                |
-| China   | https://registry.npmmirror.com/@page-agent/cdn/latest/files/dist/page-agent.demo.js |
+| Global  | https://cdn.jsdelivr.net/npm/page-agent/dist/iife/page-agent.demo.js                |
+| China   | https://registry.npmmirror.com/page-agent/latest/files/dist/iife/page-agent.demo.js |
 
 ### NPM Installation
 
@@ -68,19 +68,17 @@ const agent = new PageAgent({
 await agent.execute('Click the login button')
 ```
 
-For environments where NPM is not available. We do offer a IIFE build via CDN. [@see CDN Usage](https://alibaba.github.io/page-agent/#/docs/integration/cdn-setup)
-
 ## 🏗️ Structure
 
 PageAgent adopts a simplified monorepo structure:
 
 ```
 packages/
-├── page-agent/          # AI agent (npm: page-agent)
+├── page-agent/          # AI agent and demo(npm: page-agent)
+├── core/                # Agent core logic without UI(npm: @page-agent/core)
 ├── llms/                # LLM client (npm: @page-agent/llms)
 ├── page-controller/     # DOM operations & Visual Mask (npm: @page-agent/page-controller)
 ├── ui/                  # Panel & i18n (npm: @page-agent/ui)
-├── cdn/                 # CDN IIFE builds (npm: @page-agent/cdn)
 └── website/             # Demo & Documentation site
 ```
 

package/dist/esm/PageAgent.d.ts

@@ -1,235 +1,12 @@
-import { LLMConfig } from '@page-agent/llms';
-import { PageController } from '@page-agent/page-controller';
-import { PageControllerConfig } from '@page-agent/page-controller';
+import { PageAgentConfig } from '@page-agent/core';
+import { PageAgentCore } from '@page-agent/core';
 import { Panel } from '@page-agent/ui';
-import { SupportedLanguage } from '@page-agent/ui';
-import { z } from 'zod';
 
-declare interface AgentConfig {
-    language?: SupportedLanguage;
-    /**
-     * Whether to prompt for next task after task completion
-     * @default true
-     */
-    promptForNextTask?: boolean;
-    /**
-     * Enable the UI panel for visual feedback and user interaction
-     * When disabled, the panel will not be created and all UI operations will be skipped.
-     * Useful for automated testing or when integrating PageAgent as a library.
-     * @default true
-     */
-    enablePanel?: boolean;
-    /**
-     * Enable the ask_user tool for agent to ask questions
-     * When disabled, the agent cannot ask user questions during execution.
-     * @default true
-     */
-    enableAskUser?: boolean;
-    /**
-     * 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>;
-    /**
-     * Instructions to guide the agent's behavior
-     */
-    instructions?: {
-        /**
-         * Global system-level instructions, applied to all tasks
-         */
-        system?: string;
-        /**
-         * Dynamic page-level instructions callback
-         * Called before each step to get instructions for the current page
-         * @param url - Current page URL (window.location.href)
-         * @returns Instructions string, or undefined/null to skip
-         */
-        getPageInstructions?: (url: string) => string | undefined | null;
-    };
-    onBeforeStep?: (this: PageAgent, stepCnt: number) => 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;
-    /**
-     * @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.
-     * @todo remove `this` binding, pass agent as explicit parameter instead
-     */
-    onDispose?: (this: PageAgent, reason?: string) => void;
-    /**
-     * @experimental
-     * Enable the experimental script execution tool that allows executing generated JavaScript code on the page.
-     * @note Can cause unpredictable side effects.
-     * @note May bypass some safe guards and data-masking mechanisms.
-     */
-    experimentalScriptExecutionTool?: boolean;
-    /**
-     * Transform page content before sending to LLM.
-     * Called after DOM extraction and simplification, before LLM invocation.
-     * Use cases: inspect extraction results, modify page info, mask sensitive data.
-     *
-     * @param content - Simplified page content that will be sent to LLM
-     * @returns Transformed content
-     *
-     * @example
-     * // Mask phone numbers
-     * transformPageContent: async (content) => {
-     *   return content.replace(/1[3-9]\d{9}/g, '***********')
-     * }
-     */
-    transformPageContent?: (content: string) => Promise<string> | string;
-}
-
-/**
- * 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?
- * - memory: Key information to remember for future steps
- * - next_goal: What should be accomplished in the next action?
- */
-export declare interface AgentReflection {
-    evaluation_previous_goal: string;
-    memory: string;
-    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: HistoryEvent[];
-}
-
-/**
- * Union type for all history events
- */
-export declare type HistoryEvent = AgentStep | ObservationEvent | UserTakeoverEvent;
-
-/**
- * MacroTool input structure
- *
- * This is the core abstraction that enforces the "reflection-before-action" mental model.
- * Before executing any action, the LLM must output its reasoning state.
- */
-export declare interface MacroToolInput extends Partial<AgentReflection> {
-    action: Record<string, any>;
-}
-
-/**
- * MacroTool output structure
- */
-export declare interface MacroToolResult {
-    input: MacroToolInput;
-    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;
-    id: string;
-    panel: Panel | null;
-    tools: typeof tools;
-    disposed: boolean;
-    task: string;
-    taskId: string;
-    /** PageController for DOM operations */
-    pageController: PageController;
-    /** 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 events */
-    history: HistoryEvent[];
+export declare class PageAgent extends PageAgentCore {
+    panel: Panel;
     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;
-}
-
-export declare type PageAgentConfig = LLMConfig & AgentConfig & PageControllerConfig;
-
-/**
- * Internal tool definition that has access to PageAgent `this` context
- */
-export declare interface PageAgentTool<TParams = any> {
-    description: string;
-    inputSchema: z.ZodType<TParams>;
-    execute: (this: PageAgent, args: TParams) => Promise<string>;
 }
 
-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>>;
-
-/**
- * User takeover event
- */
-export declare interface UserTakeoverEvent {
-    type: 'user_takeover';
-}
+export { PageAgentConfig }
 
 export { }