/**
 * Browser Intent MCP Tools — ADR-175 page-agent integration.
 *
 * Adds a natural-language INTENT layer on top of the low-level selector-based
 * `browser_*` tools (browser-tools.ts, driven by the `agent-browser` CLI).
 * `browser_act({ task })` lets a caller say "Click the login button" instead
 * of chaining browser_snapshot + browser_click.
 *
 * Backing library: `page-agent` (npm, MIT, https://github.com/alibaba/page-agent)
 * — in-page injected JS that turns the DOM into text and lets an LLM execute
 * natural-language intents via `agent.execute('Click login')`.
 *
 * ============================================================================
 * VERIFIED API (recorded 2026-07-04 against page-agent@1.11.0 — `npm view
 * page-agent`, the published README, and the actual npm tarball contents).
 * Deviations from the original integration brief are called out inline.
 * ============================================================================
 *
 * - Package layout changed since the brief was written: `page-agent` is now a
 *   thin composition of `@page-agent/core` + `@page-agent/llms` +
 *   `@page-agent/page-controller` + `@page-agent/ui`. The npm package is
 *   ESM-only (`"type":"module"`) and ships two builds:
 *     - `dist/esm/page-agent.js` — the Node/bundler ESM entry.
 *     - `dist/iife/page-agent.demo.js` — a self-contained browser IIFE that
 *       sets `window.PageAgent = <class>` (this is what we inject).
 *
 * - DEVIATION #1 (load-bearing): `await import('page-agent')` is NOT a safe
 *   availability probe in Node. Empirically, importing the ESM entry throws
 *   `ReferenceError: window is not defined` — even when the package IS
 *   correctly installed — because `@page-agent/core`'s module graph touches
 *   DOM globals at import time (it's designed to run in a browser, not Node).
 *   This differs from the agenticow-loader.ts pattern used elsewhere in this
 *   repo (dynamic `import()` + catch `ERR_MODULE_NOT_FOUND`), which only
 *   works for pure-Node optional deps. Instead we detect availability via
 *   `require.resolve('page-agent')` — path resolution only, never executes
 *   module code — the same technique `browser-session-tools.ts` already uses
 *   to resolve the local `ruvector` CLI bin without invoking it.
 *
 * - DEVIATION #2: the IIFE bundle unconditionally (also) auto-constructs a
 *   DEMO `PageAgent` instance via `setTimeout`, pointed at Alibaba's public
 *   sandbox endpoint (`model: 'qwen3.5-plus'`, a `page-ag-testing-*.run`
 *   baseURL, `apiKey: 'NA'`) UNLESS the bundle is loaded via a real
 *   `<script src="...?autoInit=false">` tag — the guard reads
 *   `document.currentScript.src`, which is `null` when the bundle runs via
 *   `eval`/CDP (our only injection path through the `agent-browser`
 *   primitive set). Left alone, every `browser_act` call would leak page
 *   content to Alibaba's test endpoint using a placeholder key. We strip the
 *   demo auto-init tail (`stripDemoAutoInit`) before injecting rather than
 *   relying on the query-param guard.
 *
 * - Constructor: `new PageAgent({ model, baseURL, apiKey, language })` —
 *   `apiKey` is OPTIONAL on the type (`LLMConfig.apiKey?: string`), confirmed
 *   in `@page-agent/llms`' `LLMConfig` interface.
 *
 * - `execute(task: string): Promise<ExecutionResult>` where
 *   `ExecutionResult = { success: boolean; data: string; history: HistoricalEvent[] }`
 *   — DEVIATION #3: NOT `{ success, result, steps }` as sketched in the
 *   original brief. We map `data` → `result` and `history.length` → `steps`
 *   in the tool's own return shape, and also pass `history` through for
 *   callers that want the full step trace.
 *
 * - LLM transport: confirmed via `@page-agent/llms`' `OpenAIClient` — a
 *   single non-streaming `POST ${baseURL}/chat/completions` with
 *   `Authorization: Bearer ${apiKey}` and OpenAI tool-calling JSON. This is
 *   why a bare `ANTHROPIC_API_KEY` cannot be handed to page-agent directly:
 *   Anthropic's native API is a different shape (`/v1/messages`, different
 *   tool-call format). We require an OpenAI-*compatible* endpoint — reusing
 *   this CLI's own Tier-3 fallback ladder from `agent-execute-core.ts`
 *   (OpenRouter, then Ollama Cloud), or an explicit override.
 *
 * ARCHITECTURAL CONSTRAINT (mirrors metaharness-tools.ts / agenticow-tools.ts)
 * `page-agent` lives in `optionalDependencies`. Every code path degrades to
 * `{ degraded: true }` — never throws — when the package or an LLM provider
 * isn't available.
 *
 * KEY-SAFETY CONSTRAINT (load-bearing): page-agent's LLM calls happen FROM
 * the browser page context (it's client-side injected JS), so its `apiKey`
 * config field is necessarily visible to whatever we inject into the page.
 * To avoid ever placing a real provider key into a page-context string, we
 * start a short-lived local HTTP proxy (`startLocalLLMProxy`) bound to
 * 127.0.0.1 that holds the REAL key server-side and injects the real
 * `Authorization` header itself; the page only ever sees the proxy's
 * loopback URL plus a constant placeholder string (`PLACEHOLDER_API_KEY`).
 *
 * @module @claude-flow/cli/mcp-tools/browser-intent
 */
