@projectsolo/solo-mission-mcp 0.20.1 → 0.21.2

package/dist/index.js

@@ -957,6 +957,26 @@ var solanaTools = [
       },
       required: ["mission_id", "expected_budget"]
     }
+  },
+  {
+    name: "refund_solana_mission",
+    description: "Get a Solana mission's escrowed funds back to the sponsor. Covers all three routes: cancel (while funded, before hiring closes), emergency_refund (once the settlement deadline passes and the platform has not settled), and claim_refund (leftover budget after a partial settle).\n\nSame flow as funding: the backend builds the transaction, this tool VERIFIES it, signs locally, and submits. Your key never leaves this process.\n\nCall with no action to ask what is currently available \u2014 the response lists the legal actions for the mission's state rather than guessing. Without this tool a funded Solana mission's money was unreachable except by hand-assembling an Anchor instruction, for which Solana has no `cast send` equivalent.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string" },
+        action: {
+          type: "string",
+          enum: ["cancel", "emergency_refund", "claim_refund"],
+          description: "Omit to query what is available for this mission right now instead of attempting one."
+        },
+        dry_run: {
+          type: "boolean",
+          description: "Build and verify without signing or submitting. Nothing moves, no fee."
+        }
+      },
+      required: ["mission_id"]
+    }
   }
 ];
 function toRawAmount(amount, decimals) {
@@ -1084,6 +1104,86 @@ async function handleSolanaTool(name, args) {
       );
       return { funded: true, verified: true, ...confirmed };
     }
