@greppleai/grip 0.0.0-stage → 0.1.3

package/dist/core/tools/truncate.js

@@ -0,0 +1,215 @@
+/**
+ * Shared truncation utilities for tool outputs.
+ *
+ * Truncation is based on two independent limits - whichever is hit first wins:
+ * - Line limit (default: 2000 lines)
+ * - Byte limit (default: 50KB)
+ *
+ * Never returns partial lines (except bash tail truncation edge case).
+ */
+export const DEFAULT_MAX_LINES = 2000;
+export const DEFAULT_MAX_BYTES = 50 * 1024; // 50KB
+export const GREP_MAX_LINE_LENGTH = 500; // Max chars per grep match line
+function splitLinesForCounting(content) {
+    if (content.length === 0) {
+        return [];
+    }
+    const lines = content.split("\n");
+    if (content.endsWith("\n")) {
+        lines.pop();
+    }
+    return lines;
+}
+/**
+ * Format bytes as human-readable size.
+ */
+export function formatSize(bytes) {
+    if (bytes < 1024) {
+        return `${bytes}B`;
+    }
+    else if (bytes < 1024 * 1024) {
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    }
+    else {
+        return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+    }
+}
+/**
+ * Truncate content from the head (keep first N lines/bytes).
+ * Suitable for file reads where you want to see the beginning.
+ *
+ * Never returns partial lines. If first line exceeds byte limit,
+ * returns empty content with firstLineExceedsLimit=true.
+ */
+export function truncateHead(content, options = {}) {
+    const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const totalBytes = Buffer.byteLength(content, "utf-8");
+    const lines = splitLinesForCounting(content);
+    const totalLines = lines.length;
+    // Check if no truncation needed
+    if (totalLines <= maxLines && totalBytes <= maxBytes) {
+        return {
+            content,
+            truncated: false,
+            truncatedBy: null,
+            totalLines,
+            totalBytes,
+            outputLines: totalLines,
+            outputBytes: totalBytes,
+            lastLinePartial: false,
+            firstLineExceedsLimit: false,
+            maxLines,
+            maxBytes,
+        };
+    }
+    // Check if first line alone exceeds byte limit
+    const firstLineBytes = Buffer.byteLength(lines[0], "utf-8");
+    if (firstLineBytes > maxBytes) {
+        return {
+            content: "",
+            truncated: true,
+            truncatedBy: "bytes",
+            totalLines,
+            totalBytes,
+            outputLines: 0,
+            outputBytes: 0,
+            lastLinePartial: false,
+            firstLineExceedsLimit: true,
+            maxLines,
+            maxBytes,
+        };
+    }
+    // Collect complete lines that fit
+    const outputLinesArr = [];
+    let outputBytesCount = 0;
+    let truncatedBy = "lines";
+    for (let i = 0; i < lines.length && i < maxLines; i++) {
+        const line = lines[i];
+        const lineBytes = Buffer.byteLength(line, "utf-8") + (i > 0 ? 1 : 0); // +1 for newline
+        if (outputBytesCount + lineBytes > maxBytes) {
+            truncatedBy = "bytes";
+            break;
+        }
+        outputLinesArr.push(line);
+        outputBytesCount += lineBytes;
+    }
+    // If we exited due to line limit
+    if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {
+        truncatedBy = "lines";
+    }
+    const outputContent = outputLinesArr.join("\n");
+    const finalOutputBytes = Buffer.byteLength(outputContent, "utf-8");
+    return {
+        content: outputContent,
+        truncated: true,
+        truncatedBy,
+        totalLines,
+        totalBytes,
+        outputLines: outputLinesArr.length,
+        outputBytes: finalOutputBytes,
+        lastLinePartial: false,
+        firstLineExceedsLimit: false,
+        maxLines,
+        maxBytes,
+    };
+}
+/**
+ * Truncate content from the tail (keep last N lines/bytes).
+ * Suitable for bash output where you want to see the end (errors, final results).
+ *
+ * May return partial first line if the last line of original content exceeds byte limit.
+ */
+export function truncateTail(content, options = {}) {
+    const maxLines = options.maxLines ?? DEFAULT_MAX_LINES;
+    const maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;
+    const totalBytes = Buffer.byteLength(content, "utf-8");
+    const lines = splitLinesForCounting(content);
+    const totalLines = lines.length;
+    // Check if no truncation needed
+    if (totalLines <= maxLines && totalBytes <= maxBytes) {
+        return {
+            content,
+            truncated: false,
+            truncatedBy: null,
+            totalLines,
+            totalBytes,
+            outputLines: totalLines,
+            outputBytes: totalBytes,
+            lastLinePartial: false,
+            firstLineExceedsLimit: false,
+            maxLines,
+            maxBytes,
+        };
+    }
+    // Work backwards from the end
+    const outputLinesArr = [];
+    let outputBytesCount = 0;
+    let truncatedBy = "lines";
+    let lastLinePartial = false;
+    for (let i = lines.length - 1; i >= 0 && outputLinesArr.length < maxLines; i--) {
+        const line = lines[i];
+        const lineBytes = Buffer.byteLength(line, "utf-8") + (outputLinesArr.length > 0 ? 1 : 0); // +1 for newline
+        if (outputBytesCount + lineBytes > maxBytes) {
+            truncatedBy = "bytes";
+            // Edge case: if we haven't added ANY lines yet and this line exceeds maxBytes,
+            // take the end of the line (partial)
+            if (outputLinesArr.length === 0) {
+                const truncatedLine = truncateStringToBytesFromEnd(line, maxBytes);
+                outputLinesArr.unshift(truncatedLine);
+                outputBytesCount = Buffer.byteLength(truncatedLine, "utf-8");
+                lastLinePartial = true;
+            }
+            break;
+        }
+        outputLinesArr.unshift(line);
+        outputBytesCount += lineBytes;
+    }
+    // If we exited due to line limit
+    if (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {
+        truncatedBy = "lines";
+    }
+    const outputContent = outputLinesArr.join("\n");
+    const finalOutputBytes = Buffer.byteLength(outputContent, "utf-8");
+    return {
+        content: outputContent,
+        truncated: true,
+        truncatedBy,
+        totalLines,
+        totalBytes,
+        outputLines: outputLinesArr.length,
+        outputBytes: finalOutputBytes,
+        lastLinePartial,
+        firstLineExceedsLimit: false,
+        maxLines,
+        maxBytes,
+    };
+}
+/**
+ * Truncate a string to fit within a byte limit (from the end).
+ * Handles multi-byte UTF-8 characters correctly.
+ */
+function truncateStringToBytesFromEnd(str, maxBytes) {
+    const buf = Buffer.from(str, "utf-8");
+    if (buf.length <= maxBytes) {
+        return str;
+    }
+    // Start from the end, skip maxBytes back
+    let start = buf.length - maxBytes;
+    // Find a valid UTF-8 boundary (start of a character)
+    while (start < buf.length && (buf[start] & 0xc0) === 0x80) {
+        start++;
+    }
+    return buf.slice(start).toString("utf-8");
+}
+/**
+ * Truncate a single line to max characters, adding [truncated] suffix.
+ * Used for grep match lines.
+ */
+export function truncateLine(line, maxChars = GREP_MAX_LINE_LENGTH) {
+    if (line.length <= maxChars) {
+        return { text: line, wasTruncated: false };
+    }
+    return { text: `${line.slice(0, maxChars)}... [truncated]`, wasTruncated: true };
+}
+//# sourceMappingURL=truncate.js.map

package/dist/core/tools/truncate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncate.js","sourceRoot":"","sources":["../../../src/core/tools/truncate.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Shared truncation utilities for tool outputs.\n *\n * Truncation is based on two independent limits - whichever is hit first wins:\n * - Line limit (default: 2000 lines)\n * - Byte limit (default: 50KB)\n *\n * Never returns partial lines (except bash tail truncation edge case).\n */\n\nimport type { LineTruncationResult, TruncationOptions, TruncationResult } from \"@greppleai/grip-agent-core\";\n\nexport type { TruncationOptions, TruncationResult };\nexport const DEFAULT_MAX_LINES = 2000;\nexport const DEFAULT_MAX_BYTES = 50 * 1024; // 50KB\nexport const GREP_MAX_LINE_LENGTH = 500; // Max chars per grep match line\n\nfunction splitLinesForCounting(content: string): string[] {\n\tif (content.length === 0) {\n\t\treturn [];\n\t}\n\tconst lines = content.split(\"\\n\");\n\tif (content.endsWith(\"\\n\")) {\n\t\tlines.pop();\n\t}\n\treturn lines;\n}\n\n/**\n * Format bytes as human-readable size.\n */\nexport function formatSize(bytes: number): string {\n\tif (bytes < 1024) {\n\t\treturn `${bytes}B`;\n\t} else if (bytes < 1024 * 1024) {\n\t\treturn `${(bytes / 1024).toFixed(1)}KB`;\n\t} else {\n\t\treturn `${(bytes / (1024 * 1024)).toFixed(1)}MB`;\n\t}\n}\n\n/**\n * Truncate content from the head (keep first N lines/bytes).\n * Suitable for file reads where you want to see the beginning.\n *\n * Never returns partial lines. If first line exceeds byte limit,\n * returns empty content with firstLineExceedsLimit=true.\n */\nexport function truncateHead(content: string, options: TruncationOptions = {}): TruncationResult {\n\tconst maxLines = options.maxLines ?? DEFAULT_MAX_LINES;\n\tconst maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;\n\n\tconst totalBytes = Buffer.byteLength(content, \"utf-8\");\n\tconst lines = splitLinesForCounting(content);\n\tconst totalLines = lines.length;\n\n\t// Check if no truncation needed\n\tif (totalLines <= maxLines && totalBytes <= maxBytes) {\n\t\treturn {\n\t\t\tcontent,\n\t\t\ttruncated: false,\n\t\t\ttruncatedBy: null,\n\t\t\ttotalLines,\n\t\t\ttotalBytes,\n\t\t\toutputLines: totalLines,\n\t\t\toutputBytes: totalBytes,\n\t\t\tlastLinePartial: false,\n\t\t\tfirstLineExceedsLimit: false,\n\t\t\tmaxLines,\n\t\t\tmaxBytes,\n\t\t};\n\t}\n\n\t// Check if first line alone exceeds byte limit\n\tconst firstLineBytes = Buffer.byteLength(lines[0], \"utf-8\");\n\tif (firstLineBytes > maxBytes) {\n\t\treturn {\n\t\t\tcontent: \"\",\n\t\t\ttruncated: true,\n\t\t\ttruncatedBy: \"bytes\",\n\t\t\ttotalLines,\n\t\t\ttotalBytes,\n\t\t\toutputLines: 0,\n\t\t\toutputBytes: 0,\n\t\t\tlastLinePartial: false,\n\t\t\tfirstLineExceedsLimit: true,\n\t\t\tmaxLines,\n\t\t\tmaxBytes,\n\t\t};\n\t}\n\n\t// Collect complete lines that fit\n\tconst outputLinesArr: string[] = [];\n\tlet outputBytesCount = 0;\n\tlet truncatedBy: \"lines\" | \"bytes\" = \"lines\";\n\n\tfor (let i = 0; i < lines.length && i < maxLines; i++) {\n\t\tconst line = lines[i];\n\t\tconst lineBytes = Buffer.byteLength(line, \"utf-8\") + (i > 0 ? 1 : 0); // +1 for newline\n\n\t\tif (outputBytesCount + lineBytes > maxBytes) {\n\t\t\ttruncatedBy = \"bytes\";\n\t\t\tbreak;\n\t\t}\n\n\t\toutputLinesArr.push(line);\n\t\toutputBytesCount += lineBytes;\n\t}\n\n\t// If we exited due to line limit\n\tif (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {\n\t\ttruncatedBy = \"lines\";\n\t}\n\n\tconst outputContent = outputLinesArr.join(\"\\n\");\n\tconst finalOutputBytes = Buffer.byteLength(outputContent, \"utf-8\");\n\n\treturn {\n\t\tcontent: outputContent,\n\t\ttruncated: true,\n\t\ttruncatedBy,\n\t\ttotalLines,\n\t\ttotalBytes,\n\t\toutputLines: outputLinesArr.length,\n\t\toutputBytes: finalOutputBytes,\n\t\tlastLinePartial: false,\n\t\tfirstLineExceedsLimit: false,\n\t\tmaxLines,\n\t\tmaxBytes,\n\t};\n}\n\n/**\n * Truncate content from the tail (keep last N lines/bytes).\n * Suitable for bash output where you want to see the end (errors, final results).\n *\n * May return partial first line if the last line of original content exceeds byte limit.\n */\nexport function truncateTail(content: string, options: TruncationOptions = {}): TruncationResult {\n\tconst maxLines = options.maxLines ?? DEFAULT_MAX_LINES;\n\tconst maxBytes = options.maxBytes ?? DEFAULT_MAX_BYTES;\n\n\tconst totalBytes = Buffer.byteLength(content, \"utf-8\");\n\tconst lines = splitLinesForCounting(content);\n\tconst totalLines = lines.length;\n\n\t// Check if no truncation needed\n\tif (totalLines <= maxLines && totalBytes <= maxBytes) {\n\t\treturn {\n\t\t\tcontent,\n\t\t\ttruncated: false,\n\t\t\ttruncatedBy: null,\n\t\t\ttotalLines,\n\t\t\ttotalBytes,\n\t\t\toutputLines: totalLines,\n\t\t\toutputBytes: totalBytes,\n\t\t\tlastLinePartial: false,\n\t\t\tfirstLineExceedsLimit: false,\n\t\t\tmaxLines,\n\t\t\tmaxBytes,\n\t\t};\n\t}\n\n\t// Work backwards from the end\n\tconst outputLinesArr: string[] = [];\n\tlet outputBytesCount = 0;\n\tlet truncatedBy: \"lines\" | \"bytes\" = \"lines\";\n\tlet lastLinePartial = false;\n\n\tfor (let i = lines.length - 1; i >= 0 && outputLinesArr.length < maxLines; i--) {\n\t\tconst line = lines[i];\n\t\tconst lineBytes = Buffer.byteLength(line, \"utf-8\") + (outputLinesArr.length > 0 ? 1 : 0); // +1 for newline\n\n\t\tif (outputBytesCount + lineBytes > maxBytes) {\n\t\t\ttruncatedBy = \"bytes\";\n\t\t\t// Edge case: if we haven't added ANY lines yet and this line exceeds maxBytes,\n\t\t\t// take the end of the line (partial)\n\t\t\tif (outputLinesArr.length === 0) {\n\t\t\t\tconst truncatedLine = truncateStringToBytesFromEnd(line, maxBytes);\n\t\t\t\toutputLinesArr.unshift(truncatedLine);\n\t\t\t\toutputBytesCount = Buffer.byteLength(truncatedLine, \"utf-8\");\n\t\t\t\tlastLinePartial = true;\n\t\t\t}\n\t\t\tbreak;\n\t\t}\n\n\t\toutputLinesArr.unshift(line);\n\t\toutputBytesCount += lineBytes;\n\t}\n\n\t// If we exited due to line limit\n\tif (outputLinesArr.length >= maxLines && outputBytesCount <= maxBytes) {\n\t\ttruncatedBy = \"lines\";\n\t}\n\n\tconst outputContent = outputLinesArr.join(\"\\n\");\n\tconst finalOutputBytes = Buffer.byteLength(outputContent, \"utf-8\");\n\n\treturn {\n\t\tcontent: outputContent,\n\t\ttruncated: true,\n\t\ttruncatedBy,\n\t\ttotalLines,\n\t\ttotalBytes,\n\t\toutputLines: outputLinesArr.length,\n\t\toutputBytes: finalOutputBytes,\n\t\tlastLinePartial,\n\t\tfirstLineExceedsLimit: false,\n\t\tmaxLines,\n\t\tmaxBytes,\n\t};\n}\n\n/**\n * Truncate a string to fit within a byte limit (from the end).\n * Handles multi-byte UTF-8 characters correctly.\n */\nfunction truncateStringToBytesFromEnd(str: string, maxBytes: number): string {\n\tconst buf = Buffer.from(str, \"utf-8\");\n\tif (buf.length <= maxBytes) {\n\t\treturn str;\n\t}\n\n\t// Start from the end, skip maxBytes back\n\tlet start = buf.length - maxBytes;\n\n\t// Find a valid UTF-8 boundary (start of a character)\n\twhile (start < buf.length && (buf[start] & 0xc0) === 0x80) {\n\t\tstart++;\n\t}\n\n\treturn buf.slice(start).toString(\"utf-8\");\n}\n\n/**\n * Truncate a single line to max characters, adding [truncated] suffix.\n * Used for grep match lines.\n */\nexport function truncateLine(line: string, maxChars: number = GREP_MAX_LINE_LENGTH): LineTruncationResult {\n\tif (line.length <= maxChars) {\n\t\treturn { text: line, wasTruncated: false };\n\t}\n\treturn { text: `${line.slice(0, maxChars)}... [truncated]`, wasTruncated: true };\n}\n"]}

