@prismnetwork/agent-sdk 0.3.1 → 0.5.0

package/README.md

@@ -16,7 +16,7 @@ npm install @prismnetwork/agent-sdk viem
 import { PrismAgent, DEFAULT_IMAGE } from "@prismnetwork/agent-sdk";
 
 const agent = new PrismAgent({
-  privateKey: process.env.AGENT_KEY,        // agent's wallet
+  privateKey: process.env.PRISM_AGENT_KEY,  // agent's wallet
   escrow: "0x62C042265991bEa17B07229322A01850974626dA",
 });
 
@@ -29,6 +29,18 @@ agent.endLease(lease);
 
 `image` must be an immutable digest-pinned reference (`repo@sha256:...`). `DEFAULT_IMAGE` is one; a plain tag is rejected.
 
+## Toolset
+
+`@prismnetwork/agent-sdk/toolset` exports `PrismToolset`, the framework-neutral
+tool surface the framework plugins (elizaOS, Virtuals GAME) wrap: `wallet`,
+`listGpus`, `leaseAndRun`, `run`, `endLease`, each resolving to a
+human-readable string, including on failure. It holds the wallet, the open
+leases and the per-lease spending cap in one place, reads `PRISM_AGENT_KEY`,
+`PRISM_ESCROW`, `PRISM_API_BASE` and `PRISM_RPC_URL` from the environment by
+default (`agentFromEnv` accepts a getter for hosts with their own settings
+store), and answers the read-only questions from the public API when no wallet
+is configured.
+
 ## Vault
 
 Cards, identity documents, API credentials and recovery codes go in the vault
@@ -45,7 +57,7 @@ const value = await agent.vault.get(card.item_id, { json: true });
 
 `unlock()` derives the key from a signature over a fixed statement. Ethereum's
 ECDSA is deterministic, so the same wallet reproduces the same vault on any
-machine — no recovery copy is held anywhere. Pass `{ passphrase }` to require a
+machine; no recovery copy is held anywhere. Pass `{ passphrase }` to require a
 second factor beyond the wallet.
 
 Every item carries the weakest workspace trust class it may ever be released
@@ -65,6 +77,62 @@ ciphertext, so a service that moved an item between accounts, replayed an older
 version, or lowered its floor would produce a failed decrypt rather than a
 plausible wrong answer. See [docs/VAULT.md](../docs/VAULT.md).
 
+## Workspaces
+
+A lease destroys its machine, so training output, checkpoints and a working
+directory need somewhere that outlives it. A workspace is that place: the SDK
+archives a directory off the leased box, seals it here under a key derived from
+your wallet, and uploads the ciphertext straight to object storage. Prism
+records the version, the size and the hash, and holds nothing that opens it.
+
+```js
+await agent.workspace.unlock();
+
+const ws = await agent.workspace.create("finetune-run");
+const saved = await agent.workspace.save(lease, ws, "/root/out");
+
+// On a later lease, onto a fresh machine.
+await agent.workspace.restore(next, ws, "/root/out", { expectVersion: saved.version });
+```
+
+The workspace key comes from a different statement and a different salt than
+the vault's, so opening one does not open the other. Pass `{ passphrase }` to
+require a second factor beyond the wallet.
+
+A restore hashes the downloaded ciphertext and compares it to the digest
+recorded at save time before it decrypts anything, so bytes altered in storage
+are reported as tampering rather than as a wrong key. The account, workspace,
+version and trust floor are authenticated into the ciphertext, so a snapshot
+served for the wrong workspace, or under a floor that has been rewritten, fails
+to open rather than returning a plausible wrong answer.
+
+An older snapshot is a different case worth being precise about: its own
+associated data is genuine for its own version, so it decrypts cleanly and
+nothing in the ciphertext gives it away. A restore therefore compares the
+version it was granted against the version the record says is current, and
+refuses a rollback on that basis. Pass `expectVersion` to pin a specific one,
+and `expectTrustClass` to refuse a floor that has moved.
+
+A restore names the lease it is landing on, and Prism refuses to issue the
+download at all when that lease's trust class is below the workspace's floor.
+The check is server-side deliberately: a client-side one would be a courtesy
+that a modified client could skip.
+
+Bulk data never passes through Prism. Uploads and downloads use presigned URLs
+that live fifteen minutes, and they are used from your process, never handed to
+the leased machine. The machine only ever sees `tar` and `base64`, which is all
+this needs from it.
+
+Snapshots travel over the lease's SSH channel, which caps a single save at 64
+MiB of archive; a larger directory is refused on the machine before anything is
+transferred. New workspaces default to the `open` trust floor, unlike vault
+items: their contents are the files you are already handing to a rented box.
+Raise it at creation when they deserve more:
+
+```js
+await agent.workspace.create("model-weights", { minTrustClass: "isolated" });
+```
+
 ## Auth
 
 `authenticate()` fetches a challenge (`GET /api/agent/challenge`), signs the message with the wallet, and exchanges it for a session (`POST /api/agent/session`). The session is a bearer token used on every `/api/agent/proxy/*` call. No shared secret, no cookie. The wallet is the identity (`subject = wallet:0x...`).
@@ -79,6 +147,7 @@ The wallet needs two balances on Robinhood Chain (id 4663): USDG (`0x5fc5360D040
 
 ## Requirements
 
-Node >= 20, `viem` ^2 (peer), and `ssh` + `ssh-keygen` on PATH for `run()`.
+Node >= 20, `viem` ^2 (peer), and `ssh` + `ssh-keygen` on PATH for `run()` and
+for workspace save and restore.
 
-See `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,20 +1,36 @@
 {
   "name": "@prismnetwork/agent-sdk",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Headless GPU leasing and renter-encrypted storage on Prism Network for wallet-holding agents.",
   "type": "module",
   "main": "prism.mjs",
   "exports": {
-    ".": "./prism.mjs",
+    ".": {
+      "types": "./prism.d.mts",
+      "default": "./prism.mjs"
+    },
+    "./toolset": {
+      "types": "./toolset.d.mts",
+      "default": "./toolset.mjs"
+    },
     "./vault": {
       "types": "./vault.d.ts",
       "default": "./vault.mjs"
+    },
+    "./workspace": {
+      "types": "./workspace.d.ts",
+      "default": "./workspace.mjs"
     }
   },
   "files": [
     "prism.mjs",
+    "toolset.d.mts",
+    "prism.d.mts",
+    "toolset.mjs",
     "vault.mjs",
     "vault.d.ts",
+    "workspace.mjs",
+    "workspace.d.ts",
     "README.md"
   ],
   "engines": {
@@ -44,5 +60,6 @@
   "license": "Apache-2.0",
   "publishConfig": {
     "access": "public"
-  }
+  },
+  "types": "prism.d.mts"
 }

package/prism.d.mts

@@ -0,0 +1,84 @@
+export declare const robinhoodChain: unknown;
+export declare const USDG: string;
+export declare const DEFAULT_IMAGE: string;
+export declare const TRUST_CLASSES: readonly ["open", "isolated", "attested", "confidential"];
+
+export interface LeaseAccess {
+  mode?: string;
+  ssh_host?: string;
+  ssh_port?: number;
+  ssh_user?: string;
+  expires_at?: string;
+  [key: string]: unknown;
+}
+
+export interface LeaseHandle {
+  leaseId: number;
+  access: LeaseAccess;
+  keyPath: string;
+  keyDir: string;
+  publicKey: string;
+  fundingHash: string;
+  quote: Record<string, unknown>;
+}
+
+export interface BatchLeaseHandle {
+  leaseId: number;
+  result: { exit_code?: number; stdout?: string; stderr?: string; truncated?: boolean };
+  fundingHash: string;
+  quote: Record<string, unknown>;
+}
+
+export interface RunResult {
+  code: number;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+}
+
+export declare class PrismAgent {
+  constructor(options: { privateKey: string; escrow: string; apiBase?: string; rpcUrl?: string });
+  readonly address: string;
+  readonly vault: unknown;
+  readonly workspace: unknown;
+  authenticate(): Promise<{ session: string }>;
+  offers(options?: { minTrust?: string }): Promise<Array<Record<string, unknown>>>;
+  balances(): Promise<{ address: string; usdg: string; eth: string }>;
+  transferUsdg(to: string, amountMicros: number | string | bigint): Promise<string>;
+  quote(options: {
+    image: string;
+    durationSeconds: number;
+    minVramMib?: number;
+    preferredNodeId?: string | null;
+    minTrustClass?: string;
+    command?: string | null;
+  }): Promise<Record<string, unknown>>;
+  fund(quote: Record<string, unknown>): Promise<{ hash: string; clientReference: string }>;
+  confirm(options: { quoteId: string; transactionHash: string; sshAuthorizedKey: string }): Promise<Record<string, unknown>>;
+  leases(): Promise<Array<Record<string, unknown>>>;
+  access(leaseId: number): Promise<LeaseAccess>;
+  result(leaseId: number): Promise<Record<string, unknown>>;
+  waitForResult(leaseId: number, options?: { timeoutMs?: number; intervalMs?: number }): Promise<Record<string, unknown>>;
+  waitForAccess(leaseId: number, options?: { timeoutMs?: number; intervalMs?: number }): Promise<LeaseAccess>;
+  lease(options: {
+    image: string;
+    durationSeconds: number;
+    minVramMib?: number;
+    preferredNodeId?: string | null;
+    maxDeposit?: number | string | bigint | null;
+    minTrustClass?: string;
+    command?: string | null;
+  }): Promise<LeaseHandle | BatchLeaseHandle>;
+  run(
+    lease: LeaseHandle,
+    command: string,
+    options?: { timeoutMs?: number; connectRetries?: number; connectDelayMs?: number; stdin?: string | null },
+  ): Promise<RunResult>;
+  endLease(lease: LeaseHandle): void;
+}
+
+export declare class PrismError extends Error {
+  readonly status: number;
+  readonly code: string;
+  readonly body: Record<string, unknown> | null | undefined;
+}

package/prism.mjs

@@ -15,8 +15,15 @@ import {
 } from "viem";
 import { privateKeyToAccount } from "viem/accounts";
 import { PrismVault } from "./vault.mjs";
+import { PrismWorkspace } from "./workspace.mjs";
 
 export { PrismVault, VaultError, DEFAULT_TRUST_FLOOR, VAULT_KEY_STATEMENT } from "./vault.mjs";
+export {
+  PrismWorkspace,
+  WorkspaceError,
+  DEFAULT_WORKSPACE_TRUST_FLOOR,
+  WORKSPACE_KEY_STATEMENT,
+} from "./workspace.mjs";
 
 export const robinhoodChain = defineChain({
   id: 4663,
@@ -51,7 +58,7 @@ const escrowAbi = parseAbi([
 
 // Matches the limit the control plane and the node both enforce, so a command
 // that cannot run is rejected here rather than after an escrow is funded.
-const MAX_COMMAND_BYTES = 8 * 1024;
+export const MAX_COMMAND_BYTES = 8 * 1024;
 
 function assertCommand(value) {
   if (typeof value !== "string" || value.trim() === "") {
@@ -100,22 +107,36 @@ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 export class PrismAgent {
   constructor({ privateKey, apiBase = "https://prismnetwork.tech", escrow, rpcUrl }) {
     if (!escrow) throw new Error("escrow address is required");
+    if (typeof privateKey !== "string" || privateKey.trim() === "") {
+      throw new Error(
+        "privateKey is required: a 32-byte hex key, with or without 0x (most surfaces read it from PRISM_AGENT_KEY)",
+      );
+    }
     this.apiBase = apiBase.replace(/\/$/, "");
     this.escrow = escrow;
-    this.account = privateKeyToAccount(privateKey);
+    const trimmed = privateKey.trim();
+    try {
+      this.account = privateKeyToAccount(trimmed.startsWith("0x") ? trimmed : `0x${trimmed}`);
+    } catch (err) {
+      throw new Error(
+        `privateKey is not a valid key: ${err?.message ?? err}. Expected 32 bytes of hex, with or without the 0x prefix.`,
+      );
+    }
     const transport = http(rpcUrl ?? robinhoodChain.rpcUrls.default.http[0]);
     this.publicClient = createPublicClient({ chain: robinhoodChain, transport });
     this.walletClient = createWalletClient({ account: this.account, chain: robinhoodChain, transport });
     this.session = null;
     this.vault = new PrismVault(this);
+    this.workspace = new PrismWorkspace(this);
   }
 
   get address() {
     return this.account.address;
   }
 
-  // The vault key is derived from this signature on the caller's machine. It is
-  // returned to the vault client and never sent anywhere.
+  // The vault and workspace keys are derived from this signature on the
+  // caller's machine. It is returned to the client that asked and never sent
+  // anywhere.
   async signVaultStatement(statement) {
     return this.account.signMessage({ message: statement });
   }
@@ -124,6 +145,10 @@ export class PrismAgent {
     return this.#proxy(method, ["vault", ...segments], { body });
   }
 
+  async workspaceRequest(method, segments, { body = null } = {}) {
+    return this.#proxy(method, ["workspaces", ...segments], { body });
+  }
+
   async authenticate() {
     const challenge = await this.#json(`/api/agent/challenge?address=${this.address}`);
     const signature = await this.account.signMessage({ message: challenge.message });
@@ -251,13 +276,43 @@ export class PrismAgent {
 
   async waitForResult(leaseId, { timeoutMs = 900_000, intervalMs = 10_000 } = {}) {
     const deadline = Date.now() + timeoutMs;
+    let polls = 0;
     while (Date.now() < deadline) {
       const res = await this.#proxy("GET", ["leases", String(leaseId), "result"], { raw: true });
       if (res.status === 200) return res.body;
-      if (res.status !== 404) throw new PrismError(res.status, res.body?.code ?? "result_failed", res.body);
-      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+      // The control plane keeps answering 404 for a batch whose node died
+      // without reporting, so check the lease state occasionally and stop
+      // waiting once it is terminal. 429 and 5xx are transient; aborting a
+      // paid wait on one would strand the deposit.
+      if (res.status === 404) {
+        polls += 1;
+        if (polls % 6 === 0) {
+          const state = await this.#terminalState(leaseId);
+          if (state) {
+            const again = await this.#proxy("GET", ["leases", String(leaseId), "result"], { raw: true });
+            if (again.status === 200) return again.body;
+            throw new PrismError(502, "batch_no_result", { lease_id: leaseId, state });
+          }
+        }
+      } else if (res.status !== 429 && res.status < 500) {
+        throw new PrismError(res.status, res.body?.code ?? "result_failed", res.body);
+      }
+      await sleep(intervalMs);
     }
-    throw new PrismError(408, "result_timeout");
+    throw new PrismError(408, "result_timeout", { lease_id: leaseId });
+  }
+
+  async #terminalState(leaseId) {
+    let leases;
+    try {
+      leases = await this.leases();
+    } catch {
+      return null;
+    }
+    const record = Array.isArray(leases) ? leases.find((l) => l.lease_id === leaseId) : null;
+    const state = record?.state ?? "";
+    const terminal = ["closing", "settlement_pending", "finalized", "refunded", "failed"];
+    return terminal.includes(state) ? state : null;
   }
 
   async waitForAccess(leaseId, { timeoutMs = 600_000, intervalMs = 10_000 } = {}) {
@@ -268,10 +323,12 @@ export class PrismAgent {
         if (!res.body?.ssh_host && res.body?.mode !== "gateway") throw new PrismError(502, "malformed_access");
         return res.body;
       }
-      if (res.status !== 404) throw new PrismError(res.status, res.body?.error ?? "access_error");
+      if (res.status !== 404 && res.status !== 429 && res.status < 500) {
+        throw new PrismError(res.status, res.body?.error ?? "access_error", res.body);
+      }
       await sleep(intervalMs);
     }
-    throw new PrismError(408, "access_timeout");
+    throw new PrismError(408, "access_timeout", { lease_id: leaseId });
   }
 
   // quote -> ssh keygen -> fund on-chain -> confirm -> wait for access.
@@ -285,6 +342,18 @@ export class PrismAgent {
     command = null,
   } = {}) {
     if (!this.session) await this.authenticate();
+    // A wallet with no balance at all cannot fund anything, and a doomed quote
+    // still holds capacity against other renters until it expires. Refuse
+    // before quoting.
+    const balances = await this.balances();
+    if (balances.usdg === "0" || balances.eth === "0") {
+      throw new PrismError(402, "wallet_unfunded", {
+        address: this.address,
+        usdg: balances.usdg,
+        eth_wei: balances.eth,
+        hint: "the wallet needs USDG for the deposit and native ETH for gas on Robinhood Chain (id 4663) before it can lease",
+      });
+    }
     const quote = await this.quote({
       image,
       durationSeconds,
@@ -297,25 +366,30 @@ export class PrismAgent {
       throw new PrismError(402, "cost_exceeds_max", { required: quote.maximum_escrow, max: String(maxDeposit) });
     }
     const key = this.#generateSshKey();
+    let funded = null;
+    let leaseId = null;
     try {
-      const funded = await this.fund(quote);
+      funded = await this.fund(quote);
       const record = await this.confirm({
         quoteId: quote.quote_id,
         transactionHash: funded.hash,
         sshAuthorizedKey: key.publicKey,
       });
-      if (!Number.isInteger(record?.lease_id)) throw new PrismError(502, "malformed_lease_record");
+      if (!Number.isInteger(record?.lease_id)) {
+        throw new PrismError(502, "malformed_lease_record", { funding_hash: funded.hash });
+      }
+      leaseId = record.lease_id;
       // A batch lease never hands out access, so waiting for it would block
       // until the timeout and then report a failure that never happened. Wait
       // for what the command printed instead.
       if (command !== null) {
-        const result = await this.waitForResult(record.lease_id);
+        const result = await this.waitForResult(leaseId, { timeoutMs: durationSeconds * 1000 + 900_000 });
         rmSync(key.dir, { recursive: true, force: true });
-        return { leaseId: record.lease_id, result, fundingHash: funded.hash, quote };
+        return { leaseId, result, fundingHash: funded.hash, quote };
       }
-      const access = await this.waitForAccess(record.lease_id);
+      const access = await this.waitForAccess(leaseId);
       return {
-        leaseId: record.lease_id,
+        leaseId,
         access,
         keyPath: key.keyPath,
         keyDir: key.dir,
@@ -324,17 +398,33 @@ export class PrismAgent {
         quote,
       };
     } catch (err) {
-      rmSync(key.dir, { recursive: true, force: true });
-      throw err;
+      // Before funding, the key opens nothing; discard it. After funding it is
+      // the only way into a machine that is being paid for, so it stays on
+      // disk and the error says where everything is.
+      if (funded === null) {
+        rmSync(key.dir, { recursive: true, force: true });
+        throw err;
+      }
+      const detail = { funding_hash: funded.hash, lease_id: leaseId, key_path: key.keyPath };
+      if (err instanceof PrismError) {
+        err.body = { ...(err.body ?? {}), ...detail };
+        throw err;
+      }
+      throw new PrismError(502, "lease_failed_after_funding", { ...detail, cause: err?.message ?? String(err) });
     }
   }
 
   // Run a command in the remote login shell over SSH (so pipes, redirects, and
   // $(...) all evaluate on the GPU). Retries through the host's sshd warmup, which
-  // can lag a few minutes after the box reports ready.
-  async run(lease, command, { timeoutMs = 120_000, connectRetries = 24, connectDelayMs = 10_000 } = {}) {
+  // can lag a few minutes after the box reports ready. `stdin` feeds the command
+  // its input, which keeps anything sensitive out of the remote process table.
+  async run(lease, command, { timeoutMs = 120_000, connectRetries = 24, connectDelayMs = 10_000, stdin = null } = {}) {
     if (!lease?.access?.ssh_host || !lease.access.ssh_port || !lease.keyPath) {
-      throw new PrismError(400, "invalid_lease_handle");
+      throw new PrismError(400, "invalid_lease_handle", {
+        mode: lease?.access?.mode ?? null,
+        lease_id: lease?.leaseId ?? null,
+        hint: "gateway-mode access has no ssh endpoint",
+      });
     }
     if (typeof command !== "string" || command.length === 0) throw new PrismError(400, "command_required");
     const target = {
@@ -345,7 +435,7 @@ export class PrismAgent {
     };
     let last;
     for (let attempt = 0; attempt <= connectRetries; attempt++) {
-      const res = await this.#ssh(target, command, timeoutMs);
+      const res = await this.#ssh(target, command, timeoutMs, stdin);
       if (!isSshWarmup(res)) return res;
       last = res;
       if (attempt < connectRetries) await sleep(connectDelayMs);
@@ -376,7 +466,7 @@ export class PrismAgent {
     }
   }
 
-  #ssh(target, command, timeoutMs) {
+  #ssh(target, command, timeoutMs, stdin = null) {
     const args = [
       "-i", target.keyPath,
       "-p", String(target.port),
@@ -398,6 +488,12 @@ export class PrismAgent {
       }, timeoutMs);
       child.stdout.on("data", (d) => (stdout += d));
       child.stderr.on("data", (d) => (stderr += d));
+      if (stdin !== null) {
+        // A command that exits before reading its input closes the pipe, which
+        // is a normal end to the transfer and not a failure to report.
+        child.stdin.on("error", () => {});
+        child.stdin.end(stdin);
+      }
       child.on("close", (code) => {
         clearTimeout(timer);
         resolve({ code: code ?? -1, stdout: stdout.trim(), stderr: stderr.trim(), timedOut });
@@ -455,6 +551,7 @@ export class PrismAgent {
 export class PrismError extends Error {
   constructor(status, code, body) {
     super(`prism ${status}: ${code}`);
+    this.name = "PrismError";
     this.status = status;
     this.code = code;
     this.body = body;

package/toolset.d.mts

@@ -0,0 +1,30 @@
+import type { PrismAgent } from "./prism.mjs";
+
+export declare const DEFAULT_ESCROW: string;
+export declare const PUBLIC_API: string;
+export declare const NO_WALLET: string;
+
+export declare function isRefusal(body: string): boolean;
+
+export declare function agentFromEnv(
+  get?: (name: string) => string | undefined,
+): PrismAgent | null;
+
+export interface LeaseAndRunOptions {
+  command: string;
+  durationSeconds?: number;
+  minVramMib?: number;
+  image?: string;
+  maxUsdg?: number;
+  minTrustClass?: "open" | "isolated" | "attested" | "confidential";
+}
+
+export declare class PrismToolset {
+  constructor(options?: { agent?: PrismAgent | null; publicApi?: string });
+  readonly agent: PrismAgent | null;
+  wallet(): Promise<string>;
+  listGpus(minTrustClass?: string): Promise<string>;
+  leaseAndRun(options: LeaseAndRunOptions): Promise<string>;
+  run(leaseId: number, command: string): Promise<string>;
+  endLease(leaseId: number): string;
+}