@gugacoder/agentic-sdk 0.2.0

package/src/tools/batch.ts

@@ -0,0 +1,103 @@
+import { tool, type Tool } from "ai";
+import { z } from "zod";
+
+const MAX_OUTPUT = 50_000;
+
+/**
+ * Factory that creates the Batch tool for parallel tool execution.
+ *
+ * Receives the resolved tool registry so it can look up tools by name.
+ * The Batch tool itself is excluded from the registry to prevent recursion.
+ */
+export function createBatchTool(toolRegistry: Record<string, Tool>) {
+  // Build the list of available tool names (excluding Batch itself)
+  const availableTools = Object.keys(toolRegistry).filter(
+    (name) => name !== "Batch"
+  );
+
+  return tool({
+    description:
+      "Execute 2-10 tool calls simultaneously in parallel using Promise.allSettled(). " +
+      "Partial failures do not cancel other calls. " +
+      "Batch cannot call itself (no recursion). " +
+      `Available tools: ${availableTools.join(", ")}`,
+    inputSchema: z.object({
+      tool_calls: z
+        .array(
+          z.object({
+            tool: z
+              .string()
+              .describe("Name of the tool to call (must be a registered tool)"),
+            parameters: z
+              .record(z.any())
+              .describe("Parameters to pass to the tool"),
+          })
+        )
+        .min(2)
+        .max(10)
+        .describe("Array of tool calls to execute in parallel (2-10 items)"),
+    }),
+    execute: async ({ tool_calls }) => {
+      // Validate: no Batch inside Batch
+      const batchCalls = tool_calls.filter((tc) => tc.tool === "Batch");
+      if (batchCalls.length > 0) {
+        return "Error: Batch cannot call itself. Remove Batch from tool_calls.";
+      }
+
+      // Validate: all tools exist
+      const unknownTools = tool_calls.filter(
+        (tc) => !availableTools.includes(tc.tool)
+      );
+      if (unknownTools.length > 0) {
+        const names = unknownTools.map((tc) => tc.tool).join(", ");
+        return `Error: Unknown tool(s): ${names}. Available: ${availableTools.join(", ")}`;
+      }
+
+      // Execute all calls in parallel
+      const promises = tool_calls.map(async (tc, index) => {
+        const targetTool = toolRegistry[tc.tool] as Tool & {
+          execute?: (params: Record<string, unknown>) => Promise<string>;
+        };
+
+        if (!targetTool.execute) {
+          return { index, tool: tc.tool, result: `Error: Tool "${tc.tool}" has no execute function.` };
+        }
+
+        try {
+          const result = await targetTool.execute(tc.parameters, {
+            toolCallId: `batch-${index}-${tc.tool}`,
+            messages: [],
+            abortSignal: undefined as unknown as AbortSignal,
+          });
+          return { index, tool: tc.tool, result: String(result) };
+        } catch (err: any) {
+          return {
+            index,
+            tool: tc.tool,
+            result: `Error: ${err.message ?? String(err)}`,
+          };
+        }
+      });
+
+      const settled = await Promise.allSettled(promises);
+
+      const parts: string[] = [];
+      for (const outcome of settled) {
+        if (outcome.status === "fulfilled") {
+          const { index, tool: toolName, result } = outcome.value;
+          parts.push(`### [${index}] ${toolName}\n\n${result}`);
+        } else {
+          parts.push(`### [?] Error\n\n${outcome.reason?.message ?? String(outcome.reason)}`);
+        }
+      }
+
+      let output = parts.join("\n\n---\n\n");
+
+      if (output.length > MAX_OUTPUT) {
+        output = output.slice(0, MAX_OUTPUT) + "\n...[truncated at 50KB]";
+      }
+
+      return output;
+    },
+  });
+}

package/src/tools/brave-search.ts

@@ -0,0 +1,24 @@
+import type { WebSearchResult } from "./web-search.js";
+
+/**
+ * Brave Web Search API client.
+ * Docs: https://api.search.brave.com/app#/documentation/web-search
+ */
+export async function braveSearch(
+  query: string,
+  numResults: number,
+  apiKey: string
+): Promise<WebSearchResult[]> {
+  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: any = await res.json();
+  return (data.web?.results ?? []).slice(0, numResults).map((r: any) => ({
+    title: r.title,
+    url: r.url,
+    snippet: r.description,
+  }));
+}

package/src/tools/code-search.ts

