gsd-pi 2.33.1 → 2.34.0-dev.6769913

package/dist/resources/extensions/browser-tools/settle.ts

@@ -1,197 +0,0 @@
-/**
- * browser-tools — DOM settle logic
- *
- * Adaptive settling after browser actions. Polls for DOM quiet (mutation
- * counter stable, no pending critical requests, optional focus stability)
- * before returning control.
- */
-
-import type { Frame, Page } from "playwright";
-import type { AdaptiveSettleDetails, AdaptiveSettleOptions } from "./state.js";
-import { getPendingCriticalRequests } from "./utils.js";
-
-// ---------------------------------------------------------------------------
-// Mutation counter (installed in-page via evaluate)
-// ---------------------------------------------------------------------------
-
-export async function ensureMutationCounter(p: Page): Promise<void> {
-	await p.evaluate(() => {
-		const key = "__piMutationCounter" as const;
-		const installedKey = "__piMutationCounterInstalled" as const;
-		const w = window as unknown as Record<string, unknown>;
-		if (typeof w[key] !== "number") w[key] = 0;
-		if (w[installedKey]) return;
-		const observer = new MutationObserver(() => {
-			const current = typeof w[key] === "number" ? (w[key] as number) : 0;
-			w[key] = current + 1;
-		});
-		observer.observe(document.documentElement || document.body, {
-			subtree: true,
-			childList: true,
-			attributes: true,
-			characterData: true,
-		});
-		w[installedKey] = true;
-	});
-}
-
-export async function readMutationCounter(p: Page): Promise<number> {
-	try {
-		return await p.evaluate(() => {
-			const w = window as unknown as Record<string, unknown>;
-			const value = w.__piMutationCounter;
-			return typeof value === "number" ? value : 0;
-		});
-	} catch {
-		return 0;
-	}
-}
-
-// ---------------------------------------------------------------------------
-// Focus descriptor (for focus-stability checks)
-// ---------------------------------------------------------------------------
-
-export async function readFocusedDescriptor(target: Page | Frame): Promise<string> {
-	try {
-		return await target.evaluate(() => {
-			const el = document.activeElement as HTMLElement | null;
-			if (!el || el === document.body || el === document.documentElement) return "";
-			const id = el.id ? `#${el.id}` : "";
-			const role = el.getAttribute("role") || "";
-			const name = (el.getAttribute("aria-label") || el.getAttribute("name") || "").trim();
-			return `${el.tagName.toLowerCase()}${id}|${role}|${name}`;
-		});
-	} catch {
-		return "";
-	}
-}
-
-// ---------------------------------------------------------------------------
-// Combined settle-state reader (mutation counter + focus in one evaluate)
-// ---------------------------------------------------------------------------
-
-/**
- * Reads the mutation counter and optionally the focused element descriptor
- * in a single `evaluate()` call, saving one round-trip per poll iteration.
- */
-async function readSettleState(
-	target: Page | Frame,
-	checkFocus: boolean,
-): Promise<{ mutationCount: number; focusDescriptor: string }> {
-	try {
-		return await target.evaluate((wantFocus: boolean) => {
-			const w = window as unknown as Record<string, unknown>;
-			const mutationCount = typeof w.__piMutationCounter === "number" ? (w.__piMutationCounter as number) : 0;
-			if (!wantFocus) return { mutationCount, focusDescriptor: "" };
-			const el = document.activeElement as HTMLElement | null;
-			if (!el || el === document.body || el === document.documentElement) {
-				return { mutationCount, focusDescriptor: "" };
-			}
-			const id = el.id ? `#${el.id}` : "";
-			const role = el.getAttribute("role") || "";
-			const name = (el.getAttribute("aria-label") || el.getAttribute("name") || "").trim();
-			return { mutationCount, focusDescriptor: `${el.tagName.toLowerCase()}${id}|${role}|${name}` };
-		}, checkFocus);
-	} catch {
-		return { mutationCount: 0, focusDescriptor: "" };
-	}
-}
-
-// ---------------------------------------------------------------------------
-// Adaptive settle
-// ---------------------------------------------------------------------------
-
-/** Threshold (ms) after which zero mutations triggers a shortened quiet window. */
-const ZERO_MUTATION_THRESHOLD_MS = 60;
-/** Shortened quiet window when no mutations have been observed. */
-const ZERO_MUTATION_QUIET_MS = 30;
-
-export async function settleAfterActionAdaptive(
-	p: Page,
-	opts: AdaptiveSettleOptions = {},
-): Promise<AdaptiveSettleDetails> {
-	const timeoutMs = Math.max(150, opts.timeoutMs ?? 500);
-	const pollMs = Math.min(100, Math.max(20, opts.pollMs ?? 40));
-	const baseQuietWindowMs = Math.max(60, opts.quietWindowMs ?? 100);
-	const checkFocus = opts.checkFocusStability ?? false;
-
-	const startedAt = Date.now();
-	let polls = 0;
-	let sawUrlChange = false;
-	let lastActivityAt = startedAt;
-	let previousUrl = p.url();
-	let totalMutationsSeen = 0;
-	let activeQuietWindowMs = baseQuietWindowMs;
-
-	// Install mutation counter + read initial state in one evaluate sequence.
-	// ensureMutationCounter must run first (installs the observer), then we
-	// read the baseline via the combined reader.
-	await ensureMutationCounter(p).catch((e) => { if (process.env.GSD_DEBUG) console.error("[browser-tools] ensureMutationCounter failed:", e.message); });
-	const initial = await readSettleState(p, checkFocus);
-	let previousMutationCount = initial.mutationCount;
-	let previousFocus = initial.focusDescriptor;
-
-	while (Date.now() - startedAt < timeoutMs) {
-		await new Promise((resolve) => setTimeout(resolve, pollMs));
-		polls += 1;
-		const now = Date.now();
-
-		const currentUrl = p.url();
-		if (currentUrl !== previousUrl) {
-			sawUrlChange = true;
-			previousUrl = currentUrl;
-			lastActivityAt = now;
-		}
-
-		// Single combined evaluate for mutation count + focus descriptor.
-		const state = await readSettleState(p, checkFocus);
-
-		if (state.mutationCount > previousMutationCount) {
-			totalMutationsSeen += state.mutationCount - previousMutationCount;
-			previousMutationCount = state.mutationCount;
-			lastActivityAt = now;
-		}
-
-		if (checkFocus && state.focusDescriptor !== previousFocus) {
-			previousFocus = state.focusDescriptor;
-			lastActivityAt = now;
-		}
-
-		const pendingCritical = getPendingCriticalRequests(p);
-		if (pendingCritical > 0) {
-			lastActivityAt = now;
-			continue;
-		}
-
-		// Zero-mutation short-circuit: after ZERO_MUTATION_THRESHOLD_MS with
-		// no mutations observed at all, reduce the quiet window to settle faster.
-		if (
-			totalMutationsSeen === 0 &&
-			now - startedAt >= ZERO_MUTATION_THRESHOLD_MS &&
-			activeQuietWindowMs !== ZERO_MUTATION_QUIET_MS
-		) {
-			activeQuietWindowMs = ZERO_MUTATION_QUIET_MS;
-		}
-
-		if (now - lastActivityAt >= activeQuietWindowMs) {
-			const usedShortcut = activeQuietWindowMs === ZERO_MUTATION_QUIET_MS && totalMutationsSeen === 0;
-			return {
-				settleMode: "adaptive",
-				settleMs: now - startedAt,
-				settleReason: usedShortcut
-					? "zero_mutation_shortcut"
-					: sawUrlChange
-						? "url_changed_then_quiet"
-						: "dom_quiet",
-				settlePolls: polls,
-			};
-		}
-	}
-
-	return {
-		settleMode: "adaptive",
-		settleMs: Date.now() - startedAt,
-		settleReason: "timeout_fallback",
-		settlePolls: polls,
-	};
-}

