@prismnetwork/mcp 0.9.3 → 0.10.0

package/README.md

@@ -76,7 +76,7 @@ real prices. Leasing spends money, so those tools ask for a wallet and say so.
 - `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
   class `isolated` or above, so it can find no supplier when none is online.
-- `prism_end_lease`: release a lease.
+- `prism_end_lease`: release a lease. Billing stops at the release; the unused deposit returns after settlement.
 - `prism_vault_store`: seal private data under the wallet-derived key.
 - `prism_vault_list`: list sealed items; values are never returned.
 - `prism_vault_read`: decrypt one item in this process.
@@ -106,6 +106,32 @@ 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.
 
+## Spend policy
+
+The limits above cap how much an agent spends. A spend policy decides whether a
+given lease has a reason you accept. Set `PRISM_SPEND_POLICY` to the policy as
+JSON, or to the path of a JSON file:
+
+```json
+{
+  "policy_id": "gpu-v1",
+  "allow": ["fine_tune", "benchmark"],
+  "require": ["needs_gpu"],
+  "minimums": { "needs_gpu": 0.8 }
+}
+```
+
+Every lease tool then takes a `decision`: the action, what made the call, and
+typed answers with a confidence from 0 to 1. A decision that misses the policy
+is refused with every reason before anything is quoted, funded or counted
+against the budget. One that passes is hashed into the escrow deposit, so the
+lease on chain carries a reference only that decision reproduces. `prism_budget`
+shows the policy in force. Without `PRISM_SPEND_POLICY` a decision is optional
+and still binds when given.
+
+The binding shows a decision existed before the money moved and met your rules.
+It does not show the decision was sound.
+
 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.

package/budget.mjs

@@ -7,10 +7,25 @@
 // 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";
+// one daily ceiling whoever is holding it, and the Python SDK's `_budget.py`
+// reads and writes the same entries this module does.
+import {
+  closeSync,
+  fsyncSync,
+  mkdirSync,
+  openSync,
+  readFileSync,
+  readlinkSync,
+  realpathSync,
+  renameSync,
+  statSync,
+  unlinkSync,
+  utimesSync,
+  writeSync,
+} from "node:fs";
+import { randomBytes } from "node:crypto";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 
 const MICROS = 1_000_000;
 const DAY_MS = 86_400_000;
@@ -19,6 +34,31 @@ const DAY_MS = 86_400_000;
 const MEMORY_MS = 2 * DAY_MS;
 const LOCK_STALE_MS = 15_000;
 const LOCK_WAIT_MS = 5_000;
+// Above this a USDG figure is a typo or an attack, and multiplying it out is how
+// the arithmetic stops being arithmetic.
+const MAX_CALL_USDG = 1e12;
+// The last instant both languages can name: Python's datetime stops at year
+// 9999 where this one keeps going, so a stamp past this is one only this client
+// could print, and it would sit in the file forever.
+export const MAX_AT_MS = 253_402_300_799_999;
+// One number grammar for both languages. Node's Number() takes "0x10" and
+// Python's float() takes "1_000", and an operator who typed either meant
+// neither. \d is ASCII here and every decimal digit there is in Python, so the
+// range is spelled out: Python reads "٣" as a 3 and no ledger should.
+const DECIMAL = /^[+-]?([0-9]+\.?[0-9]*|\.[0-9]+)([eE][+-]?[0-9]+)?$/;
+// The two languages also disagree about what padding is: trim() takes U+FEFF
+// where Python's strip does not, and Python's takes U+001C where trim() does
+// not. Trimming these four leaves one answer on both sides.
+const PADDING = new Set([" ", "\t", "\r", "\n"]);
+
+function trim(value) {
+  const text = String(value);
+  let start = 0;
+  let end = text.length;
+  while (start < end && PADDING.has(text[start])) start += 1;
+  while (end > start && PADDING.has(text[end - 1])) end -= 1;
+  return text.slice(start, end);
+}
 
 export class BudgetError extends Error {
   constructor(message, detail = {}) {
@@ -30,9 +70,14 @@ export class BudgetError extends Error {
 
 export const usdg = (micros) => `${(Number(micros) / MICROS).toFixed(6)} USDG`;
 
+const isAmount = (value) => typeof value === "number" && Number.isFinite(value) && value >= 0;
+
+const isStamp = (value) => isAmount(value) && value <= MAX_AT_MS;
+
 function positiveNumber(raw, fallback, name) {
-  if (raw === undefined || raw === null || String(raw).trim() === "") return fallback;
-  const value = Number(raw);
+  const text = raw === undefined || raw === null ? "" : trim(raw);
+  if (text === "") return fallback;
+  const value = DECIMAL.test(text) ? Number(text) : Number.NaN;
   if (!Number.isFinite(value) || value < 0) {
     throw new BudgetError(`${name} must be a non-negative number of USDG, got ${JSON.stringify(raw)}`);
   }
@@ -45,7 +90,7 @@ function positiveNumber(raw, fallback, name) {
 // "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];
+    if (key.startsWith("PRISM_") && /^\$\{[^}]*\}$/.test(trim(value ?? ""))) delete env[key];
   }
   return env;
 }
@@ -86,22 +131,76 @@ export function callCeiling(maxUsdg, ceilingMicros) {
   if (typeof maxUsdg !== "number" || !Number.isFinite(maxUsdg) || maxUsdg <= 0) {
     throw new BudgetError("max_usdg must be a positive number of USDG.");
   }
+  // Checked before the multiplication, because that is where a figure this size
+  // stops being a number.
+  if (maxUsdg > MAX_CALL_USDG) throw new BudgetError(`max_usdg must be at most ${MAX_CALL_USDG} USDG.`);
   return Math.min(Math.round(maxUsdg * MICROS), ceilingMicros);
 }
 
+function lockOwner(lock) {
+  try {
+    return readFileSync(lock, "latin1").slice(0, 128);
+  } catch {
+    return null;
+  }
+}
+
+// A holder whose lock was broken as stale must not delete the lock its breaker
+// now holds, which is how two processes end up inside the ledger at once.
+function release(lock, token) {
+  if (lockOwner(lock) !== token) return;
+  try {
+    unlinkSync(lock);
+  } catch {
+    /* already gone */
+  }
+}
+
+// The lock this process is writing under, so the write itself can keep it alive
+// and refuse to publish under someone else's. A timer would do it in Python,
+// where the heartbeat runs on a thread; here the whole ledger is synchronous,
+// so nothing on this loop could fire between taking the lock and writing.
+let writing = null;
+
+function touch(lock, token) {
+  // Refreshing a lock that was broken and retaken would be this process
+  // vouching for a lock it does not hold.
+  if (lockOwner(lock) !== token) return;
+  const stamp = new Date();
+  try {
+    utimesSync(lock, stamp, stamp);
+  } catch {
+    /* it went while we were looking at it */
+  }
+}
+
+const keepLock = () => writing && touch(writing.lock, writing.token);
+
+const holdingLock = () => writing === null || lockOwner(writing.lock) === writing.token;
+
 // 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`;
