agentix-cli 0.8.0 → 0.13.0

package/README.md

@@ -1,8 +1,18 @@
 # AgentX
 
-**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.
+**Self-hosted multi-agent orchestrator.** Routes messages from Telegram, WhatsApp, Discord, GitLab, crons, webhooks, and cross-machine 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.
+## Why AgentX?
+
+Existing multi-agent frameworks (CrewAI, AutoGen, LangGraph) are SDK-first, Python-heavy, and cloud-dependent. AgentX is **infrastructure-first** — closer to systemd for AI agents than to another framework.
+
+- **BYOAI** — Bring your own AI. Claude, OpenAI, Ollama, whatever
+- **Agents = directories** — Each agent is a workspace with config files. No code required
+- **Mesh federation** — Agents on different machines collaborate over Tailscale/VPN
+- **Channel routing** — Telegram, GitLab, WhatsApp, Discord, webhooks — built in
+- **Cross-channel messaging** — Agents receive on one channel, send to another via `/send` API
+- **Wiki memory** — Agents build compounding knowledge from conversations
+- **Live monitoring** — Real-time SSE event stream + debug mode with categories
 
 ## Install
 
@@ -10,16 +20,17 @@
 npm install -g agentix-cli
 ```
 
-## Quick start
+## Quick Start
 
 ```bash
-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
+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 the daemon
+agentx daemon watch            # Live activity feed (color-coded)
 ```
 
-## How it works
+## Architecture
 
 ```
   Telegram ──┐
@@ -31,63 +42,306 @@ agentx daemon start        # Start
   A2A mesh ──┘
                     │
             Context Engine
