@omnivoice/page-agent 0.5.0 → 0.6.1

package/dist/esm/debug-extension-D0P_sNkc.js

@@ -0,0 +1,45 @@
+const debugWindow = () => window;
+const MAX_STEPS = 200;
+const MAX_PAGES = 5;
+const HEAD_LENGTH = 4e3;
+function createDebugExtension() {
+  const store = () => debugWindow().__pageAgentDebug ??= { task: "", steps: [], pages: [] };
+  let pageCount = 0;
+  return {
+    name: "debug",
+    hooks: {
+      onBeforeTask(agent) {
+        debugWindow().__pageAgentDebug = { task: agent.task, steps: [], pages: [] };
+        pageCount = 0;
+        console.debug("[page-agent debug] tarefa:", agent.task);
+      },
+      transformPageContent(content) {
+        const debug = store();
+        pageCount += 1;
+        debug.pages.push({ step: pageCount, length: content.length, head: content.slice(0, HEAD_LENGTH) });
+        if (debug.pages.length > MAX_PAGES) debug.pages.shift();
+        return content;
+      },
+      onAfterStep(_agent, history) {
+        const last = [...history].reverse().find((event) => event.type === "step");
+        if (!last || last.type !== "step") return;
+        const entry = {
+          step: last.stepIndex,
+          goal: last.reflection.next_goal ?? "",
+          evaluation: last.reflection.evaluation_previous_goal ?? "",
+          tool: last.action.name,
+          input: last.action.input,
+          output: last.action.output.slice(0, 300)
+        };
+        const debug = store();
+        debug.steps.push(entry);
+        if (debug.steps.length > MAX_STEPS) debug.steps.shift();
+        console.debug(`[page-agent debug] passo ${entry.step}: ${entry.goal} → ${entry.tool}`, entry.input, "⇒", entry.output);
+      }
+    }
+  };
+}
+export {
+  createDebugExtension
+};
+//# sourceMappingURL=debug-extension-D0P_sNkc.js.map

