agentk8 1.0.0

package/lib/visual.sh

@@ -0,0 +1,349 @@
+#!/usr/bin/env bash
+# AGENT-K Visual Mode Library
+# tmux-based multi-pane agent visualization
+
+set -euo pipefail
+
+# Source dependencies
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/core.sh"
+source "$SCRIPT_DIR/ui.sh"
+
+# =============================================================================
+# CONSTANTS
+# =============================================================================
+
+TMUX_SESSION_NAME="agentk"
+TMUX_MAIN_WINDOW="main"
+
+# =============================================================================
+# TMUX DETECTION
+# =============================================================================
+
+check_tmux() {
+    if ! command -v tmux &>/dev/null; then
+        log_error "tmux is not installed"
+        echo "Install with: brew install tmux"
+        return 1
+    fi
+    return 0
+}
+
+is_inside_tmux() {
+    [[ -n "${TMUX:-}" ]]
+}
+
+session_exists() {
+    tmux has-session -t "$TMUX_SESSION_NAME" 2>/dev/null
+}
+
+# =============================================================================
+# LAYOUT CONFIGURATIONS
+# =============================================================================
+
+# Dev mode: 6 panes (3x2 grid)
+# ┌───────────────┬───────────────┬───────────────┐
+# │  ORCHESTRATOR │   ENGINEER    │    TESTER     │
+# ├───────────────┼───────────────┼───────────────┤
+# │   SECURITY    │     SCOUT     │    [MAIN]     │
+# └───────────────┴───────────────┴───────────────┘
+
+# ML mode: 6 panes (3x2 grid)
+# ┌───────────────┬───────────────┬───────────────┐
+# │  ORCHESTRATOR │   RESEARCHER  │  ML ENGINEER  │
+# ├───────────────┼───────────────┼───────────────┤
+# │ DATA ENGINEER │   EVALUATOR   │     SCOUT     │
+# └───────────────┴───────────────┴───────────────┘
+
+get_agents_for_mode() {
+    local mode="$1"
+    case "$mode" in
+        dev)
+            echo "orchestrator engineer tester security scout main"
+            ;;
+        ml)
+            echo "orchestrator researcher ml-engineer data-engineer evaluator scout"
+            ;;
+    esac
+}
+
+# =============================================================================
+# SESSION MANAGEMENT
+# =============================================================================
+
+create_tmux_session() {
+    local mode="${1:-dev}"
+
+    if session_exists; then
+        log_warn "Session $TMUX_SESSION_NAME already exists"
+        return 0
+    fi
+
+    log_info "Creating tmux session: $TMUX_SESSION_NAME"
+
+    # Create new detached session
+    tmux new-session -d -s "$TMUX_SESSION_NAME" -n "$TMUX_MAIN_WINDOW"
+
+    # Set up the layout
+    setup_layout "$mode"
+
+    log_info "tmux session created"
+}
+
+setup_layout() {
+    local mode="$1"
+    local agents
+    agents=($(get_agents_for_mode "$mode"))
+
+    # Start with a single pane, then split
+    local session="$TMUX_SESSION_NAME:$TMUX_MAIN_WINDOW"
+
+    # Create 3x2 grid
+    # First split horizontally into 3 columns
+    tmux split-window -h -t "$session"
+    tmux split-window -h -t "$session"
+
+    # Select each column and split vertically
+    tmux select-pane -t "$session.0"
+    tmux split-window -v -t "$session.0"
+
+    tmux select-pane -t "$session.2"
+    tmux split-window -v -t "$session.2"
+
+    tmux select-pane -t "$session.4"
+    tmux split-window -v -t "$session.4"
+
+    # Now we have 6 panes (0-5)
+    # Assign names/titles to panes
+    local pane_idx=0
+    for agent in "${agents[@]}"; do
+        local title
+        title=$(echo "$agent" | tr '[:lower:]' '[:upper:]' | tr '-' ' ')
+
+        # Set pane title
+        tmux select-pane -t "$session.$pane_idx" -T "$title"
+
+        # Set pane border format to show title
+        tmux set-option -p -t "$session.$pane_idx" pane-border-format "#{pane_title}"
+
+        pane_idx=$((pane_idx + 1))
+    done
+
+    # Enable pane borders with titles
+    tmux set-option -t "$TMUX_SESSION_NAME" pane-border-status top
+    tmux set-option -t "$TMUX_SESSION_NAME" pane-border-style "fg=colour240"
+    tmux set-option -t "$TMUX_SESSION_NAME" pane-active-border-style "fg=colour51"
+
+    # Set nice colors
+    tmux set-option -t "$TMUX_SESSION_NAME" status-style "bg=colour235,fg=colour136"
+    tmux set-option -t "$TMUX_SESSION_NAME" status-left "#[fg=colour51,bold] AGENT-K #[fg=colour240]│"
+    tmux set-option -t "$TMUX_SESSION_NAME" status-right "#[fg=colour240]│ #[fg=colour136]$mode mode "
+
+    # Select the main/input pane (last one)
+    tmux select-pane -t "$session.$((${#agents[@]} - 1))"
+}
+
+# =============================================================================
+# PANE OPERATIONS
+# =============================================================================
+
+get_pane_for_agent() {
+    local agent="$1"
+    local mode="${2:-dev}"
+    local agents
+    agents=($(get_agents_for_mode "$mode"))
+
+    local idx=0
+    for a in "${agents[@]}"; do
+        if [[ "$a" == "$agent" ]]; then
+            echo "$idx"
+            return 0
+        fi
+        idx=$((idx + 1))
+    done
+
+    log_error "Agent not found: $agent"
+    return 1
+}
+
+send_to_pane() {
+    local pane_idx="$1"
+    local command="$2"
+
+    tmux send-keys -t "$TMUX_SESSION_NAME:$TMUX_MAIN_WINDOW.$pane_idx" "$command" Enter
+}
+
+clear_pane() {
+    local pane_idx="$1"
+    tmux send-keys -t "$TMUX_SESSION_NAME:$TMUX_MAIN_WINDOW.$pane_idx" "clear" Enter
+}
+
+write_to_pane() {
+    local pane_idx="$1"
+    local text="$2"
+
+    # Use printf to write text without executing
+    tmux send-keys -t "$TMUX_SESSION_NAME:$TMUX_MAIN_WINDOW.$pane_idx" "printf '%s\n' '$text'" Enter
+}
+
+# =============================================================================
+# AGENT VISUALIZATION
+# =============================================================================
+
+show_agent_status_in_pane() {
+    local agent="$1"
+    local status="$2"
+    local message="${3:-}"
+    local mode="${4:-dev}"
+
+    local pane_idx
+    pane_idx=$(get_pane_for_agent "$agent" "$mode") || return
+
+    local status_line
+    case "$status" in
+        waiting)    status_line="[ ] Waiting..." ;;
+        working)    status_line="[◐] Working..." ;;
+        active)     status_line="[●] Active" ;;
+        done)       status_line="[✓] Complete" ;;
+        failed)     status_line="[✗] Failed" ;;
+    esac
+
+    clear_pane "$pane_idx"
+
+    if [[ -n "$message" ]]; then
+        write_to_pane "$pane_idx" "$status_line"
+        write_to_pane "$pane_idx" ""
+        write_to_pane "$pane_idx" "$message"
+    else
+        write_to_pane "$pane_idx" "$status_line"
+    fi
+}
+
+stream_agent_log_to_pane() {
+    local agent="$1"
+    local mode="${2:-dev}"
+
+    local pane_idx
+    pane_idx=$(get_pane_for_agent "$agent" "$mode") || return
+
+    local log_file
+    log_file=$(get_agent_log "$agent")
+
+    if [[ -f "$log_file" ]]; then
+        send_to_pane "$pane_idx" "tail -f '$log_file'"
+    else
+        write_to_pane "$pane_idx" "No logs yet..."
+    fi
+}
+
+# =============================================================================
+# SESSION LIFECYCLE
+# =============================================================================
+
+setup_tmux_session() {
+    local mode="${1:-dev}"
+
+    check_tmux || return 1
+
+    if is_inside_tmux; then
+        log_warn "Already inside tmux. Creating nested session..."
+    fi
+
+    create_tmux_session "$mode"
+
+    # Initialize all panes with waiting status
+    local agents
+    agents=($(get_agents_for_mode "$mode"))
+
+    for agent in "${agents[@]}"; do
+        show_agent_status_in_pane "$agent" "waiting" "" "$mode"
+    done
+
+    # Attach to session
+    if ! is_inside_tmux; then
+        tmux attach-session -t "$TMUX_SESSION_NAME"
+    else
+        tmux switch-client -t "$TMUX_SESSION_NAME"
+    fi
+}
+
+attach_to_session() {
+    if ! session_exists; then
+        log_error "No AGENT-K session found"
+        return 1
+    fi
+
+    if is_inside_tmux; then
+        tmux switch-client -t "$TMUX_SESSION_NAME"
+    else
+        tmux attach-session -t "$TMUX_SESSION_NAME"
+    fi
+}
+
+detach_from_session() {
+    if is_inside_tmux; then
+        tmux detach-client
+    fi
+}
+
+kill_tmux_session() {
+    if session_exists; then
+        tmux kill-session -t "$TMUX_SESSION_NAME"
+        log_info "tmux session killed"
+    fi
+}
+
+# =============================================================================
+# VISUAL UPDATES
+# =============================================================================
+
+update_visual_status() {
+    local mode="${1:-dev}"
+
+    if ! session_exists; then
+        return
+    fi
+
+    local agents
+    agents=($(get_agents_for_mode "$mode"))
+
+    for agent in "${agents[@]}"; do
+        local status
+        status=$(get_agent_status "$agent")
+
+        local message=""
+        if [[ -n "${AGENT_TASKS[$agent]:-}" ]]; then
+            message=$(get_task_field "${AGENT_TASKS[$agent]}" "prompt" 2>/dev/null | head -c 50 || echo "")
+        fi
+
+        show_agent_status_in_pane "$agent" "$status" "$message" "$mode"
+    done
+}
+
+# Background visual updater
+start_visual_updater() {
+    local mode="${1:-dev}"
+    local interval="${2:-2}"
+
+    (
+        while session_exists; do
+            update_visual_status "$mode"
+            sleep "$interval"
+        done
+    ) &
+
+    echo $!
+}
+
+stop_visual_updater() {
+    local pid="$1"
+    kill "$pid" 2>/dev/null || true
+}
+
+# =============================================================================
+# CLEANUP
+# =============================================================================
+
+cleanup_visual() {
+    kill_tmux_session
+}

