@agent-fuel/sdk 0.3.0 → 0.3.1

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes to `@agent-fuel/sdk` are documented here. Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this package follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.1] — 2026-05-31
+
+### Changed
+
+- CLI: replace the generic `account not found: <PDA>` with command-specific messages that name the missing resource and the inputs that produced the lookup. `agent-fuel vault Cowi… 5ro8…` now reports `no vault found at <PDA> for owner=Cowi… agent=5ro8… — has init_vault been called for this pair?` instead of dumping a raw PDA the user has no way to map back. Applies to `score`, `vault`, `policy`, `service`, and `pay`.
+
 ## [0.3.0] — 2026-05-31
 
 ### Added

package/dist/cli.cjs

@@ -4163,7 +4163,7 @@ async function safeText(res) {
 }
 
 // src/cli.ts
-var VERSION = "0.3.0";
+var VERSION = "0.3.1";
 var RPC_DEFAULTS = {
   "mainnet-beta": "https://api.mainnet-beta.solana.com",
   devnet: "https://api.devnet.solana.com",
@@ -4281,6 +4281,16 @@ function jsonReplacer(_key, value) {
 function errMsg(e) {
   return e instanceof Error ? e.message : String(e);
 }
+async function rephraseNotFound(fn, reword) {
+  try {
+    return await fn();
+  } catch (e) {
+    if (e instanceof AccountNotFoundError) {
+      throw new Error(reword(e.account));
+    }
+    throw e;
+  }
+}
 function explorerUrl(cluster, sig) {
   const suffix = cluster === "mainnet-beta" ? "" : `?cluster=${cluster}`;
   return `https://explorer.solana.com/tx/${sig}${suffix}`;
@@ -4299,7 +4309,10 @@ program.command("score <agent>").description("Show the latest reputation snapsho
   const g = readGlobalOpts(cmd);
   const agentPk = parsePubkey(agent, "<agent>");
   const fuel = readOnlyFuel(g);
-  const score = await fuel.getScore(agentPk);
+  const score = await rephraseNotFound(
+    () => fuel.getScore(agentPk),
+    () => `no reputation data yet for agent ${agent} \u2014 the backend has no AgentProfile mirror for this agent (it hasn't received any recorded payments)`
+  );
   emit(g, () => formatScore(score), score);
 });
 program.command("vault <owner> <agent>").description("Show on-chain credit vault state for the (owner, agent) pair.").action(async (owner, agent, _opts, cmd) => {
@@ -4307,7 +4320,10 @@ program.command("vault <owner> <agent>").description("Show on-chain credit vault
   const ownerPk = parsePubkey(owner, "<owner>");
   const agentPk = parsePubkey(agent, "<agent>");
   const fuel = readOnlyFuel(g);
-  const vault = await fuel.getVaultBalance({ owner: ownerPk, agent: agentPk });
+  const vault = await rephraseNotFound(
+    () => fuel.getVaultBalance({ owner: ownerPk, agent: agentPk }),
+    (pda) => `no vault found at ${pda} for owner=${owner} agent=${agent} \u2014 has init_vault been called for this pair?`
+  );
   emit(g, () => formatVault(vault), vault);
 });
 program.command("policy <owner> <agent>").description("Show the spend policy guarding an (owner, agent) vault.").action(async (owner, agent, _opts, cmd) => {
@@ -4315,14 +4331,20 @@ program.command("policy <owner> <agent>").description("Show the spend policy gua
   const ownerPk = parsePubkey(owner, "<owner>");
   const agentPk = parsePubkey(agent, "<agent>");
   const fuel = readOnlyFuel(g);
-  const policy = await fuel.getPolicy({ owner: ownerPk, agent: agentPk });
+  const policy = await rephraseNotFound(
+    () => fuel.getPolicy({ owner: ownerPk, agent: agentPk }),
+    (pda) => `no spend policy found at ${pda} for owner=${owner} agent=${agent} \u2014 policy is created alongside the vault, so this usually means init_vault hasn't been called`
+  );
   emit(g, () => formatPolicy(policy), policy);
 });
 program.command("service <authority>").description("Look up a registered service by its authority pubkey.").action(async (authority, _opts, cmd) => {
   const g = readGlobalOpts(cmd);
   const authPk = parsePubkey(authority, "<authority>");
   const fuel = readOnlyFuel(g);
-  const svc = await fuel.checkService(authPk);
+  const svc = await rephraseNotFound(
+    () => fuel.checkService(authPk),
+    (pda) => `no service registered for authority ${authority} (registry PDA ${pda} doesn't exist) \u2014 run \`agent-fuel register-service\` to create one`
+  );
   emit(g, () => formatService(svc), svc);
 });
 program.command("pay").description(
@@ -4338,14 +4360,17 @@ program.command("pay").description(
     const owner = parsePubkey(opts.owner, "--owner");
     const amountUsdc = parseAmountToMicro(opts.amount);
     const receiptHash = parseReceiptHash(opts.receiptHash);
-    const result = await pay({
-      agent,
-      service,
-      owner,
-      amountUsdc,
-      receiptHash,
-      connection: connectionFor(g)
-    });
+    const result = await rephraseNotFound(
+      () => pay({
+        agent,
+        service,
+        owner,
+        amountUsdc,
+        receiptHash,
+        connection: connectionFor(g)
+      }),
+      (pda) => `pay failed: account not found at ${pda} \u2014 either the vault for owner=${opts.owner} agent=${agent.publicKey.toBase58()} doesn't exist, or the spend policy hasn't been created. Try \`agent-fuel vault ${opts.owner} ${agent.publicKey.toBase58()}\` to verify.`
+    );
     emit(
       g,
       () => [