pi-lean-portal 0.1.0

package/tools/browser-snapshot.ts

@@ -0,0 +1,90 @@
+/**
+ * browser-snapshot 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";
+import { updateFooterStatus } from "./utils.js";
+
+export const browserSnapshotTool = defineTool({
+	name: "browser-snapshot",
+	label: "Page Snapshot",
+	description:
+		"Get the current page's accessibility tree with @e1, @e2 element references. " +
+		"Also captures a screenshot to a temp file (see output for path). " +
+		"Use after browser-navigate to refresh the element list, or after page changes (click, scroll) to see the updated state.",
+	parameters: Type.Object({
+		full: Type.Optional(
+			Type.Boolean({
+				description:
+					"If true, return complete tree instead of compact view (default: false)",
+			}),
+		),
+	}),
+
+	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		const p = params as { full?: boolean; taskId?: string };
+		const tid = p?.taskId ?? taskId(ctx);
+		const full = p?.full ?? false;
+		const result = await router.snapshot(tid, full);
+		updateFooterStatus(ctx);
+
+		if (!result.success) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Snapshot failed: ${result.error ?? "unknown"}`,
+					},
+				],
+				details: { error: true },
+			};
+		}
+
+		const screenshotLine = await router.captureScreenshotLine(tid);
+
+		const parts = [screenshotLine, result.snapshot || "(empty page)"];
+
+		return {
+			content: [{ type: "text", text: parts.filter(Boolean).join("\n\n") }],
+			details: { elementCount: result.elementCount, full },
+		};
+	},
+
+	renderCall(args, theme, _context) {
+		const label = args.full ? "full" : "compact";
+		return new Text(
+			`${theme.fg("toolTitle", theme.bold("browser-snapshot"))} ${theme.fg("dim", label)}`,
+			0,
+			0,
+		);
+	},
+
+	renderResult(result, { expanded, isPartial }, theme, _context) {
+		if (isPartial)
+			return new Text(theme.fg("warning", "Taking snapshot…"), 0, 0);
+		const d = result.details as Record<string, unknown> | undefined;
+		if (d?.error) return new Text(theme.fg("error", "Snapshot failed"), 0, 0);
+		const ec = (d?.elementCount as number) ?? 0;
+		const content = (result.content?.[0] as any)?.text ?? "";
+		const isFull = !!(d?.full as boolean);
+		if (expanded) {
+			const preview = content.slice(0, 400);
+			let text = theme.fg("accent", `📋 ${ec} elements`);
+			text += isFull ? "" : theme.fg("dim", " (compact)");
+			text += `\n${theme.fg("dim", preview)}`;
+			if (content.length > 400)
+				text += `\n${theme.fg("muted", `… ${content.length - 400} more chars`)}`;
+			return new Text(text, 0, 0);
+		}
+		const label = isFull ? " (full)" : " (compact)";
+		return new Text(
+			theme.fg("accent", `📋 ${ec} elements${label} (expand)`),
+			0,
+			0,
+		);
+	},
+});

package/tools/browser-type.ts

@@ -0,0 +1,60 @@
+/**
+ * browser-type 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 browserTypeTool = defineTool({
+	name: "browser-type",
+	label: "Type Text",
+	description:
+		"Type text into an input element identified by its @e reference ID. " +
+		"Clears existing content before typing. Use after browser-navigate or browser-snapshot.",
+	parameters: Type.Object({
+		ref: Type.String({
+			description:
+				"Element reference like @e5 (must be a textbox, searchbox, or combobox)",
+		}),
+		text: Type.String({ description: "Text to type into the element" }),
+	}),
+
+	async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+		const { ref, text } = params as { ref: string; text: string };
+		return executeInteractionTool(
+			ctx,
+			"Type",
+			(tid) => router.type(tid, ref, text),
+			(result) => ({
+				message: `Typed "${text}" into ${ref}`,
+				details: { typed: true, ref, text, elementCount: result.elementCount },
+			}),
+		);
+	},
+
+	renderCall(args, theme, _context) {
+		return new Text(
+			`${theme.fg("toolTitle", theme.bold("browser-type"))} ${theme.fg("accent", args.ref)} "${args.text}"`,
+			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", `Type failed: ${d.error}`), 0, 0);
+		const ec = d?.elementCount as number | undefined;
+		return new Text(
+			theme.fg(
+				"success",
+				`📝 typed "${d?.text || "?"}"${ec !== undefined ? ` · ${ec} elements` : ""}`,
+			),
+			0,
+			0,
+		);
+	},
+});

package/tools/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Tool definitions barrel — exports all 12 tool definitions for registration.
+ *
+ * Each tool is defined in its own file under tools/ for maintainability.
+ * This barrel collects them for import by index.ts.
+ */
+
+export { browserNavigateTool } from "./browser-navigate.js";
+export { browserSnapshotTool } from "./browser-snapshot.js";
+export { browserClickTool } from "./browser-click.js";
+export { browserTypeTool } from "./browser-type.js";
+export { browserScrollTool } from "./browser-scroll.js";
+export { browserBackTool } from "./browser-back.js";
+export { browserPressTool } from "./browser-press.js";
+export { browserConsoleTool } from "./browser-console.js";
+export { browserInspectTool } from "./browser-inspect.js";
+export { webFetchTool } from "./web-fetch.js";
+export { webGuideTool } from "./web-guide.js";
+export { webLearnTool } from "./web-learn.js";