+// the case this file exists for. A holder refreshes its lock as it writes, so a
+// lock older than LOCK_STALE_MS belonged to a process that died; breaking it is
+// safe and not breaking it wedges the wallet. A break that happens anyway,
+// because a machine slept or a clock stepped, is caught at the write.
+//
+// Exported because the tests that matter here need two real processes inside it.
+export function withLock(path, fn, waitMs = LOCK_WAIT_MS) {
   mkdirSync(dirname(path), { recursive: true });
+  // The lock names the file the write lands on rather than the name the caller
+  // spelled. One client reaching the ledger through a link and another through
+  // its target would otherwise hold two different locks over one file, and each
+  // would publish a state read before the other's charge existed.
+  const lock = `${resolveTarget(path)}.lock`;
   const deadline = Date.now() + waitMs;
+  const token = `${process.pid}-${randomBytes(8).toString("hex")}`;
   for (;;) {
     let fd;
     try {
-      fd = openSync(lock, "wx");
+      fd = openSync(lock, "wx", 0o600);
     } catch (err) {
       if (err?.code !== "EEXIST") throw err;
+      const held = lockOwner(lock);
       let age = 0;
       try {
         age = Date.now() - statSync(lock).mtimeMs;
@@ -109,10 +208,15 @@ function withLock(path, fn, waitMs = LOCK_WAIT_MS) {
         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 */
+        // Break the lock that was read as stale and no other: re-reading the
+        // token keeps a slow breaker from deleting a lock a third process took
+        // in the meantime.
+        if (lockOwner(lock) === held) {
+          try {
+            unlinkSync(lock);
+          } catch {
+            /* another process broke it first, which is the outcome we wanted */
+          }
         }
         continue;
       }
@@ -127,38 +231,140 @@ function withLock(path, fn, waitMs = LOCK_WAIT_MS) {
       continue;
     }
     try {
+      writeSync(fd, token);
+      fsyncSync(fd);
+    } catch (err) {
       closeSync(fd);
+      release(lock, token);
+      throw err;
+    }
+    closeSync(fd);
+    const outer = writing;
+    writing = { lock, token };
+    try {
       return fn();
     } finally {
-      try {
-        unlinkSync(lock);
-      } catch {
-        /* already gone */
-      }
+      writing = outer;
+      release(lock, token);
     }
   }
 }
 
+const unreadable = (path, reason) =>
+  new BudgetError(`the spend ledger at ${path} is unreadable (${reason}), so spending is refused. Move or repair the file.`);
+
 function readState(path) {
+  let raw;
   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)) };