package/dist/resources/extensions/browser-tools/state.ts

@@ -1,408 +0,0 @@
-/**
- * browser-tools — shared mutable state
- *
- * All mutable state lives behind accessor functions (get/set) so that
- * jiti-transpiled modules see updates reliably.  ES module live bindings
- * (`export let`) are not guaranteed to work under jiti's CJS shim layer.
- *
- * State is initialized to sensible defaults and can be bulk-reset via
- * `resetAllState()` (called by closeBrowser).
- */
-
-import type { Browser, BrowserContext, Frame, Page } from "playwright";
-import type { ExtensionAPI } from "@gsd/pi-coding-agent";
-import path from "node:path";
-import {
-	createActionTimeline,
-	createBoundedLogPusher,
-	createPageRegistry,
-} from "./core.js";
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-export const ARTIFACT_ROOT = path.resolve(process.cwd(), ".artifacts", "browser");
-export const HAR_FILENAME = "session.har";
-
-// ---------------------------------------------------------------------------
-// Type / interface definitions
-// ---------------------------------------------------------------------------
-
-export interface ConsoleEntry {
-	type: string;
-	text: string;
-	timestamp: number;
-	url: string;
-	pageId: number;
-}
-
-export interface NetworkEntry {
-	method: string;
-	url: string;
-	status: number | null;
-	resourceType: string;
-	timestamp: number;
-	failed: boolean;
-	failureText?: string;
-	responseBody?: string;
-	pageId: number;
-}
-
-export interface DialogEntry {
-	type: string;
-	message: string;
-	timestamp: number;
-	url: string;
-	defaultValue?: string;
-	accepted: boolean;
-	pageId: number;
-}
-
-export interface RefNode {
-	ref: string;
-	tag: string;
-	role: string;
-	name: string;
-	selectorHints: string[];
-	isVisible: boolean;
-	isEnabled: boolean;
-	xpathOrPath: string;
-	href?: string;
-	type?: string;
-	path: number[];
-	contentHash?: string;
-	structuralSignature?: string;
-	nearestHeading?: string;
-	formOwnership?: string;
-}
-
-export interface RefMetadata {
-	url: string;
-	timestamp: number;
-	selectorScope?: string;
-	interactiveOnly: boolean;
-	limit: number;
-	version: number;
-	frameContext?: string;
-	mode?: string;
-}
-
-export interface CompactSelectorState {
-	exists: boolean;
-	visible: boolean;
-	value: string;
-	checked: boolean | null;
-	text: string;
-}
-
-export interface CompactPageState {
-	url: string;
-	title: string;
-	focus: string;
-	headings: string[];
-	bodyText: string;
-	counts: {
-		landmarks: number;
-		buttons: number;
-		links: number;
-		inputs: number;
-	};
-	dialog: {
-		count: number;
-		title: string;
-	};
-	selectorStates: Record<string, CompactSelectorState>;
-}
-
-export interface TraceSessionState {
-	startedAt: number;
-	name: string;
-	title?: string;
-	path?: string;
-}
-
-export interface HarState {
-	enabled: boolean;
-	configuredAtContextCreation: boolean;
-	path: string | null;
-	exportCount: number;
-	lastExportedPath: string | null;
-	lastExportedAt: number | null;
-}
-
-export interface ClickTargetStateSnapshot {
-	exists: boolean;
-	ariaExpanded: string | null;
-	ariaPressed: string | null;
-	ariaSelected: string | null;
-	open: boolean | null;
-}
-
-export interface BrowserVerificationCheck {
-	name: string;
-	passed: boolean;
-	value?: unknown;
-	expected?: unknown;
-}
-
-export interface BrowserVerificationResult {
-	verified: boolean;
-	checks: BrowserVerificationCheck[];
-	verificationSummary: string;
-	retryHint?: string;
-}
-
-export interface AdaptiveSettleOptions {
-	timeoutMs?: number;
-	pollMs?: number;
-	quietWindowMs?: number;
-	checkFocusStability?: boolean;
-}
-
-export interface AdaptiveSettleDetails {
-	settleMode: "adaptive";
-	settleMs: number;
-	settleReason: "dom_quiet" | "url_changed_then_quiet" | "timeout_fallback" | "zero_mutation_shortcut";
-	settlePolls: number;
-}
-
-export interface ParsedRefSpec {
-	key: string;
-	version: number | null;
-	display: string;
-}
-
-export interface BrowserAssertionCheckInput {
-	kind: string;
-	selector?: string;
-	text?: string;
-	value?: string;
-	checked?: boolean;
-	sinceActionId?: number;
-}
-
-// ---------------------------------------------------------------------------
-// Mutable state variables — accessed only via get/set functions
-// ---------------------------------------------------------------------------
-
-// 1. browser
-let _browser: Browser | null = null;
-export function getBrowser(): Browser | null { return _browser; }
-export function setBrowser(b: Browser | null): void { _browser = b; }
-
-// 2. context
-let _context: BrowserContext | null = null;
-export function getContext(): BrowserContext | null { return _context; }
-export function setContext(c: BrowserContext | null): void { _context = c; }
-
-// 3. pageRegistry (object with internal state — export the instance directly + getter)
-export const pageRegistry = createPageRegistry();
-export function getPageRegistry() { return pageRegistry; }
-
-// 4. activeFrame
-let _activeFrame: Frame | null = null;
-export function getActiveFrame(): Frame | null { return _activeFrame; }
-export function setActiveFrame(f: Frame | null): void { _activeFrame = f; }
-
-// 5. logPusher (bounded log push function — stateless utility, export directly)
-export const logPusher = createBoundedLogPusher(1000);
-
-// 6. consoleLogs
-let _consoleLogs: ConsoleEntry[] = [];
-export function getConsoleLogs(): ConsoleEntry[] { return _consoleLogs; }
-export function setConsoleLogs(logs: ConsoleEntry[]): void { _consoleLogs = logs; }
-
-// 7. networkLogs
-let _networkLogs: NetworkEntry[] = [];
-export function getNetworkLogs(): NetworkEntry[] { return _networkLogs; }
-export function setNetworkLogs(logs: NetworkEntry[]): void { _networkLogs = logs; }
-
-// 8. dialogLogs
-let _dialogLogs: DialogEntry[] = [];
-export function getDialogLogs(): DialogEntry[] { return _dialogLogs; }
-export function setDialogLogs(logs: DialogEntry[]): void { _dialogLogs = logs; }
-
-// 9. pendingCriticalRequestsByPage (WeakMap — can't be reassigned, just cleared by replacing)
-let _pendingCriticalRequestsByPage = new WeakMap<Page, number>();
-export function getPendingCriticalRequestsByPage(): WeakMap<Page, number> { return _pendingCriticalRequestsByPage; }
-export function resetPendingCriticalRequestsByPage(): void { _pendingCriticalRequestsByPage = new WeakMap(); }
-
-// 10. currentRefMap
-let _currentRefMap: Record<string, RefNode> = {};
-export function getCurrentRefMap(): Record<string, RefNode> { return _currentRefMap; }
-export function setCurrentRefMap(m: Record<string, RefNode>): void { _currentRefMap = m; }
-
-// 11. refVersion
-let _refVersion = 0;
-export function getRefVersion(): number { return _refVersion; }
-export function setRefVersion(v: number): void { _refVersion = v; }
-
-// 12. refMetadata
-let _refMetadata: RefMetadata | null = null;
-export function getRefMetadata(): RefMetadata | null { return _refMetadata; }
-export function setRefMetadata(m: RefMetadata | null): void { _refMetadata = m; }
-
-// 13. actionTimeline (object with internal state)
-export const actionTimeline = createActionTimeline(60);
-export function getActionTimeline() { return actionTimeline; }
-
-// 14. lastActionBeforeState
-let _lastActionBeforeState: CompactPageState | null = null;
-export function getLastActionBeforeState(): CompactPageState | null { return _lastActionBeforeState; }
-export function setLastActionBeforeState(s: CompactPageState | null): void { _lastActionBeforeState = s; }
-
-// 15. lastActionAfterState
-let _lastActionAfterState: CompactPageState | null = null;
-export function getLastActionAfterState(): CompactPageState | null { return _lastActionAfterState; }
-export function setLastActionAfterState(s: CompactPageState | null): void { _lastActionAfterState = s; }
-
-// 16. sessionStartedAt
-let _sessionStartedAt: number | null = null;
-export function getSessionStartedAt(): number | null { return _sessionStartedAt; }
-export function setSessionStartedAt(t: number | null): void { _sessionStartedAt = t; }
-
-// 17. sessionArtifactDir
-let _sessionArtifactDir: string | null = null;
-export function getSessionArtifactDir(): string | null { return _sessionArtifactDir; }
-export function setSessionArtifactDir(d: string | null): void { _sessionArtifactDir = d; }
-
-// 18a. activeTraceSession
-let _activeTraceSession: TraceSessionState | null = null;
-export function getActiveTraceSession(): TraceSessionState | null { return _activeTraceSession; }
-export function setActiveTraceSession(t: TraceSessionState | null): void { _activeTraceSession = t; }
-
-// 18b. harState
-const DEFAULT_HAR_STATE: HarState = {
-	enabled: false,
-	configuredAtContextCreation: false,
-	path: null,
-	exportCount: 0,
-	lastExportedPath: null,
-	lastExportedAt: null,
-};
-let _harState: HarState = { ...DEFAULT_HAR_STATE };
-export function getHarState(): HarState { return _harState; }
-export function setHarState(h: HarState): void { _harState = h; }
-
-// ---------------------------------------------------------------------------
-// resetAllState — mirrors closeBrowser()'s reset logic
-// ---------------------------------------------------------------------------
-
-export function resetAllState(): void {
-	_browser = null;
-	_context = null;
-	pageRegistry.pages = [];
-	pageRegistry.activePageId = null;
-	pageRegistry.nextId = 1;
-	_activeFrame = null;
-	_consoleLogs = [];
-	_networkLogs = [];
-	_dialogLogs = [];
-	_pendingCriticalRequestsByPage = new WeakMap();
-	_currentRefMap = {};
-	_refVersion = 0;
-	_refMetadata = null;
-	_lastActionBeforeState = null;
-	_lastActionAfterState = null;
-	actionTimeline.entries = [];
-	actionTimeline.nextId = 1;
-	_sessionStartedAt = null;
-	_sessionArtifactDir = null;
-	_activeTraceSession = null;
-	_harState = { ...DEFAULT_HAR_STATE };
-}
-
-// ---------------------------------------------------------------------------
-// ToolDeps — interface that tool registration functions consume
-// ---------------------------------------------------------------------------
-
-/**
- * Bundles the infrastructure functions that tool registration files need.
- * Built once in the index.ts orchestrator and passed to each register* function.
- */
-export interface ToolDeps {
-	// Lifecycle
-	ensureBrowser: () => Promise<{ browser: Browser; context: BrowserContext; page: Page }>;
-	closeBrowser: () => Promise<void>;
-	getActivePage: () => Page;
-	getActiveTarget: () => Page | Frame;
-	getActivePageOrNull: () => Page | null;
-
-	// Page event wiring
-	attachPageListeners: (p: Page, pageId: number) => void;
-
-	// Capture & summary
-	captureCompactPageState: (
-		p: Page,
-		options?: { selectors?: string[]; includeBodyText?: boolean; target?: Page | Frame }
-	) => Promise<CompactPageState>;
-	postActionSummary: (p: Page, target?: Page | Frame) => Promise<string>;
-	formatCompactStateSummary: (state: CompactPageState) => string;
-	constrainScreenshot: (page: Page, buffer: Buffer, mimeType: string, quality: number) => Promise<Buffer>;
-	captureErrorScreenshot: (p: Page | null) => Promise<{ data: string; mimeType: string } | null>;
-	getRecentErrors: (pageUrl: string) => string;
-
-	// Settle
-	settleAfterActionAdaptive: (p: Page, opts?: AdaptiveSettleOptions) => Promise<AdaptiveSettleDetails>;
-	ensureMutationCounter: (p: Page) => Promise<void>;
-
-	// Refs
-	buildRefSnapshot: (
-		target: Page | Frame,
-		options: { selector?: string; interactiveOnly: boolean; limit: number; mode?: string }
-	) => Promise<Array<Omit<RefNode, "ref">>>;
-	resolveRefTarget: (
-		target: Page | Frame,
-		node: RefNode
-	) => Promise<{ ok: true; selector: string } | { ok: false; reason: string }>;
-	parseRef: (input: string) => ParsedRefSpec;
-	formatVersionedRef: (version: number, key: string) => string;
-	staleRefGuidance: (refDisplay: string, reason: string) => string;
-
-	// Action tracking
-	beginTrackedAction: (tool: string, params: unknown, beforeUrl: string) => ReturnType<typeof import("./core.js").beginAction>;
-	finishTrackedAction: (
-		actionId: number,
-		updates: {
-			status: "success" | "error";
-			afterUrl?: string;
-			verificationSummary?: string;
-			warningSummary?: string;
-			diffSummary?: string;
-			changed?: boolean;
-			error?: string;
-			beforeState?: CompactPageState;
-			afterState?: CompactPageState;
-		}
-	) => ReturnType<typeof import("./core.js").finishAction>;
-
-	// Utilities (forwarded from utils.ts)
-	truncateText: (text: string) => string;
-	verificationFromChecks: (checks: BrowserVerificationCheck[], retryHint?: string) => BrowserVerificationResult;
-	verificationLine: (verification: BrowserVerificationResult) => string;
-	collectAssertionState: (
-		p: Page,
-		checks: BrowserAssertionCheckInput[],
-		target?: Page | Frame
-	) => Promise<Record<string, unknown>>;
-	formatAssertionText: (result: ReturnType<typeof import("./core.js").evaluateAssertionChecks>) => string;
-	formatDiffText: (diff: ReturnType<typeof import("./core.js").diffCompactStates>) => string;
-	getUrlHash: (url: string) => string;
-	captureClickTargetState: (target: Page | Frame, selector: string) => Promise<ClickTargetStateSnapshot>;
-	readInputLikeValue: (target: Page | Frame, selector?: string) => Promise<string | null>;
-	firstErrorLine: (err: unknown) => string;
-	captureAccessibilityMarkdown: (selector?: string) => Promise<{ snapshot: string; scope: string; source: string }>;
-	resolveAccessibilityScope: (selector?: string) => Promise<{ selector?: string; scope: string; source: string }>;
-	getLivePagesSnapshot: () => Promise<ReturnType<typeof import("./core.js").registryListPages>>;
-	getSinceTimestamp: (sinceActionId?: number) => number;
-	getConsoleEntriesSince: (sinceActionId?: number) => ConsoleEntry[];
-	getNetworkEntriesSince: (sinceActionId?: number) => NetworkEntry[];
-	writeArtifactFile: (filePath: string, content: string | Uint8Array) => Promise<{ path: string; bytes: number }>;
-	copyArtifactFile: (sourcePath: string, destinationPath: string) => Promise<{ path: string; bytes: number }>;
-	ensureSessionArtifactDir: () => Promise<string>;
-	buildSessionArtifactPath: (filename: string) => string;
-	getSessionArtifactMetadata: () => Record<string, unknown>;
-	sanitizeArtifactName: (value: string, fallback: string) => string;
-	formatArtifactTimestamp: (timestamp: number) => string;
-}