@gugacoder/agentic-sdk 0.2.0

package/dist/tools/brave-search.js

@@ -0,0 +1,19 @@
+/**
+ * Brave Web Search API client.
+ * Docs: https://api.search.brave.com/app#/documentation/web-search
+ */
+export async function braveSearch(query, numResults, apiKey) {
+    const count = numResults ?? 5;
+    const url = `https://api.search.brave.com/res/v1/web/search?q=${encodeURIComponent(query)}&count=${count}`;
+    const res = await fetch(url, {
+        headers: { "X-Subscription-Token": apiKey },
+    });
+    if (!res.ok)
+        return [];
+    const data = await res.json();
+    return (data.web?.results ?? []).slice(0, numResults).map((r) => ({
+        title: r.title,
+        url: r.url,
+        snippet: r.description,
+    }));
+}

package/dist/tools/code-search.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A single code search result returned by a CodeSearch provider.
+ */
+export interface CodeSearchResult {
+    title: string;
+    url: string;
+    content: string;
+}
+/**
+ * Callback type for pluggable code search providers.
+ * Implementors receive the query and return code examples and documentation snippets.
+ */
+export type CodeSearchProvider = (query: string) => Promise<CodeSearchResult[]>;
+/**
+ * Factory that creates the CodeSearch tool with an injected search provider.
+ * If no provider is given, returns a tool that explains no provider is configured.
+ */
+export declare function createCodeSearchTool(searchProvider?: CodeSearchProvider): import("ai").Tool<{
+    query: string;
+}, string>;

package/dist/tools/code-search.js

@@ -0,0 +1,42 @@
+import { tool } from "ai";
+import { z } from "zod";
+const MAX_OUTPUT = 50_000;
+/**
+ * Factory that creates the CodeSearch tool with an injected search provider.
+ * If no provider is given, returns a tool that explains no provider is configured.
+ */
+export function createCodeSearchTool(searchProvider) {
+    return tool({
+        description: "Search for code examples, API documentation, and library patterns online. Use this to find usage examples, best practices, and documentation for APIs and libraries.",
+        inputSchema: z.object({
+            query: z
+                .string()
+                .describe("Search query about APIs, libraries, or coding patterns (e.g. 'zod v4 migration', 'express middleware error handling')"),
+        }),
+        execute: async ({ query }) => {
+            if (!searchProvider) {
+                return "CodeSearch provider not configured. The consuming application must provide an onCodeSearch callback in AiAgentOptions to enable code search.";
+            }
+            try {
+                const results = await searchProvider(query);
+                if (results.length === 0) {
+                    return `No code examples found for: "${query}"`;
+                }
+                let output = `# Code search results for: "${query}"\n\n`;
+                for (let i = 0; i < results.length; i++) {
+                    const r = results[i];
+                    output += `## ${i + 1}. ${r.title}\n`;
+                    output += `**Source:** ${r.url}\n\n`;
+                    output += `${r.content}\n\n`;
+                }
+                if (output.length > MAX_OUTPUT) {
+                    output = output.slice(0, MAX_OUTPUT) + "\n...[truncated at 50KB]";
+                }
+                return output.trim();
+            }
+            catch (err) {
+                return `Error searching code: ${err.message}`;
+            }
+        },
+    });
+}

package/dist/tools/diagnostics.d.ts

@@ -0,0 +1,4 @@
+export declare const diagnosticsTool: import("ai").Tool<{
+    file_path?: string | undefined;
+    command?: string | undefined;
+}, string>;

package/dist/tools/diagnostics.js

