@ifi/oh-pi-ant-colony 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Ifiok Jr.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,119 @@
+# 🐜 Ant Colony — Multi-Agent Swarm Extension
+
+> A self-organizing multi-agent system modeled after real ant colony ecology. Adaptive concurrency,
+> pheromone communication, zero centralized scheduling.
+
+## Architecture
+
+```
+Queen                           Main pi process, receives goals, orchestrates lifecycle
+  │
+  ├─ 🔍 Scout                   Lightweight haiku, explores paths, marks food sources
+  ├─ ⚒️  Worker                  Sonnet, executes tasks, may spawn sub-tasks
+  └─ 🛡️ Soldier                 Sonnet, reviews quality, may request rework
+
+Pheromone                       .ant-colony/ file system, indirect ant-to-ant communication
+Nest                            Shared state, atomic file operations, cross-process safe
+```
+
+## Lifecycle
+
+```
+Goal → Scouting → Task Pool → Workers Execute in Parallel → Soldiers Review → Fix (if needed) → Done
+          │                           │
+          │  Pheromone decay (10min)   │  Sub-tasks auto-spawned
+          └───────────────────────────┘
+```
+
+## Adaptive Concurrency
+
+Models real ant colony dynamic recruitment:
+
+- **Cold start**: 1–2 ants, gradual exploration
+- **Exploration phase**: +1 each wave, monitoring throughput inflection point
+- **Steady state**: fine-tune around optimal value
+- **Overload protection**: CPU > 85% or memory < 500MB → auto-reduce
+- **Elastic scaling**: more tasks → recruit; fewer tasks → shrink
+
+## Usage
+
+### Auto-Trigger
+
+The LLM automatically invokes the `ant_colony` tool when task complexity warrants it.
+
+### Commands
+
+```
+/colony-stop                Cancel a running colony
+Ctrl+Shift+A                Open colony details panel
+```
+
+### Examples
+
+```
+/colony Migrate the entire project from CommonJS to ESM, updating all imports/exports and tsconfig
+
+/colony Add unit tests for all modules under src/, targeting 80% coverage
+
+/colony Refactor auth system from session-based to JWT, maintaining API compatibility
+```
+
+## Pheromone System
+
+Ants communicate indirectly through pheromones (stigmergy), not direct messages:
+
+| Type       | Released By | Meaning                                 |
+| ---------- | ----------- | --------------------------------------- |
+| discovery  | Scout       | Discovered code structure, dependencies |
+| progress   | Worker      | Completed changes, file modifications   |
+| warning    | Soldier     | Quality issues, conflict risks          |
+| completion | Worker      | Task completion marker                  |
+| dependency | Any         | File dependency relationships           |
+
+Pheromones decay exponentially (10-minute half-life), preventing stale info from misleading
+subsequent ants.
+
+## File Locking
+
+Each task declares the files it operates on. The queen guarantees:
+
+- Only one ant modifies a given file at any time
+- Conflicting tasks are automatically marked `blocked` and resume when locks release
+
+## Nest Structure
+
+```
+.ant-colony/{colony-id}/
+├── state.json           Colony state
+├── pheromone.jsonl       Append-only pheromone log
+└── tasks/               One file per task (atomic updates)
+    ├── t-xxx.json
+    └── t-yyy.json
+```
+
+## Installation
+
+```bash
+# Option 1: Symlink to pi extensions directory
+mkdir -p ~/.pi/agent/extensions/ant-colony
+ln -sf "$(pwd)/pi-package/extensions/ant-colony/index.ts" ~/.pi/agent/extensions/ant-colony/index.ts
+# ... (symlink all .ts files)
+
+# Option 2: Install via oh-pi
+npx oh-pi  # Select "Full Power" preset
+```
+
+## Module Reference
+
+| File             | Lines | Responsibility                                                             |
+| ---------------- | ----- | -------------------------------------------------------------------------- |
+| `types.ts`       | ~150  | Type system: ants, tasks, pheromones, colony state                         |
+| `nest.ts`        | ~500  | Nest: file-system shared state, atomic R/W, pheromone decay                |
+| `concurrency.ts` | ~120  | Adaptive concurrency: system sampling, exploration/steady-state adjustment |
+| `spawner.ts`     | ~370  | Ant spawning: session management, prompt construction, output parsing      |
+| `queen.ts`       | ~1000 | Queen scheduling: lifecycle, task waves, multi-round iteration             |
+| `index.ts`       | ~900  | Extension entry: tool/shortcut registration, TUI rendering                 |
+| `deps.ts`        | ~140  | Lightweight import graph for dependency-aware scheduling                   |
+| `parser.ts`      | ~180  | Sub-task and pheromone extraction from ant output                          |
+| `prompts.ts`     | ~90   | Per-caste system prompts and prompt builder                                |
+| `ui.ts`          | ~140  | Formatting helpers for status bar, overlay, and reports                    |

package/extensions/ant-colony/concurrency.ts

