@desplega.ai/agent-swarm 1.2.1 → 1.9.0

package/.claude/settings.local.json

@@ -3,7 +3,26 @@
     "allow": [
       "mcp__agent-swarm__*",
       "Bash(bun run tsc:*)",
-      "Bash(docker build:*)"
+      "Bash(docker build:*)",
+      "Skill(frontend-design:frontend-design)",
+      "Bash(gh repo view:*)",
+      "WebSearch",
+      "WebFetch(domain:www.claude.com)",
+      "WebFetch(domain:simonwillison.net)",
+      "WebFetch(domain:deepwiki.com)",
+      "WebFetch(domain:docs.claude.com)",
+      "Bash(bun run tsc:check:*)",
+      "Bash(bun tsc:*)",
+      "Bash(bun run lint:*)",
+      "Bash(bun run format:*)",
+      "Bash(sqlite3:*)",
+      "Bash(cat:*)",
+      "mcp__context7__resolve-library-id",
+      "mcp__context7__get-library-docs",
+      "Bash(bun run build:*)",
+      "Bash(pnpm run build:*)",
+      "WebFetch(domain:geminicli.com)",
+      "Bash(bun run docs:mcp:*)"
     ]
   },
   "enableAllProjectMcpServers": true,

package/.env.docker.example

@@ -2,11 +2,32 @@
 # Copy this file to .env.docker and fill in your values
 
 # Required
+# Run `claude setup-token` to get your OAuth token
 CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token-here
 API_KEY=your-api-key-here
 
 # Optional (auto-generated if not provided)
 AGENT_ID=
 MCP_BASE_URL=http://host.docker.internal:3013
+
+# Service Registry (PM2 background services)
+# Port mapping for exposed services (default: 3000)
+SERVICE_PORT=3000
+
+# To re-use an existing session, set SESSION_ID to the desired value
+# Will be used for log directory paths
 SESSION_ID=
-WORKER_YOLO=false
+
+# If true, enables YOLO mode for the agent (default: false)
+# which will keep spawning claudes even if an iteration fails
+YOLO=false
+
+# If true, the worker will exit if the startup script fails (default: true)
+STARTUP_SCRIPT_STRICT=true
+
+# System Prompt (optional - customize agent behavior)
+SYSTEM_PROMPT=
+SYSTEM_PROMPT_FILE=
+
+# For the agent exposed services (optional)
+SWARM_URL=swarm.example.com

package/.env.example

@@ -4,6 +4,23 @@ API_KEY=
 # Server port (default: 3013)
 PORT=3013
 
+# Swarm URL for service discovery (e.g., swarm.example.com)
+# Services are accessible at https://{AGENT_ID}.{SWARM_URL}
+SWARM_URL=localhost
+
 # MCP Base URL for remote server (used by setup command)
 # Default: https://agent-swarm-mcp.desplega.sh
 MCP_BASE_URL=
+
+# Slack Bot Configuration (Socket Mode)
+# Get these from https://api.slack.com/apps
+SLACK_BOT_TOKEN=xoxb-...      # Bot User OAuth Token
+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
+
+# 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=

package/.github/workflows/docker-publish.yml

@@ -0,0 +1,92 @@
+name: Docker Build and Publish
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push-server:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Get version from package.json
+        id: version
+        run: echo "version=$(jq -r '.version' package.json)" >> $GITHUB_OUTPUT
+
+      - name: Log in to Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels)
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=raw,value=latest
+            type=raw,value=${{ steps.version.outputs.version }}
+            type=sha
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./Dockerfile
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+
+  build-and-push-worker:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Get version from package.json
+        id: version
+        run: echo "version=$(jq -r '.version' package.json)" >> $GITHUB_OUTPUT
+
+      - name: Log in to Container Registry
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels)
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}-worker
+          tags: |
+            type=raw,value=latest
+            type=raw,value=${{ steps.version.outputs.version }}
+            type=sha
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./Dockerfile.worker
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

package/CONTRIBUTING.md

