Skip to content

CLI backend selection and PTY session management commands #677

@geoffjay

Description

@geoffjay

Context

Part of #671 (PTY execution backend epic). Blocked by: #673 (PtyBackend implementation).

Update the CLI to support the new PTY backend and expose PTY-specific session management capabilities.

Problem

The CLI's wrap commands currently assume tmux sessions. With three backends (tmux, docker, pty), the CLI needs:

  1. A way to specify or detect which backend is active
  2. PTY-specific features (attach to session for interactive use)
  3. Consistent behavior across backends

Changes

1. Backend-Aware Session Commands

The existing agent wrap commands should work transparently across backends. The CLI already communicates with the wrap/orchestrator service via REST, so most commands need no changes. However, new capabilities should be exposed:

# Existing commands (work unchanged)
agent wrap list
agent wrap kill <session>
agent wrap launch --agent-type claude-code ...
agent wrap health

# New: show backend info
agent wrap info                    # Shows active backend type, version, capabilities

# New: attach to PTY session (PTY backend only)
agent wrap attach <session>        # Opens interactive terminal to PTY session

2. Backend Configuration

# Environment variable (already exists for orchestrator)
AGENTD_BACKEND=pty   # or tmux (default), docker

# CLI flag override for wrap service
agent wrap launch --backend pty ...

3. Session Info Enhancement

The agent wrap list output should indicate the backend type and session capabilities:

NAME                    BACKEND  STATUS   CAPABILITIES
agentd-orch-abc123      pty      running  terminal,interactive
agentd-orch-def456      tmux     running  attach-tmux
agentd-orch-ghi789      docker   running  health-check,logs

4. PTY Attach Command

For PTY backend sessions, the attach command opens an interactive terminal:

  • Connects to the orchestrator's /terminal/{agent_id} WebSocket endpoint
  • Uses crossterm for raw terminal mode in the CLI
  • Forwards all input/output between the local terminal and remote PTY
  • Ctrl-D or special key sequence to detach

Implementation Steps

  1. Add info subcommand to WrapCommand enum in crates/cli/src/commands/wrap.rs
  2. Add attach subcommand with session name argument
  3. Implement attach using crossterm raw mode + WebSocket client to /terminal/{agent_id}
  4. Add --backend flag to launch subcommand
  5. Update list output to include backend type
  6. Add crossterm dependency to CLI crate

Relevant Files

  • crates/cli/src/commands/wrap.rs — wrap subcommands
  • crates/cli/src/commands/mod.rs — command registration
  • crates/cli/Cargo.toml — dependencies
  • crates/common/src/client.rs — service client base

Acceptance Criteria

  • agent wrap info shows active backend type and capabilities
  • agent wrap attach <session> opens interactive terminal for PTY sessions
  • agent wrap attach returns clear error for non-PTY backends
  • agent wrap list shows backend type per session
  • Attach uses raw terminal mode, forwards I/O correctly
  • Ctrl-D or escape sequence cleanly detaches
  • Existing commands work unchanged for tmux/docker backends

Caution

All work for this issue must branch from feature/autonomous-pipeline and PR back into it — never directly to main.

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions