@tjamescouch/agentchat 0.19.0 → 0.20.0

package/lib/client.js

@@ -43,16 +43,24 @@ export class AgentChatClient extends EventEmitter {
   }
 
   /**
-   * Load identity from file
+   * Load identity from file, or create new one if it doesn't exist
    */
   async _loadIdentity() {
     if (this.identityPath) {
       try {
-        this._identity = await Identity.load(this.identityPath);
+        // Check if identity file exists
+        const exists = await Identity.exists(this.identityPath);
+        if (exists) {
+          this._identity = await Identity.load(this.identityPath);
+        } else {
+          // Generate new identity and save it
+          this._identity = Identity.generate(this.name);
+          await this._identity.save(this.identityPath);
+        }
         this.name = this._identity.name;
         this.pubkey = this._identity.pubkey;
       } catch (err) {
-        throw new Error(`Failed to load identity from ${this.identityPath}: ${err.message}`);
+        throw new Error(`Failed to load/create identity at ${this.identityPath}: ${err.message}`);
       }
     }
   }

package/lib/supervisor/USAGE.md

@@ -0,0 +1,110 @@
+# Agent Supervisor System
+
+Robust daemon management for Claude agents with automatic restart and state persistence.
+
+## Why This Exists
+
+Claude's built-in resume is unreliable. This system:
+- Saves agent state externally to files
+- Auto-restarts with exponential backoff
+- Feeds previous context back on restart
+- Lets agents save their own state before shutdown
+
+## Quick Start
+
+```bash
+# Add to PATH
+export PATH="$PATH:$HOME/dev/claude/agentchat/lib/supervisor"
+
+# Start an agent
+agentctl start monitor "monitor agentchat #general, respond to messages, moderate spam"
+
+# Check status
+agentctl status
+
+# View logs
+agentctl logs monitor
+
+# Stop gracefully
+agentctl stop monitor
+
+# Force kill
+agentctl kill monitor
+
+# Stop all agents
+agentctl stopall
+```
+
+## Agent Self-Persistence
+
+Inside your agent prompt, include instructions like:
+
+```
+IMPORTANT: You are running under a supervisor that will restart you on failure.
+
+Your state directory: ~/.agentchat/agents/YOUR_NAME/
+- context.md: Save important state here BEFORE doing risky operations
+- Read this file on startup to resume your work
+
+Before any operation that might fail:
+1. Write current task to context.md
+2. Do the operation
+3. Update context.md with result
+
+On quota warnings or before shutdown:
+- Save everything important to context.md
+- Exit gracefully (the supervisor will restart you)
+```
+
+## File Structure
+
+```
+~/.agentchat/agents/
+└── <agent-name>/
+    ├── supervisor.pid   # Supervisor process ID
+    ├── state.json       # Current state (managed by supervisor)
+    ├── mission.txt      # Original mission prompt
+    ├── context.md       # Agent-managed context (survives restarts)
+    └── supervisor.log   # Supervisor logs
+```
+
+## Backoff Strategy
+
+- Starts at 5 seconds
+- Doubles on each failure (5 → 10 → 20 → 40 → 80 → 160 → 300)
+- Caps at 5 minutes
+- Resets if agent runs for >5 minutes before crashing
+
+## Graceful Shutdown
+
+Agents can check for stop signals:
+```bash
+# In bash
+if [ -f ~/.agentchat/agents/YOUR_NAME/stop ]; then
+  echo "Shutdown requested, saving state..."
+  exit 0
+fi
+```
+
+## Multiple Agents
+
+You can run multiple specialized agents:
+
+```bash
+agentctl start monitor "monitor agentchat, moderate, respond to questions"
+agentctl start social "manage moltx/moltbook, post updates, engage with mentions"
+agentctl start builder "work on assigned tasks from #tasks channel"
+```
+
+## Viewing All State
+
+```bash
+# Status of all agents
+agentctl status
+
+# List registered agents
+agentctl list
+
+# View specific agent's saved context
+agentctl context monitor
+```

package/lib/supervisor/agent-supervisor.sh

@@ -0,0 +1,135 @@
+#!/bin/bash
+# Agent Supervisor - manages Claude agent lifecycle with automatic restart and backoff
+# Usage: ./agent-supervisor.sh <agent-name> <mission>
+
+set -e
+
+AGENT_NAME="${1:-default}"
+MISSION="${2:-monitor agentchat and respond to messages}"
+STATE_DIR="$HOME/.agentchat/agents/$AGENT_NAME"
+LOG_FILE="$STATE_DIR/supervisor.log"
+PID_FILE="$STATE_DIR/supervisor.pid"
+STOP_FILE="$STATE_DIR/stop"
+STATE_FILE="$STATE_DIR/state.json"
+
+# Backoff settings
+MIN_BACKOFF=5
+MAX_BACKOFF=300
+BACKOFF_MULTIPLIER=2
+
+mkdir -p "$STATE_DIR"
+
+log() {
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] $1" | tee -a "$LOG_FILE"
+}
+
+save_state() {
+    local status="$1"
+    local error="$2"
+    cat > "$STATE_FILE" << EOF
+{
+  "agent_name": "$AGENT_NAME",
+  "mission": "$MISSION",
+  "status": "$status",
+  "last_error": "$error",
+  "restart_count": $RESTART_COUNT,
+  "started_at": "$STARTED_AT",
+  "updated_at": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
+  "pid": $$
+}
+EOF
+}
+
+cleanup() {
+    log "Supervisor shutting down"
+    save_state "stopped" ""
+    rm -f "$PID_FILE"
+    exit 0
+}
+
+trap cleanup SIGINT SIGTERM
+
+# Check if already running
+if [ -f "$PID_FILE" ]; then
+    OLD_PID=$(cat "$PID_FILE")
+    if ps -p "$OLD_PID" > /dev/null 2>&1; then
+        log "Supervisor already running (PID $OLD_PID)"
+        exit 1
+    fi
+fi
+
+echo $$ > "$PID_FILE"
+rm -f "$STOP_FILE"
+
+RESTART_COUNT=0
+BACKOFF=$MIN_BACKOFF
+STARTED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+log "Starting supervisor for agent '$AGENT_NAME'"
+log "Mission: $MISSION"
+save_state "starting" ""
+
+while true; do
+    # Check for stop signal
+    if [ -f "$STOP_FILE" ]; then
+        log "Stop file detected, shutting down"
+        rm -f "$STOP_FILE"
+        cleanup
+    fi
+
+    log "Starting agent (attempt $((RESTART_COUNT + 1)), backoff ${BACKOFF}s)"
+    save_state "running" ""
+
+    # Build the resume prompt with state context
+    RESUME_PROMPT="You are agent '$AGENT_NAME'. Your mission: $MISSION
+
+IMPORTANT: You are being restarted by a supervisor. Check your state file at:
+$STATE_FILE
+
+Read ~/.agentchat/agents/$AGENT_NAME/context.md for any saved context from your previous run.
+Before doing significant work, save your current task to context.md so you can resume if interrupted.
+
+On quota errors or before shutdown, write your current state to context.md.
+
+Begin your mission now."
+
+    # Run claude with the mission
+    START_TIME=$(date +%s)
+
+    if claude -p "$RESUME_PROMPT" 2>> "$LOG_FILE"; then
+        # Clean exit
+        log "Agent exited cleanly"
+        BACKOFF=$MIN_BACKOFF
+    else
+        EXIT_CODE=$?
+        END_TIME=$(date +%s)
+        DURATION=$((END_TIME - START_TIME))
+
+        log "Agent crashed (exit code $EXIT_CODE, ran for ${DURATION}s)"
+        save_state "crashed" "exit_code=$EXIT_CODE"
+
+        # If it ran for more than 5 minutes, reset backoff
+        if [ $DURATION -gt 300 ]; then
+            BACKOFF=$MIN_BACKOFF
+            log "Ran long enough, resetting backoff"
+        else
+            # Exponential backoff
+            BACKOFF=$((BACKOFF * BACKOFF_MULTIPLIER))
+            if [ $BACKOFF -gt $MAX_BACKOFF ]; then
+                BACKOFF=$MAX_BACKOFF
+            fi
+        fi
+    fi
+
+    RESTART_COUNT=$((RESTART_COUNT + 1))
+
+    # Check for stop signal before sleeping
+    if [ -f "$STOP_FILE" ]; then
+        log "Stop file detected, shutting down"
+        rm -f "$STOP_FILE"
+        cleanup
+    fi
+
+    log "Waiting ${BACKOFF}s before restart..."
+    sleep $BACKOFF
+done

package/lib/supervisor/agentctl.sh

