agentix-cli 0.4.0 → 0.6.0

package/README.md

@@ -1,6 +1,6 @@
 # AgentX
 
-**Self-hosted multi-agent orchestrator.** Routes messages from Telegram, WhatsApp, Discord, crons, and cross-machine A2A mesh to AI agents running on Claude Code, OpenAI, Ollama, or any LLM provider.
+**Self-hosted multi-agent orchestrator.** Routes messages from Telegram, WhatsApp, Discord, GitLab, crons, webhooks, and cross-machine A2A mesh to AI agents running on Claude Code, OpenAI, Ollama, or any LLM provider.
 
 > **Experimental.** Built as a self-hosted, bring-your-own-key alternative to third-party AI orchestrators affected by [Anthropic's updated terms of use](https://www.anthropic.com/policies). You run it on your own machines with your own API keys or Claude subscription.
 
@@ -13,138 +13,96 @@ npm install -g agentix-cli
 ## Quick start
 
 ```bash
-# 1. Initialize
-agentx init
-
-# 2. Add an agent (interactive)
-agentx agent add
-
-# 3. Add a Telegram bot (interactive, verifies token)
-agentx channel add
-
-# 4. Start
-agentx daemon start
+agentx init               # Create config + workspace
+agentx agent add           # Add an agent (interactive)
+agentx channel add         # Add a channel (Telegram/WhatsApp/Discord/GitLab)
+agentx daemon start        # Start
 ```
 
-That's it. Your agent is live on Telegram.
-
 ## How it works
 
 ```
   Telegram ──┐
-  WhatsApp ──┤  agentx     ┌─ claude -p --cwd /workspace
-  Discord ───┤  daemon  ───┤─ openai API
-  Cron ──────┤             └─ ollama generate
+  WhatsApp ──┤               ┌─ claude -p --cwd /workspace
+  Discord ───┤   agentx      │
+  GitLab  ───┤   daemon  ────┤─ openai API
+  Cron ──────┤               │
+  Webhook ───┤               └─ ollama generate
   A2A mesh ──┘
-                 │
-         routes messages to the right
-         agent workspace with wiki context
+                    │
+            Context Engine
+         (8 layers, token-budgeted)
 ```
 
-Each agent = a workspace directory. For Claude Code agents, permissions, hooks, MCP servers, skills, and memory live in the workspace's `.claude/` directory. AgentX just orchestrates when and where agents run.
-
-## CLI Commands
+Each agent = a workspace directory with Claude Code configuration (`.claude/`, `CLAUDE.md`, skills, hooks, MCP servers). AgentX orchestrates when and where agents run.
 
-### Daemon (core)
-
-```bash
-agentx daemon start              # Start foreground
-agentx daemon start --detach     # Start background
-agentx daemon stop               # Stop daemon
-agentx daemon status             # Show agents, crons, mesh health
-agentx daemon logs -f            # Follow logs
-agentx daemon send <agent> <msg> # Send a task to an agent
-agentx daemon send <agent> <msg> --peer server-2  # Send to remote agent
-agentx daemon deploy <host> -i ~/.ssh/key --restart  # Deploy + restart remote
-```
-
-### Agents
-
-```bash
-agentx agent add        # Interactive: creates workspace, CLAUDE.md, settings, wiki skill
-agentx agent list       # List all agents
-agentx agent remove <id>  # Remove from config (keeps workspace)
-```
+## Features
 
 ### Channels
+- **Telegram** — Multi-account bots, streaming responses, HTML formatting, typing indicators, seen reactions, bot-to-bot delegation, media handling (photos, voice, audio, video, documents)
+- **WhatsApp** — Baileys integration, QR pairing, self-chat mode, per-contact/group agent routing
+- **Discord** — Bot with mention-based routing, DM support
+- **GitLab** — Webhook channel: comments, issues, MRs, pipeline events route to agents. Agents reply as GitLab comments. @mention-based agent resolution in comments.
+- **Webhooks** — Generic `POST /webhook/:agentId` endpoint for Stripe, Sentry, GitHub, etc.
+
+### Core
+- **Multi-agent** — Named agents with custom permissions, concurrency limits, mention-based routing
+- **Context engine** — 8-layer structured context with per-layer token budgets (channel, scope, identity, peers, intent, artifacts, history, wiki)
+- **Wiki knowledge base** — Karpathy/Farzapedia-inspired Markdown wiki with permissions (private/shared/public). Agents compile conversations into articles.
+- **Session continuity** — `--resume SESSION_ID` for Claude Code, conversation history injection for other tiers
+- **Bot-to-bot** — Agents mention each other on Telegram, conversation chains with loop prevention (visited set + max depth)
+- **Group context** — Persistent group conversation log, agents see last 30 messages when mentioned
+- **Media handling** — Photos, voice messages, audio, video, documents downloaded and passed to agent
+- **Reply-to context** — When replying to a message, agent sees the original text
+
+### Operations
+- **Cron scheduler** — Timezone-aware recurring tasks with run logging
+- **A2A mesh** — Cross-machine agent communication over Tailscale/VPN
+- **Rate limiting** — Per-agent, 10/min, 100/hour (configurable)
+- **Token tracking** — Estimated tokens per agent per day, 7-day summaries
+- **Process management** — PID file, graceful shutdown, uncaught exception handlers
+- **72 unit tests** — Config, sessions, wiki, group log, context engine, telegram format
 
-```bash
-agentx channel add      # Interactive: Telegram bot token, verify, bind to agent
-agentx channel list     # List all channel bindings
-```
-
-**Supported channels:**
-- **Telegram** — Multi-account bots, streaming responses, MarkdownV2, typing indicators, seen reactions, bot-to-bot delegation
-- **WhatsApp** — Via Baileys (QR pairing), self-chat mode (message yourself to talk to agent), per-contact/group agent routing
-- **Discord** — Via discord.js, mention-based routing, DM support
-
-### Cron jobs
-
-```bash
-agentx cron add         # Interactive: schedule, agent, prompt, timezone
-agentx cron list        # List all jobs with status
-agentx cron enable <id> # Enable a job
-agentx cron disable <id>  # Disable a job
-```
-
-### Mesh (multi-machine)
-
-```bash
-agentx mesh add         # Interactive: URL, name, verifies connectivity
-agentx mesh list        # List peers with health status
-agentx mesh remove <name>  # Remove a peer
-```
-
-### Skills
-
-```bash
-agentx skill add ./path/to/skill --agent my-agent     # Add to one agent
-agentx skill add ./path/to/skill --all                 # Add to all agents
-agentx skill list       # List skills per agent
-```
-
-### Hooks
-
-```bash
-agentx hook add <agent>  # Interactive: event, type (command/http), matcher
-```
-
-### Migration
+## CLI Commands
 
+### Daemon
 ```bash
-agentx migrate openclaw                    # Auto-detect ~/.openclaw/
-agentx migrate openclaw /path/to/config    # Explicit path
-agentx migrate openclaw --dry-run          # Preview without writing
+agentx daemon start [--detach]       # Start (foreground or background)
+agentx daemon stop                   # Graceful shutdown
+agentx daemon status                 # Agents, crons, mesh health
+agentx daemon logs [-f]              # Tail logs
+agentx daemon send <agent> <msg>     # Send task to agent
+agentx daemon send <agent> <msg> --peer server-2  # Remote agent
+agentx daemon deploy <host> -i key [--restart]    # Deploy (runs tests first)
 ```
 
-### Setup
-
+### Management
 ```bash
-agentx init             # Create agentx.json, .env, workspace dirs
-agentx init --force     # Overwrite existing config
+agentx agent add / list / remove <id>
+agentx channel add / list              # Telegram, WhatsApp, Discord, GitLab
+agentx cron add / list / enable / disable <id>
+agentx mesh add / list / remove <name>
+agentx skill add <path> [--agent X] [--all]  / list
+agentx hook add <agent>
+agentx config check                    # Validate config + workspaces
+agentx config show                     # Print resolved config
+agentx migrate openclaw [path] [--dry-run]
+agentx init [--force]
 ```
 
 ## Configuration
 
-Single `agentx.json` file. Environment variables expanded (`${VAR_NAME}`). Auto-loads `.env`.
+Single `agentx.json`. Environment variables expanded (`${VAR_NAME}`). Auto-loads `.env`.
 
 ```jsonc
 {
-  "node": {
-    "id": "my-machine",
-    "name": "My Machine",
-    "bind": "127.0.0.1:18800"
-  },
-
-  "providers": {
-    "claude": { "apiKey": "${ANTHROPIC_API_KEY}" }
-  },
+  "node": { "id": "my-machine", "name": "My Machine", "bind": "127.0.0.1:18800" },
 
   "agents": {
     "assistant": {
       "name": "Assistant",
       "workspace": "/path/to/workspace",
-      "tier": "claude-code",
+      "tier": "claude-code",        // "sdk" or "orchestrator"
       "model": "claude-sonnet-4-6",
       "mentions": ["@my_bot"],
       "maxConcurrent": 2,
@@ -162,7 +120,6 @@ Single `agentx.json` file. Environment variables expanded (`${VAR_NAME}`). Auto-
     },
     "whatsapp": {
       "enabled": true,
-      "sessionDir": ".agentx/whatsapp-sessions",
       "defaultAgent": "assistant",
       "routes": [
         { "contact": "+1234567890", "agent": "assistant" },
@@ -173,6 +130,20 @@ Single `agentx.json` file. Environment variables expanded (`${VAR_NAME}`). Auto-
       "enabled": true,
       "token": "${DISCORD_BOT_TOKEN}",
       "agentBinding": "assistant"
+    },
+    "gitlab": {
+      "enabled": true,
+      "host": "https://gitlab.example.com",
+      "token": "${GITLAB_TOKEN}",
+      "webhookPort": 18810,
+      "routes": [
+        { "project": "team/project-a", "agent": "pm-a" },
+        { "project": "*", "agent": "atlas" }
+      ],
+      "agentMappings": [
+        { "agentId": "coder", "gitlabUsernames": ["coder-bot"], "keywords": ["coder"] },
+        { "agentId": "devops", "gitlabUsernames": ["devops-bot"], "keywords": ["deploy"] }
+      ]
     }
   },
 
@@ -182,8 +153,7 @@ Single `agentx.json` file. Environment variables expanded (`${VAR_NAME}`). Auto-
       "schedule": "0 9 * * *",
       "timezone": "UTC",
       "agent": "assistant",
-      "prompt": "Generate today's status report.",
-      "timeout": 600
+      "prompt": "Generate today's status report."
     }
   },
 
@@ -196,115 +166,78 @@ Single `agentx.json` file. Environment variables expanded (`${VAR_NAME}`). Auto-
 }
 ```
 
-## Agent workspace
-
-Each agent is a directory with Claude Code configuration:
-
-```
-my-workspace/
-├── .claude/
-│   ├── settings.json      # Permissions, hooks, env vars
-│   ├── .mcp.json          # MCP servers
-│   ├── agents/            # Subagents
-│   └── skills/            # SKILL.md files (gitlab, wiki, etc.)
-├── CLAUDE.md              # Agent identity and instructions
-└── ... (project files)
-```
-
-New agents created via `agentx agent add` get `CLAUDE.md`, `settings.json`, and the wiki skill automatically.
+## Context Engine
 
-## Three execution tiers
-
-| Tier | How | Auth | Best for |
-|------|-----|------|----------|
-| `claude-code` | Spawns `claude` CLI | Subscription | Full power: subagents, MCP, skills, hooks, 1M context |
-| `sdk` | Claude Agent SDK | API key | Programmatic control, headless servers |
-| `orchestrator` | AgentX's own loop | Any provider key | Non-Claude providers (OpenAI, Ollama) |
-
-## Session continuity
-
-Agents remember conversations:
-- **Claude Code tier**: `--resume SESSION_ID` with reliable ID from `--output-format json`
-- **Other tiers**: Recent conversation history injected into each prompt
-- **Wiki context**: Relevant knowledge articles injected before each response
-
-## Wiki knowledge base
-
-Inspired by [Karpathy's LLM knowledge base](https://x.com/karpathy/status/2040572272944324650) and [Farzapedia](https://gist.github.com/farzaa/c35ac0cfbeb957788650e36aabea836d).
-
-Agents build a shared Markdown wiki from conversations. Token-efficient: ~1K tokens for wiki context vs ~10K for session replay.
-
-```
-.agentx/wiki/
-├── WIKI.md              # Master index
-├── raw/entries/          # Auto-ingested conversations
-├── projects/             # Compiled knowledge
-├── decisions/
-└── patterns/
-```
+Every agent prompt is built from 8 structured layers, each with a token budget:
 
-**Permissions**: `private` (owner only), `shared` (listed agents), `public` (all agents).
+| Layer | Priority | Budget | Content |
+|-------|----------|--------|---------|
+| Channel | 1 | 200 | Channel type + rules (GitLab: no @handles, use GFM) |
+| Scope | 2 | 200 | Group name, project path, or DM |
+| Identity | 3 | 300 | Agent system prompt (first line) |
+| Peers | 4 | 400 | Team roster with handles (Telegram only) |
+| Intent | 5 | 200 | Extracted from message: deploy, review, bugfix... |
+| Artifacts | 6 | 500 | Media, reply-to text, issue/MR references |
+| History | 7 | 1200 | Group conversation or session history |
+| Wiki | 8 | 1000 | Relevant knowledge articles |
 
-## A2A Mesh
-
-Run `agentx daemon` on multiple machines. Agents communicate cross-machine via HTTP over Tailscale/VPN.
-
-```
-MacBook (Nadia, DevOps)  ←── Tailscale ──→  Server (Atlas, MTGL, KSI, ...)
-        :18800                                       :19900
-```
+Total budget: 4000 tokens. Lower layers truncated if over budget.
 
 ## HTTP API
 
-The daemon exposes a REST API:
-
 | Endpoint | Method | Description |
 |----------|--------|-------------|
-| `/health` | GET | System status, agents, crons, mesh |
+| `/health` | GET | Status, agents, crons, mesh, today's usage |
 | `/agents` | GET | List agents |
 | `/crons` | GET | List cron jobs |
-| `/mesh` | GET | Mesh peer directory |
+| `/mesh` | GET | Mesh peers |
+| `/usage` | GET | 7-day token usage per agent |
 | `/task` | POST | `{ "agent": "id", "message": "..." }` |
 | `/mesh/task` | POST | `{ "peer": "name", "message": "..." }` |
+| `/webhook/:agentId[/:source]` | POST | Webhook callback (GitLab, GitHub, Stripe, Sentry) |
+| `/v1/chat/completions` | POST | OpenAI-compatible endpoint (ElevenLabs, Cursor, any client) |
+| `/llm/:agentId/v1/chat/completions` | POST | OpenAI-compatible with explicit agent |
 | `/.well-known/agent-card.json` | GET | A2A agent discovery |
 
-## Migrating from OpenClaw
+## OpenAI-Compatible Endpoint
+
+Any agent can be used as an LLM backend for ElevenLabs Conversational AI, Cursor, or any OpenAI-compatible client.
 
 ```bash
-agentx migrate openclaw
+curl -X POST http://your-server:18800/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -d '{"model": "atlas", "messages": [{"role": "user", "content": "Hello"}]}'
 ```
 
-Auto-imports agents, Telegram bots, cron jobs, and WhatsApp config. Also ports:
-- Skills to workspace `.claude/skills/`
-- Permissions to `.claude/settings.json`
-- Agent identity to `CLAUDE.md`
-- WhatsApp sessions (reuses existing pairing)
+Supports streaming (`"stream": true`) with SSE. The `model` field maps to the agent ID.
+
+## Three execution tiers
+
+| Tier | How | Auth | Best for |
+|------|-----|------|----------|
+| `claude-code` | Spawns `claude` CLI | Subscription | Full power: subagents, MCP, skills, hooks, 1M context |
+| `sdk` | Claude Agent SDK | API key | Programmatic control, headless servers |
+| `orchestrator` | AgentX's own loop | Any provider key | Non-Claude providers (OpenAI, Ollama) |
 
-| OpenClaw | AgentX |
-|----------|--------|
-| Gateway + Node | Single daemon per machine |
-| OAuth proxy | Direct API key or subscription |
-| `openclaw.json` | `agentx.json` |
-| `exec-approvals.json` | `.claude/settings.json` per workspace |
+## Migrating from OpenClaw
+
+```bash
+agentx migrate openclaw    # Auto-imports agents, channels, crons, skills
+```
 
 ## Use cases
 
-- **Team of Telegram bots** — each project gets its own bot + agent with isolated workspace
+- **Team of Telegram bots** — each project gets its own bot + agent
+- **GitLab code review** — comment on MR, agent reviews and replies as a GitLab comment
 - **WhatsApp assistant** — message yourself, agent replies in self-chat
 - **Scheduled content** — cron jobs generate blog posts, reports, social media drafts
 - **Multi-machine swarm** — agents on MacBook + server collaborate via mesh
-- **Bot-to-bot delegation** — Nadia mentions @devops in her response, DevOps agent picks up
-- **Wiki knowledge** — agents accumulate knowledge, share insights across the team
+- **Webhook automation** — Sentry error → DevOps agent investigates, Stripe payment → billing agent processes
+- **Bot-to-bot delegation** — Nadia mentions @devops, DevOps picks up and responds
 
 ## Legal
 
-AgentX is a **self-hosted, bring-your-own-key** tool:
-
-- Each user provides their own API key or Claude subscription
-- No credentials are stored, shared, or proxied by AgentX
-- Built on official public packages: Claude API, Claude Agent SDK, Claude Code CLI
-- Provider-agnostic — works with any LLM, not locked to Anthropic
-- Same model as LangChain, CrewAI, AutoGen, Dify, n8n
+Self-hosted, bring-your-own-key. No credentials stored or proxied. Built on official public packages (Claude API, Claude Agent SDK, Claude Code CLI). Same model as LangChain, CrewAI, AutoGen.
 
 ## License