+    raw = readFileSync(path);
   } catch (err) {
     if (err?.code === "ENOENT") return { entries: [] };
+    throw unreadable(path, err?.message ?? err);
+  }
+  let parsed;
+  try {
+    // Invalid UTF-8 is refused rather than patched up with replacement
+    // characters, because the bytes a ledger cannot read are the bytes it must
+    // not spend against.
+    parsed = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(raw));
+  } catch (err) {
     // 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.`,
-    );
+    throw unreadable(path, err?.message ?? err);
+  }
+  const entries = parsed && typeof parsed === "object" ? parsed.entries : undefined;
+  if (!Array.isArray(entries)) throw unreadable(path, "it holds no list of entries");
+  // Dropping the entries that fail this check would be the corrupt-reads-as-
+  // empty bug again, one charge at a time.
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object" || !isStamp(entry.at) || !isAmount(entry.micros)) {
+      throw unreadable(path, "an entry is not a charge with non-negative micros and an at a date can hold");
+    }
+  }
+  return { entries };
+}
+
+// The entry is written before the money moves, so it has to survive the crash
+// that lands between the two.
+function fsyncDir(directory) {
+  let fd;
+  try {
+    fd = openSync(directory, "r");
+  } catch {
+    return; // not every platform lets a directory be opened, and the rename is still ordered
+  }
+  try {
+    fsyncSync(fd);
+  } catch {
+    /* some filesystems refuse it */
+  } finally {
+    closeSync(fd);
+  }
+}
+
+// A symlinked ledger is written through, not replaced: an operator who pointed
+// the path at a file elsewhere means to keep reading that file. realpathSync
+// gives up when the target does not exist yet, so a link is followed by hand
+// and the last name is resolved against its own directory, which is how the
+// first write creates the file through the link rather than over it.
+function resolveTarget(path) {
+  let current = path;
+  for (let hop = 0; hop < 40; hop += 1) {
+    try {
+      return realpathSync(current);
+    } catch {
+      /* nothing there yet */
+    }
+    let link;
+    try {
+      link = readlinkSync(current);
+    } catch {
+      break; // a plain name that is not there, which is the ordinary first write
+    }
+    current = resolve(dirname(current), link);
+  }
+  try {
+    return join(realpathSync(dirname(current)), basename(current));
+  } catch {
+    return current;
   }
 }
 
