@prismnetwork/mcp 0.5.0 → 0.7.0

package/README.md

@@ -22,6 +22,7 @@ real prices. Leasing spends money, so those tools ask for a wallet and say so.
 | `prism_receipts` | no |
 | `prism_wallet` | yes |
 | `prism_leases` | yes |
+| `prism_infer` | yes |
 | `prism_lease_and_run` | yes |
 | `prism_lease` | yes |
 | `prism_run` | yes |
@@ -39,6 +40,10 @@ real prices. Leasing spends money, so those tools ask for a wallet and say so.
 - `prism_receipts`: recent settled receipts from the public proof feed, with the
   settlement transaction on Robinhood Chain.
 - `prism_leases`: this wallet's leases and their state.
+- `prism_infer`: buy one LLM generation from the managed inference endpoint,
+  paying the quoted USDG price from this wallet (about 0.01 USDG). Waits
+  through a cold start; an unconsumed payment is kept and reused on the next
+  call instead of paying twice.
 - `prism_lease_and_run`: lease a GPU, run a command, return the output (one shot).
 - `prism_lease`: lease a GPU and keep it; returns a `lease_id` and SSH access.
 - `prism_run`: run a command on an existing lease.
@@ -60,7 +65,7 @@ derived from the agent's wallet inside this server process; Prism receives
 ciphertext and holds no way to read it.
 
 Each item names the weakest workspace trust class it may ever be released into,
-and new items default to `confidential` — above anything the network serves
+and new items default to `confidential`, above anything the network serves
 today. `prism_vault_release` is therefore refused on current capacity instead of
 handing a secret to a host that can read it. Lowering an item's floor is a
 deliberate act, and allowed releases are recorded against the account.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismnetwork/mcp",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "MCP server for leasing and running on Prism Network GPUs.",
   "mcpName": "io.github.prismnetwork-tech/mcp",
   "type": "module",
