@neoline/hostbridge 1.4.3 → 2.0.0

package/README.md

@@ -25,57 +25,27 @@ This repo is portable: it ships with no personal server paths or built-in hosts.
 
 Every tool returns a structured payload with a stable `error_code` on failure (`HOST_NOT_FOUND`, `SESSION_NOT_FOUND`, `POLICY_DENIED`, `TASK_NOT_FOUND`, `TIMEOUT`, `INTERNAL`).
 
-## Install, connect to agents, and configure hosts
+## Install and configure v1
 
-The lifecycle mirrors tools like CodeGraph: install the CLI, register the MCP with local agent clients, then configure per-machine host entries. Installing the CLI alone does not connect it to any agent; `hostbridge install` performs that wiring. It does not configure any servers; per-server setup is the separate `hostbridge setup` step.
-
-The shared distribution path is npm. Users can run the MCP server or setup wizard with `npx`:
-
-```bash
-npx -y @neoline/hostbridge install
-npx -y @neoline/hostbridge setup
-npx -y @neoline/hostbridge list
-```
-
-For a persistent global install:
+Install from npm or Python, then create a schema-v1 configuration and start the daemon:
 
 ```bash
 npm install -g @neoline/hostbridge
-hostbridge install
 hostbridge setup
+hostbridge daemon start
+hostbridge doctor
 ```
 
-`hostbridge install` detects supported local agents and writes only the hostbridge MCP entry into each detected config, preserving existing MCP servers. Supported targets are:
-
-- Codex CLI: `~/.codex/config.toml`
-- Claude Code: `~/.claude.json`
-- Cursor: `~/.cursor/mcp.json`
-- Gemini CLI: `~/.gemini/settings.json`
-- opencode: `~/.config/opencode/opencode.json`
-- Hermes Agent: `~/.hermes/mcp.json`
-- Antigravity IDE: `~/.antigravity/mcp.json`
-- Kiro: `~/.kiro/settings/mcp.json`
+The public CLI is intentionally small: `setup`, `migrate`, `doctor`, `hosts`, `daemon`, `mock-ssh`, and `version`. Configure MCP clients manually to run `npx -y @neoline/hostbridge`; when no CLI command is supplied the same entrypoint serves MCP over stdio.
 
-Use `--target <name>` for one client only, for example `hostbridge install --target codex`. From a source checkout, the installer registers `python3 <repo>/run_server.py`. From an installed package, it registers the `hostbridge` executable. Restart open agent clients or start new sessions once after installation so the new MCP server is loaded.
-
-This npm package is a Node launcher around the Python MCP core, so the machine still needs Python 3.11+ and the package's Python dependencies available to that interpreter. To point at a non-default interpreter:
-
-```bash
-HOSTBRIDGE_PYTHON=/path/to/python3 npx -y @neoline/hostbridge setup
-```
-
-For local development from this repository:
+Add a host as one validated JSON object:
 
 ```bash
-git clone <repo-url> hostbridge
-cd hostbridge
-python3 -m pip install -e .
-python3 -m server_control_mcp.server install
-npm run test:node
+hostbridge hosts add '{"id":"gpu","label":"GPU","ssh":{"host":"alice@gpu.example.com"},"transport":"auto"}'
+hostbridge hosts list
+hostbridge hosts check gpu
 ```
 
-
-
 ## File transfer model
 
 HostBridge file transfer is shell-based because recorded login paths may be JumpServer menus, OTP flows, wrapper scripts, or `docker exec` sessions rather than standard SSH/SFTP connections. The first-class transfer tools stream chunked base64 through the already-open shell session, verify hashes, and work for text or binary artifacts up to 100MiB:
@@ -92,7 +62,7 @@ Give file tools local and remote paths; do not paste base64 into tool arguments.
 Some clients, including compute providers, know how to connect to SSH targets but cannot run HostBridge's MCP connector inside their local sandbox. `hostbridge mock-ssh` exposes one configured HostBridge host as a local SSH server while keeping the actual remote access path behind HostBridge. This is useful when the client-side SSH implementation runs outside a restricted sandbox.
 
 ```bash
-hostbridge mock-ssh a800_95
+hostbridge mock-ssh start a800_95
 ```
 
 By default HostBridge selects a free local port from `2222-2299`, creates host/client keys under `~/.hostbridge/mock-ssh/<host_id>/`, and writes a managed `Host hostbridge-<host_id>` block into `~/.ssh/config`. The command prints the chosen alias, port, config path, and identity file:
@@ -108,7 +78,7 @@ identity file: /Users/alice/.hostbridge/mock-ssh/a800_95/client_ed25519_key
 Point the compute provider at the printed SSH alias, for example `ssh:hostbridge-a800_95`. To remove the managed SSH config block later:
 
 ```bash
-hostbridge mock-ssh a800_95 --remove
+hostbridge mock-ssh remove a800_95
 ```
 
 Advanced options are still available for fixed deployments: `--listen-host`, `--port`, `--key-dir`, `--ssh-host-alias`, `--ssh-config`, and `--no-ssh-config`.