package/tools/utils.ts

@@ -0,0 +1,157 @@
+/**
+ * Shared helpers for the pi-lean-portal tool definitions.
+ *
+ * Extracted from index.ts to avoid duplication across ~14 tool files.
+ * Includes taskId resolution, status bar updates, and profile line formatting.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { getToggleState, getLearnState } from "../browser-toggle.js";
+import { sessionManager } from "../core/shared/session-manager.js";
+import { taskId } from "../core/shared/task-id.js";
+
+// ─── Status bar ─────────────────────────────────────────────────
+
+/**
+ * Retained reference to the most recent extension context for use by
+ * the browser.profile event listener (which fires asynchronously from
+ * tool execution contexts). Updated on session_start and cleared on
+ * session_shutdown.
+ */
+let _lastCtx: {
+	ui: {
+		setStatus: (key: string, label: string) => void;
+		theme: { fg: (c: string, t: string) => string };
+	};
+} | null = null;
+
+/**
+ * Update the TUI status bar with the current browser state.
+ */
+export function updateFooterStatus(ctx: {
+	ui: {
+		setStatus: (key: string, label: string) => void;
+		theme: { fg: (c: string, t: string) => string };
+	};
+}): void {
+	_lastCtx = ctx;
+	const toggleState = getToggleState();
+	if (toggleState === false) {
+		ctx.ui.setStatus("browser", "○ web off");
+		return;
+	}
+	const body = sessionManager.getStatus();
+	const learn = getLearnState();
+	const dot = ctx.ui.theme.fg(learn ? "success" : "accent", "●");
+	ctx.ui.setStatus("browser", `${dot} ${body}`);
+}
+
+/** @internal — used by index.ts's profile event listener */
+export function getLastCtx(): typeof _lastCtx {
+	return _lastCtx;
+}
+
+/** @internal — set by index.ts on startup/shutdown */
+export function setLastCtx(ctx: typeof _lastCtx): void {
+	_lastCtx = ctx;
+}
+
+// ─── Profile line formatting ────────────────────────────────────
+
+/**
+ * Format the profile line for browser-navigate output.
+ *
+ * Examples:
+ *   Profile: none
+ *   Profile: session (this conversation)
+ *   Profile: work (shared)
+ */
+export function profileLine(result: {
+	profileMode?: string;
+	profileName?: string;
+}): string {
+	const mode = result.profileMode;
+	if (mode === "none") {
+		return "Profile: none";
+	}
+	if (mode === "session") {
+		return "Profile: session (this conversation)";
+	}
+	// Named profile
+	return `Profile: ${result.profileName ?? "unnamed"} (shared)`;
+}
+
+/**
+ * Execute an interaction tool with standard boilerplate handling.
+ *
+ * Handles:
+ * - taskId resolution from context
+ * - Footer status update
+ * - Error formatting with consistent pattern
+ * - Snapshot and elementCount appending
+ *
+ * Each tool provides its router call and a formatSuccess callback that
+ * returns the success message and details object.
+ *
+ * @param ctx - Extension tool execution context
+ * @param actionName - Human-readable action name (e.g. "Click", "Type")
+ * @param action - Async function that performs the router call with a resolved taskId
+ * @param formatSuccess - Callback to produce the success message and details from the result
+ */
+export async function executeInteractionTool<
+	T extends {
+		success: boolean;
+		error?: string;
+		snapshot?: string;
+		elementCount?: number;
+	},
+>(
+	ctx: {
+		ui: {
+			setStatus: (key: string, label: string) => void;
+			theme: { fg: (c: string, t: string) => string };
+		};
+		sessionManager?: { getSessionId?(): string };
+	},
+	actionName: string,
+	action: (tid: string) => Promise<T>,
+	formatSuccess: (result: T) => {
+		message: string;
+		details: Record<string, unknown>;
+	},
+): Promise<{
+	content: Array<{ type: "text"; text: string }>;
+	details: Record<string, unknown>;
+}> {
+	const tid = taskId(ctx);
+	const result = await action(tid);
+	updateFooterStatus(ctx);
+
+	if (!result.success) {
+		return {
+			content: [
+				{
+					type: "text",
+					text: `${actionName} failed: ${result.error ?? "unknown"}`,
+				},
+			],
+			details: { error: true },
+		};
+	}
+
+	const { message, details } = formatSuccess(result);
+	let content = message;
+	if (result.snapshot) {
+		content += `\n\n${result.snapshot}`;
+	}
+	if (result.elementCount !== undefined) {
+		content += `\n\nInteractive elements: ${result.elementCount}`;
+	}
+
+	return {
+		content: [{ type: "text", text: content }],
+		details,
+	};
+}
+
+export type { ExtensionAPI };

