pi-firecrawl-lite 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 James Lindfors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,98 @@
+# pi-firecrawl-lite
+
+Firecrawl for Pi, with a small prompt footprint and the full v2 capability set.
+
+`pi-firecrawl-lite` adds reliable web search and page scraping to Pi while keeping less-common crawl and site-mapping tools out of the model’s default tool list. When a task needs them, the model can call `firecrawl_load` to activate the relevant tools for the rest of the session.
+
+## Install
+
+Install the package in Pi’s normal extension directory or add it to a project:
+
+```bash
+pi install npm:pi-firecrawl-lite
+```
+
+For a project-local installation, add the package to `package.json` and use the extension entry already included in its `pi` manifest:
+
+```json
+{
+  "pi": {
+    "extensions": ["./node_modules/pi-firecrawl-lite/src/index.ts"]
+  }
+}
+```
+
+The extension has no runtime dependencies. Pi and TypeBox are peer dependencies supplied by the host.
+
+## Configure Firecrawl
+
+The extension resolves configuration in this order:
+
+1. An API URL configured explicitly in Pi.
+2. `FIRECRAWL_API_URL`, with an optional `FIRECRAWL_API_KEY`.
+3. A key without a URL uses Firecrawl Cloud at `https://api.firecrawl.dev/v2`.
+4. With neither value, it uses a keyless local server at `http://localhost:3002/v2`.
+
+Supported environment variables:
+
+```bash
+export FIRECRAWL_API_URL=http://localhost:3002
+export FIRECRAWL_API_KEY=fc-your-key       # optional for local deployments
+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:
+
+```text
+/firecrawl status
+/firecrawl url http://localhost:3002
+/firecrawl key
+/firecrawl timeout 120000
+/firecrawl reset
+```
+
+`/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.
+
+## Tools
+
+Always active:
+
+- `firecrawl_search` — web search with a query, optional result limit, advanced JSON options, and concise/raw output.
+- `firecrawl_scrape` — scrape a URL in markdown or other Firecrawl formats.
+- `firecrawl_load` — load deferred tools without removing Pi or other extension tools.
+
+Deferred tools:
+
+- `firecrawl_map` — discover URLs on a site.
+- `firecrawl_crawl` — start a crawl job.
+- `firecrawl_crawl_status` — inspect progress and returned documents.
+
+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.
+
+## Development
+
+This repository uses Bun:
+
+```bash
+bun install
+bun run validate
+```
+
+The validation command runs unit/integration-style mocked-fetch tests, strict typechecking, and the exact npm tarball allowlist check. The package intentionally publishes only `package.json`, `README.md`, `LICENSE`, and the three runtime files under `src/`; tests, workflows, lockfiles, `PLAN.md`, and local artifacts are excluded.
+
+## Releases
+
+Publishing is deliberately release-driven. Maintainers should create and publish a Gitea release whose tag exactly matches the package version, for example `v0.1.0`. The repository workflow then verifies tests, types, package contents, npm availability, and the tag/version match before publishing:
+
+- stable releases use npm dist-tag `latest`;
+- SemVer prereleases use npm dist-tag `next`.
+
+Do not run `npm publish` manually. A tag push by itself does not publish anything.
+
+## License
+
+MIT © James Lindfors

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "pi-firecrawl-lite",
+  "version": "0.1.1",
+  "description": "A lightweight Pi extension that brings Firecrawl search, scrape, map, and crawl tools to your agent.",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "author": "James Lindfors <lindforsdev@gmail.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://git.jameslindfors.xyz/james/pi-firecrawl-lite.git"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit",
+    "check:package": "npm --cache /tmp/pi-firecrawl-npm-cache pack --dry-run --json --ignore-scripts | node scripts/check-package.mjs",
+    "validate": "bun test && bun run typecheck && bun run check:package"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": ">=0.80.0",
+    "typebox": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.87.1",
+    "@types/bun": "latest",
+    "@types/node": "^22.0.0",
+    "typebox": "^1.3.34",
+    "typescript": "^5.7.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  }
+}

