@desplega.ai/agent-swarm 1.20.0 → 1.49.0

package/docs-site/app/docs/[[...slug]]/page.tsx

@@ -0,0 +1,87 @@
+import { source } from "@/lib/source";
+import {
+  DocsPage,
+  DocsBody,
+  DocsTitle,
+  DocsDescription,
+} from "fumadocs-ui/layouts/docs/page";
+import { notFound } from "next/navigation";
+import { getMDXComponents } from "@/mdx-components";
+import type { Metadata } from "next";
+import type { MDXContent } from "mdx/types";
+import type { TOCItemType } from "fumadocs-core/toc";
+
+interface DocsPageData {
+  title: string;
+  description?: string;
+  body: MDXContent;
+  toc: TOCItemType[];
+  full?: boolean;
+}
+
+export default async function Page(props: {
+  params: Promise<{ slug?: string[] }>;
+}) {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  const data = page.data as unknown as DocsPageData;
+  const MDX = data.body;
+
+  return (
+    <DocsPage toc={data.toc} full={data.full}>
+      <DocsTitle>{data.title}</DocsTitle>
+      <DocsDescription>{data.description}</DocsDescription>
+      <DocsBody>
+        <MDX components={getMDXComponents()} />
+      </DocsBody>
+    </DocsPage>
+  );
+}
+
+export async function generateStaticParams() {
+  return source.generateParams();
+}
+
+export async function generateMetadata(props: {
+  params: Promise<{ slug?: string[] }>;
+}): Promise<Metadata> {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  const title = page.data.title;
+  const description = page.data.description;
+  const slug = params.slug?.join("/") ?? "";
+  const url = `https://docs.agent-swarm.dev/docs${slug ? `/${slug}` : ""}`;
+
+  return {
+    title,
+    description,
+    alternates: {
+      canonical: url,
+    },
+    openGraph: {
+      title: `${title} | Agent Swarm`,
+      description,
+      url,
+      siteName: "Agent Swarm Docs",
+      type: "article",
+      images: [
+        {
+          url: "https://agent-swarm.dev/og-image.png",
+          width: 1200,
+          height: 630,
+          alt: `${title} — Agent Swarm Documentation`,
+        },
+      ],
+    },
+    twitter: {
+      card: "summary_large_image",
+      title: `${title} | Agent Swarm`,
+      description,
+      images: ["https://agent-swarm.dev/og-image.png"],
+    },
+  };
+}

package/docs-site/app/docs/layout.tsx

@@ -0,0 +1,12 @@
+import { source } from "@/lib/source";
+import { DocsLayout } from "fumadocs-ui/layouts/docs";
+import type { ReactNode } from "react";
+import { baseOptions } from "@/app/layout.config";
+
+export default function Layout({ children }: { children: ReactNode }) {
+  return (
+    <DocsLayout tree={source.pageTree} {...baseOptions}>
+      {children}
+    </DocsLayout>
+  );
+}

package/docs-site/app/globals.css

@@ -0,0 +1,24 @@
+@import "tailwindcss";
+@import "fumadocs-ui/css/neutral.css";
+@import "fumadocs-ui/css/preset.css";
+@import "fumadocs-openapi/css/preset.css";
+
+@source "../node_modules/fumadocs-ui/dist/**/*.js";
+@source "../node_modules/fumadocs-openapi/dist/**/*.js";
+
+/* Amber accent colors — matching new-ui (Zinc base + amber primary) */
+@theme {
+  --color-fd-primary: oklch(0.555 0.163 48.998);
+  --color-fd-primary-foreground: oklch(0.985 0 0);
+  --color-fd-ring: oklch(0.555 0.163 48.998);
+  --color-fd-accent: oklch(0.967 0.001 286.375);
+  --color-fd-accent-foreground: oklch(0.21 0.006 285.885);
+}
+
+.dark {
+  --color-fd-primary: oklch(0.769 0.188 70.08);
+  --color-fd-primary-foreground: oklch(0.21 0.006 285.885);
+  --color-fd-ring: oklch(0.769 0.188 70.08);
+  --color-fd-accent: oklch(0.274 0.006 286.033);
+  --color-fd-accent-foreground: oklch(0.985 0 0);
+}

