@narumitw/pi-firecrawl 0.1.33 → 0.1.35

package/README.md

@@ -15,7 +15,10 @@ Use it to give your AI coding agent reliable web research capabilities for docum
 - Search the web and optionally scrape search result pages.
 - Supports Firecrawl API endpoint overrides.
 - Shows statusline activity only while Firecrawl tools are running.
-- Never logs or displays your Firecrawl API key.
+- Provides a `/firecrawl` menu with configuration help and tool controls.
+- Provides a Plan-mode-style selector for choosing individual Firecrawl tools.
+- Persists the selected Firecrawl tools across Pi restarts.
+- Never logs, displays, or stores your Firecrawl API key.
 
 ## 📦 Install
 
@@ -67,7 +70,43 @@ All tools fail with a clear configuration error when `FIRECRAWL_API_KEY` is miss
 /firecrawl
 ```
 
-Shows whether the extension sees an API key and which Firecrawl API URL it will call.
+Opens a menu with configuration quick start, command usage, tool status, controls for enabling
+or disabling all Firecrawl tools, and a selector for choosing individual tools.
+
+Direct subcommands are also available:
+
+```text
+/firecrawl help
+/firecrawl config
+/firecrawl quickstart
+/firecrawl status
+/firecrawl tools
+/firecrawl toggle
+/firecrawl enable
+/firecrawl disable
+```
+
+- `help` shows command usage.
+- `config` shows API-key presence and API URL without displaying the API key value.
+- `quickstart` is an alias for `config`.
+- `status` shows runtime tool state, persisted selection, settings file path, API-key presence,
+  API URL, and active non-Firecrawl tool count.
+- `tools` opens a Plan-mode-style selector for choosing individual `firecrawl_*` tools.
+- `toggle` is an alias for `tools`.
+- `enable` enables all `firecrawl_*` tools for future turns.
+- `disable` disables all `firecrawl_*` tools for future turns. The slash command remains
+  available.
+
+The selected tool names are saved to:
+
+```text
+${PI_CODING_AGENT_DIR:-~/.pi/agent}/pi-firecrawl-settings.json
+```
+
+When the file is missing or invalid, the extension preserves Pi's current active-tool policy
+instead of enabling tools by itself. A valid saved selection is restored on Pi startup and
+`/reload`. The settings file stores only tool names and a timestamp; it never stores
+`FIRECRAWL_API_KEY`, request headers, or other secrets.
 
 ## 🚀 Examples
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@narumitw/pi-firecrawl",
-	"version": "0.1.33",
+	"version": "0.1.35",
 	"description": "Pi extension that exposes Firecrawl web scraping and crawling tools.",
 	"type": "module",
 	"license": "MIT",

package/src/firecrawl.ts

@@ -1,15 +1,82 @@
-import { defineTool, type ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import {
+	defineTool,
+	type ExtensionAPI,
+	type ExtensionCommandContext,
+} from "@mariozechner/pi-coding-agent";
 import { Type } from "typebox";
 
 const DEFAULT_API_URL = "https://api.firecrawl.dev/v1";
 const STATUS_KEY = "firecrawl";
+const SETTINGS_FILE = join(
+	process.env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent"),
+	"pi-firecrawl-settings.json",
+);
+const FIRECRAWL_TOOL_NAMES = [
+	"firecrawl_scrape",
+	"firecrawl_crawl",
+	"firecrawl_crawl_status",
+	"firecrawl_map",
+	"firecrawl_search",
+] as const;
+const COMMAND_COMPLETIONS = [
+	{ value: "help", label: "Show command usage" },
+	{ value: "config", label: "Show configuration quick start" },
+	{ value: "quickstart", label: "Show configuration quick start" },
+	{ value: "status", label: "Show tool and settings status" },
+	{ value: "tools", label: "Select Firecrawl tools" },
+	{ value: "toggle", label: "Select Firecrawl tools" },
+	{ value: "enable", label: "Enable all Firecrawl tools" },
+	{ value: "disable", label: "Disable all Firecrawl tools" },
+];
+const MENU_OPTIONS = {
+	config: "Configuration quick start",
+	help: "Command usage guide",
+	status: "Show tool status",
+	tools: "Select Firecrawl tools",
+	enable: "Enable all Firecrawl tools",
+	disable: "Disable all Firecrawl tools",
+} as const;
+const TOOL_SELECTOR_DONE = "Done";
+const TOOL_SELECTOR_ENABLE_ALL = "Enable all Firecrawl tools";
+const TOOL_SELECTOR_DISABLE_ALL = "Disable all Firecrawl tools";
 
 const StringArray = Type.Array(Type.String());
 
+type FirecrawlToolName = (typeof FIRECRAWL_TOOL_NAMES)[number];
+type ToolRuntimeStatus = "enabled" | "disabled" | "partial";
+type CommandAction =
+	| "menu"
+	| "help"
+	| "config"
+	| "quickstart"
+	| "status"
+	| "tools"
+	| "enable"
+	| "disable";
+type CommandContext = ExtensionCommandContext;
+type ToolSelectorAction = "enableAll" | "disableAll" | "done";
+type ToolSelectorRow =
+	| { kind: "tool"; toolName: FirecrawlToolName }
+	| { kind: "action"; action: ToolSelectorAction; label: string };
+
 interface FirecrawlState {
 	apiUrl: string;
 }
 
+interface FirecrawlSettings {
+	tools: FirecrawlToolName[];
+	updatedAt: number;
+}
+
+interface ToolStatusSummary {
+	runtimeStatus: ToolRuntimeStatus;
+	activeFirecrawlToolCount: number;
+	activeNonFirecrawlToolCount: number;
+}
+
 interface StatusContext {
 	ui: { setStatus: (key: string, value: string | undefined) => void };
 }
@@ -19,7 +86,7 @@ const state: FirecrawlState = {
 };
 
 const scrapeTool = defineTool({
-	name: "firecrawl_scrape",
+	name: FIRECRAWL_TOOL_NAMES[0],
 	label: "Firecrawl: Scrape",
 	description: "Scrape a single URL through Firecrawl and return requested formats.",
 	promptSnippet: "Scrape a URL through Firecrawl",
@@ -81,7 +148,7 @@ const scrapeTool = defineTool({
 });
 
 const crawlTool = defineTool({
-	name: "firecrawl_crawl",
+	name: FIRECRAWL_TOOL_NAMES[1],
 	label: "Firecrawl: Crawl",
 	description: "Start a Firecrawl crawl job for a website.",
 	promptSnippet: "Start a Firecrawl site crawl job",
@@ -119,7 +186,7 @@ const crawlTool = defineTool({
 });
 
 const crawlStatusTool = defineTool({
-	name: "firecrawl_crawl_status",
+	name: FIRECRAWL_TOOL_NAMES[2],
 	label: "Firecrawl: Crawl Status",
 	description: "Check a Firecrawl crawl job status and retrieve completed crawl data.",
 	promptSnippet: "Check a Firecrawl crawl job status",
@@ -140,7 +207,7 @@ const crawlStatusTool = defineTool({
 });
 
 const mapTool = defineTool({
-	name: "firecrawl_map",
+	name: FIRECRAWL_TOOL_NAMES[3],
 	label: "Firecrawl: Map",
 	description: "Discover URLs for a site through Firecrawl's map endpoint.",
 	promptSnippet: "Map/discover URLs for a site through Firecrawl",
@@ -167,7 +234,7 @@ const mapTool = defineTool({
 });
 
 const searchTool = defineTool({
-	name: "firecrawl_search",
+	name: FIRECRAWL_TOOL_NAMES[4],
 	label: "Firecrawl: Search",
 	description: "Search the web through Firecrawl and optionally scrape search results.",
 	promptSnippet: "Search the web through Firecrawl",
@@ -198,14 +265,23 @@ export default function firecrawl(pi: ExtensionAPI) {
 	pi.registerTool(searchTool);
 
 	pi.registerCommand("firecrawl", {
-		description: "Show Firecrawl extension configuration status",
-		handler: async (_args, ctx) => {
-			ctx.ui.notify(buildStatusMessage(), hasApiKey() ? "info" : "warning");
+		description: "Open Firecrawl help and tool controls",
+		getArgumentCompletions: (prefix) => commandCompletions(prefix),
+		handler: async (args, ctx) => {
+			await handleFirecrawlCommand(pi, args, ctx);
 		},
 	});
 
-	pi.on("session_start", (_event, ctx) => {
+	pi.on("session_start", async (_event, ctx) => {
 		ctx.ui.setStatus(STATUS_KEY, undefined);
+		const settings = await loadSettings();
+		if (settings.kind === "loaded") {
+			applyFirecrawlTools(pi, settings.settings.tools);
+			return;
+		}
+		if (settings.kind === "invalid") {
+			ctx.ui.notify(`Firecrawl settings ignored: ${settings.reason}`, "warning");
+		}
 	});
 
 	pi.on("session_shutdown", (_event, ctx) => {
@@ -213,6 +289,443 @@ export default function firecrawl(pi: ExtensionAPI) {
 	});
 }
 
+async function handleFirecrawlCommand(pi: ExtensionAPI, args: string, ctx: CommandContext) {
+	const command = parseCommand(args);
+	switch (command) {
+		case "menu":
+			await showMenu(pi, ctx);
+			return;
+		case "help":
+			ctx.ui.notify(buildCommandGuide(), "info");
+			return;
+		case "config":
+		case "quickstart":
+			ctx.ui.notify(buildConfigMessage(), hasApiKey() ? "info" : "warning");
+			return;
+		case "status":
+			ctx.ui.notify(await buildStatusMessage(pi), hasApiKey() ? "info" : "warning");
+			return;
+		case "tools":
+			await showToolSelector(pi, ctx);
+			return;
+		case "enable":
+			await updateFirecrawlTools(pi, ctx, allFirecrawlTools(), "enabled all");
+			return;
+		case "disable":
+			await updateFirecrawlTools(pi, ctx, [], "disabled all");
+			return;
+	}
+
+	ctx.ui.notify(`Unknown /firecrawl command: ${args.trim()}\n\n${buildCommandGuide()}`, "warning");
+}
+
+async function showMenu(pi: ExtensionAPI, ctx: CommandContext) {
+	if (!ctx.hasUI) {
+		ctx.ui.notify(`${buildCommandGuide()}\n\n${await buildStatusMessage(pi)}`, hasApiKey() ? "info" : "warning");
+		return;
+	}
+
+	const choice = await ctx.ui.select("Firecrawl", Object.values(MENU_OPTIONS));
+	switch (choice) {
+		case MENU_OPTIONS.config:
+			ctx.ui.notify(buildConfigMessage(), hasApiKey() ? "info" : "warning");
+			return;
+		case MENU_OPTIONS.help:
+			ctx.ui.notify(buildCommandGuide(), "info");
+			return;
+		case MENU_OPTIONS.status:
+			ctx.ui.notify(await buildStatusMessage(pi), hasApiKey() ? "info" : "warning");
+			return;
+		case MENU_OPTIONS.tools:
+			await showToolSelector(pi, ctx);
+			return;
+		case MENU_OPTIONS.enable:
+			await updateFirecrawlTools(pi, ctx, allFirecrawlTools(), "enabled all");
+			return;
+		case MENU_OPTIONS.disable:
+			await updateFirecrawlTools(pi, ctx, [], "disabled all");
+			return;
+	}
+}
+
+function parseCommand(args: string): CommandAction | "unknown" {
+	const command = args.trim().toLowerCase();
+	if (!command) return "menu";
+	if (command === "help") return "help";
+	if (command === "config") return "config";
+	if (command === "quickstart") return "quickstart";
+	if (command === "status") return "status";
+	if (command === "tools" || command === "select" || command === "toggle") return "tools";
+	if (command === "enable" || command === "on") return "enable";
+	if (command === "disable" || command === "off") return "disable";
+	return "unknown";
+}
+
+function commandCompletions(prefix: string) {
+	const normalized = prefix.trim().toLowerCase();
+	if (normalized.includes(" ")) return null;
+
+	const matches = COMMAND_COMPLETIONS.filter((completion) =>
+		completion.value.startsWith(normalized),
+	);
+	return matches.length > 0 ? matches : null;
+}
+
+async function showToolSelector(pi: ExtensionAPI, ctx: CommandContext) {
+	if (!ctx.hasUI) {
+		ctx.ui.notify(
+			`Firecrawl tool selection needs an interactive UI.\n\n${await buildStatusMessage(pi)}`,
+			hasApiKey() ? "info" : "warning",
+		);
+		return;
+	}
+
+	let selectedTools = new Set<FirecrawlToolName>(getActiveFirecrawlTools(pi));
+	let persistQueue = Promise.resolve();
+	const commitSelectedTools = () => {
+		const nextSelectedTools = orderedFirecrawlTools(selectedTools);
+		applyFirecrawlTools(pi, nextSelectedTools);
+		persistQueue = persistQueue.then(() => persistSettings(ctx, nextSelectedTools));
+	};
+
+	const customResult = await ctx.ui.custom<"closed" | undefined>(
+		(tui, theme, keybindings, done) => {
+			const rows = firecrawlToolSelectorRows();
+			let selectedIndex = 0;
+			const moveSelection = (delta: number) => {
+				selectedIndex = (selectedIndex + delta + rows.length) % rows.length;
+			};
+			const activateSelectedRow = () => {
+				const row = rows[selectedIndex];
+				if (!row) return;
+
+				if (row.kind === "tool") {
+					if (selectedTools.has(row.toolName)) selectedTools.delete(row.toolName);
+					else selectedTools.add(row.toolName);
+					commitSelectedTools();
+					return;
+				}
+
+				if (row.action === "enableAll") {
+					selectedTools = new Set(allFirecrawlTools());
+					commitSelectedTools();
+					return;
+				}
+				if (row.action === "disableAll") {
+					selectedTools = new Set();
+					commitSelectedTools();
+					return;
+				}
+
+				done("closed");
+			};
+
+			return {
+				invalidate() {},
+				render() {
+					return [
+						theme.fg("accent", theme.bold(toolSelectorTitle(selectedTools))),
+						"",
+						...rows.map((row, index) => {
+							const label = formatToolSelectorRow(row, selectedTools);
+							if (index === selectedIndex) {
+								return `${theme.fg("accent", "›")} ${theme.fg("accent", label)}`;
+							}
+							return `  ${label}`;
+						}),
+						"",
+						theme.fg("dim", "↑↓ navigate • Enter/Space toggle • Esc close"),
+					];
+				},
+				handleInput(data: string) {
+					if (keybindings.matches(data, "tui.select.up")) {
+						moveSelection(-1);
+						tui.requestRender();
+						return;
+					}
+					if (keybindings.matches(data, "tui.select.down")) {
+						moveSelection(1);
+						tui.requestRender();
+						return;
+					}
+					if (keybindings.matches(data, "tui.select.pageUp")) {
+						selectedIndex = 0;
+						tui.requestRender();
+						return;
+					}
+					if (keybindings.matches(data, "tui.select.pageDown")) {
+						selectedIndex = rows.length - 1;
+						tui.requestRender();
+						return;
+					}
+					if (keybindings.matches(data, "tui.select.confirm") || data === " ") {
+						activateSelectedRow();
+						tui.requestRender();
+						return;
+					}
+					if (keybindings.matches(data, "tui.select.cancel")) {
+						done("closed");
+					}
+				},
+			};
+		},
+	);
+
+	if (customResult !== "closed") {
+		await showDialogToolSelector(pi, ctx);
+		return;
+	}
+
+	await persistQueue;
+	ctx.ui.notify(await buildStatusMessage(pi), hasApiKey() ? "info" : "warning");
+}
+
+async function showDialogToolSelector(pi: ExtensionAPI, ctx: CommandContext) {
+	let selectedTools = new Set<FirecrawlToolName>(getActiveFirecrawlTools(pi));
+	while (true) {
+		const rows = firecrawlToolSelectorRows();
+		const choices = rows.map((row) => formatToolSelectorRow(row, selectedTools));
+		const choice = await ctx.ui.select(toolSelectorTitle(selectedTools), choices);
+		if (!choice) break;
+
+		const row = rows[choices.indexOf(choice)];
+		if (!row) continue;
+		if (row.kind === "action" && row.action === "done") break;
+
+		if (row.kind === "tool") {
+			if (selectedTools.has(row.toolName)) selectedTools.delete(row.toolName);
+			else selectedTools.add(row.toolName);
+		} else if (row.action === "enableAll") {
+			selectedTools = new Set(allFirecrawlTools());
+		} else if (row.action === "disableAll") {
+			selectedTools = new Set();
+		}
+
+		await setSelectedFirecrawlTools(pi, ctx, orderedFirecrawlTools(selectedTools));
+	}
+
+	ctx.ui.notify(await buildStatusMessage(pi), hasApiKey() ? "info" : "warning");
+}
+
+async function updateFirecrawlTools(
+	pi: ExtensionAPI,
+	ctx: CommandContext,
+	selectedTools: readonly FirecrawlToolName[],
+	action: string,
+) {
+	await setSelectedFirecrawlTools(pi, ctx, selectedTools);
+	ctx.ui.notify(
+		`Firecrawl tools ${action}.\n\n${await buildStatusMessage(pi)}`,
+		hasApiKey() ? "info" : "warning",
+	);
+}
+
+async function setSelectedFirecrawlTools(
+	pi: ExtensionAPI,
+	ctx: CommandContext,
+	selectedTools: readonly FirecrawlToolName[],
+) {
+	applyFirecrawlTools(pi, selectedTools);
+	await persistSettings(ctx, selectedTools);
+}
+
+function applyFirecrawlTools(pi: ExtensionAPI, selectedTools: readonly FirecrawlToolName[]) {
+	const activeToolNames = pi.getActiveTools();
+	const firecrawlToolNames = new Set<string>(FIRECRAWL_TOOL_NAMES);
+	const activeNonFirecrawlToolNames = activeToolNames.filter(
+		(name) => !firecrawlToolNames.has(name),
+	);
+	pi.setActiveTools(unique([...activeNonFirecrawlToolNames, ...selectedTools]));
+}
+
+function getToolStatusSummary(pi: ExtensionAPI): ToolStatusSummary {
+	const firecrawlToolNames = new Set<string>(FIRECRAWL_TOOL_NAMES);
+	const activeToolNames = new Set(pi.getActiveTools());
+	const activeFirecrawlToolCount = FIRECRAWL_TOOL_NAMES.filter((name) =>
+		activeToolNames.has(name),
+	).length;
+	const activeNonFirecrawlToolCount = Array.from(activeToolNames).filter(
+		(name) => !firecrawlToolNames.has(name),
+	).length;
+	const runtimeStatus =
+		activeFirecrawlToolCount === FIRECRAWL_TOOL_NAMES.length
+			? "enabled"
+			: activeFirecrawlToolCount === 0
+				? "disabled"
+				: "partial";
+
+	return { runtimeStatus, activeFirecrawlToolCount, activeNonFirecrawlToolCount };
+}
+
+async function buildStatusMessage(pi: ExtensionAPI) {
+	const summary = getToolStatusSummary(pi);
+	const persistedSetting = await persistedSettingLabel();
+	return [
+		`Firecrawl tools: ${formatRuntimeStatus(summary)}`,
+		`Persisted selection: ${persistedSetting}`,
+		`Settings file: ${SETTINGS_FILE}`,
+		`Other active tools preserved: ${summary.activeNonFirecrawlToolCount}`,
+		`API key: ${hasApiKey() ? "present" : "missing"} (FIRECRAWL_API_KEY)`,
+		`API URL: ${state.apiUrl}`,
+	].join("\n");
+}
+
+function buildConfigMessage() {
+	return [
+		"Firecrawl configuration:",
+		`API key: ${hasApiKey() ? "present" : "missing"} (FIRECRAWL_API_KEY)`,
+		`API URL: ${state.apiUrl}`,
+		"Override API URL with FIRECRAWL_API_URL or FIRECRAWL_BASE_URL.",
+		"This extension never logs, displays, or stores your Firecrawl API key.",
+	].join("\n");
+}
+
+function buildCommandGuide() {
+	return [
+		"Firecrawl commands:",
+		"/firecrawl — open this menu",
+		"/firecrawl help — show command usage",
+		"/firecrawl config — show API key presence and API URL",
+		"/firecrawl quickstart — alias for /firecrawl config",
+		"/firecrawl status — show tool and settings status",
+		"/firecrawl tools — select individual Firecrawl tools",
+		"/firecrawl toggle — alias for /firecrawl tools",
+		"/firecrawl enable — enable all Firecrawl tools",
+		"/firecrawl disable — disable all Firecrawl tools",
+	].join("\n");
+}
+
+function toolSelectorTitle(selectedTools: ReadonlySet<FirecrawlToolName>) {
+	return `Firecrawl tools (${selectedTools.size}/${FIRECRAWL_TOOL_NAMES.length}). Non-built-in tools run at user risk.`;
+}
+
+function firecrawlToolSelectorRows(): ToolSelectorRow[] {
+	return [
+		...FIRECRAWL_TOOL_NAMES.map((toolName) => ({ kind: "tool" as const, toolName })),
+		{ kind: "action", action: "enableAll", label: TOOL_SELECTOR_ENABLE_ALL },
+		{ kind: "action", action: "disableAll", label: TOOL_SELECTOR_DISABLE_ALL },
+		{ kind: "action", action: "done", label: TOOL_SELECTOR_DONE },
+	];
+}
+
+function formatToolSelectorRow(
+	row: ToolSelectorRow,
+	selectedTools: ReadonlySet<FirecrawlToolName>,
+) {
+	if (row.kind === "action") return row.label;
+	return `${selectedTools.has(row.toolName) ? "[x]" : "[ ]"} ${row.toolName}`;
+}
+
+function getActiveFirecrawlTools(pi: ExtensionAPI) {
+	const activeToolNames = new Set(pi.getActiveTools());
+	return FIRECRAWL_TOOL_NAMES.filter((toolName) => activeToolNames.has(toolName));
+}
+
+function allFirecrawlTools() {
+	return [...FIRECRAWL_TOOL_NAMES];
+}
+
+function orderedFirecrawlTools(selectedTools: ReadonlySet<FirecrawlToolName>) {
+	return FIRECRAWL_TOOL_NAMES.filter((toolName) => selectedTools.has(toolName));
+}
+
+function formatRuntimeStatus(summary: ToolStatusSummary) {
+	return `${summary.runtimeStatus} (${summary.activeFirecrawlToolCount}/${FIRECRAWL_TOOL_NAMES.length} active)`;
+}
+
+async function persistedSettingLabel() {
+	const settings = await loadSettings();
+	if (settings.kind === "loaded") return formatPersistedSelection(settings.settings.tools);
+	if (settings.kind === "invalid") {
+		return `none; current active-tool policy preserved (invalid settings ignored: ${settings.reason})`;
+	}
+	return "none; current active-tool policy preserved";
+}
+
+function formatPersistedSelection(tools: readonly FirecrawlToolName[]) {
+	if (tools.length === FIRECRAWL_TOOL_NAMES.length) {
+		return `all enabled (${tools.length}/${FIRECRAWL_TOOL_NAMES.length} selected)`;
+	}
+	if (tools.length === 0) return `all disabled (0/${FIRECRAWL_TOOL_NAMES.length} selected)`;
+	return `${tools.length}/${FIRECRAWL_TOOL_NAMES.length} selected: ${tools.join(", ")}`;
+}
+
+async function persistSettings(
+	ctx: CommandContext,
+	selectedTools: readonly FirecrawlToolName[],
+) {
+	try {
+		await saveSettings({ tools: [...selectedTools], updatedAt: Date.now() });
+	} catch (error) {
+		ctx.ui.notify(`Firecrawl settings save failed: ${formatError(error)}`, "warning");
+	}
+}
+
+async function loadSettings(): Promise<
+	| { kind: "missing" }
+	| { kind: "invalid"; reason: string }
+	| { kind: "loaded"; settings: FirecrawlSettings }
+> {
+	let text: string;
+	try {
+		text = await readFile(SETTINGS_FILE, "utf8");
+	} catch (error) {
+		if (isNodeError(error) && error.code === "ENOENT") return { kind: "missing" };
+		return { kind: "invalid", reason: formatError(error) };
+	}
+
+	try {
+		const parsed = JSON.parse(text) as unknown;
+		const settings = normalizeFirecrawlSettings(parsed);
+		if (settings) return { kind: "loaded", settings };
+		return { kind: "invalid", reason: "expected tools to be an array of Firecrawl tool names" };
+	} catch (error) {
+		return { kind: "invalid", reason: formatError(error) };
+	}
+}
+
+function normalizeFirecrawlSettings(value: unknown): FirecrawlSettings | undefined {
+	if (!value || typeof value !== "object") return undefined;
+	const settings = value as { tools?: unknown; updatedAt?: unknown };
+	if (typeof settings.updatedAt !== "number") return undefined;
+	if (!Array.isArray(settings.tools)) return undefined;
+	if (!settings.tools.every(isFirecrawlToolName)) return undefined;
+	return { tools: orderedUniqueFirecrawlTools(settings.tools), updatedAt: settings.updatedAt };
+}
+
+function isFirecrawlToolName(value: unknown): value is FirecrawlToolName {
+	return typeof value === "string" && FIRECRAWL_TOOL_NAMES.includes(value as never);
+}
+
+function orderedUniqueFirecrawlTools(tools: readonly FirecrawlToolName[]) {
+	const selectedTools = new Set(tools);
+	return orderedFirecrawlTools(selectedTools);
+}
+
+async function saveSettings(settings: FirecrawlSettings) {
+	await mkdir(dirname(SETTINGS_FILE), { recursive: true });
+	const tempFile = `${SETTINGS_FILE}.${process.pid}.${Date.now()}.tmp`;
+	try {
+		await writeFile(tempFile, `${JSON.stringify(settings, null, 2)}\n`, "utf8");
+		await rename(tempFile, SETTINGS_FILE);
+	} catch (error) {
+		await rm(tempFile, { force: true }).catch(() => undefined);
+		throw error;
+	}
+}
+
+function isNodeError(error: unknown): error is NodeJS.ErrnoException {
+	return error instanceof Error && "code" in error;
+}
+
+function formatError(error: unknown) {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function unique<T>(values: T[]) {
+	return Array.from(new Set(values));
+}
+
 async function firecrawlRequest(
 	method: "GET" | "POST",
 	path: string,
@@ -292,12 +805,6 @@ async function withStatus<T>(ctx: StatusContext, status: string, callback: () =>
 	}
 }
 
-function buildStatusMessage() {
-	return hasApiKey()
-		? `Firecrawl configured: ${state.apiUrl} (API key present).`
-		: `Firecrawl missing FIRECRAWL_API_KEY. API URL: ${state.apiUrl}.`;
-}
-
 function cleanObject<T>(value: T): T {
 	if (Array.isArray(value)) {
 		return value.map((item) => cleanObject(item)) as T;