package/dist/core/tools/websearch.d.ts

@@ -0,0 +1,33 @@
+import type { AgentTool } from "@greppleai/grip-agent-core";
+import { type Static, Type } from "typebox";
+import type { ToolDefinition } from "../extensions/types.ts";
+export type WebsearchProvider = "duckduckgo" | "duckduckgo-instant-answer" | "brave" | "brave-search" | "firecrawl" | "firecrawl-search";
+export interface WebsearchToolOptions {
+    provider?: WebsearchProvider;
+    apiKey?: string;
+    baseUrl?: string;
+}
+declare const websearchSchema: Type.TObject<{
+    query: Type.TString;
+    limit: Type.TOptional<Type.TNumber>;
+}>;
+export type WebsearchToolInput = Static<typeof websearchSchema>;
+export type WebsearchSource = "duckduckgo-instant-answer" | "brave-search" | "firecrawl-search";
+export interface WebsearchResultItem {
+    title: string;
+    url: string;
+    snippet?: string;
+}
+export interface WebsearchToolDetails {
+    query: string;
+    results: WebsearchResultItem[];
+    source: WebsearchSource;
+}
+export declare function parseWebsearchToolOptions(value: unknown): WebsearchToolOptions | undefined;
+export declare function parseDuckDuckGoResponse(data: unknown, limit: number): WebsearchResultItem[];
+export declare function parseBraveSearchResponse(data: unknown, limit: number): WebsearchResultItem[];
+export declare function parseFirecrawlSearchResponse(data: unknown, limit: number): WebsearchResultItem[];
+export declare function createWebsearchToolDefinition(options?: WebsearchToolOptions): ToolDefinition<typeof websearchSchema, WebsearchToolDetails>;
+export declare function createWebsearchTool(options?: WebsearchToolOptions): AgentTool<typeof websearchSchema>;
+export {};
+//# sourceMappingURL=websearch.d.ts.map

