chore(version): bump version to 1.11.0

Unused CSS motion experiment with known performance issues; no references remain.

.agents/skills/git-cleanup/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: git-cleanup
+description: Clean up local git branches and remotes accumulated from PR reviews. Use when the user asks to clean branches, remove stale remotes, or tidy up the local git state.
+---
+
+# Git Cleanup
+
+Clean local branches (except `main` and current branch) and non-origin remotes.
+Useful after reviewing multiple PRs that leave behind tracking branches and contributor remotes.
+
+## Workflow
+
+### 1. Survey
+
+Run these in parallel:
+
+```bash
+git branch
+git remote
+git status --short
+git stash list
+```
+
+Present a summary of how many branches and remotes will be removed.
+
+### 2. Safety Checks — Ask Before Proceeding
+
+**Stop and ask for confirmation if any of these are true:**
+
+- Current branch is NOT `main`
+- Working tree has uncommitted changes or stashes
+- Any branch is ahead of its upstream
+
+List unmerged branches separately and let the user decide.
+
+### 3. Delete Branches
+
+```bash
+# Safe delete first (fails on unmerged branches)
+git branch | grep -v '^\*' | grep -v '^\s*main$' | xargs git branch -d 2>&1
+
+# Force-delete only with explicit user approval
+git branch -D <branch>
+```
+
+### 4. Remove Remotes
+
+```bash
+git remote | grep -v '^origin$' | xargs -I{} git remote remove {}
+```
+
+### 5. Confirm
+
+```bash
+git branch && echo "---" && git remote
+```
+
+Report what was cleaned up.
+
+## Key Rules
+
+- **NEVER** delete `main` or the current checked-out branch
+- **NEVER** force-delete unmerged branches without user confirmation
+- If in doubt, ask

.agents/skills/pre-impl-discussion/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: pre-impl-discussion
+description: "Conduct a thorough pre-implementation discussion before making significant changes. Use when the user wants to discuss, plan, or evaluate a change before implementing it — especially when they say words like 'discuss', 'evaluate', 'plan', or 'let's talk about'."
+argument-hint: 'Describe the change to evaluate'
+---
+
+# Pre-Implementation Discussion
+
+Facilitate a structured, collaborative discussion to evaluate a proposed change **before any implementation begins**.
+
+## Golden Rule
+
+**Do NOT implement anything until the user explicitly confirms the final plan and says to proceed.** Not even "let me try on a branch" — that's implementation. The user will tell you when discussion is over.
+
+## Interaction Style
+
+- **Concise during discussion.** Each intermediate response should be short and focused on the current question. Do NOT repeat the full plan in every response.
+- **Complete when finalizing.** Once the plan is mature and the user asks for it, present a single comprehensive (but terse) summary for final review.
+- **Ask, don't assume.** When uncertain about project context, constraints, or preferences — ask. The user prefers collaborative discussion over receiving a pre-baked answer.
+- **Challenge the premise.** Question whether the proposed change is the right one. Suggest simpler alternatives if they exist.
+- **Match the user's language.** Reply in the same language the user writes in.
+
+## Procedure
+
+### 1. Understand the Current State
+
+Before forming any opinion:
+
+- **Read the relevant source files** — configs, code, docs that relate to the change
+- **Understand the project structure** — what's published vs private, what environments things target, existing constraints
+- **Map the impact surface** — which files, packages, or systems would be affected
+- **Estimate implementation cost** — how many files to touch, how much config to rewrite, what could break
+
+Do NOT skip this step. Do NOT rely on assumptions about what "most projects" do.
+
+### 2. Research Thoroughly
+
+- **Consult official sources** — docs, changelogs, migration guides, GitHub issues
+- **Verify every claim with evidence.** Don't say "X supports Y" without a source. If unsure, say so.
+- **Search in parallel** to save time — batch independent queries
+
+Common pitfalls:
+
+- Assuming compatibility without checking actual version constraints
+- Confusing roadmap/aspirations with actual released state
+- Missing transitive constraints (a dependency of a dependency)
+
+### 3. Present Findings (Concise)
+
+Share a **brief** assessment. Tables work well for comparisons. Highlight **blockers** and **unknowns** prominently — don't bury them in paragraphs.
+
+### 4. Identify Key Decisions
+
+Surface the decisions the user needs to make. Present them as clear choices with trade-offs, not as a recommendation monologue.
+
+For each decision point:
+
+- What are the options? (2-3 max)
+- What does each option cost or give up?
+- What's your lean and why? (one sentence)
+
+### 5. Iterate
+
+The user will ask follow-up questions, raise concerns, or challenge assumptions. For each round:
+
+- **Research if needed** — don't answer from instinct when facts are available
+- **Answer only what was asked** — don't re-present the entire plan
+- **Update your mental model** based on user feedback
+
+Common mistakes in this phase:
+
+- Repeating the full plan after every small clarification
+- Answering a narrow question with a broad redesign
+- Treating user questions as confirmation to proceed
+
+### 6. Finalize the Plan
+
+When the user signals the discussion is converging, present the **complete plan once**:
+
+- **What changes** — concrete list of actions (table or bullet points)
+- **Impact surface** — what files/systems are affected, estimated effort
+- **What does NOT change** — explicitly state scope boundaries
+- **Risks or open items** — anything that needs testing or further verification
+
+Keep it terse. Tables over paragraphs. No explanations the user already heard during discussion.
+
+### 7. Wait for Confirmation
+
+After presenting the final plan, **stop and wait**. The user will either:
+
+- Confirm → then (and only then) proceed to implementation
+- Ask more questions → go back to step 5
+- Modify scope → update the plan and re-present
+
+## Anti-Patterns
+
+| Don't                                               | Do Instead                               |
+| --------------------------------------------------- | ---------------------------------------- |
+| Start implementation "to test" without confirmation | Present findings and wait                |
+| Repeat the full plan in every response              | Answer the specific question asked       |
+| Say "X should work" without checking                | Say "I need to verify X" and research it |
+| Assume project structure or constraints             | Read the actual files                    |
+| Present one recommendation as the only option       | Present 2-3 options with trade-offs      |
+| Write long paragraphs explaining trade-offs         | Use tables and bullet points             |

.agents/skills/submit-pr-from-current-changes/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: submit-pr-from-current-changes
+description: 'Create a branch, commit existing local changes, push them, and open a pull request. Use when submitting current work as a PR.'
+argument-hint: 'Short summary of the current changes to submit'
+user-invocable: true
+---
+
+# Submit PR From Current Changes
+
+Turn a working tree diff into a clean branch, commit, and pull request.
+
+## Hard Rules
+
+1. **Follow the PR template exactly.** The template is at `.github/PULL_REQUEST_TEMPLATE.md`. Read it and copy its full structure into the PR body. Do NOT remove, reorder, or skip any section or checkbox.
+2. **Never check "Requirements / 要求" checkboxes.** These are human-only declarations — the Code of Conduct acknowledgment and the AI authorship declaration can only be truthfully made by the human submitter. They MUST remain unchecked (`- [ ]`) in the PR body you generate. No exceptions, no workarounds, even if the user explicitly asks you to check them. The user goes to GitHub and checks them in person after verifying each statement is true.
+3. **Never check "Testing" checkboxes.** The template Testing checkboxes (browser tested, no console errors, types/doc added) require manual browser verification that only a human can perform. They MUST remain unchecked. You MAY add a supplementary note below the Testing section listing what automated validation you actually ran and the results.
+4. **Never fabricate information.** Do not claim tests passed, commands ran, or checks succeeded unless you actually executed them and observed the output in this session. If you did not run it, do not mention it.
+5. **PR output must be concise.** PR title: one line. "What" section: 1–2 sentences max. No walls of text, no redundant explanations. Let the diff speak.
+
+## Prerequisites
+
+Before attempting to push or open a PR, verify that the necessary tools are available:
+
+- Check that `gh` CLI is installed and authenticated (`gh auth status`). If not available, stop and ask the user to install and authenticate GitHub CLI first.
+- If the workflow uses MCP tools for GitHub operations, verify the MCP server is accessible.
+
+## Procedure
+
+1. **Read contribution rules.** Read `CONTRIBUTING.md` and any package-level instructions (e.g. `packages/*/AGENTS.md`) relevant to the changed files.
+2. **Inspect the diff.** Review changed files, scope, and impact. Understand what the change does before writing anything.
+3. **Inspect repo conventions.** Check recent branch names (`git branch -r --sort=-committerdate | head -20`), recent commit messages (`git log --oneline -20`), and the PR template.
+4. **Pre-submission health checks** (run all before creating the PR):
+    - **Unified theme**: All changes should serve one purpose. If unrelated changes are mixed in, ask the user to split or confirm.
+    - **Commit hygiene**: Every new commit must follow the repo's conventional commit style. Squash or reword if needed.
+    - **Author identity**: Verify `git config user.name` and `git config user.email` are set and the email looks real (not empty, not `noreply` unless intentional). Warn the user if not.
+    - **No leftover artifacts**: Check for debug logs, `.only` in tests, conflict markers, or temp files in the diff.
+    - **Lint and build**: Run lint/build for the affected area. Record results honestly.
+5. **Warn if the PR looks too hasty.** If any of these are true, pause and warn the user before proceeding:
+    - Large diff with no description of intent provided
+    - Changes touch core lib or extension (where vibe coding is prohibited per `CONTRIBUTING.md`)
+    - Multiple unrelated concerns in one diff
+    - No validation has been run at all
+    - Remind the user: _"This project does not accept low-quality or AI-generated PRs without meaningful human review. Please review your changes carefully."_
+6. **Branch.** Check the current branch first:
+    - If already on a non-main feature branch with a valid name (matching `type/topic` convention), reuse it.
+    - If the branch name does not follow repo conventions (e.g. missing prefix, unclear topic), ask the user whether to rename or create a new one.
+    - If on `main` or a default branch, create a new branch from it with a short kebab-case name: prefix (`fix/`, `feat/`, `docs/`, `refactor/`, `chore/`) + concrete topic words.
+7. **Stage and commit.** Stage only the intended files. Use `type(scope): subject` format. Keep the subject specific and compact.
+8. **Push.** Push with `-u origin HEAD`.
+9. **Open PR.** Use `gh pr create` with the full PR template structure. Fill in "What" and "Type" sections based on the actual diff. Leave all "Testing" and "Requirements" checkboxes unchecked.
+10. **Report results.** Tell the user: branch name, commit hash, PR link, and what validation actually ran (with pass/fail).
+
+## Post-Submission Reminder
+
+After successfully opening the PR, ALWAYS give a brief reminder in the user's language. Keep it concise and natural, but make sure it clearly tells the user:
+
+1. They need to test the changes themselves in the browser.
+2. They need to go to the PR page and check the Testing and Requirements checkboxes only after verifying each item.
+3. The PR will not enter review until those checkboxes are checked.
+4. The project does not accept autonomously AI-generated PRs, so they should only check the AI declaration if it is truthful.
+
+## Branch Naming
+
+- Prefer short kebab-case names with a repo-consistent prefix such as `fix/`, `feat/`, `docs/`, `refactor/`, or `chore/`.
+- Match the change type first, then the smallest useful topic.
+- Prefer concrete topic words over issue text dumps.
+
+## Commit Style
+
+- Use the repository's prevailing commit style (conventional commits).
+- Use `type(scope): subject` when scope is clear from the changed area.
+- Keep the subject specific and compact.
+- If multiple commits exist on the branch, each one must independently follow conventions.
+
+## Validation Strategy
+
+- Default to enough validation to defend the PR, not the absolute minimum.
+- Run `npm run ci` to run all build and lint checks.
+- Escalate to broader validation when the diff crosses packages, changes shared code, or affects release behavior.
+- Never claim checks that did not actually run.
+- You MAY note what you ran and the results below the Testing section in the PR body, but do NOT check the template checkboxes.
+
+## Decision Points
+
+- No local changes → stop, say so.
+- `gh` CLI not available → stop, ask user to install it.
+- Unrelated files mixed → stage only the intended subset or ask whether the work should be split.
+- If the repo has area-specific instructions, read them before naming the branch or writing the PR.
+- Change is small but high-risk → prefer broader validation.
+- Change is narrowly scoped and low-risk → run the most relevant checks, not arbitrary unrelated ones.
+- Template has declarations you cannot truthfully check → leave unchecked, tell the user why.
+
+## Completion Checks
+
+- The branch exists remotely and tracks upstream.
+- The commit message(s) match repo style.
+- All commit authors have proper name and email configured.
+- The PR title matches the commit intent.
+- The PR body follows the template structure completely.
+- All "Requirements" and "Testing" checkboxes are unchecked (`- [ ]`) in the PR body. Double-check: if any `- [x]` appears in these sections, it is a violation — fix it before submitting.
+- The reported validation is accurate — nothing fabricated.
+- The post-submission reminder was delivered in the user's language, concisely and accurately.

.agents/skills/update-changelog/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: update-changelog
+description: 'Update docs/CHANGELOG.md from git history, GitHub releases, and code diffs. Use when: writing release notes, syncing the latest changelog entry, summarizing a new tag, or keeping changelog wording concise and consistent.'
+argument-hint: 'Describe the target, for example: latest version only'
+---
+
+# Update Changelog
+
+Update `docs/CHANGELOG.md` from repository evidence instead of guesswork.
+
+## When to Use
+
+- Add the newest release entry to `docs/CHANGELOG.md`
+- Sync changelog text with GitHub Releases
+- Summarize the latest tag from git history or code diffs
+
+## Defaults
+
+- Keep the wording brief
+- Only add the latest missing version unless the user explicitly asks to backfill older releases
+- Prefer GitHub sources first, especially Releases and tag metadata
+- Skip `Features` / `Improvements` / `Bug Fixes` headings when the release only has a few clear items
+
+## Procedure
+
+### 1. Read the local style
+
+- Open `docs/CHANGELOG.md`
+- Match the existing tone, bullet style, section ordering, and date format
+
+### 2. Determine the target release
+
+- Read the root `package.json` version and compare it with the top changelog entry
+- Find the previous tag for the target version
+- If the latest version is already documented, stop and report that no changelog update is needed
+
+### 3. Gather evidence
+
+Prefer these sources in order:
+
+1. GitHub release notes
+
+```bash
+GH_PAGER=cat gh release view v<version> --repo <owner>/<repo> --json tagName,name,publishedAt,body
+```
+
+2. Tag date
+
+```bash
+git log -1 --format=%cs v<version>
+```
+
+3. Commit history between tags
+
+```bash
+git --no-pager log --format='%h %s' --no-merges v<previous>..v<version>
+```
+
+4. Diff scope when commit subjects are vague
+
+```bash
+git --no-pager diff --name-only v<previous>..v<version>
+git --no-pager diff --stat v<previous>..v<version>
+```
+
+5. Read touched files directly only when the user-visible change is still unclear
+
+### 4. Distill what belongs in the changelog
+
+Include:
+
+- User-visible features
+- Important behavior changes
+- Bug fixes that improve reliability, compatibility, or developer experience
+- Small docs updates only when they materially change supported setups or onboarding
+
+Exclude unless explicitly requested:
+
+- Pure version bumps
+- Routine dependency updates
+- Internal refactors with no visible impact
+- Mechanical formatting noise
+
+### 5. Choose the structure
+
+- If the release has 1 to 3 clear points, write flat bullets directly under the version heading
+- If the release has several distinct items, use short headings such as `### Features`, `### Improvements`, and `### Bug Fixes`
+- Do not force categories when they make the entry longer or noisier
+
+### 6. Write the entry
+
+- Add or update only the requested release entry
+- Keep bullets short and concrete
+- Reuse project terminology from nearby entries
+- Avoid marketing language
+- Do not copy noisy GitHub release text verbatim
+
+### 7. Verify
+
+- Check dates, version numbers, and tag boundaries
+- Ensure Markdown structure matches nearby entries
+- Confirm no intermediate versions were added unless requested
+
+## Completion Checks
+
+- The newest requested version is documented
+- The wording is concise and consistent with the surrounding changelog
+- The entry is backed by GitHub releases, git history, or code diff evidence
+- Low-signal internal changes were left out

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -1,61 +1,59 @@
 name: Bug Report
 description: Report a bug
 title: '[Bug] '
-labels: ['bug']
+type: Bug
 body:
   - type: markdown
     attributes:
       value: |