package/src/client.ts

@@ -0,0 +1,219 @@
+import { randomUUID } from "node:crypto";
+import { chmod, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export const DEFAULT_TIMEOUT_MS = 120_000;
+export const DEFAULT_LOCAL_API_URL = "http://localhost:3002/v2";
+export const DEFAULT_HOSTED_API_URL = "https://api.firecrawl.dev/v2";
+
+export type FirecrawlEnv = Record<string, string | undefined>;
+
+export interface FirecrawlConfig {
+  apiUrl: string;
+  apiKey?: string;
+  timeoutMs: number;
+  source: "explicit" | "key" | "local";
+}
+
+export interface FirecrawlOverrides {
+  apiUrl?: string;
+  apiKey?: string | null;
+  timeoutMs?: number;
+}
+
+export class FirecrawlError extends Error {
+  readonly kind: "configuration" | "connection" | "timeout" | "http" | "api" | "response";
+  readonly status?: number;
+
+  constructor(
+    kind: FirecrawlError["kind"],
+    message: string,
+    options?: { status?: number; cause?: unknown },
+  ) {
+    super(message, options);
+    this.name = "FirecrawlError";
+    this.kind = kind;
+    this.status = options?.status;
+  }
+}
+
+function parseTimeout(value: string | undefined): number {
+  if (value === undefined || value.trim() === "") return DEFAULT_TIMEOUT_MS;
+  const timeout = Number(value);
+  if (!Number.isInteger(timeout) || timeout <= 0 || timeout > 86_400_000) {
+    throw new FirecrawlError("configuration", "FIRECRAWL_TIMEOUT_MS must be a positive integer no greater than 86400000.");
+  }
+  return timeout;
+}
+
+export function normalizeApiUrl(value: string): string {
+  const trimmed = value.trim();
+  let parsed: URL;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw new FirecrawlError("configuration", "Firecrawl API URL must be an absolute HTTP or HTTPS URL.");
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new FirecrawlError("configuration", "Firecrawl API URL must use HTTP or HTTPS.");
+  }
+  if (parsed.username || parsed.password || parsed.search || parsed.hash) {
+    throw new FirecrawlError("configuration", "Firecrawl API URL must not contain credentials, a query string, or a fragment.");
+  }
+  const pathname = parsed.pathname.replace(/\/+$/, "");
+  if (pathname === "/v1" || pathname.startsWith("/v1/")) {
+    throw new FirecrawlError("configuration", "Firecrawl API v1 is not supported; configure the host root or a /v2 URL.");
+  }
+  if (pathname !== "" && pathname !== "/v2") {
+    throw new FirecrawlError("configuration", "Firecrawl API URL must point to the host root or end in /v2.");
+  }
+  parsed.pathname = pathname === "/v2" ? "/v2" : "/v2";
+  return parsed.toString().replace(/\/$/, "");
+}
+
+export function resolveConfig(env: FirecrawlEnv = process.env, overrides: FirecrawlOverrides = {}): FirecrawlConfig {
+  const hasUrlOverride = Object.prototype.hasOwnProperty.call(overrides, "apiUrl");
+  const hasKeyOverride = Object.prototype.hasOwnProperty.call(overrides, "apiKey");
+  const configuredUrl = hasUrlOverride ? overrides.apiUrl : env.FIRECRAWL_API_URL;
+  const configuredKey = hasKeyOverride ? overrides.apiKey : env.FIRECRAWL_API_KEY;
+  const apiKey = configuredKey?.trim() || undefined;
+  const apiUrl = configuredUrl?.trim()
+    ? normalizeApiUrl(configuredUrl)
+    : apiKey
+      ? DEFAULT_HOSTED_API_URL
+      : DEFAULT_LOCAL_API_URL;
+  const timeoutMs = overrides.timeoutMs ?? parseTimeout(env.FIRECRAWL_TIMEOUT_MS);
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 86_400_000) {
+    throw new FirecrawlError("configuration", "Timeout must be a positive integer no greater than 86400000.");
+  }
+  return {
+    apiUrl,
+    apiKey,
+    timeoutMs,
+    source: configuredUrl?.trim() ? "explicit" : apiKey ? "key" : "local",
+  };
+}
+
+export type FetchLike = (input: string | URL, init?: RequestInit) => Promise<Response>;
+
+export class FirecrawlClient {
+  private overrides: FirecrawlOverrides = {};
+
+  constructor(private readonly env: FirecrawlEnv = process.env, private readonly fetchImpl: FetchLike = fetch) {}
+
+  setOverrides(overrides: FirecrawlOverrides): void {
+    const candidate = { ...this.overrides, ...overrides };
+    resolveConfig(this.env, candidate);
+    this.overrides = candidate;
+  }
+
+  clearOverrides(): void {
+    this.overrides = {};
+  }
+
+  getConfig(): FirecrawlConfig {
+    return resolveConfig(this.env, this.overrides);
+  }
+
+  async search(body: Record<string, unknown>, signal?: AbortSignal): Promise<unknown> {
+    return this.request("/search", { method: "POST", body: JSON.stringify(body) }, signal);
+  }
+
+  async scrape(body: Record<string, unknown>, signal?: AbortSignal): Promise<unknown> {
+    return this.request("/scrape", { method: "POST", body: JSON.stringify(body) }, signal);
+  }
+
+  async map(body: Record<string, unknown>, signal?: AbortSignal): Promise<unknown> {
+    return this.request("/map", { method: "POST", body: JSON.stringify(body) }, signal);
+  }
+
+  async crawl(body: Record<string, unknown>, signal?: AbortSignal): Promise<unknown> {
+    return this.request("/crawl", { method: "POST", body: JSON.stringify(body) }, signal);
+  }
+
+  async crawlStatus(jobId: string, signal?: AbortSignal): Promise<unknown> {
+    return this.request(`/crawl/${encodeURIComponent(jobId)}`, { method: "GET" }, signal);
+  }
+
+  private async request(path: string, init: RequestInit, callerSignal?: AbortSignal): Promise<unknown> {
+    const config = this.getConfig();
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(new Error("deadline exceeded")), config.timeoutMs);
+    const abortCaller = () => controller.abort(callerSignal?.reason);
+    callerSignal?.addEventListener("abort", abortCaller, { once: true });
+    if (callerSignal?.aborted) controller.abort(callerSignal.reason);
+    const headers = new Headers(init.headers);
+    headers.set("accept", "application/json");
+    if (init.body !== undefined) headers.set("content-type", "application/json");
+    if (config.apiKey) headers.set("authorization", `Bearer ${config.apiKey}`);
+    try {
+      const response = await this.fetchImpl(`${config.apiUrl}${path}`, { ...init, headers, signal: controller.signal });
+      const text = await response.text();
+      let payload: unknown;
+      try {
+        payload = text ? JSON.parse(text) : {};
+      } catch (error) {
+        throw new FirecrawlError("response", "Firecrawl returned malformed JSON.", { cause: error });
+      }
+      if (!response.ok) {
+        const message = redactSecret(extractApiMessage(payload) ?? `Firecrawl returned HTTP ${response.status}.`, config.apiKey);
+        throw new FirecrawlError("http", message, { status: response.status });
+      }
+      if (isApiFailure(payload)) {
+        throw new FirecrawlError("api", redactSecret(extractApiMessage(payload) ?? "Firecrawl reported an API failure.", config.apiKey));
+      }
+      return payload;
+    } catch (error) {
+      if (error instanceof FirecrawlError) throw error;
+      if (callerSignal?.aborted) throw new FirecrawlError("connection", "Firecrawl request was cancelled.", { cause: error });
+      if (controller.signal.aborted) throw new FirecrawlError("timeout", `Firecrawl request timed out after ${config.timeoutMs} ms.`, { cause: error });
+      const message = redactSecret(error instanceof Error ? error.message : String(error), config.apiKey);
+      throw new FirecrawlError("connection", `Could not connect to Firecrawl: ${message}.`, { cause: error });
+    } finally {
+      clearTimeout(timeout);
+      callerSignal?.removeEventListener("abort", abortCaller);
+    }
+  }
+}
+
+function isApiFailure(payload: unknown): boolean {
+  return typeof payload === "object" && payload !== null && "success" in payload && (payload as { success?: unknown }).success === false;
+}
+
+function extractApiMessage(payload: unknown): string | undefined {
+  if (typeof payload !== "object" || payload === null) return undefined;
+  const value = payload as Record<string, unknown>;
+  for (const key of ["error", "message", "detail"]) {
+    if (typeof value[key] === "string" && value[key].trim()) return value[key].trim();
+  }
+  return undefined;
+}
+
+export function redactSecret(text: string, secret: string | undefined): string {
+  if (!secret) return text;
+  return text.split(secret).join("[REDACTED]");
+}
+
+export class ArtifactStore {
+  private directory?: string;
+
+  async save(contents: string): Promise<string> {
+    if (!this.directory) {
+      this.directory = await mkdtemp(join(tmpdir(), "pi-firecrawl-"));
+      await chmod(this.directory, 0o700);
+    }
+    const filename = `response-${Date.now()}-${randomUUID()}.json`;
+    const path = join(this.directory, filename);
+    await writeFile(path, contents, { encoding: "utf8", mode: 0o600 });
+    await chmod(path, 0o600);
+    return path;
+  }
+
+  async cleanup(): Promise<void> {
+    if (!this.directory) return;
+    const directory = this.directory;
+    this.directory = undefined;
+    await rm(directory, { recursive: true, force: true });
+  }
+}

