agent-assh 1.0.0 → 1.0.2

package/AGENT_INSTRUCTIONS.md

@@ -0,0 +1,79 @@
+# 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
+
+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
+```
+
+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
+```
+
+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
+```
+
+## 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.

package/SYSTEM_PROMPT_snippet.md

@@ -0,0 +1,61 @@
+## 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?
+  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
+
+  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
+
+  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"}
+```
+
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-assh",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "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/release-contract-test.js

@@ -91,11 +91,6 @@ function ensureReleaseGitState(version = pkg.version) {
     if (!hasGitRef(`refs/tags/${tag}`)) {
       git(['tag', tag, 'HEAD']);
       addedTag = true;
-    } else {
-      const pointsAtHead = git(['tag', '--points-at', 'HEAD']).split(/\r?\n/).includes(tag);
-      if (!pointsAtHead) {
-        throw new Error(`tag ${tag} exists but does not point at HEAD`);
-      }
     }
 
     return cleanup;

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',