rentahuman-mcp 3.2.0 → 3.2.1

package/dist/serve.js

@@ -3175,7 +3175,12 @@ var common = {
   invalidTimeFormat: "Invalid time format. Use HH:mm (e.g., 09:00, 14:30)."
 };
 var bounties = {
-  dryRunPreview: "This is a preview \u2014 the bounty has NOT been created yet. preview.fundingTotal is the total funding requirement (including the platform fee) before any existing wallet balance is applied, so it may be higher than the hosted checkout charge. Show this estimate to the operator and ask if they'd like to edit anything before posting. To create the bounty, call create_bounty again with the same parameters and dryRun omitted or set to false.",
+  dryRunPreview: "This is a preview \u2014 the bounty has NOT been created yet, no funds were reserved, and no checkout was started. preview.fundingTotal is the total funding requirement (including the platform fee) before any existing wallet balance is applied, so it may be higher than the hosted checkout charge. Show this estimate to the operator and ask if they'd like to edit anything before posting. To create the bounty, call create_bounty again with the same parameters and dryRun omitted or set to false.",
+  dryRunServerValidated: "serverValidation=passed: the RentAHuman API validated and normalized these parameters with the same rules as a real create (country targeting, pricing, screening fields, content moderation). The AI content review runs only on the real create, so a live bounty can additionally land in pending_review.",
+  dryRunServerUnavailable: "serverValidation=unavailable: the RentAHuman API could not be reached, so this preview was computed locally and has NOT been validated by the server (country targeting, pricing rules and screening fields are only checked there). Tell the operator the preview is unverified and retry the preview before creating.",
+  dryRunMockPreview: "serverValidation=skipped: mock mode computes the preview locally without contacting the API.",
+  retryWithSameKey: (idempotencyKey) => `The API did not confirm whether the bounty was created. Retry create_bounty with the same parameters and the same idempotencyKey ("${idempotencyKey}") after about 30 seconds: a replay returns the original bounty (including its deposit_url) instead of creating a duplicate, and a 409 idempotency_in_progress means the first attempt is still running \u2014 wait and retry again. Do not change the idempotencyKey.`,
+  retryWithoutKey: "The API did not confirm whether the bounty was created, and this call had no idempotencyKey, so a plain retry could create a duplicate. First call list_bounties (mine=true) to check for a bounty with this title (an unfunded one is in pending_deposit status and is not publicly visible). If it is missing, retry with an idempotencyKey so further retries are safe.",
   createdMultiPerson: (spotsAvailable) => `Multi-person bounty created successfully. Looking for ${spotsAvailable} humans.`,
   createdSingle: "Bounty created successfully. Humans can now view and apply.",
   depositRequired: "DEPOSIT REQUIRED: The bounty has been created but is NOT visible yet. Tell the operator checkout_total (it includes a platform fee) before they pay. They must complete checkout at the deposit_url to make the bounty live. Share this URL with the human who owns this account.",
@@ -3300,6 +3305,12 @@ var MOCK_HIRING_STATUSES = /* @__PURE__ */ new Set([
   "pending_funding",
   "partially_filled"
 ]);
+var asRecord = (value) => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return {};
+  }
+  return Object.fromEntries(Object.entries(value));
+};
 var mockHiringSpotsRemaining = (bounty) => MOCK_HIRING_STATUSES.has(bounty.status) ? Math.max(0, (bounty.spotsAvailable || 1) - (bounty.spotsFilled || 0)) : 0;
 var handleCreateBounty = (args) => Effect9.gen(function* () {
   const params = yield* decode(CreateBountyRequest)(args);
@@ -3317,6 +3328,11 @@ var handleCreateBounty = (args) => Effect9.gen(function* () {
   const screeningFields = screeningFieldsResult.fields;
   const excludedParticipantSourceBountyIds = params.excludedParticipantSourceBountyIds?.length ? params.excludedParticipantSourceBountyIds : void 0;
   const exclusionFields = excludedParticipantSourceBountyIds ? { excludedParticipantSourceBountyIds } : {};
+  const {
+    dryRun: _dryRun,
+    excludedParticipantSourceBountyIds: _rawExclusion,
+    ...createParams
+  } = params;
   if (params.dryRun) {
     const spotsAvailable = params.spotsAvailable || 1;
     const currency = params.currency || "USD";
@@ -3365,11 +3381,66 @@ var handleCreateBounty = (args) => Effect9.gen(function* () {
         spotsAvailable
       })
     };
+    if (config.mockMode) {
+      return ok({
+        success: true,
+        dryRun: true,
+        serverValidation: "skipped",
+        preview,
+        message: `${messages.bounties.dryRunPreview} ${messages.bounties.dryRunMockPreview}`
+      });
+    }
+    const verification2 = yield* identity2.createVerification("create_bounty");
+    const { idempotencyKey: _previewKey, ...previewParams } = createParams;
+    const outcome = yield* api.post("/bounties", {
+      ...previewParams,
+      ...exclusionFields,
+      applicationDetails: screeningFields,
+      dryRun: true,
+      ...verification2
+    }).pipe(
+      Effect9.map((result2) => ({
+        kind: "server",
+        result: asRecord(result2)
+      })),
+      Effect9.catchTag(
+        "TimeoutError",
+        () => Effect9.succeed({ kind: "unreachable" })
+      ),
+      Effect9.catchTag(
+        "ApiError",
+        (error) => Effect9.succeed(
+          error.statusCode === 0 ? { kind: "unreachable" } : { kind: "rejected", error }
+        )
+      )
+    );
+    if (outcome.kind === "rejected") {
+      return err({
+        success: false,
+        dryRun: true,
+        error: outcome.error.body,
+        errorType: "ApiError",
+        statusCode: outcome.error.statusCode,
+        endpoint: outcome.error.endpoint
+      });
+    }
+    if (outcome.kind === "unreachable") {
+      return ok({
+        success: true,
+        dryRun: true,
+        serverValidation: "unavailable",
+        preview,
+        message: `${messages.bounties.dryRunPreview} ${messages.bounties.dryRunServerUnavailable}`
+      });
+    }
+    const serverPreview = asRecord(outcome.result.preview);
+    const fundingTotal = typeof outcome.result.fundingTotal === "number" ? outcome.result.fundingTotal : preview.fundingTotal;
     return ok({
       success: true,
       dryRun: true,
-      preview,
-      message: messages.bounties.dryRunPreview
+      serverValidation: "passed",
+      preview: { ...serverPreview, fundingTotal },
+      message: `${messages.bounties.dryRunPreview} ${messages.bounties.dryRunServerValidated}`
     });
   }
   yield* rateLimit.check("create_bounty");
@@ -3428,18 +3499,42 @@ var handleCreateBounty = (args) => Effect9.gen(function* () {
       })
     );
   }
-  const {
-    dryRun: _,
-    excludedParticipantSourceBountyIds: _rawExclusion,
-    ...createParams
-  } = params;
   const verification = yield* identity2.createVerification("create_bounty");
-  const result = yield* api.post("/bounties", {
+  const created = yield* api.post("/bounties", {
     ...createParams,
     ...exclusionFields,
     applicationDetails: screeningFields,
     ...verification
-  });
+  }).pipe(
+    Effect9.map((result2) => ({
+      ok: true,
+      result: asRecord(result2)
+    })),
+    // Upstream failures (gateway errors, timeouts, no response) leave the
+    // agent unsure whether the bounty exists. Client errors keep their
+    // normal error path — they are answers, not uncertainty.
+    Effect9.catchTag(
+      "TimeoutError",
+      (error) => Effect9.succeed({ ok: false, error })
+    ),
+    Effect9.catchTag(
+      "ApiError",
+      (error) => error.statusCode === 0 || error.statusCode >= 500 ? Effect9.succeed({ ok: false, error }) : Effect9.fail(error)
+    )
+  );
+  if (!created.ok) {
+    const failure = created.error;
+    const isApiError = "statusCode" in failure;
+    return err({
+      success: false,
+      error: failure.message,
+      errorType: isApiError ? "ApiError" : "TimeoutError",
+      ...isApiError ? { statusCode: failure.statusCode } : {},
+      endpoint: failure.endpoint,
+      retry_guidance: params.idempotencyKey ? messages.bounties.retryWithSameKey(params.idempotencyKey) : messages.bounties.retryWithoutKey
+    });
+  }
+  const result = created.result;
   if (result.deposit_url) {
     return ok({
       ...result,
@@ -3908,7 +4003,7 @@ var payEnterpriseBountyTool = toMcpTool(
 var bountyTools = [
   {
     name: "create_bounty",
-    description: `Create a one-shot task bounty for humans to apply to. To target an entire country, pass location with an ISO country code and isRemoteAllowed=false while omitting city and state. **IMPORTANT: Always call with dryRun=true first** to preview the bounty. Dry-run \`preview.fundingTotal\` is the total funding requirement before any existing wallet balance is applied. Show that estimate to the operator before posting. Show the preview to the user and ask 'Here's your bounty \u2014 would you like to edit anything before posting?' Only call again with dryRun=false (or omitted) after the user confirms. **You MUST help the user define completionCriteria and evidenceTypes** \u2014 ask what 'done' looks like and what proof they need (text/data, photos, video, or links). For specialized standard-application tasks, configure applicationDetails so applicants provide application details before review. Blank rows are ignored; application upload fields are one file each and capped at 3 total; acknowledgment checkboxes are capped at 5 total and can be optional or required; and one required live_video field may contain a script applicants must record with the in-browser camera. For appearance-based bounties where the worker appears on camera or their presence is part of the deliverable (sign holding, UGC, sponsored posts, on-camera video, promo/GTM appearances), always include one required live_video field with a label asking the applicant to explain in two sentences why they are a good fit \u2014 this gates applications on a live self-recorded video so the poster sees each applicant before accepting. Do not ask for passwords, OTP/2FA codes, API keys, private keys, seed phrases, government IDs, bank/card details, exact home addresses, dates of birth, or other sensitive personal information. For direct-review collection bounties, use submissionMode='photo_upload', 'video_upload', or 'document_upload' with matching submission settings instead of applicationDetails. lifecycleMessages can define auto-message templates for acceptance, rejection, and submission review transitions. You can require applicants to provide specific links (LinkedIn, GitHub, resume, etc.) using the requiredLinks parameter. Requires RENTAHUMAN_API_KEY from the account owner. Standard accounts use available wallet balance first; if the wallet cannot cover the bounty, the response includes deposit_url and checkout_total (the hosted charge after wallet balance is applied) and the account owner must complete checkout before the bounty is visible. Supports multi-person bounties by setting spotsAvailable > 1. Set completionWindowHours (any whole number of hours from 1 to 720, e.g. 36) to give confirmed workers a completion deadline: overdue seats auto-release and reopen for other applicants; workers may request extensions you answer with decide_extension_request. Pass optional \`idempotencyKey\` to make this safe to retry (a replayed key returns the original result instead of duplicating). Applicants are auto-reviewed by default (autoAccept, default true): deterministic checks always run and an AI review runs only for free-text screening answers \u2014 qualified applicants are accepted, clear mismatches rejected with a reason, uncertain cases left pending for manual review; pass autoAccept: false to review and accept every application yourself; on micCheckRequired bounties, set autoAcceptMinMicScore (1-5) to make the mic score a hard cutoff: applications below it are auto-rejected, at/above proceed toward acceptance, and unscored recordings stay pending. When omitted, the platform default 3.0 applies and lower scores only stay pending for manual review. To keep previous participants out, pass excludedParticipantSourceBountyIds with up to ${MAX_EXCLUDED_PARTICIPANT_SOURCE_BOUNTIES} ids of your OWN earlier bounties: any worker who was ever accepted on one of them cannot see or apply to the new bounty, and you can change the list later with update_bounty. AI-managed, QA, and taste run bounties, and never-funded drafts are rejected as sources. BETA: pass aiManaged: true to have the platform fully manage the bounty \u2014 automated recruiting, vetting, submission review, payment release, and a final report. Fixed price USD only, 1-50 spots. Poll the bounty's managed run or subscribe to run.report_ready for the finished work.`,
+    description: `Create a one-shot task bounty for humans to apply to. To target an entire country, pass location with an ISO country code and isRemoteAllowed=false while omitting city and state. **IMPORTANT: Always call with dryRun=true first** to preview the bounty. A preview never creates a bounty, reserves funds, or starts a checkout. When the API is reachable it validates and normalizes the parameters with the same rules as a real create and the response carries serverValidation=passed; if the API cannot be reached the preview is computed locally and carries serverValidation=unavailable \u2014 tell the operator it is unverified. Dry-run \`preview.fundingTotal\` is the total funding requirement before any existing wallet balance is applied. Show that estimate to the operator before posting. Show the preview to the user and ask 'Here's your bounty \u2014 would you like to edit anything before posting?' Only call again with dryRun=false (or omitted) after the user confirms. **You MUST help the user define completionCriteria and evidenceTypes** \u2014 ask what 'done' looks like and what proof they need (text/data, photos, video, or links). For specialized standard-application tasks, configure applicationDetails so applicants provide application details before review. Blank rows are ignored; application upload fields are one file each and capped at 3 total; acknowledgment checkboxes are capped at 5 total and can be optional or required; and one required live_video field may contain a script applicants must record with the in-browser camera. For appearance-based bounties where the worker appears on camera or their presence is part of the deliverable (sign holding, UGC, sponsored posts, on-camera video, promo/GTM appearances), always include one required live_video field with a label asking the applicant to explain in two sentences why they are a good fit \u2014 this gates applications on a live self-recorded video so the poster sees each applicant before accepting. Do not ask for passwords, OTP/2FA codes, API keys, private keys, seed phrases, government IDs, bank/card details, exact home addresses, dates of birth, or other sensitive personal information. For direct-review collection bounties, use submissionMode='photo_upload', 'video_upload', or 'document_upload' with matching submission settings instead of applicationDetails. lifecycleMessages can define auto-message templates for acceptance, rejection, and submission review transitions. You can require applicants to provide specific links (LinkedIn, GitHub, resume, etc.) using the requiredLinks parameter. Requires RENTAHUMAN_API_KEY from the account owner. Standard accounts use available wallet balance first; if the wallet cannot cover the bounty, the response includes deposit_url and checkout_total (the hosted charge after wallet balance is applied) and the account owner must complete checkout before the bounty is visible. Supports multi-person bounties by setting spotsAvailable > 1. Set completionWindowHours (any whole number of hours from 1 to 720, e.g. 36) to give confirmed workers a completion deadline: overdue seats auto-release and reopen for other applicants; workers may request extensions you answer with decide_extension_request. Pass optional \`idempotencyKey\` to make this safe to retry (a replayed key returns the original result instead of duplicating). Applicants are auto-reviewed by default (autoAccept, default true): deterministic checks always run and an AI review runs only for free-text screening answers \u2014 qualified applicants are accepted, clear mismatches rejected with a reason, uncertain cases left pending for manual review; pass autoAccept: false to review and accept every application yourself; on micCheckRequired bounties, set autoAcceptMinMicScore (1-5) to make the mic score a hard cutoff: applications below it are auto-rejected, at/above proceed toward acceptance, and unscored recordings stay pending. When omitted, the platform default 3.0 applies and lower scores only stay pending for manual review. To keep previous participants out, pass excludedParticipantSourceBountyIds with up to ${MAX_EXCLUDED_PARTICIPANT_SOURCE_BOUNTIES} ids of your OWN earlier bounties: any worker who was ever accepted on one of them cannot see or apply to the new bounty, and you can change the list later with update_bounty. AI-managed, QA, and taste run bounties, and never-funded drafts are rejected as sources. BETA: pass aiManaged: true to have the platform fully manage the bounty \u2014 automated recruiting, vetting, submission review, payment release, and a final report. Fixed price USD only, 1-50 spots. Poll the bounty's managed run or subscribe to run.report_ready for the finished work.`,
     inputSchema: toInputSchema(CreateBountyRequest),
     handler: handleCreateBounty
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rentahuman-mcp",
-  "version": "3.2.0",
+  "version": "3.2.1",
   "description": "MCP server for AI agents to browse and book humans on rentahuman.ai",
   "keywords": [
     "ai",