grok-cli-acp 0.1.2

package/docs/settings.md

@@ -0,0 +1,293 @@
+# Grok CLI Settings (`settings` command)
+
+Grok CLI provides a powerful settings system using `.env` files with hierarchical configuration.
+
+## Configuration Files
+
+- **System settings**: `~/.grok/.env` (Linux/macOS) or `%USERPROFILE%\.grok\.env` (Windows)
+- **Project settings**: `.grok/.env` (in your project directory)
+
+Note: Project settings override system settings. Environment variables override all files.
+
+## Using the Settings Command
+
+### Interactive Settings Browser
+```bash
+# Launch interactive settings browser
+grok settings show
+
+# Edit settings interactively
+grok settings edit
+```
+
+### Reset Settings
+```bash
+# Reset all settings to defaults
+grok settings reset
+
+# Reset specific category to defaults
+grok settings reset --category ui
+grok settings reset --category general
+```
+
+### Import/Export Settings
+```bash
+# Export current settings to a file
+grok settings export --path my-settings.env
+
+# Import settings from a file
+grok settings import --path my-settings.env
+```
+
+## Settings Categories
+
+Settings are organized into logical categories for easier management:
+
+### General
+Core application settings and preferences.
+
+### UI
+User interface appearance, themes, and display options.
+
+### Model
+AI model configuration and behavior settings.
+
+### Context
+File handling, context discovery, and memory management.
+
+### Tools
+Tool execution, shell integration, and external command settings.
+
+### Security
+Security policies, trust settings, and access controls.
+
+### Experimental
+Preview features and experimental functionality.
+
+### ACP
+Agent Client Protocol settings for Zed editor integration.
+
+### Network
+Network configuration, timeouts, and Starlink optimizations.
+
+### Logging
+Logging levels, file output, and debugging options.
+
+## Settings Reference
+
+Here is a comprehensive list of all available settings, grouped by category:
+
+### General Settings
+
+| Setting | Description | Default | Type |
+|---------|-------------|---------|------|
+| `general.preview_features` | Enable preview features and experimental models | `false` | Boolean |
+| `general.vim_mode` | Enable Vim keybindings throughout the interface | `false` | Boolean |
+| `general.disable_auto_update` | Disable automatic updates | `false` | Boolean |
+| `general.disable_update_nag` | Hide update notification messages | `false` | Boolean |
+| `general.enable_prompt_completion` | Enable AI-powered prompt completion while typing | `false` | Boolean |
+| `general.retry_fetch_errors` | Automatically retry failed network requests | `false` | Boolean |
+| `general.debug_keystroke_logging` | Log keystrokes for debugging purposes | `false` | Boolean |
+
+### UI Settings
+
+| Setting | Description | Default | Type |
+|---------|-------------|---------|------|
+| `ui.theme` | Color theme for the interface | `"default"` | String |
+| `ui.colors` | Enable colored output in terminal | `true` | Boolean |
+| `ui.progress_bars` | Show progress indicators during operations | `true` | Boolean |
+| `ui.verbose_errors` | Display detailed error information | `false` | Boolean |
+| `ui.terminal_width` | Terminal width override (0 = auto-detect) | `0` | Number |
+| `ui.unicode` | Enable Unicode characters and emojis | `true` | Boolean |
+| `ui.hide_window_title` | Hide the window title bar | `false` | Boolean |
+| `ui.show_status_in_title` | Show Grok CLI status in terminal title | `false` | Boolean |
+| `ui.hide_tips` | Hide helpful tips and suggestions | `false` | Boolean |
+| `ui.hide_banner` | Hide the ASCII art startup banner | `false` | Boolean |
+| `ui.hide_context_summary` | Hide context summary above input | `false` | Boolean |
+| `ui.hide_footer` | Hide the status footer | `false` | Boolean |
+| `ui.show_memory_usage` | Display memory usage information | `false` | Boolean |
+| `ui.show_line_numbers` | Show line numbers in chat output | `true` | Boolean |
+| `ui.show_citations` | Show citations for generated content | `false` | Boolean |
+| `ui.show_model_info_in_chat` | Display model name in chat responses | `false` | Boolean |
+| `ui.use_full_width` | Use entire terminal width for output | `true` | Boolean |
+| `ui.use_alternate_buffer` | Use alternate screen buffer (preserves history) | `false` | Boolean |
+| `ui.incremental_rendering` | Enable incremental text rendering | `false` | Boolean |
+
+### Footer Settings
+
+| Setting | Description | Default | Type |
+|---------|-------------|---------|------|
+| `ui.footer.hide_cwd` | Hide current working directory in footer | `false` | Boolean |
+| `ui.footer.hide_sandbox_status` | Hide sandbox status indicator | `false` | Boolean |
+| `ui.footer.hide_model_info` | Hide model information in footer | `false` | Boolean |
+| `ui.footer.hide_context_percentage` | Hide context usage percentage | `true` | Boolean |
+
+### Accessibility Settings
+
+| Setting | Description | Default | Type |
+|---------|-------------|---------|------|
+| `ui.accessibility.disable_loading_phrases` | Disable witty loading phrases | `false` | Boolean |
+| `ui.accessibility.screen_reader` | Optimize output for screen readers | `false` | Boolean |
+
+### Interactive UI Settings
+
+| Setting | Description | Default | Type |
+|---------|-------------|---------|------|
+| `ui.interactive.prompt_style` | Prompt style (simple, rich, minimal) | `"rich"` | String |
+| `ui.interactive.show_context_usage` | Enable context usage display | `true` | Boolean |
+| `ui.interactive.auto_save_sessions` | Auto-save sessions | `false` | Boolean |
+| `ui.interactive.check_directory` | Check for home directory usage | `true` | Boolean |
+| `ui.interactive.startup_animation` | Enable startup animation | `true` | Boolean |
+| `ui.interactive.update_check_hours` | Update check frequency in hours (0 = disabled) | `24` | Number |
+
+### Model Settings
+
+| Setting | Description | Default | Type |
+|---------|-------------|---------|------|
+| `default_model` | Default Grok model to use | `"grok-3"` | String |
+| `default_temperature` | Default temperature for responses (0.0-2.0) | `0.7` | Number |
+| `default_max_tokens` | Default maximum tokens per response | `4096` | Number |
+| `model.max_session_turns` | Maximum conversation turns (-1 = unlimited) | `-1` | Number |
+| `model.compression_threshold` | Context compression threshold (0.1-1.0) | `0.2` | Number |
+| `model.skip_next_speaker_check` | Skip next speaker validation | `true` | Boolean |
+
+### Context Settings
+
+| Setting | Description | Default | Type |
+|---------|-------------|---------|------|
+| `context.discovery_max_dirs` | Maximum directories to search for context | `200` | Number |
+| `context.load_memory_from_include_directories` | Load memory from included directories | `false` | Boolean |
+| `context.file_filtering.respect_git_ignore` | Respect .gitignore files | `true` | Boolean |
+| `context.file_filtering.respect_grok_ignore` | Respect .grokignore files | `true` | Boolean |
+| `context.file_filtering.enable_recursive_file_search` | Enable recursive file search | `true` | Boolean |
+| `context.file_filtering.disable_fuzzy_search` | Disable fuzzy file matching | `false` | Boolean |
+
+### Tools Settings
+
+| Setting | Description | Default | Type |
+|---------|-------------|---------|------|
+| `tools.shell.enable_interactive_shell` | Enable interactive shell mode | `true` | Boolean |
+| `tools.shell.show_color` | Show colors in shell output | `false` | Boolean |
+| `tools.auto_accept` | Automatically accept safe tool executions | `false` | Boolean |
+| `tools.use_ripgrep` | Use ripgrep for faster file searches | `true` | Boolean |
+| `tools.enable_tool_output_truncation` | Truncate large tool outputs | `true` | Boolean |
+| `tools.truncate_tool_output_threshold` | Truncation threshold in characters | `10000` | Number |
+| `tools.truncate_tool_output_lines` | Lines to keep when truncating | `100` | Number |
+| `tools.enable_message_bus_integration` | Enable message bus integration | `true` | Boolean |
+
+### Security Settings
+
+| Setting | Description | Default | Type |
+|---------|-------------|---------|------|
+| `security.disable_yolo_mode` | Disable YOLO mode even if flagged | `false` | Boolean |
+| `security.enable_permanent_tool_approval` | Allow permanent tool approvals | `false` | Boolean |
+| `security.block_git_extensions` | Block Git-based extensions | `false` | Boolean |
+| `security.folder_trust.enabled` | Enable folder trust system | `false` | Boolean |
+| `security.environment_variable_redaction.enabled` | Enable env var redaction | `false` | Boolean |
+
+### Experimental Settings
+
+| Setting | Description | Default | Type |
+|---------|-------------|---------|------|
+| `experimental.enable_agents` | Enable experimental agent features | `false` | Boolean |
+| `experimental.extension_management` | Enable extension management | `false` | Boolean |
+| `experimental.jit_context` | Enable just-in-time context loading | `false` | Boolean |
+| `experimental.codebase_investigator_settings.enabled` | Enable codebase investigator | `true` | Boolean |
+| `experimental.codebase_investigator_settings.max_num_turns` | Max investigator turns | `10` | Number |
+
+### ACP Settings
+
+| Setting | Description | Default | Type |
+|---------|-------------|---------|------|
+| `acp.enabled` | Enable Agent Client Protocol | `true` | Boolean |
+| `acp.bind_host` | ACP server bind address | `"127.0.0.1"` | String |
+| `acp.default_port` | Default ACP server port | `None` | Number |
+| `acp.protocol_version` | ACP protocol version | `"1.0"` | String |
+| `acp.dev_mode` | Enable development mode | `false` | Boolean |
+
+### Network Settings
+
+| Setting | Description | Default | Type |
+|---------|-------------|---------|------|
+| `network.starlink_optimizations` | Enable Starlink satellite optimizations | `false` | Boolean |
+| `network.base_retry_delay` | Base retry delay in seconds | `1` | Number |
+| `network.max_retry_delay` | Maximum retry delay in seconds | `60` | Number |
+| `network.health_monitoring` | Enable network health monitoring | `true` | Boolean |
+| `network.connect_timeout` | Connection timeout in seconds | `10` | Number |
+| `network.read_timeout` | Read timeout in seconds | `30` | Number |
+
+### Logging Settings
+
+| Setting | Description | Default | Type |
+|---------|-------------|---------|------|
+| `logging.level` | Log level (trace/debug/info/warn/error) | `"info"` | String |
+| `logging.file_logging` | Enable logging to file | `false` | Boolean |
+| `logging.max_file_size_mb` | Maximum log file size in MB | `10` | Number |
+| `logging.rotation_count` | Number of rotated log files to keep | `5` | Number |
+
+## Configuration File Example
+
+Here's an example of what your `.env` file might look like:
+
+```toml
+api_key = "your-x-api-key-here"
+default_model = "grok-3"
+default_temperature = 0.7
+default_max_tokens = 4096
+timeout_secs = 30
+max_retries = 3
+
+[general]
+preview_features = true
+vim_mode = false
+disable_auto_update = false
+
+[ui]
+theme = "default"
+colors = true
+hide_banner = false
+hide_tips = false
+show_line_numbers = true
+use_full_width = true
+
+[ui.footer]
+hide_cwd = false
+hide_model_info = false
+hide_context_percentage = true
+
+[model]
+max_session_turns = -1
+compression_threshold = 0.2
+
+[acp]
+enabled = true
+bind_host = "127.0.0.1"
+protocol_version = "1.0"
+
+[network]
+starlink_optimizations = true
+base_retry_delay = 2
+max_retry_delay = 60
+
+[logging]
+level = "info"
+file_logging = true
+```
+
+## Tips
+
+1. **Start with defaults**: The interactive settings browser shows current values and defaults for easy comparison.
+
+2. **Category-specific resets**: Use `grok settings reset --category <name>` to reset only specific sections.
+
+3. **Backup your settings**: Use `grok settings export` to create backups before making major changes.
+
+4. **Project-specific configs**: Create a `.grok/.env` file in your project directory for project-specific settings.
+
+5. **Restart requirements**: Some settings require restarting Grok CLI to take effect. The settings browser will indicate these.
+
+6. **Use .env format**: All configuration now uses environment variable format (KEY=value) instead of TOML.
+
+6. **Environment variables**: Many settings can also be overridden with environment variables (e.g., `GROK_API_KEY`).
+
+For more information about specific features, see the main [Grok CLI documentation](README.md).

