peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/progress/progress-service.js

@@ -0,0 +1,192 @@
+/**
+ * Sub-agent progress file for the RD/QA sub-agents in `peaks-code`'s
+ * Swarm phase. A sub-agent (or the LLM via the `peaks progress step`
+ * CLI) writes a stable JSON file at
+ * `.peaks/_sub_agents/<sid>/subagent-progress.json`. The dispatch +
+ * heartbeat flow (slice #009 + #010) reads this file as the source
+ * of truth for "is this sub-agent still alive?".
+ *
+ * Token cost design (the binding constraint of this feature):
+ *   - The LLM side (step CLI) writes the file at most once per
+ *     phase transition. That is approximately one Bash call per
+ *     RD/QA sub-step. In a typical 5-step sub-agent slice the
+ *     cost is < 10 output tokens.
+ *   - The dispatch side polls the file via `peaks sub-agent
+ *     heartbeat`, not the LLM. Zero token cost.
+ *
+ * Slice #014: the legacy `peaks progress start|watch|close` auto-spawn
+ * surface is DELETED. With dispatch + heartbeat (slice #009 + #010), the
+ * same sub-agent now runs in the same IDE/terminal as the main loop, so
+ * a separate watch window is dead weight. The only remaining consumer
+ * of this module is the `peaks progress step` write path + the
+ * dispatcher's read-back of the progress file.
+ *
+ * This module is pure filesystem. It does NOT import the LLM
+ * harness, does NOT spawn terminals, and does NOT talk to any
+ * IPC. The dispatch-side consumption is in
+ * `src/services/dispatch/sub-agent-dispatcher.ts` and reads the
+ * progress file via `subAgentProgressPath`.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { getSessionIdCanonical } from '../session/session-manager.js';
+import { findProjectRoot } from '../config/config-safety.js';
+// As of slice 2026-06-06-sub-agent-spawn-bug-and-decouple, the per-session
+// sub-agent state files live under `.peaks/_sub_agents/<sid>/`, NOT under
+// `.peaks/_runtime/<sid>/system/`. The new path mirrors the existing `_runtime/`
+// and `_dogfood/` convention (leading underscore = meta-classification, not
+// a per-session artifact). The previous `<sid>/system/...` locations are
+// migrated to the new path on first run of `peaks workspace reconcile
+// --apply` (see `migrateSubAgentState` in reconcile-service.ts).
+const SUB_AGENTS_DIR = '_sub_agents';
+const PROGRESS_FILE_NAME = 'subagent-progress.json';
+function progressPath(projectRoot) {
+    // The progress file lives at `.peaks/_sub_agents/<sid>/subagent-progress.json`.
+    // The leading `_sub_agents/` is a meta-classification (mirrors `_runtime/`,
+    // `_dogfood/`) — the SID is the per-session discriminator inside that meta
+    // dir. Without the SID, sessions would collide on the same file.
+    const sessionId = getSessionIdCanonical(projectRoot);
+    const subDir = sessionId ?? 'unbound';
+    return join(projectRoot, '.peaks', SUB_AGENTS_DIR, subDir, PROGRESS_FILE_NAME);
+}
+function ensureParentDir(path) {
+    const dir = dirname(path);
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+/**
+ * Read the current progress file. Returns a tagged result so
+ * the CLI can map each failure mode to a distinct nextActions
+ * hint (no-binding → run peaks workspace init; no-progress-file
+ * → sub-agent has not started yet; invalid-json → the LLM wrote
+ * garbage; recover by writing a fresh file).
+ */
+export function readSubAgentProgress(options) {
+    const sessionId = getSessionIdCanonical(options.projectRoot);
+    if (sessionId === null) {
+        return { ok: false, reason: 'no-binding' };
+    }
+    const path = progressPath(options.projectRoot);
+    if (!existsSync(path)) {
+        return { ok: false, reason: 'no-progress-file' };
+    }
+    try {
+        const data = JSON.parse(readFileSync(path, 'utf8'));
+        if (data.version !== 1 || typeof data.sessionId !== 'string') {
+            return { ok: false, reason: 'invalid-json' };
+        }
+        return { ok: true, data, path };
+    }
+    catch {
+        return { ok: false, reason: 'invalid-json' };
+    }
+}
+/**
+ * Append-or-replace the current step. Idempotent on identical
+ * (step, phase) — the file is rewritten with the same payload
+ * (no new history entry) so heartbeats from the same phase do
+ * not pollute the history. Phase transitions append a new step
+ * to the history and replace `current`.
+ */
+export function writeSubAgentProgress(options) {
+    const existing = readSubAgentProgress({ projectRoot: options.projectRoot });
+    const now = nowIso();
+    const path = progressPath(options.projectRoot);
+    if (existing.ok) {
+        const prev = existing.data;
+        // Heartbeat on the same current step: just bump updatedAt, do
+        // NOT add a history entry. The shape of `current` is preserved.
+        if (prev.current.step === options.step && prev.current.phase === options.phase) {
+            const next = {
+                ...prev,
+                updatedAt: now,
+                current: {
+                    ...prev.current,
+                    updatedAt: now,
+                    ...(options.verdict !== undefined ? { verdict: options.verdict } : {}),
+                    ...(options.counts !== undefined ? { counts: options.counts } : {})
+                }
+            };
+            ensureParentDir(path);
+            writeFileSync(path, JSON.stringify(next, null, 2) + '\n', 'utf8');
+            return next;
+        }
+        // Real phase / step transition: archive the prior current
+        // into history, install the new current.
+        const archived = {
+            ...prev.current,
+            updatedAt: now
+        };
+        const next = {
+            ...prev,
+            updatedAt: now,
+            current: {
+                startedAt: now,
+                updatedAt: now,
+                step: options.step,
+                phase: options.phase,
+                ...(options.verdict !== undefined ? { verdict: options.verdict } : {}),
+                ...(options.counts !== undefined ? { counts: options.counts } : {})
+            },
+            history: [...prev.history, archived]
+        };
+        ensureParentDir(path);
+        writeFileSync(path, JSON.stringify(next, null, 2) + '\n', 'utf8');
+        return next;
+    }
+    // No prior file: this is the first write. Bootstrap a fresh
+    // progress doc. The sessionId is whatever the binding points
+    // at, so cross-session confusion is impossible.
+    const sessionId = getSessionIdCanonical(options.projectRoot) ?? 'unbound';
+    const fresh = {
+        version: 1,
+        sessionId,
+        ...(options.outerSessionId !== undefined ? { outerSessionId: options.outerSessionId } : {}),
+        role: options.role,
+        requestId: options.requestId,
+        startedAt: now,
+        updatedAt: now,
+        current: {
+            startedAt: now,
+            updatedAt: now,
+            step: options.step,
+            phase: options.phase,
+            ...(options.verdict !== undefined ? { verdict: options.verdict } : {}),
+            ...(options.counts !== undefined ? { counts: options.counts } : {})
+        },
+        history: []
+    };
+    ensureParentDir(path);
+    writeFileSync(path, JSON.stringify(fresh, null, 2) + '\n', 'utf8');
+    return fresh;
+}
+/**
+ * Resolve the project root for a CLI invocation: --project
+ * override wins, otherwise the canonical git-root promotion
+ * (so the sub-agent's writes land in the same `.peaks/_runtime/<sid>/`
+ * the user's manual CLI would use). Re-exports the same
+ * helper peaks workspace init / session rotate already use
+ * for symmetry.
+ */
+export function resolveProgressProjectRoot(override, cwd) {
+    if (override !== undefined)
+        return override;
+    return findProjectRoot(cwd) ?? cwd;
+}
+/**
+ * Compute the absolute path to the progress file for a given
+ * project root, for callers that need to display / fs.watch it
+ * (the dispatcher's read-back, the LLM-side step write banner,
+ * etc.). This MUST agree with `progressPath` — the read/write
+ * helpers resolve through `progressPath` and use the session
+ * sub-directory, so the displayed path does too. Without this
+ * agreement the dispatcher's read-back would point at a path
+ * the writer never touches.
+ */
+export function subAgentProgressPath(projectRoot) {
+    return progressPath(resolve(projectRoot));
+}

package/dist/services/proxy/proxy-service.d.ts

@@ -0,0 +1,7 @@
+export type ProxyTestResult = {
+    proxy: string;
+    target: string;
+    dryRun: boolean;
+    commandPreview: string;
+};
+export declare function planProxyTest(proxy: string, target?: string, dryRun?: boolean): ProxyTestResult;

package/dist/services/proxy/proxy-service.js

@@ -0,0 +1,31 @@
+function shellQuote(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function validateUrl(value, label) {
+    if (!value.startsWith('http://') && !value.startsWith('https://')) {
+        throw new Error(`${label} URL must start with http:// or https://`);
+    }
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        throw new Error(`${label} URL must be a valid URL`);
+    }
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+        throw new Error(`${label} URL must start with http:// or https://`);
+    }
+    if (url.username || url.password) {
+        throw new Error(`${label} URL must not include credentials`);
+    }
+}
+export function planProxyTest(proxy, target = 'https://www.google.com', dryRun = true) {
+    validateUrl(proxy, 'Proxy');
+    validateUrl(target, 'Target');
+    return {
+        proxy,
+        target,
+        dryRun,
+        commandPreview: `curl -x ${shellQuote(proxy)} -I ${shellQuote(target)}`
+    };
+}

package/dist/services/qa/browser-event-logger.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Slice 2026-06-16-playwright-restart-loop — G4.
+ *
+ * BrowserEventLogger
+ *
+ * Append-only JSONL writer for browser-event records. Each line is
+ * a self-contained JSON object, so a crash mid-write leaves a
+ * partial line that downstream readers skip.
+ *
+ * The log path is supplied by the caller (CLI / sub-agent progress
+ * signal). For QA slices the convention is:
+ *   `.peaks/_runtime/<session-id>/qa/browser-events.jsonl`
+ *
+ * The logger is fire-and-forget for the production write path:
+ * a failed append prints a stderr hint and continues, never throws.
+ * The test suite asserts the on-disk format.
+ */
+export type SpuriousRestartEvent = {
+    readonly kind: 'spurious_restart';
+    readonly ts: string;
+    readonly sessionId: string;
+    readonly closeTs: string;
+    readonly navigateTs: string;
+    readonly deltaMs: number;
+};
+export type BrowserEventRecord = SpuriousRestartEvent;
+export type BrowserEventLoggerOptions = {
+    /** Absolute file path. The logger creates the parent dir if missing. */
+    readonly filePath: string;
+};
+export declare class BrowserEventLogger {
+    private readonly filePath;
+    constructor(options: BrowserEventLoggerOptions);
+    /**
+     * Append one record to the JSONL file. Never throws on write
+     * failure (matches the log-commands fire-and-forget pattern; the
+     * detector's halt is the user-facing signal, not the log line).
+     */
+    append(record: BrowserEventRecord): void;
+}