@@ -0,0 +1,69 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { exec } from "node:child_process";
+const MAX_OUTPUT = 50_000;
+const DEFAULT_COMMAND = "npx tsc --noEmit";
+const DEFAULT_TIMEOUT = 120_000;
+export const diagnosticsTool = tool({
+    description: "Runs a type-checking or linting command and returns structured diagnostics. " +
+        "Defaults to `npx tsc --noEmit`. Optionally filters errors to a specific file.",
+    inputSchema: z.object({
+        command: z
+            .string()
+            .optional()
+            .describe('The diagnostic command to run (default: "npx tsc --noEmit"). Examples: "npx eslint src/", "npx tsc --noEmit"'),
+        file_path: z
+            .string()
+            .optional()
+            .describe("Filter errors to this file path only. When set, only lines mentioning this path are returned."),
+    }),
+    execute: async ({ command, file_path }) => {
+        const cmd = command ?? DEFAULT_COMMAND;
+        const raw = await new Promise((resolve) => {
+            exec(cmd, { timeout: DEFAULT_TIMEOUT, maxBuffer: 10 * 1024 * 1024 }, (err, stdout, stderr) => {
+                resolve({
+                    stdout: stdout ?? "",
+                    stderr: stderr ?? "",
+                    exitCode: err ? err.code ?? 1 : 0,
+                });
+            });
+        });
+        // Combine stdout + stderr (tsc writes to stdout, eslint to stdout, some tools to stderr)
+        let combined = raw.stdout;
+        if (raw.stderr) {
+            combined += (combined ? "\n" : "") + raw.stderr;
+        }
+        // If the command succeeded with no output, report clean
+        if (raw.exitCode === 0 && !combined.trim()) {
+            return "Nenhum erro encontrado.";
+        }
+        // If there's output but exit code 0, it may be warnings — still return them
+        let lines = combined.split("\n");
+        // Filter to specific file if requested
+        if (file_path) {
+            // Normalize path separators for matching
+            const normalized = file_path.replace(/\\/g, "/");
+            lines = lines.filter((line) => {
+                const normalizedLine = line.replace(/\\/g, "/");
+                return normalizedLine.includes(normalized);
+            });
+            if (lines.length === 0) {
+                return `Nenhum erro encontrado para ${file_path}.`;
+            }
+        }
+        let output = lines.join("\n").trim();
+        // If exit code 0 and we have output, it passed (possibly with warnings)
+        if (raw.exitCode === 0 && !output) {
+            return "Nenhum erro encontrado.";
+        }
+        if (!output) {
+            return raw.exitCode === 0
+                ? "Nenhum erro encontrado."
+                : `Comando falhou com código ${raw.exitCode} mas sem saída de erros.`;
+        }
+        if (output.length > MAX_OUTPUT) {
+            output = output.slice(0, MAX_OUTPUT) + "\n...[truncated]";
+        }
+        return output;
+    },
+});

package/dist/tools/display.d.ts

