ralphblaster-agent 1.2.0

package/src/index.js

@@ -0,0 +1,243 @@
+const ApiClient = require('./api-client');
+const Executor = require('./executor');
+const config = require('./config');
+const logger = require('./logger');
+
+// Timing constants
+const SHUTDOWN_DELAY_MS = 500;
+const ERROR_RETRY_DELAY_MS = 5000;
+const HEARTBEAT_INTERVAL_MS = 60000;
+
+class RalphAgent {
+  constructor() {
+    this.apiClient = new ApiClient();
+    this.executor = new Executor(this.apiClient);
+    this.isRunning = false;
+    this.currentJob = null;
+    this.heartbeatInterval = null;
+    this.jobCompleting = false; // Flag to prevent heartbeat race conditions
+
+    // Rate limiting state
+    this.consecutiveErrors = 0;
+    this.lastRequestTime = 0;
+    this.minRequestInterval = 1000; // Minimum 1s between requests
+  }
+
+  /**
+   * Start the agent
+   */
+  async start() {
+    this.isRunning = true;
+
+    logger.info('Ralph Agent starting...');
+    logger.info(`API URL: ${config.apiUrl}`);
+
+    // Setup graceful shutdown
+    this.setupShutdownHandlers();
+
+    // Start polling loop
+    await this.pollLoop();
+  }
+
+  /**
+   * Stop the agent
+   */
+  async stop() {
+    logger.info('Ralph Agent stopping...');
+    this.isRunning = false;
+
+    // Stop heartbeat first to prevent updates during shutdown
+    this.stopHeartbeat();
+
+    // Kill any running Claude process
+    if (this.executor.currentProcess) {
+      logger.warn('Terminating running Claude process');
+      await this.executor.killCurrentProcess();
+    }
+
+    // If currently executing a job, mark it as failed
+    if (this.currentJob) {
+      logger.warn(`Marking job #${this.currentJob.id} as failed due to shutdown`);
+      try {
+        await this.apiClient.markJobFailed(
+          this.currentJob.id,
+          'Agent shutdown during execution'
+        );
+      } catch (error) {
+        logger.error('Failed to mark job as failed during shutdown', error.message);
+      }
+    }
+
+    logger.info('Ralph Agent stopped');
+    // Give async operations time to complete before exiting
+    setTimeout(() => process.exit(0), SHUTDOWN_DELAY_MS);
+  }
+
+  /**
+   * Main polling loop with rate limiting and exponential backoff
+   */
+  async pollLoop() {
+    while (this.isRunning) {
+      try {
+        // Enforce minimum interval between requests
+        const now = Date.now();
+        const timeSinceLastRequest = now - this.lastRequestTime;
+        if (timeSinceLastRequest < this.minRequestInterval) {
+          await this.sleep(this.minRequestInterval - timeSinceLastRequest);
+        }
+        this.lastRequestTime = Date.now();
+
+        // Check for next job (long polling - server waits up to 30s)
+        const job = await this.apiClient.getNextJob();
+
+        // Reset error counter on successful API call
+        this.consecutiveErrors = 0;
+
+        if (job) {
+          await this.processJob(job);
+          // After processing, immediately poll for next job
+        } else {
+          // No jobs available after long poll timeout
+          // Small delay before reconnecting to prevent hammering
+          await this.sleep(1000); // 1s minimum between polls
+        }
+      } catch (error) {
+        this.consecutiveErrors++;
+        logger.error(`Error in poll loop (consecutive: ${this.consecutiveErrors})`, error.message);
+
+        // Exponential backoff: 5s, 10s, 20s, 40s, max 60s
+        const backoffTime = Math.min(
+          ERROR_RETRY_DELAY_MS * Math.pow(2, this.consecutiveErrors - 1),
+          60000
+        );
+
+        logger.info(`Backing off for ${backoffTime}ms before retry`);
+        await this.sleep(backoffTime);
+
+        // Circuit breaker: Stop if too many consecutive errors
+        if (this.consecutiveErrors >= 10) {
+          logger.error('Too many consecutive errors (10+), shutting down');
+          await this.stop();
+        }
+      }
+    }
+  }
+
+  /**
+   * Process a job
+   * @param {Object} job - Job object from API
+   */
+  async processJob(job) {
+    this.currentJob = job;
+    this.jobCompleting = false;
+
+    try {
+      // Mark job as running
+      await this.apiClient.markJobRunning(job.id);
+
+      // Start heartbeat to keep job alive
+      this.startHeartbeat(job.id);
+
+      // Execute the job with progress callback
+      const result = await this.executor.execute(job, async (chunk) => {
+        // Send progress update to server
+        try {
+          await this.apiClient.sendProgress(job.id, chunk);
+        } catch (error) {
+          logger.warn(`Failed to send progress update for job #${job.id}`, error.message);
+          // Don't fail the job if progress update fails
+        }
+      });
+
+      // Set flag to prevent heartbeat race conditions, then stop heartbeat
+      this.jobCompleting = true;
+      this.stopHeartbeat();
+
+      // Mark job as completed
+      await this.apiClient.markJobCompleted(job.id, result);
+
+      logger.info(`Job #${job.id} completed successfully`);
+    } catch (error) {
+      // Set flag to prevent heartbeat race conditions, then stop heartbeat
+      this.jobCompleting = true;
+      this.stopHeartbeat();
+
+      // Mark job as failed (pass full error object to include categorization)
+      await this.apiClient.markJobFailed(
+        job.id,
+        error,  // Pass full error object instead of just message
+        error.partialOutput || null
+      );
+
+      logger.error(`Job #${job.id} failed`, error.message);
+    } finally {
+      // Clear current job reference and reset completion flag
+      this.currentJob = null;
+      this.jobCompleting = false;
+    }
+  }
+
+  /**
+   * Start heartbeat for job
+   * @param {number} jobId - Job ID
+   */
+  startHeartbeat(jobId) {
+    // Send heartbeat every 60 seconds to prevent timeout
+    this.heartbeatInterval = setInterval(() => {
+      // Check if job is completing to prevent race conditions
+      if (this.jobCompleting) {
+        logger.debug('Skipping heartbeat - job is completing');
+        return;
+      }
+
+      this.apiClient.sendHeartbeat(jobId).catch(err => {
+        logger.warn('Heartbeat failed', err.message);
+      });
+    }, HEARTBEAT_INTERVAL_MS);
+  }
+
+  /**
+   * Stop heartbeat
+   */
+  stopHeartbeat() {
+    if (this.heartbeatInterval) {
+      clearInterval(this.heartbeatInterval);
+      this.heartbeatInterval = null;
+    }
+  }
+
+  /**
+   * Setup graceful shutdown handlers
+   */
+  setupShutdownHandlers() {
+    process.on('SIGINT', () => {
+      logger.info('Received SIGINT signal');
+      this.stop();
+    });
+
+    process.on('SIGTERM', () => {
+      logger.info('Received SIGTERM signal');
+      this.stop();
+    });
+
+    process.on('uncaughtException', (error) => {
+      logger.error('Uncaught exception', error);
+      this.stop();
+    });
+
+    process.on('unhandledRejection', (reason, promise) => {
+      logger.error('Unhandled rejection', reason);
+      this.stop();
+    });
+  }
+
+  /**
+   * Sleep helper
+   * @param {number} ms - Milliseconds to sleep
+   */
+  sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+  }
+}
+
+module.exports = RalphAgent;

