@prismnetwork/mcp 0.9.0 → 0.9.2

package/README.md

@@ -17,6 +17,7 @@ real prices. Leasing spends money, so those tools ask for a wallet and say so.
 
 | Tool | Wallet |
 | --- | --- |
+| `prism_budget` | no |
 | `prism_list_gpus` | no |
 | `prism_price_index` | no |
 | `prism_receipts` | no |
@@ -37,6 +38,8 @@ real prices. Leasing spends money, so those tools ask for a wallet and say so.
 | `prism_vault_delete` | yes |
 | `prism_vault_release` | yes |
 
+- `prism_budget`: the spending limits this server enforces, what it has spent
+  in the last 24 hours, and the recent charges.
 - `prism_wallet`: the agent's address and USDG/ETH balances.
 - `prism_list_gpus`: GPUs available to lease, with price per second and per hour.
 - `prism_price_index`: sourced and settled pricing per GPU model, for cost estimates.
@@ -66,6 +69,9 @@ real prices. Leasing spends money, so those tools ask for a wallet and say so.
   terminates.
 - `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.
+  The SSH block carries `host_key_fingerprint` and `host_key_claim` when the
+  network can say which machine should answer, and says so plainly when it
+  cannot. Check it before connecting by hand; `prism_run` checks it for you.
 - `prism_run`: run a command on an existing lease.
 - `prism_batch_run`: fund a lease that runs one command with no interactive
   access; the node reports the signed output. Matches only suppliers at trust
@@ -77,6 +83,33 @@ real prices. Leasing spends money, so those tools ask for a wallet and say so.
 - `prism_vault_delete`: permanently delete an item.
 - `prism_vault_release`: authorize an item into a lease that clears its trust floor.
 
+## Spending limits
+
+Two ceilings bound what this server can spend, and a refusal quotes both.
+
+| Variable | Default | What it bounds |
+| --- | --- | --- |
+| `PRISM_MAX_USDG` | 1 | Any single lease or generation. `max_usdg` on a call may lower it, never raise it past this. |
+| `PRISM_DAILY_BUDGET_USDG` | 5 | Everything in a rolling 24 hours. `0` removes the ceiling. |
+| `PRISM_LEDGER_PATH` | `~/.prism/spend.json` | Where the spend is recorded. |
+
+A `max_usdg` above `PRISM_MAX_USDG` is clamped back to it. The argument is
+written by the agent being bounded, so it is treated as a request for a lower
+ceiling and never as permission for a higher one.
+
+Spend is written before the money moves, so a crash between funding an escrow
+and answering is counted rather than forgiven, and a restart does not hand back
+a fresh day's allowance. Only an attempt that provably never reached the chain
+is reverted. Two clients pointed at one wallet share one ceiling, because they
+share the ledger file.
+
+None of this is the real limit. Fund a dedicated wallet with what you are
+willing to lose: that balance is what survives a bug in everything above.
+
+Tools that spend are annotated `destructiveHint` and carry
+`anthropic/requiresUserInteraction`, so Claude Code asks before every one of
+them even in modes that otherwise approve tools automatically.
+
 ## Vault
 
 An agent that handles a card, an identity document or a credential should not
@@ -102,7 +135,7 @@ Point your MCP client (Claude Desktop / Code) at the published server:
       "args": ["-y", "@prismnetwork/mcp"],
       "env": {
         "PRISM_AGENT_KEY": "0x<agent wallet private key>",
-        "PRISM_ESCROW": "0x62C042265991bEa17B07229322A01850974626dA"
+        "PRISM_ESCROW": "0xfD4228eEEfC49e4b76A0CD40af9fdd546220B2FD"
       }
     }
   }
@@ -115,7 +148,7 @@ Or add it to Claude Code in one line:
 
 ```sh
 claude mcp add prism \
