agent-assh 1.0.1 → 1.1.0

package/AGENT_INSTRUCTIONS.md

@@ -0,0 +1,198 @@
+# assh Agent Instructions
+
+`assh` is the SSH workflow helper for LLM agents. Start with `assh connect` so access, key setup, tmux, cleanup, and the first persistent session are prepared in one step.
+
+## Install
+
+```bash
+npm i -g agent-assh
+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
+assh connect-info --file /path/to/tmp-server-info -n NAME
+```
+
+Then delete the temporary file. Server-info formats vary; if parsing fails, extract host, user, and password yourself, put the password in an environment variable, and use `assh connect -E PASSWORD_ENV`.
+
+If first-contact password access may be needed:
+
+```bash
+assh connect -H HOST -u root -E PASSWORD_ENV -n NAME
+```
+
+If key login is already configured:
+
+```bash
+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
+
+```bash
+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
+```
+
+Pre/post hooks:
+
+```bash
+assh session exec -s SID --before "git stash" --after "git stash pop" -- "deploy.sh"
+```
+
+Clean up stale trusted sessions:
+
+```bash
+assh session gc --older-than 24h --execute
+```
+
+## One-Off Commands
+
+Use `exec/read` when no persistent directory or environment is needed:
+
+```bash
+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.
+- Errors use `{"ok":false,"error":"code","message":"..."}`.
+- `session exec` responses include `rc`, `seq`, `stdout_lines`, `stderr_lines`, `sid`, and `session`.
+- Remote non-zero exit status is a command result, not a transport failure.
+
+## Context Discipline
+
+If `stdout_lines` or `stderr_lines` is large, do not read all output. Use targeted windows with `--limit`, `--offset`, and `--stream`. Use `read --raw` or `session read --raw` only when piping or exact output is required.
+
+## Security Rules
+
+- Never put passwords in command arguments.
+- Passwords are passed only through env vars named by `--password-env`.
+- For pasted server-info blocks, prefer `connect-info --file`; remove the temporary file after connect.
+- 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

@@ -0,0 +1,122 @@
+## assh SSH Workflow
+
+Use `assh` for SSH work so large remote output stays out of the agent context.
+
+Install when missing:
+
+```bash
+npm i -g agent-assh
+assh version
+```
+
+### Agent Algorithm
+
+```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
+    delete TMP after connect
+    if parsing fails, extract host/user/password, put password in env, then use connect
+
+  First step:
+    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
+
+  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
+
+  Audit:
+    assh audit --last 20 --host HOST --failed
+```
+
+### JSON Contract
+
+`assh connect` returns a session id and next commands:
+
+```json
+{"ok":true,"sid":"f7a2b3c4","session":"deploy","tmux_name":"assh_f7a2b3c4","next_commands":{"exec":"assh session exec -s f7a2b3c4 -- \"pwd\"","read":"assh session read -s f7a2b3c4 --seq 1 --limit 50","close":"assh session close -s f7a2b3c4"}}
+```
+
+`assh session exec` returns command metadata:
+
+```json
+{"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.
+- `read --raw` and `session read --raw` print only content.
+- 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.1",
+  "version": "1.1.0",
   "description": "SSH workflow helper for LLM agents",
   "license": "MIT",
   "repository": {
@@ -34,6 +34,8 @@
     "scripts",
     "README.md",
     "README.en.md",
+    "AGENT_INSTRUCTIONS.md",
+    "SYSTEM_PROMPT_snippet.md",
     "LICENSE"
   ]
 }

package/scripts/smoke-test.js

@@ -8,8 +8,12 @@ const { target } = require('./platform');
 const { expectedArchives, verifyArtifactFiles } = require('./release-contract-test');
 
 const root = path.join(__dirname, '..');
+const pkg = require(path.join(root, 'package.json'));
 const nativeDir = path.join(root, 'native');
 
+assert.ok(pkg.files.includes('AGENT_INSTRUCTIONS.md'), 'package files must include AGENT_INSTRUCTIONS.md');
+assert.ok(pkg.files.includes('SYSTEM_PROMPT_snippet.md'), 'package files must include SYSTEM_PROMPT_snippet.md');
+
 assert.deepEqual(target('linux', 'x64'), {
   os: 'linux',
   arch: 'amd64',