package/tools/web-fetch.ts

@@ -0,0 +1,147 @@
+/**
+ * web-fetch 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 { webFetch } from "../core/fetch-backend.js";
+import { taskId } from "../core/shared/task-id.js";
+
+export const webFetchTool = defineTool({
+	name: "web-fetch",
+	label: "Web Fetch",
+	description:
+		"Perform a stateless HTTP fetch of a URL and return its content as Markdown. " +
+		"Auto-detects JS-only shells and bot challenge pages. " +
+		"For interactive browsing with @e1/@e2 element references, use browser-navigate instead.",
+	promptSnippet: "Fetch a URL via stateless HTTP and get Markdown content",
+	promptGuidelines: [
+		"Use web-fetch for quick, stateless page retrieval when you don't need JavaScript or interactive elements.",
+		"The tool returns page content as Markdown, truncated to ~4K chars inline.",
+		"If the result mentions a temp file with full content, use the read tool with offset/limit to access specific sections.",
+		"If the result indicates the page needs JavaScript, switch to browser-navigate (try strategy='chromium' or strategy='firefox').",
+		"If bot detection is triggered, the page may be blocked — try browser-navigate instead.",
+		"This tool does NOT create a browser session — it's a simple HTTP fetch.",
+	],
+	parameters: Type.Object({
+		url: Type.String({ description: "The URL to fetch" }),
+		timeout: Type.Optional(
+			Type.Number({
+				description: "Timeout in seconds (default: 30, max: 120)",
+				minimum: 1,
+				maximum: 120,
+			}),
+		),
+	}),
+
+	async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+		const { url, timeout = 30 } = params as {
+			url: string;
+			timeout?: number;
+		};
+		const tid = taskId(ctx);
+
+		const fetchOptions: {
+			url: string;
+			timeout: number;
+			signal?: AbortSignal;
+			taskId?: string;
+		} = {
+			url,
+			timeout,
+			taskId: tid,
+		};
+		if (signal) fetchOptions.signal = signal;
+
+		const result = await webFetch(fetchOptions);
+
+		if (!result.success) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: `Fetch failed: ${result.error ?? "unknown error"}`,
+					},
+				],
+				details: {
+					error: true,
+					url: result.url,
+					statusCode: result.statusCode,
+				},
+			};
+		}
+
+		const lines = [
+			result.title ? `Title: ${result.title}` : "",
+			`URL: ${result.url}`,
+			`Backend: ${result.backendUsed}`,
+			result.statusCode ? `HTTP ${result.statusCode}` : "",
+			result.needsJavaScript
+				? "⚠ This page appears to need JavaScript for full rendering."
+				: "",
+			result.botDetected
+				? "⚠ Bot detection triggered — the page may be blocking automation. Try browser-navigate with a stealth backend instead if one is configured."
+				: "",
+			"",
+			result.content,
+		];
+
+		return {
+			content: [{ type: "text", text: lines.filter(Boolean).join("\n") }],
+			details: {
+				title: result.title,
+				url: result.url,
+				backendUsed: result.backendUsed,
+				statusCode: result.statusCode,
+				needsJavaScript: result.needsJavaScript,
+				botDetected: result.botDetected,
+				...(result.filePath ? { filePath: result.filePath } : {}),
+				...(result.totalChars ? { totalChars: result.totalChars } : {}),
+			},
+		};
+	},
+
+	renderCall(args, theme, _context) {
+		const parts: string[] = [theme.fg("toolTitle", theme.bold("web-fetch "))];
+		parts.push(theme.fg("accent", `"${args.url}"`));
+		return new Text(parts.join(" "), 0, 0);
+	},
+
+	renderResult(result, { expanded, isPartial }, theme, _context) {
+		if (isPartial) return new Text(theme.fg("warning", "Fetching…"), 0, 0);
+		const d = result.details as Record<string, unknown> | undefined;
+		if (d?.error)
+			return new Text(
+				theme.fg(
+					"error",
+					`Fetch failed: ${(result.content?.[0] as any)?.text ?? "?"}`,
+				),
+				0,
+				0,
+			);
+
+		const title = (d?.title as string) || "(no title)";
+		const url = (d?.url as string) || "";
+		const statusCode = d?.statusCode as number | undefined;
+		const needsJS = d?.needsJavaScript as boolean | undefined;
+		const botDetected = d?.botDetected as boolean | undefined;
+
+		let text = theme.fg("accent", theme.bold(`📡 ${title}`));
+		text += `\n${theme.fg("dim", url)}`;
+		if (statusCode) text += ` · HTTP ${statusCode}`;
+		if (needsJS) text += ` ${theme.fg("warning", "⚠ needs JS")}`;
+		if (botDetected) text += ` ${theme.fg("warning", "⚠ bot detected")}`;
+
+		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/web-guide.ts

@@ -0,0 +1,55 @@
+/**
+ * web-guide tool definition.
+ */
+
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "@earendil-works/pi-ai";
+import type { Guide } from "../core/guides.js";
+import { formatGuideList, getGuideContent } from "../core/guides.js";
+
+export const webGuideTool = defineTool({
+	name: "web-guide",
+	label: "Web Navigation Guide",
+	description:
+		"Get navigation guidance for a site or pattern. " +
+		"Call with a guide name (e.g. 'reddit', 'cookie-consent', 'bot-detection') " +
+		"for guidance, or with no parameter to list all available guides.",
+	parameters: Type.Object({
+		guide: Type.Optional(
+			Type.String({
+				description:
+					"Guide name (e.g. 'reddit', 'cookie-consent', 'bot-detection'). Omit to list all guides.",
+			}),
+		),
+	}),
+
+	async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+		const { guide } = params as { guide?: string };
+		if (!guide) {
+			return {
+				content: [{ type: "text", text: formatGuideList() }],
+				details: {},
+			};
+		}
+		const entry: Guide | undefined = getGuideContent()[guide];
+		if (!entry) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: `No guide for '${guide}'. Available: ${Object.keys(getGuideContent()).join(", ")}`,
+					},
+				],
+				details: {},
+			};
+		}
+		const currentDate = new Date().toISOString().slice(0, 10);
+		const text =
+			entry.content +
+			`\n\n_Guide updated: ${entry.updated} · Current date: ${currentDate} · Source: ${entry.source}_`;
+		return {
+			content: [{ type: "text", text }],
+			details: {},
+		};
+	},
+});

