@goodandready/dsh-remote-workspace

Readme

# 📦 @goodandready/dsh-remote-workspace

<div align="center">

<h3>Enterprise Remote Workspace for DeepSeek Harness: SSH, SFTP File Sync & Tunneling</h3>

<p align="center">
  <a href="https://www.npmjs.com/package/@goodandready/dsh-remote-workspace"><img src="https://img.shields.io/npm/v/@goodandready/dsh-remote-workspace.svg?style=for-the-badge&color=6366f1&labelColor=1e1b4b" alt="npm version"></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/GooDAnDReaDY/dsh-remote-workspace.svg?style=for-the-badge&color=10b981&labelColor=064e3b" alt="license"></a>
  <a href="https://github.com/topics/dsh-plugin"><img src="https://img.shields.io/badge/DSH-Plugin-8b5cf6.svg?style=for-the-badge&labelColor=2e1065" alt="DSH Plugin"></a>
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/Node-20%2B-f59e0b.svg?style=for-the-badge&labelColor=451a03" alt="Node version"></a>
</p>

<!-- Author Showcase Badge -->
<p align="center">
  <a href="https://goodandready.app/"><img src="https://img.shields.io/badge/Все_проекты_автора-goodandready.app-ff4500.svg?style=for-the-badge&logo=rocket&logoColor=white&labelColor=1a1a2e" alt="GoodAndReady Showcase"></a>
</p>

<p align="center">
  <a href="README.md"><b>🇬🇧 English</b></a> •
  <a href="README.ru.md"><b>🇷🇺 Русский</b></a> •
  <a href="README.zh.md"><b>🇨🇳 中文说明</b></a>
</p>

<table align="center">
  <tr>
    <td align="center">
      ⭐ <strong>If you like this plugin, please star it on GitHub</strong> — it shows me that the plugin is useful to you and motivates me to keep developing it.
      <br><br>
      🐛 <strong>If you find a bug or would like to request a feature</strong>, open a GitHub issue in any language — I will review your proposal and implement useful suggestions in a future plugin version.
    </td>
  </tr>
</table>

</div>

---

## ⚡ Overview & The Problem

In modern software engineering and agentic workflows, AI agents orchestrating code within **DeepSeek Harness (DSH)** frequently need to work across remote environments: cloud virtual machines, high-performance GPU instances, containerized remote clusters, and staging servers.

Without `@goodandready/dsh-remote-workspace`, developers face critical roadblocks:
1. **Local Boundary Limitation**: Standard DSH operations and agent tools run exclusively against the local machine where DSH is deployed.
2. **Fragile Ad-Hoc Scripts**: Manual SSH wrappers and ad-hoc SCP uploads lack robust connection pooling, causing connection drops, hangs under network latency, and high resource overhead.
3. **Silent File Overwrites**: Naive file copies risk corrupting data during network interruptions or overwriting concurrent modifications made by remote teams.
4. **Port Accessibility**: Accessing remote web servers, inference APIs, or debuggers typically requires manual external SSH tunneling configuration.

`@goodandready/dsh-remote-workspace` solves these challenges directly within the Cordis framework. It provides an enterprise-grade remote development subsystem with persistent SSH2 connection pooling, atomic SFTP file operations, conflict-aware 3-way synchronization, dynamic port tunneling, and an interactive Web UI settings card styled after `dsh-clinebot`.

---

## 🏗️ Architecture

