# 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:

```bash
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

1. **Bootstrap**: Run the bootstrap script to create the swarm environment and start the Master Agent.
   ```bash
   ./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.


2. **Monitor**: Open another terminal and attach to the tmux session to see sub-agents:
   ```bash
   tmux attach -t jetski_swarm
   ```

3. **Send Request**: Drop JSON request files into `comms/requests/`.


**Format:**
```json
{
  "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`).

## 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:**
```json
{
  "request_id": "req_create",
  "type": "control",
  "action": "create",
  "target_agent": "agent_new",
  "response_file": "swarm_framework/comms/responses/res_create.json"
}
```

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

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

**Resume Session:**
```json
{
  "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):

```bash
./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.