min-agent 0.1.3 → 0.1.5

package/dist/tools/code_search.js

@@ -0,0 +1,91 @@
+import { tool, jsonSchema } from "ai";
+import { truncateToolOutput } from "../tool-output.js";
+const EXA_MCP_URL = process.env.EXA_API_KEY
+    ? `https://mcp.exa.ai/mcp?exaApiKey=${encodeURIComponent(process.env.EXA_API_KEY)}`
+    : "https://mcp.exa.ai/mcp";
+export const codeSearchTool = tool({
+    description: `Search and get relevant context for any programming task using Exa Code API.
+Provides high-quality, fresh context for libraries, SDKs, and APIs.
+Use this for ANY question or task related to programming — finding code examples, documentation, API references, and patterns.
+
+Usage:
+- Adjustable token count (1000-50000) for focused or comprehensive results
+- Default 5000 tokens for balanced context
+- Examples: 'React useState hook examples', 'Python pandas dataframe filtering', 'Express.js middleware', 'Rust async trait implementation'`,
+    inputSchema: jsonSchema({
+        type: "object",
+        properties: {
+            query: {
+                type: "string",
+                description: "Search query for APIs, libraries, SDKs. E.g. 'React useState hook examples', 'Express.js middleware'",
+            },
+            tokensNum: {
+                type: "number",
+                description: "Number of tokens to return (1000-50000). Default 5000. Use lower for focused queries, higher for comprehensive docs.",
+            },
+        },
+        required: ["query"],
+    }),
+    execute: async ({ query, tokensNum }) => {
+        const tokens = Math.max(1000, Math.min(50000, tokensNum ?? 5000));
+        try {
+            const result = await callExaCode(query, tokens);
+            if (!result) {
+                return "No code snippets or documentation found. Try a different query, be more specific about the library or concept, or check spelling.";
+            }
+            return truncateToolOutput(result, { direction: "head" }).content;
+        }
+        catch (err) {
+            return `Code search error: ${err.message}`;
+        }
+    },
+});
+/**
+ * Call Exa's MCP endpoint for code context.
+ * Uses JSON-RPC over HTTP with SSE response format.
+ */
+async function callExaCode(query, tokensNum) {
+    const body = JSON.stringify({
+        jsonrpc: "2.0",
+        id: 1,
+        method: "tools/call",
+        params: {
+            name: "get_code_context_exa",
+            arguments: { query, tokensNum },
+        },
+    });
+    const response = await fetch(EXA_MCP_URL, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Accept: "application/json, text/event-stream",
+        },
+        body,
+        signal: AbortSignal.timeout(30000),
+    });
+    if (!response.ok) {
+        throw new Error(`Exa API returned ${response.status}`);
+    }
+    const text = await response.text();
+    // Parse SSE response: look for "data: {...}" lines
+    for (const line of text.split("\n")) {
+        if (!line.startsWith("data: "))
+            continue;
+        try {
+            const data = JSON.parse(line.slice(6));
+            const content = data?.result?.content?.[0]?.text;
+            if (content)
+                return content;
+        }
+        catch { }
+    }
+    // Try parsing as direct JSON response
+    try {
+        const data = JSON.parse(text);
+        const content = data?.result?.content?.[0]?.text;
+        if (content)
+            return content;
+    }
+    catch { }
+    return null;
+}

package/dist/tools/explore.js

