agentctl-swarm 0.1.1

package/owl/constraints.md

@@ -0,0 +1,42 @@
+# constraints
+
+## isolation
+
+- each agent gets its own workspace directory: ~/dev/claude/<agent-id>/
+- agents must not access other agents' workspaces
+- agents must not access ~/.ssh, ~/.aws, ~/.config/gcloud, or other credential stores
+- the supervisor may mount specific secrets into agent workspaces via config (explicit opt-in)
+
+## identity
+
+- each agent gets a unique agentchat identity generated at spawn time
+- identities are stored in the agent's workspace: <workspace>/.agentchat/identities/<name>.json
+- agent names follow the pattern: swarm-<role>-<index> (e.g., swarm-builder-003)
+- identities are ephemeral by default — destroyed on swarm shutdown unless persist: true in config
+
+## resource limits
+
+- max concurrent active (promoted) agents is configurable, default 5
+- idle daemons have no resource cap (they burn minimal tokens)
+- per-agent memory limit is configurable, enforced via process group cgroups or ulimit
+- total swarm token budget is configurable — supervisor pauses promotions when budget threshold is reached
+
+## communication
+
+- all agents connect to the same agentchat server
+- agents join a configured work channel (default: #agents)
+- supervisor listens on #agents for status messages
+- agents must not send messages to channels outside their assigned list
+
+## process management
+
+- supervisor is the parent process of all daemons
+- daemons are child processes, not detached — they die if supervisor dies
+- supervisor writes a pidfile at ~/.agentctl/swarm.pid
+- only one swarm instance per machine (enforced via pidfile lock)
+
+## config location
+
+- swarm config file: ~/.agentctl/swarm.yaml (or AGENTCTL_SWARM_CONFIG env var)
+- per-agent overrides: ~/.agentctl/roles/<role-name>.yaml
+- config is read at startup and on SIGHUP (live reload)

package/owl/product.md

@@ -0,0 +1,23 @@
+# agentctl-swarm
+
+a supervisor for spawning, managing, and recovering fleets of AI agents that coordinate through agentchat.
+
+agentctl-swarm starts N lightweight daemon processes, each with its own workspace, agentchat identity, and role. daemons idle until a task is available, then promote to full claude code sessions to execute work. the supervisor monitors health, restarts crashed agents with backoff, and enforces resource limits.
+
+## components
+
+- [supervisor](components/supervisor.md) - spawns and monitors agent processes, handles lifecycle
+- [daemon](components/daemon.md) - lightweight idle listener that promotes to active agent on task claim
+- [spawner](components/spawner.md) - creates isolated workspaces and agent identities
+- [health-monitor](components/health-monitor.md) - heartbeat checks, crash detection, resource tracking
+
+## behaviors
+
+- [swarm-lifecycle](behaviors/swarm-lifecycle.md) - from spawn to shutdown
+- [promotion](behaviors/promotion.md) - daemon claims task and promotes to active builder
+- [recovery](behaviors/recovery.md) - handling crashes, quota exhaustion, and disconnects
+- [scaling](behaviors/scaling.md) - adding and removing agents from a running swarm
+
+## constraints
+
+see [constraints.md](constraints.md)

package/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "agentctl-swarm",
+  "version": "0.1.1",
+  "description": "Supervisor for spawning, managing, and recovering fleets of AI agents coordinated through agentchat",
+  "type": "module",
+  "main": "lib/index.js",
+  "scripts": {
+    "test": "node --test lib/*.test.js"
+  },
+  "keywords": ["agents", "swarm", "agentchat", "supervisor"],
+  "author": "James Couch",
+  "license": "MIT"
+}