```mermaid
graph LR
  subgraph DSH["DeepSeek Harness (Cordis Architecture)"]
    UI["Web UI Client Card<br/>(dsh-clinebot style)"]
    Routes["REST API Routes<br/>(/state, /browse, /test, /sync)"]
    Tools["Model Tools<br/>(remote_exec, remote_fs, sync, tunnel)"]
    Ssh["SshService<br/>(Connection Pool & Keepalive)"]
    SFTP["RemoteFsService<br/>(Atomic SFTP Streaming)"]
    Sync["MirrorSyncService<br/>(3-Way SHA-256 Engine)"]
    Tunnel["TunnelService<br/>(Port Forwarding)"]
  end

  subgraph RemoteNode["Remote Environment (Cloud VM / GPU Node)"]
    SSHD["SSH Server (:22)"]
    FS["Remote Filesystem"]
    AppPort["Remote Dev Server / Service"]
  end

  UI -->|REST API| Routes
  Routes --> Ssh
  Routes --> SFTP
  Routes --> Sync
  Tools --> Ssh
  Tools --> SFTP
  Tools --> Sync
  Tools --> Tunnel
  Ssh -->|SSH2 Channel / Key or Password| SSHD
  SFTP -->|SFTP Subsystem| FS
  Sync -->|Pull / Push Differential| FS
  Tunnel -->|Local Port Forwarding| AppPort

  classDef default fill:#1e1e2e,stroke:#6366f1,stroke-width:1px,color:#cdd6f4;
  classDef accent fill:#313244,stroke:#a6e3a1,stroke-width:2px,color:#a6e3a1;
  class DSH,RemoteNode accent;
```

---

## ✨ Full Feature Breakdown

### 1. `SshService` — High-Performance Connection Pool & Authentication
- **Connection Pooling**: Maintains reusable, authenticated SSH2 client sessions keyed by `host:port:username`.
- **Dual Authentication Modes**:
  - **SSH Private Key**: Path to local key (`~/.ssh/id_ed25519`), raw PEM string, and optional passphrase decryption.
  - **Password Authentication**: Direct secure password authentication.
- **Diagnostic Health Probing**: Built-in `testConnection` executes latency measurements (ping in milliseconds) and detects remote OS architecture (`uname -srm`).
- **Resilience**: Heartbeat keep-alive packets prevent timeout disconnects from aggressive firewalls.
- **Proxy and jump hosts**: `proxyCommand` runs an OpenSSH-style command. Tokens are `%h`, `%p`, `%r`, `%n`, and `%%`. `jumpHosts` is an ordered list of profile ids. A comma-separated `jumpHostId` is the fallback. The first bastion comes from the pool. Each later bastion has its own connection, released when the target session ends.
- **Agent and one-time codes**: `agentPath` selects an agent socket. An empty value uses `SSH_AUTH_SOCK`, or Pageant on Windows when that is the configured path. A keyboard-interactive server shows its prompt on the card. The prompt expires after 60 seconds.
- **Idle pool**: a pooled connection with no tunnel and no running command closes after 30 minutes. The next command opens it again.
- **Reconnect before output**: if the connection drops before the command prints anything, the command runs again, up to three times. A command timeout, output that already started, or `idempotent: false` is not repeated.
- **Separate terminal session**: the terminal does not share the pooled connection. Closing the terminal closes only that SSH session.

### 2. `RemoteFsService` — Resilient SFTP Operations
- **Atomic File Writing**: Writes content to an ephemeral temporary file (`.tmp.<timestamp>.<hash>`) and renames it atomically upon complete upload, preventing partial or corrupted files.
- **Streaming Reads**: High-speed chunked stream reader supporting large files with selectable encoding.
- **Filesystem Primitives**: Provides `stat`, `listDir`, recursive `mkdir` (like `mkdir -p`), and recursive `remove` directly over the SFTP subsystem.

### 3. `MirrorSyncService` — Conflict-Aware 3-Way Synchronization
- **State Manifest Tracking**: Maintains baseline SHA-256 hash digests in `.dsh-sync-manifest.json` for all tracked files.
- **Conflict Prevention**: Detects when both local and remote files have diverged since the last synchronization baseline, halting operations with a detailed conflict report rather than silently overwriting changes.
- **Selective Sync**: Supports directional `pull` (remote → local) and `push` (local → remote) with optional `force` override.
- **Dry-Run Inspection**: Allows agents or developers to preview affected files, additions, modifications, and deletions before applying changes.
- **Smart Exclusion**: Built-in default ignore patterns for version control, dependencies, and temporary files (`.git`, `node_modules`, `.dsh`, `.worktrees`, `.DS_Store`).

