Swarm Orchestration Framework

This framework allows you to control a swarm of $N$ agents with isolated environments via file operations.

Setup

Run the bootstrap script to create the tmux session, spawn agents, and start the orchestrator:

cd swarm_framework
chmod +x bootstrap.sh
./bootstrap.sh <N>

Replace <N> with the desired number of agents (default is 4).

Isolation

Each agent runs in its own directory: swarm_framework/agents/agent_N/. This isolates their working directory and local state if they store it there.

Usage

Bootstrap: Run the bootstrap script to create the swarm environment and start the Master Agent.
```
./bootstrap.sh <number_of_agents>
```
Default is 4 agents if not specified. This script will start the Master Agent (jetski-cli) in the foreground. Exit the Master Agent (Ctrl+D or type exit) to stop the swarm and cleanup all resources.

Monitor: Open another terminal and attach to the tmux session to see sub-agents:
```
tmux attach -t jetski_swarm
```
Send Request: Drop JSON request files into comms/requests/.

Format:

{
  "request_id": "req_123",
  "target_agent": "agent_1",
  "prompt": "Hello",
  "response_file": "swarm_framework/comms/responses/res_123.json"
}

Note: The target_agent should be the window name (e.g., agent_1, agent_2).

Decentralized Cross-Agent Communication

For communication between sub-agents, a decentralized folder-based system is used in each agent's directory (agents/agent_N/):

incoming/: For receiving messages.
output/: For sending messages.
archive/: For archived messages.

Usage:

Drop a JSON file in agents/agent_source/output/ named to_{target}_{msg_id}.json.
The orchestrator will move it to agents/{target}/incoming/ and then to archive/, notifying the target agent.

This reduces load on the central orchestrator and provides a clear audit trail.

Communication Rules:

Atomicity Rule: You MUST write files to output/ with a .tmp extension first and then rename to .json when complete.
Payload Extraction Rule: Wrap your final answer in ===RESULT=== and ===END_RESULT=== markers to allow the system to extract the raw result and remove UI garbage.

Control Actions

You can control the swarm lifecycle by sending requests with type: "control".

Actions:

create: Spawn a new agent window and directory.
kill: Remove an agent window.
clear: Clear agent screen (visual).
resume: Resume a session by ID.

Examples:

Create Agent:

{
  "request_id": "req_create",
  "type": "control",
  "action": "create",
  "target_agent": "agent_new",
  "response_file": "swarm_framework/comms/responses/res_create.json"
}

Kill Agent:

{
  "request_id": "req_kill",
  "type": "control",
  "action": "kill",
  "target_agent": "agent_new",
  "response_file": "swarm_framework/comms/responses/res_kill.json"
}

Clear Screen:

{
  "request_id": "req_clear",
  "type": "control",
  "action": "clear",
  "target_agent": "agent_1",
  "response_file": "swarm_framework/comms/responses/res_clear.json"
}

Resume Session:

{
  "request_id": "req_resume",
  "type": "control",
  "action": "resume",
  "target_agent": "agent_1",
  "conversation_id": "CONV_ID_HERE",
  "response_file": "swarm_framework/comms/responses/res_resume.json"
}

Cleanup

To clear the CLI screen for a specific agent (visually cleaning up the window):

./clear_pane.sh <target_agent>

Example: ./clear_pane.sh agent_1

Note: This preserves the session ID and conversation history; it only clears the visual terminal display.

Components

bootstrap.sh: Initializes the environment.
orchestrator.py: The background polling script.
clear_pane.sh: Script to clear agent screen.
SKILL.md: The skill definition.
comms/: Communication directories.
agents/: Isolated working directories for agents.