agent-assh 1.0.2 → 1.1.0

package/AGENT_INSTRUCTIONS.md

@@ -11,6 +11,8 @@ assh version
 
 ## First SSH Step
 
+Prefer `assh connect --ssh-config ALIAS` for hosts already in `~/.ssh/config`.
+
 If the user pasted a provider server-info block, write the block to a temporary file with mode `0600`, run:
 
 ```bash
@@ -31,6 +33,12 @@ If key login is already configured:
 assh connect -H HOST -u root -i ~/.ssh/id_agent_ed25519 -n NAME
 ```
 
+If host is in `~/.ssh/config`:
+
+```bash
+assh connect --ssh-config my-alias -n NAME
+```
+
 Use the returned `sid` and `next_commands`.
 
 ## Normal Workflow
@@ -43,6 +51,12 @@ assh session read -s SID --seq 2 --stream stderr --limit 50
 assh session close -s SID
 ```
 
+Pre/post hooks:
+
+```bash
+assh session exec -s SID --before "git stash" --after "git stash pop" -- "deploy.sh"
+```
+
 Clean up stale trusted sessions:
 
 ```bash
@@ -58,6 +72,104 @@ assh exec -H HOST -u root -i KEY -- "df -h"
 assh read --id OUTPUT_ID --limit 50
 ```
 
+## Host Scanning
+
+```bash
+assh scan -H HOST -u USER
+# Returns JSON with hostname, OS, kernel, arch, CPU cores, IP, uptime, load, memory, disk
+```
+
+## File Operations
+
+```bash
+assh transfer list -H HOST -u USER --path /var/log
+assh transfer stat -H HOST -u USER --path /etc/nginx.conf
+assh transfer put -H HOST -u USER LOCAL_PATH REMOTE_PATH
+assh transfer get -H HOST -u USER REMOTE_PATH LOCAL_PATH
+assh transfer sync --direction push --source ./dist --dest /var/www -H HOST -u USER
+assh transfer sync --direction pull --source /var/log --dest ./logs -H HOST -u USER
+assh transfer mkdir -H HOST -u USER --path /opt/newapp
+assh transfer rm -H HOST -u USER --path /tmp/junk.log
+assh transfer rm -H HOST -u USER --path /tmp/old --recursive
+assh transfer mv -H HOST -u USER --source /tmp/a --dest /tmp/b
+```
+
+## Process Management
+
+```bash
+assh session ps -s SID --top 20
+assh session ps -s SID --filter nginx
+assh session kill -s SID --pid 1234
+assh session kill -s SID --pid 1234 --signal KILL
+```
+
+## Service Management
+
+```bash
+assh session service -s SID --action status --service nginx
+assh session service -s SID --action restart --service docker
+assh session service -s SID --action start --service postgresql
+assh session service -s SID --action stop --service apache2
+assh session service -s SID --action logs --service nginx --lines 100
+```
+
+## Background Jobs
+
+For long-running commands (builds, deployments):
+
+```bash
+assh session exec-async -s SID -- "make build"
+# Returns job_id for tracking
+assh session job-status -s SID --job-id JOB_ID
+assh session job-cancel -s SID --job-id JOB_ID
+```
+
+## Docker Management
+
+```bash
+assh session docker-ps -s SID
+assh session docker-ps -s SID -a  # all containers including stopped
+assh session docker-logs -s SID --container myapp --tail 100
+assh session docker-exec -s SID --container myapp -- "ls -la /app"
+```
+
+## Database Query (Read-Only)
+
+Only SELECT, SHOW, DESCRIBE, and EXPLAIN queries are allowed for safety:
+
+```bash
+assh session db-query -s SID --type mysql -d mydb -q "SELECT COUNT(*) FROM users"
+assh session db-query -s SID --type postgres -d mydb -q "SELECT * FROM orders LIMIT 10"
+assh session db-query -s SID --type mysql -d mydb -U dbuser -W dbpass -q "SHOW TABLES"
+```
+
+## Fleet (Multi-Host)
+
+Execute the same command across multiple hosts in parallel:
+
+```bash
+assh fleet exec -H host1 -H host2 -H host3 -u root -- "uptime"
+assh fleet exec -H web01 -H web02 -u deploy -i ~/.ssh/id_ed25519 -- "df -h"
+```
+
+## Session Observability
+
+Watch what the agent is doing in real-time:
+
+```bash
+assh session watch -s SID
+# Returns an attach_cmd — paste it in a terminal to attach to the agent's tmux
+```
+
+## MCP Server (for Claude Code, Cursor, Windsurf)
+
+Start as an MCP stdio server so agents can call assh as MCP tools:
+
+```bash
+assh mcp serve
+# Wire into Claude Code: claude mcp add assh -- assh mcp serve
+```
+
 ## JSON Rules
 
 - Operational commands emit one JSON value by default.
@@ -77,3 +189,10 @@ If `stdout_lines` or `stderr_lines` is large, do not read all output. Use target
 - If key login works, `connect` does not read the password env var.
 - Prefer `--host-key-policy strict` when host keys are already managed.
 - Treat `--host-key-policy no-check` as unsafe and only for disposable lab/dev hosts.
+- If `session exec` returns `dangerous_command_requires_confirmation`, do not add `--confirm-danger` unless the user explicitly intended the destructive action.
+- `db-query` is read-only by design — write operations are blocked with a safety error.
+- Use `assh session watch` to observe agent actions in real-time.
+
+## Connection Pooling (Automatic)
+
+`assh` uses SSH ControlMaster to multiplex connections to the same host. The first `connect` or `session exec` opens a master connection; subsequent commands reuse it. Control sockets live in `~/.ssh/controlmasters/` with a 5-minute idle timeout. No configuration needed — this is automatic.

package/README.en.md

@@ -11,6 +11,10 @@ SSH workflow helper for LLM agents.
 
 `assh` bootstraps SSH access, opens a persistent remote `tmux` session, and keeps large SSH output out of the agent context. Commands return compact JSON metadata first; agents read only the lines they need.
 
+<p align="center">
+  <img src="docs/assh-architecture.png" alt="assh architecture" width="800">
+</p>
+
 ## Quick Start
 
 ```bash