-         (8 layers, token-budgeted)
+       (10 layers, token-budgeted)
+                    │
+          ┌─────────┼─────────┐
+       Wiki    Memory    Bootstrap
+   (per-agent) (Haiku)  (SOUL.md)
 ```
 
 Each agent = a workspace directory with Claude Code configuration (`.claude/`, `CLAUDE.md`, skills, hooks, MCP servers). AgentX orchestrates when and where agents run.
 
+## Communication Matrix
+
+AgentX supports every communication path: human-to-agent, agent-to-human, agent-to-agent, and cross-channel — across all channels.
+
+| Path | Telegram | WhatsApp | Discord | GitLab | API |
+|------|:--------:|:--------:|:-------:|:------:|:---:|
+| **H2A** (human to agent) | mention/DM | route | mention/DM | @username | POST /task |
+| **A2H reply** | streaming | text | text | per-agent token | JSON |
+| **A2H initiate** | /send | /send | /send | /send | - |
+| **A2A delegation** | per-account bot chain | shared number + name prefix | shared + name prefix | @mention webhook | - |
+| **Cross-channel** | /send | /send | /send | /send | - |
+| **Cross-mesh** | mesh task | mesh task | mesh task | mesh task | mesh task |
+
+### Cross-Channel Messaging
+
+Agents can send messages to ANY channel proactively — not just reply:
+
+```bash
+# Agent on GitLab sends a notification to Telegram
+curl -X POST http://localhost:19900/send \
+  -H "Content-Type: application/json" \
+  -d '{"channel":"telegram","chatId":"-1001234567890","text":"Deploy complete!","agentId":"devops"}'
+```
+
+This enables **H2A2H chains**: a human asks an agent on GitLab to notify someone on WhatsApp. The agent calls `/send` to deliver the message cross-channel.
+
+### Automated Client Services
+
+Define predictable request-response services that intercept messages BEFORE agent routing — no LLM needed for known patterns:
+
+```jsonc
+"services": {
+  "monthly-report": {
+    "name": "Monthly Client Report",
+    "triggers": [
+      { "pattern": "monthly report|client records|تقرير الشهر", "channel": "whatsapp" }
+    ],
+    "allowedContacts": ["+966"],
+    "agent": "atlas",
+    "prompt": "Run the monthly report SQL query and export as CSV...",
+    "schedule": "0 9 1 * *",
+    "notify": { "channel": "whatsapp", "chatId": "+966...@s.whatsapp.net" }
+  }
+}
+```
+
+- **Regex triggers** with optional channel filter (Arabic + English patterns)
+- **Contact allowlist** — only authorized contacts can trigger
+- **Predefined prompt** — service sends a known prompt, not the user's raw message
+- **Optional cron schedule** — also runs automatically on a schedule
+- **Cross-channel notify** — results delivered to any channel
+
 ## 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
-
-## CLI Commands
-
-### Daemon
+
+| Channel | Highlights |
+|---------|-----------|
+| **Telegram** | Multi-account bots, streaming edits, bot-to-bot delegation, media handling |
+| **WhatsApp** | Baileys integration, QR pairing, per-contact/group routing, agent delegation (shared number, name-prefixed) |
+| **Discord** | Mention-based routing, DM support, agent delegation |
+| **GitLab** | Per-agent identity via PAT tokens, @mention routing, bot-to-bot handoff, image attachments, cascade prevention |
+| **Webhooks** | Generic `POST /webhook/:agentId` for Stripe, Sentry, GitHub, etc. |
+
+### GitLab Integration
+
+Agents participate in GitLab as first-class team members:
+- **Per-agent identity** — Each agent has its own GitLab user and PAT. Agent usernames resolved from tokens at startup via API (not manual config)
+- **Deterministic @mention routing** — `@coding-agent` routes to that agent. Username-to-agent map built from token resolution
+- **Bot-to-bot handoff** — QA agent can `@mention` devops in its review, devops picks it up automatically
+- **Eye reaction** — Agents react with 👀 using their own token (never the global token)
+- **Cascade prevention** — Hidden signature `<!-- agentx:agentId -->`, sent-note dedup, bot-user detection
+- **Human mention filtering** — If @mentioned user isn't a known agent, the note is ignored
+- **Image attachments** — Screenshots and diagrams in comments are downloaded and passed to agents for analysis
+
+### Context Compaction
+
+Long conversations don't lose context. When session history exceeds threshold:
+1. **Memory flush** — Haiku extracts memorable facts before compaction
+2. **Summarize** — Older messages compressed into a structured summary
+3. **Preserve** — Last 6 messages kept verbatim, tool call pairs kept intact
+
+### Message Queue
+
+When an agent is busy, incoming messages are queued instead of dropped:
+
+| Mode | Behavior |
+|------|----------|
+| `collect` (default) | Batch all messages, deliver as one when agent finishes |
+| `followup` | Process each queued message as a separate follow-up turn |
+| `drop` | Silently discard (for non-critical channels) |
+
+Configure per agent: `agents.<id>.queueMode`
+
+### Sub-Agent Spawning
+
+Agents can spawn background sub-agents for parallel work:
+- `spawn_agent` tool available in orchestrator tier
+- Depth-limited (max 3 levels) to prevent infinite chains
+- Timeout enforcement per spawn
+- Results returned to parent agent
+
+### Bootstrap Identity Files
+
+Structured workspace files loaded into agent context automatically:
+
+| File | Purpose | Lifecycle |
+|------|---------|-----------|
+| `SOUL.md` | Personality, tone, boundaries | Persistent |
+| `IDENTITY.md` | Name, role, tagline | Persistent |
+| `USER.md` | User profile, preferences | Persistent |
+| `AGENTS.md` | Operating rules, standing orders | Persistent |
+| `BOOTSTRAP.md` | First-run ritual | Auto-deleted after first load |
+
+### Heartbeat
+
+Periodic in-session check-ins (unlike cron which creates isolated sessions):
+
+```jsonc
+"agents": {
+  "assistant": {
+    "heartbeat": {
+      "enabled": true,
+      "intervalMinutes": 30,
+      "prompt": "Check inbox, pending tasks, and system health."
+    }
+  }
+}
+```
+
+Heartbeat runs in the agent's existing session context, preserving conversation history and memory.
+
+### Cron with Retry & Missed Run Detection
+
+Scheduled jobs with production-grade reliability:
+- **Exponential backoff** on failure: 30s, 1m, 5m, 15m, 60m (up to 5 retries)
+- **Missed run detection** — On startup, compares saved last-run times against schedule and catches up
+- **Failure notifications** — Configure per-job `notify` destination (any channel)
+- **Auto-disable** after 3 consecutive failures (`onError: "disable"`)
+- **Health endpoint** — `GET /crons/health` returns healthy/failing/disabled/missed counts
+
+```jsonc
+"crons": {
+  "daily-report": {
+    "schedule": "0 9 * * *",
+    "agent": "assistant",
+    "prompt": "Generate today's status report.",
+    "notify": {
+      "channel": "telegram",
+      "chatId": "-1001234567890"
+    }
+  }
+}
+```
+
+### Smart Block Streaming
+
+Intelligent chunking for message delivery across channels:
+- **minChars** threshold — no fragment spam
+- **Paragraph-aware breaks** — never splits inside code fences
+- **Per-channel defaults** — Telegram (60 chars), WhatsApp (40 chars + human pacing), Discord (80 chars)
+- **Coalescing** — idle debounce merges consecutive small blocks
+
+### Observability & Debug Mode
+
+Toggle verbose debug logging at runtime:
+
+```bash
+# Enable debug for specific categories
+curl -X POST http://localhost:19900/debug/on?categories=webhook,agent
+
+# Check debug state + recent log entries
+curl http://localhost:19900/debug
+
+# Disable
+curl -X POST http://localhost:19900/debug/off
+
+# Or via environment variable
+AGENTX_DEBUG=webhook,agent agentx daemon start
+```
+
+**Categories:** `webhook`, `agent`, `channel`, `cron`, `mesh`, `context`, `memory`, `config`, `all`
+
+### Live Monitoring
+
+```bash
+agentx daemon watch            # Color-coded live feed
+```
+
+Or connect via SSE:
+```bash
+curl -N http://localhost:19900/events
+```
+
+### Wiki Knowledge Base
+
+Each agent has a personal wiki — a compounding knowledge artifact built from conversations.
+
+1. **Ingest** — Every conversation saved as raw entry
+2. **Absorb** — LLM compiles entries into wiki articles
+3. **Query** — Agents get relevant context filtered by tags
+4. **Sync** — Federated wiki view across mesh peers
+
+Three compilation modes: `unified` (default), `flat`, `graph`. Wikipedia-style UI at `agentx wiki serve`.
+
+### Persistent Agent Memory
+
+Haiku-powered cross-session memory:
+- Facts, preferences, commitments extracted after each conversation
+- BM25 full-text search across memories
+- Injected into context for future conversations
+- Auto-pruning with configurable expiry
+
+### Skills
+
+Reusable capabilities installed per-agent or globally:
+
+```bash
+agentx skill add skills/my-skill --all
+agentx skill list
+```
+
+### Mesh Federation
+
+Agents on different machines collaborate:
+
+```bash
+agentx mesh add server-2 http://100.x.x.x:19900
+agentx daemon send devops "check disk space" --peer server-2
+```
+
+- Static or mDNS peer discovery
+- Health checks every 60s
+- Wiki sync across peers
+- Cross-machine agent delegation via A2A protocol
+
+### MCP Server
+
+AgentX exposes its full capabilities as MCP tools, usable from Claude Code, Cursor, or Windsurf:
+
+| Tool | Description |
+|------|-------------|
+| `agentx_generate` | Generate code/components/APIs with tech stack awareness |
+| `agentx_inspect` | Analyze project tech stack and schemas |
+| `agentx_send` | Send messages to any channel (cross-channel routing) |
+| `agentx_task` | Delegate work to a specific agent |
+| `agentx_agents` | List agents and their status |
+| `agentx_health` | Daemon health check |
+| `agentx_crons` | Cron job health with error details |
+| `agentx_debug` | Toggle debug mode with categories |
+
 ```bash