@@ -0,0 +1,104 @@
+import { tool, jsonSchema, streamText, stepCountIs } from "ai";
+import { resolveModel } from "../provider.js";
+import { bashTool } from "./bash.js";
+import { readTool } from "./read.js";
+import { globTool } from "./glob.js";
+import { grepTool } from "./grep.js";
+import { stripThinkingFromAssistantText } from "../assistant-stream.js";
+import { truncateToolOutput } from "../tool-output.js";
+const EXPLORE_SYSTEM = `You are a file search specialist. You excel at thoroughly navigating and exploring codebases.
+
+Your strengths:
+- Rapidly finding files using glob patterns
+- Searching code and text with powerful regex patterns
+- Reading and analyzing file contents
+
+Guidelines:
+- Use glob for broad file pattern matching
+- Use grep for searching file contents with regex
+- Use read when you know the specific file path
+- Use bash ONLY for read-only operations (ls, find, cat, wc, head, tail)
+- Adapt your search approach based on the thoroughness level specified
+- Return file paths as absolute paths in your final response
+- Do NOT create, modify, or delete any files
+- Do NOT run commands that change system state
+
+Complete the search request efficiently and report findings clearly.
+
+Working directory: ${process.cwd()}
+Platform: ${process.platform}`;
+const EXPLORE_MAX_STEPS = 20;
+export function createExploreTool(modelId) {
+    return tool({
+        description: `Deep codebase exploration agent. Use this to understand project structure, find files by patterns, search code for keywords, trace module relationships, or answer questions about the codebase.
+
+Specify thoroughness:
+- "quick": basic search, 1-3 tool calls
+- "medium": moderate exploration, follow references
+- "thorough": comprehensive analysis across multiple locations and naming conventions
+
+Examples:
+- "Find all API route handlers" (medium)
+- "How does the auth system work?" (thorough)
+- "Where is the database config?" (quick)`,
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {
+                query: { type: "string", description: "What to explore or find in the codebase" },
+                thoroughness: { type: "string", description: "Search depth: quick, medium, or thorough (default: medium)" },
+            },
+            required: ["query"],
+        }),
+        execute: async ({ query, thoroughness }) => {
+            const level = thoroughness ?? "medium";
+            console.log(`\x1b[90m  ┌─ Explore (${level}): ${query.slice(0, 60)}\x1b[0m`);
+            try {
+                const result = await runExploreAgent(query, level, modelId);
+                console.log(`\x1b[90m  └─ ✓ Done\x1b[0m`);
+                return truncateToolOutput(result, { direction: "head" }).content;
+            }
+            catch (err) {
+                console.log(`\x1b[90m  └─ ✗ Failed: ${err.message}\x1b[0m`);
+                return `Explore error: ${err.message}`;
+            }
+        },
+    });
+}
+async function runExploreAgent(query, thoroughness, modelId) {
+    const model = resolveModel(modelId);
+    // Read-only tools only
+    const tools = {
+        glob: globTool,
+        grep: grepTool,
+        read: readTool,
+        bash: bashTool, // bash is available but prompt restricts to read-only
+    };
+    const prompt = `Thoroughness level: ${thoroughness}
+${thoroughness === "quick" ? "Do a quick search (1-3 tool calls max)." : ""}
+${thoroughness === "medium" ? "Do a moderate exploration, follow references if needed." : ""}
+${thoroughness === "thorough" ? "Do a comprehensive analysis. Check multiple locations, naming conventions, and cross-references." : ""}
+
+Task: ${query}`;
+    const messages = [{ role: "user", content: prompt }];
+    const result = streamText({
+        model,
+        system: EXPLORE_SYSTEM,
+        messages,
+        tools,
+        stopWhen: stepCountIs(EXPLORE_MAX_STEPS),
+        maxRetries: 2,
+        onError() { },
+    });
+    let assistantText = "";
+    for await (const event of result.fullStream) {
+        switch (event.type) {
+            case "text-delta":
+                assistantText += event.text;
+                break;
+            case "tool-call":
+                console.log(`\x1b[90m  │ ⚡ ${event.toolName}\x1b[0m`);
+                break;
+        }
+    }
+    return stripThinkingFromAssistantText(assistantText) || "(explore agent produced no output)";
+}

package/dist/tools/index.js

@@ -6,8 +6,11 @@ import { globTool } from "./glob.js";
 import { grepTool } from "./grep.js";
 import { webSearchTool } from "./web_search.js";
 import { webFetchTool } from "./web_fetch.js";
