ralphblaster-agent 1.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wildfront LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# Ralph Agent
+
+Ralph Agent is a distributed autonomous coding agent that polls a Rails API for jobs and executes them locally using Claude CLI.
+
+## Features
+
+- 🔄 **Automatic Job Polling**: Continuously polls the Ralph API for new coding jobs
+- 🤖 **Claude CLI Integration**: Executes jobs using the Claude CLI
+- 💪 **Resilient**: Handles failures gracefully with automatic retries and timeouts
+- 🔐 **Secure**: Uses API tokens with specific permissions for authentication
+- 📊 **Real-time Updates**: Reports job progress and status back to the API
+- ⚡ **Heartbeat System**: Keeps jobs alive during long-running executions
+
+## Prerequisites
+
+- Node.js >= 18.0.0
+- Claude CLI installed and available in PATH (`claude --version` should work)
+- A Ralph API token with `ralph_agent` permission
+
+## Installation
+
+### Global Installation
+
+```bash
+npm install -g ralph-agent
+```
+
+### Local Installation
+
+```bash
+git clone <repository>
+cd ralph-agent
+npm install
+```
+
+### Using npx (No Installation Required)
+
+```bash
+npx ralph-agent --token=your_token_here
+```
+
+## Usage
+
+### Basic Usage
+
+```bash
+# Production (default)
+ralph-agent --token=your_api_token_here
+
+# Using environment variable
+RALPH_API_TOKEN=your_api_token_here ralph-agent
+
+# Local development (override API URL)
+ralph-agent --token=your_token --api-url=http://localhost:5002
+```
+
+### Configuration Options
+
+The agent can be configured via environment variables or command-line flags:
+
+| Environment Variable | CLI Flag | Default | Description |
+|---------------------|----------|---------|-------------|
+| `RALPH_API_TOKEN` | `--token=` | *Required* | API authentication token |
+| `RALPH_API_URL` | `--api-url=` | `https://ralphblaster.com` | Ralph API base URL |
+| `RALPH_POLL_INTERVAL` | - | `5000` | Polling interval in milliseconds |
+| `RALPH_LOG_LEVEL` | - | `info` | Log level (error, warn, info, debug) |
+| `RALPH_MAX_RETRIES` | - | `3` | Maximum retry attempts |
+
+### Using .env File
+
+Create a `.env` file in the ralph-agent directory:
+
+```env
+RALPH_API_TOKEN=your_api_token_here
+# RALPH_API_URL=http://localhost:5002  # Uncomment for local development
+RALPH_POLL_INTERVAL=5000
+RALPH_LOG_LEVEL=info
+```
+
+Then run:
+
+```bash
+ralph-agent
+```
+
+## How It Works
+
+1. **Polling**: The agent continuously polls the API endpoint `/api/v1/ralph/jobs/next` for available jobs
+2. **Job Claiming**: When a job is found, it's automatically claimed by the agent
+3. **Status Update**: The agent marks the job as "running" and starts sending heartbeats
+4. **Execution**: The job is executed based on its type:
+   - **PRD Generation**: Uses Claude `/prd` skill or direct prompts
+   - **Code Execution**: Creates a Ralph autonomous agent instance (see below)
+5. **Completion**: Results are parsed and reported back to the API
+6. **Cleanup**: The agent marks the job as completed or failed and continues polling
+
+## Ralph Autonomous Agent Integration
+
+For `code_execution` job types, the agent uses the Ralph autonomous system - an iterative, PRD-driven execution framework that enables complex, multi-step implementations.
+
+### How Ralph Works
+
+1. **Worktree Creation**: Creates an isolated git worktree for the job
+2. **Instance Setup**: Creates a `ralph-instance/` directory with:
+   - `prd.json` - Converted from the job prompt using Claude `/ralph` skill
+   - `ralph.sh` - The autonomous agent loop script
+   - `prompt.md` - Agent instructions
+   - `progress.txt` - Progress tracking log
+3. **Iterative Execution**: Ralph runs up to 10 iterations, each:
+   - Reading the PRD and current progress
+   - Selecting the next highest-priority user story
+   - Implementing the story in the worktree
+   - Running quality checks (tests, typecheck, lint)
+   - Committing changes
+   - Updating the PRD to mark the story as complete
+   - Logging progress
+4. **Completion Detection**: Ralph signals completion with `<promise>COMPLETE</promise>` when all stories pass
+5. **Progress Reporting**: Real-time updates from `progress.txt` are sent back to the API
+
+### Ralph Directory Structure
+
+```
+.ralph-worktrees/job-{id}/
+├── ralph-instance/              # Ralph state directory
+│   ├── ralph.sh                 # Execution loop
+│   ├── prompt.md                # Agent instructions
+│   ├── prd.json                 # Generated PRD with user stories
+│   ├── progress.txt             # Progress log
+│   └── .worktree-path           # Worktree location reference
+└── [project files...]           # Isolated worktree content
+```
+
+### Environment Variables for Ralph
+
+Ralph execution uses these environment variables:
+
+- `RALPH_WORKTREE_PATH` - Path to the git worktree
+- `RALPH_INSTANCE_DIR` - Path to the Ralph instance directory
+- `RALPH_MAIN_REPO` - Path to the main repository
+
+### Ralph Execution Limits
+
+- **Max Iterations**: 10
+- **Timeout**: 2 hours
+- **Completion**: All user stories must pass quality checks
+
+### Advantages of Ralph Integration
+
+- **Structured Approach**: PRD-driven development ensures clear requirements
+- **Quality Assurance**: Each story is validated with tests before proceeding
+- **Progress Tracking**: Detailed logs of what was accomplished
+- **Isolation**: Git worktrees keep work separate from main repository
+- **Iterative Refinement**: Can fix issues and retry failed stories automatically
+
+## API Token Setup
+
+To create an API token with ralph_agent permission:
+
+1. Log into your Ralph account
+2. Navigate to API Tokens settings
+3. Create a new token
+4. Check the "Ralph Agent Access" permission
+5. Copy the token (shown only once!)
+
+## Example Output
+
+```
+[2026-01-16T20:00:00.000Z] [INFO]
+╔═══════════════════════════════════════╗
+║      Ralph Agent Starting...          ║
+╚═══════════════════════════════════════╝
+
+[2026-01-16T20:00:00.123Z] [INFO] Ralph Agent starting...
+[2026-01-16T20:00:00.124Z] [INFO] API URL: https://ralphblaster.com
+[2026-01-16T20:00:00.125Z] [INFO] Poll interval: 5000ms
+[2026-01-16T20:00:05.234Z] [INFO] Claimed job #42 - Implement user authentication
+[2026-01-16T20:00:05.345Z] [INFO] Job #42 marked as running
+[2026-01-16T20:00:05.456Z] [INFO] Executing job #42 in /path/to/project
+[2026-01-16T20:05:30.789Z] [INFO] Job #42 marked as completed
+[2026-01-16T20:05:30.890Z] [INFO] Job #42 completed successfully
+```
+
+## Graceful Shutdown
+
+The agent handles shutdown signals gracefully:
+
+- `SIGINT` (Ctrl+C): Marks current job as failed and exits
+- `SIGTERM`: Same as SIGINT
+- Uncaught exceptions: Logged and triggers shutdown
+
+## Troubleshooting
+
+### "API token requires 'ralph_agent' permission"
+
+Your API token doesn't have the correct permissions. Create a new token with the `ralph_agent` permission checked.
+
+### "Cannot connect to API"
+
+Check that:
+- The API URL is correct
+- The Rails server is running
+- There are no firewall issues
+
+### "Failed to execute Claude CLI"
+
+Ensure:
+- Claude CLI is installed (`claude --version`)
+- Claude CLI is in your PATH
+- You're authenticated with Claude
+
+### "Project path does not exist"
+
+The project's `system_path` in Ralph is incorrect or the directory doesn't exist on your machine.
+
+## Development
+
+### Running Locally
+
+```bash
+npm start
+```
+
+### Debugging
+
+Enable debug logging:
+
+```bash
+RALPH_LOG_LEVEL=debug ralph-agent --token=your_token
+```
+
+## Architecture
+
+```
+┌─────────────────┐         ┌──────────────────┐
+│  Ralph Agent    │         │   Rails API      │
+│                 │         │                  │
+│  ┌──────────┐   │  Poll   │  ┌────────────┐  │
+│  │  Polling │───┼────────>│  │ Job Queue  │  │
+│  │   Loop   │   │         │  └────────────┘  │
+│  └──────────┘   │         │                  │
+│       │         │  Claim  │                  │
+│       ▼         │<────────┤                  │
+│  ┌──────────┐   │         │                  │
+│  │ Executor │   │         │                  │
+│  │  (Claude)│   │ Status  │                  │
+│  └──────────┘   │────────>│                  │
+│                 │         │                  │
+└─────────────────┘         └──────────────────┘
+```
+
+## License
+
+MIT