package/docs-site/app/layout.config.tsx

@@ -0,0 +1,34 @@
+import type { BaseLayoutProps } from "fumadocs-ui/layouts/shared";
+import Image from "next/image";
+
+export const baseOptions: BaseLayoutProps = {
+  nav: {
+    title: (
+      <>
+        <Image src="/logo.png" alt="Agent Swarm" width={28} height={28} />
+        Agent Swarm
+      </>
+    ),
+  },
+  links: [
+    {
+      text: "Docs",
+      url: "/docs",
+    },
+    {
+      text: "Templates",
+      url: "https://templates.agent-swarm.dev",
+      external: true,
+    },
+    {
+      text: "GitHub",
+      url: "https://github.com/desplega-ai/agent-swarm",
+      external: true,
+    },
+    {
+      text: "Discord",
+      url: "https://discord.gg/KZgfyyDVZa",
+      external: true,
+    },
+  ],
+};

package/docs-site/app/layout.tsx

@@ -0,0 +1,119 @@
+import { RootProvider } from "fumadocs-ui/provider/next";
+import type { ReactNode } from "react";
+import type { Metadata } from "next";
+import "./globals.css";
+
+export const metadata: Metadata = {
+  title: {
+    default: "Agent Swarm",
+    template: "%s | Agent Swarm",
+  },
+  description:
+    "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants.",
+  keywords: [
+    "agent swarm",
+    "documentation",
+    "multi-agent orchestration",
+    "claude code",
+    "codex",
+    "gemini cli",
+    "AI coding",
+    "MCP tools",
+    "task lifecycle",
+    "developer tools",
+  ],
+  metadataBase: new URL("https://docs.agent-swarm.dev"),
+  openGraph: {
+    title: "Agent Swarm Documentation",
+    description:
+      "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants.",
+    url: "https://docs.agent-swarm.dev",
+    siteName: "Agent Swarm Docs",
+    type: "website",
+    locale: "en_US",
+    images: [
+      {
+        url: "https://agent-swarm.dev/og-image.png",
+        width: 1200,
+        height: 630,
+        alt: "Agent Swarm",
+      },
+    ],
+  },
+  twitter: {
+    card: "summary_large_image",
+    title: "Agent Swarm Documentation",
+    description:
+      "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants.",
+    images: ["https://agent-swarm.dev/og-image.png"],
+  },
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <script
+          type="application/ld+json"
+          dangerouslySetInnerHTML={{
+            __html: JSON.stringify({
+              "@context": "https://schema.org",
+              "@graph": [
+                {
+                  "@type": "Organization",
+                  "@id": "https://agent-swarm.dev/#organization",
+                  name: "Agent Swarm",
+                  url: "https://agent-swarm.dev",
+                  logo: {
+                    "@type": "ImageObject",
+                    url: "https://agent-swarm.dev/logo.png",
+                  },
+                },
+                {
+                  "@type": "WebSite",
+                  "@id": "https://docs.agent-swarm.dev/#website",
+                  url: "https://docs.agent-swarm.dev",
+                  name: "Agent Swarm Documentation",
+                  publisher: {
+                    "@id": "https://agent-swarm.dev/#organization",
+                  },
+                },
+                {
+                  "@type": "TechArticle",
+                  name: "Agent Swarm Documentation",
+                  description:
+                    "Multi-agent orchestration for Claude Code, Codex, Gemini CLI, and other AI coding assistants.",
+                  url: "https://docs.agent-swarm.dev",
+                  mainEntity: {
+                    "@type": "SoftwareApplication",
+                    name: "Agent Swarm",
+                    applicationCategory: "DeveloperApplication",
+                    operatingSystem: "Linux, macOS",
+                  },
+                },
+              ],
+            }),
+          }}
+        />
+        <script
+          async
+          src="https://plausible.io/js/pa-N5qqdwlGhd8el6aPC8pJ7.js"
+        />
+        <script
+          dangerouslySetInnerHTML={{
+            __html: `window.plausible=window.plausible||function(){(plausible.q=plausible.q||[]).push(arguments)},plausible.init=plausible.init||function(i){plausible.o=i||{}};plausible.init()`,
+          }}
+        />
+      </head>
+      <body
+        style={{
+          display: "flex",
+          flexDirection: "column",
+          minHeight: "100vh",
+        }}
+      >
+        <RootProvider>{children}</RootProvider>
+      </body>
+    </html>
+  );
+}

