feat: create llms package and mv files

.vscode/settings.json

@@ -1,6 +1,13 @@
 {
 	"editor.fontLigatures": true,
-	"cSpell.words": ["HITL", "innerhtml", "opensource", "retryable", "wouter"],
+	"cSpell.words": [
+		"HITL",
+		"innerhtml",
+		"llms",
+		"opensource",
+		"retryable",
+		"wouter"
+	],
 	"markdownlint.config": {
 		// "comment": "Relaxed rules",
 		"default": true,

package-lock.json

@@ -11,6 +11,7 @@
 			"workspaces": [
 				"packages/page-controller",
 				"packages/ui",
+				"packages/llms",
 				"packages/page-agent",
 				"packages/website"
 			],
@@ -1558,6 +1559,10 @@
 				"url": "https://github.com/sponsors/epoberezkin"
 			}
 		},
+		"node_modules/@page-agent/llms": {
+			"resolved": "packages/llms",
+			"link": true
+		},
 		"node_modules/@page-agent/page-controller": {
 			"resolved": "packages/page-controller",
 			"link": true
@@ -7183,10 +7188,20 @@
 				"zod": "^3.25.0 || ^4.0.0"
 			}
 		},
+		"packages/llms": {
+			"name": "@page-agent/llms",
+			"version": "0.0.13",
+			"license": "MIT",
+			"dependencies": {
+				"chalk": "^5.6.2",
+				"zod": "^4.2.0"
+			}
+		},
 		"packages/page-agent": {
 			"version": "0.0.13",
 			"license": "MIT",
 			"dependencies": {
+				"@page-agent/llms": "0.0.13",
 				"@page-agent/page-controller": "0.0.13",
 				"@page-agent/ui": "0.0.13",
 				"chalk": "^5.6.2",

package.json

@@ -6,6 +6,7 @@
 	"workspaces": [
 		"packages/page-controller",
 		"packages/ui",
+		"packages/llms",
 		"packages/page-agent",
 		"packages/website"
 	],

packages/llms/README.md

@@ -0,0 +1,82 @@
+# @page-agent/llms
+
+LLM client with a **reflection-before-action** mental model for page-agent.
+
+## Why This Package Exists
+
+The LLM module and the agent logic are inherently coupled. This package exists not to decouple them, but to **define the interface contract** between the LLM and the agent.
+
+The core abstraction is the `MacroToolInput` — a structured output format that **forces the model to reflect before acting**.
+
+## The Reflection-Before-Action Model
+
+Every tool call must first output its reasoning state before the actual action:
+
+```typescript
+interface MacroToolInput {
+  // Reflection (mandatory before any action)
+  evaluation_previous_goal?: string  // How well did the previous action work?
+  memory?: string                     // Key information to remember
+  next_goal?: string                  // What to accomplish next
+
+  // Action (the actual operation)
+  action: Record<string, any>
+}
+```
+
+This design ensures that:
+
+1. **The model evaluates its previous action** before deciding the next step
+2. **Working memory is explicitly maintained** across conversation turns
+3. **Goals are clearly stated**, making the agent's reasoning transparent and debuggable
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│                    PageAgent                        │
+│  - Maintains agent state and history                │
+│  - Orchestrates tool execution                      │
+│  - Assembles prompts with browser state             │
+└─────────────────────┬───────────────────────────────┘
+                      │ uses
+                      ▼
+┌─────────────────────────────────────────────────────┐
+│                 @page-agent/llms                    │
+│  - Defines MacroToolInput contract                  │
+│  - Handles LLM API calls                            │
+│  - Parses and validates structured output           │
+│  - Executes tool calls                              │
+└─────────────────────────────────────────────────────┘
+```
+
+## Key Components
+
+| Export | Description |
+|--------|-------------|
+| `LLM` | Main LLM client class with retry logic |
+| `MacroToolInput` | The reflection-before-action input schema |
+| `AgentBrain` | Agent's thinking state (eval, memory, goal) |
+| `LLMConfig` | Configuration for LLM connection |
+| `parseLLMConfig` | Parse and apply defaults to config |
+
+## Usage
+
+This package is used internally by `page-agent`. Direct usage:
+
+```typescript
+import { LLM, type MacroToolInput } from '@page-agent/llms'
+
+const llm = new LLM({
+  model: 'gpt-4o',
+  apiKey: 'your-api-key',
+  baseURL: 'https://api.openai.com/v1',
+})
+
+const result = await llm.invoke(messages, tools, abortSignal)
+```
+
+## License
+
+MIT
+

packages/llms/package.json

@@ -0,0 +1,44 @@
+{
+	"name": "@page-agent/llms",
+	"version": "0.0.13",
+	"type": "module",
+	"main": "./dist/lib/page-agent-llms.js",
+	"module": "./dist/lib/page-agent-llms.js",
+	"types": "./dist/lib/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/lib/index.d.ts",
+			"import": "./dist/lib/page-agent-llms.js",
+			"default": "./dist/lib/page-agent-llms.js"
+		}
+	},
+	"files": [
+		"dist/"
+	],
+	"description": "LLM client with reflection-before-action mental model for page-agent",
+	"keywords": [
+		"page-agent",
+		"llm",
+		"openai",
+		"tool-calling",
+		"agent"
+	],
+	"author": "Simon<gaomeng1900>",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/alibaba/page-agent.git",
+		"directory": "packages/llms"
+	},
+	"homepage": "https://alibaba.github.io/page-agent/",
+	"scripts": {
+		"build": "vite build",
+		"prepublishOnly": "node -e \"const fs=require('fs');['LICENSE'].forEach(f=>fs.copyFileSync('../../'+f,f))\"",
+		"postpublish": "node -e \"['LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
+	},
+	"dependencies": {
+		"chalk": "^5.6.2",
+		"zod": "^4.2.0"
+	}
+}
+

packages/llms/tsconfig.dts.json

@@ -0,0 +1,10 @@
+{
+	"extends": "./tsconfig.json",
+	"compilerOptions": {
+		// @workaround DTS bug
+		// dts do not work with monorepo path mapping
+		// disable path mapping for it
+		"paths": {}
+	}
+}
+

packages/llms/tsconfig.json

@@ -0,0 +1,13 @@
+{
+	"extends": "../../tsconfig.base.json",
+	"compilerOptions": {
+		"tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo",
+		"noEmit": false,
+		"allowImportingTsExtensions": false,
+		"baseUrl": ".",
+		"outDir": "dist"
+	},
+	"include": ["**/*.ts"],
+	"exclude": ["dist", "node_modules"]
+}
+

packages/llms/vite.config.js

@@ -0,0 +1,37 @@
+// @ts-check
+import chalk from 'chalk'
+import { dirname, resolve } from 'path'
+import dts from 'unplugin-dts/vite'
+import { fileURLToPath } from 'url'
+import { defineConfig } from 'vite'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+console.log(chalk.cyan(`📦 Building @page-agent/llms`))
+
+export default defineConfig({
+	clearScreen: false,
+	plugins: [dts({ tsconfigPath: './tsconfig.dts.json', bundleTypes: true })],
+	publicDir: false,
+	esbuild: {
+		keepNames: true,
+	},
+	build: {
+		lib: {
+			entry: resolve(__dirname, 'src/index.ts'),
+			name: 'PageAgentLLMs',
+			fileName: 'page-agent-llms',
+			formats: ['es'],
+		},
+		outDir: resolve(__dirname, 'dist', 'lib'),
+		rollupOptions: {
+			external: ['chalk', 'zod'],
+		},
+		minify: false,
+		sourcemap: true,
+	},
+	define: {
+		'process.env.NODE_ENV': '"production"',
+	},
+})
+

packages/page-agent/package.json

@@ -46,6 +46,7 @@
 	"dependencies": {
 		"chalk": "^5.6.2",
 		"zod": "^4.2.0",
+		"@page-agent/llms": "0.0.13",
 		"@page-agent/page-controller": "0.0.13",
 		"@page-agent/ui": "0.0.13"
 	}

packages/page-agent/tsconfig.json

@@ -8,6 +8,7 @@
 		"outDir": "dist",
 		"paths": {
 			//
+			"@page-agent/llms": ["../llms/src/index.ts"],
 			"@page-agent/page-controller": ["../page-controller/src/PageController.ts"],
 			"@page-agent/ui": ["../ui/src/index.ts"]
 		}
@@ -16,6 +17,7 @@
 	"exclude": ["dist", "node_modules"],
 	"references": [
 		//
+		{ "path": "../llms" },
 		{ "path": "../page-controller" },
 		{ "path": "../ui" }
 	]

packages/website/tsconfig.json

@@ -12,6 +12,7 @@
 
 			// Simplified monorepo solution (raw npm workspace with hoisting)
 			"page-agent": ["../page-agent/src/PageAgent.ts"],
+			"@page-agent/llms": ["../llms/src/index.ts"],
 			"@page-agent/page-controller": ["../page-controller/src/PageController.ts"],
 			"@page-agent/ui": ["../ui/src/index.ts"]
 		}
@@ -20,6 +21,7 @@
 	"exclude": ["dist", "node_modules"],
 	"references": [
 		//
+		{ "path": "../llms" },
 		{ "path": "../page-agent" },
 		{ "path": "../page-controller" },
 		{ "path": "../ui" }

packages/website/vite.config.js

@@ -22,6 +22,7 @@ export default defineConfig({
 			'@': resolve(__dirname, 'src'),
 
 			// Monorepo packages (always bundle local code instead of npm versions)
+			'@page-agent/llms': resolve(__dirname, '../llms/src/index.ts'),
 			'@page-agent/page-controller': resolve(__dirname, '../page-controller/src/PageController.ts'),
 			'@page-agent/ui': resolve(__dirname, '../ui/src/index.ts'),
 			'page-agent': resolve(__dirname, '../page-agent/src/PageAgent.ts'),

tsconfig.json

@@ -3,6 +3,7 @@
 	"references": [
 		{ "path": "./packages/page-controller" },
 		{ "path": "./packages/ui" },
+		{ "path": "./packages/llms" },
 		{ "path": "./packages/page-agent" },
 		{ "path": "./packages/website" }
 	],