-function writeState(path, state, now) {
+// Exported alongside withLock, for the same reason: what a write does when the
+// lock under it changed hands can only be tested from a second real process.
+export 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);
+  const target = resolveTarget(path);
+  const tmp = `${target}.${process.pid}.tmp`;
+  try {
+    unlinkSync(tmp);
+  } catch {
+    /* nothing to clear */
+  }
+  keepLock();
+  // Exclusive, so a temp file left behind by anyone else cannot lend this one
+  // its permissions.
+  const fd = openSync(tmp, "wx", 0o600);
+  try {
+    writeSync(fd, `${JSON.stringify({ version: 1, entries }, null, 2)}\n`);
+    fsyncSync(fd);
+  } finally {
+    closeSync(fd);
+  }
+  // The last moment this is still a decision. A lock read as stale is broken by
+  // whoever wants it next, and if that happened while these bytes were being
+  // prepared they no longer describe the file: publishing them would erase the
+  // charge the breaker just recorded.
+  if (!holdingLock()) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* nothing to clear */
+    }
+    throw new BudgetError("lost the ledger lock; nothing written");
+  }
+  renameSync(tmp, target);
+  fsyncDir(dirname(target));
 }
 
 export function spentInWindow(entries, now) {
@@ -195,7 +401,7 @@ export class SpendLedger {
         .slice(0, 20)
         .map((e) => ({
           at: new Date(e.at).toISOString(),
-          tool: e.tool,
+          ...("tool" in e ? { tool: e.tool } : {}),
           amount: usdg(e.micros),
           ...(e.reference ? { reference: e.reference } : {}),
         })),
@@ -215,6 +421,11 @@ export class SpendLedger {
         { required: micros, cap: this.maxPerCallMicros },
       );
     }
+    // A caller handing this nanoseconds writes an entry no reader can date and
+    // no write can prune, which wedges the ledger for good.
+    if (!isStamp(now)) {
+      throw new BudgetError("a charge has to be stamped in milliseconds since the epoch, and this one is not");
+    }
     return withLock(
       this.path,
       () => {
@@ -227,7 +438,10 @@ export class SpendLedger {
             { spent, requested: micros, cap: this.dailyMicros },
           );
         }
-        const id = `${now.toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+        // The suffix separates two charges stamped in the same millisecond, and
+        // Math.random makes that a guess anyone sharing the file can make:
+        // settle and revert both take an id.
+        const id = `${Math.max(Math.trunc(now), 0).toString(36)}-${randomBytes(8).toString("hex")}`;
         state.entries.push({ id, at: now, tool, micros });
         writeState(this.path, state, now);
         return id;
@@ -252,24 +466,45 @@ export class SpendLedger {
 
   // 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.
+  // list of intentions. The reservation is the ceiling the escrow was funded
+  // against, so settling can only lower it.
   //
   // 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.
+  //
+  // The fold rests on a reference naming exactly one payment, which holds
+  // because recordSpend passes nothing but a transaction this process
+  // broadcast. It is bounded to the same tool inside the same day regardless:
+  // the file remembers two days, and folding today's reservation into a charge
+  // the window no longer counts would take a spend off the day's total rather
+  // than deduplicate one.
   settle(id, { micros, reference } = {}) {
     if (!id) return false;
     return withLock(this.path, () => {
+      const now = Date.now();
       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 booked = reference
+        ? state.entries.find(
+            (e) => e.id !== id && e.reference === reference && e.tool === entry.tool && now - e.at < DAY_MS,
+          )
+        : undefined;
       const target = booked ?? entry;
-      if (Number.isFinite(micros) && micros >= 0) target.micros = micros;
+      if (isAmount(micros)) {
+        if (micros > target.micros) {
+          console.error(
+            `prism: a settlement of ${usdg(micros)} is above the ${usdg(target.micros)} reserved for ledger entry ${target.id}; the reservation stands.`,
+          );
+        } else {
+          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());
+      writeState(this.path, state, now);
       return true;
     }, this.lockWaitMs);
   }
@@ -293,12 +528,15 @@ export async function recordSpend(book, tool, micros, run) {
       console.error(`prism mcp: could not ${action} the ledger entry for ${tool}: ${err?.message ?? err}`);
     }
   };
+  let outcome;
   try {
-    const { value, settledMicros, reference } = await run();
-    reconcile("settle", { micros: settledMicros, reference });
-    return value;
+    outcome = await run();
   } catch (err) {
-    const paid = err?.body?.funding_hash ?? err?.body?.payment_tx;
+    // Only a transaction this process put on the wire proves money moved. A
+    // failure's body is whatever the control plane sent back, and reading a
+    // hash out of it would let the far side decide which reservations stand and
+    // which later ones are folded into them.
+    const paid = typeof err?.broadcast === "string" && err.broadcast ? err.broadcast : null;
     if (paid) {
       reconcile("settle", { reference: paid });
     } else if (err?.code === "chain_error") {
@@ -313,4 +551,20 @@ export async function recordSpend(book, tool, micros, run) {
     }
     throw err;
   }
+  // The attempt ran, so the money is as gone as the caller's ability to
+  // describe it. The reservation stands and the shape is reported as the
+  // programming error it is.
+  // An array carries no settledMicros and no reference, so reading one as an
+  // outcome would book the reservation as if it had been settled and hand the
+  // caller undefined. Python refuses the same shape.
+  if (!outcome || typeof outcome !== "object" || Array.isArray(outcome)) {
+    reconcile("settle");
+    const shape = outcome === null ? "null" : Array.isArray(outcome) ? "array" : typeof outcome;
+    throw new BudgetError(
+      `${tool} reported ${shape} where the ledger needs an object of ` +
+        `value, settledMicros and reference; the reservation stands.`,
+    );
+  }
+  reconcile("settle", { micros: outcome.settledMicros, reference: outcome.reference });
+  return outcome.value;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismnetwork/mcp",
-  "version": "0.9.3",
+  "version": "0.10.0",
   "description": "MCP server for leasing and running on Prism Network GPUs.",
   "mcpName": "io.github.prismnetwork-tech/mcp",
   "type": "module",
@@ -9,6 +9,7 @@
   },
   "files": [
     "budget.mjs",
+    "policy.mjs",
     "server.mjs",
     "README.md"
   ],
@@ -18,7 +19,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
     "@phala/dcap-qvl": "^0.6.1",
-    "@prismnetwork/agent-sdk": "^0.7.3",
+    "@prismnetwork/agent-sdk": "^0.7.12",
     "jose": "^6",
     "viem": "^2"
   },

package/policy.mjs

@@ -0,0 +1,117 @@
+// The operator's spending rules for leases. The budget caps how much an agent
+// may spend; the policy decides whether a given spend has a reason the operator
+// accepts. The agent states its reason as a decision, the SDK checks it against
+// this policy before anything is quoted, and only the decision's hash leaves
+// the machine, bound into the escrow deposit.
+import { readFileSync } from "node:fs";
+import { answer, decision as makeDecision, decisionDigest, refusals } from "@prismnetwork/agent-sdk/decision";
+
+export class PolicyError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "PolicyError";
+  }
+}
+
+const strings = (value, field) => {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((v) => typeof v !== "string" || !v.trim())) {
+    throw new PolicyError(`PRISM_SPEND_POLICY: ${field} must be a list of names`);
+  }
+  return value;
+};
+
+/// PRISM_SPEND_POLICY holds the policy as JSON, or the path to a JSON file.
+/// Unset means no policy: a decision is optional and, when given, still binds.
+export function readPolicy(raw = process.env.PRISM_SPEND_POLICY) {
+  if (raw === undefined || raw.trim() === "") return null;
+  let text = raw.trim();
+  if (!text.startsWith("{")) {
+    try {
+      text = readFileSync(text, "utf8");
+    } catch (err) {
+      throw new PolicyError(`PRISM_SPEND_POLICY: cannot read ${raw}: ${err.code ?? err.message}`);
+    }
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    throw new PolicyError("PRISM_SPEND_POLICY is not valid JSON");
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new PolicyError("PRISM_SPEND_POLICY must be a JSON object");
+  }
+  const policyId = parsed.policy_id;
+  if (typeof policyId !== "string" || !policyId.trim()) {
+    throw new PolicyError("PRISM_SPEND_POLICY needs a policy_id, so every decision records which rules admitted it");
+  }
+  const minimums = parsed.minimums ?? {};
+  if (typeof minimums !== "object" || Array.isArray(minimums)) {
+    throw new PolicyError("PRISM_SPEND_POLICY: minimums must map an answer name to a confidence floor");
+  }
+  for (const [name, floor] of Object.entries(minimums)) {
+    if (typeof floor !== "number" || !(floor >= 0 && floor <= 1)) {
+      throw new PolicyError(`PRISM_SPEND_POLICY: the floor for ${name} must be a number from 0 to 1`);
+    }
+  }
+  return {
+    policyId,
+    allow: strings(parsed.allow, "allow"),
+    require: strings(parsed.require, "require"),
+    minimums,
+  };
+}
+
+/// What prism_budget shows, so an agent can shape its decision before it asks.
+export function describePolicy(policy) {
+  if (!policy) return { spend_policy: "none: leases need no stated reason" };
+  return {
+    spend_policy: {
+      policy_id: policy.policyId,
+      allowed_actions: policy.allow.length ? policy.allow : "any",
+      required_answers: policy.require,
+      confidence_floors: policy.minimums,
+    },
+  };
+}
+
+/// The decision a tool call carries, in the SDK's form. Malformed input is the
+/// caller's mistake and says which field; a missing decision under a policy is
+/// refused with what the policy needs.
+export function decisionFrom(input, policy) {
+  if (input === undefined || input === null) {
+    if (!policy) return null;
+    const needs = [
+      policy.allow.length ? `action one of ${policy.allow.join(", ")}` : "an action",
+      ...policy.require.map((n) => `an answer for ${n}`),
+      ...Object.entries(policy.minimums).map(([n, f]) => `${n} with confidence at least ${f}`),
+    ];
+    throw new PolicyError(
+      `the operator's spend policy ${policy.policyId} requires a decision with this lease: ${needs.join("; ")}. Nothing was quoted or funded.`,
+    );
+  }
+  if (typeof input !== "object") throw new PolicyError("decision must be an object with action, source and answers");
+  const answers = (input.answers ?? []).map((a) => {
+    if (!a || typeof a.name !== "string") throw new PolicyError("each decision answer needs a name");
+    return answer(a.name, a.value ?? null, a.confidence ?? null);
+  });
+  return makeDecision({
+    action: input.action,
+    source: input.source,
+    answers,
+    policyId: input.policy_id ?? policy?.policyId ?? null,
+  });
+}
+
+/// Checked here, before the spend is booked against the budget, so a refused
+/// decision neither costs anything nor holds capacity.
+export function authorised(policy, d) {
+  if (!policy) return;
+  const reasons = refusals(policy, d);
+  if (reasons.length) {
+    throw new PolicyError(`the spend policy ${policy.policyId} refused this lease: ${reasons.join("; ")}. Nothing was quoted or funded.`);
+  }
+}
+
+export { decisionDigest };

