@agent-native/core 0.68.3 → 0.69.0

package/corpus/README.md

@@ -28,4 +28,4 @@ rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
 ## Generated Counts
 
 - core files: 1138
-- template files: 3944
+- template files: 3945

package/corpus/core/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @agent-native/core
 
+## 0.69.0
+
+### Minor Changes
+
+- 530de18: Add Firecrawl as a BYOK backend for the web-search agent tool. When `FIRECRAWL_API_KEY` is configured (via app secrets or environment) the tool routes searches through Firecrawl's `/v2/search` API. It slots into the existing first-configured-wins chain after Brave, Tavily, and Exa, and before Builder-managed search, and is registered as an optional framework secret so it surfaces in every template's settings UI.
+
 ## 0.68.3
 
 ### Patch Changes

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.68.3",
+  "version": "0.69.0",
   "type": "module",
   "engines": {
     "node": ">=22"

package/corpus/core/src/extensions/web-search-tool.ts

@@ -7,13 +7,15 @@
  *   1. Brave Search API  (BRAVE_SEARCH_API_KEY)
  *   2. Tavily            (TAVILY_API_KEY)
  *   3. Exa               (EXA_API_KEY)
- *   4. Builder.io        (connected Builder credentials)
+ *   4. Firecrawl         (FIRECRAWL_API_KEY)
+ *   5. Builder.io        (connected Builder credentials)
  *
  * The first configured backend wins. If none is configured, the tool
  * returns a helpful message telling the user which keys to add.
  *
- * Connect Builder.io or register BRAVE_SEARCH_API_KEY, TAVILY_API_KEY, or
- * EXA_API_KEY via app secrets settings or environment variables.
+ * Connect Builder.io or register BRAVE_SEARCH_API_KEY, TAVILY_API_KEY,
+ * EXA_API_KEY, or FIRECRAWL_API_KEY via app secrets settings or environment
+ * variables.
  */
 
 import type { ActionEntry } from "../agent/production-agent.js";
@@ -222,6 +224,40 @@ async function searchExa(
   }));
 }
 
