Introduction

In development and debugging, DSH Agent typically runs as a single instance. This mode limits the Agent’s collaboration and isolation capabilities. The dsh-remote-control plugin gives the Agent the ability to directly control another full local DSH instance, allowing it to operate remote sessions and workspaces like a user.

Plugin Positioning

Plugin Name: dsh-remote-control
Maintainer: mazov2love
License: MIT
Core Value: Non-invasive and ready to use out of the box. It enables the Agent to control another independent DSH instance with user-like operational semantics, supporting incremental reading, reference saving, and searching remote sessions and workspaces.

Core Capabilities

  • Direct Control: The Agent can directly control another DSH instance.
  • Non-invasive: The target instance does not need to install a companion plugin.
  • Incremental Reading and Reference Saving: Supports incremental reading of remote session content and managing local references.
  • Search Capabilities: Supports searching remote sessions and workspaces.
  • Six Standing Tools: Provides tools for creating sessions, sending messages, checking status, searching, managing references, and querying operations.

Installation and Activation

The installation command is as follows. This plugin requires DSH baseline version 0.2.0-rc.2 and Node.js version 22.19+.

dsh plugin --profile web add 'github:mazov2love/dsh-remote-control#v1.0.0'

After installation, restart the caller (the instance hosting the Agent) to enable connection configuration in the conversation.

Configuration and Connection

After installation, inform the Agent of the target instance’s connection information in the conversation.

Example configuration prompt:

I want to use another DSH on local port 3080. The token is <target current token>. Please help me configure the connection and verify it.

The Agent configures the connection based on the conversation content. Connection settings are stored in $DSH_HOME/remote-control/connections.json. After connection settings change, reload the plugin or restart the caller.

Common Tools

The plugin provides six standing tools for interacting with a remote DSH:

  • dsh_create: Create a session or register an existing directory as a workspace, automatically saving references and usage/notes.
  • dsh_send: Send a message using a ref or instance/sessionId, returning an acknowledgment immediately.
  • dsh_status: Check status. view=new reads new replies; view=final previews the latest reply.
  • dsh_search: Search saved references; scope=sessions/workspaces searches brief remote metadata.
  • dsh_refs: View, save, update, or delete local references with pagination.
  • dsh_other: Query detailed operation usage, or execute by explicit operation name (advanced operation details must be queried through this tool).

Data and State

The plugin maintains state under the $DSH_HOME/remote-control/ directory.

  • Reference Saving: References are saved automatically when created; deleting a reference only removes the local record, and the remote session is not affected.
  • Staged Results: Valid for 24 hours by default, with a maximum of 50 saved results. Mainly used for handling large results that exceed the return budget.
  • Return Budget: The default tool return budget is 6000 characters (JSON text). When the budget is exceeded, the result is staged and must be read in segments through dsh_other.
  • Incremental Reading: dsh_status view=new returns only unread assistant text by default.

Precautions

  • Permission Dependency: The plugin runs with the permissions of the current caller process. Ensure you inspect the source code and license before installing.
  • Token Security: Tokens are provided through the conversation, and tools do not proactively return credentials.
  • Configuration Reload: Connection settings must be reloaded or the caller restarted after they change.
  • Advanced Operations: The plugin does not register extra system prompt content and does not put a complete operation manual into the base tool schema. Advanced operation details must be queried through dsh_other.
  • Target Instance: The target DSH instance does not need to install this plugin.

Conclusion

This plugin addresses the limitations of running an Agent in a single instance. Through a non-invasive approach, the Agent can independently operate another DSH instance for testing, collaboration, or complex task decomposition.