-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)
+# Start the MCP server (stdio transport)
+agentx mcp
 ```
 
-### Management
+Configure in Claude Code's `.claude/settings.json` or Cursor's MCP settings.
+
+## CLI Reference
+
 ```bash
-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
+# Daemon
+agentx daemon start [--detach]
+agentx daemon stop
+agentx daemon status
+agentx daemon watch
+agentx daemon logs [-f]
+agentx daemon send <agent> <msg> [--peer <name>]
+agentx daemon deploy <host> -i key [--restart]
+
+# Wiki
+agentx wiki status [--mode M]
+agentx wiki absorb [--agent X] [--mode M] [--dry-run]
+agentx wiki serve [--mode M] [--peer URL]
+agentx wiki sync [--peer URL]
+agentx wiki compare --agent X
+agentx wiki lint [--agent X]
+agentx wiki search <query>
+
+# Management
+agentx agent add | list | remove <id>
+agentx channel add | list
+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 config check | show
 agentx init [--force]
+
+# Usage
+agentx usage [report] [--days N]
 ```
 
 ## Configuration
@@ -96,7 +350,7 @@ Single `agentx.json`. Environment variables expanded (`${VAR_NAME}`). Auto-loads
 
 ```jsonc
 {
-  "node": { "id": "my-machine", "name": "My Machine", "bind": "127.0.0.1:18800" },
+  "node": { "id": "my-machine", "name": "My Machine", "bind": "0.0.0.0:19900" },
 
   "agents": {
     "assistant": {
@@ -104,9 +358,15 @@ Single `agentx.json`. Environment variables expanded (`${VAR_NAME}`). Auto-loads
       "workspace": "/path/to/workspace",
       "tier": "claude-code",        // "sdk" or "orchestrator"
       "model": "claude-sonnet-4-6",
-      "mentions": ["@my_bot"],
+      "mentions": ["@my_bot", "my-gitlab-user"],
       "maxConcurrent": 2,
-      "systemPrompt": "You are a helpful assistant."
+      "queueMode": "collect",       // "followup" or "drop"
+      "systemPrompt": "You are a helpful assistant.",
+      "heartbeat": {
+        "enabled": false,
+        "intervalMinutes": 30,
+        "prompt": "Check inbox and pending tasks."
+      }
     }
   },
 
@@ -118,19 +378,6 @@ Single `agentx.json`. Environment variables expanded (`${VAR_NAME}`). Auto-loads
       },
       "policy": { "dm": "pair", "group": "mention-required" }
     },