package/server.mjs

@@ -15,6 +15,7 @@ import {
   verifyConfidential,
 } from "@prismnetwork/agent-sdk";
 import { BudgetError, SpendLedger, callCeiling, readBudget, recordSpend, stripUnexpanded } from "./budget.mjs";
+import { authorised, decisionDigest, decisionFrom, describePolicy, readPolicy } from "./policy.mjs";
 
 stripUnexpanded(process.env);
 
@@ -64,6 +65,26 @@ try {
   console.error(`prism mcp: ${budgetProblem}`);
 }
 
+// Same rule as the budget: a policy the operator got wrong stops leasing rather
+// than letting every lease through unchecked.
+let policy = null;
+let policyProblem = null;
+try {
+  policy = readPolicy();
+} catch (err) {
+  policyProblem = err?.message ?? String(err);
+  console.error(`prism mcp: ${policyProblem}`);
+}
+
+/// The decision this lease carries, checked against the operator's policy
+/// before anything is booked, quoted or funded.
+function leaseDecision(tool, args) {
+  if (policyProblem) throw new Error(`${tool} is disabled until the spend policy is fixed: ${policyProblem}`);
+  const d = decisionFrom(args.decision, policy);
+  if (d) authorised(policy, d);
+  return d;
+}
+
 function requireWallet(tool, reason = "spends money") {
   if (!agent) {
     throw new Error(
@@ -211,6 +232,33 @@ const spends = {
   _meta: { "anthropic/requiresUserInteraction": true },
 };
 
+// Why a lease is being funded. Only its hash leaves the machine, bound into the
+// escrow deposit, so whoever holds the decision can prove it came first.
+const DECISION_SCHEMA = {
+  type: "object",
+  description:
+    "Why this lease is being funded. Required when the operator set a spend policy (see prism_budget), and the lease is refused before anything is quoted if the decision does not meet it. Only a hash of it leaves this machine, recorded with the escrow deposit.",
+  properties: {
+    action: { type: "string", description: "What the spend is for, e.g. 'fine_tune' or 'benchmark'." },
+    source: { type: "string", description: "What made the call: a model name, a rule, or 'operator'." },
+    answers: {
+      type: "array",
+      description: "Typed answers behind the decision. confidence (0 to 1) is what a policy floor reads.",
+      items: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Lowercase identifier, e.g. 'needs_gpu'." },
+          value: { description: "The answer: an option, a score, or a probability." },
+          confidence: { type: "number", minimum: 0, maximum: 1 },
+        },
+        required: ["name", "value"],
+      },
+    },
+    policy_id: { type: "string", description: "The policy this decision was made under; defaults to the operator's." },
+  },
+  required: ["action", "source"],
+};
+
 const TOOLS = [
   {
     name: "prism_budget",
@@ -272,6 +320,7 @@ const TOOLS = [
         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: "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." },
+        decision: DECISION_SCHEMA,
       },
       required: ["command"],
     },
@@ -371,6 +420,7 @@ const TOOLS = [
           description: "Refuse suppliers below this trust class (default 'open'). Raise it for anything the host operator must not read.",
         },
         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." },
+        decision: DECISION_SCHEMA,
       },
       required: ["command"],
     },