package/examples/extensions/logging-hook/README.md

@@ -0,0 +1,91 @@
+# Logging Hook Extension
+
+A sample extension that demonstrates the Grok CLI extension system by logging tool invocations.
+
+## Overview
+
+This extension provides a simple hook that logs all tool invocations before and after execution, which can be useful for:
+- Debugging tool interactions
+- Monitoring agent behavior
+- Auditing tool usage
+- Performance profiling
+
+## Installation
+
+1. Copy this directory to your Grok extensions folder:
+   ```bash
+   cp -r logging-hook ~/.grok/extensions/
+   ```
+
+2. Enable the extension in your `~/.config/grok-cli/config.toml`:
+   ```toml
+   [experimental.extensions]
+   enabled = true
+   enabled_extensions = ["logging-hook"]
+   ```
+
+3. Restart Grok CLI to load the extension.
+
+## Configuration
+
+The extension can be configured in the `extension.json` file:
+
+- **log_level**: Set to "debug", "info", "warn", or "error" (default: "debug")
+- **include_args**: Whether to log tool arguments (default: true)
+- **include_results**: Whether to log tool results (default: true)
+- **max_result_length**: Maximum length of result to log, to avoid huge logs (default: 500)
+
+## How It Works
+
+The logging hook implements both `before_tool` and `after_tool` hooks:
+
+1. **before_tool**: Logs when a tool is about to be invoked, including:
+   - Tool name
+   - Arguments (if enabled)
+   - Timestamp
+
+2. **after_tool**: Logs after tool execution completes, including:
+   - Tool name
+   - Result preview (if enabled)
+   - Execution duration
+   - Timestamp
+
+## Example Output
+
+When enabled, you'll see log entries like:
+
+```
+[DEBUG] Extension 'logging-hook' hook 'tool-logger' executing before tool 'read_file'
+[DEBUG] Tool args: {"path": "src/main.rs"}
+[DEBUG] Extension 'logging-hook' hook 'tool-logger' executing after tool 'read_file'
+[DEBUG] Result length: 1234 bytes
+```
+
+## Extending This Example
+
+You can use this as a template to create your own extensions:
+
+1. Modify `extension.json` to change the extension name and configuration
+2. Add additional hooks as needed
+3. In a full implementation, you could:
+   - Execute external scripts or commands
+   - Send metrics to monitoring systems
+   - Implement security policies
+   - Transform tool inputs/outputs
+   - Add custom validation logic
+
+## Limitations
+
+This is a basic config-based extension. For more advanced functionality, you would need to:
+- Implement dynamic library loading (`.so`, `.dll`, `.dylib`)
+- Add scripting language support (Lua, Python, etc.)
+- Create a proper extension SDK with more hook types
+- Add tool registration capabilities for custom tools
+
+## License
+
+MIT License - feel free to modify and distribute.
+
+## Author
+
+john mcconnell <john.microtech@gmail.com>