-  --env PRISM_ESCROW=0x62C042265991bEa17B07229322A01850974626dA \
+  --env PRISM_ESCROW=0xfD4228eEEfC49e4b76A0CD40af9fdd546220B2FD \
   --env PRISM_AGENT_KEY=0x<agent wallet private key> \
   -- npx -y @prismnetwork/mcp
 ```

package/budget.mjs

@@ -0,0 +1,316 @@
+// What stands between a model deciding to rent a GPU and a wallet paying for it.
+// The real ceiling is the balance; fund the agent wallet with what you are
+// willing to lose. This is the second line, and it exists because `max_usdg`
+// never was one: it bounds a single lease and says nothing about the fortieth in
+// a row, which is what an unattended agent actually does.
+//
+// Spend is written before the money moves and reverted only when the attempt
+// provably cost nothing, so a crash between funding and reply is counted rather
+// than forgiven. The file is shared across clients on purpose: one wallet gets
+// one daily ceiling whoever is holding it.
+import { mkdirSync, readFileSync, renameSync, writeFileSync, openSync, closeSync, unlinkSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const MICROS = 1_000_000;
+const DAY_MS = 86_400_000;
+// Entries older than this are dropped on write. Two days covers the rolling
+// window with room for a clock that stepped backwards.
+const MEMORY_MS = 2 * DAY_MS;
+const LOCK_STALE_MS = 15_000;
+const LOCK_WAIT_MS = 5_000;
+
+export class BudgetError extends Error {
+  constructor(message, detail = {}) {
+    super(message);
+    this.name = "BudgetError";
+    this.detail = detail;
+  }
+}
+
+export const usdg = (micros) => `${(Number(micros) / MICROS).toFixed(6)} USDG`;
+
+function positiveNumber(raw, fallback, name) {
+  if (raw === undefined || raw === null || String(raw).trim() === "") return fallback;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || value < 0) {
+    throw new BudgetError(`${name} must be a non-negative number of USDG, got ${JSON.stringify(raw)}`);
+  }
+  return value;
+}
+
+// One .mcp.json serves every client, and they disagree about templates: Claude
+// Code expands ${user_config.x} before launch, Codex passes it through. Reading
+// the literal template as a value would turn "no wallet configured" into
+// "wallet configured and broken", so an unexpanded placeholder is nothing.
+export function stripUnexpanded(env = process.env) {
+  for (const [key, value] of Object.entries(env)) {
+    if (key.startsWith("PRISM_") && /^\$\{[^}]*\}$/.test(String(value ?? "").trim())) delete env[key];
+  }
+  return env;
+}
+
+export function defaultLedgerPath(env = process.env) {
+  if (env.PRISM_LEDGER_PATH) return env.PRISM_LEDGER_PATH;
+  return join(env.HOME || homedir(), ".prism", "spend.json");
+}
+
+// A missing budget is not an unlimited one. The default is deliberately small:
+// enough for a handful of real leases, cheap enough that discovering the plugin
+// spends money costs about the price of a coffee rather than a rent cheque.
+export function readBudget(env = process.env) {
+  const maxPerCall = positiveNumber(env.PRISM_MAX_USDG, 1, "PRISM_MAX_USDG");
+  const daily = positiveNumber(env.PRISM_DAILY_BUDGET_USDG, 5, "PRISM_DAILY_BUDGET_USDG");
+  if (maxPerCall <= 0) throw new BudgetError("PRISM_MAX_USDG must be above zero");
+  // A per-call cap above the day's allowance is a cap in name only, and the
+  // mismatch is always a configuration mistake rather than an intention.
+  if (daily > 0 && maxPerCall > daily) {
+    throw new BudgetError(
+      `PRISM_MAX_USDG (${maxPerCall}) cannot exceed PRISM_DAILY_BUDGET_USDG (${daily}); lower the per-call cap or raise the daily one`,
+    );
+  }
+  return {
+    maxPerCallMicros: Math.round(maxPerCall * MICROS),
+    // Zero means the operator explicitly removed the daily ceiling. It is not
+    // the default and it is not what a missing variable produces.
+    dailyMicros: Math.round(daily * MICROS),
+    ledgerPath: defaultLedgerPath(env),
+  };
+}
+
+// What a single call is allowed to spend, given what it asked for. The caller's
+// figure is written by the thing being bounded, so it lowers the operator's
+// ceiling and can never lift it.
+export function callCeiling(maxUsdg, ceilingMicros) {
+  if (maxUsdg === undefined || maxUsdg === null) return ceilingMicros;
+  if (typeof maxUsdg !== "number" || !Number.isFinite(maxUsdg) || maxUsdg <= 0) {
+    throw new BudgetError("max_usdg must be a positive number of USDG.");
+  }
+  return Math.min(Math.round(maxUsdg * MICROS), ceilingMicros);
+}
+
+// A lock rather than last-write-wins, because two clients sharing one wallet is
+// the case this file exists for. A lock older than LOCK_STALE_MS belonged to a
+// process that died; breaking it is safe and not breaking it wedges the wallet.
+function withLock(path, fn, waitMs = LOCK_WAIT_MS) {
+  const lock = `${path}.lock`;
+  mkdirSync(dirname(path), { recursive: true });
+  const deadline = Date.now() + waitMs;
+  for (;;) {
+    let fd;
+    try {
+      fd = openSync(lock, "wx");
+    } catch (err) {
+      if (err?.code !== "EEXIST") throw err;
+      let age = 0;
+      try {
+        age = Date.now() - statSync(lock).mtimeMs;
+      } catch {
+        continue; // it vanished between the open and the stat; retry immediately
+      }
+      if (age > LOCK_STALE_MS) {
+        try {
+          unlinkSync(lock);
+        } catch {
+          /* another process broke it first, which is the outcome we wanted */
+        }
+        continue;
+      }
+      if (Date.now() > deadline) {
+        throw new BudgetError(
+          `the spend ledger at ${path} is locked by another Prism process; nothing was charged. Retry in a moment.`,
+        );
+      }
+      // Busy-wait deliberately: this holds for milliseconds and the alternative
+      // is making every caller of a synchronous ledger asynchronous.
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+      continue;
+    }
+    try {
+      closeSync(fd);
+      return fn();
+    } finally {
+      try {
+        unlinkSync(lock);
+      } catch {
+        /* already gone */
+      }
+    }
+  }
+}
+
+function readState(path) {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (!parsed || !Array.isArray(parsed.entries)) return { entries: [] };
+    return { entries: parsed.entries.filter((e) => e && Number.isFinite(e.at) && Number.isFinite(e.micros)) };
+  } catch (err) {
+    if (err?.code === "ENOENT") return { entries: [] };
+    // A corrupt ledger must not read as an empty one: that would hand the
+    // caller a fresh day's budget every time the file got truncated.
+    throw new BudgetError(
+      `the spend ledger at ${path} is unreadable (${err?.message ?? err}), so spending is refused. Move or repair the file.`,
+    );
+  }
+}
+
+function writeState(path, state, now) {
+  const entries = state.entries.filter((e) => now - e.at < MEMORY_MS);
+  const tmp = `${path}.${process.pid}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify({ version: 1, entries }, null, 2)}\n`, { mode: 0o600 });
+  renameSync(tmp, path);
+}
+
+export function spentInWindow(entries, now) {
+  return entries.reduce((total, e) => (now - e.at < DAY_MS ? total + e.micros : total), 0);
+}
+
+export class SpendLedger {
+  constructor({ ledgerPath, dailyMicros, maxPerCallMicros, lockWaitMs = LOCK_WAIT_MS }) {
+    this.path = ledgerPath;
+    this.dailyMicros = dailyMicros;
+    this.maxPerCallMicros = maxPerCallMicros;
+    this.lockWaitMs = lockWaitMs;
+  }
+
+  // What is left of today, for the caller to show before it asks to spend.
+  remaining(now = Date.now()) {
+    if (this.dailyMicros <= 0) return null;
+    const { entries } = readState(this.path);
+    return Math.max(0, this.dailyMicros - spentInWindow(entries, now));
+  }
+
+  status(now = Date.now()) {
+    const { entries } = readState(this.path);
+    const spent = spentInWindow(entries, now);
+    return {
+      daily_budget: this.dailyMicros > 0 ? usdg(this.dailyMicros) : "unlimited (PRISM_DAILY_BUDGET_USDG=0)",
+      spent_last_24h: usdg(spent),
+      remaining_today: this.dailyMicros > 0 ? usdg(Math.max(0, this.dailyMicros - spent)) : "unlimited",
+      max_per_call: usdg(this.maxPerCallMicros),
+      ledger: this.path,
+      charges_last_24h: entries
+        .filter((e) => now - e.at < DAY_MS)
+        .sort((a, b) => b.at - a.at)
+        .slice(0, 20)
+        .map((e) => ({
+          at: new Date(e.at).toISOString(),
+          tool: e.tool,
+          amount: usdg(e.micros),
+          ...(e.reference ? { reference: e.reference } : {}),
+        })),
+    };
+  }
+
+  // Records the spend before the money moves. Returns a handle the caller
+  // reverts only when it can prove nothing was charged.
+  commit({ tool, micros, now = Date.now() }) {
+    if (!Number.isFinite(micros) || micros <= 0) {
+      throw new BudgetError("a spend must be a positive number of micros");
+    }
+    if (micros > this.maxPerCallMicros) {
+      throw new BudgetError(
+        `${tool} would commit up to ${usdg(micros)}, past the ${usdg(this.maxPerCallMicros)} per-call cap. ` +
+          `Lower max_usdg for this call, or raise PRISM_MAX_USDG.`,
+        { required: micros, cap: this.maxPerCallMicros },
+      );
+    }
+    return withLock(
+      this.path,
+      () => {
+        const state = readState(this.path);
+        const spent = spentInWindow(state.entries, now);
+        if (this.dailyMicros > 0 && spent + micros > this.dailyMicros) {
+          throw new BudgetError(
+            `${tool} would take today's Prism spend to ${usdg(spent + micros)}, past the ${usdg(this.dailyMicros)} ` +
+              `daily cap (${usdg(spent)} already spent). Nothing was charged. Raise PRISM_DAILY_BUDGET_USDG to continue.`,
+            { spent, requested: micros, cap: this.dailyMicros },
+          );
+        }
+        const id = `${now.toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+        state.entries.push({ id, at: now, tool, micros });
+        writeState(this.path, state, now);
+        return id;
+      },
+      this.lockWaitMs,
+    );
+  }
+
+  // Only for an attempt that provably cost nothing. A funded lease whose command
+  // failed is not one of those.
+  revert(id) {
+    if (!id) return false;
+    return withLock(this.path, () => {
+      const state = readState(this.path);
+      const before = state.entries.length;
+      state.entries = state.entries.filter((e) => e.id !== id);
+      if (state.entries.length === before) return false;
+      writeState(this.path, state, Date.now());
+      return true;
+    }, this.lockWaitMs);
+  }
+
+  // Replaces the reserved figure with what was actually committed on-chain and
+  // pins the receipt to it, so the ledger reads like a statement rather than a
+  // list of intentions.
+  //
+  // A payment the endpoint never consumed is redeemed by the next attempt at the
+  // same request, so one transaction can settle more than one reservation.
+  // Booking each would charge the day twice for money that moved once: a
+  // reference already on file keeps its entry and this one is released.
+  settle(id, { micros, reference } = {}) {
+    if (!id) return false;
+    return withLock(this.path, () => {
+      const state = readState(this.path);
+      const entry = state.entries.find((e) => e.id === id);
+      if (!entry) return false;
+      const booked = reference ? state.entries.find((e) => e.id !== id && e.reference === reference) : undefined;
+      const target = booked ?? entry;
+      if (Number.isFinite(micros) && micros >= 0) target.micros = micros;
+      if (reference) target.reference = reference;
+      if (booked) state.entries = state.entries.filter((e) => e.id !== id);
+      writeState(this.path, state, Date.now());
+      return true;
+    }, this.lockWaitMs);
+  }
+}
+
+/// Records a spend before the money moves, then reconciles it against what
+/// happened. A failure that never reached the chain is given back; anything
+/// that funded an escrow or paid an endpoint keeps its entry and gains the
+/// transaction that proves it, because a ledger that forgets a spend is worse
+/// than no ledger at all.
+export async function recordSpend(book, tool, micros, run) {
+  const id = book.commit({ tool, micros });
+  // Reconciling is bookkeeping and must never be the reason a caller loses a
+  // machine it paid for, or the reason a failure is reported as the wrong
+  // failure. A ledger that cannot be written says so on stderr and the
+  // committed figure stands, which errs towards counting the spend.
+  const reconcile = (action, ...args) => {
+    try {
+      book[action](id, ...args);
+    } catch (err) {
+      console.error(`prism mcp: could not ${action} the ledger entry for ${tool}: ${err?.message ?? err}`);
+    }
+  };
+  try {
+    const { value, settledMicros, reference } = await run();
+    reconcile("settle", { micros: settledMicros, reference });
+    return value;
+  } catch (err) {
+    const paid = err?.body?.funding_hash ?? err?.body?.payment_tx;
+    if (paid) {
+      reconcile("settle", { reference: paid });
+    } else if (err?.code === "chain_error") {
+      // Signed, broadcast, and then something went wrong reading it back, which
+      // is not the same as never having reached the chain. Handing the
+      // reservation back would let one wallet fund escrow after escrow through
+      // an rpc having a bad hour while the day's ceiling reported nothing
+      // spent, so the entry stands at what it reserved.
+      reconcile("settle");
+    } else {
+      reconcile("revert");
+    }
+    throw err;
+  }
+}

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@prismnetwork/mcp",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "MCP server for leasing and running on Prism Network GPUs.",
-  "mcpName": "io.github.prismnetwork-tech/mcp",
+  "mcpName": "io.github.winter0x/mcp",
   "type": "module",
   "bin": {
     "prism-mcp": "server.mjs"
   },
   "files": [
+    "budget.mjs",
     "server.mjs",
     "README.md"
   ],
@@ -17,7 +18,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@phala/dcap-qvl": "^0.6.1",
-    "@prismnetwork/agent-sdk": "^0.7.0",
+    "@prismnetwork/agent-sdk": "^0.7.3",
     "jose": "^6",
     "viem": "^2"
   },
@@ -32,14 +33,17 @@
   "homepage": "https://prismnetwork.tech",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/prismnetwork-tech/prism.git",
+    "url": "git+https://github.com/winter0x/prism.git",
     "directory": "mcp"
   },
   "bugs": {
-    "url": "https://github.com/prismnetwork-tech/prism/issues"
+    "url": "https://github.com/winter0x/prism/issues"
   },
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "test": "node --test"
   }
 }

package/server.mjs

@@ -9,17 +9,21 @@ import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprot
 import {
   DEFAULT_IMAGE,
   DEFAULT_TRUST_FLOOR,
+  hostKeyPolicy,
   PrismAgent,
   TRUST_CLASSES,
   verifyConfidential,
 } from "@prismnetwork/agent-sdk";
+import { BudgetError, SpendLedger, callCeiling, readBudget, recordSpend, stripUnexpanded } from "./budget.mjs";
+
+stripUnexpanded(process.env);
 
 const IMAGE = process.env.PRISM_DEFAULT_IMAGE ?? DEFAULT_IMAGE;
 
 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";
+const DEFAULT_ESCROW = "0xfD4228eEEfC49e4b76A0CD40af9fdd546220B2FD";
 // 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;
@@ -48,6 +52,18 @@ if (!agent) {
   );
 }
 
+// A budget the operator got wrong must stop spending, not fall back to none.
+// Reading capacity and prices is unaffected, so a typo is discoverable rather
+// than fatal.
+let ledger = null;
+let budgetProblem = null;
+try {
+  ledger = new SpendLedger(readBudget());
+} catch (err) {
+  budgetProblem = err?.message ?? String(err);
+  console.error(`prism mcp: ${budgetProblem}`);
+}
+
 function requireWallet(tool, reason = "spends money") {
   if (!agent) {
     throw new Error(
@@ -57,6 +73,17 @@ function requireWallet(tool, reason = "spends money") {
   return agent;
 }
 
+function requireLedger(tool) {
+  if (!ledger) {
+    throw new Error(`${tool} needs the spend limits, and they are unusable: ${budgetProblem}`);
+  }
+  return ledger;
+}
+
+// The ledger has to be usable before anything is spent, and the refusal names
+// the tool that asked.
+const spending = (tool, micros, run) => recordSpend(requireLedger(tool), tool, micros, run);
+
 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'.");
@@ -67,12 +94,29 @@ function requireCommand(value) {
   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);
+// What the caller can check the machine against if they open their own session.
+// A lease that publishes nothing says so, rather than leaving the field out and
+// letting its absence read as "fine".
+function hostKey(access) {
+  const policy = hostKeyPolicy(access);
+  return policy.fingerprint === null
+    ? { host_key: "unpublished: this lease cannot tell you which machine answers" }
+    : { host_key_fingerprint: policy.fingerprint, host_key_claim: policy.mode };
+}
+
+// What the escrow actually holds, which is what the day's budget should count.
+// Booking the caller's ceiling instead charged a 0.2 USDG lease against a 0.5
+// USDG cap, so a 5 USDG day bought ten leases where it could afford twenty-five.
+function escrowed(quote) {
+  const held = Number(quote?.maximum_escrow);
+  return Number.isFinite(held) && held > 0 ? held : undefined;
+}
+
+// The per-call ceiling is the operator's, not the model's: an omitted max_usdg
+// takes PRISM_MAX_USDG rather than a hardcoded number, and a stated one above it
+// is clamped back down to it.
+function maxDeposit(tool, args) {
+  return callCeiling(args.max_usdg, requireLedger(tool).maxPerCallMicros);
 }
 
 const PROOF_FEED = process.env.PRISM_PROOF_URL ?? "https://prismnetwork.tech/api/proof";
@@ -129,13 +173,14 @@ async function inferenceOffer(base, requested) {
   return { offer, model, unit: BigInt(offer.price_micros ?? 0) };
 }
 
-function withinCap(price, maxUsdg, fallback, what) {
-  const cap = maxUsdg ?? fallback;
-  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)} ${what}, past the ${cap} USDG cap.`);
+// The quoted price against the lower of what this call asked for and what the
+// operator allows, so the refusal names whichever ceiling stopped it.
+function withinCap(tool, price, maxUsdg, fallback, what) {
+  const operator = requireLedger(tool).maxPerCallMicros;
+  const cap = callCeiling(maxUsdg ?? fallback, operator);
+  if (price <= 0n || price > BigInt(cap)) {
+    const named = cap === operator ? "PRISM_MAX_USDG" : "max_usdg";
+    throw new Error(`the endpoint quotes ${usdg(price)} ${what}, past the ${named} cap of ${usdg(cap)}.`);
   }
 }
 