-    "whatsapp": {
-      "enabled": true,
-      "defaultAgent": "assistant",
-      "routes": [
-        { "contact": "+1234567890", "agent": "assistant" },
-        { "group": "Team Chat", "agent": "devops" }
-      ]
-    },
-    "discord": {
-      "enabled": true,
-      "token": "${DISCORD_BOT_TOKEN}",
-      "agentBinding": "assistant"
-    },
     "gitlab": {
       "enabled": true,
       "host": "https://gitlab.example.com",
@@ -138,11 +385,14 @@ Single `agentx.json`. Environment variables expanded (`${VAR_NAME}`). Auto-loads
       "webhookPort": 18810,
       "routes": [
         { "project": "team/project-a", "agent": "pm-a" },
-        { "project": "*", "agent": "atlas" }
+        { "project": "*", "agent": "default-agent" }
       ],
       "agentMappings": [
-        { "agentId": "coder", "gitlabUsernames": ["coder-bot"], "keywords": ["coder"] },
-        { "agentId": "devops", "gitlabUsernames": ["devops-bot"], "keywords": ["deploy"] }
+        {
+          "agentId": "coder",
+          "gitlabUsernames": ["coder-bot"],
+          "token": "${CODER_GITLAB_TOKEN}"
+        }
       ]
     }
   },
@@ -153,65 +403,66 @@ Single `agentx.json`. Environment variables expanded (`${VAR_NAME}`). Auto-loads
       "schedule": "0 9 * * *",
       "timezone": "UTC",
       "agent": "assistant",
