payclaw-mcp

Instructions

Implementation Reference

• src/index.ts:105-135 (handler)

  Registration of the kya_reportBadgeOutcome tool in src/index.ts.

  server.tool(
    "kya_reportBadgeOutcome",
    `Report how the merchant responded when you presented your Badge.
  
  Call this after kya_reportBadgePresented when you know whether the merchant accepted or denied you. Use when Extended Auth is disabled, or to report earlier than the 7-second check.`,
    {
      verification_token: z.string().describe(
        "The verification_token returned by kya_getAgentIdentity"
      ),
      merchant: z.string().max(200).describe(
        "The merchant where you presented (e.g., 'starbucks.com')"
      ),
      outcome: z
        .enum(["accepted", "denied", "inconclusive"])
        .describe(
          "accepted = merchant let you through; denied = blocked/bot-walled; inconclusive = unknown or timed out"
        ),
      trip_id: z.string().uuid().optional().describe(
        "Trip ID from kya_getAgentIdentity — links events in this shopping session"
      ),
    },
    async ({ verification_token, merchant, outcome, trip_id }) => {
      reportOutcomeFromAgent(verification_token, merchant, outcome, trip_id);
      return {
        content: [{
          type: "text",
          text: `✓ Outcome recorded: ${outcome} at ${merchant}`,
        }],
      };
    }
  );

• src/sampling.ts:312-343 (handler)

  Implementation of the reportOutcomeFromAgent function used by the kya_reportBadgeOutcome tool.

  export function reportOutcomeFromAgent(
    token: string,
    merchant: string,
    outcome: "accepted" | "denied" | "inconclusive",
    tripId?: string
  ): void {
    if (activeTrips.has(token)) {
      // Attach trip_id to the active trip before resolving
      if (tripId) activeTrips.get(token)!.tripId = tripId;
      resolveTrip(token, outcome, "agent_reported");
      return;
    }
    // Token may be from before restart — try to find a unique trip by merchant
    let matchToken: string | null = null;
    let matchCount = 0;
    for (const [t, trip] of activeTrips) {
      if (trip.merchant === merchant && trip.presented && !trip.outcome) {
        matchToken = t;
        matchCount++;
        if (matchCount > 1) break;
      }
    }
    if (matchCount === 1 && matchToken) {
      if (tripId) activeTrips.get(matchToken)!.tripId = tripId;
      resolveTrip(matchToken, outcome, "agent_reported");
      return;
    }
    // No matching trip — still report to API so outcome is recorded
    reportOutcome(token, outcome, merchant, "agent_reported", tripId).catch((err) => {
      process.stderr.write(`[BADGE] Failed to report outcome: ${err}\n`);
    });
  }