package/src/logger.js

@@ -0,0 +1,96 @@
+const config = require('./config');
+
+const LOG_LEVELS = {
+  error: 0,
+  warn: 1,
+  info: 2,
+  debug: 3
+};
+
+const currentLevel = LOG_LEVELS[config.logLevel] || LOG_LEVELS.info;
+
+/**
+ * Redact sensitive data from logs
+ * @param {any} data - Data to redact
+ * @returns {any} Redacted data
+ */
+function redactSensitiveData(data) {
+  if (!data) return data;
+
+  try {
+    // Convert to string for pattern matching
+    let dataStr = typeof data === 'string' ? data : JSON.stringify(data);
+
+    // Redact common token patterns
+    dataStr = dataStr
+      .replace(/"Authorization":\s*"Bearer [^"]+"/g, '"Authorization": "Bearer [REDACTED]"')
+      .replace(/Authorization:\s*Bearer\s+[^\s,}]+/g, 'Authorization: Bearer [REDACTED]')
+      .replace(/RALPH_API_TOKEN=[^\s&]+/g, 'RALPH_API_TOKEN=[REDACTED]')
+      .replace(/"apiToken":\s*"[^"]+"/g, '"apiToken": "[REDACTED]"')
+      .replace(/"token":\s*"[^"]+"/g, '"token": "[REDACTED]"')
+      .replace(/"api_token":\s*"[^"]+"/g, '"api_token": "[REDACTED]"')
+      .replace(/Bearer\s+[A-Za-z0-9_-]{20,}/g, 'Bearer [REDACTED]');
+
+    // Return in original format
+    if (typeof data === 'string') {
+      return dataStr;
+    } else {
+      try {
+        return JSON.parse(dataStr);
+      } catch {
+        return dataStr; // Return string if can't parse back
+      }
+    }
+  } catch (error) {
+    // If redaction fails, return safe placeholder
+    return '[REDACTION_ERROR]';
+  }
+}
+
+/**
+ * Safe JSON stringify that handles circular references
+ * @param {*} obj - Object to stringify
+ * @returns {string} JSON string or error message
+ */
+function safeStringify(obj) {
+  const seen = new WeakSet();
+  try {
+    return JSON.stringify(obj, (key, value) => {
+      // Handle circular references
+      if (typeof value === 'object' && value !== null) {
+        if (seen.has(value)) {
+          return '[Circular]';
+        }
+        seen.add(value);
+      }
+      return value;
+    }, 2);
+  } catch (error) {
+    return `[Unable to stringify: ${error.message}]`;
+  }
+}
+
+function log(level, message, data = null) {
+  if (LOG_LEVELS[level] <= currentLevel) {
+    const timestamp = new Date().toISOString();
+    const prefix = `[${timestamp}] [${level.toUpperCase()}]`;
+
+    // Redact sensitive data from message
+    const safeMessage = redactSensitiveData(message);
+
+    if (data) {
+      // Redact and stringify data
+      const redactedData = redactSensitiveData(data);
+      console.log(prefix, safeMessage, safeStringify(redactedData));
+    } else {
+      console.log(prefix, safeMessage);
+    }
+  }
+}
+
+module.exports = {
+  error: (msg, data) => log('error', msg, data),
+  warn: (msg, data) => log('warn', msg, data),
+  info: (msg, data) => log('info', msg, data),
+  debug: (msg, data) => log('debug', msg, data)
+};