@@ -156,11 +201,28 @@ function leaseId(value) {
   return id;
 }
 
+// Hints a client uses to decide what it may run unattended. `reads` is anything
+// that cannot change state or move money; `spends` is anything that can, and it
+// carries the Claude Code marker that forces a confirmation prompt on every call
+// even in modes that otherwise auto-approve.
+const reads = { readOnlyHint: true, openWorldHint: true };
+const spends = {
+  annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
+  _meta: { "anthropic/requiresUserInteraction": true },
+};
+
 const TOOLS = [
+  {
+    name: "prism_budget",
+    description: "Show the spending limits this server enforces and what it has already spent in the last 24 hours, with the recent charges. Needs no wallet. Check this before a long job; a lease refused for budget says the same numbers.",
+    inputSchema: { type: "object", properties: {} },
+    annotations: { title: "Spending limits", readOnlyHint: true, openWorldHint: false },
+  },
   {
     name: "prism_wallet",
     description: "Show the agent's wallet address and on-chain balances (USDG and ETH for gas) on Robinhood Chain. Check this before leasing to confirm the wallet can pay.",
     inputSchema: { type: "object", properties: {} },
+    annotations: { title: "Wallet balances", ...reads },
   },
   {
     name: "prism_list_gpus",
@@ -175,11 +237,13 @@ const TOOLS = [
         },
       },
     },
