# 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`).

## 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:**
1. Drop a JSON file in `agents/agent_source/output/` named `to_{target}_{msg_id}.json`.
2. 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:**
```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.