@@ -391,6 +441,7 @@ const TOOLS = [
           description: "Refuse suppliers below this trust class (default 'open'). Raise it for anything the host operator must not read.",
         },
         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." },
+        decision: DECISION_SCHEMA,
       },
     },
     ...spends,
@@ -412,7 +463,7 @@ const TOOLS = [
   },
   {
     name: "prism_end_lease",
-    description: "Release a lease's local access. The on-chain lease settles at the end of its paid duration.",
+    description: "Release a lease. Access closes and billing stops here: settlement charges the seconds the lease was open and returns the rest of the deposit. A lease nobody releases bills until its window ends.",
     inputSchema: {
       type: "object",
       properties: { lease_id: { type: "integer" } },
@@ -483,7 +534,9 @@ const TOOLS = [
 ];
 
 async function handle(name, args) {
-  if (name === "prism_budget") return requireLedger(name).status();
+  if (name === "prism_budget") {
+    return { ...requireLedger(name).status(), ...(policyProblem ? { spend_policy_error: policyProblem } : describePolicy(policy)) };
+  }
   if (name === "prism_wallet") {
     const b = await requireWallet("prism_wallet").balances();
     return { address: b.address, usdg: usdg(b.usdg), eth_wei: b.eth };
@@ -574,6 +627,7 @@ async function handle(name, args) {
   if (name === "prism_batch_run") {
     requireCommand(args.command);
     requireWallet(name);
+    const decision = leaseDecision(name, args);
     const cap = maxDeposit(name, args);
     return spending(name, cap, async () => {
       const batch = await agent.lease({
@@ -582,6 +636,8 @@ async function handle(name, args) {
         minVramMib: args.min_vram_mib ?? 16000,
         maxDeposit: cap,
         command: args.command,
+        decision,
+        policy,
       });
       return {
         reference: batch.fundingHash,
@@ -589,6 +645,7 @@ async function handle(name, args) {
         value: {
           lease_id: batch.leaseId,
           funding_tx: batch.fundingHash,
+          ...(decision ? { decision_hash: decisionDigest(decision) } : {}),
           exit_code: batch.result?.exit_code,
           stdout: batch.result?.stdout,
           stderr: batch.result?.stderr,
@@ -731,6 +788,7 @@ 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 decision = leaseDecision(name, args);
     const cap = maxDeposit(name, args);
     sweepExpiredLeases();
     const lease = await spending(name, cap, async () => {
@@ -740,6 +798,8 @@ async function handle(name, args) {
         minVramMib: args.min_vram_mib ?? 16000,
         maxDeposit: cap,
         minTrustClass: args.min_trust_class ?? "open",
+        decision,
+        policy,
       });
       return { value: funded, reference: funded.fundingHash, settledMicros: escrowed(funded.quote) };
     });
@@ -747,6 +807,7 @@ async function handle(name, args) {
     const summary = {
       lease_id: lease.leaseId,
       funding_tx: lease.fundingHash,
+      ...(decision ? { decision_hash: decisionDigest(decision) } : {}),
       // `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
@@ -789,11 +850,13 @@ async function handle(name, args) {
   if (name === "prism_end_lease") {
     const id = leaseId(args.lease_id);
     const lease = leases.get(id);
-    if (lease) {
-      agent.endLease(lease);
-      leases.delete(id);
+    if (!lease) return { lease_id: id, released: false, next: "no lease with this id is open in this session; prism_leases lists the wallet's leases" };
+    leases.delete(id);
+    const out = await agent.endLease(lease);
+    if (out.release === "failed") {
+      return { lease_id: id, released: false, error: out.error, next: "the access key is gone but the meter may still be running; check prism_receipts for the settled charge" };
     }
-    return { lease_id: id, released: Boolean(lease) };
+    return { lease_id: id, released: true, release: out.release, next: "billing stopped here; the unused deposit returns after settlement and prism_receipts shows the charge" };
   }
   if (name.startsWith("prism_vault_")) return handleVault(name, args);
   throw new Error(`unknown tool ${name}. Valid tools: ${TOOLS.map((t) => t.name).join(", ")}`);
@@ -848,7 +911,7 @@ async function handleVault(name, args) {
   throw new Error(`unknown tool ${name}`);
 }
 
-const server = new Server({ name: "prism", version: "0.9.0" }, { capabilities: { tools: {} } });
+const server = new Server({ name: "prism", version: "0.10.0" }, { capabilities: { tools: {} } });
 server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   try {