@@ -0,0 +1,127 @@
+/**
+ * Adaptive concurrency control — modeled after ant colony dynamic recruitment.
+ *
+ * Real ant colonies: more food → more recruitment pheromones → more foragers leave the nest.
+ * Mapping: more tasks + idle system → increase concurrency; overloaded/few tasks → decrease.
+ *
+ * Explores boundaries: gradually increases concurrency at startup, monitoring throughput inflection points.
+ */
+
+import * as os from "node:os";
+import type { ConcurrencyConfig, ConcurrencySample } from "./types.js";
+
+const CPU_CORES = os.cpus().length;
+
+export function defaultConcurrency(): ConcurrencyConfig {
+	return {
+		current: 2,
+		min: 1,
+		max: Math.min(CPU_CORES, 8),
+		optimal: 3,
+		history: [],
+	};
+}
+
+/** Sample current system load (CPU, memory, throughput). */
+export function sampleSystem(activeTasks: number, completedRecently: number, windowMinutes: number): ConcurrencySample {
+	const cpus = os.cpus();
+	const cpuLoad =
+		cpus.reduce((sum, c) => {
+			const total = Object.values(c.times).reduce((a, b) => a + b, 0);
+			return sum + 1 - c.times.idle / total;
+		}, 0) / cpus.length;
+
+	const mem = os.freemem();
+	const throughput = windowMinutes > 0 ? completedRecently / windowMinutes : 0;
+
+	return {
+		timestamp: Date.now(),
+		concurrency: activeTasks,
+		cpuLoad,
+		memFree: mem,
+		throughput,
+	};
+}
+
+/**
+ * Adaptive adjustment algorithm.
+ *
+ * Phase 1 — Exploration (samples < 10): increment by 1 each wave, finding throughput inflection.
+ * Phase 2 — Steady state: fine-tune around the optimal value.
+ *
+ * Constraints:
+ * - CPU load > 85% → reduce
+ * - Free memory < 500MB → reduce
+ * - Throughput declining → revert to previous optimal
+ * - No pending tasks → drop to min
+ */
+export function adapt(config: ConcurrencyConfig, pendingTasks: number): ConcurrencyConfig {
+	const next = { ...config };
+	const samples = config.history;
+
+	// No pending tasks — drop to minimum
+	if (pendingTasks === 0) {
+		next.current = config.min;
+		return next;
+	}
+
+	// Cap at pending task count
+	const taskCap = Math.min(pendingTasks, config.max);
+
+	if (samples.length < 2) {
+		// Cold start: use half of max for fast ramp-up
+		next.current = Math.min(Math.ceil(config.max / 2), taskCap);
+		return next;
+	}
+
+	const latest = samples[samples.length - 1];
+	const prev = samples[samples.length - 2];
+
+	// CPU sliding window: average of last 3 samples
+	const recentCpuSamples = samples.slice(-3);
+	const avgCpu = recentCpuSamples.reduce((s, x) => s + x.cpuLoad, 0) / recentCpuSamples.length;
+
+	// 429 cooldown: no concurrency increases within 30s of rate limit
+	const inRateLimitCooldown = config.lastRateLimitAt != null && Date.now() - config.lastRateLimitAt < 30000;
+
+	// Hard constraint: reduce immediately on overload (hysteresis: >85% reduce, 60-85% hold)
+	if (avgCpu > 0.85 || latest.memFree < 500 * 1024 * 1024) {
+		next.current = Math.max(config.min, config.current - 1);
+		return next;
+	}
+
+	// Hysteresis band: CPU between 60-85% holds steady
+	const canIncrease = avgCpu < 0.6 && !inRateLimitCooldown;
+
+	// Exploration phase: insufficient samples, ramp up gradually
+	if (samples.length < 10) {
+		if (latest.throughput >= prev.throughput && canIncrease) {
+			next.current = Math.min(config.current + 1, taskCap);
+		} else if (latest.throughput < prev.throughput) {
+			// Throughput declining — inflection point found
+			next.optimal = prev.concurrency;
+			next.current = prev.concurrency;
+		}
+		return next;
+	}
+
+	// Steady state: fine-tune around optimal
+	const recentThroughput = samples.slice(-5).reduce((s, x) => s + x.throughput, 0) / 5;
+	const olderThroughput = samples.slice(-10, -5).reduce((s, x) => s + x.throughput, 0) / 5;
+
+	if (recentThroughput > olderThroughput * 1.1 && canIncrease) {
+		next.current = Math.min(config.current + 1, taskCap);
+		if (recentThroughput > olderThroughput * 1.2) {
+			next.optimal = next.current;
+		}
+	} else if (recentThroughput < olderThroughput * 0.8) {
+		next.current = Math.max(config.min, config.optimal);
+	}
+
+	// 429 recovery: restore to optimal when CPU is underutilized (e.g. after backoff)
+	if (avgCpu < 0.5 && next.current < config.optimal && !inRateLimitCooldown) {
+		next.current = config.optimal;
+	}
+
+	return next;
+}

package/extensions/ant-colony/deps.ts