+    case "refund_solana_mission": {
+      const { loadSolanaWallet, associatedTokenAddress, signTransaction } = await import("./wallet-IUQWBW6F.js");
+      const wallet = await loadSolanaWallet();
+      const cfg = await apiGet2("/agent/solana/config");
+      const mint = cfg.mints.TEST_USDC ?? Object.values(cfg.mints)[0];
+      const tokenAccount = await associatedTokenAddress(mint, wallet.publicKey);
+      if (!args.action) {
+        try {
+          await apiPost2(`/agent/solana/missions/${args.mission_id}/refund-transaction`, {
+            action: "claim_refund",
+            sponsor_wallet: wallet.publicKey,
+            sponsor_token_account: tokenAccount
+          });
+          return { available_actions: ["claim_refund"], note: "claim_refund is available now" };
+        } catch (e) {
+          const body = e?.data ?? e?.response?.data ?? e?.body ?? {};
+          return {
+            available_actions: body.available_actions ?? [],
+            why_not_claim_refund: body.message,
+            note: (body.available_actions?.length ?? 0) === 0 ? "Nothing is refundable right now. cancel needs the hiring window still open; emergency_refund needs the settlement deadline to have passed." : "Re-run with one of available_actions."
+          };
+        }
+      }
+      const built = await apiPost2(
+        `/agent/solana/missions/${args.mission_id}/refund-transaction`,
+        {
+          action: args.action,
+          sponsor_wallet: wallet.publicKey,
+          sponsor_token_account: tokenAccount
+        }
+      );
+      const { Transaction, PublicKey } = await import("@solana/web3.js");
+      const tx = Transaction.from(Buffer.from(built.transaction_base64, "base64"));
+      const problems = [];
+      if (tx.instructions.length !== 1) {
+        problems.push(`expected 1 instruction, found ${tx.instructions.length}`);
+      }
+      const ix = tx.instructions[0];
+      if (ix?.programId?.toBase58() !== cfg.program_id) {
+        problems.push(`program is ${ix?.programId?.toBase58()}, expected ${cfg.program_id}`);
+      }
+      const signers = (ix?.keys ?? []).filter((k) => k.isSigner).map((k) => k.pubkey.toBase58());
+      if (signers.length !== 1 || signers[0] !== wallet.publicKey) {
+        problems.push(`expected only ${wallet.publicKey} to sign, found [${signers.join(", ")}]`);
+      }
+      const keys = (ix?.keys ?? []).map((k) => k.pubkey.toBase58());
+      if (!keys.includes(tokenAccount)) {
+        problems.push(
+          `the refund destination ${tokenAccount} is not in the transaction \u2014 the funds would go elsewhere`
+        );
+      }
+      if ((ix?.data?.length ?? 0) !== 8) {
+        problems.push(`instruction data is ${ix?.data?.length} bytes, expected 8`);
+      }
+      void PublicKey;
+      if (problems.length > 0) {
+        return {
+          refunded: false,
+          refused_to_sign: true,
+          problems,
+          what_this_means: "The refund transaction does not match what was asked for, so it was NOT signed and nothing moved. Do not retry blindly."
+        };
+      }
+      if (args.dry_run) {
+        return {
+          refunded: false,
+          dry_run: true,
+          verified: true,
+          action: args.action,
+          task_id: built.task_id,
+          destination: tokenAccount
+        };
+      }
+      const signed = await signTransaction(built.transaction_base64, wallet);
+      const confirmed = await apiPost2(
+        `/agent/solana/missions/${args.mission_id}/confirm-refund`,
+        { signed_transaction: signed, action: args.action }
+      );
+      return { refunded: true, verified: true, ...confirmed };
+    }
     default:
       throw new Error(`Unknown Solana tool: ${name}`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@projectsolo/solo-mission-mcp",
-  "version": "0.20.1",
+  "version": "0.21.2",
   "description": "MCP server for Solo Mission Platform \u2014 lets AI agents create missions, browse humans, and chat.",
   "type": "module",
   "main": "dist/index.js",

package/src/scripts/check-tools-against-spec.ts

@@ -122,10 +122,46 @@ try {
   process.exit(1);
 }
 
-const uncalled = specRoutes.filter((route) => !called.has(route) && !route.endsWith('/agent/openapi.json'));
+/**
+ * Whether a documented route is this package's responsibility at all.
+ *
+ * This is an AGENT-facing package: every tool authenticates with X-Agent-Key. A human-authenticated
+ * route is out of scope by design — an agent has no Firebase user token and could not call it if a
+ * tool existed.
+ *
+ * The check's original premise, "every route the spec documents must be called by something here",
+ * held only while the spec happened to annotate agent routes exclusively. It broke the moment
+ * solo-firebase documented `GET /human/solana/rewards` and `POST /profile/wallet/solana/bind` —
+ * correctly, since a published API should describe its human surface too. The Base equivalents
+ * (`/human/rewards`, `/profile/wallet/bind`) are simply not annotated yet, which is why this never
+ * fired before rather than the rule ever having been right.
+ *
+ * Scoped by path prefix rather than an allowlist of specific routes, so the next human endpoint
+ * does not fail a release for the same reason.
+ */
+function isAgentScoped(route: string): boolean {
+  const path = route.split(' ')[1] ?? '';
+  return path.startsWith('/agent') || path.startsWith('/missions') || path.startsWith('/humans');
+}
+
+const uncalled = specRoutes.filter(
+  (route) =>
+    !called.has(route) &&
+    !route.endsWith('/agent/openapi.json') &&
+    isAgentScoped(route),
+);
+
+const outOfScope = specRoutes.filter((route) => !isAgentScoped(route));
+if (outOfScope.length > 0) {
+  // Reported, not silent: a route landing here because it is genuinely human-facing is fine, but
+  // one landing here because an agent route was misnamed would otherwise vanish from the check.
+  console.log('Human-authenticated routes, out of scope for this agent-facing package:');
+  for (const route of outOfScope) console.log(`  - ${route}`);
+  console.log('');
+}
 
 if (uncalled.length > 0) {
-  console.error("The live API spec documents routes that no tool in src/tools/*.ts calls:");
+  console.error("The live API spec documents AGENT routes that no tool in src/tools/*.ts calls:");
   for (const route of uncalled) console.error(`  - ${route}`);
   console.error(`\nSpec source: ${SPEC_URL}`);
   console.error("Either a tool's REST call was changed/removed without updating this check's");

package/src/tools/solana.ts

@@ -63,6 +63,28 @@ export const solanaTools: Tool[] = [
       required: ['mission_id', 'expected_budget'],
     },
   },
+  {
+    name: 'refund_solana_mission',
+    description:
+      "Get a Solana mission's escrowed funds back to the sponsor. Covers all three routes: cancel (while funded, before hiring closes), emergency_refund (once the settlement deadline passes and the platform has not settled), and claim_refund (leftover budget after a partial settle).\n\nSame flow as funding: the backend builds the transaction, this tool VERIFIES it, signs locally, and submits. Your key never leaves this process.\n\nCall with no action to ask what is currently available — the response lists the legal actions for the mission's state rather than guessing. Without this tool a funded Solana mission's money was unreachable except by hand-assembling an Anchor instruction, for which Solana has no `cast send` equivalent.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        mission_id: { type: 'string' },
+        action: {
+          type: 'string',
+          enum: ['cancel', 'emergency_refund', 'claim_refund'],
+          description:
+            'Omit to query what is available for this mission right now instead of attempting one.',
+        },
+        dry_run: {
+          type: 'boolean',
+          description: 'Build and verify without signing or submitting. Nothing moves, no fee.',
+        },
+      },
+      required: ['mission_id'],
+    },
+  },
 ];
 
 /**
@@ -248,6 +270,115 @@ export async function handleSolanaTool(
       return { funded: true, verified: true, ...(confirmed as Record<string, unknown>) };
     }
 
+    case 'refund_solana_mission': {
+      const { loadSolanaWallet, associatedTokenAddress, signTransaction } = await import(
+        '../solana/wallet.js'
+      );
+      const wallet = await loadSolanaWallet();
+      const cfg = (await apiGet('/agent/solana/config')) as {
+        program_id: string;
+        mints: Record<string, string>;
+      };
+      const mint = cfg.mints.TEST_USDC ?? Object.values(cfg.mints)[0];
+      const tokenAccount = await associatedTokenAddress(mint, wallet.publicKey);
+
+      // No action: ask what is legal rather than guessing and getting a 409. Uses a deliberately
+      // invalid action so the backend answers with available_actions for this mission's state.
+      if (!args.action) {
+        try {
+          await apiPost(`/agent/solana/missions/${args.mission_id}/refund-transaction`, {
+            action: 'claim_refund',
+            sponsor_wallet: wallet.publicKey,
+            sponsor_token_account: tokenAccount,
+          });
+          return { available_actions: ['claim_refund'], note: 'claim_refund is available now' };
+        } catch (e: any) {
+          // ApiResponseError carries the parsed body on `.data`; the other shapes are kept for
+          // any client that wraps differently. Reading only the latter silently yielded an empty
+          // available_actions, i.e. a false "nothing is refundable" on a mission that could cancel.
+          const body: any = e?.data ?? e?.response?.data ?? e?.body ?? {};
+          return {
+            available_actions: body.available_actions ?? [],
+            why_not_claim_refund: body.message,
+            note:
+              (body.available_actions?.length ?? 0) === 0
+                ? 'Nothing is refundable right now. cancel needs the hiring window still open; ' +
+                  'emergency_refund needs the settlement deadline to have passed.'
+                : 'Re-run with one of available_actions.',
+          };
+        }
+      }
+
+      const built = (await apiPost(
+        `/agent/solana/missions/${args.mission_id}/refund-transaction`,
+        {
+          action: args.action,
+          sponsor_wallet: wallet.publicKey,
+          sponsor_token_account: tokenAccount,
+        },
+      )) as { transaction_base64: string; task_id: string };
+
+      // Verify before signing, same rule as funding: a headless agent has no wallet UI, so an
+      // unverified blob is bytes it cannot read. A refund moves the WHOLE escrow, so the checks
+      // that matter are that it is our program, we are the only signer, and the tokens land in our
+      // own token account.
+      const { Transaction, PublicKey } = await import('@solana/web3.js');
+      const tx = Transaction.from(Buffer.from(built.transaction_base64, 'base64'));
+      const problems: string[] = [];
+      if (tx.instructions.length !== 1) {
+        problems.push(`expected 1 instruction, found ${tx.instructions.length}`);
+      }
+      const ix = tx.instructions[0];
+      if (ix?.programId?.toBase58() !== cfg.program_id) {
+        problems.push(`program is ${ix?.programId?.toBase58()}, expected ${cfg.program_id}`);
+      }
+      const signers = (ix?.keys ?? []).filter((k) => k.isSigner).map((k) => k.pubkey.toBase58());
+      if (signers.length !== 1 || signers[0] !== wallet.publicKey) {
+        problems.push(`expected only ${wallet.publicKey} to sign, found [${signers.join(', ')}]`);
+      }
+      const keys = (ix?.keys ?? []).map((k) => k.pubkey.toBase58());
+      if (!keys.includes(tokenAccount)) {
+        problems.push(
+          `the refund destination ${tokenAccount} is not in the transaction — the funds would go elsewhere`,
+        );
+      }
+      // No arguments on any of the three instructions, so the data is exactly the 8-byte
+      // discriminator. Anything longer means something was appended.
+      if ((ix?.data?.length ?? 0) !== 8) {
+        problems.push(`instruction data is ${ix?.data?.length} bytes, expected 8`);
+      }
+      void PublicKey;
+
+      if (problems.length > 0) {
+        return {
+          refunded: false,
+          refused_to_sign: true,
+          problems,
+          what_this_means:
+            'The refund transaction does not match what was asked for, so it was NOT signed and ' +
+            'nothing moved. Do not retry blindly.',
+        };
+      }
+
+      if (args.dry_run) {
+        return {
+          refunded: false,
+          dry_run: true,
+          verified: true,
+          action: args.action,
+          task_id: built.task_id,
+          destination: tokenAccount,
+        };
+      }
+
+      const signed = await signTransaction(built.transaction_base64, wallet);
+      const confirmed = await apiPost(
+        `/agent/solana/missions/${args.mission_id}/confirm-refund`,
+        { signed_transaction: signed, action: args.action },
+      );
+      return { refunded: true, verified: true, ...(confirmed as Record<string, unknown>) };
+    }
+
     default:
       throw new Error(`Unknown Solana tool: ${name}`);
   }