package/src/index.ts

@@ -0,0 +1,48 @@
+import type { AgentToolResult, ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { configureFromCommand, createRuntime, registerCrawlTools, registerMapTool, registerScrapeTool, registerSearchTool } from "./tools.js";
+
+export default function firecrawlExtension(pi: ExtensionAPI): void {
+  const runtime = createRuntime();
+  registerSearchTool(pi, runtime);
+  registerScrapeTool(pi, runtime);
+
+  let mapLoaded = false;
+  let crawlLoaded = false;
+  pi.registerTool({
+    name: "firecrawl_load",
+    label: "Load Firecrawl Capability",
+    description: "Load deferred Firecrawl tools: crawl, map, or all.",
+    parameters: Type.Object({
+      capability: Type.String({ description: "Capability to load: crawl, map, or all." }),
+    }),
+    async execute(_id, params) {
+      const capability = String(params.capability).trim().toLowerCase();
+      if (capability !== "crawl" && capability !== "map" && capability !== "all") {
+        return { content: [{ type: "text" as const, text: "Firecrawl error: capability must be crawl, map, or all." }], details: { capability } } satisfies AgentToolResult<{ capability: string }>;
+      }
+      if ((capability === "map" || capability === "all") && !mapLoaded) {
+        registerMapTool(pi, runtime);
+        mapLoaded = true;
+      }
+      if ((capability === "crawl" || capability === "all") && !crawlLoaded) {
+        registerCrawlTools(pi, runtime);
+        crawlLoaded = true;
+      }
+      const loaded = capability === "all" ? "map, crawl, and crawl-status" : capability === "crawl" ? "crawl and crawl-status" : "map";
+      return { content: [{ type: "text" as const, text: `Loaded Firecrawl tools: ${loaded}.` }], details: { capability } };
+    },
+  });
+
+  pi.registerCommand("firecrawl", {
+    description: "Configure Firecrawl for this Pi session: /firecrawl status|url|key|timeout|reset",
+    handler: async (args, ctx) => configureFromCommand(args, runtime, ctx),
+  });
+  pi.on("session_start", () => {
+    const active = pi.getActiveTools();
+    pi.setActiveTools(active.filter((name) => name !== "firecrawl_map" && name !== "firecrawl_crawl" && name !== "firecrawl_crawl_status"));
+    mapLoaded = false;
+    crawlLoaded = false;
+  });
+  pi.on("session_shutdown", async () => runtime.artifacts.cleanup());
+}

package/src/tools.ts

@@ -0,0 +1,359 @@
+import { Type } from "typebox";
+import type { AgentToolResult, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { ArtifactStore, FirecrawlClient, FirecrawlError, redactSecret } from "./client.js";
+
+export const MAX_OUTPUT_BYTES = 50 * 1024;
+export const MAX_OUTPUT_LINES = 2_000;
+const POLLUTION_KEYS = new Set(["__proto__", "prototype", "constructor"]);
+
+type JsonObject = Record<string, unknown>;
+type ResponseMode = "concise" | "raw";
+type ToolDetails = { error?: string; responseMode?: ResponseMode };
+
+export const searchParameters = Type.Object({
+  query: Type.String({ description: "Search query." }),
+  limit: Type.Optional(Type.Integer({ description: "Maximum number of results." })),
+  options_json: Type.Optional(Type.String({ description: "Advanced Firecrawl search options as a JSON object." })),
+  response_mode: Type.Optional(Type.String({ description: "Output mode: concise (default) or raw." })),
+});
+
+export const scrapeParameters = Type.Object({
+  url: Type.String({ description: "Page URL to scrape." }),
+  formats: Type.Optional(Type.String({ description: "Comma-separated formats, default: markdown." })),
+  only_main_content: Type.Optional(Type.Boolean({ description: "Prefer the main page content." })),
+  wait_for_ms: Type.Optional(Type.Integer({ description: "Milliseconds to wait for page rendering." })),
+  options_json: Type.Optional(Type.String({ description: "Advanced Firecrawl scrape options as a JSON object." })),
+  response_mode: Type.Optional(Type.String({ description: "Output mode: concise (default) or raw." })),
+});
+
+export const mapParameters = Type.Object({
+  url: Type.String({ description: "Website URL to map." }),
+  search: Type.Optional(Type.String({ description: "Optional map search term." })),
+  limit: Type.Optional(Type.Integer({ description: "Maximum number of discovered URLs." })),
+  options_json: Type.Optional(Type.String({ description: "Advanced Firecrawl map options as a JSON object." })),
+  response_mode: Type.Optional(Type.String({ description: "Output mode: concise (default) or raw." })),
+});
+
+export const crawlParameters = Type.Object({
+  url: Type.String({ description: "Website URL to crawl." }),
+  limit: Type.Optional(Type.Integer({ description: "Maximum number of pages." })),
+  max_depth: Type.Optional(Type.Integer({ description: "Maximum crawl depth." })),
+  options_json: Type.Optional(Type.String({ description: "Advanced Firecrawl crawl options as a JSON object." })),
+  response_mode: Type.Optional(Type.String({ description: "Output mode: concise (default) or raw." })),
+});
+
+export const crawlStatusParameters = Type.Object({
+  job_id: Type.String({ description: "Crawl job ID returned by firecrawl_crawl." }),
+  response_mode: Type.Optional(Type.String({ description: "Output mode: concise (default) or raw." })),
+});
+
+export const loadParameters = Type.Object({
+  capability: Type.String({ description: "Capability to load: crawl, map, or all." }),
+});
+
+export function parseOptionsJson(value: string | undefined): JsonObject {
+  if (value === undefined || value.trim() === "") return {};
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch (error) {
+    throw new Error(`options_json must be valid JSON: ${error instanceof Error ? error.message : "parse failed"}`);
+  }
+  if (!isPlainObject(parsed)) throw new Error("options_json must contain a JSON object, not an array or primitive.");
+  return cloneJsonObject(parsed, "options_json");
+}
+
+function cloneJsonObject(value: JsonObject, path: string): JsonObject {
+  const result: JsonObject = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (POLLUTION_KEYS.has(key)) throw new Error(`${path} contains a forbidden key: ${key}.`);
+    result[key] = cloneJsonValue(child, `${path}.${key}`);
+  }
+  return result;
+}
+
+function cloneJsonValue(value: unknown, path: string): unknown {
+  if (Array.isArray(value)) return value.map((item, index) => cloneJsonValue(item, `${path}[${index}]`));
+  if (isPlainObject(value)) return cloneJsonObject(value, path);
+  return value;
+}
+
+function isPlainObject(value: unknown): value is JsonObject {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+export function mergeOptions(options: JsonObject, explicit: JsonObject, protectedKeys: string[]): JsonObject {
+  const result = cloneJsonObject(options, "options_json");
+  for (const key of protectedKeys) delete result[key];
+  for (const [key, value] of Object.entries(explicit)) {
+    if (value !== undefined) result[key] = value;
+  }
+  return result;
+}
+
+function requireText(value: unknown, name: string): string {
+  if (typeof value !== "string" || value.trim() === "") throw new Error(`${name} must be a non-empty string.`);
+  return value.trim();
+}
+
+function optionalInteger(value: unknown, name: string): number | undefined {
+  if (value === undefined) return undefined;
+  if (!Number.isInteger(value) || (value as number) < 0) throw new Error(`${name} must be a non-negative integer.`);
+  return value as number;
+}
+
+function mode(value: unknown): ResponseMode {
+  if (value === undefined || value === "concise") return "concise";
+  if (value === "raw") return "raw";
+  throw new Error("response_mode must be concise or raw.");
+}
+
+function formats(value: unknown): string[] {
+  if (value === undefined) return ["markdown"];
+  if (typeof value !== "string") throw new Error("formats must be a comma-separated string.");
+  const parsed = value.split(",").map((item) => item.trim()).filter(Boolean);
+  if (parsed.length === 0) throw new Error("formats must contain at least one format.");
+  return parsed;
+}
+
+export function buildSearchBody(params: Record<string, unknown>): JsonObject {
+  const query = requireText(params.query, "query");
+  const limit = optionalInteger(params.limit, "limit");
+  return mergeOptions(parseOptionsJson(params.options_json as string | undefined), { query, limit }, ["query"]);
+}
+
+export function buildScrapeBody(params: Record<string, unknown>): JsonObject {
+  const url = requireText(params.url, "url");
+  const waitFor = optionalInteger(params.wait_for_ms, "wait_for_ms");
+  return mergeOptions(
+    parseOptionsJson(params.options_json as string | undefined),
+    {
+      url,
+      formats: formats(params.formats),
+      onlyMainContent: params.only_main_content,
+      waitFor,
+    },
+    ["url"],
+  );
+}
+
+export function buildMapBody(params: Record<string, unknown>): JsonObject {
+  const url = requireText(params.url, "url");
+  const limit = optionalInteger(params.limit, "limit");
+  return mergeOptions(parseOptionsJson(params.options_json as string | undefined), { url, search: params.search, limit }, ["url"]);
+}
+
+export function buildCrawlBody(params: Record<string, unknown>): JsonObject {
+  const url = requireText(params.url, "url");
+  const limit = optionalInteger(params.limit, "limit");
+  const maxDepth = optionalInteger(params.max_depth, "max_depth");
+  return mergeOptions(parseOptionsJson(params.options_json as string | undefined), { url, limit, maxDepth }, ["url"]);
+}
+
+function pretty(value: unknown): string {
+  return JSON.stringify(value, null, 2) ?? "null";
+}
+
+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[];
+    }
+  }
+  return [];
+}
+
+export function conciseSearch(payload: unknown): string {
+  const entries = arrayFrom(payload);
+  if (entries.length === 0) return "No search results.";
+  return entries.map((entry, index) => {
+    const item = isPlainObject(entry) ? entry : {};
+    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}` : ""}`;
+  }).join("\n\n");
+}
+
+export function conciseScrape(payload: unknown): string {
+  const item = isPlainObject(payload) ? payload : {};
+  const metadata = isPlainObject(item.metadata) ? item.metadata : {};
+  const source = item.sourceURL ?? metadata.sourceURL ?? item.url;
+  const title = item.title ?? metadata.title;
+  const content = item.markdown ?? item.html ?? item.rawHtml ?? item.content ?? item.data;
+  const lines = [
+    typeof source === "string" ? `Source: ${source}` : undefined,
+    typeof title === "string" && title ? `Title: ${title}` : undefined,
+    typeof content === "string" ? content : content === undefined ? undefined : pretty(content),
+  ];
+  return lines.filter((line): line is string => line !== undefined).join("\n\n") || "Scrape returned no content.";
+}
+
+export function conciseMap(payload: unknown): string {
+  const entries = arrayFrom(payload);
+  if (entries.length === 0) return "No URLs found.";
+  return entries.map((entry, index) => {
+    if (typeof entry === "string") return `${index + 1}. ${entry}`;
+    const item = isPlainObject(entry) ? entry : {};
+    const url = typeof item.url === "string" ? item.url : "(no URL)";
+    const title = typeof item.title === "string" ? ` — ${item.title}` : "";
+    return `${index + 1}. ${url}${title}`;
+  }).join("\n");
+}
+
+export function conciseCrawl(payload: unknown): string {
+  const item = isPlainObject(payload) ? payload : {};
+  const id = item.id ?? item.jobId;
+  const status = item.status;
+  const lines = [typeof id === "string" ? `Job ID: ${id}` : undefined, typeof status === "string" ? `Status: ${status}` : undefined];
+  return lines.filter((line): line is string => line !== undefined).join("\n") || pretty(payload);
+}
+
+export function conciseCrawlStatus(payload: unknown): string {
+  const item = isPlainObject(payload) ? payload : {};
+  const summary = [
+    typeof item.status === "string" ? `Status: ${item.status}` : undefined,
+    item.completed !== undefined && item.total !== undefined ? `Progress: ${item.completed}/${item.total}` : undefined,
+  ].filter((line): line is string => line !== undefined);
+  const documents = arrayFrom(item.data);
+  if (documents.length > 0) {
+    summary.push("\nDocuments:");
+    summary.push(documents.map((document, index) => {
+      const value = isPlainObject(document) ? document : {};
+      const url = value.url ?? value.sourceURL ?? `document ${index + 1}`;
+      const content = value.markdown ?? value.title;
+      return `${index + 1}. ${String(url)}${content ? `\n   ${String(content)}` : ""}`;
+    }).join("\n\n"));
+  }
+  return summary.join("\n") || pretty(payload);
+}
+
+function formatPayload(kind: "search" | "scrape" | "map" | "crawl" | "crawl-status", payload: unknown, responseMode: ResponseMode): string {
+  if (responseMode === "raw") return pretty(payload);
+  switch (kind) {
+    case "search": return conciseSearch(payload);
+    case "scrape": return conciseScrape(payload);
+    case "map": return conciseMap(payload);
+    case "crawl": return conciseCrawl(payload);
+    case "crawl-status": return conciseCrawlStatus(payload);
+  }
+}
+
+function utf8Bytes(value: string): number {
+  return new TextEncoder().encode(value).byteLength;
+}
+
+function truncateUtf8(value: string, maxBytes: number): string {
+  const encoded = new TextEncoder().encode(value);
+  if (encoded.byteLength <= maxBytes) return value;
+  const decoder = new TextDecoder("utf-8", { fatal: true });
+  let end = Math.min(maxBytes, encoded.byteLength);
+  while (end > 0) {
+    try {
+      return decoder.decode(encoded.subarray(0, end));
+    } catch {
+      end -= 1;
+    }
+  }
+  return "";
+}
+
+export async function limitOutput(text: string, rawResponse: string, artifacts: ArtifactStore): Promise<string> {
+  const bytes = utf8Bytes(text);
+  const lines = text === "" ? 1 : text.split("\n").length;
+  if (bytes <= MAX_OUTPUT_BYTES && lines <= MAX_OUTPUT_LINES) return text;
+  const path = await artifacts.save(rawResponse);
+  const notice = `[truncated: response was ${bytes} bytes across ${lines} lines; complete response saved to ${path}]`;
+  let body = text.split("\n").slice(0, MAX_OUTPUT_LINES - 1).join("\n").replace(/\n+$/u, "");
+  body = truncateUtf8(body, MAX_OUTPUT_BYTES - utf8Bytes(notice) - 1);
+  return `${body}\n${notice}`;
+}
+
+export interface ToolRuntime {
+  client: FirecrawlClient;
+  artifacts: ArtifactStore;
+}
+
+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>;
+}
+
+async function execute(runtime: ToolRuntime, kind: Parameters<typeof formatPayload>[0], responseMode: unknown, operation: () => Promise<unknown>): Promise<AgentToolResult<ToolDetails>> {
+  try {
+    const payload = await operation();
+    const raw = pretty(payload);
+    const text = await limitOutput(formatPayload(kind, payload, mode(responseMode)), raw, runtime.artifacts);
+    return { content: [{ type: "text" as const, text }], details: { responseMode: mode(responseMode) } };
+  } catch (error) {
+    return errorResult(error, runtime.client);
+  }
+}
+
+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)); } });
+}
+
+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)); } });
+}
+
+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)); } });
+}
+
+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)); } });
+}
+
+export function createRuntime(): ToolRuntime {
+  return { client: new FirecrawlClient(), artifacts: new ArtifactStore() };
+}
+
+export async function configureFromCommand(args: string, runtime: ToolRuntime, ctx: ExtensionContext): Promise<void> {
+  const trimmed = args.trim();
+  const [command, ...rest] = trimmed.split(/\s+/u);
+  const value = rest.join(" ").trim();
+  const notify = (message: string, level: "info" | "warning" = "info") => ctx.ui.notify(message, level);
+  try {
+    if (!command || command === "status") {
+      const config = runtime.client.getConfig();
+      notify(`Firecrawl endpoint: ${config.apiUrl}; authentication: ${config.apiKey ? "configured" : "not configured"}; timeout: ${config.timeoutMs} ms.`);
+      return;
+    }
+    if (command === "reset") {
+      runtime.client.clearOverrides();
+      notify("Firecrawl command overrides cleared; environment configuration is active.");
+      return;
+    }
+    if (command === "url" || command === "key") {
+      const input = value || await ctx.ui.input(command === "url" ? "Firecrawl API URL" : "Firecrawl API key", command === "url" ? "http://localhost:3002" : "Enter a key (leave blank to clear)");
+      if (input === undefined) return;
+      if (command === "url") {
+        runtime.client.setOverrides({ apiUrl: input.trim() });
+        runtime.client.getConfig();
+        notify("Firecrawl API URL updated for this Pi session.");
+      } else {
+        runtime.client.setOverrides({ apiKey: input.trim() || null });
+        notify("Firecrawl API key updated for this Pi session (value hidden).");
+      }
+      return;
+    }
+    if (command === "timeout") {
+      const timeout = Number(value);
+      if (!Number.isInteger(timeout) || timeout <= 0) throw new Error("Usage: /firecrawl timeout <positive milliseconds>");
+      runtime.client.setOverrides({ timeoutMs: timeout });
+      notify("Firecrawl timeout updated for this Pi session.");
+      return;
+    }
+    notify("Usage: /firecrawl [status|url [URL]|key [KEY]|timeout MS|reset]", "warning");
+  } catch (error) {
+    notify(error instanceof Error ? error.message : String(error), "warning");
+  }
+}