@desplega.ai/agent-swarm 1.49.0 → 1.52.0

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

@@ -1,87 +0,0 @@
-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

@@ -1,12 +0,0 @@
-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

@@ -1,24 +0,0 @@
-@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

@@ -1,34 +0,0 @@
-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

@@ -1,119 +0,0 @@
-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

@@ -1,11 +0,0 @@
-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

@@ -1,24 +0,0 @@
-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

@@ -1,8 +0,0 @@
-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

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

package/docs-site/app/robots.ts

@@ -1,13 +0,0 @@
-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

@@ -1,37 +0,0 @@
-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

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

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

@@ -1,7 +0,0 @@
-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

@@ -1,55 +0,0 @@
-"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

@@ -1,117 +0,0 @@
----
-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

@@ -1,77 +0,0 @@
----
-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