@@ -0,0 +1,270 @@
+# Contributing to Agent Swarm
+
+Thanks for your interest in contributing to Agent Swarm MCP!
+
+## Table of Contents
+
+- [Development Setup](#development-setup)
+- [Running the Project](#running-the-project)
+- [Code Quality](#code-quality)
+- [Building](#building)
+- [Project Structure](#project-structure)
+- [Adding New Tools](#adding-new-tools)
+
+---
+
+## Development Setup
+
+### Prerequisites
+
+- [Bun](https://bun.sh) (recommended) or Node.js 22+
+- Git
+
+### Install Dependencies
+
+```bash
+git clone https://github.com/desplega-ai/agent-swarm.git
+cd agent-swarm
+bun install
+```
+
+### Environment Setup
+
+```bash
+cp .env.docker.example .env
+# Edit .env with your API_KEY
+```
+
+---
+
+## Running the Project
+
+### MCP Server
+
+```bash
+# STDIO transport (for local testing)
+bun run start
+
+# HTTP transport (for production)
+bun run start:http
+
+# With hot reload
+bun run dev      # STDIO
+bun run dev:http # HTTP
+```
+
+### MCP Inspector
+
+Debug and test MCP tools interactively:
+
+```bash
+bun run inspector:http # HTTP transport
+```
+
+### CLI Commands
+
+```bash
+# Run CLI locally
+bun run cli setup
+bun run cli setup --dry-run
+
+# Run worker/lead
+bun run worker
+bun run lead
+
+# Hook handler
+bun run hook
+```
+
+### Docker Worker
+
+```bash
+# Build worker image
+bun run docker:build:worker
+
+# Run worker container
+bun run docker:run:worker
+
+# Run lead container
+bun run docker:run:lead
+```
+
+---
+
+## Code Quality
+
+### Linting
+
+```bash
+# Check for issues
+bun run lint
+
+# Fix issues automatically
+bun run lint:fix
+```
+
+### Formatting
+
+```bash
+bun run format
+```
+
+### Type Checking
+
+```bash
+bun run tsc:check
+```
+
+### Pre-commit
+
+Run all checks before committing:
+
+```bash
+bun run lint && bun run tsc:check
+```
+
+---
+
+## Building
+
+### Binary Builds
+
+Create standalone binaries for Linux:
+
+```bash
+# x64
+bun run build:binary
+
+# ARM64
+bun run build:binary:arm64
+```
+
+Output: `./dist/agent-swarm`
+
+### Docker Images
+
+```bash
+# Build worker image
+bun run docker:build:worker
+
+# Push to registry (maintainers only)
+bun run deploy:docker
+```
+
+---
+
+## Project Structure
+
+```
+agent-swarm/
+├── src/
+│   ├── cli.tsx          # CLI entry point (Ink/React)
+│   ├── http.ts          # HTTP server entry
+│   ├── server.ts        # MCP server setup & tool registration
+│   ├── tools/           # MCP tool implementations
+│   │   ├── join-swarm.ts
+│   │   ├── poll-task.ts
+│   │   ├── send-task.ts
+│   │   └── ...
+│   ├── be/              # Backend (database, business logic)
+│   │   └── db.ts        # SQLite database
+│   ├── commands/        # CLI command implementations
+│   │   ├── worker.ts
+│   │   ├── lead.ts
+│   │   └── ...
+│   └── hooks/           # Claude Code hooks
+├── deploy/              # Deployment scripts
+├── scripts/             # Utility scripts
+├── docker-compose.example.yml
+├── Dockerfile           # API server image
+├── Dockerfile.worker    # Worker image
+└── package.json
+```
+
+---
+
+## Adding New Tools
+
+### 1. Create Tool File
+
+Create `src/tools/my-tool.ts`:
+
+```typescript
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import * as z from "zod";
+import { createToolRegistrar } from "@/tools/utils";
+
+export const registerMyTool = (server: McpServer) => {
+  createToolRegistrar(server)(
+    "my-tool",
+    {
+      title: "My Tool",
+      description: "What this tool does.",
+      inputSchema: z.object({
+        param1: z.string().describe("Parameter description"),
+        param2: z.number().optional().describe("Optional parameter"),
+      }),
+      outputSchema: z.object({
+        success: z.boolean(),
+        message: z.string(),
+      }),
+    },
+    async ({ param1, param2 }, requestInfo, _meta) => {
+      // requestInfo.agentId - caller's agent ID
+      // requestInfo.sessionId - session ID
+
+      // Your implementation here
+
+      return {
+        content: [{ type: "text", text: "Result message" }],
+        structuredContent: {
+          success: true,
+          message: "Result message",
+        },
+      };
+    },
+  );
+};
+```
+
+### 2. Register in Server
+
+Edit `src/server.ts`:
+
+```typescript
+import { registerMyTool } from "./tools/my-tool";
+
+export function createServer() {
+  // ...existing code...
+
+  // Register under appropriate capability
+  if (hasCapability("my-capability")) {
+    registerMyTool(server);
+  }
+
+  return server;
+}
+```
+
+### 3. Update Documentation
+
+```bash
+bun run docs:mcp
+```
+
+---
+
+## Coding Guidelines
+
+See [CLAUDE.md](./CLAUDE.md) for:
+
+- Bun-specific APIs and patterns
+- Testing conventions
+- Frontend development with HTML imports
+
+### Key Points
+
+- Use Bun instead of Node.js (`bun run`, `Bun.serve()`, `bun:sqlite`)
+- Use Zod for schema validation
+- Return both `content` (text) and `structuredContent` (JSON) from tools
+- Group tools by capability (core, task-pool, messaging, profiles, services)