package/bin/ralph-agent.js

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+// Parse command line arguments BEFORE loading modules that use config
+const args = process.argv.slice(2);
+
+// Check for --token flag
+const tokenIndex = args.findIndex(arg => arg.startsWith('--token='));
+if (tokenIndex !== -1) {
+  const token = args[tokenIndex].split('=')[1];
+  if (!token || token.trim() === '') {
+    console.error('Error: --token flag requires a value');
+    process.exit(1);
+  }
+  process.env.RALPH_API_TOKEN = token;
+}
+
+// Check for --api-url flag
+const apiUrlIndex = args.findIndex(arg => arg.startsWith('--api-url='));
+if (apiUrlIndex !== -1) {
+  const apiUrl = args[apiUrlIndex].split('=')[1];
+  if (!apiUrl || apiUrl.trim() === '') {
+    console.error('Error: --api-url flag requires a value');
+    process.exit(1);
+  }
+  process.env.RALPH_API_URL = apiUrl;
+}
+
+// Show help
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+Ralph Agent - Autonomous coding agent for Ralph
+
+Usage:
+  ralph-agent [options]
+
+Options:
+  --token=<token>       API token for authentication (required)
+  --api-url=<url>       API base URL (default: https://ralphblaster.com)
+  --help, -h            Show this help message
+
+Environment Variables:
+  RALPH_API_TOKEN       API token (required if not using --token)
+  RALPH_API_URL         API base URL (default: https://ralphblaster.com)
+  RALPH_LOG_LEVEL       Log level: error, warn, info, debug (default: info)
+  RALPH_ALLOWED_PATHS   Colon-separated list of allowed base paths for projects
+                        (optional security whitelist, e.g., /Users/me/projects:/home/me/work)
+
+Examples:
+  # Run with token from command line
+  ralph-agent --token=your_token_here
+
+  # Run with environment variable
+  RALPH_API_TOKEN=your_token_here ralph-agent
+
+  # Run with custom API URL
+  ralph-agent --token=your_token --api-url=http://localhost:3000
+
+  # Use npx
+  npx ralph-agent --token=your_token_here
+  `);
+  process.exit(0);
+}
+
+// Check for version
+if (args.includes('--version') || args.includes('-v')) {
+  const packageJson = require('../package.json');
+  console.log(`ralph-agent v${packageJson.version}`);
+  process.exit(0);
+}
+
+// Load modules AFTER environment variables are set
+const RalphAgent = require('../src/index');
+const logger = require('../src/logger');
+
+// Start the agent
+const agent = new RalphAgent();
+
+logger.info('');
+logger.info('╔═══════════════════════════════════════╗');
+logger.info('║      Ralph Agent Starting...          ║');
+logger.info('╚═══════════════════════════════════════╝');
+logger.info('');
+
+agent.start().catch(error => {
+  logger.error('Fatal error starting agent', error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "ralphblaster-agent",
+  "version": "1.2.0",
+  "description": "Ralph agent that polls for and executes coding jobs via Claude CLI",
+  "main": "src/index.js",
+  "bin": {
+    "ralphblaster-agent": "bin/ralph-agent.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "start": "node bin/ralph-agent.js",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "test:coverage": "jest --coverage"
+  },
+  "keywords": [
+    "ralph",
+    "agent",
+    "claude",
+    "automation"
+  ],
+  "author": "Wildfront LLC <m@wildfront.co>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Wildfront/ralphblaster-agent.git"
+  },
+  "homepage": "https://github.com/Wildfront/ralphblaster-agent#readme",
+  "bugs": {
+    "url": "https://github.com/Wildfront/ralphblaster-agent/issues"
+  },
+  "dependencies": {
+    "axios": "^1.6.0",
+    "dotenv": "^16.3.1"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.14",
+    "jest": "^29.7.0"
+  },
+  "jest": {
+    "testEnvironment": "node",
+    "coverageDirectory": "coverage",
+    "collectCoverageFrom": [
+      "src/**/*.js",
+      "!src/logger.js"
+    ],
+    "testMatch": [
+      "**/test/**/*.test.js"
+    ]
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}