@desplega.ai/agent-swarm 1.10.3 → 1.20.0

package/.claude/settings.local.json

@@ -24,7 +24,20 @@
       "WebFetch(domain:geminicli.com)",
       "Bash(bun run docs:mcp:*)",
       "Bash(bun test:*)",
-      "Bash(curl:*)"
+      "Bash(curl:*)",
+      "WebFetch(domain:github.com)",
+      "Bash(gh pr checks:*)",
+      "Bash(gh run view:*)",
+      "Bash(timeout 5 bun run:*)",
+      "Bash(bun run typecheck:*)",
+      "Bash(npx tsc:*)",
+      "WebFetch(domain:docs.github.com)",
+      "Bash(bun run lint:fix:*)",
+      "Skill(desplega:research)",
+      "Bash(bun run check:*)",
+      "Bash(bun build:*)",
+      "WebFetch(domain:www.npmjs.com)",
+      "Bash(sentry-cli:*)"
     ]
   },
   "enableAllProjectMcpServers": true,

package/.env.docker.example

@@ -31,3 +31,9 @@ SYSTEM_PROMPT_FILE=
 
 # For the agent exposed services (optional)
 SWARM_URL=swarm.example.com
+
+# Sentry Integration (optional - for issue investigation)
+# Create an Organization Auth Token at https://sentry.io/settings/{org}/auth-tokens/
+# Required scopes: event:read, project:read, org:read
+SENTRY_AUTH_TOKEN=
+SENTRY_ORG=

package/.env.example

@@ -19,8 +19,22 @@ SLACK_APP_TOKEN=xapp-...      # App-Level Token (for Socket Mode)
 SLACK_SIGNING_SECRET=...      # Signing Secret (optional for Socket Mode)
 SLACK_DISABLE=true            # Set to "true" to disable Slack integration
 
+# Slack User Filtering (optional - leave empty to allow all users)
+# SLACK_ALLOWED_EMAIL_DOMAINS=desplega.ai,partner.com  # Comma-separated email domains
+# SLACK_ALLOWED_USER_IDS=U12345678,U87654321           # Comma-separated Slack user IDs to always allow
+
 # App URL for Slack message links (e.g., https://your-dashboard.com)
 APP_URL=
 
 # Environment mode - set to "development" to add (dev) prefix to agent names in Slack
 ENV=
+
+# GitHub App Integration (optional)
+# GITHUB_DISABLE=true             # Set to skip GitHub integration
+GITHUB_WEBHOOK_SECRET=            # Webhook secret from GitHub App settings
+GITHUB_BOT_NAME=agent-swarm-bot   # Bot name for @mentions (default: agent-swarm-bot)
+GITHUB_APP_ID=                    # GitHub App ID (from app settings)
+GITHUB_APP_PRIVATE_KEY=           # Private key: raw PEM with \n escapes, OR base64-encoded
+
+# Scheduler configuration
+SCHEDULER_INTERVAL_MS=10000       # Polling interval for scheduled tasks (default: 10 seconds)

package/.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  lint-and-typecheck:
+    name: Lint and Type Check
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run Biome linter
+        run: bun run lint
+
+      - name: Run TypeScript type check
+        run: bun run tsc:check
+
+  test:
+    name: Run Tests
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Run tests
+        run: bun test
+
+  docker-build:
+    name: Docker Build Test
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+
+    strategy:
+      matrix:
+        dockerfile: [Dockerfile, Dockerfile.worker]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./${{ matrix.dockerfile }}
+          push: false
+          tags: test-image:latest

package/.github/workflows/{docker-publish.yml → docker-and-deploy.yml}

@@ -1,4 +1,4 @@
-name: Docker Build and Publish
+name: Docker Build + Publish + Deploy
 
 on:
   push:
@@ -50,6 +50,7 @@ jobs:
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          no-cache: true
 
   build-and-push-worker:
     runs-on: ubuntu-latest
@@ -90,3 +91,27 @@ jobs:
           push: true
           tags: ${{ steps.meta.outputs.tags }}
           labels: ${{ steps.meta.outputs.labels }}
