open-agents-ai 0.1.0

package/README.md

@@ -0,0 +1,307 @@
+# Open Agents
+
+**AI coding agent framework powered by open-weight models via Ollama.**
+
+A multi-turn agentic tool-calling loop that iteratively reads code, makes changes, runs tests, and fixes failures until the task is complete — modeled after how Claude Code operates, but running entirely on local open-weight models.
+
+## How It Works
+
+```
+You: oa "fix the null check in auth.ts"
+
+Agent: [Turn 1] file_read(src/auth.ts)
+       [Turn 2] grep_search(pattern="null", path="src/auth.ts")
+       [Turn 3] file_edit(old_string="if (user)", new_string="if (user != null)")
+       [Turn 4] shell(command="npm test")
+       [Turn 5] task_complete(summary="Fixed null check — all tests pass")
+```
+
+The agent has **11 tools** and uses them autonomously in a loop, reading errors, fixing code, and re-running validation until the task succeeds or the turn limit is reached.
+
+## Quick Start
+
+```bash
+# 1. Install Ollama (https://ollama.com)
+curl -fsSL https://ollama.com/install.sh | sh
+
+# 2. Pull the model
+ollama pull qwen3.5:122b
+
+# 3. Clone and install
+git clone https://github.com/robit-man/open-agents.git && cd open-agents
+./scripts/install.sh
+
+# 4. Use it
+oa "add pagination to the users endpoint"
+open-agents "refactor the auth module into separate files"
+```
+
+## Installation
+
+### Prerequisites
+
+- **Node.js** >= 20
+- **pnpm** (`npm install -g pnpm`)
+- **Ollama** ([ollama.com](https://ollama.com)) with a model that supports tool calling
+
+### Install System-Wide
+
+```bash
+# Install to ~/.local/bin (no sudo needed)
+./scripts/install.sh
+
+# Install to /usr/local/bin
+sudo ./scripts/install.sh --global
+
+# Custom prefix
+./scripts/install.sh --prefix ~/bin
+
+# Uninstall
+./scripts/install.sh --uninstall
+```
+
+The installer will:
+1. Check Node.js and pnpm versions
+2. Install workspace dependencies
+3. Build all packages
+4. Create `open-agents` and `oa` symlinks
+5. Configure an optimized Ollama model (auto-detects RAM for context window sizing)
+
+### Manual Build
+
+```bash
+pnpm install
+pnpm -r build
+pnpm -r test   # 911 tests across 77 files
+```
+
+## Tools
+
+The agent has access to 11 tools that it calls autonomously:
+
+| Tool | Description |
+|------|-------------|
+| `file_read` | Read file contents with line numbers (supports offset/limit) |
+| `file_write` | Create or overwrite files |
+| `file_edit` | Precise string replacement in files (preferred over full rewrites) |
+| `shell` | Execute any shell command (tests, builds, git, etc.) |
+| `grep_search` | Search file contents with regex (uses ripgrep when available) |
+| `find_files` | Find files by glob pattern |
+| `list_directory` | List directory contents with types and sizes |
+| `web_search` | Search the web via DuckDuckGo |
+| `web_fetch` | Fetch and extract text from web pages (docs, MDN, w3schools) |
+| `memory_read` | Read from persistent memory store |
+| `memory_write` | Store patterns and solutions for future tasks |
+
+### Self-Learning
+
+When the agent encounters an unfamiliar API or language feature, it automatically:
+1. Searches the web for documentation
+2. Fetches the relevant page (w3schools.com, MDN, official docs)
+3. Stores the learned pattern in persistent memory
+4. Applies the knowledge to the current task
+
+### Error Recovery
+
+The agent follows an iterative fix loop:
+1. Run validation (tests/build/lint)
+2. Read the full error output
+3. Identify the exact file, line, and failure
+4. Fix with `file_edit`
+5. Re-run validation
+6. Repeat until passing
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `oa "task"` | Run a coding task (short alias) |
+| `open-agents "task"` | Run a coding task |
+| `open-agents run "task" --repo /path` | Run against a specific repo |
+| `open-agents index /path` | Index a repository |
+| `open-agents status` | Show system status |
+| `open-agents config` | Show/set configuration |
+| `open-agents serve` | Start/verify backend server |
+| `open-agents eval` | Run evaluation suite |
+
+### Flags
+
+```
+-m, --model <name>         Model name (default: qwen3.5:122b)
+-b, --backend-url <url>    Backend URL (default: http://localhost:11434)
+    --backend <type>       Backend type: ollama (default), vllm, fake
+-r, --repo <path>          Repository root (default: cwd)
+    --dry-run              Show what would happen without writing files
+    --offline              Skip backend health check
+-v, --verbose              Show model responses and debug info
+    --timeout-ms <ms>      Per-request timeout (default: 300000)
+-h, --help                 Show help
+-V, --version              Show version
+```
+
+### Configuration
+
+Config priority: CLI flags > environment variables > `~/.open-agents/config.json` > defaults.
+
+```bash
+# Set defaults
+open-agents config set model qwen3.5:122b
+open-agents config set backendUrl http://localhost:11434
+open-agents config set backendType ollama
+
+# Environment variables
+export OPEN_AGENTS_MODEL=qwen3.5:122b
+export OPEN_AGENTS_BACKEND_URL=http://localhost:11434
+export OPEN_AGENTS_BACKEND_TYPE=ollama
+```
+
+## Model Support
+
+**Primary target**: Qwen3.5-122B-A10B via Ollama (MoE, runs on 48GB+ VRAM)
+
+The `setup-model.sh` script auto-configures the context window based on available RAM:
+
+| RAM | Context Window |
+|-----|---------------|
+| 300GB+ | 128K tokens |
+| 128GB+ | 64K tokens |
+| 64GB+ | 32K tokens |
+| < 64GB | 16K tokens |
+
+### Other Models
+
+Any model that supports tool calling via Ollama or an OpenAI-compatible API works:
+
+```bash
+# Use a different Ollama model
+oa --model qwen2.5-coder:32b "fix the bug"
+
+# Use vLLM backend
+oa --backend vllm --backend-url http://localhost:8000/v1 "add tests"
+
+# Use any OpenAI-compatible API
+oa --backend-url http://10.0.0.5:11434 "refactor auth"
+```
+
+## Architecture
+
+### Agentic Loop
+
+The core is `AgenticRunner` — a multi-turn tool-calling loop:
+
+```
+User task
+    ↓
+System prompt + tools → LLM
+    ↓
+LLM returns tool_calls → Execute tools → Feed results back → LLM
+    ↓  (repeat until task_complete or max turns)
+Result: completed/incomplete, turns, tool calls, duration
+```
+
+Key design decisions:
+- **Tool-first**: The model explores via tools rather than pre-stuffed context
+- **Iterative**: Tests, sees failures, fixes them — no need for perfect one-shot output
+- **Context compaction**: Long conversations are compressed, preserving only recent context
+- **Bounded**: Maximum turns, timeout, and output limits prevent runaway loops
+- **Observable**: Every tool call and result is emitted as a real-time event
+
+### Package Structure
+
+```
+packages/
+  orchestrator/   - AgenticRunner, OllamaAgenticBackend, RALPH loop
+  execution/      - 11 tools (file, shell, grep, web, memory), validation pipeline
+  schemas/        - Zod schemas and TypeScript types
+  backend-vllm/   - Ollama + vLLM backend clients (OpenAI-compatible)
+  memory/         - SQLite-backed persistent memory stores
+  indexer/        - Codebase scanning and symbol extraction
+  retrieval/      - Multi-stage retrieval (lexical + semantic + graph)
+  prompts/        - Prompt contracts for each agent role
+  cli/            - CLI entry point, commands, config, UI
+
+apps/
+  api/            - Express API server
+  worker/         - Background task processor
+
+eval/             - 8 evaluation tasks with agentic runner
+scripts/          - install.sh, setup-model.sh, bootstrap.sh
+```
+
+## Evaluation
+
+The framework includes 8 evaluation tasks that test the agent's ability to autonomously resolve coding problems:
+
+```bash
+# Run all 8 tasks with agentic tool-calling loop
+node eval/run-agentic.mjs
+
+# Single task
+node eval/run-agentic.mjs 04-add-test
+
+# Different model
+node eval/run-agentic.mjs --model qwen2.5-coder:32b
+```
+
+### Results (Qwen3.5-122B)
+
+```
+TASK                 RESULT   TIME       TURNS    TOOLS
+01-fix-typo          PASS     39.1s      4        7
+02-add-function      PASS     24.5s      4        5
+03-fix-bug           PASS     26.9s      4        5
+04-add-test          PASS     198.1s     6        8
+05-refactor          PASS     73.1s      4        5
+06-type-error        PASS     143.2s     5        7
+07-add-endpoint      PASS     40.0s      4        5
+08-multi-file        PASS     75.5s      8        13
+
+Pass rate: 100% (8/8)
+Total: 39 turns, 55 tool calls, ~10 minutes
+```
+
+### Task Descriptions
+
+| ID | Task | Difficulty |
+|----|------|-----------|
+| 01 | Fix typo in function name | Easy |
+| 02 | Add isPrime function | Easy |
+| 03 | Fix off-by-one bug | Easy |
+| 04 | Write comprehensive tests for untested functions | Medium |
+| 05 | Extract functions from long method (refactor) | Medium |
+| 06 | Fix TypeScript type errors | Medium |
+| 07 | Add REST API endpoint | Medium |
+| 08 | Add pagination across multiple files | Hard |
+
+## Test Suite
+
+```
+Package          Tests
+─────────────────────────
+schemas          216
+backend-vllm     162
+execution        136
+indexer            94
+cli                72
+orchestrator       70
+retrieval          66
+memory             58
+prompts            34
+apps/api            1
+apps/worker         2
+─────────────────────────
+Total             911 passing
+```
+
+## Development
+
+```bash
+pnpm install          # Install dependencies
+pnpm -r build         # Build all packages
+pnpm -r test          # Run all 911 tests
+pnpm -r dev           # Watch mode
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { parseCliArgs, routeCommand } from "./types.js";
+export type { ParsedCliArgs, CommandName } from "./types.js";
+export { loadConfig, mergeConfig, setConfigValue, DEFAULT_CONFIG } from "./types.js";
+export type { AgentConfig, BackendType } from "./types.js";
+export { Spinner } from "./types.js";
+export { printHeader, printSuccess, printError, printWarning, printInfo, printSection, printKeyValue, printBlank, printReport, formatDuration } from "./types.js";