@kirosnn/mosaic 0.74.0 → 0.75.0

package/README.md

@@ -5,7 +5,7 @@
 <h1 align="center">Mosaic CLI</h1>
 
 <p align="center">
-  <strong>Version 0.74.0</strong>
+  <strong>Version 0.75.0</strong>
 </p>
 
 <p align="center">

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirosnn/mosaic",
-  "version": "0.74.0",
+  "version": "0.75.0",
   "description": "The open source coding agent.",
   "license": "MIT",
   "type": "module",
@@ -52,4 +52,4 @@
     "zod": "^3.23.8",
     "zod-to-json-schema": "^3.25.1"
   }
-}
+}

package/src/agent/prompts/systemPrompt.ts

@@ -5,7 +5,7 @@ import { getToolsPrompt } from './toolsPrompt';
 
 export const DEFAULT_SYSTEM_PROMPT = `You are Mosaic, an AI coding agent operating in the user's terminal.
 You assist with software engineering tasks: coding, debugging, refactoring, testing, and documentation.
-Version : 0.74.0 *(Beta)*
+Version : 0.75.0 *(Beta)*
 
 # Environment
 

package/src/agent/prompts/toolsPrompt.ts

@@ -38,21 +38,28 @@ List directory contents.
 ## Search & Discovery
 
 ### explore (RECOMMENDED for understanding context)
-Autonomous exploration agent that intelligently searches the codebase.
+Autonomous exploration agent that intelligently searches the codebase and the web.
 - purpose (string, required): What to find/understand
 
+The explore agent has access to: read, glob, grep, list, fetch (web pages), and search (web search).
+It can look up external documentation, API references, and tutorials when needed.
+
 USE EXPLORE WHEN:
 - Starting work on an unfamiliar codebase
 - Understanding how something works
 - Finding related code, patterns, or architecture
 - You're unsure where to make changes
+- You need to look up library/framework documentation
+- You need to research an API or find usage examples online
 
 Examples:
 - explore(purpose="Find API endpoints and understand routing")
 - explore(purpose="Understand the authentication flow")
 - explore(purpose="Find UserService and all its usages")
+- explore(purpose="Look up the React Query documentation for useQuery options")
+- explore(purpose="Find the Playwright API docs for page.waitForSelector")
 
-The explore tool is INTELLIGENT - it autonomously reads files, follows imports, and builds understanding. This is MORE EFFICIENT than manual glob/grep/read cycles.
+The explore tool is INTELLIGENT - it autonomously reads files, follows imports, searches the web, reads documentation, and builds understanding. This is MORE EFFICIENT than manual glob/grep/read/fetch cycles.
 
 ### glob
 Find files by name pattern. Fast file discovery.
@@ -144,6 +151,7 @@ CRITICAL: Never ask questions in plain text. Always use this tool.
 | Task | Tool | Example |
 |------|------|---------|
 | Understand codebase/architecture | explore | explore(purpose="How does auth work?") |
+| Look up external documentation | explore | explore(purpose="Find React Query docs for useMutation") |
 | Find files by name | glob | glob(pattern="**/*.config.ts") |
 | Find specific text | grep | grep(query="handleSubmit", file_type="tsx") |
 | Read file contents | read | read(path="src/auth.ts") |
@@ -154,6 +162,7 @@ CRITICAL: Never ask questions in plain text. Always use this tool.
 | Need user input | question | question(prompt="...", options=[...]) |
 
 PREFER EXPLORE for understanding context before making changes.
+PREFER EXPLORE for looking up documentation - it can search the web and read doc pages.
 PREFER grep with file_type for targeted text searches.
 
 # Continuation - CRITICAL

package/src/agent/tools/explore.ts

@@ -3,10 +3,10 @@ import { z } from 'zod';
 import { executeExploreTool } from './exploreExecutor';
 
 export const explore: CoreTool = tool({
-  description: `Explore the codebase autonomously to gather information.
-This tool launches an exploration agent that will use read, glob, grep, and list tools iteratively.
-The agent will continue exploring until it has gathered enough information to answer the purpose.
-Use this for open-ended exploration tasks like understanding code structure, finding implementations, etc.`,
+  description: `Explore the codebase and web autonomously to gather information.
+This tool launches an exploration agent that will use read, glob, grep, list, fetch, and search tools iteratively.
+The agent can search the web for documentation and fetch web pages when needed.
+Use this for open-ended exploration tasks like understanding code structure, finding implementations, looking up documentation, etc.`,
   parameters: z.object({
     purpose: z.string().describe('The goal of the exploration - what information you need to gather'),
   }),

package/src/agent/tools/exploreExecutor.ts

@@ -20,13 +20,15 @@ let exploreLogs: ExploreLog[] = [];
 
 const EXPLORE_TIMEOUT = 8 * 60 * 1000;
 
-const EXPLORE_SYSTEM_PROMPT = `You are an exploration agent that gathers information from a codebase.
+const EXPLORE_SYSTEM_PROMPT = `You are an exploration agent that gathers information from a codebase and the web.
 
-Your goal is to explore the codebase to fulfill the given purpose. You have access to these tools:
+Your goal is to explore the codebase and external documentation to fulfill the given purpose. You have access to these tools:
 - read: Read file contents
 - glob: Find files by pattern
 - grep: Search for text in files
 - list: List directory contents
+- fetch: Fetch a URL and return its content as markdown (for reading documentation pages, API docs, etc.)
+- search: Search the web for documentation, tutorials, API references, error solutions
 
 IMPORTANT RULES:
 1. Be thorough but efficient - don't repeat the same searches
@@ -34,7 +36,10 @@ IMPORTANT RULES:
 3. If you cannot find the information after reasonable exploration, call "done" with what you found
 4. Focus on the purpose - don't explore unrelated areas
 5. Summarize findings clearly and include relevant file paths and code snippets
-6. You MUST call the "done" tool when finished - this is the only way to complete the exploration`;
+6. You MUST call the "done" tool when finished - this is the only way to complete the exploration
+7. When the purpose involves understanding a library, framework, or external API, use search to find official documentation, then fetch to read the relevant pages
+8. Prefer official documentation over blog posts or Stack Overflow when possible
+9. If search is unavailable, you can still use fetch with known documentation URLs`;
 
 const MAX_STEPS = 100;
 
@@ -170,6 +175,53 @@ function createExploreTools() {
         return result.result;
       },
     }),
+    fetch: createTool({
+      description: 'Fetch a URL and return its content as markdown. Use this to read documentation pages, API references, tutorials, etc.',
+      parameters: z.object({
+        url: z.string().describe('The URL to fetch (must be a valid HTTP/HTTPS URL)'),
+        max_length: z.number().optional().describe('Maximum characters to return (default: 10000, max: 100000)'),
+      }),
+      execute: async (args) => {
+        if (isExploreAborted()) return { error: 'Exploration aborted' };
+        const result = await executeTool('fetch', { ...args, max_length: args.max_length ?? 10000 });
+        const resultLen = result.result?.length || 0;
+        const preview = result.success ? `${resultLen} chars` : (result.error || 'error');
+        exploreLogs.push({ tool: 'fetch', args, success: result.success, resultPreview: preview });
+        notifyExploreTool('fetch', args, { success: result.success, preview }, resultLen);
+        if (!result.success) return { error: result.error };
+        return result.result;
+      },
+    }),
+    search: createTool({
+      description: 'Search the web and return top results. Use this to find documentation, API references, tutorials, or solutions to errors.',
+      parameters: z.object({
+        query: z.string().describe('Search query'),
+        engine: z.enum(['google', 'bing', 'duckduckgo']).optional().describe('Search engine to use (default: google)'),
+      }),
+      execute: async (args) => {
+        if (isExploreAborted()) return { error: 'Exploration aborted' };
+        try {
+          const { getMcpManager, isMcpInitialized } = require('../../mcp/index');
+          if (!isMcpInitialized()) {
+            return { error: 'Web search unavailable (MCP not initialized)' };
+          }
+          const pm = getMcpManager();
+          const callArgs = { query: args.query, engine: args.engine || 'google' };
+          const result = await pm.callTool('navigation', 'navigation_search', callArgs);
+          const resultLen = result.content?.length || 0;
+          const preview = result.isError ? (result.content || 'error') : `${resultLen} chars`;
+          exploreLogs.push({ tool: 'search', args: callArgs, success: !result.isError, resultPreview: preview });
+          notifyExploreTool('search', callArgs, { success: !result.isError, preview }, resultLen);
+          if (result.isError) return { error: result.content || 'Search failed' };
+          return result.content;
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          exploreLogs.push({ tool: 'search', args, success: false, resultPreview: message });
+          notifyExploreTool('search', args, { success: false, preview: message }, 0);
+          return { error: `Web search failed: ${message}` };
+        }
+      },
+    }),
     done: createTool({
       description: 'Call this when you have gathered enough information. Provide a comprehensive summary of your findings. This MUST be called to complete the exploration.',
       parameters: z.object({
@@ -188,7 +240,7 @@ function formatExploreLogs(): string {
 
   const lines = ['Tools used:'];
   for (const log of exploreLogs) {
-    const argStr = log.args.path || log.args.pattern || log.args.query || '';
+    const argStr = log.args.path || log.args.pattern || log.args.query || log.args.url || '';
     const status = log.success ? '→' : '-';
     lines.push(`  ${status} ${log.tool}(${argStr}) -> ${log.resultPreview || 'ok'}`);
   }