@@ -0,0 +1,69 @@
+import { tool } from "ai";
+import { z } from "zod";
+
+const MAX_OUTPUT = 50_000;
+
+/**
+ * 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 function createCodeSearchTool(searchProvider?: CodeSearchProvider) {
+  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: any) {
+        return `Error searching code: ${err.message}`;
+      }
+    },
+  });
+}

package/src/tools/diagnostics.ts

@@ -0,0 +1,93 @@
+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<{ stdout: string; stderr: string; exitCode: number }>(
+      (resolve) => {
+        exec(
+          cmd,
+          { timeout: DEFAULT_TIMEOUT, maxBuffer: 10 * 1024 * 1024 },
+          (err, stdout, stderr) => {
+            resolve({
+              stdout: stdout ?? "",
+              stderr: stderr ?? "",
+              exitCode: err ? (err as NodeJS.ErrnoException & { code?: number }).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/src/tools/display.ts

@@ -0,0 +1,105 @@
+import { tool } from "ai";
+import { z } from "zod";
+import {
+  DisplayMetricSchema,
+  DisplayChartSchema,
+  DisplayTableSchema,
+  DisplayProgressSchema,
+  DisplayProductSchema,
+  DisplayComparisonSchema,
+  DisplayPriceSchema,
+  DisplayImageSchema,
+  DisplayGallerySchema,
+  DisplayCarouselSchema,
+  DisplaySourcesSchema,
+  DisplayLinkSchema,
+  DisplayMapSchema,
+  DisplayFileSchema,
+  DisplayCodeSchema,
+  DisplaySpreadsheetSchema,
+  DisplayStepsSchema,
+  DisplayAlertSchema,
+  DisplayChoicesSchema,
+} from "../display-schemas.js";
+
+// display_highlight: metric, price, alert, choices
+const highlightSchema = z.discriminatedUnion("action", [
+  z.object({ action: z.literal("metric"), ...DisplayMetricSchema.shape }),
+  z.object({ action: z.literal("price"), ...DisplayPriceSchema.shape }),
+  z.object({ action: z.literal("alert"), ...DisplayAlertSchema.shape }),
+  z.object({ action: z.literal("choices"), ...DisplayChoicesSchema.shape }),
+]);
+
+// display_collection: table, spreadsheet, comparison, carousel, gallery, sources
+const collectionSchema = z.discriminatedUnion("action", [
+  z.object({ action: z.literal("table"), ...DisplayTableSchema.shape }),
+  z.object({ action: z.literal("spreadsheet"), ...DisplaySpreadsheetSchema.shape }),
+  z.object({ action: z.literal("comparison"), ...DisplayComparisonSchema.shape }),
+  z.object({ action: z.literal("carousel"), ...DisplayCarouselSchema.shape }),
+  z.object({ action: z.literal("gallery"), ...DisplayGallerySchema.shape }),
+  z.object({ action: z.literal("sources"), ...DisplaySourcesSchema.shape }),
+]);
+
+// display_card: product, link, file, image
+const cardSchema = z.discriminatedUnion("action", [
+  z.object({ action: z.literal("product"), ...DisplayProductSchema.shape }),
+  z.object({ action: z.literal("link"), ...DisplayLinkSchema.shape }),
+  z.object({ action: z.literal("file"), ...DisplayFileSchema.shape }),
+  z.object({ action: z.literal("image"), ...DisplayImageSchema.shape }),
+]);
+
+// display_visual: chart, map, code, progress, steps
+const visualSchema = z.discriminatedUnion("action", [
+  z.object({ action: z.literal("chart"), ...DisplayChartSchema.shape }),
+  z.object({ action: z.literal("map"), ...DisplayMapSchema.shape }),
+  z.object({ action: z.literal("code"), ...DisplayCodeSchema.shape }),
+  z.object({ action: z.literal("progress"), ...DisplayProgressSchema.shape }),
+  z.object({ action: z.literal("steps"), ...DisplayStepsSchema.shape }),
+]);
+
+export function createDisplayTools() {
+  return {
+    display_highlight: tool({
+      description: [
+        "Destaca informacao importante na resposta.",
+        "Actions: metric (KPI com valor e tendencia), price (preco em destaque),",
+        "alert (banner info/warning/error/success), choices (opcoes clicaveis para o usuario).",
+      ].join(" "),
+      inputSchema: highlightSchema,
+      execute: async (args) => ({ ...args, _display: true }),
+    }),
+
+    display_collection: tool({
+      description: [
+        "Apresenta colecao de itens organizados.",
+        "Actions: table (tabela rica com colunas tipadas), spreadsheet (planilha exportavel),",
+        "comparison (itens lado a lado), carousel (cards horizontais navegaveis),",
+        "gallery (grid de imagens), sources (lista de fontes consultadas).",
+      ].join(" "),
+      inputSchema: collectionSchema,
+      execute: async (args) => ({ ...args, _display: true }),
+    }),
+
+    display_card: tool({
+      description: [
+        "Apresenta item individual com detalhes visuais.",
+        "Actions: product (card com imagem, preco, rating, badges),",
+        "link (preview de URL com OG image), file (card de arquivo para download),",
+        "image (imagem unica com caption e zoom).",
+      ].join(" "),
+      inputSchema: cardSchema,
+      execute: async (args) => ({ ...args, _display: true }),
+    }),
+
+    display_visual: tool({
+      description: [
+        "Visualizacao especializada de dados ou fluxos.",
+        "Actions: chart (grafico bar/line/pie/area/donut), map (mapa com pins),",
+        "code (bloco com syntax highlighting), progress (barra de progresso com etapas),",
+        "steps (timeline/checklist de etapas).",
+      ].join(" "),
+      inputSchema: visualSchema,
+      execute: async (args) => ({ ...args, _display: true }),
+    }),
+  };
+}

package/src/tools/edit.ts

@@ -0,0 +1,55 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { readFile, writeFile } from "node:fs/promises";
+
+export function createEditTool(opts?: { autoApprove?: boolean }) {
+  const baseTool = tool({
+    description:
+      "Performs exact string replacement in a file. The old_string must be unique in the file unless replace_all is true.",
+    inputSchema: z.object({
+      file_path: z.string().describe("Absolute path to the file to edit"),
+      old_string: z.string().describe("The exact text to find and replace"),
+      new_string: z.string().describe("The replacement text"),
+      replace_all: z
+        .boolean()
+        .optional()
+        .default(false)
+        .describe("Replace all occurrences instead of just the first"),
+    }),
+    execute: async ({ file_path, old_string, new_string, replace_all }) => {
+      try {
+        const content = await readFile(file_path, "utf-8");
+
+        if (!content.includes(old_string)) {
+          return `Error: old_string not found in ${file_path}`;
+        }
+
+        if (!replace_all) {
+          const count = content.split(old_string).length - 1;
+          if (count > 1) {
+            return `Error: old_string appears ${count} times in the file. Provide more context to make it unique, or set replace_all to true.`;
+          }
+        }
+
+        const updated = replace_all
+          ? content.replaceAll(old_string, new_string)
+          : content.replace(old_string, new_string);
+
+        await writeFile(file_path, updated, "utf-8");
+        return `File edited successfully: ${file_path}`;
+      } catch (err: any) {
+        return `Error editing file: ${err.message}`;
+      }
+    },
+  });
+
+  if (opts?.autoApprove === false) {
+    return Object.assign(baseTool, {
+      needsApproval: async () => true as const,
+    });
+  }
+
+  return baseTool;
+}
+
+export const editTool = createEditTool();

package/src/tools/glob.ts

@@ -0,0 +1,46 @@
+import { tool } from "ai";
+import { z } from "zod";
+import fg from "fast-glob";
+import { stat } from "node:fs/promises";
+
+export const globTool = tool({
+  description:
+    "Fast file pattern matching. Supports glob patterns like '**/*.ts'. Returns matching file paths sorted by modification time.",
+  inputSchema: z.object({
+    pattern: z.string().describe("Glob pattern to match files against"),
+    path: z
+      .string()
+      .optional()
+      .describe("Directory to search in. Defaults to cwd."),
+  }),
+  execute: async ({ pattern, path }) => {
+    try {
+      const cwd = path ?? process.cwd();
+      const files = await fg(pattern, {
+        cwd,
+        absolute: true,
+        dot: false,
+        onlyFiles: true,
+      });
+
+      // Sort by mtime (most recent first)
+      const withStats = await Promise.all(
+        files.map(async (f) => {
+          try {
+            const s = await stat(f);
+            return { file: f, mtime: s.mtimeMs };
+          } catch {
+            return { file: f, mtime: 0 };
+          }
+        })
+      );
+
+      withStats.sort((a, b) => b.mtime - a.mtime);
+
+      if (withStats.length === 0) return "No files matched the pattern.";
+      return withStats.map((w) => w.file).join("\n");
+    } catch (err: any) {
+      return `Error: ${err.message}`;
+    }
+  },
+});