@@ -16,7 +16,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@prismnetwork/agent-sdk": "^0.3.1",
+    "@prismnetwork/agent-sdk": "^0.5.0",
     "viem": "^2"
   },
   "keywords": [

package/server.mjs

@@ -9,59 +9,85 @@ import { DEFAULT_IMAGE, DEFAULT_TRUST_FLOOR, PrismAgent, TRUST_CLASSES } from "@
 
 const IMAGE = process.env.PRISM_DEFAULT_IMAGE ?? DEFAULT_IMAGE;
 
-function requireEnv(name) {
-  const value = process.env[name];
-  if (!value) throw new Error(`${name} is required`);
-  return value;
-}
-
 const PUBLIC_API = process.env.PRISM_PUBLIC_API ?? "https://api.prismnetwork.tech";
+// The live lease escrow. Overridable, but its absence must not silently
+// disable the wallet the way a missing key does.
+const DEFAULT_ESCROW = "0x62C042265991bEa17B07229322A01850974626dA";
+// Matches the limit the SDK and the control plane enforce, so a command that
+// cannot run is rejected before an escrow is funded.
+const MAX_COMMAND_BYTES = 8 * 1024;
 
 // Refusing to start without a wallet meant nobody could ask what a GPU costs
 // without first producing a private key, which is a strange thing to demand of
 // someone deciding whether to use you at all.
 let agent = null;
-try {
-  agent = new PrismAgent({
-    privateKey: requireEnv("PRISM_AGENT_KEY"),
-    escrow: requireEnv("PRISM_ESCROW"),
-    apiBase: process.env.PRISM_API_BASE ?? "https://prismnetwork.tech",
-    rpcUrl: process.env.PRISM_RPC_URL,
-  });
-} catch {
+let walletProblem = "PRISM_AGENT_KEY is not set";
+if (process.env.PRISM_AGENT_KEY) {
+  try {
+    agent = new PrismAgent({
+      privateKey: process.env.PRISM_AGENT_KEY,
+      escrow: process.env.PRISM_ESCROW ?? DEFAULT_ESCROW,
+      apiBase: process.env.PRISM_API_BASE ?? "https://prismnetwork.tech",
+      rpcUrl: process.env.PRISM_RPC_URL,
+    });
+    walletProblem = null;
+  } catch (err) {
+    walletProblem = `PRISM_AGENT_KEY is set but unusable: ${err?.message ?? err}`;
+  }
+}
+if (!agent) {
   console.error(
-    "prism mcp: no wallet configured, so capacity and pricing are readable and leasing is not. " +
-      "Set PRISM_AGENT_KEY and PRISM_ESCROW to lease.",
+    `prism mcp: no wallet configured (${walletProblem}), so capacity and pricing are readable and leasing is not.`,
   );
 }
 
-function requireWallet(tool) {
+function requireWallet(tool, reason = "spends money") {
   if (!agent) {
     throw new Error(
-      `${tool} spends money, so it needs a wallet. Set PRISM_AGENT_KEY and PRISM_ESCROW in this server's environment and restart it.`,
+      `${tool} ${reason} and needs a wallet. None is configured: ${walletProblem}. Fix the environment and restart the server.`,
     );
   }
   return agent;
 }
 
-async function publicOffers(minTrust) {
-  const url = new URL("/v1/offers", PUBLIC_API);
-  if (minTrust) url.searchParams.set("min_trust", minTrust);
-  const response = await fetch(url, { headers: { accept: "application/json" } });
-  if (!response.ok) throw new Error(`prism offers unavailable (${response.status})`);
-  return response.json();
+function requireCommand(value) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error("command is required: the shell command to run on the GPU, e.g. 'nvidia-smi'.");
+  }
+  if (Buffer.byteLength(value, "utf8") > MAX_COMMAND_BYTES) {
+    throw new Error(`command exceeds the ${MAX_COMMAND_BYTES / 1024} KiB limit.`);
+  }
+  return value;
+}
+
+function maxDeposit(args) {
+  const cap = args.max_usdg ?? 1;
+  if (typeof cap !== "number" || !Number.isFinite(cap) || cap <= 0) {
+    throw new Error("max_usdg must be a positive number of USDG.");
+  }
+  return Math.round(cap * 1e6);
 }
 
 const PROOF_FEED = process.env.PRISM_PROOF_URL ?? "https://prismnetwork.tech/api/proof";
 
 async function publicJson(url, what) {
-  const response = await fetch(url, { headers: { accept: "application/json" } });
+  const response = await fetch(url, {
+    headers: { accept: "application/json" },
+    signal: AbortSignal.timeout(10_000),
+  });
   if (!response.ok) throw new Error(`prism ${what} unavailable (${response.status})`);
-  return response.json();
+  const body = await response.json().catch(() => null);
+  if (body === null) throw new Error(`prism ${what} answered with something that is not JSON`);
+  return body;
 }
 
 const leases = new Map();
-const usdg = (micros) => `${(Number(micros) / 1e6).toFixed(6)} USDG`;
+// Unconsumed inference payments, keyed by endpoint and price, so a failed
+// generation is retried with the same paid header instead of paying again.
+const pendingInference = new Map();
+// null in, null out: a missing price must never render as 0.000000 USDG.
+const usdg = (micros) =>
+  micros == null || !Number.isFinite(Number(micros)) ? null : `${(Number(micros) / 1e6).toFixed(6)} USDG`;
 
 function sweepExpiredLeases() {
   const now = Date.now();
@@ -111,7 +137,7 @@ const TOOLS = [
     inputSchema: {
       type: "object",
       properties: {
-        limit: { type: "integer", description: "Max receipts to return (default 10)." },
+        limit: { type: "integer", description: "Max receipts to return (default 10, max 50)." },
       },
     },
   },
@@ -122,17 +148,42 @@ const TOOLS = [
   },
   {
     name: "prism_batch_run",
-    description: "Fund a lease that runs one command with no interactive access at all: the node executes it and reports the signed output. Matches only suppliers at trust class 'isolated' or above, so it can find no supplier when none is online — prefer prism_lease_and_run for broad availability. Output is capped at 64 KiB per stream.",
+    description: "Fund a lease that runs one command with no interactive access at all: the node executes it and reports the signed output. Matches only suppliers at trust class 'isolated' or above, so it can find no supplier when none is online; prefer prism_lease_and_run for broad availability. Output is capped at 64 KiB per stream.",
     inputSchema: {
       type: "object",
       properties: {
         command: { type: "string", description: "Shell command to run (max 8 KiB)." },
         duration_seconds: { type: "integer", description: "Paid window in seconds (default 900, max 21600). A command still running at the end is killed and reported exit 124." },
         min_vram_mib: { type: "integer", description: "Minimum GPU memory in MiB (default 16000)." },
+        max_usdg: { type: "number", description: "Hard cap on the USDG this lease may cost (default 1). Raise it deliberately for longer leases." },
       },
       required: ["command"],
     },
   },
+  {
+    name: "prism_batch_result",
+    description: "Read the output of a batch lease by lease_id, once its node has reported. Use it to recover a result after prism_batch_run timed out.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        lease_id: { type: "integer", description: "The lease_id from prism_batch_run's output or error." },
+      },
+      required: ["lease_id"],
+    },
+  },
+  {
+    name: "prism_infer",
+    description: "Buy one LLM generation from Prism's managed inference endpoint. Pays the quoted USDG price from this wallet (about 0.01 USDG), waits through a cold start when no box is warm (up to a few minutes), and returns the generation with token usage. Cheaper and simpler than leasing when all you need is a completion.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        prompt: { type: "string", description: "The prompt to generate from (max 32 KiB)." },
+        model: { type: "string", description: "Model to use; defaults to the endpoint's first offered model." },
+        max_usdg: { type: "number", description: "Refuse if the quoted price exceeds this (default 0.05)." },
+      },
+      required: ["prompt"],
+    },
+  },
   {
     name: "prism_lease_and_run",
     description: "Lease a GPU, run one shell command on it, and return the output. The lease stays alive (use prism_run for more commands, prism_end_lease to release). Prefer this for a single command; use prism_lease when you'll run several.",
@@ -147,6 +198,7 @@ const TOOLS = [
           enum: TRUST_CLASSES,
           description: "Refuse suppliers below this trust class (default 'open'). Raise it for anything the host operator must not read.",
         },
+        max_usdg: { type: "number", description: "Hard cap on the USDG this lease may cost (default 1). Raise it deliberately for longer leases." },
       },
       required: ["command"],
     },