-      "prompt": "Generate today's status report."
+      "prompt": "Generate today's status report.",
+      "onError": "notify",
+      "notify": {
+        "channel": "telegram",
+        "chatId": "-1001234567890"
+      }
     }
   },
 
   "mesh": {
     "enabled": true,
     "peers": [
-      { "url": "http://100.67.108.119:19900", "name": "server-2" }
+      { "url": "http://100.x.x.x:19900", "name": "server-2" }
     ]
   }
 }
 ```
 
-## Context Engine
-
-Every agent prompt is built from 8 structured layers, each with a token budget:
-
-| 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 |
-
-Total budget: 4000 tokens. Lower layers truncated if over budget.
-
 ## HTTP API
 
 | Endpoint | Method | Description |
 |----------|--------|-------------|
-| `/health` | GET | Status, agents, crons, mesh, today's usage |
+| `/health` | GET | Status, agents, crons, mesh, usage |
+| `/events` | GET | SSE live event stream |
 | `/agents` | GET | List agents |
+| `/channels` | GET | List registered channels |
 | `/crons` | GET | List cron jobs |
-| `/mesh` | GET | Mesh peers |
-| `/usage` | GET | 7-day token usage per agent |
+| `/crons/health` | GET | Cron health: healthy/failing/disabled/missed |
+| `/services` | GET | List registered automated services |
 | `/task` | POST | `{ "agent": "id", "message": "..." }` |
+| `/send` | POST | `{ "channel": "telegram", "chatId": "...", "text": "...", "agentId": "..." }` |
 | `/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 |
+| `/webhook/:agentId[/:source]` | POST | Webhook callback |
+| `/v1/chat/completions` | POST | OpenAI-compatible endpoint |
+| `/debug` | GET | Debug state + recent log entries |
+| `/debug/on` | POST | Enable debug (`?categories=webhook,agent`) |
+| `/debug/off` | POST | Disable debug |
 | `/.well-known/agent-card.json` | GET | A2A agent discovery |
 
-## OpenAI-Compatible Endpoint
+## Context Engine
 
-Any agent can be used as an LLM backend for ElevenLabs Conversational AI, Cursor, or any OpenAI-compatible client.
+Every agent prompt is built from structured layers, each with a token budget:
 
-```bash
-curl -X POST http://your-server:18800/v1/chat/completions \
-  -H "Content-Type: application/json" \
-  -d '{"model": "atlas", "messages": [{"role": "user", "content": "Hello"}]}'
-```
+| Layer | Priority | Budget | Content |
+|-------|----------|--------|---------|
+| Channel | 1 | 200 | Channel type + formatting rules |
+| Scope | 2 | 200 | Group name, project path, or DM |
+| Landscape | 3 | 800 | Team roster, mesh peers, rules, /send API docs |
+| Identity | 4 | 200 | Agent system prompt |
+| Bootstrap | 4.5 | 500 | SOUL.md, IDENTITY.md, AGENTS.md |
+| Intent | 5 | 200 | Extracted: deploy, review, bugfix... |
+| Artifacts | 6 | 500 | Media, reply-to text, issue refs |
+| Memory | 6.5 | 600 | Cross-session facts (Haiku-extracted) |
+| History | 7 | 1200 | Conversation or session history |
+| Cross-chat | 7 | 800 | Context from other active chats |
+| Wiki | 8 | 1000 | Tag-matched knowledge articles |
 
-Supports streaming (`"stream": true`) with SSE. The `model` field maps to the agent ID.
+Total budget: 6000 tokens. Context always injected, even on resumed sessions.
 
-## Three execution tiers
+## Three Execution Tiers
 
 | Tier | How | Auth | Best for |
 |------|-----|------|----------|
@@ -219,25 +470,45 @@ Supports streaming (`"stream": true`) with SSE. The `model` field maps to the ag
 | `sdk` | Claude Agent SDK | API key | Programmatic control, headless servers |
 | `orchestrator` | AgentX's own loop | Any provider key | Non-Claude providers (OpenAI, Ollama) |
 
-## Migrating from OpenClaw
+## Daemon Management
+
+Single-instance guard via PID file — prevents orphan processes on restart:
 
 ```bash
-agentx migrate openclaw    # Auto-imports agents, channels, crons, skills
+agentx daemon start            # Checks .agentx/daemon.pid, exits if another is running
+agentx daemon stop              # Graceful shutdown, saves cron last-run times
+systemctl --user restart agentx-daemon.service  # Safe — PID guard prevents duplicates
 ```
 