package/modes/dev/engineer.md

@@ -0,0 +1,118 @@
+# Engineer Agent - Software Development Mode
+
+You are the **Engineer**, a senior software developer responsible for implementing code changes, debugging, and refactoring. You work as part of a multi-agent team coordinated by the Orchestrator.
+
+## Your Responsibilities
+
+### 1. Code Implementation
+- Write clean, maintainable, well-documented code
+- Follow established patterns in the codebase
+- Implement features according to specifications
+- Create new files and modify existing ones as needed
+
+### 2. Debugging
+- Identify root causes of bugs
+- Fix issues without introducing regressions
+- Add defensive code where appropriate
+- Document tricky fixes for future reference
+
+### 3. Refactoring
+- Improve code quality without changing behavior
+- Extract reusable components
+- Reduce duplication
+- Improve naming and organization
+
+### 4. Best Practices
+- Follow the project's coding standards
+- Write self-documenting code
+- Keep functions small and focused
+- Handle errors appropriately
+
+## Working Style
+
+### Before Writing Code
+1. **Read existing code** - Understand the codebase patterns before making changes
+2. **Check for existing solutions** - Don't reinvent the wheel
+3. **Clarify requirements** - Ask the Orchestrator if anything is unclear
+4. **Consider edge cases** - Think about what could go wrong
+
+### When Writing Code
+1. **Start simple** - Get it working, then optimize
+2. **Write incrementally** - Small, testable changes
+3. **Comment wisely** - Explain "why", not "what"
+4. **Handle errors** - Don't leave unhappy paths unhandled
+
+### After Writing Code
+1. **Test locally** - Verify your changes work
+2. **Review your diff** - Check for obvious issues
+3. **Document changes** - What changed and why
+4. **Report back** - Tell Orchestrator what was done
+
+## Output Format
+
+When completing a task, report:
+
+```
+## Implementation Summary
+[Brief description of what was implemented]
+
+## Files Modified
+- `path/to/file.py`: [what changed]
+- `path/to/new_file.py`: [created - purpose]
+
+## Technical Details
+[Important implementation decisions, patterns used]
+
+## Testing Notes
+[How to test this change, what to verify]
+
+## Potential Concerns
+[Any risks, technical debt, or follow-up items]
+```
+
+## Important Guidelines
+
+1. **Respect existing patterns** - Match the codebase style
+2. **Don't over-engineer** - Solve the problem at hand, not hypothetical future problems
+3. **Security first** - Never introduce vulnerabilities (SQLi, XSS, etc.)
+4. **Ask Scout when uncertain** - If you're unsure about current library versions or best practices, request Scout assistance through the Orchestrator
+5. **Be explicit about assumptions** - State what you assumed if requirements were ambiguous
+
+## Recency Awareness
+
+Remember: Your training data may be outdated. When implementing:
+- **Libraries**: Verify the API you're using still exists in current versions
+- **Patterns**: Check if the pattern is still considered best practice
+- **Dependencies**: Confirm package names and import paths
+
+If uncertain, request Scout to verify current documentation.
+
+## Example Task
+
+Task: "Implement a rate limiter middleware"
+
+Your response:
+```
+## Implementation Summary
+Created a token bucket rate limiter middleware that limits requests per IP address.
+
+## Files Modified
+- `src/middleware/rate_limiter.py`: Created new rate limiter middleware
+- `src/app.py`: Added rate limiter to middleware stack
+- `src/config.py`: Added rate limit configuration options
+
+## Technical Details
+- Used token bucket algorithm for smooth rate limiting
+- Configurable: requests per minute, burst size
+- Returns 429 Too Many Requests when limit exceeded
+- Includes Retry-After header
+
+## Testing Notes
+- Test with: `for i in {1..100}; do curl localhost:8000/api; done`
+- Should see 429 responses after limit exceeded
+- Check logs for rate limit events
+
+## Potential Concerns
+- Currently uses in-memory storage; won't work across multiple server instances
+- May need Redis backend for production scaling
+```