package/docs-site/app/llms-full.txt/route.ts

@@ -0,0 +1,11 @@
+import { source } from "@/lib/source";
+import { getLLMText } from "@/lib/get-llm-text";
+
+export const revalidate = false;
+
+export async function GET() {
+  const scan = source.getPages().map(getLLMText);
+  const scanned = await Promise.all(scan);
+
+  return new Response(scanned.join("\n\n"));
+}

package/docs-site/app/llms.mdx/docs/[[...slug]]/route.ts

@@ -0,0 +1,24 @@
+import { getLLMText } from "@/lib/get-llm-text";
+import { source } from "@/lib/source";
+import { notFound } from "next/navigation";
+
+export const revalidate = false;
+
+export async function GET(
+  _req: Request,
+  { params }: { params: Promise<{ slug?: string[] }> },
+) {
+  const { slug } = await params;
+  const page = source.getPage(slug);
+  if (!page) notFound();
+
+  return new Response(await getLLMText(page), {
+    headers: {
+      "Content-Type": "text/markdown",
+    },
+  });
+}
+
+export function generateStaticParams() {
+  return source.generateParams();
+}

package/docs-site/app/llms.txt/route.ts

@@ -0,0 +1,8 @@
+import { source } from "@/lib/source";
+import { llms } from "fumadocs-core/source";
+
+export const revalidate = false;
+
+export function GET() {
+  return new Response(llms(source).index());
+}

package/docs-site/app/page.tsx

@@ -0,0 +1,5 @@
+import { redirect } from "next/navigation";
+
+export default function HomePage() {
+  redirect("/docs");
+}

package/docs-site/app/robots.ts

@@ -0,0 +1,13 @@
+import type { MetadataRoute } from "next";
+
+export default function robots(): MetadataRoute.Robots {
+  return {
+    rules: [
+      {
+        userAgent: "*",
+        allow: "/",
+      },
+    ],
+    sitemap: "https://docs.agent-swarm.dev/sitemap.xml",
+  };
+}

package/docs-site/app/sitemap.ts

@@ -0,0 +1,37 @@
+import type { MetadataRoute } from "next";
+
+export default function sitemap(): MetadataRoute.Sitemap {
+  const baseUrl = "https://docs.agent-swarm.dev";
+
+  const docPages = [
+    "/docs",
+    "/docs/getting-started",
+    "/docs/architecture/overview",
+    "/docs/architecture/agents",
+    "/docs/architecture/memory",
+    "/docs/architecture/hooks",
+    "/docs/concepts/task-lifecycle",
+    "/docs/concepts/epics",
+    "/docs/concepts/services",
+    "/docs/concepts/scheduling",
+    "/docs/concepts/workflows",
+    "/docs/guides/deployment",
+    "/docs/guides/slack-integration",
+    "/docs/guides/github-integration",
+    "/docs/guides/gitlab-integration",
+    "/docs/guides/agentmail-integration",
+    "/docs/guides/sentry-integration",
+    "/docs/guides/x402-payments",
+    "/docs/reference/mcp-tools",
+    "/docs/reference/environment-variables",
+    "/docs/reference/cli",
+    "/docs/contributing",
+  ];
+
+  return docPages.map((path) => ({
+    url: `${baseUrl}${path}`,
+    lastModified: new Date(),
+    changeFrequency: "weekly" as const,
+    priority: path === "/docs" ? 1 : 0.8,
+  }));
+}