@@ -164,6 +216,7 @@ const TOOLS = [
           enum: TRUST_CLASSES,
           description: "Refuse suppliers below this trust class (default 'open'). Raise it for anything the host operator must not read.",
         },
+        max_usdg: { type: "number", description: "Hard cap on the USDG this lease may cost (default 1). Raise it deliberately for longer leases." },
       },
     },
   },
@@ -191,7 +244,7 @@ const TOOLS = [
   },
   {
     name: "prism_vault_store",
-    description: "Store private data — a card, an identity document, an API credential — encrypted under a key derived from this agent's wallet on this machine. Prism receives ciphertext only and cannot read it. Use this instead of writing a secret into a workspace or a file. Returns an item_id; the value is not recoverable without the wallet.",
+    description: "Store private data (a card, an identity document, an API credential) encrypted under a key derived from this agent's wallet on this machine. Prism receives ciphertext only and cannot read it. Use this instead of writing a secret into a workspace or a file. Returns an item_id; the value is not recoverable without the wallet.",
     inputSchema: {
       type: "object",
       properties: {
@@ -213,7 +266,7 @@ const TOOLS = [
   },
   {
     name: "prism_vault_read",
-    description: "Decrypt and return one vault item, in this process, using the wallet-derived key. The plaintext exists only here — do not echo it into a leased workspace, a log, or a message.",
+    description: "Decrypt and return one vault item, in this process, using the wallet-derived key. The plaintext exists only here; do not echo it into a leased workspace, a log, or a message.",
     inputSchema: {
       type: "object",
       properties: { item_id: { type: "string", description: "The item_id from prism_vault_store or prism_vault_list." } },
@@ -250,12 +303,16 @@ async function handle(name, args) {
   }
   if (name === "prism_list_gpus") {
     const minTrust = args.min_trust ?? "open";
+    if (!TRUST_CLASSES.includes(minTrust)) {
+      throw new Error(`min_trust must be one of ${TRUST_CLASSES.join(", ")}`);
+    }
     let offers;
     if (agent) {
-      await ensureAuth();
       offers = await agent.offers({ minTrust });
     } else {
-      offers = await publicOffers(minTrust);
+      const url = new URL("/v1/offers", PUBLIC_API);
+      url.searchParams.set("min_trust", minTrust);
+      offers = await publicJson(url, "offers");
     }
     return {
       available: offers.length,
@@ -265,6 +322,9 @@ async function handle(name, args) {
         price_per_second: usdg(o.rate_per_second),
         price_per_hour: usdg(o.rate_per_second * 3600),
         trust: o.trust_class,
+        // A staker-only offer will not match a wallet without the stake, so an
+        // unstaked renter should budget from the non-staker rows.
+        ...(o.staker_only ? { staker_only: true } : {}),
       })),
     };
   }
@@ -278,21 +338,27 @@ async function handle(name, args) {
         sourced_low_per_hour: usdg(g.sourced_low_micros_per_hour),
         sourced_median_per_hour: usdg(g.sourced_median_micros_per_hour),
         sourced_high_per_hour: usdg(g.sourced_high_micros_per_hour),
-        settled_mean_per_hour: g.settled_mean_micros_per_hour == null ? null : usdg(g.settled_mean_micros_per_hour),
+        settled_mean_per_hour: usdg(g.settled_mean_micros_per_hour),
         settled_leases: g.settled_leases,
       })),
     };
   }
   if (name === "prism_receipts") {
     const feed = await publicJson(PROOF_FEED, "proof feed");
-    const limit = Number.isInteger(args.limit) && args.limit > 0 ? args.limit : 10;
+    if (args.limit !== undefined && (!Number.isInteger(args.limit) || args.limit <= 0)) {
+      throw new Error("limit must be a positive integer (max 50)");
+    }
+    const limit = Math.min(args.limit ?? 10, 50);
     return {
       generated_at: feed.generated_at,
       receipts: (feed.receipts ?? []).slice(0, limit).map((r) => ({
+        // The feed numbers leases per escrow deployment, so lease_id repeats
+        // across deployments; receipt_id is the unique handle.
+        receipt_id: r.receipt_id,
         lease_id: r.lease_id,
         outcome: r.outcome,
         gpu_model: r.gpu_model,
-        trust: r.trust_class,
+        trust: r.trust_class ?? null,
         runtime_seconds: r.runtime_seconds,
         charged: usdg(r.charged_base_units),
         refunded: usdg(r.refunded_base_units),
@@ -302,7 +368,6 @@ async function handle(name, args) {
   }
   if (name === "prism_leases") {
     requireWallet(name);
-    await ensureAuth();
     const all = await agent.leases();
     return {
       total: all.length,
@@ -320,13 +385,14 @@ async function handle(name, args) {
     };
   }
   if (name === "prism_batch_run") {
-    if (!args.command) throw new Error("command is required");
+    requireCommand(args.command);
     requireWallet(name);
-    await ensureAuth();
+    const cap = maxDeposit(args);
     const batch = await agent.lease({
       image: IMAGE,
       durationSeconds: args.duration_seconds ?? 900,
       minVramMib: args.min_vram_mib ?? 16000,
+      maxDeposit: cap,
       command: args.command,
     });
     return {
@@ -338,35 +404,114 @@ async function handle(name, args) {
       truncated: batch.result?.truncated ?? false,
     };
   }
+  if (name === "prism_batch_result") {
+    requireWallet(name, "reads this wallet's leases");
+    const id = leaseId(args.lease_id);
+    return { lease_id: id, result: await agent.result(id) };
+  }
+  if (name === "prism_infer") {
+    if (typeof args.prompt !== "string" || args.prompt.trim() === "") {
+      throw new Error("prompt is required.");
+    }
+    requireWallet(name);
+    const base = (process.env.PRISM_INFERENCE_URL ?? "https://api.prismnetwork.tech/inference").replace(/\/$/, "");
+    const offer = await publicJson(`${base}/v1/models`, "inference endpoint");
+    const model = args.model ?? offer.models?.[0];
+    if (!model || (Array.isArray(offer.models) && !offer.models.includes(model))) {
+      throw new Error(`model must be one of ${offer.models?.join(", ") ?? "(endpoint offered none)"}`);
+    }
+    const price = BigInt(offer.price_micros ?? 0);
+    const cap = args.max_usdg ?? 0.05;
+    if (typeof cap !== "number" || !Number.isFinite(cap) || cap <= 0) {
+      throw new Error("max_usdg must be a positive number of USDG.");
+    }
+    if (price <= 0n || price > BigInt(Math.round(cap * 1e6))) {
+      throw new Error(`the endpoint quotes ${usdg(price)} per generation, past the ${cap} USDG cap.`);
+    }
+    const pendingKey = `${base}:${price}`;
+    let pending = pendingInference.get(pendingKey);
+    if (!pending) {
+      const paymentTx = await agent.transferUsdg(offer.pay_to, price);
+      const signature = await agent.account.signMessage({ message: paymentTx });
+      pending = {
+        tx: paymentTx,
+        header: Buffer.from(JSON.stringify({ txHash: paymentTx, signature })).toString("base64"),
+      };
+      pendingInference.set(pendingKey, pending);
+    }
+    // A cold endpoint holds the request through provisioning; when it answers
+    // 503 instead, the payment is not consumed and the same header retries.
+    const deadline = Date.now() + 600_000;
+    for (;;) {
+      const res = await fetch(`${base}/v1/inference`, {
+        method: "POST",
+        headers: { "content-type": "application/json", "x-payment": pending.header },
+        body: JSON.stringify({ model, prompt: args.prompt }),
+        signal: AbortSignal.timeout(620_000),
+      });
+      const body = await res.json().catch(() => null);
+      if (res.status === 200 && body) {
+        pendingInference.delete(pendingKey);
+        return { ...body, paid: usdg(price), payment_tx: pending.tx };
+      }
+      const last = body?.detail ?? body?.error ?? `status ${res.status}`;
+      // 503 means the box is warming; a 402 for a payment that is merely too
+      // young (confirmations still landing, receipt not yet visible) heals by
+      // itself. Everything else is final.
+      const retryable =
+        res.status === 503 ||
+        (res.status === 402 && ["insufficient_confirmations", "tx_not_found"].includes(body?.error));
+      if (!retryable || Date.now() > deadline) {
+        throw new Error(
+          `inference failed: ${last}. The payment (tx ${pending.tx}) was not consumed and is kept; the next prism_infer call retries with it instead of paying again.`,
+        );
+      }
+      await new Promise((r) => setTimeout(r, 15_000));
+    }
+  }
   if (name === "prism_lease_and_run" || name === "prism_lease") {
-    if (name === "prism_lease_and_run" && !args.command) throw new Error("command is required");
+    if (name === "prism_lease_and_run") requireCommand(args.command);
     requireWallet(name);
-    await ensureAuth();
+    const cap = maxDeposit(args);
     sweepExpiredLeases();
     const lease = await agent.lease({
       image: IMAGE,
       durationSeconds: args.duration_seconds ?? 900,
       minVramMib: args.min_vram_mib ?? 16000,
+      maxDeposit: cap,
       minTrustClass: args.min_trust_class ?? "open",
     });
     leases.set(lease.leaseId, lease);
     const summary = {
       lease_id: lease.leaseId,
+      funding_tx: lease.fundingHash,
       ssh: { host: lease.access.ssh_host, port: lease.access.ssh_port, user: lease.access.ssh_user },
       trust: lease.quote?.trust_class ?? "open",
       expires_at: lease.access.expires_at,
     };
     if (name === "prism_lease") return summary;
-    const out = await agent.run(lease, args.command);
-    return { ...summary, command: args.command, exit_code: out.code, stdout: out.stdout, stderr: out.stderr };
+    // The lease is paid for by this point; an SSH failure must still hand the
+    // caller everything it bought.
+    try {
+      const out = await agent.run(lease, args.command);
+      return { ...summary, command: args.command, exit_code: out.code, stdout: out.stdout, stderr: out.stderr };
+    } catch (err) {
+      return {
+        ...summary,
+        error: `the lease is funded but the command could not run: ${err?.message ?? err}`,
+        next: `the lease stays open; try prism_run with lease_id ${lease.leaseId}, or prism_end_lease`,
+      };
+    }
   }
   if (name === "prism_run") {
-    if (!args.command) throw new Error("command is required");
+    requireCommand(args.command);
     const id = leaseId(args.lease_id);
     const lease = leases.get(id);
     if (!lease) throw new Error(`no active lease ${id} in this session`);
+    const timeoutSeconds = args.timeout_seconds ?? 120;
     const out = await agent.run(lease, args.command, {
-      timeoutMs: (args.timeout_seconds ?? 120) * 1000,
+      timeoutMs: timeoutSeconds * 1000,
+      connectRetries: 6,
     });
     return { lease_id: id, exit_code: out.code, stdout: out.stdout, stderr: out.stderr };
   }
@@ -380,14 +525,13 @@ async function handle(name, args) {
     return { lease_id: id, released: Boolean(lease) };
   }
   if (name.startsWith("prism_vault_")) return handleVault(name, args);
-  throw new Error(`unknown tool ${name}`);
+  throw new Error(`unknown tool ${name}. Valid tools: ${TOOLS.map((t) => t.name).join(", ")}`);
 }
 
 // The vault key is derived here from the wallet signature and stays in this
 // process. Nothing in this function sends a key or a plaintext to Prism.
 async function handleVault(name, args) {
-  const vault = requireWallet(name).vault;
-  await ensureAuth();
+  const vault = requireWallet(name, "derives the vault key from the wallet").vault;
   if (!vault.unlocked) await vault.unlock();
 
   if (name === "prism_vault_store") {
@@ -433,23 +577,26 @@ async function handleVault(name, args) {
   throw new Error(`unknown tool ${name}`);
 }
 
-let authPromise = null;
-function ensureAuth() {
-  authPromise ??= agent.authenticate().catch((err) => {
-    authPromise = null;
-    throw err;
-  });
-  return authPromise;
-}
-
-const server = new Server({ name: "prism", version: "0.5.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "prism", version: "0.7.0" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   try {
     const result = await handle(request.params.name, request.params.arguments ?? {});
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
   } catch (err) {
-    return { isError: true, content: [{ type: "text", text: `error: ${err.message ?? err}` }] };
+    const body = err?.body ?? {};
+    const detail = [
+      body.cause,
+      body.hint,
+      body.required != null ? `required ${body.required}` : null,
+      body.max != null ? `cap ${body.max}` : null,
+      body.lease_id != null ? `lease_id ${body.lease_id}` : null,
+      body.funding_hash ? `funding_tx ${body.funding_hash}` : null,
+    ]
+      .filter(Boolean)
+      .join("; ");
+    const text = `error: ${err?.message ?? err}${detail ? ` (${detail})` : ""}`;
+    return { isError: true, content: [{ type: "text", text }] };
   }
 });