@kirosnn/mosaic 0.73.0 → 0.75.0

package/README.md

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirosnn/mosaic",
-  "version": "0.73.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.73.0 *(Beta)*
+Version : 0.75.0 *(Beta)*
 
 # Environment
 

package/src/agent/prompts/toolsPrompt.ts

@@ -1,3 +1,9 @@
+import { NATIVE_SERVER_IDS } from '../../mcp/types';
+
+const NATIVE_SERVER_LABELS: Record<string, string> = {
+  navigation: 'Browser Navigation',
+};
+
 export const TOOLS_PROMPT = `
 # Available Tools
 
@@ -32,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.
@@ -138,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") |
@@ -148,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
@@ -235,8 +250,63 @@ export function getToolsPrompt(mcpToolInfos?: Array<{ serverId: string; name: st
     return TOOLS_PROMPT;
   }
 
-  const mcpSection = buildMcpToolsSection(mcpToolInfos);
-  return TOOLS_PROMPT + '\n\n' + mcpSection;
+  const nativeTools = mcpToolInfos.filter(t => NATIVE_SERVER_IDS.has(t.serverId));
+  const externalTools = mcpToolInfos.filter(t => !NATIVE_SERVER_IDS.has(t.serverId));
+
+  let result = TOOLS_PROMPT;
+
+  if (nativeTools.length > 0) {
+    result += '\n\n' + buildNativeToolsSection(nativeTools);
+  }
+
+  if (externalTools.length > 0) {
+    result += '\n\n' + buildMcpToolsSection(externalTools);
+  }
+
+  return result;
+}
+
+function buildNativeToolsSection(tools: Array<{ serverId: string; name: string; description: string; inputSchema: Record<string, unknown>; canonicalId: string; safeId: string }>): string {
+  const lines: string[] = [];
+
+  const byServer = new Map<string, typeof tools>();
+  for (const t of tools) {
+    const list = byServer.get(t.serverId) || [];
+    list.push(t);
+    byServer.set(t.serverId, list);
+  }
+
+  for (const [serverId, serverTools] of byServer) {
+    const label = NATIVE_SERVER_LABELS[serverId] || serverId.charAt(0).toUpperCase() + serverId.slice(1);
+    lines.push(`## ${label}`);
+    lines.push('');
+
+    for (const t of serverTools) {
+      lines.push(`### ${t.safeId}`);
+      if (t.description) {
+        lines.push(t.description);
+      }
+      const schema = t.inputSchema;
+      if (schema && typeof schema === 'object' && schema.properties) {
+        const props = schema.properties as Record<string, Record<string, unknown>>;
+        const required = (schema.required || []) as string[];
+        const paramLines: string[] = [];
+        for (const [key, propSchema] of Object.entries(props)) {
+          const type = propSchema.type || 'unknown';
+          const desc = propSchema.description || '';
+          const req = required.includes(key) ? 'required' : 'optional';
+          paramLines.push(`- ${key} (${type}, ${req})${desc ? ': ' + desc : ''}`);
+        }
+        if (paramLines.length > 0) {
+          lines.push('Parameters:');
+          lines.push(...paramLines);
+        }
+      }
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n');
 }
 
 function buildMcpToolsSection(tools: Array<{ serverId: string; name: string; description: string; inputSchema: Record<string, unknown>; canonicalId: string; safeId: string }>): string {
@@ -283,4 +353,4 @@ function buildMcpToolsSection(tools: Array<{ serverId: string; name: string; des
   }
 
   return lines.join('\n');
-}
+}

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'}`);
   }