@@ -75,12 +79,22 @@ assh session close -s f7a2b3c4
 - `assh connect`: first-contact bootstrap and session open.
 - `assh connect-info`: parse a pasted provider server-info block and connect.
 - `assh session exec|read|close|gc`: persistent tmux workflow.
+- `assh session ps|kill`: process management.
+- `assh session service`: service management (status/restart/start/stop/logs).
+- `assh session exec-async|job-status|job-cancel`: background jobs.
+- `assh session docker-ps|docker-logs|docker-exec`: Docker management.
+- `assh session db-query`: read-only MySQL/PostgreSQL queries.
+- `assh session watch`: human observability into the agent's tmux session.
 - `assh exec`: run one remote command and store output locally.
 - `assh read`: read stored output with pagination or `--raw`.
+- `assh transfer put|get|list|stat|mkdir|rm|mv|sync`: file ops and sync.
+- `assh forward`: port forwarding (start/status/stop).
+- `assh fleet exec`: parallel execution across multiple hosts.
+- `assh scan`: return host inventory JSON (OS, CPU, memory, disk, uptime).
 - `assh capabilities`: inspect remote session support.
-- `assh scan`: return host inventory JSON.
 - `assh key-deploy`: low-level key deployment using a password from env.
 - `assh audit`: read local audit events with `--last`, `--host`, and `--failed`.
+- `assh mcp serve`: start MCP stdio server for Claude Code/Cursor/Windsurf.
 - `assh version`: print version metadata.
 
 ## Token Economy
@@ -141,14 +155,20 @@ OpenCode: Use `assh connect-info` for provider server-info blocks and `assh sess
 - SSH runs non-interactively and disables pseudo-terminal allocation.
 - `--host-key-policy accept-new` is the default. Use `strict` for hardened environments.
 - `--host-key-policy no-check` is unsafe and should be limited to disposable lab/dev hosts.
+- `session exec` blocks clearly destructive commands such as `rm -rf`, `find ... -delete`, `mkfs`, `wipefs`, dangerous `dd`, and recursive permission changes; intentional runs require `--confirm-danger`.
 - Remote cleanup only targets sessions with trusted `assh` metadata.
 
 ## Advantages
 
 - One command handles first login, key setup, tmux readiness, cleanup, and session open.
+- ControlMaster connection pooling — repeat calls reuse the SSH socket.
 - Large output stays outside the agent context until explicitly paged in.
 - Persistent sessions preserve working directory and environment between commands.
 - JSON responses are stable for agent parsing.
+- Built-in command safety classifier blocks destructive operations.
+- Background jobs via tmux (exec-async).
+- Read-only database queries with write protection.
+- MCP server for Claude Code, Cursor, Windsurf.
 
 ## Limitations
 

package/README.md

@@ -11,6 +11,10 @@ SSH-инструмент для LLM-агентов.
 
 `assh` подготавливает SSH-доступ, открывает persistent `tmux`-сессию на сервере и не тащит большой вывод в контекст агента. Команды сначала возвращают компактный JSON с метаданными, а агент читает только нужные строки.
 
+<p align="center">
+  <img src="docs/assh-architecture.png" alt="assh architecture" width="800">
+</p>
+
 ## Быстрый старт
 
 ```bash
