bmalph 2.7.4 → 2.7.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bmalph",
-  "version": "2.7.4",
+  "version": "2.7.5",
   "description": "Unified AI Development Framework - BMAD phases with Ralph execution loop",
   "type": "module",
   "bin": {

package/ralph/RALPH-REFERENCE.md

@@ -85,13 +85,19 @@ Ralph maintains session continuity across loop iterations using `--resume` with
 
 Ralph uses `--resume <session_id>` instead of `--continue` to resume sessions. This ensures Ralph only resumes its own saved sessions and avoids hijacking unrelated active sessions.
 
+This applies to every driver that exposes resumable IDs today:
+
+- Claude Code
+- OpenAI Codex
+- Cursor
+
 ### Session Files
 
 | File | Purpose |
 |------|---------|
 | `.ralph/.ralph_session` | Current session ID and timestamps |
 | `.ralph/.ralph_session_history` | History of last 50 session transitions |
-| `.ralph/.claude_session_id` | Persisted driver session ID (shared filename for historical reasons) |
+| `.ralph/.claude_session_id` | Persisted driver session ID (shared filename for historical reasons; used by Claude Code, Codex, and Cursor) |
 
 ### Session Lifecycle
 
@@ -256,7 +262,9 @@ bash .ralph/ralph_loop.sh --monitor --live # Live streaming with tmux monitoring
 
 ### How It Works
 
-- Switches output format to `stream-json` and pipes through `jq` for human-readable display
+- Live mode switches the active driver to its structured streaming format and pipes the stream through `jq`
+- Cursor background loop execution stays on `json` output and switches to `stream-json` for live display
+- Claude Code also uses `stream-json` for live display, while Codex streams its native JSONL events directly
 - Shows text deltas and tool invocations in real-time
 - Requires `jq` and `stdbuf` (from coreutils); falls back to background mode if unavailable
 
@@ -341,6 +349,20 @@ When using `--monitor` with `--live`, tmux creates a 3-pane layout:
 2. Start a new session with `bash .ralph/ralph_loop.sh --reset-session`
 3. Context will be rebuilt from `@fix_plan.md` and `specs/`
 
+#### Cursor preflight fails
+
+**Symptoms:** `bmalph doctor` or `bmalph run --driver cursor` fails before the loop starts
+
+**Causes:**
+- `command -v jq` fails in the bash environment Ralph uses
+- `command -v cursor-agent` fails in that same bash environment
+- `cursor-agent status` reports an authentication problem
+
+**Solutions:**
+1. Run `command -v jq` in the same bash shell Ralph uses and install `jq` if missing
+2. Run `command -v cursor-agent` and ensure the official Cursor CLI is on the bash `PATH`
+3. Run `cursor-agent status` and sign in to Cursor before starting Ralph
+
 ### Diagnostic Commands
 
 ```bash
@@ -383,12 +405,14 @@ Loop execution logs are stored in `.ralph/logs/`:
   "calls_made_this_hour": 25,
   "max_calls_per_hour": 100,
   "last_action": "description",
-  "status": "running|paused|complete",
+  "status": "running|completed|halted|paused|stopped|success|graceful_exit|error",
   "exit_reason": "reason (if exited)",
   "next_reset": "timestamp for rate limit reset"
 }
 ```
 
+`bmalph status` normalizes these raw bash values to `running`, `blocked`, `completed`, `not_started`, or `unknown`.
+
 ---
 
 ## Error Detection

package/ralph/drivers/cursor.sh

@@ -1,11 +1,7 @@
 #!/bin/bash
-# Cursor CLI driver for Ralph (EXPERIMENTAL)
-# Provides platform-specific CLI invocation logic for Cursor CLI.
-#
-# Known limitations:
-# - CLI is in beta — binary name and flags may change
-# - NDJSON stream format assumes {type: "text", content: "..."} events
-# - Session continuity is disabled until Cursor exposes a stable capturable session ID
+# Cursor CLI driver for Ralph
+# Uses the documented cursor-agent contract for background execution and
+# switches to stream-json only for live display paths.
 
 driver_name() {
     echo "cursor"
@@ -42,7 +38,6 @@ driver_check_available() {
     command -v "$cli_binary" &>/dev/null
 }
 
-# Cursor CLI tool names
 driver_valid_tools() {
     VALID_TOOL_PATTERNS=(
         "file_edit"
@@ -53,10 +48,6 @@ driver_valid_tools() {
     )
 }
 
-# Build Cursor CLI command
-# Context is prepended to the prompt (same pattern as Codex/Copilot drivers).
-# Uses --print for headless mode, --force for autonomous execution,
-# --output-format stream-json for NDJSON streaming.
 driver_build_command() {
     local prompt_file=$1
     local loop_context=$2
@@ -76,16 +67,12 @@ driver_build_command() {
         CLAUDE_CMD_ARGS+=("$cli_binary")
     fi
 
-    # Headless mode
-    CLAUDE_CMD_ARGS+=("--print")
+    CLAUDE_CMD_ARGS+=("-p" "--force" "--output-format" "json")
 
-    # Autonomous execution
-    CLAUDE_CMD_ARGS+=("--force")
-
-    # NDJSON streaming output
-    CLAUDE_CMD_ARGS+=("--output-format" "stream-json")
+    if [[ "$CLAUDE_USE_CONTINUE" == "true" && -n "$session_id" ]]; then
+        CLAUDE_CMD_ARGS+=("--resume" "$session_id")
+    fi
 
-    # Build prompt with context prepended
     local prompt_content
     if driver_running_on_windows; then
         prompt_content=$(driver_build_windows_bootstrap_prompt "$loop_context" "$prompt_file")
@@ -102,20 +89,43 @@ $prompt_content"
 }
 
 driver_supports_sessions() {
-    return 1  # false — session IDs are not capturable from current NDJSON output
+    return 0
 }
 
 driver_supports_live_output() {
-    return 0  # true
+    return 0
 }
 
 driver_prepare_live_command() {
-    LIVE_CMD_ARGS=("${CLAUDE_CMD_ARGS[@]}")
+    LIVE_CMD_ARGS=()
+    local skip_next=false
+
+    for arg in "${CLAUDE_CMD_ARGS[@]}"; do
+        if [[ "$skip_next" == "true" ]]; then
+            LIVE_CMD_ARGS+=("stream-json")
+            skip_next=false
+        elif [[ "$arg" == "--output-format" ]]; then
+            LIVE_CMD_ARGS+=("$arg")
+            skip_next=true
+        else
+            LIVE_CMD_ARGS+=("$arg")
+        fi
+    done
+
+    if [[ "$skip_next" == "true" ]]; then
+        return 1
+    fi
 }
 
-# Cursor CLI outputs NDJSON events
 driver_stream_filter() {
-    echo 'select(.type == "text") | .content // empty'
+    echo '
+        if .type == "assistant" then
+            [(.message.content[]? | select(.type == "text") | .text)] | join("\n")
+        elif .type == "tool_call" then
+            "\n\n⚡ [" + (.tool_call.name // .name // "tool_call") + "]\n"
+        else
+            empty
+        end'
 }
 
 driver_running_on_windows() {
@@ -208,10 +218,18 @@ driver_localappdata_cli_binary() {
         local_app_data=$(cygpath -u "$local_app_data")
     fi
 
-    local candidate="$local_app_data/cursor-agent/agent.cmd"
-    if [[ -f "$candidate" ]]; then
-        echo "$candidate"
-    fi
+    local candidates=(
+        "$local_app_data/cursor-agent/cursor-agent.cmd"
+        "$local_app_data/cursor-agent/agent.cmd"
+    )
+
+    local candidate
+    for candidate in "${candidates[@]}"; do
+        if [[ -f "$candidate" ]]; then
+            echo "$candidate"
+            return 0
+        fi
+    done
 }
 
 driver_wrapper_path() {

package/ralph/lib/response_analyzer.sh

@@ -97,6 +97,37 @@ normalize_codex_jsonl_response() {
     ' "$output_file" > "$normalized_file"
 }
 
+# Normalize Cursor stream-json event output into the object shape expected downstream.
+normalize_cursor_stream_json_response() {
+    local output_file=$1
+    local normalized_file=$2
+
+    jq -rs '
+        def assistant_text($item):
+            [($item.message.content // [])[]? | select(.type == "text") | .text]
+            | join("\n");
+
+        (map(select(.type == "result")) | last // {}) as $result_event
+        | {
+            result: (
+                $result_event.result
+                // (
+                    map(select(.type == "assistant"))
+                    | map(assistant_text(.))
+                    | map(select(length > 0))
+                    | join("\n")
+                )
+            ),
+            sessionId: (
+                $result_event.session_id
+                // (map(select(.type == "system" and .subtype == "init") | .session_id // empty) | first)
+                // ""
+            ),
+            metadata: {}
+        }
+    ' "$output_file" > "$normalized_file"
+}
+
 # Detect whether a multi-document stream matches Codex JSONL events.
 is_codex_jsonl_output() {
     local output_file=$1
@@ -112,6 +143,24 @@ is_codex_jsonl_output() {
     ' < "$output_file" 2>/dev/null
 }
 
+# Detect whether a multi-document stream matches Cursor stream-json events.
+is_cursor_stream_json_output() {
+    local output_file=$1
+
+    jq -n -j '
+        reduce inputs as $item (
+            false;
+            . or (
+                $item.type == "system" or
+                $item.type == "user" or
+                $item.type == "assistant" or
+                $item.type == "tool_call" or
+                $item.type == "result"
+            )
+        )
+    ' < "$output_file" 2>/dev/null
+}
+
 # Normalize structured output to a single object when downstream parsing expects one.
 normalize_json_output() {
     local output_file=$1
@@ -129,6 +178,14 @@ normalize_json_output() {
             return $?
         fi
 
+        local is_cursor_stream_json
+        is_cursor_stream_json=$(is_cursor_stream_json_output "$output_file") || return 1
+
+        if [[ "$is_cursor_stream_json" == "true" ]]; then
+            normalize_cursor_stream_json_response "$output_file" "$normalized_file"
+            return $?
+        fi
+
         return 1
     fi
 
@@ -215,25 +272,45 @@ detect_output_format() {
 
         if [[ "$is_codex_jsonl" == "true" ]]; then
             echo "json"
-        else
+            return
+        fi
+
+        local is_cursor_stream_json
+        is_cursor_stream_json=$(is_cursor_stream_json_output "$output_file") || {
             echo "text"
+            return
+        }
+
+        if [[ "$is_cursor_stream_json" == "true" ]]; then
+            echo "json"
+            return
         fi
-        return
     fi
 
     echo "text"
 }
 
+trim_shell_whitespace() {
+    local value="${1//$'\r'/}"
+
+    value="${value#"${value%%[![:space:]]*}"}"
+    value="${value%"${value##*[![:space:]]}"}"
+
+    printf '%s' "$value"
+}
+
 # Parse JSON response and extract structured fields
 # Creates .ralph/.json_parse_result with normalized analysis data
-# Supports FOUR JSON formats:
+# Supports FIVE JSON formats:
 # 1. Flat format: { status, exit_signal, work_type, files_modified, ... }
 # 2. Claude CLI object format: { result, sessionId, metadata: { files_changed, has_errors, completion_status, ... } }
 # 3. Claude CLI array format: [ {type: "system", ...}, {type: "assistant", ...}, {type: "result", ...} ]
 # 4. Codex JSONL format: {"type":"thread.started",...}\n{"type":"item.completed","item":{...}}
+# 5. Cursor stream-json format: {"type":"assistant",...}\n{"type":"result",...}
 parse_json_response() {
     local output_file=$1
     local result_file="${2:-$RALPH_DIR/.json_parse_result}"
+    local original_output_file=$output_file
     local normalized_file=""
     local json_document_count=""
     local response_shape="object"
@@ -267,7 +344,11 @@ parse_json_response() {
         output_file="$normalized_file"
 
         if [[ "$response_shape" == "jsonl" ]]; then
-            response_shape="codex_jsonl"
+            if is_codex_jsonl_output "$original_output_file" >/dev/null 2>&1; then
+                response_shape="codex_jsonl"
+            else
+                response_shape="cursor_stream_jsonl"
+            fi
         fi
     fi
 
@@ -296,7 +377,7 @@ parse_json_response() {
         if [[ -n "$result_text" ]] && echo "$result_text" | grep -q -- "---RALPH_STATUS---"; then
             # Extract EXIT_SIGNAL value from RALPH_STATUS block within result text
             local embedded_exit_sig
-            embedded_exit_sig=$(echo "$result_text" | grep "EXIT_SIGNAL:" | cut -d: -f2 | tr -d '\r' | xargs)
+            embedded_exit_sig=$(trim_shell_whitespace "$(printf '%s\n' "$result_text" | grep "EXIT_SIGNAL:" | cut -d: -f2)")
             if [[ -n "$embedded_exit_sig" ]]; then
                 # Explicit EXIT_SIGNAL found in RALPH_STATUS block
                 explicit_exit_signal_found="true"
@@ -311,7 +392,7 @@ parse_json_response() {
             # Also check STATUS field as fallback ONLY when EXIT_SIGNAL was not specified
             # This respects explicit EXIT_SIGNAL: false which means "task complete, continue working"
             local embedded_status
-            embedded_status=$(echo "$result_text" | grep "STATUS:" | cut -d: -f2 | tr -d '\r' | xargs)
+            embedded_status=$(trim_shell_whitespace "$(printf '%s\n' "$result_text" | grep "STATUS:" | cut -d: -f2)")
             if [[ "$embedded_status" == "COMPLETE" && "$explicit_exit_signal_found" != "true" ]]; then
                 # STATUS: COMPLETE without any EXIT_SIGNAL field implies completion
                 exit_signal="true"
@@ -341,7 +422,7 @@ parse_json_response() {
     local summary=$(jq -r -j '.result // .summary // ""' "$output_file" 2>/dev/null)
 
     # Session ID: from Claude CLI format (sessionId) OR from metadata.session_id
-    local session_id=$(jq -r -j '.sessionId // .metadata.session_id // ""' "$output_file" 2>/dev/null)
+    local session_id=$(jq -r -j '.sessionId // .metadata.session_id // .session_id // ""' "$output_file" 2>/dev/null)
 
     # Loop number: from metadata
     local loop_number=$(jq -r -j '.metadata.loop_number // .loop_number // 0' "$output_file" 2>/dev/null)
@@ -375,7 +456,7 @@ parse_json_response() {
     # completion markers are absent. This keeps JSONL analysis aligned with text mode.
     local summary_has_completion_keyword="false"
     local summary_has_no_work_pattern="false"
-    if [[ "$response_shape" == "codex_jsonl" && "$explicit_exit_signal_found" != "true" && -n "$summary" ]]; then
+    if [[ "$response_shape" == "codex_jsonl" || "$response_shape" == "cursor_stream_jsonl" ]] && [[ "$explicit_exit_signal_found" != "true" && -n "$summary" ]]; then
         for keyword in "${COMPLETION_KEYWORDS[@]}"; do
             if echo "$summary" | grep -qi "$keyword"; then
                 summary_has_completion_keyword="true"
@@ -639,8 +720,8 @@ analyze_response() {
     # 1. Check for explicit structured output (if Claude follows schema)
     if grep -q -- "---RALPH_STATUS---" "$output_file"; then
         # Parse structured output
-        local status=$(grep "STATUS:" "$output_file" | cut -d: -f2 | tr -d '\r' | xargs)
-        local exit_sig=$(grep "EXIT_SIGNAL:" "$output_file" | cut -d: -f2 | tr -d '\r' | xargs)
+        local status=$(trim_shell_whitespace "$(grep "STATUS:" "$output_file" | cut -d: -f2)")
+        local exit_sig=$(trim_shell_whitespace "$(grep "EXIT_SIGNAL:" "$output_file" | cut -d: -f2)")
 
         # If EXIT_SIGNAL is explicitly provided, respect it
         if [[ -n "$exit_sig" ]]; then
@@ -1093,7 +1174,9 @@ export -f detect_output_format
 export -f count_json_documents
 export -f normalize_cli_array_response
 export -f normalize_codex_jsonl_response
+export -f normalize_cursor_stream_json_response
 export -f is_codex_jsonl_output
+export -f is_cursor_stream_json_output
 export -f normalize_json_output
 export -f extract_session_id_from_output
 export -f parse_json_response