package/dist/esm/debug-extension-D0P_sNkc.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug-extension-D0P_sNkc.js","sources":["../../src/package/debug-extension.ts"],"sourcesContent":["/**\n * Diagnóstico do agente: por passo, o que ele PENSOU (objetivo), FEZ (ferramenta e entrada) e VIU (o conteúdo\n * indexado que foi ao modelo). Serve para responder \"por que o agente não achou X?\" sem adivinhar.\n *\n * ATENÇÃO: o conteúdo da página pode ter dados de clientes. Os registros ficam só no navegador (console e\n * `window.__pageAgentDebug`), nunca são enviados a lugar nenhum, e só existem com `debug: true`. Use em diagnóstico.\n */\n\nimport type { WidgetExtension } from \"../../vendor/page-agent/packages/page-agent/src/widget\";\n\nexport interface DebugStep {\n  step: number;\n  goal: string;\n  evaluation: string;\n  tool: string;\n  input: unknown;\n  output: string;\n}\n\nexport interface DebugPage {\n  step: number;\n  length: number;\n  /** Primeiros caracteres do conteúdo que o modelo recebeu naquele passo. */\n  head: string;\n}\n\nexport interface PageAgentDebug {\n  task: string;\n  steps: DebugStep[];\n  pages: DebugPage[];\n}\n\n/** `window` com o registro de diagnóstico. Local de propósito: não polui o escopo global de quem consome o pacote. */\ntype DebugWindow = Window & { __pageAgentDebug?: PageAgentDebug };\nconst debugWindow = (): DebugWindow => window;\n\nconst MAX_STEPS = 200;\nconst MAX_PAGES = 5;\nconst HEAD_LENGTH = 4000;\n\nexport function createDebugExtension(): WidgetExtension {\n  const store = (): PageAgentDebug => (debugWindow().__pageAgentDebug ??= { task: \"\", steps: [], pages: [] });\n  let pageCount = 0;\n\n  return {\n    name: \"debug\",\n    hooks: {\n      onBeforeTask(agent) {\n        debugWindow().__pageAgentDebug = { task: agent.task, steps: [], pages: [] };\n        pageCount = 0;\n        console.debug(\"[page-agent debug] tarefa:\", agent.task);\n      },\n\n      transformPageContent(content) {\n        const debug = store();\n        pageCount += 1;\n        debug.pages.push({ step: pageCount, length: content.length, head: content.slice(0, HEAD_LENGTH) });\n        if (debug.pages.length > MAX_PAGES) debug.pages.shift();\n        return content;\n      },\n\n      onAfterStep(_agent, history) {\n        const last = [...history].reverse().find((event) => event.type === \"step\");\n        if (!last || last.type !== \"step\") return;\n        const entry: DebugStep = {\n          step: last.stepIndex,\n          goal: last.reflection.next_goal ?? \"\",\n          evaluation: last.reflection.evaluation_previous_goal ?? \"\",\n          tool: last.action.name,\n          input: last.action.input,\n          output: last.action.output.slice(0, 300),\n        };\n        const debug = store();\n        debug.steps.push(entry);\n        if (debug.steps.length > MAX_STEPS) debug.steps.shift();\n        console.debug(`[page-agent debug] passo ${entry.step}: ${entry.goal} → ${entry.tool}`, entry.input, \"⇒\", entry.output);\n      },\n    },\n  };\n}\n"],"names":[],"mappings":"AAkCA,MAAM,cAAc,MAAmB;AAEvC,MAAM,YAAY;AAClB,MAAM,YAAY;AAClB,MAAM,cAAc;AAEb,SAAS,uBAAwC;AACtD,QAAM,QAAQ,MAAuB,YAAA,EAAc,qBAAqB,EAAE,MAAM,IAAI,OAAO,IAAI,OAAO,CAAA,EAAC;AACvG,MAAI,YAAY;AAEhB,SAAO;AAAA,IACL,MAAM;AAAA,IACN,OAAO;AAAA,MACL,aAAa,OAAO;AAClB,oBAAA,EAAc,mBAAmB,EAAE,MAAM,MAAM,MAAM,OAAO,CAAA,GAAI,OAAO,GAAC;AACxE,oBAAY;AACZ,gBAAQ,MAAM,8BAA8B,MAAM,IAAI;AAAA,MACxD;AAAA,MAEA,qBAAqB,SAAS;AAC5B,cAAM,QAAQ,MAAA;AACd,qBAAa;AACb,cAAM,MAAM,KAAK,EAAE,MAAM,WAAW,QAAQ,QAAQ,QAAQ,MAAM,QAAQ,MAAM,GAAG,WAAW,GAAG;AACjG,YAAI,MAAM,MAAM,SAAS,UAAW,OAAM,MAAM,MAAA;AAChD,eAAO;AAAA,MACT;AAAA,MAEA,YAAY,QAAQ,SAAS;AAC3B,cAAM,OAAO,CAAC,GAAG,OAAO,EAAE,QAAA,EAAU,KAAK,CAAC,UAAU,MAAM,SAAS,MAAM;AACzE,YAAI,CAAC,QAAQ,KAAK,SAAS,OAAQ;AACnC,cAAM,QAAmB;AAAA,UACvB,MAAM,KAAK;AAAA,UACX,MAAM,KAAK,WAAW,aAAa;AAAA,UACnC,YAAY,KAAK,WAAW,4BAA4B;AAAA,UACxD,MAAM,KAAK,OAAO;AAAA,UAClB,OAAO,KAAK,OAAO;AAAA,UACnB,QAAQ,KAAK,OAAO,OAAO,MAAM,GAAG,GAAG;AAAA,QAAA;AAEzC,cAAM,QAAQ,MAAA;AACd,cAAM,MAAM,KAAK,KAAK;AACtB,YAAI,MAAM,MAAM,SAAS,UAAW,OAAM,MAAM,MAAA;AAChD,gBAAQ,MAAM,4BAA4B,MAAM,IAAI,KAAK,MAAM,IAAI,MAAM,MAAM,IAAI,IAAI,MAAM,OAAO,KAAK,MAAM,MAAM;AAAA,MACvH;AAAA,IAAA;AAAA,EACF;AAEJ;"}

package/dist/esm/page-agent.d.ts

@@ -224,6 +224,21 @@ export declare interface AgentStepEvent {
     rawRequest?: unknown;
 }
 
+export declare type BrainExtension = WidgetExtension & {
+    name: "brain";
+};
+
+export declare interface BrainOptions {
+    /** `task-intent` (padrão): escrever só se a tarefa pedir. `allow` desliga; `deny` torna somente-leitura. */
+    writePolicy?: WritePolicyMode;
+    /** Quantas repetições consecutivas da mesma ação sem efeito encerram a tarefa. @default 3 */
+    repeatLimit?: number;
+    /** Quantos passos recentes o histórico mantém por inteiro. @default 6 */
+    historyWindow?: number;
+    /** Quantas escritas recusadas encerram a tarefa (o agente insiste em algo que a política nega). @default 3 */
+    refusalLimit?: number;
+}
+
 /**
  * Structured browser state for LLM consumption
  */
