@prismnetwork/agent-sdk 0.7.6 → 0.7.8

package/README.md

@@ -24,7 +24,7 @@ await agent.authenticate();
 const lease = await agent.lease({ image: DEFAULT_IMAGE, durationSeconds: 900, minVramMib: 16000 });
 const out = await agent.run(lease, "nvidia-smi");
 console.log(out.stdout);
-agent.endLease(lease);
+await agent.endLease(lease);
 ```
 
 `image` must be an immutable digest-pinned reference (`repo@sha256:...`). `DEFAULT_IMAGE` is one; a plain tag is rejected.
@@ -156,7 +156,7 @@ it.
 The chain walk runs in our control plane, so `attested` says we checked the
 report. The SDK holds the session to the fingerprint we published and never sees
 the report itself, which leaves us in the set you are trusting.
-[ATTESTATION.md](https://github.com/winter0x/prism/blob/main/docs/ATTESTATION.md)
+[ATTESTATION.md](https://github.com/prismnetwork-tech/prism/blob/main/docs/ATTESTATION.md)
 says what the report covers and what it does not.
 
 `reported` means the node named the key on the signed report that opened access.
@@ -170,7 +170,9 @@ it is seen and held for the rest of the lease, which catches a machine swapped i
 partway through and cannot catch one that was wrong from the start.
 
 Nothing is written to your own `~/.ssh/known_hosts`. The record sits beside the
-lease's private key and is removed with it by `endLease()`.
+lease's private key and is removed with it by `endLease()`, which also releases
+the lease on the network so billing stops there instead of at the end of the
+window.
 
 To refuse the third case outright:
 
@@ -198,4 +200,4 @@ The wallet needs two balances on Robinhood Chain (id 4663): USDG (`0x5fc5360D040
 Node >= 20, `viem` ^2 (peer), and `ssh`, `ssh-keygen` and `ssh-keyscan` on PATH
 for `run()` and for workspace save and restore.
 