-        Thanks for your interest in improving the project! Before submitting, please read our guidelines.
-        感谢您对改进项目的兴趣！提交前请阅读我们的指南。
+        Thanks for your interest in improving the project! Before submitting, please search for existing issues.
+        感谢参与我们的社区！请先搜索现有 Issue，避免重复提交。
 
         - [Code of Conduct](https://github.com/alibaba/page-agent/blob/main/docs/CODE_OF_CONDUCT.md)
         - [Contributing Guide](https://github.com/alibaba/page-agent/blob/main/CONTRIBUTING.md)
 
+        > 为了让更多人参与讨论，请尽量使用英文提交 Issue，感谢理解 🙏
+
   - type: textarea
     id: description
     attributes:
-      label: What happened?
-      placeholder: Describe the bug and expected behavior
+      label: What happened? / 问题描述
+      description: Describe what you expected vs what actually happened.
+      placeholder: 'A clear description of the bug.'
     validations:
       required: true
 
   - type: textarea
-    id: code
+    id: reproduction
     attributes:
-      label: Code
-      render: typescript
-      placeholder: Minimal reproduction code
+      label: How to reproduce / 如何复现
+      description: Provide steps, URL, config or code snippet to reproduce the bug.
+      placeholder: '1. Open URL: https://...'
     validations:
-      required: false
+      required: true
+
+  - type: input
+    id: version
+    attributes:
+      label: Version
+      placeholder: '0.0.0'
 
   - type: input
     id: browser
     attributes:
       label: Browser
-      placeholder: 'Chrome 120, Firefox 119, etc.'
-    validations:
-      required: false
-
-  - type: input
-    id: version
-    attributes:
-      label: version
-      placeholder: '0.0.0'
-    validations:
-      required: false
+      placeholder: 'e.g. Chrome 130'
 
   - type: checkboxes
-    id: community
+    id: checklist
     attributes:
-      label: Community Communication / 社区沟通
-      description: Confirm you will communicate respectfully and constructively / 确认将以礼貌、建设性的方式沟通
+      label: Before submitting
       options:
         - label: I will be polite and respectful. / 我会保持礼貌与尊重。
           required: true
-        - label: I will share constructive, actionable suggestions. / 我会提供建设性、可行动的建议。
-          required: true
         - label: I have read the Code of Conduct. / 我已阅读行为准则。
           required: true
+        - label: I have searched existing issues and this is not a duplicate.
+          required: true
     validations:
       required: true

.github/ISSUE_TEMPLATE/config.yml

@@ -1,11 +1,5 @@
 blank_issues_enabled: false
 contact_links:
-  - name: Questions & Ideas / 问题与想法（Discussions）
-    url: https://github.com/alibaba/page-agent/discussions
-    about: Use Discussions for Q&A and ideation. 使用 Discussions 进行问答与想法交流。
-  - name: Security Report / 安全问题报告
-    url: https://github.com/alibaba/page-agent/security/policy
-    about: Report security vulnerabilities responsibly. 通过安全页面报告漏洞。
   - name: Contributing Guide / 贡献指南
     url: https://github.com/alibaba/page-agent/blob/main/CONTRIBUTING.md
     about: How to contribute code and ideas. 如何进行贡献与提交代码。

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -1,32 +1,28 @@
 name: Feature Request
 description: Suggest a feature
 title: '[Feature] '
-labels: ['enhancement']
+type: Feature
 body:
   - type: markdown
     attributes:
       value: |
-        Thanks for your interest in improving the project! Before submitting, please read our guidelines.
-        感谢您对改进项目的兴趣！提交前请阅读我们的指南。
+        Thanks for your interest in improving the project! Before submitting, please search for existing issues.
+        感谢参与我们的社区！请先搜索现有 Issue，避免重复提交。
 
         - [Code of Conduct](https://github.com/alibaba/page-agent/blob/main/docs/CODE_OF_CONDUCT.md)
         - [Contributing Guide](https://github.com/alibaba/page-agent/blob/main/CONTRIBUTING.md)
 
+        > 为了让更多人参与讨论，请尽量使用英文提交 Issue，感谢理解 🙏
+
   - type: textarea
     id: description
     attributes:
       label: Feature Description / 功能描述
-      description: Describe the problem, solution, and any API changes. / 描述问题、解决方案以及 API 变更。
+      description: Describe the problem, solution, and any API changes.
       placeholder: |
         **Problem**:
-        What problem does this solve?
-
         **Solution**:
-        How should this work?
-
         **Proposed API**:
-        ```typescript
-        // code here
         ```
     validations:
       required: true
@@ -34,14 +30,13 @@ body:
   - type: checkboxes
     id: community
     attributes:
-      label: Community Communication / 社区沟通
-      description: Confirm you will communicate respectfully and constructively / 确认将以礼貌、建设性的方式沟通
+      label: Before submitting
       options:
         - label: I will be polite and respectful. / 我会保持礼貌与尊重。
           required: true
-        - label: I will share constructive, actionable suggestions. / 我会提供建设性、可行动的建议。
-          required: true
         - label: I have read the CODE_OF_CONDUCT.md and CONTRIBUTING.md. / 我已阅读行为准则。
           required: true
+        - label: I have searched existing issues and this is not a duplicate.
+          required: true
     validations:
       required: true

.github/PULL_REQUEST_TEMPLATE.md

@@ -2,15 +2,15 @@
 
 Brief description of changes.
 
+Closes #(issue)
+
 ## Type
 
+- [ ] Breaking change
 - [ ] Bug fix
 - [ ] Feature / Improvement
-- [ ] Refactor
-- [ ] Documentation
-- [ ] Website
-- [ ] Demo / Testing
-- [ ] Breaking change
+- [ ] Refactor / Chores
+- [ ] Documentation / Website / Demo / Testing
 
 ## Testing
 
@@ -18,8 +18,7 @@ Brief description of changes.
 - [ ] No console errors
 - [ ] Types/doc added
 
-Closes #(issue)
-
 ## Requirements / 要求
 
 - [ ] I have read and follow the [Code of Conduct](../docs/CODE_OF_CONDUCT.md) and [Contributing Guide](../CONTRIBUTING.md) . / 我已阅读并遵守行为准则。
+- [ ] This PR is NOT generated by a bot or AI agent acting autonomously. I have authored or meaningfully reviewed every change. / 此 PR 不是由 bot 或 AI 自主生成的，我已亲自编写或充分审查了每一处变更。

.github/dependabot.yml

@@ -4,28 +4,35 @@ updates:
     directory: '/'
     schedule:
       interval: 'weekly'
+    labels:
+      - 'dependencies'
     groups:
-      # 生产依赖 - 小版本更新
       production-dependencies:
         dependency-type: 'production'
         update-types:
           - 'minor'
           - 'patch'
 
-      # 开发依赖 - 小版本更新
       development-dependencies:
         dependency-type: 'development'
         update-types:
           - 'minor'
           - 'patch'
 
-      # Major 更新单独处理（不分组，需要人工审查）
-      # 安全更新也不分组，Dependabot 会自动优先创建独立 PR
+      development-major:
+        dependency-type: 'development'
+        update-types:
+          - 'major'
+
+      # Production major updates are intentionally ungrouped for individual review.
+      # Security updates are also ungrouped — Dependabot prioritizes them automatically.
 
   - package-ecosystem: 'github-actions'
     directory: '/'
     schedule:
       interval: 'weekly'
+    labels:
+      - 'dependencies'
     groups:
       github-actions:
         patterns:

.github/workflows/ci.yml

@@ -1,6 +1,6 @@
+name: CI
 permissions:
   contents: read
-name: CI
 
 on:
   push:
@@ -16,7 +16,9 @@ jobs:
         node-version: [24]
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
 
       - name: Setup Node.js ${{ matrix.node-version }}
         uses: actions/setup-node@v6
@@ -24,18 +26,8 @@ jobs:
           node-version: ${{ matrix.node-version }}
           cache: 'npm'
 
-      # test on default version of npm
-      # - 9.6~10.8 on node@20
-      # - 11.3~11.6 on node@24
-
-      - name: Node and NPM version
-        run: node --version && npm --version
-
       - name: Install dependencies
-        run: npm install
+        run: npm ci
 
-      - name: Lint
-        run: npx eslint . && npx prettier --check **/*.ts
-
-      - name: Build
-        run: npm run build
+      - name: CI checks
+        run: node scripts/ci.js

.github/workflows/deploy-demo.yml

@@ -13,7 +13,7 @@ jobs:
       id-token: write
 
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Setup Node.js
         uses: actions/setup-node@v6
@@ -28,13 +28,13 @@ jobs:
         run: npm run build:website
 
       - name: Setup Pages
-        uses: actions/configure-pages@v5
+        uses: actions/configure-pages@v6
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v4
+        uses: actions/upload-pages-artifact@v5
         with:
           path: './packages/website/dist'
 
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v5

.github/workflows/release.yml

@@ -13,7 +13,7 @@ jobs:
   release:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@v7
 
       - name: Setup Node.js
         uses: actions/setup-node@v6

.gitignore

@@ -25,6 +25,9 @@ dist-ssr
 *.sw?
 .qoder
 
+# publish backup
+package.json.bak
+
 # env files
 .env
 .env.*
@@ -34,8 +37,7 @@ dist-ssr
 .wxt
 
 # AI
-.agent
 .claude
 .cursor
 .gemini
-CLAUDE.md
+.codex

.prettierignore

@@ -0,0 +1,8 @@
+# Prompt templates (formatted manually for LLM readability)
+*prompt.md
+
+# Generated
+packages/extension/.wxt
+
+# Vendored
+**/components/ui

.vscode/cspell.json

@@ -0,0 +1,82 @@
+{
+    "version": "0.2",
+    "language": "en",
+    "globRoot": "..",
+    "ignorePaths": [
+        "**/node_modules/**",
+        "**/dist/**",
+        "**/dist-ssr/**",
+        "**/.output/**",
+        "**/.wxt/**",
+        "**/*.svg"
+    ],
+    "words": [
+        "activedescendant",
+        "adex",
+        "agentactivity",
+        "agentic",
+        "akldabonmimlicnjlflnapfeklbfemhj",
+        "aliyun",
+        "Bailian",
+        "Bento",
+        "BYOK",
+        "Chromewebstore",
+        "contenteditable",
+        "deepseek",
+        "executionresult",
+        "fieldsets",
+        "gaomeng",
+        "Googlechrome",
+        "Grabbable",
+        "Gregor",
+        "haspopup",
+        "highspeed",
+        "historicalevent",
+        "historychange",
+        "HITL",
+        "hrefs",
+        "IDBP",
+        "innerhtml",
+        "instructionsconfig",
+        "kimi",
+        "languagedetector",
+        "Lian",
+        "llms",
+        "magicui",
+        "maxlength",
+        "menuitemcheckbox",
+        "menuitemradio",
+        "modelcontextprotocol",
+        "multipageagent",
+        "nesw",
+        "npmmirror",
+        "Ollama",
+        "onwarn",
+        "opensource",
+        "openrouter",
+        "pageagent",
+        "pageagentcore",
+        "pageagentext",
+        "postpublish",
+        "qwen",
+        "reactid",
+        "reactroot",
+        "retryable",
+        "shadcn",
+        "sidepanel",
+        "spinbutton",
+        "staticity",
+        "statuschange",
+        "Supabase",
+        "toggleable",
+        "trivago",
+        "Uncapitalize",
+        "unparseable",
+        "valuenow",
+        "valuetext",
+        "WCAG",
+        "webgl",
+        "wouter",
+        "Zunic"
+    ]
+}

.vscode/settings.json

@@ -1,27 +1,9 @@
 {
-    "cSpell.words": [
-        "deepseek",
-        "historychange",
-        "HITL",
-        "innerhtml",
-        "languagedetector",
-        "llms",
-        "magicui",
-        "npmmirror",
-        "onwarn",
-        "opensource",
-        "qwen",
-        "retryable",
-        "shadcn",
-        "sidepanel",
-        "statuschange",
-        "wouter"
-    ],
     "files.exclude": {
         "packages/*/node_modules": true
     },
     "markdownlint.config": {
-        // "comment": "Relaxed rules",
+        // Relaxed rules
         "default": true,
         "whitespace": false,
         "line_length": false,
@@ -34,5 +16,9 @@
         "blanks-around-lists": false,
         "ol-prefix": false,
         "no-duplicate-heading": false
-    }
+    },
+    "editor.defaultFormatter": "esbenp.prettier-vscode",
+    "js/ts.tsdk.path": "node_modules/typescript/lib",
+    "typescript.tsdk": "node_modules/typescript/lib",
+    "typescript.enablePromptUseWorkspaceTsdk": true
 }

AGENTS.md

@@ -5,7 +5,7 @@
 This is a **monorepo** with npm workspaces:
 
 - **Page Agent** (`packages/page-agent/`) - Main entry with built-in UI Panel, published as `page-agent` on npm
-- **Extension** (`packages/extension/`) - Browser extension (WXT + React) 🚧 WIP
+- **Extension** (`packages/extension/`) - Browser extension (WXT + React)
 - **Website** (`packages/website/`) - React docs and landing page. **When working on website, follow `packages/website/AGENTS.md`**
 
 Internal packages:
@@ -18,18 +18,20 @@ Internal packages:
 ## Development Commands
 
 ```bash
-npm start                    # Start website dev server
-npm run build                # Build all packages
-npm run build:libs           # Build all libraries
-npm run lint                 # ESLint with TypeScript strict rules
-npm run zip -w @page-agent/ext # Zip the extension package
+npm start                      # Start website dev server
+npm run build                  # Build all packages
+npm run build:libs             # Build all libraries
+npm run build:ext              # Build and zip the extension package
+npm run typecheck              # Typecheck all packages
+npm run test                   # Run unit tests across all workspaces
+npm run lint                   # ESLint
 ```
 
 ## Architecture
 
 ### Monorepo Structure
 
-Simple monorepo solution: TypeScript references + Vite aliases. Update tsconfig and vite config when adding/removing packages.
+Source-first monorepo: library `package.json` exports point to `src/*.ts` during development. At publish time, `scripts/pre-publish.js` promotes `publishConfig` fields to top-level (swapping to `dist/`), and `scripts/post-publish.js` restores the originals.
 
 ```
 packages/
@@ -37,7 +39,7 @@ packages/
 ├── page-agent/              # npm: "page-agent" entry class (with UI + controller + demo builds)
 ├── website/                 # @page-agent/website (private)
 ├── llms/                    # @page-agent/llms
-├── extension/               # Browser extension (WXT + React)
+├── extension/               # Browser extension
 ├── page-controller/         # @page-agent/page-controller
 └── ui/                      # @page-agent/ui
 ```
@@ -124,6 +126,20 @@ const pageInfo = await this.pageController.getPageInfo()
 2. Expose via async method in `PageController.ts`
 3. Export from `packages/page-controller/src/index.ts`
 
+## Testing
+
+- **Framework**: Vitest (unit tests only for now; future E2E goes to `packages/e2e/` with Playwright)
+- **Location**: co-located, `src/foo.test.ts` next to `src/foo.ts`
+- **Coverage today**: `packages/llms` only — other packages will follow incrementally
+- **Adding tests to a new package**: create `vitest.config.ts` in the package and add a `"test": "vitest run"` script. Root `npm test` and `node scripts/ci.js` pick it up through npm workspaces.
+- **Template**: See @page-agent/llms
+
+```bash
+npm test                            # all packages with a test script
+npm test -w @page-agent/llms        # single package
+cd packages/llms && npx vitest      # watch mode in one package
+```
+
 ## Code Standards
 
 - Explicit typing for exported/public APIs

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

CONTRIBUTING.md

@@ -1,41 +1,14 @@
-# Contributing to Page-Agent
+# Contributing to PageAgent
 
-Thank you for your interest in contributing to Page-Agent! We welcome contributions from everyone.
+♥️ We welcome contributions from everyone.
 
-## 🚀 Quick Start
-
-### Development Setup
-
-1. **Prerequisites**
-    - `node.js >= 20` with `npm >= 10`
-    - An editor that supports `ts/eslint/prettier`
-    - Make sure `eslint`, `prettier` and `commitlint` work well
-
-2. **Setup**
-
-    ```bash
-    npm ci
-    npm start          # Start demo and documentation site
-    ```
-
-### Project Structure
-
-This is a **monorepo** with npm workspaces containing **4 main packages**:
-
-- **Page Agent** (`packages/page-agent/`) - Main entry with built-in UI Panel, published as `page-agent` on npm
-- **Core** (`packages/core/`) - Core agent logic without UI (npm: `@page-agent/core`)
-- **Extension** (`packages/extension/`) - Chrome extension for multi-page tasks and browser-level automation
-- **Website** (`packages/website/`) - React documentation and landing page. Also as demo and test page for the core lib. private package `@page-agent/website`
-
-We use a simplified monorepo solution with `native npm-workspace + ts reference + vite alias`. No fancy tooling. Hoisting is required.
-
-- When developing. Use alias so that we don't have to pre-build.
-- When bundling. Use external and disable ts `paths` alias to leave deps out.
-- When bundling `IIFE` and `Website`. Bundle everything including local packages.
+For local development workflows, setup, local LLM config, extension development, testing on other websites, and more details, see [docs/developer-guide.md](docs/developer-guide.md).
 
 ## 🤝 How to Contribute
 
-### Reporting Issues
+> **[Maintainer's Note](https://github.com/alibaba/page-agent/issues/349)**
+
+### Opening Issues
 
 - Use the GitHub issue tracker to report bugs or request features
 - Search existing issues before creating new ones
@@ -44,170 +17,31 @@ We use a simplified monorepo solution with `native npm-workspace + ts reference
 
 ### Code Contributions
 
-1. **Fork and Clone**
+1. Follow existing code style and patterns
+2. Update documentation as needed
+3. Add JSDoc for public APIs
+4. Build and lint everything
+5. Test in our demo website, and on other websites if applicable
+6. Include screenshots for UI changes
 
-    ```bash
-    git clone https://github.com/your-username/page-agent.git
-    cd page-agent
-    ```
+### Vibe Coding with AI
 
-2. **Create Feature Branch**
-
-    ```bash
-    git checkout -b feat/your-feature-name
-    ```
-
-3. **Make Changes**
-    - Follow existing code style and patterns
-    - Add tests for new functionality
-    - Update documentation as needed
-
-4. **Test Your Changes**
-    - Test in our demo website
-    - Test it on other websites if applicable
-    - `@TODO: test suite`
-
-5. **Commit and Push**
-
-    ```bash
-    git add .
-    git commit -m "feat: add awesome feature"
-    git push origin feat/your-feature-name
-    ```
-
-6. **Create Pull Request**
-    - Provide clear description of changes
-    - Link related issues
-    - Include screenshots for UI changes
-
-## 📝 Code Style
-
-### General Guidelines
-
-- Use TypeScript for type safety
-- Follow existing naming conventions
-- Write meaningful commit messages
-- Keep functions small and focused
-- Add JSDoc for public APIs
-
-### Vibe coding with AI
-
-- It's **recommended** to heavily rely on AI (aka "vibe coding") when maintaining **demo pages and tests**.
-- Be very careful if AI ever touched the core lib!!!
+- Vibe coding is **NOT** allowed for the core lib or the extension!!!
+- Vibe coding is **RECOMMENDED** when maintaining **the demo, the website, the UI and tests**.
+- Make sure your AI references `AGENTS.md` and `website/AGENTS.md` for better quality.
 - Review anything AI wrote before make a commit. You are the author of anything you commit. NOT AI.
-- Update the [AI instructions](AGENTS.md) when structure changed.
-
-If your lame AI assistant does not support [AGENTS.md](https://agents.md/). Add an alias for it:
-
-- claude-code (`CLAUDE.md`)
-
-    ```markdown
-    @AGENTS.md
-    ```
-
-- antigravity (`.agent/rules/alias.md`)
-
-    ```markdown
-    ---
-    trigger: always_on
-    ---
-
-    @../../AGENTS.md
-    ```
-
-## 🔧 Development Workflows
-
-### Test With Your Own LLM API
-
-- Create a `.env` file in the repo root with your LLM API config
-
-    ```env
-    LLM_MODEL_NAME=gpt-5.2
-    LLM_API_KEY=your-api-key
-    LLM_BASE_URL=https://api.your-llm-provider.com/v1
-    ```
-
-- **Ollama example** (tested on 0.15 + qwen3:14b, RTX3090 24GB):
-
-    ```env
-    LLM_BASE_URL="http://localhost:11434/v1"
-    LLM_API_KEY="NA"
-    LLM_MODEL_NAME="qwen3:14b"
-    ```
-
-    > ⚠️ Add `*` to `OLLAMA_ORIGINS` (403). Models < 10B unlikely strong enough. Requires tool_call support. Set context length > 15k (default 4k will NOT work): `$env:OLLAMA_CONTEXT_LENGTH=64000; ollama serve`
-
-- Restart the dev server to load new env vars
-- If not provided, the demo will the free testing proxy by default
-
-### Website Development
-
-```bash
-npm start
-```
-
-### Extension Development
-
-```bash
-npm run dev -w @page-agent/ext
-npm run zip -w @page-agent/ext
-```
-
-- Load extension in Chrome via `chrome://extensions` -> **Load unpacked**
-- Use `packages/extension/docs/extension_api.md` (EN) or `packages/extension/docs/extension_api_zh.md` (ZH) for API integration details
-
-### Testing on Other Websites
-
-- Start and serve a local `iife` script
-
-    ```bash
-    npm run dev:demo # Serving IIFE with auto rebuild at http://localhost:5174/page-agent.demo.js
-    ```
-
-- Add a new bookmark
-
-    ```javascript
-    javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5174/page-agent.demo.js?t=${Math.random()}`;s.onload=()=>console.log(%27PageAgent ready!%27);document.head.appendChild(s);})();
-    ```
-
-- Click the bookmark on any page to load Page-Agent
-
-> Warning: AK in your local `.env` will be inlined in the iife script.
-
-### Adding Documentation
-
-Ask an AI to help you add documentation to the `website/` package. Follow the existing style.
-
-> Our AGENTS.md file and guardrails are designed for this purpose. But please be careful and review anything AI generated.
-
-## 🎯 Contribution Areas
-
-We especially welcome contributions in:
-
-- **Browser compatibility** improvements
-- **Performance optimizations** for DOM processing
-- **Documentation** and examples
-- **Testing** and quality assurance
-- **Accessibility** features
-- **Internationalization** support
 
 ## 🚫 What We Don't Accept
 
-- Changes that break existing API compatibility (Discuss first)
-- Heavy dependencies to core library
-- Contributions without proper testing
-- Code that doesn't follow project conventions
+- Breaking changes and large PRs without prior discussion
+- Heavy dependencies to core libs
+- Dependencies or code with licenses incompatible with MIT
+- Bot or AI-generated pull requests without meaningful human involvement
 
 ## 📄 Legal
 
 By contributing to this project, you agree that your contributions will be licensed under the MIT License.
 
-> You may need to sign a github CLA before you create a PR.
+---
 
-## 💬 Questions?
-
-- Open a GitHub issue for technical questions
-- Check existing documentation and issues first
-- Be respectful and constructive in discussions
-
-Thank you for helping make Page-Agent better! 🎉
+Thank you for helping make PageAgent better! 🎉

LICENSE

@@ -1,7 +1,7 @@
 MIT License
 
-Copyright (c) 2026 Alibaba
-Copyright (c) 2026 Simon
+Copyright (c) 2026 SimonLuvRamen
+Copyright (c) 2026 Alibaba Group Holding Limited
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,19 +1,21 @@
 # Page Agent
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://img.alicdn.com/imgextra/i4/O1CN01qKig1P1FnhpFKNdi6_!!6000000000532-2-tps-1280-256.png">
-  <img alt="Page Agent Banner" src="https://img.alicdn.com/imgextra/i1/O1CN01NCMKXj1Gn4tkFTsxf_!!6000000000666-2-tps-1280-256.png">
+  <source media="(prefers-color-scheme: dark)" srcset="https://page-agent.github.io/assets/readme/banner-dark.png">
+  <img alt="Page Agent Banner" src="https://page-agent.github.io/assets/readme/banner-light.png">
 </picture>
 
-[![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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-auto.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/) [![Bundle Size](https://img.shields.io/bundlephobia/minzip/page-agent)](https://bundlephobia.com/package/page-agent) [![Downloads](https://img.shields.io/npm/dt/page-agent.svg)](https://www.npmjs.com/package/page-agent) [![GitHub stars](https://img.shields.io/github/stars/alibaba/page-agent.svg)](https://github.com/alibaba/page-agent)
 
 The GUI Agent Living in Your Webpage. Control web interfaces with natural language.
 
 🌐 **English** | [中文](./docs/README-zh.md)
 
-👉 <a href="https://alibaba.github.io/page-agent/" target="_blank"><b>🚀 Demo</b></a> | <a href="https://alibaba.github.io/page-agent/docs/introduction/overview" target="_blank"><b>📖 Documentation</b></a>
+<a href="https://alibaba.github.io/page-agent/" target="_blank"><b>🚀 Demo</b></a> | <a href="https://alibaba.github.io/page-agent/docs/introduction/overview" target="_blank"><b>📖 Docs</b></a> | <a href="https://news.ycombinator.com/item?id=47264138" target="_blank"><b>📢 HN Discussion</b></a> | <a href="https://x.com/simonluvramen" target="_blank"><b>𝕏 Follow on X</b></a>
 
-<video id="demo-video" src="https://github.com/user-attachments/assets/a1f2eae2-13fb-4aae-98cf-a3fc1620a6c2" controls crossorigin muted></video>
+<!-- demo video -->
+
+https://github.com/user-attachments/assets/a1f2eae2-13fb-4aae-98cf-a3fc1620a6c2
 
 ---
 
@@ -22,20 +24,19 @@ The GUI Agent Living in Your Webpage. Control web interfaces with natural langua
 - **🎯 Easy integration**
     - No need for `browser extension` / `python` / `headless browser`.
     - Just in-page javascript. Everything happens in your web page.
-    - The best tool for your agent to control web pages.
 - **📖 Text-based DOM manipulation**
-    - No screenshots. No OCR or multi-modal LLMs needed.
-    - No special permissions required.
+    - No screenshots. No multi-modal LLMs or special permissions needed.
 - **🧠 Bring your own LLMs**
-- **🎨 Pretty UI with human-in-the-loop**
 - **🐙 Optional [chrome extension](https://alibaba.github.io/page-agent/docs/features/chrome-extension) for multi-page tasks.**
+    - And an [MCP Server (Beta)](https://alibaba.github.io/page-agent/docs/features/mcp-server) to control it from outside
 
 ## 💡 Use Cases
 
-- **SaaS AI Copilot** — Ship an AI copilot in your product in lines of code. No backend rewrite needed.
+- **SaaS AI Copilot** — Ship an AI copilot in your product in lines of code. No backend rewrite.
 - **Smart Form Filling** — Turn 20-click workflows into one sentence. Perfect for ERP, CRM, and admin systems.
 - **Accessibility** — Make any web app accessible through natural language. Voice commands, screen readers, zero barrier.
-- **Multi-page Agent** — Extend your agent's reach across browser tabs with the optional [chrome extension](https://alibaba.github.io/page-agent/docs/features/chrome-extension).
+- **Multi-page Agent** — Extend your own web agent's reach across browser tabs [chrome extension](https://alibaba.github.io/page-agent/docs/features/chrome-extension).
+- **MCP** - Allow your agent clients to control your browser.
 
 ## 🚀 Quick Start
 
@@ -47,13 +48,15 @@ Fastest way to try PageAgent with our free Demo LLM:
 <script src="{URL}" crossorigin="true"></script>
 ```
 
-| Mirrors | URL                                                                                |
-| ------- | ---------------------------------------------------------------------------------- |
-| Global  | https://cdn.jsdelivr.net/npm/page-agent@1.5.2/dist/iife/page-agent.demo.js         |
-| China   | https://registry.npmmirror.com/page-agent/1.5.2/files/dist/iife/page-agent.demo.js |
-
 > **⚠️ For technical evaluation only.** This demo CDN uses our free [testing LLM API](https://alibaba.github.io/page-agent/docs/features/models#free-testing-api). By using it, you agree to its [terms](https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md).
 
+| Mirrors | URL                                                                                 |
+| ------- | ----------------------------------------------------------------------------------- |
+| Global  | https://cdn.jsdelivr.net/npm/page-agent@1.11.0/dist/iife/page-agent.demo.js         |
+| China   | https://registry.npmmirror.com/page-agent/1.11.0/files/dist/iife/page-agent.demo.js |
+
+Add `?autoInit=false` to load the script without creating the demo agent automatically. You can then instantiate it with `new window.PageAgent(...)`.
+
 ### NPM Installation
 
 ```bash
@@ -75,11 +78,27 @@ await agent.execute('Click the login button')
 
 For more programmatic usage, see [📖 Documentations](https://alibaba.github.io/page-agent/docs/introduction/overview).
 
+## 🌟 Awesome Page Agent
+
+Built something cool with PageAgent? Add it here! Open a PR to share your project.
+
+> These are community projects — not maintained or endorsed by us. Use at your own discretion.
+
+| Project  | Description                                                 |
+| -------- | ----------------------------------------------------------- |
+| _Yours?_ | [Open a PR](https://github.com/alibaba/page-agent/pulls) 🙌 |
+
 ## 🤝 Contributing
 
-We welcome contributions from the community! Follow our instructions in [CONTRIBUTING.md](CONTRIBUTING.md) for environment setup and local development.
+We welcome contributions from the community! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and [docs/developer-guide.md](docs/developer-guide.md) for local development workflows.
 
-Please read [Code of Conduct](docs/CODE_OF_CONDUCT.md) before contributing.
+Please read the [maintainer's note](https://github.com/alibaba/page-agent/issues/349) on principles and current state.
+
+Contributions generated entirely by **bots or AI** without substantial human involvement will **not be accepted**.
+
+## ⚖️ License
+
+[MIT License](LICENSE)
 
 ## 👏 Acknowledgments
 
@@ -90,24 +109,15 @@ This project builds upon the excellent work of **[`browser-use`](https://github.
 ```
 DOM processing components and prompt are derived from browser-use:
 
-Browser Use
+Browser Use <https://github.com/browser-use/browser-use>
 Copyright (c) 2024 Gregor Zunic
 Licensed under the MIT License
 
-Original browser-use project: <https://github.com/browser-use/browser-use>
-
 We gratefully acknowledge the browser-use project and its contributors for their
 excellent work on web automation and DOM interaction patterns that helped make
 this project possible.
-
-Third-party dependencies and their licenses can be found in the package.json
-file and in the node_modules directory after installation.
 ```
 
-## 📄 License
-
-[MIT License](LICENSE)
-
 ---
 
 **⭐ Star this repo if you find PageAgent helpful!**

docs/CHANGELOG.md

@@ -5,6 +5,174 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.10.0] - 2026-06-15
+
+### Breaking Changes
+
+- **Agent run lifecycle rework** - `stop()` is now async and resolves only after the run fully settles. Run status is decoupled from task outcome: a new `stopped` state was added, and LLM self-reported failures now end as `completed`. Lifecycle hooks re-throw instead of folding errors into the result, agent errors are recorded in history, and `agent.lastResult` was added.
+
+### Features
+
+- **Abortable JavaScript execution** - `execute_javascript` now honors the `AbortSignal`.
+- **Leaner agent prompts** - Simplified the waiting-response flow and removed navigation-back instructions to reduce LLM cognitive load.
+- **MultiPageAgent safety** - Disabled `ScriptExecutionTool` for `MultiPageAgent`.
+
+### Improvements
+
+- **Dark mode detection** - Refined detection heuristics and made `isMainContentDark` less aggressive by checking `html` and `body` data attributes independently.
+- **Extension lifecycle robustness** - Drove heartbeat and running state from status changes, cleared stale activity on any non-running status, handled the stopped lifecycle state, and cleared `currentTabId` on `TabsController.init`.
+
+### Bug Fixes
+
+- **Accurate wait reporting** - Wait steps now report the actual wait duration.
+- **Scroll predicates** - Scroll predicates now return booleans.
+- **Docs** - Fixed the broken demo video on GitHub.
+
+## [1.9.0] - 2026-06-08
+
+### Features
+
+- **Robust abort handling** - Rewrote the aborting system; sync tools, loop execution, and LLM clients now correctly respect task abort signals (`ctx.signal`). Also decoupled `AbortError` from `InvokeError` in `@page-agent/llms`.
+- **Claude Opus 4.8 support** - Added support for Claude Opus 4.8 model.
+
+### Improvements
+
+- **Concurrency guard** - Prevented concurrent `execute()` calls on a single PageAgent/Core instance to avoid race conditions.
+- **Model recommendations refresh** - Updated default and tested model list recommendations.
+- **Test coverage** - Added comprehensive Vitest unit tests for the `@page-agent/llms` package.
+- **Improved documentation** - Added website documentation for the `ctx.signal` abort contract and `execute()` concurrency rules.
+
+### Bug Fixes
+
+- **DTS bundle fix** - Fixed a packaging bug where global type declarations were incorrectly bundled into `.d.ts` outputs.
+- **Website sidebar fix** - Normalized trailing slashes in the website's sidebar location comparison.
+
+## [1.8.2] - 2026-05-11
+
+### Features
+
+- **IIFE demo control** - Added `showPanel` and `autoInit` switches to the IIFE CDN script to control whether the UI panel automatically displays or initializes on load.
+
+### Improvements
+
+- **Build toolchain modernization** - Upgraded build infrastructure to Vite 8.
+
+### Bug Fixes
+
+- **TypeScript `InvokeErrorType` fix** - Separated the value and type space for `InvokeErrorType` to resolve TypeScript compilation issues.
+- **Website chunking fix** - Restored working code-splitting with `manualChunks` for the documentation website.
+
+## [1.8.1] - 2026-04-27
+
+### Features
+
+- **GPT-5.4 & Qwen 3.6 support** - Added support for `gpt-5.4` and `qwen3.6-max/flash` in the recommended LLM list.
+- **Custom LLM request hook** - Added a `transformRequestBody` hook to allow custom modification of payloads before sending requests to LLM providers.
+
+### Improvements
+
+- **Accessibility (a11y) enhancements** - Added descriptive accessible labels to `ConfigPanel` input fields and icon buttons in compliance with WCAG 4.1.2.
+- **UI polish** - Improved `HistoryList` loading and empty states, and added helpful tooltips for actions.
+- **Prompt caching guidance** - Added website documentation for prompt caching optimization.
+- **Build speedups** - Added parallel build scripts to accelerate local development compilation.
+
+### Bug Fixes
+
+- **DeepSeek tool choice fix** - Disabled explicit `tool_choice` for DeepSeek models to avoid API compatibility errors.
+- **MCP version advertising** - MCP server now correctly advertises its package version.
+
+## [1.8.0] - 2026-04-15
+
+### Breaking Changes
+
+- **TypeScript 6 & ESLint 10 upgrade** - Major toolchain modernization. Upgraded the entire monorepo to TypeScript 6 and ESLint 10 with source-first monorepo resolution (library exports resolve to source files directly during local development).
+
+### Improvements
+
+- **MCP security hardening** - Bound the MCP HTTP + WebSocket server to `localhost` only.
+- **Extension UI refinement** - Made the history panel height responsive to the viewport and improved the result card readability by increasing font size.
+
+### Bug Fixes
+
+- **SimulatorMask memory leak** - Fixed a memory leak by ensuring the `requestAnimationFrame` loop is cancelled when disposing the SimulatorMask.
+- **Autofixer format fix** - Corrected the fallback action format for `autoFixer` when waiting.
+- **IIFE scope protection** - Fixed a name collision in IIFE builds by preventing global helper function re-declarations.
+
+## [1.7.1] - 2026-04-04
+
+### Features
+
+- **Optional `keepSemanticTags`** - Added an experimental `keepSemanticTags` config to preserve semantic structure in PageController output
+- **Per-task extension system instructions** - Extension `ExecuteConfig` now supports `systemInstruction`
+
+### Improvements
+
+- **Smarter scroll handling** - Scroll container detection and scroll direction handling are more reliable
+- **Better accessibility-aware element detection** - Interactive candidates with supported ARIA attributes and `role="listitem"` are recognized more accurately
+
+### Bug Fixes
+
+- Fixed iframe-origin filtering for extension `postMessage` listeners
+- Avoided a `currentScript` null pointer during deferred initialization
+
+## [1.7.0] - 2026-03-31
+
+- **More reliable click actions** - Click handling now reuses pointer coordinates, verifies targets with `elementFromPoint`, and behaves better on layered layouts
+- **Better mask event handling** - `SimulatorMask` now supports passthrough events when automation should not fully swallow input
+- Fixed a `SimulatorMask` memory leak
+
+## [1.6.3] - 2026-03-30
+
+### Features
+
+- **Experimental all-tabs control** - Extension can include and control all browser tabs via `experimentalIncludeAllTabs`
+
+### Improvements
+
+- **Calmer empty state motion** - Disabled the EmptyState auto-start animation in the extension UI
+- **Cleaner extension docs** - Simplified setup and tab-control documentation across the README and developer guide
+
+### Bug Fixes
+
+- Fixed new-tab detection from content scripts
+- Fixed tab deduplication and multi-window handling in the extension
+
+## [1.6.2] - 2026-03-25
+
+- **Longer task input** - The UI task input now accepts up to 1000 characters
+- **Contributor docs refresh** - Added a maintainer note and refreshed contributor-facing documentation
+- Fixed lint issues in the release pipeline
+
+## [1.6.1] - 2026-03-22
+
+- **Internal PageController action exports** - PageController actions are now exposed as internal methods for easier reuse across packages
+- **Expanded docs** - Added MCP docs and clarified project limitations and homepage details
+
+## [1.6.0] - 2026-03-21
+
+### Features
+
+- **Beta MCP support** - New `@page-agent/mcp` package lets MCP clients such as Claude Desktop and Copilot control the browser through the Page Agent extension
+- **Better iframe handling** - Same-origin iframe elements are handled more reliably during DOM extraction and actions
+- **Extension history workflows** - Users can rerun past tasks, export history sessions as JSON, and approve MCP-triggered tasks before execution
+
+### Improvements
+
+- **Unified versioning across packages** - The extension now follows the root workspace version. Changelog entries are no longer split into a separate extension version section
+- **Configurable `stepDelay`** - Agent pacing between steps is now configurable via `stepDelay`
+- **Optional API key** - `apiKey` can now be omitted for compatible deployments that do not require one
+- **Optional named tool choice** - Tool invocation can disable named tool choice for providers that behave better without it
+- **Better rich-text input support** - Improved `contenteditable` handling with better event dispatching and `execCommand` fallback for more editors
+- **More flexible DOM extraction** - `includeAttributes` now supports wildcards, `contenteditable` is included by default, and heuristically interactive elements expose more useful attributes
+- **MiniMax model support** - Added MiniMax compatibility, with the default recommendation updated to `MiniMax-M2.7`
+
+### Bug Fixes
+
+- Fixed Safari issues when `requestIdleCallback` is unavailable
+- Avoid throwing when `webgl2` initialization fails
+- Improved OpenAI-compatible request patches for GPT-5.4 chat tools and MiniMax temperature/tool-call compatibility
+- Fixed several UI polish issues in the extension and website, including cursor and layout regressions
+
 ## [1.5.1] - 2026-03-05
 
 ### Breaking Changes
@@ -153,42 +321,6 @@ PageAgent is now ready for production use. The API is stable and breaking change
 - **Ask User Tool** - Agent can ask users for clarification
 - **i18n Support** - English and Chinese localization
 
-### Configuration 
-
-```typescript
-// Version 1.0.0
-interface PageAgentConfig {
-    // LLM Configuration (required)
-    baseURL: string
-    apiKey: string
-    model: string
-    temperature?: number
-    maxRetries?: number
-    customFetch?: typeof fetch
-
-    // Agent Configuration
-    language?: 'en-US' | 'zh-CN'
-    maxSteps?: number // default: 20
-    customTools?: Record<string, PageAgentTool> // experimental
-    instructions?: InstructionsConfig
-    transformPageContent?: (content: string) => string | Promise<string>
-    experimentalScriptExecutionTool?: boolean // default: false
-
-    // Lifecycle Hooks (experimental)
-    onBeforeTask?: (agent, result) => void
-    onAfterTask?: (agent, result) => void
-    onBeforeStep?: (agent, stepCount) => void
-    onAfterStep?: (agent, history) => void
-    onDispose?: (agent, reason?) => void
-
-    // Page Controller Configuration
-    enableMask?: boolean // default: true
-    viewportExpansion?: number
-    interactiveBlacklist?: Element[]
-    interactiveWhitelist?: Element[]
-}
-```
-
 ### Packages
 
 | Package                       | Description                        |

docs/CODE_OF_CONDUCT.md

@@ -16,22 +16,22 @@ appearance, race, religion, or sexual identity and orientation.
 Examples of behavior that contributes to creating a positive environment
 include:
 
-* Using welcoming and inclusive language
-* Being respectful of differing viewpoints and experiences
-* Gracefully accepting constructive criticism
-* Focusing on what is best for the community
-* Showing empathy towards other community members
+- Using welcoming and inclusive language
+- Being respectful of differing viewpoints and experiences
+- Gracefully accepting constructive criticism
+- Focusing on what is best for the community
+- Showing empathy towards other community members
 
 Examples of unacceptable behavior by participants include:
 
-* The use of sexualized language or imagery and unwelcome sexual attention or
- advances
-* Trolling, insulting/derogatory comments, and personal or political attacks
-* Public or private harassment
-* Publishing others' private information, such as a physical or electronic
- address, without explicit permission
-* Other conduct which could reasonably be considered inappropriate in a
- professional setting
+- The use of sexualized language or imagery and unwelcome sexual attention or
+  advances
+- Trolling, insulting/derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting
 
 ## Our Responsibilities
 
@@ -85,19 +85,19 @@ available at https://www.contributor-covenant.org/version/1/4/code-of-conduct.ht
 
 有助于创造正面环境的行为包括但不限于：
 
-* 使用友好和包容性语言
-* 尊重不同的观点和经历
-* 耐心地接受建设性批评
-* 关注对社区最有利的事情
-* 友善对待其他社区成员
+- 使用友好和包容性语言
+- 尊重不同的观点和经历
+- 耐心地接受建设性批评
+- 关注对社区最有利的事情
+- 友善对待其他社区成员
 
 身为参与者不能接受的行为包括但不限于：
 
-* 使用与性有关的言语或是图像，以及不受欢迎的性骚扰
-* 捣乱/煽动/造谣的行为或进行侮辱/贬损的评论，人身攻击及政治攻击
-* 公开或私下的骚扰
-* 未经许可地发布他人的个人资料，例如住址或是电子地址
-* 其他可以被合理地认定为不恰当或者违反职业操守的行为
+- 使用与性有关的言语或是图像，以及不受欢迎的性骚扰
+- 捣乱/煽动/造谣的行为或进行侮辱/贬损的评论，人身攻击及政治攻击
+- 公开或私下的骚扰
+- 未经许可地发布他人的个人资料，例如住址或是电子地址
+- 其他可以被合理地认定为不恰当或者违反职业操守的行为
 
 ## 我们的责任
 

docs/README-zh.md

@@ -1,41 +1,41 @@
 # Page Agent
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="https://img.alicdn.com/imgextra/i4/O1CN01qKig1P1FnhpFKNdi6_!!6000000000532-2-tps-1280-256.png">
-  <img alt="Page Agent Banner" src="https://img.alicdn.com/imgextra/i1/O1CN01NCMKXj1Gn4tkFTsxf_!!6000000000666-2-tps-1280-256.png">
+  <source media="(prefers-color-scheme: dark)" srcset="https://page-agent.github.io/assets/readme/banner-dark.png">
+  <img alt="Page Agent Banner" src="https://page-agent.github.io/assets/readme/banner-light.png">
 </picture>
 
-[![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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-auto.svg)](https://opensource.org/licenses/MIT) [![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/) [![Bundle Size](https://img.shields.io/bundlephobia/minzip/page-agent)](https://bundlephobia.com/package/page-agent) [![Downloads](https://img.shields.io/npm/dt/page-agent.svg)](https://www.npmjs.com/package/page-agent) [![GitHub stars](https://img.shields.io/github/stars/alibaba/page-agent.svg)](https://github.com/alibaba/page-agent)
 
 纯 JS 实现的 GUI agent。使用自然语言操作你的 Web 应用。无须后端、客户端、浏览器插件。
 
 🌐 [English](../README.md) | **中文**
 
-👉 <a href="https://alibaba.github.io/page-agent/" target="_blank"><b>🚀 Demo</b></a> | <a href="https://alibaba.github.io/page-agent/docs/introduction/overview" target="_blank"><b>📖 Documentation</b></a>
+<a href="https://alibaba.github.io/page-agent/" target="_blank"><b>🚀 Demo</b></a> | <a href="https://alibaba.github.io/page-agent/docs/introduction/overview" target="_blank"><b>📖 Docs</b></a> | <a href="https://news.ycombinator.com/item?id=47264138" target="_blank"><b>📢 HN Discussion</b></a> | <a href="https://x.com/simonluvramen" target="_blank"><b>𝕏 Follow on X</b></a>
 
-<video id="demo-video" src="https://github.com/user-attachments/assets/a1f2eae2-13fb-4aae-98cf-a3fc1620a6c2" controls crossorigin muted></video>
+<!-- demo video -->
+
+https://github.com/user-attachments/assets/a1f2eae2-13fb-4aae-98cf-a3fc1620a6c2
 
 ---
 
 ## ✨ Features
 
 - **🎯 轻松集成**
-    - 无需 `浏览器插件` / `Python` / `无头浏览器`。
-    - 纯页面内 JavaScript，一切都在你的网页中完成。
-    - The best tool for your agent to control web pages.
+    - 无需 `浏览器插件` / `Python` / `无头浏览器`，纯页面内 JavaScript
 - **📖 基于文本的 DOM 操作**
-    - 无需截图，无需 OCR 或多模态模型。
-    - 无需特殊权限。
-- **🧠 用你自己的 LLM**
-- **🎨 精美 UI，支持人机协同**
-- **🐙 可选的 [Chrome 扩展](https://alibaba.github.io/page-agent/docs/features/chrome-extension)，支持跨页面任务。**
+    - 无需截图，无需多模态模型或特殊权限
+- **🧠 自备 LLM**
+- 🐙 可选的 [Chrome 扩展](https://alibaba.github.io/page-agent/docs/features/chrome-extension)，支持跨页面任务
+    - [MCP Server (Beta)](https://alibaba.github.io/page-agent/docs/features/mcp-server)
 
 ## 💡 应用场景
 
-- **SaaS AI 副驾驶** — 几行代码为你的产品加上 AI 副驾驶，不需要重写后端。
+- **SaaS AI Copilot** — 几行代码为你的产品加上 AI 副驾驶，无需重写后端。
 - **智能表单填写** — 把 20 次点击变成一句话。ERP、CRM、管理后台的最佳拍档。
 - **无障碍增强** — 用自然语言让任何网页无障碍。语音指令、屏幕阅读器，零门槛。
-- **跨页面 Agent** — 通过可选的 [Chrome 扩展](https://alibaba.github.io/page-agent/docs/features/chrome-extension)，让你的 Agent 跨标签页工作。
+- **跨页面 Agent** — 通过可选的 [Chrome 扩展](https://alibaba.github.io/page-agent/docs/features/chrome-extension)，让你自己的 Web Agent 跨标签页工作。
+- 通过 MCP 为现有 Agent 加入浏览器控制能力。
 
 ## 🚀 快速开始
 
@@ -47,13 +47,15 @@
 <script src="{URL}" crossorigin="true"></script>
 ```
 
-| Mirrors | URL                                                                                |
-| ------- | ---------------------------------------------------------------------------------- |
-| Global  | https://cdn.jsdelivr.net/npm/page-agent@1.5.2/dist/iife/page-agent.demo.js         |
-| China   | https://registry.npmmirror.com/page-agent/1.5.2/files/dist/iife/page-agent.demo.js |
-
 > **⚠️ 仅用于技术评估。** 该 Demo CDN 使用了免费的[测试 LLM API](https://alibaba.github.io/page-agent/docs/features/models#free-testing-api)，使用即表示您同意其[条款](https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md)。
 
+| Mirrors | URL                                                                                 |
+| ------- | ----------------------------------------------------------------------------------- |
+| Global  | https://cdn.jsdelivr.net/npm/page-agent@1.11.0/dist/iife/page-agent.demo.js         |
+| China   | https://registry.npmmirror.com/page-agent/1.11.0/files/dist/iife/page-agent.demo.js |
+
+在 URL 后添加 `?autoInit=false` 可只加载脚本，不自动创建 Demo Agent；之后可通过 `new window.PageAgent(...)` 手动初始化。
+
 ### NPM 安装
 
 ```bash
@@ -77,11 +79,13 @@ await agent.execute('点击登录按钮')
 
 ## 🤝 贡献
 
-欢迎社区贡献！请参阅 [CONTRIBUTING.md](../CONTRIBUTING.md) 了解环境配置和本地开发说明。
+欢迎社区贡献！请参阅 [CONTRIBUTING.md](../CONTRIBUTING.md) 了解安装与贡献指南。
 
-请在贡献前阅读[行为准则](CODE_OF_CONDUCT.md)。
+提交 issue 或 PR 之前，请先阅读[作者声明](https://github.com/alibaba/page-agent/issues/349)和[行为准则](CODE_OF_CONDUCT.md)。
 
-## 👏 致谢
+我们不接受未经实质性人类参与、完全由 Bot 或 Agent 自动生成的代码。
+
+## 👏 声明与致谢
 
 本项目基于 **[`browser-use`](https://github.com/browser-use/browser-use)** 的优秀工作构建。
 
@@ -90,21 +94,16 @@ await agent.execute('点击登录按钮')
 ```
 DOM processing components and prompt are derived from browser-use:
 
-Browser Use
+Browser Use <https://github.com/browser-use/browser-use>
 Copyright (c) 2024 Gregor Zunic
 Licensed under the MIT License
 
-Original browser-use project: <https://github.com/browser-use/browser-use>
-
 We gratefully acknowledge the browser-use project and its contributors for their
 excellent work on web automation and DOM interaction patterns that helped make
 this project possible.
-
-Third-party dependencies and their licenses can be found in the package.json
-file and in the node_modules directory after installation.
 ```
 
-## 📄 许可证
+## ⚖️ 许可证
 
 [MIT License](../LICENSE)
 

docs/SECURITY.md

@@ -0,0 +1,50 @@
+# Security Policy
+
+## Supported Versions
+
+We provide security fixes on a best-effort basis for:
+
+| Version                                                   | Supported |
+| --------------------------------------------------------- | --------- |
+| `main`                                                    | Yes       |
+| Latest npm release of `page-agent` and workspace packages | Yes       |
+| Older releases                                            | No        |
+
+Please upgrade to the latest release before reporting an issue against an older build.
+
+## Reporting a Vulnerability
+
+Please do not report security vulnerabilities through public GitHub issues, discussions, or pull requests.
+
+Use GitHub's private vulnerability reporting flow:
+
+- Open https://github.com/alibaba/page-agent/security/policy
+- Click `Report a vulnerability`
+
+If private reporting is unavailable, open a minimal public issue only to request a private contact channel. Do not include exploit details.
+
+## What to Include
+
+- Affected package or feature
+- Exact version, commit, or build
+- Browser, OS, and runtime environment
+- Reproduction steps or a proof of concept
+- Expected impact
+
+## Scope
+
+We prioritize reports that show a real security boundary failure, such as:
+
+- Unauthorized access to data, tokens, or extension capabilities
+- Bypassing explicit safety constraints
+- Sensitive data exposure caused by default behavior
+
+The following usually do not qualify by themselves:
+
+- Unsafe custom integrations that ignore documented safeguards
+- Intentionally embedding secrets into client-side builds
+- Reports against unsupported older versions
+
+## Disclosure
+
+Please avoid public disclosure until maintainers have had a reasonable chance to investigate and ship a fix.

docs/developer-guide.md

@@ -0,0 +1,105 @@
+# Developer Guide
+
+This file is for local development workflows.
+
+For contribution rules and expectations, see [../CONTRIBUTING.md](../CONTRIBUTING.md).
+
+## 🚀 Quick Start
+
+### Development Setup
+
+1. **Prerequisites**
+    - `macOS` / `Linux` / `WSL`
+    - `node.js ^22.13 || >=24` with `npm >= 11`
+    - An editor that supports `ts/eslint/prettier`
+    - Make sure `eslint`, `prettier` and `commitlint` work well. Un-linted code won't pass the CI.
+
+2. **Setup**
+
+    ```bash
+    npm i            # Or `npm ci` if you don't want to change the lockfile
+    npm start        # Start website dev server
+    npm run build    # Build everything
+    ```
+
+## 📦 Project Structure
+
+This is a **monorepo** with npm workspaces.
+
+Published packages:
+
+- **Page Agent** (`packages/page-agent/`) - Main entry with built-in UI Panel (npm: `page-agent`)
+- **MCP** (`packages/mcp/`) - MCP server for browser control via Page Agent extension (npm: `@page-agent/mcp`)
+- **Core** (`packages/core/`) - Core agent logic without UI (npm: `@page-agent/core`)
+- **LLMs** (`packages/llms/`) - LLM client with reflection-before-action mental model
+- **Page Controller** (`packages/page-controller/`) - DOM operations and visual feedback, independent of LLM
+- **UI** (`packages/ui/`) - Panel and i18n, decoupled from PageAgent
+
+Applications:
+
+- **Extension** (`packages/extension/`) - Browser extension (WXT + React)
+- **Website** (`packages/website/`) - React docs, landing page, and dev playground (private)
+
+> Source-first monorepo with `npm workspaces + ts references + vite alias`. Library `package.json` exports point to `src/*.ts` during development, and point to `dist/*.js` when published. `workspaces` in root `package.json` must be in topological order.
+
+## 🤖 AGENTS.md Alias
+
+If your AI assistant does not support [AGENTS.md](https://agents.md/). Add an alias for it.
+
+## 🔧 Development Workflows
+
+### Test With Your Own LLM API
+
+- Create a `.env` file in the repo root with your LLM API config
+
+    ```env
+    LLM_MODEL_NAME=gpt-5.2
+    LLM_API_KEY=your-api-key
+    LLM_BASE_URL=https://api.your-llm-provider.com/v1
+    ```
+
+- **Ollama example** (tested on 0.15 + qwen3:14b, RTX3090 24GB):
+
+    ```env
+    LLM_BASE_URL="http://localhost:11434/v1"
+    LLM_API_KEY="NA"
+    LLM_MODEL_NAME="qwen3:14b"
+    ```
+
+    > @see https://alibaba.github.io/page-agent/docs/features/models#ollama for configuration
+
+- **Restart the dev server** to load new env vars
+- If not provided, the demo will use the free testing proxy by default. By using it, you agree to its [terms](./terms-and-privacy.md).
+
+### Extension Development
+
+```bash
+npm run dev:ext
+npm run build:ext
+```
+
+- Update `packages/extension/docs/extension_api.md` for API integration details
+
+### Testing on Other Websites
+
+- Start and serve a local `iife` script
+
+    ```bash
+    npm run dev:demo # Serving IIFE with auto rebuild at http://localhost:5174/page-agent.demo.js
+    ```
+
+- Add a new bookmark
+
+    ```javascript
+    javascript:(function(){var s=document.createElement('script');s.src=`http://localhost:5174/page-agent.demo.js?lang=en-US&t=${Math.random()}`;s.onload=()=>console.log(%27PageAgent ready!%27);document.head.appendChild(s);})();
+    ```
+
+- Click the bookmark on any page to load Page-Agent
+
+> Warning: AK in your local `.env` will be inlined in the iife script. Be very careful when you distribute the script.
+
+### Adding Documentation
+
+Ask an AI to help you add documentation to the `website/` package. Follow the existing style.
+
+> Our AGENTS.md file and guardrails are designed for this purpose. But please be careful and review anything AI generated.

docs/terms-and-privacy.md

@@ -1,42 +1,44 @@
 # Terms of Use & Privacy
 
-**Last updated:** February 2026
+**Last updated:** March 2026
 
-"We" in this document refers to the maintainers of the open-source Page Agent project (https://github.com/alibaba/page-agent). This document covers the Page Agent software itself and the testing services we provide — **not** any third-party product or service built with it.
+"We" in this document refers to the maintainers of the open-source Page Agent project (https://github.com/alibaba/page-agent). "The software" refers to Page Agent (the JavaScript library) and Page Agent Ext (the browser extension). This document covers the software itself and the testing API we provide — **not** any third-party product or service built with it.
 
 ---
 
 ## 1. Open Source Software Privacy
 
-Page Agent (PageAgent.js and Page Agent Extension) is a **client-side only** tool with a "Bring Your Own Key" (BYOK) architecture. The software itself does **not** include any backend service. The software does **not** collect or transmit any user data on its own, and the maintainers do **not** have access to your browsing activity, page content, or task instructions through the software.
+The software is a **client-side only** tool with a "Bring Your Own Key" (BYOK) architecture. The software itself does **not** include any backend service. The software does **not** collect or transmit any user data on its own, and we do **not** have access to your browsing activity, page content, or task instructions through the software.
 
 All data transmission occurs **only** between your browser and the LLM provider you configure. You are in full control of which provider receives your data.
 
-- You choose which LLM provider to use
-- You may configure your own API endpoint at any time
-- The project is open source and can be audited: https://github.com/alibaba/page-agent
+The project is open source under the [MIT License](https://github.com/alibaba/page-agent/blob/main/LICENSE) and can be audited at: https://github.com/alibaba/page-agent
 
 ---
 
 ## 2. Testing API and Demo Disclaimer & Terms of Use
 
-To facilitate easy testing and technical evaluation, we provide a free testing LLM API. This API is used in the project homepage's live demo, the pre-built demo CDN bundles, and the browser extension's default configuration. Users may also use it independently for their own technical evaluation of page-agent.
+To facilitate easy testing and technical evaluation, we provide a free testing LLM API. This API is used in the project homepage's live demo, the pre-built demo CDN bundles, and the browser extension's default configuration. Users may also use it independently for their own technical evaluation of the software.
 
-This free testing API is provided **strictly for technical evaluation and R&D purposes only**. It must not be used in any production environment. By using this service, you agree to the following terms:
+This free testing API is provided **strictly for technical evaluation and R&D purposes only**. It must not be used in any production environment. By using this API, you agree to the following terms:
 
-**No Sensitive Data**: You are strictly prohibited from inputting any Personal Identifiable Information (PII), confidential business data, financial/medical records, or using this agent on web pages containing such sensitive information.
+- **Permitted Use Only**: This API must be used solely for technical evaluation of the software. Any other use — including integration into other products or services, unlawful activities, violation of the underlying LLM provider's usage policies, or automated scraping at scale — is strictly prohibited.
 
-**Zero Data Retention**: We do not store, log, or use your prompts or webpage data (DOM) for model training. All data is processed in-transit and immediately discarded. However, we do temporarily process necessary, identity-agnostic network data (such as IP addresses) solely for rate-limiting and anti-abuse purposes.
+- **No Sensitive Data**: You are strictly prohibited from inputting any Personal Identifiable Information (PII), confidential business data, financial/medical records, or using this agent on web pages containing such sensitive information.
 
-**Independent Infrastructure**: The `page-agent` open-source software is completely frontend-based with a "Bring Your Own Key" (BYOK) architecture and no built-in backend. To facilitate easy testing, the maintainers have independently purchased public cloud services from Alibaba Cloud China ([aliyun.com](https://www.aliyun.com) FC and BaiLian Qwen models). This project is not affiliated with, nor endorsed by, Alibaba Cloud.
+- **Data Processing**: We do not store or log your prompts, webpage data (HTML), or any submitted content, nor do we use such data for model training. All data is processed in-transit and immediately discarded. We perform in-memory request validation to prevent abuse of the testing API, and temporarily process IP addresses for rate-limiting purposes. No data from these processes is retained. Data is processed through Alibaba Cloud infrastructure, which is subject to its own privacy policy.
 
-**No Guaranteed Availability**: This testing API may be rate-limited, degraded, or discontinued at any time without prior notice.
+- **Independent Infrastructure**: The software is completely frontend-based with a "Bring Your Own Key" (BYOK) architecture and **no built-in backend**. To facilitate easy testing, the maintainers have purchased public cloud services from Alibaba Cloud China ([aliyun.com](https://www.aliyun.com) Function Compute and BaiLian Qwen models). This project is not a product of, nor endorsed by, Alibaba Cloud.
 
-**"AS IS" & Limitation of Liability**: This service is provided strictly on an "AS IS" and "AS AVAILABLE" basis, without any warranties. The maintainers bear no liability for any data loss, service interruption, or legal consequences arising from your use of this demo.
+- **No Guaranteed Availability**: This testing API may be rate-limited, degraded, or discontinued at any time without prior notice.
 
-**Recommendation for Real Usage**: For secure and continuous usage, we strongly advise using the default BYOK mode with your own legally compliant commercial LLM API keys, or connecting to local, offline models (e.g., Ollama).
+- **"AS IS" & Limitation of Liability**: This service is provided strictly on an "AS IS" and "AS AVAILABLE" basis, without any warranties. The maintainers bear no liability for any data loss, service interruption, or legal consequences arising from your use of this service.
 
-**Note**: This testing LLM api processes data via servers located in Mainland China. If you are located in a region with strict data localization laws (such as the EU/EEA), please do not use this demo.
+- **Recommendation for Real Usage**: For secure and continuous usage, we strongly advise using the BYOK mode with your own legally compliant commercial LLM API keys, or connecting to local, offline models (e.g., Ollama).
+
+**Note**: This free testing LLM API processes data via servers located in Mainland China. If you are located in a region with strict data localization laws (such as the EU/EEA), please do not use this API.
+
+**Age Requirement**: The software and testing API are not intended for use by individuals under the age of 13 (or the minimum age of digital consent in your jurisdiction).
 
 ---
 
@@ -49,19 +51,19 @@ The extension performs DOM analysis and automation actions **locally in your bro
 Data is transmitted to external servers **only when you initiate an automation task**. When this occurs:
 
 - Your task instructions (natural language commands)
-- Simplified page structure (cleaned DOM) of all pages under the extension's control
+- Simplified page structure (cleaned HTML) of all pages under the extension's control
 
 are sent to the LLM API endpoint configured in **your settings**.
 
-> **Note:** The DOM cleaning process simplifies page structure for AI readability but **does not guarantee removal of sensitive information** (e.g., visible text, form values, or personal data on the page). Please be mindful of the page content when initiating tasks.
+> **Note:** The HTML cleaning process simplifies page structure for AI readability but **does not guarantee removal of sensitive information** (e.g., visible text, form values, or personal data on the page). Please be mindful of the page content when initiating tasks.
 
 **If you configure a third-party LLM provider** (e.g., OpenAI, Anthropic, or others), data is sent directly to that provider. Their privacy policies apply.
 
-**If you use the built-in testing API**, the terms in [Section 2](#2-testing-api-and-demo-disclaimer--terms-of-use) apply. By using the extension with the default testing API, you agree to those terms.
+**If you use the testing API**, the terms in [Section 2](#2-testing-api-and-demo-disclaimer--terms-of-use) apply. By using the extension with the default testing API, you agree to those terms.
 
 ### Data Storage
 
-- **Local storage only**: Your configuration (API endpoint, API key, model selection) is stored in your browser via `chrome.storage.local`
+- **Local storage only**: Your configuration (API endpoint, API key, model selection) is stored in your browser via `chrome.storage.local` (or equivalent browser storage APIs)
 - **No cloud sync**: Configuration is not synced to any external server
 - **No analytics**: The extension does not include any analytics or tracking code
 
@@ -76,7 +78,7 @@ are sent to the LLM API endpoint configured in **your settings**.
 
 ## Changes
 
-We may update these terms as the project evolves.
+We may update these terms at our discretion.
 
 ## Contact
 

eslint.config.js

@@ -1,8 +1,5 @@
+import eslintReact from '@eslint-react/eslint-plugin'
 import js from '@eslint/js'
-import reactDom from 'eslint-plugin-react-dom'
-import reactHooks from 'eslint-plugin-react-hooks'
-import reactRefresh from 'eslint-plugin-react-refresh'
-import reactX from 'eslint-plugin-react-x'
 import { defineConfig, globalIgnores } from 'eslint/config'
 import globals from 'globals'
 import tseslint from 'typescript-eslint'
@@ -15,44 +12,24 @@ export default defineConfig([
 		'**/.wxt',
 		'**/.output',
 	]),
-	{
-		plugins: {
-			'react-hooks': reactHooks,
-		},
-		rules: reactHooks.configs.recommended.rules,
-	},
 	{
 		files: ['**/*.{ts,tsx}'],
 		extends: [
 			js.configs.recommended,
 			tseslint.configs.recommended,
-			// reactHooks.configs['recommended-latest'],
-			reactRefresh.configs.vite,
-
-			// Remove tseslint.configs.recommended and replace with this
 			...tseslint.configs.recommendedTypeChecked,
-			// Alternatively, use this for stricter rules
 			...tseslint.configs.strictTypeChecked,
-			// Optionally, add this for stylistic rules
 			...tseslint.configs.stylisticTypeChecked,
-
-			// Enable lint rules for React
-			reactX.configs['recommended-typescript'],
-			// Enable lint rules for React DOM
-			reactDom.configs.recommended,
+			eslintReact.configs['recommended-typescript'],
 		],
 		languageOptions: {
 			parserOptions: {
-				// project: ['./tsconfig.json'],
-				// project: ['./packages/*/tsconfig.json'],
-				// tsconfigRootDir: import.meta.dirname,
 				projectService: true,
 			},
 			ecmaVersion: 2020,
 			globals: globals.browser,
 		},
 		rules: {
-			// Add any additional rules here
 			'@typescript-eslint/no-non-null-assertion': 'off',
 			'@typescript-eslint/no-unsafe-assignment': 'off',
 			'@typescript-eslint/no-unsafe-member-access': 'off',
@@ -72,14 +49,15 @@ export default defineConfig([
 			'@typescript-eslint/no-unsafe-argument': 'off',
 			'@typescript-eslint/no-unsafe-return': 'off',
 			'@typescript-eslint/restrict-plus-operands': 'off',
-			'react-dom/no-missing-button-type': 'off',
-			'react-x/no-nested-component-definitions': 'off',
 			'@typescript-eslint/prefer-optional-chain': 'off',
 			'@typescript-eslint/use-unknown-in-catch-callback-variable': 'off',
 			'@typescript-eslint/no-unnecessary-type-parameters': 'off',
-
-			// 'require-await': 'off',
 			'@typescript-eslint/require-await': 'off',
+			'@typescript-eslint/no-deprecated': 'off',
+			'@eslint-react/dom-no-missing-button-type': 'off',
+			'@eslint-react/no-nested-component-definitions': 'off',
+			'@eslint-react/no-array-index-key': 'off',
+			'@eslint-react/dom-no-dangerously-set-innerhtml': 'off',
 		},
 	},
 ])

package.json

@@ -1,7 +1,7 @@
 {
     "name": "root",
     "private": true,
-    "version": "1.5.2",
+    "version": "1.11.0",
     "type": "module",
     "workspaces": [
         "packages/page-controller",
@@ -9,6 +9,7 @@
         "packages/llms",
         "packages/core",
         "packages/page-agent",
+        "packages/mcp",
         "packages/extension",
         "packages/website"
     ],
@@ -21,50 +22,54 @@
     },
     "homepage": "https://alibaba.github.io/page-agent/",
     "engines": {
-        "node": "^20.19.0 || ^22.13.0 || >=24"
+        "node": "^22.22.1 || >=24",
+        "npm": "^11.6.3"
     },
     "scripts": {
-        "cleanup": "rm -rf packages/*/dist",
         "start": "npm run dev --workspace=@page-agent/website",
-        "build:website": "npm run build:website --workspace=@page-agent/website",
-        "build:libs": "npm run build --workspaces --if-present",
-        "build": "npm run build:libs && npm run build:website",
+        "dev:ext": "npm run dev -w @page-agent/ext",
         "dev:demo": "npm run dev:demo --workspace=page-agent",
+        "build": "node scripts/build.js",
+        "build:libs": "node scripts/build-libs.js",
+        "build:website": "npm run build:website --workspace=@page-agent/website",
+        "build:ext": "npm run zip -w @page-agent/ext",
         "version": "node scripts/sync-version.js",
+        "postpublish": "npm run postpublish --workspaces --if-present",
+        "typecheck": "tsc --noEmit -p tsconfig.typecheck.json && tsc --noEmit -p packages/extension/tsconfig.json",
+        "test": "npm test --workspaces --if-present",
         "lint": "eslint .",
-        "prepare": "husky"
+        "ci": "node scripts/ci.js",
+        "cleanup": "rm -rf packages/*/dist && rm -rf packages/*/.output",
+        "prepare": "husky || true"
     },
     "devDependencies": {
-        "@commitlint/cli": "^20.4.2",
-        "@commitlint/config-conventional": "^20.4.2",
-        "@eslint/js": "^9.39.2",
-        "@microsoft/api-extractor": "^7.57.6",
-        "@tailwindcss/vite": "^4.2.1",
+        "@commitlint/cli": "^21.2.0",
+        "@commitlint/config-conventional": "^21.2.0",
+        "@eslint-react/eslint-plugin": "^5.10.0",
+        "@eslint/js": "^10.0.1",
+        "@microsoft/api-extractor": "^7.58.9",
+        "@tailwindcss/vite": "^4.3.2",
         "@trivago/prettier-plugin-sort-imports": "^6.0.2",
-        "@types/node": "^25.3.3",
-        "@vitejs/plugin-react-swc": "^4.1.0",
+        "@types/node": "^26.0.1",
+        "@vitejs/plugin-react": "^6.0.3",
         "chalk": "^5.6.2",
-        "concurrently": "^9.2.1",
-        "dotenv": "^17.3.1",
-        "eslint": "^9.39.2",
-        "eslint-config-prettier": "^10.1.8",
-        "eslint-plugin-react-dom": "^2.13.0",
-        "eslint-plugin-react-hooks": "^7.0.1",
-        "eslint-plugin-react-refresh": "^0.5.2",
-        "eslint-plugin-react-x": "^2.13.0",
-        "globals": "^17.4.0",
+        "concurrently": "^10.0.3",
+        "dotenv": "^17.4.2",
+        "eslint": "^10.6.0",
+        "globals": "^17.7.0",
+        "happy-dom": "^20.10.6",
         "husky": "^9.1.7",
-        "lint-staged": "^16.3.1",
-        "prettier": "^3.8.0",
-        "typescript": "^5.9.3",
-        "typescript-eslint": "^8.56.1",
-        "unplugin-dts": "^1.0.0-beta.6",
-        "vite": "^7.3.1",
-        "vite-plugin-css-injected-by-js": "^4.0.1",
-        "vite-bundle-analyzer": "^1.3.6"
+        "lint-staged": "^17.0.8",
+        "prettier": "^3.9.4",
+        "typescript": "^6.0.3",
+        "typescript-eslint": "^8.62.1",
+        "unplugin-dts": "^1.0.3",
+        "vite": "^8.1.2",
+        "vite-plugin-css-injected-by-js": "^5.0.1",
+        "vitest": "^4.1.9"
     },
     "overrides": {
-        "typescript": "^5.9.3"
+        "typescript": "^6.0.3"
     },
     "lint-staged": {
         "*.{js,ts,cjs,cts,mjs,mts}": [

packages/core/package.json

@@ -1,16 +1,26 @@
 {
     "name": "@page-agent/core",
     "private": false,
-    "version": "1.5.2",
+    "version": "1.11.0",
     "type": "module",
-    "main": "./dist/esm/page-agent-core.js",
-    "module": "./dist/esm/page-agent-core.js",
-    "types": "./dist/esm/PageAgentCore.d.ts",
+    "main": "./src/PageAgentCore.ts",
+    "types": "./src/PageAgentCore.ts",
     "exports": {
         ".": {
-            "types": "./dist/esm/PageAgentCore.d.ts",
-            "import": "./dist/esm/page-agent-core.js",
-            "default": "./dist/esm/page-agent-core.js"
+            "types": "./src/PageAgentCore.ts",
+            "default": "./src/PageAgentCore.ts"
+        }
+    },
+    "publishConfig": {
+        "main": "./dist/esm/page-agent-core.js",
+        "module": "./dist/esm/page-agent-core.js",
+        "types": "./dist/esm/PageAgentCore.d.ts",
+        "exports": {
+            ".": {
+                "types": "./dist/esm/PageAgentCore.d.ts",
+                "import": "./dist/esm/page-agent-core.js",
+                "default": "./dist/esm/page-agent-core.js"
+            }
         }
     },
     "files": [
@@ -38,19 +48,20 @@
     "homepage": "https://alibaba.github.io/page-agent/",
     "scripts": {
         "build": "vite build",
+        "test": "vitest run",
         "dev:iife": "concurrently \"vite build --config vite.iife.config.js --watch\" \"npx serve dist/iife -p 5174\"",
-        "prepublishOnly": "node -e \"const fs=require('fs');['README.md','LICENSE'].forEach(f=>fs.copyFileSync('../../'+f,f))\"",
-        "postpublish": "node -e \"['README.md','LICENSE'].forEach(f=>{try{require('fs').unlinkSync(f)}catch{}})\""
+        "prepublishOnly": "node ../../scripts/pre-publish.js",
+        "postpublish": "node ../../scripts/post-publish.js"
     },
     "dependencies": {
         "chalk": "^5.6.2",
-        "@page-agent/llms": "1.5.2",
-        "@page-agent/page-controller": "1.5.2"
+        "@page-agent/llms": "1.11.0",
+        "@page-agent/page-controller": "1.11.0"
     },
     "peerDependencies": {
         "zod": "^3.25.0 || ^4.0.0"
     },
     "devDependencies": {
-        "zod": "^4.3.5"
+        "zod": "^4.4.3"
     }
 }

packages/core/src/PageAgentCore.test.ts

@@ -0,0 +1,365 @@
+import type { BrowserState, PageController } from '@page-agent/page-controller'
+import { describe, expect, it, vi } from 'vitest'
+import * as z from 'zod/v4'
+
+import { PageAgentCore, tool } from './PageAgentCore'
+import type { ExecutionResult } from './types'
+
+type TestFetch = (...args: Parameters<typeof globalThis.fetch>) => Promise<Response>
+
+function agentResponse(args: unknown): Response {
+	return new Response(
+		JSON.stringify({
+			choices: [
+				{
+					finish_reason: 'tool_calls',
+					message: {
+						tool_calls: [
+							{
+								function: {
+									name: 'AgentOutput',
+									arguments: JSON.stringify(args),
+								},
+							},
+						],
+					},
+				},
+			],
+			usage: {},
+		})
+	)
+}
+
+function createPageController(): PageController {
+	const browserState: BrowserState = {
+		url: 'https://example.test/',
+		title: 'Test page',
+		header: '',
+		content: '',
+		footer: '',
+	}
+
+	return {
+		showMask: vi.fn(async () => {}),
+		hideMask: vi.fn(),
+		cleanUpHighlights: vi.fn(),
+		getLastUpdateTime: vi.fn(() => Date.now()),
+		getBrowserState: vi.fn(async () => browserState),
+		dispose: vi.fn(),
+	} as unknown as PageController
+}
+
+function createAgent(
+	customFetch: TestFetch,
+	options: Partial<ConstructorParameters<typeof PageAgentCore>[0]> = {}
+): PageAgentCore {
+	return new PageAgentCore({
+		baseURL: 'https://llm.test',
+		model: 'test-model',
+		maxRetries: 0,
+		stepDelay: 0,
+		customFetch,
+		customSystemPrompt: 'test',
+		pageController: createPageController(),
+		...options,
+	})
+}
+
+function createFetchMock() {
+	return vi.fn<TestFetch>()
+}
+
+function onceActivity(
+	agent: PageAgentCore,
+	predicate: (detail: unknown) => boolean
+): Promise<void> {
+	return new Promise((resolve) => {
+		const onActivity = (event: Event) => {
+			if (!predicate((event as CustomEvent).detail)) return
+			agent.removeEventListener('activity', onActivity)
+			resolve()
+		}
+
+		agent.addEventListener('activity', onActivity)
+	})
+}
+
+function isExecutingTool(detail: unknown, toolName: string): boolean {
+	return (
+		typeof detail === 'object' &&
+		detail !== null &&
+		'type' in detail &&
+		'tool' in detail &&
+		detail.type === 'executing' &&
+		detail.tool === toolName
+	)
+}
+
+function doneResponse(text: string, success = true): Response {
+	return agentResponse({ action: { done: { text, success } } })
+}
+
+function waitResponse(seconds = 10): Response {
+	return agentResponse({ action: { wait: { seconds } } })
+}
+
+/**
+ * Start a task that blocks on `wait`, returning once the tool is executing.
+ * The running promise is wrapped so awaiting this helper does not await the task.
+ */
+async function startBlockedTask(
+	agent: PageAgentCore,
+	task = 'first'
+): Promise<{ result: Promise<ExecutionResult> }> {
+	const waitStarted = onceActivity(agent, (detail) => isExecutingTool(detail, 'wait'))
+	const result = agent.execute(task)
+	await waitStarted
+	return { result }
+}
+
+describe.concurrent('PageAgentCore lifecycle', () => {
+	describe('normal execution', () => {
+		it('runs a task to natural completion', async () => {
+			const fetchMock = createFetchMock().mockResolvedValueOnce(doneResponse('all done'))
+			const agent = createAgent(fetchMock)
+
+			const result = await agent.execute('do something')
+
+			expect(result).toMatchObject({ success: true, data: 'all done' })
+			expect(agent.status).toBe('completed')
+			expect(fetchMock).toHaveBeenCalledTimes(1)
+		})
+
+		it('completes (not errors) when the LLM reports task failure', async () => {
+			const fetchMock = createFetchMock().mockResolvedValueOnce(doneResponse('gave up', false))
+			const agent = createAgent(fetchMock)
+
+			const result = await agent.execute('do something')
+
+			expect(result).toMatchObject({ success: false, data: 'gave up' })
+			expect(agent.status).toBe('completed')
+		})
+
+		it('throws when a task is already running', async () => {
+			const fetchMock = createFetchMock().mockResolvedValueOnce(waitResponse())
+			const agent = createAgent(fetchMock)
+			const { result } = await startBlockedTask(agent)
+
+			await expect(agent.execute('second')).rejects.toThrow('A task is already running.')
+
+			await agent.stop()
+			await result
+		})
+	})
+
+	describe('stop', () => {
+		it('aborts the running task and keeps the agent reusable', async () => {
+			const fetchMock = createFetchMock()
+				.mockResolvedValueOnce(waitResponse())
+				.mockResolvedValueOnce(doneResponse('second task'))
+			const agent = createAgent(fetchMock)
+			const { result: firstTask } = await startBlockedTask(agent)
+
+			await agent.stop()
+			expect(agent.status).toBe('stopped')
+			await expect(firstTask).resolves.toMatchObject({ success: false, data: 'Task aborted' })
+
+			const secondTask = await agent.execute('second')
+			expect(secondTask).toMatchObject({ success: true, data: 'second task' })
+			expect(agent.status).toBe('completed')
+		})
+
+		it('resolves only after the run has fully settled', async () => {
+			const fetchMock = createFetchMock().mockResolvedValueOnce(waitResponse())
+			const agent = createAgent(fetchMock)
+			const { result } = await startBlockedTask(agent)
+
+			await agent.stop()
+			expect(agent.status).toBe('stopped')
+			await expect(result).resolves.toMatchObject({ success: false })
+		})
+
+		it('is a no-op when no task is running', async () => {
+			const agent = createAgent(createFetchMock())
+
+			await expect(agent.stop()).resolves.toBeUndefined()
+			await expect(agent.stop()).resolves.toBeUndefined()
+			expect(agent.status).toBe('idle')
+		})
+	})
+
+	describe('dispose', () => {
+		it('aborts the running task and blocks further execution', async () => {
+			const fetchMock = createFetchMock().mockResolvedValueOnce(waitResponse())
+			const agent = createAgent(fetchMock)
+			const { result: task } = await startBlockedTask(agent)
+
+			agent.dispose()
+			await expect(task).resolves.toMatchObject({ success: false, data: 'Task aborted' })
+
+			expect(agent.disposed).toBe(true)
+			await expect(agent.execute('again')).rejects.toThrow('has been disposed')
+		})
+
+		it('is idempotent', () => {
+			const agent = createAgent(createFetchMock())
+
+			expect(() => {
+				agent.dispose()
+				agent.dispose()
+			}).not.toThrow()
+			expect(agent.disposed).toBe(true)
+		})
+	})
+
+	describe('error handling', () => {
+		it('fails the task when the network request rejects', async () => {
+			const fetchMock = createFetchMock().mockRejectedValue(new Error('network down'))
+			const agent = createAgent(fetchMock)
+
+			const result = await agent.execute('do something')
+
+			expect(result.success).toBe(false)
+			expect(agent.status).toBe('error')
+		})
+
+		it('fails the task when a tool throws', async () => {
+			const fetchMock = createFetchMock().mockResolvedValue(agentResponse({ action: { boom: {} } }))
+			const agent = createAgent(fetchMock, {
+				customTools: {
+					boom: tool({
+						description: 'Always throws.',
+						inputSchema: z.object({}),
+						execute: async () => {
+							throw new Error('tool exploded')
+						},
+					}),
+				},
+			})
+
+			const result = await agent.execute('trigger tool error')
+
+			expect(result.success).toBe(false)
+			expect(agent.status).toBe('error')
+		})
+
+		it('re-throws and sets error status when onBeforeTask throws', async () => {
+			const agent = createAgent(createFetchMock(), {
+				onBeforeTask: async () => {
+					throw new Error('setup failed')
+				},
+			})
+
+			await expect(agent.execute('do something')).rejects.toThrow('setup failed')
+			expect(agent.status).toBe('error')
+			expect(agent.history.some((e) => e.type === 'error')).toBe(false)
+		})
+
+		it('re-throws and sets error status when onAfterTask throws', async () => {
+			const fetchMock = createFetchMock().mockResolvedValueOnce(doneResponse('all done'))
+			const agent = createAgent(fetchMock, {
+				onAfterTask: async () => {
+					throw new Error('teardown failed')
+				},
+			})
+
+			await expect(agent.execute('do something')).rejects.toThrow('teardown failed')
+			expect(agent.status).toBe('error')
+		})
+
+		it('stays reusable after onBeforeTask throws', async () => {
+			const fetchMock = createFetchMock().mockResolvedValueOnce(doneResponse('second'))
+			let failOnce = true
+			const agent = createAgent(fetchMock, {
+				onBeforeTask: async () => {
+					if (failOnce) {
+						failOnce = false
+						throw new Error('setup failed')
+					}
+				},
+			})
+
+			await expect(agent.execute('first')).rejects.toThrow('setup failed')
+			const result = await agent.execute('second')
+			expect(result).toMatchObject({ success: true, data: 'second' })
+		})
+
+		it('re-throws and sets error status when onBeforeStep throws', async () => {
+			const agent = createAgent(createFetchMock(), {
+				onBeforeStep: async () => {
+					throw new Error('before step failed')
+				},
+			})
+
+			await expect(agent.execute('do something')).rejects.toThrow('before step failed')
+			expect(agent.status).toBe('error')
+			expect(agent.history.some((e) => e.type === 'error')).toBe(false)
+		})
+
+		it('re-throws and sets error status when onAfterStep throws', async () => {
+			const fetchMock = createFetchMock().mockResolvedValueOnce(doneResponse('all done'))
+			const agent = createAgent(fetchMock, {
+				onAfterStep: async () => {
+					throw new Error('after step failed')
+				},
+			})
+
+			await expect(agent.execute('do something')).rejects.toThrow('after step failed')
+			expect(agent.status).toBe('error')
+			expect(agent.history.some((e) => e.type === 'error')).toBe(false)
+		})
+	})
+
+	describe('cancellation edge cases', () => {
+		it('rejects a new task while a stop is still settling', async () => {
+			const fetchMock = createFetchMock().mockResolvedValueOnce(waitResponse())
+			const agent = createAgent(fetchMock)
+			const { result: firstTask } = await startBlockedTask(agent)
+
+			const stopped = agent.stop()
+
+			await expect(agent.execute('too early')).rejects.toThrow('A task is already running.')
+
+			await stopped
+			await expect(firstTask).resolves.toMatchObject({ success: false, data: 'Task aborted' })
+			expect(fetchMock).toHaveBeenCalledTimes(1)
+		})
+
+		it('discards a custom tool result that resolves after stop', async () => {
+			let resolveTool!: () => void
+			let notifyToolStarted!: () => void
+			const toolFinished = new Promise<void>((resolve) => {
+				resolveTool = resolve
+			})
+			const toolStarted = new Promise<void>((resolve) => {
+				notifyToolStarted = resolve
+			})
+			const fetchMock = createFetchMock().mockResolvedValue(
+				agentResponse({ action: { slow_tool: {} } })
+			)
+			const agent = createAgent(fetchMock, {
+				customTools: {
+					slow_tool: tool({
+						description: 'A tool that deliberately ignores cancellation.',
+						inputSchema: z.object({}),
+						execute: async () => {
+							notifyToolStarted()
+							await toolFinished
+							return 'ignored stop'
+						},
+					}),
+				},
+			})
+
+			const task = agent.execute('run slow tool')
+			await toolStarted
+
+			const stopped = agent.stop()
+			resolveTool()
+			await stopped
+
+			await expect(task).resolves.toMatchObject({ success: false, data: 'Task aborted' })
+			expect(agent.status).toBe('stopped')
+		})
+	})
+})

packages/core/src/PageAgentCore.ts

@@ -1,5 +1,6 @@
 /**
  * Copyright (C) 2025 Alibaba Group Holding Limited
+ * Copyright (C) 2026 SimonLuvRamen
  * All rights reserved.
  */
 import { InvokeError, LLM, type Tool } from '@page-agent/llms'
@@ -20,7 +21,7 @@ import type {
 	MacroToolInput,
 	MacroToolResult,
 } from './types'
-import { assert, fetchLlmsTxt, normalizeResponse, uid, waitFor } from './utils'
+import { assert, fetchLlmsTxt, normalizeResponse, suppress, uid, waitFor } from './utils'
 
 export { tool, type PageAgentTool } from './tools'
 export type * from './types'
@@ -41,7 +42,7 @@ export type PageAgentCoreConfig = AgentConfig & { pageController: PageController
  * - loop
  *
  * ## Event System
- * - `statuschange` - Agent status transitions (idle → running → completed/error)
+ * - `statuschange` - Agent status transitions (idle → running → completed/error/stopped)
  * - `historychange` - History events updated (persistent, part of agent memory)
  * - `activity` - Real-time activity feedback (transient, for UI only)
  * - `dispose` - Agent cleanup triggered
@@ -72,17 +73,28 @@ export class PageAgentCore extends EventTarget {
 	disposed = false
 
 	/**
-	 * Callback for when agent needs user input (ask_user tool)
-	 * If not set, ask_user tool will be disabled
+	 * Called when the agent needs to ask the user questions.
+	 * If unset, the `ask_user` tool will be disabled.
+	 * Implementations should reject the promise when `signal` aborts.
 	 * @example onAskUser: (q) => window.prompt(q) || ''
 	 */
-	onAskUser?: (question: string) => Promise<string>
+	onAskUser?: (question: string, options?: { signal: AbortSignal }) => Promise<string>
 
 	#status: AgentStatus = 'idle'
 	#llm: LLM
+	/**
+	 * Task cancellation primitive: its signal reaches the LLM fetch, tools
+	 * (via `ctx.signal`) and async callbacks. Aborted only by `stop`/`dispose`
+	 * (during a task) or task setup, always WITHOUT a reason so `signal.reason`
+	 * stays a standard `AbortError`.
+	 */
 	#abortController = new AbortController()
 	#observations: string[] = []
 
+	/** Resolves when the current run has fully settled. Awaited by `stop()`. */
+	#running: Promise<void> = Promise.resolve()
+	#lastResult: ExecutionResult | null = null
+
 	/** internal states during a single task execution */
 	#states = {
 		/** Accumulated wait time in seconds */
@@ -102,11 +114,14 @@ export class PageAgentCore extends EventTarget {
 		this.tools = new Map(tools)
 		this.pageController = config.pageController
 
-		// Listen to LLM retry events
 		this.#llm.addEventListener('retry', (e) => {
-			const { attempt, maxAttempts } = (e as CustomEvent).detail
+			const { attempt, maxAttempts, lastError } = (e as CustomEvent).detail
 			this.#emitActivity({ type: 'retrying', attempt, maxAttempts })
-			// Also push to history for panel rendering
+			this.history.push({
+				type: 'error',
+				message: String(lastError),
+				rawResponse: (lastError as InvokeError).rawResponse,
+			})
 			this.history.push({
 				type: 'retry',
 				message: `LLM retry attempt ${attempt} of ${maxAttempts}`,
@@ -115,19 +130,6 @@ export class PageAgentCore extends EventTarget {
 			})
 			this.#emitHistoryChange()
 		})
-		this.#llm.addEventListener('error', (e) => {
-			const error = (e as CustomEvent).detail.error as Error | InvokeError
-			if ((error as any)?.rawError?.name === 'AbortError') return
-			const message = String(error)
-			this.#emitActivity({ type: 'error', message })
-			// Also push to history for panel rendering
-			this.history.push({
-				type: 'error',
-				message,
-				rawResponse: (error as InvokeError).rawResponse,
-			})
-			this.#emitHistoryChange()
-		})
 
 		if (this.config.customTools) {
 			for (const [name, tool] of Object.entries(this.config.customTools)) {
@@ -149,13 +151,19 @@ export class PageAgentCore extends EventTarget {
 		return this.#status
 	}
 
+	/** Result of the most recent run, or `null` before the first run completes. */
+	get lastResult(): ExecutionResult | null {
+		return this.#lastResult
+	}
+
 	/** Emit statuschange event */
 	#emitStatusChange(): void {
 		this.dispatchEvent(new Event('statuschange'))
 	}
 
 	/** Emit historychange event */
-	#emitHistoryChange(): void {
+	#emitHistoryChange(pushHistoricalEvent?: HistoricalEvent): void {
+		if (pushHistoricalEvent) this.history.push(pushHistoricalEvent)
 		this.dispatchEvent(new Event('historychange'))
 	}
 
@@ -176,7 +184,7 @@ export class PageAgentCore extends EventTarget {
 	}
 
 	/**
-	 * Push a observation message to the history event stream.
+	 * Push an observation message to the history event stream.
 	 * This will be visible in <agent_history> and remain persistent in memory across steps.
 	 * @experimental @internal
 	 * @note history change will be emitted before next step starts
@@ -185,165 +193,184 @@ export class PageAgentCore extends EventTarget {
 		this.#observations.push(content)
 	}
 
-	/** Stop the current task. Agent remains reusable. */
-	stop() {
-		this.pageController.cleanUpHighlights()
-		this.pageController.hideMask()
+	/**
+	 * Stop the current task and wait until the run has fully settled (including lifecycle hooks).
+	 * @note never await .stop() in a lifecycle hook.
+	 */
+	async stop(): Promise<void> {
+		if (this.#status !== 'running') return
 		this.#abortController.abort()
+		await this.#running
 	}
 
+	/**
+	 * external errors (pre-checks/config/hooks) will threw;
+	 * agent errors will be caught and added to history, and return a failed result
+	 */
 	async execute(task: string): Promise<ExecutionResult> {
+		// pre-checks
 		if (this.disposed) throw new Error('PageAgent has been disposed. Create a new instance.')
+		if (this.#status === 'running') throw new Error('A task is already running.')
 		if (!task) throw new Error('Task is required')
+
 		this.task = task
 		this.taskId = uid()
 
+		this.history = []
+		this.#observations = []
+		this.#states = { totalWaitTime: 0, lastURL: '', browserState: null }
+		this.#abortController = new AbortController()
+		const signal = this.#abortController.signal
+
+		let resolveRunning!: () => void
+		this.#running = new Promise<void>((r) => (resolveRunning = r))
+
+		this.#setStatus('running')
+		this.#emitHistoryChange()
+
 		// Disable ask_user tool if onAskUser is not set
-		if (!this.onAskUser) {
-			this.tools.delete('ask_user')
-		}
+		if (!this.onAskUser) this.tools.delete('ask_user')
 
 		const onBeforeStep = this.config.onBeforeStep
 		const onAfterStep = this.config.onAfterStep
 		const onBeforeTask = this.config.onBeforeTask
 		const onAfterTask = this.config.onAfterTask
-
-		await onBeforeTask?.(this)
-
-		// Show mask
-		await this.pageController.showMask()
-
-		if (this.#abortController) {
-			this.#abortController.abort()
-			this.#abortController = new AbortController()
-		}
-
-		this.history = []
-		this.#setStatus('running')
-		this.#emitHistoryChange()
-		this.#observations = []
-
-		// Reset internal states
-		this.#states = { totalWaitTime: 0, lastURL: '', browserState: null }
+		const stepDelay = this.config.stepDelay ?? 0.4
+		const maxSteps = this.config.maxSteps
 
 		let step = 0
+		let taskResult: ExecutionResult
+		let finalStatus: AgentStatus = 'error'
 
-		while (true) {
-			try {
-				console.group(`step: ${step}`)
+		await suppress(() => this.pageController.showMask())
 
+		// graceful exit
+		try {
+			await onBeforeTask?.(this)
+
+			while (true) {
 				await onBeforeStep?.(this, step)
 
-				// observe
+				// handle internal agent errors
+				try {
+					console.group(`step: ${step}`)
 
-				console.log(chalk.blue.bold('👀 Observing...'))
+					// @note It's convenient to treat stepDelay as part of the next step.
+					// Maybe move it to a dedicated try block for better semantics?
+					if (step > 0) await waitFor(stepDelay, signal)
 
-				this.#states.browserState = await this.pageController.getBrowserState()
-				await this.#handleObservations(step)
+					signal.throwIfAborted()
 
-				// assemble prompts
+					// observe
 
-				const messages = [
-					{ role: 'system' as const, content: this.#getSystemPrompt() },
-					{ role: 'user' as const, content: await this.#assembleUserPrompt() },
-				]
+					console.log(chalk.blue.bold('👀 Observing...'))
 
-				const macroTool = { AgentOutput: this.#packMacroTool() }
+					this.#states.browserState = await this.pageController.getBrowserState()
+					await this.#handleObservations(step)
 
-				// invoke LLM
+					// assemble prompts
 
-				console.log(chalk.blue.bold('🧠 Thinking...'))
-				this.#emitActivity({ type: 'thinking' })
+					const messages = [
+						{ role: 'system' as const, content: this.#getSystemPrompt() },
+						{ role: 'user' as const, content: await this.#assembleUserPrompt() },
+					]
 
-				const result = await this.#llm.invoke(messages, macroTool, this.#abortController.signal, {
-					toolChoiceName: 'AgentOutput',
-					normalizeResponse: (res) => normalizeResponse(res, this.tools),
-				})
+					const macroTool = { AgentOutput: this.#packMacroTool() }
 
-				// assemble history
+					// invoke LLM
 
-				const macroResult = result.toolResult as MacroToolResult
-				const input = macroResult.input
-				const output = macroResult.output
-				const reflection: Partial<AgentReflection> = {
-					evaluation_previous_goal: input.evaluation_previous_goal,
-					memory: input.memory,
-					next_goal: input.next_goal,
-				}
-				const actionName = Object.keys(input.action)[0]
-				const action: AgentStepEvent['action'] = {
-					name: actionName,
-					input: input.action[actionName],
-					output: output,
-				}
+					console.log(chalk.blue.bold('🧠 Thinking...'))
+					this.#emitActivity({ type: 'thinking' })
 
-				this.history.push({
-					type: 'step',
-					stepIndex: step,
-					reflection,
-					action,
-					usage: result.usage,
-					rawResponse: result.rawResponse,
-					rawRequest: result.rawRequest,
-				} as AgentStepEvent)
-				this.#emitHistoryChange()
+					const result = await this.#llm.invoke(messages, macroTool, signal, {
+						toolChoiceName: 'AgentOutput',
+						normalizeResponse: (res) => normalizeResponse(res, this.tools),
+					})
 
-				//
+					// assemble history
 
-				await onAfterStep?.(this, this.history)
-
-				console.groupEnd()
-
-				// finish task if done
-
-				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)
-					this.#onDone(success)
-					const result: ExecutionResult = {
-						success,
-						data: text,
-						history: this.history,
+					const macroResult = result.toolResult as MacroToolResult
+					const input = macroResult.input
+					const output = macroResult.output
+					const reflection: Partial<AgentReflection> = {
+						evaluation_previous_goal: input.evaluation_previous_goal,
+						memory: input.memory,
+						next_goal: input.next_goal,
+					}
+					const actionName = Object.keys(input.action)[0]
+					const action: AgentStepEvent['action'] = {
+						name: actionName,
+						input: input.action[actionName],
+						output: output,
 					}
-					await onAfterTask?.(this, result)
-					return result
-				}
-			} catch (error: unknown) {
-				console.groupEnd() // to prevent nested groups
-				const isAbortError = (error as any)?.rawError?.name === 'AbortError'
 
-				console.error('Task failed', error)
-				const errorMessage = isAbortError ? 'Task stopped' : String(error)
-				this.#emitActivity({ type: 'error', message: errorMessage })
-				this.history.push({ type: 'error', message: errorMessage, rawResponse: error })
-				this.#emitHistoryChange()
-				this.#onDone(false)
-				const result: ExecutionResult = {
-					success: false,
-					data: errorMessage,
-					history: this.history,
-				}
-				await onAfterTask?.(this, result)
-				return result
-			}
+					this.#emitHistoryChange({
+						type: 'step',
+						stepIndex: step,
+						reflection,
+						action,
+						usage: result.usage,
+						rawResponse: result.rawResponse,
+						rawRequest: result.rawRequest,
+					})
 
-			step++
-			if (step > this.config.maxSteps) {
-				const errorMessage = 'Step count exceeded maximum limit'
-				this.history.push({ type: 'error', message: errorMessage })
-				this.#emitHistoryChange()
-				this.#onDone(false)
-				const result: ExecutionResult = {
-					success: false,
-					data: errorMessage,
-					history: this.history,
-				}
-				await onAfterTask?.(this, result)
-				return result
-			}
+					if (actionName === 'done') {
+						const success = action.input?.success ?? false
+						const data = action.input?.text || 'no text provided'
+						console.log(chalk.green.bold('Task completed'), success, data)
+						taskResult = { success, data, history: this.history }
+						this.#lastResult = taskResult
+						finalStatus = 'completed'
+						break
+					}
+				} catch (error: unknown) {
+					// catch block must not throw error. otherwise the error may be overridden if finally block also throws error.
 
-			await waitFor(0.4) // @TODO: configurable
+					const isAbortError = (error as any)?.name === 'AbortError'
+					if (!isAbortError) console.error('Task failed', error)
+					const message = isAbortError ? 'Task aborted' : String(error)
+					this.#emitActivity({ type: 'error', message: message })
+					this.#emitHistoryChange({ type: 'error', message: message, rawResponse: error })
+					taskResult = { success: false, data: message, history: this.history }
+					this.#lastResult = taskResult
+					finalStatus = isAbortError ? 'stopped' : 'error'
+					break
+				} finally {
+					// finally block runs before the break above.
+
+					console.groupEnd()
+					// @note hook may throw error.
+					// which will override the `break` above and be handled as an external error.
+					// as expected.
+					await onAfterStep?.(this, this.history)
+				}
+
+				step++
+				if (step > maxSteps) {
+					const message = 'Step count exceeded maximum limit'
+					console.error(message)
+					this.#emitActivity({ type: 'error', message: message })
+					this.#emitHistoryChange({ type: 'error', message: message })
+					taskResult = { success: false, data: message, history: this.history }
+					this.#lastResult = taskResult
+					finalStatus = 'error'
+					break
+				}
+			} // while
+
+			await onAfterTask?.(this, taskResult)
+
+			return taskResult
+		} catch (error) {
+			this.#emitActivity({ type: 'error', message: String(error) })
+			finalStatus = 'error'
+			throw error
+		} finally {
+			await suppress(() => this.pageController.cleanUpHighlights())
+			await suppress(() => this.pageController.hideMask())
+			this.#abortController.abort()
+			resolveRunning()
+			this.#setStatus(finalStatus)
 		}
 	}
 
@@ -377,8 +404,8 @@ export class PageAgentCore extends EventTarget {
 			description: 'You MUST call this tool every step!',
 			inputSchema: macroToolSchema as z.ZodType<MacroToolInput>,
 			execute: async (input: MacroToolInput): Promise<MacroToolResult> => {
-				// abort
-				if (this.#abortController.signal.aborted) throw new Error('AbortError')
+				const signal = this.#abortController.signal
+				signal.throwIfAborted()
 
 				console.log(chalk.blue.bold('MacroTool input'), input)
 				const action = input.action
@@ -410,8 +437,9 @@ export class PageAgentCore extends EventTarget {
 
 				const startTime = Date.now()
 
-				// Execute tool, bind `this` to PageAgent
-				const result = await tool.execute.bind(this)(toolInput)
+				const result = await tool.execute.bind(this)(toolInput, { signal })
+				// Enforce abort even if the tool ignored the signal and resolved normally.
+				signal.throwIfAborted()
 
 				const duration = Date.now() - startTime
 				console.log(chalk.green.bold(`Tool (${toolName}) executed for ${duration}ms`), result)
@@ -511,7 +539,8 @@ export class PageAgentCore extends EventTarget {
 		// Accumulated wait time warning
 		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.`
+				`You have waited ${this.#states.totalWaitTime} seconds accumulatively. ` +
+					`DO NOT wait any longer unless you have a good reason.`
 			)
 		}
 
@@ -527,7 +556,8 @@ export class PageAgentCore extends EventTarget {
 		const remaining = this.config.maxSteps - step
 		if (remaining === 5) {
 			this.pushObservation(
-				`⚠️ Only ${remaining} steps remaining. Consider wrapping up or calling done with partial results.`
+				`⚠️ Only ${remaining} steps remaining. ` +
+					`Consider wrapping up or calling done with partial results.`
 			)
 		} else if (remaining === 2) {
 			this.pushObservation(
@@ -616,13 +646,6 @@ export class PageAgentCore extends EventTarget {
 		return prompt
 	}
 
-	#onDone(success = true) {
-		this.pageController.cleanUpHighlights()
-		this.pageController.hideMask() // No await - fire and forget
-		this.#setStatus(success ? 'completed' : 'error')
-		this.#abortController.abort()
-	}
-
 	dispose() {
 		console.log('Disposing PageAgent...')
 		this.disposed = true

packages/core/src/prompts/.prettierignore

@@ -1 +0,0 @@
-system_prompt.md

packages/core/src/prompts/system_prompt.md

@@ -37,7 +37,7 @@ and system messages wrapped in <sys> tag.
 <user_request>
 USER REQUEST: This is your ultimate objective and always remains visible.
 - This has the highest priority. Make the user happy.
-- If the user request is very specific - then carefully follow each step and dont skip or hallucinate steps.
+- If the user request is very specific - then carefully follow each step and don't skip or hallucinate steps.
 - If the task is open ended you can plan yourself how to get it done.
 </user_request>
 
@@ -69,8 +69,7 @@ Strictly follow these rules while using the browser and navigating the web:
 - By default, only elements in the visible viewport are listed. Use scrolling actions if you suspect relevant content is offscreen which you need to interact with. Scroll ONLY if there are more pixels below or above the page.
 - You can scroll by a specific number of pages using the num_pages parameter (e.g., 0.5 for half page, 2.0 for two pages).
 - All the elements that are scrollable are marked with `data-scrollable` attribute. Including the scrollable distance in every directions. You can scroll *the element* in case some area are overflowed.
-- If a captcha appears, tell user you can not solve captcha. finished the task and ask user to solve it.
-- If expected elements are missing, try scrolling, or navigating back.
+- If a captcha appears, tell user you can not solve captcha. Finish the task and ask user to solve it.
 - If the page is not fully loaded, use the `wait` action.
 - Do not repeat one action for more than 3 times unless some conditions changed.
 - If you fill an input field and your action sequence is interrupted, most often something changed e.g. suggestions popped up under the field.
@@ -87,11 +86,11 @@ Strictly follow these rules while using the browser and navigating the web:
 
 <capability>
 - You can only handle single page app. Do not jump out of current page.
-- Do not click on link if it will open in a new page (etc. <a target="_blank">)
+- Do not click on link if it will open in a new page (e.g., <a target="_blank">)
 - It is ok to fail the task.
 	- User can be wrong. If the request of user is not achievable, inappropriate or you do not have enough information or tools to achieve it. Tell user to make a better request.
 	- Webpage can be broken. All webpages or apps have bugs. Some bug will make it hard for your job. It's encouraged to tell user the problem of current page. Your feedbacks (including failing) are valuable for user.
-	- Trying to hard can be harmful. Repeating some action back and forth or pushing for a complex procedure with little knowledge can cause unwanted result and harmful side-effects. User would rather you to complete the task with a fail.
+	- Trying too hard can be harmful. Repeating some action back and forth or pushing for a complex procedure with little knowledge can cause unwanted results and harmful side-effects. User would rather you complete the task with a fail.
 - If you do not have knowledge for the current webpage or task. You must require user to give specific instructions and detailed steps.
 </capability>
 

packages/core/src/tools/index.ts

@@ -7,6 +7,14 @@ import * as z from 'zod/v4'
 import type { PageAgentCore } from '../PageAgentCore'
 import { waitFor } from '../utils'
 
+/**
+ * Per-invocation context passed to every tool execution.
+ * Tools MUST honor `signal` to support cooperative cancellation.
+ */
+export interface ToolContext {
+	signal: AbortSignal
+}
+
 /**
  * Internal tool definition that has access to PageAgent `this` context
  */
@@ -14,7 +22,7 @@ export interface PageAgentTool<TParams = any> {
 	// name: string
 	description: string
 	inputSchema: z.ZodType<TParams>
-	execute: (this: PageAgentCore, args: TParams) => Promise<string>
+	execute: (this: PageAgentCore, args: TParams, ctx: ToolContext) => Promise<string>
 }
 
 export function tool<TParams>(options: PageAgentTool<TParams>): PageAgentTool<TParams> {
@@ -50,14 +58,16 @@ tools.set(
 		inputSchema: z.object({
 			seconds: z.number().min(1).max(10).default(1),
 		}),
-		execute: async function (this: PageAgentCore, input) {
+		execute: async function (this: PageAgentCore, input, { signal }) {
 			// try to subtract LLM calling time from the actual wait time
 			const lastTimeUpdate = await this.pageController.getLastUpdateTime()
-			const actualWaitTime = Math.max(0, input.seconds - (Date.now() - lastTimeUpdate) / 1000)
+			const secondsSinceLastUpdate = (Date.now() - lastTimeUpdate) / 1000
+			const actualWaitTime = Math.max(0, input.seconds - secondsSinceLastUpdate)
 			console.log(`actualWaitTime: ${actualWaitTime} seconds`)
-			await waitFor(actualWaitTime)
+			await waitFor(actualWaitTime, signal)
 
-			return `✅ Waited for ${input.seconds} seconds.`
+			const waitedSeconds = (secondsSinceLastUpdate + actualWaitTime).toFixed(2)
+			return `✅ Waited for ${waitedSeconds} seconds.`
 		},
 	})
 )
@@ -70,11 +80,11 @@ tools.set(
 		inputSchema: z.object({
 			question: z.string(),
 		}),
-		execute: async function (this: PageAgentCore, input) {
+		execute: async function (this: PageAgentCore, input, { signal }) {
 			if (!this.onAskUser) {
 				throw new Error('ask_user tool requires onAskUser callback to be set')
 			}
-			const answer = await this.onAskUser(input.question)
+			const answer = await this.onAskUser(input.question, { signal })
 			return `User answered: ${answer}`
 		},
 	})
@@ -131,7 +141,8 @@ tools.set(
 tools.set(
 	'scroll',
 	tool({
-		description: 'Scroll the page vertically. Use index for scroll elements (dropdowns/custom UI).',
+		description:
+			'Scroll vertically. Without index: scrolls the document. With index: scrolls the container at that index (or its nearest scrollable ancestor). Use index of a data-scrollable element to scroll a specific area.',
 		inputSchema: z.object({
 			down: z.boolean().default(true),
 			num_pages: z.number().min(0).max(10).optional().default(0.1),
@@ -155,7 +166,7 @@ tools.set(
 	'scroll_horizontally',
 	tool({
 		description:
-			'Scroll the page horizontally, or within a specific element by index. Useful for wide tables.',
+			'Scroll horizontally. Without index: scrolls the document. With index: scrolls the container at that index (or its nearest scrollable ancestor). Use index of a data-scrollable element to scroll a specific area.',
 		inputSchema: z.object({
 			right: z.boolean().default(true),
 			pixels: z.number().int().min(0),
@@ -172,12 +183,15 @@ tools.set(
 	'execute_javascript',
 	tool({
 		description:
-			'Execute JavaScript code on the current page. Supports async/await syntax. Use with caution!',
+			'Execute JavaScript code on the current page. Supports async/await syntax. Use with caution! ' +
+			'An `AbortSignal` named `signal` is available in scope: long-running async code MUST honor it ' +
+			'(e.g. `await fetch(url, { signal })`, or `signal.throwIfAborted()` in loops)',
 		inputSchema: z.object({
 			script: z.string(),
 		}),
-		execute: async function (this: PageAgentCore, input) {
-			const result = await this.pageController.executeJavascript(input.script)
+		execute: async function (this: PageAgentCore, input, { signal }) {
+			const result = await this.pageController.executeJavascript(input.script, signal)
+			signal.throwIfAborted()
 			return result.message
 		},
 	})
@@ -185,5 +199,4 @@ tools.set(
 
 // @todo send_keys
 // @todo upload_file
-// @todo go_back
 // @todo extract_structured_data

packages/core/src/types.ts

@@ -152,6 +152,12 @@ export interface AgentConfig extends LLMConfig {
 	 * @experimental Use with caution - incorrect prompts may break agent behavior.
 	 */
 	customSystemPrompt?: string
+
+	/**
+	 * Delay between steps in seconds.
+	 * @default 0.4
+	 */
+	stepDelay?: number
 }
 
 /**
@@ -249,16 +255,12 @@ export interface AgentErrorEvent {
  * Union type for all history events
  */
 export type HistoricalEvent =
-	| AgentStepEvent
-	| ObservationEvent
-	| UserTakeoverEvent
-	| RetryEvent
-	| AgentErrorEvent
+	AgentStepEvent | ObservationEvent | UserTakeoverEvent | RetryEvent | AgentErrorEvent
 
 /**
- * Agent execution status
+ * Agent lifecycle status.
  */
-export type AgentStatus = 'idle' | 'running' | 'completed' | 'error'
+export type AgentStatus = 'idle' | 'running' | 'completed' | 'error' | 'stopped'
 
 /**
  * Agent activity - transient state for immediate UI feedback.

packages/core/src/utils/autoFixer.ts

@@ -1,4 +1,4 @@
-import { InvokeError, InvokeErrorType } from '@page-agent/llms'
+import { InvokeError, InvokeErrorTypes } from '@page-agent/llms'
 import chalk from 'chalk'
 import * as z from 'zod/v4'
 
@@ -19,7 +19,7 @@ const log = console.log.bind(console, chalk.yellow('[autoFixer]'))
  * - etc.
  */
 export function normalizeResponse(response: any, tools?: Map<string, PageAgentTool>): any {
-	let resolvedArguments = null as any
+	let resolvedArguments: any
 
 	const choice = (response as { choices?: Choice[] }).choices?.[0]
 	if (!choice) throw new Error('No choices in response')
@@ -93,7 +93,7 @@ export function normalizeResponse(response: any, tools?: Map<string, PageAgentTo
 	// fix incomplete formats
 	if (!resolvedArguments.action) {
 		log(`#5: fixing tool_call`)
-		resolvedArguments.action = { name: 'wait', input: { seconds: 1 } }
+		resolvedArguments.action = { wait: { seconds: 1 } }
 	}
 
 	// pack back to standard format
@@ -137,7 +137,7 @@ function validateAction(action: any, tools: Map<string, PageAgentTool>): any {
 	if (!tool) {
 		const available = Array.from(tools.keys()).join(', ')
 		throw new InvokeError(
-			InvokeErrorType.INVALID_TOOL_ARGS,
+			InvokeErrorTypes.INVALID_TOOL_ARGS,
 			`Unknown action "${toolName}". Available: ${available}`
 		)
 	}
@@ -159,7 +159,7 @@ function validateAction(action: any, tools: Map<string, PageAgentTool>): any {
 	const result = schema.safeParse(value)
 	if (!result.success) {
 		throw new InvokeError(
-			InvokeErrorType.INVALID_TOOL_ARGS,
+			InvokeErrorTypes.INVALID_TOOL_ARGS,
 			`Invalid input for action "${toolName}": ${z.prettifyError(result.error)}`
 		)
 	}

packages/core/src/utils/index.ts

@@ -2,8 +2,28 @@ import chalk from 'chalk'
 
 export * from './autoFixer'
 
-export async function waitFor(seconds: number): Promise<void> {
-	await new Promise((resolve) => setTimeout(resolve, seconds * 1000))
+/**
+ * Wait for `seconds`. If a `signal` is provided, the wait is cancellable:
+ * aborting rejects with the signal's reason (an `AbortError`).
+ */
+export async function waitFor(seconds: number, signal?: AbortSignal): Promise<void> {
+	if (!signal) {
+		await new Promise((resolve) => setTimeout(resolve, seconds * 1000))
+		return
+	}
+	signal.throwIfAborted()
+	await new Promise<void>((resolve, reject) => {
+		const timer = setTimeout(() => {
+			signal.removeEventListener('abort', onAbort)
+			resolve()
+		}, seconds * 1000)
+		const onAbort = () => {
+			clearTimeout(timer)
+			// reason is a DOMException AbortError.
+			reject(signal.reason as DOMException)
+		}
+		signal.addEventListener('abort', onAbort, { once: true })
+	})
 }
 
 //
@@ -31,7 +51,7 @@ export function randomID(existingIDs?: string[]): string {
 		id = Math.random().toString(36).substring(2, 11)
 		tryCount++
 		if (tryCount > MAX_TRY) {
-			throw new Error('randomID: too many try')
+			throw new Error('randomID: too many tries')
 		}
 	}
 
@@ -61,7 +81,15 @@ const llmsTxtCache = new Map<string, string | null>()
 
 /** Fetch /llms.txt for a URL's origin. Cached per origin, `null` = tried and not found. */
 export async function fetchLlmsTxt(url: string): Promise<string | null> {
-	const origin = new URL(url).origin
+	let origin: string
+	try {
+		origin = new URL(url).origin
+	} catch {
+		return null // Invalid URL
+	}
+	// about:blank, data:, file:
+	if (origin === 'null') return null
+
 	if (llmsTxtCache.has(origin)) return llmsTxtCache.get(origin)!
 
 	const endpoint = `${origin}/llms.txt`
@@ -101,3 +129,15 @@ export function assert(condition: unknown, message?: string, silent?: boolean):
 		throw new Error(errorMessage)
 	}
 }
+
+/**
+ * Suppress errors from a function.
+ */
+export async function suppress<T>(fn: () => T | Promise<T>): Promise<Awaited<T> | undefined> {
+	try {
+		return await fn()
+	} catch (error) {
+		console.error(error)
+		return undefined
+	}
+}

packages/core/tsconfig.dts.json

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

packages/core/tsconfig.json

@@ -1,22 +1,8 @@
 {
     "extends": "../../tsconfig.base.json",
     "compilerOptions": {
-        "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo",
-        "noEmit": false,
-        "allowImportingTsExtensions": false,
-        "baseUrl": ".",
-        "outDir": "dist",
-        "paths": {
-            //
-            "@page-agent/llms": ["../llms/src/index.ts"],
-            "@page-agent/page-controller": ["../page-controller/src/PageController.ts"]
-        }
+        "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo"
     },
-    "include": ["**/*.ts"],
-    "exclude": ["dist", "node_modules"],
-    "references": [
-        //
-        { "path": "../llms" },
-        { "path": "../page-controller" }
-    ]
+    "include": ["src/**/*.ts"],
+    "exclude": ["dist", "node_modules"]
 }

packages/core/vite.config.js

@@ -11,13 +11,20 @@ const __dirname = dirname(fileURLToPath(import.meta.url))
 export default defineConfig({
 	clearScreen: false,
 	plugins: [
-		dts({ tsconfigPath: './tsconfig.dts.json', bundleTypes: true }),
+		dts({
+			include: ['src/**/*.ts'],
+			exclude: ['src/**/*.test.ts'],
+			bundleTypes: true,
+			compilerOptions: {
+				composite: true,
+				noEmit: false,
+				emitDeclarationOnly: true,
+				declaration: true,
+			},
+		}),
 		cssInjectedByJsPlugin({ relativeCSSInjection: true }),
 	],
 	publicDir: false,
-	esbuild: {
-		keepNames: true,
-	},
 	build: {
 		lib: {
 			entry: resolve(__dirname, 'src/PageAgentCore.ts'),

packages/core/vitest.config.js

@@ -0,0 +1,9 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+	test: {
+		name: 'core',
+		include: ['src/**/*.test.ts'],
+		silent: 'passed-only',
+	},
+})

packages/extension/.prettierignore

@@ -1,2 +0,0 @@
-.wxt
-src/components/ui

packages/extension/docs/extension_api.md

@@ -42,33 +42,28 @@ localStorage.setItem('PageAgentExtUserAuthToken', 'your-token')
 ## Quick Start
 
 ```typescript
-import type {
-  AgentActivity,
-  AgentStatus,
-  ExecutionResult,
-  HistoricalEvent,
-} from '@page-agent/core'
+import type { AgentActivity, AgentStatus, ExecutionResult, HistoricalEvent } from '@page-agent/core'
 
 // Wait for extension injection (up to 1 second)
 async function waitForExtension(timeout = 1000): Promise<boolean> {
-  const start = Date.now()
-  while (Date.now() - start < timeout) {
-    if (window.PAGE_AGENT_EXT) return true
-    await new Promise((r) => setTimeout(r, 100))
-  }
-  return false
+    const start = Date.now()
+    while (Date.now() - start < timeout) {
+        if (window.PAGE_AGENT_EXT) return true
+        await new Promise((r) => setTimeout(r, 100))
+    }
+    return false
 }
 
 // Usage
 if (await waitForExtension()) {
-  const result = await window.PAGE_AGENT_EXT!.execute('Click the login button', {
-    baseURL: 'https://api.openai.com/v1',
-    apiKey: 'your-api-key',
-    model: 'gpt-5.2',
-    onStatusChange: (status) => console.log('Status:', status),
-    onActivity: (activity) => console.log('Activity:', activity),
-  })
-  console.log('Result:', result)
+    const result = await window.PAGE_AGENT_EXT!.execute('Click the login button', {
+        baseURL: 'https://api.openai.com/v1',
+        apiKey: 'your-api-key',
+        model: 'gpt-5.2',
+        onStatusChange: (status) => console.log('Status:', status),
+        onActivity: (activity) => console.log('Activity:', activity),
+    })
+    console.log('Result:', result)
 }
 ```
 
@@ -90,10 +85,10 @@ Execute one agent task.
 
 Parameters:
 
-| Name | Type | Required | Description |
-| ---- | ---- | -------- | ----------- |
-| `task` | `string` | Yes | Task description |
-| `config` | `ExecuteConfig` | Yes | LLM settings, options, and callbacks |
+| Name     | Type            | Required | Description                          |
+| -------- | --------------- | -------- | ------------------------------------ |
+| `task`   | `string`        | Yes      | Task description                     |
+| `config` | `ExecuteConfig` | Yes      | LLM settings, options, and callbacks |
 
 Returns: `Promise<ExecutionResult>`
 
@@ -101,29 +96,37 @@ Returns: `Promise<ExecutionResult>`
 
 Stop the current task.
 
+## Limitations
+
+- **Normal browser windows only.** This extension relies on tab group API which does not work for pop-up window or PWA App window.
+
 ## Types
 
 Install `@page-agent/core` for complete types:
 
 ```typescript
-import type {
-  AgentActivity,
-  AgentStatus,
-  ExecutionResult,
-  HistoricalEvent,
-} from '@page-agent/core'
+import type { AgentActivity, AgentStatus, ExecutionResult, HistoricalEvent } from '@page-agent/core'
 
 export interface ExecuteConfig {
-  baseURL: string
-  apiKey: string
-  model: string
+    baseURL: string
+    model: string
+    apiKey?: string
 
-  // Include the initial tab where page JS starts. Default: true.
-  includeInitialTab?: boolean
+    // Global system-level instructions for the agent.
+    // Equivalent to AgentConfig.instructions.system.
+    systemInstruction?: string
 
-  onStatusChange?: (status: AgentStatus) => void
-  onActivity?: (activity: AgentActivity) => void
-  onHistoryUpdate?: (history: HistoricalEvent[]) => void
+    // Include the initial tab where page JS starts. Default: true.
+    includeInitialTab?: boolean
+
+    // Control all unpinned tabs in the window instead of only the tab group.
+    // When enabled, agent sees and can switch to every non-pinned tab.
+    // Default: false. Experimental.
+    experimentalIncludeAllTabs?: boolean
+
+    onStatusChange?: (status: AgentStatus) => void
+    onActivity?: (activity: AgentActivity) => void
+    onHistoryUpdate?: (history: HistoricalEvent[]) => void
 }
 
 export type Execute = (task: string, config: ExecuteConfig) => Promise<ExecutionResult>
@@ -132,38 +135,38 @@ export type Execute = (task: string, config: ExecuteConfig) => Promise<Execution
 `AgentStatus`
 
 ```typescript
-type AgentStatus = 'idle' | 'running' | 'completed' | 'error'
+type AgentStatus = 'idle' | 'running' | 'completed' | 'error' | 'stopped'
 ```
 
 `AgentActivity`
 
 ```typescript
 type AgentActivity =
-  | { type: 'thinking' }
-  | { type: 'executing'; tool: string; input: unknown }
-  | { type: 'executed'; tool: string; input: unknown; output: string; duration: number }
-  | { type: 'retrying'; attempt: number; maxAttempts: number }
-  | { type: 'error'; message: string }
+    | { type: 'thinking' }
+    | { type: 'executing'; tool: string; input: unknown }
+    | { type: 'executed'; tool: string; input: unknown; output: string; duration: number }
+    | { type: 'retrying'; attempt: number; maxAttempts: number }
+    | { type: 'error'; message: string }
 ```
 
 `HistoricalEvent`
 
 ```typescript
 type HistoricalEvent =
-  | { type: 'step'; stepIndex: number; reflection: AgentReflection; action: Action }
-  | { type: 'observation'; content: string }
-  | { type: 'user_takeover' }
-  | { type: 'retry'; message: string; attempt: number; maxAttempts: number }
-  | { type: 'error'; message: string; rawResponse?: unknown }
+    | { type: 'step'; stepIndex: number; reflection: AgentReflection; action: Action }
+    | { type: 'observation'; content: string }
+    | { type: 'user_takeover' }
+    | { type: 'retry'; message: string; attempt: number; maxAttempts: number }
+    | { type: 'error'; message: string; rawResponse?: unknown }
 ```
 
 `ExecutionResult`
 
 ```typescript
 interface ExecutionResult {
-  success: boolean
-  data: string
-  history: HistoricalEvent[]
+    success: boolean
+    data: string
+    history: HistoricalEvent[]
 }
 ```
 
@@ -173,15 +176,15 @@ interface ExecutionResult {
 
 ```typescript
 const result = await window.PAGE_AGENT_EXT!.execute(
-  'Fill in the email field with test@example.com and click Submit',
-  {
-    baseURL: 'https://api.openai.com/v1',
-    apiKey: process.env.OPENAI_API_KEY!,
-    model: 'gpt-5.2',
-    includeInitialTab: false, // Optional: exclude current tab
-    onStatusChange: (status) => console.log(status),
-    onActivity: (activity) => console.log(activity),
-  }
+    'Fill in the email field with test@example.com and click Submit',
+    {
+        baseURL: 'https://api.openai.com/v1',
+        apiKey: process.env.OPENAI_API_KEY!,
+        model: 'gpt-5.2',
+        includeInitialTab: false, // Optional: exclude current tab
+        onStatusChange: (status) => console.log(status),
+        onActivity: (activity) => console.log(activity),
+    }
 )
 ```
 
@@ -196,31 +199,30 @@ window.PAGE_AGENT_EXT!.stop()
 If you are not importing `@page-agent/core`, add:
 
 ```typescript
-import type {
-  AgentActivity,
-  AgentStatus,
-  ExecutionResult,
-  HistoricalEvent,
-} from '@page-agent/core'
+import type { AgentActivity, AgentStatus, ExecutionResult, HistoricalEvent } from '@page-agent/core'
 
 interface ExecuteConfig {
-  baseURL: string
-  apiKey: string
-  model: string
-  includeInitialTab?: boolean
-  onStatusChange?: (status: AgentStatus) => void
-  onActivity?: (activity: AgentActivity) => void
-  onHistoryUpdate?: (history: HistoricalEvent[]) => void
+    baseURL: string
+    model: string
+    apiKey?: string
+
+    systemInstruction?: string
+
+    includeInitialTab?: boolean
+    experimentalIncludeAllTabs?: boolean
+    onStatusChange?: (status: AgentStatus) => void
+    onActivity?: (activity: AgentActivity) => void
+    onHistoryUpdate?: (history: HistoricalEvent[]) => void
 }
 
 declare global {
-  interface Window {
-    PAGE_AGENT_EXT_VERSION?: string
-    PAGE_AGENT_EXT?: {
-      version: string
-      execute: Execute
-      stop: () => void
+    interface Window {
+        PAGE_AGENT_EXT_VERSION?: string
+        PAGE_AGENT_EXT?: {
+            version: string
+            execute: Execute
+            stop: () => void
+        }
     }
-  }
 }
 ```

packages/extension/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@page-agent/ext",
     "private": true,
-    "version": "0.1.11",
+    "version": "1.11.0",
     "type": "module",
     "scripts": {
         "dev": "wxt",
@@ -10,38 +10,38 @@
         "postinstall": "wxt prepare"
     },
     "devDependencies": {
-        "@radix-ui/react-hover-card": "^1.1.15",
+        "@radix-ui/react-hover-card": "^1.1.18",
         "@radix-ui/react-icons": "^1.3.2",
-        "@radix-ui/react-label": "^2.1.8",
-        "@radix-ui/react-separator": "^1.1.8",
-        "@radix-ui/react-slot": "^1.2.4",
-        "@radix-ui/react-switch": "^1.2.6",
-        "@radix-ui/react-tooltip": "^1.2.8",
-        "@types/chrome": "^0.1.37",
-        "@types/react": "^19.2.14",
-        "@types/react-dom": "^19.2.1",
-        "@wxt-dev/module-react": "^1.1.5",
+        "@radix-ui/react-label": "^2.1.11",
+        "@radix-ui/react-separator": "^1.1.11",
+        "@radix-ui/react-slot": "^1.3.0",
+        "@radix-ui/react-switch": "^1.3.2",
+        "@tailwindcss/vite": "^4.3.2",
+        "@types/chrome": "^0.2.1",
+        "@types/react": "^19.2.17",
+        "@types/react-dom": "^19.2.3",
+        "@wxt-dev/module-react": "^1.2.2",
         "class-variance-authority": "^0.7.1",
         "clsx": "^2.1.1",
         "idb": "^8.0.3",
-        "lucide-react": "^0.576.0",
-        "motion": "^12.34.5",
+        "lucide-react": "^1.22.0",
+        "motion": "^12.42.2",
         "next-themes": "^0.4.6",
-        "react": "^19.2.4",
-        "react-dom": "^19.2.4",
+        "react": "^19.2.7",
+        "react-dom": "^19.2.7",
         "rough-notation": "^0.5.1",
-        "simple-icons": "^16.10.0",
+        "simple-icons": "^16.24.1",
         "sonner": "^2.0.7",
-        "tailwind-merge": "^3.5.0",
-        "tailwindcss": "^4.1.14",
+        "tailwind-merge": "^3.6.0",
+        "tailwindcss": "^4.3.2",
         "tw-animate-css": "^1.4.0",
-        "wxt": "^0.20.18"
+        "wxt": "^0.20.27"
     },
     "dependencies": {
-        "@page-agent/core": "1.5.2",
-        "@page-agent/llms": "1.5.2",
-        "@page-agent/page-controller": "1.5.2",
-        "@page-agent/ui": "1.5.2",
+        "@page-agent/core": "1.11.0",
+        "@page-agent/llms": "1.11.0",
+        "@page-agent/page-controller": "1.11.0",
+        "@page-agent/ui": "1.11.0",
         "ai-motion": "^0.4.8",
         "chalk": "^5.6.2"
     },

packages/extension/public/_locales/en/messages.json

@@ -1,11 +1,11 @@
 {
-	"extName": {
-		"message": "Page Agent Ext"
-	},
-	"extDescription": {
-		"message": "AI-powered browser automation assistant. Control web pages with natural language."
-	},
-	"extActionTitle": {
-		"message": "Open Page Agent"
-	}
+    "extName": {
+        "message": "Page Agent Ext"
+    },
+    "extDescription": {
+        "message": "AI-powered browser automation assistant. Control web pages with natural language."
+    },
+    "extActionTitle": {
+        "message": "Open Page Agent"
+    }
 }

packages/extension/public/_locales/zh_CN/messages.json

@@ -1,11 +1,11 @@
 {
-	"extName": {
-		"message": "Page Agent Ext"
-	},
-	"extDescription": {
-		"message": "AI 驱动的浏览器自动化助手，用自然语言控制网页。"
-	},
-	"extActionTitle": {
-		"message": "打开 Page Agent"
-	}
+    "extName": {
+        "message": "Page Agent Ext"
+    },
+    "extDescription": {
+        "message": "AI 驱动的浏览器自动化助手，用自然语言控制网页。"
+    },
+    "extActionTitle": {
+        "message": "打开 Page Agent"
+    }
 }

packages/extension/src/agent/.prettierignore

@@ -1 +0,0 @@
-system_prompt.md

packages/extension/src/agent/MultiPageAgent.ts

@@ -11,13 +11,18 @@ function detectLanguage(): 'en-US' | 'zh-CN' {
 	return lang.startsWith('zh') ? 'zh-CN' : 'en-US'
 }
 
+interface MultiPageAgentConfig extends AgentConfig {
+	includeInitialTab?: boolean
+	experimentalIncludeAllTabs?: boolean
+}
+
 /**
  * MultiPageAgent
  * - use with extension
  * - can be used from a side panel or a content script
  */
 export class MultiPageAgent extends PageAgentCore {
-	constructor(config: AgentConfig & { includeInitialTab?: boolean }) {
+	constructor(config: MultiPageAgentConfig) {
 		// multi page controller
 		const tabsController = new TabsController()
 		const pageController = new RemotePageController(tabsController)
@@ -31,66 +36,63 @@ export class MultiPageAgent extends PageAgentCore {
 			`Default working language: **${targetLanguage}**`
 		)
 
-		// include initial tab for controlling
 		const includeInitialTab = config.includeInitialTab ?? true
+		const experimentalIncludeAllTabs = config.experimentalIncludeAllTabs ?? false
 
 		/**
+		 * Project agent status into chrome.storage. The content script polls
+		 * `isAgentRunning` + `agentHeartbeat` (eventually consistent by design).
+		 *
 		 * When the agent is in side-panel and user closed the side-panel.
 		 * There is no chance for isAgentRunning to be set false.
 		 * (unload event doesn't work well in side panel.)
 		 * (I'm trying not to use long-lived connection because the lifecycle of a sw is hard to predict.)
 		 * This heartbeat mechanism acts as a backup.
 		 */
-		let heartBeatInterval: null | number = null
+		let heartBeatInterval: number | null = null
 
 		super({
 			...config,
+			// Disabled: AbortSignal cannot cross contexts
+			experimentalScriptExecutionTool: false,
 			pageController: pageController as any,
 			customTools: customTools,
 			customSystemPrompt: systemPrompt,
 
 			onBeforeTask: async (agent) => {
-				await tabsController.init(agent.task, includeInitialTab)
-
-				heartBeatInterval = window.setInterval(() => {
-					chrome.storage.local.set({
-						agentHeartbeat: Date.now(),
-					})
-				}, 1_000)
-
-				await chrome.storage.local.set({
-					isAgentRunning: true,
-				})
-			},
-
-			onAfterTask: async () => {
-				if (heartBeatInterval) {
-					window.clearInterval(heartBeatInterval)
-					heartBeatInterval = null
-				}
-
-				await chrome.storage.local.set({
-					isAgentRunning: false,
-				})
+				await tabsController.init(agent.task, { includeInitialTab, experimentalIncludeAllTabs })
 			},
 
 			onBeforeStep: async (agent) => {
+				if (!tabsController.currentTabId) return
 				// make sure the current tab is loaded before the step starts
 				await tabsController.waitUntilTabLoaded(tabsController.currentTabId!)
 			},
 
 			onDispose: () => {
 				if (heartBeatInterval) {
-					window.clearInterval(heartBeatInterval)
+					clearInterval(heartBeatInterval)
 					heartBeatInterval = null
 				}
-
-				chrome.storage.local.set({
-					isAgentRunning: false,
-				})
+				chrome.storage.local.set({ isAgentRunning: false }).catch(console.error)
 
 				tabsController.dispose()
 			},
 		})
+
+		this.addEventListener('statuschange', () => {
+			const running = this.status === 'running'
+
+			if (running && !heartBeatInterval) {
+				heartBeatInterval = window.setInterval(() => {
+					void chrome.storage.local.set({ agentHeartbeat: Date.now() })
+				}, 1_000)
+			} else if (!running && heartBeatInterval) {
+				clearInterval(heartBeatInterval)
+				heartBeatInterval = null
+			}
+
+			chrome.storage.local.set({ isAgentRunning: running }).catch(console.error)
+		})
 	}
 }

packages/extension/src/agent/RemotePageController.background.ts

@@ -10,9 +10,7 @@ export function handlePageControlMessage(
 ): true | undefined {
 	const PREFIX = '[RemotePageController.background]'
 
-	function debug(...messages: any[]) {
-		console.debug(`\x1b[90m${PREFIX}\x1b[0m`, ...messages)
-	}
+	const debug = console.debug.bind(console, `\x1b[90m${PREFIX}\x1b[0m`)
 
 	const { action, payload, targetTabId } = message
 

packages/extension/src/agent/RemotePageController.content.ts

@@ -19,7 +19,10 @@ export function initPageController() {
 
 	function getPC(): PageController {
 		if (!pageController) {
-			pageController = new PageController({ enableMask: false, viewportExpansion: 400 })
+			pageController = new PageController({
+				enableMask: false,
+				viewportExpansion: 400,
+			})
 		}
 		return pageController
 	}

packages/extension/src/agent/RemotePageController.ts

@@ -4,9 +4,7 @@ import type { TabsController } from './TabsController'
 
 const PREFIX = '[RemotePageController]'
 
-function debug(...messages: any[]) {
-	console.debug(`\x1b[90m${PREFIX}\x1b[0m`, ...messages)
-}
+const debug = console.debug.bind(console, `\x1b[90m${PREFIX}\x1b[0m`)
 
 function sendMessage(message: {
 	type: 'PAGE_CONTROL'
@@ -58,9 +56,7 @@ export class RemotePageController {
 	}
 
 	async getBrowserState(): Promise<BrowserState> {
-		if (!this.currentTabId) throw new Error('tabsController not initialized.')
-
-		let browserState = {} as BrowserState
+		let browserState: BrowserState
 		debug('getBrowserState', this.currentTabId)
 
 		const currentUrl = await this.getCurrentUrl()
@@ -137,9 +133,7 @@ export class RemotePageController {
 		return this.remoteCallDomAction('scroll_horizontally', args)
 	}
 
-	async executeJavascript(...args: any[]): Promise<DomActionReturn> {
-		return this.remoteCallDomAction('execute_javascript', args)
-	}
+	// `execute_javascript` is intentionally not implemented: AbortSignal cannot cross context
 
 	/** @note Managed by content script via storage polling. */
 	async showMask(): Promise<void> {}
@@ -178,7 +172,7 @@ interface DomActionReturn {
 /**
  * Check if a URL can run content scripts.
  */
-function isContentScriptAllowed(url: string | undefined): boolean {
+export function isContentScriptAllowed(url: string | undefined): boolean {
 	if (!url) return false
 
 	const restrictedPatterns = [

packages/extension/src/agent/TabsController.background.ts

@@ -5,8 +5,39 @@ import type { TabAction } from './TabsController'
 
 const PREFIX = '[TabsController.background]'
 
-function debug(...messages: any[]) {
-	console.debug(`\x1b[90m${PREFIX}\x1b[0m`, ...messages)
+const debug = console.debug.bind(console, `\x1b[90m${PREFIX}\x1b[0m`)
+
+/**
+ * Resolve active tab.
+ *
+ * - `tabs.query({ active: true })` does not work in multi-window scenarios.
+ * - Extension pages (side panel, hub tab) can resolve their own windowId.
+ *   We just find the active tab within that window.
+ * - Content scripts (PAGE_AGENT_EXT) can't self-report a windowId.
+ *   Chrome populates `sender.tab` for every content-script message,
+ *   which is the tab hosting the script.
+ */
+async function resolveActiveTab(
+	payload: { windowId?: number } | undefined,
+	sender: chrome.runtime.MessageSender
+): Promise<chrome.tabs.Tab> {
+	const windowId = payload?.windowId
+
+	if (windowId != null) {
+		debug('get_active_tab: resolving via caller-reported windowId', windowId)
+		const [tab] = await chrome.tabs.query({ active: true, windowId })
+		if (!tab) throw new Error(`No active tab found in window ${windowId}.`)
+		return tab
+	}
+
+	if (sender.tab) {
+		debug('get_active_tab: resolving via sender.tab (content script)', sender.tab.id)
+		return sender.tab
+	}
+
+	throw new Error(
+		'Cannot resolve active tab: caller reported no windowId and is not a content script (no sender.tab).'
+	)
 }
 
 export function handleTabControlMessage(
@@ -18,13 +49,11 @@ export function handleTabControlMessage(
 
 	switch (action as TabAction) {
 		case 'get_active_tab': {
-			debug('get_active_tab')
-			chrome.tabs
-				.query({ active: true, currentWindow: true })
-				.then((tabs) => {
-					const tabId = tabs.length > 0 ? tabs[0].id || null : null
-					debug('get_active_tab: success', tabId)
-					sendResponse({ success: true, tabId })
+			debug('get_active_tab', payload)
+			resolveActiveTab(payload, sender)
+				.then((tab) => {
+					debug('get_active_tab: success', tab)
+					sendResponse({ success: true, tab })
 				})
 				.catch((error) => {
 					sendResponse({ error: error instanceof Error ? error.message : String(error) })
@@ -49,10 +78,10 @@ export function handleTabControlMessage(
 		case 'open_new_tab': {
 			debug('open_new_tab', payload)
 			chrome.tabs
-				.create({ url: payload.url, active: false })
+				.create({ url: payload.url, windowId: payload.windowId, active: false })
 				.then((newTab) => {
 					debug('open_new_tab: success', newTab)
-					sendResponse({ success: true, tabId: newTab.id, windowId: newTab.windowId })
+					sendResponse({ success: true, tabId: newTab.id })
 				})
 				.catch((error) => {
 					sendResponse({ error: error instanceof Error ? error.message : String(error) })
@@ -114,47 +143,59 @@ export function handleTabControlMessage(
 			return true // async response
 		}
 
+		case 'get_window_tabs': {
+			debug('get_window_tabs', payload)
+			chrome.tabs
+				.query({ windowId: payload.windowId })
+				.then((tabs) => {
+					sendResponse({ success: true, tabs })
+				})
+				.catch((error) => {
+					sendResponse({ error: error instanceof Error ? error.message : String(error) })
+				})
+			return true
+		}
+
 		default:
 			sendResponse({ error: `Unknown action: ${action}` })
 			return
 	}
 }
 
-export function setupTabChangeEvents() {
-	console.log('[TabsController.background] setupTabChangeEvents')
+const tabEventPorts = new Set<chrome.runtime.Port>()
+
+function broadcastTabEvent(message: object) {
+	for (const port of tabEventPorts) {
+		port.postMessage(message)
+	}
+}
+
+/**
+ * Port-based tab events: agents connect via `chrome.runtime.connect({ name: 'tab-events' })`
+ * and receive tab change events through the port. Works for both extension pages and content scripts.
+ */
+export function setupTabEventsPort() {
+	chrome.runtime.onConnect.addListener((port) => {
+		if (port.name !== 'tab-events') return
+
+		debug('port connected', port.sender?.tab?.id ?? port.sender?.url)
+		tabEventPorts.add(port)
+
+		port.onDisconnect.addListener(() => {
+			debug('port disconnected')
+			tabEventPorts.delete(port)
+		})
+	})
 
 	chrome.tabs.onCreated.addListener((tab) => {
-		debug('onCreated', tab)
-		chrome.runtime
-			.sendMessage({ type: 'TAB_CHANGE', action: 'created', payload: { tab } })
-			.catch((error) => {
-				debug('onCreated error:', error)
-			})
+		broadcastTabEvent({ action: 'created', payload: { tab } })
 	})
 
 	chrome.tabs.onRemoved.addListener((tabId, removeInfo) => {
-		debug('onRemoved', tabId, removeInfo)
-		chrome.runtime
-			.sendMessage({
-				type: 'TAB_CHANGE',
-				action: 'removed',
-				payload: { tabId, removeInfo },
-			})
-			.catch((error) => {
-				debug('onRemoved error:', error)
-			})
+		broadcastTabEvent({ action: 'removed', payload: { tabId, removeInfo } })
 	})
 
 	chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => {
-		debug('onUpdated', tabId, changeInfo)
-		chrome.runtime
-			.sendMessage({
-				type: 'TAB_CHANGE',
-				action: 'updated',
-				payload: { tabId, changeInfo, tab },
-			})
-			.catch((error) => {
-				debug('onUpdated error:', error)
-			})
+		broadcastTabEvent({ action: 'updated', payload: { tabId, changeInfo, tab } })
 	})
 }

packages/extension/src/agent/TabsController.ts

@@ -1,8 +1,8 @@
+import { isContentScriptAllowed } from './RemotePageController'
+
 const PREFIX = '[TabsController]'
 
-function debug(...messages: any[]) {
-	console.debug(`\x1b[90m${PREFIX}\x1b[0m`, ...messages)
-}
+const debug = console.debug.bind(console, `\x1b[90m${PREFIX}\x1b[0m`)
 
 function sendMessage(message: {
 	type: 'TAB_CONTROL'
@@ -15,107 +15,122 @@ function sendMessage(message: {
 	})
 }
 
+/**
+ * Resolve the window hosting this script's own context, when knowable.
+ *
+ * Extension pages (side panel, hub tab) have `chrome.windows` access and can
+ * identify their own window directly via `getCurrent()`.
+ * Content scripts have no `chrome.windows` access; they resolve `undefined`
+ * here and the background script falls back to `sender.tab` instead.
+ */
+async function getOwnWindowId(): Promise<number | undefined> {
+	if (typeof chrome.windows === 'undefined') return undefined
+	const win = await chrome.windows.getCurrent()
+	return win.id
+}
+
 /**
  * Controller for managing browser tabs.
  * - live in the agent env (extension page or content script)
  * - no chrome apis. call sw for tab operations
  */
-export class TabsController extends EventTarget {
+export class TabsController {
 	currentTabId: number | null = null
 
+	private disposed = false
+	private port?: chrome.runtime.Port
+	private portRetries = 0
+
+	private windowId: number | null = null
 	private tabs: TabMeta[] = []
 	private initialTabId: number | null = null
 	private tabGroupId: number | null = null
+	private experimentalIncludeAllTabs = false
 	private task: string = ''
-	private windowId: number | null = null
 
-	async init(task: string, includeInitialTab: boolean = true) {
-		debug('init', task, includeInitialTab)
+	async init(task: string, options: TabsInitOptions = {}) {
+		const { includeInitialTab = true, experimentalIncludeAllTabs = false } = options
+		debug('init', task, options)
 
-		this.task = task
-		this.tabs = []
-		this.currentTabId = null
-		this.tabGroupId = null
-		this.initialTabId = null
-		this.windowId = null
-
-		const result = await sendMessage({
-			type: 'TAB_CONTROL',
-			action: 'get_active_tab',
-		})
-
-		this.initialTabId = result.tabId
-
-		if (!this.initialTabId) {
-			throw new Error('Failed to get initial tab ID')
+		if (this.disposed) {
+			throw new Error('TabsController already disposed')
 		}
 
-		if (includeInitialTab) {
-			this.currentTabId = this.initialTabId
+		await this.updateCurrentTabId(null)
+		this.disposed = false
+		this.port = undefined
+		this.portRetries = 0
 
-			// update tab status immediately
+		this.windowId = null
+		this.tabs = []
+		this.tabGroupId = null
+		this.initialTabId = null
+		this.experimentalIncludeAllTabs = experimentalIncludeAllTabs
+		this.task = task
+
+		const activeTabResult = await sendMessage({
+			type: 'TAB_CONTROL',
+			action: 'get_active_tab',
+			payload: { windowId: await getOwnWindowId() },
+		})
+
+		this.initialTabId = activeTabResult.tab?.id
+		this.windowId = activeTabResult.tab?.windowId
+
+		if (!this.initialTabId || !this.windowId) {
+			if (activeTabResult.error) {
+				throw new Error(activeTabResult.error)
+			} else {
+				throw new Error('Failed to get active tab')
+			}
+		}
+
+		this.connectTabEvents()
+
+		if (experimentalIncludeAllTabs) {
+			const allTabs = await sendMessage({
+				type: 'TAB_CONTROL',
+				action: 'get_window_tabs',
+				payload: { windowId: this.windowId },
+			})
+			for (const tab of allTabs.tabs as chrome.tabs.Tab[]) {
+				if (tab.id && !tab.pinned && isContentScriptAllowed(tab.url)) {
+					this.addTab({
+						id: tab.id,
+						isInitial: tab.id === this.initialTabId,
+						url: tab.url,
+						title: tab.title,
+						status: tab.status,
+					})
+				}
+			}
+			if (this.tabs.find((t) => t.id === this.initialTabId)) {
+				this.currentTabId = this.initialTabId
+				await this.createTabGroup([this.initialTabId])
+			}
+		} else if (includeInitialTab) {
 			const info = await sendMessage({
 				type: 'TAB_CONTROL',
 				action: 'get_tab_info',
 				payload: { tabId: this.initialTabId },
 			})
 
-			this.tabs.push({
-				id: result.tabId,
-				isInitial: true,
-				url: info.url,
-				title: info.title,
-				status: info.status,
-			})
+			if (isContentScriptAllowed(info.url) && !info.pinned) {
+				this.currentTabId = this.initialTabId
+
+				this.addTab({
+					id: this.initialTabId,
+					isInitial: true,
+					url: info.url,
+					title: info.title,
+					status: info.status,
+				})
+
+				await this.createTabGroup([this.initialTabId])
+			}
 		}
 
 		await this.updateCurrentTabId(this.currentTabId)
-
-		const tabChangeHandler = (message: any): void => {
-			if (message.type !== 'TAB_CHANGE') {
-				// throw new Error(`[TabsController]: Invalid message type: ${message.type}`)
-				return
-			}
-
-			if (message.action === 'created') {
-				const tab = message.payload.tab as chrome.tabs.Tab
-				if (tab.groupId === this.tabGroupId && tab.id != null) {
-					// Tab created in our controlled group
-					if (!this.tabs.find((t) => t.id === tab.id)) {
-						this.tabs.push({ id: tab.id, isInitial: false })
-					}
-					this.switchToTab(tab.id)
-				}
-			} else if (message.action === 'removed') {
-				const { tabId } = message.payload as { tabId: number }
-				const targetTab = this.tabs.find((t) => t.id === tabId)
-				if (targetTab) {
-					this.tabs = this.tabs.filter((t) => t.id !== tabId)
-					if (this.currentTabId === tabId) {
-						const newCurrentTab = this.tabs[this.tabs.length - 1] || null
-						if (newCurrentTab) {
-							this.switchToTab(newCurrentTab.id)
-						} else {
-							this.updateCurrentTabId(null)
-						}
-					}
-				}
-			} else if (message.action === 'updated') {
-				const { tabId, tab } = message.payload as { tabId: number; tab: chrome.tabs.Tab }
-				const targetTab = this.tabs.find((t) => t.id === tabId)
-				if (targetTab) {
-					targetTab.url = tab.url
-					targetTab.title = tab.title
-					targetTab.status = tab.status
-				}
-			}
-		}
-
-		chrome.runtime.onMessage.addListener(tabChangeHandler)
-
-		this.addEventListener('dispose', () => {
-			chrome.runtime.onMessage.removeListener(tabChangeHandler)
-		})
 	}
 
 	async openNewTab(url: string): Promise<string> {
@@ -124,7 +139,7 @@ export class TabsController extends EventTarget {
 		const result = await sendMessage({
 			type: 'TAB_CONTROL',
 			action: 'open_new_tab',
-			payload: { url },
+			payload: { url, windowId: this.windowId },
 		})
 
 		if (!result.success) {
@@ -132,11 +147,8 @@ export class TabsController extends EventTarget {
 		}
 
 		const tabId = result.tabId as number
-		const windowId = result.windowId as number
 
-		this.windowId = windowId
-
-		this.tabs.push({
+		this.addTab({
 			id: tabId,
 			isInitial: false,
 		})
@@ -144,32 +156,7 @@ export class TabsController extends EventTarget {
 		await this.switchToTab(tabId)
 
 		if (!this.tabGroupId) {
-			const result = await sendMessage({
-				type: 'TAB_CONTROL',
-				action: 'create_tab_group',
-				payload: { tabIds: [tabId], windowId: this.windowId },
-			})
-
-			if (!result.success) {
-				throw new Error(`Failed to create tab group: ${result.error}`)
-			}
-
-			const groupId = result.groupId as number
-
-			this.tabGroupId = groupId
-
-			await sendMessage({
-				type: 'TAB_CONTROL',
-				action: 'update_tab_group',
-				payload: {
-					groupId: this.tabGroupId,
-					properties: {
-						title: `PageAgent(${this.task})`,
-						color: randomColor(),
-						collapsed: false,
-					},
-				},
-			})
+			await this.createTabGroup([tabId])
 		} else {
 			await sendMessage({
 				type: 'TAB_CONTROL',
@@ -230,6 +217,38 @@ export class TabsController extends EventTarget {
 		}
 	}
 
+	private async createTabGroup(tabIds: number[]) {
+		const result = await sendMessage({
+			type: 'TAB_CONTROL',
+			action: 'create_tab_group',
+			payload: { tabIds, windowId: this.windowId },
+		})
+
+		if (!result?.success) {
+			throw new Error(`Failed to create tab group: ${result?.error}`)
+		}
+
+		this.tabGroupId = result.groupId as number
+
+		await sendMessage({
+			type: 'TAB_CONTROL',
+			action: 'update_tab_group',
+			payload: {
+				groupId: this.tabGroupId,
+				properties: {
+					title: `PageAgent(${this.task})`,
+					color: randomColor(),
+					collapsed: false,
+				},
+			},
+		})
+	}
+
+	private addTab(meta: TabMeta) {
+		if (this.tabs.find((t) => t.id === meta.id)) return
+		this.tabs.push(meta)
+	}
+
 	async updateCurrentTabId(tabId: number | null) {
 		debug('updateCurrentTabId', tabId)
 
@@ -286,9 +305,80 @@ export class TabsController extends EventTarget {
 		await waitUntil(() => tab.status === 'complete', 4_000)
 	}
 
-	dispose() {
-		this.dispatchEvent(new Event('dispose'))
+	/**
+	 * Connect to background SW via port to receive tab change events.
+	 *
+	 * @note Port is 1:1 (runtime.connect → background SW has no frames),
+	 * so onDisconnect fires exactly once and we can safely reconnect.
+	 * Reconnection may miss events during the gap.
+	 * TODO: refresh this.tabs from background after reconnect to stay consistent.
+	 */
+	private connectTabEvents() {
+		this.port = chrome.runtime.connect({ name: 'tab-events' })
+
+		this.port.onMessage.addListener((message: any) => {
+			if (this.disposed) return
+			this.portRetries = 0
+
+			if (message.action === 'created') {
+				const tab = message.payload.tab as chrome.tabs.Tab
+				const shouldTrack =
+					tab.groupId === this.tabGroupId ||
+					// @note Never track tabs from other windows.
+					(this.experimentalIncludeAllTabs && tab.windowId === this.windowId)
+				if (shouldTrack && tab.id != null) {
+					this.addTab({ id: tab.id, isInitial: false })
+					this.switchToTab(tab.id)
+				}
+			} else if (message.action === 'removed') {
+				const { tabId } = message.payload as { tabId: number }
+				const targetTab = this.tabs.find((t) => t.id === tabId)
+				if (targetTab) {
+					this.tabs = this.tabs.filter((t) => t.id !== tabId)
+					if (this.currentTabId === tabId) {
+						const newCurrentTab = this.tabs[this.tabs.length - 1] || null
+						if (newCurrentTab) {
+							this.switchToTab(newCurrentTab.id)
+						} else {
+							this.updateCurrentTabId(null)
+						}
+					}
+				}
+			} else if (message.action === 'updated') {
+				const { tabId, tab } = message.payload as { tabId: number; tab: chrome.tabs.Tab }
+				const targetTab = this.tabs.find((t) => t.id === tabId)
+				if (targetTab) {
+					targetTab.url = tab.url
+					targetTab.title = tab.title
+					targetTab.status = tab.status
+				}
+			}
+		})
+
+		this.port.onDisconnect.addListener(() => {
+			this.port = undefined
+			if (this.disposed) return
+			if (this.portRetries >= 7) {
+				console.error(PREFIX, 'tab events port failed after 7 retries, giving up')
+				return
+			}
+			debug('port disconnected, reconnecting...')
+			this.portRetries++
+			this.connectTabEvents()
+		})
 	}
+
+	dispose() {
+		debug('dispose')
+		this.disposed = true
+		this.port?.disconnect()
+		this.port = undefined
+	}
+}
+
+export interface TabsInitOptions {
+	includeInitialTab?: boolean
+	experimentalIncludeAllTabs?: boolean
 }
 
 export type TabAction =
@@ -300,6 +390,7 @@ export type TabAction =
 	| 'add_tab_to_group'
 	| 'close_tab'
 	| 'get_tab_title'
+	| 'get_window_tabs'
 
 interface TabMeta {
 	id: number
@@ -309,16 +400,7 @@ interface TabMeta {
 	status?: 'loading' | 'unloaded' | 'complete'
 }
 
-const TAB_GROUP_COLORS = [
-	'grey',
-	'blue',
-	'red',
-	'yellow',
-	'green',
-	'pink',
-	'purple',
-	'cyan',
-] as const
+const TAB_GROUP_COLORS = ['blue', 'red', 'yellow', 'green', 'pink', 'purple', 'cyan'] as const
 
 type TabGroupColor = (typeof TAB_GROUP_COLORS)[number]
 

packages/extension/src/agent/constants.ts

@@ -3,12 +3,12 @@ import type { LLMConfig } from '@page-agent/llms'
 // Demo LLM for testing
 export const DEMO_MODEL = 'qwen3.5-plus'
 export const DEMO_BASE_URL = 'https://page-ag-testing-ohftxirgbn.cn-shanghai.fcapp.run'
-export const DEMO_API_KEY = 'NA'
+// export const DEMO_API_KEY = 'NA'
 
 export const DEMO_CONFIG: LLMConfig = {
-	apiKey: DEMO_API_KEY,
 	baseURL: DEMO_BASE_URL,
 	model: DEMO_MODEL,
+	// apiKey: DEMO_API_KEY,
 }
 
 /** Legacy testing endpoints that should be auto-migrated to DEMO_BASE_URL */

packages/extension/src/agent/system_prompt.md

@@ -37,7 +37,7 @@ and system messages wrapped in <sys> tag.
 <user_request>
 USER REQUEST: This is your ultimate objective and always remains visible.
 - This has the highest priority. Make the user happy.
-- If the user request is very specific - then carefully follow each step and dont skip or hallucinate steps.
+- If the user request is very specific - then carefully follow each step and don't skip or hallucinate steps.
 - If the task is open ended you can plan yourself how to get it done.
 </user_request>
 
@@ -71,8 +71,7 @@ Strictly follow these rules while using the browser and navigating the web:
 - By default, only elements in the visible viewport are listed. Use scrolling actions if you suspect relevant content is offscreen which you need to interact with. Scroll ONLY if there are more pixels below or above the page.
 - You can scroll by a specific number of pages using the num_pages parameter (e.g., 0.5 for half page, 2.0 for two pages).
 - All the elements that are scrollable are marked with `data-scrollable` attribute. Including the scrollable distance in every directions. You can scroll *the element* in case some area are overflowed.
-- If a captcha appears, tell user you can not solve captcha. finished the task and ask user to solve it.
-- If expected elements are missing, try scrolling, or navigating back.
+- If a captcha appears, tell user you can not solve captcha. Finish the task and ask user to solve it.
 - If the page is not fully loaded, use the `wait` action.
 - Do not repeat one action for more than 3 times unless some conditions changed.
 - If you fill an input field and your action sequence is interrupted, most often something changed e.g. suggestions popped up under the field.

packages/extension/src/agent/useAgent.ts

@@ -4,6 +4,7 @@
 import type {
 	AgentActivity,
 	AgentStatus,
+	ExecutionResult,
 	HistoricalEvent,
 	SupportedLanguage,
 } from '@page-agent/core'
@@ -20,6 +21,8 @@ export interface AdvancedConfig {
 	maxSteps?: number
 	systemInstruction?: string
 	experimentalLlmsTxt?: boolean
+	experimentalIncludeAllTabs?: boolean
+	disableNamedToolChoice?: boolean
 }
 
 export interface ExtConfig extends LLMConfig, AdvancedConfig {
@@ -32,7 +35,7 @@ export interface UseAgentResult {
 	activity: AgentActivity | null
 	currentTask: string
 	config: ExtConfig | null
-	execute: (task: string) => Promise<void>
+	execute: (task: string) => Promise<ExecutionResult>
 	stop: () => void
 	configure: (config: ExtConfig) => Promise<void>
 }
@@ -77,7 +80,7 @@ export function useAgent(): UseAgentResult {
 		const handleStatusChange = (e: Event) => {
 			const newStatus = agent.status as AgentStatus
 			setStatus(newStatus)
-			if (newStatus === 'idle' || newStatus === 'completed' || newStatus === 'error') {
+			if (newStatus !== 'running') {
 				setActivity(null)
 			}
 		}
@@ -105,12 +108,11 @@ export function useAgent(): UseAgentResult {
 
 	const execute = useCallback(async (task: string) => {
 		const agent = agentRef.current
-		console.log('🚀 [useAgent] start executing task:', task)
 		if (!agent) throw new Error('Agent not initialized')
 
 		setCurrentTask(task)
 		setHistory([])
-		await agent.execute(task)
+		return agent.execute(task)
 	}, [])
 
 	const stop = useCallback(() => {
@@ -123,6 +125,8 @@ export function useAgent(): UseAgentResult {
 			maxSteps,
 			systemInstruction,
 			experimentalLlmsTxt,
+			experimentalIncludeAllTabs,
+			disableNamedToolChoice,
 			...llmConfig
 		}: ExtConfig) => {
 			await chrome.storage.local.set({ llmConfig })
@@ -131,7 +135,13 @@ export function useAgent(): UseAgentResult {
 			} else {
 				await chrome.storage.local.remove('language')
 			}
-			const advancedConfig: AdvancedConfig = { maxSteps, systemInstruction, experimentalLlmsTxt }
+			const advancedConfig: AdvancedConfig = {
+				maxSteps,
+				systemInstruction,
+				experimentalLlmsTxt,
+				experimentalIncludeAllTabs,
+				disableNamedToolChoice,
+			}
 			await chrome.storage.local.set({ advancedConfig })
 			setConfig({ ...llmConfig, ...advancedConfig, language })
 		},

packages/extension/src/components/ConfigPanel.tsx

@@ -1,18 +1,20 @@
 import {
-	ChevronDown,
 	Copy,
 	CornerUpLeft,
+	ExternalLink,
 	Eye,
 	EyeOff,
+	FoldVertical,
 	HatGlasses,
 	Home,
 	Loader2,
 	Scale,
+	UnfoldVertical,
 } from 'lucide-react'
 import { useEffect, useState } from 'react'
 import { siGithub } from 'simple-icons'
 
-import { DEMO_API_KEY, DEMO_BASE_URL, DEMO_MODEL, isTestingEndpoint } from '@/agent/constants'
+import { DEMO_BASE_URL, DEMO_MODEL, isTestingEndpoint } from '@/agent/constants'
 import type { ExtConfig, LanguagePreference } from '@/agent/useAgent'
 import { Button } from '@/components/ui/button'
 import { Input } from '@/components/ui/input'
@@ -25,31 +27,41 @@ interface ConfigPanelProps {
 }
 
 export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
-	const [apiKey, setApiKey] = useState(config?.apiKey || DEMO_API_KEY)
 	const [baseURL, setBaseURL] = useState(config?.baseURL || DEMO_BASE_URL)
 	const [model, setModel] = useState(config?.model || DEMO_MODEL)
+	const [apiKey, setApiKey] = useState(config?.apiKey)
 	const [language, setLanguage] = useState<LanguagePreference>(config?.language)
-	const [maxSteps, setMaxSteps] = useState<number | undefined>(config?.maxSteps)
+	const [maxSteps, setMaxSteps] = useState(config?.maxSteps)
 	const [systemInstruction, setSystemInstruction] = useState(config?.systemInstruction ?? '')
 	const [experimentalLlmsTxt, setExperimentalLlmsTxt] = useState(
 		config?.experimentalLlmsTxt ?? false
 	)
+	const [experimentalIncludeAllTabs, setExperimentalIncludeAllTabs] = useState(
+		config?.experimentalIncludeAllTabs ?? false
+	)
+	const [disableNamedToolChoice, setDisableNamedToolChoice] = useState(
+		config?.disableNamedToolChoice ?? false
+	)
 	const [advancedOpen, setAdvancedOpen] = useState(false)
 	const [saving, setSaving] = useState(false)
-	const [userAuthToken, setUserAuthToken] = useState<string>('')
+	const [userAuthToken, setUserAuthToken] = useState('')
 	const [copied, setCopied] = useState(false)
 	const [showToken, setShowToken] = useState(false)
 	const [showApiKey, setShowApiKey] = useState(false)
 
-	useEffect(() => {
-		setApiKey(config?.apiKey || DEMO_API_KEY)
+	const [prevConfig, setPrevConfig] = useState(config)
+	if (prevConfig !== config) {
+		setPrevConfig(config)
 		setBaseURL(config?.baseURL || DEMO_BASE_URL)
 		setModel(config?.model || DEMO_MODEL)
+		setApiKey(config?.apiKey)
 		setLanguage(config?.language)
 		setMaxSteps(config?.maxSteps)
 		setSystemInstruction(config?.systemInstruction ?? '')
 		setExperimentalLlmsTxt(config?.experimentalLlmsTxt ?? false)
-	}, [config])
+		setExperimentalIncludeAllTabs(config?.experimentalIncludeAllTabs ?? false)
+		setDisableNamedToolChoice(config?.disableNamedToolChoice ?? false)
+	}
 
 	// Poll for user auth token every second until found
 	useEffect(() => {
@@ -94,6 +106,8 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 				maxSteps: maxSteps || undefined,
 				systemInstruction: systemInstruction || undefined,
 				experimentalLlmsTxt,
+				experimentalIncludeAllTabs,
+				disableNamedToolChoice,
 			})
 		} finally {
 			setSaving(false)
@@ -109,6 +123,7 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 					size="icon-sm"
 					onClick={onClose}
 					className="absolute top-2 right-3 cursor-pointer"
+					aria-label="Back"
 				>
 					<CornerUpLeft className="size-3.5" />
 				</Button>
@@ -116,12 +131,15 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 
 			{/* User Auth Token Section */}
 			<div className="flex flex-col gap-1.5 p-3 bg-muted/50 rounded-md border">
-				<label className="text-xs font-medium text-muted-foreground">User Auth Token</label>
+				<label htmlFor="user-auth-token" className="text-xs font-medium text-muted-foreground">
+					User Auth Token
+				</label>
 				<p className="text-[10px] text-muted-foreground mb-1">
 					Give a website the ability to call this extension.
 				</p>
 				<div className="flex gap-2 items-center">
 					<Input
+						id="user-auth-token"
 						readOnly
 						value={
 							userAuthToken
@@ -138,6 +156,8 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 						className="h-8 w-8 shrink-0 cursor-pointer"
 						onClick={() => setShowToken(!showToken)}
 						disabled={!userAuthToken}
+						aria-label={showToken ? 'Hide token' : 'Show token'}
+						aria-pressed={showToken}
 					>
 						{showToken ? <EyeOff className="size-3" /> : <Eye className="size-3" />}
 					</Button>
@@ -147,15 +167,33 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 						className="h-8 w-8 shrink-0 cursor-pointer"
 						onClick={handleCopyToken}
 						disabled={!userAuthToken}
+						aria-label="Copy token"
 					>
 						{copied ? <span className="">✓</span> : <Copy className="size-3" />}
 					</Button>
+					<span role="status" aria-live="polite" aria-atomic="true" className="sr-only">
+						{copied ? 'Token copied' : ''}
+					</span>
 				</div>
 			</div>
 
+			{/* Hub link */}
+			<a
+				href="/hub.html"
+				target="_blank"
+				rel="noopener noreferrer"
+				className="flex items-center justify-between p-3 rounded-md border bg-muted/50 text-xs font-medium text-muted-foreground hover:text-foreground hover:border-foreground/20 transition-colors"
+			>
+				Manage Page Agent Hub
+				<ExternalLink className="size-3" />
+			</a>
+
 			<div className="flex flex-col gap-1.5">
-				<label className="text-xs text-muted-foreground">Base URL</label>
+				<label htmlFor="base-url" className="text-xs text-muted-foreground">
+					Base URL
+				</label>
 				<Input
+					id="base-url"
 					placeholder="https://api.openai.com/v1"
 					value={baseURL}
 					onChange={(e) => setBaseURL(e.target.value)}
@@ -167,7 +205,7 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 			{isTestingEndpoint(baseURL) && (
 				<div className="p-2.5 rounded-md border border-amber-500/30 bg-amber-500/5 text-[11px] text-muted-foreground leading-relaxed">
 					<Scale className="size-3 inline-block mr-1 -mt-0.5 text-amber-600" />
-					You are using the free testing API. By using this service you agree to the{' '}
+					You are using our testing API. By using this you agree to the{' '}
 					<a
 						href="https://github.com/alibaba/page-agent/blob/main/docs/terms-and-privacy.md"
 						target="_blank"
@@ -176,14 +214,16 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 					>
 						Terms of Use & Privacy Policy
 					</a>
-					. No sensitive data. No guaranteed availability.
 				</div>
 			)}
 
 			<div className="flex flex-col gap-1.5">
-				<label className="text-xs text-muted-foreground">Model</label>
+				<label htmlFor="model" className="text-xs text-muted-foreground">
+					Model
+				</label>
 				<Input
-					placeholder="gpt-5.2"
+					id="model"
+					placeholder="gpt-5.1"
 					value={model}
 					onChange={(e) => setModel(e.target.value)}
 					className="text-xs h-8"
@@ -191,11 +231,14 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 			</div>
 
 			<div className="flex flex-col gap-1.5">
-				<label className="text-xs text-muted-foreground">API Key</label>
+				<label htmlFor="api-key" className="text-xs text-muted-foreground">
+					API Key
+				</label>
 				<div className="flex gap-2 items-center">
 					<Input
+						id="api-key"
 						type={showApiKey ? 'text' : 'password'}
-						placeholder="sk-..."
+						// placeholder="sk-..."
 						value={apiKey}
 						onChange={(e) => setApiKey(e.target.value)}
 						className="text-xs h-8"
@@ -205,6 +248,7 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 						size="icon"
 						className="h-8 w-8 shrink-0 cursor-pointer"
 						onClick={() => setShowApiKey(!showApiKey)}
+						aria-label={showApiKey ? 'Hide API key' : 'Show API key'}
 					>
 						{showApiKey ? <EyeOff className="size-3" /> : <Eye className="size-3" />}
 					</Button>
@@ -212,7 +256,7 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 			</div>
 
 			<div className="flex flex-col gap-1.5">
-				<label className="text-xs text-muted-foreground">Language</label>
+				<label className="text-xs text-muted-foreground">Response Language</label>
 				<select
 					value={language ?? ''}
 					onChange={(e) => setLanguage((e.target.value || undefined) as LanguagePreference)}
@@ -231,17 +275,17 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 				className="flex items-center gap-1 text-xs text-muted-foreground hover:text-foreground cursor-pointer mt-1 font-bold"
 			>
 				Advanced
-				<ChevronDown
-					className="size-3 transition-transform"
-					style={{ transform: advancedOpen ? 'rotate(0deg)' : 'rotate(90deg)' }}
-				/>
+				{advancedOpen ? <FoldVertical className="size-3" /> : <UnfoldVertical className="size-3" />}
 			</button>
 
 			{advancedOpen && (
 				<>
 					<div className="flex flex-col gap-1.5">
-						<label className="text-xs text-muted-foreground">Max Steps</label>
+						<label htmlFor="max-steps" className="text-xs text-muted-foreground">
+							Max Steps
+						</label>
 						<Input
+							id="max-steps"
 							type="number"
 							placeholder="40"
 							min={1}
@@ -263,10 +307,23 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 						/>
 					</div>
 
+					<label className="flex items-center justify-between cursor-pointer">
+						<span className="text-xs text-muted-foreground">Disable named tool_choice</span>
+						<Switch checked={disableNamedToolChoice} onCheckedChange={setDisableNamedToolChoice} />
+					</label>
+
 					<label className="flex items-center justify-between cursor-pointer">
 						<span className="text-xs text-muted-foreground">Experimental llms.txt support</span>
 						<Switch checked={experimentalLlmsTxt} onCheckedChange={setExperimentalLlmsTxt} />
 					</label>
+
+					<label className="flex items-center justify-between cursor-pointer">
+						<span className="text-xs text-muted-foreground">Experimental include all tabs</span>
+						<Switch
+							checked={experimentalIncludeAllTabs}
+							onCheckedChange={setExperimentalIncludeAllTabs}
+						/>
+					</label>
 				</>
 			)}
 
@@ -286,6 +343,10 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 			{/* Footer */}
 			<div className="mt-4 mb-4 pt-4 border-t border-border/50 flex gap-2 justify-between text-[10px] text-muted-foreground">
 				<div className="flex flex-col justify-between">
+					<span>
+						Version <span className="font-mono">v{__VERSION__}</span>
+					</span>
+
 					<a
 						href="https://github.com/alibaba/page-agent"
 						target="_blank"
@@ -297,7 +358,9 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 						</svg>
 						<span>Source Code</span>
 					</a>
+				</div>
 
+				<div className="flex flex-col items-end">
 					<a
 						href="https://alibaba.github.io/page-agent/"
 						target="_blank"
@@ -315,18 +378,9 @@ export function ConfigPanel({ config, onSave, onClose }: ConfigPanelProps) {
 						className="flex items-center gap-1 hover:text-foreground"
 					>
 						<HatGlasses className="size-3" />
-						<span>Privacy Policy</span>
+						<span>Privacy</span>
 					</a>
 				</div>
-
-				<div className="flex flex-col items-end">
-					<span>
-						Extension <span className="font-mono">v{__EXT_VERSION__}</span>
-					</span>
-					<span>
-						PageAgent <span className="font-mono">v{__CORE_VERSION__}</span>
-					</span>
-				</div>
 			</div>
 
 			{/* attribute */}

packages/extension/src/components/ErrorBoundary.tsx

@@ -1,4 +1,4 @@
-import { AlertTriangle, RotateCcw } from 'lucide-react'
+import { AlertTriangle, Eraser, RotateCcw } from 'lucide-react'
 import { Component, type ErrorInfo, type ReactNode } from 'react'
 
 import { Button } from '@/components/ui/button'
@@ -27,6 +27,11 @@ export class ErrorBoundary extends Component<Props, State> {
 		window.location.reload()
 	}
 
+	handleResetConfig = async () => {
+		await chrome.storage.local.remove(['llmConfig', 'language', 'advancedConfig'])
+		window.location.reload()
+	}
+
 	render() {
 		if (!this.state.hasError) {
 			return this.props.children
@@ -39,10 +44,16 @@ export class ErrorBoundary extends Component<Props, State> {
 				<p className="text-sm text-muted-foreground mb-4 max-w-xs">
 					{this.state.error?.message || 'An unexpected error occurred'}
 				</p>
-				<Button variant="outline" size="sm" onClick={this.handleReload}>
-					<RotateCcw className="size-3.5 mr-2" />
-					Reload Panel
-				</Button>
+				<div className="flex gap-2">
+					<Button variant="outline" size="sm" onClick={this.handleResetConfig}>
+						<Eraser className="size-3.5 mr-2" />
+						Reset Config
+					</Button>
+					<Button variant="outline" size="sm" onClick={this.handleReload}>
+						<RotateCcw className="size-3.5 mr-2" />
+						Reload Panel
+					</Button>
+				</div>
 			</div>
 		)
 	}

packages/extension/src/components/HistoryDetail.tsx

@@ -1,12 +1,20 @@
-import { ArrowLeft } from 'lucide-react'
+import { ArrowLeft, RotateCcw, Trash2 } from 'lucide-react'
 import { useEffect, useState } from 'react'
 
 import { Button } from '@/components/ui/button'
-import { type SessionRecord, getSession } from '@/lib/db'
+import { type SessionRecord, deleteSession, getSession } from '@/lib/db'
 
 import { EventCard } from './cards'
 
-export function HistoryDetail({ sessionId, onBack }: { sessionId: string; onBack: () => void }) {
+export function HistoryDetail({
+	sessionId,
+	onBack,
+	onRerun,
+}: {
+	sessionId: string
+	onBack: () => void
+	onRerun: (task: string) => void
+}) {
 	const [session, setSession] = useState<SessionRecord | null>(null)
 
 	useEffect(() => {
@@ -37,12 +45,32 @@ export function HistoryDetail({ sessionId, onBack }: { sessionId: string; onBack
 				<div className="text-xs font-medium" title={session.task}>
 					{session.task}
 				</div>
+				<div className="mt-2 flex items-center gap-2">
+					<button
+						type="button"
+						onClick={() => onRerun(session.task)}
+						className="flex items-center gap-1 text-[10px] text-muted-foreground hover:text-foreground transition-colors cursor-pointer disabled:opacity-50 disabled:cursor-not-allowed"
+					>
+						<RotateCcw className="size-3" />
+						Run again
+					</button>
+					<button
+						type="button"
+						onClick={async () => {
+							await deleteSession(sessionId)
+							onBack()
+						}}
+						className="flex items-center gap-1 text-[10px] text-muted-foreground hover:text-destructive transition-colors cursor-pointer"
+					>
+						<Trash2 className="size-3" />
+						Delete
+					</button>
+				</div>
 			</div>
 
 			{/* Events (read-only) */}
 			<div className="flex-1 overflow-y-auto p-3 space-y-2">
 				{session.history.map((event, index) => (
-					// eslint-disable-next-line react-x/no-array-index-key
 					<EventCard key={index} event={event} />
 				))}
 			</div>

packages/extension/src/components/HistoryList.tsx

@@ -0,0 +1,181 @@
+import {
+	ArrowDownToLine,
+	ArrowLeft,
+	CheckCircle,
+	History,
+	RotateCcw,
+	Trash2,
+	XCircle,
+} from 'lucide-react'
+import { useCallback, useEffect, useState } from 'react'
+
+import { Button } from '@/components/ui/button'
+import { type SessionRecord, clearSessions, deleteSession, listSessions } from '@/lib/db'
+import { downloadHistoryExport } from '@/lib/history-export'
+
+function timeAgo(ts: number): string {
+	const seconds = Math.floor((Date.now() - ts) / 1000)
+	if (seconds < 60) return 'just now'
+	const minutes = Math.floor(seconds / 60)
+	if (minutes < 60) return `${minutes}m ago`
+	const hours = Math.floor(minutes / 60)
+	if (hours < 24) return `${hours}h ago`
+	const days = Math.floor(hours / 24)
+	return `${days}d ago`
+}
+
+export function HistoryList({
+	onSelect,
+	onBack,
+	onRerun,
+}: {
+	onSelect: (id: string) => void
+	onBack: () => void
+	onRerun: (task: string) => void
+}) {
+	const [sessions, setSessions] = useState<SessionRecord[]>([])
+	const [loading, setLoading] = useState(true)
+
+	const load = useCallback(async () => {
+		try {
+			setSessions(await listSessions())
+		} catch (err) {
+			console.error('[HistoryList] Failed to load sessions:', err)
+		} finally {
+			setLoading(false)
+		}
+	}, [])
+
+	useEffect(() => {
+		load()
+	}, [load])
+
+	const handleDelete = async (e: React.MouseEvent, id: string) => {
+		e.stopPropagation()
+		await deleteSession(id)
+		setSessions((prev) => prev.filter((s) => s.id !== id))
+	}
+
+	const handleExport = (e: React.MouseEvent, session: SessionRecord) => {
+		e.stopPropagation()
+		downloadHistoryExport(session.task, session.createdAt, session.history)
+	}
+
+	const handleRerun = (e: React.MouseEvent, task: string) => {
+		e.stopPropagation()
+		onRerun(task)
+	}
+
+	return (
+		<div className="flex flex-col h-screen bg-background">
+			{/* Header */}
+			<header className="flex items-center gap-2 border-b px-3 py-2">
+				<Button
+					variant="ghost"
+					size="icon-sm"
+					onClick={onBack}
+					className="cursor-pointer"
+					aria-label="Back"
+					title="Back"
+				>
+					<ArrowLeft className="size-3.5" />
+				</Button>
+				<span className="text-sm font-medium flex-1">History</span>
+				{sessions.length > 0 && (
+					<Button
+						variant="ghost"
+						size="sm"
+						onClick={async () => {
+							await clearSessions()
+							setSessions([])
+						}}
+						className="text-[10px] text-muted-foreground hover:text-destructive cursor-pointer h-6 px-2"
+					>
+						<Trash2 className="size-3 mr-1" />
+						Clear All
+					</Button>
+				)}
+			</header>
+
+			{/* List */}
+			<div className="flex-1 overflow-y-auto">
+				{loading && (
+					<div className="flex flex-col" aria-label="Loading history" aria-busy="true">
+						{[...Array(4)].map((_, i) => (
+							<div key={i} className="flex items-start gap-2 px-3 py-2.5 border-b">
+								<div className="size-3.5 mt-0.5 rounded-full bg-muted animate-pulse shrink-0" />
+								<div className="flex-1 space-y-1.5">
+									<div className="h-2.5 bg-muted animate-pulse rounded w-3/4" />
+									<div className="h-2 bg-muted animate-pulse rounded w-1/3" />
+								</div>
+							</div>
+						))}
+					</div>
+				)}
+
+				{!loading && sessions.length === 0 && (
+					<div className="flex flex-col items-center justify-center h-40 gap-2 text-muted-foreground">
+						<History className="size-8 opacity-30" />
+						<p className="text-xs">No history yet</p>
+					</div>
+				)}
+
+				{sessions.map((session) => (
+					<div
+						key={session.id}
+						role="button"
+						tabIndex={0}
+						onClick={() => onSelect(session.id)}
+						className="w-full text-left px-3 py-2.5 border-b hover:bg-muted/50 transition-colors cursor-pointer flex items-start gap-2 group"
+					>
+						{/* Status icon */}
+						{session.status === 'completed' ? (
+							<CheckCircle className="size-3.5 text-green-500 shrink-0 mt-0.5" />
+						) : (
+							<XCircle className="size-3.5 text-destructive shrink-0 mt-0.5" />
+						)}
+
+						{/* Content */}
+						<div className="flex-1 min-w-0">
+							<p className="text-xs font-medium truncate">{session.task}</p>
+							<div className="flex items-center mt-0.5">
+								<p className="text-[10px] text-muted-foreground">
+									{timeAgo(session.createdAt)} · {session.history.length} steps
+								</p>
+								<div className="flex items-center gap-0.5 ml-auto opacity-0 group-hover:opacity-100 transition-opacity">
+									<button
+										type="button"
+										onClick={(e) => handleRerun(e, session.task)}
+										className="p-0.5 text-muted-foreground hover:text-foreground transition-colors cursor-pointer"
+										title="Run task again"
+										aria-label={`Run history task again: ${session.task}`}
+									>
+										<RotateCcw className="size-3" />
+									</button>
+									<button
+										type="button"
+										onClick={(e) => handleExport(e, session)}
+										className="p-1 text-muted-foreground hover:text-foreground transition-colors cursor-pointer"
+										title="Export history JSON"
+										aria-label={`Export history for ${session.task}`}
+									>
+										<ArrowDownToLine className="size-3" />
+									</button>
+									<button
+										type="button"
+										onClick={(e) => handleDelete(e, session.id)}
+										className="p-0.5 text-muted-foreground hover:text-destructive transition-colors cursor-pointer"
+										title="Delete history"
+										aria-label={`Delete history for ${session.task}`}
+									>
+										<Trash2 className="size-3" />
+									</button>
+								</div>
+							</div>
+						</div>
+					</div>
+				))}
+			</div>
+		</div>
+	)
+}

packages/extension/src/components/cards.tsx

@@ -54,7 +54,7 @@ function ResultCard({
 					Result: {success ? 'Success' : 'Failed'}
 				</span>
 			</div>
-			<p className="text-xs text-[11px] text-muted-foreground pl-5 whitespace-pre-wrap">{text}</p>
+			<p className="text-[12px] text-foreground pl-5 whitespace-pre-wrap">{text}</p>
 			{children}
 		</div>
 	)
@@ -146,6 +146,7 @@ function CopyButton({ text, label }: { text: string; label: string }) {
 function extractPrompt(rawRequest: unknown, role: 'system' | 'user'): string | null {
 	const messages = (rawRequest as { messages?: { role: string; content?: unknown }[] })?.messages
 	if (!messages) return null
+	if (!Array.isArray(messages)) return null
 	const msg =
 		role === 'system'
 			? messages.find((m) => m.role === role)

packages/extension/src/components/misc.tsx

@@ -14,6 +14,7 @@ export function StatusDot({ status }: { status: AgentStatus }) {
 		running: 'bg-blue-500',
 		completed: 'bg-green-500',
 		error: 'bg-destructive',
+		stopped: 'bg-muted-foreground',
 	}[status]
 
 	const label = {
@@ -21,6 +22,7 @@ export function StatusDot({ status }: { status: AgentStatus }) {
 		running: 'Running',
 		completed: 'Done',
 		error: 'Error',
+		stopped: 'Stopped',
 	}[status]
 
 	return (
@@ -84,7 +86,7 @@ export function MotionOverlay({ active }: { active: boolean }) {
 	return (
 		<div
 			ref={containerRef}
-			className="pointer-events-none absolute inset-0 z-10 opacity-60"
+			className="pointer-events-none absolute inset-0 z-10 opacity-60 overflow-hidden"
 			style={{ display: active ? undefined : 'none' }}
 		/>
 	)
@@ -111,6 +113,7 @@ export function EmptyState() {
 					]}
 					cursorStyle="underscore"
 					loop
+					startOnView={false}
 					typeSpeed={20}
 					deleteSpeed={10}
 					pauseDelay={3000}

packages/extension/src/components/ui/switch.tsx

@@ -8,7 +8,7 @@ function Switch({ className, ...props }: React.ComponentProps<typeof SwitchPrimi
 		<SwitchPrimitive.Root
 			data-slot="switch"
 			className={cn(
-				'peer data-[state=checked]:bg-primary data-[state=unchecked]:bg-input focus-visible:border-ring focus-visible:ring-ring/50 dark:data-[state=unchecked]:bg-input/80 inline-flex h-[1.15rem] w-8 shrink-0 items-center rounded-full border border-transparent shadow-xs transition-all outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50',
+				'peer data-[state=checked]:bg-primary data-[state=unchecked]:bg-input focus-visible:border-ring focus-visible:ring-ring/50 dark:data-[state=unchecked]:bg-input/80 inline-flex h-[1.15rem] w-8 shrink-0 cursor-pointer items-center rounded-full border border-transparent shadow-xs transition-all outline-none focus-visible:ring-[3px] disabled:cursor-not-allowed disabled:opacity-50',
 				className
 			)}
 			{...props}

packages/extension/src/entrypoints/background.ts

@@ -1,12 +1,12 @@
 import { handlePageControlMessage } from '@/agent/RemotePageController.background'
-import { handleTabControlMessage, setupTabChangeEvents } from '@/agent/TabsController.background'
+import { handleTabControlMessage, setupTabEventsPort } from '@/agent/TabsController.background'
 
 export default defineBackground(() => {
 	console.log('[Background] Service Worker started')
 
 	// tab change events
 
-	setupTabChangeEvents()
+	setupTabEventsPort()
 
 	// generate user auth token
 
@@ -30,7 +30,34 @@ export default defineBackground(() => {
 		}
 	})
 
+	// external messages (from localhost launcher page via externally_connectable)
+
+	chrome.runtime.onMessageExternal.addListener((message, sender, sendResponse) => {
+		if (message.type === 'OPEN_HUB') {
+			openOrFocusHubTab(message.wsPort).then(() => {
+				if (sender.tab?.id) chrome.tabs.remove(sender.tab.id)
+				sendResponse({ ok: true })
+			})
+			return true
+		}
+	})
+
 	// setup
 
 	chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true }).catch(() => {})
 })
+
+async function openOrFocusHubTab(wsPort: number) {
+	const hubUrl = chrome.runtime.getURL('hub.html')
+	const existing = await chrome.tabs.query({ url: `${hubUrl}*` })
+
+	if (existing.length > 0 && existing[0].id) {
+		await chrome.tabs.update(existing[0].id, {
+			active: true,
+			url: `${hubUrl}?ws=${wsPort}`,
+		})
+		return
+	}
+
+	await chrome.tabs.create({ url: `${hubUrl}?ws=${wsPort}`, pinned: true })
+}

packages/extension/src/entrypoints/content.ts

@@ -46,6 +46,8 @@ async function exposeAgentToPage() {
 	let multiPageAgent: InstanceType<typeof MultiPageAgent> | null = null
 
 	window.addEventListener('message', async (e) => {
+		if (e.source !== window) return
+
 		const data = e.data
 		if (typeof data !== 'object' || data === null) return
 		if (data.channel !== 'PAGE_AGENT_EXT_REQUEST') return
@@ -70,11 +72,15 @@ async function exposeAgentToPage() {
 
 				try {
 					const { task, config } = payload
+					const { systemInstruction, ...agentConfig } = config
 
 					// Dispose old instance before creating new one
 					multiPageAgent?.dispose()
 
-					multiPageAgent = new MultiPageAgent(config)
+					multiPageAgent = new MultiPageAgent({
+						...agentConfig,
+						instructions: systemInstruction ? { system: systemInstruction } : undefined,
+					})
 
 					// events
 

packages/extension/src/entrypoints/hub/App.tsx

@@ -0,0 +1,250 @@
+import { FoldVertical, Plug, PlugZap, Square, UnfoldVertical, Unplug } from 'lucide-react'
+import { useEffect, useRef, useState } from 'react'
+
+import { useAgent } from '@/agent/useAgent'
+import { ActivityCard, EventCard } from '@/components/cards'
+import { Logo, MotionOverlay, StatusDot } from '@/components/misc'
+import { Button } from '@/components/ui/button'
+import { Switch } from '@/components/ui/switch'
+
+import { useHubWs } from './hub-ws'
+
+export default function App() {
+	const { status, history, activity, currentTask, config, execute, stop, configure } = useAgent()
+	const { wsState } = useHubWs(execute, stop, configure, config)
+
+	const historyRef = useRef<HTMLDivElement>(null)
+
+	useEffect(() => {
+		if (historyRef.current) {
+			historyRef.current.scrollTop = historyRef.current.scrollHeight
+		}
+	}, [history, activity])
+
+	const isRunning = status === 'running'
+	const WsIcon = wsState === 'connected' ? PlugZap : wsState === 'connecting' ? Plug : Unplug
+	const wsLabel = {
+		connected: 'Connected',
+		connecting: 'Connecting…',
+		disconnected: new URLSearchParams(location.search).get('ws') ? 'Disconnected' : 'No connection',
+	}[wsState]
+
+	return (
+		<div className="flex h-screen bg-background">
+			{/* Left — Protocol docs */}
+			<aside className="w-80 shrink-0 border-r flex flex-col bg-muted/20">
+				<a
+					href="https://alibaba.github.io/page-agent/"
+					target="_blank"
+					rel="noopener noreferrer"
+					className="flex items-center gap-2 px-5 h-12 border-b hover:bg-muted/30 transition-colors"
+				>
+					<Logo className="size-5" />
+					<span className="text-sm font-semibold tracking-tight">Page Agent Hub</span>
+					<span className="text-[9px] font-medium uppercase tracking-wider text-amber-600 bg-amber-500/10 border border-amber-500/30 rounded px-1.5 py-0.5">
+						Beta
+					</span>
+				</a>
+
+				<div className="flex-1 overflow-y-auto px-5 py-4 space-y-6">
+					<div className="text-xs text-muted-foreground leading-relaxed space-y-2">
+						<p>
+							Page Agent Hub lets local apps (e.g. MCP servers) control the Page Agent extension via
+							WebSocket.
+						</p>
+						<p>
+							Check out the official{' '}
+							<a
+								href="https://github.com/alibaba/page-agent/tree/main/packages/mcp"
+								target="_blank"
+								rel="noopener noreferrer"
+								className="underline hover:text-foreground"
+							>
+								MCP server package
+							</a>
+							.
+						</p>
+					</div>
+
+					<HubConfig />
+
+					<ProtocolDocsCollapsible />
+				</div>
+
+				<div className="border-t px-5 py-3 text-[10px] text-muted-foreground/60 flex items-center justify-between">
+					<span className="font-mono">v{__VERSION__}</span>
+					<span>
+						Built with ♥️ by{' '}
+						<a
+							href="https://github.com/gaomeng1900"
+							target="_blank"
+							rel="noopener noreferrer"
+							className="underline hover:text-foreground"
+						>
+							@Simon
+						</a>
+					</span>
+				</div>
+			</aside>
+
+			{/* Right — Live session */}
+			<main className="flex-1 flex flex-col min-w-0 relative">
+				<MotionOverlay active={isRunning} />
+
+				<header className="flex items-center justify-between border-b px-5 h-12">
+					<div className="flex items-center gap-2 text-xs text-muted-foreground">
+						<WsIcon className="size-3.5" />
+						<span>{wsLabel}</span>
+					</div>
+					<div className="flex items-center gap-3">
+						<StatusDot status={status} />
+						{isRunning && (
+							<Button variant="destructive" size="sm" onClick={stop} className="h-7 text-xs">
+								<Square className="size-3 mr-1" />
+								Stop
+							</Button>
+						)}
+					</div>
+				</header>
+
+				{/* Task banner */}
+				{currentTask && (
+					<div className="border-b px-5 py-2 bg-muted/30">
+						<div className="text-[10px] text-muted-foreground uppercase tracking-wide">
+							Current Task
+						</div>
+						<div className="text-sm font-medium truncate" title={currentTask}>
+							{currentTask}
+						</div>
+					</div>
+				)}
+
+				{/* Event stream */}
+				<div ref={historyRef} className="flex-1 overflow-y-auto p-5 space-y-2">
+					{!currentTask && history.length === 0 && !isRunning && (
+						<div className="flex flex-col items-center justify-center h-full text-muted-foreground gap-3">
+							<WsIcon className="size-10 opacity-30" />
+							<p className="text-sm">
+								{wsState === 'connected'
+									? 'Waiting for task from external caller…'
+									: 'No active session'}
+							</p>
+						</div>
+					)}
+
+					{history.map((event, index) => (
+						<EventCard key={index} event={event} />
+					))}
+
+					{activity && <ActivityCard activity={activity} />}
+				</div>
+			</main>
+		</div>
+	)
+}
+
+function HubConfig() {
+	const [allowAll, setAllowAll] = useState(false)
+
+	useEffect(() => {
+		chrome.storage.local.get('allowAllHubConnection').then((r) => {
+			setAllowAll(r.allowAllHubConnection === true)
+		})
+	}, [])
+
+	const toggle = (checked: boolean) => {
+		setAllowAll(checked)
+		chrome.storage.local.set({ allowAllHubConnection: checked })
+	}
+
+	return (
+		<div>
+			<h3 className="text-[11px] font-semibold text-foreground/80 uppercase tracking-wider mb-2">
+				Config
+			</h3>
+			<div className="group/hub relative">
+				<label
+					className={`flex items-center justify-between p-3 rounded-md border cursor-pointer text-xs ${allowAll ? 'bg-amber-500/10 border-amber-500/30 text-amber-600' : 'bg-muted/50 text-muted-foreground'}`}
+				>
+					Auto-approve connections
+					<Switch
+						checked={allowAll}
+						onCheckedChange={toggle}
+						className={allowAll ? 'data-[state=checked]:bg-amber-500' : ''}
+					/>
+				</label>
+
+				{/* hide with invisible absolute opacity-0*/}
+				<div className="group-hover/hub:visible group-hover/hub:opacity-100 transition-opacity duration-150  left-0 right-0 top-full z-10 pt-2">
+					<div className="relative p-2.5 rounded-md border border-border bg-background/60 backdrop-blur-md shadow-2xl text-muted-foreground text-xs leading-relaxed">
+						<div className="absolute -top-1.5 left-5 size-3 rotate-45 rounded-[1px] border-l border-t border-border bg-background/60 backdrop-blur-md" />
+						By default, each connection requires your approval before running tasks. <br />
+						Enable this to skip per-session approval.
+						<br />
+						<span className="font-semibold">* Use with caution!</span>
+					</div>
+				</div>
+			</div>
+		</div>
+	)
+}
+
+function ProtocolDocsCollapsible() {
+	const [open, setOpen] = useState(false)
+
+	return (
+		<div>
+			<button
+				type="button"
+				onClick={() => setOpen(!open)}
+				className="flex items-center gap-1 text-[11px] font-semibold text-foreground/80 uppercase tracking-wider cursor-pointer"
+			>
+				Docs
+				{open ? <FoldVertical className="size-3" /> : <UnfoldVertical className="size-3" />}
+			</button>
+
+			{open && (
+				<div className="mt-3 space-y-4 text-xs text-muted-foreground">
+					<p className="text-[10px]">
+						Connect via <code className="text-[10px]">hub.html?ws=PORT</code>
+					</p>
+
+					<section>
+						<h4 className="text-[11px] font-medium text-foreground/60 mb-1.5">Flow</h4>
+						<ol className="list-decimal list-inside space-y-1 text-[11px] leading-relaxed">
+							<li>Hub opens WS to caller's server</li>
+							<li>
+								Sends <code className="text-[10px]">ready</code>
+							</li>
+							<li>
+								Caller sends <code className="text-[10px]">execute</code> with task
+							</li>
+							<li>Hub runs agent, streams events</li>
+							<li>
+								Hub sends <code className="text-[10px]">result</code> or{' '}
+								<code className="text-[10px]">error</code>
+							</li>
+						</ol>
+					</section>
+
+					<section>
+						<h4 className="text-[11px] font-medium text-foreground/60 mb-1.5">Caller → Hub</h4>
+						<pre className="bg-muted/50 rounded-md p-3 font-mono text-[10px] leading-relaxed whitespace-pre-wrap">
+							{`{ type: "execute", task: string, config?: object }
+{ type: "stop" }`}
+						</pre>
+					</section>
+
+					<section>
+						<h4 className="text-[11px] font-medium text-foreground/60 mb-1.5">Hub → Caller</h4>
+						<pre className="bg-muted/50 rounded-md p-3 font-mono text-[10px] leading-relaxed whitespace-pre-wrap">
+							{`{ type: "ready" }
+{ type: "result", success: boolean, data: string }
+{ type: "error", message: string }`}
+						</pre>
+					</section>
+				</div>
+			)}
+		</div>
+	)
+}

packages/extension/src/entrypoints/hub/hub-ws.ts

@@ -0,0 +1,243 @@
+/**
+ * Hub WebSocket Protocol
+ *
+ * Hub connects as WS client to `ws://localhost:{port}`.
+ * All messages are JSON. One task at a time.
+ *
+ * Inbound (Caller → Hub):
+ *   { type: "execute", task: string, config?: object }
+ *   { type: "stop" }
+ *
+ * Outbound (Hub → Caller):
+ *   { type: "ready" }
+ *   { type: "result", success: boolean, data: string }
+ *   { type: "error", message: string }
+ */
+import type { ExecutionResult } from '@page-agent/core'
+import { useEffect, useRef, useState } from 'react'
+
+import type { ExtConfig } from '@/agent/useAgent'
+
+// --- Protocol types ---
+
+interface ExecuteMessage {
+	type: 'execute'
+	task: string
+	config?: Record<string, unknown>
+}
+
+interface StopMessage {
+	type: 'stop'
+}
+
+type InboundMessage = ExecuteMessage | StopMessage
+
+interface ReadyMessage {
+	type: 'ready'
+}
+
+interface ResultMessage {
+	type: 'result'
+	success: boolean
+	data: string
+}
+
+interface ErrorMessage {
+	type: 'error'
+	message: string
+}
+
+type OutboundMessage = ReadyMessage | ResultMessage | ErrorMessage
+
+export type HubWsState = 'connecting' | 'connected' | 'disconnected'
+
+// --- HubWs class ---
+
+export interface HubWsHandlers {
+	onExecute: (
+		task: string,
+		config?: Record<string, unknown>
+	) => Promise<{ success: boolean; data: string }>
+	onStop: () => void
+}
+
+/**
+ * Framework-agnostic WebSocket client for Hub.
+ * Connects to an external WS server, receives tasks, dispatches to handlers,
+ * and sends results back. No React, no DOM.
+ */
+export class HubWs {
+	#ws: WebSocket | null = null
+	#state: HubWsState = 'disconnected'
+	#busy = false
+	#approved = false
+	#handlers: HubWsHandlers
+	#port: number
+	#onStateChange: (state: HubWsState) => void
+
+	constructor(port: number, handlers: HubWsHandlers, onStateChange: (state: HubWsState) => void) {
+		this.#port = port
+		this.#handlers = handlers
+		this.#onStateChange = onStateChange
+	}
+
+	get state() {
+		return this.#state
+	}
+
+	get busy() {
+		return this.#busy
+	}
+
+	connect() {
+		if (this.#ws) return
+		this.#setState('connecting')
+
+		const ws = new WebSocket(`ws://localhost:${this.#port}`)
+		this.#ws = ws
+
+		ws.addEventListener('open', () => {
+			this.#setState('connected')
+			this.#send({ type: 'ready' })
+		})
+
+		ws.addEventListener('close', () => {
+			this.#ws = null
+			this.#busy = false
+			this.#approved = false
+			this.#setState('disconnected')
+		})
+
+		ws.addEventListener('message', (event) => {
+			this.#handleMessage(event.data as string)
+		})
+	}
+
+	disconnect() {
+		this.#ws?.close()
+		this.#ws = null
+		this.#busy = false
+		this.#approved = false
+		this.#setState('disconnected')
+	}
+
+	#setState(state: HubWsState) {
+		if (this.#state === state) return
+		this.#state = state
+		this.#onStateChange(state)
+	}
+
+	#send(msg: OutboundMessage) {
+		if (this.#ws?.readyState === WebSocket.OPEN) {
+			this.#ws.send(JSON.stringify(msg))
+		}
+	}
+
+	async #handleMessage(raw: string) {
+		let msg: InboundMessage
+		try {
+			msg = JSON.parse(raw)
+		} catch {
+			return
+		}
+
+		if (!(await this.#checkApproval())) {
+			this.#send({ type: 'error', message: 'User denied the connection request.' })
+			return
+		}
+
+		switch (msg.type) {
+			case 'execute':
+				this.#handleExecute(msg)
+				break
+			case 'stop':
+				this.#handlers.onStop()
+				break
+		}
+	}
+
+	async #checkApproval(): Promise<boolean> {
+		if (this.#approved) return true
+
+		const { allowAllHubConnection } = await chrome.storage.local.get('allowAllHubConnection')
+		if (allowAllHubConnection === true) {
+			this.#approved = true
+			return true
+		}
+
+		const ok = window.confirm(
+			'An external application is requesting to control your browser via Page Agent Ext.\nAllow this session?'
+		)
+		if (ok) this.#approved = true
+		return ok
+	}
+
+	async #handleExecute(msg: ExecuteMessage) {
+		if (this.#busy) {
+			this.#send({ type: 'error', message: 'Hub is busy with another task' })
+			return
+		}
+
+		this.#busy = true
+		try {
+			const result = await this.#handlers.onExecute(msg.task, msg.config)
+			this.#send({ type: 'result', success: result.success, data: result.data })
+		} catch (err) {
+			this.#send({ type: 'error', message: err instanceof Error ? err.message : String(err) })
+		} finally {
+			this.#busy = false
+		}
+	}
+}
+
+// --- React hook ---
+
+/**
+ * React hook that bridges HubWs to the agent's execute/stop/configure.
+ * Handles the config-before-execute dance internally.
+ */
+export function useHubWs(
+	execute: (task: string) => Promise<ExecutionResult>,
+	stop: () => void,
+	configure: (config: ExtConfig) => Promise<void>,
+	config: ExtConfig | null
+): { wsState: HubWsState } {
+	const wsPort = new URLSearchParams(location.search).get('ws')
+	const [wsState, setWsState] = useState<HubWsState>(() => (wsPort ? 'connecting' : 'disconnected'))
+	const hubWsRef = useRef<HubWs | null>(null)
+
+	const latestRef = useRef({ execute, stop, configure, config })
+	useEffect(() => {
+		latestRef.current = { execute, stop, configure, config }
+	})
+
+	useEffect(() => {
+		if (!wsPort) return
+
+		const hubWs = new HubWs(
+			Number(wsPort),
+			{
+				onExecute: async (task, incomingConfig) => {
+					const { execute, configure, config } = latestRef.current
+					if (incomingConfig) {
+						await configure({ ...config, ...incomingConfig } as ExtConfig)
+					}
+					const result = await execute(task)
+					return { success: result.success, data: result.data }
+				},
+				onStop: () => latestRef.current.stop(),
+			},
+			setWsState
+		)
+
+		hubWs.connect()
+		hubWsRef.current = hubWs
+
+		return () => {
+			hubWs.disconnect()
+			hubWsRef.current = null
+		}
+	}, [wsPort])
+
+	return { wsState }
+}

packages/extension/src/entrypoints/hub/index.html

@@ -0,0 +1,13 @@
+<!doctype html>
+<html>
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<link rel="icon" type="image/png" href="/assets/page-agent-64.png" />
+		<title>Page Agent Hub</title>
+	</head>
+	<body>
+		<div id="root"></div>
+		<script type="module" src="./main.tsx"></script>
+	</body>
+</html>

packages/extension/src/entrypoints/hub/main.tsx

@@ -0,0 +1,25 @@
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+
+import { ErrorBoundary } from '@/components/ErrorBoundary'
+
+import App from './App'
+
+import '@/assets/index.css'
+
+const syncDarkMode = () => {
+	document.documentElement.classList.toggle(
+		'dark',
+		matchMedia('(prefers-color-scheme: dark)').matches
+	)
+}
+syncDarkMode()
+matchMedia('(prefers-color-scheme: dark)').addEventListener('change', syncDarkMode)
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+	<React.StrictMode>
+		<ErrorBoundary>
+			<App />
+		</ErrorBoundary>
+	</React.StrictMode>
+)

packages/extension/src/entrypoints/main-world.ts

@@ -4,8 +4,14 @@ export type Execute = (task: string, config: ExecuteConfig) => Promise<Execution
 
 export interface ExecuteConfig {
 	baseURL: string
-	apiKey: string
 	model: string
+	apiKey?: string
+
+	/**
+	 * Global system-level instructions for the agent.
+	 * Equivalent to `AgentConfig.instructions.system`.
+	 */
+	systemInstruction?: string
 
 	/**
 	 * Whether to include the initial tab (that holds this main world script) in the task.
@@ -13,6 +19,9 @@ export interface ExecuteConfig {
 	 */
 	includeInitialTab?: boolean
 
+	/** Control all unpinned tabs in the window instead of only the tab group. */
+	experimentalIncludeAllTabs?: boolean
+
 	onStatusChange?: (status: AgentStatus) => void
 	onActivity?: (activity: AgentActivity) => void
 	onHistoryUpdate?: (history: HistoricalEvent[]) => void
@@ -30,13 +39,14 @@ export default defineUnlistedScript(() => {
 		if (task.trim().length === 0) throw new Error('Task cannot be empty')
 		if (!config) throw new Error('Config is required')
 		if (!config.baseURL) throw new Error('Config must have a baseURL')
-		if (!config.apiKey) throw new Error('Config must have an apiKey')
 		if (!config.model) throw new Error('Config must have a model')
 
 		const id = getId()
 
 		const promise = new Promise<ExecutionResult>((resolve, reject) => {
 			function handleMessage(e: MessageEvent) {
+				if (e.source !== window) return
+
 				const data = e.data
 				if (typeof data !== 'object' || data === null) return
 				if (data.channel !== 'PAGE_AGENT_EXT_RESPONSE') return
@@ -85,9 +95,11 @@ export default defineUnlistedScript(() => {
 					task,
 					config: {
 						baseURL: config.baseURL,
-						apiKey: config.apiKey,
 						model: config.model,
+						apiKey: config.apiKey,
+						systemInstruction: config.systemInstruction,
 						includeInitialTab: config.includeInitialTab,
+						experimentalIncludeAllTabs: config.experimentalIncludeAllTabs,
 					},
 				},
 			},
@@ -110,9 +122,9 @@ export default defineUnlistedScript(() => {
 		)
 	}
 
-	;(window as any).PAGE_AGENT_EXT_VERSION = __EXT_VERSION__
+	;(window as any).PAGE_AGENT_EXT_VERSION = __VERSION__
 	;(window as any).PAGE_AGENT_EXT = {
-		version: __EXT_VERSION__,
+		version: __VERSION__,
 		execute,
 		stop,
 	}

packages/extension/src/entrypoints/sidepanel/App.tsx

@@ -1,6 +1,11 @@
 import { History, Send, Settings, Square } from 'lucide-react'
 import { useCallback, useEffect, useRef, useState } from 'react'
 
+import { ConfigPanel } from '@/components/ConfigPanel'
+import { HistoryDetail } from '@/components/HistoryDetail'
+import { HistoryList } from '@/components/HistoryList'
+import { ActivityCard, EventCard } from '@/components/cards'
+import { EmptyState, Logo, MotionOverlay, StatusDot } from '@/components/misc'
 import { Button } from '@/components/ui/button'
 import {
 	InputGroup,
@@ -11,11 +16,6 @@ import {
 import { saveSession } from '@/lib/db'
 
 import { useAgent } from '../../agent/useAgent'
-import { ConfigPanel } from './components/ConfigPanel'
-import { HistoryDetail } from './components/HistoryDetail'
-import { HistoryList } from './components/HistoryList'
-import { ActivityCard, EventCard } from './components/cards'
-import { EmptyState, Logo, MotionOverlay, StatusDot } from './components/misc'
 
 type View =
 	| { name: 'chat' }
@@ -39,7 +39,7 @@ export default function App() {
 
 		if (
 			prev === 'running' &&
-			(status === 'completed' || status === 'error') &&
+			(status === 'completed' || status === 'error' || status === 'stopped') &&
 			history.length > 0 &&
 			currentTask
 		) {
@@ -56,19 +56,27 @@ export default function App() {
 		}
 	}, [history, activity])
 
-	const handleSubmit = useCallback(
-		(e?: React.SyntheticEvent) => {
-			e?.preventDefault()
-			if (!inputValue.trim() || status === 'running') return
+	const runTask = useCallback(
+		(task: string) => {
+			const normalizedTask = task.trim()
+			if (!normalizedTask || status === 'running') return
 
-			const taskToExecute = inputValue.trim()
 			setInputValue('')
+			setView({ name: 'chat' })
 
-			execute(taskToExecute).catch((error) => {
+			execute(normalizedTask).catch((error) => {
 				console.error('[SidePanel] Failed to execute task:', error)
 			})
 		},
-		[inputValue, status, execute]
+		[execute, status]
+	)
+
+	const handleSubmit = useCallback(
+		(e?: React.SyntheticEvent) => {
+			e?.preventDefault()
+			runTask(inputValue)
+		},
+		[inputValue, runTask]
 	)
 
 	const handleStop = useCallback(() => {
@@ -103,12 +111,19 @@ export default function App() {
 			<HistoryList
 				onSelect={(id) => setView({ name: 'history-detail', sessionId: id })}
 				onBack={() => setView({ name: 'chat' })}
+				onRerun={runTask}
 			/>
 		)
 	}
 
 	if (view.name === 'history-detail') {
-		return <HistoryDetail sessionId={view.sessionId} onBack={() => setView({ name: 'history' })} />
+		return (
+			<HistoryDetail
+				sessionId={view.sessionId}
+				onBack={() => setView({ name: 'history' })}
+				onRerun={runTask}
+			/>
+		)
 	}
 
 	// --- Chat view ---
@@ -132,6 +147,8 @@ export default function App() {
 						size="icon-sm"
 						onClick={() => setView({ name: 'history' })}
 						className="cursor-pointer"
+						aria-label="History"
+						title="History"
 					>
 						<History className="size-3.5" />
 					</Button>
@@ -140,6 +157,8 @@ export default function App() {
 						size="icon-sm"
 						onClick={() => setView({ name: 'config' })}
 						className="cursor-pointer"
+						aria-label="Settings"
+						title="Settings"
 					>
 						<Settings className="size-3.5" />
 					</Button>
@@ -163,7 +182,6 @@ export default function App() {
 					{showEmptyState && <EmptyState />}
 
 					{history.map((event, index) => (
-						// eslint-disable-next-line react-x/no-array-index-key
 						<EventCard key={index} event={event} />
 					))}
 
@@ -191,6 +209,8 @@ export default function App() {
 								variant="destructive"
 								onClick={handleStop}
 								className="size-7"
+								aria-label="Stop task"
+								title="Stop task"
 							>
 								<Square className="size-3" />
 							</InputGroupButton>
@@ -201,6 +221,8 @@ export default function App() {
 								onClick={() => handleSubmit()}
 								disabled={!inputValue.trim()}
 								className="size-7 cursor-pointer"
+								aria-label="Send"
+								title="Send"
 							>
 								<Send className="size-3" />
 							</InputGroupButton>

packages/extension/src/entrypoints/sidepanel/components/HistoryList.tsx

@@ -1,119 +0,0 @@
-import { ArrowLeft, CheckCircle, Trash2, XCircle } from 'lucide-react'
-import { useCallback, useEffect, useState } from 'react'
-
-import { Button } from '@/components/ui/button'
-import { type SessionRecord, clearSessions, deleteSession, listSessions } from '@/lib/db'
-
-function timeAgo(ts: number): string {
-	const seconds = Math.floor((Date.now() - ts) / 1000)
-	if (seconds < 60) return 'just now'
-	const minutes = Math.floor(seconds / 60)
-	if (minutes < 60) return `${minutes}m ago`
-	const hours = Math.floor(minutes / 60)
-	if (hours < 24) return `${hours}h ago`
-	const days = Math.floor(hours / 24)
-	return `${days}d ago`
-}
-
-export function HistoryList({
-	onSelect,
-	onBack,
-}: {
-	onSelect: (id: string) => void
-	onBack: () => void
-}) {
-	const [sessions, setSessions] = useState<SessionRecord[]>([])
-	const [loading, setLoading] = useState(true)
-
-	const load = useCallback(async () => {
-		setSessions(await listSessions())
-		setLoading(false)
-	}, [])
-
-	useEffect(() => {
-		// eslint-disable-next-line react-hooks/set-state-in-effect
-		load()
-	}, [load])
-
-	const handleDelete = async (e: React.MouseEvent, id: string) => {
-		e.stopPropagation()
-		await deleteSession(id)
-		setSessions((prev) => prev.filter((s) => s.id !== id))
-	}
-
-	return (
-		<div className="flex flex-col h-screen bg-background">
-			{/* Header */}
-			<header className="flex items-center gap-2 border-b px-3 py-2">
-				<Button variant="ghost" size="icon-sm" onClick={onBack} className="cursor-pointer">
-					<ArrowLeft className="size-3.5" />
-				</Button>
-				<span className="text-sm font-medium flex-1">History</span>
-				{sessions.length > 0 && (
-					<Button
-						variant="ghost"
-						size="sm"
-						onClick={async () => {
-							await clearSessions()
-							setSessions([])
-						}}
-						className="text-[10px] text-muted-foreground hover:text-destructive cursor-pointer h-6 px-2"
-					>
-						<Trash2 className="size-3 mr-1" />
-						Clear All
-					</Button>
-				)}
-			</header>
-
-			{/* List */}
-			<div className="flex-1 overflow-y-auto">
-				{loading && (
-					<div className="flex items-center justify-center h-32 text-xs text-muted-foreground">
-						Loading...
-					</div>
-				)}
-
-				{!loading && sessions.length === 0 && (
-					<div className="flex items-center justify-center h-32 text-xs text-muted-foreground">
-						No history yet
-					</div>
-				)}
-
-				{sessions.map((session) => (
-					<div
-						key={session.id}
-						role="button"
-						tabIndex={0}
-						onClick={() => onSelect(session.id)}
-						onKeyDown={(e) => e.key === 'Enter' && onSelect(session.id)}
-						className="w-full text-left px-3 py-2.5 border-b hover:bg-muted/50 transition-colors cursor-pointer flex items-start gap-2 group"
-					>
-						{/* Status icon */}
-						{session.status === 'completed' ? (
-							<CheckCircle className="size-3.5 text-green-500 shrink-0 mt-0.5" />
-						) : (
-							<XCircle className="size-3.5 text-destructive shrink-0 mt-0.5" />
-						)}
-
-						{/* Content */}
-						<div className="flex-1 min-w-0">
-							<p className="text-xs font-medium truncate">{session.task}</p>
-							<p className="text-[10px] text-muted-foreground mt-0.5">
-								{timeAgo(session.createdAt)} · {session.history.length} steps
-							</p>
-						</div>
-
-						{/* Delete */}
-						<button
-							type="button"
-							onClick={(e) => handleDelete(e, session.id)}
-							className="opacity-0 group-hover:opacity-100 transition-opacity p-1 hover:text-destructive cursor-pointer shrink-0"
-						>
-							<Trash2 className="size-3" />
-						</button>
-					</div>
-				))}
-			</div>
-		</div>
-	)
-}

packages/extension/src/entrypoints/sidepanel/main.tsx

@@ -1,8 +1,9 @@
 import React from 'react'
 import ReactDOM from 'react-dom/client'
 
+import { ErrorBoundary } from '@/components/ErrorBoundary'
+
 import App from './App'
-import { ErrorBoundary } from './components/ErrorBoundary'
 
 import '@/assets/index.css'
 

packages/extension/src/lib/db.ts

@@ -8,7 +8,7 @@ export interface SessionRecord {
 	id: string
 	task: string
 	history: HistoricalEvent[]
-	status: 'completed' | 'error'
+	status: 'completed' | 'error' | 'stopped'
 	createdAt: number
 }
 

packages/extension/src/lib/history-export.ts

@@ -0,0 +1,60 @@
+import type { HistoricalEvent } from '@page-agent/core'
+
+const EXPORT_FILE_PREFIX = 'page-agent-history'
+const MAX_TASK_SLUG_LENGTH = 40
+
+export function serializeHistoryExport(history: HistoricalEvent[]): string {
+	return `${JSON.stringify(history, null, 2)}\n`
+}
+
+export function buildHistoryExportFilename(task: string, createdAt: number): string {
+	const taskSlug = sanitizeTaskForFilename(task)
+	const timestamp = formatTimestampForFilename(createdAt)
+
+	return taskSlug
+		? `${EXPORT_FILE_PREFIX}-${taskSlug}-${timestamp}.json`
+		: `${EXPORT_FILE_PREFIX}-${timestamp}.json`
+}
+
+export function downloadHistoryExport(
+	task: string,
+	createdAt: number,
+	history: HistoricalEvent[]
+): void {
+	const filename = buildHistoryExportFilename(task, createdAt)
+	const content = serializeHistoryExport(history)
+	const blob = new Blob([content], { type: 'application/json;charset=utf-8' })
+	const url = URL.createObjectURL(blob)
+	const link = document.createElement('a')
+
+	link.href = url
+	link.download = filename
+	link.click()
+
+	URL.revokeObjectURL(url)
+}
+
+function sanitizeTaskForFilename(task: string): string {
+	return task
+		.trim()
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, '-')
+		.replace(/^-+|-+$/g, '')
+		.slice(0, MAX_TASK_SLUG_LENGTH)
+}
+
+function formatTimestampForFilename(createdAt: number): string {
+	const date = new Date(createdAt)
+	const year = date.getFullYear()
+	const month = pad(date.getMonth() + 1)
+	const day = pad(date.getDate())
+	const hours = pad(date.getHours())
+	const minutes = pad(date.getMinutes())
+	const seconds = pad(date.getSeconds())
+
+	return `${year}-${month}-${day}_${hours}-${minutes}-${seconds}`
+}
+
+function pad(value: number): string {
+	return value.toString().padStart(2, '0')
+}

packages/extension/src/types/globals.d.ts

@@ -1,2 +1 @@
-declare const __EXT_VERSION__: string
-declare const __CORE_VERSION__: string
+declare const __VERSION__: string

packages/extension/tsconfig.json

@@ -3,26 +3,11 @@
     "compilerOptions": {
         "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.tsbuildinfo",
         "useDefineForClassFields": true,
-        "noEmit": false,
-        "allowImportingTsExtensions": false,
         "strictNullChecks": true,
         "jsx": "react-jsx",
-        "baseUrl": ".",
+        "types": ["node", "chrome"],
         "paths": {
-            // Self root
-            "@/*": ["src/*"],
-
-            "@page-agent/llms": ["../llms/src/index.ts"],
-            "@page-agent/page-controller": ["../page-controller/src/PageController.ts"],
-            "@page-agent/core": ["../core/src/PageAgentCore.ts"],
-            "@page-agent/ui": ["../ui/src/index.ts"]
+            "@/*": ["./src/*"]
         }
-    },
-    "references": [
-        //
-        { "path": "../llms" },
-        { "path": "../page-controller" },
-        { "path": "../core" },
-        { "path": "../ui" }
-    ]
+    }
 }

packages/extension/wxt.config.js

@@ -19,8 +19,7 @@ export default defineConfig({
 	vite: () => ({
 		plugins: [tailwindcss()],
 		define: {
-			__EXT_VERSION__: JSON.stringify(pkg.version),
-			__CORE_VERSION__: JSON.stringify(pkg.dependencies['@page-agent/core']),
+			__VERSION__: JSON.stringify(pkg.version),
 		},
 		optimizeDeps: {
 			force: true,
@@ -37,7 +36,11 @@ export default defineConfig({
 			},
 		},
 	}),
+	zip: {
+		artifactTemplate: 'page-agent-ext-{{version}}-{{browser}}.zip',
+	},
 	manifest: {
+		key: 'MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAqbzT0iTYeYlnCvDJIGDnGU8oarJgZILDzSfLi/ufuSxXEPDKuMyD892GhvrMCZNVHS11Sh6NYUOc/PcUOhtaR2urHtcNkrpSJNV10zUamY7fxBdVEkOucfyLu8INVy+teis62MoRWYPaUPkfZUjrLGW8MsZ9aFzARfu9GGDEp2EAYsWDN6w6vyz9LJ82pm542EWnVT4MjmDPgvYFCWGBtaU/dfHD+GAX6URJFapsCvryVURKJ+76c/GO9/I3EX1IBfbY6dec78bLCMvVxiTmiv36KyGPwX1OpakW8IiCpXWdbAxjm+plbYlp5t5zTyyoE3sOSFeXsBH0Kg27o8GcvQIDAQAB',
 		default_locale: 'en',
 		name: '__MSG_extName__',
 		description: '__MSG_extDescription__',
@@ -59,5 +62,8 @@ export default defineConfig({
 		side_panel: {
 			default_path: 'sidepanel/index.html',
 		},
+		externally_connectable: {
+			matches: ['http://localhost/*'],
+		},
 	},
 })

packages/llms/package.json

@@ -1,15 +1,25 @@
 {
     "name": "@page-agent/llms",
-    "version": "1.5.2",
+    "version": "1.11.0",
     "type": "module",
-    "main": "./dist/lib/page-agent-llms.js",
-    "module": "./dist/lib/page-agent-llms.js",
-    "types": "./dist/lib/index.d.ts",
+    "main": "./src/index.ts",
+    "types": "./src/index.ts",
     "exports": {
         ".": {
-            "types": "./dist/lib/index.d.ts",
-            "import": "./dist/lib/page-agent-llms.js",
-            "default": "./dist/lib/page-agent-llms.js"
+            "types": "./src/index.ts",
+            "default": "./src/index.ts"
+        }
+    },
+    "publishConfig": {
+        "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": [
@@ -33,8 +43,9 @@
     "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{}})\""
+        "test": "vitest run",
+        "prepublishOnly": "node ../../scripts/pre-publish.js",
+        "postpublish": "node ../../scripts/post-publish.js"
     },
     "dependencies": {
         "chalk": "^5.6.2"
@@ -43,6 +54,6 @@
         "zod": "^3.25.0 || ^4.0.0"
     },
     "devDependencies": {
-        "zod": "^4.3.5"
+        "zod": "^4.4.3"
     }
 }

packages/llms/src/OpenAIClient.test.ts

@@ -0,0 +1,369 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+import * as z from 'zod/v4'
+
+import { OpenAIClient } from './OpenAIClient'
+import { InvokeError, InvokeErrorTypes } from './errors'
+import { parseLLMConfig } from './index'
+import type { LLMConfig, Tool } from './types'
+
+// ---------- Fixtures ----------
+
+function makeClient(overrides: Partial<LLMConfig> = {}) {
+	const fetchMock = vi.fn<typeof fetch>()
+	const config = parseLLMConfig({
+		baseURL: 'http://test.local/v1',
+		model: 'test-model',
+		apiKey: 'sk-test',
+		customFetch: fetchMock,
+		...overrides,
+	})
+	const client = new OpenAIClient(config)
+	return { client, fetchMock }
+}
+
+function makeTool(): Tool<{ name: string }, string> {
+	return {
+		description: 'greet',
+		inputSchema: z.object({ name: z.string() }),
+		execute: vi.fn(async (args) => `hello ${args.name}`),
+	}
+}
+
+function jsonResponse(body: unknown, status = 200): Response {
+	return new Response(JSON.stringify(body), {
+		status,
+		headers: { 'Content-Type': 'application/json' },
+	})
+}
+
+function toolCallBody(toolName: string, args: unknown, finishReason = 'tool_calls') {
+	return {
+		choices: [
+			{
+				finish_reason: finishReason,
+				message: {
+					tool_calls: [
+						{
+							id: 'call_1',
+							type: 'function',
+							function: {
+								name: toolName,
+								arguments: typeof args === 'string' ? args : JSON.stringify(args),
+							},
+						},
+					],
+				},
+			},
+		],
+		usage: { prompt_tokens: 10, completion_tokens: 5, total_tokens: 15 },
+	}
+}
+
+function abortError(message = 'aborted'): Error {
+	const err = new Error(message)
+	err.name = 'AbortError'
+	return err
+}
+
+function getSentBody(fetchMock: ReturnType<typeof vi.fn>): Record<string, unknown> {
+	const init = fetchMock.mock.calls[0][1] as RequestInit
+	return JSON.parse(init.body as string)
+}
+
+const signal = new AbortController().signal
+
+// ---------- Request construction ----------
+
+describe('OpenAIClient.invoke — request construction', () => {
+	let setup: ReturnType<typeof makeClient>
+	const tools = { greet: makeTool() }
+
+	beforeEach(() => {
+		setup = makeClient()
+		setup.fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', { name: 'world' })))
+	})
+
+	it('defaults tool_choice to "required" when no toolChoiceName is given', async () => {
+		await setup.client.invoke([], tools, signal)
+		expect(getSentBody(setup.fetchMock).tool_choice).toBe('required')
+	})
+
+	it('uses named tool_choice when toolChoiceName is given', async () => {
+		await setup.client.invoke([], tools, signal, { toolChoiceName: 'greet' })
+		expect(getSentBody(setup.fetchMock).tool_choice).toEqual({
+			type: 'function',
+			function: { name: 'greet' },
+		})
+	})
+
+	it('falls back to "required" when disableNamedToolChoice is true', async () => {
+		const { client, fetchMock } = makeClient({ disableNamedToolChoice: true })
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', { name: 'world' })))
+		await client.invoke([], tools, signal, { toolChoiceName: 'greet' })
+		expect(getSentBody(fetchMock).tool_choice).toBe('required')
+	})
+
+	it('sends Authorization header when apiKey is set', async () => {
+		await setup.client.invoke([], tools, signal)
+		const init = setup.fetchMock.mock.calls[0][1]!
+		expect((init.headers as Record<string, string>).Authorization).toBe('Bearer sk-test')
+	})
+
+	it('omits Authorization header when apiKey is empty', async () => {
+		const { client, fetchMock } = makeClient({ apiKey: '' })
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', { name: 'world' })))
+		await client.invoke([], tools, signal)
+		const init = fetchMock.mock.calls[0][1]!
+		expect((init.headers as Record<string, string>).Authorization).toBeUndefined()
+	})
+
+	it('applies transformRequestBody (in-place form, returns undefined)', async () => {
+		const { client, fetchMock } = makeClient({
+			transformRequestBody: (body) => {
+				body.custom_flag = 42
+				return undefined
+			},
+		})
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', { name: 'world' })))
+		await client.invoke([], tools, signal)
+		expect(getSentBody(fetchMock).custom_flag).toBe(42)
+	})
+
+	it('applies transformRequestBody (returning a new object)', async () => {
+		const { client, fetchMock } = makeClient({
+			transformRequestBody: () => ({ replaced: true }),
+		})
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', { name: 'world' })))
+		await client.invoke([], tools, signal)
+		expect(getSentBody(fetchMock)).toEqual({ replaced: true })
+	})
+
+	it('wraps transformRequestBody throws as CONFIG_ERROR', async () => {
+		const { client } = makeClient({
+			transformRequestBody: () => {
+				throw new Error('bad transform')
+			},
+		})
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			name: 'InvokeError',
+			type: InvokeErrorTypes.CONFIG_ERROR,
+		})
+	})
+})
+
+// ---------- Success path ----------
+
+describe('OpenAIClient.invoke — success', () => {
+	it('returns toolCall, toolResult and usage', async () => {
+		const { client, fetchMock } = makeClient()
+		const tool = makeTool()
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', { name: 'Alice' })))
+
+		const result = await client.invoke([], { greet: tool }, signal)
+
+		expect(result.toolCall).toEqual({ name: 'greet', args: { name: 'Alice' } })
+		expect(result.toolResult).toBe('hello Alice')
+		expect(result.usage).toEqual({
+			promptTokens: 10,
+			completionTokens: 5,
+			totalTokens: 15,
+			cachedTokens: undefined,
+			reasoningTokens: undefined,
+		})
+		expect(tool.execute).toHaveBeenCalledWith({ name: 'Alice' })
+	})
+
+	it('accepts finish_reason="stop" with tool calls', async () => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', { name: 'Bob' }, 'stop')))
+		const result = await client.invoke([], { greet: makeTool() }, signal)
+		expect(result.toolResult).toBe('hello Bob')
+	})
+})
+
+// ---------- HTTP errors ----------
+
+describe('OpenAIClient.invoke — HTTP errors', () => {
+	const tools = { greet: makeTool() }
+
+	it.each([
+		[401, InvokeErrorTypes.AUTH_ERROR],
+		[403, InvokeErrorTypes.AUTH_ERROR],
+		[429, InvokeErrorTypes.RATE_LIMIT],
+		[500, InvokeErrorTypes.SERVER_ERROR],
+		[502, InvokeErrorTypes.SERVER_ERROR],
+		[418, InvokeErrorTypes.UNKNOWN],
+	])('maps status %i to %s', async (status, type) => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockResolvedValue(jsonResponse({ error: { message: 'nope' } }, status))
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			name: 'InvokeError',
+			type,
+		})
+	})
+
+	it('falls back to statusText when body has no error.message', async () => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockResolvedValue(
+			new Response('not json', { status: 500, statusText: 'Internal Boom' })
+		)
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			type: InvokeErrorTypes.SERVER_ERROR,
+			message: expect.stringContaining('Internal Boom'),
+		})
+	})
+})
+
+// ---------- Response anomalies ----------
+
+describe('OpenAIClient.invoke — response anomalies', () => {
+	const tools = { greet: makeTool() }
+
+	it('throws CONTEXT_LENGTH on finish_reason="length"', async () => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockResolvedValue(
+			jsonResponse({ choices: [{ finish_reason: 'length', message: {} }] })
+		)
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			type: InvokeErrorTypes.CONTEXT_LENGTH,
+		})
+	})
+
+	it('throws CONTENT_FILTER on finish_reason="content_filter"', async () => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockResolvedValue(
+			jsonResponse({ choices: [{ finish_reason: 'content_filter', message: {} }] })
+		)
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			type: InvokeErrorTypes.CONTENT_FILTER,
+		})
+	})
+
+	it('throws INVALID_SCHEMA when there are no choices', async () => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockResolvedValue(jsonResponse({}))
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			type: InvokeErrorTypes.INVALID_SCHEMA,
+		})
+	})
+
+	it('throws NO_TOOL_CALL when message has no tool_calls', async () => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockResolvedValue(
+			jsonResponse({ choices: [{ finish_reason: 'tool_calls', message: {} }] })
+		)
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			type: InvokeErrorTypes.NO_TOOL_CALL,
+		})
+	})
+
+	it('throws INVALID_TOOL_ARGS when arguments are not valid JSON', async () => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', 'not-json{')))
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			type: InvokeErrorTypes.INVALID_TOOL_ARGS,
+			message: expect.stringContaining('JSON'),
+		})
+	})
+
+	it('throws INVALID_TOOL_ARGS when args fail Zod validation', async () => {
+		const { client, fetchMock } = makeClient()
+		// tool expects { name: string }, send { name: 123 }
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', { name: 123 })))
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			type: InvokeErrorTypes.INVALID_TOOL_ARGS,
+		})
+	})
+
+	it('throws UNKNOWN when model calls a tool that does not exist', async () => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('mystery', { name: 'x' })))
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			type: InvokeErrorTypes.UNKNOWN,
+			message: expect.stringContaining('mystery'),
+		})
+	})
+
+	it('wraps tool.execute failures as TOOL_EXECUTION_ERROR', async () => {
+		const { client, fetchMock } = makeClient()
+		const tool: Tool<{ name: string }, string> = {
+			inputSchema: z.object({ name: z.string() }),
+			execute: vi.fn(async () => {
+				throw new Error('downstream blew up')
+			}),
+		}
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', { name: 'x' })))
+		await expect(client.invoke([], { greet: tool }, signal)).rejects.toMatchObject({
+			type: InvokeErrorTypes.TOOL_EXECUTION_ERROR,
+			message: expect.stringContaining('downstream blew up'),
+		})
+	})
+})
+
+// ---------- Abort handling (the important part) ----------
+
+describe('OpenAIClient.invoke — abort', () => {
+	const tools = { greet: makeTool() }
+
+	it('throws AbortError immediately when signal is already aborted', async () => {
+		const { client, fetchMock } = makeClient()
+		const controller = new AbortController()
+		controller.abort()
+
+		await expect(client.invoke([], tools, controller.signal)).rejects.toMatchObject({
+			name: 'AbortError',
+		})
+		expect(fetchMock).not.toHaveBeenCalled()
+	})
+
+	it('propagates AbortError thrown by fetch (does NOT wrap as NETWORK_ERROR)', async () => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockRejectedValue(abortError())
+
+		const err = await client.invoke([], tools, signal).catch((e) => e)
+		expect(err).toBeInstanceOf(Error)
+		expect(err).not.toBeInstanceOf(InvokeError)
+		expect(err.name).toBe('AbortError')
+	})
+
+	it('propagates AbortError thrown by response.json() (does NOT wrap as INVALID_RESPONSE)', async () => {
+		const { client, fetchMock } = makeClient()
+		// Fake Response whose .json() rejects with AbortError mid-read
+		const fakeResponse = {
+			ok: true,
+			status: 200,
+			statusText: 'OK',
+			json: () => Promise.reject(abortError()),
+		} as unknown as Response
+		fetchMock.mockResolvedValue(fakeResponse)
+
+		const err = await client.invoke([], tools, signal).catch((e) => e)
+		expect(err).not.toBeInstanceOf(InvokeError)
+		expect(err.name).toBe('AbortError')
+	})
+
+	it('propagates AbortError thrown by tool.execute (does NOT wrap as TOOL_EXECUTION_ERROR)', async () => {
+		const { client, fetchMock } = makeClient()
+		const tool: Tool<{ name: string }, string> = {
+			inputSchema: z.object({ name: z.string() }),
+			execute: vi.fn(async () => {
+				throw abortError()
+			}),
+		}
+		fetchMock.mockResolvedValue(jsonResponse(toolCallBody('greet', { name: 'x' })))
+
+		const err = await client.invoke([], { greet: tool }, signal).catch((e) => e)
+		expect(err).not.toBeInstanceOf(InvokeError)
+		expect(err.name).toBe('AbortError')
+	})
+
+	// Sanity check: the wrappers we deliberately bypass for AbortError still work for normal errors
+	it('still wraps non-Abort fetch errors as NETWORK_ERROR', async () => {
+		const { client, fetchMock } = makeClient()
+		fetchMock.mockRejectedValue(new TypeError('ECONNREFUSED'))
+		await expect(client.invoke([], tools, signal)).rejects.toMatchObject({
+			name: 'InvokeError',
+			type: InvokeErrorTypes.NETWORK_ERROR,
+		})
+	})
+})

packages/llms/src/OpenAIClient.ts

@@ -3,18 +3,25 @@
  */
 import * as z from 'zod/v4'
 
-import { InvokeError, InvokeErrorType } from './errors'
-import type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types'
+import { InvokeError, InvokeErrorTypes } from './errors'
+import type {
+	InvokeOptions,
+	InvokeResult,
+	LLMClient,
+	Message,
+	ResolvedLLMConfig,
+	Tool,
+} from './types'
 import { modelPatch, zodToOpenAITool } from './utils'
 
 /**
  * Client for OpenAI compatible APIs
  */
 export class OpenAIClient implements LLMClient {
-	config: Required<LLMConfig>
+	config: ResolvedLLMConfig
 	private fetch: typeof globalThis.fetch
 
-	constructor(config: Required<LLMConfig>) {
+	constructor(config: ResolvedLLMConfig) {
 		this.config = config
 		this.fetch = config.customFetch
 	}
@@ -25,23 +32,43 @@ export class OpenAIClient implements LLMClient {
 		abortSignal?: AbortSignal,
 		options?: InvokeOptions
 	): Promise<InvokeResult> {
+		abortSignal?.throwIfAborted()
+
 		// 1. Convert tools to OpenAI format
 		const openaiTools = Object.entries(tools).map(([name, t]) => zodToOpenAITool(name, t))
 
 		// Build request body
+
+		let toolChoice: unknown = 'required'
+		if (options?.toolChoiceName && !this.config.disableNamedToolChoice) {
+			toolChoice = { type: 'function', function: { name: options.toolChoiceName } }
+		}
+
 		const requestBody: Record<string, unknown> = {
 			model: this.config.model,
-			temperature: this.config.temperature,
 			messages,
 			tools: openaiTools,
 			parallel_tool_calls: false,
-			// Require tool call: specific tool if provided, otherwise any tool
-			tool_choice: options?.toolChoiceName
-				? { type: 'function', function: { name: options.toolChoiceName } }
-				: 'required',
+			tool_choice: toolChoice,
+		}
+		// Only sent if the caller explicitly set it. Most new models throw if this is set.
+		if (this.config.temperature !== undefined) {
+			requestBody.temperature = this.config.temperature
 		}
 
-		modelPatch(requestBody)
+		modelPatch(requestBody, this.config.baseURL)
+
+		let transformedBody: Record<string, unknown> | undefined
+		try {
+			transformedBody = this.config.transformRequestBody(requestBody)
+		} catch (error) {
+			throw new InvokeError(
+				InvokeErrorTypes.CONFIG_ERROR,
+				`transformRequestBody failed: ${(error as Error).message}`,
+				error
+			)
+		}
+		const finalRequestBody = transformedBody ?? requestBody
 
 		// 2. Call API
 		let response: Response
@@ -50,58 +77,71 @@ export class OpenAIClient implements LLMClient {
 				method: 'POST',
 				headers: {
 					'Content-Type': 'application/json',
-					Authorization: `Bearer ${this.config.apiKey}`,
+					...(this.config.apiKey && { Authorization: `Bearer ${this.config.apiKey}` }),
 				},
-				body: JSON.stringify(requestBody),
+				body: JSON.stringify(finalRequestBody),
 				signal: abortSignal,
 			})
 		} catch (error: unknown) {
-			const isAbortError = (error as any)?.name === 'AbortError'
-			const errorMessage = isAbortError ? 'Network request aborted' : 'Network request failed'
-			if (!isAbortError) console.error(error)
-			throw new InvokeError(InvokeErrorType.NETWORK_ERROR, errorMessage, error)
+			if ((error as any)?.name === 'AbortError') throw error
+			console.error(error)
+			throw new InvokeError(InvokeErrorTypes.NETWORK_ERROR, 'Network request failed', error)
 		}
 
 		// 3. Handle HTTP errors
 		if (!response.ok) {
-			const errorData = await response.json().catch()
-			const errorMessage =
-				(errorData as { error?: { message?: string } }).error?.message || response.statusText
+			let errorData: any
+			try {
+				errorData = await response.json()
+			} catch (error) {
+				if ((error as any)?.name === 'AbortError') throw error
+			}
+			const errorMessage = errorData?.error?.message || response.statusText
 
 			if (response.status === 401 || response.status === 403) {
 				throw new InvokeError(
-					InvokeErrorType.AUTH_ERROR,
+					InvokeErrorTypes.AUTH_ERROR,
 					`Authentication failed: ${errorMessage}`,
 					errorData
 				)
 			}
 			if (response.status === 429) {
 				throw new InvokeError(
-					InvokeErrorType.RATE_LIMIT,
+					InvokeErrorTypes.RATE_LIMIT,
 					`Rate limit exceeded: ${errorMessage}`,
 					errorData
 				)
 			}
 			if (response.status >= 500) {
 				throw new InvokeError(
-					InvokeErrorType.SERVER_ERROR,
+					InvokeErrorTypes.SERVER_ERROR,
 					`Server error: ${errorMessage}`,
 					errorData
 				)
 			}
 			throw new InvokeError(
-				InvokeErrorType.UNKNOWN,
+				InvokeErrorTypes.UNKNOWN,
 				`HTTP ${response.status}: ${errorMessage}`,
 				errorData
 			)
 		}
 
 		// 4. Parse and validate response
-		const data = await response.json()
+		let data: any
+		try {
+			data = await response.json()
+		} catch (error) {
+			if ((error as any)?.name === 'AbortError') throw error
+			throw new InvokeError(
+				InvokeErrorTypes.INVALID_RESPONSE,
+				'Response body is not valid JSON',
+				error
+			)
+		}
 
 		const choice = data.choices?.[0]
 		if (!choice) {
-			throw new InvokeError(InvokeErrorType.UNKNOWN, 'No choices in response', data)
+			throw new InvokeError(InvokeErrorTypes.INVALID_SCHEMA, 'No choices in response', data)
 		}
 
 		// Check finish_reason
@@ -112,21 +152,21 @@ export class OpenAIClient implements LLMClient {
 				break
 			case 'length':
 				throw new InvokeError(
-					InvokeErrorType.CONTEXT_LENGTH,
+					InvokeErrorTypes.CONTEXT_LENGTH,
 					'Response truncated: max tokens reached',
 					undefined,
 					data
 				)
 			case 'content_filter':
 				throw new InvokeError(
-					InvokeErrorType.CONTENT_FILTER,
+					InvokeErrorTypes.CONTENT_FILTER,
 					'Content filtered by safety system',
 					undefined,
 					data
 				)
 			default:
 				throw new InvokeError(
-					InvokeErrorType.UNKNOWN,
+					InvokeErrorTypes.INVALID_SCHEMA,
 					`Unexpected finish_reason: ${choice.finish_reason}`,
 					undefined,
 					data
@@ -141,7 +181,7 @@ export class OpenAIClient implements LLMClient {
 		const toolCallName = normalizedChoice?.message?.tool_calls?.[0]?.function?.name
 		if (!toolCallName) {
 			throw new InvokeError(
-				InvokeErrorType.NO_TOOL_CALL,
+				InvokeErrorTypes.NO_TOOL_CALL,
 				'No tool call found in response',
 				undefined,
 				data
@@ -151,7 +191,7 @@ export class OpenAIClient implements LLMClient {
 		const tool = tools[toolCallName]
 		if (!tool) {
 			throw new InvokeError(
-				InvokeErrorType.UNKNOWN,
+				InvokeErrorTypes.UNKNOWN,
 				`Tool "${toolCallName}" not found in tools`,
 				undefined,
 				data
@@ -162,7 +202,7 @@ export class OpenAIClient implements LLMClient {
 		const argString = normalizedChoice.message?.tool_calls?.[0]?.function?.arguments
 		if (!argString) {
 			throw new InvokeError(
-				InvokeErrorType.INVALID_TOOL_ARGS,
+				InvokeErrorTypes.INVALID_TOOL_ARGS,
 				'No tool call arguments found',
 				undefined,
 				data
@@ -174,7 +214,7 @@ export class OpenAIClient implements LLMClient {
 			parsedArgs = JSON.parse(argString)
 		} catch (error) {
 			throw new InvokeError(
-				InvokeErrorType.INVALID_TOOL_ARGS,
+				InvokeErrorTypes.INVALID_TOOL_ARGS,
 				'Failed to parse tool arguments as JSON',
 				error,
 				data
@@ -186,7 +226,7 @@ export class OpenAIClient implements LLMClient {
 		if (!validation.success) {
 			console.error(z.prettifyError(validation.error))
 			throw new InvokeError(
-				InvokeErrorType.INVALID_TOOL_ARGS,
+				InvokeErrorTypes.INVALID_TOOL_ARGS,
 				'Tool arguments validation failed',
 				validation.error,
 				data
@@ -198,11 +238,12 @@ export class OpenAIClient implements LLMClient {
 		let toolResult: unknown
 		try {
 			toolResult = await tool.execute(toolInput)
-		} catch (e) {
+		} catch (error: unknown) {
+			if ((error as any)?.name === 'AbortError') throw error
 			throw new InvokeError(
-				InvokeErrorType.TOOL_EXECUTION_ERROR,
-				`Tool execution failed: ${(e as Error).message}`,
-				e,
+				InvokeErrorTypes.TOOL_EXECUTION_ERROR,
+				`Tool execution failed: ${(error as Error)?.message}`,
+				error,
 				data
 			)
 		}
@@ -222,7 +263,7 @@ export class OpenAIClient implements LLMClient {
 				reasoningTokens: data.usage?.completion_tokens_details?.reasoning_tokens,
 			},
 			rawResponse: data,
-			rawRequest: requestBody,
+			rawRequest: finalRequestBody,
 		}
 	}
 }

packages/llms/src/constants.ts

@@ -1,3 +0,0 @@
-// Internal constants
-export const LLM_MAX_RETRIES = 2
-export const DEFAULT_TEMPERATURE = 0.7 // higher randomness helps auto-recovery

packages/llms/src/errors.ts

@@ -1,8 +1,8 @@
 /**
- * Error types and error handling for LLM invocations
+ * Error types and error handling for LLM invocations.
  */
 
-export const InvokeErrorType = {
+export const InvokeErrorTypes = {
 	// Retryable
 	NETWORK_ERROR: 'network_error', // Network error, retry
 	RATE_LIMIT: 'rate_limit', // Rate limit, retry
@@ -10,16 +10,31 @@ export const InvokeErrorType = {
 	NO_TOOL_CALL: 'no_tool_call', // Model did not call tool
 	INVALID_TOOL_ARGS: 'invalid_tool_args', // Tool args don't match schema
 	TOOL_EXECUTION_ERROR: 'tool_execution_error', // Tool execution error
+	INVALID_RESPONSE: 'invalid_response', // Response body is not valid JSON
+	INVALID_SCHEMA: 'invalid_schema', // Response is valid JSON but doesn't match expected shape
 
 	UNKNOWN: 'unknown',
 
 	// Non-retryable
+	CONFIG_ERROR: 'config_error', // Invalid local configuration or hook
 	AUTH_ERROR: 'auth_error', // Authentication failed
 	CONTEXT_LENGTH: 'context_length', // Prompt too long
 	CONTENT_FILTER: 'content_filter', // Content filtered
 } as const
 
-export type InvokeErrorType = (typeof InvokeErrorType)[keyof typeof InvokeErrorType]
+type InvokeErrorType = (typeof InvokeErrorTypes)[keyof typeof InvokeErrorTypes]
+
+const RETRYABLE_TYPES: readonly InvokeErrorType[] = [
+	InvokeErrorTypes.NETWORK_ERROR,
+	InvokeErrorTypes.RATE_LIMIT,
+	InvokeErrorTypes.SERVER_ERROR,
+	InvokeErrorTypes.NO_TOOL_CALL,
+	InvokeErrorTypes.INVALID_TOOL_ARGS,
+	InvokeErrorTypes.TOOL_EXECUTION_ERROR,
+	InvokeErrorTypes.INVALID_RESPONSE,
+	InvokeErrorTypes.INVALID_SCHEMA,
+	InvokeErrorTypes.UNKNOWN,
+]
 
 export class InvokeError extends Error {
 	type: InvokeErrorType
@@ -34,24 +49,8 @@ export class InvokeError extends Error {
 		super(message)
 		this.name = 'InvokeError'
 		this.type = type
-		this.retryable = this.isRetryable(type, rawError)
+		this.retryable = RETRYABLE_TYPES.includes(type)
 		this.rawError = rawError
 		this.rawResponse = rawResponse
 	}
-
-	private isRetryable(type: InvokeErrorType, rawError?: unknown): boolean {
-		const isAbortError = (rawError as any)?.name === 'AbortError'
-		if (isAbortError) return false
-
-		const retryableTypes: InvokeErrorType[] = [
-			InvokeErrorType.NETWORK_ERROR,
-			InvokeErrorType.RATE_LIMIT,
-			InvokeErrorType.SERVER_ERROR,
-			InvokeErrorType.NO_TOOL_CALL,
-			InvokeErrorType.INVALID_TOOL_ARGS,
-			InvokeErrorType.TOOL_EXECUTION_ERROR,
-			InvokeErrorType.UNKNOWN,
-		]
-		return retryableTypes.includes(type)
-	}
 }

packages/llms/src/index.test.ts

@@ -0,0 +1,114 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { InvokeError, InvokeErrorTypes, LLM } from './index'
+import type { LLMClient } from './types'
+
+function makeLLM(maxRetries = 2): LLM {
+	return new LLM({
+		baseURL: 'http://test.local/v1',
+		model: 'gpt-5',
+		maxRetries,
+	})
+}
+
+function abortError(): Error {
+	const err = new Error('aborted')
+	err.name = 'AbortError'
+	return err
+}
+
+describe('LLM.invoke retry behavior', () => {
+	let llm: LLM
+	let client: { invoke: ReturnType<typeof vi.fn> }
+	const signal = new AbortController().signal
+
+	beforeEach(() => {
+		llm = makeLLM(2)
+		client = { invoke: vi.fn() }
+		llm.client = client as unknown as LLMClient
+	})
+
+	it('returns immediately on first success', async () => {
+		client.invoke.mockResolvedValueOnce('ok')
+		const retryListener = vi.fn()
+		llm.addEventListener('retry', retryListener)
+
+		await expect(llm.invoke([], {}, signal)).resolves.toBe('ok')
+		expect(client.invoke).toHaveBeenCalledOnce()
+		expect(retryListener).not.toHaveBeenCalled()
+	})
+
+	it('retries up to maxRetries on retryable errors, then throws last error', async () => {
+		const retryable = new InvokeError(InvokeErrorTypes.NETWORK_ERROR, 'boom')
+		client.invoke
+			.mockRejectedValueOnce(retryable)
+			.mockRejectedValueOnce(retryable)
+			.mockRejectedValueOnce(retryable)
+
+		await expect(llm.invoke([], {}, signal)).rejects.toBe(retryable)
+		// 1 initial + 2 retries = 3 attempts total
+		expect(client.invoke).toHaveBeenCalledTimes(3)
+	})
+
+	it('succeeds on retry after transient failure', async () => {
+		const retryable = new InvokeError(InvokeErrorTypes.RATE_LIMIT, 'slow down')
+		client.invoke.mockRejectedValueOnce(retryable).mockResolvedValueOnce('ok')
+
+		await expect(llm.invoke([], {}, signal)).resolves.toBe('ok')
+		expect(client.invoke).toHaveBeenCalledTimes(2)
+	})
+
+	it('emits "retry" events with attempt count and lastError', async () => {
+		const err1 = new InvokeError(InvokeErrorTypes.NETWORK_ERROR, 'first')
+		const err2 = new InvokeError(InvokeErrorTypes.NETWORK_ERROR, 'second')
+		client.invoke
+			.mockRejectedValueOnce(err1)
+			.mockRejectedValueOnce(err2)
+			.mockResolvedValueOnce('ok')
+
+		const events: { attempt: number; maxAttempts: number; lastError: Error }[] = []
+		llm.addEventListener('retry', (e) => {
+			events.push((e as CustomEvent).detail)
+		})
+
+		await llm.invoke([], {}, signal)
+
+		expect(events).toEqual([
+			{ attempt: 1, maxAttempts: 2, lastError: err1 },
+			{ attempt: 2, maxAttempts: 2, lastError: err2 },
+		])
+	})
+
+	it('does not retry on AbortError, throws immediately', async () => {
+		const err = abortError()
+		client.invoke.mockRejectedValueOnce(err)
+
+		await expect(llm.invoke([], {}, signal)).rejects.toBe(err)
+		expect(client.invoke).toHaveBeenCalledOnce()
+	})
+
+	it('does not retry on non-retryable InvokeError (AUTH_ERROR)', async () => {
+		const err = new InvokeError(InvokeErrorTypes.AUTH_ERROR, 'bad token')
+		client.invoke.mockRejectedValueOnce(err)
+
+		await expect(llm.invoke([], {}, signal)).rejects.toBe(err)
+		expect(client.invoke).toHaveBeenCalledOnce()
+	})
+
+	it('does not retry on non-retryable InvokeError (CONFIG_ERROR)', async () => {
+		const err = new InvokeError(InvokeErrorTypes.CONFIG_ERROR, 'bad config')
+		client.invoke.mockRejectedValueOnce(err)
+
+		await expect(llm.invoke([], {}, signal)).rejects.toBe(err)
+		expect(client.invoke).toHaveBeenCalledOnce()
+	})
+
+	it('retries plain (non-InvokeError) errors as unknown failures', async () => {
+		// Plain errors are treated as retryable by withRetry (only InvokeError carries retryable flag)
+		const plain = new TypeError('weird')
+		client.invoke.mockRejectedValueOnce(plain).mockResolvedValueOnce('ok')
+
+		await expect(llm.invoke([], {}, signal)).resolves.toBe('ok')
+		expect(client.invoke).toHaveBeenCalledTimes(2)
+	})
+})

packages/llms/src/index.ts

@@ -1,32 +1,23 @@
 import { OpenAIClient } from './OpenAIClient'
-import { DEFAULT_TEMPERATURE, LLM_MAX_RETRIES } from './constants'
-import { InvokeError, InvokeErrorType } from './errors'
-import type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool } from './types'
+import { InvokeError, InvokeErrorTypes } from './errors'
+import type {
+	InvokeOptions,
+	InvokeResult,
+	LLMClient,
+	LLMConfig,
+	Message,
+	ResolvedLLMConfig,
+	Tool,
+} from './types'
 
-export { InvokeError, InvokeErrorType }
+export { InvokeError, InvokeErrorTypes }
 export type { InvokeOptions, InvokeResult, LLMClient, LLMConfig, Message, Tool }
 
-export function parseLLMConfig(config: LLMConfig): Required<LLMConfig> {
-	// Runtime validation as defensive programming (types already guarantee these)
-	if (!config.baseURL || !config.apiKey || !config.model) {
-		throw new Error(
-			'[PageAgent] LLM configuration required. Please provide: baseURL, apiKey, model. ' +
-				'See: https://alibaba.github.io/page-agent/docs/features/models'
-		)
-	}
-
-	return {
-		baseURL: config.baseURL,
-		apiKey: config.apiKey,
-		model: config.model,
-		temperature: config.temperature ?? DEFAULT_TEMPERATURE,
-		maxRetries: config.maxRetries ?? LLM_MAX_RETRIES,
-		customFetch: (config.customFetch ?? fetch).bind(globalThis), // fetch will be illegal unless bound
-	}
-}
-
+/**
+ * LLM module
+ */
 export class LLM extends EventTarget {
-	config: Required<LLMConfig>
+	config: ResolvedLLMConfig
 	client: LLMClient
 
 	constructor(config: LLMConfig) {
@@ -48,65 +39,71 @@ export class LLM extends EventTarget {
 		abortSignal: AbortSignal,
 		options?: InvokeOptions
 	): Promise<InvokeResult> {
-		return await withRetry(
-			async () => {
-				// in case user aborted before invoking
-				if (abortSignal.aborted) throw new Error('AbortError')
-
-				const result = await this.client.invoke(messages, tools, abortSignal, options)
-
-				return result
+		return await withRetry(async () => this.client.invoke(messages, tools, abortSignal, options), {
+			maxRetries: this.config.maxRetries,
+			onRetry: (attempt, lastError) => {
+				this.dispatchEvent(
+					new CustomEvent('retry', {
+						detail: { attempt, maxAttempts: this.config.maxRetries, lastError },
+					})
+				)
 			},
-			// retry settings
-			{
-				maxRetries: this.config.maxRetries,
-				onRetry: (attempt: number) => {
-					this.dispatchEvent(
-						new CustomEvent('retry', { detail: { attempt, maxAttempts: this.config.maxRetries } })
-					)
-				},
-				onError: (error: Error) => {
-					this.dispatchEvent(new CustomEvent('error', { detail: { error } }))
-				},
-			}
-		)
+		})
 	}
 }
 
+/**
+ * Retry a function until it succeeds or reaches the maximum number of retries.
+ */
 async function withRetry<T>(
 	fn: () => Promise<T>,
 	settings: {
 		maxRetries: number
-		onRetry: (attempt: number) => void
-		onError: (error: Error) => void
+		onRetry: (attempt: number, lastError: Error) => void
 	}
 ): Promise<T> {
 	let attempt = 0
-	let lastError: Error | null = null
-	while (attempt <= settings.maxRetries) {
-		if (attempt > 0) {
-			settings.onRetry(attempt)
-			await new Promise((resolve) => setTimeout(resolve, 100))
-		}
-
+	while (true) {
 		try {
 			return await fn()
 		} catch (error: unknown) {
-			// do not retry if aborted by user
-			if ((error as any)?.rawError?.name === 'AbortError') throw error
-
-			console.error(error)
-			settings.onError(error as Error)
-
-			// do not retry if error is not retryable (InvokeError)
+			if ((error as any)?.name === 'AbortError') throw error
 			if (error instanceof InvokeError && !error.retryable) throw error
-
-			lastError = error as Error
 			attempt++
+			if (attempt > settings.maxRetries) throw error
+
+			console.debug('[LLM] retryable failure, will retry:', error)
+			settings.onRetry(attempt, error as Error)
 
 			await new Promise((resolve) => setTimeout(resolve, 100))
 		}
 	}
-
-	throw lastError!
+}
+
+export function parseLLMConfig(config: LLMConfig): ResolvedLLMConfig {
+	// Runtime validation as defensive programming (types already guarantee these)
+	if (!config.baseURL || !config.model) {
+		throw new Error(
+			'[PageAgent] LLM configuration required. Please provide: baseURL, model. ' +
+				'See: https://alibaba.github.io/page-agent/docs/features/models'
+		)
+	}
+
+	if (config.temperature !== undefined) {
+		console.warn(
+			'[PageAgent] LLMConfig.temperature is deprecated and will be removed in a future version. ' +
+				'Use transformRequestBody to set it only for models you have verified accept it.'
+		)
+	}
+
+	return {
+		baseURL: config.baseURL,
+		model: config.model,
+		apiKey: config.apiKey || '',
+		temperature: config.temperature,
+		maxRetries: config.maxRetries ?? 2,
+		transformRequestBody: config.transformRequestBody ?? ((requestBody) => requestBody),
+		disableNamedToolChoice: config.disableNamedToolChoice ?? false,
+		customFetch: (config.customFetch ?? fetch).bind(globalThis), // fetch will be illegal unless bound
+	}
 }

packages/llms/src/live-models.test.ts

@@ -0,0 +1,224 @@
+/**
+ * Live compatibility test — hits real provider APIs.
+ *
+ * Purpose: verify request formatting and `modelPatch` (see `utils.ts`) work
+ * for every model below, across the providers that serve them. Not a
+ * correctness/quality eval — the tool call is trivial and forced via
+ * `toolChoiceName`, so a failure here means the request/response shape is
+ * wrong for that model, not that the model is "dumb".
+ *
+ * Tests `OpenAIClient` directly (not the `LLM` retry wrapper), so a failure
+ * always reflects the very first request/response — no retry can mask it.
+ *
+ * Each provider's tests skip (not fail) when its `TESTING_*_KEY` env var is
+ * absent, so this stays CI-safe. To actually run these, put keys in the
+ * repo-root `.env`:
+ *
+ *   TESTING_OPENROUTER_KEY=...
+ *   TESTING_DEEPSEEK_KEY=...
+ *   TESTING_ALIYUN_KEY=...
+ */
+import { config as dotenvConfig } from 'dotenv'
+import { dirname, resolve } from 'path'
+import { fileURLToPath } from 'url'
+import { describe, expect, it } from 'vitest'
+import * as z from 'zod/v4'
+
+import { OpenAIClient } from './OpenAIClient'
+import { parseLLMConfig } from './index'
+import type { Message, Tool } from './types'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+dotenvConfig({ path: resolve(__dirname, '../../../.env'), quiet: true })
+
+const TEST_TIMEOUT = 30_000
+
+/**
+ * Mirrors `packages/website/src/pages/docs/features/models/page.tsx`.
+ * This package cannot depend on the website, so the list is duplicated here.
+ * Keep both lists in sync manually when models are added or renamed.
+ */
+const MODEL_GROUPS: Record<string, string[]> = {
+	Qwen: [
+		'qwen3.7-max',
+		'qwen3.7-plus',
+		'qwen3.6-max',
+		'qwen3.6-plus',
+		'qwen3.6-flash',
+		'qwen3.5-plus',
+		'qwen3.5-flash',
+		'qwen3-max',
+	],
+	OpenAI: [
+		'gpt-5.5',
+		'gpt-5.4',
+		'gpt-5.4-mini',
+		'gpt-5.4-nano',
+		'gpt-5.2',
+		'gpt-5.1',
+		'gpt-5',
+		'gpt-5-mini',
+		'gpt-4.1',
+		'gpt-4.1-mini',
+	],
+	DeepSeek: ['deepseek-v4-pro', 'deepseek-v4-flash', 'deepseek-3.2'],
+	Google: [
+		'gemini-3.5-flash',
+		'gemini-3.1-pro',
+		'gemini-3.1-flash-lite',
+		'gemini-2.5-pro',
+		'gemini-2.5-flash',
+	],
+	Anthropic: [
+		'claude-sonnet-5',
+		'claude-opus-4-8',
+		'claude-opus-4-7',
+		'claude-opus-4-6',
+		'claude-opus-4-5',
+		'claude-sonnet-4-5',
+		'claude-haiku-4-5',
+	],
+	MiniMax: ['MiniMax-M3', 'MiniMax-M2.7', 'MiniMax-M2.5'],
+	xAI: ['grok-4.3', 'grok-build-0.1'],
+	MoonshotAI: ['kimi-k2.7-code', 'kimi-k2.6', 'kimi-k2.5'],
+	'Z.AI': ['glm-5.2', 'glm-5.1', 'glm-5', 'glm-4.7'],
+}
+
+/**
+ * OpenRouter lists every model as `<vendor-slug>/<model-id>`, lowercase.
+ * See the commented-out entries in the repo-root `.env` for real examples,
+ * e.g. `x-ai/grok-4.1-fast`, `qwen/qwen3-coder-next`, `deepseek/deepseek-v3.2-exp`.
+ */
+const OPENROUTER_VENDOR_SLUG: Record<string, string> = {
+	Qwen: 'qwen',
+	OpenAI: 'openai',
+	DeepSeek: 'deepseek',
+	Google: 'google',
+	Anthropic: 'anthropic',
+	MiniMax: 'minimax',
+	xAI: 'x-ai',
+	MoonshotAI: 'moonshotai',
+	'Z.AI': 'z-ai',
+}
+
+/**
+ * Overrides for models whose OpenRouter id doesn't match the
+ * `<vendor-slug>/<lowercased-name>` heuristic — dated snapshots, "-preview"
+ * suffixes, "v"-prefixed versions, or dots instead of hyphens in the
+ * version number. Verified against `GET https://openrouter.ai/api/v1/models`
+ * on 2026-07-03; re-check when models are added to `MODEL_GROUPS`.
+ */
+const OPENROUTER_ID_OVERRIDES: Record<string, string> = {
+	'qwen3.6-max': 'qwen/qwen3.6-max-preview',
+	'qwen3.5-plus': 'qwen/qwen3.5-plus-20260420',
+	'qwen3.5-flash': 'qwen/qwen3.5-flash-02-23',
+	'deepseek-3.2': 'deepseek/deepseek-v3.2',
+	'gemini-3.1-pro': 'google/gemini-3.1-pro-preview',
+	'claude-opus-4-8': 'anthropic/claude-opus-4.8',
+	'claude-opus-4-7': 'anthropic/claude-opus-4.7',
+	'claude-opus-4-6': 'anthropic/claude-opus-4.6',
+	'claude-opus-4-5': 'anthropic/claude-opus-4.5',
+	'claude-sonnet-4-5': 'anthropic/claude-sonnet-4.5',
+	'claude-haiku-4-5': 'anthropic/claude-haiku-4.5',
+}
+
+/**
+ * Derive a model's OpenRouter id from its brand (a `MODEL_GROUPS` key) and
+ * native model name.
+ */
+function toOpenRouterModelId(brand: string, model: string): string {
+	if (model in OPENROUTER_ID_OVERRIDES) return OPENROUTER_ID_OVERRIDES[model]
+	const slug = OPENROUTER_VENDOR_SLUG[brand]
+	if (!slug) throw new Error(`No OpenRouter vendor slug mapped for brand "${brand}"`)
+	return `${slug}/${model.toLowerCase()}`
+}
+
+const PROVIDERS = {
+	openrouter: {
+		baseURL: 'https://openrouter.ai/api/v1',
+		apiKey: process.env.TESTING_OPENROUTER_KEY,
+	},
+	aliyun: {
+		baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+		apiKey: process.env.TESTING_ALIYUN_KEY,
+	},
+	deepseek: {
+		baseURL: 'https://api.deepseek.com',
+		apiKey: process.env.TESTING_DEEPSEEK_KEY,
+	},
+} as const
+
+const ECHO_TOOL: Tool<{ message: string }, string> = {
+	description: 'Echo back the given message in uppercase.',
+	inputSchema: z.object({ message: z.string() }),
+	execute: async ({ message }) => message.toUpperCase(),
+}
+
+const PROMPT: Message[] = [
+	{
+		role: 'user',
+		content: 'Call the "echo" tool with message set to "ping". You must call the tool.',
+	},
+]
+
+async function expectEchoToolCall(baseURL: string, apiKey: string, model: string) {
+	const client = new OpenAIClient(parseLLMConfig({ baseURL, apiKey, model }))
+	const result = await client.invoke(PROMPT, { echo: ECHO_TOOL }, new AbortController().signal, {
+		toolChoiceName: 'echo',
+	})
+	expect(result.toolResult).toBe('PING')
+}
+
+describe.concurrent('OpenRouter — all listed models', () => {
+	const { baseURL, apiKey } = PROVIDERS.openrouter
+
+	for (const [brand, models] of Object.entries(MODEL_GROUPS)) {
+		for (const model of models) {
+			const id = toOpenRouterModelId(brand, model)
+			it.skipIf(!apiKey)(
+				id,
+				async () => {
+					await expectEchoToolCall(baseURL, apiKey!, id)
+				},
+				TEST_TIMEOUT
+			)
+		}
+	}
+})
+
+// Aliyun native ids that don't match the display name in MODEL_GROUPS.
+const ALIYUN_ID_OVERRIDES: Record<string, string> = {
+	'qwen3.6-max': 'qwen3.6-max-preview',
+}
+
+describe.concurrent('Aliyun DashScope — Qwen native', () => {
+	const { baseURL, apiKey } = PROVIDERS.aliyun
+
+	for (const model of MODEL_GROUPS.Qwen) {
+		const id = ALIYUN_ID_OVERRIDES[model] ?? model
+		it.skipIf(!apiKey)(
+			id,
+			async () => {
+				await expectEchoToolCall(baseURL, apiKey!, id)
+			},
+			TEST_TIMEOUT
+		)
+	}
+})
+
+describe.concurrent('DeepSeek — native', () => {
+	const { baseURL, apiKey } = PROVIDERS.deepseek
+	// deepseek-3.2 isn't served on DeepSeek's own API (only via OpenRouter
+	// resellers) — its official API only accepts deepseek-v4-pro/-flash.
+	const nativeModels = MODEL_GROUPS.DeepSeek.filter((model) => model !== 'deepseek-3.2')
+
+	for (const model of nativeModels) {
+		it.skipIf(!apiKey)(
+			model,
+			async () => {
+				await expectEchoToolCall(baseURL, apiKey!, model)
+			},
+			TEST_TIMEOUT
+		)
+	}
+})

packages/llms/src/types.ts

@@ -89,12 +89,33 @@ export interface InvokeResult<TResult = unknown> {
  */
 export interface LLMConfig {
 	baseURL: string
-	apiKey: string
 	model: string
+	apiKey?: string
 
+	/**
+	 * @deprecated No longer a standard parameter; many models reject it outright.
+	 * Use `transformRequestBody` to set it only for models you've verified.
+	 */
 	temperature?: number
+
 	maxRetries?: number
 
+	/**
+	 * Transform the final request body before sending it to the provider.
+	 * Use this to implement provider-specific request tweaks such as caching hints or custom flags.
+	 *
+	 * Return a new object, or mutate the input object and return undefined.
+	 */
+	transformRequestBody?: (
+		requestBody: Record<string, unknown>
+	) => Record<string, unknown> | undefined
+
+	/**
+	 * remove the tool_choice field from the request.
+	 * @note fix "Invalid tool_choice type: 'object'" for some LLMs.
+	 */
+	disableNamedToolChoice?: boolean
+
 	/**
 	 * Custom fetch function for LLM API requests.
 	 * Use this to customize headers, credentials, proxy, etc.
@@ -102,3 +123,5 @@ export interface LLMConfig {
 	 */
 	customFetch?: typeof globalThis.fetch
 }
+
+export type ResolvedLLMConfig = Required<Omit<LLMConfig, 'temperature'>> & { temperature?: number }

packages/llms/src/utils.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from 'vitest'
+
+import { modelPatch, normalizeModelName } from './utils'
+
+describe('normalizeModelName', () => {
+	it.each([
+		['gpt-5.2', 'gpt-52'],
+		['gpt_5_2', 'gpt52'],
+		['GPT-52-2026-01-01', 'gpt-52-2026-01-01'],
+		['openai/gpt-5.2-chat', 'gpt-52-chat'],
+		['claude_sonnet4_5', 'claudesonnet45'],
+	])('%s -> %s', (input, expected) => {
+		expect(normalizeModelName(input)).toBe(expected)
+	})
+})

packages/llms/src/utils.ts

@@ -24,68 +24,152 @@ export function zodToOpenAITool(name: string, tool: Tool) {
 }
 
 /**
- * Patch model specific parameters
- * @note in-place modification
+ * Patch model specific parameters. Only patches known models.
+ *
+ * @purpose
+ * - Reconcile the differences in the parameter schema each model accepts.
+ * - Disable thinking/reasoning, or lower it to the minimum where a full disable is impossible.
+ * - Minimize returned tokens.
+ * - Raise temperature for known smaller models to improve auto-recovery odds.
+ * @note Honor temperature if explicitly set by the user
+ *
+ * @todo Need vendor-specific patches.
+ * Local and 3rd-party hosted models may have different schema.
  */
-export function modelPatch(body: Record<string, any>) {
+export function modelPatch(body: Record<string, any>, baseURL?: string) {
 	const model: string = body.model || ''
 	if (!model) return body
 
+	const provider = getProvider(baseURL)
+
 	const modelName = normalizeModelName(model)
 
 	if (modelName.startsWith('qwen')) {
-		debug('Applying Qwen patch: use higher temperature for auto fixing')
-		body.temperature = Math.max(body.temperature || 0, 1.0)
+		debug('Patch Qwen: disable thinking')
 		body.enable_thinking = false
-	}
-
-	if (modelName.startsWith('claude')) {
-		debug('Applying Claude patch: disable thinking')
-		body.thinking = { type: 'disabled' }
-
-		// Convert tool_choice to Claude format
-		if (body.tool_choice === 'required') {
-			// 'required' -> { type: 'any' } (must call some tool)
-			debug('Applying Claude patch: convert tool_choice "required" to { type: "any" }')
-			body.tool_choice = { type: 'any' }
-		} else if (body.tool_choice?.function?.name) {
-			// { type: 'function', function: { name: '...' } } -> { type: 'tool', name: '...' }
-			debug('Applying Claude patch: convert tool_choice format')
-			body.tool_choice = { type: 'tool', name: body.tool_choice.function.name }
+		if (body.temperature === undefined && !/max|plus/.test(modelName)) {
+			debug('Patch Qwen: raise temperature to 1.0')
+			body.temperature = 1.0
 		}
 	}
 
-	if (modelName.startsWith('grok')) {
-		debug('Applying Grok patch: removing tool_choice')
+	if (modelName.startsWith('deepseek')) {
+		debug('Patch DeepSeek: disable thinking, remove tool_choice')
+		body.thinking = { type: 'disabled' }
 		delete body.tool_choice
-		debug('Applying Grok patch: disable reasoning and thinking')
-		body.thinking = { type: 'disabled', effort: 'minimal' }
-		body.reasoning = { enabled: false, effort: 'low' }
 	}
 
 	if (modelName.startsWith('gpt')) {
-		debug('Applying GPT patch: set verbosity to low')
-		body.verbosity = 'low'
+		if (modelName.startsWith('gpt-5')) {
+			body.verbosity = 'low'
 
-		if (modelName.startsWith('gpt-52')) {
-			debug('Applying GPT-52 patch: disable reasoning')
-			body.reasoning_effort = 'none'
-		} else if (modelName.startsWith('gpt-51')) {
-			debug('Applying GPT-51 patch: disable reasoning')
-			body.reasoning_effort = 'none'
-		} else if (modelName.startsWith('gpt-5-mini')) {
-			debug('Applying GPT-5-mini patch: set reasoning effort to low, temperature to 1')
-			body.reasoning_effort = 'low'
-			body.temperature = 1
-		} else if (modelName.startsWith('gpt-5')) {
-			debug('Applying GPT-5 patch: set reasoning effort to low')
+			// gpt-5 gpt-5-mini gpt-5-nano only supports "minimal";
+			// 5.1+ supports "none".
+			body.reasoning_effort = /^gpt-5(-|$)/.test(modelName) ? 'minimal' : 'none'
+			debug(`Patch GPT-5: verbosity=low, reasoning_effort=${body.reasoning_effort}`)
+		}
+
+		if (modelName.includes('chat-latest')) {
+			debug('Omitting reasoning_effort and temperature for chat-latest')
+			delete body.reasoning_effort
+			delete body.temperature
+		}
+	}
+
+	if (modelName.startsWith('claude')) {
+		if (/opus|sonnet|haiku/.test(modelName)) {
+			debug('Patch Claude: disable thinking')
+			body.thinking = { type: 'disabled' }
+
+			if (provider !== 'openrouter') {
+				// Convert tool_choice to Claude format
+				if (body.tool_choice === 'required') {
+					// 'required' -> { type: 'any' } (must call some tool)
+					debug('Applying Claude patch: convert tool_choice "required" to { type: "any" }')
+					body.tool_choice = { type: 'any' }
+				} else if (body.tool_choice?.function?.name) {
+					// { type: 'function', function: { name: '...' } } -> { type: 'tool', name: '...' }
+					debug('Applying Claude patch: convert tool_choice format')
+					body.tool_choice = { type: 'tool', name: body.tool_choice.function.name }
+				}
+			}
+		} else {
+			debug('Patch Claude: reasoning_effort=low')
 			body.reasoning_effort = 'low'
+
+			// Fable and mythos can not disable adaptive thinking.
+			// Claude does not support tool_choice with extended thinking.
+			// These 2 concepts are blurred. Basically no tool_choice with thinking.
+			delete body.tool_choice
 		}
 	}
 
 	if (modelName.startsWith('gemini')) {
-		debug('Applying Gemini patch: set reasoning effort to minimal')
-		body.reasoning_effort = 'minimal'
+		debug('Patch Gemini: reasoning_effort=low')
+		body.reasoning_effort = 'low'
+		if (/^gemini-25(?!.*pro)/.test(modelName)) {
+			debug('Patch Gemini 2.5 non-Pro: reasoning_effort=none')
+			body.reasoning_effort = 'none'
+		} else if (
+			modelName.startsWith('gemini-35-flash') ||
+			modelName.startsWith('gemini-31-flash-lite') ||
+			modelName.startsWith('gemini-3-flash')
+		) {
+			debug('Patch Gemini 3.x Flash/Lite: reasoning_effort=minimal')
+			body.reasoning_effort = 'minimal'
+		}
+	}
+
+	if (modelName.startsWith('glm')) {
+		debug('Patch GLM: disable thinking')
+		body.thinking = { type: 'disabled' }
+	}
+
+	if (modelName.startsWith('grok')) {
+		if (/^grok-4-?3/.test(modelName)) {
+			debug('Patch Grok 4.3: reasoning_effort=none')
+			body.reasoning_effort = 'none'
+		} else if (modelName.startsWith('grok-3-mini') || modelName.startsWith('grok-code-fast')) {
+			debug('Patch Grok mini/code: reasoning_effort=low')
+			body.reasoning_effort = 'low'
+		}
+	}
+
+	if (modelName.startsWith('kimi')) {
+		if (!modelName.includes('code')) {
+			// kimi-k2.7-code cannot disable thinking
+			debug('Patch Kimi: disable thinking')
+			body.thinking = { type: 'disabled' }
+		}
+	}
+
+	if (modelName.startsWith('minimax')) {
+		debug('Patch MiniMax: remove parallel_tool_calls')
+		delete body.parallel_tool_calls
+
+		if (modelName.includes('m3')) {
+			// Only M3 can disable thinking
+			debug('Patch MiniMax: disable thinking')
+			body.thinking = { type: 'disabled' }
+		}
+	}
+
+	// provider patches
+
+	if (provider === 'openrouter') {
+		// openrouter use reasoning object instead of reasoning_effort
+
+		const reasoningEffort = body.reasoning_effort
+		const reasoningDisabled =
+			body.thinking?.type === 'disabled' ||
+			body.enable_thinking === false ||
+			reasoningEffort === 'none'
+
+		if (reasoningDisabled) {
+			body.reasoning = { enabled: false }
+		} else if (reasoningEffort) {
+			body.reasoning = { enabled: true, effort: reasoningEffort }
+		}
 	}
 
 	return body
@@ -106,7 +190,7 @@ export function modelPatch(body: Record<string, any>) {
  * They should be treated as the same model.
  * Normalize them to `gpt-52`
  */
-function normalizeModelName(modelName: string): string {
+export function normalizeModelName(modelName: string): string {
 	let normalizedName = modelName.toLowerCase()
 
 	// remove prefix before '/'
@@ -122,3 +206,15 @@ function normalizeModelName(modelName: string): string {
 
 	return normalizedName
 }
+
+export function getProvider(baseURL?: string): 'openrouter' | undefined {
+	if (!baseURL) return undefined
+	try {
+		const url = new URL(baseURL)
+		const hostname = url.hostname
+		if (hostname === 'openrouter.ai') return 'openrouter'
+		return undefined
+	} catch (e) {
+		return undefined
+	}
+}

packages/llms/tsconfig.dts.json

@@ -1,9 +0,0 @@
-{
-    "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

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

packages/llms/vite.config.js

@@ -11,11 +11,20 @@ console.log(chalk.cyan(`📦 Building @page-agent/llms`))
 
 export default defineConfig({
 	clearScreen: false,
-	plugins: [dts({ tsconfigPath: './tsconfig.dts.json', bundleTypes: true })],
+	plugins: [
+		dts({
+			include: ['src/**/*.ts'],
+			exclude: ['src/**/*.test.ts'],
+			bundleTypes: true,
+			compilerOptions: {
+				composite: true,
+				noEmit: false,
+				emitDeclarationOnly: true,
+				declaration: true,
+			},
+		}),
+	],
 	publicDir: false,
-	esbuild: {
-		keepNames: true,
-	},
 	build: {
 		lib: {
 			entry: resolve(__dirname, 'src/index.ts'),

packages/llms/vitest.config.js

@@ -0,0 +1,10 @@
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+	test: {
+		name: 'llms',
+		include: ['src/**/*.test.ts'],
+		// Suppress console output from passing tests; failed tests still get their logs.
+		silent: 'passed-only',
+	},
+})

packages/mcp/README.md

@@ -0,0 +1,93 @@
+# @page-agent/mcp
+
+MCP server that lets AI agent clients (Claude Desktop, Copilot, etc.) control your browser through the [Page Agent](https://github.com/alibaba/page-agent) extension.
+
+## Prerequisites
+
+- Node.js >= 20
+- [Page Agent Extension](https://chromewebstore.google.com/detail/page-agent-ext/akldabonmimlicnjlflnapfeklbfemhj) installed in Chrome
+- An LLM API key (OpenAI-compatible)
+
+## Installation
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+    "mcpServers": {
+        "page-agent": {
+            "command": "npx",
+            "args": ["-y", "@page-agent/mcp"],
+            "env": {
+                "LLM_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1",
+                "LLM_API_KEY": "sk-xxx",
+                "LLM_MODEL_NAME": "qwen3.5-plus"
+            }
+        }
+    }
+}
+```
+
+### Cursor / Copilot
+
+Same format — add the config to the MCP settings of your client.
+
+## MCP Tools
+
+| Tool           | Input              | Description                                           |
+| -------------- | ------------------ | ----------------------------------------------------- |
+| `execute_task` | `{ task: string }` | Execute a browser task in natural language. Blocking. |
+| `get_status`   | —                  | Returns `{ connected, busy }`                         |
+| `stop_task`    | —                  | Stop the currently running task.                      |
+
+## Environment Variables
+
+| Variable         | Default | Description           |
+| ---------------- | ------- | --------------------- |
+| `LLM_BASE_URL`   | —       | LLM API base URL      |
+| `LLM_API_KEY`    | —       | LLM API key           |
+| `LLM_MODEL_NAME` | —       | Model name            |
+| `PORT`           | `38401` | HTTP + WebSocket port |
+
+## How It Works
+
+```
+┌──────────────┐  stdio   ┌──────────────────┐  WebSocket   ┌──────────────┐
+│ Claude /     │◄────────►│ @page-agent/mcp  │◄────────────►│ Hub tab      │
+│ Copilot      │  (MCP)   │ (Node.js)        │  (localhost) │ (extension)  │
+└──────────────┘          └──────────────────┘              └──────┬───────┘
+                                   │                               │
+                                   │ HTTP                          │ useAgent
+                                   ▼                               ▼
+                          ┌──────────────────┐              ┌──────────────┐
+                          │ Launcher page    │              │ MultiPage    │
+                          │ (localhost:PORT) │              │ Agent        │
+                          └──────────────────┘              └──────────────┘
+```
+
+1. Agent client starts the MCP server via stdio (`npx @page-agent/mcp`).
+2. Server starts HTTP + WS on `localhost:PORT`, opens the launcher page in browser.
+3. Launcher page triggers the extension to open a **hub tab** (`hub.html?ws=PORT`).
+4. Hub connects to the WS server. MCP tools now proxy tasks to the hub.
+
+The hub tab speaks a generic WebSocket protocol (defined in `hub-ws.ts` in the extension package) and has no knowledge of MCP. See the hub's protocol docs for message format details.
+
+## Architecture
+
+Pure JS ESM, no build step. Source files are the published artifacts.
+
+```
+src/
+├── index.js        # CLI entry: MCP server (stdio) + opens launcher
+├── hub-bridge.js   # HTTP server + WebSocket bridge to hub tab
+└── launcher.html   # Bootstrap page: detects extension, triggers hub open
+```
+
+## Dev
+
+```bash
+npm run dev:ext
+npx @modelcontextprotocol/inspector node packages/mcp/src/index.js
+```

packages/mcp/package.json

@@ -0,0 +1,35 @@
+{
+    "name": "@page-agent/mcp",
+    "private": false,
+    "version": "1.11.0",
+    "type": "module",
+    "bin": {
+        "page-agent-mcp": "src/index.js"
+    },
+    "files": [
+        "src/"
+    ],
+    "description": "MCP server for controlling the browser via Page Agent extension",
+    "keywords": [
+        "page-agent",
+        "mcp",
+        "browser-automation",
+        "chrome-extension"
+    ],
+    "author": "Simon<gaomeng1900>",
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/alibaba/page-agent.git",
+        "directory": "packages/mcp"
+    },
+    "homepage": "https://alibaba.github.io/page-agent/",
+    "engines": {
+        "node": ">=20"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.29.0",
+        "ws": "^8.21.0",
+        "zod": "^4.4.3"
+    }
+}

packages/mcp/src/hub-bridge.js

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+import { readFileSync } from 'node:fs'
+import http from 'node:http'
+import { fileURLToPath } from 'node:url'
+import { WebSocketServer } from 'ws'
+
+const EXT_ID = 'akldabonmimlicnjlflnapfeklbfemhj'
+const STORE_URL = `https://chromewebstore.google.com/detail/page-agent-ext/${EXT_ID}`
+const LOOPBACK_HOST = 'localhost'
+
+const launcherTemplate = readFileSync(
+	fileURLToPath(new URL('./launcher.html', import.meta.url)),
+	'utf-8'
+)
+
+/**
+ * HTTP + WebSocket bridge to the hub.html extension tab.
+ * - HTTP serves the launcher page (triggers extension to open hub)
+ * - WS carries execute/stop commands and result/error responses
+ */
+export class HubBridge {
+	/** @type {number} */
+	port
+
+	/** @type {http.Server} */
+	#httpServer
+
+	/** @type {WebSocketServer} */
+	#wss
+
+	/** @type {import('ws').WebSocket | null} */
+	#hub = null
+
+	/** @type {{ resolve: (r: {success: boolean, data: string}) => void, reject: (e: Error) => void } | null} */
+	#pendingTask = null
+
+	/** @param {number} port */
+	constructor(port) {
+		this.port = port
+		this.#httpServer = http.createServer((_req, res) => {
+			const html = launcherTemplate
+				.replaceAll('__EXT_ID__', EXT_ID)
+				.replaceAll('__STORE_URL__', STORE_URL)
+				.replaceAll('__WS_PORT__', String(port))
+			res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+			res.end(html)
+		})
+		this.#wss = new WebSocketServer({ server: this.#httpServer })
+		this.#wss.on('connection', (ws) => this.#onConnection(ws))
+	}
+
+	/** @returns {Promise<void>} */
+	async start() {
+		return new Promise((resolve, reject) => {
+			this.#httpServer.on('error', (/** @type {NodeJS.ErrnoException} */ err) => {
+				if (err.code === 'EADDRINUSE') {
+					reject(
+						new Error(`Port ${this.port} is in use. Another Page Agent MCP server may be running.`)
+					)
+				} else {
+					reject(err)
+				}
+			})
+			this.#httpServer.listen(this.port, LOOPBACK_HOST, () => {
+				console.error(`[page-agent-mcp] HTTP + WS on http://${LOOPBACK_HOST}:${this.port}`)
+				resolve()
+			})
+		})
+	}
+
+	get connected() {
+		return this.#hub?.readyState === 1
+	}
+
+	get busy() {
+		return this.#pendingTask !== null
+	}
+
+	/**
+	 * @param {string} task
+	 * @param {Record<string, unknown>} [config]
+	 * @returns {Promise<{success: boolean, data: string}>}
+	 */
+	async executeTask(task, config) {
+		if (!this.connected) throw new Error('Hub is not connected. Is the extension running?')
+		if (this.#pendingTask) throw new Error('Agent is already running a task.')
+
+		return new Promise((resolve, reject) => {
+			this.#pendingTask = { resolve, reject }
+			this.#hub.send(JSON.stringify({ type: 'execute', task, config }))
+		})
+	}
+
+	stopTask() {
+		if (this.connected) {
+			this.#hub.send(JSON.stringify({ type: 'stop' }))
+		}
+	}
+
+	// TODO: Add version checking
+
+	/** @param {import('ws').WebSocket} ws */
+	#onConnection(ws) {
+		if (this.#hub && this.#hub.readyState === 1) {
+			ws.close(4000, 'Another hub is already connected')
+			return
+		}
+
+		this.#hub = ws
+		console.error('[page-agent-mcp] Hub connected')
+
+		ws.on('message', (/** @type {Buffer} */ rawData) => {
+			/** @type {{ type: string, success?: boolean, data?: string, message?: string }} */
+			let msg
+			try {
+				msg = JSON.parse(rawData.toString('utf-8'))
+			} catch {
+				return
+			}
+
+			if (msg.type === 'result') {
+				this.#pendingTask?.resolve({ success: msg.success ?? false, data: msg.data ?? '' })
+				this.#pendingTask = null
+			} else if (msg.type === 'error') {
+				this.#pendingTask?.reject(new Error(msg.message ?? 'Unknown error from hub'))
+				this.#pendingTask = null
+			}
+		})
+
+		ws.on('close', () => {
+			console.error('[page-agent-mcp] Hub disconnected')
+			if (this.#hub === ws) this.#hub = null
+			if (this.#pendingTask) {
+				this.#pendingTask.reject(new Error('Hub disconnected while task was running'))
+				this.#pendingTask = null
+			}
+		})
+	}
+}

packages/mcp/src/index.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { exec } from 'node:child_process'
+import { readFileSync } from 'node:fs'
+import { platform } from 'node:os'
+import * as z from 'zod/v4'
+
+import { HubBridge } from './hub-bridge.js'
+
+const env = process.env
+const port = parseInt(env.PORT || '38401')
+const { version } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+
+/** @type {Record<string, string>} */
+const llmConfig = {}
+if (env.LLM_BASE_URL) llmConfig.baseURL = env.LLM_BASE_URL
+if (env.LLM_MODEL_NAME) llmConfig.model = env.LLM_MODEL_NAME
+if (env.LLM_API_KEY) llmConfig.apiKey = env.LLM_API_KEY
+
+// --- Hub bridge (HTTP + WebSocket) ---
+
+const hub = new HubBridge(port)
+await hub.start()
+
+// Open launcher in default browser
+const url = `http://localhost:${port}`
+const cmd = platform() === 'darwin' ? 'open' : platform() === 'win32' ? 'start ""' : 'xdg-open'
+exec(`${cmd} "${url}"`, (err) => {
+	if (err) console.error(`[page-agent-mcp] Could not open browser: ${err.message}`)
+})
+
+// --- MCP server (stdio) ---
+
+const mcpServer = new McpServer({ name: 'page-agent', version })
+
+mcpServer.registerTool(
+	'execute_task',
+	{
+		description: "Execute a task in user's browser.",
+		inputSchema: {
+			task: z
+				.string()
+				.describe(
+					'Task description. Give specific instructions for the task. Steps preferable. And the information you want to get after the task is done.'
+				),
+		},
+	},
+	async ({ task }) => {
+		try {
+			const config = Object.keys(llmConfig).length > 0 ? llmConfig : undefined
+			const result = await hub.executeTask(task, config)
+			return {
+				content: [
+					{
+						type: 'text',
+						text: result.success
+							? `Task completed.\n\n${result.data}`
+							: `Task failed.\n\n${result.data}`,
+					},
+				],
+			}
+		} catch (err) {
+			return {
+				content: [{ type: 'text', text: `Error: ${err.message}` }],
+				isError: true,
+			}
+		}
+	}
+)
+
+mcpServer.registerTool(
+	'get_status',
+	{
+		description: 'Check the current status of the Page Agent hub.',
+	},
+	async () => ({
+		content: [
+			{
+				type: 'text',
+				text: JSON.stringify({ connected: hub.connected, busy: hub.busy }, null, 2),
+			},
+		],
+	})
+)
+
+mcpServer.registerTool(
+	'stop_task',
+	{
+		description: 'Stop the currently running browser automation task.',
+	},
+	async () => {
+		hub.stopTask()
+		return { content: [{ type: 'text', text: 'Stop signal sent.' }] }
+	}
+)
+
+const transport = new StdioServerTransport()
+await mcpServer.connect(transport)
+console.error('[page-agent-mcp] MCP server ready (stdio)')

packages/mcp/src/launcher.html

@@ -0,0 +1,242 @@
+<!doctype html>
+<html>
+	<head>
+		<meta charset="UTF-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<link rel="icon" href="https://page-agent.github.io/assets/brand/page-agent-color-64.png" />
+		<title>Page Agent MCP Launcher</title>
+		<style>
+			* {
+				margin: 0;
+				padding: 0;
+				box-sizing: border-box;
+			}
+			body {
+				font-family:
+					system-ui,
+					-apple-system,
+					sans-serif;
+				background: #09090b;
+				color: #e5e5e5;
+				display: flex;
+				align-items: center;
+				justify-content: center;
+				min-height: 100vh;
+			}
+			.card {
+				text-align: center;
+				max-width: 480px;
+				padding: 3rem 2rem;
+			}
+			.logo {
+				width: 72px;
+				height: 72px;
+				border-radius: 18px;
+				margin-bottom: 1rem;
+			}
+			.badge {
+				font-size: 0.6875rem;
+				font-weight: 500;
+				color: #52525b;
+				letter-spacing: 0.05em;
+				text-transform: uppercase;
+				margin-bottom: 1.5rem;
+			}
+			h1 {
+				font-size: 1.35rem;
+				font-weight: 600;
+				margin-bottom: 0.5rem;
+			}
+			.sub {
+				font-size: 0.875rem;
+				color: #a1a1aa;
+				line-height: 1.7;
+			}
+			.spinner {
+				width: 32px;
+				height: 32px;
+				border: 3px solid #27272a;
+				border-top-color: #fff;
+				border-radius: 50%;
+				animation: spin 0.8s linear infinite;
+				margin: 0 auto 1.5rem;
+			}
+			@keyframes spin {
+				to {
+					transform: rotate(360deg);
+				}
+			}
+			a {
+				color: #60a5fa;
+				text-decoration: none;
+			}
+			a:hover {
+				text-decoration: underline;
+			}
+
+			.install {
+				display: none;
+			}
+			.install.show {
+				display: block;
+			}
+
+			.tips {
+				margin-top: 1.75rem;
+				text-align: left;
+				background: #18181b;
+				border: 1px solid #27272a;
+				border-radius: 12px;
+				padding: 1.25rem 1.5rem;
+			}
+			.tips li {
+				font-size: 0.8125rem;
+				color: #a1a1aa;
+				line-height: 1.7;
+				margin-left: 1rem;
+			}
+			.tips li + li {
+				margin-top: 0.35rem;
+			}
+
+			.store-btn {
+				display: inline-flex;
+				align-items: center;
+				gap: 0.625rem;
+				margin-top: 1.5rem;
+				padding: 0.625rem 1.5rem;
+				background: #2563eb;
+				color: #fff;
+				border-radius: 10px;
+				font-size: 0.875rem;
+				font-weight: 500;
+				transition: background 0.15s;
+			}
+			.store-btn:hover {
+				background: #1d4ed8;
+				text-decoration: none;
+			}
+			.store-btn img {
+				width: 20px;
+				height: 20px;
+			}
+
+			.links {
+				margin-top: 1.75rem;
+				display: flex;
+				justify-content: center;
+				gap: 1.5rem;
+				font-size: 0.8125rem;
+			}
+			.links a {
+				color: #71717a;
+				transition: color 0.15s;
+			}
+			.links a:hover {
+				color: #a1a1aa;
+				text-decoration: none;
+			}
+		</style>
+	</head>
+	<body>
+		<div class="card">
+			<img
+				class="logo"
+				src="https://page-agent.github.io/assets/brand/page-agent-color-512.webp"
+				alt="Page Agent"
+			/>
+			<div class="badge">Page Agent MCP Launcher</div>
+
+			<div id="connecting">
+				<div class="spinner"></div>
+				<h1 data-i18n="connecting_title">Connecting to Page Agent</h1>
+				<p class="sub" data-i18n="connecting_sub">Opening the hub in your browser…</p>
+			</div>
+
+			<div id="install" class="install">
+				<h1 data-i18n="install_title">Extension Required</h1>
+				<p class="sub" data-i18n="install_sub">
+					Page Agent requires the latest browser extension to work.
+				</p>
+
+				<a class="store-btn" href="__STORE_URL__" target="_blank">
+					<img
+						src="https://page-agent.github.io/assets/third-party/chrome-web-store-192.svg"
+						alt=""
+					/>
+					<span data-i18n="install_btn">Install from Chrome Web Store</span>
+				</a>
+
+				<ul class="tips">
+					<li data-i18n="tip_outdated">
+						If the extension is outdated, please update it to the latest version.
+					</li>
+					<li data-i18n="tip_other_browser">
+						If the extension is not installed in this browser, open this page from the browser that
+						has it installed.
+					</li>
+					<li data-i18n="tip_refresh">Refresh this page after installing or updating.</li>
+				</ul>
+			</div>
+
+			<div class="links">
+				<a
+					href="https://alibaba.github.io/page-agent/docs/introduction/overview"
+					target="_blank"
+					data-i18n="link_docs"
+					>Docs</a
+				>
+				<a
+					href="https://github.com/alibaba/page-agent/issues"
+					target="_blank"
+					data-i18n="link_issues"
+					>Report an Issue</a
+				>
+			</div>
+		</div>
+
+		<script>
+			{
+				const EXT_ID = '__EXT_ID__'
+				const wsPort = __WS_PORT__
+
+				const zh = {
+					connecting_title: '正在连接 Page Agent',
+					connecting_sub: '正在浏览器中打开 Hub…',
+					install_title: '需要安装浏览器插件',
+					install_sub: 'Page Agent 需要安装最新版浏览器插件才能运行。',
+					install_btn: '从 Chrome 应用商店安装',
+					tip_outdated: '如果插件版本过旧，请更新到最新版本。',
+					tip_other_browser: '如果该浏览器中未安装插件，请从装有插件的浏览器打开此页面。',
+					tip_refresh: '安装或更新后，请刷新此页面。',
+					link_docs: '文档',
+					link_issues: '问题反馈',
+				}
+
+				if (/^zh\b/i.test(navigator.language)) {
+					document.querySelectorAll('[data-i18n]').forEach((el) => {
+						const key = el.getAttribute('data-i18n')
+						if (zh[key]) el.textContent = zh[key]
+					})
+				}
+
+				const showInstall = () => {
+					document.getElementById('connecting').style.display = 'none'
+					document.getElementById('install').classList.add('show')
+				}
+
+				try {
+					if (!globalThis.chrome?.runtime?.sendMessage) {
+						showInstall()
+					} else {
+						chrome.runtime.sendMessage(EXT_ID, { type: 'OPEN_HUB', wsPort }, (response) => {
+							if (chrome.runtime.lastError || !response?.ok) showInstall()
+						})
+					}
+				} catch {
+					showInstall()
+				}
+			}
+		</script>
+	</body>
+</html>