pi-ssh-remote 0.1.3 → 0.1.4

package/README.md

@@ -1,12 +1,56 @@
 <!--
-Concise English documentation for pi-ssh-remote, covering its purpose, installation, essential commands, authentication, and security boundaries.
+Agent-first English documentation for pi-ssh-remote. It explains the extension's design, transparent tool routing, persistent workspace model, safety boundaries, compelling workflows, commands, and installation requirements.
 -->
 
 # pi-ssh-remote
 
-[中文](README.zh-CN.md)
+**SSH designed for agents—not just for terminals.**
 
-Use Pi's file and shell tools on a persistent remote SSH workspace. Supports multiple endpoints, remote working directories, reconnection, and local port forwarding.
+[中文文档](README.zh-CN.md) · [Community](https://linux.do/)
+
+`pi-ssh-remote` turns a remote machine into Pi's active workspace. After connecting, the agent keeps using its normal `read`, `write`, `edit`, and `bash` tools, but those operations run on the remote server. There is no need to wrap every action in `ssh ...`, copy files back and forth, or make the model reason about two unrelated shells.
+
+```text
+You: Connect to ssh root@gpu-box -p 2202, open /srv/training,
+     find why the latest run failed, fix it, and restart it in the
+     background. Return the PID and log path.
+
+Pi:  connects → changes the persistent remote cwd → reads logs →
+     edits remote files → launches the job on the GPU server
+```
+
+## Designed for agent workflows
+
+### The remote machine becomes the agent's workspace
+
+Once connected, Pi's file tools, shell tool, and `!` user shell commands are transparently routed over SSH. The agent can inspect a repository, search logs, edit code, and run tests with the same tool interface it uses locally.
+
+### Agent control plane, human control plane
+
+The extension exposes `ssh_remote_control` for the agent and `/remote` for the user. You can ask Pi to connect, inspect status, change directory, add a server note, execute a command, create a tunnel, or return to local work in natural language—and still take direct control whenever you want.
+
+### Stateful endpoints instead of disposable SSH commands
+
+Each `user@host:port` endpoint remembers its remote working directory, note, and port-forward configuration locally. Notes such as `H100 training`, `staging`, or `customer demo` appear in configuration, status messages, and Pi's footer, so the active execution environment stays visible.
+
+### Resilient and bounded by default
+
+Dropped connections are automatically re-established during the active session. Remote commands have a 30-second default timeout, oversized output is bounded before it reaches the model context, and full truncated output is preserved in a temporary file.
+
+### Hybrid local/remote workflows
+
+Tunnel mode forwards remote services to localhost while returning Pi's tools to the local machine. This is useful when the backend runs on a GPU server but the client, browser automation, or integration code lives locally.
+
+## Why not just run `ssh` in Bash?
+
+| Plain SSH command | `pi-ssh-remote` |
+|---|---|
+| Each tool call must wrap or reconstruct SSH | All agent file and shell tools route automatically |
+| Working directory is easy to lose between calls | Remote cwd is persistent and visible |
+| The model must track whether it is local or remote | Pi's prompt and footer identify the active workspace |
+| Disconnects break the workflow | Active-session connections automatically reconnect |
+| Tunneling and remote editing are separate setups | Workspace routing and port forwarding share one control plane |
+| Large output can flood context | Preview and model-output limits are built in |
 
 ## Install
 
@@ -14,32 +58,141 @@ Use Pi's file and shell tools on a persistent remote SSH workspace. Supports mul
 pi install npm:pi-ssh-remote
 ```
 
-## Use
+Requires Node.js 20+. The remote server must provide Bash, SFTP, and GNU `timeout`.
+
+## Quick start
 
 ```text
-/remote ssh USER@HOST -p PORT  # save and connect
-/remote cd /remote/project
+/remote ssh root@gpu-box.example.com -p 2202
+/remote cd /srv/project
+/remote config note H100 training server
 /remote status
-/remote off                     # return to local tools
 ```
 
-Remote command previews follow Pi's local Bash behavior and show the last 5 visual lines by default. Configure the default or override one `/remote exec` invocation:
+From this point, normal Pi operations target `/srv/project` on the remote server. The footer makes that routing explicit:
+
+```text
+SSH remote H100 training server (root@gpu-box.example.com:2202):/srv/project
+```
+
+Return to local tools with:
+
+```text
+/remote off
+```
+
+## Examples
+
+### 1. Let the agent investigate and repair a remote failure
+
+```text
+Connect to ssh ubuntu@training.example.com -p 22 and work in /opt/app.
+Inspect the failed deployment, trace the error through the logs and source,
+make the smallest safe fix, run the relevant tests, and show me the diff.
+```
+
+The connection is established once. Subsequent reads, searches, edits, and tests are ordinary Pi tool calls routed to the server.
+
+### 2. Launch a long GPU job without blocking the agent
+
+```text
+On the current remote server, validate the training command first. Then launch
+it with nohup in the background, redirect stdout and stderr from process start,
+and report the PID, output directory, and log path. Verify that the process is
+still alive and that the log has started.
+```
+
+The default foreground timeout prevents an accidental long-running command from occupying the agent indefinitely, while an explicitly backgrounded job continues on the server.
+
+### 3. Keep several machines understandable
+
+```text
+/remote ssh root@10.0.0.21 -p 22
+/remote config note 8xH100 training
+/remote config cwd /srv/train
+
+/remote ssh ubuntu@staging.example.com -p 2222
+/remote config note staging API
+/remote config cwd /opt/service
+
+/remote config
+/remote use root@10.0.0.21:22
+/remote
+```
+
+Endpoint notes and working directories survive Pi restarts because they are stored in the local remote configuration.
+
+### 4. Expose a remote service while editing locally
 
 ```text
-/remote config display-lines 10
-/remote exec --lines 20 COMMAND
+/remote config forward 7860:127.0.0.1:7860
+/remote forward
 ```
 
-The `ssh_remote_control` tool's `exec` action also accepts `displayLines`. Preview settings affect only the collapsed UI; model output keeps Pi's 2000-line/50KB safety limits, with oversized output saved to a temporary file.
+Now `localhost:7860` reaches the service on the SSH server, while Pi's file and shell tools remain local. This is ideal for a remote model server paired with a local UI or client repository.
 
-Run `/remote config` to list endpoints and `/remote` to see all available subcommands.
+Stop the tunnels with:
+
+```text
+/remote unforward
+```
+
+### 5. Ask Pi directly
+
+```text
+Connect to my configured remote, switch to /srv/api, and inspect its Git status.
+```
+
+```text
+Add the note "production read-only" to this endpoint and tell me which remote
+workspace is active.
+```
+
+```text
+Forward the remote service on port 8000 to localhost:8000, but keep my coding
+tools on the local repository.
+```
+
+These requests are handled through the agent-facing `ssh_remote_control` tool; slash commands are optional.
+
+## Command reference
+
+| Command | Purpose |
+|---|---|
+| `/remote ssh USER@HOST -p PORT` | Save, select, and connect to an endpoint |
+| `/remote` | Connect to the selected endpoint or prompt for one |
+| `/remote config` | List saved endpoints and settings |
+| `/remote use USER@HOST:PORT` | Select a saved endpoint |
+| `/remote config note TEXT` | Persist a note for the selected endpoint |
+| `/remote config note --clear` | Clear its note |
+| `/remote config cwd PATH` | Persist its default remote working directory |
+| `/remote cd PATH` | Change the connected remote cwd and persist it |
+| `/remote config forward MAPPING...` | Persist port forwards such as `7860:127.0.0.1:7860` |
+| `/remote forward [MAPPING...]` | Start tunnels and keep Pi's tools local |
+| `/remote unforward` | Stop extension-managed tunnels |
+| `/remote exec COMMAND` | Run one command in the remote cwd |
+| `/remote exec --timeout 60 COMMAND` | Override the command timeout |
+| `/remote exec --lines 20 COMMAND` | Override collapsed preview lines |
+| `/remote config display-lines 10` | Set default collapsed preview lines |
+| `/remote status` | Show the active workspace |
+| `/remote reload` | Reconnect the active workspace |
+| `/remote off` | Disconnect and return tools to local execution |
+| `/remote forget` | Disconnect and clear the in-memory password |
+
+## Persistence, output, and security
+
+Endpoint configuration is stored locally in:
+
+```text
+~/.pi/agent/ssh-remote-config.json
+```
 
-## Authentication and security
+Saved values include endpoints, active endpoint, notes, remote working directories, forwards, and preview settings. Passwords are **never written to this file**: SSH agent authentication is preferred, and prompted passwords remain only in process memory.
 
-Uses SSH agent authentication when available, otherwise prompts for a password. Passwords stay in process memory. New or changed host keys require confirmation and are stored separately from OpenSSH.
+New or changed host keys require interactive confirmation and are stored separately from OpenSSH. Remote output sent to the model is limited to 2,000 lines or 50 KB; oversized complete output is written to a temporary local file. Preview-line settings affect only the collapsed UI.
 
-Only direct SSH commands with `-p` and `-l` are supported. `~/.ssh/config`, `IdentityFile`, and ProxyJump are not currently supported.
+## Current SSH scope
 
-Requires Node.js 20+, Bash, SFTP, and GNU `timeout` on the remote host.
+The extension currently supports direct SSH commands with `-p` and `-l`. It does not yet consume `~/.ssh/config`, `IdentityFile`, or ProxyJump settings.
 
 MIT licensed.

package/README.zh-CN.md

@@ -1,12 +1,89 @@
 <!--
-pi-ssh-remote 的简明中文文档，说明扩展用途、安装方式、必要命令、认证机制和安全边界。
+pi-ssh-remote 中文说明文档，重点介绍它面向 Pi Agent 的设计、主要能力、常见使用场景、命令和安全机制。
 -->
 
 # pi-ssh-remote
 
-[English](README.md)
+**让 Pi 像操作本地项目一样操作远程服务器。**
 
-让 Pi 的文件与 Shell 工具在持久化 SSH 远程工作区中运行。支持多个服务器、远程工作目录、自动重连和本地端口转发。
+[English Docs](README.md) · [社区](https://linux.do/)
+
+`pi-ssh-remote` 是一个专门面向 Pi Agent 的 SSH 远程开发插件。
+
+它不只是帮你打开一个远程终端。连接服务器后，Pi 原有的 `read`、`write`、`edit`、`bash` 等工具会自动切换到远端。Agent 不需要反复拼接 SSH 命令，也不需要先把代码下载到本地再修改，可以直接在服务器上查看文件、分析日志、修改代码和运行任务。
+
+例如，你可以直接对 Pi 说：
+
+```text
+连接 ssh root@gpu-box -p 2202，进入 /srv/training。
+检查最近一次训练为什么失败，修复问题后在后台重新启动，
+最后把 PID 和日志路径发给我。
+```
+
+Pi 会依次完成连接服务器、切换目录、读取日志、修改文件和启动任务。整个过程中，它使用的仍然是熟悉的 Pi 工具，只是执行位置变成了远程服务器。
+
+## 为什么它更适合 Agent
+
+### 不需要给每一步都套一层 SSH
+
+普通做法通常是让 Agent 不断执行：
+
+```bash
+ssh user@host "cd /path && ..."
+```
+
+命令一多，目录、引号、环境变量和连接状态都很容易出错。使用本插件后，只需要连接一次，后续文件读写和 Shell 操作都会自动在远端执行。
+
+### Agent 知道自己正在操作哪台服务器
+
+插件会把当前远程目录和服务器信息写入 Pi 的上下文，并显示在底部状态栏：
+
+```text
+SSH remote H100 训练机 (root@gpu-box.example.com:2202):/srv/project
+```
+
+这样无论是用户还是 Agent，都能随时确认当前操作发生在本地还是远端，减少误操作。
+
+### 服务器配置会保留
+
+每台服务器都可以单独保存：
+
+- SSH 地址；
+- 默认工作目录；
+- 服务器备注；
+- 端口转发配置。
+
+例如可以把几台机器分别备注为 `8xH100 训练机`、`预发布环境`、`线上只读机`。这些配置保存在本地，重启 Pi 后仍然存在。
+
+### 断线后可以自动恢复
+
+当前会话中如果 SSH 连接意外断开，插件会尝试自动重连，不需要 Agent 从头建立工作环境。
+
+### 对 Agent 上下文更友好
+
+远程命令默认 30 秒超时，避免某个前台任务长期占住 Agent。命令输出过大时，只会把受限内容放入模型上下文，完整输出会另外保存到临时文件，方便后续继续检查。
+
+### 可以远端跑服务、本地改代码
+
+端口转发模式下，可以把远端服务映射到 `localhost`，同时让 Pi 的文件和 Shell 工具继续操作本地项目。
+
+这很适合下面这类场景：
+
+- GPU 服务器运行模型，本地开发 Web UI；
+- 远端启动 API，本地调试客户端；
+- 远端运行训练监控，本地查看页面；
+- 内网服务通过 SSH 隧道提供给本地工具使用。
+
+## 和直接使用 SSH 有什么区别
+
+| 直接执行 SSH | 使用 `pi-ssh-remote` |
+|---|---|
+| 每条命令都要重新拼接 SSH | 连接一次后，Pi 工具自动在远端执行 |
+| 多次调用之间容易丢失目录 | 自动记住远程工作目录 |
+| Agent 需要自己判断当前在哪台机器 | 系统上下文和底部状态栏会显示当前服务器 |
+| 连接中断后需要手动恢复 | 当前会话内自动重连 |
+| 文件修改、命令执行和端口转发各自处理 | 统一通过 `/remote` 和 Agent 工具管理 |
+| 大量输出可能直接占满模型上下文 | 内置超时、折叠预览和输出上限 |
 
 ## 安装
 
@@ -14,32 +91,177 @@ pi-ssh-remote 的简明中文文档，说明扩展用途、安装方式、必要
 pi install npm:pi-ssh-remote
 ```
 
-## 使用
+本地要求 Node.js 20+。远程服务器需要提供 Bash、SFTP 和 GNU `timeout`。
+
+## 快速开始
+
+连接服务器：
+
+```text
+/remote ssh root@gpu-box.example.com -p 2202
+```
+
+设置远程工作目录和备注：
+
+```text
+/remote cd /srv/project
+/remote config note H100 训练机
+```
+
+查看当前状态：
 
 ```text
-/remote ssh USER@HOST -p PORT  # 保存并连接
-/remote cd /remote/project
 /remote status
-/remote off                     # 返回本地工具
 ```
 
-远程命令预览与 Pi 本地 Bash 一致，默认展示最后 5 个视觉行。可以修改默认值，或只覆盖某一次 `/remote exec`：
+连接成功后，Pi 的文件和 Shell 工具都会操作远程 `/srv/project`。
+
+需要返回本地时执行：
+
+```text
+/remote off
+```
+
+## 常见用法
+
+### 1. 让 Pi 直接排查远程服务故障
+
+```text
+连接 ubuntu@training.example.com，进入 /opt/app。
+先检查部署日志和 Git 状态，找出失败原因。
+如果需要修改代码，先说明原因，再做最小修改并运行相关测试，
+最后把 diff 和测试结果发给我。
+```
+
+连接完成后，Pi 后续的读文件、查日志、改代码和跑测试都会直接在服务器上进行。
+
+### 2. 启动长时间训练任务
+
+```text
+在当前远程服务器检查训练命令和配置。
+确认无误后用 nohup 在后台启动，并从一开始就重定向 stdout 和 stderr。
+把 PID、输出目录和日志路径发给我，再检查一次进程是否仍在运行、日志是否已经开始写入。
+```
+
+插件默认限制前台命令的执行时间，但通过 `nohup` 等方式启动的后台任务可以继续在服务器运行。
+
+### 3. 管理多台服务器
+
+先配置训练机：
+
+```text
+/remote ssh root@10.0.0.21 -p 22
+/remote config note 8xH100 训练机
+/remote config cwd /srv/train
+```
+
+再配置预发布服务器：
+
+```text
+/remote ssh ubuntu@staging.example.com -p 2222
+/remote config note 预发布 API
+/remote config cwd /opt/service
+```
+
+查看并切换服务器：
+
+```text
+/remote config
+/remote use root@10.0.0.21:22
+/remote
+```
+
+备注和默认目录会按 `user@host:port` 分别保存，不会互相覆盖。
+
+### 4. 远端启动模型，本地开发界面
+
+保存并启动端口转发：
+
+```text
+/remote config forward 7860:127.0.0.1:7860
+/remote forward
+```
+
+现在访问本地 `localhost:7860`，实际连接的是远程服务器上的 7860 端口；与此同时，Pi 的文件和 Shell 工具会留在本地，方便继续修改前端或客户端代码。
+
+停止转发：
+
+```text
+/remote unforward
+```
+
+### 5. 直接用自然语言操作
+
+不想记命令时，可以直接告诉 Pi：
+
+```text
+连接已配置的远程服务器，进入 /srv/api，然后检查 Git 状态。
+```
 
 ```text
-/remote config display-lines 10
-/remote exec --lines 20 COMMAND
+把当前服务器备注为“线上只读机”，然后告诉我现在操作的是哪台服务器。
 ```
 
-`ssh_remote_control` 工具的 `exec` 操作也支持 `displayLines`。预览设置只影响折叠界面；提供给模型的输出仍采用 Pi 的 2000 行／50KB 安全限制，超限完整输出会保存到临时文件。
+```text
+把远端 8000 端口转发到本地 8000，但代码工具继续留在本地。
+```
+
+Pi 会通过插件提供的 `ssh_remote_control` 工具完成这些操作。
+
+## 命令说明
+
+| 命令 | 作用 |
+|---|---|
+| `/remote ssh USER@HOST -p PORT` | 保存并连接服务器 |
+| `/remote` | 连接当前选中的服务器，或提示输入 SSH 地址 |
+| `/remote config` | 查看已保存的服务器和配置 |
+| `/remote use USER@HOST:PORT` | 切换到指定服务器 |
+| `/remote config note TEXT` | 给当前服务器添加或修改备注 |
+| `/remote config note --clear` | 清除当前服务器备注 |
+| `/remote config cwd PATH` | 设置默认远程工作目录 |
+| `/remote cd PATH` | 切换当前远程目录并保存 |
+| `/remote config forward MAPPING...` | 保存端口转发配置，例如 `7860:127.0.0.1:7860` |
+| `/remote forward [MAPPING...]` | 启动端口转发，并让 Pi 工具留在本地 |
+| `/remote unforward` | 停止插件创建的端口转发 |
+| `/remote exec COMMAND` | 在当前远程目录执行一次命令 |
+| `/remote exec --timeout 60 COMMAND` | 单独设置本次命令的超时时间 |
+| `/remote exec --lines 20 COMMAND` | 单独设置本次折叠显示的行数 |
+| `/remote config display-lines 10` | 设置默认折叠显示行数 |
+| `/remote status` | 查看当前连接和工作目录 |
+| `/remote reload` | 重新连接当前服务器 |
+| `/remote off` | 断开连接并返回本地 |
+| `/remote forget` | 断开连接并清除内存中的密码 |
+
+## 配置保存在哪里
+
+服务器配置保存在本地：
+
+```text
+~/.pi/agent/ssh-remote-config.json
+```
+
+其中包括：
+
+- 已保存的服务器；
+- 当前选中的服务器；
+- 服务器备注；
+- 默认远程目录；
+- 端口转发配置；
+- 命令预览设置。
 
-使用 `/remote config` 查看服务器，使用 `/remote` 查看全部子命令。
+密码不会写入配置文件。插件会优先使用 SSH agent；如果需要手动输入密码，密码只会缓存在当前 Pi 进程的内存中。
 
-## 认证与安全
+## 安全与输出限制
 
-优先使用 SSH agent，否则提示输入密码。密码仅缓存在进程内存中。首次连接或主机密钥变化时必须确认；主机密钥独立于 OpenSSH 存储。
+- 第一次连接新服务器时，需要确认主机密钥；
+- 主机密钥发生变化时，会再次要求确认；
+- 远程命令默认 30 秒超时；
+- 发送给模型的命令输出最多为 2,000 行或 50 KB；
+- 超限的完整输出会保存到本地临时文件；
+- 折叠显示行数只影响界面，不影响模型输出上限。
 
-目前仅支持带 `-p` 和 `-l` 的直连 SSH 命令，暂不支持 `~/.ssh/config`、`IdentityFile` 和 ProxyJump。
+## 当前限制
 
-要求 Node.js 20+；远程服务器需提供 Bash、SFTP 和 GNU `timeout`。
+目前只支持 SSH 直连，以及 `-p`、`-l` 参数。暂不读取 `~/.ssh/config`，也不支持 `IdentityFile` 和 ProxyJump。
 
-采用 MIT 许可证。
+MIT License。

package/index.ts

@@ -54,6 +54,7 @@ interface RemoteEndpointConfig {
   sshCommand?: string;
   remoteCwd?: string;
   forwards?: string[];
+  note?: string;
 }
 
 interface RemoteConfig {
@@ -77,6 +78,8 @@ const KNOWN_HOSTS_FILE = join(AGENT_DIR, "ssh-remote-known-hosts.json");
 const REMOTE_CONFIG_FILE = join(AGENT_DIR, "ssh-remote-config.json");
 const FALLBACK_REMOTE_CWD = "~";
 const DEFAULT_DISPLAY_LINES = 5;
+const DEFAULT_REMOTE_TIMEOUT_SECONDS = 30;
+const MAX_REMOTE_TIMEOUT_SECONDS = 2_147_483_647 / 1000;
 const CACHE_KEY = "__piHpcCredentialCacheV1";
 const cacheHost = globalThis as typeof globalThis & { [CACHE_KEY]?: CredentialCache };
 const credentialCache = cacheHost[CACHE_KEY] ??= { passwords: new Map<string, string>() };
@@ -162,6 +165,18 @@ function parseDisplayLines(value: unknown): number {
   return lines;
 }
 
+function parseRemoteTimeout(value: unknown): number {
+  const seconds = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(seconds) || seconds <= 0 || seconds > MAX_REMOTE_TIMEOUT_SECONDS) {
+    throw new Error(`Timeout must be a positive number no greater than ${MAX_REMOTE_TIMEOUT_SECONDS} seconds`);
+  }
+  return seconds;
+}
+
+function withRemoteTimeout(command: string, timeoutSeconds: number): string {
+  return `timeout --signal=TERM --kill-after=5s ${timeoutSeconds}s bash -lc ${quote(command)}`;
+}
+
 function configuredDisplayLines(config = loadRemoteConfig()): number {
   try { return parseDisplayLines(config.displayLines ?? DEFAULT_DISPLAY_LINES); }
   catch { return DEFAULT_DISPLAY_LINES; }
@@ -232,6 +247,11 @@ function activeSshCommand(config = loadRemoteConfig()): string | undefined {
   return activeEndpointConfig(config)?.sshCommand;
 }
 
+function endpointDisplayLabel(endpoint: ParsedSsh, config = loadRemoteConfig()): string {
+  const note = endpointConfig(config, endpoint.command).note?.trim();
+  return note ? `${note} (${endpoint.label})` : endpoint.label;
+}
+
 function saveEndpointConfig(command: string, updates: RemoteEndpointConfig, makeActive = false): void {
   const config = loadRemoteConfig();
   const key = cacheId(parseSshCommand(command));
@@ -357,16 +377,34 @@ function connect(config: ParsedSsh, password: string | undefined, fingerprint: s
   });
 }
 
-function execRemote(client: Client, command: string, allowFailure = false): Promise<Buffer> {
+function execRemote(
+  client: Client,
+  command: string,
+  allowFailure = false,
+  timeoutSeconds = DEFAULT_REMOTE_TIMEOUT_SECONDS,
+): Promise<Buffer> {
+  const resolvedTimeout = parseRemoteTimeout(timeoutSeconds);
   return new Promise((resolve, reject) => {
-    client.exec(command, (error, stream) => {
+    client.exec(withRemoteTimeout(command, resolvedTimeout), (error, stream) => {
       if (error) return reject(error);
       const stdout: Buffer[] = [];
       const stderr: Buffer[] = [];
+      let locallyTimedOut = false;
+      const timer = setTimeout(() => {
+        locallyTimedOut = true;
+        stream.close();
+      }, (resolvedTimeout + 8) * 1000);
+      const cleanup = () => clearTimeout(timer);
       stream.on("data", (chunk: Buffer) => stdout.push(chunk));
       stream.stderr.on("data", (chunk: Buffer) => stderr.push(chunk));
+      stream.once("error", (streamError: Error) => {
+        cleanup();
+        reject(streamError);
+      });
       stream.on("close", (code: number | null) => {
-        if (!allowFailure && code !== 0) reject(new Error(Buffer.concat(stderr).toString().trim() || `Remote command exited with code ${code}`));
+        cleanup();
+        if (locallyTimedOut || code === 124 || code === 137) reject(new Error(`Remote command timed out after ${resolvedTimeout} seconds`));
+        else if (!allowFailure && code !== 0) reject(new Error(Buffer.concat(stderr).toString().trim() || `Remote command exited with code ${code}`));
         else resolve(Buffer.concat(stdout));
       });
     });
@@ -442,8 +480,8 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
   const status = (ctx: any) => {
     currentCtx = ctx;
     if (!remote) ctx.ui.setStatus("ssh-remote", undefined);
-    else if (routeRemoteTools) ctx.ui.setStatus("ssh-remote", ctx.ui.theme.fg("accent", `SSH remote ${remote.label}:${remote.cwd}`));
-    else ctx.ui.setStatus("ssh-remote", ctx.ui.theme.fg("accent", `SSH remote tunnel ${[...forwardServers.keys()].join(",") || remote.label}`));
+    else if (routeRemoteTools) ctx.ui.setStatus("ssh-remote", ctx.ui.theme.fg("accent", `SSH remote ${endpointDisplayLabel(remote)}:${remote.cwd}`));
+    else ctx.ui.setStatus("ssh-remote", ctx.ui.theme.fg("accent", `SSH remote tunnel ${[...forwardServers.keys()].join(",") || endpointDisplayLabel(remote)}`));
   };
 
   const attachClient = (state: RemoteState) => {
@@ -451,7 +489,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
     client.on("close", () => {
       if (remote?.client !== client) return;
       if (currentCtx) {
-        currentCtx.ui.setStatus("ssh-remote", currentCtx.ui.theme.fg("warning", `SSH remote reconnecting ${state.label}…`));
+        currentCtx.ui.setStatus("ssh-remote", currentCtx.ui.theme.fg("warning", `SSH remote reconnecting ${endpointDisplayLabel(state)}…`));
       }
       void reconnectRemote().catch((error) => {
         if (currentCtx) currentCtx.ui.notify(`SSH remote automatic reconnection failed: ${(error as Error).message}`, "error");
@@ -490,7 +528,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
       oldClient?.end();
       if (currentCtx) {
         status(currentCtx);
-        currentCtx.ui.notify(`SSH remote reconnected automatically: ${next.label}:${next.cwd}`, "info");
+        currentCtx.ui.notify(`SSH remote reconnected automatically: ${endpointDisplayLabel(next)}:${next.cwd}`, "info");
       }
       return next;
     })().finally(() => { reconnectPromise = null; });
@@ -560,7 +598,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
     }
 
     let password = getCachedPassword(parsed);
-    ctx.ui.setStatus("ssh-remote", ctx.ui.theme.fg("warning", `SSH remote connecting ${parsed.label}…`));
+    ctx.ui.setStatus("ssh-remote", ctx.ui.theme.fg("warning", `SSH remote connecting ${endpointDisplayLabel(parsed)}…`));
     try {
       let next: RemoteState;
       try {
@@ -585,7 +623,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
       lastConnectionError = undefined;
       saveEndpointConfig(command, { remoteCwd: next.cwd }, true);
       status(ctx);
-      ctx.ui.notify(`SSH remote connected: ${parsed.label}:${next.cwd}`, "info");
+      ctx.ui.notify(`SSH remote connected: ${endpointDisplayLabel(next)}:${next.cwd}`, "info");
       return next;
     } catch (error) {
       deleteCachedPassword(parsed);
@@ -688,23 +726,21 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
 
   const remoteBashOps = (): BashOperations => ({
     exec: (command, cwd, { onData, signal, timeout }) => new Promise((resolve, reject) => {
-      const timeoutSeconds = timeout ? Math.max(1, Math.ceil(timeout)) : undefined;
-      const remoteCommand = timeoutSeconds
-        ? `timeout --signal=TERM --kill-after=5s ${timeoutSeconds}s bash -lc ${quote(command)}`
-        : command;
+      const timeoutSeconds = parseRemoteTimeout(timeout ?? DEFAULT_REMOTE_TIMEOUT_SECONDS);
+      const remoteCommand = withRemoteTimeout(command, timeoutSeconds);
       const full = `cd -- ${quote(mapPath(cwd))} && ${remoteCommand}`;
       void openExecChannel(full).then((stream) => {
         let timedOut = false;
-        const timer = timeoutSeconds ? setTimeout(() => { timedOut = true; stream.close(); }, (timeoutSeconds + 8) * 1000) : undefined;
+        const timer = setTimeout(() => { timedOut = true; stream.close(); }, (timeoutSeconds + 8) * 1000);
         const abort = () => stream.close();
         signal?.addEventListener("abort", abort, { once: true });
         stream.on("data", onData);
         stream.stderr.on("data", onData);
         stream.on("close", (code: number | null) => {
-          if (timer) clearTimeout(timer);
+          clearTimeout(timer);
           signal?.removeEventListener("abort", abort);
           if (signal?.aborted) reject(new Error("aborted"));
-          else if (timedOut || code === 124) reject(new Error(`timeout:${timeoutSeconds}`));
+          else if (timedOut || code === 124 || code === 137) reject(new Error(`timeout:${timeoutSeconds}`));
           else resolve({ exitCode: code });
         });
       }, reject);
@@ -723,25 +759,28 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
   pi.registerTool({
     name: "ssh_remote_control",
     label: "SSH Remote Control",
-    description: "Connect, reconnect, change the persistent remote working directory, inspect, forward ports, run remote SSH commands, or disconnect the configured SSH environment. Exec output uses a configurable collapsed preview (5 visual lines by default), while model output is limited to 50KB or 2000 lines and saved to a local temporary file when truncated. Passwords are never accepted as arguments and are cached only in process memory.",
-    promptSnippet: "Control the configured remote SSH connection, working directory, and local port forwarding",
+    description: "Connect, reconnect, annotate endpoints, change the persistent remote working directory, inspect, forward ports, run remote SSH commands, or disconnect the configured SSH environment. Exec output uses a configurable collapsed preview (5 visual lines by default), while model output is limited to 50KB or 2000 lines and saved to a local temporary file when truncated. Passwords are never accepted as arguments and are cached only in process memory.",
+    promptSnippet: "Control the configured remote SSH connection, endpoint note, working directory, and local port forwarding",
     promptGuidelines: [
       "Use ssh_remote_control when the user asks the agent to enter, reconnect, inspect, or leave a remote SSH environment.",
       "Use ssh_remote_control with action chdir when the user asks to change the remote working directory; do not emulate a persistent directory change with action exec and a one-command cwd.",
+      `Always set timeout for ssh_remote_control remote exec commands; it defaults to ${DEFAULT_REMOTE_TIMEOUT_SECONDS} seconds when omitted.`,
       "Use ssh_remote_control with action disconnect after remote work when the user asks to return to the local environment.",
     ],
     parameters: Type.Object({
-      action: StringEnum(["connect", "reconnect", "status", "disconnect", "forget", "forward", "unforward", "exec", "chdir"] as const),
-      command: Type.Optional(Type.String({ description: "SSH command for connect, such as ssh root@host -p 22" })),
+      action: StringEnum(["connect", "reconnect", "status", "disconnect", "forget", "forward", "unforward", "exec", "chdir", "note"] as const),
+      command: Type.Optional(Type.String({ description: "SSH command for connect, such as ssh root@host -p 22; optionally selects the endpoint for note" })),
+      note: Type.Optional(Type.String({ description: "Endpoint note for the note action; omit or use an empty string to clear it" })),
       cwd: Type.Optional(Type.String({ description: "Remote working directory; required for chdir, and a one-command override for exec" })),
       forwards: Type.Optional(Type.String({ description: "Space-separated LOCAL_PORT:REMOTE_HOST:REMOTE_PORT mappings; defaults to ssh-remote-config.json" })),
       remoteCommand: Type.Optional(Type.String({ description: "Remote shell command for the exec action" })),
+      timeout: Type.Optional(Type.Number({ minimum: 1, maximum: MAX_REMOTE_TIMEOUT_SECONDS, description: `Remote command timeout in seconds; defaults to ${DEFAULT_REMOTE_TIMEOUT_SECONDS}` })),
       displayLines: Type.Optional(Type.Integer({ minimum: 1, maximum: DEFAULT_MAX_LINES, description: "Collapsed visual lines for exec output; defaults to the /remote config display-lines setting (5 initially)" })),
     }),
     async execute(_id, params, _signal, _update, ctx) {
       if (params.action === "status") {
         const mappings = [...forwardServers.keys()].sort((a, b) => a - b);
-        const text = `${remote ? `Connected: ${remote.label}:${remote.cwd}; tool routing: ${routeRemoteTools ? "remote" : "local"}` : "SSH remote is disconnected"}${mappings.length ? `; forwarded local ports: ${mappings.join(", ")}` : ""}`;
+        const text = `${remote ? `Connected: ${endpointDisplayLabel(remote)}:${remote.cwd}; tool routing: ${routeRemoteTools ? "remote" : "local"}` : "SSH remote is disconnected"}${mappings.length ? `; forwarded local ports: ${mappings.join(", ")}` : ""}`;
         return { content: [{ type: "text", text }], details: { connected: Boolean(remote), cwd: remote?.cwd, toolRouting: routeRemoteTools ? "remote" : "local", forwardedPorts: mappings } };
       }
       if (params.action === "disconnect" || params.action === "forget") {
@@ -751,7 +790,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
       if (params.action === "reconnect") {
         if (!remote && !credentialCache.resume) throw new Error("No SSH remote connection is available to reconnect");
         const state = await reconnectRemote();
-        return { content: [{ type: "text", text: `Reconnected: ${state.label}:${state.cwd}` }], details: { connected: true, cwd: state.cwd } };
+        return { content: [{ type: "text", text: `Reconnected: ${endpointDisplayLabel(state)}:${state.cwd}` }], details: { connected: true, cwd: state.cwd } };
       }
       if (params.action === "unforward") {
         await stopForwards();
@@ -774,6 +813,18 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
         const resolved = await changeRemoteCwd(params.cwd, ctx);
         return { content: [{ type: "text", text: `Remote working directory: ${resolved}` }], details: { connected: true, cwd: resolved } };
       }
+      if (params.action === "note") {
+        const command = params.command || lastCommand || activeSshCommand();
+        if (!command) throw new Error("No SSH endpoint configured; connect or select an endpoint first");
+        const note = params.note?.trim() || undefined;
+        saveEndpointConfig(command, { note });
+        if (remote && cacheId(remote) === cacheId(parseSshCommand(command)) && currentCtx) status(currentCtx);
+        const label = parseSshCommand(command).label;
+        return {
+          content: [{ type: "text", text: note ? `SSH remote note updated (${label}): ${note}` : `SSH remote note cleared (${label})` }],
+          details: { endpoint: label, note },
+        };
+      }
       if (params.action === "exec") {
         const state = await ensureConnected(ctx);
         if (!params.remoteCommand) throw new Error("remoteCommand is required for exec");
@@ -783,7 +834,13 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
           return { content: [{ type: "text", text: resolved }], details: { connected: true, cwd: resolved } };
         }
         const displayLines = parseDisplayLines(params.displayLines ?? configuredDisplayLines());
-        const output = await withReconnect((client) => execRemote(client, `cd -- ${quote(params.cwd ?? state.cwd)} && ${params.remoteCommand}`));
+        const timeoutSeconds = parseRemoteTimeout(params.timeout ?? DEFAULT_REMOTE_TIMEOUT_SECONDS);
+        const output = await withReconnect((client) => execRemote(
+          client,
+          `cd -- ${quote(params.cwd ?? state.cwd)} && ${params.remoteCommand}`,
+          false,
+          timeoutSeconds,
+        ));
         const formatted = formatRemoteOutput(output.toString());
         return {
           content: [{ type: "text", text: formatted.text }],
@@ -802,7 +859,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
       if (!command) throw new Error(`No SSH endpoint configured. Set ${REMOTE_CONFIG_FILE} or pass command.`);
       const state = await connectInteractive(command, ctx, params.cwd ?? configuredCwd(command));
       if (!state) throw new Error(lastConnectionError || "SSH remote connection was cancelled or failed");
-      return { content: [{ type: "text", text: `Connected: ${state.label}:${state.cwd}` }], details: { connected: true, cwd: state.cwd } };
+      return { content: [{ type: "text", text: `Connected: ${endpointDisplayLabel(state)}:${state.cwd}` }], details: { connected: true, cwd: state.cwd } };
     },
     renderResult(result, { expanded }, theme) {
       return renderRemoteControlResult(result, expanded, theme);
@@ -810,7 +867,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
   });
 
   pi.registerCommand("remote", {
-    description: "Connect over SSH and manage endpoints: /remote | ssh USER@HOST [-p PORT] | config | use USER@HOST:PORT | config cwd PATH | config display-lines N | forward [MAPPINGS] | unforward | exec [--lines N] COMMAND | cd PATH | status | reload | off | forget",
+    description: "Connect over SSH and manage endpoints: /remote | ssh USER@HOST [-p PORT] | config | use USER@HOST:PORT | config note TEXT|--clear | config cwd PATH | config display-lines N | forward [MAPPINGS] | unforward | exec [--timeout SECONDS] [--lines N] COMMAND | cd PATH | status | reload | off | forget",
     handler: async (args, ctx) => {
       const input = args.trim().replace(/^\/?remote(?:\s+|$)/i, "").trim();
       const action = input.toLowerCase();
@@ -818,7 +875,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
         const config = loadRemoteConfig();
         const rows = Object.entries(config.endpoints ?? {}).map(([key, endpoint]) => {
           const active = key === config.activeEndpoint ? "*" : " ";
-          return `${active} ${key}\n    SSH: ${endpoint.sshCommand}\n    cwd: ${endpoint.remoteCwd || FALLBACK_REMOTE_CWD}\n    forward: ${endpoint.forwards?.join(", ") || "none"}`;
+          return `${active} ${key}\n    note: ${endpoint.note || "none"}\n    SSH: ${endpoint.sshCommand}\n    cwd: ${endpoint.remoteCwd || FALLBACK_REMOTE_CWD}\n    forward: ${endpoint.forwards?.join(", ") || "none"}`;
         });
         ctx.ui.notify(`SSH remote configuration: ${REMOTE_CONFIG_FILE}\nDisplay lines: ${configuredDisplayLines(config)}\n${rows.join("\n") || "No saved endpoints"}`, "info");
         return;
@@ -859,6 +916,17 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
         ctx.ui.notify(`Selected SSH remote endpoint: ${key}; use /remote to connect`, "info");
         return;
       }
+      if (/^config\s+note(?:\s+|$)/i.test(input)) {
+        const value = input.replace(/^config\s+note\s*/i, "").trim();
+        if (!value) { ctx.ui.notify("Use /remote config note TEXT or /remote config note --clear", "error"); return; }
+        const command = lastCommand || activeSshCommand();
+        if (!command) { ctx.ui.notify("Configure an SSH endpoint first", "error"); return; }
+        const note = value.toLowerCase() === "--clear" ? undefined : value;
+        saveEndpointConfig(command, { note });
+        if (remote && cacheId(remote) === cacheId(parseSshCommand(command))) status(ctx);
+        ctx.ui.notify(note ? `SSH remote note updated (${parseSshCommand(command).label}): ${note}` : `SSH remote note cleared (${parseSshCommand(command).label})`, "info");
+        return;
+      }
       if (/^config\s+display-lines\s+/i.test(input)) {
         try {
           const displayLines = parseDisplayLines(input.replace(/^config\s+display-lines\s+/i, "").trim());
@@ -907,11 +975,22 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
       if (/^exec\s+/i.test(input)) {
         try {
           const state = await ensureConnected(ctx);
-          const execInput = input.replace(/^exec\s+/i, "");
-          const linesMatch = execInput.match(/^--lines\s+(\S+)\s+([\s\S]+)$/i);
-          const displayLines = linesMatch ? parseDisplayLines(linesMatch[1]) : configuredDisplayLines();
-          const remoteCommand = linesMatch ? linesMatch[2]! : execInput;
-          const output = (await withReconnect((client) => execRemote(client, `cd -- ${quote(state.cwd)} && ${remoteCommand}`))).toString().trim();
+          let execInput = input.replace(/^exec\s+/i, "").trim();
+          let displayLines = configuredDisplayLines();
+          let timeoutSeconds = DEFAULT_REMOTE_TIMEOUT_SECONDS;
+          while (execInput.startsWith("--")) {
+            const option = execInput.match(/^--(lines|timeout)\s+(\S+)\s+([\s\S]+)$/i);
+            if (!option) throw new Error("Expected --lines N or --timeout SECONDS followed by a command");
+            if (option[1]!.toLowerCase() === "lines") displayLines = parseDisplayLines(option[2]);
+            else timeoutSeconds = parseRemoteTimeout(option[2]);
+            execInput = option[3]!;
+          }
+          const output = (await withReconnect((client) => execRemote(
+            client,
+            `cd -- ${quote(state.cwd)} && ${execInput}`,
+            false,
+            timeoutSeconds,
+          ))).toString().trim();
           const formatted = formatRemoteOutput(output);
           const preview = previewRemoteOutput(formatted.content, displayLines);
           const omitted = formatted.truncation.totalLines > displayLines
@@ -925,7 +1004,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
       if (["off", "disconnect", "exit"].includes(action)) { disconnect(ctx); return; }
       if (action === "forget") { disconnect(ctx, true); return; }
       if (action === "status") {
-        ctx.ui.notify(remote ? `${remote.label}:${remote.cwd}` : "SSH remote is disconnected", "info");
+        ctx.ui.notify(remote ? `${endpointDisplayLabel(remote)}:${remote.cwd}` : "SSH remote is disconnected", "info");
         return;
       }
       if (["reload", "reconnect"].includes(action)) {
@@ -978,7 +1057,7 @@ export default function sshRemoteExtension(pi: ExtensionAPI) {
   pi.on("before_agent_start", (event) => remote && routeRemoteTools ? {
     systemPrompt: event.systemPrompt.replace(
       `Current working directory: ${localCwd}`,
-      `Current working directory: ${remote.cwd} (via SSH ${remote.label}). All read, write, edit, bash, and user shell operations run on this remote server. Use ssh_remote_control with action disconnect to return to the local environment when requested.`,
+      `Current working directory: ${remote.cwd} (via SSH ${endpointDisplayLabel(remote)}). All read, write, edit, bash, and user shell operations run on this remote server. Use ssh_remote_control with action disconnect to return to the local environment when requested.`,
     ),
   } : undefined);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ssh-remote",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Persistent remote SSH workspaces for Pi.",
   "type": "module",
   "author": "Yutong Bian",