host-execution-mcp 1.0.0

package/dist/utils/result.d.ts

@@ -0,0 +1,87 @@
+import type { AppConfig } from "../config.js";
+export interface CommandResult {
+    success: boolean;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    truncated: boolean;
+    durationMs: number;
+}
+export interface ReadFileResult extends CommandResult {
+    mode?: "head" | "tail";
+    totalLines?: number;
+    totalBytes?: number;
+    returnedLines?: number;
+    lines?: number;
+    maxLines?: number;
+    truncatedByLines?: boolean;
+    truncatedByChars?: boolean;
+}
+export interface CopyFileResult {
+    success: boolean;
+    operation: "copy";
+    source: {
+        target: string;
+        path: string;
+    };
+    dest: {
+        target: string;
+        path: string;
+    };
+    bytes?: number;
+    totalBytes?: number;
+    skippedBytes?: number;
+    skipped?: boolean;
+    skipReason?: "size-match" | "hash-match";
+    transferId?: string;
+    verified?: boolean;
+    usedFastPath?: boolean;
+    message: string;
+    exitCode: number;
+    durationMs: number;
+}
+export declare function formatCommandResult(config: AppConfig, raw: {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    durationMs: number;
+}): CommandResult;
+export declare function formatErrorResult(config: AppConfig, error: unknown, durationMs: number): CommandResult;
+export declare function formatReadFileResult(config: AppConfig, raw: {
+    content: string;
+    exitCode: number;
+    durationMs: number;
+    maxLines: number;
+    mode?: "head" | "tail";
+    meta?: {
+        totalLines?: number;
+        totalBytes?: number;
+    };
+}): ReadFileResult;
+export declare function formatCopyFileResult(raw: {
+    source: {
+        target: string;
+        path: string;
+    };
+    dest: {
+        target: string;
+        path: string;
+    };
+    exitCode: number;
+    durationMs: number;
+    bytes?: number;
+    totalBytes?: number;
+    skippedBytes?: number;
+    skipped?: boolean;
+    skipReason?: "size-match" | "hash-match";
+    transferId?: string;
+    verified?: boolean;
+    usedFastPath?: boolean;
+    message: string;
+}): CopyFileResult;
+export declare function toToolText(result: CommandResult | ReadFileResult | CopyFileResult | Record<string, unknown>): {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+};

package/dist/utils/result.js

@@ -0,0 +1,81 @@
+import { isAccessUnavailableError } from "../ssh/access-errors.js";
+import { truncateOutput } from "./truncate.js";
+export function formatCommandResult(config, raw) {
+    const combined = [raw.stdout, raw.stderr].filter(Boolean).join(raw.stdout && raw.stderr ? "\n" : "");
+    const { text, truncated } = truncateOutput(combined, config.maxOutputChars);
+    return {
+        success: raw.exitCode === 0,
+        stdout: text,
+        stderr: "",
+        exitCode: raw.exitCode,
+        truncated,
+        durationMs: raw.durationMs,
+    };
+}
+export function formatErrorResult(config, error, durationMs) {
+    const message = isAccessUnavailableError(error)
+        ? JSON.stringify({
+            ...error.toJSON(),
+            // Keep human-readable multiline message for Agents that only read stderr.
+            message: error.message,
+        }, null, 2)
+        : error instanceof Error
+            ? error.message
+            : String(error);
+    const { text, truncated } = truncateOutput(message, config.maxOutputChars);
+    return {
+        success: false,
+        stdout: "",
+        stderr: text,
+        exitCode: 1,
+        truncated,
+        durationMs,
+    };
+}
+export function formatReadFileResult(config, raw) {
+    const base = formatCommandResult(config, {
+        stdout: raw.content,
+        stderr: "",
+        exitCode: raw.exitCode,
+        durationMs: raw.durationMs,
+    });
+    const returnedLines = raw.content ? raw.content.split("\n").length : 0;
+    const totalLines = raw.meta?.totalLines;
+    const truncatedByLines = totalLines !== undefined && totalLines > raw.maxLines && returnedLines >= raw.maxLines;
+    return {
+        ...base,
+        mode: raw.mode,
+        totalLines,
+        totalBytes: raw.meta?.totalBytes,
+        returnedLines,
+        lines: raw.maxLines,
+        maxLines: raw.maxLines,
+        truncatedByLines,
+        truncatedByChars: base.truncated,
+    };
+}
+export function formatCopyFileResult(raw) {
+    return {
+        success: raw.exitCode === 0,
+        operation: "copy",
+        source: raw.source,
+        dest: raw.dest,
+        bytes: raw.bytes,
+        totalBytes: raw.totalBytes,
+        skippedBytes: raw.skippedBytes,
+        skipped: raw.skipped,
+        skipReason: raw.skipReason,
+        transferId: raw.transferId,
+        verified: raw.verified,
+        usedFastPath: raw.usedFastPath,
+        message: raw.message,
+        exitCode: raw.exitCode,
+        durationMs: raw.durationMs,
+    };
+}
+export function toToolText(result) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+    };
+}
+//# sourceMappingURL=result.js.map