@@ -159,81 +129,11 @@ For MCP clients, prefer setting the environment variable instead of relying on s
 
 Sessions can outlive a single agent client process. HostBridge records an optional `HOSTBRIDGE_AGENT_ID` owner on sessions and refuses cross-owner operations unless a force-close path is used. Set `HOSTBRIDGE_MAX_SESSIONS_PER_HOST` to cap concurrent live sessions per configured host (default `0`, unlimited).
 
-## Guided setup wizard
-
-Run the local setup wizard instead of hand-writing `hosts.json`:
-
-```bash
-hostbridge setup
-```
-
-You can also pass the host id up front to reduce prompts:
-
-```bash
-hostbridge setup gpu_1
-```
-
-The wizard now records the real login path instead of asking a fixed questionnaire:
-
-1. Collect only a stable host id, display label, and the command you already run locally, such as `ssh bastion`, `ssh -J bastion alice@gpu.internal`, `bash ~/.ssh/connect_gpu.sh`, or `docker exec -it training-box bash`.
-2. Start that command in a terminal-style PTY proxy: remote output is printed directly, and user input is forwarded to the setup session.
-3. Record the prompt visible when each line is typed. Secret-looking prompts (`password`, `passphrase`, `token`, `OTP`, `密码`, `验证码`) do not echo locally and are encrypted before saving.
-4. Convert the recorded prompt/input pairs into ordered `login_steps`; type `/ready` once the final remote shell prompt is available.
-5. Send a readiness probe through the same session, then replay the recorded `login_steps` in a fresh connection before saving `~/.hostbridge/hosts.json`.
+## Configuration lifecycle
 
-Useful helper commands:
+`hostbridge setup` creates an empty schema-v1 file with mode `0600`. It does not run an interactive login recorder. Use `hostbridge hosts add` for new entries and `hostbridge migrate OLD NEW` for legacy files. The daemon loads one validated config at startup; restart it after configuration changes.
 
-```bash
-hostbridge install
-hostbridge list
-hostbridge check gpu_1
-hostbridge remove gpu_1
-hostbridge setup --config ./hosts.json
-hostbridge reload
-```
-
-### Agent-friendly setup
-
-Agents should prefer the CLI setup flow over searching shell history or hand-editing JSON. A common JumpServer pattern is to clone a known bastion entry and change only the menu-selected host:
-
-```bash
-hostbridge setup gpu_lab_1 \
-  --label "Lab GPU server" \
-  --from-host bastion \
-  --menu-selection "gpu-lab-01" \
-  --final-prompt '.*[$#] '
-```
-
-This reuses the source host's connection command and encrypted secrets, replaces the menu selection, verifies the resulting runtime path, then saves the new host. After setup, running MCP servers that include runtime reload support will pick up the new entry on the next `hosts_list` or `session_open`; no client restart is required. If an already-running MCP process predates this feature, restart it once.
-
-Recommended agent flow:
-
-1. Call `hosts_list`.
-2. If the target host exists, call `session_open`.
-3. If `session_open` times out or fails, run `hostbridge check <host_id>` to verify the recorded login path, then retry or repair setup.
-4. If it does not exist and the user identifies a similar bastion-backed host, run `hostbridge setup <new_id> --from-host <source_id> --menu-selection <ip-or-name> --final-prompt <regex>`.
-5. Call `hosts_list` again, then `session_open(<new_id>)`.
-6. Do not inspect `~/.ssh`, old expect scripts, or shell snapshots unless the user explicitly asks or the setup command lacks required information.
-
-### Encrypted login automation
-
-Some environments require a password prompt, a bastion menu, or a JumpServer host selector before the remote shell is available. The setup wizard can save these as ordered `login_steps`. Secrets are encrypted with a local Fernet key at `~/.hostbridge/key` or `HOSTBRIDGE_KEY_FILE`; the decrypted value is used only in memory while opening a session.
-
-Equivalent non-interactive commands are available:
-
-```bash
-hostbridge secret set bastion password
-hostbridge step add bastion --expect '(?i)password:' --send-secret password
-hostbridge step add bastion --expect 'Opt>' --send 'gpu-lab-01'
-hostbridge step add bastion --expect '.*[$#] ' --send ''
-```
-
-Security model:
-
-- `hosts.json` never stores plaintext passwords.
-- `hostbridge list` and `hosts_list` do not expose secret material.
-- `~/.hostbridge/hosts.json` and `~/.hostbridge/key` should be readable only by the local user running the MCP server.
-- Local encryption protects config-at-rest, not a fully compromised same-user account. Prefer SSH keys or system keychains when available.
+Use `transport: "auto"` for normal operation, `pty` for JumpServer/menu/wrapper flows, or `ssh` for native AsyncSSH/SFTP-capable targets. Commands receive stdin explicitly through the protocol; HostBridge no longer guesses whether a command reads stdin.
 
 ## Configure hosts
 