-## Use cases
+## Use Cases
 
 - **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
-- **Webhook automation** — Sentry error → DevOps agent investigates, Stripe payment → billing agent processes
-- **Bot-to-bot delegation** — Nadia mentions @devops, DevOps picks up and responds
+- **GitLab CI/CD team** — coder, QA, devops, PM agents collaborate on issues via @mentions
+- **Cross-channel notifications** — GitLab agent notifies humans on Telegram/WhatsApp
+- **WhatsApp delegation** — shared phone number, agents identified by name prefix
+- **Scheduled automation** — cron jobs with retry, missed-run catch-up, failure alerts
+- **Multi-machine swarm** — agents on laptop + server collaborate via mesh
+- **Webhook automation** — Sentry error -> DevOps investigates, Stripe payment -> billing processes
+- **Personal wiki** — Every conversation compounds into searchable knowledge
 
-## Legal
+## Contributing
+
+```bash
+git clone https://github.com/anis-marrouchi/agentx.git
+cd agentx
+npm install
+npm run build              # ESM build via tsup
+npm test                   # Run tests
+agentx init --force        # Create local config
+agentx daemon start        # Start dev daemon
+agentx daemon watch        # See what's happening
+```
 
-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.
+Areas we're looking for help:
+- **Testing** — Unit and integration tests
+- **Channels** — Slack, Microsoft Teams adapters
+- **Dashboard** — Web UI for agent management
+- **Security** — Audit of token handling and permission boundaries
 
 ## License
 

package/dist/agent-5KIMJI3F.js

@@ -0,0 +1,2 @@
+import{s as a,t as b,u as c}from"./chunk-D6EDMQRV.js";import"./chunk-SFQUP3BP.js";import"./chunk-CJ45Y2IR.js";import"./chunk-KXZMYLHQ.js";import"./chunk-M7HKBG3V.js";import"./chunk-MCJUAE6V.js";import"./chunk-DSYKYZMT.js";import"./chunk-QOYAX2FT.js";import"./chunk-4YCH6IZV.js";export{a as createAgentContext,b as generate,c as generateStream};
+//# sourceMappingURL=agent-5KIMJI3F.js.map

package/dist/chunk-34UAFPK4.js

