pi-lean-portal 0.1.0

package/tools/browser-console.ts

@@ -0,0 +1,160 @@
+/**
+ * browser-console tool definition.
+ */
+
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "@earendil-works/pi-ai";
+import { Text } from "@earendil-works/pi-tui";
+import * as router from "../core/router.js";
+import { taskId } from "../core/shared/task-id.js";
+
+export const browserConsoleTool = defineTool({
+	name: "browser-console",
+	label: "Browser Console",
+	description:
+		"Execute JavaScript in the current page context and see the result, " +
+		"or read captured console output (log, warn, error, info). " +
+		"Useful for inspecting page state, reading hidden content, or debugging.",
+	parameters: Type.Object({
+		expression: Type.Optional(
+			Type.String({
+				description:
+					"JavaScript expression to evaluate in the page context. If omitted, returns captured console messages.",
+			}),
+		),
+		clear: Type.Optional(
+			Type.Boolean({
+				description:
+					"If true, clear the captured console log (no other action)",
+			}),
+		),
+	}),
+
+	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		const p = params as {
+			expression?: string;
+			clear?: boolean;
+			taskId?: string;
+		};
+		const tid = p?.taskId ?? taskId(ctx);
+
+		if (p?.clear) {
+			await router.clearConsole(tid);
+			return {
+				content: [{ type: "text", text: "Console log cleared." }],
+				details: { cleared: true },
+			};
+		}
+
+		if (p?.expression) {
+			const result = await router.evaluate(tid, p.expression);
+
+			if (!result.success) {
+				return {
+					content: [
+						{
+							type: "text",
+							text: `Evaluation failed: ${result.error ?? "unknown"}`,
+						},
+					],
+					details: { error: true },
+				};
+			}
+
+			let formatted: string;
+			if (typeof result.result === "string") {
+				formatted = result.result;
+			} else if (result.result === undefined || result.result === null) {
+				formatted = String(result.result);
+			} else {
+				try {
+					formatted = JSON.stringify(result.result, null, 2);
+				} catch {
+					formatted = String(result.result);
+				}
+			}
+			const TRUNCATE_LIMIT = 10_000;
+			if (formatted.length > TRUNCATE_LIMIT) {
+				formatted =
+					formatted.slice(0, TRUNCATE_LIMIT) +
+					`\n… (truncated, ${formatted.length - TRUNCATE_LIMIT} more chars)`;
+			}
+			return {
+				content: [{ type: "text", text: formatted || "undefined" }],
+				details: { result: result.result },
+			};
+		}
+
+		// No expression, no clear — read console messages
+		const consoleResult = await router.getConsoleMessages(tid);
+		if (!consoleResult.success) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Failed to read console: ${consoleResult.error}`,
+					},
+				],
+				details: { error: true },
+			};
+		}
+
+		if (consoleResult.messages.length === 0) {
+			return {
+				content: [{ type: "text", text: "No console messages captured." }],
+				details: { count: 0 },
+			};
+		}
+
+		const formatted = consoleResult.messages
+			.map((m) => `[${m.type}] ${m.text}`)
+			.join("\n");
+		return {
+			content: [{ type: "text", text: formatted }],
+			details: {
+				count: consoleResult.messages.length,
+				messages: consoleResult.messages,
+			},
+		};
+	},
+
+	renderCall(args, theme, _context) {
+		if (args.clear)
+			return new Text(
+				theme.fg("toolTitle", theme.bold("browser-console clear")),
+				0,
+				0,
+			);
+		if (args.expression) {
+			return new Text(
+				`${theme.fg("toolTitle", theme.bold("browser-console"))} ${theme.fg("dim", args.expression.slice(0, 60))}`,
+				0,
+				0,
+			);
+		}
+		return new Text(
+			theme.fg("toolTitle", theme.bold("browser-console read")),
+			0,
+			0,
+		);
+	},
+
+	renderResult(result, _options, theme, _context) {
+		const d = result.details as Record<string, unknown> | undefined;
+		if (d?.error)
+			return new Text(theme.fg("error", "Console operation failed"), 0, 0);
+		if (d?.cleared) return new Text(theme.fg("dim", "Console cleared"), 0, 0);
+		if (d?.result !== undefined)
+			return new Text(
+				theme.fg(
+					"dim",
+					`JS → ${JSON.stringify(d.result)?.slice(0, 80) || "ok"}`,
+				),
+				0,
+				0,
+			);
+		if (d?.count !== undefined)
+			return new Text(theme.fg("dim", `📋 ${d.count} console messages`), 0, 0);
+		return new Text(theme.fg("dim", "Console ok"), 0, 0);
+	},
+});

package/tools/browser-inspect.ts

@@ -0,0 +1,136 @@
+/**
+ * browser-inspect tool definition.
+ */
+
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "@earendil-works/pi-ai";
+import { Text } from "@earendil-works/pi-tui";
+import * as router from "../core/router.js";
+import { taskId } from "../core/shared/task-id.js";
+
+export const browserInspectTool = defineTool({
+	name: "browser-inspect",
+	label: "Inspect Page",
+	description:
+		"Query the current page for specific elements or extract readable " +
+		"text content. Use for targeted discovery instead of full snapshots.",
+	promptSnippet:
+		"Query the current page for elements or text content with @e ref annotations",
+	promptGuidelines: [
+		"Use browser-inspect role=... name=... to find a specific element without loading a full snapshot",
+		"Use browser-inspect text=true to read page content (article, form, etc.) with correlated @e refs",
+		"Use browser-inspect subtree=... to scope queries inside dialogs, menus, or navigation regions",
+		"After clicking or scrolling, take a fresh browser-snapshot before trusting @e refs from browser-inspect",
+		"Do NOT use browser-inspect as a replacement for browser-navigate — it requires an existing session",
+		"When browser-inspect returns multiple @e refs for the same name, disambiguate by reading the cached full snapshot",
+	],
+	parameters: Type.Object({
+		role: Type.Optional(
+			Type.String({
+				description:
+					'Filter by ARIA role. Comma-separated for multiple. E.g. "link,button"',
+			}),
+		),
+		name: Type.Optional(
+			Type.String({
+				description:
+					"Filter by accessible name (case-insensitive substring match)",
+			}),
+		),
+		ref: Type.Optional(
+			Type.String({
+				description:
+					"Look up a specific @e ref (e.g. 'e5'). When combined with text=true, scopes DOM walker to that element's subtree.",
+			}),
+		),
+		subtree: Type.Optional(
+			Type.String({
+				description:
+					"Scope to elements inside a container role. E.g. 'dialog', 'navigation'",
+			}),
+		),
+		text: Type.Optional(
+			Type.Boolean({
+				description:
+					"Include text content from DOM walker with @e ref annotations. Default: false",
+			}),
+		),
+		maxChars: Type.Optional(
+			Type.Number({
+				description:
+					'Max output characters. 0 = no limit. Default: ~2500 when omitted. Truncated output shows "… X more chars (use maxChars=0 for full content)"',
+				minimum: 0,
+			}),
+		),
+		query: Type.Optional(
+			Type.String({
+				description:
+					"Filter extracted text to only include content matching this case-insensitive keyword. " +
+					"Useful for finding specific topics on large pages without retrieving all text. " +
+					"Only active when text=true.",
+			}),
+		),
+	}),
+
+	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		const p = params as Record<string, unknown>;
+		const tid = (p?.taskId as string | undefined) ?? taskId(ctx);
+
+		const result = await router.browserInspect(tid, {
+			...(p?.role !== undefined ? { role: p.role as string } : {}),
+			...(p?.name !== undefined ? { name: p.name as string } : {}),
+			...(p?.ref !== undefined ? { ref: p.ref as string } : {}),
+			...(p?.subtree !== undefined ? { subtree: p.subtree as string } : {}),
+			...(p?.text !== undefined ? { text: Boolean(p.text) } : {}),
+			...(p?.maxChars !== undefined ? { maxChars: p.maxChars as number } : {}),
+			...(p?.query !== undefined ? { query: p.query as string } : {}),
+		});
+
+		if (!result.success) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: result.error ?? "browser-inspect failed",
+					},
+				],
+				details: { error: true },
+			};
+		}
+
+		return {
+			content: [{ type: "text", text: result.content }],
+			details: {
+				stalenessWarning: result.staleCacheWarning,
+			},
+		};
+	},
+
+	renderCall(args, theme, _context) {
+		const parts = [theme.fg("toolTitle", theme.bold("browser-inspect"))];
+		if (args.text) parts.push(theme.fg("accent", "📖 text"));
+		if (args.role) parts.push(theme.fg("dim", `role=${args.role}`));
+		if (args.name) parts.push(theme.fg("dim", `name="${args.name}"`));
+		if (args.ref) parts.push(theme.fg("dim", `@${args.ref}`));
+		if (args.subtree) parts.push(theme.fg("dim", `subtree=${args.subtree}`));
+		if (args.query) parts.push(theme.fg("accent", `query="${args.query}"`));
+		return new Text(parts.join(" "), 0, 0);
+	},
+
+	renderResult(result, _options, theme, _context) {
+		const d = result.details as Record<string, unknown> | undefined;
+		if (d?.error) return new Text(theme.fg("error", "Inspect failed"), 0, 0);
+		const content = (result.content?.[0] as any)?.text ?? "";
+		const staleness = d?.stalenessWarning
+			? ` ${theme.fg("warning", "(stale)")}`
+			: "";
+		const preview = content.replace(/\n{3,}/g, "\n\n").slice(0, 100);
+		let text = theme.fg("accent", `🔍 ${content.length} chars`) + staleness;
+		if (preview) {
+			text += `\n${theme.fg("dim", preview)}`;
+			if (content.length > 100)
+				text += `\n${theme.fg("muted", `… ${content.length - 100} more chars`)}`;
+		}
+		return new Text(text, 0, 0);
+	},
+});

package/tools/browser-navigate.ts

@@ -0,0 +1,254 @@
+/**
+ * browser-navigate tool definition.
+ */
+
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "@earendil-works/pi-ai";
+import { Text } from "@earendil-works/pi-tui";
+import * as router from "../core/router.js";
+import { resolveApplicableGuides, formatGuideFooter } from "../core/guides.js";
+import type { ApplicableGuide } from "../core/guides.js";
+import { getConversationDefaultProfile } from "../browser-toggle.js";
+import { sessionManager } from "../core/shared/session-manager.js";
+import { removeSnapshotFiles } from "../core/shared/snapshot-cache.js";
+import { taskId } from "../core/shared/task-id.js";
+import { updateFooterStatus, profileLine } from "./utils.js";
+
+export const browserNavigateTool = defineTool({
+	name: "browser-navigate",
+	label: "Browse Web",
+	description:
+		"Navigate a browser to a URL and return the page as an accessibility tree with @e1, @e2 element references. " +
+		"Uses the configured browser plugin (default: Chromium). For stateless HTTP fetches without interactive elements, use web-fetch instead.",
+	promptSnippet: "Fetch and read web pages in text form",
+	promptGuidelines: [
+		"Use browser-navigate when you need to interact with a web page using @e1/@e2 element references (click, type, scroll, etc.).",
+		"If you just need the page content as Markdown without interactive elements, use web-fetch instead.",
+		"Use @e1, @e2 references from the accessibility tree with browser-click and browser-type to interact with page elements.",
+		"If snapshot or interaction returns 'No active session', the previous navigation was in a different context. Use browser-navigate first to establish a session.",
+		"After auto-launch, @e refs may have changed — a fresh accessibility tree is returned automatically. Use the new refs for interaction.",
+		"If the snapshot is truncated, use browser-inspect role=... name=... to find specific elements, or read the cached snapshot file. Avoid browser-snapshot full=true unless you need the entire tree.",
+		"When a 📖 guide footer appears in a browser-navigate result, call web-guide for each listed guide before interacting with the page (once each per conversation — skip guides you've already reviewed).",
+	],
+	parameters: Type.Object({
+		url: Type.String({ description: "The URL to navigate to" }),
+		strategy: Type.Optional(
+			Type.String({
+				description:
+					'Backend strategy: "auto" (default) uses the first available plugin; ' +
+					'specify a registered plugin name (e.g. "chromium", "firefox", "chromium-py") to use that backend. ' +
+					"For stateless HTTP fetches, use web-fetch instead.",
+			}),
+		),
+		timeout: Type.Optional(
+			Type.Number({
+				description: "Timeout in seconds (default: 30, max: 120)",
+				minimum: 1,
+				maximum: 120,
+			}),
+		),
+		profile: Type.Optional(
+			Type.Union(
+				[Type.Literal("none"), Type.Literal("session"), Type.String()],
+				{
+					description:
+						"Profile mode: 'session' (default, persist for this conversation), " +
+						"'none' (clean slate), or a named profile (e.g. 'shopping', 'work'). " +
+						"Named profiles share cookies across subagents like browser tabs.",
+				},
+			),
+		),
+	}),
+
+	async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+		const {
+			url,
+			strategy = "auto",
+			timeout = 30,
+			profile,
+		} = params as {
+			url: string;
+			strategy?: string;
+			timeout?: number;
+			profile?: string;
+		};
+		const tid = taskId(ctx);
+		const piSessionId = ctx?.sessionManager?.getSessionId?.();
+
+		signal?.addEventListener(
+			"abort",
+			() => {
+				sessionManager.removeSession(tid);
+				removeSnapshotFiles(tid);
+				updateFooterStatus(ctx);
+			},
+			{ once: true },
+		);
+
+		const navOptions: router.NavigateOptions = {
+			strategy,
+			timeout,
+			taskId: tid,
+		};
+		if (piSessionId) navOptions.piSessionId = piSessionId;
+		if (signal) navOptions.signal = signal;
+		// Profile resolution: explicit param > conversation default > config file default
+		if (profile) {
+			// Explicit user parameter
+			navOptions.profile = profile as "none" | "session" | string;
+		} else {
+			// Conversation-scoped default (set via /web profile <name>)
+			const convDefault = getConversationDefaultProfile();
+			if (convDefault) {
+				navOptions.profile = convDefault as "none" | "session" | string;
+			}
+			// else: router falls back to browserConfig.defaultProfile
+		}
+
+		const result = await router.navigate(url, navOptions);
+
+		updateFooterStatus(ctx);
+
+		if (!result.success) {
+			// If the browser executable is not installed, notify the user with install instructions.
+			const isInstallError =
+				result.error && result.error.toLowerCase().includes("not installed");
+			if (isInstallError) {
+				ctx?.ui?.notify(
+					"Browser not installed. Run: npx playwright install chromium firefox",
+					"warning",
+				);
+			}
+
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Failed to load page: ${result.error ?? "unknown error"}`,
+					},
+				],
+				details: {
+					error: true,
+					backendUsed: result.backendUsed,
+					url: result.url,
+				},
+			};
+		}
+
+		const contentText = result.snapshot;
+
+		const screenshotLine = await router.captureScreenshotLine(tid);
+
+		// ---- Web Guide footer ----
+		const applicable = resolveApplicableGuides(
+			result.url,
+			result.dialogDetected ?? false,
+			result.botDetectionWarning ?? false,
+		);
+
+		const lines: string[] = [];
+
+		lines.push(
+			`Title: ${result.title || "(no title)"}`,
+			`URL: ${result.url}`,
+			`Backend: ${result.backendUsed}`,
+			result.elementCount !== undefined
+				? `Interactive elements: ${result.elementCount}`
+				: "",
+			result.profileMode !== undefined ? profileLine(result) : "",
+			result.botDetectionWarning
+				? "⚠ BOT DETECTION WARNING: This page appears to be protected by " +
+						"anti-automation. The content below may be incomplete or show " +
+						"a challenge page instead of the actual content."
+				: "",
+			screenshotLine,
+			"",
+			contentText,
+		);
+
+		// Append guide footer after page content (only when guides apply)
+		const guideFooter = formatGuideFooter(applicable);
+		if (guideFooter) {
+			lines.push("", guideFooter);
+		}
+
+		return {
+			content: [{ type: "text", text: lines.filter(Boolean).join("\n") }],
+			details: {
+				title: result.title,
+				url: result.url,
+				backendUsed: result.backendUsed,
+				elementCount: result.elementCount,
+				profileMode: result.profileMode,
+				profileName: result.profileName,
+				...(applicable.length > 0 ? { guides: applicable } : {}),
+			},
+		};
+	},
+
+	renderCall(args, theme, _context) {
+		const parts: string[] = [
+			theme.fg("toolTitle", theme.bold("browser-navigate ")),
+		];
+		parts.push(theme.fg("accent", `"${args.url}"`));
+		if (args.strategy && args.strategy !== "auto")
+			parts.push(theme.fg("dim", `via ${args.strategy}`));
+		return new Text(parts.join(" "), 0, 0);
+	},
+
+	renderResult(result, { expanded, isPartial }, theme, _context) {
+		if (isPartial) return new Text(theme.fg("warning", "Navigating…"), 0, 0);
+		const d = result.details as Record<string, unknown> | undefined;
+		if (d?.error)
+			return new Text(
+				theme.fg(
+					"error",
+					`Failed: ${(result.content?.[0] as any)?.text ?? "?"}`,
+				),
+				0,
+				0,
+			);
+
+		const title = (d?.title as string) || "(no title)";
+		const backend = (d?.backendUsed as string) || "?";
+		const url = (d?.url as string) || "";
+		const ec = d?.elementCount as number | undefined;
+		const pm = d?.profileMode as string | undefined;
+		const pn = d?.profileName as string | undefined;
+		let text = theme.fg("accent", theme.bold(`🌐 ${title}`));
+		text += `\n${theme.fg("dim", url)}`;
+		text += `\n${theme.fg("muted", `via ${backend}`)}`;
+		if (ec !== undefined) text += ` · ${ec} elements`;
+		if (pn) {
+			const modeTag = pm === "session" ? "📋" : "👤";
+			text += ` ${theme.fg("dim", `${modeTag} ${pn}`)}`;
+		} else if (pm === "restored") {
+			text += ` ${theme.fg("accent", "↻ restored")}`;
+		}
+
+		// Guide badge line (dedicated line below via status)
+		const guides = d?.guides as ApplicableGuide[] | undefined;
+		if (guides && guides.length > 0) {
+			const chips: string[] = [];
+			for (const g of guides) {
+				if (g.category === "site") {
+					chips.push(`${g.icon} guide avail: ${g.shortName}`);
+				} else {
+					chips.push(`${g.icon} ${g.shortName}`);
+				}
+			}
+			text += `\n${theme.fg("muted", chips.join("  "))}`;
+		}
+
+		const content = (result.content?.[0] as any)?.text ?? "";
+		if (expanded) {
+			const preview = content.replace(/\n{3,}/g, "\n\n").slice(0, 500);
+			text += `\n\n${theme.fg("dim", preview)}`;
+			if (content.length > 500)
+				text += `\n${theme.fg("muted", `… ${content.length - 500} more chars`)}`;
+		} else {
+			text += `\n${theme.fg("muted", `${content.length} chars (expand)`)}`;
+		}
+		return new Text(text, 0, 0);
+	},
+});