-See [example.mjs](https://github.com/winter0x/prism/blob/main/sdk/example.mjs) for a full run.
+See [example.mjs](https://github.com/prismnetwork-tech/prism/blob/main/sdk/example.mjs) for a full run.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@prismnetwork/agent-sdk",
-  "version": "0.7.6",
+  "version": "0.7.8",
   "description": "Headless GPU leasing and renter-encrypted storage on Prism Network for wallet-holding agents.",
   "type": "module",
   "main": "prism.mjs",

package/prism.d.mts

@@ -67,6 +67,13 @@ export interface RelayForwarder {
   close(): Promise<void>;
 }
 
+export interface LeaseRelease {
+  lease_id: number | null;
+  state: string | null;
+  release: "queued" | "already_closed" | "failed";
+  error?: string;
+}
+
 export interface LeaseHandle {
   leaseId: number;
   access: LeaseAccess;
@@ -169,7 +176,14 @@ export declare class PrismAgent {
   /// Only for a lease reached through the gateway. Use it for anything that is
   /// not a one-shot command: scp, a notebook client, an interactive shell.
   forward(lease: LeaseHandle, options?: { service?: "ssh" | "jupyter" }): Promise<RelayForwarder>;
-  endLease(lease: LeaseHandle): void;
+  /// Releases the lease on the network and removes its key material. This is
+  /// what stops the meter: settlement charges the seconds the lease was open and
+  /// returns the rest of the deposit. Never rejects; `release` is "queued",
+  /// "already_closed" or "failed" (with `error`), and a failed release means the
+  /// machine is still billing until its window ends.
+  endLease(lease: LeaseHandle): Promise<LeaseRelease>;
+  /// Releases a lease by id. Rejects when the network refuses.
+  release(leaseId: number): Promise<{ lease_id: number; state: string; release: "queued" | "already_closed" }>;
   /// Pay for one call to a metered endpoint, keeping the payment until the
   /// endpoint serves. Bytes are sent verbatim. Pass `seal` instead of `body` for
   /// a request that has to be rebuilt per attempt, with `fingerprint` so the

package/prism.mjs

@@ -239,10 +239,12 @@ export class PrismAgent {
       // The hash travels with the failure because it is the only thing that
       // says the money left this wallet, and whatever is counting the day's
       // spend has to be able to tell the two apart.
-      throw new PrismError(502, "chain_error", {
-        cause: err?.shortMessage ?? err?.message ?? String(err),
-        ...(broadcast ? { payment_tx: broadcast } : {}),
-      });
+      throw new PrismError(
+        502,
+        "chain_error",
+        { cause: err?.shortMessage ?? err?.message ?? String(err), ...(broadcast ? { payment_tx: broadcast } : {}) },
+        broadcast,
+      );
     }
   }
 
@@ -322,10 +324,12 @@ export class PrismAgent {
       // The deposit is in the escrow the moment the chain accepts this, and
       // waiting for confirmations is where a flaky rpc gives up. Losing the
       // hash here would leave a funded lease nobody can name.
-      throw new PrismError(502, "chain_error", {
-        cause: err?.shortMessage ?? err?.message ?? String(err),
-        ...(broadcast ? { funding_hash: broadcast } : {}),
-      });
+      throw new PrismError(
+        502,
+        "chain_error",
+        { cause: err?.shortMessage ?? err?.message ?? String(err), ...(broadcast ? { funding_hash: broadcast } : {}) },
+        broadcast,
+      );
     }
   }
 
@@ -498,9 +502,15 @@ export class PrismAgent {
       const detail = { funding_hash: funded.hash, lease_id: leaseId, key_path: key.keyPath };
       if (err instanceof PrismError) {
         err.body = { ...(err.body ?? {}), ...detail };
+        err.broadcast = funded.hash;
         throw err;
       }
-      throw new PrismError(502, "lease_failed_after_funding", { ...detail, cause: err?.message ?? String(err) });
+      throw new PrismError(
+        502,
+        "lease_failed_after_funding",
+        { ...detail, cause: err?.message ?? String(err) },
+        funded.hash,
+      );
     }
   }
 
@@ -589,8 +599,20 @@ export class PrismAgent {
     return openRelayForwarder(lease.access, { service });
   }
 
-  // Releases local key material. The on-chain lease settles at the end of its duration.
-  endLease(lease) {
+  // Releases the lease on the network, which is what stops the meter: settlement
+  // charges the seconds between access opening and this call and returns the
+  // rest of the deposit. Key material goes either way. Never rejects, because
+  // most callers fire it from cleanup paths; a refused release comes back in
+  // the result so a caller that cares can tell the operator the meter is still
+  // running.
+  // Releases a lease by id, for one this process holds no handle to (the id a
+  // failed fund names, a lease listed by leases()). Rejects when the network
+  // refuses, because the wallet is still paying for the machine.
+  async release(leaseId) {
+    return this.#proxy("POST", ["leases", String(leaseId), "release"]);
+  }
+
+  async endLease(lease) {
     if (lease?.keyDir) {
       try {
         rmSync(lease.keyDir, { recursive: true, force: true });
@@ -598,6 +620,13 @@ export class PrismAgent {
         /* best effort */
       }
     }
+    if (lease?.leaseId === undefined || lease?.leaseId === null) return { lease_id: null, release: "failed", error: "no lease id" };
+    try {
+      const out = await this.release(lease.leaseId);
+      return { lease_id: Number(lease.leaseId), state: out?.state ?? null, release: out?.release ?? "queued" };
+    } catch (error) {
+      return { lease_id: Number(lease.leaseId), state: null, release: "failed", error: error?.message ?? String(error) };
+    }
   }
 
   // Unconsumed inference payments, keyed by the endpoint, the price and the
@@ -669,7 +698,7 @@ export class PrismAgent {
         });
         bytes = Buffer.from(await res.arrayBuffer());
       } catch (err) {
-        throw new PrismError(504, "endpoint_unreachable", { cause: err?.message ?? String(err), ...kept });
+        throw new PrismError(504, "endpoint_unreachable", { cause: err?.message ?? String(err), ...kept }, tx);
       }
       if (res.status === 200) {
         this.#pendingPayments.delete(key);
@@ -677,10 +706,15 @@ export class PrismAgent {
         // already consumed. That is an answer to an earlier call, so it is not
         // this one's, whatever the status line says.
         if (String(res.headers.get("x-prism-replayed") ?? "").toLowerCase() === "true") {
-          throw new PrismError(409, "payment_replayed", {
-            cause: `the endpoint replayed an earlier answer for tx ${tx}`,
-            hint: "this payment was already consumed by another call; pay again to have this request served",
-          });
+          throw new PrismError(
+            409,
+            "payment_replayed",
+            {
+              cause: `the endpoint replayed an earlier answer for tx ${tx}`,
+              hint: "this payment was already consumed by another call; pay again to have this request served",
+            },
+            tx,
+          );
         }
         return { status: 200, headers: res.headers, bytes, tx, sent };
       }
@@ -700,10 +734,15 @@ export class PrismAgent {
         (res.status === 402 && ["insufficient_confirmations", "tx_not_found"].includes(answered?.error));
       if (!retryable || Date.now() > deadline) {
         const said = [answered?.detail, answered?.retry].filter(Boolean).join("; ");
-        throw new PrismError(res.status, answered?.error ?? "generation_failed", {
-          cause: said || answered?.error || `status ${res.status}`,
-          ...(this.#pendingPayments.has(key) ? kept : { payment_tx: tx }),
-        });
+        throw new PrismError(
+          res.status,
+          answered?.error ?? "generation_failed",
+          {
+            cause: said || answered?.error || `status ${res.status}`,
+            ...(this.#pendingPayments.has(key) ? kept : { payment_tx: tx }),
+          },
+          tx,
+        );
       }
       await sleep(retryDelayMs);
       if (seal) sent = seal();
@@ -1055,11 +1094,15 @@ export class PrismAgent {
 }
 
 export class PrismError extends Error {
-  constructor(status, code, body) {
+  constructor(status, code, body, broadcast = null) {
     super(`prism ${status}: ${code}`);
     this.name = "PrismError";
     this.status = status;
     this.code = code;
     this.body = body;
+    // The transaction this process put on the wire before the failure, when
+    // there was one. `body` is whatever the far side sent back and can say
+    // anything; this is the only field that says the money left this wallet.
+    this.broadcast = broadcast;
   }
 }

package/toolset.d.mts

@@ -26,5 +26,5 @@ export declare class PrismToolset {
   listGpus(minTrustClass?: string): Promise<string>;
   leaseAndRun(options: LeaseAndRunOptions): Promise<string>;
   run(leaseId: number, command: string): Promise<string>;
-  endLease(leaseId: number): string;
+  endLease(leaseId: number): Promise<string>;
 }

package/toolset.mjs

@@ -210,14 +210,17 @@ export class PrismToolset {
     return `exit ${res.code}:\n${res.stdout || res.stderr || ""}`;
   }
 
-  endLease(leaseId) {
+  async endLease(leaseId) {
     if (!this.#agent) return NO_WALLET;
     leaseId = Number(leaseId);
     if (!Number.isInteger(leaseId) || leaseId <= 0) return "lease_id must be a positive integer.";
     const lease = this.#leases.get(leaseId);
     if (!lease) return `No active lease ${leaseId} in this session.`;
-    this.#agent.endLease(lease);
     this.#leases.delete(leaseId);
-    return `released lease ${leaseId}`;
+    const out = await this.#agent.endLease(lease);
+    if (out.release === "failed") {
+      return `Lease ${leaseId} could not be released: ${out.error}. Its access key is gone but the meter may still be running; check receipts for the settled charge.`;
+    }
+    return `released lease ${leaseId}; billing stopped here and the unused deposit returns after settlement`;
   }
 }