@gugacoder/agentic-sdk 0.2.0

package/src/tools/index.ts

@@ -0,0 +1,48 @@
+import { readTool } from "./read.js";
+import { writeTool, createWriteTool } from "./write.js";
+import { editTool, createEditTool } from "./edit.js";
+import { bashTool, createBashTool } from "./bash.js";
+import { globTool } from "./glob.js";
+import { grepTool } from "./grep.js";
+import { listDirTool } from "./list-dir.js";
+import { multiEditTool, createMultiEditTool } from "./multi-edit.js";
+import { todoWriteTool, todoReadTool } from "./todo.js";
+import { diagnosticsTool } from "./diagnostics.js";
+import { createAskUserTool } from "./ask-user.js";
+import { webFetchTool } from "./web-fetch.js";
+import { createWebSearchTool } from "./web-search.js";
+import { createTaskTool } from "./task.js";
+import { createBatchTool } from "./batch.js";
+import { applyPatchTool, createApplyPatchTool } from "./apply-patch.js";
+import { createCodeSearchTool } from "./code-search.js";
+import { httpRequestTool } from "./http-request.js";
+import { apiSpecTool } from "./api-spec.js";
+
+export { createBashTool } from "./bash.js";
+export { createWriteTool } from "./write.js";
+export { createEditTool } from "./edit.js";
+export { createMultiEditTool } from "./multi-edit.js";
+export { createApplyPatchTool } from "./apply-patch.js";
+
+export const codingTools = {
+  Read: readTool,
+  Write: writeTool,
+  Edit: editTool,
+  Bash: bashTool,
+  Glob: globTool,
+  Grep: grepTool,
+  ListDir: listDirTool,
+  MultiEdit: multiEditTool,
+  TodoWrite: todoWriteTool,
+  TodoRead: todoReadTool,
+  Diagnostics: diagnosticsTool,
+  AskUser: createAskUserTool(),
+  WebFetch: webFetchTool,
+  WebSearch: createWebSearchTool(),
+  Task: createTaskTool(),
+  Batch: createBatchTool({}),
+  ApplyPatch: applyPatchTool,
+  CodeSearch: createCodeSearchTool(),
+  HttpRequest: httpRequestTool,
+  ApiSpec: apiSpecTool,
+};

package/src/tools/job-tools.ts

@@ -0,0 +1,84 @@
+/**
+ * Vercel AI SDK tool wrappers for job management.
+ * Uses callbacks to avoid coupling to a specific job engine implementation.
+ */
+import { tool } from "ai";
+import { z } from "zod";
+
+export interface JobToolCallbacks {
+  submitJob: (opts: {
+    agentId: string;
+    command: string;
+    timeout?: number;
+  }) => unknown;
+  listJobs: (agentId?: string) => unknown[];
+  getJob: (jobId: string) => unknown | undefined;
+  killJob: (jobId: string) => boolean;
+  getAgentId: () => string | undefined;
+}
+
+export function createJobTools(callbacks: JobToolCallbacks) {
+  return {
+    submit_job: tool({
+      description:
+        "Submit a long-running process for backbone supervision. The backbone captures output, applies timeout, and wakes you up when the job finishes.",
+      inputSchema: z.object({
+        command: z
+          .string()
+          .describe("Shell command to execute (e.g. 'sleep 30')"),
+        timeout: z
+          .number()
+          .optional()
+          .describe("Timeout in seconds. Default: 1800 (30min)"),
+      }),
+      execute: async ({ command, timeout }) => {
+        const agentId = callbacks.getAgentId();
+        if (!agentId) return "Error: AGENT_ID not available";
+        try {
+          const summary = callbacks.submitJob({
+            agentId,
+            command,
+            timeout,
+          });
+          return JSON.stringify(summary);
+        } catch (err) {
+          return `Error: ${err instanceof Error ? err.message : String(err)}`;
+        }
+      },
+    }),
+
+    list_jobs: tool({
+      description:
+        "List all jobs for this agent. Returns an array of job summaries.",
+      inputSchema: z.object({}),
+      execute: async () => {
+        const agentId = callbacks.getAgentId();
+        return JSON.stringify(callbacks.listJobs(agentId ?? undefined));
+      },
+    }),
+
+    get_job: tool({
+      description:
+        "Get full details of a specific job including output tail, status, exit code, and duration.",
+      inputSchema: z.object({
+        jobId: z.string().describe("Job ID to query"),
+      }),
+      execute: async ({ jobId }) => {
+        const job = callbacks.getJob(jobId);
+        return job ? JSON.stringify(job) : "Job not found";
+      },
+    }),
+
+    kill_job: tool({
+      description: "Kill a running job with SIGKILL.",
+      inputSchema: z.object({
+        jobId: z.string().describe("Job ID to kill"),
+      }),
+      execute: async ({ jobId }) => {
+        return callbacks.killJob(jobId)
+          ? "Job killed successfully"
+          : "Job not found or already finished";
+      },
+    }),
+  };
+}