package/examples/extensions/logging-hook/extension.json

@@ -0,0 +1,22 @@
+{
+  "name": "logging-hook",
+  "version": "1.0.0",
+  "description": "A sample extension that logs tool invocations for debugging and monitoring",
+  "author": "john mcconnell <john.microtech@gmail.com>",
+  "extension_type": "hook",
+  "hooks": [
+    {
+      "name": "tool-logger",
+      "hook_type": "both",
+      "script": null,
+      "config": {
+        "log_level": "debug",
+        "include_args": true,
+        "include_results": true,
+        "max_result_length": 500
+      }
+    }
+  ],
+  "dependencies": [],
+  "enabled": true
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "grok-cli-acp",
+  "version": "0.1.2",
+  "description": "grok-cli in rust with acp access",
+  "keywords": [
+    "Xai",
+    "grok",
+    "Zed",
+    "ACP"
+  ],
+  "homepage": "https://github.com/micro-tech/grok-cli#readme",
+  "bugs": {
+    "url": "https://github.com/micro-tech/grok-cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/micro-tech/grok-cli.git"
+  },
+  "license": "ISC",
+  "author": "john mcconnell",
+  "type": "commonjs",
+  "main": "H:\\GitHub\\grok-cli\\target\\release\\groke.exe",
+  "directories": {
+    "doc": "docs",
+    "example": "examples"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  }
+}