package/dist/services/qa/browser-event-logger.js

@@ -0,0 +1,54 @@
+/**
+ * Slice 2026-06-16-playwright-restart-loop — G4.
+ *
+ * BrowserEventLogger
+ *
+ * Append-only JSONL writer for browser-event records. Each line is
+ * a self-contained JSON object, so a crash mid-write leaves a
+ * partial line that downstream readers skip.
+ *
+ * The log path is supplied by the caller (CLI / sub-agent progress
+ * signal). For QA slices the convention is:
+ *   `.peaks/_runtime/<session-id>/qa/browser-events.jsonl`
+ *
+ * The logger is fire-and-forget for the production write path:
+ * a failed append prints a stderr hint and continues, never throws.
+ * The test suite asserts the on-disk format.
+ */
+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+export class BrowserEventLogger {
+    filePath;
+    constructor(options) {
+        this.filePath = options.filePath;
+    }
+    /**
+     * Append one record to the JSONL file. Never throws on write
+     * failure (matches the log-commands fire-and-forget pattern; the
+     * detector's halt is the user-facing signal, not the log line).
+     */
+    append(record) {
+        const dir = dirname(this.filePath);
+        try {
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+        }
+        catch {
+            return;
+        }
+        let line;
+        try {
+            line = JSON.stringify(record);
+        }
+        catch {
+            return;
+        }
+        try {
+            appendFileSync(this.filePath, line + '\n');
+        }
+        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+            /* best-effort; never block the CLI on a log write */
+        }
+    }
+}

package/dist/services/qa/browser-restart-detector.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Slice 2026-06-16-playwright-restart-loop — G1.
+ *
+ * BrowserRestartDetector
+ *
+ * Watches a stream of `mcp__playwright__browser_*` tool invocations
+ * (synthetic, fed in by tests or by the sub-agent-progress signal)
+ * and emits a halt signal when the model repeatedly tears down
+ * and re-spawns the browser context.
+ *
+ * The detector is intentionally simple and dependency-free:
+ *   - `record(event)` appends one event to a ring buffer.
+ *   - `shouldHalt()` returns true when >= `maxRestarts` close->navigate
+ *     pairs have occurred within `windowMs` of each other.
+ *   - `diagnostic()` renders the user-facing message.
+ *
+ * It does NOT call playwright MCP. It does NOT spawn processes. It
+ * only inspects the synthetic event log.
+ *
+ * R2 (per PRD): server-restart is a different MCP-level event;
+ * only `browser_close` followed by `browser_navigate` (or
+ * `browser_navigate` followed by `browser_close`, in either order)
+ * within `windowMs` counts as a restart. A standalone
+ * `browser_install` is not a tab close.
+ *
+ * Window: pairs are evaluated per (close_ts, navigate_ts) delta. The
+ * detector uses a sliding window of `windowMs` (default 30s, the
+ * PRD R4 default). Older events fall out of the window.
+ *
+ * Test seam: the test suite feeds a hand-rolled sequence of
+ * `BrowserEvent` objects; production will call `record` from the
+ * sub-agent-progress signal when it sees an
+ * `mcp__playwright__browser_*` invocation.
+ */
+export type BrowserEvent = {
+    /** The tool name as seen by the LLM dispatcher (e.g. `browser_close`). */
+    readonly tool: string;
+    /** ISO8601 timestamp. */
+    readonly ts: string;
+};
+export type BrowserRestartDetectorOptions = {
+    /** Maximum number of close->navigate pairs before halt. Default 3 (PRD AC1). */
+    readonly maxRestarts?: number;
+    /** Window in milliseconds within which a close must be followed by a navigate. Default 30_000. */
+    readonly windowMs?: number;
+    /** When false, the detector is a no-op (PRD AC6: --no-restart-detector). Default true. */
+    readonly enabled?: boolean;
+};
+export declare class BrowserRestartDetector {
+    private readonly maxRestarts;
+    private readonly windowMs;
+    private readonly enabled;
+    private readonly events;
+    constructor(options?: BrowserRestartDetectorOptions);
+    /**
+     * Record a single browser event. Returns true when this event
+     * caused a restart count to increment (i.e. it was a navigate
+     * that paired with a prior close inside the window). Returns
+     * false for inert events.
+     */
+    record(event: BrowserEvent): boolean;
+    /**
+     * Count of close->navigate pairs detected within the window. A
+     * pair is one `browser_close` followed by a `browser_navigate`
+     * within `windowMs` of each other.
+     */
+    restartCount(): number;
+    shouldHalt(): boolean;
+    /**
+     * Returns the human-readable diagnostic the user will see when
+     * `shouldHalt` flips to true. Format: AC1 contract.
+     */
+    diagnostic(): string;
+}

package/dist/services/qa/browser-restart-detector.js

@@ -0,0 +1,138 @@
+/**
+ * Slice 2026-06-16-playwright-restart-loop — G1.
+ *
+ * BrowserRestartDetector
+ *
+ * Watches a stream of `mcp__playwright__browser_*` tool invocations
+ * (synthetic, fed in by tests or by the sub-agent-progress signal)
+ * and emits a halt signal when the model repeatedly tears down
+ * and re-spawns the browser context.
+ *
+ * The detector is intentionally simple and dependency-free:
+ *   - `record(event)` appends one event to a ring buffer.
+ *   - `shouldHalt()` returns true when >= `maxRestarts` close->navigate
+ *     pairs have occurred within `windowMs` of each other.
+ *   - `diagnostic()` renders the user-facing message.
+ *
+ * It does NOT call playwright MCP. It does NOT spawn processes. It
+ * only inspects the synthetic event log.
+ *
+ * R2 (per PRD): server-restart is a different MCP-level event;
+ * only `browser_close` followed by `browser_navigate` (or
+ * `browser_navigate` followed by `browser_close`, in either order)
+ * within `windowMs` counts as a restart. A standalone
+ * `browser_install` is not a tab close.
+ *
+ * Window: pairs are evaluated per (close_ts, navigate_ts) delta. The
+ * detector uses a sliding window of `windowMs` (default 30s, the
+ * PRD R4 default). Older events fall out of the window.
+ *
+ * Test seam: the test suite feeds a hand-rolled sequence of
+ * `BrowserEvent` objects; production will call `record` from the
+ * sub-agent-progress signal when it sees an
+ * `mcp__playwright__browser_*` invocation.
+ */
+const DEFAULT_MAX_RESTARTS = 3;
+const DEFAULT_WINDOW_MS = 30_000;
+/**
+ * Tools that count as "tab close" (PRD R2: distinguishes tab-close
+ * from server-restart). A close must be followed by a `browser_navigate`
+ * to count as a restart.
+ */
+const TAB_CLOSE_TOOLS = new Set(['browser_close']);
+/**
+ * Tools that count as "tab spawn" (resets context). The detector
+ * specifically tracks `browser_navigate` because the user-reported
+ * loop pattern is `browser_close` -> `browser_navigate` -> `browser_close`.
+ * Other browser tools (e.g. `browser_click`, `browser_screenshot`)
+ * are inert for restart counting.
+ */
+const TAB_SPAWN_TOOLS = new Set(['browser_navigate']);
+export class BrowserRestartDetector {
+    maxRestarts;
+    windowMs;
+    enabled;
+    events = [];
+    constructor(options = {}) {
+        this.maxRestarts = options.maxRestarts ?? DEFAULT_MAX_RESTARTS;
+        this.windowMs = options.windowMs ?? DEFAULT_WINDOW_MS;
+        this.enabled = options.enabled !== false;
+    }
+    /**
+     * Record a single browser event. Returns true when this event
+     * caused a restart count to increment (i.e. it was a navigate
+     * that paired with a prior close inside the window). Returns
+     * false for inert events.
+     */
+    record(event) {
+        if (!this.enabled)
+            return false;
+        this.events.push(event);
+        // Trim old events that fall outside the window relative to
+        // the LATEST event we have seen (not Date.now()). Tests feed
+        // synthetic 2026-06-16 timestamps; using Date.now() would drop
+        // everything. We only need a 2-event sliding window per pair,
+        // but keep more for the diagnostic.
+        const last = this.events[this.events.length - 1];
+        if (last === undefined)
+            return false;
+        const cutoff = Date.parse(last.ts) - this.windowMs;
+        while (this.events.length > 0) {
+            const first = this.events[0];
+            if (first === undefined)
+                break;
+            if (Date.parse(first.ts) >= cutoff)
+                break;
+            this.events.shift();
+        }
+        return false;
+    }
+    /**
+     * Count of close->navigate pairs detected within the window. A
+     * pair is one `browser_close` followed by a `browser_navigate`
+     * within `windowMs` of each other.
+     */
+    restartCount() {
+        if (!this.enabled)
+            return 0;
+        let count = 0;
+        let pendingCloseTs = null;
+        // Walk in chronological order (the contract is: events are
+        // pushed in order; if not, the worst case is a missed pair
+        // which is still conservative).
+        for (const ev of this.events) {
+            const t = Date.parse(ev.ts);
+            if (TAB_CLOSE_TOOLS.has(ev.tool)) {
+                pendingCloseTs = t;
+                continue;
+            }
+            if (TAB_SPAWN_TOOLS.has(ev.tool)) {
+                if (pendingCloseTs !== null) {
+                    const delta = t - pendingCloseTs;
+                    if (delta >= 0 && delta <= this.windowMs) {
+                        count += 1;
+                        // Reset so we don't double-count. The next close must
+                        // re-arm the pending state.
+                        pendingCloseTs = null;
+                        continue;
+                    }
+                }
+                // A navigate WITHOUT a preceding close is a normal
+                // session start, not a restart.
+                pendingCloseTs = null;
+            }
+        }
+        return count;
+    }
+    shouldHalt() {
+        return this.restartCount() >= this.maxRestarts;
+    }
+    /**
+     * Returns the human-readable diagnostic the user will see when
+     * `shouldHalt` flips to true. Format: AC1 contract.
+     */
+    diagnostic() {
+        const count = this.restartCount();
+        return `playwright browser restart loop detected (${count} restarts in this slice). Reusing the same browser tab is the intended pattern. See .peaks/memory/playwright-restart-loop-2026-06-16.md`;
+    }
+}