package/dist/utils/result.js.map

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

package/dist/utils/shell-quote.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Escape a string for safe embedding inside single-quoted bash -lc '...'.
+ * Uses the pattern: '...'"'"'...' for embedded single quotes.
+ */
+export declare function bashSingleQuote(value: string): string;
+export declare function buildBashLcCommand(command: string, cwd?: string): string;
+/**
+ * Shared -o flags for Hop2 host ssh/scp.
+ * Password auth omits BatchMode so sshpass can prompt-less password auth.
+ */
+export declare function hostSshBaseOpts(password?: string): string;
+/**
+ * Optional sshpass + ssh|scp + shared -o opts (no target / remote command).
+ * Used by buildSshRemoteCommand and scp helpers so opts do not fork.
+ */
+export declare function buildHostTransportPrefix(binary: "ssh" | "scp", password?: string): string;
+/**
+ * Bastion → host remote exec: ssh … with the entire `bash -lc '<cmd>'` as one
+ * argv so OpenSSH does not space-join and truncate multi-word commands.
+ */
+export declare function buildSshRemoteCommand(user: string, host: string, command: string, password?: string): string;
+export declare function shellEscapeArg(value: string): string;

package/dist/utils/shell-quote.js

@@ -0,0 +1,55 @@
+/**
+ * Escape a string for safe embedding inside single-quoted bash -lc '...'.
+ * Uses the pattern: '...'"'"'...' for embedded single quotes.
+ */
+export function bashSingleQuote(value) {
+    if (!value.includes("'")) {
+        return `'${value}'`;
+    }
+    const escapedQuote = "'\"'\"'";
+    return `'${value.replace(/'/g, escapedQuote)}'`;
+}
+export function buildBashLcCommand(command, cwd) {
+    const quoted = bashSingleQuote(command);
+    if (cwd) {
+        return `cd ${bashSingleQuote(cwd)} && bash -lc ${quoted}`;
+    }
+    return `bash -lc ${quoted}`;
+}
+/**
+ * Shared -o flags for Hop2 host ssh/scp.
+ * Password auth omits BatchMode so sshpass can prompt-less password auth.
+ */
+export function hostSshBaseOpts(password) {
+    if (password) {
+        return "-o StrictHostKeyChecking=accept-new -o ConnectTimeout=10";
+    }
+    return "-o BatchMode=yes -o ConnectTimeout=10 -o StrictHostKeyChecking=accept-new";
+}
+/**
+ * Optional sshpass + ssh|scp + shared -o opts (no target / remote command).
+ * Used by buildSshRemoteCommand and scp helpers so opts do not fork.
+ */
+export function buildHostTransportPrefix(binary, password) {
+    const opts = hostSshBaseOpts(password);
+    if (password) {
+        return `sshpass -p ${bashSingleQuote(password)} ${binary} ${opts}`;
+    }
+    return `${binary} ${opts}`;
+}
+/**
+ * Bastion → host remote exec: ssh … with the entire `bash -lc '<cmd>'` as one
+ * argv so OpenSSH does not space-join and truncate multi-word commands.
+ */
+export function buildSshRemoteCommand(user, host, command, password) {
+    const target = `${user}@${host}`;
+    const remote = `bash -lc ${bashSingleQuote(command)}`;
+    return `${buildHostTransportPrefix("ssh", password)} ${bashSingleQuote(target)} ${bashSingleQuote(remote)}`;
+}
+export function shellEscapeArg(value) {
+    if (/^[A-Za-z0-9_@%+=:,./-]+$/.test(value)) {
+        return value;
+    }
+    return bashSingleQuote(value);
+}
+//# sourceMappingURL=shell-quote.js.map

