indusagi-coding-agent 0.1.21 → 0.1.23

package/docs/web-tools.md

@@ -0,0 +1,304 @@
+# Web Tools
+
+Indusagi Coding Agent includes built-in tools for web operations - web search and web fetch. These tools allow the agent to access real-time information from the internet beyond its knowledge cutoff.
+
+## Web Search Tool
+
+### Overview
+
+The `websearch` tool performs real-time web searches using the Exa AI API, providing up-to-date information for current events and recent data.
+
+### Features
+
+- **Real-time search** - Access information beyond knowledge cutoff
+- **Configurable results** - Control number of results returned (1-10)
+- **Live crawling** - Two modes:
+  - `fallback` (default): Use live crawling as backup if cached content unavailable
+  - `preferred`: Prioritize live crawling for fresh content
+- **Search types** - Three modes:
+  - `auto` (default): Balanced search
+  - `fast`: Quick results
+  - `deep`: Comprehensive search
+- **Context optimization** - Configurable character limits for LLM-friendly output
+
+### Usage
+
+```bash
+# Interactive mode - agent will use websearch automatically
+indusagi "Search for latest TypeScript news 2026"
+
+# Non-interactive mode
+indusagi -p "Search for AI developments in 2026"
+```
+
+### Parameters
+
+| Parameter | Type | Description | Default |
+|-----------|------|-------------|---------|
+| `query` | string | Web search query | - |
+| `numResults` | number | Number of results (1-10) | 8 |
+| `livecrawl` | "fallback" \| "preferred" | Live crawl mode | "fallback" |
+| `type` | "auto" \| "fast" \| "deep" | Search type | "auto" |
+| `contextMaxCharacters` | number | Max context chars for LLM | 10000 |
+
+### Examples
+
+```bash
+# Basic search
+indusagi "Search for Node.js latest release"
+
+# With specific parameters
+indusagi "Search for 'machine learning frameworks' and return 5 results with fast mode"
+
+# Current events
+indusagi "Search for AI news February 2026"
+
+# Deep search for comprehensive results
+indusagi "Do a deep search for Kubernetes security best practices"
+```
+
+### Output
+
+The tool returns search results with:
+- Title and URL of each result
+- Snippet/summary of content
+- Relevance ranking
+- LLM-formatted context for easy processing
+
+---
+
+## Web Fetch Tool
+
+### Overview
+
+The `webfetch` tool fetches content from any URL with automatic format conversion. It can retrieve webpages, documentation, or any web-accessible content.
+
+### Features
+
+- **URL fetching** - Get content from any http/https URL
+- **Format conversion** - Three output formats:
+  - `markdown` (default): HTML → Markdown conversion
+  - `text`: HTML → Plain text extraction
+  - `html`: Raw HTML content
+- **Image support** - Fetch images and return as base64 attachments
+- **Size limits** - 5MB maximum response size
+- **Timeout control** - Configurable timeout up to 120 seconds
+- **Smart headers** - User-Agent and Accept headers for better compatibility
+
+### Usage
+
+```bash
+# Fetch webpage (markdown by default)
+indusagi "Fetch https://github.com/nodejs/node README"
+
+# Fetch as plain text
+indusagi "Get https://example.com content as text"
+
+# Fetch raw HTML
+indusagi "Fetch https://example.com as HTML"
+```
+
+### Parameters
+
+| Parameter | Type | Description | Default |
+|-----------|------|-------------|---------|
+| `url` | string | URL to fetch (http:// or https://) | - |
+| `format` | "markdown" \| "text" \| "html" | Output format | "markdown" |
+| `timeout` | number | Timeout in seconds (max 120) | 30 |
+
+### Examples
+
+```bash
+# Fetch GitHub README
+indusagi "Fetch https://raw.githubusercontent.com/nodejs/node/main/README.md"
+
+# Fetch documentation
+indusagi "Get the React docs at https://react.dev"
+
+# Fetch with custom timeout
+indusagi "Fetch https://slow-website.com with timeout 60 seconds"
+
+# Fetch as text
+indusagi "Fetch https://example.com as plain text"
+```
+
+### Output
+
+- **Text/Markdown**: Returns converted content with formatting preserved
+- **Images**: Returns image data as base64 attachment with metadata
+- **Error handling**: Returns helpful error messages for:
+  - Invalid URLs
+  - Timeout errors
+  - Size limit exceeded
+  - HTTP errors (404, 500, etc.)
+
+---
+
+## Tool Availability
+
+Both web tools are included in the **default tool set** and work automatically without any additional configuration:
+
+```bash
+# Available by default
+indusagi "Search for something online"
+
+# Explicit selection (optional)
+indusagi --tools websearch,webfetch "Fetch https://example.com"
+```
+
+Default tools: `read`, `bash`, `edit`, `write`, `task`, `todoread`, `todowrite`, **`websearch`**, **`webfetch`**
+
+---
+
+## Use Cases
+
+### Research
+
+```bash
+# Search for documentation and fetch specific pages
+indusagi "Find TypeScript 5.7 release notes"
+# Agent may search and then fetch specific documentation links
+```
+
+### Current Events
+
+```bash
+# Get latest news
+indusagi "What are the latest developments in AI for 2026?"
+```
+
+### Code Examples
+
+```bash
+# Search and fetch code examples
+indusagi "Search for 'React useEffect examples' and fetch the best result"
+```
+
+### Documentation
+
+```bash
+# Fetch documentation from URL
+indusagi "Read the documentation at https://developer.mozilla.org/en-US/docs/Web/API"
+```
+
+---
+
+## Best Practices
+
+1. **Be specific with queries** - More specific search terms yield better results
+2. **Use current year** - When searching for recent info, include the year (e.g., "2026")
+3. **Start with search** - Use websearch to find relevant URLs, then use webfetch for specific pages
+4. **Check format** - For code/documentation, markdown format is usually best
+5. **Respect limits** - Large pages may be truncated; use offset/limit for large files via read tool
+
+---
+
+## Configuration
+
+The tools can be configured via the `createAgentSession` API:
+
+```typescript
+import { createAgentSession } from "indusagi-coding-agent";
+
+await createAgentSession({
+  cwd: process.cwd(),
+  tools: {
+    websearch: { baseUrl: "https://custom-endpoint.com" },
+    webfetch: { maxResponseSize: 10 * 1024 * 1024 } // 10MB
+  }
+});
+```
+
+### WebSearchToolOptions
+
+| Option | Type | Description | Default |
+|---------|------|-------------|---------|
+| `baseUrl` | string | Custom API endpoint | "https://mcp.exa.ai" |
+| `apiKey` | string | API key for Exa AI | undefined |
+
+### WebFetchToolOptions
+
+| Option | Type | Description | Default |
+|---------|------|-------------|---------|
+| `maxResponseSize` | number | Max response size in bytes | 5242880 (5MB) |
+| `defaultTimeout` | number | Default timeout in ms | 30000 (30s) |
+
+---
+
+## Permissions
+
+Both tools require permission before execution. The agent will prompt for confirmation when:
+
+- First use of websearch
+- Each webfetch request with a new URL
+
+Permission settings can be configured in global settings:
+- `websearch.always` - List of patterns to auto-allow
+- `webfetch.always` - List of URL patterns to auto-allow
+
+Example in `.indusagi/settings.json`:
+
+```json
+{
+  "websearch": {
+    "always": ["*"]  // Auto-allow all web searches
+  },
+  "webfetch": {
+    "always": ["https://github.com/*", "https://docs.github.com/*"]  // Auto-allow GitHub
+  }
+}
+```
+
+---
+
+## Troubleshooting
+
+### Web Search Issues
+
+**No results found:**
+- Try broader search terms
+- Check spelling of query
+- Use `fast` or `deep` search type
+
+**Timeout errors:**
+- Network connectivity issues
+- API temporarily unavailable
+- Try again later
+
+### Web Fetch Issues
+
+**404 Not Found:**
+- URL is incorrect or page moved
+- Check URL spelling
+
+**Timeout:**
+- Increase timeout: `"Fetch URL with timeout 60"`
+- Check network connection
+
+**Large content truncated:**
+- Content exceeds 5MB limit
+- Consider using `read` tool with offset/limit for large local files
+
+---
+
+## API Details
+
+### Exa AI (Web Search)
+
+- **Endpoint**: `https://mcp.exa.ai/mcp`
+- **Method**: Server-Sent Events (SSE)
+- **Response**: JSON-RPC 2.0 format
+- **Rate limiting**: Default limits apply
+
+### Native Fetch (Web Fetch)
+
+- **Implementation**: Native `fetch()` API
+- **Headers**: Accept, User-Agent, Accept-Language
+- **Redirects**: Automatically followed
+- **SSL**: HTTPS with certificate verification
+
+---
+
+## License
+
+MIT - Same as indusagi-coding-agent

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "indusagi-coding-agent",
-	"version": "0.1.21",
+	"version": "0.1.23",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management. Now with Kimi (Moonshot AI) support and login command!",
 	"type": "module",
 	"indusagiConfig": {
@@ -50,7 +50,7 @@
 		"diff": "^8.0.2",
 		"file-type": "^21.1.1",
 		"glob": "^11.0.3",
-		"indusagi": "0.12.6",
+		"indusagi": "^0.12.8", 
 		"marked": "^15.0.12",
 		"minimatch": "^10.1.1",
 		"proper-lockfile": "^4.1.2",