package/docs-site/components/api-page.client.tsx

@@ -0,0 +1,4 @@
+"use client";
+import { defineClientConfig } from "fumadocs-openapi/ui/client";
+
+export default defineClientConfig({});

package/docs-site/components/api-page.tsx

@@ -0,0 +1,7 @@
+import { openapi } from "@/lib/openapi";
+import { createAPIPage } from "fumadocs-openapi/ui";
+import client from "./api-page.client";
+
+export const APIPage = createAPIPage(openapi, {
+  client,
+});

package/docs-site/components/mdx/mermaid.tsx

@@ -0,0 +1,55 @@
+"use client";
+
+import { use, useEffect, useId, useState } from "react";
+import { useTheme } from "next-themes";
+
+export function Mermaid({ chart }: { chart: string }) {
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    setMounted(true);
+  }, []);
+
+  if (!mounted) return null;
+  return <MermaidContent chart={chart} />;
+}
+
+const cache = new Map<string, Promise<unknown>>();
+
+function cachePromise<T>(key: string, setPromise: () => Promise<T>): Promise<T> {
+  const cached = cache.get(key);
+  if (cached) return cached as Promise<T>;
+
+  const promise = setPromise();
+  cache.set(key, promise);
+  return promise;
+}
+
+function MermaidContent({ chart }: { chart: string }) {
+  const id = useId();
+  const { resolvedTheme } = useTheme();
+  const { default: mermaid } = use(cachePromise("mermaid", () => import("mermaid")));
+
+  mermaid.initialize({
+    startOnLoad: false,
+    securityLevel: "loose",
+    fontFamily: "inherit",
+    themeCSS: "margin: 1.5rem auto 0;",
+    theme: resolvedTheme === "dark" ? "dark" : "default",
+  });
+
+  const { svg, bindFunctions } = use(
+    cachePromise(`${chart}-${resolvedTheme}`, () => {
+      return mermaid.render(id, chart.replaceAll("\\n", "\n"));
+    }),
+  );
+
+  return (
+    <div
+      ref={(container) => {
+        if (container) bindFunctions?.(container);
+      }}
+      dangerouslySetInnerHTML={{ __html: svg }}
+    />
+  );
+}

package/docs-site/content/docs/(documentation)/architecture/agents.mdx