+          no-cache: true
+
+  deploy:
+    name: Deploy
+    runs-on: ubuntu-latest
+
+    needs:
+      - build-and-push-server
+      - build-and-push-worker
+
+    steps:
+      - name: Checkout
+        id: checkout
+        uses: actions/checkout@v4
+
+      - name: Deploy Agent Swarm
+        uses: tarasyarema/dokploy-deploy-action@main
+        with:
+          deployment_type: compose
+          compose_id: h4or-knfw2HWkTzjLmrn8
+          compose_name: agent-swarm-nrz8v0
+          dokploy_url: https://app.dokploy.com
+          auth_token: ${{ secrets.DOKPLOY_TOKEN }}
+          wait_for_completion: true

package/.wts-config.json

@@ -0,0 +1,4 @@
+{
+  "autoTmux": true,
+  "setupScript": ".wts-setup.ts"
+}

package/.wts-setup.ts

@@ -0,0 +1,102 @@
+#!/usr/bin/env bun
+// wts setup script - runs after worktree creation
+//
+// Environment variables:
+//   WTS_WORKTREE_PATH - path to the new worktree (also the working directory)
+//   WTS_GIT_ROOT      - path to the main repository root
+
+import { exists, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { join, basename } from "node:path";
+
+const worktreePath = process.env.WTS_WORKTREE_PATH!;
+const gitRoot = process.env.WTS_GIT_ROOT!;
+const worktreeName = basename(worktreePath);
+
+console.log(`Setting up worktree "${worktreeName}" at ${worktreePath}...`);
+
+// Generate a unique port based on worktree index
+// Main repo uses 3013, worktrees use 3014+
+async function getUniquePort(): Promise<number> {
+  const basePort = 3013;
+  try {
+    // Count existing worktrees to determine port offset
+    const worktreesDir = join(gitRoot, ".worktrees");
+    if (await exists(worktreesDir)) {
+      const worktrees = await readdir(worktreesDir);
+      return basePort + worktrees.length;
+    }
+  } catch {
+    // Fallback: use a hash of the worktree name
+    let hash = 0;
+    for (const char of worktreeName) {
+      hash = ((hash << 5) - hash + char.charCodeAt(0)) | 0;
+    }
+    return basePort + 1 + (Math.abs(hash) % 100);
+  }
+  return basePort + 1;
+}
+
+const port = await getUniquePort();
+console.log(`Using port ${port} for this worktree`);
+
+// --- Copy and configure .env ---
+const mainEnv = join(gitRoot, ".env");
+const envExample = join(worktreePath, ".env.example");
+const targetEnv = join(worktreePath, ".env");
+
+if (await exists(mainEnv)) {
+  console.log("Copying .env from main repo...");
+  let envContent = await readFile(mainEnv, "utf-8");
+  // Update PORT to the unique port
+  envContent = envContent.replace(/^PORT=\d+/m, `PORT=${port}`);
+  await writeFile(targetEnv, envContent);
+} else if (await exists(envExample)) {
+  console.log("Creating .env from .env.example...");
+  let envContent = await readFile(envExample, "utf-8");
+  envContent = envContent.replace(/^PORT=\d+/m, `PORT=${port}`);
+  await writeFile(targetEnv, envContent);
+}
+
+// --- Copy and configure .mcp.json ---
+const mainMcp = join(gitRoot, ".mcp.json");
+const targetMcp = join(worktreePath, ".mcp.json");
+
+if (await exists(mainMcp)) {
+  console.log("Copying .mcp.json with updated port...");
+  let mcpContent = await readFile(mainMcp, "utf-8");
+  // Update the port in the MCP URL
+  mcpContent = mcpContent.replace(/localhost:\d+/g, `localhost:${port}`);
+  await writeFile(targetMcp, mcpContent);
+}
+
+// --- Copy .claude directory ---
+const mainClaude = join(gitRoot, ".claude");
+const targetClaude = join(worktreePath, ".claude");
+
+if (await exists(mainClaude)) {
+  console.log("Copying .claude directory...");
+  await mkdir(targetClaude, { recursive: true });
+  const files = await readdir(mainClaude);
+  for (const file of files) {
+    const content = await readFile(join(mainClaude, file));
+    await writeFile(join(targetClaude, file), content);
+  }
+}
+
+// --- Copy docker env files if they exist ---
+const dockerEnvFiles = [".env.docker", ".env.docker-lead"];
+for (const envFile of dockerEnvFiles) {
+  const mainDockerEnv = join(gitRoot, envFile);
+  const targetDockerEnv = join(worktreePath, envFile);
+  if (await exists(mainDockerEnv)) {
+    console.log(`Copying ${envFile}...`);
+    await Bun.$`cp ${mainDockerEnv} ${targetDockerEnv}`;
+  }
+}
+
+// --- Install dependencies ---
+console.log("Installing dependencies...");
+await Bun.$`bun install`;
+
+console.log(`\nSetup complete! Worktree running on port ${port}`);
+console.log(`Start the server with: bun run dev:http`);

package/CLAUDE.md

@@ -1,111 +1,104 @@
----
-description: Use Bun instead of Node.js, npm, pnpm, or vite.
-globs: "*.ts, *.tsx, *.html, *.css, *.js, *.jsx, package.json"
-alwaysApply: false
----
+# Agent Swarm MCP
 
-Default to using Bun instead of Node.js.
+Multi-agent orchestration layer for Claude Code, Codex, Gemini CLI. Enables task distribution, agent communication, and service discovery.
 
-- Use `bun <file>` instead of `node <file>` or `ts-node <file>`
-- Use `bun test` instead of `jest` or `vitest`
-- Use `bun build <file.html|file.ts|file.css>` instead of `webpack` or `esbuild`
-- Use `bun install` instead of `npm install` or `yarn install` or `pnpm install`
-- Use `bun run <script>` instead of `npm run <script>` or `yarn run <script>` or `pnpm run <script>`
-- Bun automatically loads .env, so don't use dotenv.
+**Getting Started**: See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup. Run `bun run start:http` to start the server.
 
-## APIs
+**Database**: Uses `bun:sqlite` (SQLite with WAL mode). DB file at `./agent-swarm-db.sqlite` (auto-created). Schema defined in `src/be/db.ts`.
 
-- `Bun.serve()` supports WebSockets, HTTPS, and routes. Don't use `express`.
-- `bun:sqlite` for SQLite. Don't use `better-sqlite3`.
-- `Bun.redis` for Redis. Don't use `ioredis`.
-- `Bun.sql` for Postgres. Don't use `pg` or `postgres.js`.
-- `WebSocket` is built-in. Don't use `ws`.
-- Prefer `Bun.file` over `node:fs`'s readFile/writeFile
-- Bun.$`ls` instead of execa.
+## Quick Reference
 
-## Testing
+```bash
+bun install               # Install dependencies
+bun run start:http        # Run MCP HTTP server (port 3013)
+bun run dev:http          # Dev with hot reload
+bun run lint:fix          # Lint & format with Biome
+bun run tsc:check         # Type check
 
-Use `bun test` to run tests.
+# PM2 (run API + UI + lead + worker together)
+bun run pm2-start         # Start all (API :3013, UI :5274, lead :3201, worker :3202)
+bun run pm2-stop          # Stop all services
+bun run pm2-restart       # Restart all services
+bun run pm2-logs          # View logs
+bun run pm2-status        # Check status
+# Note: lead/worker run in Docker. On code changes:
+# bun run docker:build:worker && bun run pm2-restart
+```
 
-```ts#index.test.ts
-import { test, expect } from "bun:test";
+## Tech Stack
 
-test("hello world", () => {
-  expect(1).toBe(1);
-});
-```
+- **Runtime**: Bun (not Node.js) - see Bun rules below
+- **Language**: TypeScript (strict mode)
+- **Linter/Formatter**: Biome (2-space indent, double quotes, 100 line width)
+- **MCP SDK**: @modelcontextprotocol/sdk
+- **CLI**: Ink (React for terminal)
+- **Slack**: @slack/bolt
 
-## Frontend
-
-Use HTML imports with `Bun.serve()`. Don't use `vite`. HTML imports fully support React, CSS, Tailwind.
-
-Server:
-
-```ts#index.ts
-import index from "./index.html"
-
-Bun.serve({
-  routes: {
-    "/": index,
-    "/api/users/:id": {
-      GET: (req) => {
-        return new Response(JSON.stringify({ id: req.params.id }));
-      },
-    },
-  },
-  // optional websocket support
-  websocket: {
-    open: (ws) => {
-      ws.send("Hello, world!");
-    },
-    message: (ws, message) => {
-      ws.send(message);
-    },
-    close: (ws) => {
-      // handle close
-    }
-  },
-  development: {
-    hmr: true,
-    console: true,
-  }
-})
+## Project Structure
+
+```
+src/
+  http.ts       # Main HTTP server + MCP endpoints
+  stdio.ts      # Stdio MCP transport
+  cli.tsx       # CLI entry point (Ink)
+  tools/        # MCP tool definitions
+  be/           # Backend utilities (DB, storage)
+  github/       # GitHub webhook handlers
+  slack/        # Slack integration
+ui/             # Dashboard (separate React app)
 ```
 
-HTML files can import .tsx, .jsx or .js files directly and Bun's bundler will transpile & bundle automatically. `<link>` tags can point to stylesheets and Bun's CSS bundler will bundle.
+## Code Style
 
-```html#index.html
-<html>
-  <body>
-    <h1>Hello, world!</h1>
-    <script type="module" src="./frontend.tsx"></script>
-  </body>
-</html>
-```
+- Run `bun run lint:fix` before committing (lint + format)
+- Run `bun run format` for formatting only
+- Use Bun APIs, not Node.js equivalents
+- Prefer `Bun.$` over execa for shell commands
 
-With the following `frontend.tsx`:
+## Related
 
-```tsx#frontend.tsx
-import React from "react";
+- [UI Dashboard](./ui/CLAUDE.md) - React monitoring dashboard
+- [MCP.md](./MCP.md) - MCP tools reference
+- [DEPLOYMENT.md](./DEPLOYMENT.md) - Production deployment
+- [CONTRIBUTING.md](./CONTRIBUTING.md) - Development setup
 
-// import .css files directly and it works
-import './index.css';
+---
 
-import { createRoot } from "react-dom/client";
+## Local Development
 
-const root = createRoot(document.body);
+**Environment Files:**
+- `.env` - Local dev config (API server, Slack, GitHub)
+- `.env.docker` - Docker worker config
 
-export default function Frontend() {
-  return <h1>Hello, world!</h1>;
-}
+**Testing API locally:**
+```bash
+# API_KEY from .env (default: 123123)
+curl -H "Authorization: Bearer 123123" http://localhost:3013/api/agents
 
-root.render(<Frontend />);
+# With agent ID header for MCP tools
+curl -H "Authorization: Bearer 123123" -H "X-Agent-ID: <uuid>" http://localhost:3013/mcp
 ```
 
-Then, run index.ts
+**Key env vars:**
+- `API_KEY` - Auth token for API requests
+- `MCP_BASE_URL` - API server URL (default: http://localhost:3013)
+- `SLACK_DISABLE=true` / `GITHUB_DISABLE=true` - Disable integrations locally
 
-```sh
-bun --hot ./index.ts
-```
+---
+
+## Bun Rules
+
+Use Bun instead of Node.js, npm, pnpm, or vite.
+
+- `bun <file>` instead of `node` or `ts-node`
+- `bun test` instead of jest/vitest
+- `bun install` instead of npm/yarn/pnpm install
+- `bun run <script>` instead of npm/yarn run
+- Bun auto-loads .env - don't use dotenv
+
+### Bun APIs
 
-For more information, read the Bun API docs in `node_modules/bun-types/docs/**.md`.
+- `Bun.serve()` for HTTP/WebSocket. Don't use express/ws.
+- `bun:sqlite` for SQLite. Don't use better-sqlite3.
+- `Bun.file()` over node:fs for file I/O.
+- `Bun.$` for shell commands. Don't use execa.