@@ -0,0 +1,156 @@
+/**
+ * Lightweight import graph builder — static analysis of ts/js file dependencies.
+ *
+ * Parses `import`/`export`/`require` statements to build a bidirectional
+ * dependency graph. Used by the queen scheduler to detect file-level
+ * dependencies between tasks, preventing workers from editing files that
+ * depend on each other simultaneously.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/**
+ * Bidirectional import graph mapping files to their imports and reverse-imports.
+ *
+ * - `imports`: file → set of files it directly imports
+ * - `importedBy`: file → set of files that import it (reverse edges)
+ */
+export interface ImportGraph {
+	/** Forward edges: file → files it imports. */
+	imports: Map<string, Set<string>>;
+	/** Reverse edges: file → files that import it. */
+	importedBy: Map<string, Set<string>>;
+}
+
+/** Matches ESM `import ... from './path'` and `export ... from './path'` statements. */
+const IMPORT_RE = /(?:import|export)\s+.*?from\s+['"](\.[^'"]+)['"]/g;
+
+/** Matches CommonJS `require('./path')` calls. */
+const REQUIRE_RE = /require\s*\(\s*['"](\.[^'"]+)['"]\s*\)/g;
+
+/**
+ * Resolve a relative import specifier to an actual file path.
+ * Tries common extensions (.ts, .tsx, .js, .jsx) and index files.
+ *
+ * @param from - The file that contains the import statement (relative to cwd)
+ * @param specifier - The relative import specifier (e.g. `./foo`)
+ * @param cwd - Project root directory
+ * @returns Resolved path relative to cwd, or null if not found
+ */
+function resolveImport(from: string, specifier: string, cwd: string): string | null {
+	const dir = path.dirname(path.resolve(cwd, from));
+	const base = path.resolve(dir, specifier);
+	const exts = ["", ".ts", ".tsx", ".js", ".jsx", "/index.ts", "/index.js"];
+	for (const ext of exts) {
+		const full = base + ext;
+		if (fs.existsSync(full)) {
+			return path.relative(cwd, full);
+		}
+	}
+	return null;
+}
+
+/**
+ * Build a bidirectional import graph from a list of source files.
+ * Scans each file for import/require statements and resolves them to
+ * relative file paths within the project.
+ *
+ * @param files - List of file paths relative to `cwd`
+ * @param cwd - Project root directory
+ * @returns The constructed import graph
+ */
+export function buildImportGraph(files: string[], cwd: string): ImportGraph {
+	const imports = new Map<string, Set<string>>();
+	const importedBy = new Map<string, Set<string>>();
+
+	for (const file of files) {
+		const abs = path.resolve(cwd, file);
+		if (!fs.existsSync(abs)) {
+			continue;
+		}
+		let content: string;
+		try {
+			content = fs.readFileSync(abs, "utf-8");
+		} catch {
+			continue;
+		}
+
+		const deps = new Set<string>();
+		for (const re of [IMPORT_RE, REQUIRE_RE]) {
+			re.lastIndex = 0;
+			for (const m of content.matchAll(re)) {
+				const resolved = resolveImport(file, m[1], cwd);
+				if (resolved) {
+					deps.add(resolved);
+				}
+			}
+		}
+
+		imports.set(file, deps);
+		for (const dep of deps) {
+			if (!importedBy.has(dep)) {
+				importedBy.set(dep, new Set());
+			}
+			const dependents = importedBy.get(dep);
+			if (dependents) {
+				dependents.add(file);
+			}
+		}
+	}
+
+	return { imports, importedBy };
+}
+
+/**
+ * Calculate the dependency depth of a file — how many files directly or
+ * indirectly depend on it. Higher depth = more foundational = should be
+ * processed first to avoid cascading breakage.
+ *
+ * Uses BFS traversal through the `importedBy` reverse edges.
+ *
+ * @param file - File path relative to cwd
+ * @param graph - The import graph to traverse
+ * @returns Number of transitive dependents (excluding the file itself)
+ */
+export function dependencyDepth(file: string, graph: ImportGraph): number {
+	const visited = new Set<string>();
+	const queue = [file];
+	while (queue.length > 0) {
+		const current = queue.pop();
+		if (!current || visited.has(current)) {
+			continue;
+		}
+		visited.add(current);
+		const dependents = graph.importedBy.get(current);
+		if (dependents) {
+			for (const d of dependents) {
+				queue.push(d);
+			}
+		}
+	}
+	return visited.size - 1;
+}
+
+/**
+ * Check whether any file in taskA's scope imports any file in taskB's scope.
+ * Used by the queen to detect inter-task dependencies and block conflicting
+ * concurrent execution.
+ *
+ * @param taskAFiles - File paths assigned to task A
+ * @param taskBFiles - File paths assigned to task B
+ * @param graph - The import graph
+ * @returns `true` if task A depends on task B's files
+ */
+export function taskDependsOn(taskAFiles: string[], taskBFiles: string[], graph: ImportGraph): boolean {
+	for (const a of taskAFiles) {
+		const deps = graph.imports.get(a);
+		if (deps) {
+			for (const b of taskBFiles) {
+				if (deps.has(b)) {
+					return true;
+				}
+			}
+		}
+	}
+	return false;
+}