package/dist/core/tools/websearch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"websearch.d.ts","sourceRoot":"","sources":["../../../src/core/tools/websearch.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,4BAA4B,CAAC;AAE5D,OAAO,EAAE,KAAK,MAAM,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAA2B,MAAM,wBAAwB,CAAC;AAatF,MAAM,MAAM,iBAAiB,GAC1B,YAAY,GACZ,2BAA2B,GAC3B,OAAO,GACP,cAAc,GACd,WAAW,GACX,kBAAkB,CAAC;AAEtB,MAAM,WAAW,oBAAoB;IACpC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;IAC7B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,QAAA,MAAM,eAAe;;;EAKnB,CAAC;AAEH,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,eAAe,CAAC,CAAC;AAEhE,MAAM,MAAM,eAAe,GAAG,2BAA2B,GAAG,cAAc,GAAG,kBAAkB,CAAC;AAEhG,MAAM,WAAW,mBAAmB;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACpC,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,mBAAmB,EAAE,CAAC;IAC/B,MAAM,EAAE,eAAe,CAAC;CACxB;AAoCD,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,oBAAoB,GAAG,SAAS,CA2B1F;AAmDD,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAoB3F;AAED,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAqB5F;AAED,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,mBAAmB,EAAE,CAsBhG;AAoKD,wBAAgB,6BAA6B,CAC5C,OAAO,CAAC,EAAE,oBAAoB,GAC5B,cAAc,CAAC,OAAO,eAAe,EAAE,oBAAoB,CAAC,CAiD9D;AAED,wBAAgB,mBAAmB,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,SAAS,CAAC,OAAO,eAAe,CAAC,CAErG","sourcesContent":["import type { AgentTool } from \"@greppleai/grip-agent-core\";\nimport { Text } from \"@greppleai/grip-tui\";\nimport { type Static, Type } from \"typebox\";\nimport type { ToolDefinition, ToolRenderResultOptions } from \"../extensions/types.ts\";\nimport { getTextOutput, invalidArgText, str, type ToolTextOutputContent } from \"./render-utils.ts\";\nimport { wrapToolDefinition } from \"./tool-definition-wrapper.ts\";\n\ninterface RenderTheme {\n\tbold(value: string): string;\n\tfg(role: string, value: string): string;\n}\n\nconst DEFAULT_LIMIT = 8;\nconst MAX_LIMIT = 20;\nconst REQUEST_TIMEOUT_MS = 10_000;\n\nexport type WebsearchProvider =\n\t| \"duckduckgo\"\n\t| \"duckduckgo-instant-answer\"\n\t| \"brave\"\n\t| \"brave-search\"\n\t| \"firecrawl\"\n\t| \"firecrawl-search\";\n\nexport interface WebsearchToolOptions {\n\tprovider?: WebsearchProvider;\n\tapiKey?: string;\n\tbaseUrl?: string;\n}\n\nconst websearchSchema = Type.Object({\n\tquery: Type.String({ description: \"Search query\" }),\n\tlimit: Type.Optional(\n\t\tType.Number({ description: `Maximum number of links to return (default ${DEFAULT_LIMIT}, max ${MAX_LIMIT})` }),\n\t),\n});\n\nexport type WebsearchToolInput = Static<typeof websearchSchema>;\n\nexport type WebsearchSource = \"duckduckgo-instant-answer\" | \"brave-search\" | \"firecrawl-search\";\n\nexport interface WebsearchResultItem {\n\ttitle: string;\n\turl: string;\n\tsnippet?: string;\n}\n\nexport interface WebsearchToolDetails {\n\tquery: string;\n\tresults: WebsearchResultItem[];\n\tsource: WebsearchSource;\n}\n\ninterface WebsearchCallArguments {\n\tquery?: string;\n\tlimit?: number;\n}\n\ninterface WebsearchRenderResult {\n\tcontent: ToolTextOutputContent[];\n\tdetails?: WebsearchToolDetails;\n}\n\ninterface DuckDuckGoTopic {\n\tFirstURL?: unknown;\n\tText?: unknown;\n\tName?: unknown;\n\tTopics?: unknown;\n}\n\ninterface BraveSearchResult {\n\ttitle?: unknown;\n\turl?: unknown;\n\tdescription?: unknown;\n}\n\ninterface FirecrawlSearchResult {\n\ttitle?: unknown;\n\turl?: unknown;\n\tdescription?: unknown;\n\tmarkdown?: unknown;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null;\n}\n\nexport function parseWebsearchToolOptions(value: unknown): WebsearchToolOptions | undefined {\n\tif (value === undefined) return undefined;\n\tif (!isRecord(value)) throw new Error(\"tools.websearch must be an object\");\n\tconst options: WebsearchToolOptions = {};\n\n\tconst provider = asString(value.provider);\n\tif (provider !== undefined) {\n\t\tif (\n\t\t\tprovider !== \"duckduckgo\" &&\n\t\t\tprovider !== \"duckduckgo-instant-answer\" &&\n\t\t\tprovider !== \"brave\" &&\n\t\t\tprovider !== \"brave-search\" &&\n\t\t\tprovider !== \"firecrawl\" &&\n\t\t\tprovider !== \"firecrawl-search\"\n\t\t) {\n\t\t\tthrow new Error(`Invalid tools.websearch.provider: ${provider}`);\n\t\t}\n\t\toptions.provider = provider;\n\t}\n\n\tconst apiKey = asString(value.apiKey);\n\tif (apiKey !== undefined) options.apiKey = apiKey;\n\n\tconst baseUrl = asString(value.baseUrl);\n\tif (baseUrl !== undefined) options.baseUrl = baseUrl;\n\n\treturn options;\n}\n\nfunction asString(value: unknown): string | undefined {\n\treturn typeof value === \"string\" && value.trim() ? value.trim() : undefined;\n}\n\nfunction stripHtml(value: string): string {\n\treturn value\n\t\t.replace(/<[^>]*>/g, \"\")\n\t\t.replace(/\\s+/g, \" \")\n\t\t.trim();\n}\n\nfunction titleFromText(text: string): string {\n\tconst separator = text.indexOf(\" - \");\n\treturn (separator > 0 ? text.slice(0, separator) : text).trim();\n}\n\nfunction pushResult(results: WebsearchResultItem[], seen: Set<string>, item: WebsearchResultItem): void {\n\tconst url = item.url.trim();\n\tif (!url || seen.has(url)) return;\n\tseen.add(url);\n\tresults.push({ ...item, url });\n}\n\nfunction collectRelatedTopics(value: unknown, results: WebsearchResultItem[], seen: Set<string>, limit: number): void {\n\tif (results.length >= limit) return;\n\tif (!Array.isArray(value)) return;\n\n\tfor (const entry of value) {\n\t\tif (results.length >= limit) return;\n\t\tif (!isRecord(entry)) continue;\n\t\tconst topic = entry as DuckDuckGoTopic;\n\t\tconst nestedTopics = topic.Topics;\n\t\tif (Array.isArray(nestedTopics)) {\n\t\t\tcollectRelatedTopics(nestedTopics, results, seen, limit);\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst url = asString(topic.FirstURL);\n\t\tconst rawText = asString(topic.Text) ?? asString(topic.Name);\n\t\tif (!url || !rawText) continue;\n\t\tconst text = stripHtml(rawText);\n\t\tpushResult(results, seen, {\n\t\t\ttitle: titleFromText(text),\n\t\t\turl,\n\t\t\tsnippet: text,\n\t\t});\n\t}\n}\n\nexport function parseDuckDuckGoResponse(data: unknown, limit: number): WebsearchResultItem[] {\n\tconst results: WebsearchResultItem[] = [];\n\tconst seen = new Set<string>();\n\tif (!isRecord(data)) return results;\n\n\tconst heading = asString(data.Heading);\n\tconst abstractUrl = asString(data.AbstractURL);\n\tconst abstractText = asString(data.AbstractText) ?? asString(data.Abstract);\n\tif (abstractUrl && (heading || abstractText)) {\n\t\tpushResult(results, seen, {\n\t\t\ttitle: heading ?? titleFromText(stripHtml(abstractText ?? abstractUrl)),\n\t\t\turl: abstractUrl,\n\t\t\tsnippet: abstractText ? stripHtml(abstractText) : undefined,\n\t\t});\n\t}\n\n\tcollectRelatedTopics(data.RelatedTopics, results, seen, limit);\n\tcollectRelatedTopics(data.Results, results, seen, limit);\n\n\treturn results.slice(0, limit);\n}\n\nexport function parseBraveSearchResponse(data: unknown, limit: number): WebsearchResultItem[] {\n\tconst results: WebsearchResultItem[] = [];\n\tconst seen = new Set<string>();\n\tif (!isRecord(data) || !isRecord(data.web) || !Array.isArray(data.web.results)) return results;\n\n\tfor (const entry of data.web.results) {\n\t\tif (results.length >= limit) break;\n\t\tif (!isRecord(entry)) continue;\n\t\tconst item = entry as BraveSearchResult;\n\t\tconst title = asString(item.title);\n\t\tconst url = asString(item.url);\n\t\tif (!title || !url) continue;\n\t\tconst description = asString(item.description);\n\t\tpushResult(results, seen, {\n\t\t\ttitle: stripHtml(title),\n\t\t\turl,\n\t\t\tsnippet: description ? stripHtml(description) : undefined,\n\t\t});\n\t}\n\n\treturn results;\n}\n\nexport function parseFirecrawlSearchResponse(data: unknown, limit: number): WebsearchResultItem[] {\n\tconst results: WebsearchResultItem[] = [];\n\tconst seen = new Set<string>();\n\tif (!isRecord(data) || !isRecord(data.data) || !Array.isArray(data.data.web)) return results;\n\n\tfor (const entry of data.data.web) {\n\t\tif (results.length >= limit) break;\n\t\tif (!isRecord(entry)) continue;\n\t\tconst item = entry as FirecrawlSearchResult;\n\t\tconst title = asString(item.title);\n\t\tconst url = asString(item.url);\n\t\tif (!title || !url) continue;\n\t\tconst description = asString(item.description);\n\t\tconst markdown = asString(item.markdown);\n\t\tpushResult(results, seen, {\n\t\t\ttitle: stripHtml(title),\n\t\t\turl,\n\t\t\tsnippet: description ? stripHtml(description) : markdown ? stripHtml(markdown).slice(0, 500) : undefined,\n\t\t});\n\t}\n\n\treturn results;\n}\n\nfunction formatSourceName(source: WebsearchSource): string {\n\tswitch (source) {\n\t\tcase \"brave-search\":\n\t\t\treturn \"Brave Search\";\n\t\tcase \"firecrawl-search\":\n\t\t\treturn \"Firecrawl\";\n\t\tcase \"duckduckgo-instant-answer\":\n\t\t\treturn \"DuckDuckGo\";\n\t}\n}\n\nfunction formatResults(query: string, results: WebsearchResultItem[], source: WebsearchSource): string {\n\tif (results.length === 0) {\n\t\treturn `No ${formatSourceName(source)} links found for: ${query}`;\n\t}\n\treturn results\n\t\t.map((result, index) => {\n\t\t\tconst lines = [`${index + 1}. ${result.title}`, `   ${result.url}`];\n\t\t\tif (result.snippet) lines.push(`   ${result.snippet}`);\n\t\t\treturn lines.join(\"\\n\");\n\t\t})\n\t\t.join(\"\\n\\n\");\n}\n\nfunction resolveLimit(limit: number | undefined): number {\n\tif (limit === undefined) return DEFAULT_LIMIT;\n\tif (!Number.isFinite(limit) || limit <= 0) return DEFAULT_LIMIT;\n\treturn Math.min(MAX_LIMIT, Math.floor(limit));\n}\n\nfunction formatWebsearchCall(args: WebsearchCallArguments | undefined, theme: RenderTheme): string {\n\tconst query = str(args?.query);\n\tconst invalidArg = invalidArgText(theme);\n\tlet text = `${theme.fg(\"toolTitle\", theme.bold(\"websearch\"))} ${query === null ? invalidArg : theme.fg(\"accent\", query)}`;\n\tif (args?.limit !== undefined) text += theme.fg(\"toolOutput\", ` (limit ${args.limit})`);\n\treturn text;\n}\n\nfunction formatWebsearchResult(\n\tresult: WebsearchRenderResult,\n\toptions: ToolRenderResultOptions,\n\ttheme: RenderTheme,\n\tshowImages: boolean,\n): string {\n\tconst output = getTextOutput(result, showImages).trim();\n\tif (!output) return \"\";\n\tconst lines = output.split(\"\\n\");\n\tconst maxLines = options.expanded ? lines.length : 24;\n\tconst displayed = lines.slice(0, maxLines).map((line) => theme.fg(\"toolOutput\", line));\n\tconst remaining = lines.length - maxLines;\n\treturn remaining > 0\n\t\t? `${displayed.join(\"\\n\")}\\n${theme.fg(\"muted\", `... (${remaining} more lines)`)}`\n\t\t: displayed.join(\"\\n\");\n}\nfunction resolveWebsearchProvider(options?: WebsearchToolOptions): WebsearchSource {\n\tconst configured =\n\t\toptions?.provider?.trim().toLowerCase() ?? process.env.GRIP_WEBSEARCH_PROVIDER?.trim().toLowerCase();\n\tif (!configured) {\n\t\tif (process.env.GRIP_WEBSEARCH_FIRECRAWL_API_KEY || process.env.FIRECRAWL_API_KEY) return \"firecrawl-search\";\n\t\tif (options?.apiKey || process.env.GRIP_WEBSEARCH_BRAVE_API_KEY || process.env.BRAVE_SEARCH_API_KEY)\n\t\t\treturn \"brave-search\";\n\t}\n\tif (!configured || configured === \"duckduckgo\" || configured === \"duckduckgo-instant-answer\") {\n\t\treturn \"duckduckgo-instant-answer\";\n\t}\n\tif (configured === \"brave\" || configured === \"brave-search\") return \"brave-search\";\n\tif (configured === \"firecrawl\" || configured === \"firecrawl-search\") return \"firecrawl-search\";\n\tthrow new Error(`Unsupported websearch provider: ${configured}`);\n}\n\nfunction resolveBraveApiKey(options?: WebsearchToolOptions): string {\n\tconst key = options?.apiKey ?? process.env.GRIP_WEBSEARCH_BRAVE_API_KEY ?? process.env.BRAVE_SEARCH_API_KEY;\n\tif (!key?.trim()) {\n\t\tthrow new Error(\n\t\t\t\"Brave websearch requires tools.websearch.apiKey, GRIP_WEBSEARCH_BRAVE_API_KEY, or BRAVE_SEARCH_API_KEY\",\n\t\t);\n\t}\n\treturn key.trim();\n}\n\nfunction resolveFirecrawlApiKey(options?: WebsearchToolOptions): string {\n\tconst key = options?.apiKey ?? process.env.GRIP_WEBSEARCH_FIRECRAWL_API_KEY ?? process.env.FIRECRAWL_API_KEY;\n\tif (!key?.trim()) {\n\t\tthrow new Error(\n\t\t\t\"Firecrawl websearch requires tools.websearch.apiKey, GRIP_WEBSEARCH_FIRECRAWL_API_KEY, or FIRECRAWL_API_KEY\",\n\t\t);\n\t}\n\treturn key.trim();\n}\n\nasync function fetchDuckDuckGoResults(\n\tquery: string,\n\tlimit: number,\n\tsignal: AbortSignal,\n): Promise<WebsearchResultItem[]> {\n\tconst url = new URL(\"https://api.duckduckgo.com/\");\n\turl.searchParams.set(\"q\", query);\n\turl.searchParams.set(\"format\", \"json\");\n\turl.searchParams.set(\"no_html\", \"1\");\n\turl.searchParams.set(\"skip_disambig\", \"1\");\n\n\tconst response = await fetch(url, {\n\t\theaders: { accept: \"application/json\", \"user-agent\": \"grip-coding-agent\" },\n\t\tsignal,\n\t});\n\tif (!response.ok) {\n\t\tthrow new Error(`DuckDuckGo request failed: ${response.status} ${response.statusText}`);\n\t}\n\treturn parseDuckDuckGoResponse((await response.json()) as unknown, limit);\n}\n\nasync function fetchBraveResults(\n\tquery: string,\n\tlimit: number,\n\tsignal: AbortSignal,\n\toptions?: WebsearchToolOptions,\n): Promise<WebsearchResultItem[]> {\n\tconst url = new URL(\n\t\toptions?.baseUrl ?? process.env.GRIP_WEBSEARCH_BRAVE_BASE_URL ?? \"https://api.search.brave.com/res/v1/web/search\",\n\t);\n\turl.searchParams.set(\"q\", query);\n\turl.searchParams.set(\"count\", String(limit));\n\n\tconst response = await fetch(url, {\n\t\theaders: {\n\t\t\taccept: \"application/json\",\n\t\t\t\"user-agent\": \"grip-coding-agent\",\n\t\t\t\"x-subscription-token\": resolveBraveApiKey(options),\n\t\t},\n\t\tsignal,\n\t});\n\tif (!response.ok) {\n\t\tthrow new Error(`Brave Search request failed: ${response.status} ${response.statusText}`);\n\t}\n\treturn parseBraveSearchResponse((await response.json()) as unknown, limit);\n}\n\nasync function fetchFirecrawlResults(\n\tquery: string,\n\tlimit: number,\n\tsignal: AbortSignal,\n\toptions?: WebsearchToolOptions,\n): Promise<WebsearchResultItem[]> {\n\tconst url = new URL(\n\t\toptions?.baseUrl ?? process.env.GRIP_WEBSEARCH_FIRECRAWL_BASE_URL ?? \"https://api.firecrawl.dev/v2/search\",\n\t);\n\tconst response = await fetch(url, {\n\t\tmethod: \"POST\",\n\t\theaders: {\n\t\t\taccept: \"application/json\",\n\t\t\t\"content-type\": \"application/json\",\n\t\t\t\"user-agent\": \"grip-coding-agent\",\n\t\t\tauthorization: `Bearer ${resolveFirecrawlApiKey(options)}`,\n\t\t},\n\t\tbody: JSON.stringify({ query, limit, sources: [{ type: \"web\" }] }),\n\t\tsignal,\n\t});\n\tif (!response.ok) {\n\t\tthrow new Error(`Firecrawl Search request failed: ${response.status} ${response.statusText}`);\n\t}\n\treturn parseFirecrawlSearchResponse((await response.json()) as unknown, limit);\n}\nexport function createWebsearchToolDefinition(\n\toptions?: WebsearchToolOptions,\n): ToolDefinition<typeof websearchSchema, WebsearchToolDetails> {\n\treturn {\n\t\tname: \"websearch\",\n\t\tlabel: \"websearch\",\n\t\tdescription:\n\t\t\t\"Search the web for relevant links using DuckDuckGo by default, or Brave Search/Firecrawl when configured. Returns titles, URLs, and snippets when available.\",\n\t\tpromptSnippet: \"Search the web for relevant links\",\n\t\tparameters: websearchSchema,\n\t\tasync execute(_toolCallId, { query, limit }: WebsearchToolInput, signal?: AbortSignal) {\n\t\t\tconst trimmedQuery = query.trim();\n\t\t\tif (!trimmedQuery) throw new Error(\"query is required\");\n\n\t\t\tconst effectiveLimit = resolveLimit(limit);\n\t\t\tconst controller = new AbortController();\n\t\t\tconst timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);\n\t\t\tconst onAbort = () => controller.abort();\n\t\t\tsignal?.addEventListener(\"abort\", onAbort, { once: true });\n\t\t\ttry {\n\t\t\t\tconst source = resolveWebsearchProvider(options);\n\t\t\t\tconst results = await (async () => {\n\t\t\t\t\tswitch (source) {\n\t\t\t\t\t\tcase \"brave-search\":\n\t\t\t\t\t\t\treturn fetchBraveResults(trimmedQuery, effectiveLimit, controller.signal, options);\n\t\t\t\t\t\tcase \"firecrawl-search\":\n\t\t\t\t\t\t\treturn fetchFirecrawlResults(trimmedQuery, effectiveLimit, controller.signal, options);\n\t\t\t\t\t\tcase \"duckduckgo-instant-answer\":\n\t\t\t\t\t\t\treturn fetchDuckDuckGoResults(trimmedQuery, effectiveLimit, controller.signal);\n\t\t\t\t\t}\n\t\t\t\t})();\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [{ type: \"text\", text: formatResults(trimmedQuery, results, source) }],\n\t\t\t\t\tdetails: { query: trimmedQuery, results, source },\n\t\t\t\t};\n\t\t\t} finally {\n\t\t\t\tclearTimeout(timeout);\n\t\t\t\tsignal?.removeEventListener(\"abort\", onAbort);\n\t\t\t}\n\t\t},\n\t\trenderCall(args, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(formatWebsearchCall(args as WebsearchCallArguments | undefined, theme));\n\t\t\treturn text;\n\t\t},\n\t\trenderResult(result, options, theme, context) {\n\t\t\tconst text = (context.lastComponent as Text | undefined) ?? new Text(\"\", 0, 0);\n\t\t\ttext.setText(formatWebsearchResult(result as WebsearchRenderResult, options, theme, context.showImages));\n\t\t\treturn text;\n\t\t},\n\t};\n}\n\nexport function createWebsearchTool(options?: WebsearchToolOptions): AgentTool<typeof websearchSchema> {\n\treturn wrapToolDefinition(createWebsearchToolDefinition(options));\n}\n"]}