package/tools/browser-press.ts

@@ -0,0 +1,80 @@
+/**
+ * browser-press tool definition.
+ */
+
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "@earendil-works/pi-ai";
+import { Text } from "@earendil-works/pi-tui";
+import * as router from "../core/router.js";
+import { executeInteractionTool } from "./utils.js";
+
+export const browserPressTool = defineTool({
+	name: "browser-press",
+	label: "Press Key",
+	description:
+		'Press a keyboard key (e.g., "Enter", "Tab", "Escape", "ArrowDown", "ArrowUp"). ' +
+		"Useful for submitting forms, dismissing dialogs, or navigating dropdowns.",
+	parameters: Type.Object({
+		key: Type.String({
+			description:
+				"Key to press (e.g., 'Enter', 'Tab', 'Escape', 'ArrowDown', 'ArrowUp')",
+		}),
+	}),
+
+	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		const { key } = params as { key: string };
+		return executeInteractionTool(
+			ctx,
+			"Press",
+			(tid) => router.press(tid, key),
+			(result) => ({
+				message: [
+					`Pressed "${key}"`,
+					result.newUrl ? `URL: ${result.newUrl}` : "",
+					result.newTitle ? `Title: ${result.newTitle}` : "",
+				]
+					.filter(Boolean)
+					.join("\n"),
+				details: {
+					key,
+					newUrl: result.newUrl,
+					newTitle: result.newTitle,
+					elementCount: result.elementCount,
+				},
+			}),
+		);
+	},
+
+	renderCall(args, theme, _context) {
+		return new Text(
+			`${theme.fg("toolTitle", theme.bold("browser-press"))} ${theme.fg("accent", args.key)}`,
+			0,
+			0,
+		);
+	},
+
+	renderResult(result, _options, theme, _context) {
+		const d = result.details as Record<string, unknown> | undefined;
+		if (d?.error) return new Text(theme.fg("error", "Press failed"), 0, 0);
+		const ec = d?.elementCount as number | undefined;
+		const nu = d?.newUrl as string | undefined;
+		if (nu) {
+			return new Text(
+				theme.fg(
+					"success",
+					`✅ → ${nu}${ec !== undefined ? ` · ${ec} elements` : ""}`,
+				),
+				0,
+				0,
+			);
+		}
+		return new Text(
+			theme.fg(
+				"dim",
+				`⌨ ${d?.key || ""}${ec !== undefined ? ` · ${ec} elements` : ""}`,
+			),
+			0,
+			0,
+		);
+	},
+});

