agi-farm 1.0.0 → 1.0.2

package/README.md

@@ -6,10 +6,10 @@
 
 **Build production-ready AI teams with a single command**
 
+[![npm version](https://img.shields.io/npm/v/agi-farm.svg)](https://www.npmjs.com/package/agi-farm)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![OpenClaw](https://img.shields.io/badge/OpenClaw-Plugin-blue.svg)](https://docs.openclaw.ai)
 [![Node.js](https://img.shields.io/badge/Node.js-20%2B-green.svg)](https://nodejs.org/)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
 
 [Quick Start](#-quick-start) • [Features](#-what-it-does) • [Documentation](#-commands) • [Architecture](#-architecture)
 
@@ -29,8 +29,21 @@
 | 🔄 **Auto-Dispatcher** | Smart task delegation with HITL, backoff & dependencies |
 | 📦 **Portable Bundle** | Export your entire team to GitHub with one command |
 | 🏗️ **ESM Native** | Built for Node 20+ with full ES Module support |
-| 🛡️ **Production Hardened** | Audited for security, memory leaks, and CLI timeouts |
-| 🧪 **Unit Tested** | Core parsing and logic verified with a Jest/ESM test suite |
+| 🛡️ **Production Hardened** | Security-audited with CSRF, Origin validation, and timing-safe auth |
+| 🧪 **28 Unit Tests** | Extension lifecycle, security, parsing, and CLI utilities verified with Jest/ESM |
+
+---
+
+## 🆕 Recent Updates
+
+- 🔐 **Origin validation**: mutation endpoints now validate `Origin` header — only localhost origins accepted.
+- 🔒 **Timing-safe auth hardened**: CSRF token comparison no longer leaks token length via timing.
+- 🧪 **28 unit tests**: added extension lifecycle, security, and shared utility test suites (was 6).
+- 📦 **Removed unused `sse.js`**: dependency cleaned from `package.json`.
+- 🔄 **Dynamic versioning**: extension reads version from `package.json` instead of hardcoding.
+- 🛠️ **ESM `__dirname` fix**: `src/index.ts` now uses `import.meta.dirname` with proper fallback.
+- 🧰 **Shared utilities**: extracted `runCommand` to `scripts/lib/run-command.js` — eliminates duplication.
+- ✅ **Env var consistency**: `export.js` and `status.js` now respect `AGI_FARM_WORKSPACE` like all other scripts.
 
 ---
 
@@ -88,37 +101,35 @@
 ### Install
 
 ```bash
-# Install from npm (when published)
-openclaw plugins install agi-farm
+# Install officially from npm
+npm install -g agi-farm
 
-# Or install from GitHub
-openclaw plugins install https://github.com/oabdelmaksoud/AGI-FARM-PLUGIN.git
+# Or via OpenClaw plugin manager
+openclaw plugins install agi-farm
 ```
 
 ### Run Setup Wizard
 
 ```bash
 # Start the interactive wizard
-/agi-farm setup
+agi-farm setup
 ```
 
-Answer 6 questions and your team will be live in ~2 minutes:
+Answer the setup prompts and your team will be live in ~2 minutes:
 
 ```
 🧙 AGI Farm Setup Wizard
 
 ? Team name (e.g., "CooperCorp"): MyTeam
+? Orchestrator name: Cooper
 ? Team size: 11 agents (Full Stack)
-? Domain: Software Development
-? Primary framework: langgraph
-? GitHub repo: myteam/ai-agents
+? Domain: general
+? Collaboration frameworks: langgraph
 ? Confirm setup? Yes
 
 ✅ Creating 11 agents...
 ✅ Setting up workspace...
-✅ Registering cron jobs...
-✅ Creating GitHub bundle...
-✅ Launching dashboard...
+✅ Initializing AGI Farm registries...
 
 🎉 Your AI team is ready!
 ```
@@ -129,13 +140,13 @@ Answer 6 questions and your team will be live in ~2 minutes:
 
 | Command | Description | Example |
 |---------|-------------|---------|
-| 🎯 `/agi-farm setup` | Full wizard — agents, workspace, crons | Sets up complete team |
-| 🗑️ `/agi-farm teardown` | Full uninstall — removes agents & workspace | Reverts system to clean state |
-| 📊 `/agi-farm status` | Team health: agents, tasks, cron status | Shows real-time metrics |
-| 🔧 `/agi-farm rebuild` | Regenerate workspace from bundle | After git pull |
-| 📤 `/agi-farm export` | Push bundle to GitHub | Creates new release |
-| 🖥️ `/agi-farm dashboard` | Launch live ops room (SSE, :8080) | Opens in browser |
-| ⚡ `/agi-farm dispatch` | Run auto-dispatcher manually | Test task routing |
+| 🎯 `agi-farm setup` | Full wizard — agents, workspace, crons | Sets up complete team |
+| 🗑️ `agi-farm teardown` | Full uninstall — removes agents, bundle, and AGI Farm-owned registries (`TASKS.json`, `AGENT_STATUS.json`) | Reverts system to clean state |
+| 📊 `agi-farm status` | Team health: agents, tasks, cron status | Shows real-time metrics |
+| 🔧 `agi-farm rebuild` | Regenerate workspace from bundle | After git pull |
+| 📤 `agi-farm export` | Push bundle to GitHub | Creates new release |
+| 🖥️ `agi-farm dashboard` | Launch live ops room (SSE, :8080) | Opens in browser |
+| ⚡ `agi-farm dispatch` | Run auto-dispatcher manually | Test task routing |
 
 ---
 
@@ -144,11 +155,11 @@ Answer 6 questions and your team will be live in ~2 minutes:
 ### Plugin Structure
 
 ```
-.openclaw/extensions/agi-farm/
+.openclaw/extensions/agi-farm/ (or global node_modules/agi-farm/)
 ├── 📦 package.json              Plugin manifest (ESM)
 ├── ⚙️ openclaw.plugin.json     Config schema & commands
-├── 📂 src/
-│   └── 💻 index.ts             Main plugin entry (TypeScript)
+├── 📂 dist/                    Compiled TypeScript (backend)
+├── 📂 dashboard-dist/          Built React frontend (production)
 ├── 🌐 server/
 │   ├── 🖥️ dashboard.js         SSE server (Node.js)
 │   └── 🛠️ utils.js             Core parsing & logic (Unit Tested)
@@ -159,9 +170,11 @@ Answer 6 questions and your team will be live in ~2 minutes:
 │   ├── 🔧 rebuild.js           Rebuilder
 │   ├── 📤 export.js            GitHub exporter
 │   ├── 🖥️ dashboard.js         Dashboard launcher
-│   └── ⚡ dispatch.js          Auto-dispatcher
+│   ├── ⚡ dispatch.js          Auto-dispatcher
+│   └── 📂 lib/
+│       └── 🛠️ run-command.js   Shared CLI utility
 ├── 📋 templates/               Agent & workspace templates
-├── ⚛️ dashboard-react/         Vite + React 18 frontend
+├── ⚛️ dashboard-react/         Vite + React 18 source (Dev)
 └── 📚 skills/
     └── 📖 SKILL.md             Embedded documentation
 ```
@@ -284,16 +297,16 @@ Complete team for complex systems - **RECOMMENDED**
 
 Choose the right model for each role to optimize cost and quality:
 
-| Role | Model Tier | Why | Cost/Quality |
+| Role | Recommended Model | Why | Cost/Quality |
 |------|-----------|-----|--------------|
-| 🦅 Orchestrator | **High** (`sonnet`, `opus`) | Delegation judgment, broad reasoning | 💰💰💰 / ⭐⭐⭐ |
-| 🔮 Architect | **High** | Deep analysis, design decisions | 💰💰💰 / ⭐⭐⭐ |
-| ⚒️ Engineer | **Mid** (`glm-5`, `sonnet`) | Fast code gen, cost-efficiency | 💰💰 / ⭐⭐ |
-| 🐛 Debugger | **High** (`opus`) | Root-cause analysis, precision | 💰💰💰 / ⭐⭐⭐ |
-| 🔭 Analyst | **Mid-High** (`gemini-2.0-pro-exp`) | Long-context research | 💰💰 / ⭐⭐⭐ |
-| 🛡️ QA | **Fast** (`glm-4.7-flash`) | High-volume pattern checks | 💰 / ⭐⭐ |
-| ⚓ Content | **Multimodal** (`gemini-2.0-pro-exp`) | Vision + rich generation | 💰💰 / ⭐⭐⭐ |
-| 🧪 R&D | **High** | Creative + structured experiments | 💰💰💰 / ⭐⭐⭐ |
+| 🦅 Orchestrator | `anthropic/claude-3-5-sonnet` | High-level planning & delegation | 💰💰💰 / ⭐⭐⭐ |
+| 🔮 Architect | `anthropic/claude-3-opus` | Deep reasoning & system design | 💰💰💰 / ⭐⭐⭐ |
+| ⚒️ Engineer | `google/gemini-1.5-pro` | Reliable code gen & large context | 💰💰 / ⭐⭐ |
+| 🐛 Debugger | `anthropic/claude-3-5-sonnet` | Precision logic & error analysis | 💰💰 / ⭐⭐⭐ |
+| 🔭 Analyst | `google/gemini-2.0-flash` | Ultra-fast data synthesis | 💰 / ⭐⭐ |
+| 🛡️ QA | `anthropic/claude-3-haiku` | Rapid pattern validation | 💰 / ⭐ |
+| ⚓ Content | `google/gemini-1.5-pro` | Rich multimodal generation | 💰💰 / ⭐⭐⭐ |
+| 🧪 R&D | `deepseek/deepseek-reasoner` | Structured creative experimentation | 💰 / ⭐⭐⭐ |
 
 ---
 
@@ -408,7 +421,7 @@ The auto-dispatcher intelligently routes tasks to agents:
 
 ```bash
 # Manual dry-run
-/agi-farm dispatch
+agi-farm dispatch
 
 # Check logs
 tail -f ~/.openclaw/workspace/logs/auto-dispatch.log
@@ -426,8 +439,8 @@ cd AGI-FARM-PLUGIN
 # Install dependencies
 npm install
 
-# Build TypeScript
-npm run build
+# Build backend and dashboard
+npm run build:all
 
 # Link to OpenClaw extensions
 ln -s $(pwd) ~/.openclaw/extensions/agi-farm
@@ -438,7 +451,10 @@ ln -s $(pwd) ~/.openclaw/extensions/agi-farm
 ## 💻 Development
 
 ```bash
-# Build TypeScript
+# Build everything (TS + Dashboard)
+npm run build:all
+
+# Build backend only
 npm run build
 
 # Watch mode for development
@@ -463,14 +479,13 @@ npm run start-dashboard
 
 | Symptom | Fix | Command |
 |---------|-----|---------|
-| ❌ Plugin fails to load | Install dependencies | `npm install` |
-| 📊 Dashboard shows stale data | Restart dashboard | `/agi-farm dashboard` |
-| 🤖 Agent stuck >30 min | Check broadcast | `cat comms/broadcast.md` |
-| ⚠️ `openclaw` not found | Add to PATH | `export PATH=$PATH:/path/to/openclaw` |
-| 🔐 `gh repo create` fails | Login to GitHub | `gh auth login` |
-| ⏰ Cron shows 0 crons | Check duplicates | `openclaw cron list` |
-| 📄 TASKS.json parse error | Validate JSON | `python3 -m json.tool TASKS.json` |
-| 🐌 Rate-limit too aggressive | Adjust backoff | Edit dispatch script |
+| ❌ Plugin fails to load | Check global install | `npm list -g agi-farm` |
+| 📊 Dashboard shows stale data | Sync with workspace | `agi-farm status` |
+| 🤖 Agent stuck >30 min | Verify heartbeats | `cat ~/.openclaw/workspace/HEARTBEAT.md` |
+| ⚠️ `openclaw` not found | Add to PATH | `export PATH=$PATH:$(npm bin -g)` |
+| 🔐 Access Denied | Check npm login | `npm whoami` |
+| ⏰ Cron registration error | Clean crontab | `openclaw cron list --fix` |
+| 📄 JSON Parse Error | Re-run setup | `agi-farm setup --force` |
 
 ---
 
@@ -480,10 +495,11 @@ This plugin is designed with security in mind:
 
 | ✅ What It Does | ❌ What It Doesn't Do |
 |----------------|----------------------|
+| Binds dashboard to `127.0.0.1` only | Expose data to the network |
+| Validates `Origin` header on all mutations | Accept cross-origin requests |
+| Uses CSRF tokens with timing-safe comparison | Leak token length via timing |
 | Uses OpenClaw CLI (inherits credentials) | Store API keys or tokens |
 | Reads/writes local workspace files | Send data to external servers |
-| Runs local HTTP server (127.0.0.1) | Expose data to network |
-| Uses your configured LLM providers | Add additional authentication |
 
 **Your credentials stay in OpenClaw's configuration.**
 
@@ -522,6 +538,16 @@ MIT License — built for [OpenClaw](https://docs.openclaw.ai)
 
 Copyright (c) 2025 oabdelmaksoud
 
+## 📈 Star History
+
+<a href="https://www.star-history.com/?repos=oabdelmaksoud%2FAGI-FARM-PLUGIN&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/image?repos=oabdelmaksoud/AGI-FARM-PLUGIN&type=date&theme=dark&legend=bottom-right" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/image?repos=oabdelmaksoud/AGI-FARM-PLUGIN&type=date&legend=bottom-right" />
+   <img alt="Star History Chart" src="https://api.star-history.com/image?repos=oabdelmaksoud/AGI-FARM-PLUGIN&type=date&legend=bottom-right" />
+ </picture>
+</a>
+
 ---
 
 ## 🔗 Links
@@ -529,7 +555,7 @@ Copyright (c) 2025 oabdelmaksoud
 - **GitHub**: https://github.com/oabdelmaksoud/AGI-FARM-PLUGIN
 - **Issues**: https://github.com/oabdelmaksoud/AGI-FARM-PLUGIN/issues
 - **OpenClaw Docs**: https://docs.openclaw.ai
-- **NPM Package**: (coming soon)
+- **NPM Package**: https://www.npmjs.com/package/agi-farm
 
 ---