package/dist/utils/shell-quote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-quote.js","sourceRoot":"","sources":["../../src/utils/shell-quote.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAa;IAC3C,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;QACzB,OAAO,IAAI,KAAK,GAAG,CAAC;IACtB,CAAC;IACD,MAAM,YAAY,GAAG,SAAS,CAAC;IAC/B,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,YAAY,CAAC,GAAG,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,OAAe,EAAE,GAAY;IAC9D,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACxC,IAAI,GAAG,EAAE,CAAC;QACR,OAAO,MAAM,eAAe,CAAC,GAAG,CAAC,gBAAgB,MAAM,EAAE,CAAC;IAC5D,CAAC;IACD,OAAO,YAAY,MAAM,EAAE,CAAC;AAC9B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,QAAiB;IAC/C,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,0DAA0D,CAAC;IACpE,CAAC;IACD,OAAO,2EAA2E,CAAC;AACrF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAAqB,EAAE,QAAiB;IAC/E,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;IACvC,IAAI,QAAQ,EAAE,CAAC;QACb,OAAO,cAAc,eAAe,CAAC,QAAQ,CAAC,IAAI,MAAM,IAAI,IAAI,EAAE,CAAC;IACrE,CAAC;IACD,OAAO,GAAG,MAAM,IAAI,IAAI,EAAE,CAAC;AAC7B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CACnC,IAAY,EACZ,IAAY,EACZ,OAAe,EACf,QAAiB;IAEjB,MAAM,MAAM,GAAG,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;IACjC,MAAM,MAAM,GAAG,YAAY,eAAe,CAAC,OAAO,CAAC,EAAE,CAAC;IACtD,OAAO,GAAG,wBAAwB,CAAC,KAAK,EAAE,QAAQ,CAAC,IAAI,eAAe,CAAC,MAAM,CAAC,IAAI,eAAe,CAAC,MAAM,CAAC,EAAE,CAAC;AAC9G,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,IAAI,0BAA0B,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3C,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;AAChC,CAAC"}

package/dist/utils/timeout.d.ts

@@ -0,0 +1 @@
+export declare function withTimeout<T>(promise: Promise<T>, timeoutMs: number, onTimeout?: () => void): Promise<T>;

package/dist/utils/timeout.js

