@projectsolo/solo-mission-mcp 0.23.2 → 0.23.3

package/dist/server-U6ZDX3NA.js

@@ -0,0 +1,1403 @@
+import {
+  apiGet,
+  apiPatch,
+  apiPost,
+  publicApiPost
+} from "./chunk-OP4QYTL4.js";
+
+// src/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+
+// src/tools/missions.ts
+var RESPONSE_SCHEMA_PROPERTY = {
+  type: "array",
+  maxItems: 20,
+  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: true } \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. Duplicates are rejected, not merged." },
+      kind: {
+        type: "string",
+        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). 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. A required: false question does NOT block mission completion or finalize_qualification's auto-qualification \u2014 both derive purely from the required questions, so an optional question left blank (or still being typed into) will not stop either from firing the instant the required ones are answered. If every question in the schema should actually be answered, mark them all required: true; reserve required: false for a genuinely optional/skippable field."
+      },
+      options: {
+        type: "array",
+        items: { type: "string" },
+        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 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"]
+  }
+};
+var missionTools = [
+  {
+    name: "create_mission",
+    description: "Create a new mission. Off-chain missions (no budget field) are always free \u2014 no payment, no escrow. Include the budget field for a paid mission escrowed on Solana: it is created in pending_funding, and you then fund it with fund_solana_mission (pass the returned mission id). Solana is the only chain (the backend also defaults a missing chain to solana, and this tool always sends it). A paid mission's response includes funding_params: chain ('solana'), cluster, program_id, rpc_url, mint, token_address (same as mint), token_decimals, amount_raw, base_pool, lottery_reward_per_winner_raw, lottery_winner_count, qualify_deadline, settlement_deadline, seed_commit and expires_at. There is no escrow address or task id yet: the program assigns those when the mission is funded. expires_at is creation + 24 hours \u2014 a mission still unfunded then is cancelled automatically. You do not need to build anything from funding_params; fund_solana_mission does the whole funding step. The response's mission.solana_quoted_fee_bps is the platform fee rate you were quoted: the escrow transaction carries it as max_fee_bps, the most the program may charge, and fund_solana_mission refuses to sign any other value. A paid lottery (lottery_winner_count > 0) is funded with a transaction the platform Operator has already co-signed; fund_solana_mission verifies that co-signature before adding yours. Paid-mission deadlines follow the escrow program's rules \u2014 see hiring_duration_hours and work_duration_hours.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        type: {
+          type: "string",
+          enum: ["coffee_chat", "opinion", "survey", "general", "media_review"],
+          description: 'Type of mission. Use "media_review" for audio/music rating missions.'
+        },
+        chain: {
+          type: "string",
+          enum: ["solana"],
+          description: "Optional. Solana is the only chain: a paid (budget-bearing) mission is always sent with chain 'solana' whether or not you set this. Ignored for off-chain missions (no budget field)."
+        },
+        title: { type: "string", description: "Mission title (max 100 chars)" },
+        description: { type: "string", description: "Detailed mission description (max 2000 chars). Supports Markdown \u2014 use ## headings, - bullet lists, and **bold** to structure your content. The platform renders it as formatted text." },
+        requirements: {
+          type: "object",
+          description: "Optional participant requirements",
+          properties: {
+            skills: { type: "array", items: { type: "string" } },
+            location: { type: "string" },
+            languages: { type: "array", items: { type: "string" } },
+            min_rating: { type: "number", minimum: 0, maximum: 5 }
+          }
+        },
+        reward_usdt: { type: "number", minimum: 0, description: "Deprecated \u2014 ignored for off-chain missions (which are always free). Has no effect. Omit this field." },
+        max_participants: { type: "number", minimum: 1, description: "Maximum number of participants" },
+        expires_in_hours: { type: "number", minimum: 1, description: "Hours until mission expires" },
+        budget: { type: "number", description: "Total mission budget in USDC. Enables on-chain escrow on Solana (fund it afterwards with fund_solana_mission). Must also cover the platform fee, which is reserved out of the budget: base_reward * max_humans + lottery_prize_per_winner * lottery_winner_count + floor(budget * fee_bps / 10000) <= budget (equality passes). fee_bps is read from the Solana escrow program's on-chain config, not a fixed rate (currently 0 on devnet). A 400 for this rule states the rate in use; a 503 means the rate could not be read, nothing was created, and you should retry shortly. Both the backend and the Solana escrow program enforce this." },
+        max_humans: { type: "number", minimum: 1, description: "On-chain: maximum number of participants (both base-reward and lottery entrants)." },
+        base_reward: { type: "number", minimum: 0, description: "Per-participant base reward in USDC paid to every qualified human. Defaults to 0. Set to 0 for pure-lottery missions." },
+        reward_per_human: { type: "number", minimum: 0, description: "Deprecated \u2014 use base_reward instead." },
+        lottery_winner_count: { type: "integer", minimum: 1, description: "Number of winners randomly selected from all qualified participants. Must be <= max_humans. Must be paired with lottery_prize_per_winner. For a paid mission the draw happens on chain at settlement: final_entropy = keccak256(seed_reveal \u2016 entropy_hash), where seed_reveal opens the seed_commit fixed at funding and entropy_hash is the SlotHashes sysvar bank hash of the first produced slot after finalize_qualification, stored on the Task by record_entropy (settle captures it if nobody recorded it). It is NOT the blockhash getBlock returns for that slot, so recompute a draw from the Task account's entropy_hash, not from getBlock. The platform Operator co-signs a lottery's funding transaction (the escrow program requires it)." },
+        lottery_prize_per_winner: { type: "number", minimum: 0, description: "Additional prize in USDC paid to each lottery winner on top of base_reward. Must be paired with lottery_winner_count." },
+        hiring_duration_hours: { type: "number", minimum: 0.0166, description: "How long (hours) the mission accepts applications and the agent hires/rejects. The hiring window closes at now + hiring_duration_hours. Finalize-qualification cannot be called before this. Closing hiring does NOT end the work: hired humans keep voting and submitting answers after it (see work_duration_hours). Backend floor is 60s (0.0166h) \u2014 see work_duration_hours for what that floor does and does not guarantee. For a paid mission the end of the hiring window is the escrow's qualify_deadline: it may be at most 180 days ahead, and it is the cancel cut-off \u2014 refund_solana_mission's cancel is refused on chain from qualify_deadline on (TooLateToCancel)." },
+        work_duration_hours: { type: "number", minimum: 0.0166, description: "How long (hours) hired participants have to complete the work: settlement_deadline = end of the hiring window + work_duration_hours. Agent must call settle_mission before this period ends. Humans can vote and submit answers while the mission is active: on-chain until max(qualify_deadline, settlement_deadline \u2212 1260s), i.e. about 21 minutes before settlement_deadline; off-chain until finalize. Either way, finalize_qualification closes submissions. Backend floor is 60s (0.0166h) \u2014 a sanity check against a near-zero window, not a guarantee the escrow accepts it. For a paid mission the Solana escrow program separately requires settlement_deadline >= qualify_deadline + min_review_window + finalize grace, and settlement_deadline <= qualify_deadline + 90 days. min_review_window is the program's configured review window and the finalize grace equals its floor (10 seconds each on the current devnet build; the floor is 1 hour on a production build). create_mission checks both against the live program config and returns 400 on a violation; the program enforces them again when the escrow is funded, and finalize_qualification must still leave min_review_window before settlement_deadline." },
+        auto_accept_applicants: { type: "boolean", description: "Defaults to true \u2014 applicants are automatically hired when they apply, no manual hire_participant call needed, first-come first-served up to max_humans, face verification still required. Pass false to opt into manual review instead (see hire_participant for how unreviewed applicants are still handled once the hiring window closes)." },
+        response_schema: RESPONSE_SCHEMA_PROPERTY
+      },
+      required: ["type", "title", "description"]
+    }
+  },
+  {
+    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). 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: {
+        mission_id: { type: "string" },
+        response_schema: RESPONSE_SCHEMA_PROPERTY
+      },
+      required: ["mission_id", "response_schema"]
+    }
+  },
+  {
+    name: "list_missions",
+    description: "List missions created by this agent. Filter by status to manage your mission portfolio.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: {
+          type: "string",
+          enum: ["pending_funding", "active", "qualifying", "completed", "refundable", "refunded", "cancelled", "expired"],
+          description: "Filter by status"
+        },
+        limit: { type: "number", description: "Max results (default 20)" },
+        page: { type: "number", description: "Page number (default 1)" }
+      }
+    }
+  },
+  {
+    name: "get_mission",
+    description: `Get details of a specific mission by ID, including all participants. Each participant includes a conversation_id once the human has tapped "Say Hi" \u2014 use it directly with watch_conversation or send_message. Each participant also includes an agent_rating field ({ rating: 1\u20135, comment?: string, updated_at }) if that human has rated the agent; null if not rated or if the 7-day rating window after mission completion has closed. Once settled, a settlement_outcome field ('completed' / 'completed_refundable' / 'no_payout_refunded') tells you whether anyone was actually paid \u2014 see settle_mission's description; don't infer that from status alone.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string", description: "Mission ID" }
+      },
+      required: ["mission_id"]
+    }
+  },
+  {
+    name: "hire_participant",
+    description: "Accept a human applicant for a mission. Only applied humans can be hired. Hired humans can start work via conversations. Only valid while mission is active. IMPORTANT: silence is not neutral \u2014 an applicant you never call this (or reject_participant) on is automatically hired (up to max_humans, oldest applied_at first). That does NOT happen when the hiring window closes. For an on-chain mission it happens in the window just before settlement_deadline (roughly 21 to 1 minutes before it), in the same pass that auto-finalizes and settles. For an off-chain mission it happens at expires_at. If you do not want someone, call reject_participant before then.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string" },
+        uid: { type: "string", description: "Firebase UID of the applicant to hire" }
+      },
+      required: ["mission_id", "uid"]
+    }
+  },
+  {
+    name: "reject_participant",
+    description: "Reject a human applicant or hired participant. Valid for applied or hired status, before finalize_qualification is called. This is the ONLY way to exclude someone \u2014 the platform auto-hires remaining applicants and auto-qualifies hired participants by default (silence = go), so anyone you do not explicitly reject ends up hired, qualified and paid. That happens in the window just before settlement_deadline for an on-chain mission (roughly 21 to 1 minutes before it) and at expires_at for an off-chain mission, not when the hiring window closes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string" },
+        uid: { type: "string", description: "Firebase UID of the participant to reject" }
+      },
+      required: ["mission_id", "uid"]
+    }
+  },
+  {
+    name: "finalize_qualification",
+    description: "Lock in the qualified participants after reviewing their work. If the mission has a response_schema (media_review always does, by default or explicitly; any other type only if you set one via create_mission/update_mission_questions), pass an empty body \u2014 qualified_human_uids is ignored and the backend auto-qualifies anyone who completed it (every ready track for media_review, a full submission for other types). Otherwise provide an explicit list of UIDs whose work was accepted. For on-chain missions, the backend records the qualified set on the Solana escrow program. Mission transitions to qualifying. If you never call this, the platform does it for you (silence = go), qualifying every hired participant you did not explicitly reject_participant. It does NOT happen when the hiring window closes. For an on-chain mission it happens in a short window just before settlement_deadline (roughly 21 to 1 minutes before it), where the platform also auto-hires any remaining applicants, finalizes and settles in one pass. For an off-chain mission it happens at expires_at. Call reject_participant first for anyone whose work should NOT be paid.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string" },
+        qualified_human_uids: {
+          type: "array",
+          items: { type: "string" },
+          description: "Firebase UIDs of humans whose work was accepted. Ignored for any mission with a response_schema (auto-derived from completion instead)."
+        }
+      },
+      required: ["mission_id"]
+    }
+  },
+  {
+    name: "settle_mission",
+    description: "Settle the mission after finalize_qualification. For on-chain missions, the backend settles the Solana escrow with aggregate payout numbers only (no per-wallet computation); mission transitions to completed or refundable. A 'refundable' mission is holding leftover budget for you: claim it with refund_solana_mission, action: 'claim_refund' (the mission then moves to refunded). IMPORTANT: status alone cannot tell you whether anyone was paid \u2014 a mission with 8/10 slots filled (2 slots' budget refunded) and one with 0/10 filled (the whole budget refunded) both land on 'refundable'/'refunded'. Check the settlement_outcome field on the response instead: 'completed' (fully spent, no refund), 'completed_refundable' (real participants were paid, only the unfilled slots refund), or 'no_payout_refunded' (nobody qualified, the entire budget bounces). Rewards are NOT immediately claimable \u2014 a separate batched process publishes the Merkle root that makes them claimable, gated by a review window currently defaulting to about 10 seconds (minimized pre-launch; will lengthen to an hour or more once real funds are at stake). Check GET /human/solana/rewards for actual claimable status rather than assuming a fixed delay. For free (off-chain) missions, marks qualified participants as completed \u2014 no payment is involved; settlement_outcome is always 'completed' there. You may settle at any time after finalize_qualification and before settlement_deadline; there is no need to wait. If you never call this, the platform settles on your behalf, but NOT right after finalize: for an on-chain mission it happens in the window just before settlement_deadline (roughly 21 to 1 minutes before it), and for an off-chain mission at expires_at. Who is qualified is fixed at finalize, so reject anyone unwanted before finalize, not after.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string" }
+      },
+      required: ["mission_id"]
+    }
+  },
+  {
+    name: "cancel_mission",
+    description: "Cancel a mission that holds no escrowed funds: an off-chain mission (status active or qualifying), or an unfunded Solana mission still in pending_funding. For a Solana mission the backend first checks the chain: if it finds an escrow that was created but never confirmed, it returns 409 with that task_id and does not cancel \u2014 use refund_solana_mission with action: 'cancel' then. For a funded mission also use refund_solana_mission with action: 'cancel': it returns the escrowed budget to you and moves the mission to cancelled, but only strictly before qualify_deadline (the end of the hiring window) \u2014 the escrow program refuses a cancel from then on (TooLateToCancel), and the remaining exit is emergency_refund once settlement_deadline passes without a settlement. An unfunded Solana mission you leave alone is cancelled automatically at its funding_params.expires_at (creation + 24 hours).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string", description: "Mission ID" }
+      },
+      required: ["mission_id"]
+    }
+  },
+  {
+    name: "rate_participant",
+    description: "Leave a rating and optional comment for a mission participant. Allowed for every settled outcome (mission status completed, refundable or refunded), within 7 days of settlement. Limited to one rating per participant per mission; calling again overwrites the previous rating/comment.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string", description: "Mission ID" },
+        uid: { type: "string", description: "Participant UID" },
+        rating: { type: "number", minimum: 1, maximum: 5, description: "Rating 1-5" },
+        comment: { type: "string", description: "Optional comment (max 500 chars). Shown publicly on the participant's profile." }
+      },
+      required: ["mission_id", "uid", "rating"]
+    }
+  }
+];
+async function handleMissionTool(name, args) {
+  switch (name) {
+    case "create_mission": {
+      const { chain: _chain, ...body } = args;
+      return apiPost("/agent/missions", body.budget !== void 0 ? { ...body, chain: "solana" } : body);
+    }
+    case "list_missions": {
+      const params = {};
+      if (args.status) params.status = args.status;
+      if (args.limit) params.limit = args.limit;
+      if (args.page) params.page = args.page;
+      return apiGet("/agent/missions", params);
+    }
+    case "get_mission":
+      return apiGet(`/agent/missions/${args.mission_id}`);
+    case "update_mission_questions":
+      return apiPatch(`/agent/missions/${args.mission_id}/questions`, { response_schema: args.response_schema });
+    case "hire_participant":
+      return apiPost(`/agent/missions/${args.mission_id}/participants/${args.uid}/hire`);
+    case "reject_participant":
+      return apiPost(`/agent/missions/${args.mission_id}/participants/${args.uid}/reject`);
+    case "finalize_qualification":
+      return apiPost(`/agent/missions/${args.mission_id}/finalize-qualification`, {
+        qualified_human_uids: args.qualified_human_uids
+      });
+    case "settle_mission":
+      return apiPost(`/agent/missions/${args.mission_id}/settle`);
+    case "cancel_mission":
+      return apiPost(`/agent/missions/${args.mission_id}/cancel`);
+    case "rate_participant":
+      return apiPost(`/agent/missions/${args.mission_id}/participants/${args.uid}/comment`, {
+        rating: args.rating,
+        comment: args.comment
+      });
+    default:
+      throw new Error(`Unknown mission tool: ${name}`);
+  }
+}
+
+// src/tools/humans.ts
+var humanTools = [
+  {
+    name: "browse_humans",
+    description: "Browse face-verified humans on the Solo platform. Filter by skills, location, languages, and more.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        skills: { type: "string", description: 'Comma-separated skill keywords (e.g. "Software Development,Data Analysis")' },
+        location: { type: "string", description: "Filter by city or country" },
+        languages: { type: "string", description: 'Comma-separated languages (e.g. "English,Spanish")' },
+        min_rating: { type: "number", minimum: 0, maximum: 5, description: "Minimum average rating (0\u20135)" },
+        max_hourly_rate: { type: "number", description: "Maximum hourly rate in USD" },
+        min_tier: { type: "number", minimum: 1, description: "Minimum contribution tier (1=Scout, 2=Curator, 3=Oracle)" },
+        sort_by: { type: "string", enum: ["tier", "avg_rating", "completed_count"], description: "Sort results by this field (descending)" },
+        limit: { type: "number", description: "Max results (default 20)" },
+        page: { type: "number", description: "Page number (default 1)" }
+      }
+    }
+  },
+  {
+    name: "get_human_profile",
+    description: "Get the full mission profile of a specific human by their user_id.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        user_id: { type: "string", description: "The human's user_id (from browse_humans results)" }
+      },
+      required: ["user_id"]
+    }
+  }
+];
+async function handleHumanTool(name, args) {
+  switch (name) {
+    case "browse_humans": {
+      const params = {};
+      if (args.skills) params.skills = args.skills;
+      if (args.location) params.location = args.location;
+      if (args.languages) params.languages = args.languages;
+      if (args.min_rating !== void 0) params.min_rating = args.min_rating;
+      if (args.max_hourly_rate !== void 0) params.max_hourly_rate = args.max_hourly_rate;
+      if (args.min_tier !== void 0) params.min_tier = args.min_tier;
+      if (args.sort_by) params.sort_by = args.sort_by;
+      if (args.limit) params.limit = args.limit;
+      if (args.page) params.page = args.page;
+      return apiGet("/agent/humans", params);
+    }
+    case "get_human_profile":
+      return apiGet(`/agent/humans/${args.user_id}`);
+    default:
+      throw new Error(`Unknown human tool: ${name}`);
+  }
+}
+
+// src/realtime/poller.ts
+var watches = /* @__PURE__ */ new Map();
+var FIBONACCI_MS = [
+  1e3,
+  1e3,
+  2e3,
+  3e3,
+  5e3,
+  8e3,
+  13e3,
+  21e3,
+  34e3,
+  55e3,
+  89e3,
+  144e3,
+  233e3,
+  377e3,
+  6e5
+];
+function getFibMs(step) {
+  return FIBONACCI_MS[Math.min(step, FIBONACCI_MS.length - 1)];
+}
+function scheduleNext(conversationId, state) {
+  state.timeoutId = setTimeout(() => pollOnce(conversationId, state), getFibMs(state.fibStep));
+}
+async function pollOnce(conversationId, state) {
+  if (!watches.has(conversationId)) return;
+  try {
+    const data = await apiGet(
+      `/agent/conversations/${conversationId}/messages`,
+      { since: state.lastSeen }
+    );
+    const msgs = data.messages ?? [];
+    if (msgs.length > 0) {
+      state.queue.push(...msgs);
+      const latest = msgs[msgs.length - 1];
+      if (latest?.created_at) {
+        const raw = latest.created_at;
+        if (typeof raw === "string") {
+          state.lastSeen = raw;
+        } else if (raw?._seconds !== void 0) {
+          state.lastSeen = new Date(raw._seconds * 1e3 + Math.floor((raw._nanoseconds ?? 0) / 1e6)).toISOString();
+        } else if (raw?.seconds !== void 0) {
+          state.lastSeen = new Date(raw.seconds * 1e3).toISOString();
+        }
+      }
+      if (msgs.some((m) => m.sender_type === "human")) {
+        state.fibStep = 0;
+      }
+    } else {
+      state.fibStep = Math.min(state.fibStep + 1, FIBONACCI_MS.length - 1);
+    }
+  } catch {
+  }
+  if (watches.has(conversationId)) {
+    scheduleNext(conversationId, state);
+  }
+}
+function startPolling(conversationId) {
+  if (watches.has(conversationId)) return;
+  const state = {
+    timeoutId: null,
+    fibStep: 0,
+    lastSeen: (/* @__PURE__ */ new Date()).toISOString(),
+    queue: []
+  };
+  watches.set(conversationId, state);
+  scheduleNext(conversationId, state);
+}
+function drainQueue(conversationId) {
+  const state = watches.get(conversationId);
+  if (!state) return [];
+  const msgs = [...state.queue];
+  state.queue = [];
+  return msgs;
+}
+function stopPolling(conversationId) {
+  const state = watches.get(conversationId);
+  if (!state) return false;
+  if (state.timeoutId !== null) clearTimeout(state.timeoutId);
+  watches.delete(conversationId);
+  return true;
+}
+function listWatched() {
+  return [...watches.keys()];
+}
+function getPollIntervalMs(conversationId) {
+  const state = watches.get(conversationId);
+  if (!state) return null;
+  return getFibMs(state.fibStep);
+}
+
+// src/tools/conversations.ts
+var conversationTools = [
+  {
+    name: "start_conversation",
+    description: "Start a new conversation with a human. Idempotent \u2014 if a conversation already exists with this human (and mission), returns the existing one. If the existing conversation was archived, it will be reopened.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        human_uid: { type: "string", description: "The human's Firebase uid \u2014 use the 'uid' field from browse_humans results, NOT 'user_id'. user_id is a mutable display name; uid is the stable internal identifier." },
+        initial_message: { type: "string", description: "First message to send" },
+        mission_id: { type: "string", description: "Optional: link conversation to a mission" }
+      },
+      required: ["human_uid", "initial_message"]
+    }
+  },
+  {
+    name: "list_conversations",
+    description: "List conversations. Use status filter to focus on active conversations. Pagination supported for agents with many conversations.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        status: { type: "string", enum: ["active", "archived", "closed"], description: "Filter by status (default: all)" },
+        limit: { type: "number", description: "Max results (default 20, max 100)" },
+        page: { type: "number", description: "Page number (default 1)" }
+      }
+    }
+  },
+  {
+    name: "get_conversation_upload_url",
+    description: "Get a signed upload URL to attach an image to a message. For agent uploads prefer upload_conversation_image instead. Otherwise: upload the file with PUT to the returned upload_url, then pass the returned storage_path in send_message attachment_paths.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        conversation_id: { type: "string", description: "Conversation ID" },
+        content_type: { type: "string", description: "MIME type of the file, e.g. image/jpeg, image/png, image/webp (default image/jpeg)" }
+      },
+      required: ["conversation_id"]
+    }
+  },
+  {
+    name: "upload_conversation_image",
+    description: "Upload an image into a conversation and get its storage_path for use in send_message. Pass the image as base64-encoded data (e.g. from a user attachment or generated image). Returns storage_path to include in send_message attachment_paths.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        conversation_id: { type: "string", description: "Conversation ID" },
+        image_base64: { type: "string", description: "Base64-encoded image data (no data URL prefix)" },
+        content_type: { type: "string", description: "MIME type: image/jpeg, image/png, or image/webp (default image/jpeg)" }
+      },
+      required: ["conversation_id", "image_base64"]
+    }
+  },
+  {
+    name: "send_message",
+    description: "Send a message in an existing conversation. Optionally include attachment_paths (from get_conversation_upload_url + upload) to attach images. At least one of content or attachment_paths is required.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        conversation_id: { type: "string", description: "Conversation ID" },
+        content: { type: "string", description: "Message text (can be empty if attachment_paths provided)" },
+        attachment_paths: { type: "array", items: { type: "string" }, description: "Storage paths from get_conversation_upload_url flow; max 4 per message" }
+      },
+      required: ["conversation_id"]
+    }
+  },
+  {
+    name: "get_messages",
+    description: "Retrieve messages from a conversation. Use the `since` parameter to poll for new messages.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        conversation_id: { type: "string", description: "Conversation ID" },
+        since: { type: "string", description: "ISO 8601 timestamp \u2014 only return messages after this time" },
+        limit: { type: "number", description: "Max messages to return (default 50)" }
+      },
+      required: ["conversation_id"]
+    }
+  },
+  {
+    name: "close_conversation",
+    description: 'Manage conversation lifecycle. Use "archive" to shelve inactive conversations (reopenable). Use "close" to permanently end a conversation. Use "reopen" to resume an archived conversation. Best practice: archive conversations when waiting for a long response, close when the objective is met.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        conversation_id: { type: "string", description: "Conversation ID" },
+        action: { type: "string", enum: ["archive", "close", "reopen"], description: "Action to perform" }
+      },
+      required: ["conversation_id", "action"]
+    }
+  }
+];
+async function handleConversationTool(name, args) {
+  switch (name) {
+    case "start_conversation":
+      return apiPost("/agent/conversations", {
+        human_uid: args.human_uid,
+        initial_message: args.initial_message,
+        ...args.mission_id ? { mission_id: args.mission_id } : {}
+      });
+    case "list_conversations": {
+      const params = {};
+      if (args.status) params.status = args.status;
+      if (args.limit) params.limit = args.limit;
+      if (args.page) params.page = args.page;
+      return apiGet("/agent/conversations", params);
+    }
+    case "get_conversation_upload_url": {
+      const ct = args.content_type || "image/jpeg";
+      const path = `/agent/conversations/${args.conversation_id}/upload-url?content_type=${encodeURIComponent(ct)}`;
+      return apiPost(path);
+    }
+    case "upload_conversation_image": {
+      const ct = args.content_type || "image/jpeg";
+      const path = `/agent/conversations/${args.conversation_id}/upload-url?content_type=${encodeURIComponent(ct)}`;
+      const { upload_url, storage_path } = await apiPost(path);
+      const body = Buffer.from(args.image_base64, "base64");
+      const res = await fetch(upload_url, {
+        method: "PUT",
+        body,
+        headers: { "Content-Type": ct }
+      });
+      if (!res.ok) throw new Error(`Upload failed: ${res.status} ${res.statusText}`);
+      return { storage_path };
+    }
+    case "send_message": {
+      const body = { content: args.content ?? "" };
+      if (args.attachment_paths?.length) body.attachment_paths = args.attachment_paths;
+      return apiPost(`/agent/conversations/${args.conversation_id}/messages`, body);
+    }
+    case "get_messages": {
+      const params = {};
+      if (args.since) params.since = args.since;
+      if (args.limit) params.limit = args.limit;
+      return apiGet(`/agent/conversations/${args.conversation_id}/messages`, params);
+    }
+    case "close_conversation": {
+      const result = await apiPost(`/agent/conversations/${args.conversation_id}/${args.action}`);
+      if (args.action === "close") {
+        stopPolling(args.conversation_id);
+      }
+      return result;
+    }
+    default:
+      throw new Error(`Unknown conversation tool: ${name}`);
+  }
+}
+
+// src/realtime/missionPoller.ts
+var missionWatches = /* @__PURE__ */ new Map();
+async function startMissionPolling(missionId, intervalMinutes = 10) {
+  if (missionWatches.has(missionId)) return;
+  let knownParticipantUids = /* @__PURE__ */ new Set();
+  try {
+    const data = await apiGet(`/agent/missions/${missionId}`);
+    for (const p of data.participants ?? []) {
+      knownParticipantUids.add(p.uid);
+    }
+  } catch {
+  }
+  const intervalMs = intervalMinutes * 60 * 1e3;
+  const state = {
+    knownParticipantUids,
+    queue: [],
+    intervalId: setInterval(async () => {
+      try {
+        const data = await apiGet(`/agent/missions/${missionId}`);
+        for (const p of data.participants ?? []) {
+          if (!state.knownParticipantUids.has(p.uid)) {
+            state.knownParticipantUids.add(p.uid);
+            state.queue.push({
+              mission_id: missionId,
+              type: "new_participant",
+              participant: {
+                uid: p.uid,
+                user_id: p.user_id,
+                joined_at: p.joined_at,
+                ...p.conversation_id ? { conversation_id: p.conversation_id } : {}
+              }
+            });
+          }
+        }
+      } catch {
+      }
+    }, intervalMs)
+  };
+  missionWatches.set(missionId, state);
+}
+function drainMissionQueue(missionId) {
+  const state = missionWatches.get(missionId);
+  if (!state) return [];
+  const updates = [...state.queue];
+  state.queue = [];
+  return updates;
+}
+function stopMissionPolling(missionId) {
+  const state = missionWatches.get(missionId);
+  if (!state) return false;
+  clearInterval(state.intervalId);
+  missionWatches.delete(missionId);
+  return true;
+}
+function listWatchedMissions() {
+  return [...missionWatches.keys()];
+}
+
+// src/tools/realtime.ts
+var realtimeTools = [
+  {
+    name: "watch_conversation",
+    description: "Start watching a conversation for new messages. Uses a Fibonacci delay schedule: starts at 1s, advances on each miss (up to 600s cap), resets to 1s when the human replies. Drain buffered messages with get_pending_messages.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        conversation_id: { type: "string", description: "Conversation ID to watch" }
+      },
+      required: ["conversation_id"]
+    }
+  },
+  {
+    name: "get_pending_messages",
+    description: "Return and clear all buffered new messages for a watched conversation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        conversation_id: { type: "string", description: "Conversation ID" }
+      },
+      required: ["conversation_id"]
+    }
+  },
+  {
+    name: "unwatch_conversation",
+    description: "Stop watching a conversation and discard its message buffer.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        conversation_id: { type: "string", description: "Conversation ID to stop watching" }
+      },
+      required: ["conversation_id"]
+    }
+  },
+  {
+    name: "watch_mission",
+    description: 'Start polling a mission for new participants. When a human joins and taps "Say Hi", their participant entry gains a conversation_id \u2014 drain updates with get_pending_mission_updates, then call watch_conversation on each conversation_id to start chatting.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string", description: "Mission ID to watch" },
+        interval_minutes: {
+          type: "number",
+          description: "How often to check for new participants in minutes (default: 10)",
+          minimum: 1
+        }
+      },
+      required: ["mission_id"]
+    }
+  },
+  {
+    name: "get_pending_mission_updates",
+    description: "Return and clear buffered mission updates (new participants). Each update includes the participant's conversation_id if they have started a conversation. Call watch_conversation(conversation_id) for each new participant to begin chatting.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string", description: "Mission ID" }
+      },
+      required: ["mission_id"]
+    }
+  },
+  {
+    name: "unwatch_mission",
+    description: "Stop polling a mission for new participants.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string", description: "Mission ID to stop watching" }
+      },
+      required: ["mission_id"]
+    }
+  }
+];
+async function handleRealtimeTool(name, args) {
+  switch (name) {
+    case "watch_conversation": {
+      const id = args.conversation_id;
+      const alreadyWatching = listWatched().includes(id);
+      startPolling(id);
+      const intervalMs = getPollIntervalMs(id) ?? 5e3;
+      return {
+        success: true,
+        conversation_id: id,
+        watching: true,
+        already_was_watching: alreadyWatching,
+        poll_interval_seconds: intervalMs / 1e3,
+        message: alreadyWatching ? `Already watching conversation ${id}` : `Started watching conversation ${id} \u2014 polling every ${intervalMs / 1e3}s (Fibonacci schedule)`
+      };
+    }
+    case "get_pending_messages": {
+      const id = args.conversation_id;
+      const msgs = drainQueue(id);
+      return {
+        conversation_id: id,
+        pending_count: msgs.length,
+        messages: msgs
+      };
+    }
+    case "unwatch_conversation": {
+      const id = args.conversation_id;
+      const stopped = stopPolling(id);
+      return {
+        success: true,
+        conversation_id: id,
+        was_watching: stopped,
+        message: stopped ? `Stopped watching conversation ${id}` : `Conversation ${id} was not being watched`
+      };
+    }
+    case "watch_mission": {
+      const missionId = args.mission_id;
+      const intervalMinutes = args.interval_minutes ?? 10;
+      const alreadyWatching = listWatchedMissions().includes(missionId);
+      await startMissionPolling(missionId, intervalMinutes);
+      return {
+        success: true,
+        mission_id: missionId,
+        already_was_watching: alreadyWatching,
+        interval_minutes: intervalMinutes,
+        message: alreadyWatching ? `Already watching mission ${missionId}` : `Started watching mission ${missionId} \u2014 checking for new participants every ${intervalMinutes} min`
+      };
+    }
+    case "get_pending_mission_updates": {
+      const missionId = args.mission_id;
+      const updates = drainMissionQueue(missionId);
+      return {
+        mission_id: missionId,
+        pending_count: updates.length,
+        updates
+      };
+    }
+    case "unwatch_mission": {
+      const missionId = args.mission_id;
+      const stopped = stopMissionPolling(missionId);
+      return {
+        success: true,
+        mission_id: missionId,
+        was_watching: stopped,
+        message: stopped ? `Stopped watching mission ${missionId}` : `Mission ${missionId} was not being watched`
+      };
+    }
+    default:
+      throw new Error(`Unknown realtime tool: ${name}`);
+  }
+}
+
+// src/tools/agent.ts
+var agentTools = [
+  {
+    name: "register_agent",
+    description: "Self-register a new agent on the Solo platform. No existing agent key required. Returns agent_id and api_key \u2014 the key is shown only once, save it immediately. Use this to bootstrap a fresh agent identity.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: {
+          type: "string",
+          description: "Agent name (3\u201350 characters)",
+          minLength: 3,
+          maxLength: 50
+        }
+      },
+      required: ["name"]
+    }
+  }
+];
+async function handleAgentTool(name, args) {
+  switch (name) {
+    case "register_agent":
+      return publicApiPost("/agent/register", { name: args.name });
+    default:
+      throw new Error(`Unknown agent tool: ${name}`);
+  }
+}
+
+// src/tools/tracks.ts
+import { readFile } from "fs/promises";
+var trackTools = [
+  {
+    name: "add_mission_track",
+    description: "Upload a media item (audio, image, or video) to a media_review mission. Provide the file EITHER via file_path (the MCP server reads it from local disk and uploads it directly \u2014 use this for audio/video, since inlining a multi-MB file as base64 in the tool call can exceed the calling agent's own tool-call or context limits, causing a silent client-side failure before any request reaches the API) OR inline as file_base64 (fine for small images). Exactly one of the two is required. For on-chain missions, call this BEFORE fund_solana_mission \u2014 uploads are blocked once the mission is active. For off-chain missions, call while the mission is active and before any participant is hired. The item becomes visible to hired participants once confirmed. Tracks cannot be deleted or replaced, so check the file before uploading. To change the media, cancel the mission and create a new one: for an off-chain mission or an unfunded Solana mission (pending_funding), use cancel_mission; for a funded Solana mission, use refund_solana_mission with action 'cancel' before its qualify_deadline. If the upload fails partway, it is safe to call add_mission_track again: a track whose upload was never confirmed is ignored (not shown, not counted toward the 20-track cap, not required for completion).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string", description: "ID of the media_review mission" },
+        title: { type: "string", description: "Item title (required)" },
+        artist: { type: "string", description: "Artist / creator name (optional; typically used for audio)" },
+        file_path: {
+          type: "string",
+          description: "Path to a local file to upload, as an alternative to file_base64. The MCP server reads this file itself and PUTs it to the signed upload URL, so the calling agent only needs to pass the path \u2014 not the file contents. Prefer this for audio/video files. Use an absolute path: a relative path resolves against the MCP server process's working directory, not the caller's. Exactly one of file_base64 or file_path is required."
+        },
+        file_base64: {
+          type: "string",
+          description: "Base64-encoded file contents, as an alternative to file_path. Fine for small images; for audio/video prefer file_path \u2014 encoding a multi-MB file inline can exceed the calling agent's own tool-call or context limits. Exactly one of file_base64 or file_path is required."
+        },
+        content_type: {
+          type: "string",
+          enum: ["audio/mpeg", "audio/mp4", "image/jpeg", "image/png", "image/webp", "video/mp4"],
+          description: "MIME type of the file. Mobile-compatible formats only (iOS + Android). audio/mpeg (MP3) and audio/mp4 (AAC/M4A): max 25 MB. image/jpeg, image/png, image/webp: max 10 MB. video/mp4: max 200 MB \u2014 must be faststart-encoded (moov atom first) for partial play."
+        },
+        duration_seconds: { type: "number", description: "Duration in seconds (optional; applicable to audio and video only)" }
+      },
+      required: ["mission_id", "title", "content_type"]
+    }
+  },
+  {
+    name: "list_mission_tracks",
+    description: "List all media items on a media_review mission. Returns raw stats for each item: media_type (audio/image/video), vote_counts ({1,2,3,4,5,total} star-rating distribution) and total_listen_seconds (cumulative engagement time across all participants). Use these to compute your own scoring.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string", description: "ID of the mission" }
+      },
+      required: ["mission_id"]
+    }
+  },
+  {
+    name: "get_track_ratings",
+    description: "Get per-participant star ratings for one track on a media_review mission. Only participants who submitted a rating are returned \u2014 play-only rows are excluded. Each entry includes uid, rating (1\u20135), optional comment, total_listen_seconds, and rated_at.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string", description: "ID of the mission" },
+        track_id: { type: "string", description: "ID of the track" }
+      },
+      required: ["mission_id", "track_id"]
+    }
+  }
+];
+async function handleTrackTool(name, args) {
+  switch (name) {
+    case "add_mission_track": {
+      const { mission_id, title, artist, file_base64, file_path, content_type, duration_seconds } = args;
+      if (!file_base64 && !file_path) {
+        throw new Error("add_mission_track requires either file_base64 or file_path");
+      }
+      if (file_base64 && file_path) {
+        throw new Error("add_mission_track accepts only one of file_base64 or file_path, not both");
+      }
+      let fileBytes;
+      if (file_path) {
+        try {
+          fileBytes = await readFile(file_path);
+        } catch (err) {
+          throw new Error(`Could not read file_path "${file_path}": ${err.message}`);
+        }
+      } else {
+        fileBytes = Buffer.from(file_base64, "base64");
+      }
+      const urlRes = await apiPost(
+        `/agent/missions/${mission_id}/tracks/upload-url`,
+        { title, artist, content_type }
+      );
+      const uploadRes = await fetch(urlRes.upload_url, {
+        method: "PUT",
+        headers: { "Content-Type": content_type },
+        body: fileBytes
+      });
+      if (!uploadRes.ok) {
+        const errText = await uploadRes.text().catch(() => "");
+        throw new Error(
+          `Media upload failed: ${uploadRes.status} ${errText}. The unconfirmed track is ignored by the platform (not listed, not counted toward the 20-track cap), so it is safe to retry add_mission_track.`
+        );
+      }
+      const confirmed = await apiPost(
+        `/agent/missions/${mission_id}/tracks/${urlRes.track_id}/confirm`,
+        { title, artist, duration_seconds }
+      );
+      return confirmed.track;
+    }
+    case "list_mission_tracks": {
+      const { mission_id } = args;
+      return apiGet(`/agent/missions/${mission_id}/tracks`);
+    }
+    case "get_track_ratings": {
+      const { mission_id, track_id } = args;
+      return apiGet(`/agent/missions/${mission_id}/tracks/${track_id}/ratings`);
+    }
+    default:
+      throw new Error(`Unknown track tool: ${name}`);
+  }
+}
+
+// src/tools/solana.ts
+var solanaTools = [
+  {
+    name: "get_solana_config",
+    description: "Read the Solana escrow deployment: program id, cluster, RPC endpoint, accepted mints and their decimals, the minimum first payout, and escrow_interface \u2014 the program interface funding transactions use. This server verifies only escrow_interface 'v2' and refuses to fund against anything else. Call this before funding so you use a whitelisted mint \u2014 a mint that is not whitelisted is rejected on chain, not by the API. Requires no wallet.",
+    inputSchema: { type: "object", properties: {} }
+  },
+  {
+    name: "get_solana_wallet",
+    description: "Show your Solana wallet address and its balances. Reports SOL (needed for transaction fees and for account rent) and the token balance for a given mint (the mission budget). Use this before funding: an agent needs BOTH, and the rent line is easy to miss. Rent is a refundable deposit, not a fee \u2014 most of it returns when the task is closed. If no wallet is configured this explains how to set one up.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mint: {
+          type: "string",
+          description: "Mint to report a balance for. Defaults to the deployment payout mint from get_solana_config."
+        }
+      }
+    }
+  },
+  {
+    name: "fund_solana_mission",
+    description: "Fund a Solana mission end to end: the backend builds the escrow transaction, this tool DECODES AND VERIFIES it against the parameters you expect, signs it locally with your wallet, and submits it. Your key never leaves this process.\n\nVerification is not optional and cannot be skipped. On Solana the backend builds the transaction rather than publishing a parameter set for you to rebuild, so without a decode you would be signing bytes you cannot read. This tool refuses to sign if anything differs from what you expect \u2014 a substituted mint, an altered budget or deadline, an extra instruction, an account that is not the program-derived address, a raised fee ceiling, a lottery co-signer that is not the program's Operator \u2014 and returns the discrepancies instead.\n\nThe escrow program id is pinned in this package per cluster (SOLO_SOLANA_PROGRAM_ID can pin another) and the API's program_id must match it; the mint's decimals, which scale expected_budget, are read from chain.\n\nEscrow interface v2 (the only one this server verifies; get_solana_config reports it):\n- max_fee_bps: create_task carries the highest platform fee the escrow may take. It must equal the fee rate create_mission quoted you (mission.solana_quoted_fee_bps). If the program's fee has risen above it by the time the transaction lands, create_task fails with FeeAboveSponsorMax instead of charging you more; cancel the mission and create a new one for a fresh quote.\n- Lottery co-signature: a mission with lottery_winner_count > 0 must be co-signed by the platform Operator, so the transaction arrives already signed by it. This tool checks that the co-signer is the Operator in the program's on-chain Config (read directly from the cluster, not from the API), that its ed25519 signature is valid over the exact message, and that you, not the Operator, pay the fee. It then adds ONLY your signature and leaves the Operator's untouched; any change to the bytes would invalidate it. A non-lottery transaction must carry no co-signer.\n\nCall create_mission with a budget first and pass that mission's id here. Fund it within 24 hours: an unfunded mission is cancelled automatically at funding_params.expires_at. A media_review mission needs at least one ready track (add_mission_track) before funding, or this returns 409 before anything is signed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        mission_id: { type: "string", description: "A paid (budget-bearing) mission from create_mission, still in pending_funding." },
+        expected_budget: {
+          type: "number",
+          description: "The total budget in whole tokens (e.g. 10 for 10 USDC) you expect to escrow. Verified against the transaction before signing. Pass what you intended, NOT what the API told you \u2014 comparing the API to itself proves nothing."
+        },
+        expected_mint: {
+          type: "string",
+          description: "The mint you expect the budget to be taken in. Verified before signing. Defaults to the mint create_mission recorded for this mission (its funding_params.mint)."
+        },
+        expected_max_fee_bps: {
+          type: "integer",
+          minimum: 0,
+          description: "The platform fee rate, in basis points, that create_mission quoted you: its response's mission.solana_quoted_fee_bps. Verified against the transaction's max_fee_bps before signing. Defaults to the quote recorded on the mission."
+        },
+        dry_run: {
+          type: "boolean",
+          description: "Build and verify, then stop without signing or submitting. Use this to inspect what would be signed. Nothing is escrowed and no fee is paid."
+        }
+      },
+      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:\n- cancel: while the task is funded and strictly before qualify_deadline (the end of the hiring window). The escrow program refuses a cancel from qualify_deadline on (TooLateToCancel), even one built earlier, because by then the participants' work is done.\n- emergency_refund: once settlement_deadline has passed and the platform has not settled. It stays available after the cancel cut-off, and a pause does not block it.\n- claim_refund: leftover budget after a settle (mission status refundable).\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. If the backend or the chain rejects an action, the response says which one did, names the program error, and lists the actions that remain.",
+    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) {
+  const s = amount.toString();
+  if (!/^\d+(\.\d+)?$/.test(s)) {
+    throw new Error(`amount must be a non-negative decimal number, got ${s}`);
+  }
+  const [whole, frac = ""] = s.split(".");
+  if (frac.length > decimals) {
+    throw new Error(
+      `amount ${s} has ${frac.length} decimal places but the mint has only ${decimals}`
+    );
+  }
+  return (whole + frac.padEnd(decimals, "0")).replace(/^0+(?=\d)/, "");
+}
+var SOLANA_TOOL_NAMES = new Set(solanaTools.map((t) => t.name));
+function apiErrorBody(e) {
+  return e?.data ?? e?.response?.data ?? e?.body ?? {};
+}
+var CANCEL_CUTOFF_RULE = "cancel is refused on chain from qualify_deadline on (TooLateToCancel, error 6125); emergency_refund opens once settlement_deadline has passed without a settlement.";
+async function handleSolanaTool(name, args) {
+  const { apiGet: apiGet2, apiPost: apiPost2 } = await import("./client-NS6J6IO2.js");
+  const { resolvePinnedProgram, resolveTrustedRpc, solanaRpcUrl } = await import("./deployment-UCUWVIPJ.js");
+  switch (name) {
+    case "get_solana_config":
+      return apiGet2("/agent/solana/config");
+    case "get_solana_wallet": {
+      const { hasSolanaWallet, loadSolanaWallet, associatedTokenAddress, KEY_STORAGE_GUIDANCE } = await import("./wallet-LX7SI5RE.js");
+      if (!hasSolanaWallet()) {
+        return {
+          configured: false,
+          how_to_configure: {
+            recommended: "SOLO_SOLANA_KEYPAIR_ENCRYPTED_PATH + SOLO_SOLANA_KEYPAIR_PASSWORD_FILE \u2014 a keyfile encrypted with `openssl enc -aes-256-cbc -pbkdf2 -iter 10000 -md sha256`, plus a separate passphrase file (chmod 600 both)",
+            alternative: "SOLO_SOLANA_KEYPAIR_PATH \u2014 path to a plaintext `solana-keygen` keyfile, e.g. ~/.config/solana/id.json (chmod 600)",
+            key_storage: KEY_STORAGE_GUIDANCE
+          },
+          what_you_need: "SOL for transaction fees and account rent, plus the payout token for the budget. Rent is a refundable deposit, not a fee \u2014 most of it returns on close_task. Roughly $0.58 is locked per mission and about $0.24 is permanent, which buys the on-chain record that makes the escrow verifiable by anyone."
+        };
+      }
+      const wallet = await loadSolanaWallet();
+      const cfg = await apiGet2("/agent/solana/config");
+      const symbol = Object.keys(cfg.mints)[0];
+      const mint = args.mint ?? cfg.mints[symbol];
+      const tokenAccount = await associatedTokenAddress(mint, wallet.publicKey);
+      const rpc = async (method, params) => {
+        const res = await fetch(solanaRpcUrl(cfg), {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params })
+        });
+        return await res.json();
+      };
+      const solRes = await rpc("getBalance", [wallet.publicKey]);
+      const tokRes = await rpc("getTokenAccountBalance", [tokenAccount]);
+      const lamports = solRes.result?.value ?? 0;
+      const decimals = cfg.decimals[symbol] ?? 6;
+      return {
+        configured: true,
+        address: wallet.publicKey,
+        sol: lamports / 1e9,
+        // A token account only exists once tokens first arrive. create_task reads it, so funding
+        // fails without one — and the on-chain error names the account rather than the missing
+        // balance, which is confusing enough to call out explicitly.
+        token_account: tokenAccount,
+        token_account_exists: !tokRes.error,
+        token_balance: tokRes.result?.value?.uiAmountString ?? "0",
+        mint,
+        can_pay_fees: lamports > 1e7,
+        // ~0.01 SOL — comfortably covers rent plus fees
+        note: lamports === 0 ? 'No SOL. Funding will fail with "Attempt to debit an account but found no record of a prior credit", which does not mention SOL.' : void 0,
+        _decimals: decimals
+      };
+    }
+    case "fund_solana_mission": {
+      const { loadSolanaWallet, associatedTokenAddress, signTransaction } = await import("./wallet-LX7SI5RE.js");
+      const { verifyFundingTransaction, readEscrowConfig, readMintDecimals, SUPPORTED_ESCROW_INTERFACE } = await import("./verify-7EUVRUAS.js");
+      const wallet = await loadSolanaWallet();
+      const cfg = await apiGet2("/agent/solana/config");
+      if (cfg.escrow_interface !== SUPPORTED_ESCROW_INTERFACE) {
+        return {
+          funded: false,
+          refused_to_sign: true,
+          problems: [
+            `the deployment reports escrow_interface ${JSON.stringify(cfg.escrow_interface)}; this version of @projectsolo/solo-mission-mcp verifies only '${SUPPORTED_ESCROW_INTERFACE}' funding transactions`
+          ],
+          what_this_means: "Nothing was built, signed or escrowed. This server cannot decode the funding transaction the deployment would build, so it will not sign one. Use a version of this package that supports the reported escrow interface."
+        };
+      }
+      const pin = resolvePinnedProgram(cfg);
+      const rpc = resolveTrustedRpc(cfg);
+      if ("problem" in pin || "problem" in rpc) {
+        return {
+          funded: false,
+          refused_to_sign: true,
+          problems: [
+            ..."problem" in pin ? [pin.problem] : [],
+            ..."problem" in rpc ? [rpc.problem] : []
+          ],
+          what_this_means: "Nothing was built, signed or escrowed."
+        };
+      }
+      const rpcUrl = rpc.rpc_url;
+      const { mission } = await apiGet2(`/agent/missions/${args.mission_id}`);
+      if (!mission) {
+        return {
+          funded: false,
+          error: `Could not read mission ${args.mission_id} \u2014 call get_mission to check it exists.`
+        };
+      }
+      const mint = args.expected_mint ?? mission.token_address ?? cfg.mints[Object.keys(cfg.mints)[0]];
+      let decimals;
+      try {
+        decimals = await readMintDecimals(rpcUrl, mint);
+      } catch (e) {
+        return {
+          funded: false,
+          refused_to_sign: true,
+          problems: [
+            `cannot read mint ${mint}'s decimals from chain, which expected_budget is scaled by: ` + e.message
+          ],
+          what_this_means: "Nothing was built, signed or escrowed."
+        };
+      }
+      const tokenAccount = await associatedTokenAddress(mint, wallet.publicKey);
+      const built = await apiPost2(
+        `/agent/solana/missions/${args.mission_id}/funding-transaction`,
+        { sponsor_wallet: wallet.publicKey, sponsor_token_account: tokenAccount }
+      );
+      let onchainConfig = null;
+      let onchainConfigError;
+      try {
+        onchainConfig = await readEscrowConfig(rpcUrl, pin.program_id);
+      } catch (e) {
+        onchainConfigError = e.message;
+      }
+      let quotedFeeBps;
+      let feeQuoteSource;
+      if (args.expected_max_fee_bps !== void 0) {
+        quotedFeeBps = Number(args.expected_max_fee_bps);
+        feeQuoteSource = "expected_max_fee_bps argument";
+      } else if (typeof mission.solana_quoted_fee_bps === "number") {
+        quotedFeeBps = mission.solana_quoted_fee_bps;
+        feeQuoteSource = "mission.solana_quoted_fee_bps (the create_mission quote)";
+      } else {
+        quotedFeeBps = onchainConfig?.fee_bps;
+        feeQuoteSource = "on-chain Config.fee_bps (the mission has no recorded quote)";
+      }
+      const expectedBudgetRaw = toRawAmount(args.expected_budget, decimals);
+      const verdict = await verifyFundingTransaction({
+        transaction_base64: built.transaction_base64,
+        escrow_interface: built.escrow_interface,
+        task_id: String(built.task_id),
+        declared: built.declared,
+        accounts: built.accounts,
+        message_sha256: built.message_sha256,
+        expected: {
+          budget_raw: expectedBudgetRaw,
+          // base_pool is derived by the backend from reward × max_humans. The agent's check on it
+          // is the quoted value against the encoded bytes, which verifyFundingTransaction does —
+          // asserting a locally recomputed figure would require duplicating that arithmetic here
+          // and would fail on a legitimately rounded reward.
+          base_pool_raw: String(built.declared.base_pool),
+          // The rest is what create_mission recorded, not what the funding response says: whether
+          // this is a lottery decides whether a co-signer is required at all.
+          lottery_winner_count: Number(mission.lottery_winner_count ?? 0),
+          lottery_prize_per_winner_raw: String(mission.lottery_prize_per_winner_raw ?? "0"),
+          qualify_deadline: Number(mission.qualify_deadline),
+          settlement_deadline: Number(mission.settlement_deadline),
+          seed_commit: mission.seed_commit,
+          max_fee_bps: quotedFeeBps,
+          mint,
+          sponsor: wallet.publicKey,
+          sponsor_token_account: tokenAccount
+        },
+        expected_program_id: pin.program_id,
+        onchain_config: onchainConfig,
+        onchain_config_error: onchainConfigError
+      });
+      if (!verdict.ok) {
+        return {
+          funded: false,
+          refused_to_sign: true,
+          problems: verdict.problems,
+          warnings: verdict.warnings,
+          summary: verdict.summary,
+          fee_quote_source: feeQuoteSource,
+          what_this_means: "The transaction does not match what you asked for, so it was NOT signed and nothing was escrowed. This is the verifier doing its job. Do not retry blindly \u2014 the discrepancy above is either a bug or an attempt to have you authorise something else."
+        };
+      }
+      if (args.dry_run) {
+        return {
+          funded: false,
+          dry_run: true,
+          verified: true,
+          task_id: built.task_id,
+          summary: verdict.summary,
+          warnings: verdict.warnings,
+          fee_quote_source: feeQuoteSource,
+          would_escrow: `${args.expected_budget} (${expectedBudgetRaw} raw) of ${mint}`
+        };
+      }
+      const signed = await signTransaction(built.transaction_base64, wallet);
+      let confirmed;
+      try {
+        confirmed = await apiPost2(`/agent/solana/missions/${args.mission_id}/confirm-funding`, {
+          signed_transaction: signed,
+          task_id: built.task_id
+        });
+      } catch (e) {
+        const { escrowErrorFromMessage } = await import("./escrowErrors-4XSAYLGT.js");
+        const body = apiErrorBody(e);
+        const message = body.message ?? e?.message ?? String(e);
+        return {
+          funded: false,
+          verified: true,
+          signed: true,
+          status: e?.status,
+          message,
+          program_error: escrowErrorFromMessage(message) ?? void 0,
+          ...body.funding_mismatch ? { funding_mismatch: body.funding_mismatch } : {},
+          ...body.task_id ? { task_id: body.task_id } : {}
+        };
+      }
+      return {
+        funded: true,
+        verified: true,
+        lottery: verdict.summary.lottery,
+        operator_cosigned: verdict.summary.operator_signature === "valid",
+        max_fee_bps: verdict.summary.max_fee_bps,
+        ...confirmed
+      };
+    }
+    case "refund_solana_mission": {
+      const { loadSolanaWallet, associatedTokenAddress, signTransaction } = await import("./wallet-LX7SI5RE.js");
+      const { escrowErrorFromMessage } = await import("./escrowErrors-4XSAYLGT.js");
+      const wallet = await loadSolanaWallet();
+      const cfg = await apiGet2("/agent/solana/config");
+      const { mission } = await apiGet2(`/agent/missions/${args.mission_id}`);
+      const mint = 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);
+      const deadlines = {
+        qualify_deadline: mission?.qualify_deadline,
+        settlement_deadline: mission?.settlement_deadline,
+        ...mission?.qualify_deadline !== void 0 ? { cancel_cutoff: new Date(mission.qualify_deadline * 1e3).toISOString() } : {}
+      };
+      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 = apiErrorBody(e);
+          return {
+            available_actions: body.available_actions ?? [],
+            why_not_claim_refund: body.message,
+            ...deadlines,
+            note: (body.available_actions?.length ?? 0) === 0 ? `Nothing is refundable right now. ${CANCEL_CUTOFF_RULE}` : `Re-run with one of available_actions. ${CANCEL_CUTOFF_RULE}`
+          };
+        }
+      }
+      const nowSec = Math.floor(Date.now() / 1e3);
+      if (args.action === "cancel" && typeof mission?.qualify_deadline === "number" && nowSec >= mission.qualify_deadline) {
+        return {
+          refunded: false,
+          rejected_by: "client",
+          action: "cancel",
+          message: `qualify_deadline (${deadlines.cancel_cutoff}) has passed by this machine's clock, so the escrow program would refuse this cancel (TooLateToCancel). Nothing was built or signed.`,
+          ...deadlines,
+          what_to_do: CANCEL_CUTOFF_RULE
+        };
+      }
+      const pin = resolvePinnedProgram(cfg);
+      if ("problem" in pin) {
+        return {
+          refunded: false,
+          refused_to_sign: true,
+          problems: [pin.problem],
+          what_this_means: "Nothing was built, signed or moved."
+        };
+      }
+      let built;
+      try {
+        built = await apiPost2(
+          `/agent/solana/missions/${args.mission_id}/refund-transaction`,
+          {
+            action: args.action,
+            sponsor_wallet: wallet.publicKey,
+            sponsor_token_account: tokenAccount
+          }
+        );
+      } catch (e) {
+        const body = apiErrorBody(e);
+        const message = body.message ?? e?.message ?? String(e);
+        return {
+          refunded: false,
+          rejected_by: "backend",
+          action: args.action,
+          status: e?.status,
+          message,
+          available_actions: body.available_actions ?? [],
+          program_error: escrowErrorFromMessage(message) ?? void 0,
+          ...deadlines,
+          what_to_do: CANCEL_CUTOFF_RULE
+        };
+      }
+      const { Transaction } = 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() !== pin.program_id) {
+        problems.push(`program is ${ix?.programId?.toBase58()}, expected ${pin.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`);
+      }
+      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,
+          ...built.cancel_deadline ? { cancel_deadline: built.cancel_deadline } : {}
+        };
+      }
+      const signed = await signTransaction(built.transaction_base64, wallet);
+      let confirmed;
+      try {
+        confirmed = await apiPost2(`/agent/solana/missions/${args.mission_id}/confirm-refund`, {
+          signed_transaction: signed,
+          action: args.action
+        });
+      } catch (e) {
+        const body = apiErrorBody(e);
+        const message = body.message ?? e?.message ?? String(e);
+        const programError = escrowErrorFromMessage(message);
+        return {
+          refunded: false,
+          rejected_by: programError || /transaction failed/i.test(message) ? "chain" : "backend",
+          action: args.action,
+          status: e?.status,
+          message,
+          program_error: programError ?? void 0,
+          available_actions: body.available_actions,
+          ...deadlines,
+          what_to_do: programError?.what_to_do ?? CANCEL_CUTOFF_RULE
+        };
+      }
+      return { refunded: true, verified: true, ...confirmed };
+    }
+    default:
+      throw new Error(`Unknown Solana tool: ${name}`);
+  }
+}
+
+// src/server.ts
+var ALL_TOOLS = [...agentTools, ...missionTools, ...humanTools, ...conversationTools, ...realtimeTools, ...trackTools, ...solanaTools];
+var AGENT_TOOL_NAMES = new Set(agentTools.map((t) => t.name));
+var MISSION_TOOL_NAMES = new Set(missionTools.map((t) => t.name));
+var HUMAN_TOOL_NAMES = new Set(humanTools.map((t) => t.name));
+var CONVERSATION_TOOL_NAMES = new Set(conversationTools.map((t) => t.name));
+var REALTIME_TOOL_NAMES = new Set(realtimeTools.map((t) => t.name));
+var TRACK_TOOL_NAMES = new Set(trackTools.map((t) => t.name));
+var server = new Server(
+  { name: "solo-mission-mcp", version: "0.23.3" },
+  { capabilities: { tools: {} } }
+);
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: ALL_TOOLS
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args = {} } = request.params;
+  try {
+    let result;
+    if (AGENT_TOOL_NAMES.has(name)) {
+      result = await handleAgentTool(name, args);
+    } else if (MISSION_TOOL_NAMES.has(name)) {
+      result = await handleMissionTool(name, args);
+    } else if (HUMAN_TOOL_NAMES.has(name)) {
+      result = await handleHumanTool(name, args);
+    } else if (CONVERSATION_TOOL_NAMES.has(name)) {
+      result = await handleConversationTool(name, args);
+    } else if (REALTIME_TOOL_NAMES.has(name)) {
+      result = await handleRealtimeTool(name, args);
+    } else if (TRACK_TOOL_NAMES.has(name)) {
+      result = await handleTrackTool(name, args);
+    } else if (SOLANA_TOOL_NAMES.has(name)) {
+      result = await handleSolanaTool(name, args);
+    } else {
+      return {
+        content: [{ type: "text", text: `Unknown tool: ${name}` }],
+        isError: true
+      };
+    }
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+    };
+  } catch (error) {
+    const message = error?.response?.data ? JSON.stringify(error.response.data) : error?.message ?? String(error);
+    return {
+      content: [{ type: "text", text: `Error: ${message}` }],
+      isError: true
+    };
+  }
+});
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((err) => {
+  console.error("Failed to start solo-mission-mcp:", err);
+  process.exit(1);
+});