Skip to content

feat(cortex-cli): implement complete headless exec mode#191

Merged
echobt merged 1 commit intomasterfrom
feature/complete-exec-mode
Jan 27, 2026
Merged

feat(cortex-cli): implement complete headless exec mode#191
echobt merged 1 commit intomasterfrom
feature/complete-exec-mode

Conversation

@echobt
Copy link
Contributor

@echobt echobt commented Jan 27, 2026

Summary

This PR implements a comprehensive headless execution mode for cortex-cli, similar to Droid's exec mode from Factory. The new exec command is designed for CI/CD pipelines, shell scripts, and batch processing.

Features

Autonomy Levels (--auto)

  • read-only: No file/tool permissions - agent cannot make changes
  • low: Requires explicit approval for all write operations
  • medium: Auto-approve safe operations (reads), prompt for writes
  • high: Full auto-approve for all operations

Skip Permissions (--skip-permissions-unsafe)

Bypass all sandboxing for trusted environments (use with caution)

Output Formats (--format)

  • text: Human-readable streaming output (default)
  • json: Structured JSON final result
  • stream-json: NDJSON event stream for real-time monitoring
  • stream-jsonrpc: JSON-RPC 2.0 protocol for multi-turn conversations
  • debug: Verbose debug output

Input Formats (--input-format)

  • text: Single prompt input (default)
  • stream-jsonrpc: Multi-turn JSON-RPC input via stdin

Tool Controls

  • --enabled-tools: Whitelist specific tools (comma-separated)
  • --disabled-tools: Blacklist specific tools (comma-separated)

Session Management

  • --session-id: Continue an existing session

Execution Limits

  • --timeout: Maximum execution time in seconds
  • --max-turns: Maximum conversation turns

Other Features

  • Fail-fast behavior: Aborts on permission policy violations
  • Image attachments: --image flag for visual inputs
  • JSON-RPC 2.0 support: Multi-turn conversations with stdin/stdout

JSON-RPC 2.0 Protocol

For multi-turn conversations:

  • Submit user messages via stdin
  • Receive events via stdout
  • Supports cancel, status, and heartbeat operations
  • Configurable heartbeat interval (--heartbeat)

Example Usage

# Simple single-shot execution
cortex exec "Help me fix the tests" --auto high

# Read-only mode for safe exploration  
cortex exec "Analyze this codebase" --auto read-only

# JSON output for scripting
cortex exec "List all TODOs" --format json

# Multi-turn conversation mode
cortex exec --input-format stream-jsonrpc --format stream-jsonrpc

# With tool restrictions
cortex exec "Write some code" --auto high --disabled-tools Execute

# With timeout and turn limits
cortex exec "Fix bugs" --auto high --timeout 300 --max-turns 50

Migration Notes

This PR replaces the simple ExecCommand with the comprehensive ExecCli from the new exec_cmd module. The basic usage remains compatible, but additional flags are now available for fine-grained control.

Testing

  • Code compiles successfully
  • cargo fmt applied
  • All existing tests pass

Related Issues

  • Implements headless exec mode similar to Factory's Droid

@echobt echobt force-pushed the feature/complete-exec-mode branch from bec24d6 to 177fffa Compare January 27, 2026 09:59
This implements a complete headless execution mode similar to Droid's exec
mode from Factory. The new exec command is designed for CI/CD pipelines,
shell scripts, and batch processing.

Key features:
- Autonomy levels (--auto): read-only, low, medium, high
  - read-only: No file/tool permissions
  - low: Requires approval for writes
  - medium: Auto-approve safe operations
  - high: Full auto-approve
- Skip permissions (--skip-permissions-unsafe): Bypass sandboxing
- Output formats (--format):
  - text: Human-readable streaming output (default)
  - json: Structured JSON final result
  - stream-json: NDJSON event stream
  - stream-jsonrpc: JSON-RPC 2.0 protocol for multi-turn
- Input formats (--input-format):
  - text: Single prompt input
  - stream-jsonrpc: Multi-turn JSON-RPC input via stdin
- Tool controls:
  - --enabled-tools: Whitelist specific tools
  - --disabled-tools: Blacklist specific tools
- Session continuation: --session-id for resuming sessions
- Execution limits:
  - --timeout: Maximum execution time
  - --max-turns: Maximum conversation turns
- Fail-fast behavior: Aborts on permission policy violations
- Image attachments: --image flag for visual inputs

JSON-RPC 2.0 support for multi-turn conversations:
- Submit user messages via stdin
- Receive events via stdout
- Supports cancel, status, and heartbeat operations
- Configurable heartbeat interval

This replaces the simple ExecCommand with ExecCli providing
enterprise-grade automation capabilities.
@echobt echobt force-pushed the feature/complete-exec-mode branch from 177fffa to 88b02ff Compare January 27, 2026 10:01
@echobt echobt merged commit 7a12251 into master Jan 27, 2026
4 of 12 checks passed
@echobt echobt deleted the feature/complete-exec-mode branch January 27, 2026 10:02
echobt pushed a commit that referenced this pull request Jan 27, 2026
This commit implements the following features from open PRs:

PR #191: Complete headless exec mode
- Autonomy levels (--auto read-only|low|medium|high)
- Skip permissions mode (--skip-permissions-unsafe)
- Output formats (text, json, stream-json, stream-jsonrpc)
- Multi-turn conversations via stream-jsonrpc input format
- Tool controls (--enabled-tools, --disabled-tools)
- Session continuation (--session-id)
- Fail-fast behavior on permission violations
- Timeout and max-turns controls
- Image attachments support
- Verbose mode for debugging

PR #113: Expose context window configuration options
- Added model_context_window option documentation
- Added model_auto_compact_token_limit option documentation
- Both options now visible in default config template

Changes include:
- exec_cmd.rs: New comprehensive exec module with autonomy levels
- lib.rs: Export exec_cmd module
- main.rs: Use ExecCli, add context window config options
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants