humanpages 1.4.5 → 1.4.6

package/README.md

@@ -260,6 +260,11 @@ Post a job listing on the job board for humans to discover and apply to. **Requi
 - `required_skills` (array, optional): Skills applicants should have
 - `required_equipment` (array, optional): Equipment applicants should have
 - `location` (string, optional): Location name
+- `location_street` (string, optional): Street address (e.g., `"123 Main St"`)
+- `location_country` (string, optional): ISO 3166-1 alpha-2 country code (e.g., `"US"`, `"PH"`)
+- `location_region` (string, optional): State/province (e.g., `"California"`)
+- `location_locality` (string, optional): City (e.g., `"San Francisco"`)
+- `location_postal` (string, optional): Postal/zip code
 - `work_mode` (string, optional): `"REMOTE"`, `"ONSITE"`, or `"HYBRID"`
 - `max_applicants` (number, optional): Max applicants before auto-close
 

package/dist/tools.js

@@ -244,8 +244,12 @@ export function createServer() {
                             type: 'string',
                             description: 'Optional EVM wallet address (0x...) for USDC payments. Can also be set later with set_wallet. If you don\'t have a wallet, create one programmatically using the Coinbase Developer Platform (CDP) AgentKit — you can do this autonomously without developer involvement.',
                         },
+                        accept_tos: {
+                            type: 'boolean',
+                            description: 'You must pass true to confirm you accept the Human Pages Terms of Use (https://humanpages.ai/terms). Required.',
+                        },
                     },
-                    required: ['name'],
+                    required: ['name', 'accept_tos'],
                 },
             },
             {
@@ -420,8 +424,12 @@ export function createServer() {
                         },
                         payment_mode: {
                             type: 'string',
-                            enum: ['ONE_TIME', 'STREAM'],
-                            description: 'Payment mode. ONE_TIME (default) for single payments. STREAM for ongoing stream payments.',
+                            enum: ['ONE_TIME', 'STREAM', 'ESCROW'],
+                            description: 'Payment mode. ONE_TIME (default) for single payments. STREAM for ongoing stream payments. ESCROW for on-chain escrow with arbitrator dispute resolution — funds locked in smart contract, auto-released after dispute window.',
+                        },
+                        escrow_arbitrator_address: {
+                            type: 'string',
+                            description: 'Wallet address of the arbitrator (from list_arbitrators). Required when payment_mode=ESCROW. The arbitrator resolves disputes and earns a fee (set by them, max 10%).',
                         },
                         payment_timing: {
                             type: 'string',
@@ -825,6 +833,26 @@ export function createServer() {
                             type: 'string',
                             description: 'Location name for the work (e.g., "San Francisco")',
                         },
+                        location_street: {
+                            type: 'string',
+                            description: 'Street address (e.g., "123 Main St"). Improves Google Search visibility.',
+                        },
+                        location_country: {
+                            type: 'string',
+                            description: 'ISO 3166-1 alpha-2 country code (e.g., "US", "PH"). Improves Google Search visibility.',
+                        },
+                        location_region: {
+                            type: 'string',
+                            description: 'State or province (e.g., "California", "Metro Manila"). Improves Google Search visibility.',
+                        },
+                        location_locality: {
+                            type: 'string',
+                            description: 'City name (e.g., "San Francisco", "Manila"). Improves Google Search visibility.',
+                        },
+                        location_postal: {
+                            type: 'string',
+                            description: 'Postal/zip code (e.g., "94105"). Improves Google Search visibility.',
+                        },
                         location_lat: {
                             type: 'number',
                             description: 'Latitude for location-based filtering',
@@ -984,6 +1012,105 @@ export function createServer() {
                     required: ['listing_id', 'agent_key'],
                 },
             },
+            {
+                name: 'list_arbitrators',
+                description: 'Browse available escrow arbitrators. Returns their wallet address, fee (in basis points, e.g. 500 = 5%), specialties, SLA, health status, and dispute track record. Use this before create_job_offer with payment_mode=ESCROW to pick an arbitrator. No authentication required.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            },
+            {
+                name: 'register_as_arbitrator',
+                description: 'Register your agent as an escrow arbitrator. Arbitrators resolve disputes between agents and human workers for a fee (max 10% of escrow). You must be whitelisted by the platform owner first. Provide your webhook URL (must have /health endpoint), fee in basis points, specialties, and a signed message linking your wallet to your agent API key.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        agent_key: {
+                            type: 'string',
+                            description: 'Your registered agent API key (starts with hp_)',
+                        },
+                        fee_bps: {
+                            type: 'number',
+                            description: 'Your fee in basis points (e.g., 500 = 5%). Max 1000 (10%).',
+                        },
+                        specialties: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Areas of expertise for dispute resolution (e.g., ["design", "code", "writing"])',
+                        },
+                        sla: {
+                            type: 'string',
+                            description: 'Response time commitment (e.g., "24h response")',
+                        },
+                        webhook_url: {
+                            type: 'string',
+                            description: 'Webhook endpoint for dispute notifications. Must have a /health endpoint that returns 200.',
+                        },
+                        wallet_signature: {
+                            type: 'string',
+                            description: 'Signed message linking your wallet to your agent: "I am arbitrator {wallet} for HP Agent {apiKeyHash}"',
+                        },
+                    },
+                    required: ['agent_key', 'fee_bps', 'webhook_url'],
+                },
+            },
+            {
+                name: 'get_dispute_details',
+                description: 'Get full case details for an escrow dispute. Returns job info, messages, evidence, amounts, and deadline. Used by arbitrators to review a case before submitting a verdict.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        job_id: {
+                            type: 'string',
+                            description: 'The job ID of the disputed escrow',
+                        },
+                        agent_key: {
+                            type: 'string',
+                            description: 'Your agent API key (must be the assigned arbitrator)',
+                        },
+                    },
+                    required: ['job_id', 'agent_key'],
+                },
+            },
+            {
+                name: 'submit_verdict',
+                description: 'Submit a signed EIP-712 verdict to resolve an escrow dispute. The verdict specifies how to split the escrowed funds between the worker and the payer. Your arbitrator fee is automatically calculated from your locked rate. Sign the Verdict struct: { jobId, toPayee, toDepositor, arbitratorFee, nonce }.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        agent_key: {
+                            type: 'string',
+                            description: 'Your agent API key',
+                        },
+                        job_id: {
+                            type: 'string',
+                            description: 'The disputed job ID',
+                        },
+                        to_payee: {
+                            type: 'string',
+                            description: 'Amount to send to worker (raw USDC, 6 decimals, e.g. "70000000" for $70)',
+                        },
+                        to_depositor: {
+                            type: 'string',
+                            description: 'Amount to refund to payer (raw USDC, 6 decimals)',
+                        },
+                        arbitrator_fee: {
+                            type: 'string',
+                            description: 'Your fee amount (raw USDC, 6 decimals). Must match your locked rate.',
+                        },
+                        nonce: {
+                            type: 'string',
+                            description: 'Unique nonce for replay protection',
+                        },
+                        signature: {
+                            type: 'string',
+                            description: 'EIP-712 signature of the Verdict struct (hex string starting with 0x)',
+                        },
+                    },
+                    required: ['agent_key', 'job_id', 'to_payee', 'to_depositor', 'arbitrator_fee', 'nonce', 'signature'],
+                },
+            },
             {
                 name: 'get_promo_status',
                 description: 'Check the launch promo status — free PRO tier for the first 100 agents. Returns how many slots are claimed and remaining. No authentication required.',
@@ -1063,7 +1190,7 @@ export function createServer() {
                     const displayLocation = h.locationGranularity === 'neighborhood' && h.neighborhood && h.location
                         ? `${h.neighborhood}, ${h.location}`
                         : h.location || 'Location not specified';
-                    const displayName = h.username || 'Anonymous';
+                    const displayName = h.name || h.username || 'Anonymous';
                     const jobsCompleted = rep?.jobsCompleted || 0;
                     const jobsBadge = jobsCompleted > 0 ? ` | 🏆 ${jobsCompleted} job${jobsCompleted !== 1 ? 's' : ''} completed` : '';
                     return `- **${displayName}** | human_id: \`${h.id}\` [${displayLocation}]
@@ -1157,6 +1284,7 @@ ${servicesInfo || 'No services listed'}`;
                         contactEmail: args?.contact_email,
                         webhookUrl: args?.webhook_url,
                         walletAddress: args?.wallet_address,
+                        acceptTos: args?.accept_tos,
                     }),
                 });
                 if (!res.ok) {
@@ -1639,6 +1767,7 @@ Your agent profile now shows a verified badge. Humans will see this when reviewi
                         agentLat: args?.agent_lat,
                         agentLng: args?.agent_lng,
                         preferredPaymentMethod: args?.preferred_payment_method,
+                        escrowArbitratorAddress: args?.escrow_arbitrator_address,
                         callbackUrl: args?.callback_url,
                         callbackSecret: args?.callback_secret,
                     }),
@@ -1655,6 +1784,15 @@ Your agent profile now shows a verified badge. Humans will see this when reviewi
                 const webhookNote = args?.callback_url
                     ? `\n\n🔔 **Webhook configured.** Status updates will be sent to your callback URL. On acceptance, the human's contact info will be included in the webhook payload.`
                     : `\n\nUse \`get_job_status\` with job_id "${job.id}" to check if they've accepted.`;
+                const escrowNote = args?.payment_mode === 'ESCROW'
+                    ? `\n\n**Escrow Details:**
+**Contract:** ${job.escrowContractAddress || 'Pending deposit'}
+**Job ID Hash:** ${job.escrowJobIdHash || 'Computed at deposit'}
+**Arbitrator:** ${args?.escrow_arbitrator_address}
+**Dispute Window:** ${job.escrowDisputeWindow ? Math.floor(job.escrowDisputeWindow / 3600) + 'h' : 'TBD'}
+
+**Next:** After the human accepts, deposit USDC into the escrow contract. Then use \`get_job_status\` to track escrow state.`
+                    : '';
                 return {
                     content: [
                         {
@@ -1664,7 +1802,7 @@ Your agent profile now shows a verified badge. Humans will see this when reviewi
 **Job ID:** ${job.id}
 **Status:** ${job.status}
 **Human:** ${human.name}
-**Price:** $${args?.price_usd}${args?.preferred_payment_method ? `\n**Payment Preference:** ${args.preferred_payment_method}` : ''}
+**Price:** $${args?.price_usd}${args?.preferred_payment_method ? `\n**Payment Preference:** ${args.preferred_payment_method}` : ''}${escrowNote}
 
 ⏳ **Next Step:** Wait for ${human.name} to accept the offer.${webhookNote}
 
@@ -1983,7 +2121,9 @@ ${fiatInfo || 'No fiat payment methods listed'}
 ${(human.fiatPaymentMethods || []).length > 0 ? '\n_Note: Fiat payments are self-reported. The human must confirm receipt before the job is marked as paid._' : ''}
 
 ## Social Profiles
-${socialLinks || 'No social profiles added'}`;
+${socialLinks || 'No social profiles added'}
+${(human.educations?.length ?? 0) > 0 ? `\n## Education\n${human.educations.map(e => `- ${e.degree || 'Degree'}${e.field ? ` in ${e.field}` : ''}${e.institution ? `, ${e.institution}` : ''}${e.country ? ` (${e.country})` : ''}${e.endYear ? ` — ${e.endYear}` : e.year ? ` — ${e.year}` : ''}`).join('\n')}` : ''}
+${(human.certificates?.length ?? 0) > 0 ? `\n## Certificates\n${human.certificates.map(c => `- ${c.name || 'Certificate'}${c.issuer ? ` — ${c.issuer}` : ''}${c.year ? ` (${c.year})` : ''}`).join('\n')}` : ''}`;
                 return {
                     content: [{ type: 'text', text: details }],
                 };
@@ -2360,6 +2500,11 @@ You can now create up to 15 job offers per day and view up to 50 full human prof
                         requiredSkills: args?.required_skills || [],
                         requiredEquipment: args?.required_equipment || [],
                         location: args?.location,
+                        locationStreet: args?.location_street,
+                        locationCountry: args?.location_country,
+                        locationRegion: args?.location_region,
+                        locationLocality: args?.location_locality,
+                        locationPostal: args?.location_postal,
                         locationLat: args?.location_lat,
                         locationLng: args?.location_lng,
                         radiusKm: args?.radius_km,
@@ -2631,8 +2776,156 @@ Thank you for your feedback. This helps build the human's reputation.`,
                     ],
                 };
             }