+    annotations: { title: "Available GPUs", ...reads },
   },
   {
     name: "prism_price_index",
     description: "Current GPU pricing on Prism Network by model: sourced low/median/high and settled mean, in USDG per hour. Needs no wallet. Use it to estimate what an analysis job will cost before leasing.",
     inputSchema: { type: "object", properties: {} },
+    annotations: { title: "GPU price index", ...reads },
   },
   {
     name: "prism_receipts",
@@ -190,11 +254,13 @@ const TOOLS = [
         limit: { type: "integer", description: "Max receipts to return (default 10, max 50)." },
       },
     },
+    annotations: { title: "Settled receipts", ...reads },
   },
   {
     name: "prism_leases",
     description: "List this wallet's leases on Prism Network with their current state.",
     inputSchema: { type: "object", properties: {} },
+    annotations: { title: "Your leases", ...reads },
   },
   {
     name: "prism_batch_run",
@@ -205,10 +271,12 @@ const TOOLS = [
         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." },
+        max_usdg: { type: "number", description: "Cost ceiling for this lease in USDG. It lowers the operator's PRISM_MAX_USDG and cannot raise it; omitted, that ceiling applies. See prism_budget." },
       },
       required: ["command"],
     },
+    ...spends,
+    annotations: { title: "Rent a GPU for one command", ...spends.annotations },
   },
   {
     name: "prism_batch_result",
@@ -220,6 +288,7 @@ const TOOLS = [
       },
       required: ["lease_id"],
     },