import type { MCPTool } from './types.js';
export interface PageAgentBundle {
    /** Package root directory (contains package.json). */
    root: string;
    /** Absolute path to the browser-injectable IIFE bundle. */
    iifePath: string;
    version: string;
}
/**
 * Locate the installed `page-agent` package's browser bundle without ever
 * executing its module code. `resolvePkg` is injectable for tests (DI over
 * module mocking, since `vi.mock('page-agent', ...)` cannot simulate absence
 * for a package we deliberately never `import()`).
 */
export declare function locatePageAgentBundle(resolvePkg?: (id: string) => string): PageAgentBundle | null;
export interface ResolvedLLMConfig {
    baseURL: string;
    apiKey: string;
    model: string;
    source: 'explicit' | 'openrouter' | 'ollama';
}
export declare function resolvePageAgentLLMConfig(env?: NodeJS.ProcessEnv): ResolvedLLMConfig | null;
export declare const PLACEHOLDER_API_KEY = "ruflo-proxied-key";
export interface LLMProxyHandle {
    url: string;
    close: () => void;
}
export declare function startLocalLLMProxy(real: {
    baseURL: string;
    apiKey: string;
}): Promise<LLMProxyHandle>;
/** Thrown when a bundle still contains a demo/sandbox endpoint after stripping. */
export declare class DemoLeakError extends Error {
    readonly signature: string;
    constructor(signature: string);
}
/** Returns the first demo-leak signature found in `source`, or null if clean. */
export declare function findDemoLeak(source: string): string | null;
/**
 * Strip the demo bundle's auto-init tail so injecting it via eval doesn't spin
 * up a second `window.pageAgent` pointed at Alibaba's sandbox endpoint. This is
 * best-effort at the text level; the real guarantee is the fail-closed
 * `findDemoLeak` firewall enforced in `buildPageAgentInjection`, NOT this strip.
 */
export declare function stripDemoAutoInit(iifeSource: string): string;
export declare const BROWSER_ACT_RESULT_GLOBAL = "__ruflo_browser_act_result__";
export interface PageAgentPageConfig {
    baseURL: string;
    apiKey: string;
    model: string;
    language?: string;
}
/**
 * Build the full script to hand to `browser_eval` / `agent-browser eval`:
 * the (demo-stripped) IIFE bundle, followed by our own controlled
 * construction + `execute()` call whose settled result lands on a window
 * global we can poll for.
 *
 * KEY-SAFETY: `pageConfig.apiKey` MUST be `PLACEHOLDER_API_KEY` (or another
 * non-secret placeholder) — callers are responsible for routing the real key
 * through `startLocalLLMProxy` first. This function only assembles strings;
 * it does not itself guarantee key safety, so callers MUST NOT pass a real
 * key here (see `browserIntentTools` handler for the enforced call site).
 */
export declare function buildPageAgentInjection(iifeSource: string, pageConfig: PageAgentPageConfig, task: string): string;
export declare function recordBrowserTrajectory(entry: {
    task: string;
    url?: string;
    success: boolean;
    dataPreview: string;
    steps: number;
    source: string;
}): Promise<boolean>;
export declare const browserIntentTools: MCPTool[];
export default browserIntentTools;
//# sourceMappingURL=browser-intent-tools.d.ts.map