@@ -0,0 +1,250 @@
+#!/bin/bash
+# agentctl - manage supervised Claude agents
+# Usage: agentctl <command> [agent-name] [options]
+
+AGENTS_DIR="$HOME/.agentchat/agents"
+SCRIPT_DIR="$(cd "$(dirname "$(readlink -f "$0" 2>/dev/null || echo "$0")")" && pwd)"
+SUPERVISOR_SCRIPT="$SCRIPT_DIR/agent-supervisor.sh"
+
+usage() {
+    cat << EOF
+Usage: agentctl <command> [agent-name] [options]
+
+Commands:
+  start <name> <mission>   Start a new supervised agent
+  stop <name>              Stop an agent gracefully
+  kill <name>              Force kill an agent
+  restart <name>           Restart an agent
+  status [name]            Show agent status (all if no name)
+  logs <name> [lines]      Show agent logs
+  list                     List all agents
+  context <name>           Show agent's saved context
+  stopall                  Stop all agents
+
+Examples:
+  agentctl start monitor "monitor agentchat #general and moderate"
+  agentctl start social "manage moltx and moltbook social media"
+  agentctl stop monitor
+  agentctl status
+EOF
+}
+
+start_agent() {
+    local name="$1"
+    local mission="$2"
+
+    if [ -z "$name" ] || [ -z "$mission" ]; then
+        echo "Usage: agentctl start <name> <mission>"
+        exit 1
+    fi
+
+    local state_dir="$AGENTS_DIR/$name"
+    mkdir -p "$state_dir"
+
+    # Check if already running
+    if [ -f "$state_dir/supervisor.pid" ]; then
+        local pid=$(cat "$state_dir/supervisor.pid")
+        if ps -p "$pid" > /dev/null 2>&1; then
+            echo "Agent '$name' already running (PID $pid)"
+            exit 1
+        fi
+    fi
+
+    # Save mission for restarts
+    echo "$mission" > "$state_dir/mission.txt"
+
+    # Initialize context file
+    if [ ! -f "$state_dir/context.md" ]; then
+        cat > "$state_dir/context.md" << EOF
+# Agent: $name
+## Mission
+$mission
+
+## Current State
+Starting fresh.
+
+## Notes
+(Save important context here before shutdown)
+EOF
+    fi
+
+    echo "Starting agent '$name'..."
+    nohup "$SUPERVISOR_SCRIPT" "$name" "$mission" > /dev/null 2>&1 &
+    echo "Agent '$name' started (supervisor PID $!)"
+}
+
+stop_agent() {
+    local name="$1"
+    local state_dir="$AGENTS_DIR/$name"
+
+    if [ ! -d "$state_dir" ]; then
+        echo "Agent '$name' not found"
+        exit 1
+    fi
+
+    # Create stop file for graceful shutdown
+    touch "$state_dir/stop"
+    echo "Stop signal sent to '$name'"
+
+    # Wait a moment then check
+    sleep 2
+    if [ -f "$state_dir/supervisor.pid" ]; then
+        local pid=$(cat "$state_dir/supervisor.pid")
+        if ps -p "$pid" > /dev/null 2>&1; then
+            echo "Agent still running, waiting..."
+            sleep 5
+            if ps -p "$pid" > /dev/null 2>&1; then
+                echo "Agent didn't stop gracefully, use 'agentctl kill $name'"
+            fi
+        else
+            echo "Agent '$name' stopped"
+        fi
+    fi
+}
+
+kill_agent() {
+    local name="$1"
+    local state_dir="$AGENTS_DIR/$name"
+
+    if [ ! -d "$state_dir" ]; then
+        echo "Agent '$name' not found"
+        exit 1
+    fi
+
+    if [ -f "$state_dir/supervisor.pid" ]; then
+        local pid=$(cat "$state_dir/supervisor.pid")
+        if ps -p "$pid" > /dev/null 2>&1; then
+            # Kill the supervisor and its children
+            pkill -P "$pid" 2>/dev/null
+            kill "$pid" 2>/dev/null
+            rm -f "$state_dir/supervisor.pid"
+            echo "Agent '$name' killed"
+        else
+            echo "Agent '$name' not running"
+            rm -f "$state_dir/supervisor.pid"
+        fi
+    else
+        echo "No PID file for '$name'"
+    fi
+}
+
+show_status() {
+    local name="$1"
+
+    if [ -n "$name" ]; then
+        local state_dir="$AGENTS_DIR/$name"
+        if [ -f "$state_dir/state.json" ]; then
+            cat "$state_dir/state.json" | python3 -m json.tool 2>/dev/null || cat "$state_dir/state.json"
+        else
+            echo "No state file for '$name'"
+        fi
+    else
+        echo "=== Agent Status ==="
+        for dir in "$AGENTS_DIR"/*/; do
+            if [ -d "$dir" ]; then
+                local agent=$(basename "$dir")
+                local status="unknown"
+                local pid=""
+
+                if [ -f "$dir/state.json" ]; then
+                    status=$(python3 -c "import json; print(json.load(open('$dir/state.json')).get('status', 'unknown'))" 2>/dev/null || echo "unknown")
+                fi
+
+                if [ -f "$dir/supervisor.pid" ]; then
+                    pid=$(cat "$dir/supervisor.pid")
+                    if ! ps -p "$pid" > /dev/null 2>&1; then
+                        status="dead"
+                        pid=""
+                    fi
+                fi
+
+                printf "%-15s %-10s %s\n" "$agent" "$status" "${pid:+PID $pid}"
+            fi
+        done
+    fi
+}
+
+show_logs() {
+    local name="$1"
+    local lines="${2:-50}"
+    local log_file="$AGENTS_DIR/$name/supervisor.log"
+
+    if [ -f "$log_file" ]; then
+        tail -n "$lines" "$log_file"
+    else
+        echo "No logs for '$name'"
+    fi
+}
+
+list_agents() {
+    echo "=== Registered Agents ==="
+    for dir in "$AGENTS_DIR"/*/; do
+        if [ -d "$dir" ]; then
+            local agent=$(basename "$dir")
+            local mission=""
+            if [ -f "$dir/mission.txt" ]; then
+                mission=$(cat "$dir/mission.txt")
+            fi
+            echo "$agent: $mission"
+        fi
+    done
+}
+
+show_context() {
+    local name="$1"
+    local context_file="$AGENTS_DIR/$name/context.md"
+
+    if [ -f "$context_file" ]; then
+        cat "$context_file"
+    else
+        echo "No context file for '$name'"
+    fi
+}
+
+stop_all() {
+    echo "Stopping all agents..."
+    for dir in "$AGENTS_DIR"/*/; do
+        if [ -d "$dir" ]; then
+            local agent=$(basename "$dir")
+            touch "$dir/stop"
+            echo "Stop signal sent to '$agent'"
+        fi
+    done
+}
+
+# Main
+case "$1" in
+    start)
+        start_agent "$2" "$3"
+        ;;
+    stop)
+        stop_agent "$2"
+        ;;
+    kill)
+        kill_agent "$2"
+        ;;
+    restart)
+        stop_agent "$2"
+        sleep 3
+        mission=$(cat "$AGENTS_DIR/$2/mission.txt" 2>/dev/null)
+        start_agent "$2" "$mission"
+        ;;
+    status)
+        show_status "$2"
+        ;;
+    logs)
+        show_logs "$2" "$3"
+        ;;
+    list)
+        list_agents
+        ;;
+    context)
+        show_context "$2"
+        ;;
+    stopall)
+        stop_all
+        ;;
+    *)
+        usage
+        ;;
+esac

package/lib/supervisor/killswitch.sh

@@ -0,0 +1,36 @@
+#!/bin/bash
+# Kill switch checker - stops all agents if kill file exists
+# Kill file locations (check any of these):
+# 1. iCloud: ~/Library/Mobile Documents/com~apple~CloudDocs/KILL_AGENTS
+# 2. Local: ~/.agentchat/KILL
+# 3. Dropbox: ~/Dropbox/KILL_AGENTS (if exists)
+
+ICLOUD_KILL="$HOME/Library/Mobile Documents/com~apple~CloudDocs/KILL_AGENTS"
+LOCAL_KILL="$HOME/.agentchat/KILL"
+DROPBOX_KILL="$HOME/Dropbox/KILL_AGENTS"
+
+check_kill() {
+    if [ -f "$ICLOUD_KILL" ] || [ -f "$LOCAL_KILL" ] || [ -f "$DROPBOX_KILL" ]; then
+        return 0  # Kill signal found
+    fi
+    return 1  # No kill signal
+}
+
+if check_kill; then
+    echo "KILL SIGNAL DETECTED"
+    echo "Stopping all agents..."
+
+    # Stop all supervised agents
+    "$HOME/bin/agentctl" stopall 2>/dev/null
+
+    # Kill any claude processes
+    pkill -f "claude" 2>/dev/null
+
+    # Clean up kill files
+    rm -f "$ICLOUD_KILL" "$LOCAL_KILL" "$DROPBOX_KILL" 2>/dev/null
+
+    echo "All agents terminated."
+    exit 1
+fi
+
+exit 0

package/lib/supervisor/notify.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+# Send notification to phone via ntfy.sh (free, no signup needed)
+# Usage: notify.sh "title" "message" [priority]
+# Priority: 1=min, 2=low, 3=default, 4=high, 5=urgent
+
+TOPIC="agentchat-james-$(whoami | md5sum | cut -c1-8)"  # Unique topic
+TITLE="${1:-Agent Alert}"
+MESSAGE="${2:-Something happened}"
+PRIORITY="${3:-3}"
+
+# Send via ntfy.sh
+curl -s \
+    -H "Title: $TITLE" \
+    -H "Priority: $PRIORITY" \
+    -H "Tags: robot" \
+    -d "$MESSAGE" \
+    "https://ntfy.sh/$TOPIC" > /dev/null
+
+echo "Notification sent to ntfy.sh/$TOPIC"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tjamescouch/agentchat",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Real-time IRC-like communication protocol for AI agents",
   "main": "lib/client.js",
   "files": [