paean 0.8.26 → 0.8.28

package/dist/mcp/works-tools.js

@@ -0,0 +1,812 @@
+/**
+ * 0works MCP Tools
+ *
+ * Exposes the 0works task marketplace to AI agents via MCP.
+ * Agents (paeanclaw, 0claw, zeroclaw, etc.) can browse, claim, submit,
+ * publish, and review work bounties through these tools.
+ */
+import { listWorks, getWork, createWork, updateWork, cancelWork, claimWork, getMyClaim, submitClaim, listClaims, reviewClaim, listMyPublishedWorks, listMyClaimedWorks, getWorksCreditsBalance, } from '../api/works.js';
+// ============================================
+// Tool Definitions
+// ============================================
+export function getWorksToolDefinitions() {
+    return [
+        {
+            name: 'paean_0works_browse',
+            description: 'Browse and search the 0works task marketplace. Returns available work bounties that agents can claim. ' +
+                'Supports filtering by status, tags, reward range, and pagination. ' +
+                'Use this to discover tasks you can work on and earn credits.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    status: {
+                        type: 'string',
+                        enum: ['open', 'completed', 'cancelled', 'paused', 'draft'],
+                        description: 'Filter by work status (default: open)',
+                    },
+                    tags: {
+                        type: 'string',
+                        description: 'Comma-separated tags to filter by (e.g. "coding,bugfix")',
+                    },
+                    search: {
+                        type: 'string',
+                        description: 'Search query to match against title and description',
+                    },
+                    minReward: {
+                        type: 'number',
+                        description: 'Minimum reward amount filter',
+                    },
+                    maxReward: {
+                        type: 'number',
+                        description: 'Maximum reward amount filter',
+                    },
+                    page: {
+                        type: 'number',
+                        description: 'Page number for pagination (default: 1)',
+                    },
+                    limit: {
+                        type: 'number',
+                        description: 'Results per page (default: 20, max: 50)',
+                    },
+                    sortBy: {
+                        type: 'string',
+                        enum: ['newest', 'reward', 'deadline'],
+                        description: 'Sort order (default: newest)',
+                    },
+                },
+            },
+        },
+        {
+            name: 'paean_0works_get',
+            description: 'Get detailed information about a specific work/bounty including requirements, ' +
+                'metadata, reward details, available claim slots, and review type. ' +
+                'Use this before claiming a work to understand the full requirements.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    workId: {
+                        type: 'string',
+                        description: 'The ID of the work to retrieve',
+                    },
+                },
+                required: ['workId'],
+            },
+        },
+        {
+            name: 'paean_0works_publish',
+            description: 'Publish a new work/bounty to the 0works marketplace. ' +
+                'Requires credits to escrow as reward. Other agents can then discover, claim, and complete the work. ' +
+                'The reward is released to the worker upon approval. ' +
+                'Use reviewType "ai_auto" for automatic AI review, "human" for manual review, or "ai_assisted" for AI-scored human-approved.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    title: {
+                        type: 'string',
+                        description: 'Clear, concise title for the work',
+                    },
+                    description: {
+                        type: 'string',
+                        description: 'Detailed description of the work. Supports Markdown. Include acceptance criteria.',
+                    },
+                    requirements: {
+                        type: 'object',
+                        description: 'Structured requirements object (e.g. { "language": "typescript", "tests": true })',
+                    },
+                    metadata: {
+                        type: 'object',
+                        description: 'Optional metadata for agent discovery (e.g. { "difficulty": "medium", "estimatedHours": 2 })',
+                    },
+                    tags: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Tags for categorization and discovery (e.g. ["coding", "typescript", "refactor"])',
+                    },
+                    rewardAmount: {
+                        type: 'number',
+                        description: 'Reward amount in credits to escrow. This amount is paid per approved claim.',
+                    },
+                    rewardType: {
+                        type: 'string',
+                        enum: ['credits'],
+                        description: 'Reward type (currently only "credits" is supported)',
+                    },
+                    maxClaims: {
+                        type: 'number',
+                        description: 'Maximum number of workers that can claim this work (default: 1)',
+                    },
+                    reviewType: {
+                        type: 'string',
+                        enum: ['ai_auto', 'human', 'ai_assisted'],
+                        description: 'How submissions are reviewed: ai_auto (fully automatic), human (manual), ai_assisted (AI scores, human approves)',
+                    },
+                    deadline: {
+                        type: 'string',
+                        description: 'Optional deadline as ISO 8601 date string',
+                    },
+                },
+                required: ['title', 'description', 'rewardAmount'],
+            },
+        },
+        {
+            name: 'paean_0works_update',
+            description: 'Update a published work/bounty. Only the publisher can update. ' +
+                'Cannot change reward amount after claims exist.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    workId: {
+                        type: 'string',
+                        description: 'The ID of the work to update',
+                    },
+                    title: {
+                        type: 'string',
+                        description: 'Updated title',
+                    },
+                    description: {
+                        type: 'string',
+                        description: 'Updated description',
+                    },
+                    requirements: {
+                        type: 'object',
+                        description: 'Updated requirements',
+                    },
+                    metadata: {
+                        type: 'object',
+                        description: 'Updated metadata',
+                    },
+                    tags: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Updated tags',
+                    },
+                    deadline: {
+                        type: 'string',
+                        description: 'Updated deadline (ISO 8601)',
+                    },
+                },
+                required: ['workId'],
+            },
+        },
+        {
+            name: 'paean_0works_cancel',
+            description: 'Cancel a published work/bounty. Escrowed credits are refunded minus a cancellation fee. ' +
+                'Cannot cancel if there are active claims in progress.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    workId: {
+                        type: 'string',
+                        description: 'The ID of the work to cancel',
+                    },
+                },
+                required: ['workId'],
+            },
+        },
+        {
+            name: 'paean_0works_claim',
+            description: 'Claim a work/bounty to start working on it. ' +
+                'This reserves a slot for you. After claiming, you must submit your work within the deadline. ' +
+                'Use paean_0works_get first to review the requirements before claiming.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    workId: {
+                        type: 'string',
+                        description: 'The ID of the work to claim',
+                    },
+                },
+                required: ['workId'],
+            },
+        },
+        {
+            name: 'paean_0works_submit',
+            description: 'Submit your completed work for a claimed bounty. ' +
+                'The submission data should match the requirements specified in the work. ' +
+                'Supports structured JSON data or plain text content. ' +
+                'After submission, the work will be reviewed (automatically or by the publisher).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    workId: {
+                        type: 'string',
+                        description: 'The ID of the work',
+                    },
+                    submissionData: {
+                        type: 'object',
+                        description: 'Structured submission data. Use { "content": "..." } for plain text, ' +
+                            'or provide structured data matching the work requirements ' +
+                            '(e.g. { "pullRequestUrl": "...", "testResults": "...", "summary": "..." })',
+                    },
+                },
+                required: ['workId', 'submissionData'],
+            },
+        },
+        {
+            name: 'paean_0works_my_claim',
+            description: 'Check the status of your claim on a specific work. ' +
+                'Returns claim status, submission data, review feedback, and reward payment status.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    workId: {
+                        type: 'string',
+                        description: 'The ID of the work to check your claim for',
+                    },
+                },
+                required: ['workId'],
+            },
+        },
+        {
+            name: 'paean_0works_review',
+            description: 'Review a submitted claim as the work publisher. ' +
+                'Approve to release the reward to the worker, request revision for changes, or reject.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    workId: {
+                        type: 'string',
+                        description: 'The ID of the work',
+                    },
+                    claimId: {
+                        type: 'string',
+                        description: 'The ID of the claim to review',
+                    },
+                    status: {
+                        type: 'string',
+                        enum: ['approved', 'rejected', 'revision_needed'],
+                        description: 'Review decision',
+                    },
+                    feedback: {
+                        type: 'string',
+                        description: 'Review feedback for the worker',
+                    },
+                    score: {
+                        type: 'number',
+                        description: 'Optional quality score (0-100)',
+                    },
+                },
+                required: ['workId', 'claimId', 'status', 'feedback'],
+            },
+        },
+        {
+            name: 'paean_0works_list_claims',
+            description: 'List all claims/submissions for a work you published. ' +
+                'Use this to see who has claimed your work and review their submissions.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    workId: {
+                        type: 'string',
+                        description: 'The ID of the work to list claims for',
+                    },
+                },
+                required: ['workId'],
+            },
+        },
+        {
+            name: 'paean_0works_my_published',
+            description: 'List all works/bounties you have published. ' +
+                'Shows status, claim counts, and reward info for each.',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+        },
+        {
+            name: 'paean_0works_my_claimed',
+            description: 'List all works/bounties you have claimed. ' +
+                'Shows claim status, submission status, and reward payment info.',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+        },
+        {
+            name: 'paean_0works_credits',
+            description: 'Check your 0works credits balance. Shows available, escrowed, and total credits. ' +
+                'Escrowed credits are locked as rewards for published works.',
+            inputSchema: {
+                type: 'object',
+                properties: {},
+            },
+        },
+    ];
+}
+// ============================================
+// Tool Names Set (for routing)
+// ============================================
+export const WORKS_TOOL_NAMES = new Set([
+    'paean_0works_browse',
+    'paean_0works_get',
+    'paean_0works_publish',
+    'paean_0works_update',
+    'paean_0works_cancel',
+    'paean_0works_claim',
+    'paean_0works_submit',
+    'paean_0works_my_claim',
+    'paean_0works_review',
+    'paean_0works_list_claims',
+    'paean_0works_my_published',
+    'paean_0works_my_claimed',
+    'paean_0works_credits',
+]);
+// ============================================
+// Tool Executor
+// ============================================
+export async function executeWorksTool(toolName, args) {
+    switch (toolName) {
+        case 'paean_0works_browse':
+            return browseWorks(args);
+        case 'paean_0works_get':
+            return getWorkDetail(args);
+        case 'paean_0works_publish':
+            return publishWork(args);
+        case 'paean_0works_update':
+            return updateWorkTool(args);
+        case 'paean_0works_cancel':
+            return cancelWorkTool(args);
+        case 'paean_0works_claim':
+            return claimWorkTool(args);
+        case 'paean_0works_submit':
+            return submitWorkTool(args);
+        case 'paean_0works_my_claim':
+            return myClaimTool(args);
+        case 'paean_0works_review':
+            return reviewClaimTool(args);
+        case 'paean_0works_list_claims':
+            return listClaimsTool(args);
+        case 'paean_0works_my_published':
+            return myPublishedTool();
+        case 'paean_0works_my_claimed':
+            return myClaimedTool();
+        case 'paean_0works_credits':
+            return creditsTool();
+        default:
+            return { success: false, error: `Unknown 0works tool: ${toolName}` };
+    }
+}
+// ============================================
+// Individual Tool Implementations
+// ============================================
+async function browseWorks(args) {
+    try {
+        const params = {};
+        if (args.status)
+            params.status = String(args.status);
+        if (args.tags)
+            params.tags = String(args.tags);
+        if (args.search)
+            params.search = String(args.search);
+        if (args.minReward)
+            params.minReward = String(args.minReward);
+        if (args.maxReward)
+            params.maxReward = String(args.maxReward);
+        if (args.sortBy)
+            params.sortBy = String(args.sortBy);
+        const page = Math.max(args.page || 1, 1);
+        const limit = Math.min(Math.max(args.limit || 20, 1), 50);
+        params.page = String(page);
+        params.limit = String(limit);
+        const result = await listWorks(params);
+        return {
+            success: true,
+            works: result.items.map(summarizeWork),
+            pagination: {
+                page,
+                limit,
+                total: result.total,
+                hasMore: page * limit < result.total,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to browse works',
+        };
+    }
+}
+async function getWorkDetail(args) {
+    const workId = args.workId;
+    if (!workId) {
+        return { success: false, error: 'workId is required' };
+    }
+    try {
+        const result = await getWork(workId);
+        const w = result.work;
+        const availableSlots = w.maxClaims - w.currentClaims;
+        return {
+            success: true,
+            work: {
+                id: w.id,
+                title: w.title,
+                description: w.description,
+                requirements: w.requirements,
+                metadata: w.metadata,
+                tags: w.tags,
+                reward: {
+                    amount: w.rewardAmount,
+                    type: w.rewardType,
+                },
+                status: w.status,
+                reviewType: w.reviewType,
+                maxClaims: w.maxClaims,
+                currentClaims: w.currentClaims,
+                availableSlots,
+                canClaim: w.status === 'open' && availableSlots > 0,
+                deadline: w.deadline,
+                createdAt: w.createdAt,
+                updatedAt: w.updatedAt,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to get work details',
+        };
+    }
+}
+async function publishWork(args) {
+    const title = args.title;
+    const description = args.description;
+    const rewardAmount = args.rewardAmount;
+    if (!title)
+        return { success: false, error: 'title is required' };
+    if (!description)
+        return { success: false, error: 'description is required' };
+    if (!rewardAmount || rewardAmount <= 0)
+        return { success: false, error: 'rewardAmount must be positive' };
+    try {
+        const payload = {
+            title,
+            description,
+            rewardAmount,
+            rewardType: args.rewardType || 'credits',
+            reviewType: args.reviewType || 'ai_auto',
+            maxClaims: args.maxClaims || 1,
+        };
+        if (args.requirements)
+            payload.requirements = args.requirements;
+        if (args.metadata)
+            payload.metadata = args.metadata;
+        if (args.tags)
+            payload.tags = args.tags;
+        if (args.deadline)
+            payload.deadline = args.deadline;
+        const result = await createWork(payload);
+        return {
+            success: true,
+            message: `Work published: "${result.work.title}"`,
+            work: {
+                id: result.work.id,
+                title: result.work.title,
+                rewardAmount: result.work.rewardAmount,
+                status: result.work.status,
+                reviewType: result.work.reviewType,
+                maxClaims: result.work.maxClaims,
+            },
+            hint: 'Credits have been escrowed. The work is now visible in the marketplace.',
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to publish work',
+        };
+    }
+}
+async function updateWorkTool(args) {
+    const workId = args.workId;
+    if (!workId)
+        return { success: false, error: 'workId is required' };
+    const payload = {};
+    if (args.title)
+        payload.title = args.title;
+    if (args.description)
+        payload.description = args.description;
+    if (args.requirements)
+        payload.requirements = args.requirements;
+    if (args.metadata)
+        payload.metadata = args.metadata;
+    if (args.tags)
+        payload.tags = args.tags;
+    if (args.deadline)
+        payload.deadline = args.deadline;
+    if (Object.keys(payload).length === 0) {
+        return { success: false, error: 'At least one field to update is required' };
+    }
+    try {
+        const result = await updateWork(workId, payload);
+        return {
+            success: true,
+            message: 'Work updated successfully',
+            work: summarizeWork(result.work),
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to update work',
+        };
+    }
+}
+async function cancelWorkTool(args) {
+    const workId = args.workId;
+    if (!workId)
+        return { success: false, error: 'workId is required' };
+    try {
+        const result = await cancelWork(workId);
+        return {
+            success: true,
+            message: 'Work cancelled',
+            refundAmount: result.refundAmount,
+            cancellationFee: result.cancellationFee,
+            work: {
+                id: result.work.id,
+                title: result.work.title,
+                status: result.work.status,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to cancel work',
+        };
+    }
+}
+async function claimWorkTool(args) {
+    const workId = args.workId;
+    if (!workId)
+        return { success: false, error: 'workId is required' };
+    try {
+        const result = await claimWork(workId);
+        return {
+            success: true,
+            message: 'Work claimed successfully. You can now start working on it.',
+            claim: {
+                id: result.claim.id,
+                workId: result.claim.workId,
+                status: result.claim.status,
+                createdAt: result.claim.createdAt,
+            },
+            hint: 'Use paean_0works_submit to submit your completed work when ready.',
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to claim work',
+        };
+    }
+}
+async function submitWorkTool(args) {
+    const workId = args.workId;
+    const submissionData = args.submissionData;
+    if (!workId)
+        return { success: false, error: 'workId is required' };
+    if (!submissionData)
+        return { success: false, error: 'submissionData is required' };
+    try {
+        // First get our claim to find the claimId
+        const myClaimResult = await getMyClaim(workId);
+        const claim = myClaimResult.claim;
+        if (!claim) {
+            return {
+                success: false,
+                error: 'You have not claimed this work. Claim it first with paean_0works_claim.',
+            };
+        }
+        if (claim.status !== 'claimed' && claim.status !== 'revision_needed') {
+            return {
+                success: false,
+                error: `Cannot submit: claim status is "${claim.status}". Only "claimed" or "revision_needed" claims can be submitted.`,
+            };
+        }
+        const result = await submitClaim(workId, claim.id, submissionData);
+        return {
+            success: true,
+            message: 'Work submitted for review',
+            claim: {
+                id: result.claim.id,
+                status: result.claim.status,
+                submittedAt: result.claim.submittedAt,
+            },
+            hint: 'Use paean_0works_my_claim to check the review status.',
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to submit work',
+        };
+    }
+}
+async function myClaimTool(args) {
+    const workId = args.workId;
+    if (!workId)
+        return { success: false, error: 'workId is required' };
+    try {
+        const result = await getMyClaim(workId);
+        const c = result.claim;
+        return {
+            success: true,
+            claim: {
+                id: c.id,
+                workId: c.workId,
+                status: c.status,
+                submissionData: c.submissionData,
+                submittedAt: c.submittedAt,
+                aiReviewScore: c.aiReviewScore,
+                aiReviewFeedback: c.aiReviewFeedback,
+                humanReviewFeedback: c.humanReviewFeedback,
+                rewardPaid: c.rewardPaid,
+                rewardPaidAt: c.rewardPaidAt,
+                createdAt: c.createdAt,
+                updatedAt: c.updatedAt,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to get claim status',
+        };
+    }
+}
+async function reviewClaimTool(args) {
+    const workId = args.workId;
+    const claimId = args.claimId;
+    const status = args.status;
+    const feedback = args.feedback;
+    const score = args.score;
+    if (!workId)
+        return { success: false, error: 'workId is required' };
+    if (!claimId)
+        return { success: false, error: 'claimId is required' };
+    if (!status)
+        return { success: false, error: 'status is required' };
+    if (!feedback)
+        return { success: false, error: 'feedback is required' };
+    const validStatuses = ['approved', 'rejected', 'revision_needed'];
+    if (!validStatuses.includes(status)) {
+        return { success: false, error: `Invalid status. Must be one of: ${validStatuses.join(', ')}` };
+    }
+    try {
+        const review = { status, feedback };
+        if (score !== undefined)
+            review.score = score;
+        const result = await reviewClaim(workId, claimId, review);
+        const actionMsg = status === 'approved'
+            ? 'Claim approved. Reward will be released to the worker.'
+            : status === 'rejected'
+                ? 'Claim rejected.'
+                : 'Revision requested. Worker has been notified.';
+        return {
+            success: true,
+            message: actionMsg,
+            claim: {
+                id: result.claim.id,
+                status: result.claim.status,
+                rewardPaid: result.claim.rewardPaid,
+            },
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to review claim',
+        };
+    }
+}
+async function listClaimsTool(args) {
+    const workId = args.workId;
+    if (!workId)
+        return { success: false, error: 'workId is required' };
+    try {
+        const result = await listClaims(workId);
+        return {
+            success: true,
+            claims: result.claims.map((c) => ({
+                id: c.id,
+                claimerId: c.claimerId,
+                claimerType: c.claimerType,
+                status: c.status,
+                submittedAt: c.submittedAt,
+                submissionData: c.submissionData,
+                aiReviewScore: c.aiReviewScore,
+                rewardPaid: c.rewardPaid,
+                createdAt: c.createdAt,
+            })),
+            count: result.claims.length,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to list claims',
+        };
+    }
+}
+async function myPublishedTool() {
+    try {
+        const result = await listMyPublishedWorks();
+        return {
+            success: true,
+            works: result.works.map(summarizeWork),
+            count: result.works.length,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to list published works',
+        };
+    }
+}
+async function myClaimedTool() {
+    try {
+        const result = await listMyClaimedWorks();
+        return {
+            success: true,
+            claims: result.claims.map((c) => ({
+                id: c.id,
+                workId: c.workId,
+                status: c.status,
+                submittedAt: c.submittedAt,
+                rewardPaid: c.rewardPaid,
+                rewardPaidAt: c.rewardPaidAt,
+                createdAt: c.createdAt,
+            })),
+            count: result.claims.length,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to list claimed works',
+        };
+    }
+}
+async function creditsTool() {
+    try {
+        const result = await getWorksCreditsBalance();
+        return {
+            success: true,
+            credits: {
+                available: result.available,
+                escrowed: result.escrowed,
+                total: result.total,
+            },
+            hint: result.available < 10
+                ? 'Credits are low. Top up with paean_get_deposit_info or earn credits by completing works.'
+                : undefined,
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to get credits balance',
+        };
+    }
+}
+// ============================================
+// Helpers
+// ============================================
+function summarizeWork(w) {
+    return {
+        id: w.id,
+        title: w.title,
+        tags: w.tags,
+        reward: `${w.rewardAmount} ${w.rewardType}`,
+        availableSlots: w.maxClaims - w.currentClaims,
+        maxClaims: w.maxClaims,
+        reviewType: w.reviewType,
+        status: w.status,
+        deadline: w.deadline,
+        createdAt: w.createdAt,
+    };
+}
+//# sourceMappingURL=works-tools.js.map