@prismnetwork/mcp 0.9.4 → 0.10.0

package/README.md

@@ -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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismnetwork/mcp",
-  "version": "0.9.4",
+  "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.8",
+    "@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,
@@ -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
@@ -850,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 {