@gugacoder/agentic-sdk 0.2.0

package/dist/tools/multi-edit.js

@@ -0,0 +1,57 @@
+import { tool } from "ai";
+import { z } from "zod";
+import { readFile, writeFile } from "node:fs/promises";
+export function createMultiEditTool(opts) {
+    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) {
+                return `Error editing file: ${err.message}`;
+            }
+        },
+    });
+    if (opts?.autoApprove === false) {
+        return Object.assign(baseTool, {
+            needsApproval: async () => true,
+        });
+    }
+    return baseTool;
+}
+export const multiEditTool = createMultiEditTool();

package/dist/tools/read.d.ts

@@ -0,0 +1,5 @@
+export declare const readTool: import("ai").Tool<{
+    file_path: string;
+    offset?: number | undefined;
+    limit?: number | undefined;
+}, string>;

package/dist/tools/read.js

@@ -0,0 +1,33 @@
+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) {
+            return `Error reading file: ${err.message}`;
+        }
+    },
+});

package/dist/tools/task.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 declare function createTaskTool(config?: TaskConfig): import("ai").Tool<{
+    description: string;
+    prompt: string;
+}, string>;

package/dist/tools/task.js

@@ -0,0 +1,51 @@
+import { tool } from "ai";
+import { z } from "zod";
+const MAX_OUTPUT = 50_000;
+/**
+ * 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) {
+    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) {
+                return `Error running sub-agent "${description}": ${err.message}`;
+            }
+        },
+    });
+}

package/dist/tools/todo.d.ts

@@ -0,0 +1,14 @@
+import type { AiTodoItem } from "../types.js";
+/** Reset state — useful for testing or when starting a new session */
+export declare function resetTodoState(): void;
+/** Read current todos — used internally by TodoRead and available for consumers */
+export declare function getTodos(): AiTodoItem[];
+export declare const todoWriteTool: import("ai").Tool<{
+    todos: {
+        status: "pending" | "in_progress" | "completed";
+        id: string;
+        content: string;
+        priority: "high" | "medium" | "low";
+    }[];
+}, string>;
+export declare const todoReadTool: import("ai").Tool<{}, string>;

package/dist/tools/todo.js

@@ -0,0 +1,60 @@
+import { tool } from "ai";
+import { z } from "zod";
+// Module-level state: session todos keyed by a simple singleton
+// (one agent run = one process = one list)
+let currentTodos = [];
+/** Reset state — useful for testing or when starting a new session */
+export function resetTodoState() {
+    currentTodos = [];
+}
+/** Read current todos — used internally by TodoRead and available for consumers */
+export function getTodos() {
+    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;
+        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 = {
+            pending: "○",
+            in_progress: "◐",
+            completed: "●",
+        };
+        const priorityTag = {
+            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/dist/tools/web-fetch.d.ts

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

package/dist/tools/web-fetch.js

@@ -0,0 +1,126 @@
+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) {
+    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;
+            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) {
+            if (err.name === "AbortError") {
+                return `Error: Request timed out after ${FETCH_TIMEOUT / 1000}s`;
+            }
+            return `Error fetching URL: ${err.message}`;
+        }
+    },
+});

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

@@ -0,0 +1,22 @@
+/**
+ * A single search result returned by a WebSearch provider.
+ */
+export interface WebSearchResult {
+    title: string;
+    url: string;
+    snippet: string;
+}
+/**
+ * Callback type for pluggable web search providers.
+ * Implementors receive the query and desired number of results,
+ * and return an array of WebSearchResult.
+ */
+export type WebSearchProvider = (query: string, numResults: number) => Promise<WebSearchResult[]>;
+/**
+ * Factory that creates the WebSearch tool with an injected search provider.
+ * If no provider is given, returns a tool that explains no provider is configured.
+ */
+export declare function createWebSearchTool(searchProvider?: WebSearchProvider): import("ai").Tool<{
+    query: string;
+    numResults: number;
+}, string>;

package/dist/tools/web-search.js

@@ -0,0 +1,48 @@
+import { tool } from "ai";
+import { z } from "zod";
+const MAX_OUTPUT = 50_000;
+/**
+ * Factory that creates the WebSearch tool with an injected search provider.
+ * If no provider is given, returns a tool that explains no provider is configured.
+ */
+export function createWebSearchTool(searchProvider) {
+    return tool({
+        description: "Search the web and return formatted results with title, URL, and snippet. Use this to find up-to-date information, documentation, or answers to questions.",
+        inputSchema: z.object({
+            query: z.string().describe("The search query"),
+            numResults: z
+                .number()
+                .int()
+                .min(1)
+                .max(20)
+                .optional()
+                .default(5)
+                .describe("Number of results to return (default: 5)"),
+        }),
+        execute: async ({ query, numResults }) => {
+            if (!searchProvider) {
+                return "WebSearch provider not configured. The consuming application must provide an onWebSearch callback in AiAgentOptions to enable web search.";
+            }
+            try {
+                const results = await searchProvider(query, numResults);
+                if (results.length === 0) {
+                    return `No results found for: "${query}"`;
+                }
+                let output = `# 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 += `**URL:** ${r.url}\n`;
+                    output += `${r.snippet}\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 web: ${err.message}`;
+            }
+        },
+    });
+}