pi-ssh-remote 0.1.3 → 0.1.5

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, server-specific memory, 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. Server memory is automatically injected into the model context whenever that endpoint is connected as the active remote workspace.
+
+### 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,241 @@ 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 config memory Use /opt/conda/bin/python and never stop shared jobs.
 /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, working directories, and server-specific memories survive Pi restarts because they are stored in the local remote configuration. When Pi connects to an endpoint, its memory is added to the system context on every agent run while remote tool routing remains active. Disconnecting or switching to tunnel-only mode removes it from subsequent model requests.
+
+### 4. Expose a remote service while editing locally
+
+```text
+/remote config forward 7860:127.0.0.1:7860
+/remote forward
+```
+
+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.
+
+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 memory TEXT` | Persist context that is injected while working on this endpoint |
+| `/remote config memory --clear` | Clear its server-specific memory |
+| `/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
-/remote config display-lines 10
-/remote exec --lines 20 COMMAND
+~/.pi/agent/ssh-remote-config.json
 ```
 
-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.
+Saved values include endpoints, active endpoint, notes, server-specific memories, remote working directories, forwards, and preview settings. Server memory is user-configured trusted context and is inserted into each model request only while that endpoint is the active remote workspace; it is not read from the remote server. Passwords are **never written to this file**: SSH agent authentication is preferred, and prompted passwords remain only in process memory.
+
+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.
+
+## Current SSH scope
+
+The extension currently supports direct SSH commands with `-p` and `-l`. It does not yet consume `~/.ssh/config`, `IdentityFile`, or ProxyJump settings.
+
+## Release history
+
+Release dates below are npm publication dates. Every release records user-visible additions, changes, and bug fixes; `None` means that category had no changes in that release.
+
+### 0.1.5 — 2026-08-04
+
+**Added**
+
+- Added persistent, endpoint-specific server memory through `/remote config memory TEXT` and the `ssh_remote_control` `memory` action.
+- Added automatic injection of that memory into every model request while the matching endpoint is the active remote workspace.
+
+**Changed**
+
+- Server memory is removed from subsequent model requests when remote tool routing is disabled, including disconnect and tunnel-only mode.
+- `/remote config` now shows the memory stored for each endpoint.
+
+**Fixed**
+
+- None.
+
+### 0.1.4 — 2026-07-31
+
+**Added**
+
+- Added persistent endpoint notes through `/remote config note TEXT` and the `ssh_remote_control` `note` action.
+- Added per-command timeout overrides through `/remote exec --timeout SECONDS` and the tool's `timeout` parameter.
+
+**Changed**
+
+- Remote commands now default to a 30-second timeout and endpoint notes appear in status, connection, reconnection, and footer labels.
+- Expanded the documentation around agent-first workflows, multi-server operation, background jobs, and tunnel mode.
+
+**Fixed**
+
+- Fixed remote commands that could run without a deadline by enforcing GNU `timeout` remotely and a local fallback timer.
+- Fixed timeout reporting for processes terminated with timeout-related exit codes 124 and 137.
+
+### 0.1.3 — 2026-07-24
+
+**Added**
+
+- Added configurable collapsed command previews with `/remote config display-lines N`, `/remote exec --lines N`, and the tool's `displayLines` parameter.
+- Added expandable custom rendering for remote command results.
+
+**Changed**
+
+- Remote command previews default to the last five visual lines while model-facing output remains limited to 2,000 lines or 50 KB.
+- Oversized complete output is saved to a permission-restricted local temporary file.
+
+**Fixed**
+
+- Fixed `/remote exec` truncating its notification to an arbitrary 4,000 characters without preserving or identifying the full output.
+
+### 0.1.2 — 2026-07-24
+
+**Added**
+
+- None.
+
+**Changed**
+
+- Republished the 0.1.1 runtime as 0.1.2 to align npm package version metadata; there were no runtime code changes.
+
+**Fixed**
+
+- None.
+
+### 0.1.1 — 2026-07-24
+
+**Added**
+
+- Added the shorter `/remote ssh USER@HOST [-p PORT]` connection command.
+
+**Changed**
+
+- `/remote ssh` now saves, selects, and immediately connects to the endpoint instead of only storing it.
+
+**Fixed**
+
+- Fixed help and error text that still instructed users to run the obsolete `/remote config ssh ssh ...` form.
+
+### 0.1.0 — 2026-07-24
+
+**Added**
 
-Run `/remote config` to list endpoints and `/remote` to see all available subcommands.
+- Initial release with persistent multi-endpoint SSH workspaces and remote working directories.
+- Added transparent routing for Pi's `read`, `write`, `edit`, `bash`, and user shell operations.
+- Added SSH-agent/password authentication, interactive host-key verification, automatic reconnection, SFTP file access, bounded command output, and local TCP forwarding.
 
-## Authentication and security
+**Changed**
 
-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.
+- None.
 
-Only direct SSH commands with `-p` and `-l` are supported. `~/.ssh/config`, `IdentityFile`, and ProxyJump are not currently supported.
+**Fixed**
 
-Requires Node.js 20+, Bash, SFTP, and GNU `timeout` on the remote host.
+- None.
 
 MIT licensed.

package/README.zh-CN.md

@@ -1,12 +1,90 @@
 <!--
-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 训练机`、`预发布环境`、`线上只读机`。还可以为每个 `user@host:port` 保存独立记忆，例如指定 Python 环境、共享任务保护规则或部署约定。连接该 endpoint 并启用远端工具路由后，这段记忆会自动注入模型上下文；断开连接或切换到纯隧道模式后，后续请求不再注入。所有配置保存在本地，重启 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 +92,280 @@ 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 训练机
+/remote config memory 使用 /opt/conda/bin/python，不要停止其他用户的共享任务。
+```
+
+查看当前状态：
 
 ```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 display-lines 10
-/remote exec --lines 20 COMMAND
+/remote config
+/remote use root@10.0.0.21:22
+/remote
 ```
 
-`ssh_remote_control` 工具的 `exec` 操作也支持 `displayLines`。预览设置只影响折叠界面；提供给模型的输出仍采用 Pi 的 2000 行／50KB 安全限制，超限完整输出会保存到临时文件。
+备注和默认目录会按 `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
+把当前服务器备注为“线上只读机”，然后告诉我现在操作的是哪台服务器。
+```
+
+```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 memory TEXT` | 保存连接该服务器时自动注入上下文的记忆 |
+| `/remote config memory --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
+```
+
+其中包括：
+
+- 已保存的服务器；
+- 当前选中的服务器；
+- 服务器备注；
+- 服务器特定记忆；
+- 默认远程目录；
+- 端口转发配置；
+- 命令预览设置。
+
+服务器记忆是由用户在本地配置的可信上下文，不会从远程服务器自动读取；仅当对应 endpoint 作为远端工作区启用时才会加入每次模型请求。
+
+密码不会写入配置文件。插件会优先使用 SSH agent；如果需要手动输入密码，密码只会缓存在当前 Pi 进程的内存中。
+
+## 安全与输出限制
+
+- 第一次连接新服务器时，需要确认主机密钥；
+- 主机密钥发生变化时，会再次要求确认；
+- 远程命令默认 30 秒超时；
+- 发送给模型的命令输出最多为 2,000 行或 50 KB；
+- 超限的完整输出会保存到本地临时文件；
+- 折叠显示行数只影响界面，不影响模型输出上限。
+
+## 当前限制
+
+目前只支持 SSH 直连，以及 `-p`、`-l` 参数。暂不读取 `~/.ssh/config`，也不支持 `IdentityFile` 和 ProxyJump。
+
+## 版本更新记录
+
+以下日期均为 npm 发布时间。每次发布都记录用户可见的新增内容、行为变更和 Bug 修复；“无”表示该版本在对应类别没有变化。
+
+### 0.1.5 — 2026-08-04
+
+**新增**
+
+- 新增 endpoint 级持久化服务器记忆，支持 `/remote config memory TEXT` 和 `ssh_remote_control` 的 `memory` action。
+- 对应 endpoint 作为当前远程工作区时，在每次模型请求中自动注入服务器记忆。
+
+**变更**
+
+- 断开连接、关闭远端工具路由或进入纯隧道模式后，后续模型请求不再包含服务器记忆。
+- `/remote config` 现在会显示每个 endpoint 保存的记忆。
+
+**修复**
+
+- 无。
+
+### 0.1.4 — 2026-07-31
+
+**新增**
+
+- 新增 endpoint 备注，支持 `/remote config note TEXT` 和 `ssh_remote_control` 的 `note` action。
+- 新增单次命令超时覆盖，支持 `/remote exec --timeout SECONDS` 和工具的 `timeout` 参数。
+
+**变更**
+
+- 远程命令默认超时改为 30 秒；备注会显示在状态、连接、重连提示和底部状态栏中。
+- 扩充了 Agent 工作流、多服务器、后台任务和纯隧道模式文档。
+
+**修复**
+
+- 修复部分远程命令没有截止时间、可能一直占用 Agent 的问题：远端使用 GNU `timeout`，本地增加兜底定时器。
+- 修复退出码 124 和 137 未被统一识别为超时的问题。
+
+### 0.1.3 — 2026-07-24
+
+**新增**
+
+- 新增可配置的命令折叠预览，支持 `/remote config display-lines N`、`/remote exec --lines N` 和工具的 `displayLines` 参数。
+- 新增远程命令结果的展开显示。
+
+**变更**
+
+- 命令折叠预览默认显示最后 5 个视觉行；发送给模型的输出仍限制为 2,000 行或 50 KB。
+- 超限的完整输出会保存到权限受限的本地临时文件。
+
+**修复**
+
+- 修复 `/remote exec` 直接按 4,000 字符截断通知、且不保留或提示完整输出位置的问题。
+
+### 0.1.2 — 2026-07-24
+
+**新增**
+
+- 无。
+
+**变更**
+
+- 将 0.1.1 的运行时代码以 0.1.2 重新发布，用于对齐 npm 包版本元数据；没有运行时代码变化。
+
+**修复**
+
+- 无。
+
+### 0.1.1 — 2026-07-24
+
+**新增**
+
+- 新增简化命令 `/remote ssh USER@HOST [-p PORT]`。
+
+**变更**
+
+- `/remote ssh` 现在会保存、选中并立即连接 endpoint，而不只是保存配置。
+
+**修复**
+
+- 修复帮助和错误信息仍提示使用旧命令 `/remote config ssh ssh ...` 的问题。
+
+### 0.1.0 — 2026-07-24
+
+**新增**
 
-使用 `/remote config` 查看服务器，使用 `/remote` 查看全部子命令。
+- 首次发布，支持持久化多 endpoint SSH 工作区和远程工作目录。
+- 新增 Pi `read`、`write`、`edit`、`bash` 和用户 Shell 操作的透明远端路由。
+- 新增 SSH agent/密码认证、交互式主机密钥校验、自动重连、SFTP 文件访问、命令输出限制和本地 TCP 端口转发。
 
-## 认证与安全
+**变更**
 
-优先使用 SSH agent，否则提示输入密码。密码仅缓存在进程内存中。首次连接或主机密钥变化时必须确认；主机密钥独立于 OpenSSH 存储。
+- 无。
 
-目前仅支持带 `-p` 和 `-l` 的直连 SSH 命令，暂不支持 `~/.ssh/config`、`IdentityFile` 和 ProxyJump。
+**修复**
 
-要求 Node.js 20+；远程服务器需提供 Bash、SFTP 和 GNU `timeout`。
+- 无。
 
-采用 MIT 许可证。
+MIT License。

package/index.ts

@@ -54,6 +54,8 @@ interface RemoteEndpointConfig {
   sshCommand?: string;
   remoteCwd?: string;
   forwards?: string[];
+  note?: string;
+  memory?: string;
 }
 
 interface RemoteConfig {
@@ -77,6 +79,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 +166,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 +248,28 @@ 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 endpointMemory(endpoint: ParsedSsh, config = loadRemoteConfig()): string | undefined {
+  return endpointConfig(config, endpoint.command).memory?.trim() || undefined;
+}
+
+function remoteSystemPrompt(systemPrompt: string, localCwd: string, remote: RemoteState): string {
+  return systemPrompt.replace(
+    `Current working directory: ${localCwd}`,
+    `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.`,
+  );
+}
+
+function serverMemoryContext(remote: RemoteState): string | undefined {
+  const memory = endpointMemory(remote);
+  if (!memory) return undefined;
+  return `<ssh_remote_server_memory endpoint="${remote.label}">\nThe following is user-configured, persistent memory specific to this SSH server. Apply it while working on this server:\n${memory}\n</ssh_remote_server_memory>`;
+}
+
 function saveEndpointConfig(command: string, updates: RemoteEndpointConfig, makeActive = false): void {
   const config = loadRemoteConfig();
   const key = cacheId(parseSshCommand(command));
@@ -357,16 +395,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 +498,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 +507,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 +546,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 +616,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 +641,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 +744,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 +777,29 @@ 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, manage server-specific memory, 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 and memory, 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", "memory"] 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 or memory" })),
+      note: Type.Optional(Type.String({ description: "Endpoint note for the note action; omit or use an empty string to clear it" })),
+      memory: Type.Optional(Type.String({ description: "Persistent server-specific context for the memory 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 +809,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 +832,26 @@ 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" || params.action === "memory") {
+        const command = params.command || lastCommand || activeSshCommand();
+        if (!command) throw new Error("No SSH endpoint configured; connect or select an endpoint first");
+        const label = parseSshCommand(command).label;
+        if (params.action === "note") {
+          const note = params.note?.trim() || undefined;
+          saveEndpointConfig(command, { note });
+          if (remote && cacheId(remote) === cacheId(parseSshCommand(command)) && currentCtx) status(currentCtx);
+          return {
+            content: [{ type: "text", text: note ? `SSH remote note updated (${label}): ${note}` : `SSH remote note cleared (${label})` }],
+            details: { endpoint: label, note },
+          };
+        }
+        const memory = params.memory?.trim() || undefined;
+        saveEndpointConfig(command, { memory });
+        return {
+          content: [{ type: "text", text: memory ? `SSH remote server memory updated (${label}). It will be injected while this endpoint is the active remote workspace.` : `SSH remote server memory cleared (${label}).` }],
+          details: { endpoint: label, memory },
+        };
+      }
       if (params.action === "exec") {
         const state = await ensureConnected(ctx);
         if (!params.remoteCommand) throw new Error("remoteCommand is required for exec");
@@ -783,7 +861,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 +886,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 +894,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 memory 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 +902,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    memory: ${endpoint.memory || "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 +943,27 @@ 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+memory(?:\s+|$)/i.test(input)) {
+        const value = input.replace(/^config\s+memory\s*/i, "").trim();
+        if (!value) { ctx.ui.notify("Use /remote config memory TEXT or /remote config memory --clear", "error"); return; }
+        const command = lastCommand || activeSshCommand();
+        if (!command) { ctx.ui.notify("Configure an SSH endpoint first", "error"); return; }
+        const memory = value.toLowerCase() === "--clear" ? undefined : value;
+        saveEndpointConfig(command, { memory });
+        ctx.ui.notify(memory ? `SSH remote server memory updated (${parseSshCommand(command).label}); it will be injected while connected` : `SSH remote server memory 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 +1012,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 +1041,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)) {
@@ -976,9 +1092,20 @@ 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.`,
-    ),
+    systemPrompt: remoteSystemPrompt(event.systemPrompt, localCwd, remote),
   } : undefined);
+  pi.on("context", (event) => {
+    if (!remote || !routeRemoteTools) return undefined;
+    const content = serverMemoryContext(remote);
+    if (!content) return undefined;
+    return {
+      messages: [...event.messages, {
+        role: "custom",
+        customType: "ssh-remote-server-memory",
+        content,
+        display: false,
+        timestamp: Date.now(),
+      }],
+    };
+  });
 }

package/package.json

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