### 4. `TunnelService` — Integrated SSH Port Forwarding
- **Local Port Forwarding**: Binds a local port on the DSH host and securely forwards all incoming TCP traffic over the encrypted SSH channel to any target port on the remote host (e.g. `127.0.0.1:8080` → remote `127.0.0.1:8080`).
- **Dynamic Lifecycle**: Start, stop, and enumerate active tunnels programmatically or via UI.

### 5. `tools.js` — Ergonomic Agent Tools
Four orthogonal, high-leverage tools exposed directly to LLM agents:
- `remote_exec`: Execute shell commands on the remote workspace with custom working directory and exit code capture.
- `remote_fs`: Read, write, inspect, list, create directories, or delete files on the remote filesystem.
- `remote_sync`: Synchronize files between the local mirror and remote server with conflict awareness and dry-run mode.
- `remote_tunnel`: Start, stop, or list SSH port-forwarding tunnels.
- `remote_hosts`: Return a compact markdown table of configured hosts. Secrets, private keys, and proxy commands are omitted. `query` is required; an empty query lists every host.
- `remote_cluster`: Run one command on every host that matches an environment, every requested tag, and an optional alias list. `maxWorkers` defaults to 8.

### 6. `client.js` — Native DSH Settings Card UI
- Designed strictly to DSH UX guidelines and styled after `dsh-clinebot`.
- **Segmented Auth Switcher**: Clean tabbed toggle between Private Key and Password authentication.
- **Remote Directory Browser Modal**: Interactive remote file browser with breadcrumb navigation and one-click path selection.
- **Connection Diagnostic Badge**: Real-time ping testing with visual latency indicators and remote OS display. The header badge follows `/dsh-remote-workspace/state`: it shows a loading, empty, ready, or unavailable connection instead of a permanent Ready label.
- **Action Triggers**: Quick buttons for directional synchronization and tunnel monitoring. A failed save, delete, activation, directory browse, or tunnel stop shows the server error in an alert on the card. Test Connection posts the profile fields, including `host`.
- **Plugin list label**: English `Remote Workspace` or Chinese `远程开发工作区`, taken from the dictionaries already loaded with the card.
- **Updater version**: the row shows the installed version returned by the status request. Before that response it shows "Version unknown".
- **Host groups**: profiles can carry `environment`, `tags`, `location`, and `description`. The card can list them flat, by environment, or by tag, and test one group together.
- **Files**: the Files tab uploads and downloads a remote file. Progress follows the bytes already moved, and Cancel stops the transfer. Files larger than 512MB are refused.
- **Terminal font**: `terminalFontFamily` is a CSS font family for the terminal. Leave it empty for the default monospace stack.
- **Hidden tab**: status polling pauses while the browser tab is hidden and refreshes when the tab returns.
- **Sidebar workspace**: a Remote button in the left navigation opens the center column with Hosts, Terminal, Files, Containers, Tunnels, and Cluster. Switching back to chat hides that column and keeps the open terminal.

---

## 📦 Installation

Install into your DSH `web` profile:

```bash
dsh plugin --profile web add @goodandready/dsh-remote-workspace
```

Or install using the DSH CLI:

```bash
dsh plugin add @goodandready/dsh-remote-workspace
```

---

## ⚙️ Configuration Reference

Configuration can be managed either via the Web UI Settings card or defined in your DSH configuration files (`settings.yaml` / Cordis config):

```yaml
dsh-remote-workspace:
  activeProfileId: "prod-cloud-gpu"
  profiles:
    - id: "prod-cloud-gpu"
      name: "Cloud GPU VM"
      host: "remote.example.com"
      port: 22
      username: "deploy"
      authType: "key"              # "key" or "password"
      privateKeyPath: "/home/user/.ssh/id_ed25519"
      passphrase: ""
      password: ""
      remoteWorkspace: "/var/www/my-project"
      localMirrorPath: "/home/user/projects/my-project"
```

### Parameters Table

