+
+
+
+ LLM-powered autonomous agent for the NEAR AI marketplace +
+ ++ Features • + Installation • + Configuration • + Architecture • + Security +
+ +--- + +## Features + +- **Multi-channel input** - CLI, HTTP webhooks, Slack, Telegram +- **Parallel job execution** - Concurrent task processing with isolated contexts +- **Extensible tools** - Built-in tools + MCP protocol + WASM sandbox +- **Persistent memory** - Hybrid search (FTS + vector) with chunked documents +- **Prompt injection defense** - Pattern detection, content sanitization, policy enforcement +- **Self-repair** - Automatic detection and recovery of stuck jobs +- **Heartbeat system** - Proactive periodic execution for background tasks + +## Installation + +### Prerequisites + +- Rust 1.85+ +- PostgreSQL 15+ with pgvector extension +- NEAR AI session token + +### Build + +```bash +# Clone the repository +git clone https://github.com/nearai/near-agent.git +cd near-agent + +# Build +cargo build --release + +# Run tests +cargo test +``` + +### Database Setup + +```bash +# Create database +createdb near_agent + +# Enable pgvector +psql near_agent -c "CREATE EXTENSION IF NOT EXISTS vector;" + +# Run migrations +refinery migrate -c refinery.toml +``` + +## Configuration + +Copy `.env.example` to `.env` and configure: + +```bash +# Required +DATABASE_URL=postgres://user:pass@localhost/near_agent +NEARAI_SESSION_TOKEN=sess_... + +# Optional: Enable channels +SLACK_BOT_TOKEN=xoxb-... +TELEGRAM_BOT_TOKEN=... +HTTP_PORT=8080 +``` + +### Environment Variables + +| Variable | Description | Required | +|----------|-------------|----------| +| `DATABASE_URL` | PostgreSQL connection string | Yes | +| `NEARAI_SESSION_TOKEN` | NEAR AI authentication token | Yes | +| `NEARAI_MODEL` | Model to use (default: claude-3-5-sonnet) | No | +| `AGENT_MAX_PARALLEL_JOBS` | Max concurrent jobs (default: 5) | No | +| `SECRETS_MASTER_KEY` | 32+ byte key for secret encryption | For secrets | + +## Architecture + +``` +┌─────────────────────────────────────────────────────────────────┐ +│ Channels │ +│ ┌─────┐ ┌──────┐ ┌───────┐ ┌──────────┐ │ +│ │ CLI │ │ HTTP │ │ Slack │ │ Telegram │ │ +│ └──┬──┘ └──┬───┘ └───┬───┘ └────┬─────┘ │ +│ └────────┴──────────┴───────────┘ │ +│ │ │ +│ ┌────▼────┐ │ +│ │ Router │ Intent classification │ +│ └────┬────┘ │ +│ │ │ +│ ┌──────────▼──────────┐ │ +│ │ Scheduler │ Parallel job management │ +│ └──────────┬──────────┘ │ +│ │ │ +│ ┌───────────────┼───────────────┐ │ +│ ▼ ▼ ▼ │ +│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ +│ │ Worker │ │ Worker │ │ Worker │ LLM reasoning │ +│ └────┬────┘ └────┬────┘ └────┬────┘ │ +│ └───────────────┼───────────────┘ │ +│ │ │ +│ ┌──────────▼──────────┐ │ +│ │ Tool Registry │ │ +│ │ ┌───────────────┐ │ │ +│ │ │ Built-in │ │ │ +│ │ │ MCP │ │ │ +│ │ │ WASM Sandbox │ │ │ +│ │ └───────────────┘ │ │ +│ └─────────────────────┘ │ +└─────────────────────────────────────────────────────────────────┘ +``` + +### Core Components + +| Component | Purpose | +|-----------|---------| +| **Agent Loop** | Main message handling and job coordination | +| **Router** | Classifies user intent (command, query, task) | +| **Scheduler** | Manages parallel job execution with priorities | +| **Worker** | Executes jobs with LLM reasoning and tool calls | +| **Workspace** | Persistent memory with hybrid search | +| **Safety Layer** | Prompt injection defense and content sanitization | + +## Security + +### WASM Sandbox + +Untrusted tools run in a sandboxed WASM environment with: + +- **Capability-based permissions** - Explicit opt-in for HTTP, secrets, tool invocation +- **Endpoint allowlisting** - HTTP requests only to approved hosts/paths +- **Credential injection** - Secrets injected at host boundary, never exposed to WASM +- **Leak detection** - Scans requests and responses for secret exfiltration +- **Rate limiting** - Per-tool request limits (per-minute and per-hour) +- **Resource limits** - Memory, CPU, and execution time constraints + +``` +WASM ──► Allowlist ──► Leak Scan ──► Credential ──► Execute ──► Leak Scan ──► WASM + Validator (request) Injector Request (response) +``` + +### Prompt Injection Defense + +- Pattern-based detection of injection attempts +- Content sanitization and escaping +- Policy rules with severity levels (Block/Warn/Review/Sanitize) +- Tool output wrapping for LLM context + +## Usage + +### CLI Mode + +```bash +# Start interactive CLI +cargo run + +# With debug logging +RUST_LOG=near_agent=debug cargo run +``` + +### HTTP Server + +```bash +# Start with HTTP webhook server +HTTP_PORT=8080 cargo run + +# Send a request +curl -X POST http://localhost:8080/webhook \ + -H "Content-Type: application/json" \ + -d '{"message": "Hello, agent!"}' +``` + +## Development + +```bash +# Format code +cargo fmt + +# Lint +cargo clippy --all --benches --tests --examples --all-features + +# Run tests +cargo test + +# Run specific test +cargo test test_name +``` + +## License + +Licensed under either of: + +- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE)) +- MIT License ([LICENSE-MIT](LICENSE-MIT)) + +at your option. diff --git a/ironclaw.png b/ironclaw.png new file mode 100644 index 00000000..8a919549 Binary files /dev/null and b/ironclaw.png differ