feat: extract swarm_ai as standalone Hex-publishable package (#350)

Author: BlueHotDog

.changeset/extract-swarm-ai-package.md

@@ -0,0 +1,5 @@
+---
+"@frontman/frontman-core": patch
+---
+
+Extract Swarm agent execution framework from frontman_server into standalone swarm_ai Hex package. Rename all Swarm.* modules to SwarmAi.* and update telemetry atoms accordingly. frontman_server now depends on swarm_ai via path dep for monorepo development.

.github/workflows/changelog-check.yml

@@ -35,8 +35,8 @@ jobs:
             exit 0
           fi
 
-          # Check for direct CHANGELOG.md edit
-          if echo "$CHANGED" | grep -q '^CHANGELOG.md$'; then
+          # Check for direct CHANGELOG.md edit (root or per-package)
+          if echo "$CHANGED" | grep -q 'CHANGELOG.md$'; then
             echo "Found CHANGELOG.md update"
             exit 0
           fi

.github/workflows/ci.yml

@@ -453,6 +453,48 @@ jobs:
   # parallel for faster feedback.
   # ============================================================================
 
+  test-swarm-ai:
+    name: Test swarm_ai
+    runs-on: self-hosted
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install OpenSSL dev libraries
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y -qq libssl-dev libncurses5-dev
+
+      - name: Fix mise binary permissions
+        run: chmod -R +x ~/.local/share/mise/bin/ 2>/dev/null || true
+
+      # Uses mise.toml as single source of truth for Erlang/Elixir versions
+      - name: Setup Erlang/Elixir via mise
+        uses: jdx/mise-action@6d1e696aa24c1aa1bcc1adea0212707c71ab78a8 # v3.6.1
+        with:
+          install: true
+          cache: true
+
+      - name: Install dependencies
+        working-directory: apps/swarm_ai
+        run: |
+          rm -rf _build deps
+          mix deps.get
+
+      - name: Run tests
+        working-directory: apps/swarm_ai
+        run: mix test
+
+      - name: Validate Hex package
+        working-directory: apps/swarm_ai
+        run: mix hex.build --unpack
+
+      - name: Cleanup workspace
+        if: always()
+        run: |
+          rm -rf apps/swarm_ai/_build apps/swarm_ai/deps
+
+
   test-frontman-server:
     name: Test frontman-server
     runs-on: self-hosted
@@ -512,7 +554,7 @@ jobs:
         uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
         with:
           path: apps/frontman_server/_build
-          key: ${{ runner.os }}-build-${{ hashFiles('apps/frontman_server/mix.lock') }}
+          key: ${{ runner.os }}-build-${{ hashFiles('apps/frontman_server/mix.lock', 'apps/swarm_ai/lib/**') }}
           restore-keys: ${{ runner.os }}-build-
 
       - name: Install dependencies
@@ -576,7 +618,7 @@ jobs:
         uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
         with:
           path: apps/frontman_server/_build
-          key: ${{ runner.os }}-build-${{ hashFiles('apps/frontman_server/mix.lock') }}
+          key: ${{ runner.os }}-build-${{ hashFiles('apps/frontman_server/mix.lock', 'apps/swarm_ai/lib/**') }}
           restore-keys: ${{ runner.os }}-build-
 
       - name: Install dependencies
@@ -626,7 +668,7 @@ jobs:
         uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
         with:
           path: apps/frontman_server/_build
-          key: ${{ runner.os }}-build-${{ hashFiles('apps/frontman_server/mix.lock') }}
+          key: ${{ runner.os }}-build-${{ hashFiles('apps/frontman_server/mix.lock', 'apps/swarm_ai/lib/**') }}
           restore-keys: ${{ runner.os }}-build-
 
       # PLT cache includes mise.toml hash to invalidate when Erlang/Elixir versions change

.github/workflows/deploy.yml

@@ -6,6 +6,7 @@ on:
       - main
     paths:
       - 'apps/frontman_server/**'
+      - 'apps/swarm_ai/**'
       - 'libs/**'
       - 'rescript.json'
       - 'mise.toml'

.github/workflows/release-pr.yml

@@ -99,7 +99,13 @@ jobs:
             [ -f "$changelog" ] || continue
             if git status --porcelain -- "$changelog" | grep -q .; then
               PKG_DIR=$(dirname "$changelog")
-              PKG_NAME=$(node -e "console.log(require('./${PKG_DIR}/package.json').name)" 2>/dev/null || echo "$(basename "$PKG_DIR")")
+              if [ -f "${PKG_DIR}/package.json" ]; then
+                PKG_NAME=$(node -e "console.log(require('./${PKG_DIR}/package.json').name)")
+              elif [ -f "${PKG_DIR}/mix.exs" ]; then
+                PKG_NAME=$(sed -n 's/.*app: :\([a-z_]*\).*/\1/p' "${PKG_DIR}/mix.exs" | head -1)
+              else
+                PKG_NAME=$(basename "$PKG_DIR")
+              fi
               SECTION=$(awk '/^## /{if(found) exit; found=1; next} found' "$changelog")
               if [ -n "$SECTION" ]; then
                 CHANGES="${CHANGES}"$'\n\n'"#### ${PKG_NAME}"$'\n\n'"${SECTION}"

Makefile

@@ -28,7 +28,7 @@ endef
         ssl-setup tunnel \
         worktree-create worktree-create-from worktree-list worktree-remove worktree-clean \
         worktree-status worktree-devpod worktree-urls worktree-hosts worktree-register worktree-registry \
-        publish publish-astro publish-vite publish-nextjs release \
+        publish publish-astro publish-vite publish-nextjs publish-swarm-ai release \
         kill-all-processes open-dogfooding pull-webapi
 
 help: ## Display available commands
@@ -324,6 +324,9 @@ publish-vite: ## Publish @frontman-ai/vite to npm (pass OTP=<code> for 2FA)
 publish-nextjs: ## Publish @frontman-ai/nextjs to npm (pass OTP=<code> for 2FA)
 	cd libs/frontman-nextjs && $(MAKE) publish OTP=$(OTP)
 
+publish-swarm-ai: ## Publish swarm_ai to Hex (dry run by default, HEX_PUBLISH=1 for real)
+	cd apps/swarm_ai && $(MAKE) hex-publish HEX_PUBLISH=$(HEX_PUBLISH)
+
 release: ## Create a release PR from pending changesets
 	@printf "$(CYAN)Checking release prerequisites...$(RESET)\n"
 	@git fetch origin main --quiet

apps/frontman_server/lib/frontman_server/agents.ex

@@ -25,8 +25,8 @@ defmodule FrontmanServer.Agents do
   alias FrontmanServer.Providers
   alias FrontmanServer.Providers.ResolvedKey
   alias FrontmanServer.Tasks
-  alias Swarm.LLM.Chunk
-  alias Swarm.Message
+  alias SwarmAi.LLM.Chunk
+  alias SwarmAi.Message
 
   @doc """
   Checks if an agent is currently running for the given task.
@@ -74,7 +74,7 @@ defmodule FrontmanServer.Agents do
   - `:tools` - List of tool definitions for LLM (default: [])
   - `:model` - LLM model spec (defaults to provider default)
   - `:env_api_key` - Map of provider => api_key from client's environment
-  - `:agent` - Custom agent struct implementing Swarm.Agent (for testing)
+  - `:agent` - Custom agent struct implementing SwarmAi.Agent (for testing)
 
   ## Returns
   - `{:ok, pid}` - Agent started successfully
@@ -116,7 +116,7 @@ defmodule FrontmanServer.Agents do
   # Dialyzer warning suppressed: the anonymous function calls execute_agent which
   # has the same protocol dispatch issue. See execute_agent comment for details.
   @dialyzer {:nowarn_function, run_agent: 5}
-  @spec run_agent(Scope.t(), Swarm.Agent.t(), String.t(), [Message.t()], keyword()) ::
+  @spec run_agent(Scope.t(), SwarmAi.Agent.t(), String.t(), [Message.t()], keyword()) ::
           {:ok, pid()} | {:error, term()}
   defp run_agent(scope, agent, task_id, messages, opts) do
     on_event = Keyword.fetch!(opts, :on_event)
@@ -204,7 +204,7 @@ defmodule FrontmanServer.Agents do
     case Registry.lookup(FrontmanServer.AgentRegistry, {:tool_call, tool_call_id}) do
       [{_pid, %{caller_pid: caller}}] ->
         # MCP tool - send result to waiting executor
-        # Encode non-string results since Swarm.Message.ContentPart.text/1 requires strings
+        # Encode non-string results since SwarmAi.Message.ContentPart.text/1 requires strings
         encoded = encode_result_for_swarm(result)
         send(caller, {:tool_result, tool_call_id, encoded, is_error})
         :ok
@@ -223,7 +223,7 @@ defmodule FrontmanServer.Agents do
 
   ## Options
   - `:tools` - List of tool definitions for LLM (default: [])
-  - `:agent` - Custom agent struct implementing Swarm.Agent (for testing)
+  - `:agent` - Custom agent struct implementing SwarmAi.Agent (for testing)
   """
   @spec notify_user_message(Scope.t(), String.t(), list(FrontmanServer.Tools.MCP.t()), keyword()) ::
           :ok
@@ -423,7 +423,7 @@ defmodule FrontmanServer.Agents do
 
   defp to_swarm_tool_calls(tool_calls) do
     Enum.map(tool_calls, fn tc ->
-      %Swarm.ToolCall{
+      %SwarmAi.ToolCall{
         id: tc.id,
         name: ReqLLM.ToolCall.name(tc),
         arguments: ReqLLM.ToolCall.args_json(tc)
@@ -442,7 +442,7 @@ defmodule FrontmanServer.Agents do
     Phoenix.PubSub.broadcast(FrontmanServer.PubSub, Tasks.topic(task_id), message)
   end
 
-  # Encode non-string results to JSON for Swarm.Message.ContentPart.text/1
+  # Encode non-string results to JSON for SwarmAi.Message.ContentPart.text/1
   defp encode_result_for_swarm(value) when is_binary(value), do: value
   defp encode_result_for_swarm(value), do: Jason.encode!(value)
 
@@ -476,7 +476,7 @@ defmodule FrontmanServer.Agents do
     tool_executor =
       ToolExecutor.make_executor(scope, task_id, mcp_tools: mcp_tools, llm_opts: llm_opts)
 
-    Logger.info("Starting agent execution for task #{task_id} via Swarm.run_streaming")
+    Logger.info("Starting agent execution for task #{task_id} via SwarmAi.run_streaming")
 
     # Emit task start telemetry - creates the root OTEL span for this task
     TelemetryEvents.task_start(task_id)
@@ -485,7 +485,7 @@ defmodule FrontmanServer.Agents do
     # Pass task_id in metadata for telemetry correlation.
     # Swarm returns loop_id for execution identification and crash reporting.
     result =
-      Swarm.run_streaming(agent, messages,
+      SwarmAi.run_streaming(agent, messages,
         metadata: %{task_id: task_id},
         tool_executor: tool_executor,
         on_chunk: &handle_stream_chunk(&1, on_event),
@@ -538,7 +538,7 @@ defmodule FrontmanServer.Agents do
     end
   end
 
-  defp build_response_metadata(%Swarm.LLM.Response{} = response) do
+  defp build_response_metadata(%SwarmAi.LLM.Response{} = response) do
     metadata = %{}
 
     metadata =
@@ -558,7 +558,7 @@ defmodule FrontmanServer.Agents do
     metadata
   end
 
-  defp to_reqllm_tool_call(%Swarm.ToolCall{} = tc) do
+  defp to_reqllm_tool_call(%SwarmAi.ToolCall{} = tc) do
     ReqLLM.ToolCall.new(tc.id, tc.name, tc.arguments)
   end
 end

apps/frontman_server/lib/frontman_server/agents/llm_client.ex

@@ -1,6 +1,6 @@
 defmodule FrontmanServer.Agents.LLMClient do
   @moduledoc """
-  Swarm.LLM implementation using ReqLLM.
+  SwarmAi.LLM implementation using ReqLLM.
 
   Stream-first design: returns a lazy stream of chunks that can be
   consumed with callbacks or collected into a Response.
@@ -17,7 +17,7 @@ defmodule FrontmanServer.Agents.LLMClient do
 
   typedstruct do
     field(:model, String.t(), default: @default_model)
-    field(:tools, [Swarm.Tool.t()], default: [])
+    field(:tools, [SwarmAi.Tool.t()], default: [])
     # llm_opts must include :api_key (resolved at domain layer)
     field(:llm_opts, keyword(), default: [])
   end
@@ -33,21 +33,21 @@ defmodule FrontmanServer.Agents.LLMClient do
   ## Options
 
   - `:model` - Model spec string (default: "openrouter:openai/gpt-5.1-codex")
-  - `:tools` - List of Swarm.Tool structs
+  - `:tools` - List of SwarmAi.Tool structs
   - `:llm_opts` - Options for ReqLLM, must include `:api_key`
   """
   def new(opts \\ []) do
     struct!(__MODULE__, opts)
   end
 
   @doc """
-  Converts Swarm.Tool to ReqLLM.Tool format.
+  Converts SwarmAi.Tool to ReqLLM.Tool format.
   Normalizes schemas for OpenAI-compatible providers that require strict mode.
 
   When `requires_mcp_prefix: true` is passed in opts, tool names are prefixed with `mcp_`.
   """
-  @spec to_reqllm_tool(Swarm.Tool.t(), String.t(), keyword()) :: ReqLLM.Tool.t()
-  def to_reqllm_tool(%Swarm.Tool{} = tool, model, opts \\ []) do
+  @spec to_reqllm_tool(SwarmAi.Tool.t(), String.t(), keyword()) :: ReqLLM.Tool.t()
+  def to_reqllm_tool(%SwarmAi.Tool{} = tool, model, opts \\ []) do
     provider = SchemaTransformer.provider_for_model(model)
     schema = SchemaTransformer.transform(tool.parameter_schema, provider)
     strict? = provider == :openai_strict
@@ -79,12 +79,12 @@ defmodule FrontmanServer.Agents.LLMClient do
   def strip_mcp_prefix(name), do: name
 end
 
-defimpl Swarm.LLM, for: FrontmanServer.Agents.LLMClient do
+defimpl SwarmAi.LLM, for: FrontmanServer.Agents.LLMClient do
   alias FrontmanServer.Agents.{LLMClient, SchemaTransformer}
-  alias Swarm.LLM.{Chunk, Usage}
-  alias Swarm.Message
-  alias Swarm.Message.ContentPart
-  alias Swarm.ToolCall
+  alias SwarmAi.LLM.{Chunk, Usage}
+  alias SwarmAi.Message
+  alias SwarmAi.Message.ContentPart
+  alias SwarmAi.ToolCall
 
   require Logger
 
@@ -277,7 +277,7 @@ defimpl Swarm.LLM, for: FrontmanServer.Agents.LLMClient do
     end)
   end
 
-  # --- Swarm.Message -> ReqLLM.Message conversion ---
+  # --- SwarmAi.Message -> ReqLLM.Message conversion ---
 
   defp to_reqllm_message(%Message{} = msg, requires_mcp_prefix?) do
     %ReqLLM.Message{

apps/frontman_server/lib/frontman_server/agents/root_agent.ex

@@ -3,7 +3,7 @@ defmodule FrontmanServer.Agents.RootAgent do
   The main coordinating agent that handles user requests.
 
   This agent receives user messages, can use tools (including spawning sub-agents),
-  and coordinates the overall task execution. It implements the Swarm.Agent protocol
+  and coordinates the overall task execution. It implements the SwarmAi.Agent protocol
   directly, owning its system prompt generation logic.
 
   The system prompt is dynamically built based on context:
@@ -19,7 +19,7 @@ defmodule FrontmanServer.Agents.RootAgent do
   alias FrontmanServer.Agents.{LLMClient, Prompts}
 
   typedstruct do
-    field(:tools, [Swarm.Tool.t()], default: [])
+    field(:tools, [SwarmAi.Tool.t()], default: [])
     field(:has_selected_component, boolean(), default: false)
     field(:has_current_page, boolean(), default: false)
     field(:has_typescript_react, boolean(), default: false)
@@ -37,7 +37,7 @@ defmodule FrontmanServer.Agents.RootAgent do
 
   ## Options
 
-  - `:tools` - List of Swarm.Tool structs available to the agent
+  - `:tools` - List of SwarmAi.Tool structs available to the agent
   - `:has_selected_component` - Whether a component is selected in the codebase
   - `:has_current_page` - Whether current page context is available
   - `:framework` - Framework name (e.g., "nextjs") for framework-specific guidance
@@ -61,7 +61,7 @@ defmodule FrontmanServer.Agents.RootAgent do
   end
 end
 
-defimpl Swarm.Agent, for: FrontmanServer.Agents.RootAgent do
+defimpl SwarmAi.Agent, for: FrontmanServer.Agents.RootAgent do
   alias FrontmanServer.Agents.{LLMClient, Prompts, RootAgent}
 
   def system_prompt(%RootAgent{} = agent) do