aether-colony 3.1.17 → 5.1.0

package/.aether/utils/spawn-tree.sh

@@ -0,0 +1,260 @@
+#!/bin/bash
+# Spawn Tree Reconstruction Module
+# Parses spawn-tree.txt and provides tree traversal functions
+#
+# Usage: source .aether/utils/spawn-tree.sh
+# All functions output JSON to stdout
+
+# Data directory - can be overridden
+SPAWN_TREE_DATA_DIR="${SPAWN_TREE_DATA_DIR:-.aether/data}"
+SPAWN_TREE_FILE="${SPAWN_TREE_FILE:-$SPAWN_TREE_DATA_DIR/spawn-tree.txt}"
+
+# Parse spawn-tree.txt into structured data
+# Usage: parse_spawn_tree [file_path]
+# Outputs: JSON representation of all spawns
+parse_spawn_tree() {
+  local file_path="${1:-$SPAWN_TREE_FILE}"
+
+  if [[ ! -f "$file_path" ]] || [[ ! -s "$file_path" ]]; then
+    echo '{"spawns":[],"metadata":{"total_count":0,"active_count":0,"completed_count":0,"file_exists":false}}'
+    return 0
+  fi
+
+  awk -F'|' '
+  BEGIN { n=0; active=0; completed_n=0 }
+  NF == 7 && $7 == "spawned" {
+    names[n] = $4; parents[n] = $2; castes[n] = $3
+    tasks[n] = $5; statuses[n] = "spawned"; timestamps[n] = $1
+    completed_at[n] = ""; children_str[n] = ""
+    name_to_idx[$4] = n; n++
+  }
+  $3 ~ /^(completed|failed|blocked)$/ && NF >= 4 {
+    ant = $2
+    if (ant in name_to_idx) {
+      idx = name_to_idx[ant]; statuses[idx] = $3; completed_at[idx] = $1
+    }
+  }
+  END {
+    for (i = 0; i < n; i++) {
+      p = parents[i]
+      if (p in name_to_idx) {
+        pidx = name_to_idx[p]
+        if (children_str[pidx] == "") children_str[pidx] = i
+        else children_str[pidx] = children_str[pidx] " " i
+      }
+    }
+    for (i = 0; i < n; i++) {
+      if (statuses[i] == "spawned" || statuses[i] == "active") active++
+      else if (statuses[i] ~ /^(completed|failed|blocked)$/) completed_n++
+    }
+    printf "{"
+    printf "\"spawns\":["
+    for (i = 0; i < n; i++) {
+      if (i > 0) printf ","
+      nm = names[i]; gsub(/\\/, "\\\\", nm); gsub(/"/, "\\\"", nm); gsub(/\t/, "\\t", nm)
+      pr = parents[i]; gsub(/\\/, "\\\\", pr); gsub(/"/, "\\\"", pr); gsub(/\t/, "\\t", pr)
+      tk = tasks[i]; gsub(/\\/, "\\\\", tk); gsub(/"/, "\\\"", tk); gsub(/\t/, "\\t", tk)
+      printf "{\"name\":\"%s\",\"parent\":\"%s\",\"caste\":\"%s\",", nm, pr, castes[i]
+      printf "\"task\":\"%s\",\"status\":\"%s\",", tk, statuses[i]
+      printf "\"spawned_at\":\"%s\",\"completed_at\":\"%s\",", timestamps[i], completed_at[i]
+      printf "\"children\":["
+      if (children_str[i] != "") {
+        split(children_str[i], cidxs, " ")
+        for (j = 1; j <= length(cidxs); j++) {
+          if (j > 1) printf ","
+          cn = names[cidxs[j]+0]
+          gsub(/\\/, "\\\\", cn); gsub(/"/, "\\\"", cn); gsub(/\t/, "\\t", cn)
+          printf "\"%s\"", cn
+        }
+      }
+      printf "]}"
+    }
+    printf "],"
+    printf "\"metadata\":{\"total_count\":%d,\"active_count\":%d,\"completed_count\":%d,\"file_exists\":true}", n, active, completed_n
+    printf "}"
+  }
+  ' "$file_path"
+}
+
+# Get spawn depth for a given ant name
+# Usage: get_spawn_depth <ant_name>
+# Returns: JSON with ant name and depth
+get_spawn_depth() {
+  local ant_name="${1:-}"
+
+  if [[ -z "$ant_name" || "$ant_name" == "Queen" ]]; then
+    jq -n --arg ant "${ant_name:-Queen}" '{ant: $ant, depth: 0}'
+    return 0
+  fi
+
+  local file_path="${SPAWN_TREE_FILE}"
+
+  if [[ ! -f "$file_path" ]]; then
+    jq -n --arg ant "$ant_name" '{ant: $ant, depth: 1, found: false}'
+    return 0
+  fi
+
+  # Check if ant exists
+  # -F: ant_name may contain regex metacharacters (dots, plus, brackets, etc.)
+  if ! grep -qF "|$ant_name|" "$file_path" 2>/dev/null; then
+    jq -n --arg ant "$ant_name" '{ant: $ant, depth: 1, found: false}'
+    return 0
+  fi
+
+  # Calculate depth by traversing parent chain
+  local depth=1
+  local current="$ant_name"
+  local safety=0
+
+  while [[ $safety -lt 5 ]]; do
+    # Find who spawned this ant
+    local parent
+    parent=$(grep -F "|$current|" "$file_path" 2>/dev/null | grep "|spawned$" | head -1 | cut -d'|' -f2 || echo "")
+
+    if [[ -z "$parent" || "$parent" == "Queen" ]]; then
+      break
+    fi
+
+    ((depth++))
+    current="$parent"
+    ((safety++))
+  done
+
+  jq -n --arg ant "$ant_name" --argjson depth "$depth" '{ant: $ant, depth: $depth, found: true}'
+}
+
+# Get list of active spawns
+# Usage: get_active_spawns [file_path]
+# Returns: JSON array of active spawns
+get_active_spawns() {
+  local file_path="${1:-$SPAWN_TREE_FILE}"
+
+  if [[ ! -f "$file_path" ]] || [[ ! -s "$file_path" ]]; then
+    echo "[]"
+    return 0
+  fi
+
+  awk -F'|' '
+  BEGIN { spawn_n=0 }
+  $3 ~ /^(completed|failed|blocked)$/ && NF >= 4 { done_set[$2] = 1 }
+  NF == 7 && $7 == "spawned" {
+    spawn_names[spawn_n] = $4; spawn_parents[spawn_n] = $2
+    spawn_castes[spawn_n] = $3; spawn_tasks[spawn_n] = $5
+    spawn_ts[spawn_n] = $1; spawn_n++
+  }
+  END {
+    printf "["
+    first = 1
+    for (i = 0; i < spawn_n; i++) {
+      if (!(spawn_names[i] in done_set)) {
+        if (!first) printf ","
+        first = 0
+        nm = spawn_names[i]; gsub(/\\/, "\\\\", nm); gsub(/"/, "\\\"", nm); gsub(/\t/, "\\t", nm)
+        pr = spawn_parents[i]; gsub(/\\/, "\\\\", pr); gsub(/"/, "\\\"", pr); gsub(/\t/, "\\t", pr)
+        tk = spawn_tasks[i]; gsub(/\\/, "\\\\", tk); gsub(/"/, "\\\"", tk); gsub(/\t/, "\\t", tk)
+        printf "{\"name\":\"%s\",\"caste\":\"%s\",\"parent\":\"%s\",\"task\":\"%s\",\"spawned_at\":\"%s\"}", nm, spawn_castes[i], pr, tk, spawn_ts[i]
+      }
+    }
+    printf "]"
+  }
+  ' "$file_path"
+}
+
+# Get direct children of a spawn
+# Usage: get_spawn_children <ant_name> [file_path]
+# Returns: JSON array of child names
+get_spawn_children() {
+  local ant_name="${1:-}"
+  local file_path="${2:-$SPAWN_TREE_FILE}"
+
+  if [[ -z "$ant_name" || ! -f "$file_path" ]]; then
+    echo "[]"
+    return 0
+  fi
+
+  # Collect children names safely, then build JSON array via jq
+  local -a children_arr=()
+
+  # Find all spawns where parent matches
+  while IFS= read -r line || [[ -n "$line" ]]; do
+    [[ -z "$line" ]] && continue
+
+    local pipe_count
+    pipe_count=$(echo "$line" | tr -cd '|' | wc -c | tr -d ' ')
+
+    if [[ $pipe_count -eq 6 ]]; then
+      local parent child_name
+      parent=$(echo "$line" | cut -d'|' -f2)
+      child_name=$(echo "$line" | cut -d'|' -f4)
+
+      if [[ "$parent" == "$ant_name" ]]; then
+        children_arr+=("$child_name")
+      fi
+    fi
+  done < "$file_path"
+
+  if [[ ${#children_arr[@]} -eq 0 ]]; then
+    echo "[]"
+  else
+    printf '%s\n' "${children_arr[@]}" | jq -R . | jq -s .
+  fi
+}
+
+# Get full lineage from ant up to Queen
+# Usage: get_spawn_lineage <ant_name> [file_path]
+# Returns: JSON array from ant up to Queen (inclusive)
+get_spawn_lineage() {
+  local ant_name="${1:-}"
+  local file_path="${2:-$SPAWN_TREE_FILE}"
+
+  if [[ -z "$ant_name" ]]; then
+    echo "[]"
+    return 0
+  fi
+
+  if [[ ! -f "$file_path" ]]; then
+    jq -n --arg ant "$ant_name" '[$ant, "Queen"]'
+    return 0
+  fi
+
+  # Build lineage array (ant first, then ancestors) using jq for safe JSON escaping
+  local -a lineage_arr=("$ant_name")
+  local current="$ant_name"
+  local safety=0
+
+  while [[ $safety -lt 5 ]]; do
+    # Find who spawned this ant
+    local parent
+    parent=$(grep -F "|$current|" "$file_path" 2>/dev/null | grep "|spawned$" | head -1 | cut -d'|' -f2 || echo "")
+
+    if [[ -z "$parent" || "$parent" == "Queen" ]]; then
+      lineage_arr+=("Queen")
+      break
+    fi
+
+    lineage_arr+=("$parent")
+    current="$parent"
+    ((safety++))
+  done
+
+  # Build JSON array safely via jq
+  printf '%s\n' "${lineage_arr[@]}" | jq -R . | jq -s .
+}
+
+# Reconstruct full tree as JSON
+# Usage: reconstruct_tree_json [file_path]
+# Returns: Complete spawn tree with metadata
+reconstruct_tree_json() {
+  local file_path="${1:-$SPAWN_TREE_FILE}"
+  parse_spawn_tree "$file_path"
+}
+
+# Export functions if being sourced (Bash 3.2 compatible)
+if [[ "${BASH_SOURCE[0]:-}" != "${0}" ]]; then
+  export -f parse_spawn_tree 2>/dev/null || true
+  export -f get_spawn_depth 2>/dev/null || true
+  export -f get_active_spawns 2>/dev/null || true
+  export -f get_spawn_children 2>/dev/null || true
+  export -f get_spawn_lineage 2>/dev/null || true
+  export -f reconstruct_tree_json 2>/dev/null || true
+fi

package/.aether/utils/spawn.sh

@@ -0,0 +1,260 @@
+#!/bin/bash
+# Spawn utility functions — extracted from aether-utils.sh
+# Provides: _spawn_log, _spawn_complete, _spawn_can_spawn, _spawn_get_depth, _spawn_can_spawn_swarm, _spawn_tree_load, _spawn_tree_active, _spawn_tree_depth, _spawn_efficiency
+#
+# These functions are sourced by aether-utils.sh at startup.
+# All shared infrastructure (json_ok, json_err, json_warn, atomic_write, acquire_lock,
+# release_lock, feature_enabled, LOCK_DIR, DATA_DIR, SCRIPT_DIR, error constants) is available.
+# Note: get_caste_emoji is defined in the main file and available to this module at call time.
+
+_spawn_log() {
+    # Usage: spawn-log <parent_id> <child_caste> <child_name> <task_summary> [model] [status]
+    parent_id="${1:-}"
+    child_caste="${2:-}"
+    child_name="${3:-}"
+    task_summary="${4:-}"
+    model="${5:-default}"
+    status="${6:-spawned}"
+    # Model slot resolution removed (archived: .aether/archive/model-routing/)
+    # Agent frontmatter model: fields handle routing natively via Claude Code.
+    [[ "$model" == "default" ]] && model="inherit"
+    [[ -z "$parent_id" || -z "$child_caste" || -z "$task_summary" ]] && json_err "$E_VALIDATION_FAILED" "Usage: spawn-log <parent_id> <child_caste> <child_name> <task_summary> [model] [status]"
+    mkdir -p "$COLONY_DATA_DIR"
+    ts=$(date -u +"%H:%M:%S")
+    ts_full=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    emoji=$(get_caste_emoji "$child_caste")
+    parent_emoji=$(get_caste_emoji "$parent_id")
+    # Log to activity log with spawn format, emojis, and model info
+    echo "[$ts] ⚡ SPAWN $parent_emoji $parent_id -> $emoji $child_name ($child_caste): $task_summary [model: $model]" >> "$COLONY_DATA_DIR/activity.log"
+    # Log to spawn tree file for visualization (NEW FORMAT: includes model field)
+    echo "$ts_full|$parent_id|$child_caste|$child_name|$task_summary|$model|$status" >> "$COLONY_DATA_DIR/spawn-tree.txt"
+    # Return emoji-formatted result for display (jq-safe: child_name may contain JSON-special chars)
+    json_ok "$(jq -n --arg msg "⚡ $emoji $child_name spawned" '$msg')"
+}
+
+_spawn_complete() {
+    # Migrated to state-api facade: uses _state_mutate for failed spawn event logging
+    # Usage: spawn-complete <ant_name> <status> [summary]
+    ant_name="${1:-}"
+    status="${2:-completed}"
+    summary="${3:-}"
+    [[ -z "$ant_name" ]] && json_err "$E_VALIDATION_FAILED" "Usage: spawn-complete <ant_name> <status> [summary]"
+    mkdir -p "$COLONY_DATA_DIR"
+    ts=$(date -u +"%H:%M:%S")
+    ts_full=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    emoji=$(get_caste_emoji "$ant_name")
+    status_icon="✅"
+    [[ "$status" == "failed" ]] && status_icon="❌"
+    [[ "$status" == "blocked" ]] && status_icon="🚫"
+    echo "[$ts] $status_icon $emoji $ant_name: $status${summary:+ - $summary}" >> "$COLONY_DATA_DIR/activity.log"
+    # Update spawn tree
+    echo "$ts_full|$ant_name|$status|$summary" >> "$COLONY_DATA_DIR/spawn-tree.txt"
+    # Log failed spawns to events array as pipe-delimited strings (matching template format)
+    if [[ "$status" == "failed" ]] || [[ "$status" == "error" ]]; then
+      if [[ -f "$DATA_DIR/COLONY_STATE.json" ]]; then
+        SC_EVENT="$ts_full|spawn_failed|$ant_name|${summary:-unknown}" \
+          _state_mutate '
+            .events += [env.SC_EVENT]
+          ' >/dev/null 2>&1 || _aether_log_error "Failed to log spawn failure to colony state"
+      fi
+    fi
+    # Return emoji-formatted result for display (jq-safe: ant_name/summary may contain JSON-special chars)
+    json_ok "$(jq -n --arg msg "$status_icon $emoji $ant_name: ${summary:-$status}" '$msg')"
+}
+
+_spawn_can_spawn() {
+    # Check if spawning is allowed at given depth
+    # Usage: spawn-can-spawn [depth] [--enforce]
+    # Returns: {can_spawn: bool, depth: N, max_spawns: N, current_total: N, global_cap: N}
+    # --enforce: fail with non-zero exit when spawning is not allowed
+    depth=""
+    enforce_mode=false
+    for arg in "$@"; do
+      case "$arg" in
+        --enforce) enforce_mode=true ;;
+        *)
+          if [[ -z "$depth" ]]; then
+            depth="$arg"
+          else
+            json_err "$E_VALIDATION_FAILED" "Usage: spawn-can-spawn [depth] [--enforce]"
+          fi
+          ;;
+      esac
+    done
+    [[ -z "$depth" ]] && depth=1
+    [[ "$depth" =~ ^[0-9]+$ ]] || json_err "$E_VALIDATION_FAILED" "Depth must be a non-negative integer" "{\"provided\":\"$depth\"}"
+
+    # Depth limits: 1→4 spawns, 2→2 spawns, 3+→0 spawns
+    if [[ $depth -eq 1 ]]; then
+      max_for_depth=4
+    elif [[ $depth -eq 2 ]]; then
+      max_for_depth=2
+    else
+      max_for_depth=0
+    fi
+
+    # Count current spawns in this session (from spawn-tree.txt)
+    current=0
+    if [[ -f "$COLONY_DATA_DIR/spawn-tree.txt" ]]; then
+      current=$(grep -c "|spawned$" "$COLONY_DATA_DIR/spawn-tree.txt" 2>/dev/null || echo 0)  # SUPPRESS:OK -- read-default: count defaults to 0 if file missing
+    fi
+
+    # Global cap of 10 workers per phase
+    global_cap=10
+
+    # Can spawn if: depth < 3 AND under global cap
+    if [[ $depth -lt 3 && $current -lt $global_cap ]]; then
+      can="true"
+    else
+      can="false"
+    fi
+
+    if [[ "$enforce_mode" == "true" && "$can" == "false" ]]; then
+      json_err "$E_VALIDATION_FAILED" "Spawn cap exceeded: depth=$depth current=$current max=$global_cap"
+    fi
+
+    json_ok "{\"can_spawn\":$can,\"depth\":$depth,\"max_spawns\":$max_for_depth,\"current_total\":$current,\"global_cap\":$global_cap}"
+}
+
+_spawn_get_depth() {
+    # Return depth for a given ant name by tracing spawn tree
+    # Usage: spawn-get-depth <ant_name>
+    # Queen = depth 0, Queen's spawns = depth 1, their spawns = depth 2, etc.
+    ant_name="${1:-Queen}"
+
+    if [[ "$ant_name" == "Queen" ]]; then
+      json_ok '{"ant":"Queen","depth":0}'
+      exit 0
+    fi
+
+    # Check if spawn tree exists
+    if [[ ! -f "$COLONY_DATA_DIR/spawn-tree.txt" ]]; then
+      json_ok "$(jq -n --arg ant "$ant_name" '{ant: $ant, depth: 1, found: false}')"
+      exit 0
+    fi
+
+    # Check if ant exists in spawn tree (gracefully handle missing ants)
+    if ! grep -qF "|$ant_name|" "$COLONY_DATA_DIR/spawn-tree.txt" 2>/dev/null; then  # SUPPRESS:OK -- existence-test: file may not exist; -F: ant_name may contain regex metacharacters
+      json_ok "$(jq -n --arg ant "$ant_name" '{ant: $ant, depth: 1, found: false}')"
+      exit 0
+    fi
+
+    # Find the spawn record for this ant and trace parents
+    depth=1
+    current_ant="$ant_name"
+
+    # Find who spawned this ant (look for lines with |spawned)
+    while true; do
+      # Format: timestamp|parent|caste|child_name|task|spawned
+      # SUPPRESS:OK -- read-default: returns fallback on failure
+      parent=$(grep -F "|$current_ant|" "$COLONY_DATA_DIR/spawn-tree.txt" 2>/dev/null | grep "|spawned$" | head -1 | cut -d'|' -f2 || echo "")
+
+      if [[ -z "$parent" || "$parent" == "Queen" ]]; then
+        break
+      fi
+
+      depth=$((depth + 1))
+      current_ant="$parent"
+
+      # Safety limit
+      if [[ $depth -gt 5 ]]; then
+        break
+      fi
+    done
+
+    json_ok "$(jq -n --arg ant "$ant_name" --argjson depth "$depth" '{ant: $ant, depth: $depth, found: true}')"
+}
+
+_spawn_can_spawn_swarm() {
+    # Check if swarm can spawn more scouts (separate from phase workers)
+    # Usage: spawn-can-spawn-swarm <swarm_id>
+    # Swarm has its own cap of 6 (4 scouts + 2 sub-scouts max)
+    swarm_id="${1:-swarm}"
+    swarm_cap=6
+
+    current=0
+    if [[ -f "$COLONY_DATA_DIR/spawn-tree.txt" ]]; then
+      # SUPPRESS:OK -- existence-test: grep returns 1 when no matches
+      # -F: swarm_id may contain regex metacharacters; anchor $ dropped (swarm_id is unique, no substring collision risk)
+      current=$(grep -cF "|swarm:$swarm_id" "$COLONY_DATA_DIR/spawn-tree.txt" 2>/dev/null) || current=0
+    fi
+
+    if [[ $current -lt $swarm_cap ]]; then
+      can="true"
+      remaining=$((swarm_cap - current))
+    else
+      can="false"
+      remaining=0
+    fi
+
+    json_ok "$(jq -n --argjson can_spawn "$can" --argjson current "$current" \
+      --argjson cap "$swarm_cap" --argjson remaining "$remaining" --arg swarm_id "$swarm_id" \
+      '{can_spawn: $can_spawn, current: $current, cap: $cap, remaining: $remaining, swarm_id: $swarm_id}')"
+}
+
+_spawn_tree_load() {
+    source "$SCRIPT_DIR/utils/spawn-tree.sh" 2>/dev/null || {  # SUPPRESS:OK -- read-default: utility may not be installed
+      json_err "$E_FILE_NOT_FOUND" "spawn-tree.sh not found"
+      exit 1
+    }
+    tree_json=$(reconstruct_tree_json)
+    if echo "$tree_json" | jq -e . >/dev/null 2>&1; then
+      json_ok "$tree_json"
+    else
+      json_err "$E_VALIDATION_FAILED" "spawn tree reconstruction produced invalid JSON"
+      return 1
+    fi
+}
+
+_spawn_tree_active() {
+    source "$SCRIPT_DIR/utils/spawn-tree.sh" 2>/dev/null || {  # SUPPRESS:OK -- read-default: utility may not be installed
+      json_err "$E_FILE_NOT_FOUND" "spawn-tree.sh not found"
+      exit 1
+    }
+    active=$(get_active_spawns)
+    if echo "$active" | jq -e . >/dev/null 2>&1; then
+      json_ok "$active"
+    else
+      json_err "$E_VALIDATION_FAILED" "spawn-tree active produced invalid JSON"
+      return 1
+    fi
+}
+
+_spawn_tree_depth() {
+    ant_name="${1:-}"
+    [[ -z "$ant_name" ]] && json_err "$E_VALIDATION_FAILED" "Usage: spawn-tree-depth <ant_name>"
+    source "$SCRIPT_DIR/utils/spawn-tree.sh" 2>/dev/null || {  # SUPPRESS:OK -- read-default: utility may not be installed
+      json_err "$E_FILE_NOT_FOUND" "spawn-tree.sh not found"
+      exit 1
+    }
+    depth=$(get_spawn_depth "$ant_name")
+    if echo "$depth" | jq -e . >/dev/null 2>&1; then
+      json_ok "$depth"
+    else
+      json_err "$E_VALIDATION_FAILED" "spawn-tree depth produced invalid JSON"
+      return 1
+    fi
+}
+
+_spawn_efficiency() {
+    # Calculate spawn efficiency metrics from spawn-tree.txt
+    # Usage: spawn-efficiency
+    spawn_tree_file="$COLONY_DATA_DIR/spawn-tree.txt"
+    total=0
+    completed=0
+    failed=0
+
+    if [[ -f "$spawn_tree_file" ]]; then
+      total=$(grep -c "|spawned$" "$spawn_tree_file" 2>/dev/null || echo 0)  # SUPPRESS:OK -- read-default: count defaults to 0 if file missing
+      completed=$(grep -c "|completed$" "$spawn_tree_file" 2>/dev/null || echo 0)  # SUPPRESS:OK -- read-default: count defaults to 0 if file missing
+      failed=$(grep -c "|failed$" "$spawn_tree_file" 2>/dev/null || echo 0)  # SUPPRESS:OK -- read-default: count defaults to 0 if file missing
+    fi
+
+    if [[ "$total" -gt 0 ]]; then
+      efficiency=$(( completed * 100 / total ))
+    else
+      efficiency=0
+    fi
+
+    json_ok "{\"total\":$total,\"completed\":$completed,\"failed\":$failed,\"efficiency_pct\":$efficiency}"
+}