@@ -0,0 +1,483 @@
+export declare function createDisplayTools(): {
+    display_highlight: import("ai").Tool<{
+        value: string | number;
+        label: string;
+        action: "metric";
+        unit?: string | undefined;
+        trend?: {
+            value: string;
+            direction: "up" | "down" | "neutral";
+        } | undefined;
+        icon?: string | undefined;
+    } | {
+        value: {
+            value: number;
+            currency: string;
+        };
+        label: string;
+        action: "price";
+        badge?: {
+            label: string;
+            variant: "default" | "success" | "warning" | "error" | "info";
+        } | undefined;
+        source?: {
+            name: string;
+            url: string;
+            favicon?: string | undefined;
+        } | undefined;
+        context?: string | undefined;
+    } | {
+        message: string;
+        variant: "success" | "warning" | "error" | "info";
+        action: "alert";
+        title?: string | undefined;
+        icon?: string | undefined;
+    } | {
+        layout: "buttons" | "cards" | "list";
+        choices: {
+            id: string;
+            label: string;
+            description?: string | undefined;
+            icon?: string | undefined;
+        }[];
+        action: "choices";
+        question?: string | undefined;
+    }, {
+        _display: boolean;
+        value: string | number;
+        label: string;
+        action: "metric";
+        unit?: string | undefined;
+        trend?: {
+            value: string;
+            direction: "up" | "down" | "neutral";
+        } | undefined;
+        icon?: string | undefined;
+    } | {
+        _display: boolean;
+        value: {
+            value: number;
+            currency: string;
+        };
+        label: string;
+        action: "price";
+        badge?: {
+            label: string;
+            variant: "default" | "success" | "warning" | "error" | "info";
+        } | undefined;
+        source?: {
+            name: string;
+            url: string;
+            favicon?: string | undefined;
+        } | undefined;
+        context?: string | undefined;
+    } | {
+        _display: boolean;
+        message: string;
+        variant: "success" | "warning" | "error" | "info";
+        action: "alert";
+        title?: string | undefined;
+        icon?: string | undefined;
+    } | {
+        _display: boolean;
+        layout: "buttons" | "cards" | "list";
+        choices: {
+            id: string;
+            label: string;
+            description?: string | undefined;
+            icon?: string | undefined;
+        }[];
+        action: "choices";
+        question?: string | undefined;
+    }>;
+    display_collection: import("ai").Tool<{
+        columns: {
+            type: "number" | "link" | "text" | "money" | "image" | "badge";
+            label: string;
+            key: string;
+            align: "left" | "center" | "right";
+        }[];
+        rows: Record<string, unknown>[];
+        sortable: boolean;
+        action: "table";
+        title?: string | undefined;
+    } | {
+        headers: string[];
+        rows: (string | number | null)[][];
+        action: "spreadsheet";
+        title?: string | undefined;
+        format?: {
+            moneyColumns?: number[] | undefined;
+            percentColumns?: number[] | undefined;
+        } | undefined;
+    } | {
+        items: {
+            title: string;
+            description?: string | undefined;
+            url?: string | undefined;
+            image?: string | undefined;
+            price?: {
+                value: number;
+                currency: string;
+            } | undefined;
+            originalPrice?: {
+                value: number;
+                currency: string;
+            } | undefined;
+            rating?: {
+                count: number;
+                score: number;
+            } | undefined;
+            source?: {
+                name: string;
+                url: string;
+                favicon?: string | undefined;
+            } | undefined;
+            badges?: {
+                label: string;
+                variant: "default" | "success" | "warning" | "error" | "info";
+            }[] | undefined;
+        }[];
+        action: "comparison";
+        title?: string | undefined;
+        attributes?: {
+            label: string;
+            key: string;
+        }[] | undefined;
+    } | {
+        items: {
+            title: string;
+            url?: string | undefined;
+            image?: string | undefined;
+            price?: {
+                value: number;
+                currency: string;
+            } | undefined;
+            badges?: {
+                label: string;
+                variant: "default" | "success" | "warning" | "error" | "info";
+            }[] | undefined;
+            subtitle?: string | undefined;
+        }[];
+        action: "carousel";
+        title?: string | undefined;
+    } | {
+        columns: number;
+        images: {
+            url: string;
+            alt?: string | undefined;
+            caption?: string | undefined;
+        }[];
+        layout: "grid" | "masonry";
+        action: "gallery";
+        title?: string | undefined;
+    } | {
+        label: string;
+        sources: {
+            title: string;
+            url: string;
+            favicon?: string | undefined;
+            snippet?: string | undefined;
+        }[];
+        action: "sources";
+    }, {
+        _display: boolean;
+        columns: {
+            type: "number" | "link" | "text" | "money" | "image" | "badge";
+            label: string;
+            key: string;
+            align: "left" | "center" | "right";
+        }[];
+        rows: Record<string, unknown>[];
+        sortable: boolean;
+        action: "table";
+        title?: string | undefined;
+    } | {
+        _display: boolean;
+        headers: string[];
+        rows: (string | number | null)[][];
+        action: "spreadsheet";
+        title?: string | undefined;
+        format?: {
+            moneyColumns?: number[] | undefined;
+            percentColumns?: number[] | undefined;
+        } | undefined;
+    } | {
+        _display: boolean;
+        items: {
+            title: string;
+            description?: string | undefined;
+            url?: string | undefined;
+            image?: string | undefined;
+            price?: {
+                value: number;
+                currency: string;
+            } | undefined;
+            originalPrice?: {
+                value: number;
+                currency: string;
+            } | undefined;
+            rating?: {
+                count: number;
+                score: number;
+            } | undefined;
+            source?: {
+                name: string;
+                url: string;
+                favicon?: string | undefined;
+            } | undefined;
+            badges?: {
+                label: string;
+                variant: "default" | "success" | "warning" | "error" | "info";
+            }[] | undefined;
+        }[];
+        action: "comparison";
+        title?: string | undefined;
+        attributes?: {
+            label: string;
+            key: string;
+        }[] | undefined;
+    } | {
+        _display: boolean;
+        items: {
+            title: string;
+            url?: string | undefined;
+            image?: string | undefined;
+            price?: {
+                value: number;
+                currency: string;
+            } | undefined;
+            badges?: {
+                label: string;
+                variant: "default" | "success" | "warning" | "error" | "info";
+            }[] | undefined;
+            subtitle?: string | undefined;
+        }[];
+        action: "carousel";
+        title?: string | undefined;
+    } | {
+        _display: boolean;
+        columns: number;
+        images: {
+            url: string;
+            alt?: string | undefined;
+            caption?: string | undefined;
+        }[];
+        layout: "grid" | "masonry";
+        action: "gallery";
+        title?: string | undefined;
+    } | {
+        _display: boolean;
+        label: string;
+        sources: {
+            title: string;
+            url: string;
+            favicon?: string | undefined;
+            snippet?: string | undefined;
+        }[];
+        action: "sources";
+    }>;
+    display_card: import("ai").Tool<{
+        title: string;
+        action: "product";
+        description?: string | undefined;
+        url?: string | undefined;
+        image?: string | undefined;
+        price?: {
+            value: number;
+            currency: string;
+        } | undefined;
+        originalPrice?: {
+            value: number;
+            currency: string;
+        } | undefined;
+        rating?: {
+            count: number;
+            score: number;
+        } | undefined;
+        source?: {
+            name: string;
+            url: string;
+            favicon?: string | undefined;
+        } | undefined;
+        badges?: {
+            label: string;
+            variant: "default" | "success" | "warning" | "error" | "info";
+        }[] | undefined;
+    } | {
+        title: string;
+        url: string;
+        action: "link";
+        description?: string | undefined;
+        favicon?: string | undefined;
+        image?: string | undefined;
+        domain?: string | undefined;
+    } | {
+        type: string;
+        name: string;
+        action: "file";
+        url?: string | undefined;
+        size?: number | undefined;
+        preview?: string | undefined;
+    } | {
+        url: string;
+        action: "image";
+        alt?: string | undefined;
+        caption?: string | undefined;
+        width?: number | undefined;
+        height?: number | undefined;
+    }, {
+        _display: boolean;
+        title: string;
+        action: "product";
+        description?: string | undefined;
+        url?: string | undefined;
+        image?: string | undefined;
+        price?: {
+            value: number;
+            currency: string;
+        } | undefined;
+        originalPrice?: {
+            value: number;
+            currency: string;
+        } | undefined;
+        rating?: {
+            count: number;
+            score: number;
+        } | undefined;
+        source?: {
+            name: string;
+            url: string;
+            favicon?: string | undefined;
+        } | undefined;
+        badges?: {
+            label: string;
+            variant: "default" | "success" | "warning" | "error" | "info";
+        }[] | undefined;
+    } | {
+        _display: boolean;
+        title: string;
+        url: string;
+        action: "link";
+        description?: string | undefined;
+        favicon?: string | undefined;
+        image?: string | undefined;
+        domain?: string | undefined;
+    } | {
+        _display: boolean;
+        type: string;
+        name: string;
+        action: "file";
+        url?: string | undefined;
+        size?: number | undefined;
+        preview?: string | undefined;
+    } | {
+        _display: boolean;
+        url: string;
+        action: "image";
+        alt?: string | undefined;
+        caption?: string | undefined;
+        width?: number | undefined;
+        height?: number | undefined;
+    }>;
+    display_visual: import("ai").Tool<{
+        type: "bar" | "line" | "pie" | "area" | "donut";
+        title: string;
+        data: {
+            value: number;
+            label: string;
+            color?: string | undefined;
+        }[];
+        action: "chart";
+        format?: {
+            locale: string;
+            prefix?: string | undefined;
+            suffix?: string | undefined;
+        } | undefined;
+    } | {
+        pins: {
+            lat: number;
+            lng: number;
+            label?: string | undefined;
+            address?: string | undefined;
+        }[];
+        zoom: number;
+        action: "map";
+        title?: string | undefined;
+    } | {
+        code: string;
+        language: string;
+        lineNumbers: boolean;
+        action: "code";
+        title?: string | undefined;
+    } | {
+        steps: {
+            status: "pending" | "completed" | "current";
+            label: string;
+            description?: string | undefined;
+        }[];
+        action: "progress";
+        title?: string | undefined;
+    } | {
+        steps: {
+            status: "pending" | "completed" | "current";
+            title: string;
+            description?: string | undefined;
+        }[];
+        orientation: "vertical" | "horizontal";
+        action: "steps";
+        title?: string | undefined;
+    }, {
+        _display: boolean;
+        type: "bar" | "line" | "pie" | "area" | "donut";
+        title: string;
+        data: {
+            value: number;
+            label: string;
+            color?: string | undefined;
+        }[];
+        action: "chart";
+        format?: {
+            locale: string;
+            prefix?: string | undefined;
+            suffix?: string | undefined;
+        } | undefined;
+    } | {
+        _display: boolean;
+        pins: {
+            lat: number;
+            lng: number;
+            label?: string | undefined;
+            address?: string | undefined;
+        }[];
+        zoom: number;
+        action: "map";
+        title?: string | undefined;
+    } | {
+        _display: boolean;
+        code: string;
+        language: string;
+        lineNumbers: boolean;
+        action: "code";
+        title?: string | undefined;
+    } | {
+        _display: boolean;
+        steps: {
+            status: "pending" | "completed" | "current";
+            label: string;
+            description?: string | undefined;
+        }[];
+        action: "progress";
+        title?: string | undefined;
+    } | {
+        _display: boolean;
+        steps: {
+            status: "pending" | "completed" | "current";
+            title: string;
+            description?: string | undefined;
+        }[];
+        orientation: "vertical" | "horizontal";
+        action: "steps";
+        title?: string | undefined;
+    }>;
+};