@omnivoice/page-agent 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,250 @@
-# Temporary Holding Version
+# Page Agent — fork `@omnivoice`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Fork publicado como [`@omnivoice/*`](https://www.npmjs.com/org/omnivoice) (v0.2.0), a partir do
+> [page-agent](https://github.com/alibaba/page-agent) upstream `v1.12.4` (commit `9eb6b66`), MIT.**
+
+## O que este fork muda
+
+Toda divergência do upstream leva um comentário `FORK:` no código (`grep -rn "FORK:" packages/*/src`
+lista o conjunto completo). As principais:
+
+1. **`PageController.readFlatTree()` / `readSelectorMap()`** — acessores somente leitura da
+   árvore e do mapa de elementos da última `updateTree()`, para que um perfilador de página
+   descreva os mesmos elementos que o agente vê.
+2. **Painel em pt-BR** — a UI do agente é traduzida; a língua de trabalho do modelo acompanha a
+   da interface.
+3. **Ícones SVG no lugar de emoji** no painel, e layout responsivo para telas pequenas.
+4. **Renomeado para o namespace publicável `@omnivoice/*`**, versionado de forma independente
+   (`0.1.0`) — o upstream mantém os nomes `page-agent`/`@page-agent/*`.
+
+## Pacotes publicados
+
+| Pacote npm | Conteúdo |
+|---|---|
+| `@omnivoice/page-agent` | O agente completo (single-script; inclui o bundle IIFE `dist/iife/page-agent.demo.js`) |
+| `@omnivoice/core` | Núcleo do laço de raciocínio/ação |
+| `@omnivoice/llms` | Cliente de LLM com o mental model reflection-before-action |
+| `@omnivoice/page-controller` | Operações de DOM e interação com elementos |
+| `@omnivoice/ui` | Componentes de UI (painel e i18n) |
+
+## Widget central + voz (v0.2.0)
+
+**Um único ponto de integração** para qualquer projeto: `mountWidget(config)` centraliza
+agente + painel + voz + configuração num objeto só. O agente é criado **lazy** (a página não
+paga startup até o widget abrir), e a voz (reconhecimento + síntese, pt-BR) usa a Web Speech API
+nativa — degrada graciosamente se o navegador não tiver mic/voz.
+
+```js
+import { mountWidget } from "@omnivoice/page-agent";
+
+const w = mountWidget({
+  // config central do LLM (um lugar só)
+  model: "gpt-4o-mini",
+  baseURL: "https://api.exemplo.com/v1",
+  apiKey: "sk-...",
+  language: "pt-BR",
+  voice: { input: true, output: true, speakOnComplete: true }, // fala o resultado
+});
+
+// handle: w.run(task) · w.stop() · w.show()/hide()/toggle() · w.setConfig(patch) · w.unmount()
+```
+
+Ou via CDN (IIFE) — desligue o auto-init do demo com `data-auto-init="false"`:
+
+```html
+<script src="https://unpkg.com/@omnivoice/page-agent@0.2.0/dist/iife/page-agent.demo.js"
+        data-auto-init="false"></script>
+<script>
+  const w = PageAgent.mountWidget({ model: "...", baseURL: "...", apiKey: "...",
+                                    voice: { input: true, output: true } });
+</script>
+```
+
+O widget injeta um **launcher** (botão flutuante, mobile-friendly, com safe-area) e um
+**botão de microfone** ao lado do campo de tarefa. Sem assets externos, arquivo único e
+cacheável via CDN versionada — pensado para mobile/desktop e rede limitada.
+
+### Gateway — a chave fica no servidor, não no front
+
+Colocar `apiKey` no HTML/JS expõe a chave a qualquer um que abrir o devtools. O padrão: o front
+fala com um **gateway do projeto** (mesma origem do site), que injeta a chave ao chamar o modelo
+e **controla a config** (modelo, URL do provedor, voz) por servidor. Cada projeto roda o seu
+gateway com a sua config.
+
+```bash
+# No projeto (ex.: NoStopPageTest). A chave vive SÓ no ambiente do servidor.
+AGENT_BASE_URL=https://api.openai.com/v1 \
+AGENT_API_KEY=sk-… \
+AGENT_MODEL=gpt-4o-mini \
+AGENT_VOICE_OUTPUT=true \
+npx omnivoice-agent-gateway        # bin do pacote @omnivoice/page-agent
+# → GET  /config  (config pública, SEM chave)  ·  POST /v1/chat/completions (proxy p/ o provedor)
+```
+
+```js
+// No front: só aponta pro gateway. Sem chave, sem modelo — o servidor decide.
+PageAgent.mountWidget({
+  baseURL: "http://127.0.0.1:8790/v1",
+  configUrl: "http://127.0.0.1:8790/config",
+});
+```
+
+O gateway **força o modelo** configurado (o front não escolhe) e **descarta qualquer
+`Authorization` vinda do client** — uma página comprometida não usa outra chave/conta.
+Config por env **ou** `AGENT_CONFIG=agent.config.json`. Zero dependências (Node 18+).
+
+## Uso (classe)
+
+```bash
+npm install @omnivoice/page-agent
+```
+
+```js
+import { PageAgent } from "@omnivoice/page-agent";
+```
+
+Ou single-file via CDN (exposto como `window.PageAgent`):
+
+```html
+<script src="https://unpkg.com/@omnivoice/page-agent@0.2.0/dist/iife/page-agent.demo.js"></script>
+```
+
+## Como publicar
+
+```bash
+npm install
+npm run build:libs        # builda os 5 pacotes
+npm run publish:fork      # publica em ordem de dependência (llms, ui, page-controller, core, page-agent)
+npm run publish:fork -- --dry-run   # simula sem publicar
+```
+
+A publicação usa o token da conta corrente (`npm login`); os pacotes sobem como **public**
+(`--access public`). O repo de origem pode continuar privado — o npm recebe só os artefatos
+buildados.
+
+---
+
+# Page Agent (upstream)
+
+<picture>
+  <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>
+
+[![CI](https://img.shields.io/github/actions/workflow/status/alibaba/page-agent/main-ci.yml?branch=main&style=flat-square&label=ci)](https://github.com/alibaba/page-agent/actions/workflows/main-ci.yml)
+[![npm](https://img.shields.io/npm/v/page-agent?style=flat-square&label=npm)](https://www.npmjs.com/package/page-agent)
+[![downloads](https://img.shields.io/npm/dt/page-agent?style=flat-square)](https://www.npmjs.com/package/page-agent)
+[![Minzipped bundle size (excluding Zod)](https://deno.bundlejs.com/?q=page-agent&config=%7B%22esbuild%22%3A%7B%22external%22%3A%5B%22zod%22%5D%7D%7D&badge&badge-style=flat-square)](https://bundlejs.com/?q=page-agent&config=%7B%22esbuild%22%3A%7B%22external%22%3A%5B%22zod%22%5D%7D%7D 'Minified + gzip size, excluding the Zod peer dependency')
+[![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](https://opensource.org/licenses/MIT)
+[![typescript](https://img.shields.io/badge/%3C%2F%3E-typescript-blue?style=flat-square)](http://www.typescriptlang.org/)
+[![Chrome Web Store Rating](https://img.shields.io/chrome-web-store/rating/akldabonmimlicnjlflnapfeklbfemhj?style=flat-square&label=chrome%20rating)](https://chromewebstore.google.com/detail/page-agent-ext/akldabonmimlicnjlflnapfeklbfemhj)
+[![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. One script gives any web page its own AI agent.
+
+<a href="https://trendshift.io/repositories/22551?utm_source=repository-badge&amp;utm_medium=badge&amp;utm_campaign=badge-repository-22551" target="_blank" rel="noopener noreferrer"><img src="https://trendshift.io/api/badge/repositories/22551" alt="alibaba%2Fpage-agent | Trendshift" width="180"/></a>
+
+🌐 **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>📖 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>
+
+<!-- demo video -->
+
+[![Watch the demo](https://page-agent.github.io/assets/readme/poster.jpg)](https://github.com/user-attachments/assets/a1f2eae2-13fb-4aae-98cf-a3fc1620a6c2)
+
+---
+
+## ✨ Features
+
+- **🎯 Easy integration**
+    - No need for `browser extension` / `python` / `headless browser`.
+    - Just in-page javascript. Everything happens in your web page.
+- **📖 Text-based DOM manipulation**
+    - No screenshots. No multi-modal LLMs or special permissions needed.
+- **🧠 Bring your own LLMs**
+    - Works with most mainstream models, including locally deployed ones. See [supported models](https://alibaba.github.io/page-agent/docs/features/models).
+- **🐙 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.
+- **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 own web agent's reach across browser tabs via the [Chrome extension](https://alibaba.github.io/page-agent/docs/features/chrome-extension).
+- **MCP** - Allow your agent clients to control your browser.
+
+## 🚀 Quick Start
+
+### One-line integration
+
+Fastest way to try PageAgent with our free Demo LLM:
+
+```html
+<script
+    src="https://cdn.jsdelivr.net/npm/page-agent@1.12.4/dist/iife/page-agent.demo.js"
+    crossorigin="anonymous"
+></script>
+
+<!-- China CDN mirror if you can't access jsDelivr -->
+<!-- https://registry.npmmirror.com/page-agent/1.12.4/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).
+>
+> Add `?autoInit=false` to load the script without creating the demo agent automatically. You can then instantiate it with `new window.PageAgent(...)` and your own LLMs.
+
+### NPM Installation
+
+```bash
+npm install page-agent
+```
+
+```javascript
+import { PageAgent } from 'page-agent'
+
+const agent = new PageAgent({
+    model: 'qwen3.5-plus',
+    baseURL: 'https://dashscope.aliyuncs.com/compatible-mode/v1',
+    apiKey: 'YOUR_API_KEY',
+    language: 'en-US',
+})
+
+await agent.execute('Click the login button')
+```
+
+For more programmatic usage, see [📖 Documentations](https://alibaba.github.io/page-agent/docs/introduction/overview).
+
+## 🤝 Contributing
+
+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.
+
+Built something cool with PageAgent? Share it in [Show and Tell](https://github.com/alibaba/page-agent/discussions/categories/show-and-tell). 🙌
+
+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
+
+This project builds upon the excellent work of **[`browser-use`](https://github.com/browser-use/browser-use)**.
+
+`PageAgent` is designed for **client-side web enhancement**, not server-side automation.
+
+```
+DOM processing components and prompt are derived from browser-use:
+
+Browser Use <https://github.com/browser-use/browser-use>
+Copyright (c) 2024 Gregor Zunic
+Licensed under the MIT License
+
+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.
+```
+
+**⭐ Star this repo if you find PageAgent helpful!**

package/dist/esm/PageAgent.d.ts

@@ -0,0 +1,160 @@
+import { AgentConfig } from '@omnivoice/core';
+import { ExecutionResult } from '@omnivoice/core';
+import { PageAgentCore } from '@omnivoice/core';
+import { PageControllerConfig } from '@omnivoice/page-controller';
+import { Panel } from '@omnivoice/ui';
+import { PanelConfig } from '@omnivoice/ui';
+
+export declare function createVoice(options?: VoiceOptions): Voice;
+
+export declare function mountWidget(options?: WidgetOptions): Widget;
+
+export declare class PageAgent extends PageAgentCore {
+    panel: Panel;
+    constructor(config: PageAgentConfig);
+}
+
+export declare type PageAgentConfig = AgentConfig & PageControllerConfig & Omit<PanelConfig, 'language'>;
+
+export declare interface Voice {
+    /** O que o navegador realmente oferece. A UI usa isto para mostrar/ocultar controles. */
+    readonly supported: {
+        input: boolean;
+        output: boolean;
+    };
+    /**
+     * Escuta uma vez e resolve com a transcrição final. Rejeita em erro real; resolve com ""
+     * quando o usuário não fala nada ('no-speech') — não é falha, é "nada foi dito".
+     */
+    listen(): Promise<string>;
+    /** Interrompe a escuta em andamento. */
+    stopListening(): void;
+    /** Fala um texto. `interrupt` corta o que estiver sendo dito antes de começar. */
+    speak(text: string, opts?: {
+        interrupt?: boolean;
+    }): void;
+    /** Para a síntese em andamento. */
+    stopSpeaking(): void;
+    /** Observa transições de estado (a UI mostra o indicador de "ouvindo/falando"). */
+    onStatus(cb: (status: VoiceStatus) => void): () => void;
+}
+
+export declare interface VoiceOptions {
+    /** Idioma BCP-47 do reconhecimento e da síntese. @default 'pt-BR' */
+    lang?: string;
+    /** Habilita o reconhecimento de fala (botão de microfone). @default true */
+    input?: boolean;
+    /** Habilita a síntese de fala (agente fala o resultado). @default false */
+    output?: boolean;
+    /** URI de uma voz específica do speechSynthesis (deixa o módulo escolher quando ausente). */
+    voiceURI?: string;
+    /** Velocidade da síntese (0.1–10). @default 1 */
+    rate?: number;
+    /** Tom da síntese (0–2). @default 1 */
+    pitch?: number;
+    /** Trava de segurança para `listen()`: ms até rejeitar se o reconhecimento não terminar. @default 30000 */
+    listenTimeoutMs?: number;
+}
+
+/**
+ * FORK: módulo de voz do widget. Zero dependências — usa apenas a Web Speech API nativa do
+ * navegador (reconhecimento + síntese), o que mantém o bundle leve e funciona offline/sem rede
+ * além das chamadas do próprio agente.
+ *
+ * Filosofia (regras do laboratório):
+ * - Degrada sem quebrar: se o navegador não tem mic nem síntese, `supported` informa e os
+ *   métodos viram no-op silenciosos — a UI decide esconder os botões, o agente segue funcionando.
+ * - Espera por condição, nunca por relógio: `listen()` resolve quando chega o resultado final;
+ *   o timeout é só uma trava de segurança contra um reconhecimento que "prende" a UI.
+ * - Nada de rede própria: o reconhecimento/síntese são do navegador (Chrome/Edge/Safari enviam
+ *   apenas o áudio necessário para o serviço de voz do SO; em rede limitada isso é mínimo).
+ */
+declare type VoiceStatus = 'idle' | 'listening' | 'speaking';
+
+export declare interface Widget {
+    /** Agente centralizado (mesma instância que o painel controla). `null` até a primeira abertura. */
+    readonly agent: PageAgent | null;
+    /** Voz centralizada (reconhecimento + síntese). `null` até a primeira abertura. */
+    readonly voice: Voice | null;
+    /** Posição do botão-lançador. */
+    readonly launcher: HTMLElement;
+    /** Garante config (busca o `configUrl`) + voz + agente prontos. Idempotente; devolve o agente. */
+    ready(): Promise<PageAgent>;
+    /** Executa uma tarefa programaticamente. */
+    run(task: string): Promise<ExecutionResult>;
+    /** Para a tarefa em andamento (o agente segue reutilizável). */
+    stop(): Promise<void>;
+    /** Abre o painel (propaga erro de config). `hide()`/`toggle()` para fechar/alternar. */
+    show(): Promise<void>;
+    hide(): void;
+    toggle(): void;
+    /** Atualiza config em runtime (recria o agente quando muda algo de LLM/agente). */
+    setConfig(patch: Partial<WidgetOptions>): void;
+    /** Remove launcher, painel e voz da página. */
+    unmount(): void;
+}
+
+export declare interface WidgetOptions {
+    /** Modelo. Ex.: "gpt-4o-mini". */
+    model?: string;
+    /** Endpoint OpenAI-compatible. */
+    baseURL?: string;
+    /**
+     * Chave da API. Só para uso local/sem gateway (ex.: laboratório). Em produção, prefira
+     * `configUrl` + gateway: a chave fica no servidor e não aparece no front-end.
+     */
+    apiKey?: string;
+    /**
+     * URL de uma config pública servida pelo gateway do projeto (ex.: "/api/agent/config").
+     * O widget busca model/idioma/passos/voz DE LÁ — o front nunca precisa da chave. O gateway
+     * é a autoridade: ele injeta a `apiKey` no servidor e força o modelo configurado.
+     */
+    configUrl?: string;
+    /** Customiza o corpo da request (providers específicos). */
+    transformRequestBody?: PageAgentConfig['transformRequestBody'];
+    /** `fetch` custom (proxy, credentials, baixa latência). */
+    customFetch?: PageAgentConfig['customFetch'];
+    maxRetries?: number;
+    /** Idioma da interface e do raciocínio. @default 'pt-BR' */
+    language?: PageAgentConfig['language'];
+    /** Máximo de passos por tarefa. @default 30 */
+    maxSteps?: number;
+    /** Instruções globais/por página. */
+    instructions?: PageAgentConfig['instructions'];
+    /** Ferramentas customizadas. */
+    customTools?: PageAgentConfig['customTools'];
+    /** Máscula sobre a página durante a execução. @default true */
+    enableMask?: boolean;
+    /** Expansão da viewport ao enumerar elementos. @default 0 (só o que está visível) */
+    viewportExpansion?: number;
+    /** Pergunta pela próxima tarefa ao concluir. @default true */
+    promptForNextTask?: boolean;
+    /** Posição do botão-lançador. @default 'bottom-right' */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+    /** Rótulo acessível do botão-lançador. @default 'Abrir assistente da página' */
+    launcherLabel?: string;
+    /** Começa com o painel aberto (em vez de só o botão). @default false */
+    open?: boolean;
+    voice?: WidgetVoiceOptions;
+}
+
+export declare interface WidgetVoiceOptions extends VoiceOptions {
+    /** Fala o resultado quando a tarefa termina (requer `output: true`). @default true */
+    speakOnComplete?: boolean;
+    /** Fala o próximo objetivo a cada passo (mais falante; útil para mãos-livres). @default false */
+    speakSteps?: boolean;
+}
+
+
+export * from "@omnivoice/core";
+
+export { }
+
+
+
+declare global {
+	interface Window {
+		pageAgent?: PageAgent
+		PageAgent: typeof PageAgent
+	}
+}