| Parameter | Type | Default | Description |
|---|---|---|---|
| `profiles` | `Array<Profile>` | `[]` | List of configured remote server profiles. |
| `activeProfileId` | `string` | `""` | ID of the currently active remote host profile. |
| `profile.id` | `string` | `""` | Unique identifier for the profile. |
| `profile.name` | `string` | `""` | Human-readable label displayed in UI. |
| `profile.host` | `string` | `""` | Hostname, FQDN, or IP address of the remote host. |
| `profile.port` | `number` | `22` | Remote SSH port. |
| `profile.username` | `string` | `""` | SSH login username. |
| `profile.authType` | `string` | `"key"` | Authentication method: `"key"` or `"password"`. |
| `profile.privateKeyPath`| `string` | `""` | Path to local OpenSSH private key file. |
| `profile.privateKey` | `string` | `""` | Raw PEM/OpenSSH private key content (alternative to path). |
| `profile.passphrase` | `string` | `""` | Passphrase for encrypted private keys. |
| `profile.password` | `string` | `""` | Password for password-based authentication. |
| `profile.remoteWorkspace` | `string` | `""` | Base directory of the project on the remote machine. |
| `profile.localMirrorPath` | `string` | `""` | Local directory for mirror synchronization. |
| `profile.agentPath` | `string` | `""` | SSH agent socket. Empty uses `SSH_AUTH_SOCK`. | 
| `profile.proxyCommand` | `string` | `""` | OpenSSH ProxyCommand. Tokens: `%h` `%p` `%r` `%n`. | 
| `profile.jumpHosts` | `string[]` | `[]` | Bastion profile ids, first hop first. | 
| `profile.jumpHostId` | `string` | `""` | Comma-separated bastion ids when `jumpHosts` is empty. | 
| `profile.environment` | `string` | `""` | Group and cluster filter, compared case-insensitively. | 
| `profile.tags` | `string[]` | `[]` | Labels. A cluster filter requires every tag. | 
| `profile.location` | `string` | `""` | Free-form place label. | 
| `profile.description` | `string` | `""` | Free-form note. | 
| `terminalFontFamily` | `string` | `""` | Terminal CSS font family. Empty keeps the default monospace stack. |

---

## 🔌 Model Tools Reference

### `remote_exec`
Executes a bash or shell command on the active remote host.
- **Parameters**:
  - `command` (`string`, required): Shell command line to execute.
  - `cwd` (`string`, optional): Working directory on remote host. Defaults to `remoteWorkspace`.
- **Returns**: `{ exitCode: number, stdout: string, stderr: string }`

### `remote_fs`
Performs filesystem operations over SFTP.
- **Parameters**:
  - `action` (`string`, required): One of `"read"`, `"write"`, `"stat"`, `"list"`, `"mkdir"`, `"remove"`.
  - `path` (`string`, required): Target remote path (absolute or relative to workspace).
  - `content` (`string`, optional): Required for `"write"` action.
  - `recursive` (`boolean`, optional): Recursive flag for `"remove"` action.
- **Returns**: Result object depending on action (`{ content }`, `{ stat }`, `{ entries }`, `{ ok: true }`).

### `remote_sync`
Runs 3-way conflict-aware synchronization between local and remote directories.
- **Parameters**:
  - `direction` (`string`, required): `"pull"` (remote → local) or `"push"` (local → remote).
  - `force` (`boolean`, optional): Overwrite conflicts if true.
  - `dryRun` (`boolean`, optional): Simulate changes without writing to disk.
- **Returns**: Sync summary object with applied actions, changed files, and any detected conflicts.

### `remote_tunnel`
Manages SSH local port forwarding tunnels.
- **Parameters**:
  - `action` (`string`, required): `"start"`, `"stop"`, or `"list"`.
  - `localPort` (`number`, optional): Local port to bind (for `"start"`).
  - `remotePort` (`number`, optional): Remote destination port (for `"start"`).
  - `tunnelId` (`string`, optional): Identifier of the tunnel to terminate (for `"stop"`).
- **Returns**: `{ tunnelId, localPort, remotePort }` or `{ tunnels: [...] }` or `{ success: boolean }`.

