claude-flow 3.21.1 → 3.23.0

package/v3/@claude-flow/cli/dist/src/mcp-tools/browser-intent-tools.d.ts

@@ -0,0 +1,162 @@
+/**
+ * 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