+import { todoTool } from "./todo.js";
+import { questionTool } from "./question.js";
+import { codeSearchTool } from "./code_search.js";
 export function createTools() {
-    return {
+    const tools = {
         bash: bashTool,
         read: readTool,
         write: writeTool,
@@ -16,5 +19,11 @@ export function createTools() {
         grep: grepTool,
         web_search: webSearchTool,
         web_fetch: webFetchTool,
+        todo: todoTool,
+        question: questionTool,
     };
+    if (process.env.EXA_API_KEY) {
+        tools.codesearch = codeSearchTool;
+    }
+    return tools;
 }

package/dist/tools/question.js

@@ -0,0 +1,53 @@
+import { tool, jsonSchema } from "ai";
+import readline from "readline";
+export const questionTool = tool({
+    description: `Ask the user a question to get clarification before proceeding. Use this when:
+- The task is ambiguous and you need more information
+- There are multiple valid approaches and you want the user to choose
+- You need confirmation before a potentially destructive action
+- You're unsure about a requirement or preference
+
+Provide clear, specific questions. Optionally include numbered options for the user to choose from.`,
+    inputSchema: jsonSchema({
+        type: "object",
+        properties: {
+            question: { type: "string", description: "The question to ask the user" },
+            options: {
+                type: "array",
+                items: { type: "string" },
+                description: "Optional list of choices for the user to pick from",
+            },
+        },
+        required: ["question"],
+    }),
+    execute: async ({ question, options }) => {
+        console.log();
+        console.log(`\x1b[33m❓ ${question}\x1b[0m`);
+        if (options && options.length > 0) {
+            for (let i = 0; i < options.length; i++) {
+                console.log(`\x1b[90m   ${i + 1}. ${options[i]}\x1b[0m`);
+            }
+        }
+        const answer = await askUser();
+        // If user picked a number and options exist, resolve it
+        if (options && options.length > 0) {
+            const idx = parseInt(answer) - 1;
+            if (idx >= 0 && idx < options.length) {
+                return `User chose: ${options[idx]}`;
+            }
+        }
+        return `User answered: ${answer}`;
+    },
+});
+function askUser() {
+    return new Promise((resolve) => {
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        rl.question("\x1b[36m   → \x1b[0m", (answer) => {
+            rl.close();
+            resolve(answer.trim() || "(no answer)");
+        });
+    });
+}

package/dist/tools/read.js

@@ -2,6 +2,9 @@ import { tool, jsonSchema } from "ai";
 import { readFileSync, statSync } from "fs";
 import path from "path";
 import { truncateToolOutput } from "../tool-output.js";
+import { InstructionTracker } from "../instructions.js";
+// Shared tracker instance for context-aware instruction discovery
+const instructionTracker = new InstructionTracker();
 export const readTool = tool({
     description: "Read the contents of a file. Returns the file content as text. Use this to understand code, check configurations, etc.",
     inputSchema: jsonSchema({
@@ -20,14 +23,22 @@ export const readTool = tool({
             if (stat.isDirectory())
                 return `Error: ${filePath} is a directory, not a file`;
             const content = readFileSync(resolved, "utf-8");
+            let result;
             if (startLine || endLine) {
                 const lines = content.split("\n");
                 const start = (startLine ?? 1) - 1;
                 const end = endLine ?? lines.length;
-                const slice = lines.slice(start, end).join("\n");
-                return truncateToolOutput(slice, { direction: "head" }).content;
+                result = lines.slice(start, end).join("\n");
             }
-            return truncateToolOutput(content, { direction: "head" }).content;
+            else {
+                result = content;
+            }
+            // Context-aware: discover nearby instruction files
+            const nearbyInstructions = instructionTracker.resolveForFile(resolved);
+            if (nearbyInstructions.length > 0) {
+                result += "\n\n<system-reminder>\n" + nearbyInstructions.join("\n\n") + "\n</system-reminder>";
+            }
+            return truncateToolOutput(result, { direction: "head" }).content;
         }
         catch (err) {
             return `Error reading file: ${err.message}`;

package/dist/tools/task.js

@@ -0,0 +1,98 @@
+import { tool, jsonSchema, streamText, stepCountIs } from "ai";
+import { resolveModel } from "../provider.js";
+import { createTools } from "./index.js";
+import { getMcpTools } from "../mcp.js";
+import { getSkillsTool, getSkills } from "../skills.js";
+import { loadPluginTools } from "../plugins.js";
+import { DoomLoopDetector } from "../doom-loop.js";
+import { stripThinkingFromAssistantText } from "../assistant-stream.js";
+import { truncateToolOutput } from "../tool-output.js";
+const SUB_AGENT_MAX_STEPS = 15;
+const SUB_AGENT_SYSTEM = `You are a focused sub-agent executing a specific task. Complete the task thoroughly and return a clear result.
+
+Rules:
+- Focus only on the assigned task
+- Be thorough but concise
+- Use tools as needed to complete the task
+- Return a clear summary of what you did and the result
+
+Working directory: ${process.cwd()}
+Platform: ${process.platform}
+Date: ${new Date().toDateString()}`;
+export function createTaskTool(modelId) {
+    return tool({
+        description: `Launch a sub-agent to execute a task independently. The sub-agent has its own context and tools. Use this for:
+- Parallel execution: call multiple tasks at once for independent work
+- Context isolation: keep the main conversation clean while the sub-agent explores
+- Delegation: hand off well-defined subtasks (search, analysis, file operations)
+
+The sub-agent can read/write files, run commands, search, and use all available tools.
+Call multiple tasks in parallel when the work is independent.`,
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {
+                description: { type: "string", description: "Short description of the task (shown to user)" },
+                prompt: { type: "string", description: "Detailed instructions for the sub-agent" },
+            },
+            required: ["description", "prompt"],
+        }),
+        execute: async ({ description, prompt }) => {
+            console.log(`\x1b[90m  ┌─ Sub-agent: ${description}\x1b[0m`);
+            try {
+                const result = await runSubAgent(prompt, modelId);
+                console.log(`\x1b[90m  └─ ✓ Done\x1b[0m`);
+                return truncateToolOutput(result, { direction: "head" }).content;
+            }
+            catch (err) {
+                console.log(`\x1b[90m  └─ ✗ Failed: ${err.message}\x1b[0m`);
+                return `Sub-agent error: ${err.message}`;
+            }
+        },
+    });
+}
+async function runSubAgent(prompt, modelId) {
+    const model = resolveModel(modelId);
+    // Build tools for sub-agent (no task tool to prevent recursion)
+    const builtinTools = createTools();
+    const mcpTools = getMcpTools();
+    const pluginTools = await loadPluginTools();
+    const skills = getSkills();
+    const allTools = { ...builtinTools, ...pluginTools };
+    for (const [id, t] of Object.entries(mcpTools))
+        allTools[id] = t;
+    if (skills.length > 0)
+        allTools["skill"] = getSkillsTool();
+    // Remove task tool from sub-agent to prevent infinite recursion
+    delete allTools["task"];
+    const messages = [{ role: "user", content: prompt }];
+    const doomLoop = new DoomLoopDetector();
+    const result = streamText({
+        model,
+        system: SUB_AGENT_SYSTEM,
+        messages,
+        tools: allTools,
+        stopWhen: stepCountIs(SUB_AGENT_MAX_STEPS),
+        maxRetries: 2,
+        onError() { },
+    });
+    let assistantText = "";
+    for await (const event of result.fullStream) {
+        switch (event.type) {
+            case "text-delta":
+                assistantText += event.text;
+                break;
+            case "tool-call":
+                if (doomLoop.record(event.toolName, event.input)) {
+                    return assistantText + "\n\n[Sub-agent stopped: doom loop detected]";
+                }
+                console.log(`\x1b[90m  │ ⚡ ${event.toolName}\x1b[0m`);
+                break;
+            case "tool-result":
+                break;
+            case "error":
+                return assistantText + `\n\n[Sub-agent error: ${event.error}]`;
+        }
+    }
+    const cleaned = stripThinkingFromAssistantText(assistantText);
+    return cleaned || "(sub-agent produced no output)";
+}

package/dist/tools/todo.js

@@ -0,0 +1,88 @@
+import { tool, jsonSchema } from "ai";
+let todos = [];
+let nextId = 1;
+export function getTodos() {
+    return todos;
+}
+export function resetTodos() {
+    todos = [];
+    nextId = 1;
+}
+function formatTodos() {
+    if (todos.length === 0)
+        return "No tasks.";
+    const icons = {
+        pending: "○",
+        in_progress: "◐",
+        done: "●",
+        cancelled: "✕",
+    };
+    return todos
+        .map((t) => `  ${icons[t.status]} #${t.id} ${t.text}`)
+        .join("\n");
+}
+function printTodos() {
+    if (todos.length === 0)
+        return;
+    console.log(`\x1b[90m  ┌─ Tasks${"─".repeat(36)}\x1b[0m`);
+    for (const t of todos) {
+        const icon = t.status === "done" ? "\x1b[32m●\x1b[0m"
+            : t.status === "in_progress" ? "\x1b[33m◐\x1b[0m"
+                : t.status === "cancelled" ? "\x1b[90m✕\x1b[0m"
+                    : "\x1b[90m○\x1b[0m";
+        const dim = t.status === "done" || t.status === "cancelled" ? "\x1b[90m" : "";
+        const reset = dim ? "\x1b[0m" : "";
+        console.log(`\x1b[90m  │\x1b[0m ${icon} ${dim}#${t.id} ${t.text}${reset}`);
+    }
+    console.log(`\x1b[90m  └${"─".repeat(44)}\x1b[0m`);
+}
+export const todoTool = tool({
+    description: `Create or update tasks to track progress. Use this FREQUENTLY to:
+- Plan multi-step work by creating tasks upfront
+- Mark tasks as in_progress when starting them
+- Mark tasks as done when completed
+- Give the user visibility into your progress
+
+To create new tasks: provide items with "text" and optionally "status" (defaults to "pending").
+To update existing tasks: provide items with "id" and "status".
+You can mix creates and updates in one call.`,
+    inputSchema: jsonSchema({
+        type: "object",
+        properties: {
+            todos: {
+                type: "array",
+                description: "List of tasks to create or update",
+                items: {
+                    type: "object",
+                    properties: {
+                        text: { type: "string", description: "Task description (for new tasks)" },
+                        status: { type: "string", description: "Status: pending, in_progress, done, cancelled" },
+                        id: { type: "number", description: "Task ID (for updating existing tasks)" },
+                    },
+                },
+            },
+        },
+        required: ["todos"],
+    }),
+    execute: async ({ todos: items }) => {
+        for (const item of items) {
+            if (item.id) {
+                // Update existing
+                const existing = todos.find((t) => t.id === item.id);
+                if (existing && item.status) {
+                    existing.status = item.status;
+                }
+            }
+            else if (item.text) {
+                // Create new
+                todos.push({
+                    id: nextId++,
+                    text: item.text,
+                    status: item.status ?? "pending",
+                });
+            }
+        }
+        printTodos();
+        return formatTodos();
+    },
+});