@@ -75,12 +79,22 @@ assh session close -s f7a2b3c4
 - `assh connect`: первый bootstrap и открытие session.
 - `assh connect-info`: распарсить provider server-info block и подключиться.
 - `assh session exec|read|close|gc`: persistent workflow через tmux.
+- `assh session ps|kill`: управление процессами.
+- `assh session service`: управление сервисами (status/restart/start/stop/logs).
+- `assh session exec-async|job-status|job-cancel`: фоновые задачи.
+- `assh session docker-ps|docker-logs|docker-exec`: управление Docker.
+- `assh session db-query`: read-only запросы к MySQL/PostgreSQL.
+- `assh session watch`: наблюдение за tmux-сессией агента человеком.
 - `assh exec`: выполнить одну remote-команду и сохранить вывод локально.
 - `assh read`: прочитать сохранённый вывод с пагинацией или через `--raw`.
+- `assh transfer put|get|list|stat|mkdir|rm|mv|sync`: файловые операции и синхронизация.
+- `assh forward`: port forwarding (start/status/stop).
+- `assh fleet exec`: параллельное выполнение на нескольких хостах.
+- `assh scan`: вернуть JSON-инвентарь хоста (OS, CPU, память, диск, uptime).
 - `assh capabilities`: проверить поддержку session workflow на сервере.
-- `assh scan`: вернуть JSON-инвентарь хоста.
 - `assh key-deploy`: низкоуровневая установка ключа через пароль из env.
 - `assh audit`: читать локальный audit через `--last`, `--host`, `--failed`.
+- `assh mcp serve`: запустить MCP stdio сервер для Claude Code/Cursor/Windsurf.
 - `assh version`: вывести метаданные версии.
 
 ## Экономия токенов
@@ -141,14 +155,20 @@ OpenCode: Используй `assh connect-info` для provider server-info blo
 - SSH запускается неинтерактивно и отключает pseudo-terminal allocation.
 - `--host-key-policy accept-new` используется по умолчанию. Для hardened окружений используйте `strict`.
 - `--host-key-policy no-check` небезопасен и подходит только для одноразовых lab/dev хостов.
+- `session exec` блокирует явно destructive-команды вроде `rm -rf`, `find ... -delete`, `mkfs`, `wipefs`, опасный `dd` и recursive permission changes; для намеренного запуска нужен `--confirm-danger`.
 - Remote cleanup удаляет только sessions с доверенной metadata `assh`.
 
 ## Плюсы
 
 - Одна команда делает первый вход, ключ, tmux, cleanup и открытие session.
+- ControlMaster connection pooling — повторные вызовы переиспользуют SSH-сокет.
 - Большой вывод не попадает в контекст агента без явного чтения.
 - Persistent sessions сохраняют рабочую директорию и окружение между командами.
 - JSON-ответы стабильны для парсинга агентом.
+- Встроенная проверка безопасности команд (safety classifier).
+- Фоновые задачи через tmux (exec-async).
+- Read-only database queries с защитой от записи.
+- MCP-сервер для Claude Code, Cursor, Windsurf.
 
 ## Ограничения
 

package/SYSTEM_PROMPT_snippet.md

