Remote Terminal & File I/O Tools

[hellodk]

Overview

Extend the Champ agent's tool system to support remote terminal execution and file I/O operations over SSH. This enables the agent to work with code and systems on remote hosts, expanding beyond local-only workspace support.

Acceptance Criteria

• New remote_terminal_cmd tool executes shell commands on remote SSH hosts

  • Accepts host, username, port, command, and optional timeout parameters
  • Reuses existing command sandbox validation (same blocked patterns)
  • Supports both password and SSH key authentication (via ssh-agent or key file)
  • Returns stdout, stderr, and exit code (same format as local terminal)
  • Respects timeout with timeout command or OS-level kill
  • Requires user approval in Approval flow (existing tool pattern)

• New remote_read_file tool reads file contents from remote hosts

  • Parameters: host, username, port, file_path
  • Uses ssh + cat to retrieve file (no SFTP dependency)
  • Returns file contents as string or binary indicator
  • Respects workspace path protection rules
  • Returns appropriate error if file not found/not readable

• New remote_write_file tool writes/creates files on remote hosts

  • Parameters: host, username, port, file_path, content, optional mode
  • Uses ssh + tee or heredoc to write file (no SFTP dependency)
  • Creates parent directories if needed (ssh mkdir -p)
  • Requires approval in tool approval flow
  • Validates path is within allowed remote workspace

• New remote_list_directory tool lists files on remote hosts

  • Parameters: host, username, port, directory
  • Uses ssh ls -la to retrieve listing
  • Returns structured list with file type, size, permissions, name
  • Handles missing directories gracefully

• SSH host registry and credential management

  • VS Code settings: champ.remoteHosts array with host definitions
  • Each host entry: name, host, port (22 default), username, auth_method (password | key | agent)
  • Store credentials in VS Code SecretStorage (no plaintext in settings)
  • Prompt user for password interactively if not stored (one-time per session)
  • Support ssh-agent for key-based auth (no password prompt)

• Tool registry updates

  • Register all 4 new remote tools in ToolRegistry
  • Export tool definitions to LLM (same format as local tools)
  • Approval flow displays host + command preview before execution

• Error handling and safety

  • Connection errors (host unreachable, auth failed) → clear user-facing error
  • Command sandbox blocks same dangerous patterns as local (rm -rf /, curl | bash, etc.)
  • SSH key injection prevention (validate host/username before building SSH command)
  • Timeout enforcement (kill hung SSH processes)

Tests Required

Unit tests (target: 95% coverage for remote tool files):

• test/unit/tools/remote-terminal.test.ts

  • Command sandbox validation applies to remote commands
  • SSH command escaping prevents injection
  • Timeout enforcement kills process
  • stdout/stderr capture and truncation works
  • Handles SSH connection errors gracefully

• test/unit/tools/remote-read-file.test.ts

  • File path validation (no traversal attacks)
  • File not found error handling
  • Binary file indicator
  • Content encoding (UTF-8 assumed)

• test/unit/tools/remote-write-file.test.ts

  • Parent directory creation (mkdir -p)
  • File content write via SSH heredoc
  • Permission mode handling
  • Path validation (no traversal)

• test/unit/tools/remote-list-directory.test.ts

  • Parses ls -la output correctly
  • Handles missing directory error
  • Extracts permissions, size, name, type

• test/unit/tools/remote-host-registry.test.ts

  • Loads hosts from VS Code settings
  • SecretStorage integration for credential storage/retrieval
  • Host lookup by name
  • Validates required fields (host, username)

Integration tests (require live SSH host or mock SSH server):

• test/integration/tools/remote-operations.test.ts
  • Connect to mock SSH server (using node-pty or ssh2 mock)
  • Execute remote command and verify output
  • Read file from remote host
  • Write file to remote host and verify on remote
  • List directory and verify structure
  • Auth failure handling (wrong password/key)

E2E tests (optional, requires live remote host):

• test/e2e/remote-terminal-workflow.test.ts
  • User stores remote host credentials
  • Agent runs remote_terminal_cmd to execute a build script
  • Agent reads build output via remote_read_file
  • Agent edits a config file via remote_write_file

Implementation Notes

• SSH communication: Use Node.js child_process.execFile('ssh') with command piping (not ssh2 module dependency — avoid native deps)
• Credential storage: Use VS Code's built-in context.secrets.store()" and .get()` (SecretStorage)
• Path safety: Reuse existing resolveInWorkspace pattern for remote paths (validate against allow-list)
• Tool ordering: Implement in order: remote_terminal → remote_read_file → remote_write_file → remote_list_directory → registry
• Approval flow: Extend existing approval mechanism (same requiresApproval: true + preview)

Risks & Mitigations

Risk	Mitigation
SSH key injection attacks	Validate host/username format, use -- to separate args, no shell interpolation
Credential leaks	Use SecretStorage only, never log credentials, redact in observability
Network timeouts	Implement connection timeout + command timeout separately
Large remote files	Cap read output like local tool does (MAX_OUTPUT_BYTES)
Remote auth prompts	Interactive password prompt in webview (future UI work)

Related Issues

• SSH Config Storage & Workspace UI #73 SSH Config Storage & Workspace UI (credential management)
• Web search tool #71 Web search tool (external API pattern)

Phase Mapping

This feature spans Phase 2 (Tool System) and Phase 10 (Polish) but is independent of other phases except Phase 3 (UI for optional password prompts).