@projectsolo/solo-mission-mcp 0.21.9 → 0.21.11

package/dist/index.js

@@ -19,25 +19,38 @@ import {
 var RESPONSE_SCHEMA_PROPERTY = {
   type: "array",
   maxItems: 20,
-  description: "Structured completion questions a human answers to complete the mission. When set, finalize_qualification auto-derives qualified UIDs from completion instead of requiring an explicit qualified_human_uids list \u2014 same mechanism media_review has always used for track ratings, generalized to any mission type. media_review defaults to a canonical {rating (stars), comment (long, optional)} schema when this is omitted at creation; every other type has no default (stays fully manual/chat-based unless you set this).",
+  description: 'Structured completion questions a human answers to complete the mission. Question ids must be unique within one schema \u2014 a duplicate id is rejected at creation/update, not merged or silently overwritten. When set, finalize_qualification auto-derives qualified UIDs from completion instead of requiring an explicit qualified_human_uids list \u2014 same mechanism media_review has always used for track ratings, generalized to any mission type. media_review defaults to a canonical two-question schema when this is omitted at creation \u2014 literally { id: "rating", kind: "stars", required: true } and { id: "comment", kind: "long", required: false } \u2014 so read/append against those exact ids if you rely on the default rather than supplying your own schema. Every other type has no default (stays fully manual/chat-based unless you set this).',
   items: {
     type: "object",
     properties: {
-      id: { type: "string", description: "Unique id within this schema \u2014 the key answers are stored under." },
+      id: { type: "string", description: "Unique id within this schema \u2014 the key answers are stored under. Duplicates are rejected, not merged." },
       kind: {
         type: "string",
-        enum: ["single", "multi", "likert", "stars", "short", "long", "dropdown", "consent"],
-        description: "single=one choice, multi=several choices, likert=5-point agreement scale, stars=1-5 rating, short=one line of text, long=paragraph text (see min_length), dropdown=one choice from a long list, consent=a checkbox that must be explicitly true."
+        enum: [
+          "single",
+          "multi",
+          "likert",
+          "stars",
+          "short",
+          "long",
+          "dropdown",
+          "checkbox",
+          "timestamp_tag",
+          "image_region",
+          "video_region_duration"
+        ],
+        description: 'single=one choice, multi=several choices, likert=a scale rendered as a row of buttons (NOT fixed at 5 points \u2014 the number of options you supply IS the number of points, so give exactly as many option labels as the scale should have; a common convention is 5 labels like "1 Strongly disagree".."5 Strongly agree" but nothing enforces that), stars=1-5 rating (fixed, no options), short=one line of text, long=paragraph text (see min_length), dropdown=one choice from a long list, checkbox=a checkbox that must be explicitly true (usable for ANY yes/no question, not just consent-flavored ones) \u2014 the checkbox\'s own clickable text is `label` itself (there is no separate heading rendered above it, unlike every other kind); use `help` for any additional wording you want shown near it.\n\nMedia-anchored kinds \u2014 media_review only, need a track to annotate (options/min_length don\'t apply; see min_count instead):\n  timestamp_tag: the human flags a moment in an audio/video track while it plays. Each flag is { t (seconds), tag (category \u2014 one of `options` if you set it, otherwise any non-empty string), note? }. `options` is OPTIONAL here (unlike the choice kinds above) \u2014 omit it for free-form tagging, or set it to offer a closed category list.\n  image_region: the human draws a rectangle on an image track and comments on it. Each region is { x, y, width, height (all 0-1, fraction of the image, not pixels), comment }.\n  video_region_duration: like image_region, but the rectangle is held for a single time range rather than a single point \u2014 { start, end (seconds, end > start), x, y, width, height, comment }. One fixed box for the whole range, not tracked frame by frame.'
       },
-      label: { type: "string", description: "Question text shown to the human (max 200 chars)." },
+      label: { type: "string", description: "Question text shown to the human (max 200 chars). For the checkbox kind this is the checkbox's own clickable text, not a separate heading." },
       help: { type: "string", description: "Optional helper text shown under the label (max 500 chars)." },
       required: { type: "boolean", description: "Whether this question must be answered to complete the mission." },
       options: {
         type: "array",
         items: { type: "string" },
-        description: "Required for single/multi/dropdown/likert (max 20 options, 50 chars each). Not accepted by other kinds."
+        description: "Required (non-empty) for single/multi/dropdown/likert (max 20 options, 50 chars each). Optional for timestamp_tag (a closed category list; omit for free-form tagging). Not accepted by any other kind."
       },
-      min_length: { type: "number", description: "Minimum answer length, only meaningful for the 'long' kind." }
+      min_length: { type: "number", description: "Minimum answer length. Only read for the 'long' kind \u2014 silently ignored (not rejected) if set on any other kind." },
+      min_count: { type: "number", description: "Minimum number of annotations required. Only read for timestamp_tag/image_region/video_region_duration (defaults to 1 if required and unset) \u2014 silently ignored on any other kind." }
     },
     required: ["id", "kind", "label", "required"]
   }
@@ -90,7 +103,7 @@ var missionTools = [
   },
   {
     name: "update_mission_questions",
-    description: "Set or replace a mission's response_schema after creation. Locked once hiring starts \u2014 same window as add_mission_track (on-chain: only before funding; off-chain: only while active with zero hired participants yet). Replaces the entire schema, not a merge.",
+    description: "Set or replace a mission's response_schema after creation. Locked once hiring starts \u2014 same window as add_mission_track (on-chain: only before funding; off-chain: only while active with zero hired participants yet). This window is what makes a schema replacement safe: a human can only submit answers once hired, and the schema can no longer change once anyone has been hired \u2014 there is no state where a human has answered under one schema and the mission later presents a different one. Replaces the entire schema, not a merge.",
     inputSchema: {
       type: "object",
       properties: {
@@ -1046,7 +1059,7 @@ async function handleSolanaTool(name, args) {
     case "get_solana_config":
       return apiGet2("/agent/solana/config");
     case "get_solana_wallet": {
-      const { hasSolanaWallet, loadSolanaWallet, associatedTokenAddress } = await import("./wallet-IUQWBW6F.js");
+      const { hasSolanaWallet, loadSolanaWallet, associatedTokenAddress } = await import("./wallet-V4T4NTCM.js");
       if (!hasSolanaWallet()) {
         return {
           configured: false,
@@ -1092,7 +1105,7 @@ async function handleSolanaTool(name, args) {
       };
     }
     case "fund_solana_mission": {
-      const { loadSolanaWallet, associatedTokenAddress, signTransaction } = await import("./wallet-IUQWBW6F.js");
+      const { loadSolanaWallet, associatedTokenAddress, signTransaction } = await import("./wallet-V4T4NTCM.js");
       const { verifyFundingTransaction } = await import("./verify-KAETIGV5.js");
       const wallet = await loadSolanaWallet();
       const cfg = await apiGet2("/agent/solana/config");
@@ -1152,10 +1165,17 @@ 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 { loadSolanaWallet, associatedTokenAddress, signTransaction } = await import("./wallet-V4T4NTCM.js");
       const wallet = await loadSolanaWallet();
       const cfg = await apiGet2("/agent/solana/config");
-      const mint = cfg.mints.TEST_USDC ?? Object.values(cfg.mints)[0];
+      const mission = await apiGet2(`/agent/missions/${args.mission_id}`);
+      const mint = mission.mission?.token_address;
+      if (!mint) {
+        return {
+          refunded: false,
+          error: `Could not resolve mission ${args.mission_id}'s token_address \u2014 call get_mission to check it exists and is funded.`
+        };
+      }
       const tokenAccount = await associatedTokenAddress(mint, wallet.publicKey);
       if (!args.action) {
         try {

package/dist/wallet-V4T4NTCM.js

@@ -0,0 +1,143 @@
+// src/solana/wallet.ts
+import { readFileSync } from "fs";
+import { createDecipheriv, pbkdf2Sync } from "crypto";
+var SolanaWalletUnavailable = class extends Error {
+  constructor(reason) {
+    super(
+      `Solana wallet unavailable: ${reason}
+
+Set one of:
+  SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH + SOLO_SOLANA_KEYPAIR_PASSWORD_FILE
+                            - recommended: an openssl-aes-256-cbc-pbkdf2-encrypted
+                              keyfile plus a separate passphrase file (chmod 600 both)
+  SOLO_SOLANA_KEYPAIR       - JSON byte array, as \`solana-keygen\` writes it (plaintext)
+  SOLO_SOLANA_KEYPAIR_PATH  - path to that file (e.g. ~/.config/solana/id.json), plaintext
+
+The wallet needs SOL for rent and fees, and USDC for the mission budget. Rent is a
+refundable deposit, not a fee: most of it returns when the task is closed.`
+    );
+    this.name = "SolanaWalletUnavailable";
+  }
+};
+function decryptOpenSslAes256CbcPbkdf2(encrypted, password) {
+  const MAGIC = "Salted__";
+  if (encrypted.length < 16 || encrypted.subarray(0, 8).toString("utf8") !== MAGIC) {
+    throw new SolanaWalletUnavailable('encrypted keyfile is missing the OpenSSL "Salted__" header');
+  }
+  const salt = encrypted.subarray(8, 16);
+  const ciphertext = encrypted.subarray(16);
+  const derived = pbkdf2Sync(password, salt, 1e4, 48, "sha256");
+  const key = derived.subarray(0, 32);
+  const iv = derived.subarray(32, 48);
+  const decipher = createDecipheriv("aes-256-cbc", key, iv);
+  try {
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  } catch (e) {
+    throw new SolanaWalletUnavailable(
+      `failed to decrypt keyfile \u2014 wrong passphrase, or the file wasn't produced by 'openssl enc -aes-256-cbc -pbkdf2 -iter 10000 -md sha256' (${e.message})`
+    );
+  }
+}
+function parseKeypairBytes(raw) {
+  const trimmed = raw.trim();
+  if (!trimmed.startsWith("[")) {
+    throw new SolanaWalletUnavailable(
+      "value is not a JSON byte array \u2014 this is the format `solana-keygen new` writes"
+    );
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    throw new SolanaWalletUnavailable("value looks like a JSON array but does not parse");
+  }
+  if (!Array.isArray(parsed) || !parsed.every((n) => typeof n === "number")) {
+    throw new SolanaWalletUnavailable("JSON array must contain only numbers");
+  }
+  const bytes = Uint8Array.from(parsed);
+  if (bytes.length !== 64) {
+    throw new SolanaWalletUnavailable(
+      `expected 64 bytes, got ${bytes.length}` + (bytes.length === 32 ? " \u2014 this is the seed alone, not the full keypair" : "")
+    );
+  }
+  return bytes;
+}
+function expandHome(path) {
+  return path.replace(/^~/, process.env.HOME ?? "~");
+}
+var cachedWallet;
+async function loadSolanaWallet() {
+  if (cachedWallet) return cachedWallet;
+  const encryptedPath = process.env.SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH;
+  const passwordFile = process.env.SOLO_SOLANA_KEYPAIR_PASSWORD_FILE;
+  const inline = process.env.SOLO_SOLANA_KEYPAIR;
+  const path = process.env.SOLO_SOLANA_KEYPAIR_PATH;
+  let raw;
+  if (encryptedPath && encryptedPath.trim() !== "" || passwordFile && passwordFile.trim() !== "") {
+    if (!encryptedPath || !passwordFile) {
+      throw new SolanaWalletUnavailable(
+        "SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH and SOLO_SOLANA_KEYPAIR_PASSWORD_FILE must both be set \u2014 only one was found"
+      );
+    }
+    let encrypted;
+    let password;
+    try {
+      encrypted = readFileSync(expandHome(encryptedPath));
+    } catch (e) {
+      throw new SolanaWalletUnavailable(`cannot read ${encryptedPath}: ${e.message}`);
+    }
+    try {
+      password = readFileSync(expandHome(passwordFile), "utf8").replace(/\r?\n$/, "");
+    } catch (e) {
+      throw new SolanaWalletUnavailable(`cannot read ${passwordFile}: ${e.message}`);
+    }
+    raw = decryptOpenSslAes256CbcPbkdf2(encrypted, password).toString("utf8");
+  } else if (inline && inline.trim() !== "") {
+    raw = inline;
+  } else if (path && path.trim() !== "") {
+    try {
+      raw = readFileSync(expandHome(path), "utf8");
+    } catch (e) {
+      throw new SolanaWalletUnavailable(`cannot read ${path}: ${e.message}`);
+    }
+  } else {
+    throw new SolanaWalletUnavailable(
+      "no wallet source configured (checked SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH, SOLO_SOLANA_KEYPAIR, SOLO_SOLANA_KEYPAIR_PATH)"
+    );
+  }
+  const secretKey = parseKeypairBytes(raw);
+  const { Keypair } = await import("@solana/web3.js");
+  const kp = Keypair.fromSecretKey(secretKey);
+  cachedWallet = { publicKey: kp.publicKey.toBase58(), secretKey };
+  return cachedWallet;
+}
+function hasSolanaWallet() {
+  return Boolean(
+    cachedWallet || (process.env.SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH ?? "").trim() && (process.env.SOLO_SOLANA_KEYPAIR_PASSWORD_FILE ?? "").trim() || (process.env.SOLO_SOLANA_KEYPAIR ?? "").trim() || (process.env.SOLO_SOLANA_KEYPAIR_PATH ?? "").trim()
+  );
+}
+async function associatedTokenAddress(mint, owner) {
+  const { PublicKey } = await import("@solana/web3.js");
+  const TOKEN_PROGRAM_ID = new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
+  const ASSOCIATED_TOKEN_PROGRAM_ID = new PublicKey("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL");
+  const [address] = PublicKey.findProgramAddressSync(
+    [new PublicKey(owner).toBuffer(), TOKEN_PROGRAM_ID.toBuffer(), new PublicKey(mint).toBuffer()],
+    ASSOCIATED_TOKEN_PROGRAM_ID
+  );
+  return address.toBase58();
+}
+async function signTransaction(transactionBase64, wallet) {
+  const { Keypair, Transaction } = await import("@solana/web3.js");
+  const kp = Keypair.fromSecretKey(wallet.secretKey);
+  const tx = Transaction.from(Buffer.from(transactionBase64, "base64"));
+  tx.partialSign(kp);
+  return tx.serialize().toString("base64");
+}
+export {
+  SolanaWalletUnavailable,
+  associatedTokenAddress,
+  decryptOpenSslAes256CbcPbkdf2,
+  hasSolanaWallet,
+  loadSolanaWallet,
+  signTransaction
+};

package/package.json

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

package/src/solana/fixtures/test-keypair.json.enc

@@ -0,0 +1,2 @@
+Salted__\��H<�WCxUZ��y`�7�A�Ǔ�K�=6��u5D$�Q���Yd�6D����a��'SHԛE����YB��h�`���/����=5�>�������,�S8�l��?[=�-H5�i^�^�
�Oa��R�W,��lj�Cz4/�$���bx�M�_�%;!��A����Cұ
+0y�;�(V

package/src/solana/fixtures/test-keypair.pubkey

@@ -0,0 +1 @@
+GXkK4gbmGPGFmB7vobHeY82ktbAw9VPnHZJits1P2Qjw

package/src/solana/wallet.test.ts

@@ -0,0 +1,45 @@
+/**
+ * `decryptOpenSslAes256CbcPbkdf2` reimplements OpenSSL's KDF natively rather than shelling out, so
+ * it is tested against a REAL `openssl enc -aes-256-cbc -pbkdf2 -iter 10000 -md sha256` fixture —
+ * same reasoning as `verify.test.ts`: a hand-rolled ciphertext would encode my assumptions about the
+ * format twice and could only ever agree with itself, not with the `openssl enc` command the docs
+ * actually tell operators to run.
+ *
+ * `fixtures/test-keypair.json.enc` is a throwaway, never-funded devnet keypair — safe to check in.
+ */
+import { describe, it, expect } from 'vitest';
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { decryptOpenSslAes256CbcPbkdf2, SolanaWalletUnavailable } from './wallet';
+
+const FIXTURE_DIR = join(__dirname, 'fixtures');
+const encrypted = readFileSync(join(FIXTURE_DIR, 'test-keypair.json.enc'));
+const expectedPubkey = readFileSync(join(FIXTURE_DIR, 'test-keypair.pubkey'), 'utf8').trim();
+const PASSPHRASE = 'test-only-fixture-passphrase';
+
+describe('decryptOpenSslAes256CbcPbkdf2', () => {
+  it('decrypts a real openssl-produced ciphertext back to the original JSON keypair', async () => {
+    const plaintext = decryptOpenSslAes256CbcPbkdf2(encrypted, PASSPHRASE).toString('utf8');
+    const bytes = JSON.parse(plaintext);
+    expect(Array.isArray(bytes)).toBe(true);
+    expect(bytes).toHaveLength(64);
+
+    // Confirm it's not just 64 numbers — it's the actual keypair, by deriving the same public key
+    // `solana-keygen pubkey` reported when the fixture was generated.
+    const { Keypair } = await import('@solana/web3.js');
+    const kp = Keypair.fromSecretKey(Uint8Array.from(bytes));
+    expect(kp.publicKey.toBase58()).toBe(expectedPubkey);
+  });
+
+  it('rejects a wrong passphrase rather than silently returning garbage', () => {
+    expect(() => decryptOpenSslAes256CbcPbkdf2(encrypted, 'definitely-not-it')).toThrow(
+      SolanaWalletUnavailable,
+    );
+  });
+
+  it('rejects a file missing the OpenSSL "Salted__" header', () => {
+    expect(() => decryptOpenSslAes256CbcPbkdf2(Buffer.from('not an openssl file'), PASSPHRASE)).toThrow(
+      /Salted__/,
+    );
+  });
+});

package/src/solana/wallet.ts

@@ -19,9 +19,28 @@
  * the Solo API — the backend builds transactions and submits them, but only the agent can authorise
  * one. That is the whole point of the partial-signing flow: a compromised backend cannot move a
  * sponsor's funds, because it never holds the signing key.
+ *
+ * AT REST, prefer SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH + SOLO_SOLANA_KEYPAIR_PASSWORD_FILE over the
+ * plain SOLO_SOLANA_KEYPAIR / SOLO_SOLANA_KEYPAIR_PATH pair. `solana-keygen new`'s own output is a
+ * plaintext JSON byte array — chmod 600 protects it from other users on the box, but not from
+ * whoever gets that one file (a compromised account, a stray backup, a copied disk image). The
+ * encrypted form splits the secret in two: the ciphertext and the passphrase file are only useful
+ * together, matching what `references/wallet-setup.md` already does for the Base private key
+ * (openssl-encrypt at rest, decrypt only transiently). Encrypt with the exact command below so the
+ * decryptor here (which reimplements OpenSSL's KDF, not shells out to it) derives the same key:
+ *
+ *   openssl enc -aes-256-cbc -pbkdf2 -iter 10000 -md sha256 \
+ *     -in ~/.config/solana/solo-sponsor.json -out solo-sponsor.json.enc
+ *   chmod 600 solo-sponsor.json.enc
+ *   echo -n "your-passphrase" > keystore.pass && chmod 600 keystore.pass
+ *   # then delete the plaintext solo-sponsor.json
+ *
+ * The plain SOLO_SOLANA_KEYPAIR / SOLO_SOLANA_KEYPAIR_PATH pair still works, unchanged, for
+ * quick-start / devnet use where this doesn't matter.
  */
 
 import { readFileSync } from 'fs';
+import { createDecipheriv, pbkdf2Sync } from 'crypto';
 
 export interface SolanaWallet {
   publicKey: string;
@@ -34,8 +53,11 @@ export class SolanaWalletUnavailable extends Error {
     super(
       `Solana wallet unavailable: ${reason}\n\n` +
         'Set one of:\n' +
-        '  SOLO_SOLANA_KEYPAIR       - JSON byte array, as `solana-keygen` writes it\n' +
-        '  SOLO_SOLANA_KEYPAIR_PATH  - path to that file (e.g. ~/.config/solana/id.json)\n\n' +
+        '  SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH + SOLO_SOLANA_KEYPAIR_PASSWORD_FILE\n' +
+        '                            - recommended: an openssl-aes-256-cbc-pbkdf2-encrypted\n' +
+        '                              keyfile plus a separate passphrase file (chmod 600 both)\n' +
+        '  SOLO_SOLANA_KEYPAIR       - JSON byte array, as `solana-keygen` writes it (plaintext)\n' +
+        '  SOLO_SOLANA_KEYPAIR_PATH  - path to that file (e.g. ~/.config/solana/id.json), plaintext\n\n' +
         'The wallet needs SOL for rent and fees, and USDC for the mission budget. Rent is a\n' +
         'refundable deposit, not a fee: most of it returns when the task is closed.',
     );
@@ -43,6 +65,39 @@ export class SolanaWalletUnavailable extends Error {
   }
 }
 
+/**
+ * Decrypts a file produced by `openssl enc -aes-256-cbc -pbkdf2 -iter 10000 -md sha256`.
+ *
+ * Reimplemented natively rather than shelling out to `openssl` — this codebase has no
+ * child_process/exec anywhere, and a decrypt helper is not where that invariant should end. OpenSSL
+ * prefixes salted output with the 8-byte literal "Salted__" followed by an 8-byte salt; with
+ * `-pbkdf2` it derives key||iv (32 + 16 bytes for aes-256-cbc) from the passphrase and that salt in
+ * one PBKDF2-HMAC-SHA256 call. Verified byte-for-byte against real `openssl enc`/`openssl enc -d`
+ * output in `wallet.test.ts`.
+ */
+export function decryptOpenSslAes256CbcPbkdf2(encrypted: Buffer, password: string): Buffer {
+  const MAGIC = 'Salted__';
+  if (encrypted.length < 16 || encrypted.subarray(0, 8).toString('utf8') !== MAGIC) {
+    throw new SolanaWalletUnavailable('encrypted keyfile is missing the OpenSSL "Salted__" header');
+  }
+  const salt = encrypted.subarray(8, 16);
+  const ciphertext = encrypted.subarray(16);
+  const derived = pbkdf2Sync(password, salt, 10000, 48, 'sha256');
+  const key = derived.subarray(0, 32);
+  const iv = derived.subarray(32, 48);
+  const decipher = createDecipheriv('aes-256-cbc', key, iv);
+  try {
+    return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+  } catch (e) {
+    // Wrong passphrase almost always surfaces here (bad padding), not as a clean "auth failed" —
+    // CBC has no built-in integrity check, unlike GCM.
+    throw new SolanaWalletUnavailable(
+      `failed to decrypt keyfile — wrong passphrase, or the file wasn't produced by ` +
+        `'openssl enc -aes-256-cbc -pbkdf2 -iter 10000 -md sha256' (${(e as Error).message})`,
+    );
+  }
+}
+
 function parseKeypairBytes(raw: string): Uint8Array {
   const trimmed = raw.trim();
   if (!trimmed.startsWith('[')) {
@@ -71,6 +126,16 @@ function parseKeypairBytes(raw: string): Uint8Array {
   return bytes;
 }
 
+function expandHome(path: string): string {
+  return path.replace(/^~/, process.env.HOME ?? '~');
+}
+
+// Cached after first successful load — avoids re-deriving the PBKDF2 key (and re-reading the
+// passphrase file) on every tool call. Never cache a failure: a missing/misconfigured wallet on
+// one call should not wrongly still look missing after the operator fixes it mid-session, and
+// vice versa a transient read error shouldn't get baked in as permanent.
+let cachedWallet: SolanaWallet | undefined;
+
 /**
  * Loads the agent's wallet.
  *
@@ -78,32 +143,61 @@ function parseKeypairBytes(raw: string): Uint8Array {
  * with no wallet configured at all — an agent running Base missions should not need one.
  */
 export async function loadSolanaWallet(): Promise<SolanaWallet> {
+  if (cachedWallet) return cachedWallet;
+
+  const encryptedPath = process.env.SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH;
+  const passwordFile = process.env.SOLO_SOLANA_KEYPAIR_PASSWORD_FILE;
   const inline = process.env.SOLO_SOLANA_KEYPAIR;
   const path = process.env.SOLO_SOLANA_KEYPAIR_PATH;
 
   let raw: string;
-  if (inline && inline.trim() !== '') {
+  if ((encryptedPath && encryptedPath.trim() !== '') || (passwordFile && passwordFile.trim() !== '')) {
+    if (!encryptedPath || !passwordFile) {
+      throw new SolanaWalletUnavailable(
+        'SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH and SOLO_SOLANA_KEYPAIR_PASSWORD_FILE must both be set — only one was found',
+      );
+    }
+    let encrypted: Buffer;
+    let password: string;
+    try {
+      encrypted = readFileSync(expandHome(encryptedPath));
+    } catch (e) {
+      throw new SolanaWalletUnavailable(`cannot read ${encryptedPath}: ${(e as Error).message}`);
+    }
+    try {
+      password = readFileSync(expandHome(passwordFile), 'utf8').replace(/\r?\n$/, '');
+    } catch (e) {
+      throw new SolanaWalletUnavailable(`cannot read ${passwordFile}: ${(e as Error).message}`);
+    }
+    raw = decryptOpenSslAes256CbcPbkdf2(encrypted, password).toString('utf8');
+  } else if (inline && inline.trim() !== '') {
     raw = inline;
   } else if (path && path.trim() !== '') {
     try {
-      raw = readFileSync(path.replace(/^~/, process.env.HOME ?? '~'), 'utf8');
+      raw = readFileSync(expandHome(path), 'utf8');
     } catch (e) {
       throw new SolanaWalletUnavailable(`cannot read ${path}: ${(e as Error).message}`);
     }
   } else {
-    throw new SolanaWalletUnavailable('neither SOLO_SOLANA_KEYPAIR nor SOLO_SOLANA_KEYPAIR_PATH is set');
+    throw new SolanaWalletUnavailable(
+      'no wallet source configured (checked SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH, SOLO_SOLANA_KEYPAIR, SOLO_SOLANA_KEYPAIR_PATH)',
+    );
   }
 
   const secretKey = parseKeypairBytes(raw);
   const { Keypair } = await import('@solana/web3.js');
   const kp = Keypair.fromSecretKey(secretKey);
-  return { publicKey: kp.publicKey.toBase58(), secretKey };
+  cachedWallet = { publicKey: kp.publicKey.toBase58(), secretKey };
+  return cachedWallet;
 }
 
 /** Whether a Solana wallet is configured, without throwing. */
 export function hasSolanaWallet(): boolean {
   return Boolean(
-    (process.env.SOLO_SOLANA_KEYPAIR ?? '').trim() ||
+    cachedWallet ||
+      ((process.env.SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH ?? '').trim() &&
+        (process.env.SOLO_SOLANA_KEYPAIR_PASSWORD_FILE ?? '').trim()) ||
+      (process.env.SOLO_SOLANA_KEYPAIR ?? '').trim() ||
       (process.env.SOLO_SOLANA_KEYPAIR_PATH ?? '').trim(),
   );
 }

package/src/tools/missions.ts

@@ -3,41 +3,74 @@ import { apiGet, apiPatch, apiPost } from '../api/client.js';
 
 /**
  * Shared JSON-schema for Mission.response_schema, used by both create_mission (set at creation)
- * and update_mission_questions (set/replace afterward, pre-hiring). v1 kinds only — text/choice/
- * rating input; kinds needing video-stimulus/gating infra (ab/slider/rank/tags/timestamps/upload)
- * aren't supported yet.
+ * and update_mission_questions (set/replace afterward, pre-hiring).
+ *
+ * Two families of kind:
+ *   - Generic form kinds (single/multi/likert/stars/short/long/dropdown/checkbox) — usable on any
+ *     mission type, self-contained text/choice/rating input.
+ *   - Media-anchored kinds (timestamp_tag/image_region/video_region_duration) — need an actual
+ *     track to annotate (a point in time, a region of an image, a region over a time range of a
+ *     video), so they're only accepted on media_review missions. create_mission/
+ *     update_mission_questions reject them on every other type.
+ * Kinds needing infra this platform doesn't have yet ('ab'/'slider'/'rank'/'tags'/'upload') aren't
+ * supported.
  */
 const RESPONSE_SCHEMA_PROPERTY = {
   type: 'array' as const,
   maxItems: 20,
   description:
-    'Structured completion questions a human answers to complete the mission. When set, ' +
-    'finalize_qualification auto-derives qualified UIDs from completion instead of requiring an ' +
-    'explicit qualified_human_uids list — same mechanism media_review has always used for track ' +
-    'ratings, generalized to any mission type. media_review defaults to a canonical ' +
-    '{rating (stars), comment (long, optional)} schema when this is omitted at creation; every ' +
-    'other type has no default (stays fully manual/chat-based unless you set this).',
+    'Structured completion questions a human answers to complete the mission. Question ids must ' +
+    'be unique within one schema — a duplicate id is rejected at creation/update, not merged or ' +
+    'silently overwritten. When set, finalize_qualification auto-derives qualified UIDs from ' +
+    'completion instead of requiring an explicit qualified_human_uids list — same mechanism ' +
+    'media_review has always used for track ratings, generalized to any mission type. ' +
+    'media_review defaults to a canonical two-question schema when this is omitted at creation — ' +
+    'literally { id: "rating", kind: "stars", required: true } and { id: "comment", kind: "long", ' +
+    'required: false } — so read/append against those exact ids if you rely on the default rather ' +
+    'than supplying your own schema. Every other type has no default (stays fully manual/chat-based ' +
+    'unless you set this).',
   items: {
     type: 'object',
     properties: {
-      id: { type: 'string', description: 'Unique id within this schema — the key answers are stored under.' },
+      id: { type: 'string', description: 'Unique id within this schema — the key answers are stored under. Duplicates are rejected, not merged.' },
       kind: {
         type: 'string',
-        enum: ['single', 'multi', 'likert', 'stars', 'short', 'long', 'dropdown', 'consent'],
+        enum: [
+          'single', 'multi', 'likert', 'stars', 'short', 'long', 'dropdown', 'checkbox',
+          'timestamp_tag', 'image_region', 'video_region_duration',
+        ],
         description:
-          'single=one choice, multi=several choices, likert=5-point agreement scale, stars=1-5 rating, ' +
-          'short=one line of text, long=paragraph text (see min_length), dropdown=one choice from a long ' +
-          'list, consent=a checkbox that must be explicitly true.',
+          'single=one choice, multi=several choices, likert=a scale rendered as a row of buttons (NOT ' +
+          'fixed at 5 points — the number of options you supply IS the number of points, so give exactly ' +
+          'as many option labels as the scale should have; a common convention is 5 labels like "1 ' +
+          'Strongly disagree".."5 Strongly agree" but nothing enforces that), stars=1-5 rating (fixed, ' +
+          'no options), short=one line of text, long=paragraph text (see min_length), dropdown=one ' +
+          'choice from a long list, checkbox=a checkbox that must be explicitly true (usable for ANY ' +
+          'yes/no question, not just consent-flavored ones) — the checkbox\'s own clickable text is ' +
+          '`label` itself (there is no separate heading rendered above it, unlike every other kind); ' +
+          'use `help` for any additional wording you want shown near it.\n\n' +
+          'Media-anchored kinds — media_review only, need a track to annotate (options/min_length ' +
+          'don\'t apply; see min_count instead):\n' +
+          '  timestamp_tag: the human flags a moment in an audio/video track while it plays. Each ' +
+          'flag is { t (seconds), tag (category — one of `options` if you set it, otherwise any ' +
+          'non-empty string), note? }. `options` is OPTIONAL here (unlike the choice kinds above) — ' +
+          'omit it for free-form tagging, or set it to offer a closed category list.\n' +
+          '  image_region: the human draws a rectangle on an image track and comments on it. Each ' +
+          'region is { x, y, width, height (all 0-1, fraction of the image, not pixels), comment }.\n' +
+          '  video_region_duration: like image_region, but the rectangle is held for a single time ' +
+          'range rather than a single point — { start, end (seconds, end > start), x, y, width, ' +
+          'height, comment }. One fixed box for the whole range, not tracked frame by frame.',
       },
-      label: { type: 'string', description: 'Question text shown to the human (max 200 chars).' },
+      label: { type: 'string', description: 'Question text shown to the human (max 200 chars). For the checkbox kind this is the checkbox\'s own clickable text, not a separate heading.' },
       help: { type: 'string', description: 'Optional helper text shown under the label (max 500 chars).' },
       required: { type: 'boolean', description: 'Whether this question must be answered to complete the mission.' },
       options: {
         type: 'array',
         items: { type: 'string' },
-        description: 'Required for single/multi/dropdown/likert (max 20 options, 50 chars each). Not accepted by other kinds.',
+        description: 'Required (non-empty) for single/multi/dropdown/likert (max 20 options, 50 chars each). Optional for timestamp_tag (a closed category list; omit for free-form tagging). Not accepted by any other kind.',
       },
-      min_length: { type: 'number', description: "Minimum answer length, only meaningful for the 'long' kind." },
+      min_length: { type: 'number', description: "Minimum answer length. Only read for the 'long' kind — silently ignored (not rejected) if set on any other kind." },
+      min_count: { type: 'number', description: 'Minimum number of annotations required. Only read for timestamp_tag/image_region/video_region_duration (defaults to 1 if required and unset) — silently ignored on any other kind.' },
     },
     required: ['id', 'kind', 'label', 'required'],
   },
@@ -94,7 +127,10 @@ export const missionTools: Tool[] = [
     description:
       "Set or replace a mission's response_schema after creation. Locked once hiring starts — " +
       'same window as add_mission_track (on-chain: only before funding; off-chain: only while ' +
-      'active with zero hired participants yet). Replaces the entire schema, not a merge.',
+      'active with zero hired participants yet). This window is what makes a schema replacement ' +
+      'safe: a human can only submit answers once hired, and the schema can no longer change once ' +
+      'anyone has been hired — there is no state where a human has answered under one schema and ' +
+      'the mission later presents a different one. Replaces the entire schema, not a merge.',
     inputSchema: {
       type: 'object',
       properties: {

package/src/tools/solana.ts

@@ -282,7 +282,22 @@ export async function handleSolanaTool(
         program_id: string;
         mints: Record<string, string>;
       };
-      const mint = cfg.mints.TEST_USDC ?? Object.values(cfg.mints)[0];
+      // The mission's ACTUAL mint, not a guessed default — get_solana_config's mints always
+      // includes both the production payout mint (USDC) and TEST_USDC, and a mission is funded
+      // in exactly one of them. Guessing (the previous code preferred TEST_USDC whenever present)
+      // computes the wrong associated-token-account for any mission funded in the other one, and
+      // the refund/cancel/emergency-refund transaction then fails on-chain with
+      // AccountNotInitialized — confirmed live against a real USDC-funded mission.
+      const mission = (await apiGet(`/agent/missions/${args.mission_id}`)) as {
+        mission?: { token_address?: string };
+      };
+      const mint = mission.mission?.token_address;
+      if (!mint) {
+        return {
+          refunded: false,
+          error: `Could not resolve mission ${args.mission_id}'s token_address — call get_mission to check it exists and is funded.`,
+        };
+      }
       const tokenAccount = await associatedTokenAddress(mint, wallet.publicKey);
 
       // No action: ask what is legal rather than guessing and getting a 409. Uses a deliberately

package/dist/wallet-IUQWBW6F.js

@@ -1,90 +0,0 @@
-// src/solana/wallet.ts
-import { readFileSync } from "fs";
-var SolanaWalletUnavailable = class extends Error {
-  constructor(reason) {
-    super(
-      `Solana wallet unavailable: ${reason}
-
-Set one of:
-  SOLO_SOLANA_KEYPAIR       - JSON byte array, as \`solana-keygen\` writes it
-  SOLO_SOLANA_KEYPAIR_PATH  - path to that file (e.g. ~/.config/solana/id.json)
-
-The wallet needs SOL for rent and fees, and USDC for the mission budget. Rent is a
-refundable deposit, not a fee: most of it returns when the task is closed.`
-    );
-    this.name = "SolanaWalletUnavailable";
-  }
-};
-function parseKeypairBytes(raw) {
-  const trimmed = raw.trim();
-  if (!trimmed.startsWith("[")) {
-    throw new SolanaWalletUnavailable(
-      "value is not a JSON byte array \u2014 this is the format `solana-keygen new` writes"
-    );
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(trimmed);
-  } catch {
-    throw new SolanaWalletUnavailable("value looks like a JSON array but does not parse");
-  }
-  if (!Array.isArray(parsed) || !parsed.every((n) => typeof n === "number")) {
-    throw new SolanaWalletUnavailable("JSON array must contain only numbers");
-  }
-  const bytes = Uint8Array.from(parsed);
-  if (bytes.length !== 64) {
-    throw new SolanaWalletUnavailable(
-      `expected 64 bytes, got ${bytes.length}` + (bytes.length === 32 ? " \u2014 this is the seed alone, not the full keypair" : "")
-    );
-  }
-  return bytes;
-}
-async function loadSolanaWallet() {
-  const inline = process.env.SOLO_SOLANA_KEYPAIR;
-  const path = process.env.SOLO_SOLANA_KEYPAIR_PATH;
-  let raw;
-  if (inline && inline.trim() !== "") {
-    raw = inline;
-  } else if (path && path.trim() !== "") {
-    try {
-      raw = readFileSync(path.replace(/^~/, process.env.HOME ?? "~"), "utf8");
-    } catch (e) {
-      throw new SolanaWalletUnavailable(`cannot read ${path}: ${e.message}`);
-    }
-  } else {
-    throw new SolanaWalletUnavailable("neither SOLO_SOLANA_KEYPAIR nor SOLO_SOLANA_KEYPAIR_PATH is set");
-  }
-  const secretKey = parseKeypairBytes(raw);
-  const { Keypair } = await import("@solana/web3.js");
-  const kp = Keypair.fromSecretKey(secretKey);
-  return { publicKey: kp.publicKey.toBase58(), secretKey };
-}
-function hasSolanaWallet() {
-  return Boolean(
-    (process.env.SOLO_SOLANA_KEYPAIR ?? "").trim() || (process.env.SOLO_SOLANA_KEYPAIR_PATH ?? "").trim()
-  );
-}
-async function associatedTokenAddress(mint, owner) {
-  const { PublicKey } = await import("@solana/web3.js");
-  const TOKEN_PROGRAM_ID = new PublicKey("TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA");
-  const ASSOCIATED_TOKEN_PROGRAM_ID = new PublicKey("ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL");
-  const [address] = PublicKey.findProgramAddressSync(
-    [new PublicKey(owner).toBuffer(), TOKEN_PROGRAM_ID.toBuffer(), new PublicKey(mint).toBuffer()],
-    ASSOCIATED_TOKEN_PROGRAM_ID
-  );
-  return address.toBase58();
-}
-async function signTransaction(transactionBase64, wallet) {
-  const { Keypair, Transaction } = await import("@solana/web3.js");
-  const kp = Keypair.fromSecretKey(wallet.secretKey);
-  const tx = Transaction.from(Buffer.from(transactionBase64, "base64"));
-  tx.partialSign(kp);
-  return tx.serialize().toString("base64");
-}
-export {
-  SolanaWalletUnavailable,
-  associatedTokenAddress,
-  hasSolanaWallet,
-  loadSolanaWallet,
-  signTransaction
-};