@@ -0,0 +1,117 @@
+---
+title: Agent Identity & Configuration
+description: How agents are configured, personalized, and evolve over time
+---
+
+# Agent Identity & Configuration
+
+Every agent in the swarm is a persistent entity with its own identity, memories, and environment. This identity evolves over time as the agent works.
+
+## Identity Files
+
+Each agent has four identity files that persist across sessions:
+
+| File | Purpose | Example |
+|------|---------|---------|
+| **SOUL.md** | Core persona, values, behavioral directives | "You're not a chatbot. Be thorough. Own your mistakes." |
+| **IDENTITY.md** | Expertise, working style, track record | "I'm the coding arm of the swarm. I ship fast and clean." |
+| **TOOLS.md** | Environment knowledge — repos, services, APIs | "The API runs on port 3013. Use `wts` for worktree management." |
+| **CLAUDE.md** | Persistent notes and instructions | Learnings, preferences, important context |
+
+### How Identity Works
+
+1. **Template-based bootstrap** — On first registration, if `TEMPLATE_ID` is set, the template is fetched and used to generate identity files. Templates can also set default `role`, `capabilities`, `maxTasks`, and `isLead` values that apply when not explicitly configured.
+2. **Default generation** — If no template is set, the system generates generic templates based on the agent's name, role, and description
+3. **Self-editing** — Agents modify their own identity files during sessions. A PostToolUse hook syncs changes to the database in real-time
+4. **API / MCP tool** — Use the `update-profile` tool to programmatically set any identity field
+
+### Version History
+
+All identity file changes are tracked with version history. You can:
+- View past versions using the `context-history` MCP tool
+- Compare versions using the `context-diff` tool
+- Roll back to a previous version if needed
+
+## System Prompt Assembly
+
+The system prompt is built from multiple layers, assembled at task start:
+
+1. **Base role instructions** — Lead or worker-specific behavior rules
+2. **Agent identity** — SOUL.md + IDENTITY.md content
+3. **Repository context** — If the task targets a specific GitHub repo, that repo's CLAUDE.md is included
+4. **Filesystem guide** — Memory directories, personal/shared workspace, setup script instructions
+5. **Self-awareness** — How the agent is built (runtime, hooks, memory system, task lifecycle)
+6. **Additional prompt** — Custom text from `SYSTEM_PROMPT` env var or `--system-prompt` CLI flag
+
+## Startup Scripts
+
+Each agent has a startup script (`/workspace/start-up.sh`) that runs at every container start. Agents can modify this script to install tools, configure their environment, or set up workflows — and the changes persist across restarts.
+
+**Supported formats** (priority order):
+- `start-up.sh` / `start-up.bash` — Bash scripts
+- `start-up.js` — Node.js scripts
+- `start-up.ts` / `start-up.bun` — Bun/TypeScript scripts
+
+**Example: Install dependencies**
+
+```bash
+#!/bin/bash
+# /workspace/start-up.sh
+
+echo "Installing dependencies..."
+if [ -f "package.json" ]; then
+    bun install
+fi
+
+sudo apt-get update -qq
+sudo apt-get install -y -qq ripgrep
+```
+
+## Agent Workspace
+
+Each agent has access to:
+
+| Path | Description |
+|------|-------------|
+| `/workspace/personal/` | Agent's private workspace (isolated per agent) |
+| `/workspace/shared/` | Shared workspace between all agents |
+| `/workspace/personal/memory/` | Private searchable memory files |
+| `/workspace/shared/` | Read-only shared disk (all agents' directories visible) |
+| `/logs` | Session logs |
+
+### Agent Filesystem (agent-fs)
+
+When `AGENT_FS_API_URL` is configured as a global swarm config, agents gain access to **agent-fs** — a persistent, searchable filesystem shared across the swarm. Agent-fs provides:
+
+- **Personal and shared drives** — Each agent has a personal drive and access to a shared org drive
+- **Full-text and semantic search** — Search across all files with keyword or natural language queries
+- **Comments** — Human-agent collaboration via file comments
+- **CLI access** — The `agent-fs` CLI is pre-installed in worker containers and auto-configured on first boot
+
+Agents are automatically registered with agent-fs on their first container boot. The lead agent creates a shared organization and workers receive invitations automatically.
+
+## Lead vs Worker
+
+### Lead Agent
+
+- Receives incoming messages from Slack, GitHub, and email
+- Has an inbox for triaging messages
+- Can delegate tasks to workers
+- Can inject learnings into worker memories
+- Has access to all Slack channels
+- Creates and manages epics
+
+### Worker Agent
+
+- Executes assigned tasks
+- Reports progress via `store-progress`
+- Can expose HTTP services
+- Builds specialized expertise over time
+- Can claim tasks from the task pool
+- Can communicate with other agents via channels
+
+## Related
+
+- [Architecture Overview](/docs/architecture/overview) — How all the components fit together
+- [Hook System](/docs/architecture/hooks) — Hooks that sync identity files and manage sessions
+- [Memory System](/docs/architecture/memory) — How agents build compounding knowledge

package/docs-site/content/docs/(documentation)/architecture/hooks.mdx

@@ -0,0 +1,77 @@
+---
+title: Hook System
+description: The six hooks that fire during each Claude Code session
+---
+
+# Hook System
+
+Six hooks fire during each Claude Code session, providing safety, context management, and persistence. Hooks are implemented in `src/hooks/hook.ts`.
+
+## Hook Overview
+
+| Hook | When | What it does |
+|------|------|-------------|
+| **SessionStart** | Session begins | Writes CLAUDE.md from DB, loads concurrent session context for leads |
+| **PreCompact** | Before context compaction | Injects a "goal reminder" with current task details so the agent doesn't lose track |
+| **PreToolUse** | Before each tool call | Checks for task cancellation, detects tool loops, blocks excessive polling |
+| **PostToolUse** | After each tool call | Sends heartbeat, syncs identity file edits to DB, auto-indexes memory files |
+| **UserPromptSubmit** | New iteration starts | Checks for task cancellation |
+| **Stop** | Session ends | Cleans up artifact tunnels, saves PM2 state, syncs all identity files, runs session summarization, marks agent offline |
+
+## Hook Details
+
+### SessionStart
+
+Fires when a new Claude Code session begins. This hook:
+
+- Writes the agent's `CLAUDE.md` from the database to the filesystem
+- For lead agents, loads context about other concurrent sessions
+- Sets up the workspace environment
+
+### PreCompact
+
+Fires before Claude Code compacts its context window. This is critical for long-running tasks — without this hook, the agent might lose track of what it's working on after compaction.
+
+The hook injects the current task description and any saved progress as a "goal reminder" into the compacted context.
+
+### PreToolUse
+
+Fires before every tool call. This hook provides safety guardrails:
+
+- **Cancellation check** — If the task has been cancelled, the hook blocks the tool call and notifies the agent
+- **Loop detection** — Detects when the same tool is called with identical arguments repeatedly (a sign the agent is stuck)
+- **Polling limits** — Prevents excessive polling of external services
+- **Shared disk write prevention** — On Archil-mounted environments, warns agents before they attempt to write to another agent's directory under `/workspace/shared/`. Each agent can only write to its own subdirectory (`/workspace/shared/{category}/{agentId}/`)
+
+### PostToolUse
+
+Fires after every tool call. This is the most active hook:
+
+- **Heartbeat** — Sends a heartbeat to the MCP server so the lead knows the worker is alive
+- **Activity tracking** — Updates the agent's `lastActivityAt` timestamp (fire-and-forget) for stall detection
+- **Identity sync** — If an identity file (SOUL.md, IDENTITY.md, TOOLS.md, CLAUDE.md) was edited, syncs the changes to the database with `changeSource: "self_edit"` tracking to distinguish agent edits from session-end syncs
+- **Memory indexing** — If a file was written to a memory directory, automatically generates an embedding and indexes it
+- **Shared disk write failure detection** — On Archil-mounted environments, detects "Read-only file system" errors from Write, Edit, or Bash tools and warns the agent about the per-agent directory convention
+
+### UserPromptSubmit
+
+Fires when a new iteration of the agent loop begins (i.e., the agent receives a new prompt from the runner). This hook:
+
+- Checks for task cancellation
+- Can inject additional context if needed
+
+### Stop
+
+Fires when the session ends. This hook handles cleanup:
+
+- **Artifact cleanup** — Stops any active artifact tunnels (PM2 processes prefixed with `artifact-`)
+- **PM2 state** — Saves the current PM2 process list for auto-restart
+- **Identity sync** — Final sync of all identity files to the database
+- **Session summary** — Runs a lightweight model (Haiku) to extract key learnings from the session transcript
+- **Agent status** — Marks the agent as offline in the database
+
+## Related
+
+- [Memory System](/docs/architecture/memory) — How PostToolUse auto-indexes memory files
+- [Agent Identity & Configuration](/docs/architecture/agents) — Identity files synced by PostToolUse and Stop hooks
+- [Task Lifecycle](/docs/concepts/task-lifecycle) — Task states checked by PreToolUse cancellation detection