@@ -0,0 +1,18 @@
+export function withTimeout(promise, timeoutMs, onTimeout) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            onTimeout?.();
+            reject(new Error(`Operation timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        promise
+            .then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        })
+            .catch((error) => {
+            clearTimeout(timer);
+            reject(error);
+        });
+    });
+}
+//# sourceMappingURL=timeout.js.map

package/dist/utils/timeout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeout.js","sourceRoot":"","sources":["../../src/utils/timeout.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,WAAW,CACzB,OAAmB,EACnB,SAAiB,EACjB,SAAsB;IAEtB,OAAO,IAAI,OAAO,CAAI,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACxC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC5B,SAAS,EAAE,EAAE,CAAC;YACd,MAAM,CAAC,IAAI,KAAK,CAAC,6BAA6B,SAAS,IAAI,CAAC,CAAC,CAAC;QAChE,CAAC,EAAE,SAAS,CAAC,CAAC;QAEd,OAAO;aACJ,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE;YACd,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,OAAO,CAAC,KAAK,CAAC,CAAC;QACjB,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;YACxB,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,MAAM,CAAC,KAAK,CAAC,CAAC;QAChB,CAAC,CAAC,CAAC;IACP,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/utils/truncate.d.ts

@@ -0,0 +1,5 @@
+export interface TruncateResult {
+    text: string;
+    truncated: boolean;
+}
+export declare function truncateOutput(text: string, maxChars: number): TruncateResult;

package/dist/utils/truncate.js

@@ -0,0 +1,12 @@
+export function truncateOutput(text, maxChars) {
+    if (text.length <= maxChars) {
+        return { text, truncated: false };
+    }
+    const suffix = `\n\n...[truncated, ${text.length - maxChars} chars omitted]`;
+    const keep = Math.max(0, maxChars - suffix.length);
+    return {
+        text: text.slice(0, keep) + suffix,
+        truncated: true,
+    };
+}
+//# sourceMappingURL=truncate.js.map

package/dist/utils/truncate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"truncate.js","sourceRoot":"","sources":["../../src/utils/truncate.ts"],"names":[],"mappings":"AAKA,MAAM,UAAU,cAAc,CAAC,IAAY,EAAE,QAAgB;IAC3D,IAAI,IAAI,CAAC,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC5B,OAAO,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IACpC,CAAC;IACD,MAAM,MAAM,GAAG,sBAAsB,IAAI,CAAC,MAAM,GAAG,QAAQ,iBAAiB,CAAC;IAC7E,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IACnD,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,MAAM;QAClC,SAAS,EAAE,IAAI;KAChB,CAAC;AACJ,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const VERSION: string;

package/dist/version.js

@@ -0,0 +1,7 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const packagePath = join(dirname(fileURLToPath(import.meta.url)), "..", "package.json");
+const pkg = JSON.parse(readFileSync(packagePath, "utf8"));
+export const VERSION = pkg.version;
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC;AACxF,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAwB,CAAC;AAEjF,MAAM,CAAC,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC"}

package/docs/AGENT_GUIDE.md

@@ -0,0 +1,161 @@
+# Agent Guide — host-execution-mcp
+
+Extended reference for LLM agents. A shorter version is injected as MCP server `instructions` at handshake (KIND-aware for `ssh` vs `paradi-gateway`).
+
+## Naming (5.0.0)
+
+Agent-facing tools use ACCESS/Context naming: `access_check`, `shell_exec`, `context_derive`, `contextKey`, `target=landing|pod|context`. Error code: `ACCESS_UNAVAILABLE`.
+
+| ACCESS_KIND | Landing Context | `shell_exec` / `target=landing` means |
+|-------------|-----------------|----------------------------------------|
+| `ssh` (default) | ACCESS host | ACCESS OS |
+| `paradi-gateway` | TARGET host | TARGET OS (not the gateway) |
+
+User config is `ACCESS_*` / `TARGET_*` only. Async copy root: `ACCESS_COPY_JOB_ROOT`.
+
+## Architecture (read this first)
+
+**There is no direct connection from the user's laptop to pods or cluster nodes.**
+
+### Shape A — ACCESS_KIND=ssh
+
+```
+┌─────────────┐   Hop 1 (automatic)    ┌──────────┐   Hop 2 (tools)        ┌────────────┐
+│ MCP Client  │ ─── SSH (ssh2) ──────► │ ACCESS   │ ── kubectl exec ────► │ Pod        │
+│ + MCP Server│                        │ landing  │ ── ssh/sshpass ─────► │ Host/node  │
+└─────────────┘                        │          │ ── shell / docker ──► │ ACCESS OS  │
+                                       └──────────┘                        └────────────┘
+```
+
+`TARGET_*` (optional) = **default derive selector only** — not a second Context at init. `ssh_exec` = derive + shell.
+
+### Shape B — ACCESS_KIND=paradi-gateway
+
+```
+┌─────────────┐   Hop 1                ┌──────────┐
+│ MCP Client  │ ── SSH (encoded user) ►│ Gateway  │──► landing Context = TARGET
+└─────────────┘   ACCESS_USER/TARGET_HOST/TARGET_USER
+```
+
+Runtime tools run on **TARGET**. Disabled: `context_derive`, `remote_*` / `remote_copy_*` with `target=context`. Use `shell_exec` / `target=landing` / `docker_*` (omit contextKey). SFTP is `degraded` — avoid parallel hammering; prefer smaller copies / `remote_copy_start`.
+
+| Hop | Who initiates | What |
+|-----|---------------|------|
+| **Hop 1** | MCP server on user's machine | SSH to `ACCESS_HOST` (always; not exposed as a tool) |
+| **Hop 2** | Landing Context | `shell_exec`, `k8s_*`, `ssh_exec` (ssh only), `docker_*`, `remote_*` |
+
+**Common misconception:** `ssh_exec` is **NOT** "local laptop SSH to remote host". It means **ACCESS SSHs to the target** (`ACCESS_KIND=ssh` only).
+
+## Capability boundary
+
+Remote execution primitives only. No project-specific paths or namespace defaults.
+
+- `docker_*` auto-probes `capabilities.docker` (unknown ≠ true).
+- `k8s_*` does **not** gate on `capabilities.kubectl` — failures surface as exitCode; use `context_probe` for presence.
+
+## Three Runtime paths (ssh)
+
+| Path | Tool(s) | Action |
+|------|---------|--------|
+| **Landing shell** | `shell_exec`, `remote_*` target=landing | Run on ACCESS (or TARGET under Paradi) |
+| **Pod** | `k8s_exec`, `k8s_logs`, `remote_*` target=pod | kubectl exec / logs |
+| **Derived host** | `context_derive` → `ssh_exec`, `remote_*` target=context | ssh/sshpass — **ssh kind only** |
+
+### Decision matrix
+
+| User intent | Tool (ssh) | Tool (paradi) |
+|-------------|------------|---------------|
+| List/find pods | `k8s_list_pods` | same |
+| Run script in container | `k8s_exec` | same |
+| Read file in container | `remote_read_file` target=pod | same |
+| Host OS shell on landing | `shell_exec` | `shell_exec` (TARGET) |
+| Host OS after jump | `context_derive` + `ssh_exec` / target=context | **disabled** — already on TARGET |
+| Docker on landing | `docker_*` | `docker_*` (no host) |
+| Docker on worker | `docker_*` + contextKey | **disabled** under Paradi |
+| Copy short | `remote_copy_file` | same; no `target=context` under Paradi |
+| Copy large | `remote_copy_start` | same; SFTP degraded |
+
+## ssh_exec vs k8s_exec vs docker_* vs shell_exec
+
+| Tool | Reaches | Auth / notes |
+|------|---------|----------------|
+| `shell_exec` | Landing OS shell | ACCESS_* (Paradi: TARGET via gateway); optional contextKey |
+| `k8s_exec` | Inside pod container | Landing kubeconfig |
+| `ssh_exec` | Host OS (derive + shell) | ACCESS→host / TARGET_*; unavailable under Paradi |
+| `docker_ps` / `docker_exec` / `docker_logs` | Docker on landing or derived Context | SessionPool; contextKey; auto-probes docker; unknown ≠ true |
+| `context_probe` | Same Context | Returns docker/kubectl tri-state |
+
+**Derived-host defaults (`TARGET_USER` / `TARGET_PASSWORD`):** optional under ssh. When both set, omit `user`/`password`. Password-only: omit password, still pass user. See one-line status in server instructions. Under Paradi, derive guidance is replaced by a “landing=TARGET / derive unsupported” note.
+
+**Docker vs k8s:** container on host Docker engine → `docker_*`; container in Kubernetes → `k8s_exec` / `k8s_logs`.
+
+## Handshake behavior
+
+1. Connectivity unknown / first remote ops: `access_check` (ACCESS SSH probe ≤10s; ephemeral; not kubectl)
+2. Kubernetes ops only: then `shell_exec({"command":"kubectl cluster-info --request-timeout=5s"})`
+
+If `access_check.reachable=false`: stop; read JSON `message`/`hints` (VPN / `ACCESS_HOST`). If other tools return `code=ACCESS_UNAVAILABLE`: stop; Chinese hints are usually in `stderr`.
+
+Always obtain from user or context: namespace, container name for multi-container pods. For host SSH (ssh kind): only ask user/password when `TARGET_*` are unset.
+
+## Tool return format
+
+On **success** (`exitCode===0`), remote command output (stdout and stderr combined) is in `stdout`; the `stderr` field is empty.
+
+On **command failure** (`exitCode≠0`, `success=false`, no thrown exception): merged remote output is still in **`stdout`**. Only tool/connection exceptions (e.g. `ACCESS_UNAVAILABLE`) put the message in `stderr`.
+
+Always check both `success` / `exitCode` and `stdout`.
+
+## Shell / I/O pitfalls
+
+| Topic | Guidance |
+|-------|----------|
+| Shell metacharacters | Every remote command is parsed by bash. Quote `&`, `\|`, `>`, `$`, and URLs. Prefer `remote_copy_file` of an LF script, then `bash script.sh`. |
+| Non-TTY docker | `docker login` / `pull` often exit 0 with empty stdout — use `exitCode` and follow-up probe. |
+| CRLF scripts | Ship LF, or `sed -i 's/\r$//' file` / `tr -d '\r'`. |
+| DOCKER_CONFIG | If permission denied: `export DOCKER_CONFIG=$HOME/dockertmp && mkdir -p "$DOCKER_CONFIG"`. |
+| Registry SOP | Host with egress; `docker login` once; quoted Registry API probe. Never bare `&` in URLs. |
+
+## MCP prompts
+
+| Prompt | Purpose |
+|--------|---------|
+| `tool-selection` | Pick the right tool for a scenario |
+| `remote-debug-workflow` | list → read/tail → ps workflow |
+
+## Error handling
+
+| Situation | Action |
+|-----------|--------|
+| `truncatedByLines: true` | Increase `maxLines`, use `offset`, or use `remote_copy_file` |
+| `truncatedByChars: true` | Raise `MAX_OUTPUT_CHARS` or use `remote_copy_file` |
+| `ssh_exec` under Paradi | Expected error — use `shell_exec` / `target=landing` |
+| `ssh_exec` Permission denied | Add password or use `k8s_exec` for pods |
+| Command `success=false` / exit≠0 | Read **stdout** |
+| Empty stdout + exit 0 (docker) | Normal for non-TTY |
+| `k8s_logs` empty | Use `remote_read_file` mode=tail for file logs |
+| Large copy times out | Raise `totalTimeoutMs`; Paradi: expect SFTP flakiness |
+
+## Large file copy (local ↔ landing)
+
+For multi-GB landing↔local (or pod→local last hop):
+
+```json
+{
+  "source": { "target": "landing", "path": "/tmp/big.pt" },
+  "dest": { "target": "local", "path": "C:/data/big.pt" },
+  "skipIfComplete": true,
+  "totalTimeoutMs": 3600000,
+  "verify": "size"
+}
+```
+
+- Progress: throttled (`progressIntervalMs`, default 5s); MCP `notifications/progress` if client sends `progressToken`
+- `skipIfComplete`: skip gate follows `verify`
+- Result includes `transferId`; async jobs expose `remote_copy_status`
+
+| Layer | Responsibility |
+|-------|----------------|
+| **host-execution-mcp** | Access-mediated remote exec |
+| **User Skill** | Namespace, paths, scripts |
+| **User** | Approving destructive ops |

package/docs/CONFIGURATION.md

@@ -0,0 +1,130 @@
+# Configuration
+
+## Access shapes (user mental model)
+
+| Shape | Env | Meaning |
+|-------|-----|---------|
+| Single host | `ACCESS_*` only | Land on ACCESS; shell / kubectl / docker there |
+| Bastion → target | `ACCESS_*` + `TARGET_*` | Land on ACCESS; `TARGET_*` is **default derive selector** (not a second Context at init) |
+| Paradi gateway | `ACCESS_KIND=paradi-gateway` + `TARGET_HOST` + `TARGET_USER` | SSH to gateway with encoded identity; landing Context = TARGET |
+
+Runtime (shell / docker / kubectl) is **not** configured in mcp.json — Agent chooses from Context capabilities.
+
+## Required environment variables
+
+| Variable | Description |
+|----------|-------------|
+| `ACCESS_HOST` | First SSH endpoint (jump host, direct target, or Paradi gateway) |
+| `ACCESS_USER` | SSH username for ACCESS |
+
+## Optional environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `ACCESS_KIND` | `ssh` | `ssh` \| `paradi-gateway` |
+| `ACCESS_PORT` | `22` | SSH port |
+| `ACCESS_PRIVATE_KEY_PATH` | — | Explicit private key path |
+| `ACCESS_PASSWORD` | — | Password auth (dev only); also used to build Paradi compound password when that mode wins |
+| `ACCESS_PARADI_AUTH` | `auto` | Paradi only: `auto` \| `slash` \| `compound`. Default `auto` tries slash then compound on AUTH_FAILED and **pins** the winner for this MCP process |
+| `TARGET_HOST` | — | Default derive host (`ssh`) or Paradi landing host |
+| `TARGET_USER` | — | **Required if `TARGET_HOST` set** (no fallback to `ACCESS_USER`) |
+| `TARGET_PASSWORD` | — | Default derive password (sshpass); ignored for Paradi auth |
+| `DEFAULT_TIMEOUT_MS` | `60000` | Default command timeout |
+| `MAX_OUTPUT_CHARS` | `65536` | Max tool output size |
+
+## Policy (not Access)
+
+| Variable | Description |
+|----------|-------------|
+| `ACCESS_POLICY_ALLOWED_NAMESPACES` | Comma-separated kubectl namespace whitelist |
+| `ALLOWED_NAMESPACES` | Same (kept as short alias for policy only) |
+
+## Ops (not Access matrix)
+
+| Variable | Description |
+|----------|-------------|
+| `ACCESS_COPY_JOB_ROOT` | Async copy job state root (default `~/.agent-compose/remote-copy`) |
+
+## Removed in 4.0.0
+
+Do **not** set: `BASTION_HOST`, `BASTION_USER`, `BASTION_PORT`, `BASTION_PASSWORD`, `BASTION_PRIVATE_KEY_PATH`, `REMOTE_SSH_USER`, `REMOTE_SSH_PASSWORD`.  
+If present, `loadConfig` throws with rename hints (`BASTION_HOST` → `ACCESS_HOST`, etc.).
+
+## SSH authentication (ACCESS)
+
+Configure **one or more** methods; the server passes all of them to the SSH client, which tries each until one succeeds:
+
+| Method | When used |
+|--------|-----------|
+| `ACCESS_PRIVATE_KEY_PATH` | File exists at the given path |
+| Default `~/.ssh/id_ed25519`, `id_rsa`, `id_ecdsa` | Used when no explicit key path is set and a default key file exists |
+| SSH agent (`SSH_AUTH_SOCK`) | Socket path is set and the socket file exists |
+| `ACCESS_PASSWORD` | Variable is set |
+
+**Examples:**
+
+- Key or agent only (passwordless): configure keys/agent; do not set `ACCESS_PASSWORD`.
+- Password only: set `ACCESS_PASSWORD`; no keys required.
+- Agent socket present but empty (common in IDE-launched MCP): also set `ACCESS_PASSWORD`.
+
+## MCP client setup
+
+The server uses **stdio transport**. See [clients/](clients/).
+
+### Minimal
+
+```json
+{
+  "mcpServers": {
+    "host-execution": {
+      "command": "npx",
+      "args": ["-y", "host-execution-mcp@latest"],
+      "env": {
+        "ACCESS_HOST": "10.0.0.1",
+        "ACCESS_USER": "admin"
+      }
+    }
+  }
+}
+```
+
+### With default derive target
+
+```json
+{
+  "ACCESS_KIND": "ssh",
+  "ACCESS_HOST": "10.121.120.7",
+  "ACCESS_USER": "mccxadmin",
+  "ACCESS_PASSWORD": "<secret>",
+  "TARGET_HOST": "10.121.35.68",
+  "TARGET_USER": "mccuseradmin",
+  "TARGET_PASSWORD": "<secret>"
+}
+```
+
+### With Paradi gateway
+
+```json
+{
+  "ACCESS_KIND": "paradi-gateway",
+  "ACCESS_HOST": "10.121.61.3",
+  "ACCESS_USER": "bastion-login",
+  "ACCESS_PASSWORD": "<secret>",
+  "TARGET_HOST": "10.121.35.68",
+  "TARGET_USER": "mccuseradmin"
+}
+```
+
+Customers only set gateway + target. Do **not** put a three-part SSH username or `@##@` password in mcp.json — the server encodes them.
+
+Default `ACCESS_PARADI_AUTH=auto` (may omit):
+
+1. Try **slash** username `ACCESS_USER/TARGET_HOST/TARGET_USER` + `ACCESS_PASSWORD`
+2. On AUTH_FAILED only, try **compound** username `ACCESS_USER` + `ACCESS_PASSWORD@##@TARGET_HOST:SSH:22:TARGET_USER`
+3. Pin the winner for this MCP process (restart MCP to clear / re-probe)
+
+Ops override: set `ACCESS_PARADI_AUTH=slash` or `compound` to force one encoding. `access_check` may report `paradiAuth` after success.
+
+Landing Context is already TARGET: use `shell_exec` / `docker_*` (omit contextKey).
+
+See [PARADI_ACCESS_PLAN.md](PARADI_ACCESS_PLAN.md) for the full Access / Runtime model.

package/docs/COPY_SPECIALIZED_TEST_CHECKLIST.md

@@ -0,0 +1,9 @@
+# Copy specialized test checklist
+
+Hop1 3.0.0 全面端到端清单已迁移至：
+
+- **[`docs/HOP1_E2E_CHECKLIST.md`](HOP1_E2E_CHECKLIST.md)** — A1–J4（43 项，最近 **43/43 pass**）
+- **[`docs/HOP1_E2E_RESULTS.json`](HOP1_E2E_RESULTS.json)** — 原始结果
+- Runner：`scripts/hop1-e2e-one.mjs` / `scripts/hop1-e2e-all.mjs`
+
+旧 T1–T8（`scripts/specialized-one.mjs`）仍可用，映射见 HOP1_E2E_CHECKLIST 文末。