package/dist/core/tools/websearch.js

@@ -0,0 +1,341 @@
+import { Text } from "@greppleai/grip-tui";
+import { Type } from "typebox";
+import { getTextOutput, invalidArgText, str } from "./render-utils.js";
+import { wrapToolDefinition } from "./tool-definition-wrapper.js";
+const DEFAULT_LIMIT = 8;
+const MAX_LIMIT = 20;
+const REQUEST_TIMEOUT_MS = 10_000;
+const websearchSchema = Type.Object({
+    query: Type.String({ description: "Search query" }),
+    limit: Type.Optional(Type.Number({ description: `Maximum number of links to return (default ${DEFAULT_LIMIT}, max ${MAX_LIMIT})` })),
+});
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+export function parseWebsearchToolOptions(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isRecord(value))
+        throw new Error("tools.websearch must be an object");
+    const options = {};
+    const provider = asString(value.provider);
+    if (provider !== undefined) {
+        if (provider !== "duckduckgo" &&
+            provider !== "duckduckgo-instant-answer" &&
+            provider !== "brave" &&
+            provider !== "brave-search" &&
+            provider !== "firecrawl" &&
+            provider !== "firecrawl-search") {
+            throw new Error(`Invalid tools.websearch.provider: ${provider}`);
+        }
+        options.provider = provider;
+    }
+    const apiKey = asString(value.apiKey);
+    if (apiKey !== undefined)
+        options.apiKey = apiKey;
+    const baseUrl = asString(value.baseUrl);
+    if (baseUrl !== undefined)
+        options.baseUrl = baseUrl;
+    return options;
+}
+function asString(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function stripHtml(value) {
+    return value
+        .replace(/<[^>]*>/g, "")
+        .replace(/\s+/g, " ")
+        .trim();
+}
+function titleFromText(text) {
+    const separator = text.indexOf(" - ");
+    return (separator > 0 ? text.slice(0, separator) : text).trim();
+}
+function pushResult(results, seen, item) {
+    const url = item.url.trim();
+    if (!url || seen.has(url))
+        return;
+    seen.add(url);
+    results.push({ ...item, url });
+}
+function collectRelatedTopics(value, results, seen, limit) {
+    if (results.length >= limit)
+        return;
+    if (!Array.isArray(value))
+        return;
+    for (const entry of value) {
+        if (results.length >= limit)
+            return;
+        if (!isRecord(entry))
+            continue;
+        const topic = entry;
+        const nestedTopics = topic.Topics;
+        if (Array.isArray(nestedTopics)) {
+            collectRelatedTopics(nestedTopics, results, seen, limit);
+            continue;
+        }
+        const url = asString(topic.FirstURL);
+        const rawText = asString(topic.Text) ?? asString(topic.Name);
+        if (!url || !rawText)
+            continue;
+        const text = stripHtml(rawText);
+        pushResult(results, seen, {
+            title: titleFromText(text),
+            url,
+            snippet: text,
+        });
+    }
+}
+export function parseDuckDuckGoResponse(data, limit) {
+    const results = [];
+    const seen = new Set();
+    if (!isRecord(data))
+        return results;
+    const heading = asString(data.Heading);
+    const abstractUrl = asString(data.AbstractURL);
+    const abstractText = asString(data.AbstractText) ?? asString(data.Abstract);
+    if (abstractUrl && (heading || abstractText)) {
+        pushResult(results, seen, {
+            title: heading ?? titleFromText(stripHtml(abstractText ?? abstractUrl)),
+            url: abstractUrl,
+            snippet: abstractText ? stripHtml(abstractText) : undefined,
+        });
+    }
+    collectRelatedTopics(data.RelatedTopics, results, seen, limit);
+    collectRelatedTopics(data.Results, results, seen, limit);
+    return results.slice(0, limit);
+}
+export function parseBraveSearchResponse(data, limit) {
+    const results = [];
+    const seen = new Set();
+    if (!isRecord(data) || !isRecord(data.web) || !Array.isArray(data.web.results))
+        return results;
+    for (const entry of data.web.results) {
+        if (results.length >= limit)
+            break;
+        if (!isRecord(entry))
+            continue;
+        const item = entry;
+        const title = asString(item.title);
+        const url = asString(item.url);
+        if (!title || !url)
+            continue;
+        const description = asString(item.description);
+        pushResult(results, seen, {
+            title: stripHtml(title),
+            url,
+            snippet: description ? stripHtml(description) : undefined,
+        });
+    }
+    return results;
+}
+export function parseFirecrawlSearchResponse(data, limit) {
+    const results = [];
+    const seen = new Set();
+    if (!isRecord(data) || !isRecord(data.data) || !Array.isArray(data.data.web))
+        return results;
+    for (const entry of data.data.web) {
+        if (results.length >= limit)
+            break;
+        if (!isRecord(entry))
+            continue;
+        const item = entry;
+        const title = asString(item.title);
+        const url = asString(item.url);
+        if (!title || !url)
+            continue;
+        const description = asString(item.description);
+        const markdown = asString(item.markdown);
+        pushResult(results, seen, {
+            title: stripHtml(title),
+            url,
+            snippet: description ? stripHtml(description) : markdown ? stripHtml(markdown).slice(0, 500) : undefined,
+        });
+    }
+    return results;
+}
+function formatSourceName(source) {
+    switch (source) {
+        case "brave-search":
+            return "Brave Search";
+        case "firecrawl-search":
+            return "Firecrawl";
+        case "duckduckgo-instant-answer":
+            return "DuckDuckGo";
+    }
+}
+function formatResults(query, results, source) {
+    if (results.length === 0) {
+        return `No ${formatSourceName(source)} links found for: ${query}`;
+    }
+    return results
+        .map((result, index) => {
+        const lines = [`${index + 1}. ${result.title}`, `   ${result.url}`];
+        if (result.snippet)
+            lines.push(`   ${result.snippet}`);
+        return lines.join("\n");
+    })
+        .join("\n\n");
+}
+function resolveLimit(limit) {
+    if (limit === undefined)
+        return DEFAULT_LIMIT;
+    if (!Number.isFinite(limit) || limit <= 0)
+        return DEFAULT_LIMIT;
+    return Math.min(MAX_LIMIT, Math.floor(limit));
+}
+function formatWebsearchCall(args, theme) {
+    const query = str(args?.query);
+    const invalidArg = invalidArgText(theme);
+    let text = `${theme.fg("toolTitle", theme.bold("websearch"))} ${query === null ? invalidArg : theme.fg("accent", query)}`;
+    if (args?.limit !== undefined)
+        text += theme.fg("toolOutput", ` (limit ${args.limit})`);
+    return text;
+}
+function formatWebsearchResult(result, options, theme, showImages) {
+    const output = getTextOutput(result, showImages).trim();
+    if (!output)
+        return "";
+    const lines = output.split("\n");
+    const maxLines = options.expanded ? lines.length : 24;
+    const displayed = lines.slice(0, maxLines).map((line) => theme.fg("toolOutput", line));
+    const remaining = lines.length - maxLines;
+    return remaining > 0
+        ? `${displayed.join("\n")}\n${theme.fg("muted", `... (${remaining} more lines)`)}`
+        : displayed.join("\n");
+}
+function resolveWebsearchProvider(options) {
+    const configured = options?.provider?.trim().toLowerCase() ?? process.env.GRIP_WEBSEARCH_PROVIDER?.trim().toLowerCase();
+    if (!configured) {
+        if (process.env.GRIP_WEBSEARCH_FIRECRAWL_API_KEY || process.env.FIRECRAWL_API_KEY)
+            return "firecrawl-search";
+        if (options?.apiKey || process.env.GRIP_WEBSEARCH_BRAVE_API_KEY || process.env.BRAVE_SEARCH_API_KEY)
+            return "brave-search";
+    }
+    if (!configured || configured === "duckduckgo" || configured === "duckduckgo-instant-answer") {
+        return "duckduckgo-instant-answer";
+    }
+    if (configured === "brave" || configured === "brave-search")
+        return "brave-search";
+    if (configured === "firecrawl" || configured === "firecrawl-search")
+        return "firecrawl-search";
+    throw new Error(`Unsupported websearch provider: ${configured}`);
+}
+function resolveBraveApiKey(options) {
+    const key = options?.apiKey ?? process.env.GRIP_WEBSEARCH_BRAVE_API_KEY ?? process.env.BRAVE_SEARCH_API_KEY;
+    if (!key?.trim()) {
+        throw new Error("Brave websearch requires tools.websearch.apiKey, GRIP_WEBSEARCH_BRAVE_API_KEY, or BRAVE_SEARCH_API_KEY");
+    }
+    return key.trim();
+}
+function resolveFirecrawlApiKey(options) {
+    const key = options?.apiKey ?? process.env.GRIP_WEBSEARCH_FIRECRAWL_API_KEY ?? process.env.FIRECRAWL_API_KEY;
+    if (!key?.trim()) {
+        throw new Error("Firecrawl websearch requires tools.websearch.apiKey, GRIP_WEBSEARCH_FIRECRAWL_API_KEY, or FIRECRAWL_API_KEY");
+    }
+    return key.trim();
+}
+async function fetchDuckDuckGoResults(query, limit, signal) {
+    const url = new URL("https://api.duckduckgo.com/");
+    url.searchParams.set("q", query);
+    url.searchParams.set("format", "json");
+    url.searchParams.set("no_html", "1");
+    url.searchParams.set("skip_disambig", "1");
+    const response = await fetch(url, {
+        headers: { accept: "application/json", "user-agent": "grip-coding-agent" },
+        signal,
+    });
+    if (!response.ok) {
+        throw new Error(`DuckDuckGo request failed: ${response.status} ${response.statusText}`);
+    }
+    return parseDuckDuckGoResponse((await response.json()), limit);
+}
+async function fetchBraveResults(query, limit, signal, options) {
+    const url = new URL(options?.baseUrl ?? process.env.GRIP_WEBSEARCH_BRAVE_BASE_URL ?? "https://api.search.brave.com/res/v1/web/search");
+    url.searchParams.set("q", query);
+    url.searchParams.set("count", String(limit));
+    const response = await fetch(url, {
+        headers: {
+            accept: "application/json",
+            "user-agent": "grip-coding-agent",
+            "x-subscription-token": resolveBraveApiKey(options),
+        },
+        signal,
+    });
+    if (!response.ok) {
+        throw new Error(`Brave Search request failed: ${response.status} ${response.statusText}`);
+    }
+    return parseBraveSearchResponse((await response.json()), limit);
+}
+async function fetchFirecrawlResults(query, limit, signal, options) {
+    const url = new URL(options?.baseUrl ?? process.env.GRIP_WEBSEARCH_FIRECRAWL_BASE_URL ?? "https://api.firecrawl.dev/v2/search");
+    const response = await fetch(url, {
+        method: "POST",
+        headers: {
+            accept: "application/json",
+            "content-type": "application/json",
+            "user-agent": "grip-coding-agent",
+            authorization: `Bearer ${resolveFirecrawlApiKey(options)}`,
+        },
+        body: JSON.stringify({ query, limit, sources: [{ type: "web" }] }),
+        signal,
+    });
+    if (!response.ok) {
+        throw new Error(`Firecrawl Search request failed: ${response.status} ${response.statusText}`);
+    }
+    return parseFirecrawlSearchResponse((await response.json()), limit);
+}
+export function createWebsearchToolDefinition(options) {
+    return {
+        name: "websearch",
+        label: "websearch",
+        description: "Search the web for relevant links using DuckDuckGo by default, or Brave Search/Firecrawl when configured. Returns titles, URLs, and snippets when available.",
+        promptSnippet: "Search the web for relevant links",
+        parameters: websearchSchema,
+        async execute(_toolCallId, { query, limit }, signal) {
+            const trimmedQuery = query.trim();
+            if (!trimmedQuery)
+                throw new Error("query is required");
+            const effectiveLimit = resolveLimit(limit);
+            const controller = new AbortController();
+            const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+            const onAbort = () => controller.abort();
+            signal?.addEventListener("abort", onAbort, { once: true });
+            try {
+                const source = resolveWebsearchProvider(options);
+                const results = await (async () => {
+                    switch (source) {
+                        case "brave-search":
+                            return fetchBraveResults(trimmedQuery, effectiveLimit, controller.signal, options);
+                        case "firecrawl-search":
+                            return fetchFirecrawlResults(trimmedQuery, effectiveLimit, controller.signal, options);
+                        case "duckduckgo-instant-answer":
+                            return fetchDuckDuckGoResults(trimmedQuery, effectiveLimit, controller.signal);
+                    }
+                })();
+                return {
+                    content: [{ type: "text", text: formatResults(trimmedQuery, results, source) }],
+                    details: { query: trimmedQuery, results, source },
+                };
+            }
+            finally {
+                clearTimeout(timeout);
+                signal?.removeEventListener("abort", onAbort);
+            }
+        },
+        renderCall(args, theme, context) {
+            const text = context.lastComponent ?? new Text("", 0, 0);
+            text.setText(formatWebsearchCall(args, theme));
+            return text;
+        },
+        renderResult(result, options, theme, context) {
+            const text = context.lastComponent ?? new Text("", 0, 0);
+            text.setText(formatWebsearchResult(result, options, theme, context.showImages));
+            return text;
+        },
+    };
+}
+export function createWebsearchTool(options) {
+    return wrapToolDefinition(createWebsearchToolDefinition(options));
+}
+//# sourceMappingURL=websearch.js.map