+async function searchFirecrawl(
+  query: string,
+  count: number,
+  apiKey: string,
+): Promise<WebSearchResult[]> {
+  const res = await fetch("https://api.firecrawl.dev/v2/search", {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${apiKey}`,
+    },
+    body: JSON.stringify({
+      query,
+      limit: count,
+    }),
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!res.ok) {
+    throw new Error(`Firecrawl error ${res.status}: ${await res.text()}`);
+  }
+  // v2 groups results by source ({ data: { web: [...] } }); older shapes
+  // return a flat array ({ data: [...] }). Accept both defensively.
+  type FirecrawlResult = { title?: string; url?: string; description?: string };
+  const data = (await res.json()) as {
+    data?: FirecrawlResult[] | { web?: FirecrawlResult[] };
+  };
+  const results = Array.isArray(data.data) ? data.data : (data.data?.web ?? []);
+  return results.map((r) => ({
+    title: r.title ?? "",
+    url: r.url ?? "",
+    snippet: r.description ?? "",
+  }));
+}
+
 async function searchBuilderManaged(
   query: string,
   count: number,
@@ -287,7 +323,7 @@ export function createWebSearchToolEntry(
     "web-search": {
       tool: {
         description:
-          "Search the public web. Use to find API documentation, endpoints, current information, or any topic. Returns ranked results from BYOK providers or a grounded Builder-managed summary. Follow up with web-request or provider-api-docs using responseMode:'markdown' or responseMode:'matches' to fetch clean text, links, or compact snippets from promising URLs. Requires either Connect Builder.io or one of: BRAVE_SEARCH_API_KEY, TAVILY_API_KEY, or EXA_API_KEY.",
+          "Search the public web. Use to find API documentation, endpoints, current information, or any topic. Returns ranked results from BYOK providers or a grounded Builder-managed summary. Follow up with web-request or provider-api-docs using responseMode:'markdown' or responseMode:'matches' to fetch clean text, links, or compact snippets from promising URLs. Requires either Connect Builder.io or one of: BRAVE_SEARCH_API_KEY, TAVILY_API_KEY, EXA_API_KEY, or FIRECRAWL_API_KEY.",
         parameters: {
           type: "object" as const,
           properties: {
@@ -318,6 +354,7 @@ export function createWebSearchToolEntry(
         const braveKey = await resolveSearchKey("BRAVE_SEARCH_API_KEY", opts);
         const tavilyKey = await resolveSearchKey("TAVILY_API_KEY", opts);
         const exaKey = await resolveSearchKey("EXA_API_KEY", opts);
+        const firecrawlKey = await resolveSearchKey("FIRECRAWL_API_KEY", opts);
         const builderCredentials = await resolveBuilderSearchCredentials(opts);
 
         let results: WebSearchResult[];
@@ -334,6 +371,9 @@ export function createWebSearchToolEntry(
           } else if (exaKey) {
             results = await searchExa(query, count, exaKey);
             backend = "Exa";
+          } else if (firecrawlKey) {
+            results = await searchFirecrawl(query, count, firecrawlKey);
+            backend = "Firecrawl";
           } else if (builderCredentials) {
             managedText = await searchBuilderManaged(
               query,
@@ -350,6 +390,7 @@ export function createWebSearchToolEntry(
               "  • BRAVE_SEARCH_API_KEY  — https://brave.com/search/api/",
               "  • TAVILY_API_KEY        — https://tavily.com/",
               "  • EXA_API_KEY           — https://exa.ai/",
+              "  • FIRECRAWL_API_KEY     — https://firecrawl.dev/",
             ].join("\n");
           }
         } catch (err: unknown) {

package/corpus/core/src/secrets/register-framework-secrets.ts

@@ -47,6 +47,13 @@ export function registerFrameworkSecrets(): void {
         "Enables the web-search agent tool via Exa. Used as fallback when Brave and Tavily are not set and before Builder-managed search.",
       docsUrl: "https://exa.ai/",
     },
+    {
+      key: "FIRECRAWL_API_KEY",
+      label: "Firecrawl API Key",
+      description:
+        "Enables the web-search agent tool via Firecrawl. Used as fallback when Brave, Tavily, and Exa are not set and before Builder-managed search.",
+      docsUrl: "https://firecrawl.dev/",
+    },
   ];
 
   for (const entry of webSearchKeys) {

package/corpus/templates/clips/app/components/recorder/pre-record-panel.tsx

@@ -48,6 +48,10 @@ import {
   type RecordingMode,
 } from "./recorder-engine";
 import type { CameraBubbleSize } from "./camera-bubble";
+import {
+  loadRecorderPreferences,
+  saveRecorderPreferences,
+} from "@/lib/recorder-preferences";
 import { CameraVisualizer, type CameraTestStatus } from "./camera-visualizer";
 import {
   MicrophoneVisualizer,
@@ -184,11 +188,14 @@ export function PreRecordPanel({
 }: PreRecordPanelProps) {
   const fileInputRef = useRef<HTMLInputElement>(null);
   const loomInputRef = useRef<HTMLInputElement>(null);
+  // Saved selections from the last visit. A `?mode=`/`?surface=` deep link
+  // (initialMode/initialDisplaySurface) still takes precedence over them.
+  const savedPrefs = useMemo(() => loadRecorderPreferences(), []);
   const [mode, setMode] = useState<RecordingMode>(
-    () => initialMode ?? "screen+camera",
+    () => initialMode ?? savedPrefs.mode ?? "screen+camera",
   );
   const [displaySurface, setDisplaySurface] = useState<DisplaySurface>(
-    () => initialDisplaySurface ?? "window",
+    () => initialDisplaySurface ?? savedPrefs.displaySurface ?? "window",
   );
   const [sourceOpen, setSourceOpen] = useState(false);
   const [deviceSettingsOpen, setDeviceSettingsOpen] = useState(false);
@@ -197,8 +204,12 @@ export function PreRecordPanel({
   const [loomError, setLoomError] = useState<string | null>(null);
   const [mics, setMics] = useState<MediaDeviceInfo[]>([]);
   const [cameras, setCameras] = useState<MediaDeviceInfo[]>([]);
-  const [micId, setMicId] = useState<string>("default");
-  const [cameraId, setCameraId] = useState<string>("default");
+  const [micId, setMicId] = useState<string>(
+    () => savedPrefs.micId ?? "default",
+  );
+  const [cameraId, setCameraId] = useState<string>(
+    () => savedPrefs.cameraId ?? "default",
+  );
   const [enumError, setEnumError] = useState<string | null>(null);
   const [micAccessStatus, setMicAccessStatus] =
     useState<DeviceAccessStatus>("idle");
@@ -274,13 +285,56 @@ export function PreRecordPanel({
     [mics],
   );
 
+  // Reset to "default" only once a populated list genuinely excludes the saved
+  // device — an empty list means "not enumerated yet", and resetting then would
+  // wipe a restored preference before devices load.
   useEffect(() => {
     if (micId === "default" || micId === NO_MIC_DEVICE_ID) return;
-    if (!mics.some((mic) => mic.deviceId === micId)) {
+    if (mics.length > 0 && !mics.some((mic) => mic.deviceId === micId)) {
       setMicId("default");
     }
   }, [micId, mics]);
 
+  // Same guard for cameras. Not persisted, so a temporarily missing device
+  // doesn't erase the saved choice.
+  useEffect(() => {
+    if (cameraId === "default" || cameraId === NO_CAMERA_DEVICE_ID) return;
+    if (
+      cameras.length > 0 &&
+      !cameras.some((camera) => camera.deviceId === cameraId)
+    ) {
+      setCameraId("default");
+    }
+  }, [cameraId, cameras]);
+
+  // Camera-only mode needs a camera — coerce a restored "off" sentinel to
+  // "default" so Start doesn't forward it as an exact deviceId (covers the
+  // ?mode=camera deep-link/restore path the mode buttons already handle).
+  useEffect(() => {
+    if (mode === "camera" && cameraId === NO_CAMERA_DEVICE_ID) {
+      setCameraId("default");
+    }
+  }, [mode, cameraId]);
+
+  // Persist deliberate picks only (not the resets above), so an unavailable
+  // device on load can't clobber the stored preference.
+  const chooseMode = useCallback((value: RecordingMode) => {
+    setMode(value);
+    saveRecorderPreferences({ mode: value });
+  }, []);
+  const chooseDisplaySurface = useCallback((value: DisplaySurface) => {
+    setDisplaySurface(value);
+    saveRecorderPreferences({ displaySurface: value });
+  }, []);
+  const chooseMic = useCallback((value: string) => {
+    setMicId(value);
+    saveRecorderPreferences({ micId: value });
+  }, []);
+  const chooseCamera = useCallback((value: string) => {
+    setCameraId(value);
+    saveRecorderPreferences({ cameraId: value });
+  }, []);
+
   const requestMicrophoneChoices = useCallback(async () => {
     if (!navigator.mediaDevices?.getUserMedia) {
       setMicAccessStatus("error");
@@ -376,9 +430,9 @@ export function PreRecordPanel({
         void requestMicrophoneChoices();
         return;
       }
-      setMicId(value);
+      chooseMic(value);
     },
-    [requestMicrophoneChoices],
+    [requestMicrophoneChoices, chooseMic],
   );
 
   const handleMicSignalChange = useCallback((hasSignal: boolean) => {
@@ -530,12 +584,12 @@ export function PreRecordPanel({
                 key={opt.value}
                 type="button"
                 onClick={() => {
-                  setMode(opt.value);
+                  chooseMode(opt.value);
                   if (
                     opt.value === "camera" &&
                     cameraId === NO_CAMERA_DEVICE_ID
                   ) {
-                    setCameraId("default");
+                    chooseCamera("default");
                   }
                 }}
                 className={cn(
@@ -605,7 +659,7 @@ export function PreRecordPanel({
                   <button
                     key={opt.value}
                     type="button"
-                    onClick={() => setDisplaySurface(opt.value)}
+                    onClick={() => chooseDisplaySurface(opt.value)}
                     className={cn(
                       "flex min-h-[76px] flex-col rounded-lg border p-2 text-left transition-colors",
                       active
@@ -703,7 +757,7 @@ export function PreRecordPanel({
                   <Switch
                     checked={audioEnabled}
                     onCheckedChange={(checked) =>
-                      setMicId(checked ? "default" : NO_MIC_DEVICE_ID)
+                      chooseMic(checked ? "default" : NO_MIC_DEVICE_ID)
                     }
                     disabled={busy}
                     aria-label="Include audio in this recording"
@@ -740,7 +794,7 @@ export function PreRecordPanel({
                     </div>
                     <Select
                       value={cameraId}
-                      onValueChange={setCameraId}
+                      onValueChange={chooseCamera}
                       disabled={!needsCamera}
                     >
                       <SelectTrigger className="h-9 min-w-0 flex-1 border-0 bg-transparent px-2 shadow-none hover:bg-muted/45 focus:ring-0 focus:ring-offset-0 disabled:opacity-60">
@@ -762,7 +816,9 @@ export function PreRecordPanel({
                       <Switch
                         checked={needsCamera}
                         onCheckedChange={(checked) =>
-                          setCameraId(checked ? "default" : NO_CAMERA_DEVICE_ID)
+                          chooseCamera(
+                            checked ? "default" : NO_CAMERA_DEVICE_ID,
+                          )
                         }
                         disabled={busy}
                         aria-label="Include camera in this recording"

package/corpus/templates/clips/app/components/recorder/recorder-engine.ts

@@ -186,6 +186,17 @@ function errorName(err: unknown): string {
   return (err as { name?: string } | null)?.name ?? "";
 }
 
+// getUserMedia failed because the requested device is gone (unplugged / stale
+// saved id), not a permission error — recoverable by retrying with the default.
+function isDeviceUnavailableError(err: unknown): boolean {
+  const name = errorName(err);
+  return (
+    name === "OverconstrainedError" ||
+    name === "NotFoundError" ||
+    name === "DevicesNotFoundError"
+  );
+}
+
 function errorMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err || "Unknown error");
 }
@@ -592,7 +603,20 @@ export class RecorderEngine {
             audio: false,
           });
         } catch (err) {
-          throw this.friendlyError(err, "camera");
+          // Stale/unplugged cameraDeviceId — retry with the default camera
+          // instead of failing the recording.
+          if (this.opts.cameraDeviceId && isDeviceUnavailableError(err)) {
+            try {
+              this.cameraStream = await navigator.mediaDevices.getUserMedia({
+                video: true,
+                audio: false,
+              });
+            } catch (retryErr) {
+              throw this.friendlyError(retryErr, "camera");
+            }
+          } else {
+            throw this.friendlyError(err, "camera");
+          }
         }
       }
 
@@ -603,7 +627,19 @@ export class RecorderEngine {
             video: false,
           });
         } catch (err) {
-          throw this.friendlyError(err, "microphone");
+          // Same stale-device fallback as the camera — retry default mic.
+          if (this.opts.micDeviceId && isDeviceUnavailableError(err)) {
+            try {
+              this.micStream = await navigator.mediaDevices.getUserMedia({
+                audio: voiceFocusedAudioConstraints(),
+                video: false,
+              });
+            } catch (retryErr) {
+              throw this.friendlyError(retryErr, "microphone");
+            }
+          } else {
+            throw this.friendlyError(err, "microphone");
+          }
         }
       }
 

package/corpus/templates/clips/app/lib/recorder-preferences.ts

@@ -0,0 +1,67 @@
+import type { CameraBubbleSize } from "@/components/recorder/camera-bubble";
+import type {
+  DisplaySurface,
+  RecordingMode,
+} from "@/components/recorder/recorder-engine";
+
+/**
+ * Last-used recorder selections, remembered across `/record` visits via
+ * localStorage so the panel doesn't reset to defaults every time. Device ids
+ * are best-effort: a remembered mic/camera that no longer exists (machine
+ * changed, permission revoked) falls back to "default" in the panel, so we
+ * never feed a stale `deviceId: { exact }` to getUserMedia.
+ *
+ * `?mode=` / `?surface=` URL params still win over a saved preference — those
+ * are explicit deep-link intents (e.g. the agent navigating to a specific
+ * capture mode).
+ */
+export interface RecorderPreferences {
+  mode: RecordingMode;
+  displaySurface: DisplaySurface;
+  micId: string;
+  cameraId: string;
+  cameraSize: CameraBubbleSize;
+}
+
+const STORAGE_KEY = "clips:recorder-preferences";
+
+const VALID_MODES: RecordingMode[] = ["screen", "camera", "screen+camera"];
+const VALID_SURFACES: DisplaySurface[] = ["monitor", "window", "browser"];
+const VALID_SIZES: CameraBubbleSize[] = ["sm", "md", "lg"];
+
+export function loadRecorderPreferences(): Partial<RecorderPreferences> {
+  if (typeof window === "undefined") return {};
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    if (!raw) return {};
+    const parsed = JSON.parse(raw) as Record<string, unknown>;
+    const prefs: Partial<RecorderPreferences> = {};
+    if (VALID_MODES.includes(parsed.mode as RecordingMode)) {
+      prefs.mode = parsed.mode as RecordingMode;
+    }
+    if (VALID_SURFACES.includes(parsed.displaySurface as DisplaySurface)) {
+      prefs.displaySurface = parsed.displaySurface as DisplaySurface;
+    }
+    if (typeof parsed.micId === "string") prefs.micId = parsed.micId;
+    if (typeof parsed.cameraId === "string") prefs.cameraId = parsed.cameraId;
+    if (VALID_SIZES.includes(parsed.cameraSize as CameraBubbleSize)) {
+      prefs.cameraSize = parsed.cameraSize as CameraBubbleSize;
+    }
+    return prefs;
+  } catch {
+    return {};
+  }
+}
+
+export function saveRecorderPreferences(
+  patch: Partial<RecorderPreferences>,
+): void {
+  if (typeof window === "undefined") return;
+  try {
+    const next = { ...loadRecorderPreferences(), ...patch };
+    window.localStorage.setItem(STORAGE_KEY, JSON.stringify(next));
+  } catch {
+    // localStorage may be unavailable (private mode, quota) — preferences are
+    // a nicety, never block recording on a write failure.
+  }
+}

package/corpus/templates/clips/app/routes/_app.trash.tsx

@@ -88,6 +88,16 @@ export default function TrashRoute() {
   };
 
   const selectedIds = Array.from(selected);
+  const allSelected =
+    recordings.length > 0 && selected.size === recordings.length;
+
+  const toggleSelectAll = () => {
+    setSelected((prev) =>
+      prev.size === recordings.length
+        ? new Set()
+        : new Set(recordings.map((r) => r.id)),
+    );
+  };
 
   return (
     <div className="flex flex-1 flex-col min-h-0">
@@ -96,6 +106,17 @@ export default function TrashRoute() {
         <div className="ml-auto flex items-center gap-2">
           {selectedIds.length > 0 && (
             <>
+              <span className="text-sm text-muted-foreground">
+                {selectedIds.length} selected
+              </span>
+              <Button
+                size="sm"
+                variant="ghost"
+                className="gap-1.5"
+                onClick={toggleSelectAll}
+              >
+                {allSelected ? "Deselect all" : "Select all"}
+              </Button>
               <Button
                 size="sm"
                 variant="outline"

package/corpus/templates/clips/app/routes/record.tsx

@@ -53,6 +53,10 @@ import {
   compressBlobIfTooLarge,
   formatMb,
 } from "@/lib/compress";
+import {
+  loadRecorderPreferences,
+  saveRecorderPreferences,
+} from "@/lib/recorder-preferences";
 import { cn } from "@/lib/utils";
 
 // Client-side app-state writer (the server module pulls in Node's `events`
@@ -718,7 +722,14 @@ export default function RecordRoute() {
   const [isPaused, setIsPaused] = useState(false);
   const [elapsedMs, setElapsedMs] = useState(0);
   const [cameraStream, setCameraStream] = useState<MediaStream | null>(null);
-  const [cameraSize, setCameraSize] = useState<CameraBubbleSize>("md");
+  const [cameraSize, setCameraSize] = useState<CameraBubbleSize>(
+    () => loadRecorderPreferences().cameraSize ?? "md",
+  );
+  // Remember the bubble size across visits alongside the panel's selections.
+  const handleCameraSizeChange = useCallback((size: CameraBubbleSize) => {
+    setCameraSize(size);
+    saveRecorderPreferences({ cameraSize: size });
+  }, []);
   const [previewStream, setPreviewStream] = useState<MediaStream | null>(null);
   // The capture surface the user actually picked in the browser's native screen
   // picker (authority over the requested `displaySurface` hint). Drives whether
@@ -2058,7 +2069,7 @@ export default function RecordRoute() {
                   onImportLoom={importLoom}
                   importingLoom={loomImporting}
                   cameraSize={cameraSize}
-                  onCameraSizeChange={setCameraSize}
+                  onCameraSizeChange={handleCameraSizeChange}
                 />
               ) : (
                 <StorageSetupCard
@@ -2137,7 +2148,7 @@ export default function RecordRoute() {
         <CameraBubble
           stream={cameraStream}
           size={cameraSize}
-          onSizeChange={setCameraSize}
+          onSizeChange={handleCameraSizeChange}
           hidden={
             (uiState !== "recording" && uiState !== "countdown") ||
             hideBubbleForFullScreenCapture

package/corpus/templates/content/vitest.config.ts

@@ -13,5 +13,8 @@ export default defineConfig({
   test: {
     include: ["**/*.{test,spec}.?(c|m)[jt]s?(x)"],
     exclude: ["**/node_modules/**", "**/.git/**", "**/dist/**", "**/e2e/**"],
+    hookTimeout: 60_000,
+    testTimeout: 60_000,
+    maxWorkers: "50%",
   },
 });

package/dist/extensions/web-search-tool.d.ts

@@ -7,13 +7,15 @@
  *   1. Brave Search API  (BRAVE_SEARCH_API_KEY)
  *   2. Tavily            (TAVILY_API_KEY)
  *   3. Exa               (EXA_API_KEY)
- *   4. Builder.io        (connected Builder credentials)
+ *   4. Firecrawl         (FIRECRAWL_API_KEY)
+ *   5. Builder.io        (connected Builder credentials)
  *
  * The first configured backend wins. If none is configured, the tool
  * returns a helpful message telling the user which keys to add.
  *
- * Connect Builder.io or register BRAVE_SEARCH_API_KEY, TAVILY_API_KEY, or
- * EXA_API_KEY via app secrets settings or environment variables.
+ * Connect Builder.io or register BRAVE_SEARCH_API_KEY, TAVILY_API_KEY,
+ * EXA_API_KEY, or FIRECRAWL_API_KEY via app secrets settings or environment
+ * variables.
  */
 import type { ActionEntry } from "../agent/production-agent.js";
 import type { CredentialContext } from "../credentials/index.js";

package/dist/extensions/web-search-tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"web-search-tool.d.ts","sourceRoot":"","sources":["../../src/extensions/web-search-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxD;;OAEG;IACH,iBAAiB,CAAC,EAAE,CAClB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,iBAAiB,KACnB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACjC;;OAEG;IACH,oBAAoB,CAAC,EAAE,MAAM,iBAAiB,GAAG,IAAI,CAAC;IACtD;;OAEG;IACH,yBAAyB,CAAC,EAAE,MAAM,OAAO,CAAC,2BAA2B,CAAC,CAAC;IACvE;;OAEG;IACH,0BAA0B,CAAC,EAAE,MAAM,MAAM,CAAC;IAC1C;;OAEG;IACH,wBAAwB,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzD;AAKD,UAAU,2BAA2B;IACnC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAsND;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,GAAE,oBAAyB,GAC9B,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CA+G7B"}
+{"version":3,"file":"web-search-tool.d.ts","sourceRoot":"","sources":["../../src/extensions/web-search-tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACxD;;OAEG;IACH,iBAAiB,CAAC,EAAE,CAClB,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,iBAAiB,KACnB,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACjC;;OAEG;IACH,oBAAoB,CAAC,EAAE,MAAM,iBAAiB,GAAG,IAAI,CAAC;IACtD;;OAEG;IACH,yBAAyB,CAAC,EAAE,MAAM,OAAO,CAAC,2BAA2B,CAAC,CAAC;IACvE;;OAEG;IACH,0BAA0B,CAAC,EAAE,MAAM,MAAM,CAAC;IAC1C;;OAEG;IACH,wBAAwB,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACzD;AAKD,UAAU,2BAA2B;IACnC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAwPD;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,GAAE,oBAAyB,GAC9B,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAoH7B"}

package/dist/extensions/web-search-tool.js

@@ -7,13 +7,15 @@
  *   1. Brave Search API  (BRAVE_SEARCH_API_KEY)
  *   2. Tavily            (TAVILY_API_KEY)
  *   3. Exa               (EXA_API_KEY)
- *   4. Builder.io        (connected Builder credentials)
+ *   4. Firecrawl         (FIRECRAWL_API_KEY)
+ *   5. Builder.io        (connected Builder credentials)
  *
  * The first configured backend wins. If none is configured, the tool
  * returns a helpful message telling the user which keys to add.
  *
- * Connect Builder.io or register BRAVE_SEARCH_API_KEY, TAVILY_API_KEY, or
- * EXA_API_KEY via app secrets settings or environment variables.
+ * Connect Builder.io or register BRAVE_SEARCH_API_KEY, TAVILY_API_KEY,
+ * EXA_API_KEY, or FIRECRAWL_API_KEY via app secrets settings or environment
+ * variables.
  */
 const DEFAULT_COUNT = 5;
 const MAX_COUNT = 10;
@@ -136,6 +138,30 @@ async function searchExa(query, count, apiKey) {
         snippet: r.text ?? "",
     }));
 }
+async function searchFirecrawl(query, count, apiKey) {
+    const res = await fetch("https://api.firecrawl.dev/v2/search", {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify({
+            query,
+            limit: count,
+        }),
+        signal: AbortSignal.timeout(15_000),
+    });
+    if (!res.ok) {
+        throw new Error(`Firecrawl error ${res.status}: ${await res.text()}`);
+    }
+    const data = (await res.json());
+    const results = Array.isArray(data.data) ? data.data : (data.data?.web ?? []);
+    return results.map((r) => ({
+        title: r.title ?? "",
+        url: r.url ?? "",
+        snippet: r.description ?? "",
+    }));
+}
 async function searchBuilderManaged(query, count, credentials, opts) {
     const baseUrl = opts.getBuilderWebSearchBaseUrl?.() ??
         process.env.BUILDER_WEB_SEARCH_BASE_URL ??
@@ -183,7 +209,7 @@ export function createWebSearchToolEntry(opts = {}) {
     return {
         "web-search": {
             tool: {
-                description: "Search the public web. Use to find API documentation, endpoints, current information, or any topic. Returns ranked results from BYOK providers or a grounded Builder-managed summary. Follow up with web-request or provider-api-docs using responseMode:'markdown' or responseMode:'matches' to fetch clean text, links, or compact snippets from promising URLs. Requires either Connect Builder.io or one of: BRAVE_SEARCH_API_KEY, TAVILY_API_KEY, or EXA_API_KEY.",
+                description: "Search the public web. Use to find API documentation, endpoints, current information, or any topic. Returns ranked results from BYOK providers or a grounded Builder-managed summary. Follow up with web-request or provider-api-docs using responseMode:'markdown' or responseMode:'matches' to fetch clean text, links, or compact snippets from promising URLs. Requires either Connect Builder.io or one of: BRAVE_SEARCH_API_KEY, TAVILY_API_KEY, EXA_API_KEY, or FIRECRAWL_API_KEY.",
                 parameters: {
                     type: "object",
                     properties: {
@@ -211,6 +237,7 @@ export function createWebSearchToolEntry(opts = {}) {
                 const braveKey = await resolveSearchKey("BRAVE_SEARCH_API_KEY", opts);
                 const tavilyKey = await resolveSearchKey("TAVILY_API_KEY", opts);
                 const exaKey = await resolveSearchKey("EXA_API_KEY", opts);
+                const firecrawlKey = await resolveSearchKey("FIRECRAWL_API_KEY", opts);
                 const builderCredentials = await resolveBuilderSearchCredentials(opts);
                 let results;
                 let backend;
@@ -228,6 +255,10 @@ export function createWebSearchToolEntry(opts = {}) {
                         results = await searchExa(query, count, exaKey);
                         backend = "Exa";
                     }
+                    else if (firecrawlKey) {
+                        results = await searchFirecrawl(query, count, firecrawlKey);
+                        backend = "Firecrawl";
+                    }
                     else if (builderCredentials) {
                         managedText = await searchBuilderManaged(query, count, builderCredentials, opts);
                         results = [];
@@ -240,6 +271,7 @@ export function createWebSearchToolEntry(opts = {}) {
                             "  • BRAVE_SEARCH_API_KEY  — https://brave.com/search/api/",
                             "  • TAVILY_API_KEY        — https://tavily.com/",
                             "  • EXA_API_KEY           — https://exa.ai/",
+                            "  • FIRECRAWL_API_KEY     — https://firecrawl.dev/",
                         ].join("\n");
                     }
                 }

package/dist/extensions/web-search-tool.js.map

@@ -1 +1 @@
-{"version":3,"file":"web-search-tool.js","sourceRoot":"","sources":["../../src/extensions/web-search-tool.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Web-search tool — agent tool for searching the public web.\n *\n * Pluggable backends resolved at call time based on which API key is\n * configured (env var or secrets/credentials store):\n *\n *   1. Brave Search API  (BRAVE_SEARCH_API_KEY)\n *   2. Tavily            (TAVILY_API_KEY)\n *   3. Exa               (EXA_API_KEY)\n *   4. Builder.io        (connected Builder credentials)\n *\n * The first configured backend wins. If none is configured, the tool\n * returns a helpful message telling the user which keys to add.\n *\n * Connect Builder.io or register BRAVE_SEARCH_API_KEY, TAVILY_API_KEY, or\n * EXA_API_KEY via app secrets settings or environment variables.\n */\n\nimport type { ActionEntry } from \"../agent/production-agent.js\";\nimport type { CredentialContext } from \"../credentials/index.js\";\n\nexport interface WebSearchResult {\n  title: string;\n  url: string;\n  snippet: string;\n}\n\nexport interface WebSearchToolOptions {\n  /**\n   * Resolve a request-scoped secret by key. When not provided the tool falls\n   * back to env-var lookup only.\n   */\n  resolveSecret?: (key: string) => Promise<string | null>;\n  /**\n   * Legacy credential resolver retained for older callers.\n   */\n  resolveCredential?: (\n    key: string,\n    ctx: CredentialContext,\n  ) => Promise<string | undefined>;\n  /**\n   * Legacy credential context callback retained for older callers.\n   */\n  getCredentialContext?: () => CredentialContext | null;\n  /**\n   * Resolve connected Builder credentials for managed web search.\n   */\n  resolveBuilderCredentials?: () => Promise<BuilderWebSearchCredentials>;\n  /**\n   * Base URL for Builder-managed web search.\n   */\n  getBuilderWebSearchBaseUrl?: () => string;\n  /**\n   * Stable attribution headers for Builder-managed API calls.\n   */\n  getBuilderRequestHeaders?: () => Record<string, string>;\n}\n\nconst DEFAULT_COUNT = 5;\nconst MAX_COUNT = 10;\n\ninterface BuilderWebSearchCredentials {\n  privateKey: string | null;\n  publicKey: string | null;\n  userId?: string | null;\n}\n\nasync function resolveSearchKey(\n  key: string,\n  opts: WebSearchToolOptions,\n): Promise<string | undefined> {\n  let usedRequestScopedResolver = false;\n  // 1. Try request-scoped app secrets (user/org/workspace stored key).\n  if (opts.resolveSecret) {\n    usedRequestScopedResolver = true;\n    try {\n      const value = await opts.resolveSecret(key);\n      if (value) return value;\n    } catch {\n      // Secret lookup failures are non-fatal; fall through to legacy/env.\n    }\n  }\n\n  // 2. Try legacy per-request credential context.\n  if (opts.resolveCredential && opts.getCredentialContext) {\n    const ctx = opts.getCredentialContext();\n    if (ctx) {\n      try {\n        const value = await opts.resolveCredential(key, ctx);\n        if (value) return value;\n      } catch {\n        // Credential lookup failures are non-fatal; fall through to env.\n      }\n    }\n  }\n\n  if (usedRequestScopedResolver) return undefined;\n\n  // 3. Fall back to env var.\n  return process.env[key] || undefined;\n}\n\nasync function resolveBuilderSearchCredentials(\n  opts: WebSearchToolOptions,\n): Promise<BuilderWebSearchCredentials | null> {\n  if (!opts.resolveBuilderCredentials) return null;\n  try {\n    const creds = await opts.resolveBuilderCredentials();\n    if (creds.privateKey && creds.publicKey) return creds;\n  } catch {\n    // Builder credential lookup failures are non-fatal; BYOK backends or the\n    // setup hint below can still handle the tool call.\n  }\n  return null;\n}\n\n// ---------------------------------------------------------------------------\n// Backend implementations\n// ---------------------------------------------------------------------------\n\nasync function searchBrave(\n  query: string,\n  count: number,\n  apiKey: string,\n): Promise<WebSearchResult[]> {\n  const url = `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(query)}&count=${count}`;\n  const res = await fetch(url, {\n    headers: {\n      Accept: \"application/json\",\n      \"Accept-Encoding\": \"gzip\",\n      \"X-Subscription-Token\": apiKey,\n    },\n    signal: AbortSignal.timeout(15_000),\n  });\n  if (!res.ok) {\n    throw new Error(`Brave Search error ${res.status}: ${await res.text()}`);\n  }\n  const data = (await res.json()) as {\n    web?: {\n      results?: Array<{\n        title?: string;\n        url?: string;\n        description?: string;\n      }>;\n    };\n  };\n  return (data.web?.results ?? []).map((r) => ({\n    title: r.title ?? \"\",\n    url: r.url ?? \"\",\n    snippet: r.description ?? \"\",\n  }));\n}\n\nasync function searchTavily(\n  query: string,\n  count: number,\n  apiKey: string,\n): Promise<WebSearchResult[]> {\n  const res = await fetch(\"https://api.tavily.com/search\", {\n    method: \"POST\",\n    headers: {\n      \"Content-Type\": \"application/json\",\n    },\n    body: JSON.stringify({\n      api_key: apiKey,\n      query,\n      max_results: count,\n      search_depth: \"basic\",\n    }),\n    signal: AbortSignal.timeout(15_000),\n  });\n  if (!res.ok) {\n    throw new Error(`Tavily error ${res.status}: ${await res.text()}`);\n  }\n  const data = (await res.json()) as {\n    results?: Array<{\n      title?: string;\n      url?: string;\n      content?: string;\n    }>;\n  };\n  return (data.results ?? []).map((r) => ({\n    title: r.title ?? \"\",\n    url: r.url ?? \"\",\n    snippet: r.content ?? \"\",\n  }));\n}\n\nasync function searchExa(\n  query: string,\n  count: number,\n  apiKey: string,\n): Promise<WebSearchResult[]> {\n  const res = await fetch(\"https://api.exa.ai/search\", {\n    method: \"POST\",\n    headers: {\n      \"Content-Type\": \"application/json\",\n      \"x-api-key\": apiKey,\n    },\n    body: JSON.stringify({\n      query,\n      numResults: count,\n      type: \"auto\",\n      contents: { text: { maxCharacters: 400 } },\n    }),\n    signal: AbortSignal.timeout(15_000),\n  });\n  if (!res.ok) {\n    throw new Error(`Exa error ${res.status}: ${await res.text()}`);\n  }\n  const data = (await res.json()) as {\n    results?: Array<{\n      title?: string;\n      url?: string;\n      text?: string;\n    }>;\n  };\n  return (data.results ?? []).map((r) => ({\n    title: r.title ?? \"\",\n    url: r.url ?? \"\",\n    snippet: r.text ?? \"\",\n  }));\n}\n\nasync function searchBuilderManaged(\n  query: string,\n  count: number,\n  credentials: BuilderWebSearchCredentials,\n  opts: WebSearchToolOptions,\n): Promise<string> {\n  const baseUrl =\n    opts.getBuilderWebSearchBaseUrl?.() ??\n    process.env.BUILDER_WEB_SEARCH_BASE_URL ??\n    \"https://api.builder.io/agent-native/web-search/v1\";\n  const url = new URL(\n    \"search\",\n    baseUrl.endsWith(\"/\") ? baseUrl : `${baseUrl}/`,\n  );\n  const res = await fetch(url.toString(), {\n    method: \"POST\",\n    headers: {\n      \"Content-Type\": \"application/json\",\n      Authorization: `Bearer ${credentials.privateKey}`,\n      \"x-builder-api-key\": credentials.publicKey ?? \"\",\n      ...(credentials.userId\n        ? { \"x-builder-user-id\": credentials.userId }\n        : {}),\n      ...(opts.getBuilderRequestHeaders?.() ?? {}),\n    },\n    body: JSON.stringify({\n      query,\n      count,\n      source: {\n        appId: \"agent-native\",\n        feature: \"web-search-tool\",\n      },\n    }),\n    signal: AbortSignal.timeout(45_000),\n  });\n  if (!res.ok) {\n    const text = await res.text().catch(() => \"\");\n    throw new Error(\n      `Builder web search error ${res.status}${text ? `: ${text.slice(0, 300)}` : \"\"}`,\n    );\n  }\n  const data = (await res.json()) as {\n    text?: string;\n  };\n  const text = data.text?.trim();\n  if (!text) {\n    throw new Error(\"Builder web search returned no text.\");\n  }\n  return text;\n}\n\n// ---------------------------------------------------------------------------\n// Tool entry factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create the web-search tool entry for the agent tool registry.\n */\nexport function createWebSearchToolEntry(\n  opts: WebSearchToolOptions = {},\n): Record<string, ActionEntry> {\n  return {\n    \"web-search\": {\n      tool: {\n        description:\n          \"Search the public web. Use to find API documentation, endpoints, current information, or any topic. Returns ranked results from BYOK providers or a grounded Builder-managed summary. Follow up with web-request or provider-api-docs using responseMode:'markdown' or responseMode:'matches' to fetch clean text, links, or compact snippets from promising URLs. Requires either Connect Builder.io or one of: BRAVE_SEARCH_API_KEY, TAVILY_API_KEY, or EXA_API_KEY.\",\n        parameters: {\n          type: \"object\" as const,\n          properties: {\n            query: {\n              type: \"string\",\n              description:\n                \"Search query. Be specific — include API name, version, and what you need (e.g. 'Stripe API list subscriptions endpoint').\",\n            },\n            count: {\n              type: \"number\",\n              description: `Number of results to return. Default ${DEFAULT_COUNT}, max ${MAX_COUNT}.`,\n            },\n          },\n          required: [\"query\"],\n        },\n      },\n      run: async (args: Record<string, string>) => {\n        const query = (args.query ?? \"\").trim();\n        if (!query) return \"query is required.\";\n\n        const rawCount = Number(args.count);\n        const count =\n          Number.isFinite(rawCount) && rawCount > 0\n            ? Math.min(Math.floor(rawCount), MAX_COUNT)\n            : DEFAULT_COUNT;\n\n        // Backend selection — first configured wins.\n        const braveKey = await resolveSearchKey(\"BRAVE_SEARCH_API_KEY\", opts);\n        const tavilyKey = await resolveSearchKey(\"TAVILY_API_KEY\", opts);\n        const exaKey = await resolveSearchKey(\"EXA_API_KEY\", opts);\n        const builderCredentials = await resolveBuilderSearchCredentials(opts);\n\n        let results: WebSearchResult[];\n        let backend: string;\n        let managedText: string | null = null;\n\n        try {\n          if (braveKey) {\n            results = await searchBrave(query, count, braveKey);\n            backend = \"Brave Search\";\n          } else if (tavilyKey) {\n            results = await searchTavily(query, count, tavilyKey);\n            backend = \"Tavily\";\n          } else if (exaKey) {\n            results = await searchExa(query, count, exaKey);\n            backend = \"Exa\";\n          } else if (builderCredentials) {\n            managedText = await searchBuilderManaged(\n              query,\n              count,\n              builderCredentials,\n              opts,\n            );\n            results = [];\n            backend = \"Builder.io\";\n          } else {\n            return [\n              \"No web-search backend configured.\",\n              \"Connect Builder.io in Settings, or add one of the following keys via app settings or environment variables:\",\n              \"  • BRAVE_SEARCH_API_KEY  — https://brave.com/search/api/\",\n              \"  • TAVILY_API_KEY        — https://tavily.com/\",\n              \"  • EXA_API_KEY           — https://exa.ai/\",\n            ].join(\"\\n\");\n          }\n        } catch (err: unknown) {\n          const msg = err instanceof Error ? err.message : String(err);\n          return `Web search failed (${msg}). Try web-request to fetch a specific URL directly.`;\n        }\n\n        if (managedText) {\n          return [\n            `Web search results for \"${query}\" (backend: ${backend}):`,\n            \"\",\n            managedText,\n            \"\",\n            \"Use web-request or provider-api-docs with responseMode:'markdown' for readable docs or responseMode:'matches' plus search for compact snippets.\",\n          ].join(\"\\n\");\n        }\n\n        if (results.length === 0) {\n          return `No results found for \"${query}\" (backend: ${backend}).`;\n        }\n\n        const lines: string[] = [\n          `Web search results for \"${query}\" (backend: ${backend}):`,\n          \"\",\n        ];\n        for (let i = 0; i < results.length; i++) {\n          const r = results[i];\n          lines.push(`${i + 1}. ${r.title}`);\n          lines.push(`   URL: ${r.url}`);\n          if (r.snippet) {\n            const snippet = r.snippet.slice(0, 300).replace(/\\n+/g, \" \");\n            lines.push(`   ${snippet}`);\n          }\n          lines.push(\"\");\n        }\n        lines.push(\n          \"Use web-request or provider-api-docs with responseMode:'markdown' for readable docs or responseMode:'matches' plus search for compact snippets.\",\n        );\n        return lines.join(\"\\n\");\n      },\n      readOnly: true,\n    },\n  };\n}\n"]}
+{"version":3,"file":"web-search-tool.js","sourceRoot":"","sources":["../../src/extensions/web-search-tool.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Web-search tool — agent tool for searching the public web.\n *\n * Pluggable backends resolved at call time based on which API key is\n * configured (env var or secrets/credentials store):\n *\n *   1. Brave Search API  (BRAVE_SEARCH_API_KEY)\n *   2. Tavily            (TAVILY_API_KEY)\n *   3. Exa               (EXA_API_KEY)\n *   4. Firecrawl         (FIRECRAWL_API_KEY)\n *   5. Builder.io        (connected Builder credentials)\n *\n * The first configured backend wins. If none is configured, the tool\n * returns a helpful message telling the user which keys to add.\n *\n * Connect Builder.io or register BRAVE_SEARCH_API_KEY, TAVILY_API_KEY,\n * EXA_API_KEY, or FIRECRAWL_API_KEY via app secrets settings or environment\n * variables.\n */\n\nimport type { ActionEntry } from \"../agent/production-agent.js\";\nimport type { CredentialContext } from \"../credentials/index.js\";\n\nexport interface WebSearchResult {\n  title: string;\n  url: string;\n  snippet: string;\n}\n\nexport interface WebSearchToolOptions {\n  /**\n   * Resolve a request-scoped secret by key. When not provided the tool falls\n   * back to env-var lookup only.\n   */\n  resolveSecret?: (key: string) => Promise<string | null>;\n  /**\n   * Legacy credential resolver retained for older callers.\n   */\n  resolveCredential?: (\n    key: string,\n    ctx: CredentialContext,\n  ) => Promise<string | undefined>;\n  /**\n   * Legacy credential context callback retained for older callers.\n   */\n  getCredentialContext?: () => CredentialContext | null;\n  /**\n   * Resolve connected Builder credentials for managed web search.\n   */\n  resolveBuilderCredentials?: () => Promise<BuilderWebSearchCredentials>;\n  /**\n   * Base URL for Builder-managed web search.\n   */\n  getBuilderWebSearchBaseUrl?: () => string;\n  /**\n   * Stable attribution headers for Builder-managed API calls.\n   */\n  getBuilderRequestHeaders?: () => Record<string, string>;\n}\n\nconst DEFAULT_COUNT = 5;\nconst MAX_COUNT = 10;\n\ninterface BuilderWebSearchCredentials {\n  privateKey: string | null;\n  publicKey: string | null;\n  userId?: string | null;\n}\n\nasync function resolveSearchKey(\n  key: string,\n  opts: WebSearchToolOptions,\n): Promise<string | undefined> {\n  let usedRequestScopedResolver = false;\n  // 1. Try request-scoped app secrets (user/org/workspace stored key).\n  if (opts.resolveSecret) {\n    usedRequestScopedResolver = true;\n    try {\n      const value = await opts.resolveSecret(key);\n      if (value) return value;\n    } catch {\n      // Secret lookup failures are non-fatal; fall through to legacy/env.\n    }\n  }\n\n  // 2. Try legacy per-request credential context.\n  if (opts.resolveCredential && opts.getCredentialContext) {\n    const ctx = opts.getCredentialContext();\n    if (ctx) {\n      try {\n        const value = await opts.resolveCredential(key, ctx);\n        if (value) return value;\n      } catch {\n        // Credential lookup failures are non-fatal; fall through to env.\n      }\n    }\n  }\n\n  if (usedRequestScopedResolver) return undefined;\n\n  // 3. Fall back to env var.\n  return process.env[key] || undefined;\n}\n\nasync function resolveBuilderSearchCredentials(\n  opts: WebSearchToolOptions,\n): Promise<BuilderWebSearchCredentials | null> {\n  if (!opts.resolveBuilderCredentials) return null;\n  try {\n    const creds = await opts.resolveBuilderCredentials();\n    if (creds.privateKey && creds.publicKey) return creds;\n  } catch {\n    // Builder credential lookup failures are non-fatal; BYOK backends or the\n    // setup hint below can still handle the tool call.\n  }\n  return null;\n}\n\n// ---------------------------------------------------------------------------\n// Backend implementations\n// ---------------------------------------------------------------------------\n\nasync function searchBrave(\n  query: string,\n  count: number,\n  apiKey: string,\n): Promise<WebSearchResult[]> {\n  const url = `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(query)}&count=${count}`;\n  const res = await fetch(url, {\n    headers: {\n      Accept: \"application/json\",\n      \"Accept-Encoding\": \"gzip\",\n      \"X-Subscription-Token\": apiKey,\n    },\n    signal: AbortSignal.timeout(15_000),\n  });\n  if (!res.ok) {\n    throw new Error(`Brave Search error ${res.status}: ${await res.text()}`);\n  }\n  const data = (await res.json()) as {\n    web?: {\n      results?: Array<{\n        title?: string;\n        url?: string;\n        description?: string;\n      }>;\n    };\n  };\n  return (data.web?.results ?? []).map((r) => ({\n    title: r.title ?? \"\",\n    url: r.url ?? \"\",\n    snippet: r.description ?? \"\",\n  }));\n}\n\nasync function searchTavily(\n  query: string,\n  count: number,\n  apiKey: string,\n): Promise<WebSearchResult[]> {\n  const res = await fetch(\"https://api.tavily.com/search\", {\n    method: \"POST\",\n    headers: {\n      \"Content-Type\": \"application/json\",\n    },\n    body: JSON.stringify({\n      api_key: apiKey,\n      query,\n      max_results: count,\n      search_depth: \"basic\",\n    }),\n    signal: AbortSignal.timeout(15_000),\n  });\n  if (!res.ok) {\n    throw new Error(`Tavily error ${res.status}: ${await res.text()}`);\n  }\n  const data = (await res.json()) as {\n    results?: Array<{\n      title?: string;\n      url?: string;\n      content?: string;\n    }>;\n  };\n  return (data.results ?? []).map((r) => ({\n    title: r.title ?? \"\",\n    url: r.url ?? \"\",\n    snippet: r.content ?? \"\",\n  }));\n}\n\nasync function searchExa(\n  query: string,\n  count: number,\n  apiKey: string,\n): Promise<WebSearchResult[]> {\n  const res = await fetch(\"https://api.exa.ai/search\", {\n    method: \"POST\",\n    headers: {\n      \"Content-Type\": \"application/json\",\n      \"x-api-key\": apiKey,\n    },\n    body: JSON.stringify({\n      query,\n      numResults: count,\n      type: \"auto\",\n      contents: { text: { maxCharacters: 400 } },\n    }),\n    signal: AbortSignal.timeout(15_000),\n  });\n  if (!res.ok) {\n    throw new Error(`Exa error ${res.status}: ${await res.text()}`);\n  }\n  const data = (await res.json()) as {\n    results?: Array<{\n      title?: string;\n      url?: string;\n      text?: string;\n    }>;\n  };\n  return (data.results ?? []).map((r) => ({\n    title: r.title ?? \"\",\n    url: r.url ?? \"\",\n    snippet: r.text ?? \"\",\n  }));\n}\n\nasync function searchFirecrawl(\n  query: string,\n  count: number,\n  apiKey: string,\n): Promise<WebSearchResult[]> {\n  const res = await fetch(\"https://api.firecrawl.dev/v2/search\", {\n    method: \"POST\",\n    headers: {\n      \"Content-Type\": \"application/json\",\n      Authorization: `Bearer ${apiKey}`,\n    },\n    body: JSON.stringify({\n      query,\n      limit: count,\n    }),\n    signal: AbortSignal.timeout(15_000),\n  });\n  if (!res.ok) {\n    throw new Error(`Firecrawl error ${res.status}: ${await res.text()}`);\n  }\n  // v2 groups results by source ({ data: { web: [...] } }); older shapes\n  // return a flat array ({ data: [...] }). Accept both defensively.\n  type FirecrawlResult = { title?: string; url?: string; description?: string };\n  const data = (await res.json()) as {\n    data?: FirecrawlResult[] | { web?: FirecrawlResult[] };\n  };\n  const results = Array.isArray(data.data) ? data.data : (data.data?.web ?? []);\n  return results.map((r) => ({\n    title: r.title ?? \"\",\n    url: r.url ?? \"\",\n    snippet: r.description ?? \"\",\n  }));\n}\n\nasync function searchBuilderManaged(\n  query: string,\n  count: number,\n  credentials: BuilderWebSearchCredentials,\n  opts: WebSearchToolOptions,\n): Promise<string> {\n  const baseUrl =\n    opts.getBuilderWebSearchBaseUrl?.() ??\n    process.env.BUILDER_WEB_SEARCH_BASE_URL ??\n    \"https://api.builder.io/agent-native/web-search/v1\";\n  const url = new URL(\n    \"search\",\n    baseUrl.endsWith(\"/\") ? baseUrl : `${baseUrl}/`,\n  );\n  const res = await fetch(url.toString(), {\n    method: \"POST\",\n    headers: {\n      \"Content-Type\": \"application/json\",\n      Authorization: `Bearer ${credentials.privateKey}`,\n      \"x-builder-api-key\": credentials.publicKey ?? \"\",\n      ...(credentials.userId\n        ? { \"x-builder-user-id\": credentials.userId }\n        : {}),\n      ...(opts.getBuilderRequestHeaders?.() ?? {}),\n    },\n    body: JSON.stringify({\n      query,\n      count,\n      source: {\n        appId: \"agent-native\",\n        feature: \"web-search-tool\",\n      },\n    }),\n    signal: AbortSignal.timeout(45_000),\n  });\n  if (!res.ok) {\n    const text = await res.text().catch(() => \"\");\n    throw new Error(\n      `Builder web search error ${res.status}${text ? `: ${text.slice(0, 300)}` : \"\"}`,\n    );\n  }\n  const data = (await res.json()) as {\n    text?: string;\n  };\n  const text = data.text?.trim();\n  if (!text) {\n    throw new Error(\"Builder web search returned no text.\");\n  }\n  return text;\n}\n\n// ---------------------------------------------------------------------------\n// Tool entry factory\n// ---------------------------------------------------------------------------\n\n/**\n * Create the web-search tool entry for the agent tool registry.\n */\nexport function createWebSearchToolEntry(\n  opts: WebSearchToolOptions = {},\n): Record<string, ActionEntry> {\n  return {\n    \"web-search\": {\n      tool: {\n        description:\n          \"Search the public web. Use to find API documentation, endpoints, current information, or any topic. Returns ranked results from BYOK providers or a grounded Builder-managed summary. Follow up with web-request or provider-api-docs using responseMode:'markdown' or responseMode:'matches' to fetch clean text, links, or compact snippets from promising URLs. Requires either Connect Builder.io or one of: BRAVE_SEARCH_API_KEY, TAVILY_API_KEY, EXA_API_KEY, or FIRECRAWL_API_KEY.\",\n        parameters: {\n          type: \"object\" as const,\n          properties: {\n            query: {\n              type: \"string\",\n              description:\n                \"Search query. Be specific — include API name, version, and what you need (e.g. 'Stripe API list subscriptions endpoint').\",\n            },\n            count: {\n              type: \"number\",\n              description: `Number of results to return. Default ${DEFAULT_COUNT}, max ${MAX_COUNT}.`,\n            },\n          },\n          required: [\"query\"],\n        },\n      },\n      run: async (args: Record<string, string>) => {\n        const query = (args.query ?? \"\").trim();\n        if (!query) return \"query is required.\";\n\n        const rawCount = Number(args.count);\n        const count =\n          Number.isFinite(rawCount) && rawCount > 0\n            ? Math.min(Math.floor(rawCount), MAX_COUNT)\n            : DEFAULT_COUNT;\n\n        // Backend selection — first configured wins.\n        const braveKey = await resolveSearchKey(\"BRAVE_SEARCH_API_KEY\", opts);\n        const tavilyKey = await resolveSearchKey(\"TAVILY_API_KEY\", opts);\n        const exaKey = await resolveSearchKey(\"EXA_API_KEY\", opts);\n        const firecrawlKey = await resolveSearchKey(\"FIRECRAWL_API_KEY\", opts);\n        const builderCredentials = await resolveBuilderSearchCredentials(opts);\n\n        let results: WebSearchResult[];\n        let backend: string;\n        let managedText: string | null = null;\n\n        try {\n          if (braveKey) {\n            results = await searchBrave(query, count, braveKey);\n            backend = \"Brave Search\";\n          } else if (tavilyKey) {\n            results = await searchTavily(query, count, tavilyKey);\n            backend = \"Tavily\";\n          } else if (exaKey) {\n            results = await searchExa(query, count, exaKey);\n            backend = \"Exa\";\n          } else if (firecrawlKey) {\n            results = await searchFirecrawl(query, count, firecrawlKey);\n            backend = \"Firecrawl\";\n          } else if (builderCredentials) {\n            managedText = await searchBuilderManaged(\n              query,\n              count,\n              builderCredentials,\n              opts,\n            );\n            results = [];\n            backend = \"Builder.io\";\n          } else {\n            return [\n              \"No web-search backend configured.\",\n              \"Connect Builder.io in Settings, or add one of the following keys via app settings or environment variables:\",\n              \"  • BRAVE_SEARCH_API_KEY  — https://brave.com/search/api/\",\n              \"  • TAVILY_API_KEY        — https://tavily.com/\",\n              \"  • EXA_API_KEY           — https://exa.ai/\",\n              \"  • FIRECRAWL_API_KEY     — https://firecrawl.dev/\",\n            ].join(\"\\n\");\n          }\n        } catch (err: unknown) {\n          const msg = err instanceof Error ? err.message : String(err);\n          return `Web search failed (${msg}). Try web-request to fetch a specific URL directly.`;\n        }\n\n        if (managedText) {\n          return [\n            `Web search results for \"${query}\" (backend: ${backend}):`,\n            \"\",\n            managedText,\n            \"\",\n            \"Use web-request or provider-api-docs with responseMode:'markdown' for readable docs or responseMode:'matches' plus search for compact snippets.\",\n          ].join(\"\\n\");\n        }\n\n        if (results.length === 0) {\n          return `No results found for \"${query}\" (backend: ${backend}).`;\n        }\n\n        const lines: string[] = [\n          `Web search results for \"${query}\" (backend: ${backend}):`,\n          \"\",\n        ];\n        for (let i = 0; i < results.length; i++) {\n          const r = results[i];\n          lines.push(`${i + 1}. ${r.title}`);\n          lines.push(`   URL: ${r.url}`);\n          if (r.snippet) {\n            const snippet = r.snippet.slice(0, 300).replace(/\\n+/g, \" \");\n            lines.push(`   ${snippet}`);\n          }\n          lines.push(\"\");\n        }\n        lines.push(\n          \"Use web-request or provider-api-docs with responseMode:'markdown' for readable docs or responseMode:'matches' plus search for compact snippets.\",\n        );\n        return lines.join(\"\\n\");\n      },\n      readOnly: true,\n    },\n  };\n}\n"]}

package/dist/secrets/register-framework-secrets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"register-framework-secrets.d.ts","sourceRoot":"","sources":["../../src/secrets/register-framework-secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,wBAAgB,wBAAwB,IAAI,IAAI,CA2D/C"}
+{"version":3,"file":"register-framework-secrets.d.ts","sourceRoot":"","sources":["../../src/secrets/register-framework-secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,wBAAgB,wBAAwB,IAAI,IAAI,CAkE/C"}

package/dist/secrets/register-framework-secrets.js

@@ -37,6 +37,12 @@ export function registerFrameworkSecrets() {
             description: "Enables the web-search agent tool via Exa. Used as fallback when Brave and Tavily are not set and before Builder-managed search.",
             docsUrl: "https://exa.ai/",
         },
+        {
+            key: "FIRECRAWL_API_KEY",
+            label: "Firecrawl API Key",
+            description: "Enables the web-search agent tool via Firecrawl. Used as fallback when Brave, Tavily, and Exa are not set and before Builder-managed search.",
+            docsUrl: "https://firecrawl.dev/",
+        },
     ];
     for (const entry of webSearchKeys) {
         if (!getRequiredSecret(entry.key)) {

package/dist/secrets/register-framework-secrets.js.map

@@ -1 +1 @@
-{"version":3,"file":"register-framework-secrets.js","sourceRoot":"","sources":["../../src/secrets/register-framework-secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAE1E,MAAM,UAAU,wBAAwB;IACtC,kEAAkE;IAClE,0EAA0E;IAC1E,MAAM,aAAa,GAKd;QACH;YACE,GAAG,EAAE,sBAAsB;YAC3B,KAAK,EAAE,sBAAsB;YAC7B,WAAW,EACT,mHAAmH;YACrH,OAAO,EAAE,+BAA+B;SACzC;QACD;YACE,GAAG,EAAE,gBAAgB;YACrB,KAAK,EAAE,gBAAgB;YACvB,WAAW,EACT,wIAAwI;YAC1I,OAAO,EAAE,qBAAqB;SAC/B;QACD;YACE,GAAG,EAAE,aAAa;YAClB,KAAK,EAAE,aAAa;YACpB,WAAW,EACT,kIAAkI;YACpI,OAAO,EAAE,iBAAiB;SAC3B;KACF,CAAC;IAEF,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;QAClC,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YAClC,sBAAsB,CAAC;gBACrB,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,KAAK,EAAE,WAAW;gBAClB,IAAI,EAAE,SAAS;gBACf,QAAQ,EAAE,KAAK;aAChB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,IAAI,CAAC,iBAAiB,CAAC,cAAc,CAAC,EAAE,CAAC;QACvC,sBAAsB,CAAC;YACrB,GAAG,EAAE,cAAc;YACnB,KAAK,EAAE,cAAc;YACrB,WAAW,EACT,0FAA0F;YAC5F,OAAO,EACL,kHAAkH;YACpH,KAAK,EAAE,WAAW;YAClB,IAAI,EAAE,SAAS;YACf,QAAQ,EAAE,KAAK;SAChB,CAAC,CAAC;IACL,CAAC;AACH,CAAC","sourcesContent":["/**\n * Framework-level secret registrations.\n *\n * Side-effect module — imported by the core-routes plugin at boot so the\n * sidebar settings UI and the `/_agent-native/secrets` list route surface the\n * relevant keys in every template.\n *\n * Each call uses a `getRequiredSecret` guard so a template that has already\n * registered the same key (often with stricter settings like `required: true`)\n * wins — the framework registration is a fallback, not an override.\n *\n * NOTE: The framework previously registered OPENAI_API_KEY here for Whisper\n * voice transcription. Voice transcription now routes through the Builder.io\n * gateway (or Groq as a BYOK fallback), so the framework no longer registers\n * the OpenAI key. Templates that need it (e.g. Clips) register it themselves.\n */\n\nimport { getRequiredSecret, registerRequiredSecret } from \"./register.js\";\n\nexport function registerFrameworkSecrets(): void {\n  // Web-search tool backends — optional; the tool selects the first\n  // configured manual key at call time, then falls back to Builder Connect.\n  const webSearchKeys: Array<{\n    key: string;\n    label: string;\n    description: string;\n    docsUrl: string;\n  }> = [\n    {\n      key: \"BRAVE_SEARCH_API_KEY\",\n      label: \"Brave Search API Key\",\n      description:\n        \"Enables the web-search agent tool via Brave Search. Optional when Builder.io is connected for managed web search.\",\n      docsUrl: \"https://brave.com/search/api/\",\n    },\n    {\n      key: \"TAVILY_API_KEY\",\n      label: \"Tavily API Key\",\n      description:\n        \"Enables the web-search agent tool via Tavily. Used as fallback when BRAVE_SEARCH_API_KEY is not set and before Builder-managed search.\",\n      docsUrl: \"https://tavily.com/\",\n    },\n    {\n      key: \"EXA_API_KEY\",\n      label: \"Exa API Key\",\n      description:\n        \"Enables the web-search agent tool via Exa. Used as fallback when Brave and Tavily are not set and before Builder-managed search.\",\n      docsUrl: \"https://exa.ai/\",\n    },\n  ];\n\n  for (const entry of webSearchKeys) {\n    if (!getRequiredSecret(entry.key)) {\n      registerRequiredSecret({\n        key: entry.key,\n        label: entry.label,\n        description: entry.description,\n        docsUrl: entry.docsUrl,\n        scope: \"workspace\",\n        kind: \"api-key\",\n        required: false,\n      });\n    }\n  }\n\n  if (!getRequiredSecret(\"GITHUB_TOKEN\")) {\n    registerRequiredSecret({\n      key: \"GITHUB_TOKEN\",\n      label: \"GitHub token\",\n      description:\n        \"Enables connector-scoped repository file reads and writes for headless/cloud agent runs.\",\n      docsUrl:\n        \"https://docs.github.com/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens\",\n      scope: \"workspace\",\n      kind: \"api-key\",\n      required: false,\n    });\n  }\n}\n"]}
+{"version":3,"file":"register-framework-secrets.js","sourceRoot":"","sources":["../../src/secrets/register-framework-secrets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,iBAAiB,EAAE,sBAAsB,EAAE,MAAM,eAAe,CAAC;AAE1E,MAAM,UAAU,wBAAwB;IACtC,kEAAkE;IAClE,0EAA0E;IAC1E,MAAM,aAAa,GAKd;QACH;YACE,GAAG,EAAE,sBAAsB;YAC3B,KAAK,EAAE,sBAAsB;YAC7B,WAAW,EACT,mHAAmH;YACrH,OAAO,EAAE,+BAA+B;SACzC;QACD;YACE,GAAG,EAAE,gBAAgB;YACrB,KAAK,EAAE,gBAAgB;YACvB,WAAW,EACT,wIAAwI;YAC1I,OAAO,EAAE,qBAAqB;SAC/B;QACD;YACE,GAAG,EAAE,aAAa;YAClB,KAAK,EAAE,aAAa;YACpB,WAAW,EACT,kIAAkI;YACpI,OAAO,EAAE,iBAAiB;SAC3B;QACD;YACE,GAAG,EAAE,mBAAmB;YACxB,KAAK,EAAE,mBAAmB;YAC1B,WAAW,EACT,8IAA8I;YAChJ,OAAO,EAAE,wBAAwB;SAClC;KACF,CAAC;IAEF,KAAK,MAAM,KAAK,IAAI,aAAa,EAAE,CAAC;QAClC,IAAI,CAAC,iBAAiB,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;YAClC,sBAAsB,CAAC;gBACrB,GAAG,EAAE,KAAK,CAAC,GAAG;gBACd,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,KAAK,EAAE,WAAW;gBAClB,IAAI,EAAE,SAAS;gBACf,QAAQ,EAAE,KAAK;aAChB,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,IAAI,CAAC,iBAAiB,CAAC,cAAc,CAAC,EAAE,CAAC;QACvC,sBAAsB,CAAC;YACrB,GAAG,EAAE,cAAc;YACnB,KAAK,EAAE,cAAc;YACrB,WAAW,EACT,0FAA0F;YAC5F,OAAO,EACL,kHAAkH;YACpH,KAAK,EAAE,WAAW;YAClB,IAAI,EAAE,SAAS;YACf,QAAQ,EAAE,KAAK;SAChB,CAAC,CAAC;IACL,CAAC;AACH,CAAC","sourcesContent":["/**\n * Framework-level secret registrations.\n *\n * Side-effect module — imported by the core-routes plugin at boot so the\n * sidebar settings UI and the `/_agent-native/secrets` list route surface the\n * relevant keys in every template.\n *\n * Each call uses a `getRequiredSecret` guard so a template that has already\n * registered the same key (often with stricter settings like `required: true`)\n * wins — the framework registration is a fallback, not an override.\n *\n * NOTE: The framework previously registered OPENAI_API_KEY here for Whisper\n * voice transcription. Voice transcription now routes through the Builder.io\n * gateway (or Groq as a BYOK fallback), so the framework no longer registers\n * the OpenAI key. Templates that need it (e.g. Clips) register it themselves.\n */\n\nimport { getRequiredSecret, registerRequiredSecret } from \"./register.js\";\n\nexport function registerFrameworkSecrets(): void {\n  // Web-search tool backends — optional; the tool selects the first\n  // configured manual key at call time, then falls back to Builder Connect.\n  const webSearchKeys: Array<{\n    key: string;\n    label: string;\n    description: string;\n    docsUrl: string;\n  }> = [\n    {\n      key: \"BRAVE_SEARCH_API_KEY\",\n      label: \"Brave Search API Key\",\n      description:\n        \"Enables the web-search agent tool via Brave Search. Optional when Builder.io is connected for managed web search.\",\n      docsUrl: \"https://brave.com/search/api/\",\n    },\n    {\n      key: \"TAVILY_API_KEY\",\n      label: \"Tavily API Key\",\n      description:\n        \"Enables the web-search agent tool via Tavily. Used as fallback when BRAVE_SEARCH_API_KEY is not set and before Builder-managed search.\",\n      docsUrl: \"https://tavily.com/\",\n    },\n    {\n      key: \"EXA_API_KEY\",\n      label: \"Exa API Key\",\n      description:\n        \"Enables the web-search agent tool via Exa. Used as fallback when Brave and Tavily are not set and before Builder-managed search.\",\n      docsUrl: \"https://exa.ai/\",\n    },\n    {\n      key: \"FIRECRAWL_API_KEY\",\n      label: \"Firecrawl API Key\",\n      description:\n        \"Enables the web-search agent tool via Firecrawl. Used as fallback when Brave, Tavily, and Exa are not set and before Builder-managed search.\",\n      docsUrl: \"https://firecrawl.dev/\",\n    },\n  ];\n\n  for (const entry of webSearchKeys) {\n    if (!getRequiredSecret(entry.key)) {\n      registerRequiredSecret({\n        key: entry.key,\n        label: entry.label,\n        description: entry.description,\n        docsUrl: entry.docsUrl,\n        scope: \"workspace\",\n        kind: \"api-key\",\n        required: false,\n      });\n    }\n  }\n\n  if (!getRequiredSecret(\"GITHUB_TOKEN\")) {\n    registerRequiredSecret({\n      key: \"GITHUB_TOKEN\",\n      label: \"GitHub token\",\n      description:\n        \"Enables connector-scoped repository file reads and writes for headless/cloud agent runs.\",\n      docsUrl:\n        \"https://docs.github.com/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens\",\n      scope: \"workspace\",\n      kind: \"api-key\",\n      required: false,\n    });\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.68.3",
+  "version": "0.69.0",
   "type": "module",
   "engines": {
     "node": ">=22"