mcp-ssh-terminal 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kirill Zhdanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,261 @@
+# mcp-ssh-terminal
+
+[![npm](https://img.shields.io/npm/v/mcp-ssh-terminal)](https://www.npmjs.com/package/mcp-ssh-terminal)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Node.js ≥ 22](https://img.shields.io/badge/node-%E2%89%A5%2022-brightgreen)](https://nodejs.org)
+[![MCP](https://img.shields.io/badge/protocol-MCP-blueviolet)](https://modelcontextprotocol.io)
+
+An [MCP](https://modelcontextprotocol.io) server that gives an AI agent **persistent, fully interactive SSH sessions** — a real shell into a remote host that behaves as if you were typing at a local terminal.
+
+- **Sessions persist across tool calls** — connect once, run commands, inspect output, run more; state (working directory, environment, running programs) is preserved.
+- **A real terminal, not a command runner** — arbitrary control characters (Ctrl-C, Ctrl-X, arrows, Tab, function keys) pass through faithfully, so interactive TUIs, pagers, tab-completion, and prompts all work.
+- **Non-Unix CLIs work too** — network appliances like **Mikrotik RouterOS** are first-class citizens because the session is a genuine PTY.
+- **Your existing SSH setup just works** — `~/.ssh/config` aliases, `IdentityFile`, ssh-agent, `ProxyJump` chains, and known_hosts are all handled by the real OpenSSH client, untouched.
+
+```text
+ssh_connect { "host": "prod-web" }                                → s1 + login screen
+ssh_send    { "session": "s1", "text": "htop", "appendEnter": true }
+ssh_send    { "session": "s1", "keys": ["F5"] }                   → tree view, rendered
+ssh_interrupt { "session": "s1" }                                 → Ctrl-C, back to prompt
+```
+
+## Table of contents
+
+- [How it works](#how-it-works)
+- [Requirements](#requirements)
+- [Install](#install)
+- [Register with an MCP client](#register-with-an-mcp-client)
+- [Docker](#docker-optional)
+- [Tools](#tools)
+- [Special keys](#special-keys-for-ssh_send)
+- [Usage walkthroughs](#usage-walkthroughs)
+- [Security notes](#security-notes)
+- [Troubleshooting](#troubleshooting)
+- [Development](#development)
+
+## How it works
+
+### Decision 1: drive the real OpenSSH client (`ssh`) inside a PTY
+
+Rather than reimplementing SSH in JavaScript, each session spawns your actual `ssh` binary attached to a pseudo-terminal. Every connection requirement you'd otherwise have to hand-build is something OpenSSH already does correctly:
+
+| Requirement | How it's satisfied |
+| --- | --- |
+| Honor `~/.ssh/config` | `ssh` reads it natively — `Host` aliases, `IdentityFile`, `Match`, `Include`, everything. No config parsing of our own is in the connection path. |
+| ProxyJump A → B → C | `ProxyJump` in your config, or the `jump` argument (`ssh -J`), handled entirely by `ssh`. |
+| known_hosts verification | `ssh`'s default `StrictHostKeyChecking` behavior is left intact. A new host's fingerprint prompt appears on the screen; you approve it with `ssh_send` (`yes`). |
+| Key-based auth | `ssh` uses your `IdentityFile`, ssh-agent, encrypted keys, FIDO tokens — unchanged. Passphrase/password/2FA prompts surface on the screen and you answer them with `ssh_send`. |
+| Arbitrary control characters | The child runs on a PTY, so raw bytes (0x00–0x1F, 0x7F, escape sequences) reach the remote program exactly. The ssh escape char is disabled (`-e none`) so nothing is intercepted. |
+| Non-Unix shells (RouterOS) | Because it's a faithful terminal (PTY + `-tt` to force a remote PTY), interactive CLIs, paging, and tab-completion behave normally. |
+| Uninterrupted sessions | The `ssh` process is long-lived and tracked by session id; you connect once and interact repeatedly. Keepalives (`ServerAliveInterval=30`, `ServerAliveCountMax=3`) are set by default so NAT/conntrack doesn't silently drop idle sessions; override via `extraArgs`. |
+
+A pure-JS library (e.g. `ssh2`) would force us to re-implement ssh_config resolution, `Match` logic, ProxyJump chaining, known_hosts hashing/verification, and key handling — a large, security-sensitive surface that OpenSSH already gets right. Delegating to `ssh` means the server behaves **exactly like your own `ssh <host>` command**.
+
+### Decision 2: a headless terminal emulator for reading output
+
+Raw PTY output is a byte stream full of cursor moves, colors, and redraws. Feeding that to an agent is unreadable. So output is piped through [`@xterm/headless`](https://www.npmjs.com/package/@xterm/headless), which maintains a virtual screen. Tools return the **rendered screen a human would see** — redraws collapsed to their final state, escape codes resolved to plain text. (A `raw` mode is still available on `ssh_read` when you need the underlying bytes.) The emulator also answers terminal queries from the remote side (cursor-position reports, device attributes), so programs that probe the terminal don't hang.
+
+### How "is the output done?" is decided
+
+After input is sent, the server waits until output has been **quiet for `settleMs`** (default 500 ms) or a `timeoutMs` cap is hit, then renders. A long-running command returns partial output at the timeout with a hint to call `ssh_read` again — no output is lost, and short commands feel snappy.
+
+### Terminal multiplexing
+
+Two levels:
+
+- **Multiple concurrent sessions** — connect to many hosts at once; each has its own session id (up to 32 concurrent).
+- **tmux/screen inside a session** — since each session is a real terminal, you can run `tmux` on the remote host and drive it with control keys (`ssh_send { keys: ["C-b", "c"] }`, etc.).
+
+## Requirements
+
+- **Node.js ≥ 22** (`fs.glob`, used by the config lister, does not exist on Node 20)
+- The **OpenSSH client** (`ssh`) on `PATH` — the same one your shell uses.
+- macOS/Linux. (`node-pty` ships prebuilt binaries; on macOS the bundled `spawn-helper` must be executable — see [Troubleshooting](#troubleshooting).)
+
+## Install
+
+**From npm** — nothing to do up front; register it straight with `npx` (next section). Or install globally:
+
+```bash
+npm install -g mcp-ssh-terminal
+```
+
+**From source:**
+
+```bash
+git clone https://github.com/zhdkirill/mcp-ssh-terminal.git
+cd mcp-ssh-terminal
+npm install
+npm run build      # compiles TypeScript to dist/
+npm test           # optional: runs the tests (keys, argv builder, ssh_config, live PTY sessions)
+```
+
+## Register with an MCP client
+
+**Claude Code (CLI):**
+
+```bash
+claude mcp add ssh -- npx -y mcp-ssh-terminal
+# or, from a source checkout:
+claude mcp add ssh -- node /path/to/mcp-ssh-terminal/dist/index.js
+```
+
+**Project-scoped `.mcp.json` or Claude Desktop config:**
+
+```json
+{
+  "mcpServers": {
+    "ssh": {
+      "command": "npx",
+      "args": ["-y", "mcp-ssh-terminal"]
+    }
+  }
+}
+```
+
+(For a source checkout, use `"command": "node", "args": ["/path/to/mcp-ssh-terminal/dist/index.js"]` instead.)
+
+The server speaks MCP over stdio. It writes nothing to stdout except protocol traffic (logs go to stderr), so it is safe to run under any stdio MCP host.
+
+## Docker (optional)
+
+**Run it natively if you can.** The whole design delegates auth to *your* OpenSSH — config, keys, agent, known_hosts — and a container sees none of that unless you mount it in. Docker is the right choice when the consuming machine shouldn't need Node, or you want a pinned, hermetic runtime; it is the wrong choice if you rely on ssh-agent, FIDO keys, or VPN-only routes that exist on the host.
+
+```bash
+docker build -t mcp-ssh-terminal .
+```
+
+Register (mounting your ssh config/keys read-only):
+
+```bash
+claude mcp add ssh -- docker run -i --rm --init -v "$HOME/.ssh:/home/node/.ssh:ro" mcp-ssh-terminal
+```
+
+Notes for container mode:
+
+- **`-i` is mandatory** (stdio transport) and `--init` is recommended (proper PID-1 signal handling; the server also handles SIGTERM itself).
+- **ssh-agent:** Linux: add `-v "$SSH_AUTH_SOCK:/agent.sock" -e SSH_AUTH_SOCK=/agent.sock`. Docker Desktop for Mac: `-v /run/host-services/ssh-auth.sock:/agent.sock -e SSH_AUTH_SOCK=/agent.sock`. Without an agent, mounted key files still work (you'll type passphrases interactively via `ssh_send`).
+- **known_hosts:** with a read-only mount, newly-accepted host keys can't be persisted — ssh warns and continues for that session. Mount `~/.ssh` read-write (or a dedicated known_hosts file) if you want them remembered.
+- **File ownership:** the image runs as the `node` user (uid 1000). If your bind-mounted keys come through owned by a different uid and unreadable, add `--user root` (the container is ephemeral and has your keys mounted either way).
+- **Networking:** the container has its own network namespace. Host-only routes (VPN tunnels, `localhost` targets) may need `--network host` (Linux only) or won't work as they do natively.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `ssh_connect` | Open a session to a host. Returns a session id and the initial screen (prompt, or an auth/host-key prompt to answer). |
+| `ssh_send` | Send `text` and/or special `keys` (and optional Enter), wait for output to settle, return the updated screen. |
+| `ssh_read` | Read the current screen without sending — poll long-running output. Supports `mode: "raw"` and blocking for new output via `waitMs`. |
+| `ssh_interrupt` | Send Ctrl-C to the foreground program. |
+| `ssh_resize` | Change terminal dimensions (affects wrapping and full-screen apps). |
+| `ssh_list` | List active sessions with state, pid, age, destination. |
+| `ssh_disconnect` | Close a session and terminate its `ssh` process. |
+| `ssh_config_hosts` | List `Host` aliases from `~/.ssh/config` (best-effort, follows `Include`) for discovery. |
+
+### `ssh_connect` parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `host` | string, required | ssh_config `Host` alias, hostname, or `user@hostname` |
+| `user` | string | Username (prepended as `user@host`) |
+| `port` | number | Port (`ssh -p`); usually unnecessary if set in config |
+| `identityFile` | string | Private key path (`ssh -i`); `~` is expanded |
+| `jump` | string | ProxyJump chain (`ssh -J`), e.g. `"bastion"` or `"userA@a,userB@b"` |
+| `remoteCommand` | string | Run this command instead of an interactive login shell (still on a PTY) |
+| `extraArgs` | string[] | Extra raw ssh arguments appended verbatim |
+| `forceTty` | boolean | Force remote PTY allocation (`ssh -tt`). Default `true` |
+| `cols`, `rows` | number | Terminal size (default 120×40) |
+| `settleMs`, `timeoutMs` | number | Output-settle threshold / max wait (defaults 700 / 20000) |
+| `maxLines` | number | Max screen lines returned (default 200) |
+
+Every screen-returning tool accepts `settleMs`, `timeoutMs`, and `maxLines`, and appends a status footer:
+
+```text
+[session=s1 | state=live | wait=idle | cursor=12,1 | screen=40x120 | shown=24/40]
+```
+
+`state` becomes `exited code=N` when the ssh process ends; `wait` tells you whether output settled (`idle`), was still streaming (`timeout`), or nothing new arrived (`quiet`).
+
+## Special keys for `ssh_send`
+
+Pass an ordered `keys` array. Recognised tokens (case-insensitive):
+
+- **Control chords:** `C-c` (Ctrl-C), `C-x`, `Ctrl-d`, `^u`, `C-[` (Esc), `C-@` (NUL), `C-\`, `C-?` (DEL) — covers all of 0x00–0x1F and 0x7F.
+- **Named keys:** `Enter`, `Tab`, `Backtab`, `Space`, `Escape`, `Backspace`, `Delete`, `Insert`, `Up`/`Down`/`Left`/`Right`, `Home`, `End`, `PageUp`, `PageDown`, `F1`–`F12`.
+- **Alt/Meta:** `M-b`, `Alt-f`, `meta-.` → ESC-prefixed.
+- **Raw bytes:** `hex:1b5b41` → arbitrary byte sequence.
+- **Single characters:** `y`, `Q` → sent as-is.
+
+Any other multi-character token is an **error** — a typo'd chord is rejected instead of being typed into the remote shell. Literal text belongs in `text`, not `keys`. Arrow/Home/End keys automatically switch to SS3 sequences when the remote app enables application cursor-keys mode (DECCKM), like a real terminal.
+
+`text` is sent literally first, then `keys` in order, then Enter if `appendEnter: true`.
+
+## Usage walkthroughs
+
+**Basic:**
+1. `ssh_connect { "host": "prod-web" }` → screen shows the shell prompt.
+2. `ssh_send { "session": "s1", "text": "uname -a", "appendEnter": true }` → screen shows the output.
+3. `ssh_disconnect { "session": "s1" }`.
+
+**Mikrotik RouterOS:**
+1. `ssh_connect { "host": "admin@192.0.2.1" }` → RouterOS banner + `[admin@MikroTik] >` prompt.
+2. `ssh_send { "session": "s1", "text": "/interface print", "appendEnter": true }`.
+3. Tab-completion: `ssh_send { "session": "s1", "text": "/ip ad", "keys": ["Tab"] }`.
+4. Abort a running command: `ssh_interrupt { "session": "s1" }` (Ctrl-C), or send `Q` to quit a pager.
+
+RouterOS console gotchas worth knowing:
+- `?` and Tab are **live hotkeys** (inline help / completion) — they act the instant they arrive, so keep them out of `text` unless intended, and prefer single-line commands (multi-line pastes are mangled by auto-indent; use `/import` for scripts).
+- Long `print` output stops at a pager line (`-- [Q quit|D dump|down]`): send `D` to dump the rest, or run `print without-paging`.
+- `keys: ["C-x"]` toggles **Safe Mode** — enter it before config changes so they auto-revert if the session drops.
+
+**ProxyJump A → B → C:** use a config alias that sets `ProxyJump`, and just `ssh_connect { "host": "internal-box" }`. Or set the chain inline: `ssh_connect { "host": "10.0.0.5", "jump": "bastionA,bastionB" }`.
+
+**Answering auth / host-key prompts:** if the initial screen shows `Are you sure you want to continue connecting (yes/no)?`, reply `ssh_send { "session": "s1", "text": "yes", "appendEnter": true }`. For a password prompt, send the password the same way. The known_hosts check is never disabled.
+
+**Long-running output:** `ssh_send` returns at the settle/timeout; if the footer says output is still arriving, call `ssh_read { "session": "s1", "waitMs": 2000 }` to poll for more. `ssh_read` blocks until *new* output arrives (footer `wait=idle`/`timeout`) or reports `wait=quiet` if nothing new came within `waitMs`.
+
+## Security notes
+
+This server hands an AI agent a real shell with **your** SSH identity. Read this section before wiring it into anything.
+
+- **The agent can do whatever your keys can do.** Every host reachable from your `~/.ssh/config` and agent is reachable by the model. Use your MCP client's permission prompts (don't blanket-allow `ssh_send`), and consider a dedicated restricted key or user for agent-driven work.
+- **Remote output is untrusted input to the model.** Screen content from a remote host flows back into the agent's context; a compromised or malicious host could try prompt injection through banners, MOTDs, or command output. Treat sessions to untrusted hosts accordingly.
+- **known_hosts verification is left on.** The server does not add `StrictHostKeyChecking=no` or similar; you decide, per host, by answering the fingerprint prompt.
+- **Argument injection is blocked** for `host`/`user`/`jump`: values starting with `-` are rejected and the destination is passed after a `--` separator, so a hostile hostname can't smuggle in ssh options like `ProxyCommand`. `extraArgs` remains a deliberate raw passthrough — treat it as you would a shell: options like `-oProxyCommand=…` execute **local** commands as the user running the server. If your MCP client supports per-tool argument review, scrutinize `extraArgs`.
+- **`ssh_config_hosts` reads the file you point it at.** `configPath` accepts any path readable by the server's user (it only echoes config-shaped lines, but still). Point it at ssh configs only.
+- **Credentials are never handled by this server**; `ssh`/ssh-agent own them. Passwords you type via `ssh_send` go straight to the PTY (not logged to stdout) — but they **do transit the MCP transport and may end up in client-side conversation logs**. Prefer key-based auth over typing passwords.
+- Run it as your normal user so it inherits your `~/.ssh` and agent.
+
+## Troubleshooting
+
+- **`posix_spawnp failed` from node-pty on macOS:** the prebuilt `spawn-helper` lost its execute bit. Fix: `chmod +x node_modules/node-pty/prebuilds/darwin-*/spawn-helper`. `npm run build` is unaffected, but a fresh `npm install` may need this once.
+- **`ssh: connect to host … Connection refused`:** faithfully reported from the real `ssh`; the destination isn't listening. Session exits with code 255.
+- **`Connection timed out during banner exchange` on a ProxyJump chain:** OpenSSH's `ConnectTimeout` (default here: 30) also caps the destination's banner exchange, and that clock keeps running while you answer interactive prompts (host key, password) at the *jump* hop. Answer promptly, or raise it: `extraArgs: ["-o", "ConnectTimeout=120"]`. Note that `-o` options are not propagated to the jump hop itself — its host key is checked against your default known_hosts.
+- **`channel 0: open failed: administratively prohibited` via a jump host:** the jump's sshd has `AllowTcpForwarding no` (common on hardened/minimal distros, e.g. Alpine's default). Enable it on the jump host; ProxyJump needs TCP forwarding there.
+- **Output looks truncated:** increase `maxLines` on `ssh_send`/`ssh_read`, or poll with `ssh_read`. The emulator keeps 5000 lines of scrollback per session.
+- **Session limit reached:** at most 32 concurrent sessions; exited ones are evicted automatically, live ones must be `ssh_disconnect`ed first.
+
+## Development
+
+```bash
+npm run build   # tsc → dist/
+npm test        # vitest: unit tests + live PTY integration tests
+```
+
+```
+src/
+  index.ts       entry point; stdio transport + graceful shutdown
+  server.ts      MCP server + tool definitions
+  manager.ts     session registry + ssh argv builder
+  session.ts     PTY + headless xterm; idle-wait + screen rendering
+  keys.ts        key-token → byte-sequence translation
+  sshConfig.ts   best-effort ~/.ssh/config host lister (discovery only)
+test/            vitest tests (keys, argv builder, ssh_config, live PTY sessions)
+Dockerfile       optional container packaging (see the Docker section)
+```
+
+Contributions welcome — please run `npm test` before opening a PR.
+
+## License
+
+[MIT](LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { SessionManager } from "./manager.js";
+import { createServer } from "./server.js";
+async function main() {
+    const manager = new SessionManager();
+    const server = createServer(manager);
+    let shuttingDown = false;
+    const shutdown = () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        manager.closeAll(250);
+        // Exit only after the SIGKILL escalation inside closeAll has had a
+        // chance to run, so stubborn children aren't orphaned.
+        setTimeout(() => process.exit(0), 500);
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // When the MCP client disconnects, shut down too — live PTY children would
+    // otherwise keep this process (and its ssh sessions) running forever. The
+    // SDK's stdio transport only watches stdin 'data'/'error' (onclose fires
+    // solely on explicit close), so watch stdin EOF ourselves as well.
+    server.server.onclose = shutdown;
+    process.stdin.on("end", shutdown);
+    process.stdin.on("close", shutdown);
+    // IMPORTANT: stdout is the MCP protocol channel. Never write logs there.
+    console.error("mcp-ssh server started (stdio).");
+}
+main().catch((err) => {
+    console.error("Fatal:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,KAAK,UAAU,IAAI;IACjB,MAAM,OAAO,GAAG,IAAI,cAAc,EAAE,CAAC;IACrC,MAAM,MAAM,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IAErC,IAAI,YAAY,GAAG,KAAK,CAAC;IACzB,MAAM,QAAQ,GAAG,GAAG,EAAE;QACpB,IAAI,YAAY;YAAE,OAAO;QACzB,YAAY,GAAG,IAAI,CAAC;QACpB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC;QACtB,mEAAmE;QACnE,uDAAuD;QACvD,UAAU,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACzC,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC/B,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;IAEhC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAEhC,2EAA2E;IAC3E,0EAA0E;IAC1E,yEAAyE;IACzE,mEAAmE;IACnE,MAAM,CAAC,MAAM,CAAC,OAAO,GAAG,QAAQ,CAAC;IACjC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAClC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC;IAEpC,yEAAyE;IACzE,OAAO,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;AACnD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC;IAC7B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/keys.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Translation from human-friendly key tokens to the exact byte sequences a
+ * terminal application receives. This is what lets a caller press Ctrl-X,
+ * arrow keys, function keys, Escape, Tab, etc. against an interactive remote
+ * shell (bash, vi, RouterOS CLI, ...) without knowing the raw escape codes.
+ *
+ * Tokens are case-insensitive. Recognised forms:
+ *   - Named keys:      "Enter", "Tab", "Escape", "Up", "F5", "Backspace", ...
+ *   - Control chords:  "C-c", "Ctrl-x", "^d", "control-["   -> a single 0x00..0x1f/0x7f byte
+ *   - Alt/Meta chords: "M-b", "Alt-f", "meta-."             -> ESC-prefixed byte
+ *   - Raw hex:         "hex:1b5b41"                          -> arbitrary bytes
+ *   - A single character is sent as-is (e.g. "y", "Q").
+ *
+ * Any other multi-character token is an error: silently typing a typo'd
+ * chord (e.g. "ctrl+c") into a live remote shell is far worse than failing
+ * the call. Literal text belongs in `text`, not `keys`.
+ */
+export interface KeyOptions {
+    /** Emit SS3 cursor-key sequences (remote app has DECCKM enabled). */
+    applicationCursorKeys?: boolean;
+}
+/**
+ * Resolve a single key token to its byte sequence. Throws on a malformed
+ * control/alt/hex chord — or any unrecognised multi-character token — so the
+ * caller gets a clear error instead of silently sending the wrong bytes.
+ */
+export declare function resolveKey(token: string, opts?: KeyOptions): string;
+/** Resolve an ordered list of key tokens to one concatenated byte string. */
+export declare function resolveKeys(tokens: string[], opts?: KeyOptions): string;

package/dist/keys.js

@@ -0,0 +1,158 @@
+/**
+ * Translation from human-friendly key tokens to the exact byte sequences a
+ * terminal application receives. This is what lets a caller press Ctrl-X,
+ * arrow keys, function keys, Escape, Tab, etc. against an interactive remote
+ * shell (bash, vi, RouterOS CLI, ...) without knowing the raw escape codes.
+ *
+ * Tokens are case-insensitive. Recognised forms:
+ *   - Named keys:      "Enter", "Tab", "Escape", "Up", "F5", "Backspace", ...
+ *   - Control chords:  "C-c", "Ctrl-x", "^d", "control-["   -> a single 0x00..0x1f/0x7f byte
+ *   - Alt/Meta chords: "M-b", "Alt-f", "meta-."             -> ESC-prefixed byte
+ *   - Raw hex:         "hex:1b5b41"                          -> arbitrary bytes
+ *   - A single character is sent as-is (e.g. "y", "Q").
+ *
+ * Any other multi-character token is an error: silently typing a typo'd
+ * chord (e.g. "ctrl+c") into a live remote shell is far worse than failing
+ * the call. Literal text belongs in `text`, not `keys`.
+ */
+const ESC = "\x1b";
+/** Named keys mapped to the byte sequence xterm-style terminals expect. */
+const NAMED_KEYS = {
+    enter: "\r",
+    return: "\r",
+    ret: "\r",
+    newline: "\n",
+    lf: "\n",
+    cr: "\r",
+    tab: "\t",
+    backtab: `${ESC}[Z`,
+    space: " ",
+    escape: ESC,
+    esc: ESC,
+    backspace: "\x7f",
+    bs: "\x7f",
+    delete: `${ESC}[3~`,
+    del: `${ESC}[3~`,
+    insert: `${ESC}[2~`,
+    ins: `${ESC}[2~`,
+    up: `${ESC}[A`,
+    down: `${ESC}[B`,
+    right: `${ESC}[C`,
+    left: `${ESC}[D`,
+    home: `${ESC}[H`,
+    end: `${ESC}[F`,
+    pageup: `${ESC}[5~`,
+    pgup: `${ESC}[5~`,
+    pagedown: `${ESC}[6~`,
+    pgdn: `${ESC}[6~`,
+    f1: `${ESC}OP`,
+    f2: `${ESC}OQ`,
+    f3: `${ESC}OR`,
+    f4: `${ESC}OS`,
+    f5: `${ESC}[15~`,
+    f6: `${ESC}[17~`,
+    f7: `${ESC}[18~`,
+    f8: `${ESC}[19~`,
+    f9: `${ESC}[20~`,
+    f10: `${ESC}[21~`,
+    f11: `${ESC}[23~`,
+    f12: `${ESC}[24~`,
+    nul: "\x00",
+    null: "\x00",
+};
+/**
+ * Cursor/keypad keys switch to SS3 sequences when the remote app enables
+ * DECCKM (application cursor-keys mode), the way a real terminal does.
+ */
+const APP_CURSOR_KEYS = {
+    up: `${ESC}OA`,
+    down: `${ESC}OB`,
+    right: `${ESC}OC`,
+    left: `${ESC}OD`,
+    home: `${ESC}OH`,
+    end: `${ESC}OF`,
+};
+/**
+ * Map a single control-chord target character to its control byte.
+ * Ctrl-A..Ctrl-Z -> 0x01..0x1a, plus the C0 punctuation chords.
+ */
+function controlByte(ch) {
+    if (ch.length !== 1)
+        return undefined;
+    const c = ch.toLowerCase();
+    if (c >= "a" && c <= "z") {
+        return String.fromCharCode(c.charCodeAt(0) - 96); // 'a'->1 ... 'z'->26
+    }
+    // C0 control punctuation, matching what a real terminal produces.
+    const punct = {
+        "@": 0,
+        " ": 0,
+        "[": 27,
+        "\\": 28,
+        "]": 29,
+        "^": 30,
+        "_": 31,
+        "?": 127,
+    };
+    if (ch in punct)
+        return String.fromCharCode(punct[ch]);
+    return undefined;
+}
+function parseHex(spec) {
+    const hex = spec.replace(/[\s:]/g, "");
+    if (hex.length === 0 || hex.length % 2 !== 0 || /[^0-9a-fA-F]/.test(hex)) {
+        throw new Error(`Invalid hex key token "hex:${spec}"`);
+    }
+    let out = "";
+    for (let i = 0; i < hex.length; i += 2) {
+        out += String.fromCharCode(parseInt(hex.slice(i, i + 2), 16));
+    }
+    return out;
+}
+/**
+ * Resolve a single key token to its byte sequence. Throws on a malformed
+ * control/alt/hex chord — or any unrecognised multi-character token — so the
+ * caller gets a clear error instead of silently sending the wrong bytes.
+ */
+export function resolveKey(token, opts = {}) {
+    if (token.length === 0)
+        return "";
+    const lower = token.toLowerCase();
+    if (opts.applicationCursorKeys && lower in APP_CURSOR_KEYS)
+        return APP_CURSOR_KEYS[lower];
+    if (lower in NAMED_KEYS)
+        return NAMED_KEYS[lower];
+    if (lower.startsWith("hex:"))
+        return parseHex(token.slice(4));
+    // Control chord: "C-x", "Ctrl-x", "control-x", "^x"
+    const m = /^(?:c|ctrl|control)-(.+)$/i.exec(token);
+    const caretTarget = !m && token.length === 2 && token[0] === "^" ? token.slice(1) : undefined;
+    if (m || caretTarget !== undefined) {
+        const target = m ? m[1] : caretTarget;
+        // Allow a named key as the chord target (e.g. "C-Space").
+        const namedTarget = target.toLowerCase();
+        const base = namedTarget in NAMED_KEYS ? NAMED_KEYS[namedTarget] : target;
+        const cb = controlByte(base.length === 1 ? base : target);
+        if (cb === undefined)
+            throw new Error(`Unsupported control chord "${token}"`);
+        return cb;
+    }
+    // Alt / Meta chord: "M-b", "Alt-f", "meta-." -> ESC followed by the target.
+    const alt = /^(?:m|alt|meta)-(.+)$/i.exec(token);
+    if (alt) {
+        const target = alt[1];
+        const resolvedTarget = resolveKey(target, opts); // supports Alt+named/control targets
+        return ESC + resolvedTarget;
+    }
+    // A single character is a literal keypress. Count code points, not UTF-16
+    // units, so an astral-plane character (e.g. an emoji) still counts as one.
+    if ([...token].length === 1)
+        return token;
+    throw new Error(`Unrecognised key token "${token}". Use a named key (Enter, Tab, Up, F5, ...), ` +
+        `a chord ("C-x", "M-b"), "hex:..", a single character, or put literal text in \`text\`.`);
+}
+/** Resolve an ordered list of key tokens to one concatenated byte string. */
+export function resolveKeys(tokens, opts = {}) {
+    return tokens.map((t) => resolveKey(t, opts)).join("");
+}
+//# sourceMappingURL=keys.js.map

package/dist/keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keys.js","sourceRoot":"","sources":["../src/keys.ts"],"names":[],"mappings":"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"}

package/dist/manager.d.ts

@@ -0,0 +1,45 @@
+import { Session } from "./session.js";
+export interface ConnectSpec {
+    /** Destination: an ssh_config Host alias, hostname, or user@hostname. */
+    host: string;
+    user?: string;
+    port?: number;
+    /** IdentityFile path (-i). ~ is expanded. */
+    identityFile?: string;
+    /** ProxyJump chain (-J), e.g. "bastion" or "userA@a,userB@b". */
+    jump?: string;
+    /** Raw command to run instead of an interactive login shell. */
+    remoteCommand?: string;
+    /** Extra raw ssh arguments appended verbatim. */
+    extraArgs?: string[];
+    /** Force PTY allocation on the remote side (-tt). Default true. */
+    forceTty?: boolean;
+    cols?: number;
+    rows?: number;
+}
+export interface BuiltCommand {
+    file: string;
+    args: string[];
+    label: string;
+}
+/**
+ * Build the argv for the OpenSSH client from a connect spec. Everything the
+ * ssh client natively understands — ~/.ssh/config, known_hosts, ssh-agent,
+ * ProxyJump — is left to ssh; we only translate the explicit overrides.
+ */
+export declare function buildSshCommand(spec: ConnectSpec): BuiltCommand;
+/** In-memory registry of live sessions. */
+export declare class SessionManager {
+    private sessions;
+    private counter;
+    create(cmd: BuiltCommand, cols: number, rows: number): Session;
+    get(id: string): Session | undefined;
+    require(id: string): Session;
+    list(): Session[];
+    remove(id: string): boolean;
+    /**
+     * SIGHUP everything, escalating to SIGKILL after `escalateMs` for children
+     * that ignore it. Callers that exit afterwards must wait past `escalateMs`.
+     */
+    closeAll(escalateMs?: number): void;
+}