indusagi-coding-agent 0.1.28 → 0.1.30

package/docs/web-tools.md

@@ -1,304 +0,0 @@
-# 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/docs/windows.md

@@ -1,17 +0,0 @@
-# Windows Setup
-
-Indusagi requires a bash shell on Windows. Checked locations (in order):
-
-1. Custom path from `~/.indusagi/agent/settings.json`
-2. Git Bash (`C:\Program Files\Git\bin\bash.exe`)
-3. `bash.exe` on PATH (Cygwin, MSYS2, WSL)
-
-For most users, [Git for Windows](https://git-scm.com/download/win) is sufficient.
-
-## Custom Shell Path
-
-```json
-{
-  "shellPath": "C:\\cygwin64\\bin\\bash.exe"
-}
-```

package/examples/README.md

@@ -1,25 +0,0 @@
-# Examples
-
-Example code for indusagi-coding-agent SDK and extensions.
-
-## Directories
-
-### [sdk/](sdk/)
-Programmatic usage via `createAgentSession()`. Shows how to customize models, prompts, tools, extensions, and session management.
-
-### [extensions/](extensions/)
-Example extensions demonstrating:
-- Lifecycle event handlers (tool interception, safety gates, context modifications)
-- Custom tools (todo lists, questions, subagents, output truncation)
-- Commands and keyboard shortcuts
-- Custom UI (footers, headers, editors, overlays)
-- Git integration (checkpoints, auto-commit)
-- System prompt modifications and custom compaction
-- External integrations (SSH, file watchers, system theme sync)
-- Custom providers (Anthropic with custom streaming, GitLab Duo)
-
-## Documentation
-
-- [SDK Reference](sdk/README.md)
-- [Extensions Documentation](../docs/extensions.md)
-- [Skills Documentation](../docs/skills.md)

package/examples/extensions/README.md

@@ -1,192 +0,0 @@
-# Extension Examples
-
-Example extensions for indusagi-coding-agent.
-
-## Usage
-
-```bash
-# Load an extension with --extension flag
-indusagi --extension examples/extensions/permission-gate.ts
-
-# Or copy to extensions directory for auto-discovery
-cp permission-gate.ts ~/.indusagi/agent/extensions/
-```
-
-## Examples
-
-### Lifecycle & Safety
-
-| Extension | Description |
-|-----------|-------------|
-| `permission-gate.ts` | Prompts for confirmation before dangerous bash commands (rm -rf, sudo, etc.) |
-| `protected-paths.ts` | Blocks writes to protected paths (.env, .git/, node_modules/) |
-| `confirm-destructive.ts` | Confirms before destructive session actions (clear, switch, fork) |
-| `dirty-repo-guard.ts` | Prevents session changes with uncommitted git changes |
-| `sandbox/` | OS-level sandboxing using `@anthropic-ai/sandbox-runtime` with per-project config |
-
-### Custom Tools
-
-| Extension | Description |
-|-----------|-------------|
-| `todo.ts` | Todo list tool + `/todos` command with custom rendering and state persistence |
-| `hello.ts` | Minimal custom tool example |
-| `question.ts` | Demonstrates `ctx.ui.select()` for asking the user questions with custom UI |
-| `questionnaire.ts` | Multi-question input with tab bar navigation between questions |
-| `tool-override.ts` | Override built-in tools (e.g., add logging/access control to `read`) |
-| `truncated-tool.ts` | Wraps ripgrep with proper output truncation (50KB/2000 lines) |
-| `antigravity-image-gen.ts` | Generate images via Google Antigravity with optional save-to-disk modes |
-| `ssh.ts` | Delegate all tools to a remote machine via SSH using pluggable operations |
-| `subagent/` | Delegate tasks to specialized subagents with isolated context windows |
-
-### Commands & UI
-
-| Extension | Description |
-|-----------|-------------|
-| `preset.ts` | Named presets for model, thinking level, tools, and instructions via `--preset` flag and `/preset` command |
-| `plan-mode/` | Claude Code-style plan mode for read-only exploration with `/plan` command and step tracking |
-| `tools.ts` | Interactive `/tools` command to enable/disable tools with session persistence |
-| `handoff.ts` | Transfer context to a new focused session via `/handoff <goal>` |
-| `qna.ts` | Extracts questions from last response into editor via `ctx.ui.setEditorText()` |
-| `status-line.ts` | Shows turn progress in footer via `ctx.ui.setStatus()` with themed colors |
-| `widget-placement.ts` | Shows widgets above and below the editor via `ctx.ui.setWidget()` placement |
-| `model-status.ts` | Shows model changes in status bar via `model_select` hook |
-| `snake.ts` | Snake game with custom UI, keyboard handling, and session persistence |
-| `send-user-message.ts` | Demonstrates `indusagi.sendUserMessage()` for sending user messages from extensions |
-| `timed-confirm.ts` | Demonstrates AbortSignal for auto-dismissing `ctx.ui.confirm()` and `ctx.ui.select()` dialogs |
-| `modal-editor.ts` | Custom vim-like modal editor via `ctx.ui.setEditorComponent()` |
-| `rainbow-editor.ts` | Animated rainbow text effect via custom editor |
-| `notify.ts` | Desktop notifications via OSC 777 when agent finishes (Ghostty, iTerm2, WezTerm) |
-| `summarize.ts` | Summarize conversation with GPT-5.2 and show in transient UI |
-| `custom-footer.ts` | Custom footer with git branch and token stats via `ctx.ui.setFooter()` |
-| `custom-header.ts` | Custom header via `ctx.ui.setHeader()` |
-| `overlay-test.ts` | Test overlay compositing with inline text inputs and edge cases |
-| `overlay-qa-tests.ts` | Comprehensive overlay QA tests: anchors, margins, stacking, overflow, animation |
-| `doom-overlay/` | DOOM game running as an overlay at 35 FPS (demonstrates real-time game rendering) |
-| `shutdown-command.ts` | Adds `/quit` command demonstrating `ctx.shutdown()` |
-| `interactive-shell.ts` | Run interactive commands (vim, htop) with full terminal via `user_bash` hook |
-| `inline-bash.ts` | Expands `!{command}` patterns in prompts via `input` event transformation |
-
-### Git Integration
-
-| Extension | Description |
-|-----------|-------------|
-| `git-checkpoint.ts` | Creates git stash checkpoints at each turn for code restoration on fork |
-| `auto-commit-on-exit.ts` | Auto-commits on exit using last assistant message for commit message |
-
-### System Prompt & Compaction
-
-| Extension | Description |
-|-----------|-------------|
-| `pirate.ts` | Demonstrates `systemPromptAppend` to dynamically modify system prompt |
-| `claude-rules.ts` | Scans `.claude/rules/` folder and lists rules in system prompt |
-| `custom-compaction.ts` | Custom compaction that summarizes entire conversation |
-| `trigger-compact.ts` | Triggers compaction when context usage exceeds 100k tokens and adds `/trigger-compact` command |
-
-### System Integration
-
-| Extension | Description |
-|-----------|-------------|
-| `mac-system-theme.ts` | Syncs indusagi theme with macOS dark/light mode |
-
-### Messages & Communication
-
-| Extension | Description |
-|-----------|-------------|
-| `message-renderer.ts` | Custom message rendering with colors and expandable details via `registerMessageRenderer` |
-| `event-bus.ts` | Inter-extension communication via `indusagi.events` |
-
-### Session Metadata
-
-| Extension | Description |
-|-----------|-------------|
-| `session-name.ts` | Name sessions for the session selector via `setSessionName` |
-| `bookmark.ts` | Bookmark entries with labels for `/tree` navigation via `setLabel` |
-
-### Custom Providers
-
-| Extension | Description |
-|-----------|-------------|
-| `custom-provider-anthropic/` | Custom Anthropic provider with OAuth support and custom streaming implementation |
-| `custom-provider-gitlab-duo/` | GitLab Duo provider using indusagi-ai's built-in Anthropic/OpenAI streaming via proxy |
-
-### External Dependencies
-
-| Extension | Description |
-|-----------|-------------|
-| `with-deps/` | Extension with its own package.json and dependencies (demonstrates jiti module resolution) |
-| `file-trigger.ts` | Watches a trigger file and injects contents into conversation |
-
-## Writing Extensions
-
-See [docs/extensions.md](../../docs/extensions.md) for full documentation.
-
-```typescript
-import type { ExtensionAPI } from "indusagi-coding-agent";
-import { Type } from "@sinclair/typebox";
-
-export default function (indusagi: ExtensionAPI) {
-  // Subscribe to lifecycle events
-  indusagi.on("tool_call", async (event, ctx) => {
-    if (event.toolName === "bash" && event.input.command?.includes("rm -rf")) {
-      const ok = await ctx.ui.confirm("Dangerous!", "Allow rm -rf?");
-      if (!ok) return { block: true, reason: "Blocked by user" };
-    }
-  });
-
-  // Register custom tools
-  indusagi.registerTool({
-    name: "greet",
-    label: "Greeting",
-    description: "Generate a greeting",
-    parameters: Type.Object({
-      name: Type.String({ description: "Name to greet" }),
-    }),
-    async execute(toolCallId, params, onUpdate, ctx, signal) {
-      return {
-        content: [{ type: "text", text: `Hello, ${params.name}!` }],
-        details: {},
-      };
-    },
-  });
-
-  // Register commands
-  indusagi.registerCommand("hello", {
-    description: "Say hello",
-    handler: async (args, ctx) => {
-      ctx.ui.notify("Hello!", "info");
-    },
-  });
-}
-```
-
-## Key Patterns
-
-**Use StringEnum for string parameters** (required for Google API compatibility):
-```typescript
-import { StringEnum } from "indusagi-ai";
-
-// Good
-action: StringEnum(["list", "add"] as const)
-
-// Bad - doesn't work with Google
-action: Type.Union([Type.Literal("list"), Type.Literal("add")])
-```
-
-**State persistence via details:**
-```typescript
-// Store state in tool result details for proper forking support
-return {
-  content: [{ type: "text", text: "Done" }],
-  details: { todos: [...todos], nextId },  // Persisted in session
-};
-
-// Reconstruct on session events
-indusagi.on("session_start", async (_event, ctx) => {
-  for (const entry of ctx.sessionManager.getBranch()) {
-    if (entry.type === "message" && entry.message.toolName === "my_tool") {
-      const details = entry.message.details;
-      // Reconstruct state from details
-    }
-  }
-});
-```