Skip to content

Commit a55854f

Browse files
jpelaez-23blocksclaude
jpelaez-23blocks
and
claude
committed
Initial release: AI Maestro Gateway Services
Multi-gateway monorepo for AI Maestro mesh network: - Email Gateway (Mandrill webhooks, IMAP/SMTP) - Slack Gateway (Socket Mode, Events API) - Discord Gateway (discord.js, Gateway Intents) - WhatsApp Gateway (Baileys, WhatsApp Web) Features: - Unified content security (34 injection patterns, trust-based wrapping) - Timing-safe authentication across all gateways - Management APIs (activity logs, config, stats) - Docker + docker-compose deployment - CI/CD with GitHub Actions - ESLint + TypeScript strict mode Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
0 parents  commit a55854f

117 files changed

Lines changed: 22310 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: CI
2+
3+
on:
4+
push:
5+
branches: [main]
6+
pull_request:
7+
branches: [main]
8+
9+
jobs:
10+
lint:
11+
runs-on: ubuntu-latest
12+
13+
steps:
14+
- uses: actions/checkout@v4
15+
16+
- uses: actions/setup-node@v4
17+
with:
18+
node-version: 22
19+
20+
- name: Install root dependencies
21+
run: npm install
22+
23+
- name: Lint
24+
run: npm run lint
25+
26+
build:
27+
runs-on: ubuntu-latest
28+
29+
strategy:
30+
matrix:
31+
gateway: [discord-gateway, slack-gateway, email-gateway, whatsapp-gateway]
32+
33+
defaults:
34+
run:
35+
working-directory: ${{ matrix.gateway }}
36+
37+
steps:
38+
- uses: actions/checkout@v4
39+
40+
- uses: actions/setup-node@v4
41+
with:
42+
node-version: 22
43+
cache: npm
44+
cache-dependency-path: ${{ matrix.gateway }}/package-lock.json
45+
46+
- name: Install dependencies
47+
run: npm ci
48+
49+
- name: Type check
50+
run: npm run typecheck --if-present
51+
52+
- name: Test
53+
run: npm test --if-present

‎.gitignore‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
node_modules/
2+
dist/
3+
.env
4+
.env.*
5+
!.env.example
6+
credentials/
7+
credentials.yaml
8+
*.bak