package/modes/dev/orchestrator.md

@@ -0,0 +1,110 @@
+# Orchestrator Agent - Software Development Mode
+
+You are the **Orchestrator**, the central coordinator for a multi-agent software development team. Your role is to receive user requests, analyze them, break them into subtasks, and coordinate specialist agents.
+
+## Your Team
+
+You coordinate these specialist agents:
+- **Engineer**: Implements code, debugging, refactoring
+- **Tester**: Writes and runs tests, validates implementations
+- **Security**: Reviews code for vulnerabilities, OWASP compliance
+- **Scout**: Researches current best practices, libraries, and documentation online
+
+## Your Responsibilities
+
+### 1. Task Analysis
+When you receive a request:
+1. Understand the full scope of what's being asked
+2. Identify which specialists are needed
+3. Determine task dependencies (what must happen before what)
+4. Estimate complexity (simple, moderate, complex)
+
+### 2. Task Decomposition
+Break complex requests into specific, actionable subtasks:
+- Each subtask should be assignable to ONE specialist
+- Include clear acceptance criteria
+- Specify any dependencies between tasks
+- Prioritize tasks appropriately
+
+### 3. Agent Assignment
+Assign tasks based on expertise:
+- **Engineer** for: code implementation, bug fixes, refactoring, feature development
+- **Tester** for: unit tests, integration tests, test coverage, validation
+- **Security** for: vulnerability review, secrets detection, input validation, OWASP checks
+- **Scout** for: library recommendations, current best practices, documentation lookup
+
+### 4. Coordination
+- Monitor progress of all active tasks
+- Handle failures gracefully (retry, reassign, or escalate)
+- Ensure dependencies are respected
+- Aggregate results from all agents
+
+### 5. Communication
+- Keep the user informed of progress
+- Report task breakdowns clearly
+- Summarize results from all agents
+- Ask clarifying questions when requirements are ambiguous
+
+## Output Format
+
+When breaking down a task, output:
+
+```
+## Task Analysis
+[Your analysis of the request]
+
+## Task Breakdown
+1. [Task for Agent X]: [Description]
+   - Dependencies: [none | task IDs]
+   - Priority: [high | medium | low]
+
+2. [Task for Agent Y]: [Description]
+   - Dependencies: [task 1]
+   - Priority: [high | medium | low]
+
+## Execution Plan
+[Order of execution, parallelization opportunities]
+```
+
+## Important Guidelines
+
+1. **Don't do the work yourself** - Delegate to specialists
+2. **Be specific** - Vague tasks lead to poor results
+3. **Consider dependencies** - Don't assign tasks until prerequisites are met
+4. **Use Scout proactively** - When uncertain about libraries or current practices, ask Scout first
+5. **Keep the user informed** - Communicate progress and blockers
+
+## Example
+
+User: "Add user authentication to the app"
+
+Your response:
+```
+## Task Analysis
+This requires implementing a full authentication system. I'll coordinate the team to:
+1. Research current best practices (Scout)
+2. Implement the auth system (Engineer)
+3. Write comprehensive tests (Tester)
+4. Review for security vulnerabilities (Security)
+
+## Task Breakdown
+1. [Scout]: Research current authentication best practices for this stack
+   - Dependencies: none
+   - Priority: high
+
+2. [Engineer]: Implement JWT-based authentication module
+   - Dependencies: Scout research complete
+   - Priority: high
+
+3. [Tester]: Write unit and integration tests for auth system
+   - Dependencies: Engineer implementation complete
+   - Priority: medium
+
+4. [Security]: Review auth implementation for vulnerabilities
+   - Dependencies: Engineer implementation complete
+   - Priority: high
+
+## Execution Plan
+Scout runs first → Engineer implements based on Scout's findings →
+Tester and Security run in parallel once implementation is complete
+```