aether-colony 3.1.0 → 3.1.1

package/bin/cli.js

@@ -74,6 +74,7 @@ const HUB_SYSTEM = path.join(HUB_DIR, 'system');
 const HUB_COMMANDS_CLAUDE = path.join(HUB_DIR, 'commands', 'claude');
 const HUB_COMMANDS_OPENCODE = path.join(HUB_DIR, 'commands', 'opencode');
 const HUB_AGENTS = path.join(HUB_DIR, 'agents');
+const HUB_VISUALIZATIONS = path.join(HUB_DIR, 'visualizations');
 const HUB_REGISTRY = path.join(HUB_DIR, 'registry.json');
 const HUB_VERSION = path.join(HUB_DIR, 'version.json');
 
@@ -893,6 +894,17 @@ function setupHub() {
       }
     }
 
+    // Sync .aether/visualizations/ -> ~/.aether/visualizations/
+    const visualizationsSrc = path.join(PACKAGE_DIR, '.aether', 'visualizations');
+    if (fs.existsSync(visualizationsSrc)) {
+      const result = syncDirWithCleanup(visualizationsSrc, HUB_VISUALIZATIONS);
+      log(`  Hub visualizations: ${result.copied} files -> ${HUB_VISUALIZATIONS}`);
+      if (result.removed.length > 0) {
+        log(`  Hub visualizations: removed ${result.removed.length} stale files`);
+        for (const f of result.removed) log(`    - ${f}`);
+      }
+    }
+
     // Create/preserve registry.json
     if (!fs.existsSync(HUB_REGISTRY)) {
       writeJsonSync(HUB_REGISTRY, { schema_version: 1, repos: [] });
@@ -968,15 +980,18 @@ async function updateRepo(repoPath, sourceVersion, opts) {
     const systemCopied = result.sync_result?.system?.copied || 0;
     const commandsCopied = (result.sync_result?.commands?.copied || 0);
     const agentsCopied = result.sync_result?.agents?.copied || 0;
+    const visualizationsCopied = result.sync_result?.visualizations?.copied || 0;
 
     const systemRemoved = result.sync_result?.system?.removed?.length || 0;
     const commandsRemoved = result.sync_result?.commands?.removed?.length || 0;
     const agentsRemoved = result.sync_result?.agents?.removed?.length || 0;
+    const visualizationsRemoved = result.sync_result?.visualizations?.removed?.length || 0;
 
     const allRemovedFiles = [
       ...(result.sync_result?.system?.removed || []),
       ...(result.sync_result?.commands?.removed || []).map(f => `.claude/commands/ant/${f}`),
       ...(result.sync_result?.agents?.removed || []).map(f => `.opencode/agents/${f}`),
+      ...(result.sync_result?.visualizations?.removed || []).map(f => `.aether/visualizations/${f}`),
     ];
 
     return {
@@ -986,7 +1001,8 @@ async function updateRepo(repoPath, sourceVersion, opts) {
       system: systemCopied,
       commands: commandsCopied,
       agents: agentsCopied,
-      removed: systemRemoved + commandsRemoved + agentsRemoved,
+      visualizations: visualizationsCopied,
+      removed: systemRemoved + commandsRemoved + agentsRemoved + visualizationsRemoved,
       removedFiles: allRemovedFiles,
       stashCreated: !!transaction.checkpoint?.stashRef,
       checkpoint_id: result.checkpoint_id,
@@ -1155,14 +1171,14 @@ program
             console.error(`  Skipping. Use --force to stash and update.`);
             dirty++;
           } else if (result.status === 'dry-run') {
-            log(`  Would update: ${repo.path} (${result.from} -> ${result.to}) [${result.system} system, ${result.commands} commands, ${result.agents} agents]`);
+            log(`  Would update: ${repo.path} (${result.from} -> ${result.to}) [${result.system} system, ${result.commands} commands, ${result.agents} agents, ${result.visualizations} visualizations]`);
             if (result.removed > 0) {
               log(`  Would remove ${result.removed} stale files:`);
               for (const f of result.removedFiles) log(`    - ${f}`);
             }
             updated++;
           } else if (result.status === 'updated') {
-            log(`  ${c.success('Updated:')} ${repo.path} (${result.from} -> ${result.to}) [${result.system} system, ${result.commands} commands, ${result.agents} agents]`);
+            log(`  ${c.success('Updated:')} ${repo.path} (${result.from} -> ${result.to}) [${result.system} system, ${result.commands} commands, ${result.agents} agents, ${result.visualizations} visualizations]`);
             if (result.removed > 0) {
               log(`  Removed ${result.removed} stale files:`);
               for (const f of result.removedFiles) log(`    - ${f}`);
@@ -1238,7 +1254,7 @@ program
 
         if (result.status === 'dry-run') {
           console.log(`Would update: ${result.from} -> ${result.to}`);
-          console.log(`  ${result.system} system files, ${result.commands} command files, ${result.agents} agent files`);
+          console.log(`  ${result.system} system files, ${result.commands} command files, ${result.agents} agent files, ${result.visualizations} visualization files`);
           if (result.removed > 0) {
             console.log(`  Would remove ${result.removed} stale files:`);
             for (const f of result.removedFiles) console.log(`    - ${f}`);
@@ -1248,7 +1264,7 @@ program
         }
 
         console.log(c.success(`Updated: ${result.from} -> ${result.to}`));
-        console.log(`  ${result.system} system files, ${result.commands} command files, ${result.agents} agent files`);
+        console.log(`  ${result.system} system files, ${result.commands} command files, ${result.agents} agent files, ${result.visualizations} visualization files`);
         if (result.removed > 0) {
           console.log(`  Removed ${result.removed} stale files:`);
           for (const f of result.removedFiles) console.log(`    - ${f}`);

package/bin/lib/model-profiles.js

@@ -43,7 +43,19 @@ function loadModelProfiles(repoPath) {
   }
 
   try {
-    return yaml.load(content);
+    const config = yaml.load(content);
+
+    // Substitute environment variables in proxy config
+    if (config.proxy) {
+      if (config.proxy.auth_token) {
+        config.proxy.auth_token = substituteEnvVars(config.proxy.auth_token);
+      }
+      if (config.proxy.endpoint) {
+        config.proxy.endpoint = substituteEnvVars(config.proxy.endpoint);
+      }
+    }
+
+    return config;
   } catch (error) {
     throw new ConfigurationError(
       `Invalid YAML in model profiles file: ${error.message}`,
@@ -52,6 +64,25 @@ function loadModelProfiles(repoPath) {
   }
 }
 
+/**
+ * Substitute environment variables in a string
+ * Supports ${VAR} and ${VAR:-default} syntax
+ * @param {string} str - String with potential env vars
+ * @returns {string} String with env vars substituted
+ */
+function substituteEnvVars(str) {
+  if (typeof str !== 'string') return str;
+
+  // Match ${VAR:-default} or ${VAR}
+  return str.replace(/\$\{([^}:]+)(?::-([^}]*))?\}/g, (match, varName, defaultValue) => {
+    const envValue = process.env[varName];
+    if (envValue !== undefined && envValue !== '') {
+      return envValue;
+    }
+    return defaultValue !== undefined ? defaultValue : '';
+  });
+}
+
 /**
  * Get the assigned model for a specific caste
  * @param {object} profiles - Parsed model profiles

package/bin/lib/update-transaction.js

@@ -163,6 +163,7 @@ class UpdateTransaction {
     this.HUB_COMMANDS_CLAUDE = path.join(this.HUB_DIR, 'commands', 'claude');
     this.HUB_COMMANDS_OPENCODE = path.join(this.HUB_DIR, 'commands', 'opencode');
     this.HUB_AGENTS = path.join(this.HUB_DIR, 'agents');
+    this.HUB_VISUALIZATIONS = path.join(this.HUB_DIR, 'visualizations');
     this.HUB_VERSION = path.join(this.HUB_DIR, 'version.json');
     this.HUB_REGISTRY = path.join(this.HUB_DIR, 'registry.json');
 
@@ -696,6 +697,7 @@ class UpdateTransaction {
       system: { copied: 0, removed: 0, skipped: 0 },
       commands: { copied: 0, removed: 0, skipped: 0 },
       agents: { copied: 0, removed: 0, skipped: 0 },
+      visualizations: { copied: 0, removed: 0, skipped: 0 },
       errors: [],
     };
 
@@ -727,6 +729,12 @@ class UpdateTransaction {
       results.agents = this.syncDirWithCleanup(this.HUB_AGENTS, repoAgents, { dryRun });
     }
 
+    // Sync visualizations from hub
+    const repoVisualizations = path.join(this.repoPath, '.aether', 'visualizations');
+    if (fs.existsSync(this.HUB_VISUALIZATIONS)) {
+      results.visualizations = this.syncDirWithCleanup(this.HUB_VISUALIZATIONS, repoVisualizations, { dryRun });
+    }
+
     this.syncResult = results;
     return results;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aether-colony",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "Multi-agent system using ant colony intelligence for Claude Code and OpenCode — workers self-organize via pheromone signals",
   "bin": {
     "aether": "./bin/cli.js"
@@ -12,6 +12,7 @@
     ".opencode/agents/",
     ".opencode/opencode.json",
     "runtime/",
+    ".aether/visualizations/",
     "README.md",
     "LICENSE",
     "DISCLAIMER.md",

package/runtime/workers.md

@@ -50,6 +50,106 @@ bash .aether/aether-utils.sh spawn-complete "Hammer-42" "completed" "auth module
 
 ---
 
+## Model-Aware Spawning
+
+Aether colony workers are spawned with model-specific configurations based on their caste. This enables optimal task routing through the LiteLLM proxy.
+
+### How It Works
+
+1. **Model Assignment**: Each caste is mapped to an optimal model in `.aether/model-profiles.yaml`
+2. **Prompt Context**: Queen includes model assignment in worker's prompt via `--- MODEL CONTEXT ---` section
+3. **Worker Self-Reporting**: Workers echo their assigned model in JSON output for verification
+4. **Proxy Routing** (Optional): With LiteLLM proxy running, set `ANTHROPIC_MODEL` in parent shell for true model routing
+
+### Model Assignments by Caste
+
+| Caste | Model | Purpose |
+|-------|-------|---------|
+| prime | glm-5 | Long-horizon coordination, strategic planning (200K context) |
+| archaeologist | glm-5 | Historical pattern analysis across long timeframes |
+| architect | glm-5 | Pattern synthesis, documentation coordination (200K context) |
+| oracle | minimax-2.5 | Research, foresight, browse/search (76.3% BrowseComp) |
+| route_setter | kimi-k2.5 | Task decomposition, structured planning (256K context) |
+| builder | kimi-k2.5 | Code generation, refactoring (76.8% SWE-Bench) |
+| watcher | kimi-k2.5 | Validation, testing, verification |
+| scout | minimax-2.5| Research exploration, parallel sub-agent spawning |
+| chaos | kimi-k2.5 | Edge case probing, resilience testing |
+| colonizer | minimax-2.5| Environment setup, visual coding from screenshots |
+
+### Worker Model Self-Reporting
+
+All workers must include model context in their JSON output:
+
+```json
+{
+  "status": "completed",
+  "summary": "...",
+  "model_context": {
+    "assigned": "kimi-k2.5",
+    "caste": "builder",
+    "source": "caste-default",
+    "reported_at": "2026-02-15T10:30:00Z"
+  }
+}
+```
+
+This enables:
+- **Visibility**: See which model each worker used
+- **Verification**: Confirm routing is working correctly
+- **Debugging**: Detect mismatches between expected and actual
+
+### LiteLLM Proxy Integration (Optional)
+
+For true model routing through LiteLLM:
+
+```bash
+# 1. Start proxy with your API keys
+litellm --config proxy.yaml
+
+# 2. In parent shell (before starting Claude Code):
+export ANTHROPIC_BASE_URL=http://localhost:4000
+export ANTHROPIC_AUTH_TOKEN=sk-litellm-local
+export ANTHROPIC_MODEL=kimi-k2.5  # Or your preferred default
+
+# 3. Start Claude Code - it will inherit these variables
+claude
+```
+
+**Note:** Claude Code's Task tool doesn't support explicit environment variable passing,
+so proxy routing relies on parent shell inheritance. The self-reporting approach works
+regardless of proxy status.
+
+### Available Models
+
+- **glm-5** (via Z_AI): Powerful reasoning for complex tasks, architecture, planning
+- **kimi-k2.5** (via Kimi): Fast code generation, refactoring, implementation
+- **minimax-2.5** (via MiniMax): Efficient validation, research, lightweight tasks
+
+### Fallback Behavior
+
+If the model profile is missing or a caste is not mapped:
+- Default to `kimi-k2.5` (fastest, most cost-effective)
+- Log a warning to the activity log
+- Continue with worker spawn
+
+### Sub-Worker Spawning
+
+When workers spawn sub-workers, they should:
+1. Check if the sub-worker's caste differs from their own
+2. If different, the sub-worker will automatically get their caste's model via the same mechanism
+3. If spawning with the same caste, the model remains the same
+
+### Model Context in Prompts
+
+Worker prompts include a MODEL CONTEXT section that informs the worker about:
+- Which model they are running on
+- The model's strengths and optimal use cases
+- Expected task complexity
+
+This helps workers adjust their approach based on model capabilities.
+
+---
+
 ## Honest Execution Model
 
 **What the colony metaphor means:**
@@ -227,7 +327,7 @@ Actions: CREATED (path + lines), MODIFIED (path), RESEARCH (finding), SPAWN (cas
 
 ### Spawning Sub-Workers
 
-Workers can spawn sub-workers directly using the **Task tool** with `subagent_type="general-purpose"`.
+Workers can spawn sub-workers directly using the **Task tool** with `subagent_type="general"`.
 
 **Depth-Based Behavior:**
 
@@ -278,7 +378,7 @@ bash .aether/aether-utils.sh spawn-log "{your_name}" "{child_caste}" "{child_nam
 
 **Step 4: Use Task tool**
 ```
-Use the Task tool with subagent_type="general-purpose":
+Use the Task tool with subagent_type="general":
 
 You are {child_name}, a {emoji} {Caste} Ant in the Aether Colony at depth {your_depth + 1}.
 
@@ -366,6 +466,12 @@ Next Steps / Recommendations: {required}
 
 🔨 **Purpose:** Implement code, execute commands, and manipulate files to achieve concrete outcomes. The colony's hands -- when tasks need doing, you make them happen.
 
+**Model Context:**
+- Assigned model: kimi-k2.5
+- Strengths: Code generation, refactoring, multimodal capabilities
+- Best for: Implementation tasks, code writing, visual coding from screenshots
+- Benchmark: 76.8% SWE-Bench Verified, 256K context
+
 **When to use:** Code implementation, file manipulation, command execution
 
 **Workflow (TDD-First):**
@@ -417,6 +523,12 @@ Fix count: {N}/3
 
 👁️ **Purpose:** Validate implementation, run tests, and ensure quality. The colony's guardian -- when work is done, you verify it's correct and complete. Also handles security audits, performance analysis, and test coverage.
 
+**Model Context:**
+- Assigned model: kimi-k2.5
+- Strengths: Validation, testing, visual regression testing
+- Best for: Verification, test coverage analysis, multimodal checks (screenshots)
+- Context window: 256K tokens, multimodal capable
+
 **When to use:** Quality review, testing, validation, security/performance audits, phase completion approval
 
 **The Watcher's Iron Law:** Evidence before approval, always. No "should work" or "looks good" -- only verified claims with proof.
@@ -520,6 +632,12 @@ Recommendation: {specific fix or investigation needed}
 
 🔍 **Purpose:** Gather information, search documentation, and retrieve context. The colony's researcher -- when the colony needs to know, you venture forth to find answers.
 
+**Model Context:**
+- Assigned model: kimi-k2.5
+- Strengths: Parallel exploration via agent swarm (up to 100 sub-agents), broad research
+- Best for: Documentation lookup, pattern discovery, wide exploration
+- Benchmark: Can coordinate 1,500 simultaneous tool calls
+
 **When to use:** Research questions, documentation lookup, finding information, learning new domains
 
 **Workflow:**
@@ -537,6 +655,12 @@ Recommendation: {specific fix or investigation needed}
 
 🗺️ **Purpose:** Explore and index codebase structure. Build semantic understanding, detect patterns, and map dependencies. The colony's explorer -- when new territory is encountered, you venture forth to understand the landscape.
 
+**Model Context:**
+- Assigned model: kimi-k2.5
+- Strengths: Visual coding, environment setup, can turn screenshots into functional code
+- Best for: Codebase mapping, dependency analysis, UI/prototype generation
+- Multimodal: Can process visual inputs alongside text
+
 **When to use:** Codebase exploration, structure mapping, dependency analysis, pattern detection
 
 **Workflow:**
@@ -553,6 +677,12 @@ Recommendation: {specific fix or investigation needed}
 
 🏛️ **Purpose:** Synthesize knowledge, extract patterns, and coordinate documentation. The colony's wisdom -- when the colony learns, you organize and preserve that knowledge.
 
+**Model Context:**
+- Assigned model: glm-5
+- Strengths: Long-context synthesis, pattern extraction, complex documentation
+- Best for: Synthesizing knowledge, coordinating docs, pattern recognition
+- Benchmark: 744B MoE, 200K context, strong execution with guidance
+
 **When to use:** Knowledge synthesis, pattern extraction, documentation coordination, decision organization
 
 **Workflow:**
@@ -569,6 +699,12 @@ Recommendation: {specific fix or investigation needed}
 
 📋 **Purpose:** Create structured phase plans, break down goals into achievable tasks, and analyze dependencies. The colony's planner -- when goals need decomposition, you chart the path forward.
 
+**Model Context:**
+- Assigned model: kimi-k2.5
+- Strengths: Structured planning, large context for understanding codebases, fast iteration
+- Best for: Breaking down goals, creating phase structures, dependency analysis
+- Benchmark: 256K context, 76.8% SWE-Bench, strong at structured output
+
 **When to use:** Planning, goal decomposition, phase structuring, dependency analysis
 
 **Planning Discipline:** See `.aether/planning.md` for full reference.
@@ -606,7 +742,15 @@ Steps:
 
 ## Prime Worker
 
-The **Prime Worker** is a special coordinator role at depth 1. When spawned by `/ant:build`, the Prime Worker:
+🏛️ **Purpose:** Coordinate complex, multi-step colony operations. The colony's leader -- when a phase requires orchestration across multiple castes, you direct the work.
+
+**Model Context:**
+- Assigned model: glm-5
+- Strengths: Long-horizon planning, strategic coordination, complex reasoning
+- Best for: Multi-phase coordination, long-term task execution, complex synthesis
+- Benchmark: 744B MoE (40B active), 200K context, tested on 1-year business simulations
+
+**When spawned by `/ant:build`, the Prime Worker:**
 
 1. **Reads phase context** -- tasks, success criteria, constraints
 2. **Self-organizes** -- decides what specialists to spawn based on task analysis