Swarm

src/swarm is the L3 External multi-agent layer — crews of teammate agents working a shared task board over a mailbox, optionally isolated in git worktrees. Imported as indusagi/swarm, or as the swarm namespace from indusagi.

A crew is a roster of teammate agents working a shared, dependency-aware board of tickets, talking over one cursor-based channel, with every coordination step narrated to an append-only activity log. The coordinator (Crew) ties four domain services — each a thin wrapper over a frozen kernel — plus an optional worktree isolation seam into one driveable object.

Table of Contents

• Public exports
• Sub-directories
• The coordinator
• Domain services and kernel
• Relationship to neighbors

Public exports

From src/swarm/index.ts:

Types: CrewOptions, CrewStatus, RoundOutcome, TaskDraft, SpawnAgent; CrewMember, CrewRecord, MemberDraft, CrewToolCollection; Ticket, TicketStatus, TicketDraft; Envelope, EnvelopeType, PayloadOf; WorktreeRef, WorktreeEntry, CreateOptions, RemoveOptions, ShellRunner, RunResult; CrewEvent, CrewEventKind, CrewEventInput; GuardOptions, TreeNode, SwarmFaultKind.

Sub-directories

The coordinator

A Crew owns no node:fs locking or coercion of its own — that lives in the kernel under the services. The coordinator adds the policy: matching ready tickets to idle members, spawning a teammate agent to work a ticket, and folding its result back onto the board and the channel. The agent spawner is injectable: by default defaultSpawnAgent backs a member with a real createAgent bound to the member's model and tool collection; tests pass a scripted fake (it need only implement the Agent handle's submit and snapshot).

Crew.runRound is the heartbeat: read the board's ready tickets and the idle members, pair them, and for each pair claim the ticket, spawn the member's agent, let it work, post a result envelope, complete or fail the ticket, and narrate every step to the activity log:

import { createCrew } from "indusagi/swarm";

const crew = await createCrew(/* CrewOptions */); // createCrew is async
const outcome = await crew.runRound();            // resolves a RoundOutcome

Domain services and kernel

The four services wrap the frozen kernel: CrewManifest is the roster (with a ModelPolicy for which model a member runs on); TicketBoard is the shared task store backed by a DepGraph so a ticket only becomes ready once its dependencies complete (ticketSchema / ticketStatuses define a ticket); Channel is the cursor-based mailbox of Envelopes (encode/decode, ENVELOPE_SCHEMA, ENVELOPE_TYPES); and ActivityLog is the append-only transcript of CrewEvents (CREW_EVENT_KINDS). Workspace adds optional per-teammate git-worktree isolation over a ShellRunner (nodeRunner is the real one). The kernel primitives — JsonCell (atomic JSON state), JsonlLog (append-only log), newId (ULID), and SwarmFault — are re-exported so a host can compose its own service over the same foundation.

Relationship to neighbors

Each teammate is a Runtime Agent built with createAgent and a Capabilities toolBox (CrewToolCollection selects which one). The swarm is a layer above the agent runtime: it orchestrates many agents rather than driving one model conversation.

Back to the Architecture overview.