package/src/tools/grep.ts

@@ -0,0 +1,68 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { execFile } from "node:child_process";
+
+const MAX_OUTPUT = 30_000;
+
+export const grepTool = tool({
+  description:
+    "Searches file contents using ripgrep (rg) with regex support. Falls back to grep if rg is unavailable.",
+  inputSchema: z.object({
+    pattern: z.string().describe("Regex pattern to search for"),
+    path: z
+      .string()
+      .optional()
+      .describe("File or directory to search in. Defaults to cwd."),
+    glob: z
+      .string()
+      .optional()
+      .describe("Glob pattern to filter files (e.g. '*.ts')"),
+    output_mode: z
+      .enum(["content", "files_with_matches", "count"])
+      .optional()
+      .default("files_with_matches")
+      .describe("Output mode"),
+  }),
+  execute: async ({ pattern, path, glob: globFilter, output_mode }) => {
+    const searchPath = path ?? ".";
+
+    // Build rg args array (no shell quoting needed with execFile)
+    const args: string[] = [];
+
+    if (output_mode === "files_with_matches") args.push("-l");
+    else if (output_mode === "count") args.push("-c");
+    else args.push("-n"); // content mode: show line numbers
+
+    if (globFilter) args.push("--glob", globFilter);
+
+    args.push(pattern, searchPath);
+
+    return new Promise<string>((resolve) => {
+      execFile("rg", args, { timeout: 30_000, maxBuffer: 10 * 1024 * 1024 }, (err, stdout) => {
+        if (stdout) {
+          const output = stdout.length > MAX_OUTPUT
+            ? stdout.slice(0, MAX_OUTPUT) + "\n...[truncated]"
+            : stdout;
+          resolve(output.trim());
+        } else if (err) {
+          // rg returns exit code 1 for no matches
+          if ((err as any).code === 1) {
+            resolve("No matches found.");
+          } else {
+            // Try grep fallback
+            const grepArgs = ["-rn"];
+            if (globFilter) grepArgs.push(`--include=${globFilter}`);
+            grepArgs.push(pattern, searchPath);
+
+            execFile("grep", grepArgs, { timeout: 30_000 }, (gErr, gOut) => {
+              if (gOut) resolve(gOut.trim());
+              else resolve("No matches found.");
+            });
+          }
+        } else {
+          resolve("No matches found.");
+        }
+      });
+    });
+  },
+});