package/tools/browser-scroll.ts

@@ -0,0 +1,56 @@
+/**
+ * browser-scroll tool definition.
+ */
+
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type, StringEnum } from "@earendil-works/pi-ai";
+import { Text } from "@earendil-works/pi-tui";
+import * as router from "../core/router.js";
+import { executeInteractionTool } from "./utils.js";
+
+export const browserScrollTool = defineTool({
+	name: "browser-scroll",
+	label: "Scroll Page",
+	description:
+		"Scroll the page up or down by approximately one viewport height.",
+	parameters: Type.Object({
+		direction: StringEnum(["up", "down"] as const, {
+			description: "Scroll direction",
+		}),
+	}),
+
+	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		const { direction } = params as { direction: "up" | "down" };
+		return executeInteractionTool(
+			ctx,
+			"Scroll",
+			(tid) => router.scroll(tid, direction),
+			(result) => ({
+				message: `Scrolled ${direction}`,
+				details: { direction, elementCount: result.elementCount },
+			}),
+		);
+	},
+
+	renderCall(args, theme, _context) {
+		return new Text(
+			`${theme.fg("toolTitle", theme.bold("browser-scroll"))} ${theme.fg("dim", args.direction)}`,
+			0,
+			0,
+		);
+	},
+
+	renderResult(result, _options, theme, _context) {
+		const d = result.details as Record<string, unknown> | undefined;
+		if (d?.error) return new Text(theme.fg("error", "Scroll failed"), 0, 0);
+		const ec = d?.elementCount as number | undefined;
+		return new Text(
+			theme.fg(
+				"dim",
+				`↕ ${d?.direction || "?"}${ec !== undefined ? ` · ${ec} elements` : ""}`,
+			),
+			0,
+			0,
+		);
+	},
+});