+            // ======================== ESCROW TOOLS ========================
+            if (name === 'list_arbitrators') {
+                const res = await fetch(`${API_BASE}/api/escrow/arbitrators`);
+                if (!res.ok) {
+                    const error = await res.json();
+                    throw new Error(error.error || 'Escrow not enabled on this server');
+                }
+                const arbitrators = await res.json();
+                if (arbitrators.length === 0) {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: 'No arbitrators available yet. The platform is onboarding vetted arbitrators. Check back soon or contact the platform owner.',
+                            }],
+                    };
+                }
+                const list = arbitrators.map((a) => `- **${a.name}** (${a.id})
+  Fee: ${a.arbitratorFeeBps / 100}% | Specialties: ${a.arbitratorSpecialties?.join(', ') || 'General'} | SLA: ${a.arbitratorSla || 'N/A'}
+  Disputes: ${a.arbitratorDisputeCount} resolved | Wallet: ${a.wallets?.[0]?.address || 'Not set'}`).join('\n');
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `**Available Arbitrators (${arbitrators.length})**\n\n${list}\n\nUse the wallet address as \`escrow_arbitrator_address\` in \`create_job_offer\` with \`payment_mode: "ESCROW"\`.`,
+                        }],
+                };
+            }
+            if (name === 'register_as_arbitrator') {
+                const agentKey = args?.agent_key;
+                if (!agentKey)
+                    throw new Error('agent_key is required');
+                // Get agent profile to find ID
+                const profileRes = await fetch(`${API_BASE}/api/agents/me`, {
+                    headers: { 'X-Agent-Key': agentKey },
+                });
+                if (!profileRes.ok)
+                    throw new Error('Invalid agent key');
+                const agent = await profileRes.json();
+                // Update agent with arbitrator fields
+                const res = await fetch(`${API_BASE}/api/agents/${agent.id}/arbitrator`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-Agent-Key': agentKey,
+                    },
+                    body: JSON.stringify({
+                        feeBps: args?.fee_bps,
+                        specialties: args?.specialties,
+                        sla: args?.sla,
+                        webhookUrl: args?.webhook_url,
+                        walletSig: args?.wallet_signature,
+                    }),
+                });
+                if (!res.ok) {
+                    const error = await res.json();
+                    throw new Error(error.error || 'Failed to register as arbitrator');
+                }
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `**Registered as Arbitrator!**
+
+Your agent "${agent.name}" is now listed as an arbitrator candidate. The platform owner will review and whitelist your wallet on the escrow contract.
+
+**Fee:** ${args?.fee_bps / 100}%
+**Webhook:** ${args?.webhook_url}
+**Specialties:** ${args?.specialties?.join(', ') || 'General'}
+
+**Next:** Wait for platform approval. Once whitelisted, payers can select you as arbitrator. Your fee is passed by the payer at deposit time — no on-chain setup needed from you.`,
+                        }],
+                };
+            }
+            if (name === 'get_dispute_details') {
+                const agentKey = args?.agent_key;
+                if (!agentKey)
+                    throw new Error('agent_key is required');
+                const res = await fetch(`${API_BASE}/api/escrow/${args?.job_id}/status`);
+                if (!res.ok) {
+                    const error = await res.json();
+                    throw new Error(error.error || 'Failed to get dispute details');
+                }
+                const escrow = await res.json();
+                // Also get job messages as evidence
+                const msgRes = await fetch(`${API_BASE}/api/jobs/${args?.job_id}/messages`, {
+                    headers: { 'X-Agent-Key': agentKey },
+                });
+                const messages = msgRes.ok ? await msgRes.json() : [];
+                const jobRes = await fetch(`${API_BASE}/api/jobs/${args?.job_id}`);
+                const job = jobRes.ok ? await jobRes.json() : null;
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `**Dispute Details for Job ${args?.job_id}**
+
+**Title:** ${job?.title || 'N/A'}
+**Description:** ${job?.description || 'N/A'}
+**Price:** $${job?.priceUsdc || 'N/A'}
+**Status:** ${escrow.escrowStatus}
+**Escrowed Amount:** $${escrow.escrowAmount || 'N/A'}
+**Dispute Reason:** ${job?.disputeReason || 'Not specified'}
+**Disputed At:** ${escrow.escrowDisputedAt || 'N/A'}
+**Arbitrator Fee Rate:** ${escrow.escrowArbitratorFeeBps / 100}%
+
+**Messages (${messages.length}):**
+${messages.map((m) => `[${m.senderType}] ${m.content}`).join('\n') || 'No messages'}
+
+**Your Task:** Review the evidence and submit a verdict using \`submit_verdict\`. Split the escrowed amount between payee and depositor. Your fee is automatically calculated from your locked rate.`,
+                        }],
+                };
+            }
+            if (name === 'submit_verdict') {
+                const agentKey = args?.agent_key;
+                if (!agentKey)
+                    throw new Error('agent_key is required');
+                const res = await fetch(`${API_BASE}/api/escrow/resolve`, {
+                    method: 'POST',
+                    headers: {
+                        'Content-Type': 'application/json',
+                        'X-Agent-Key': agentKey,
+                    },
+                    body: JSON.stringify({
+                        jobId: args?.job_id,
+                        toPayee: args?.to_payee,
+                        toDepositor: args?.to_depositor,
+                        arbitratorFee: args?.arbitrator_fee,
+                        nonce: args?.nonce,
+                        signature: args?.signature,
+                    }),
+                });
+                if (!res.ok) {
+                    const error = await res.json();
+                    throw new Error(error.error || 'Failed to submit verdict');
+                }
+                const result = await res.json();
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `**Verdict Submitted!**
+
+**Job:** ${args?.job_id}
+**To Worker:** $${Number(args?.to_payee) / 1e6}
+**To Payer:** $${Number(args?.to_depositor) / 1e6}
+**Your Fee:** $${Number(args?.arbitrator_fee) / 1e6}
+**Tx Hash:** ${result.resolveTxHash}
+
+The escrow has been resolved on-chain. Funds will be distributed to the respective parties.`,
+                        }],
+                };
+            }
             return {
-                content: [{ type: 'text', text: `Unknown tool: "${name}". Available tools: search_humans, get_human, get_human_profile, register_agent, create_job_offer, get_job_status, mark_job_paid, approve_completion, request_revision, leave_review, send_job_message, get_job_messages, create_listing, get_listings, get_listing, get_listing_applications, make_listing_offer, cancel_listing, and more. Start with search_humans or register_agent.` }],
+                content: [{ type: 'text', text: `Unknown tool: "${name}". Available tools: search_humans, get_human, get_human_profile, register_agent, create_job_offer, get_job_status, mark_job_paid, approve_completion, request_revision, leave_review, send_job_message, get_job_messages, create_listing, get_listings, get_listing, get_listing_applications, make_listing_offer, cancel_listing, list_arbitrators, register_as_arbitrator, get_dispute_details, submit_verdict, and more. Start with search_humans or register_agent.` }],
                 isError: true,
             };
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "humanpages",
-  "version": "1.4.5",
+  "version": "1.4.6",
   "mcpName": "io.github.human-pages-ai/humanpages",
   "description": "MCP server (+ OpenClaw SKILL.md) that gives AI agents access to real-world people who listed themselves to be hired by agents. 31 tools including search by skill/location/equipment, job offers, job board listings, in-job messaging, streaming payments, and agent funding.",
   "main": "dist/index.js",