@@ -243,6 +143,7 @@ Create `~/.hostbridge/hosts.json`:
 mkdir -p ~/.hostbridge
 cat > ~/.hostbridge/hosts.json <<'JSON'
 {
+  "schema_version": 1,
   "hosts": [
     {
       "id": "gpu_direct",
@@ -256,7 +157,7 @@ cat > ~/.hostbridge/hosts.json <<'JSON'
 JSON
 ```
 
-Running MCP servers reload this file during `hosts_list` and `session_open`, so a client restart is not normally required after editing it.
+The daemon validates this file at startup. Restart the daemon after editing it.
 
 ### Direct SSH, no jump host
 
@@ -339,26 +240,14 @@ Use this for non-SSH interactive shells, containers, or custom connection tools.
 
 ## MCP client config
 
-Prefer the installer:
-
-```bash
-hostbridge install
-```
-
-Single-client install is also available:
-
-```bash
-hostbridge install --target codex
-hostbridge install --target cursor
-hostbridge install --target opencode
-```
+Register the stdio entrypoint in each client. HostBridge v1 does not mutate client configuration files.
 
-Codex config written by the installer, for example in `~/.codex/config.toml`:
+Codex example in `~/.codex/config.toml`:
 
 ```toml
 [mcp_servers.hostbridge]
 command = "npx"
-args = ["-y", "hostbridge"]
+args = ["-y", "@neoline/hostbridge"]
 [mcp_servers.hostbridge.env]
 HOSTBRIDGE_AGENT_ID = "codex"
 ```
@@ -418,14 +307,12 @@ See `SECURITY.md` and `docs/THREAT_MODEL.md` for the trust model and audited eve
 ## Typical agent workflow
 
 1. Call `hosts_list` and choose a configured host id.
-2. If the host is missing, ask for only the missing fields and use `hostbridge setup <host_id>` rather than manually editing config.
+2. Add missing hosts with `hostbridge hosts add '<json>'`, then restart the daemon.
 3. Call `session_open` once for the chosen host.
-4. Only if `session_open` times out or fails, run `hostbridge check <host_id>` and retry after fixing the login path.
-5. Use `command_run` for quick commands such as `nvidia-smi`, `pwd`, `df -h`, or `tmux ls`.
-6. Use `task_start` for long training jobs, downloads, builds, or scripts.
-7. Poll `task_status` until `state` is `finished`; inspect `exit_code` and `log_tail`.
-8. Call `task_stop` early if a job should be aborted.
-9. Call `session_close` when finished, or `sessions_close_all` to tear down every session.
+4. Only after a connection failure, run `hostbridge hosts check <host_id>`.
+5. Use `command_run` for quick work and `task_start` / `task_status` for long jobs.
+6. Use text tools for UTF-8 and upload/download tools for streamed binary transfers.
+7. Close the session when finished.
 
 ## Security notes
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neoline/hostbridge",
-  "version": "1.4.3",
+  "version": "2.0.0",
   "description": "HostBridge MCP server for persistent allowlisted SSH and shell sessions.",
   "type": "module",
   "license": "MIT",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "hostbridge"
-version = "1.4.3"
+version = "2.0.0"
 description = "HostBridge MCP server for persistent allowlisted SSH and shell sessions."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -45,6 +45,7 @@ dependencies = [
 [project.optional-dependencies]
 dev = [
   "pytest>=8.0.0",
+  "pytest-asyncio>=0.24.0",
   "pytest-cov>=4.1.0",
   "ruff>=0.6.0",
   "mypy>=1.10.0",

package/src/server_control_mcp/__init__.py

@@ -2,13 +2,13 @@
 
 from __future__ import annotations
 
-import sys
 import os
 import subprocess
+import sys
 from typing import NoReturn
 
 __all__ = ["__version__", "ensure_runtime"]
-__version__ = "1.4.1"
+__version__ = "2.0.0"
 
 # (import_name, pip_name) pairs for runtime dependency probing.
 _REQUIRED_DEPENDENCIES = (
@@ -40,9 +40,8 @@ def ensure_runtime() -> None:
     missing = _missing_dependencies()
     if not missing:
         return
-    if _auto_install_enabled() and _install_missing_dependencies(missing):
-        if not _missing_dependencies():
-            return
+    if _auto_install_enabled() and _install_missing_dependencies(missing) and not _missing_dependencies():
+        return
 
     install_command = "pip install " + " ".join(missing)
     message = (