package/src/tools/list-dir.ts

@@ -0,0 +1,102 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { readdir, stat } from "node:fs/promises";
+import { join, basename } from "node:path";
+
+const DEFAULT_IGNORE = ["node_modules", ".git", "dist", "build"];
+
+async function buildTree(
+  dirPath: string,
+  depth: number,
+  maxDepth: number,
+  ignore: string[],
+  prefix: string
+): Promise<string[]> {
+  if (depth >= maxDepth) return [];
+
+  let entries;
+  try {
+    entries = await readdir(dirPath, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  // Filter ignored entries
+  entries = entries.filter((e) => !ignore.includes(e.name));
+
+  // Sort: directories first, then files, alphabetically within each group
+  entries.sort((a, b) => {
+    if (a.isDirectory() && !b.isDirectory()) return -1;
+    if (!a.isDirectory() && b.isDirectory()) return 1;
+    return a.name.localeCompare(b.name);
+  });
+
+  const lines: string[] = [];
+
+  for (let i = 0; i < entries.length; i++) {
+    const entry = entries[i];
+    const isLast = i === entries.length - 1;
+    const connector = isLast ? "└── " : "├── ";
+    const childPrefix = isLast ? "    " : "│   ";
+
+    if (entry.isDirectory()) {
+      lines.push(`${prefix}${connector}${entry.name}/`);
+      const children = await buildTree(
+        join(dirPath, entry.name),
+        depth + 1,
+        maxDepth,
+        ignore,
+        prefix + childPrefix
+      );
+      lines.push(...children);
+    } else {
+      lines.push(`${prefix}${connector}${entry.name}`);
+    }
+  }
+
+  return lines;
+}
+
+export const listDirTool = tool({
+  description:
+    "Lists files and directories as an indented tree. Use this to understand project structure.",
+  inputSchema: z.object({
+    path: z.string().describe("Absolute path of the directory to list"),
+    depth: z
+      .number()
+      .optional()
+      .default(3)
+      .describe("Maximum depth to traverse (default: 3)"),
+    ignore: z
+      .array(z.string())
+      .optional()
+      .default(DEFAULT_IGNORE)
+      .describe(
+        "Directory/file names to ignore (default: node_modules, .git, dist, build)"
+      ),
+  }),
+  execute: async ({ path, depth, ignore }) => {
+    try {
+      const s = await stat(path);
+      if (!s.isDirectory()) {
+        return `Error: ${path} is not a directory`;
+      }
+
+      const rootName = basename(path) || path;
+      const lines = [`${rootName}/`];
+      const children = await buildTree(path, 0, depth, ignore, "");
+      lines.push(...children);
+
+      const result = lines.join("\n");
+
+      // Respect 50KB output limit
+      if (result.length > 50_000) {
+        return result.slice(0, 50_000) + "\n... (truncated at 50KB)";
+      }
+
+      return result;
+    } catch (err: any) {
+      return `Error: ${err.message}`;
+    }
+  },
+});

package/src/tools/multi-edit.ts

@@ -0,0 +1,65 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { readFile, writeFile } from "node:fs/promises";
+
+export function createMultiEditTool(opts?: { autoApprove?: boolean }) {
+  const baseTool = tool({
+    description:
+      "Applies multiple string replacements to a single file atomically. If any edit fails (old_string not found), none are applied.",
+    inputSchema: z.object({
+      file_path: z.string().describe("Absolute path to the file to edit"),
+      edits: z
+        .array(
+          z.object({
+            old_string: z.string().describe("The exact text to find"),
+            new_string: z.string().describe("The replacement text"),
+            replace_all: z
+              .boolean()
+              .optional()
+              .default(false)
+              .describe("Replace all occurrences instead of just the first"),
+          })
+        )
+        .min(1)
+        .describe("Array of edits to apply sequentially"),
+    }),
+    execute: async ({ file_path, edits }) => {
+      try {
+        let content = await readFile(file_path, "utf-8");
+
+        // Validation pass: check all old_strings exist before applying any edit
+        for (let i = 0; i < edits.length; i++) {
+          const edit = edits[i];
+          if (!content.includes(edit.old_string)) {
+            return `Error: edit[${i}] old_string not found in ${file_path}. No edits applied (atomic rollback).`;
+          }
+          if (!edit.replace_all) {
+            const count = content.split(edit.old_string).length - 1;
+            if (count > 1) {
+              return `Error: edit[${i}] old_string appears ${count} times. Provide more context or set replace_all to true. No edits applied.`;
+            }
+          }
+          // Apply the edit to the working content so subsequent edits see the result
+          content = edit.replace_all
+            ? content.replaceAll(edit.old_string, edit.new_string)
+            : content.replace(edit.old_string, edit.new_string);
+        }
+
+        await writeFile(file_path, content, "utf-8");
+        return `${edits.length} edit(s) applied successfully to ${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 multiEditTool = createMultiEditTool();

package/src/tools/read.ts

@@ -0,0 +1,40 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { readFile } from "node:fs/promises";
+
+export const readTool = tool({
+  description:
+    "Reads a file from the local filesystem. Returns content with line numbers (cat -n format).",
+  inputSchema: z.object({
+    file_path: z.string().describe("Absolute path to the file to read"),
+    offset: z
+      .number()
+      .optional()
+      .describe("Line number to start reading from (1-based)"),
+    limit: z
+      .number()
+      .optional()
+      .describe("Maximum number of lines to read"),
+  }),
+  execute: async ({ file_path, offset, limit }) => {
+    try {
+      const content = await readFile(file_path, "utf-8");
+      let lines = content.split("\n");
+
+      const start = offset ? offset - 1 : 0;
+      const end = limit ? start + limit : lines.length;
+      lines = lines.slice(start, end);
+
+      const maxLineNum = start + lines.length;
+      const pad = String(maxLineNum).length;
+
+      const numbered = lines.map(
+        (line, i) =>
+          `${String(start + i + 1).padStart(pad)}\t${line}`
+      );
+      return numbered.join("\n");
+    } catch (err: any) {
+      return `Error reading file: ${err.message}`;
+    }
+  },
+});

package/src/tools/task.ts

@@ -0,0 +1,71 @@
+import { tool } from "ai";
+import { z } from "zod";
+
+const MAX_OUTPUT = 50_000;
+
+/**
+ * Configuration for spawning a sub-agent via the Task tool.
+ * Inherits model/apiKey from the parent agent.
+ */
+export interface TaskConfig {
+  model: string;
+  apiKey: string;
+  /** Maximum steps the sub-agent can take (default: 10) */
+  maxSubSteps?: number;
+}
+
+/**
+ * Factory that creates the Task tool for launching sub-agents.
+ *
+ * If no config is provided, returns a tool that explains it's not configured.
+ * When configured, uses runAiAgent() internally to spawn an isolated sub-agent
+ * that inherits the parent's model and apiKey but has no access to conversation history.
+ */
+export function createTaskTool(config?: TaskConfig) {
+  return tool({
+    description:
+      "Launch a sub-agent to handle a task autonomously. The sub-agent receives the same coding tools but runs in an isolated session without access to the parent's conversation history. Use this for tasks that can be completed independently.",
+    inputSchema: z.object({
+      description: z
+        .string()
+        .describe("Short description of the task (3-5 words)"),
+      prompt: z
+        .string()
+        .describe("Detailed instructions for the sub-agent to execute"),
+    }),
+    execute: async ({ description, prompt }) => {
+      if (!config) {
+        return "Task tool not configured. The consuming application must provide model and apiKey configuration to enable sub-agent spawning.";
+      }
+
+      try {
+        // Dynamic import to avoid circular dependency at module load time
+        const { runAiAgent } = await import("../agent.js");
+
+        let resultText = "";
+
+        const generator = runAiAgent(prompt, {
+          model: config.model,
+          apiKey: config.apiKey,
+          maxSteps: config.maxSubSteps ?? 10,
+        });
+
+        for await (const event of generator) {
+          if (event.type === "result") {
+            resultText = event.content;
+          }
+        }
+
+        let output = `## Sub-agent result for: "${description}"\n\n${resultText}`;
+
+        if (output.length > MAX_OUTPUT) {
+          output = output.slice(0, MAX_OUTPUT) + "\n...[truncated at 50KB]";
+        }
+
+        return output;
+      } catch (err: any) {
+        return `Error running sub-agent "${description}": ${err.message}`;
+      }
+    },
+  });
+}

package/src/tools/todo.ts

@@ -0,0 +1,82 @@
+import { tool } from "ai";
+import { z } from "zod";
+import type { AiTodoItem } from "../types.js";
+
+// Module-level state: session todos keyed by a simple singleton
+// (one agent run = one process = one list)
+let currentTodos: AiTodoItem[] = [];
+
+/** Reset state — useful for testing or when starting a new session */
+export function resetTodoState(): void {
+  currentTodos = [];
+}
+
+/** Read current todos — used internally by TodoRead and available for consumers */
+export function getTodos(): AiTodoItem[] {
+  return [...currentTodos];
+}
+
+const todoItemSchema = z.object({
+  id: z.string().describe("Unique identifier for the todo item"),
+  content: z.string().describe("Description of the task"),
+  status: z
+    .enum(["pending", "in_progress", "completed"])
+    .describe("Current status of the task"),
+  priority: z
+    .enum(["high", "medium", "low"])
+    .describe("Priority level of the task"),
+});
+
+export const todoWriteTool = tool({
+  description:
+    "Creates or updates the task list for the current session. Replaces the entire list with the provided todos. Use this to track progress on multi-step tasks.",
+  inputSchema: z.object({
+    todos: z
+      .array(todoItemSchema)
+      .min(1)
+      .describe("The complete list of todos (replaces any existing list)"),
+  }),
+  execute: async ({ todos }) => {
+    currentTodos = todos as AiTodoItem[];
+
+    const pending = currentTodos.filter((t) => t.status === "pending").length;
+    const inProgress = currentTodos.filter(
+      (t) => t.status === "in_progress"
+    ).length;
+    const completed = currentTodos.filter(
+      (t) => t.status === "completed"
+    ).length;
+
+    return `Todo list updated: ${currentTodos.length} items (${completed} completed, ${inProgress} in progress, ${pending} pending)`;
+  },
+});
+
+export const todoReadTool = tool({
+  description:
+    "Reads the current task list for the session. Returns all todos with their status and priority.",
+  inputSchema: z.object({}),
+  execute: async () => {
+    if (currentTodos.length === 0) {
+      return "Nenhuma tarefa registrada.";
+    }
+
+    const statusIcon: Record<string, string> = {
+      pending: "○",
+      in_progress: "◐",
+      completed: "●",
+    };
+
+    const priorityTag: Record<string, string> = {
+      high: "[HIGH]",
+      medium: "[MED]",
+      low: "[LOW]",
+    };
+
+    const lines = currentTodos.map(
+      (t) =>
+        `${statusIcon[t.status]} ${priorityTag[t.priority]} ${t.id}: ${t.content} (${t.status})`
+    );
+
+    return lines.join("\n");
+  },
+});

package/src/tools/web-fetch.ts

@@ -0,0 +1,155 @@
+import { tool } from "ai";
+import { z } from "zod";
+
+const MAX_OUTPUT = 50_000;
+const FETCH_TIMEOUT = 30_000;
+
+/**
+ * Converts HTML to a simplified markdown representation.
+ * Handles common elements: headings, links, lists, paragraphs, code blocks, bold, italic.
+ */
+function htmlToMarkdown(html: string): string {
+  let text = html;
+
+  // Remove script, style, nav, footer, header tags and their content
+  text = text.replace(/<(script|style|nav|footer|header|aside|svg|noscript)\b[^>]*>[\s\S]*?<\/\1>/gi, "");
+
+  // Remove HTML comments
+  text = text.replace(/<!--[\s\S]*?-->/g, "");
+
+  // Headings
+  text = text.replace(/<h1\b[^>]*>([\s\S]*?)<\/h1>/gi, "\n# $1\n");
+  text = text.replace(/<h2\b[^>]*>([\s\S]*?)<\/h2>/gi, "\n## $1\n");
+  text = text.replace(/<h3\b[^>]*>([\s\S]*?)<\/h3>/gi, "\n### $1\n");
+  text = text.replace(/<h4\b[^>]*>([\s\S]*?)<\/h4>/gi, "\n#### $1\n");
+  text = text.replace(/<h5\b[^>]*>([\s\S]*?)<\/h5>/gi, "\n##### $1\n");
+  text = text.replace(/<h6\b[^>]*>([\s\S]*?)<\/h6>/gi, "\n###### $1\n");
+
+  // Code blocks (pre > code)
+  text = text.replace(/<pre\b[^>]*>\s*<code\b[^>]*>([\s\S]*?)<\/code>\s*<\/pre>/gi, "\n```\n$1\n```\n");
+  text = text.replace(/<pre\b[^>]*>([\s\S]*?)<\/pre>/gi, "\n```\n$1\n```\n");
+
+  // Inline code
+  text = text.replace(/<code\b[^>]*>([\s\S]*?)<\/code>/gi, "`$1`");
+
+  // Bold
+  text = text.replace(/<(strong|b)\b[^>]*>([\s\S]*?)<\/\1>/gi, "**$2**");
+
+  // Italic
+  text = text.replace(/<(em|i)\b[^>]*>([\s\S]*?)<\/\1>/gi, "*$2*");
+
+  // Links
+  text = text.replace(/<a\b[^>]*href="([^"]*)"[^>]*>([\s\S]*?)<\/a>/gi, "[$2]($1)");
+
+  // Images
+  text = text.replace(/<img\b[^>]*alt="([^"]*)"[^>]*src="([^"]*)"[^>]*\/?>/gi, "![$1]($2)");
+  text = text.replace(/<img\b[^>]*src="([^"]*)"[^>]*alt="([^"]*)"[^>]*\/?>/gi, "![$2]($1)");
+  text = text.replace(/<img\b[^>]*src="([^"]*)"[^>]*\/?>/gi, "![]($1)");
+
+  // List items
+  text = text.replace(/<li\b[^>]*>([\s\S]*?)<\/li>/gi, "- $1\n");
+
+  // Unordered/ordered list wrappers
+  text = text.replace(/<\/?(ul|ol)\b[^>]*>/gi, "\n");
+
+  // Paragraphs and divs
+  text = text.replace(/<\/?p\b[^>]*>/gi, "\n");
+  text = text.replace(/<\/?div\b[^>]*>/gi, "\n");
+
+  // Line breaks
+  text = text.replace(/<br\s*\/?>/gi, "\n");
+
+  // Horizontal rules
+  text = text.replace(/<hr\b[^>]*\/?>/gi, "\n---\n");
+
+  // Table handling (basic)
+  text = text.replace(/<\/tr>/gi, "\n");
+  text = text.replace(/<\/?(table|thead|tbody|tfoot)\b[^>]*>/gi, "\n");
+  text = text.replace(/<th\b[^>]*>([\s\S]*?)<\/th>/gi, "| **$1** ");
+  text = text.replace(/<td\b[^>]*>([\s\S]*?)<\/td>/gi, "| $1 ");
+
+  // Strip remaining HTML tags
+  text = text.replace(/<[^>]+>/g, "");
+
+  // Decode common HTML entities
+  text = text.replace(/&amp;/g, "&");
+  text = text.replace(/&lt;/g, "<");
+  text = text.replace(/&gt;/g, ">");
+  text = text.replace(/&quot;/g, '"');
+  text = text.replace(/&#39;/g, "'");
+  text = text.replace(/&nbsp;/g, " ");
+  text = text.replace(/&#(\d+);/g, (_, code) => String.fromCharCode(Number(code)));
+
+  // Clean up whitespace: collapse multiple blank lines
+  text = text.replace(/\n{3,}/g, "\n\n");
+  text = text.trim();
+
+  return text;
+}
+
+export const webFetchTool = tool({
+  description:
+    "Fetches content from a URL and returns it as markdown/text. Converts HTML to markdown. Timeout: 30s. Max output: 50KB.",
+  inputSchema: z.object({
+    url: z.string().url().describe("The URL to fetch content from"),
+    prompt: z
+      .string()
+      .optional()
+      .describe("Extraction instruction — what to look for in the content"),
+  }),
+  execute: async ({ url, prompt }) => {
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT);
+
+      const response = await fetch(url, {
+        signal: controller.signal,
+        headers: {
+          "User-Agent": "AiSDK/1.0 (WebFetch tool)",
+          Accept: "text/html, application/json, text/plain, */*",
+        },
+      });
+
+      clearTimeout(timer);
+
+      if (!response.ok) {
+        return `Error: HTTP ${response.status} ${response.statusText}`;
+      }
+
+      const contentType = response.headers.get("content-type") ?? "";
+      const rawBody = await response.text();
+
+      let content: string;
+
+      if (contentType.includes("text/html")) {
+        content = htmlToMarkdown(rawBody);
+      } else if (contentType.includes("application/json")) {
+        try {
+          const parsed = JSON.parse(rawBody);
+          content = JSON.stringify(parsed, null, 2);
+        } catch {
+          content = rawBody;
+        }
+      } else {
+        content = rawBody;
+      }
+
+      if (content.length > MAX_OUTPUT) {
+        content = content.slice(0, MAX_OUTPUT) + "\n...[truncated at 50KB]";
+      }
+
+      let result = `# Fetched: ${url}\n\n${content}`;
+
+      if (prompt) {
+        result = `# Fetched: ${url}\n# Extraction: ${prompt}\n\n${content}`;
+      }
+
+      return result;
+    } catch (err: any) {
+      if (err.name === "AbortError") {
+        return `Error: Request timed out after ${FETCH_TIMEOUT / 1000}s`;
+      }
+      return `Error fetching URL: ${err.message}`;
+    }
+  },
+});