+    annotations: { title: "Batch result", ...reads },
   },
   {
     name: "prism_infer",
@@ -229,10 +298,12 @@ const TOOLS = [
       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)." },
+        max_usdg: { type: "number", description: "Refuse if the quoted price exceeds this (default 0.05). The operator's PRISM_MAX_USDG binds it either way." },
       },
       required: ["prompt"],
     },
+    ...spends,
+    annotations: { title: "Buy one LLM generation", ...spends.annotations },
   },
   {
     name: "prism_infer_batch",
@@ -248,10 +319,12 @@ const TOOLS = [
           description: "Independent prompts, answered in the order given (each 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 total exceeds this (default 0.5)." },
+        max_usdg: { type: "number", description: "Refuse if the quoted total exceeds this (default 0.5). The operator's PRISM_MAX_USDG binds it either way." },
       },
       required: ["prompts"],
     },
+    ...spends,
+    annotations: { title: "Buy many LLM generations", ...spends.annotations },
   },
   {
     name: "prism_confidential_infer",
@@ -262,11 +335,13 @@ const TOOLS = [
         prompt: { type: "string", description: "The prompt to generate from." },
         model: { type: "string", description: "Confidential model to use; defaults to the endpoint's first." },
         max_tokens: { type: "integer", description: "Cap on generated tokens (default 512). The price is quoted against this cap." },
-        max_usdg: { type: "number", description: "Refuse if the quoted price exceeds this (default 0.25)." },
+        max_usdg: { type: "number", description: "Refuse if the quoted price exceeds this (default 0.25). The operator's PRISM_MAX_USDG binds it either way." },
         e2ee: { type: "boolean", description: "Encrypt message contents to the attested enclave key (default true). Turn it off only when the relay is allowed to read the prompt." },
       },
       required: ["prompt"],
     },
