cloudgpu-mcp 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CloudGPU
+
+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

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# CloudGPU MCP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[CloudGPU](https://cloudgpu.app) MCP server: let an AI agent rent a GPU by the minute, run a job, bring the results back and shut the GPU down. The same API key and balance also cover CloudGPU's OpenAI-compatible model API, so an agent can call a hosted model without renting anything.
+
+> "Fine-tune a 7B base model with LoRA on data/train.jsonl and put the adapter in ./outputs."
+
+The agent checks live prices and quotes you, rents the GPU once you say yes, uploads your code and data, starts training in the background, watches the logs, downloads the adapter and destroys the instance. You get the files and the final cost.
+
+It is a local (stdio) MCP server. It works with any MCP client that can start one: Claude Code, Cursor, Cline, opencode, goose, VS Code, Windsurf and others.
+
+## Install
+
+1. Create an API key at [cloudgpu.app/api](https://cloudgpu.app/api) and add a prepaid balance (card or USDT).
+2. Add the server to your client. Node.js 18 or newer is required. The key goes in the environment variable `CLOUDGPU_API_KEY`.
+
+<details open>
+<summary><b>Claude Code</b></summary>
+
+```bash
+claude mcp add cloudgpu --env CLOUDGPU_API_KEY=cgw-sk-... -- npx -y cloudgpu-mcp
+```
+</details>
+
+<details>
+<summary><b>Cursor</b> (<code>~/.cursor/mcp.json</code> or <code>.cursor/mcp.json</code>)</summary>
+
+```json
+{
+  "mcpServers": {
+    "cloudgpu": {
+      "command": "npx",
+      "args": ["-y", "cloudgpu-mcp"],
+      "env": { "CLOUDGPU_API_KEY": "cgw-sk-..." }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>Cline</b> (MCP Servers → Configure MCP Servers → <code>cline_mcp_settings.json</code>)</summary>
+
+```json
+{
+  "mcpServers": {
+    "cloudgpu": {
+      "command": "npx",
+      "args": ["-y", "cloudgpu-mcp"],
+      "env": { "CLOUDGPU_API_KEY": "cgw-sk-..." }
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>opencode</b> (<code>opencode.json</code>)</summary>
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "cloudgpu": {
+      "type": "local",
+      "command": ["npx", "-y", "cloudgpu-mcp"],
+      "environment": { "CLOUDGPU_API_KEY": "cgw-sk-..." },
+      "enabled": true
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary><b>goose</b> (<code>~/.config/goose/config.yaml</code>, or <code>goose configure</code> → Add Extension → Command-line Extension)</summary>
+
+```yaml
+extensions:
+  cloudgpu:
+    name: cloudgpu
+    type: stdio
+    cmd: npx
+    args: ["-y", "cloudgpu-mcp"]
+    envs:
+      CLOUDGPU_API_KEY: "cgw-sk-..."
+    enabled: true
+    timeout: 300
+```
+</details>
+
+3. Optional but recommended: copy [`rules/cloudgpu.md`](rules/cloudgpu.md) into your project as `AGENTS.md`, `.cursor/rules/cloudgpu.md` or `.clinerules/cloudgpu.md`. It tells the agent to quote before renting, download before shutting down, and never leave a GPU running. The server also exposes the same text as the resource `cloudgpu://rules`.
+
+To check the install, ask your agent: "List the GPUs available, then estimate the cost for a 24 GB GPU for one hour. Do not create anything." You should see `list_gpus` and `estimate_cost` calls and a quote, and nothing is rented.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `get_account` | Balance, and how many instances the account may run at once |
+| `list_gpus` | GPU models with VRAM, live price per GPU-hour and availability |
+| `list_templates` | Ready-made images: JupyterLab, Ollama, ComfyUI, LLaMA-Factory, … |
+| `estimate_cost` | Live quote for a GPU and a number of hours, plus your balance afterwards; returns a `quote_id` |
+| `create_instance` | Rents from an approved quote, with a budget, a time limit and an idle limit |
+| `get_status` / `list_instances` | Status, minutes run, cost so far, auto-shutdown limits |
+| `run_command` | Runs a command on the instance; `background=true` for long jobs |
+| `tail_logs` | Latest log lines, whether the job finished, GPU utilisation |
+| `upload` / `download` | Files and folders between your computer and the instance (SFTP) |
+| `stop_instance` | Destroys the instance and stops billing |
+| `list_models` | Models on the OpenAI-compatible API, for inference without renting a GPU |
+
+The server also provides a `train_on_cloudgpu` prompt.
+
+## Guardrails
+
+- **A quote first.** `create_instance` only takes a `quote_id` from `estimate_cost` and `user_confirmed=true`.
+- **Server-side limits.** Every instance is created with `max_spend_usd`, `max_hours` and an idle limit (60 minutes by default). CloudGPU's servers check them and destroy the instance when one is hit, even if your client has disconnected or your laptop is asleep.
+- **Your own ceiling.** `CLOUDGPU_MAX_SPEND_USD` and `CLOUDGPU_MAX_HOURS` cap what the agent may set.
+- **Results before shutdown.** After commands have run, `stop_instance` refuses until something has been downloaded, unless the user confirms `force=true`.
+- **Secrets stay out of the chat.** The instance's SSH login is used inside this process and never returned to the model. Tool output is scrubbed of the API key and login details. Uploading `.ssh`, `.env`, key files or your whole home directory needs `allow_sensitive=true`.
+- **The instance stays manageable.** Commands that change the root password, SSH configuration, firewall or the platform's monitoring agent are refused. CloudGPU shuts down instances that it can no longer monitor.
+- **Read-only mode.** `CLOUDGPU_READ_ONLY=1` registers only the look-up tools.
+
+## Configuration
+
+| Env | Default | |
+|---|---|---|
+| `CLOUDGPU_API_KEY` | (required) | From https://cloudgpu.app/api |
+| `CLOUDGPU_MAX_SPEND_USD` | `50` | Highest budget the agent may set for one instance |
+| `CLOUDGPU_MAX_HOURS` | `24` | Longest time limit the agent may set |
+| `CLOUDGPU_READ_ONLY` | off | `1` = look-up tools only |
+| `CLOUDGPU_BASE_URL` | `https://cloudgpu.app` | Override the API host |
+
+## Model API on the same balance
+
+The key also works with the OpenAI-compatible API at `https://cloudgpu.app/v1`. Call `list_models` (or `GET /v1/models`) to see the available model IDs. Model prices are on [cloudgpu.app/api](https://cloudgpu.app/api).
+
+## Without MCP
+
+The server wraps CloudGPU's public REST API, which any agent or script can call with the same key:
+
+```bash
+curl https://cloudgpu.app/v1/gpu/offers -H "Authorization: Bearer $CLOUDGPU_API_KEY"
+```
+
+## Links
+
+- MCP docs: https://cloudgpu.app/docs/mcp
+- GPU pricing: https://cloudgpu.app/pricing
+- Model API and prices: https://cloudgpu.app/api
+- API reference: https://cloudgpu.app/api/docs · OpenAPI: https://cloudgpu.app/openapi.json · For LLMs: https://cloudgpu.app/llms.txt
+
+CloudGPU here means cloudgpu.app. Prepaid balance, billed per minute; when the balance runs out, running instances are destroyed and their disks erased, so keep enough balance for the job and download results as you go.
+
+## Development
+
+```bash
+npm install
+npm test
+node src/index.js   # stdio server; set CLOUDGPU_API_KEY first
+```
+
+## License
+
+MIT, see [LICENSE](LICENSE).

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "cloudgpu-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "mcpName": "io.github.mrhy7176/cloudgpu-mcp",
+  "description": "MCP server for cloudgpu.app: let Claude Code, Cursor, Cline, opencode, goose and other MCP clients rent a GPU per minute, run a job, fetch the results and shut it down, with spending limits the platform enforces.",
+  "type": "module",
+  "bin": {
+    "cloudgpu-mcp": "src/index.js"
+  },
+  "main": "src/index.js",
+  "files": [
+    "src",
+    "rules",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "gpu",
+    "cloud-gpu",
+    "gpu-rental",
+    "model-api",
+    "ai-agent",
+    "claude-code",
+    "cursor",
+    "cline",
+    "opencode",
+    "goose",
+    "fine-tuning",
+    "cloudgpu"
+  ],
+  "homepage": "https://cloudgpu.app/docs/mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrhy7176/cloudgpu-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mrhy7176/cloudgpu-mcp/issues"
+  },
+  "license": "MIT",
+  "author": "CloudGPU <support@cloudgpu.app>",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "ssh2": "^1.17.0",
+    "zod": "^3.25.0"
+  }
+}

package/rules/cloudgpu.md

@@ -0,0 +1,45 @@
+# CloudGPU rules for AI assistants
+
+Use these rules whenever you rent or use a GPU on CloudGPU (cloudgpu.app) through the `cloudgpu` MCP tools.
+Copy this file into your project as `AGENTS.md`, `.cursor/rules/cloudgpu.md` or `.clinerules/cloudgpu.md`, or wherever your assistant reads project instructions.
+
+## Before renting
+
+1. Call `get_account` and `list_gpus`. Pick a GPU with enough VRAM for the job, and don't rent more GPU than the job needs. As a rough guide, LoRA on a 7–8B model fits in 24 GB, and a full fine-tune of the same model needs 80 GB or more.
+2. Call `estimate_cost` with a realistic number of hours.
+3. Show the user a short quote before you rent anything:
+   - the GPU and how many,
+   - the price per hour,
+   - the estimated hours and cost,
+   - the budget and time limit you will set,
+   - their balance after the job.
+4. Rent only after the user says yes. Pass `user_confirmed=true` only in that case.
+
+## Renting
+
+- Always set `max_spend_usd` and `max_hours`. CloudGPU's servers destroy the instance when either is reached, even if you have disconnected.
+- Keep `idle_minutes` on (default 60). Raise it if setup will take long, because installing packages and downloading models leave the GPU idle.
+- Call `get_status` at intervals, not in a tight loop, until the instance is `running`.
+- `failed` instances are not charged. Tell the user, then offer another GPU.
+
+## Working on the instance
+
+- Put code and data on the instance with `upload`. Do not upload credentials.
+- Use `run_command` for short steps. For training, long installs or big downloads, use `background=true` and follow progress with `tail_logs`.
+- Instances come with Python and CUDA, but not always PyTorch. Check first: `nvidia-smi -L` and `python -c "import torch; print(torch.__version__, torch.cuda.is_available())"`.
+- If PyTorch is missing, plain `pip install torch` installs a current CUDA build. It is a few GB, so run it with `background=true`. Index URLs for older CUDA versions (for example `.../whl/cu124`) may have no wheel for the machine's Python, which can be as new as 3.14. Only use them if the project needs that CUDA version, and then create an environment with an older Python first (`conda create -y -n work python=3.12`, then `conda activate work && ...` in each command).
+- If `nvidia-smi` shows no GPU once the instance is running, stop and tell the user. CloudGPU detects such machines, shuts them down and refunds them automatically.
+- **Do not** change the root password, edit the SSH configuration, change the firewall, or stop the platform's monitoring agent (`cgpu-*` processes). The platform must keep its access to the instance; if that access is lost, the platform shuts the instance down. The MCP server refuses such commands.
+- Never use the GPU for cryptocurrency mining or anything the [acceptable use policy](https://cloudgpu.app/aup) forbids. Instances that do so are shut down.
+
+## Finishing (always)
+
+1. Download every result: model weights, adapters, checkpoints, logs, metrics. Destroying an instance erases its disk, and CloudGPU has no persistent storage.
+2. Call `stop_instance`.
+3. Tell the user what ran, where the results are on their computer, and the final cost from `stop_instance`.
+
+If anything goes wrong mid-way, do not leave the instance running. Download whatever exists, stop the instance, then explain what happened.
+
+## Only need a model, not a GPU?
+
+The same API key works for CloudGPU's OpenAI-compatible model API at `https://cloudgpu.app/v1`. Call `list_models` to see the models. If you only need inference on a hosted model, use the API instead of renting a GPU.

package/src/api.js

@@ -0,0 +1,99 @@
+// CloudGPU REST client. Talks only to the public API (https://cloudgpu.app/v1/...),
+// with the user's own API key. Nothing here knows or needs anything that is not public.
+
+export class ApiError extends Error {
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export class CloudGpuApi {
+  constructor({ apiKey, baseUrl = "https://cloudgpu.app", fetchImpl = globalThis.fetch } = {}) {
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.fetch = fetchImpl;
+  }
+
+  async request(method, path, body) {
+    if (!this.apiKey) {
+      throw new ApiError(
+        401,
+        "missing_api_key",
+        "CLOUDGPU_API_KEY is not set. Create a key at https://cloudgpu.app/api and add it to this MCP server's env.",
+      );
+    }
+    let lastErr;
+    // Retry only on network errors and 502/503/504; never on 4xx (a create must not run twice).
+    const attempts = method === "GET" ? 3 : 1;
+    for (let i = 0; i < attempts; i++) {
+      try {
+        const res = await this.fetch(this.baseUrl + path, {
+          method,
+          headers: {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+            "User-Agent": "cloudgpu-mcp/0.1",
+          },
+          body: body === undefined ? undefined : JSON.stringify(body),
+        });
+        const text = await res.text();
+        let json;
+        try {
+          json = text ? JSON.parse(text) : {};
+        } catch {
+          json = null;
+        }
+        if (!res.ok) {
+          const e = json && json.error ? json.error : {};
+          const err = new ApiError(res.status, e.code || `http_${res.status}`, e.message || `HTTP ${res.status}`);
+          if (method === "GET" && res.status >= 502 && res.status <= 504 && i < attempts - 1) {
+            lastErr = err;
+            await sleep(1000 * (i + 1));
+            continue;
+          }
+          throw err;
+        }
+        if (json === null) {
+          throw new ApiError(res.status, "bad_response", "The server returned something that is not JSON.");
+        }
+        return json;
+      } catch (err) {
+        if (err instanceof ApiError) throw err;
+        lastErr = new ApiError(0, "network_error", `Could not reach ${this.baseUrl}: ${err.message}`);
+        if (i < attempts - 1) await sleep(1000 * (i + 1));
+      }
+    }
+    throw lastErr;
+  }
+
+  account() {
+    return this.request("GET", "/v1/gpu/account");
+  }
+  offers() {
+    return this.request("GET", "/v1/gpu/offers").then((r) => r.data || []);
+  }
+  templates() {
+    return this.request("GET", "/v1/gpu/templates").then((r) => r.data || []);
+  }
+  instances() {
+    return this.request("GET", "/v1/gpu/instances").then((r) => r.data || []);
+  }
+  instance(id) {
+    return this.request("GET", `/v1/gpu/instances/${encodeURIComponent(id)}`);
+  }
+  create(body) {
+    return this.request("POST", "/v1/gpu/instances", body);
+  }
+  destroy(id) {
+    return this.request("DELETE", `/v1/gpu/instances/${encodeURIComponent(id)}`);
+  }
+  models() {
+    return this.request("GET", "/v1/models").then((r) => r.data || []);
+  }
+}
+
+export function sleep(ms) {
+  return new Promise((r) => setTimeout(r, ms));
+}

package/src/guards.js

@@ -0,0 +1,118 @@
+// Guardrails that run on this machine, before anything reaches the API or the instance.
+// The hard limits (auto-shutdown on time, budget and idle GPU) are enforced by CloudGPU's servers;
+// these catch mistakes early and keep secrets out of the model's context.
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+
+// ── Commands that would break the instance ───────────────────────────────────
+//
+// Every CloudGPU instance runs a small platform monitoring agent, and the platform checks on it
+// over SSH. Changing the root password, rewriting the SSH config or killing the agent locks that
+// check out, and the platform then shuts the instance down. These patterns stop an assistant from
+// doing that by accident (for example while "hardening" SSH or "cleaning up" processes).
+const BLOCKED = [
+  { re: /\b(passwd|chpasswd)\b/, why: "changes a login password" },
+  { re: /\busermod\b[^\n]*\s-p\b/, why: "changes a login password" },
+  { re: /sshd_config|\/etc\/ssh\//, why: "edits the SSH server configuration" },
+  { re: /\b(systemctl|service)\s+(stop|disable|mask|restart)\s+(ssh|sshd)\b/, why: "stops the SSH server" },
+  { re: /cgpu-(watchdog|agent)/, why: "touches the platform monitoring agent" },
+  { re: /\bkill\s+(-9\s+|-KILL\s+|-s\s+KILL\s+)?-1\b/, why: "kills every process on the machine" },
+  { re: /\bpkill\s+(-9\s+)?(-f\s+)?(bash|sh|sshd)\b/, why: "kills the shells the platform relies on" },
+  { re: /\bkillall\s+(-9\s+)?(bash|sh|sshd)\b/, why: "kills the shells the platform relies on" },
+  { re: /\b(iptables|nft|ufw)\b/, why: "changes the firewall" },
+];
+
+export function checkCommand(command) {
+  for (const b of BLOCKED) {
+    if (b.re.test(command)) {
+      return (
+        `Refused: this command ${b.why}. CloudGPU instances must stay reachable for the platform's ` +
+        `monitoring, otherwise the instance is shut down. Do the task another way.`
+      );
+    }
+  }
+  return null;
+}
+
+// ── Local files that should not be shipped to a rented machine by default ─────
+const SENSITIVE = [
+  /(^|\/)\.ssh(\/|$)/,
+  /(^|\/)\.aws(\/|$)/,
+  /(^|\/)\.gnupg(\/|$)/,
+  /(^|\/)\.config\/gcloud(\/|$)/,
+  /(^|\/)\.kube(\/|$)/,
+  /(^|\/)\.docker\/config\.json$/,
+  /(^|\/)\.netrc$/,
+  /(^|\/)\.npmrc$/,
+  /(^|\/)\.pypirc$/,
+  /(^|\/)\.env(\..*)?$/,
+  /\.(pem|key|p12|pfx)$/,
+  /(^|\/)id_(rsa|ed25519|ecdsa|dsa)(\.pub)?$/,
+];
+
+export function sensitiveReason(localPath) {
+  const abs = path.resolve(expandHome(localPath)).replace(/\\/g, "/");
+  if (abs === os.homedir().replace(/\\/g, "/")) return "it is your whole home directory";
+  for (const re of SENSITIVE) if (re.test(abs)) return "it looks like credentials or a secrets file";
+  return null;
+}
+
+export function expandHome(p) {
+  if (!p) return p;
+  return p === "~" ? os.homedir() : p.startsWith("~/") ? path.join(os.homedir(), p.slice(2)) : p;
+}
+
+// ── Redaction ─────────────────────────────────────────────────────────────
+/** Remove secrets (API key, SSH password, SSH host) from any text going back to the model. */
+export function redact(text, secrets) {
+  if (text == null) return text;
+  let out = String(text);
+  for (const s of secrets) {
+    if (s && String(s).length >= 4) out = out.split(String(s)).join("[redacted]");
+  }
+  out = out.replace(/\bsk-[A-Za-z0-9_-]{16,}/g, "sk-[redacted]");
+  return out;
+}
+
+/** Instance object as the model sees it: no SSH host, user or password. */
+export function publicInstance(inst) {
+  if (!inst) return inst;
+  const { ssh, ...rest } = inst;
+  return { ...rest, ssh_ready: !!(ssh && ssh.host && inst.status === "running") };
+}
+
+// ── Quotes ────────────────────────────────────────────────────────────────
+//
+// create_instance only accepts a quote_id from estimate_cost, so the assistant always has the
+// real hourly price, the estimate and the balance in hand (and shows them) before renting.
+export class Quotes {
+  constructor(ttlMs = 15 * 60 * 1000) {
+    this.ttlMs = ttlMs;
+    this.map = new Map();
+  }
+  put(q) {
+    const id = "q_" + crypto.randomBytes(6).toString("hex");
+    this.map.set(id, { ...q, id, at: Date.now() });
+    return id;
+  }
+  take(id) {
+    const q = this.map.get(id);
+    if (!q) return { error: "Unknown quote_id. Call estimate_cost first and show the quote to the user." };
+    if (Date.now() - q.at > this.ttlMs) {
+      this.map.delete(id);
+      return { error: "This quote expired (quotes last 15 minutes). Call estimate_cost again; prices are live." };
+    }
+    this.map.delete(id);
+    return { quote: q };
+  }
+}
+
+export function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+
+/** Shell-quote one argument for bash. */
+export function shq(s) {
+  return `'${String(s).replace(/'/g, `'\\''`)}'`;
+}

package/src/index.js

@@ -0,0 +1,571 @@
+#!/usr/bin/env node
+// CloudGPU MCP server (stdio). Lets an AI coding assistant rent a GPU on cloudgpu.app, run a job,
+// fetch the results and shut the GPU down.
+//
+// Env:
+//   CLOUDGPU_API_KEY         required; create one at https://cloudgpu.app/api
+//   CLOUDGPU_MAX_SPEND_USD   optional; highest budget the assistant may set for one instance (default 50)
+//   CLOUDGPU_MAX_HOURS       optional; longest run the assistant may set for one instance (default 24)
+//   CLOUDGPU_READ_ONLY       optional; "1" registers only the tools that look things up
+//   CLOUDGPU_BASE_URL        optional; default https://cloudgpu.app
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { CloudGpuApi, ApiError } from "./api.js";
+import { SshPool, exec, upload, download, writeFile } from "./ssh.js";
+import {
+  checkCommand,
+  sensitiveReason,
+  expandHome,
+  redact,
+  publicInstance,
+  Quotes,
+  round2,
+  shq,
+} from "./guards.js";
+
+const VERSION = "0.1.1";
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const RULES = fs.readFileSync(path.join(HERE, "..", "rules", "cloudgpu.md"), "utf8");
+
+const cfg = {
+  apiKey: (process.env.CLOUDGPU_API_KEY || "").trim(),
+  baseUrl: process.env.CLOUDGPU_BASE_URL || "https://cloudgpu.app",
+  maxSpend: num(process.env.CLOUDGPU_MAX_SPEND_USD, 50),
+  maxHours: num(process.env.CLOUDGPU_MAX_HOURS, 24),
+  readOnly: /^(1|true|yes)$/i.test(process.env.CLOUDGPU_READ_ONLY || ""),
+};
+
+function num(v, d) {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : d;
+}
+
+const api = new CloudGpuApi({ apiKey: cfg.apiKey, baseUrl: cfg.baseUrl });
+const pool = new SshPool();
+const quotes = new Quotes();
+// Instances this session touched: did we run anything, did we download anything.
+const session = new Map();
+
+const INSTRUCTIONS = `CloudGPU (cloudgpu.app) rents GPUs billed per minute from a prepaid balance.
+Workflow: get_account and list_gpus -> estimate_cost -> show the quote to the user and get an explicit yes -> create_instance -> get_status until running -> upload -> run_command (background for long jobs) -> tail_logs -> download results -> stop_instance -> report the actual cost.
+Rules: never rent without the user's yes on a quote; always set a budget and time limit (the platform shuts the instance down when either is hit); download results before stop_instance because destroying an instance erases its disk; never change passwords, SSH config, the firewall or the platform's monitoring agent on the instance; if anything fails, download what exists and stop the instance rather than leaving it running.
+The same API key also works for the OpenAI-compatible model API at ${cfg.baseUrl}/v1 (see list_models).`;
+
+const server = new McpServer({ name: "cloudgpu", version: VERSION }, { instructions: INSTRUCTIONS });
+
+// ── helpers ──────────────────────────────────────────────────────────────
+
+function ok(obj) {
+  const text = typeof obj === "string" ? obj : JSON.stringify(obj, null, 2);
+  return { content: [{ type: "text", text: redact(text, [cfg.apiKey]) }] };
+}
+
+function fail(msg) {
+  return { content: [{ type: "text", text: redact(msg, [cfg.apiKey]) }], isError: true };
+}
+
+function wrap(fn) {
+  return async (args) => {
+    try {
+      return await fn(args || {});
+    } catch (err) {
+      if (err instanceof ApiError) {
+        let hint = "";
+        if (err.status === 401) hint = " Check CLOUDGPU_API_KEY (create one at https://cloudgpu.app/api).";
+        if (err.status === 402) hint = " Top up at https://cloudgpu.app/billing.";
+        return fail(`CloudGPU API error ${err.status} ${err.code}: ${err.message}${hint}`);
+      }
+      return fail(`Error: ${err && err.message ? err.message : String(err)}`);
+    }
+  };
+}
+
+function track(id) {
+  if (!session.has(id)) session.set(id, { ran: false, downloaded: false });
+  return session.get(id);
+}
+
+/** Running instance + SSH client; throws a readable error otherwise. */
+async function connectTo(id) {
+  const inst = await api.instance(id);
+  if (inst.status !== "running") {
+    throw new Error(
+      `Instance ${id} is ${inst.status}` +
+        (inst.status === "creating"
+          ? "; wait for it with get_status until it is running."
+          : inst.failure_reason
+            ? `: ${inst.failure_reason}`
+            : inst.limits && inst.limits.stopped_by
+              ? ` (stopped by its ${inst.limits.stopped_by} limit).`
+              : "."),
+    );
+  }
+  if (!inst.ssh || !inst.ssh.host) throw new Error(`Instance ${id} has no SSH access yet; try get_status again shortly.`);
+  const client = await pool.get(id, inst.ssh);
+  const secrets = [cfg.apiKey, inst.ssh.password, inst.ssh.host];
+  return { inst, client, secrets };
+}
+
+const JOBS = ".cloudgpu/jobs";
+// bash -i so conda / venv set up in ~/.bashrc are active, the same as an interactive login.
+const NOISE = /^bash: (cannot set terminal process group|no job control in this shell).*\n?/gm;
+
+function cleanOut(s, secrets) {
+  return redact((s || "").replace(NOISE, ""), secrets);
+}
+
+// ── account and catalogue ────────────────────────────────────────────────
+
+server.registerTool(
+  "get_account",
+  {
+    title: "CloudGPU account",
+    description: "Balance in USD, how many instances this account may run at once, and how many are running now.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  },
+  wrap(async () => ok(await api.account())),
+);
+
+server.registerTool(
+  "list_gpus",
+  {
+    title: "List GPUs",
+    description:
+      "GPU models you can rent now, with VRAM, live price per GPU-hour in USD and availability (ok / low / none). Prices are live; never assume them.",
+    inputSchema: {
+      min_vram_gb: z.number().optional().describe("Only GPUs with at least this much VRAM per card"),
+      gpu_model: z.string().optional().describe("Filter by name, e.g. 4090, A100, H20"),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  },
+  wrap(async ({ min_vram_gb, gpu_model }) => {
+    let rows = await api.offers();
+    if (min_vram_gb) rows = rows.filter((r) => (r.vram_gb || 0) >= min_vram_gb);
+    if (gpu_model) {
+      const q = gpu_model.toLowerCase().replace(/\s+/g, "");
+      rows = rows.filter((r) => String(r.gpu_model).toLowerCase().replace(/\s+/g, "").includes(q));
+    }
+    return ok({
+      gpus: rows.map((r) => ({
+        gpu_model: r.gpu_model,
+        vram_gb: r.vram_gb,
+        usd_per_gpu_hour: r.hourly_usd,
+        available: r.available,
+        min_gpu_count: r.min_gpu_count,
+      })),
+      note: "Billed per minute. 'available' is live and can change before you rent.",
+    });
+  }),
+);
+
+server.registerTool(
+  "list_templates",
+  {
+    title: "List templates",
+    description:
+      "Ready-made instance images (e.g. JupyterLab, Ollama, ComfyUI, LLaMA-Factory) with the GPU each recommends. Templates with has_api_endpoint get a public HTTPS api_url.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  },
+  wrap(async () => ok({ templates: await api.templates() })),
+);
+
+server.registerTool(
+  "estimate_cost",
+  {
+    title: "Quote a rental",
+    description:
+      "Live price and estimated cost for a GPU, plus your balance after it. Returns a quote_id that create_instance needs. Show the quote to the user and get an explicit yes before renting.",
+    inputSchema: {
+      gpu_model: z.string().describe("GPU model exactly as list_gpus returns it"),
+      gpu_count: z.number().int().min(1).max(8).default(1),
+      hours: z.number().positive().describe("Expected run time in hours"),
+      template: z.string().optional().describe("Template id from list_templates; omit for a plain GPU with Python and CUDA"),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  },
+  wrap(async ({ gpu_model, gpu_count = 1, hours, template }) => {
+    const [offers, account] = await Promise.all([api.offers(), api.account().catch(() => null)]);
+    const offer = offers.find((o) => String(o.gpu_model).toLowerCase() === gpu_model.toLowerCase());
+    if (!offer) {
+      return fail(`No GPU named "${gpu_model}". Available: ${offers.map((o) => o.gpu_model).join(", ")}`);
+    }
+    if (gpu_count < (offer.min_gpu_count || 1)) {
+      return fail(`${offer.gpu_model} is rented in groups of at least ${offer.min_gpu_count} GPUs.`);
+    }
+    const hourly = round2(Number(offer.hourly_usd) * gpu_count);
+    const estimate = round2(hourly * hours);
+    const balance = account ? Number(account.balance_usd) : null;
+    const warnings = [];
+    if (offer.available === "none") warnings.push("This GPU is out of stock right now; renting will likely fail. Pick another.");
+    if (offer.available === "low") warnings.push("Only a few of these are free; renting may fail.");
+    if (balance != null && balance < estimate * 1.1) {
+      warnings.push(
+        `Balance $${balance} does not cover the estimate plus a 10% buffer. When the balance runs out the instance is destroyed and its disk erased. Top up at https://cloudgpu.app/billing.`,
+      );
+    }
+    const quote_id = quotes.put({ gpu_model: offer.gpu_model, gpu_count, template, hourly, hours, estimate });
+    return ok({
+      quote_id,
+      gpu_model: offer.gpu_model,
+      gpu_count,
+      template: template || null,
+      usd_per_hour: hourly,
+      hours,
+      estimated_cost_usd: estimate,
+      balance_usd: balance,
+      balance_after_usd: balance == null ? null : round2(balance - estimate),
+      suggested_max_spend_usd: round2(Math.min(cfg.maxSpend, Math.max(1, estimate * 1.25))),
+      warnings,
+      next: "Show this quote to the user. Only after they say yes, call create_instance with this quote_id.",
+    });
+  }),
+);
+
+server.registerTool(
+  "list_models",
+  {
+    title: "List hosted models",
+    description:
+      "Models on CloudGPU's OpenAI-compatible API (same key, same balance). Use them from code with base_url " +
+      `${cfg.baseUrl}/v1 instead of renting a GPU when you only need inference.`,
+    inputSchema: {},
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  },
+  wrap(async () => {
+    const models = await api.models();
+    return ok({
+      base_url: `${cfg.baseUrl}/v1`,
+      auth: "Authorization: Bearer <the same CLOUDGPU_API_KEY>",
+      models: models.map((m) => m.id),
+      pricing: `${cfg.baseUrl}/pricing`,
+    });
+  }),
+);
+
+// ── instances (read) ─────────────────────────────────────────────────────
+
+server.registerTool(
+  "get_status",
+  {
+    title: "Instance status",
+    description:
+      "Status (creating / running / stopped / failed), minutes run, cost so far, whether SSH is ready, the public api_url if the template has one, and the auto-shutdown limits.",
+    inputSchema: { instance_id: z.string() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  },
+  wrap(async ({ instance_id }) => ok(publicInstance(await api.instance(instance_id)))),
+);
+
+server.registerTool(
+  "list_instances",
+  {
+    title: "List instances",
+    description: "Instances on this account: running, starting, and those stopped in the last 7 days, with cost.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  },
+  wrap(async () => ok({ instances: (await api.instances()).map(publicInstance) })),
+);
+
+// ── instances (act) ──────────────────────────────────────────────────────
+
+if (!cfg.readOnly) {
+  server.registerTool(
+    "create_instance",
+    {
+      title: "Rent a GPU",
+      description:
+        "Rents the GPU from a quote. Costs money. Requires a quote_id from estimate_cost that the user has approved. " +
+        "max_spend_usd and max_hours are enforced by CloudGPU's servers: the instance is destroyed when either is reached, even if this assistant has disconnected. " +
+        "idle_minutes destroys it after the GPU sits idle that long (installing packages and downloading data count as idle, so allow for setup).",
+      inputSchema: {
+        quote_id: z.string(),
+        user_confirmed: z.boolean().describe("true only if the user explicitly approved this quote in the conversation"),
+        max_spend_usd: z.number().positive().describe(`Budget for this instance in USD (at most ${cfg.maxSpend})`),
+        max_hours: z.number().positive().describe(`Hard time limit in hours (at most ${cfg.maxHours})`),
+        idle_minutes: z
+          .number()
+          .int()
+          .min(0)
+          .max(1440)
+          .default(60)
+          .describe("Destroy after the GPU has been idle this long; 0 turns it off; otherwise at least 10"),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    },
+    wrap(async ({ quote_id, user_confirmed, max_spend_usd, max_hours, idle_minutes = 60 }) => {
+      if (user_confirmed !== true) {
+        return fail("Not rented: show the quote to the user and wait for an explicit yes, then call again with user_confirmed=true.");
+      }
+      if (max_spend_usd > cfg.maxSpend) {
+        return fail(
+          `max_spend_usd ${max_spend_usd} is above this server's cap of ${cfg.maxSpend} (CLOUDGPU_MAX_SPEND_USD). Ask the user to raise the cap in the MCP config if they want more.`,
+        );
+      }
+      if (max_hours > cfg.maxHours) {
+        return fail(`max_hours ${max_hours} is above this server's cap of ${cfg.maxHours} (CLOUDGPU_MAX_HOURS).`);
+      }
+      if (idle_minutes > 0 && idle_minutes < 10) return fail("idle_minutes must be 0 (off) or at least 10.");
+      const { quote, error } = quotes.take(quote_id);
+      if (error) return fail(error);
+      const account = await api.account();
+      const balance = Number(account.balance_usd);
+      const needed = round2(Math.min(max_spend_usd, quote.estimate) * 1.1);
+      if (balance < needed) {
+        return fail(
+          `Not rented: balance $${balance} is below $${needed} (the estimate or budget plus 10%). If the balance runs out the instance is destroyed and its disk erased. Top up at https://cloudgpu.app/billing.`,
+        );
+      }
+      const body = {
+        gpu_model: quote.gpu_model,
+        gpu_count: quote.gpu_count,
+        max_minutes: Math.ceil(max_hours * 60),
+        max_spend_usd,
+        idle_minutes,
+      };
+      if (quote.template) body.template = quote.template;
+      const inst = await api.create(body);
+      track(inst.id);
+      return ok({
+        ...publicInstance(inst),
+        next: "Call get_status at intervals (not in a tight loop) until status is running, then upload and run_command.",
+      });
+    }),
+  );
+
+  server.registerTool(
+    "run_command",
+    {
+      title: "Run a command on the instance",
+      description:
+        "Runs a bash command on the instance as root, in an interactive-style shell so conda/venv from ~/.bashrc are active. " +
+        "Foreground returns the exit code and the last 20k characters of output. For anything longer than a few minutes (training, big downloads) use background=true, then tail_logs.",
+      inputSchema: {
+        instance_id: z.string(),
+        command: z.string().describe("bash command or script"),
+        background: z.boolean().default(false),
+        timeout_sec: z.number().int().min(5).max(3600).default(600).describe("Foreground only"),
+        workdir: z.string().default("~").describe("Directory to run in"),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+    },
+    wrap(async ({ instance_id, command, background = false, timeout_sec = 600, workdir = "~" }) => {
+      const blocked = checkCommand(command);
+      if (blocked) return fail(blocked);
+      const { client, secrets } = await connectTo(instance_id);
+      track(instance_id).ran = true;
+      const job = "j" + Date.now().toString(36);
+      const cd = workdir === "~" ? "cd ~" : workdir.startsWith("~/") ? `cd ~/${shq(workdir.slice(2))}` : `cd ${shq(workdir)}`;
+      await writeFile(client, `${JOBS}/${job}.sh`, `${cd} || exit 97\n${command}\n`);
+      if (background) {
+        const r = await exec(
+          client,
+          `cd ~ && setsid nohup bash -c 'bash -i ${JOBS}/${job}.sh > ${JOBS}/${job}.log 2>&1 < /dev/null; echo $? > ${JOBS}/${job}.exit' > /dev/null 2>&1 < /dev/null & echo started`,
+          { timeoutSec: 30 },
+        );
+        if (!/started/.test(r.stdout)) return fail(`Could not start the job: ${cleanOut(r.stderr, secrets)}`);
+        return ok({
+          job_id: job,
+          log: `~/${JOBS}/${job}.log`,
+          next: "Check progress with tail_logs (job_id). The job keeps running if this assistant disconnects; the instance's limits still apply.",
+        });
+      }
+      const r = await exec(client, `cd ~ && timeout ${timeout_sec} bash -i ${JOBS}/${job}.sh 2>&1 < /dev/null`, {
+        timeoutSec: timeout_sec + 15,
+      });
+      const out = cleanOut(r.stdout + (r.stderr ? "\n" + r.stderr : ""), secrets);
+      return ok({
+        exit_code: r.timedOut || r.code === 124 ? null : r.code,
+        timed_out: r.timedOut || r.code === 124,
+        output: out,
+        ...(r.timedOut || r.code === 124 ? { hint: "Timed out. Re-run long work with background=true." } : {}),
+      });
+    }),
+  );
+
+  server.registerTool(
+    "upload",
+    {
+      title: "Upload to the instance",
+      description:
+        "Copies a local file or directory (this computer) to the instance over SFTP. node_modules, .git and __pycache__ are skipped. Credentials files (.ssh, .env, keys) are refused unless allow_sensitive is true and the user asked for it.",
+      inputSchema: {
+        instance_id: z.string(),
+        local_path: z.string(),
+        remote_path: z.string().describe("Destination on the instance, e.g. /root/project or /root/data/"),
+        allow_sensitive: z.boolean().default(false),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    },
+    wrap(async ({ instance_id, local_path, remote_path, allow_sensitive = false }) => {
+      const local = path.resolve(expandHome(local_path));
+      if (!fs.existsSync(local)) return fail(`No such local path: ${local}`);
+      const why = sensitiveReason(local);
+      if (why && !allow_sensitive) {
+        return fail(`Refused to upload ${local}: ${why}. If the user explicitly wants it on the instance, call again with allow_sensitive=true.`);
+      }
+      const { client } = await connectTo(instance_id);
+      const remote = remote_path.startsWith("~/") ? remote_path.slice(2) : remote_path;
+      const r = await upload(client, local, remote);
+      return ok({ uploaded_files: r.files, bytes: r.bytes, remote_path });
+    }),
+  );
+
+  server.registerTool(
+    "download",
+    {
+      title: "Download from the instance",
+      description:
+        "Copies a file or directory from the instance to this computer. Do this for every result before stop_instance: destroying an instance erases its disk.",
+      inputSchema: {
+        instance_id: z.string(),
+        remote_path: z.string(),
+        local_path: z.string().describe("Local destination file or directory, e.g. ./outputs/"),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    },
+    wrap(async ({ instance_id, remote_path, local_path }) => {
+      const { client } = await connectTo(instance_id);
+      const remote = remote_path.startsWith("~/") ? remote_path.slice(2) : remote_path;
+      const r = await download(client, remote, path.resolve(expandHome(local_path)));
+      track(instance_id).downloaded = true;
+      return ok({
+        files: r.files.slice(0, 200),
+        file_count: r.files.length,
+        bytes: r.bytes,
+      });
+    }),
+  );
+
+  server.registerTool(
+    "tail_logs",
+    {
+      title: "Job logs and GPU use",
+      description:
+        "Last lines of a background job's log (job_id) or any log file (path), whether the job is still running and its exit code, plus current GPU utilisation and memory.",
+      inputSchema: {
+        instance_id: z.string(),
+        job_id: z.string().optional(),
+        path: z.string().optional(),
+        lines: z.number().int().min(1).max(2000).default(100),
+      },
+      annotations: { readOnlyHint: true, openWorldHint: true },
+    },
+    wrap(async ({ instance_id, job_id, path: logPath, lines = 100 }) => {
+      if (!job_id && !logPath) return fail("Give job_id (from run_command background=true) or path.");
+      if (job_id && !/^[a-z0-9]+$/i.test(job_id)) return fail("Bad job_id.");
+      const { client, secrets } = await connectTo(instance_id);
+      const file = job_id ? `${JOBS}/${job_id}.log` : logPath.startsWith("~/") ? logPath.slice(2) : logPath;
+      const exitFile = job_id ? `${JOBS}/${job_id}.exit` : "/nonexistent";
+      const r = await exec(
+        client,
+        `cd ~; echo '<<LOG'; tail -n ${lines} ${shq(file)} 2>&1; echo 'LOG>>'; ` +
+          `if [ -f ${shq(exitFile)} ]; then echo "EXIT=$(cat ${shq(exitFile)})"; fi; ` +
+          `nvidia-smi --query-gpu=index,utilization.gpu,memory.used,memory.total --format=csv,noheader,nounits 2>/dev/null | sed 's/^/GPU=/'`,
+        { timeoutSec: 60 },
+      );
+      const s = r.stdout;
+      const log = s.includes("<<LOG") ? s.slice(s.indexOf("<<LOG") + 6, s.lastIndexOf("LOG>>")) : s;
+      const exitM = s.match(/EXIT=(\d+)/);
+      const gpus = [...s.matchAll(/GPU=(\d+), (\d+), (\d+), (\d+)/g)].map((m) => ({
+        gpu: Number(m[1]),
+        utilization_pct: Number(m[2]),
+        memory_used_mb: Number(m[3]),
+        memory_total_mb: Number(m[4]),
+      }));
+      return ok({
+        log: cleanOut(log, secrets),
+        ...(job_id ? { running: !exitM, exit_code: exitM ? Number(exitM[1]) : null } : {}),
+        gpus,
+      });
+    }),
+  );
+
+  server.registerTool(
+    "stop_instance",
+    {
+      title: "Destroy an instance",
+      description:
+        "Destroys the instance and stops billing. Its disk is erased. If commands were run on it in this session and nothing was downloaded, this refuses unless force=true (only after the user confirms the results are not needed).",
+      inputSchema: {
+        instance_id: z.string(),
+        force: z.boolean().default(false),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    },
+    wrap(async ({ instance_id, force = false }) => {
+      const s = session.get(instance_id);
+      if (s && s.ran && !s.downloaded && !force) {
+        return fail(
+          "Not stopped: nothing has been downloaded from this instance yet, and stopping erases its disk. Download the results first, or ask the user and call again with force=true.",
+        );
+      }
+      pool.close(instance_id);
+      try {
+        const inst = await api.destroy(instance_id);
+        session.delete(instance_id);
+        return ok({ ...publicInstance(inst), note: "Destroyed. Billing has stopped." });
+      } catch (err) {
+        if (err instanceof ApiError && err.code === "cannot_destroy") {
+          // 已经停了（限额到线、余额用完、开出来没 GPU 被平台退款）：告诉助手结果，而不是报错
+          const inst = await api.instance(instance_id).catch(() => null);
+          if (inst && inst.status !== "running") {
+            session.delete(instance_id);
+            return ok({ ...publicInstance(inst), note: "Already stopped; nothing more to do. Billing has stopped." });
+          }
+        }
+        if (err instanceof ApiError && err.code === "instance_provisioning") {
+          return fail("The instance is still starting and cannot be destroyed yet. Wait for get_status to show running (or failed; failed instances are not charged), then call stop_instance again.");
+        }
+        throw err;
+      }
+    }),
+  );
+}
+
+// ── rules for the assistant ──────────────────────────────────────────────
+
+server.registerResource(
+  "rules",
+  "cloudgpu://rules",
+  { title: "CloudGPU agent rules", description: "How to rent, run and shut down safely", mimeType: "text/markdown" },
+  async (uri) => ({ contents: [{ uri: uri.href, mimeType: "text/markdown", text: RULES }] }),
+);
+
+server.registerPrompt(
+  "train_on_cloudgpu",
+  {
+    title: "Run a job on a CloudGPU GPU",
+    description: "Rent a GPU, run a training or fine-tuning job, bring the results back and shut down",
+    argsSchema: { task: z.string().describe("What to run, e.g. 'LoRA fine-tune a 7B base model on data/train.jsonl'") },
+  },
+  ({ task }) => ({
+    messages: [{ role: "user", content: { type: "text", text: `${RULES}\n\n---\n\nTask: ${task}` } }],
+  }),
+);
+
+// ── start ────────────────────────────────────────────────────────────────
+
+if (process.argv.includes("--version")) {
+  console.log(VERSION);
+  process.exit(0);
+}
+
+const transport = new StdioServerTransport();
+await server.connect(transport);
+const bye = () => {
+  pool.closeAll();
+  process.exit(0);
+};
+process.on("SIGINT", bye);
+process.on("SIGTERM", bye);
+process.stdin.on("close", bye);
+if (!cfg.apiKey) {
+  console.error("cloudgpu-mcp: CLOUDGPU_API_KEY is not set; tools will return an error until it is. Create a key at https://cloudgpu.app/api");
+}

package/src/ssh.js

@@ -0,0 +1,233 @@
+// SSH to a rented instance: run commands, upload, download.
+//
+// The SSH password comes from the API and stays inside this process. It is never put in a tool
+// result, so it never reaches the model's context or the chat log.
+import { Client } from "ssh2";
+import fs from "node:fs";
+import path from "node:path";
+import { sleep } from "./api.js";
+
+const MAX_OUTPUT = 20000; // characters of command output returned to the model
+
+export class SshPool {
+  constructor() {
+    this.conns = new Map(); // instanceId -> { client, key }
+  }
+
+  async get(instanceId, ssh) {
+    const key = `${ssh.host}:${ssh.port}:${ssh.user}`;
+    const cur = this.conns.get(instanceId);
+    if (cur && cur.key === key && cur.ready) return cur.client;
+    if (cur) this.close(instanceId);
+    // Some instance gateways drop several connections opened back to back, so retry with backoff.
+    let lastErr;
+    for (let i = 0; i < 4; i++) {
+      try {
+        const client = await connect(ssh);
+        const entry = { client, key, ready: true };
+        client.on("close", () => {
+          entry.ready = false;
+        });
+        client.on("error", () => {
+          entry.ready = false;
+        });
+        this.conns.set(instanceId, entry);
+        return client;
+      } catch (err) {
+        lastErr = err;
+        await sleep(2000 * (i + 1));
+      }
+    }
+    throw new Error(`SSH connection failed: ${lastErr && lastErr.message}`);
+  }
+
+  close(instanceId) {
+    const cur = this.conns.get(instanceId);
+    if (cur) {
+      try {
+        cur.client.end();
+      } catch {
+        /* already closed */
+      }
+      this.conns.delete(instanceId);
+    }
+  }
+
+  closeAll() {
+    for (const id of [...this.conns.keys()]) this.close(id);
+  }
+}
+
+function connect(ssh) {
+  return new Promise((resolve, reject) => {
+    const c = new Client();
+    const timer = setTimeout(() => {
+      c.end();
+      reject(new Error("timed out"));
+    }, 25000);
+    c.on("ready", () => {
+      clearTimeout(timer);
+      resolve(c);
+    });
+    c.on("error", (e) => {
+      clearTimeout(timer);
+      reject(e);
+    });
+    c.connect({
+      host: ssh.host,
+      port: ssh.port || 22,
+      username: ssh.user || "root",
+      password: ssh.password,
+      readyTimeout: 20000,
+      keepaliveInterval: 15000,
+      keepaliveCountMax: 4,
+      tryKeyboard: true,
+    });
+    c.on("keyboard-interactive", (_n, _i, _l, prompts, finish) => finish(prompts.map(() => ssh.password)));
+  });
+}
+
+/** Run a command; resolves { code, stdout, stderr } (both truncated to the tail). */
+export function exec(client, command, { timeoutSec = 600 } = {}) {
+  return new Promise((resolve, reject) => {
+    client.exec(command, (err, stream) => {
+      if (err) return reject(err);
+      let out = "";
+      let errOut = "";
+      let done = false;
+      const timer = setTimeout(() => {
+        if (done) return;
+        done = true;
+        try {
+          stream.close();
+        } catch {
+          /* ignore */
+        }
+        resolve({ code: null, timedOut: true, stdout: tail(out), stderr: tail(errOut) });
+      }, timeoutSec * 1000);
+      stream.on("data", (d) => {
+        out = keepTail(out + d.toString("utf8"));
+      });
+      stream.stderr.on("data", (d) => {
+        errOut = keepTail(errOut + d.toString("utf8"));
+      });
+      stream.on("close", (code) => {
+        if (done) return;
+        done = true;
+        clearTimeout(timer);
+        resolve({ code, timedOut: false, stdout: tail(out), stderr: tail(errOut) });
+      });
+    });
+  });
+}
+
+function keepTail(s) {
+  return s.length > MAX_OUTPUT * 2 ? s.slice(-MAX_OUTPUT * 2) : s;
+}
+
+function tail(s) {
+  return s.length > MAX_OUTPUT ? "…(earlier output cut)…\n" + s.slice(-MAX_OUTPUT) : s;
+}
+
+function sftpOf(client) {
+  return new Promise((resolve, reject) => client.sftp((err, sftp) => (err ? reject(err) : resolve(sftp))));
+}
+
+const p = (fn) =>
+  new Promise((resolve, reject) => fn((err, v) => (err ? reject(err) : resolve(v))));
+
+async function mkdirp(sftp, dir) {
+  const parts = dir.split("/").filter(Boolean);
+  let cur = dir.startsWith("/") ? "" : ".";
+  for (const part of parts) {
+    cur = `${cur}/${part}`;
+    try {
+      await p((cb) => sftp.stat(cur, cb));
+    } catch {
+      await p((cb) => sftp.mkdir(cur, cb)).catch(() => {});
+    }
+  }
+}
+
+/** Upload a local file or directory. Returns { files, bytes }. */
+export async function upload(client, localPath, remotePath) {
+  const sftp = await sftpOf(client);
+  try {
+    const st = fs.statSync(localPath);
+    let files = 0;
+    let bytes = 0;
+    const put = async (src, dst) => {
+      await mkdirp(sftp, path.posix.dirname(dst));
+      await p((cb) => sftp.fastPut(src, dst, cb));
+      files += 1;
+      bytes += fs.statSync(src).size;
+    };
+    if (st.isDirectory()) {
+      const walk = async (dir, rel) => {
+        for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
+          if (ent.name === "node_modules" || ent.name === ".git" || ent.name === "__pycache__") continue;
+          const src = path.join(dir, ent.name);
+          const dst = path.posix.join(remotePath, rel, ent.name);
+          if (ent.isDirectory()) await walk(src, path.posix.join(rel, ent.name));
+          else if (ent.isFile()) await put(src, dst);
+        }
+      };
+      await mkdirp(sftp, remotePath);
+      await walk(localPath, "");
+    } else {
+      await put(localPath, remotePath.endsWith("/") ? path.posix.join(remotePath, path.basename(localPath)) : remotePath);
+    }
+    return { files, bytes };
+  } finally {
+    sftp.end();
+  }
+}
+
+/** Download a remote file or directory. Returns { files: [{path, bytes}], bytes }. */
+export async function download(client, remotePath, localPath) {
+  const sftp = await sftpOf(client);
+  try {
+    const st = await p((cb) => sftp.stat(remotePath, cb));
+    const files = [];
+    let bytes = 0;
+    const get = async (src, dst, size) => {
+      fs.mkdirSync(path.dirname(dst), { recursive: true });
+      await p((cb) => sftp.fastGet(src, dst, cb));
+      files.push({ path: dst, bytes: size });
+      bytes += size;
+    };
+    if (st.isDirectory()) {
+      const walk = async (dir, rel) => {
+        const list = await p((cb) => sftp.readdir(dir, cb));
+        for (const ent of list) {
+          const src = path.posix.join(dir, ent.filename);
+          const dst = path.join(localPath, rel, ent.filename);
+          if (ent.attrs.isDirectory()) await walk(src, path.join(rel, ent.filename));
+          else if (ent.attrs.isFile()) await get(src, dst, ent.attrs.size);
+        }
+      };
+      fs.mkdirSync(localPath, { recursive: true });
+      await walk(remotePath, "");
+    } else {
+      let dst = localPath;
+      if (fs.existsSync(localPath) && fs.statSync(localPath).isDirectory()) {
+        dst = path.join(localPath, path.posix.basename(remotePath));
+      }
+      await get(remotePath, dst, st.size);
+    }
+    return { files, bytes };
+  } finally {
+    sftp.end();
+  }
+}
+
+/** Write a small text file on the instance. */
+export async function writeFile(client, remotePath, content) {
+  const sftp = await sftpOf(client);
+  try {
+    await mkdirp(sftp, path.posix.dirname(remotePath));
+    await p((cb) => sftp.writeFile(remotePath, content, { mode: 0o700 }, cb));
+  } finally {
+    sftp.end();
+  }
+}