package/scripts/test_acp.py

@@ -0,0 +1,252 @@
+#!/usr/bin/env python3
+"""
+Test script for ACP (Agent Client Protocol) stdio communication
+This script properly handles the JSON-RPC protocol and session management
+"""
+
+import json
+import subprocess
+import sys
+import time
+from typing import Optional
+
+
+def send_message(proc, message: dict) -> None:
+    """Send a JSON-RPC message to the process"""
+    msg_str = json.dumps(message)
+    print(f">>> Sending: {msg_str}", file=sys.stderr)
+    proc.stdin.write(msg_str + "\n")
+    proc.stdin.flush()
+
+
+def read_response(proc, timeout: float = 5.0) -> Optional[dict]:
+    """Read a JSON-RPC response from the process"""
+    proc.stdout.flush()
+    line = proc.stdout.readline()
+    if not line:
+        return None
+
+    line = line.strip()
+    if not line:
+        return None
+
+    print(f"<<< Received: {line}", file=sys.stderr)
+
+    try:
+        return json.loads(line)
+    except json.JSONDecodeError as e:
+        print(f"Error parsing JSON: {e}", file=sys.stderr)
+        print(f"Raw line: {line}", file=sys.stderr)
+        return None
+
+
+def main():
+    print("=" * 60)
+    print("Testing ACP Protocol via stdio")
+    print("=" * 60)
+    print()
+
+    # Start grok in ACP stdio mode
+    proc = subprocess.Popen(
+        ["./target/release/grok.exe", "acp", "stdio"],
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        bufsize=1,
+    )
+
+    try:
+        # Give it a moment to start
+        time.sleep(0.5)
+
+        # Step 1: Initialize
+        print("Step 1: Initialize")
+        print("-" * 60)
+        init_msg = {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "initialize",
+            "params": {
+                "protocolVersion": "1",
+                "clientInfo": {"name": "test-client", "version": "1.0.0"},
+            },
+        }
+        send_message(proc, init_msg)
+        init_response = read_response(proc)
+
+        if not init_response:
+            print("❌ No initialize response")
+            return 1
+
+        if "error" in init_response:
+            print(f"❌ Initialize error: {init_response['error']}")
+            return 1
+
+        print(f"✓ Initialize successful")
+        print()
+
+        # Step 2: Create new session
+        print("Step 2: Create Session")
+        print("-" * 60)
+        new_session_msg = {
+            "jsonrpc": "2.0",
+            "id": 2,
+            "method": "session/new",
+            "params": {},
+        }
+        send_message(proc, new_session_msg)
+        session_response = read_response(proc)
+
+        if not session_response:
+            print("❌ No session/new response")
+            return 1
+
+        if "error" in session_response:
+            print(f"❌ Session creation error: {session_response['error']}")
+            return 1
+
+        session_id = session_response.get("result", {}).get("sessionId")
+        if not session_id:
+            print(f"❌ No session ID in response: {session_response}")
+            return 1
+
+        print(f"✓ Session created: {session_id}")
+        print()
+
+        # Step 3: Send prompt
+        print("Step 3: Send Prompt")
+        print("-" * 60)
+        prompt_msg = {
+            "jsonrpc": "2.0",
+            "id": 3,
+            "method": "session/prompt",
+            "params": {
+                "sessionId": session_id,
+                "prompt": [
+                    {
+                        "type": "text",
+                        "text": "Hello! Please respond with exactly: Hello World!",
+                    }
+                ],
+            },
+        }
+        send_message(proc, prompt_msg)
+
+        # Step 4: Read all responses (notifications + final response)
+        print()
+        print("Step 4: Reading Responses")
+        print("-" * 60)
+
+        notifications = []
+        final_response = None
+        timeout_counter = 0
+        max_timeout = 30  # 30 seconds max
+
+        while timeout_counter < max_timeout:
+            response = read_response(proc, timeout=1.0)
+
+            if response:
+                # Check if it's a notification (no id) or a response (has id)
+                if "id" not in response:
+                    # Notification
+                    notifications.append(response)
+                    print(f"  📢 Notification: {response.get('method', 'unknown')}")
+
+                    # Check for session/update with content
+                    if response.get("method") == "session/update":
+                        params = response.get("params", {})
+                        update = params.get("update", {})
+                        if update.get("sessionUpdate") == "agent_message_chunk":
+                            content = update.get("content", {})
+                            if content.get("type") == "text":
+                                text = content.get("text", "")
+                                print(f"     💬 Content: {text}")
+                elif response.get("id") == 3:
+                    # Final response to our prompt
+                    final_response = response
+                    print(f"  ✓ Final response received")
+                    break
+
+                timeout_counter = 0
+            else:
+                timeout_counter += 1
+                time.sleep(0.1)
+
+        print()
+        print("=" * 60)
+        print("Results")
+        print("=" * 60)
+
+        # Analyze results
+        print(f"Notifications received: {len(notifications)}")
+
+        # Check for session/update notifications
+        update_notifications = [
+            n for n in notifications if n.get("method") == "session/update"
+        ]
+        print(f"session/update notifications: {len(update_notifications)}")
+
+        # Extract content
+        content_chunks = []
+        for notif in update_notifications:
+            params = notif.get("params", {})
+            update = params.get("update", {})
+            if update.get("sessionUpdate") == "agent_message_chunk":
+                content = update.get("content", {})
+                if content.get("type") == "text":
+                    text = content.get("text", "")
+                    content_chunks.append(text)
+
+        if content_chunks:
+            print(f"✓ Content found: {len(content_chunks)} chunk(s)")
+            print()
+            print("Combined content:")
+            print("-" * 60)
+            for i, chunk in enumerate(content_chunks, 1):
+                print(f"Chunk {i}: {chunk}")
+            print("-" * 60)
+        else:
+            print("❌ No content found in notifications")
+
+        # Check final response
+        if final_response:
+            if "error" in final_response:
+                print(f"❌ Error in final response: {final_response['error']}")
+                return 1
+            else:
+                result = final_response.get("result", {})
+                stop_reason = result.get("stopReason")
+                print(f"✓ Stop reason: {stop_reason}")
+        else:
+            print("❌ No final response received")
+            return 1
+
+        print()
+        if content_chunks and final_response and "error" not in final_response:
+            print("✅ Test PASSED - ACP protocol working correctly!")
+            return 0
+        else:
+            print("❌ Test FAILED - Missing content or errors")
+            return 1
+
+    except KeyboardInterrupt:
+        print("\nTest interrupted")
+        return 1
+    except Exception as e:
+        print(f"❌ Exception: {e}")
+        import traceback
+
+        traceback.print_exc()
+        return 1
+    finally:
+        # Clean shutdown
+        try:
+            proc.stdin.close()
+            proc.wait(timeout=2)
+        except:
+            proc.kill()
+
+
+if __name__ == "__main__":
+    sys.exit(main())