+    ...spends,
+    annotations: { title: "Buy one confidential LLM generation", ...spends.annotations },
   },
   {
     name: "prism_verify_attestation",
@@ -279,6 +354,7 @@ const TOOLS = [
       },
       required: ["receipt_id"],
     },
+    annotations: { title: "Check a confidential generation", ...reads },
   },
   {
     name: "prism_lease_and_run",
@@ -294,10 +370,12 @@ 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." },
+        max_usdg: { type: "number", description: "Cost ceiling for this lease in USDG. It lowers the operator's PRISM_MAX_USDG and cannot raise it; omitted, that ceiling applies. See prism_budget." },
       },
       required: ["command"],
     },
+    ...spends,
+    annotations: { title: "Rent a GPU and run a command", ...spends.annotations },
   },
   {
     name: "prism_lease",
@@ -312,9 +390,11 @@ 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." },
+        max_usdg: { type: "number", description: "Cost ceiling for this lease in USDG. It lowers the operator's PRISM_MAX_USDG and cannot raise it; omitted, that ceiling applies. See prism_budget." },
       },
     },
+    ...spends,
+    annotations: { title: "Rent a GPU", ...spends.annotations },
   },
   {
     name: "prism_run",
@@ -328,6 +408,7 @@ const TOOLS = [
       },
       required: ["lease_id", "command"],
     },