‎CONTRIBUTING.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# Contributing to AI Maestro Gateways
2+
3+
Thank you for your interest in contributing! This guide will help you get started.
4+
5+
## How to Contribute
6+
7+
1. **Fork** the repository
8+
2. **Create a branch** for your feature or fix (`git checkout -b feature/my-change`)
9+
3. **Make your changes** and write tests if applicable
10+
4. **Run type checks** to ensure nothing is broken
11+
5. **Commit** with a clear message describing the change
12+
6. **Open a Pull Request** against `main`
13+
14+
## Development Setup
15+
16+
### Prerequisites
17+
18+
- Node.js 22+
19+
- npm 10+
20+
21+
### Getting Started
22+
23+
Each gateway is an independent Node.js project. To work on a specific gateway:
24+
25+
```bash
26+
cd discord-gateway # or slack-gateway, email-gateway, whatsapp-gateway
27+
cp .env.example .env # configure your local environment
28+
npm install
29+
npm run dev # start with file watching
30+
```
31+
32+
### Running Type Checks
33+
34+
```bash
35+
cd <gateway-dir>
36+
npm run typecheck # runs tsc --noEmit
37+
```
38+
39+
### Running Tests
40+
41+
```bash
42+
cd <gateway-dir>
43+
npm test # if tests exist for that gateway
44+
```
45+
46+
## Code Style
47+
48+
- **Language:** TypeScript (strict mode)
49+
- **Module system:** ESM (`"type": "module"` in package.json)
50+
- **Runtime:** tsx (TypeScript execution without build step)
51+
- **Formatting:** Use consistent indentation (2 spaces)
52+
- **Naming:** camelCase for variables/functions, PascalCase for types/interfaces
53+
- **Imports:** Use `.js` extensions in import paths (required for ESM)
54+
- **Error handling:** Always handle errors gracefully; log with `[CONTEXT]` prefixes
55+
56+
## Pull Requests
57+
58+
- Keep PRs focused on a single change
59+
- Include a clear description of what the PR does and why
60+
- Reference any related issues
61+
- Make sure type checks pass before requesting review
62+
- Update `.env.example` if you add new environment variables
63+
- Update the gateway's README if you change behavior
64+
65+
## Adding a New Gateway
66+
67+
To add a new gateway to the monorepo:
68+
69+
1. **Create the directory** at the repo root (e.g., `telegram-gateway/`)
70+
2. **Initialize the project:**
71+
```bash
72+
mkdir telegram-gateway && cd telegram-gateway
73+
npm init -y
74+
```
75+
3. **Follow the existing structure:**
76+
```
77+
telegram-gateway/
78+
├── .env.example # All env vars with placeholder values
79+
├── .gitignore # node_modules, dist, .env
80+
├── Dockerfile # Multi-stage build (see other gateways)
81+
├── ecosystem.config.cjs # pm2 configuration
82+
├── package.json # Scripts: start, dev, typecheck
83+
├── tsconfig.json
84+
└── src/
85+
├── config.ts # Load env vars with dotenv
86+
├── content-security.ts # Trust model + injection scanning
87+
├── inbound.ts # Platform -> AI Maestro
88+
├── outbound.ts # AI Maestro -> Platform
89+
├── server.ts # Express health/management + main()
90+
└── types.ts # TypeScript interfaces
91+
```
92+
4. **Implement the content security module** with the standard trust model (operator/external) and injection pattern scanner
93+
5. **Add a health endpoint** at `GET /health`
94+
6. **Add the gateway** to the CI matrix in `.github/workflows/ci.yml`
95+
7. **Add a service** to `docker-compose.yml`
96+
8. **Create a Dockerfile** following the multi-stage pattern
97+
9. **Update the root README** with the new gateway info

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 23blocks-OS
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# AI Maestro Gateways
2+
3+
Gateway services that bridge external messaging platforms with the [AI Maestro](https://github.com/23blocks-OS/ai-maestro) agent mesh network.
4+
5+
## Gateways
6+
7+
| Gateway | Port | Platform | Status |
8+
|---------|------|----------|--------|
9+
| [Email](./email-gateway/) | 3020 | IMAP/SMTP | Production |
10+
| [WhatsApp](./whatsapp-gateway/) | 3021 | WhatsApp Web | WIP |
11+
| [Slack](./slack-gateway/) | 3022 | Slack Bolt (Socket Mode) | Production |
12+
| [Discord](./discord-gateway/) | 3023 | discord.js v14 | Ready |
13+
14+
## Architecture
15+
16+
All gateways follow the same pattern:
17+
18+
- **Runtime:** Node.js + TypeScript + Express
19+
- **Process manager:** pm2
20+
- **Inbound:** Platform events → content security scan → AI Maestro message
21+
- **Outbound:** Poll AI Maestro inbox → format response → send to platform
22+
- **Security:** Trust-based content wrapping (operator vs external), 34 injection pattern detection
23+
- **Management APIs:** `/health`, `/api/config`, `/api/stats`, `/api/activity`
24+
25+
## Message Flow
26+
27+
```
28+
Platform (Slack/Discord/Email/WhatsApp)
29+
↓ inbound
30+
Content Security (trust check + injection scan)
31+
↓
32+
Agent Resolver (multi-host lookup with caching)
33+
↓ POST /api/messages
34+
AI Maestro Agent Network
35+
↓ response
36+
Outbound Poller (poll inbox every 2s)
37+
↓
38+
Platform (formatted reply)
39+
```
40+
41+
## Agent Routing
42+
43+
All gateways support the `@AIM:agent-name` syntax to route messages to specific agents across the mesh network. Without a routing prefix, messages go to the configured default agent.
44+
45+
## Setup
46+
47+
Each gateway has its own `.env` (git-ignored) for configuration. See the `.env.example` in each gateway directory.
48+
49+
```bash
50+
cd <gateway>/
51+
npm install
52+
cp .env.example .env # Edit with your credentials
53+
npm start # Or: pm2 start ecosystem.config.cjs
54+
```

‎discord-gateway/.dockerignore‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
node_modules
2+
dist
3+
.env
4+
.env.*
5+
!.env.example
6+
.git
7+
.gitignore
8+
*.md
9+
credentials/
10+
credentials.yaml
11+
.github

‎discord-gateway/.env.example‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
# Discord Bot Configuration (required)
2+
DISCORD_BOT_TOKEN=your-discord-bot-token
3+
4+
# Gateway Configuration
5+
PORT=3023
6+
7+
# AI Maestro Configuration
8+
# AIMAESTRO_API=http://127.0.0.1:23000
9+
# DEFAULT_AGENT=my-agent
10+
# HOST_ID=my-host
11+
12+
# Security: Operator Discord user IDs (comma-separated, full trust - no content wrapping)
13+
# OPERATOR_DISCORD_IDS=000000000000000000
14+
15+
# Admin API token (required for config mutation endpoints)
16+
# ADMIN_TOKEN=your-admin-token
17+
18+
# Cache TTLs (milliseconds)
19+
# CACHE_AGENT_TTL_MS=300000
20+
# CACHE_HOSTS_TTL_MS=60000
21+
22+
# Polling
23+
# POLL_INTERVAL_MS=2000
24+
# POLL_TIMEOUT_MS=5000
25+
26+
# Development
27+
# DEBUG=true

‎discord-gateway/.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
node_modules/
2+
dist/
3+
.env
4+
.env.*
5+
!.env.example
6+
start-*.sh

‎discord-gateway/Dockerfile‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
FROM node:22-alpine AS deps
2+
3+
WORKDIR /app
4+
COPY package.json package-lock.json ./
5+
RUN npm ci
6+
7+
FROM deps AS build
8+
9+
COPY tsconfig.json ./
10+
COPY src ./src
11+
RUN npm run build
12+
13+
FROM node:22-alpine
14+
15+
RUN addgroup -S gateway && adduser -S gateway -G gateway
16+
17+
WORKDIR /app
18+
19+
COPY package.json package-lock.json ./
20+
RUN npm ci --production
21+
22+
COPY --from=build /app/dist ./dist
23+
24+
RUN chown -R gateway:gateway /app
25+
USER gateway
26+
27+
EXPOSE 3023
28+
CMD ["node", "dist/server.js"]

‎discord-gateway/README.md‎

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
# Discord Gateway
2+
3+
Discord connector for AI Maestro. Routes Discord messages (DMs and @mentions) to AI Maestro agents, and delivers agent responses back to Discord channels.
4+
5+
## Features
6+
7+
- DM handling (routes to default agent)
8+
- @mention detection in guild channels
9+
- `@AIM:agent-name` routing syntax for multi-agent support
10+
- Thread support
11+
- 2000-character message splitting for long responses
12+
- Typing indicators while waiting for agent responses
13+
- Content security (trust model + injection pattern scanning)
14+
- Management APIs (health, config, stats, activity log)
15+
- Admin token authentication
16+
17+
## Quick Start
18+
19+
```bash
20+
cp .env.example .env
21+
# Edit .env with your Discord bot token
22+
npm install
23+
npm run dev
24+
```
25+
26+
## Prerequisites
27+
28+
1. Create a Discord Application at https://discord.com/developers/applications
29+
2. Create a Bot and copy the token
30+
3. Enable **Message Content Intent** in Bot settings
31+
4. Invite the bot to your server with permissions: Send Messages, Read Messages, Add Reactions
32+
33+
## Configuration
34+
35+
See `.env.example` for all available environment variables.
36+
37+
## Message Flow
38+
39+
### Inbound (Discord → Agent)
40+
1. User sends DM or @mentions the bot
41+
2. Gateway applies content security (trust assessment + injection scanning)
42+
3. Message forwarded to AI Maestro with Discord context (channelId, messageId)
43+
4. Target agent receives the message
44+
45+
### Outbound (Agent → Discord)
46+
1. Agent sends response via AI Maestro
47+
2. Gateway polls inbox, picks up responses
48+
3. Replies sent to the originating Discord channel/thread
49+
4. Long responses split at 2000-character boundaries
50+
51+
## API Endpoints
52+
53+
| Endpoint | Method | Auth | Description |
54+
|----------|--------|------|-------------|
55+
| `/health` | GET | No | Health check with Discord connection status |
56+
| `/api/config` | GET | Yes | Current gateway configuration |
57+
| `/api/config/security` | PATCH | Yes | Update operator Discord IDs |
58+
| `/api/stats` | GET | Yes | Gateway metrics and uptime |
59+
| `/api/activity` | GET | Yes | Recent activity log |
60+
61+
## Running with pm2
62+
63+
```bash
64+
pm2 start ecosystem.config.cjs
65+
pm2 logs discord-gateway
66+
```

0 commit comments

Comments
 (0)