@@ -0,0 +1,10 @@
+import{readFileSync as R,writeFileSync as D,appendFileSync as S,existsSync as C,mkdirSync as _}from"fs";import{resolve as T}from"path";var y={"claude-opus":{input:15,output:75,cacheRead:1.5,cacheCreate:18.75},"claude-sonnet":{input:3,output:15,cacheRead:.3,cacheCreate:3.75},"claude-haiku":{input:.25,output:1.25,cacheRead:.025,cacheCreate:.3125}};function v(O){let t=O.toLowerCase();return t.includes("opus")?"claude-opus":t.includes("haiku")?"claude-haiku":"claude-sonnet"}var b=class{dir;cache=null;constructor(t=T(process.cwd(),".agentx/usage")){this.dir=t,_(this.dir,{recursive:!0})}static calculateCost(t){let o=v(t.model||"claude-sonnet"),n=y[o]||y["claude-sonnet"];return(t.inputTokens||0)/1e6*n.input+(t.outputTokens||0)/1e6*n.output+(t.cacheReadTokens||0)/1e6*n.cacheRead+(t.cacheCreateTokens||0)/1e6*n.cacheCreate}record(t,o,n,c,s,i,l){let e=this.today(),a=e.agents[t]||{tasks:0,inputTokens:0,outputTokens:0,cacheReadTokens:0,cacheCreateTokens:0,totalDuration:0,errors:0};a.tasks++,a.totalDuration+=o,l&&(a.model=l),n?(a.inputTokens+=n.inputTokens,a.outputTokens+=n.outputTokens,a.cacheReadTokens+=n.cacheReadTokens,a.cacheCreateTokens+=n.cacheCreateTokens):c!==void 0&&s!==void 0&&(a.inputTokens+=Math.ceil(c/4),a.outputTokens+=Math.ceil(s/4)),i&&a.errors++,e.agents[t]=a,this.save(e)}today(){let t=new Date().toISOString().slice(0,10);if(this.cache?.date===t)return this.cache;let o=this.filePath(t);if(C(o))try{return this.cache=JSON.parse(R(o,"utf-8")),this.cache}catch{}return this.cache={date:t,agents:{}},this.cache}getDate(t){let o=this.filePath(t);if(!C(o))return null;try{return JSON.parse(R(o,"utf-8"))}catch{return null}}generateDailyReport(t){let o=t||new Date().toISOString().slice(0,10),n=this.getDate(o);if(!n)return null;let c=0,s=0,i=0,l=0,e=0,a=0,g="",m=0,p={};for(let[k,h]of Object.entries(n.agents)){let d=b.calculateCost(h);p[k]=d,c+=h.tasks,s+=h.inputTokens||0,i+=h.outputTokens||0,l+=h.cacheReadTokens||0,e+=h.cacheCreateTokens||0,a+=d,d>m&&(m=d,g=k)}return{date:o,totalTasks:c,totalInput:s,totalOutput:i,totalCacheRead:l,totalCacheCreate:e,totalCost:a,topAgent:g,topCost:m,agentCosts:p}}appendToTokenCosts(t,o){let n=o||T(process.cwd(),".agentx/TOKEN_COSTS.md"),c=e=>e<.01?e.toFixed(4):e.toFixed(2),s=e=>e>=1e6?`${(e/1e6).toFixed(1)}M`:e>=1e3?`${(e/1e3).toFixed(0)}K`:String(e),i=Object.entries(t.agentCosts).sort(([,e],[,a])=>a-e).map(([e,a])=>`${e}: $${c(a)}`).join(", "),l=`| ${t.date} | ${t.totalTasks} | ${s(t.totalInput)} | ${s(t.totalOutput)} | ${s(t.totalCacheRead)} | ${s(t.totalCacheCreate)} | $${c(t.totalCost)} | ${i} |`;C(n)?S(n,l+`
+`):D(n,`# Token Costs
+
+Daily token cost tracking. Auto-appended at midnight (Africa/Tunis).
+
+| Date | Tasks | Input | Output | Cache R | Cache W | Cost | Per Agent |
+|------|-------|-------|--------|---------|---------|------|-----------|
+`+l+`
+`)}summary(t=7){let o=0,n=0,c=0,s=0,i=0,l=0,e=0,a={};for(let p=0;p<t;p++){let k=new Date(Date.now()-p*864e5).toISOString().slice(0,10),h=this.getDate(k);if(h)for(let[d,u]of Object.entries(h.agents)){let f=b.calculateCost(u);o+=u.tasks,n+=u.inputTokens||0,c+=u.outputTokens||0,s+=u.cacheReadTokens||0,i+=u.cacheCreateTokens||0,l+=u.errors,e+=f;let r=a[d]||{tasks:0,input:0,output:0,cacheRead:0,cacheCreate:0,total:0,avgDuration:0,totalDuration:0,cost:0};r.tasks+=u.tasks,r.input+=u.inputTokens||0,r.output+=u.outputTokens||0,r.cacheRead+=u.cacheReadTokens||0,r.cacheCreate+=u.cacheCreateTokens||0,r.total=r.input+r.output+r.cacheRead+r.cacheCreate,r.totalDuration+=u.totalDuration,r.avgDuration=r.totalDuration/r.tasks,r.cost+=f,u.model&&(r.model=u.model),a[d]=r}}let g=n+c+s+i,m=s+i>0?s/(s+i):0;return{totalTasks:o,totalTokens:g,totalInput:n,totalOutput:c,totalCacheRead:s,totalCacheCreate:i,cacheHitRatio:m,totalErrors:l,totalCost:e,byAgent:a}}filePath(t){return T(this.dir,`${t}.json`)}save(t){try{D(this.filePath(t.date),JSON.stringify(t,null,2))}catch{}}};export{b as a};
+//# sourceMappingURL=chunk-34UAFPK4.js.map