package/src/ralph/prompt.md

@@ -0,0 +1,165 @@
+# Ralph Agent Instructions
+
+You are an autonomous coding agent working on a software project.
+
+## CRITICAL: Worktree Awareness
+
+This Ralph instance works in an isolated git worktree, NOT the main repository.
+
+**Environment variables (always available):**
+- `RALPH_WORKTREE_PATH`: Your worktree directory where code lives (e.g., ~/src/myproject-worktrees/feature-name)
+- `RALPH_INSTANCE_DIR`: Instance directory where state files live (e.g., ~/src/myproject/ralph-instances/prd-feature)
+- `RALPH_MAIN_REPO`: Main repository path (e.g., ~/src/myproject)
+
+**File locations:**
+- **Code files**: Work in `$RALPH_WORKTREE_PATH` - this is your working directory
+- **State files**: Read/write from `$RALPH_INSTANCE_DIR`:
+  - `$RALPH_INSTANCE_DIR/prd.json` - Your task configuration
+  - `$RALPH_INSTANCE_DIR/progress.txt` - Your progress log
+
+**Working directory rules:**
+1. ALWAYS run code/git operations from worktree: `cd $RALPH_WORKTREE_PATH`
+2. Read/write state files using absolute paths (the environment variables above)
+
+## Permissions
+
+You have FULL PERMISSION to:
+- Edit ANY files in the repository (no need to ask for approval)
+- Write new files as required by user stories
+- Run bash commands for git operations, quality checks, testing, etc.
+- Delete files if necessary for completing user stories
+
+DO NOT wait for permission or approval - you are authorized to make all necessary changes autonomously.
+
+## Your Task
+
+1. Read the PRD at `$RALPH_INSTANCE_DIR/prd.json`
+2. Read the progress log at `$RALPH_INSTANCE_DIR/progress.txt` (check Codebase Patterns section first)
+3. Navigate to worktree: `cd $RALPH_WORKTREE_PATH` (SKIP branch checkout - you're already on the correct branch!)
+4. Pick the **highest priority** user story where `passes: false`
+5. Implement that single user story
+6. Run quality checks (e.g., typecheck, lint, test - use whatever your project requires)
+7. Update AGENTS.md files if you discover reusable patterns (see below)
+8. If checks pass, commit ALL changes with message: `feat: [Story ID] - [Story Title]`
+9. Update the PRD at `$RALPH_INSTANCE_DIR/prd.json` to set `passes: true` for the completed story
+10. Append your progress to `$RALPH_INSTANCE_DIR/progress.txt`
+
+## Example Commands
+
+```bash
+# Read configuration
+cat $RALPH_INSTANCE_DIR/prd.json
+
+# Navigate to worktree
+cd $RALPH_WORKTREE_PATH
+
+# Check git status
+git status
+
+# Make code changes (you're in the worktree)
+# ... edit files, run tests, etc ...
+
+# Run quality checks
+npm run typecheck
+npm test
+
+# Commit changes
+git add .
+git commit -m "feat: US-001 - Add feature"
+
+# Update state files (use absolute paths with environment variables!)
+# Use Edit or Write tool with: $RALPH_INSTANCE_DIR/prd.json
+# Use Edit or Write tool with: $RALPH_INSTANCE_DIR/progress.txt
+```
+
+## Progress Report Format
+
+APPEND to progress.txt (never replace, always append):
+```
+## [Date/Time] - [Story ID]
+Thread: https://ampcode.com/threads/$AMP_CURRENT_THREAD_ID
+- What was implemented
+- Files changed
+- **Learnings for future iterations:**
+  - Patterns discovered (e.g., "this codebase uses X for Y")
+  - Gotchas encountered (e.g., "don't forget to update Z when changing W")
+  - Useful context (e.g., "the evaluation panel is in component X")
+---
+```
+
+Include the thread URL so future iterations can use the `read_thread` tool to reference previous work if needed.
+
+The learnings section is critical - it helps future iterations avoid repeating mistakes and understand the codebase better.
+
+## Consolidate Patterns
+
+If you discover a **reusable pattern** that future iterations should know, add it to the `## Codebase Patterns` section at the TOP of progress.txt (create it if it doesn't exist). This section should consolidate the most important learnings:
+
+```
+## Codebase Patterns
+- Example: Use `sql<number>` template for aggregations
+- Example: Always use `IF NOT EXISTS` for migrations
+- Example: Export types from actions.ts for UI components
+```
+
+Only add patterns that are **general and reusable**, not story-specific details.
+
+## Update AGENTS.md Files
+
+Before committing, check if any edited files have learnings worth preserving in nearby AGENTS.md files:
+
+1. **Identify directories with edited files** - Look at which directories you modified
+2. **Check for existing AGENTS.md** - Look for AGENTS.md in those directories or parent directories
+3. **Add valuable learnings** - If you discovered something future developers/agents should know:
+   - API patterns or conventions specific to that module
+   - Gotchas or non-obvious requirements
+   - Dependencies between files
+   - Testing approaches for that area
+   - Configuration or environment requirements
+
+**Examples of good AGENTS.md additions:**
+- "When modifying X, also update Y to keep them in sync"
+- "This module uses pattern Z for all API calls"
+- "Tests require the dev server running on PORT 3000"
+- "Field names must match the template exactly"
+
+**Do NOT add:**
+- Story-specific implementation details
+- Temporary debugging notes
+- Information already in progress.txt
+
+Only update AGENTS.md if you have **genuinely reusable knowledge** that would help future work in that directory.
+
+## Quality Requirements
+
+- ALL commits must pass your project's quality checks (typecheck, lint, test)
+- Do NOT commit broken code
+- Keep changes focused and minimal
+- Follow existing code patterns
+
+## Browser Testing (Required for Frontend Stories)
+
+For any story that changes UI, you MUST verify it works in the browser:
+
+1. Load the `dev-browser` skill
+2. Navigate to the relevant page
+3. Verify the UI changes work as expected
+4. Take a screenshot if helpful for the progress log
+
+A frontend story is NOT complete until browser verification passes.
+
+## Stop Condition
+
+After completing a user story, check if ALL stories have `passes: true`.
+
+If ALL stories are complete and passing, reply with:
+<promise>COMPLETE</promise>
+
+If there are still stories with `passes: false`, end your response normally (another iteration will pick up the next story).
+
+## Important
+
+- Work on ONE story per iteration
+- Commit frequently
+- Keep CI green
+- Read the Codebase Patterns section in progress.txt before starting