pi-firecrawl-lite 0.1.1 → 0.1.2

package/README.md

@@ -17,7 +17,7 @@ For a project-local installation, add the package to `package.json` and use the
 ```json
 {
   "pi": {
-    "extensions": ["./node_modules/pi-firecrawl-lite/src/index.ts"]
+    "extensions": ["./node_modules/pi-firecrawl-lite/index.ts"]
   }
 }
 ```
@@ -43,7 +43,7 @@ export FIRECRAWL_TIMEOUT_MS=120000         # optional
 
 The URL must be HTTP or HTTPS and must point to the host root or end in `/v2`. v1 URLs are rejected. The API key is never shown in tool output, errors, notifications, or saved response details.
 
-Configuration can also be changed for the current Pi session with slash commands:
+Configuration can also be changed interactively for the current Pi session. Run `/firecrawl` and choose an option from the menu. The same actions are available as slash commands:
 
 ```text
 /firecrawl status
@@ -55,6 +55,8 @@ Configuration can also be changed for the current Pi session with slash commands
 
 `/firecrawl key` opens an input prompt when no key follows it. Session command overrides are kept in memory and reset when the extension is reloaded; use environment variables for a durable configuration.
 
+Search and scrape are available immediately; `firecrawl_load` is only needed before using the deferred map or crawl tools. If a local Firecrawl server is not reachable, the tool reports the active endpoint and points back to `/firecrawl`.
+
 ## Tools
 
 Always active:
@@ -71,7 +73,7 @@ Deferred tools:
 
 Every model-facing schema is flat. `options_json` accepts an object for advanced Firecrawl features such as browser actions, extraction, headers, location, tags, search filters, webhooks, and nested scrape options. It rejects malformed JSON, arrays, primitive values, and prototype-pollution keys. Explicit top-level arguments always override advanced options.
 
-Responses are concise by default. Set `response_mode` to `raw` when debugging or passing the full Firecrawl response to another step. Output is bounded at 50 KiB and 2,000 lines. A truncated response is saved in a private, session-specific temporary directory with restrictive permissions, and the tool reports its exact path and limits. Artifacts are removed when the session shuts down or the extension reloads.
+Responses are concise by default and are rendered with readable labels and width-aware Markdown in Pi. Set `response_mode` to `raw` when debugging or passing the full Firecrawl response to another step. Output is bounded at 50 KiB and 2,000 lines. A truncated response is saved in a private, session-specific temporary directory with restrictive permissions, and the tool reports its exact path and limits. Artifacts are removed when the session shuts down or the extension reloads.
 
 ## Development
 

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.js";

package/package.json

@@ -1,7 +1,14 @@
 {
   "name": "pi-firecrawl-lite",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "A lightweight Pi extension that brings Firecrawl search, scrape, map, and crawl tools to your agent.",
+  "keywords": [
+    "pi-package",
+    "firecrawl",
+    "web search",
+    "web scraping",
+    "ai agents"
+  ],
   "type": "module",
   "private": false,
   "license": "MIT",
@@ -11,13 +18,14 @@
     "url": "https://git.jameslindfors.xyz/james/pi-firecrawl-lite.git"
   },
   "files": [
+    "index.ts",
     "src",
     "README.md",
     "LICENSE"
   ],
   "pi": {
     "extensions": [
-      "./src/index.ts"
+      "./index.ts"
     ]
   },
   "scripts": {

package/src/index.ts

@@ -35,7 +35,7 @@ export default function firecrawlExtension(pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("firecrawl", {
-    description: "Configure Firecrawl for this Pi session: /firecrawl status|url|key|timeout|reset",
+    description: "Configure Firecrawl interactively, or use /firecrawl status|url|key|timeout|reset",
     handler: async (args, ctx) => configureFromCommand(args, runtime, ctx),
   });
   pi.on("session_start", () => {

package/src/tools.ts

@@ -1,5 +1,7 @@
 import { Type } from "typebox";
 import type { AgentToolResult, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
+import { Markdown } from "@earendil-works/pi-tui";
 import { ArtifactStore, FirecrawlClient, FirecrawlError, redactSecret } from "./client.js";
 
 export const MAX_OUTPUT_BYTES = 50 * 1024;
@@ -160,12 +162,22 @@ function arrayFrom(value: unknown): unknown[] {
   if (Array.isArray(value)) return value;
   if (isPlainObject(value)) {
     for (const key of ["data", "links", "web", "results"]) {
-      if (Array.isArray(value[key])) return value[key] as unknown[];
+      const child = value[key];
+      if (Array.isArray(child)) return child;
+      if (key === "data" && isPlainObject(child)) {
+        const nested = arrayFrom(child);
+        if (nested.length > 0) return nested;
+      }
     }
   }
   return [];
 }
 
+function dataObject(value: unknown): JsonObject {
+  if (!isPlainObject(value)) return {};
+  return isPlainObject(value.data) ? value.data : value;
+}
+
 export function conciseSearch(payload: unknown): string {
   const entries = arrayFrom(payload);
   if (entries.length === 0) return "No search results.";
@@ -174,12 +186,12 @@ export function conciseSearch(payload: unknown): string {
     const title = typeof item.title === "string" ? item.title : "Untitled result";
     const url = typeof item.url === "string" ? item.url : "(no URL)";
     const description = typeof item.description === "string" ? item.description : "";
-    return `${index + 1}. ${title}\n   ${url}${description ? `\n   ${description}` : ""}`;
+    return `${index + 1}. ${title}\n   URL: ${url}${description ? `\n   Description: ${description}` : ""}`;
   }).join("\n\n");
 }
 
 export function conciseScrape(payload: unknown): string {
-  const item = isPlainObject(payload) ? payload : {};
+  const item = dataObject(payload);
   const metadata = isPlainObject(item.metadata) ? item.metadata : {};
   const source = item.sourceURL ?? metadata.sourceURL ?? item.url;
   const title = item.title ?? metadata.title;
@@ -281,7 +293,22 @@ function errorResult(error: unknown, client: FirecrawlClient) {
   const config = (() => { try { return client.getConfig(); } catch { return undefined; } })();
   const message = error instanceof FirecrawlError ? `${error.kind}: ${error.message}` : error instanceof Error ? error.message : String(error);
   const safe = redactSecret(message, config?.apiKey);
-  return { content: [{ type: "text" as const, text: `Firecrawl error: ${safe}` }], details: { error: safe } } satisfies AgentToolResult<ToolDetails>;
+  const hint = error instanceof FirecrawlError && (error.kind === "connection" || error.kind === "timeout")
+    ? `\nEndpoint: ${config?.apiUrl ?? "unknown"}. Run /firecrawl to configure Firecrawl.`
+    : "";
+  const text = `Firecrawl error: ${safe}${hint}`;
+  return { content: [{ type: "text" as const, text }], details: { error: text } } satisfies AgentToolResult<ToolDetails>;
+}
+
+function renderToolResult(result: AgentToolResult<ToolDetails>, options: { expanded: boolean; isPartial: boolean }) {
+  if (options.isPartial) return new Markdown("Fetching Firecrawl…", 0, 0, getMarkdownTheme());
+  const content = result.content[0];
+  if (content?.type !== "text") return new Markdown("Firecrawl returned no text output.", 0, 0, getMarkdownTheme());
+  const lines = content.text.split("\n");
+  const text = options.expanded || lines.length <= 14
+    ? content.text
+    : `${lines.slice(0, 14).join("\n")}\n\n_${lines.length - 14} more lines — expand to view_`;
+  return new Markdown(text, 0, 0, getMarkdownTheme());
 }
 
 async function execute(runtime: ToolRuntime, kind: Parameters<typeof formatPayload>[0], responseMode: unknown, operation: () => Promise<unknown>): Promise<AgentToolResult<ToolDetails>> {
@@ -296,20 +323,20 @@ async function execute(runtime: ToolRuntime, kind: Parameters<typeof formatPaylo
 }
 
 export function registerSearchTool(pi: ExtensionAPI, runtime: ToolRuntime): void {
-  pi.registerTool({ name: "firecrawl_search", label: "Firecrawl Search", description: "Search the web through Firecrawl.", parameters: searchParameters, async execute(_id, params, signal) { return execute(runtime, "search", params.response_mode, () => runtime.client.search(buildSearchBody(params), signal)); } });
+  pi.registerTool({ name: "firecrawl_search", label: "Firecrawl Search", description: "Search the web through Firecrawl.", parameters: searchParameters, async execute(_id, params, signal) { return execute(runtime, "search", params.response_mode, () => runtime.client.search(buildSearchBody(params), signal)); }, renderResult: renderToolResult });
 }
 
 export function registerScrapeTool(pi: ExtensionAPI, runtime: ToolRuntime): void {
-  pi.registerTool({ name: "firecrawl_scrape", label: "Firecrawl Scrape", description: "Scrape a web page through Firecrawl.", parameters: scrapeParameters, async execute(_id, params, signal) { return execute(runtime, "scrape", params.response_mode, () => runtime.client.scrape(buildScrapeBody(params), signal)); } });
+  pi.registerTool({ name: "firecrawl_scrape", label: "Firecrawl Scrape", description: "Scrape a web page through Firecrawl.", parameters: scrapeParameters, async execute(_id, params, signal) { return execute(runtime, "scrape", params.response_mode, () => runtime.client.scrape(buildScrapeBody(params), signal)); }, renderResult: renderToolResult });
 }
 
 export function registerMapTool(pi: ExtensionAPI, runtime: ToolRuntime): void {
-  pi.registerTool({ name: "firecrawl_map", label: "Firecrawl Map", description: "Discover URLs on a website through Firecrawl.", parameters: mapParameters, async execute(_id, params, signal) { return execute(runtime, "map", params.response_mode, () => runtime.client.map(buildMapBody(params), signal)); } });
+  pi.registerTool({ name: "firecrawl_map", label: "Firecrawl Map", description: "Discover URLs on a website through Firecrawl.", parameters: mapParameters, async execute(_id, params, signal) { return execute(runtime, "map", params.response_mode, () => runtime.client.map(buildMapBody(params), signal)); }, renderResult: renderToolResult });
 }
 
 export function registerCrawlTools(pi: ExtensionAPI, runtime: ToolRuntime): void {
-  pi.registerTool({ name: "firecrawl_crawl", label: "Firecrawl Crawl", description: "Start a Firecrawl site crawl.", parameters: crawlParameters, async execute(_id, params, signal) { return execute(runtime, "crawl", params.response_mode, () => runtime.client.crawl(buildCrawlBody(params), signal)); } });
-  pi.registerTool({ name: "firecrawl_crawl_status", label: "Firecrawl Crawl Status", description: "Read the status and documents for a Firecrawl crawl.", parameters: crawlStatusParameters, async execute(_id, params, signal) { return execute(runtime, "crawl-status", params.response_mode, () => runtime.client.crawlStatus(requireText(params.job_id, "job_id"), signal)); } });
+  pi.registerTool({ name: "firecrawl_crawl", label: "Firecrawl Crawl", description: "Start a Firecrawl site crawl.", parameters: crawlParameters, async execute(_id, params, signal) { return execute(runtime, "crawl", params.response_mode, () => runtime.client.crawl(buildCrawlBody(params), signal)); }, renderResult: renderToolResult });
+  pi.registerTool({ name: "firecrawl_crawl_status", label: "Firecrawl Crawl Status", description: "Read the status and documents for a Firecrawl crawl.", parameters: crawlStatusParameters, async execute(_id, params, signal) { return execute(runtime, "crawl-status", params.response_mode, () => runtime.client.crawlStatus(requireText(params.job_id, "job_id"), signal)); }, renderResult: renderToolResult });
 }
 
 export function createRuntime(): ToolRuntime {
@@ -322,6 +349,22 @@ export async function configureFromCommand(args: string, runtime: ToolRuntime, c
   const value = rest.join(" ").trim();
   const notify = (message: string, level: "info" | "warning" = "info") => ctx.ui.notify(message, level);
   try {
+    if (!command && ctx.hasUI) {
+      const choice = await ctx.ui.select("Configure Firecrawl", [
+        "Show status",
+        "Set API URL",
+        "Set API key",
+        "Set timeout",
+        "Reset session overrides",
+        "Cancel",
+      ]);
+      if (choice === "Show status") return configureFromCommand("status", runtime, ctx);
+      if (choice === "Set API URL") return configureFromCommand("url", runtime, ctx);
+      if (choice === "Set API key") return configureFromCommand("key", runtime, ctx);
+      if (choice === "Set timeout") return configureFromCommand("timeout", runtime, ctx);
+      if (choice === "Reset session overrides") return configureFromCommand("reset", runtime, ctx);
+      return;
+    }
     if (!command || command === "status") {
       const config = runtime.client.getConfig();
       notify(`Firecrawl endpoint: ${config.apiUrl}; authentication: ${config.apiKey ? "configured" : "not configured"}; timeout: ${config.timeoutMs} ms.`);