+    annotations: { title: "Run a command on a lease", readOnlyHint: false, destructiveHint: true, openWorldHint: true },
   },
   {
     name: "prism_end_lease",
@@ -337,6 +418,7 @@ const TOOLS = [
       properties: { lease_id: { type: "integer" } },
       required: ["lease_id"],
     },
+    annotations: { title: "Release a lease", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
   },
   {
     name: "prism_vault_store",
@@ -354,11 +436,13 @@ const TOOLS = [
       },
       required: ["value"],
     },
+    annotations: { title: "Seal a secret", readOnlyHint: false, destructiveHint: false, openWorldHint: true },
   },
   {
     name: "prism_vault_list",
     description: "List the agent's sealed vault items: item_id, label, version and trust floor. Values are not returned and are not readable by Prism.",
     inputSchema: { type: "object", properties: {} },
+    annotations: { title: "List sealed items", ...reads },
   },
   {
     name: "prism_vault_read",
@@ -368,6 +452,8 @@ const TOOLS = [
       properties: { item_id: { type: "string", description: "The item_id from prism_vault_store or prism_vault_list." } },
       required: ["item_id"],
     },
+    _meta: { "anthropic/requiresUserInteraction": true },
+    annotations: { title: "Decrypt one sealed item", readOnlyHint: true, openWorldHint: true },
   },
   {
     name: "prism_vault_delete",
@@ -377,6 +463,8 @@ const TOOLS = [
       properties: { item_id: { type: "string" } },
       required: ["item_id"],
     },
+    ...spends,
+    annotations: { title: "Delete a sealed item", ...spends.annotations },
   },
   {
     name: "prism_vault_release",
@@ -389,10 +477,13 @@ const TOOLS = [
       },
       required: ["item_id", "lease_id"],
     },