package/src/tools/http-request.ts

@@ -0,0 +1,103 @@
+import { tool } from "ai";
+import { z } from "zod";
+
+const MAX_RESPONSE_SIZE = 50 * 1024; // 50KB
+const MAX_TIMEOUT = 60_000;
+
+export const httpRequestTool = tool({
+  description:
+    "Sends an HTTP request to a URL. Supports all methods, custom headers, and JSON/text bodies. Use for REST API interactions.",
+  inputSchema: z.object({
+    method: z
+      .enum(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"])
+      .describe("HTTP method"),
+    url: z.string().url().describe("Target URL"),
+    headers: z
+      .record(z.string())
+      .optional()
+      .describe("Custom headers (e.g. Authorization, Content-Type)"),
+    body: z
+      .string()
+      .optional()
+      .describe("Request body (JSON string or plain text)"),
+    timeout: z
+      .number()
+      .optional()
+      .default(30_000)
+      .describe("Timeout in ms (max 60000)"),
+  }),
+  execute: async ({ method, url, headers, body, timeout }) => {
+    const effectiveTimeout = Math.min(timeout ?? 30_000, MAX_TIMEOUT);
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), effectiveTimeout);
+
+    try {
+      const fetchHeaders: Record<string, string> = { ...headers };
+
+      // Auto-set Content-Type for JSON bodies if not specified
+      if (body && !fetchHeaders["Content-Type"] && !fetchHeaders["content-type"]) {
+        try {
+          JSON.parse(body);
+          fetchHeaders["Content-Type"] = "application/json";
+        } catch {
+          // Not JSON — leave Content-Type unset
+        }
+      }
+
+      const response = await fetch(url, {
+        method,
+        headers: fetchHeaders,
+        body: method !== "GET" && method !== "HEAD" ? body : undefined,
+        signal: controller.signal,
+      });
+
+      // Collect response headers (subset)
+      const responseHeaders: Record<string, string> = {};
+      for (const key of ["content-type", "location", "x-request-id", "retry-after"]) {
+        const val = response.headers.get(key);
+        if (val) responseHeaders[key] = val;
+      }
+
+      // Read response body
+      const contentType = response.headers.get("content-type") ?? "";
+      let responseBody: unknown;
+
+      if (method === "HEAD") {
+        responseBody = null;
+      } else {
+        const text = await response.text();
+        const truncated = text.length > MAX_RESPONSE_SIZE;
+        const bodyText = truncated ? text.slice(0, MAX_RESPONSE_SIZE) : text;
+
+        // Try JSON parse if content-type indicates JSON
+        if (contentType.includes("json")) {
+          try {
+            responseBody = JSON.parse(bodyText);
+          } catch {
+            responseBody = bodyText;
+          }
+        } else {
+          responseBody = bodyText;
+        }
+
+        if (truncated) {
+          responseHeaders["x-truncated"] = `true (${text.length} bytes, showing first ${MAX_RESPONSE_SIZE})`;
+        }
+      }
+
+      return JSON.stringify({
+        status: response.status,
+        statusText: response.statusText,
+        headers: responseHeaders,
+        body: responseBody,
+      });
+    } catch (err: any) {
+      if (err.name === "AbortError") {
+        return `Error: Request timed out after ${effectiveTimeout}ms`;
+      }
+      return `Error: ${err.message}`;
+    } finally {
+      clearTimeout(timer);
+    }
+  },
+});