host-execution-mcp 1.0.1 → 2.0.0

package/dist/tools/register.js

@@ -1,10 +1,9 @@
 import { z } from "zod";
-import { assertCopyEndpointsAllowed, executeRemoteCopy } from "../utils/copy-executor.js";
-import { CopyJobManager } from "../utils/copy-job-manager.js";
+import { executeRemoteCopy } from "../utils/copy-executor.js";
 import { buildPsCommand, buildRemoteReadCommand, parseReadFileMeta, } from "../utils/remote-target.js";
 import { formatCommandResult, formatCopyFileResult, formatErrorResult, formatReadFileResult, toToolText, } from "../utils/result.js";
-import { remoteCopyCancelSchema, remoteCopyStatusSchema, buildRemoteCopyStartSchema, } from "./copy-job-schemas.js";
-import { buildRemoteCopyFileSchema, buildRemotePsSchema, buildRemoteReadFileSchema, fileEndpointToInternal, materializeCopyEndpoint, remoteInputToTarget, resolveReadOptions, } from "./remote-schemas.js";
+import { remoteCopyCancelSchema, remoteCopyStatusSchema, remoteCopyStartSchema, } from "./copy-job-schemas.js";
+import { assertCopySkipVerify, hopHostField, linkDescriptionField, materializeAgentCopyEndpoint, remoteCopyFileSchema, remotePsSchema, remoteReadFileSchema, resolveReadOptions, runTargetFromArgs, } from "./remote-schemas.js";
 async function handleTool(config, fn) {
     const started = Date.now();
     try {
@@ -21,15 +20,59 @@ async function handleTool(config, fn) {
         return toToolText(formatErrorResult(config, error, Date.now() - started));
     }
 }
-async function handleRemoteReadFile(config, remote, args) {
+function openMachine(hub, pick) {
+    const session = hub.resolve({ description: pick.description });
+    const ctx = session.access.selectMachine({
+        host: pick.host,
+        user: pick.user,
+        password: pick.password,
+    });
+    return { session, contextKey: ctx.key };
+}
+/** Catch pick/select errors as tool JSON (same shape as handleTool), not MCP protocol faults. */
+async function handleMachineTool(hub, pick, fn) {
     const started = Date.now();
-    const resolved = resolveReadOptions(args);
     try {
+        const { session, contextKey } = openMachine(hub, pick);
+        return await handleTool(session.config, () => fn(session, contextKey));
+    }
+    catch (error) {
+        return toToolText(formatErrorResult(hub.hintConfig() ?? sessionlessConfig(), error, Date.now() - started));
+    }
+}
+function machineSelectFields(config) {
+    const targetUserConfigured = Boolean(config?.targetUser?.trim());
+    const targetPasswordConfigured = Boolean(config?.targetPassword);
+    const isParadi = config?.accessKind === "paradi-gateway";
+    return {
+        description: linkDescriptionField,
+        host: hopHostField,
+        user: z
+            .string()
+            .optional()
+            .describe(targetUserConfigured
+            ? `Omit to use TARGET_USER=${config?.targetUser}`
+            : "Required for a hop-2 / Paradi host unless the selected link has TARGET_USER"),
+        password: z
+            .string()
+            .optional()
+            .describe(isParadi
+            ? "Ignored for Paradi default auth (gateway password is ACCESS_PASSWORD)"
+            : targetPasswordConfigured
+                ? "Omit to use TARGET_PASSWORD"
+                : "Hop-2 password when the selected link has no TARGET_PASSWORD"),
+    };
+}
+async function handleRemoteReadFile(hub, args) {
+    const started = Date.now();
+    try {
+        const { session, contextKey } = openMachine(hub, args);
+        const resolved = resolveReadOptions(args);
         const command = buildRemoteReadCommand(args.path, resolved);
-        const raw = await remote.runOnTarget(remoteInputToTarget(args), command, args.timeoutMs);
+        const raw = await session.remote.runOnTarget(runTargetFromArgs(contextKey, args), command, args.timeoutMs);
         const mergedStdout = [raw.stdout, raw.stderr].filter(Boolean).join("\n");
         const { meta, content } = parseReadFileMeta(mergedStdout);
-        return toToolText(formatReadFileResult(config, {
+        return toToolText(formatReadFileResult(session.config, {
             content,
             exitCode: raw.exitCode,
             durationMs: raw.durationMs ?? Date.now() - started,
@@ -39,168 +82,90 @@ async function handleRemoteReadFile(config, remote, args) {
         }));
     }
     catch (error) {
-        return toToolText(formatErrorResult(config, error, Date.now() - started));
+        return toToolText(formatErrorResult(hub.hintConfig() ?? sessionlessConfig(), error, Date.now() - started));
     }
 }
-function resolveCopyEndpoints(access, config, args) {
-    const sourceRaw = fileEndpointToInternal(args.source);
-    const destRaw = fileEndpointToInternal(args.dest);
-    assertCopyEndpointsAllowed(config, sourceRaw, destRaw);
-    const source = materializeCopyEndpoint(access, sourceRaw);
-    const dest = materializeCopyEndpoint(access, destRaw);
-    return { source, dest };
+function resolveCopyEndpoints(hub, args) {
+    assertCopySkipVerify(args);
+    const { session, contextKey } = openMachine(hub, args);
+    return {
+        session,
+        source: materializeAgentCopyEndpoint(session.access, contextKey, args.source),
+        dest: materializeAgentCopyEndpoint(session.access, contextKey, args.dest),
+    };
+}
+function sessionlessConfig() {
+    return {
+        accessKind: "ssh",
+        accessHost: "",
+        accessUser: "",
+        accessPort: 22,
+        defaultTimeoutMs: 60_000,
+        maxOutputChars: 65_536,
+    };
 }
 export function registerTools(server, deps) {
-    const { config, accessClient, access, kubectl, remote } = deps;
-    const copyJobs = new CopyJobManager({ accessClient, config });
-    const targetUserConfigured = Boolean(config.targetUser?.trim());
-    const targetPasswordConfigured = Boolean(config.targetPassword);
-    const targetHostConfigured = Boolean(config.targetHost?.trim());
-    const isParadi = config.accessKind === "paradi-gateway";
-    const allowContext = !isParadi;
-    const remoteReadFileSchema = buildRemoteReadFileSchema({ allowContext });
-    const remotePsSchema = buildRemotePsSchema({ allowContext });
-    const remoteCopyFileSchema = buildRemoteCopyFileSchema({ allowContext });
-    const remoteCopyStartSchema = buildRemoteCopyStartSchema({ allowContext });
-    const contextKeyField = allowContext
-        ? z
-            .string()
-            .optional()
-            .describe("HostExecutionContext key from context_derive (omit for landing Context)")
-        : undefined;
-    const shellInputSchema = {
-        command: z.string().min(1).describe("Shell command to run on the selected Context"),
-        timeoutMs: z.number().int().positive().optional().describe("Timeout in milliseconds"),
-        cwd: z.string().optional().describe("Working directory on the Context"),
-        ...(contextKeyField ? { contextKey: contextKeyField } : {}),
-    };
+    const { hub } = deps;
+    const config = hub.hintConfig();
+    const select = machineSelectFields(config);
     server.registerTool("access_check", {
-        description: isParadi
-            ? `Probe Local → Paradi gateway → TARGET connectivity (≤10s). Structured JSON: reachable, latencyMs, host, port, auth.
+        description: `Probe Local → ACCESS SSH connectivity with short timeouts (≤10s). Structured JSON: reachable, latencyMs, host, port, auth.
 
-Under ACCESS_KIND=paradi-gateway, AccessTransport SSHs the gateway with encoded username; success means landing Context (TARGET) is reachable. Does NOT run kubectl.
+AccessTransport only (MCP client → SSH → ACCESS). Does NOT run kubectl or touch hop-2 hosts. Uses an ephemeral SSH session.
 
 When to use: first session; VPN/network unsure; after ACCESS_UNAVAILABLE.
-If reachable=false: stop; check VPN / ACCESS_HOST (gateway). Example: {}`
-            : `Probe Local → ACCESS SSH connectivity with short timeouts (≤10s). Structured JSON: reachable, latencyMs, host, port, auth.
-
-AccessTransport only (MCP client → SSH → ACCESS). Does NOT run kubectl or touch pods/hosts. Uses an ephemeral SSH session (does not sever in-flight shell_exec / copy).
-
-When to use: first session; VPN/network unsure; after ACCESS_UNAVAILABLE; before long copy/exec when connectivity may be down.
-When NOT to use: checking cluster/kubectl health (shell_exec cluster-info); pod/context ops.
-If reachable=false (code ACCESS_UNAVAILABLE): stop retrying other tools; tell user to check VPN / ACCESS_HOST (hints in message). Negative TTL may return a cached failure without re-probing.
-Example: {}`,
-        inputSchema: {},
-    }, async () => {
+When NOT to use: cluster/kubectl health (shell_exec cluster-info); pod ops.
+If reachable=false (code ACCESS_UNAVAILABLE): stop THIS YAML link (VPN / ACCESS_HOST). Other descriptions may still work. Negative TTL may return a cached failure without re-probing.
+Example: {} or {"description":"<exact link>"}`,
+        inputSchema: {
+            description: linkDescriptionField,
+        },
+    }, async ({ description }) => {
         const started = Date.now();
         try {
-            const result = await accessClient.check();
+            const session = hub.resolve({ description });
+            const result = await session.accessClient.check();
             return toToolText({ ...result });
         }
         catch (error) {
-            return toToolText(formatErrorResult(config, error, Date.now() - started));
+            return toToolText(formatErrorResult(hub.hintConfig() ?? sessionlessConfig(), error, Date.now() - started));
         }
     });
     server.registerTool("shell_exec", {
-        description: isParadi
-            ? `Run a shell command on the Paradi landing Context (TARGET host OS).
-
-Architecture: MCP → SSH(gateway, encoded user) → TARGET shell. Omit contextKey.
+        description: `Run a shell command on the selected machine.
 
-When to use: TARGET OS shell, kubectl on TARGET, local scripts on TARGET.
-When NOT to use: second-hop SSH (context_derive / ssh_exec unsupported under Paradi); inside a pod (k8s_exec).
-Example: {"command":"hostname","timeoutMs":30000}`
-            : `Run a shell command on a HostExecutionContext (default landing).
-
-Architecture: MCP client → SSH → ACCESS → shell on landing or derived Context (contextKey).
-
-When to use: kubectl cluster-info, landing scripts, or shell on a derived host via contextKey.
-When NOT to use: inside a pod (k8s_exec), derive-only probe (context_derive), pure connectivity probe (access_check).
-Prerequisites: prefer access_check if VPN/network may be down. On ACCESS_UNAVAILABLE: do not retry — ask user to fix VPN.
-Example: {"command":"kubectl get nodes","timeoutMs":30000} or {"command":"hostname","contextKey":"<from context_derive>"}`,
-        inputSchema: shellInputSchema,
-    }, async ({ command, contextKey, timeoutMs, cwd }) => handleTool(config, () => access.shellExec(command, {
+Omit host = this YAML link's landing (laptop-direct host, or the jump). Pass host = ssh hop-2 from ACCESS, or Paradi TARGET select.
+When NOT to use: inside a pod (k8s_exec), connectivity probe (access_check).
+Example: {"command":"hostname"} or {"host":"10.0.0.5","command":"hostname"}`,
+        inputSchema: {
+            command: z.string().min(1).describe("Shell command to run on the selected machine"),
+            timeoutMs: z.number().int().positive().optional().describe("Timeout in milliseconds"),
+            cwd: z.string().optional().describe("Working directory"),
+            ...select,
+        },
+    }, async ({ command, timeoutMs, cwd, description, host, user, password }) => handleMachineTool(hub, { description, host, user, password }, (session, contextKey) => session.access.shellExec(command, {
         contextKey,
-        timeoutMs: timeoutMs ?? config.defaultTimeoutMs,
+        timeoutMs: timeoutMs ?? session.config.defaultTimeoutMs,
         cwd,
     })));
-    server.registerTool("context_derive", {
-        description: isParadi
-            ? `UNAVAILABLE under ACCESS_KIND=paradi-gateway — landing Context is already TARGET. Handler throws.`
-            : `Derive a child HostExecutionContext from landing. Returns contextKey + endpoint + capabilities summary.
-
-Use the returned contextKey on shell_exec, docker_*, context_probe, remote_* target=context, and remote_copy_* target=context.
-Omit host to use TARGET_HOST when configured; useTarget=true forces default TARGET derive selector.
-Example: {"host":"10.0.0.5","user":"admin"} or {"useTarget":true}`,
-        inputSchema: isParadi
-            ? {}
-            : {
-                host: z
-                    .string()
-                    .optional()
-                    .describe(targetHostConfigured
-                    ? `Omit to use TARGET_HOST=${config.targetHost} with useTarget=true`
-                    : "Target host IP/hostname reachable FROM ACCESS"),
-                useTarget: z
-                    .boolean()
-                    .optional()
-                    .describe(targetHostConfigured
-                    ? `When true, derive TARGET_HOST=${config.targetHost}`
-                    : "When true, derive default TARGET from config (requires TARGET_HOST)"),
-                user: z
-                    .string()
-                    .optional()
-                    .describe(targetUserConfigured
-                    ? `Omit to use TARGET_USER=${config.targetUser}`
-                    : "SSH user (required unless TARGET_USER set)"),
-                password: z
-                    .string()
-                    .optional()
-                    .describe(targetPasswordConfigured
-                    ? "Omit to use TARGET_PASSWORD"
-                    : "SSH password via sshpass (or set TARGET_PASSWORD)"),
-            },
-    }, async (args) => {
-        const started = Date.now();
-        try {
-            const summary = access.deriveContext(args);
-            return toToolText({
-                success: true,
-                ...summary,
-                durationMs: Date.now() - started,
-            });
-        }
-        catch (error) {
-            return toToolText(formatErrorResult(config, error, Date.now() - started));
-        }
-    });
     server.registerTool("k8s_list_pods", {
-        description: `List pods in a namespace (kubectl on landing Context only — ${isParadi ? "TARGET" : "ACCESS"}).
-
-By design k8s_* have no contextKey. For kubectl on a derived host use shell_exec with contextKey.
-
-No capabilities.kubectl gate — kubectl failures surface via exitCode; use context_probe to check kubectl CLI presence.
+        description: `List pods in a namespace (kubectl get pods on the selected machine).
 
-When to use: discover pod names before k8s_exec, k8s_logs, or remote_* with target=pod.
-When NOT to use: running commands in a pod (k8s_exec), reading files (remote_read_file), listing processes (remote_ps), SSH to hosts (ssh_exec).
-Prerequisites: namespace from user or context.
-Example: {"namespace":"default","labelSelector":"app=web","fieldSelector":"status.phase=Running","output":"wide"}`,
+No capabilities.kubectl gate — failures surface via exitCode; use context_probe for CLI presence.
+Example: {"namespace":"default","labelSelector":"app=web","output":"wide"}`,
         inputSchema: {
             namespace: z.string().min(1),
             labelSelector: z.string().optional(),
             fieldSelector: z.string().optional(),
             output: z.enum(["wide", "json", "name"]).optional(),
             timeoutMs: z.number().int().positive().optional(),
+            ...select,
         },
-    }, async ({ namespace, labelSelector, fieldSelector, output, timeoutMs }) => handleTool(config, () => kubectl.listPods(namespace, { labelSelector, fieldSelector, output }, timeoutMs)));
+    }, async ({ namespace, labelSelector, fieldSelector, output, timeoutMs, description, host, user, password }) => handleMachineTool(hub, { description, host, user, password }, (session, contextKey) => session.kubectl.listPods(namespace, { labelSelector, fieldSelector, output }, timeoutMs, contextKey)));
     server.registerTool("k8s_exec", {
-        description: `Run a command inside a pod container (${isParadi ? "TARGET" : "ACCESS"} → kubectl exec, non-interactive).
+        description: `Run a command inside a pod container (kubectl exec on the selected machine, non-interactive).
 
-Architecture: MCP client → SSH → ${isParadi ? "TARGET" : "ACCESS"} → kubectl exec → pod. NOT local SSH to pod.
-
-When to use: run scripts, inspect env, list dirs, start processes inside a container.
-When NOT to use: file logs on disk (remote_read_file mode=tail), container stdout history (k8s_logs), host OS via SSH (ssh_exec).
-Prerequisites: namespace and pod — use k8s_list_pods first if unknown.
+When to use: scripts, env, dirs inside a container. Not file logs (remote_read_file) or container stdout history (k8s_logs).
 Example: {"namespace":"dev","pod":"web-abc","command":"ls -la /app","container":"app"}`,
         inputSchema: {
             namespace: z.string().min(1),
@@ -208,14 +173,13 @@ Example: {"namespace":"dev","pod":"web-abc","command":"ls -la /app","container":
             command: z.string().min(1),
             container: z.string().optional(),
             timeoutMs: z.number().int().positive().optional(),
+            ...select,
         },
-    }, async ({ namespace, pod, command, container, timeoutMs }) => handleTool(config, () => kubectl.exec(namespace, pod, command, container, timeoutMs)));
+    }, async ({ namespace, pod, command, container, timeoutMs, description, host, user, password }) => handleMachineTool(hub, { description, host, user, password }, (session, contextKey) => session.kubectl.exec(namespace, pod, command, container, timeoutMs, contextKey)));
     server.registerTool("k8s_logs", {
-        description: `Fetch pod container stdout/stderr (${isParadi ? "TARGET" : "ACCESS"} → kubectl logs).
+        description: `Fetch pod container stdout/stderr (kubectl logs on the selected machine).
 
-When to use: process output captured by container runtime logging.
-When NOT to use: log files on disk (remote_read_file mode=tail). Often empty for sshd-only idle pods.
-Prerequisites: namespace and pod name.
+When to use: container runtime logs. Not log files on disk (remote_read_file). Often empty for sshd-only idle pods.
 Example: {"namespace":"dev","pod":"web-abc","tail":200,"since":"1h"}`,
         inputSchema: {
             namespace: z.string().min(1),
@@ -224,97 +188,28 @@ Example: {"namespace":"dev","pod":"web-abc","tail":200,"since":"1h"}`,
             tail: z.number().int().positive().optional(),
             since: z.string().optional(),
             timeoutMs: z.number().int().positive().optional(),
+            ...select,
         },
-    }, async ({ namespace, pod, container, tail, since, timeoutMs }) => handleTool(config, () => kubectl.logs(namespace, pod, { container, tail, since }, timeoutMs)));
-    server.registerTool("ssh_exec", {
-        description: isParadi
-            ? `UNAVAILABLE under ACCESS_KIND=paradi-gateway — landing Context is already TARGET. Use shell_exec for TARGET shell, docker_* (omit contextKey), or k8s_* for pods. Handler errors if called.`
-            : `Shortcut: context_derive + shell_exec on a remote host (ACCESS → ssh/sshpass → host).
-
-IMPORTANT: NOT SSH from the laptop. MCP → ACCESS; ACCESS derives and shells to the host.
-Returns reusable contextKey + standard command result fields (exitCode, stdout, etc.). Prefer this for derive+shell in one call; reuse contextKey for follow-up shell_exec / docker_* / remote_* target=context.
-
-When to use: host IP/node when kubectl exec is not appropriate; omit host to use TARGET_HOST when configured.
-When NOT to use: inside a pod (k8s_exec); ACCESS_KIND=paradi-gateway (unsupported — handler throws).
-Example: {"host":"10.0.0.5","command":"hostname"} or {"command":"hostname"} with TARGET_HOST set`,
-        inputSchema: {
-            host: z
-                .string()
-                .optional()
-                .describe(isParadi
-                ? "UNAVAILABLE under paradi-gateway"
-                : targetHostConfigured
-                    ? `Omit to use TARGET_HOST=${config.targetHost}`
-                    : "Target host IP/hostname reachable FROM ACCESS (required unless TARGET_HOST set)"),
-            command: z.string().min(1),
-            user: z
-                .string()
-                .optional()
-                .describe(isParadi
-                ? "UNAVAILABLE under paradi-gateway"
-                : targetUserConfigured
-                    ? `Omit to use TARGET_USER=${config.targetUser}`
-                    : "SSH user (required unless TARGET_USER set)"),
-            password: z
-                .string()
-                .optional()
-                .describe(isParadi
-                ? "UNAVAILABLE under paradi-gateway"
-                : targetPasswordConfigured
-                    ? "Omit to use TARGET_PASSWORD"
-                    : "SSH password via sshpass (or set TARGET_PASSWORD)"),
-            timeoutMs: z.number().int().positive().optional(),
-        },
-    }, async ({ host, command, user, password, timeoutMs }) => {
-        const started = Date.now();
-        try {
-            const raw = await access.sshExec({
-                host,
-                command,
-                user,
-                password,
-                timeoutMs: timeoutMs ?? config.defaultTimeoutMs,
-            });
-            const mergedStdout = [raw.stdout, raw.stderr].filter(Boolean).join("\n");
-            const base = formatCommandResult(config, {
-                stdout: mergedStdout,
-                stderr: "",
-                exitCode: raw.exitCode,
-                durationMs: raw.durationMs ?? Date.now() - started,
-            });
-            return toToolText({
-                ...base,
-                contextKey: raw.contextKey,
-                endpoint: raw.endpoint,
-            });
-        }
-        catch (error) {
-            return toToolText(formatErrorResult(config, error, Date.now() - started));
-        }
-    });
-    const withOptionalContextKey = (fields) => contextKeyField ? { ...fields, contextKey: contextKeyField } : fields;
+    }, async ({ namespace, pod, container, tail, since, timeoutMs, description, host, user, password }) => handleMachineTool(hub, { description, host, user, password }, (session, contextKey) => session.kubectl.logs(namespace, pod, { container, tail, since }, timeoutMs, contextKey)));
     server.registerTool("context_probe", {
-        description: isParadi
-            ? `Probe TARGET landing capabilities (docker/kubectl CLI). SSH success ≠ docker/kubectl.
-Example: {}`
-            : `Probe Context capabilities (docker/kubectl CLI presence). SSH success does NOT imply docker/kubectl.
+        description: `Probe docker/kubectl CLI on the selected machine. SSH success ≠ docker/kubectl.
 
-Returns capabilities tri-state: true | false | unknown. Prefer this (or let docker_* auto-probe) before assuming docker.
-Default Context = landing; pass contextKey to probe a derived host.
-Example: {} or {"contextKey":"<from context_derive>"}`,
-        inputSchema: withOptionalContextKey({
+Returns true | false | unknown. Prefer this (or let docker_* auto-probe) before assuming docker.
+Example: {} or {"host":"10.0.0.5"}`,
+        inputSchema: {
             timeoutMs: z.number().int().positive().optional().describe("Timeout in milliseconds"),
-        }),
-    }, async ({ contextKey, timeoutMs }) => {
+            ...select,
+        },
+    }, async ({ timeoutMs, description, host, user, password }) => {
         const started = Date.now();
         try {
-            const result = await access.probe({
+            const { session, contextKey } = openMachine(hub, { description, host, user, password });
+            const result = await session.access.probe({
                 contextKey,
-                timeoutMs: timeoutMs ?? config.defaultTimeoutMs,
+                timeoutMs: timeoutMs ?? session.config.defaultTimeoutMs,
             });
             return toToolText({
                 success: true,
-                contextKey: result.contextKey,
                 endpoint: result.endpoint,
                 capabilities: result.capabilities,
                 durationMs: Date.now() - started,
@@ -322,120 +217,81 @@ Example: {} or {"contextKey":"<from context_derive>"}`,
             });
         }
         catch (error) {
-            return toToolText(formatErrorResult(config, error, Date.now() - started));
+            return toToolText(formatErrorResult(hub.hintConfig() ?? sessionlessConfig(), error, Date.now() - started));
         }
     });
     server.registerTool("docker_ps", {
-        description: isParadi
-            ? `List Docker containers on TARGET landing (Runtime via SessionPool). Auto-probes docker.
-Example: {"all":true}`
-            : `List Docker containers on a HostExecutionContext (landing or derived via contextKey).
-
-Runtime only — uses SessionPool; does not create SSH. Auto-probes capabilities.docker if unknown; fails if false.
-Example: {"all":true} or {"contextKey":"<from context_derive>","all":true}`,
-        inputSchema: withOptionalContextKey({
+        description: `List Docker containers on the selected machine (auto-probes docker).
+Example: {"all":true} or {"host":"10.0.0.5","all":true}`,
+        inputSchema: {
             timeoutMs: z.number().int().positive().optional().describe("Timeout in milliseconds"),
             all: z.boolean().optional().describe("Include stopped containers (-a)"),
             quiet: z.boolean().optional().describe("Only container IDs (-q)"),
             filter: z.string().optional().describe("docker ps --filter value"),
-        }),
-    }, async ({ contextKey, timeoutMs, all, quiet, filter, }) => handleTool(config, () => access.dockerPs({
+            ...select,
+        },
+    }, async ({ timeoutMs, all, quiet, filter, description, host, user, password }) => handleMachineTool(hub, { description, host, user, password }, (session, contextKey) => session.access.dockerPs({
         contextKey,
         all,
         quiet,
         filter,
-        timeoutMs: timeoutMs ?? config.defaultTimeoutMs,
+        timeoutMs: timeoutMs ?? session.config.defaultTimeoutMs,
     })));
     server.registerTool("docker_exec", {
-        description: isParadi
-            ? `Run a command inside a Docker container on TARGET landing (docker exec → bash -lc). Not kubectl exec. Auto-probes docker.
-Example: {"container":"musa-starvla","command":"nvidia-smi"}`
-            : `Run a command inside a Docker container on landing or derived Context (docker exec → bash -lc).
-
-Not kubectl exec (use k8s_exec for pods). Auto-probes docker capability.
-Example: {"container":"musa-starvla","command":"nvidia-smi"} or {"contextKey":"<key>","container":"c1","command":"pwd"}`,
-        inputSchema: withOptionalContextKey({
+        description: `Run a command inside a Docker container (docker exec → bash -lc). Not kubectl exec.
+Example: {"container":"app","command":"pwd"} or {"host":"10.0.0.5","container":"c1","command":"pwd"}`,
+        inputSchema: {
             container: z.string().min(1).describe("Container name or ID"),
             command: z.string().min(1).describe("Command run via bash -lc inside the container"),
             workdir: z.string().optional().describe("docker exec -w"),
             timeoutMs: z.number().int().positive().optional().describe("Timeout in milliseconds"),
-        }),
-    }, async ({ container, command, workdir, contextKey, timeoutMs, }) => handleTool(config, () => access.dockerExec({
+            ...select,
+        },
+    }, async ({ container, command, workdir, timeoutMs, description, host, user, password }) => handleMachineTool(hub, { description, host, user, password }, (session, contextKey) => session.access.dockerExec({
         container,
         command,
         workdir,
         contextKey,
-        timeoutMs: timeoutMs ?? config.defaultTimeoutMs,
+        timeoutMs: timeoutMs ?? session.config.defaultTimeoutMs,
     })));
     server.registerTool("docker_logs", {
-        description: isParadi
-            ? `Fetch Docker container logs on TARGET landing (docker logs). For k8s pod logs use k8s_logs. Auto-probes docker.
-Example: {"container":"musa-starvla","tail":200}`
-            : `Fetch Docker container logs (docker logs) on landing or derived Context.
-
-For k8s pod logs use k8s_logs. Auto-probes docker capability.
-Example: {"container":"musa-starvla","tail":200}`,
-        inputSchema: withOptionalContextKey({
+        description: `Fetch Docker container logs on the selected machine. For k8s pod logs use k8s_logs.
+Example: {"container":"app","tail":200}`,
+        inputSchema: {
             container: z.string().min(1),
             tail: z.number().int().positive().optional().describe("Default 200"),
             since: z.string().optional().describe("docker logs --since"),
             timestamps: z.boolean().optional(),
             timeoutMs: z.number().int().positive().optional().describe("Timeout in milliseconds"),
-        }),
-    }, async ({ container, tail, since, timestamps, contextKey, timeoutMs, }) => handleTool(config, () => access.dockerLogs({
+            ...select,
+        },
+    }, async ({ container, tail, since, timestamps, timeoutMs, description, host, user, password }) => handleMachineTool(hub, { description, host, user, password }, (session, contextKey) => session.access.dockerLogs({
         container,
         tail,
         since,
         timestamps,
         contextKey,
-        timeoutMs: timeoutMs ?? config.defaultTimeoutMs,
+        timeoutMs: timeoutMs ?? session.config.defaultTimeoutMs,
     })));
     server.registerTool("remote_read_file", {
-        description: isParadi
-            ? `Read a file on TARGET landing (target=landing) or in a pod (target=pod).
-
-Schema rejects target=context under Paradi — use target=landing for OS files.
-Use mode=head|tail. Limits: MAX_OUTPUT_CHARS. For transfer use remote_copy_file.
-Example: {"target":"landing","path":"/var/log/app.log","mode":"tail","lines":100}`
-            : `Read a file on landing, in a pod, or on a derived Context (target=context).
-
-Use target to select path: landing=shell, pod=kubectl exec, context=derived shell (contextKey required).
-Use mode to read from start or end of file:
-- mode=head (default): first N lines; default lines=500; supports offset for pagination
-- mode=tail: last N lines; default lines=200; supports grep filter
-
-Limits: MAX_OUTPUT_CHARS env (default 65536) may truncate response; check truncatedByChars.
-Response includes totalLines/totalBytes/truncatedByLines. For file transfer use remote_copy_file.
+        description: `Read a file on the selected machine (description + optional host). Add namespace+pod to read inside a container via kubectl on that machine.
 
+mode=head (default, lines=500, offset) or mode=tail (lines=200, grep).
 When NOT to use: container stdout (k8s_logs); copying files (remote_copy_file).
-Example (head): {"target":"pod","namespace":"dev","pod":"web","path":"/app/main.py","mode":"head","lines":2000}
-Example (context): {"target":"context","contextKey":"<key>","path":"/etc/hostname"}`,
+Example: {"path":"/etc/hostname"} or {"host":"10.0.0.5","path":"/var/log/app.log","mode":"tail"}`,
         inputSchema: remoteReadFileSchema,
-    }, async (args) => handleRemoteReadFile(config, remote, args));
+    }, async (args) => handleRemoteReadFile(hub, args));
     server.registerTool("remote_copy_file", {
-        description: isParadi
-            ? `Synchronous copy between local, landing (=TARGET), or pod. Schema rejects target=context under Paradi.
-
-local↔landing uses SFTP (declared degraded — prefer smaller transfers / remote_copy_start; expect retries).
-Example: {"source":{"target":"local","path":"C:/tmp/a.bin"},"dest":{"target":"landing","path":"/tmp/a.bin"}}`
-            : `Synchronous copy of a file or directory between local, landing, pod, or context.
-
-Always waits for completion and returns success/bytes/transferId — does NOT start a background job.
-- local↔landing: independent SFTP (ssh2-sftp-client); files and directories (directory = walk + per-file)
-- landing/pod/context (context materializes before copy): kubectl cp, scp, cp on landing
+        description: `Synchronous copy. Endpoints: target=local (MCP machine), target=remote (selected Linux), target=pod (kubectl on that Linux).
 
-skipIfComplete: gate strength = verify (default size=cheap; size+sha256=content). verify=none + skip is rejected. Verify fail → rewrite (not throw-only).
-Set totalTimeoutMs (or timeoutMs alias). Progress via notifications/progress when client provides progressToken.
-
-When to use: short/medium sync copies that fit the MCP call timeout.
-When NOT to use: long/large copies — call remote_copy_start (async) then remote_copy_status (size>256MB or ETA>2min). Do not expect remote_copy_file to auto-async.
-Example (file): {"source":{"target":"local","path":"C:/tmp/a.bin"},"dest":{"target":"landing","path":"/tmp/a.bin"}}
-Example (context): {"source":{"target":"context","contextKey":"<key>","path":"/data/a.bin"},"dest":{"target":"local","path":"C:/data/a.bin"}}`,
+Select the Linux with description + optional host (same as shell_exec). Paradi: no hop-2.
+Large/long copies: remote_copy_start, not this tool.
+Example: {"source":{"target":"remote","path":"/etc/hostname"},"dest":{"target":"local","path":"C:/tmp/hostname"}}`,
         inputSchema: remoteCopyFileSchema,
     }, async (args, extra) => {
         const started = Date.now();
         try {
-            const { source, dest } = resolveCopyEndpoints(access, config, args);
+            const { session, source, dest } = resolveCopyEndpoints(hub, args);
             const progressToken = extra._meta?.progressToken;
             const onProgress = (progress) => {
                 if (progressToken === undefined) {
@@ -452,7 +308,7 @@ Example (context): {"source":{"target":"context","contextKey":"<key>","path":"/d
                 })
                     .catch(() => undefined);
             };
-            const result = await executeRemoteCopy({ accessClient, config }, source, dest, {
+            const result = await executeRemoteCopy({ accessClient: session.accessClient, config: session.config }, source, dest, {
                 recursive: args.recursive ?? true,
                 timeoutMs: args.timeoutMs,
                 skipIfComplete: args.skipIfComplete,
@@ -479,27 +335,20 @@ Example (context): {"source":{"target":"context","contextKey":"<key>","path":"/d
             }));
         }
         catch (error) {
-            return toToolText(formatErrorResult(config, error, Date.now() - started));
+            return toToolText(formatErrorResult(hub.hintConfig() ?? sessionlessConfig(), error, Date.now() - started));
         }
     });
     server.registerTool("remote_copy_start", {
-        description: isParadi
-            ? `Start an async copy job and return transferId immediately. Same rules as remote_copy_file under Paradi: landing=TARGET; schema rejects target=context. SFTP degraded — prefer this for large transfers.
-Example: {"source":{"target":"landing","path":"/tmp/big.pt"},"dest":{"target":"local","path":"C:/data/big.pt"},"skipIfComplete":true,"totalTimeoutMs":7200000}`
-            : `Start an async file/directory copy job (same path engine as remote_copy_file) and return immediately with transferId.
+        description: `Start an async copy job (same rules as remote_copy_file) and return transferId immediately.
 
-This is the async primitive — remote_copy_file never auto-promotes to a job.
-Job state: ~/.agent-compose/remote-copy/jobs/<transferId>.json
-Poll remote_copy_status; cancel with remote_copy_cancel.
-Prefer when size>256MB or ETA>2min. Supports skipIfComplete/verify/totalTimeoutMs.
-Terminal statuses: success|failed|cancelled|timeout.
-Example: {"source":{"target":"landing","path":"/tmp/big.pt"},"dest":{"target":"local","path":"C:/data/big.pt"},"skipIfComplete":true,"totalTimeoutMs":7200000}`,
+Prefer when size>256MB or ETA>2min. Poll remote_copy_status; cancel with remote_copy_cancel.
+Example: {"source":{"target":"remote","path":"/tmp/big.pt"},"dest":{"target":"local","path":"C:/data/big.pt"},"skipIfComplete":true,"totalTimeoutMs":7200000}`,
         inputSchema: remoteCopyStartSchema,
     }, async (args) => {
         const started = Date.now();
         try {
-            const { source, dest } = resolveCopyEndpoints(access, config, args);
-            const result = await copyJobs.start({
+            const { session, source, dest } = resolveCopyEndpoints(hub, args);
+            const result = await hub.copyStart(session, {
                 source,
                 dest,
                 recursive: args.recursive,
@@ -512,7 +361,7 @@ Example: {"source":{"target":"landing","path":"/tmp/big.pt"},"dest":{"target":"l
             return toToolText(result);
         }
         catch (error) {
-            return toToolText(formatErrorResult(config, error, Date.now() - started));
+            return toToolText(formatErrorResult(hub.hintConfig() ?? sessionlessConfig(), error, Date.now() - started));
         }
     });
     server.registerTool("remote_copy_status", {
@@ -524,47 +373,41 @@ Example: {"transferId":"copy-xxx"}`,
     }, async (args) => {
         const started = Date.now();
         try {
-            const result = await copyJobs.status(args.transferId);
+            const result = await hub.copyStatus(args.transferId);
             return toToolText(result);
         }
         catch (error) {
-            return toToolText(formatErrorResult(config, error, Date.now() - started));
+            return toToolText(formatErrorResult(hub.hintConfig() ?? sessionlessConfig(), error, Date.now() - started));
         }
     });
     server.registerTool("remote_copy_cancel", {
         description: `Cancel a running/queued async copy job by transferId.
 
-Aborts the in-process worker: local↔landing SFTP sessions end promptly; kubectl cp / scp on landing is best-effort (abort checked between hops).
+Aborts the in-process worker: local↔remote SFTP sessions end promptly; kubectl cp / scp on landing is best-effort.
 Already-finished jobs are left unchanged (terminal status is fenced).
 Example: {"transferId":"copy-xxx"}`,
         inputSchema: remoteCopyCancelSchema,
     }, async (args) => {
         const started = Date.now();
         try {
-            const result = await copyJobs.cancel(args.transferId);
+            const result = await hub.copyCancel(args.transferId);
             return toToolText(result);
         }
         catch (error) {
-            return toToolText(formatErrorResult(config, error, Date.now() - started));
+            return toToolText(formatErrorResult(hub.hintConfig() ?? sessionlessConfig(), error, Date.now() - started));
         }
     });
     server.registerTool("remote_ps", {
-        description: isParadi
-            ? `List processes on TARGET landing (target=landing) or in a pod (target=pod).
-Example: {"target":"landing","pattern":"python"}`
-            : `List processes on landing, in a pod, or on a derived Context (ps aux | grep).
-
-When NOT to use: reading log files (remote_read_file).
-Example (pod): {"target":"pod","namespace":"dev","pod":"train-0","pattern":"python"}
-Example (context): {"target":"context","contextKey":"<key>","pattern":"nginx"}`,
+        description: `List processes on the selected machine (description + optional host). Add namespace+pod to list inside a container.
+Example: {"pattern":"sshd"} or {"host":"10.0.0.5","pattern":"python"}`,
         inputSchema: remotePsSchema,
-    }, async (args) => handleTool(config, async () => {
+    }, async (args) => handleMachineTool(hub, args, async (session, contextKey) => {
         const command = buildPsCommand(args.pattern);
-        return remote.runOnTarget(remoteInputToTarget(args), command, args.timeoutMs);
+        return session.remote.runOnTarget(runTargetFromArgs(contextKey, args), command, args.timeoutMs);
     }));
 }
 export function registerPrompts(server) {
-    server.prompt("tool-selection", "Recommend the best host-execution-mcp tool for a scenario (all ops go via ACCESS landing Context)", {
+    server.prompt("tool-selection", "Recommend the best host-execution-mcp tool for a scenario (all ops go via ACCESS landing, optional host for hop-2)", {
         scenario: z.string().describe("Description of what the user wants to do remotely"),
     }, async ({ scenario }) => ({
         messages: [
@@ -573,11 +416,11 @@ export function registerPrompts(server) {
                 content: {
                     type: "text",
                     text: `Analyze the user's remote operation scenario and respond with:
-1. Recommended tool (access_check | context_derive | context_probe | shell_exec | k8s_list_pods | k8s_exec | ssh_exec | docker_ps | docker_exec | docker_logs | k8s_logs | remote_read_file | remote_copy_file | remote_copy_start | remote_copy_status | remote_copy_cancel | remote_ps)
-2. Why this tool fits (remember: MCP → ACCESS → Context; ssh_exec is ACCESS SSH derive, NOT local SSH; large copies — remote_copy_start; VPN/network unsure — access_check first)
+1. Recommended tool (access_check | context_probe | shell_exec | k8s_list_pods | k8s_exec | docker_ps | docker_exec | docker_logs | k8s_logs | remote_read_file | remote_copy_file | remote_copy_start | remote_copy_status | remote_copy_cancel | remote_ps)
+2. Why this tool fits (MCP → ACCESS landing; pass host only for hop-2 / Paradi TARGET select; large copies — remote_copy_start; VPN/network unsure — access_check first)
 3. The first MCP tool call (JSON arguments only)
 
-If VPN/connectivity may be down, recommend access_check first. Use k8s_list_pods when pod name is unknown. Use context_derive before target=context or contextKey tools. Prefer k8s_exec over ssh_exec for pod/container access.
+If VPN/connectivity may be down, recommend access_check first. Use k8s_list_pods when pod name is unknown. Prefer k8s_exec for pod/container access.
 
 Scenario: ${scenario}`,
                 },
@@ -603,8 +446,8 @@ Log path: ${log_path ?? "(ask user if needed)"}
 Process pattern: ${pattern ?? "(optional)"}
 
 Steps:
-1. Verify connectivity (access_check); if unreachable stop and report VPN/ACCESS_HOST
-2. Verify cluster (shell_exec kubectl cluster-info)
+1. Verify connectivity (access_check); if this link is unreachable, stop that link and report VPN/ACCESS_HOST
+2. Verify cluster (shell_exec kubectl cluster-info) when kubectl is needed
 3. List pods if needed (k8s_list_pods)
 4. Read or tail files (remote_read_file); copy files (remote_copy_file or remote_copy_start for large)
 5. Check processes (remote_ps)