package/dist/services/qa/browser-reuse-hint.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Slice 2026-06-16-playwright-restart-loop — G2.
+ *
+ * The browser-context reuse hint is appended to the sub-agent prompt
+ * whenever a peaks-qa-dispatched sub-agent (peaks-ui or general-purpose
+ * with a browser-E2E role) is invoked. The hint tells the model to
+ * keep one browser tab alive across the QA slice and to NOT call
+ * `browser_close` between steps.
+ *
+ * The constant lives here so both the dispatch CLI
+ * (`src/cli/commands/sub-agent-commands.ts`) and any future
+ * SKILL.md / dispatch table can reference the SAME string. Drift
+ * between "the detector knows X" and "the dispatch prompt says X"
+ * is the most common bug in this slice, so a single source of
+ * truth is non-negotiable.
+ */
+export declare const BROWSER_REUSE_HINT = "reuse existing browser tab; do NOT call mcp__playwright__browser_close between steps within this slice \u2014 closing and re-opening the tab repeatedly is a restart loop and will be halted by the slice guard";
+export declare const BROWSER_RESTART_LOOP_MEMORY_PATH = ".peaks/memory/playwright-restart-loop-2026-06-16.md";

package/dist/services/qa/browser-reuse-hint.js

@@ -0,0 +1,18 @@
+/**
+ * Slice 2026-06-16-playwright-restart-loop — G2.
+ *
+ * The browser-context reuse hint is appended to the sub-agent prompt
+ * whenever a peaks-qa-dispatched sub-agent (peaks-ui or general-purpose
+ * with a browser-E2E role) is invoked. The hint tells the model to
+ * keep one browser tab alive across the QA slice and to NOT call
+ * `browser_close` between steps.
+ *
+ * The constant lives here so both the dispatch CLI
+ * (`src/cli/commands/sub-agent-commands.ts`) and any future
+ * SKILL.md / dispatch table can reference the SAME string. Drift
+ * between "the detector knows X" and "the dispatch prompt says X"
+ * is the most common bug in this slice, so a single source of
+ * truth is non-negotiable.
+ */
+export const BROWSER_REUSE_HINT = 'reuse existing browser tab; do NOT call mcp__playwright__browser_close between steps within this slice — closing and re-opening the tab repeatedly is a restart loop and will be halted by the slice guard';
+export const BROWSER_RESTART_LOOP_MEMORY_PATH = '.peaks/memory/playwright-restart-loop-2026-06-16.md';

package/dist/services/qa/browser-wrapper-service.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Slice 3 — `peaks browser action <intent> [args...]` thin wrapper.
+ *
+ * Five supported intents: navigate, click, fill, snapshot, extract.
+ * Each intent invokes EXACTLY ONE Playwright MCP tool call. No auto
+ * snapshots between intents, no retry, no selector caching, no healing.
+ *
+ * Anti-features (per slice 3 spec):
+ *   - No retry / circuit-breaker
+ *   - No selector caching
+ *   - No accessibility tree customization
+ *   - No screenshot / video
+ *   - No "smart selector healing"
+ *
+ * Selectors are restricted to simple forms (`#id`, `.class`, `tag#id`,
+ * `tag.class`, `tag`). Anything else returns a fall-back error pointing
+ * the caller to the raw MCP.
+ */
+export type BrowserIntent = 'navigate' | 'click' | 'fill' | 'snapshot' | 'extract';
+export type McpCaller = (tool: string, args: Record<string, unknown>) => Promise<unknown>;
+export interface BrowserActionArgs {
+    url?: string | undefined;
+    selector?: string | undefined;
+    value?: string | undefined;
+    expression?: string | undefined;
+}
+export interface BrowserActionResult {
+    readonly intent: BrowserIntent;
+    readonly ok: boolean;
+    readonly data: unknown;
+    readonly elapsedMs: number;
+}
+/**
+ * Run a single browser intent. Throws on validation errors; returns
+ * a structured result on success.
+ */
+export declare function runBrowserAction(intent: BrowserIntent, args: BrowserActionArgs, caller: McpCaller): Promise<BrowserActionResult>;