+    ...spends,
+    annotations: { title: "Release a secret into a lease", ...spends.annotations },
   },
 ];
 
 async function handle(name, args) {
+  if (name === "prism_budget") return requireLedger(name).status();
   if (name === "prism_wallet") {
     const b = await requireWallet("prism_wallet").balances();
     return { address: b.address, usdg: usdg(b.usdg), eth_wei: b.eth };
@@ -483,22 +574,28 @@ async function handle(name, args) {
   if (name === "prism_batch_run") {
     requireCommand(args.command);
     requireWallet(name);
-    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,
+    const cap = maxDeposit(name, args);
+    return spending(name, cap, async () => {
+      const batch = await agent.lease({
+        image: IMAGE,
+        durationSeconds: args.duration_seconds ?? 900,
+        minVramMib: args.min_vram_mib ?? 16000,
+        maxDeposit: cap,
+        command: args.command,
+      });
+      return {
+        reference: batch.fundingHash,
+        settledMicros: escrowed(batch.quote),
+        value: {
+          lease_id: batch.leaseId,
+          funding_tx: batch.fundingHash,
+          exit_code: batch.result?.exit_code,
+          stdout: batch.result?.stdout,
+          stderr: batch.result?.stderr,
+          truncated: batch.result?.truncated ?? false,
+        },
+      };
     });
-    return {
-      lease_id: batch.leaseId,
-      funding_tx: batch.fundingHash,
-      exit_code: batch.result?.exit_code,
-      stdout: batch.result?.stdout,
-      stderr: batch.result?.stderr,
-      truncated: batch.result?.truncated ?? false,
-    };
   }
   if (name === "prism_batch_result") {
     requireWallet(name, "reads this wallet's leases");
@@ -512,14 +609,17 @@ async function handle(name, args) {
     requireWallet(name);
     const base = inferenceBase();
     const { offer, model, unit } = await inferenceOffer(base, args.model);
-    withinCap(unit, args.max_usdg, 0.05, "per generation");
-    return payAndPost({
-      base,
-      path: "/v1/inference",
-      price: unit,
-      payTo: offer.pay_to,
-      body: { model, prompt: args.prompt },
-      tool: "prism_infer",
+    withinCap(name, unit, args.max_usdg, 0.05, "per generation");
+    return spending(name, Number(unit), async () => {
+      const value = await payAndPost({
+        base,
+        path: "/v1/inference",
+        price: unit,
+        payTo: offer.pay_to,
+        body: { model, prompt: args.prompt },
+        tool: "prism_infer",
+      });
+      return { value, settledMicros: Number(unit), reference: value.payment_tx };
     });
   }
   if (name === "prism_infer_batch") {
@@ -537,14 +637,17 @@ async function handle(name, args) {
     const base = inferenceBase();
     const { offer, model, unit } = await inferenceOffer(base, args.model);
     const price = unit * BigInt(prompts.length);
-    withinCap(price, args.max_usdg, 0.5, `for ${prompts.length} generations`);
-    return payAndPost({
-      base,
-      path: "/v1/batch",
-      price,
-      payTo: offer.pay_to,
-      body: { model, prompts },
-      tool: "prism_infer_batch",
+    withinCap(name, price, args.max_usdg, 0.5, `for ${prompts.length} generations`);
+    return spending(name, Number(price), async () => {
+      const value = await payAndPost({
+        base,
+        path: "/v1/batch",
+        price,
+        payTo: offer.pay_to,
+        body: { model, prompts },
+        tool: "prism_infer_batch",
+      });
+      return { value, settledMicros: Number(price), reference: value.payment_tx };
     });
   }
   if (name === "prism_confidential_infer") {
@@ -553,13 +656,19 @@ async function handle(name, args) {
     }
     requireWallet(name);
     const base = inferenceBase();
-    const run = await agent.confidentialInfer({
-      prompt: args.prompt,
-      model: args.model,
-      maxTokens: args.max_tokens ?? 512,
-      maxUsdg: args.max_usdg ?? 0.25,
-      e2ee: args.e2ee ?? true,
-      endpoint: base,
+    // The endpoint quotes inside the SDK, so the day is charged the ceiling up
+    // front and corrected to the quoted price once the call has been served.
+    const cap = callCeiling(args.max_usdg ?? 0.25, requireLedger(name).maxPerCallMicros);
+    const run = await spending(name, cap, async () => {
+      const served = await agent.confidentialInfer({
+        prompt: args.prompt,
+        model: args.model,
+        maxTokens: args.max_tokens ?? 512,
+        maxUsdg: cap / 1e6,
+        e2ee: args.e2ee ?? true,
+        endpoint: base,
+      });
+      return { value: served, settledMicros: Number(served.priceMicros), reference: served.tx };
     });
     rememberConfidentialCall(run.receiptId, {
       base,
@@ -622,20 +731,32 @@ async function handle(name, args) {
   if (name === "prism_lease_and_run" || name === "prism_lease") {
     if (name === "prism_lease_and_run") requireCommand(args.command);
     requireWallet(name);
-    const cap = maxDeposit(args);
+    const cap = maxDeposit(name, 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",
+    const lease = await spending(name, cap, async () => {
+      const funded = await agent.lease({
+        image: IMAGE,
+        durationSeconds: args.duration_seconds ?? 900,
+        minVramMib: args.min_vram_mib ?? 16000,
+        maxDeposit: cap,
+        minTrustClass: args.min_trust_class ?? "open",
+      });
+      return { value: funded, reference: funded.fundingHash, settledMicros: escrowed(funded.quote) };
     });
     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 },
+      // `prism_run` checks this itself. It is in the summary because the
+      // caller is being handed an address they may connect to by hand, and an
+      // address with no key to check is an invitation to accept whatever
+      // answers.
+      ssh: {
+        host: lease.access.ssh_host,
+        port: lease.access.ssh_port,
+        user: lease.access.ssh_user,
+        ...hostKey(lease.access),
+      },
       trust: lease.quote?.trust_class ?? "open",
       expires_at: lease.access.expires_at,
     };
@@ -734,6 +855,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const result = await handle(request.params.name, request.params.arguments ?? {});
     return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
   } catch (err) {
+    if (err instanceof BudgetError) {
+      return { isError: true, content: [{ type: "text", text: `${err.message} See prism_budget.` }] };
+    }
     const body = err?.body ?? {};
     const detail = [
       body.cause,