package/tools/web-learn.ts

@@ -0,0 +1,128 @@
+/**
+ * web-learn 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 { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { USER_GUIDES_DIR, invalidateGuideContent } from "../core/guides.js";
+
+export const webLearnTool = defineTool({
+	name: "web-learn",
+	label: "Learn Navigation Patterns",
+	description:
+		"Save or update a navigation guide for a site. " +
+		"Creates a new guide file for the given domain, or updates an existing one with new content and date. " +
+		"The guide becomes available immediately via web-guide and appears in the guide footer on future navigations. " +
+		"Requires /web learn to be active.",
+	parameters: Type.Object({
+		domain: Type.String({
+			description: "Primary domain (e.g. 'reddit.com'). Used as the filename.",
+		}),
+		content: Type.String({
+			description:
+				"Markdown guidance content describing the site's navigation patterns, page structure, consent dialogs, and known quirks.",
+		}),
+		domains: Type.Optional(
+			Type.String({
+				description:
+					"Comma-separated additional domains (e.g. 'www.reddit.com, old.reddit.com'). Omit if only the primary domain applies.",
+			}),
+		),
+	}),
+
+	async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+		const { domain, content, domains } = params as {
+			domain: string;
+			content: string;
+			domains?: string;
+		};
+
+		// ── Validation ────────────────────────────────────────────
+		if (!domain.includes(".")) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: `'${domain}' doesn't look like a domain. Use the full domain (e.g. 'reddit.com').`,
+					},
+				],
+				details: {},
+			};
+		}
+
+		if (!content || content.trim().length < 20) {
+			return {
+				content: [
+					{
+						type: "text",
+						text: "Content too short. Provide at least a few sentences of guidance.",
+					},
+				],
+				details: {},
+			};
+		}
+
+		// ── File path ─────────────────────────────────────────────
+		mkdirSync(USER_GUIDES_DIR, { recursive: true });
+		const filename = `${domain}.md`;
+		const filepath = join(USER_GUIDES_DIR, filename);
+
+		// ── Build frontmatter ─────────────────────────────────────
+		const today = new Date().toISOString().slice(0, 10);
+		const allDomains = [domain];
+		if (domains) {
+			for (const d of domains
+				.split(",")
+				.map((s) => s.trim())
+				.filter(Boolean)) {
+				if (!allDomains.includes(d)) allDomains.push(d);
+			}
+		}
+
+		const frontmatter = [
+			"---",
+			"category: site",
+			`domains: ${allDomains.join(", ")}`,
+			`updated: ${today}`,
+			"---",
+		].join("\n");
+
+		const fileContent = frontmatter + "\n\n" + content.trim() + "\n";
+
+		// ── Detect whether this is a create or update ──────────────
+		const isUpdate = existsSync(filepath);
+		writeFileSync(filepath, fileContent, "utf-8");
+
+		// ── Invalidate cache ────────────────────────────────────
+		invalidateGuideContent();
+
+		const verb = isUpdate ? "Updated" : "Created";
+		return {
+			content: [
+				{
+					type: "text",
+					text:
+						`📖 ${verb} guide at ~/.pi/agent/pi-lean-portal/web-guides/${filename}\n` +
+						`  Domains: ${allDomains.join(", ")}\n` +
+						`  Call web-guide guide="${domain}" to view it.\n` +
+						`  A guide badge and footer will appear when navigating to ${allDomains[0]}.`,
+				},
+			],
+			details: {
+				filePath: filepath,
+				domains: allDomains,
+				guideName: domain,
+				isUpdate,
+			},
+		};
+	},
+
+	renderCall(args, theme, _context) {
+		const parts: string[] = [theme.fg("toolTitle", theme.bold("web-learn "))];
+		parts.push(theme.fg("accent", `"${args.domain}"`));
+		return new Text(parts.join(" "), 0, 0);
+	},
+});