@@ -242,6 +257,22 @@ declare function cleanUpHighlights(): void;
 
 export declare function createVoice(options?: VoiceOptions): Voice;
 
+declare interface DebugPage {
+    step: number;
+    length: number;
+    /** Primeiros caracteres do conteúdo que o modelo recebeu naquele passo. */
+    head: string;
+}
+
+export declare interface DebugStep {
+    step: number;
+    goal: string;
+    evaluation: string;
+    tool: string;
+    input: unknown;
+    output: string;
+}
+
 declare namespace dom {
     export {
         resolveViewportExpansion,
@@ -622,6 +653,12 @@ export declare type PageAgentCoreConfig = AgentConfig & {
     pageController: PageController;
 };
 
+export declare interface PageAgentDebug {
+    task: string;
+    steps: DebugStep[];
+    pages: DebugPage[];
+}
+
 /** `window.PageAgent` na build IIFE (CDN): a classe com `mountWidget` e `createVoice` anexados. */
 export declare type PageAgentGlobal = typeof PageAgent & {
     mountWidget: typeof mountWidget;
@@ -891,6 +928,11 @@ export declare interface RetryEvent {
     maxAttempts: number;
 }
 
+/** Resultado da tarefa, com a verificação que o supervisor anexa. */
+export declare type SupervisedResult = {
+    verification?: Verification;
+};
+
 /** Supported UI languages */
 export declare type SupportedLanguage = 'en-US' | 'zh-CN' | 'pt-BR';
 
@@ -944,6 +986,29 @@ export declare interface UserTakeoverEvent {
     type: 'user_takeover';
 }
 
+export declare interface Verification {
+    status: VerificationStatus;
+    reasons: string[];
+    evidence: {
+        effects: number;
+        navigations: number;
+        refusedWrites: number;
+    };
+}
+
+/**
+ * Veredito do supervisor sobre uma tarefa que o agente deu por encerrada. Lógica pura (sem DOM): recebe o que foi
+ * observado e devolve o resultado final com a verificação anexada.
+ *
+ * Princípios:
+ * - Quem manda parar (não-progresso, escritas recusadas em excesso) torna o resultado FALHA, com o motivo.
+ * - "Sucesso" declarado pelo modelo só vira VERIFICADO quando requisitos explícitos da tarefa foram confirmados no DOM
+ *   por um verificador independente. Tarefas abertas (resumir, navegar, responder) não têm esse verificador: ficam
+ *   NÃO VERIFICADAS, com a contagem de efeitos observados. Isso não as reprova — uma resposta legítima pode não mexer
+ *   na página — mas deixa de apresentar a palavra do modelo como fato.
+ */
+export declare type VerificationStatus = "verified" | "unverified" | "failed";
+
 export declare interface Voice {
     /** O que o navegador realmente oferece. A UI usa isto para mostrar/ocultar controles. */
     readonly supported: {
@@ -1017,12 +1082,39 @@ export declare interface Widget {
     hide(): void;
     toggle(): void;
     /** Atualiza config em runtime (recria o agente quando muda algo de LLM/agente). */
-    setConfig(patch: Partial<WidgetOptions>): void;
+    setConfig(patch: Partial<WidgetOptions_2>): void;
     /** Remove launcher, painel e voz da página. */
     unmount(): void;
 }
 
-export declare interface WidgetOptions {
+/**
+ * Extensão do agente: um pacote de ferramentas, instruções e ganchos que se acopla ao agente do widget
+ * sem o widget conhecê-la (o segundo cérebro é uma extensão). Fusão com o que o host já passou:
+ * - `customTools`: mescladas; a extensão que vem depois vence um nome repetido;
+ * - `instructions.system`: concatenado; `getPageInstructions`: resultados concatenados;
+ * - `hooks`: encadeados em ordem (primeiro os do host, depois os de cada extensão); o erro de um gancho
+ *   é registrado e NÃO derruba a tarefa; `transformPageContent` forma um pipeline.
+ */
+export declare interface WidgetExtension {
+    /** Nome, só para diagnóstico. */
+    name?: string;
+    customTools?: PageAgentConfig['customTools'];
+    instructions?: {
+        system?: string;
+        getPageInstructions?: (url: string) => string | undefined | null;
+    };
+    hooks?: WidgetHooks;
+}
+
+/** Ganchos do ciclo do agente (os mesmos do núcleo). Vários ganchos são encadeados em ordem. */
+export declare type WidgetHooks = Pick<PageAgentConfig, 'onBeforeStep' | 'onAfterStep' | 'onBeforeTask' | 'onAfterTask' | 'onDispose' | 'transformPageContent'>;
+
+export declare type WidgetOptions = Omit<WidgetOptions_2, 'brain'> & {
+    /** Liga o segundo cérebro (opt-in). Aceita as opções dele; o gateway só consegue enviar `true`/`false`. */
+    brain?: boolean | BrainOptions;
+};
+
+declare interface WidgetOptions_2 {
     /** Modelo. Ex.: "gpt-4o-mini". */
     model?: string;
     /** Endpoint OpenAI-compatible. */
@@ -1057,6 +1149,20 @@ export declare interface WidgetOptions {
     viewportExpansion?: number;
     /** Pergunta pela próxima tarefa ao concluir. @default true */
     promptForNextTask?: boolean;
+    /** Ganchos do host (rodam antes dos das extensões). */
+    hooks?: WidgetHooks;
+    /** Extensões já prontas (síncronas). */
+    extensions?: WidgetExtension[];
+    /**
+     * Chamada a cada vez que um agente é criado, DEPOIS de a config do gateway ter sido aplicada a `options`.
+     * Serve para decidir extensões a partir de flags declarativas (`brain`, `debug`), que o gateway pode enviar
+     * em JSON — o que não comporta funções.
+     */
+    resolveExtensions?: (options: WidgetOptions_2) => WidgetExtension[] | Promise<WidgetExtension[]>;
+    /** Flag declarativa (o gateway pode enviá-la). Quem a interpreta é `resolveExtensions`; o widget só a repassa. */
+    brain?: boolean;
+    /** Flag declarativa de diagnóstico (idem). */
+    debug?: 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' */
@@ -1073,4 +1179,22 @@ export declare interface WidgetVoiceOptions extends VoiceOptions {
     speakSteps?: boolean;
 }
 
+/**
+ * Política de escrita do segundo cérebro: o agente só altera dados quando a TAREFA pede.
+ *
+ * Por que existe: numa execução real o agente recebeu uma tarefa de localizar um registro e, por conta própria,
+ * digitou texto inventado em formulários, clicou em "Salvar" e em "Criar", e disparou uma sincronização no
+ * servidor. Ler e navegar são seguros; escrever num sistema em produção não é, e o modelo não distingue.
+ *
+ * O que é "escrita", sem inferência de modelo:
+ * - digitar ou selecionar um valor num campo (`input_text`, `select_dropdown_option`);
+ * - clicar num controle cujo NOME de acesso é um verbo de alteração (Salvar, Criar, Excluir, Atualizar, ...).
+ * Clicar em menus, abas, links e botões comuns nunca é bloqueado.
+ *
+ * Quando é permitida: a tarefa contém um verbo de alteração (salvar, criar, excluir, ...); para digitar/selecionar também
+ * basta um verbo de preenchimento (preencher, digitar, selecionar, ...) ou conter o próprio valor a escrever. Os verbos são uma lista fixa e pública (abaixo): a decisão é reproduzível e
+ * não muda com a página. Modo `allow` desliga a política; `deny` torna o agente somente-leitura.
+ */
+export declare type WritePolicyMode = "task-intent" | "allow" | "deny";
+
 export { }

package/dist/esm/page-agent.js

@@ -4558,7 +4558,66 @@ function positionCss(position) {
       return { bottom: "20px", right: "20px", top: "auto", left: "auto" };
   }
 }
-function mountWidget(options = {}) {
+function logHookError(name, error2) {
+  console.error(`[page-agent-widget] gancho ${name} falhou (a tarefa segue):`, error2);
+}
+function mergeExtensions(host, extensions) {
+  const customTools = { ...host.customTools };
+  for (const extension of extensions) Object.assign(customTools, extension.customTools);
+  const system = [host.instructions?.system, ...extensions.map((e) => e.instructions?.system)].map((text) => text?.trim()).filter((text) => Boolean(text)).join("\n\n");
+  const pageProviders = [host.instructions?.getPageInstructions, ...extensions.map((e) => e.instructions?.getPageInstructions)].filter(
+    (fn) => typeof fn === "function"
+  );
+  const getPageInstructions = pageProviders.length ? (url) => {
+    const parts = [];
+    for (const provide of pageProviders) {
+      try {
+        const text = provide(url)?.trim();
+        if (text) parts.push(text);
+      } catch (error2) {
+        logHookError("getPageInstructions", error2);
+      }
+    }
+    return parts.join("\n\n") || void 0;
+  } : void 0;
+  const sources = [host.hooks, ...extensions.map((e) => e.hooks)].filter((h) => Boolean(h));
+  const chain = (name) => {
+    const fns = sources.map((source) => source[name]).filter((fn) => typeof fn === "function");
+    if (!fns.length) return void 0;
+    return (async (...args) => {
+      for (const fn of fns) {
+        try {
+          await fn(...args);
+        } catch (error2) {
+          logHookError(String(name), error2);
+        }
+      }
+    });
+  };
+  const transforms = sources.map((source) => source.transformPageContent).filter((fn) => typeof fn === "function");
+  const transformPageContent = transforms.length ? async (content) => {
+    let current = content;
+    for (const transform of transforms) {
+      try {
+        current = await transform(current);
+      } catch (error2) {
+        logHookError("transformPageContent", error2);
+      }
+    }
+    return current;
+  } : void 0;
+  return {
+    customTools,
+    instructions: system || getPageInstructions ? { ...system ? { system } : {}, ...getPageInstructions ? { getPageInstructions } : {} } : void 0,
+    onBeforeStep: chain("onBeforeStep"),
+    onAfterStep: chain("onAfterStep"),
+    onBeforeTask: chain("onBeforeTask"),
+    onAfterTask: chain("onAfterTask"),
+    onDispose: chain("onDispose"),
+    transformPageContent
+  };
+}
+function mountWidget$1(options = {}) {
   const position = options.position ?? DEFAULTS.position;
   const launcherLabel = options.launcherLabel ?? DEFAULTS.launcherLabel;
   const open = options.open ?? DEFAULTS.open;
@@ -4574,7 +4633,7 @@ function mountWidget(options = {}) {
       const res = await fetch(options.configUrl, { headers: { accept: "application/json" } });
       if (!res.ok) throw new Error(`mountWidget: configUrl respondeu ${res.status} — o gateway está no ar?`);
       const server = await res.json();
-      for (const key of ["model", "language", "maxSteps", "promptForNextTask", "instructions", "voice"]) {
+      for (const key of ["model", "language", "maxSteps", "promptForNextTask", "instructions", "voice", "brain", "debug"]) {
         const value = server[key];
         if (value !== void 0 && value !== null) {
           options[key] = value;
@@ -4598,6 +4657,8 @@ function mountWidget(options = {}) {
         options.configUrl ? "mountWidget: o gateway não enviou `model` e/ou falta `baseURL` no front. Confira AGENT_MODEL no gateway e a baseURL do widget." : "mountWidget: configure `model` e `baseURL` (config central do LLM) antes de abrir o agente."
       );
     }
+    const resolved = options.resolveExtensions ? await options.resolveExtensions(options) : [];
+    const merged = mergeExtensions(options, [...options.extensions ?? [], ...resolved]);
     agent = new PageAgent({
       model,
       baseURL,
@@ -4609,8 +4670,14 @@ function mountWidget(options = {}) {
       maxSteps: options.maxSteps ?? DEFAULTS.maxSteps,
       enableMask: options.enableMask ?? DEFAULTS.enableMask,
       viewportExpansion: options.viewportExpansion ?? DEFAULTS.viewportExpansion,
-      instructions: options.instructions,
-      customTools: options.customTools,
+      instructions: merged.instructions,
+      customTools: merged.customTools,
+      onBeforeStep: merged.onBeforeStep,
+      onAfterStep: merged.onAfterStep,
+      onBeforeTask: merged.onBeforeTask,
+      onAfterTask: merged.onAfterTask,
+      onDispose: merged.onDispose,
+      transformPageContent: merged.transformPageContent,
       promptForNextTask: options.promptForNextTask ?? DEFAULTS.promptForNextTask
     });
     wireVoiceOutput(agent, v);
@@ -4773,6 +4840,26 @@ function mountWidget(options = {}) {
   };
   return widget;
 }
+function mountWidget(options = {}) {
+  const { brain: brainOption, ...rest } = options;
+  const previous = rest.resolveExtensions;
+  return mountWidget$1({
+    ...rest,
+    brain: Boolean(brainOption),
+    resolveExtensions: async (resolved) => {
+      const extensions = previous ? [...await previous(resolved)] : [];
+      if (resolved.brain) {
+        const { createBrainExtension } = await import("./brain-extension-DDuKTYrJ.js").then((n) => n.d);
+        extensions.push(createBrainExtension(typeof brainOption === "object" ? brainOption : {}));
+      }
+      if (resolved.debug) {
+        const { createDebugExtension } = await import("./debug-extension-D0P_sNkc.js");
+        extensions.push(createDebugExtension());
+      }
+      return extensions;
+    }
+  });
+}
 export {
   PageAgent,
   PageAgentCore,