### `remote_hosts`
Lists configured hosts for the model without secrets.
- **Parameters**:
  - `query` (`string`, required): Case-insensitive match against name, host, or id. An empty string lists every host.
- **Returns**: A markdown table. Password, private key, key path, passphrase, agent socket, and proxy command are omitted.

### `remote_cluster`
Runs one shell command on a filtered set of hosts.
- **Parameters**:
  - `command` (`string`, required): Shell command.
  - `environment` (`string`, optional): Exact environment name.
  - `tags` (`string`, optional): Comma-separated tags. Every tag must match.
  - `aliases` (`string`, optional): Comma-separated profile ids or names.
  - `maxWorkers` (`number`, optional): Parallel connections. Default 8.
- **Returns**: One row per host with success, exit code, duration, stdout, stderr, and error.
- **Limit**: A host that fails to connect is reported on its own row. Other hosts still run.

---

## 🌐 HTTP API Routes Reference

All endpoints are hosted under `/dsh-remote-workspace`:

| Method | Route | Description | Request Body |
|---|---|---|---|
| `GET` | `/dsh-remote-workspace/state` | Returns profiles, active profile ID, and active tunnels. | — |
| `POST` | `/dsh-remote-workspace/profiles/save` | Create or update a profile. | Profile JSON object |
| `POST` | `/dsh-remote-workspace/profiles/delete` | Delete a profile by ID. | `{ id: string }` |
| `POST` | `/dsh-remote-workspace/profiles/active` | Set active profile. | `{ id: string }` |
| `POST` | `/dsh-remote-workspace/test` | Test SSH connectivity and latency. | Profile JSON object |
| `POST` | `/dsh-remote-workspace/browse` | List directory contents for remote browser modal. | `{ profile: object, path: string }` |
| `POST` | `/dsh-remote-workspace/sync` | Trigger manual pull or push synchronization. | `{ direction: "pull" \| "push", dryRun?: boolean, force?: boolean }` |
| `POST` | `/dsh-remote-workspace/profiles/import-ssh-config` | Import `~/.ssh/config`, or the posted config text. | `{ content?: string }` |
| `POST` | `/dsh-remote-workspace/profiles/test-group` | Test the stored profiles whose ids are posted. | `{ ids: string[] }` |
| `POST` | `/dsh-remote-workspace/cluster` | Run one command on the filtered stored profiles. | `{ command, environment?, tags?, aliases?, maxWorkers? }` |
| `GET` | `/dsh-remote-workspace/file/download` | Stream a remote file. Query: `profileId`, `filePath`. | — |
| `POST` | `/dsh-remote-workspace/file/upload` | Upload a raw file body. Query: `profileId`, `filePath`. | file bytes |
| `POST` | `/dsh-remote-workspace/terminal/font` | Save the terminal font family. | `{ fontFamily: string }` |
| `POST` | `/dsh-remote-workspace/auth/keyboard` | Submit a keyboard-interactive code. | `{ id, answers }` |

---

## 📄 License

MIT © [GooDAnDReaDY](https://github.com/GooDAnDReaDY)

### 13. Smart Tarball Sync & Diagnostics (v0.3.1)
- **`🚀 Fast Tarball Stream`**: High-throughput directory sync via on-the-fly streaming `tar -czf` bypassing per-file roundtrips.
- **`🩺 Remote Diagnostics (remote_diagnose)`**: Instant one-shot checks for occupied ports (`ports`), OOM killer events (`oom_killer`), disk consumption (`disk`), and service crash-logs (`service_logs`).
- **`📥 Import from ~/.ssh/config`**: One-click import of hosts, keys, and ProxyJump configurations directly into the encrypted `.env` vault.
- **`🗃️ Remote Environment Manager (remote_env)`**: Inspect and atomically modify remote `.env` key-values with password masking and structural preservation.
- **`📡 Background Anomaly Alerts`**: Proactive monitoring of disk (<10% free), memory (<5%), and restarting Docker containers via Cordis event bus (`remote-workspace/alert`).