@@ -13,6 +13,8 @@ assh version
 
 ```text
 Need SSH?
+  prefer assh connect --ssh-config ALIAS for hosts in ~/.ssh/config
+
   If the user pasted provider server info:
     save it to a 0600 temp file
     assh connect-info --file TMP -n NAME
@@ -23,13 +25,57 @@ Need SSH?
     assh connect -H HOST -u root -E PASSWORD_ENV -n NAME
     or, when key login already works:
     assh connect -H HOST -u root -i KEY -n NAME
+    or, resolve from ~/.ssh/config:
+    assh connect --ssh-config my-alias -n NAME
+
+  Scan host health:
+    assh scan -H HOST -u USER
 
   Continue with returned sid:
     assh session exec -s SID -- "pwd"
     assh session read -s SID --seq 1 --limit 50
     assh session exec -s SID --timeout 600 -- "git pull"
     assh session read -s SID --seq 2 --stream stderr --limit 50
-    assh session close -s SID
+
+  File operations:
+    assh transfer list -H HOST -u USER --path /var/log
+    assh transfer stat -H HOST -u USER --path /etc/nginx.conf
+    assh transfer put -H HOST -u USER LOCAL_PATH REMOTE_PATH
+    assh transfer get -H HOST -u USER REMOTE_PATH LOCAL_PATH
+    assh transfer sync --direction push --source ./dist --dest /var/www -H HOST
+    assh transfer mkdir -H HOST -u USER --path /opt/newapp
+    assh transfer rm -H HOST -u USER --path /tmp/junk.log
+    assh transfer mv -H HOST -u USER --source /tmp/a --dest /tmp/b
+
+  Server management:
+    assh session ps -s SID --top 20
+    assh session kill -s SID --pid 1234
+    assh session service -s SID --action status --service nginx
+    assh session service -s SID --action restart --service docker
+    assh session service -s SID --action logs --service nginx --lines 100
+
+  Background jobs:
+    assh session exec-async -s SID -- "long-build.sh"
+    assh session job-status -s SID --job-id JOB_ID
+    assh session job-cancel -s SID --job-id JOB_ID
+
+  Docker:
+    assh session docker-ps -s SID
+    assh session docker-logs -s SID --container myapp
+    assh session docker-exec -s SID --container myapp -- "ls -la"
+
+  Database (read-only):
+    assh session db-query -s SID --type mysql -d mydb -q "SELECT COUNT(*) FROM users"
+
+  Fleet (multi-host):
+    assh fleet exec -H host1 -H host2 -H host3 -u root -- "uptime"
+
+  Pre/post hooks:
+    assh session exec -s SID --before "git stash" --after "git stash pop" -- "deploy.sh"
+
+  Watch agent session (human observability):
+    assh session watch -s SID
+    # Copy the attach_cmd to a terminal to see the agent's tmux in real-time.
 
   Cleanup:
     assh session gc --older-than 24h --execute
@@ -52,6 +98,18 @@ Need SSH?
 {"ok":true,"rc":0,"seq":2,"stdout_lines":15,"stderr_lines":0,"sid":"f7a2b3c4","session":"deploy"}
 ```
 
+`assh scan` returns host inventory:
+
+```json
+{"hostname":"web01","os":"Linux","kernel":"6.1.0","arch":"x86_64","cpu_cores":"4","ip":"10.0.0.1","uptime":"30 days","load":"0.15 0.10 0.05","mem_total_kb":"8176248","mem_avail_kb":"5241360","disk":"12G/50G (25%)"}
+```
+
+`assh transfer list` returns file entries:
+
+```json
+{"ok":true,"host":"web01","user":"root","path":"/var/log","count":5,"entries":[{"name":"syslog","type":"f","size":12345,"mtime":"2026-06-05T10:00:00Z"}]}
+```
+
 Rules:
 
 - Operational commands emit one JSON value by default.
@@ -59,3 +117,6 @@ Rules:
 - Remote non-zero status is a command result, not a transport failure.
 - Passwords are only accepted through environment variables; never put passwords in command arguments.
 - Command text is not written to audit logs.
+- If `session exec` returns `dangerous_command_requires_confirmation`, ask for explicit user intent before rerunning with `--confirm-danger`.
+- db-query is read-only — only SELECT/SHOW/DESCRIBE/EXPLAIN allowed.
+- session watch shows a tmux attach command; the human opens a terminal to observe the agent.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-assh",
-  "version": "1.0.2",
+  "version": "1.1.0",
   "description": "SSH workflow helper for LLM agents",
   "license": "MIT",
   "repository": {