swarm

1# Swarm
2 
3Process many independent items in parallel. `create` builds a table handle;
4`run` fans work out across rows and merges results back. One row = one unit
5of work — swarm handles batching automatically.
6 
7## Flow
8 
91. **Create.** Build a table from a source — files, a glob pattern, or
10   pre-parsed records. One row per item. Returns a handle.
112. **Run.** Dispatch an `instruction` template across rows. Results are merged
12   back into the table. Returns `{ completed, failed, skipped, failures }`.
133. **Aggregate.** Use `rows()` and plain JS to count, filter, or summarize.
14   Do not spawn additional subagents for aggregation.
154. **Retry.** Re-run with `filter: { column: "<col>", exists: false }` to
16   reprocess only failed rows.
17 
18## Choosing a source
19 
20**`glob` / `filePaths`** — one file = one row. Use when each file is an
21independent unit of work. Each row gets `{ id, file }`; the subagent reads
22the file itself via the `{file}` placeholder.
23 
24**`tasks`** — pass pre-built records directly. Use when the data lives inside
25a file (JSONL, CSV, JSON array). Read and parse the file first inside
26`eval`, then pass the records. One record = one row — do not group
27multiple items into a single row.
28 
29For small files (under ~500 lines), parse and create in one block:
30 
31```javascript
32const { create } = await import("@/skills/swarm");
33const raw = await tools.readFile({ file_path: "/data.jsonl" });
34const records = raw.trim().split("\n").map(l => JSON.parse(l));
35…