@compilr-dev/sdk 0.1.7 → 0.1.8

package/dist/platform/tools/workitem-tools.js

@@ -0,0 +1,715 @@
+/**
+ * Work Item Tools — CRUD + workflow operations for work items.
+ *
+ * 9 tools: workitem_query, workitem_add, workitem_update, workitem_next,
+ *          workitem_delete, workitem_status_counts, workitem_advance_step,
+ *          workitem_claim, workitem_handoff
+ *
+ * Ported from CLI's src/tools/workitem-db.ts. Key adaptations:
+ * - getActiveProject()?.id → ctx.currentProjectId
+ * - getActiveSharedContext() "self" resolution → hooks?.resolveOwner?.('self')
+ * - awardWorkItemCompletion() → hooks?.onWorkItemCompleted?.(item)
+ * - workitem_advance_step imports from ../workflow.js (SDK's module)
+ */
+import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/agents';
+import { getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, STEP_ORDER, } from '../workflow.js';
+// eslint-disable-next-line @typescript-eslint/explicit-function-return-type
+export function createWorkItemTools(config) {
+    const { context: ctx, hooks } = config;
+    // ---------------------------------------------------------------------------
+    // workitem_query
+    // ---------------------------------------------------------------------------
+    const workitemQueryTool = defineTool({
+        name: 'workitem_query',
+        description: 'Query PERSISTENT work items from the project backlog (stored in database). ' +
+            'For session todos shown in footer, use todo_read. ' +
+            'Supports filtering by status, type, priority, owner, and search.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'number',
+                    description: 'Project ID (uses active project if not provided)',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['backlog', 'in_progress', 'completed', 'skipped', 'all'],
+                    description: 'Filter by status (default: all)',
+                },
+                type: {
+                    type: 'string',
+                    enum: ['feature', 'bug', 'tech-debt', 'chore', 'all'],
+                    description: 'Filter by type (default: all)',
+                },
+                priority: {
+                    type: 'string',
+                    enum: ['critical', 'high', 'medium', 'low', 'all'],
+                    description: 'Filter by priority (default: all)',
+                },
+                owner: {
+                    type: 'string',
+                    description: 'Filter by owner: agent ID, "self" for your own items, "unassigned" for unowned, or "all" (default: all)',
+                },
+                search: {
+                    type: 'string',
+                    description: 'Search in title and description',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum items to return (default: 50)',
+                },
+                offset: {
+                    type: 'number',
+                    description: 'Offset for pagination (default: 0)',
+                },
+            },
+            required: [],
+        },
+        execute: async (input) => {
+            try {
+                const projectId = input.project_id ?? ctx.currentProjectId;
+                if (!projectId) {
+                    return createErrorResult('No project specified and no active project. Use project_get or /projects to select a project first.');
+                }
+                // Resolve "self" to the active agent ID via hook
+                let resolvedOwner = input.owner;
+                if (input.owner === 'self') {
+                    resolvedOwner = hooks?.resolveOwner?.('self') ?? undefined;
+                }
+                const queryInput = {
+                    project_id: projectId,
+                    status: input.status,
+                    type: input.type,
+                    priority: input.priority,
+                    owner: resolvedOwner,
+                    search: input.search,
+                    limit: input.limit ?? 50,
+                    offset: input.offset ?? 0,
+                };
+                const result = await ctx.workItems.query(queryInput);
+                const items = result.items.map((item) => ({
+                    id: item.id,
+                    itemId: item.itemId,
+                    type: item.type,
+                    status: item.status,
+                    priority: item.priority,
+                    owner: item.owner,
+                    guidedStep: item.guidedStep,
+                    title: item.title,
+                    description: item.description,
+                    estimatedEffort: item.estimatedEffort,
+                    completedAt: item.completedAt?.toISOString(),
+                    commitHash: item.commitHash,
+                    createdAt: item.createdAt.toISOString(),
+                }));
+                return createSuccessResult({
+                    success: true,
+                    items,
+                    total: result.total,
+                    hasMore: result.hasMore,
+                    projectId,
+                });
+            }
+            catch (error) {
+                return createErrorResult(`Failed to query work items: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // workitem_add
+    // ---------------------------------------------------------------------------
+    const workitemAddTool = defineTool({
+        name: 'workitem_add',
+        description: 'Add a PERSISTENT work item to the project backlog (stored in database). ' +
+            'For session-level tasks shown in footer, use todo_write.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'number',
+                    description: 'Project ID (uses active project if not provided)',
+                },
+                type: {
+                    type: 'string',
+                    enum: ['feature', 'bug', 'tech-debt', 'chore'],
+                    description: 'Work item type',
+                },
+                title: {
+                    type: 'string',
+                    description: 'Title of the work item',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Detailed description',
+                },
+                priority: {
+                    type: 'string',
+                    enum: ['critical', 'high', 'medium', 'low'],
+                    description: 'Priority (default: medium)',
+                },
+                estimated_effort: {
+                    type: 'string',
+                    enum: ['low', 'medium', 'high'],
+                    description: 'Estimated effort',
+                },
+                owner: {
+                    type: 'string',
+                    description: 'Owner agent ID. Omit for unassigned.',
+                },
+            },
+            required: ['type', 'title'],
+        },
+        execute: async (input) => {
+            try {
+                const projectId = input.project_id ?? ctx.currentProjectId;
+                if (!projectId) {
+                    return createErrorResult('No project specified and no active project. Use project_get or /projects to select a project first.');
+                }
+                const createInput = {
+                    project_id: projectId,
+                    type: input.type,
+                    title: input.title,
+                    description: input.description,
+                    priority: input.priority,
+                    estimated_effort: input.estimated_effort,
+                    owner: input.owner,
+                };
+                const item = await ctx.workItems.create(createInput);
+                return createSuccessResult({
+                    success: true,
+                    message: `Work item ${item.itemId} created: "${item.title}"${item.owner ? ` (owner: ${item.owner})` : ''}`,
+                    item: {
+                        id: item.id,
+                        itemId: item.itemId,
+                        type: item.type,
+                        status: item.status,
+                        priority: item.priority,
+                        owner: item.owner,
+                        title: item.title,
+                    },
+                });
+            }
+            catch (error) {
+                return createErrorResult(`Failed to add work item: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // workitem_update
+    // ---------------------------------------------------------------------------
+    const workitemUpdateTool = defineTool({
+        name: 'workitem_update',
+        description: 'Update a PERSISTENT work item in the project backlog (stored in database). ' +
+            'Can update status, priority, owner, title, description, and more.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                item_id: {
+                    type: 'string',
+                    description: 'Work item ID (e.g., "REQ-001", "BUG-002")',
+                },
+                project_id: {
+                    type: 'number',
+                    description: 'Project ID (uses active project if not provided)',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['backlog', 'in_progress', 'completed', 'skipped'],
+                    description: 'Work item status',
+                },
+                priority: {
+                    type: 'string',
+                    enum: ['critical', 'high', 'medium', 'low'],
+                    description: 'Priority',
+                },
+                owner: {
+                    type: 'string',
+                    description: 'Owner agent ID. Set to empty string to unassign.',
+                },
+                guided_step: {
+                    type: 'string',
+                    enum: ['plan', 'implement', 'test', 'commit', 'review'],
+                    description: 'Current step in guided mode workflow',
+                },
+                title: {
+                    type: 'string',
+                    description: 'Updated title',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Updated description',
+                },
+                commit_hash: {
+                    type: 'string',
+                    description: 'Git commit hash when completing the item',
+                },
+            },
+            required: ['item_id'],
+        },
+        execute: async (input) => {
+            try {
+                const projectId = input.project_id ?? ctx.currentProjectId;
+                if (!projectId) {
+                    return createErrorResult('No project specified and no active project. Use project_get or /projects to select a project first.');
+                }
+                const existingItem = await ctx.workItems.getByItemId(projectId, input.item_id);
+                if (!existingItem) {
+                    return createErrorResult(`Work item "${input.item_id}" not found in current project`);
+                }
+                const updateInput = {};
+                if (input.status)
+                    updateInput.status = input.status;
+                if (input.priority)
+                    updateInput.priority = input.priority;
+                if (input.owner !== undefined) {
+                    updateInput.owner = input.owner === '' ? null : input.owner;
+                }
+                if (input.guided_step !== undefined)
+                    updateInput.guided_step = input.guided_step;
+                if (input.title)
+                    updateInput.title = input.title;
+                if (input.description !== undefined)
+                    updateInput.description = input.description;
+                if (input.commit_hash)
+                    updateInput.commit_hash = input.commit_hash;
+                const item = await ctx.workItems.update(existingItem.id, updateInput);
+                if (!item) {
+                    return createErrorResult(`Failed to update work item "${input.item_id}"`);
+                }
+                // Fire hook if work item was just completed
+                if (input.status === 'completed' && existingItem.status !== 'completed') {
+                    hooks?.onWorkItemCompleted?.({
+                        id: item.id,
+                        itemId: item.itemId,
+                        title: item.title,
+                    });
+                }
+                return createSuccessResult({
+                    success: true,
+                    message: `Work item ${item.itemId} updated`,
+                    item: {
+                        id: item.id,
+                        itemId: item.itemId,
+                        type: item.type,
+                        status: item.status,
+                        priority: item.priority,
+                        owner: item.owner,
+                        guidedStep: item.guidedStep,
+                        title: item.title,
+                        completedAt: item.completedAt?.toISOString(),
+                        commitHash: item.commitHash,
+                    },
+                });
+            }
+            catch (error) {
+                return createErrorResult(`Failed to update work item: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // workitem_next
+    // ---------------------------------------------------------------------------
+    const workitemNextTool = defineTool({
+        name: 'workitem_next',
+        description: 'Get the next work item to work on (highest priority backlog item). Useful for guided mode to pick the next task.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'number',
+                    description: 'Project ID (uses active project if not provided)',
+                },
+                type: {
+                    type: 'string',
+                    enum: ['feature', 'bug', 'tech-debt', 'chore'],
+                    description: 'Filter by type (optional)',
+                },
+            },
+            required: [],
+        },
+        execute: async (input) => {
+            try {
+                const projectId = input.project_id ?? ctx.currentProjectId;
+                if (!projectId) {
+                    return createErrorResult('No project specified and no active project. Use project_get or /projects to select a project first.');
+                }
+                const item = await ctx.workItems.getNext(projectId, input.type);
+                if (!item) {
+                    return createSuccessResult({
+                        success: true,
+                        item: null,
+                        message: 'No backlog items found. The backlog is empty or all items are completed.',
+                    });
+                }
+                return createSuccessResult({
+                    success: true,
+                    item: {
+                        id: item.id,
+                        itemId: item.itemId,
+                        type: item.type,
+                        status: item.status,
+                        priority: item.priority,
+                        title: item.title,
+                        description: item.description,
+                        estimatedEffort: item.estimatedEffort,
+                    },
+                    message: `Next item: ${item.itemId} "${item.title}" (${item.priority} priority)`,
+                });
+            }
+            catch (error) {
+                return createErrorResult(`Failed to get next work item: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // workitem_delete
+    // ---------------------------------------------------------------------------
+    const workitemDeleteTool = defineTool({
+        name: 'workitem_delete',
+        description: 'Delete a work item from the backlog.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                item_id: {
+                    type: 'string',
+                    description: 'Work item ID (e.g., "REQ-001", "BUG-002")',
+                },
+                project_id: {
+                    type: 'number',
+                    description: 'Project ID (uses active project if not provided)',
+                },
+            },
+            required: ['item_id'],
+        },
+        execute: async (input) => {
+            try {
+                const projectId = input.project_id ?? ctx.currentProjectId;
+                if (!projectId) {
+                    return createErrorResult('No project specified and no active project. Use project_get or /projects to select a project first.');
+                }
+                const existingItem = await ctx.workItems.getByItemId(projectId, input.item_id);
+                if (!existingItem) {
+                    return createErrorResult(`Work item "${input.item_id}" not found in current project`);
+                }
+                const deleted = await ctx.workItems.delete(existingItem.id);
+                if (!deleted) {
+                    return createErrorResult(`Failed to delete work item "${input.item_id}"`);
+                }
+                return createSuccessResult({
+                    success: true,
+                    message: `Work item ${input.item_id} deleted`,
+                });
+            }
+            catch (error) {
+                return createErrorResult(`Failed to delete work item: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // workitem_status_counts
+    // ---------------------------------------------------------------------------
+    const workitemStatusCountsTool = defineTool({
+        name: 'workitem_status_counts',
+        description: 'Get counts of work items by status for the current project. Useful for showing progress.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_id: {
+                    type: 'number',
+                    description: 'Project ID (uses active project if not provided)',
+                },
+            },
+            required: [],
+        },
+        execute: async (input) => {
+            try {
+                const projectId = input.project_id ?? ctx.currentProjectId;
+                if (!projectId) {
+                    return createErrorResult('No project specified and no active project. Use project_get or /projects to select a project first.');
+                }
+                const counts = await ctx.workItems.getStatusCounts(projectId);
+                const total = counts.backlog + counts.in_progress + counts.completed + counts.skipped;
+                const progress = total > 0 ? Math.round((counts.completed / total) * 100) : 0;
+                return createSuccessResult({
+                    success: true,
+                    counts,
+                    total,
+                    progress,
+                    summary: `${String(counts.completed)}/${String(total)} completed (${String(progress)}%)`,
+                });
+            }
+            catch (error) {
+                return createErrorResult(`Failed to get status counts: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // workitem_advance_step
+    // ---------------------------------------------------------------------------
+    const workitemAdvanceStepTool = defineTool({
+        name: 'workitem_advance_step',
+        description: `Advance a work item to the next guided workflow step.\n` +
+            `Steps progress in order: ${STEP_ORDER.join(' → ')} → complete.\n` +
+            `Use this tool when the criteria for the current step are met.\n` +
+            `The agent should explicitly call this to advance - it provides visibility and audit trail.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                item_id: {
+                    type: 'string',
+                    description: 'Work item ID (e.g., "REQ-001", "BUG-002")',
+                },
+                reason: {
+                    type: 'string',
+                    description: 'Why the step criteria was met (shown to user for visibility)',
+                },
+                force: {
+                    type: 'boolean',
+                    description: 'Skip validation and force advance (e.g., user override after test failures)',
+                },
+                project_id: {
+                    type: 'number',
+                    description: 'Project ID (uses active project if not provided)',
+                },
+            },
+            required: ['item_id', 'reason'],
+        },
+        execute: async (input) => {
+            try {
+                const projectId = input.project_id ?? ctx.currentProjectId;
+                if (!projectId) {
+                    return createErrorResult('No project specified and no active project. Use project_get or /projects to select a project first.');
+                }
+                const item = await ctx.workItems.getByItemId(projectId, input.item_id);
+                if (!item) {
+                    return createErrorResult(`Work item "${input.item_id}" not found in current project`);
+                }
+                if (item.status !== 'in_progress') {
+                    return createErrorResult(`Work item "${input.item_id}" is not in progress (status: ${item.status}). ` +
+                        'Use workitem_update to set status to in_progress first.');
+                }
+                const currentStep = item.guidedStep;
+                const nextStep = getNextStep(currentStep);
+                // Check for valid transition (unless forced)
+                if (!input.force && currentStep !== null) {
+                    if (!isValidTransition(currentStep, nextStep)) {
+                        return createErrorResult(`Cannot advance from ${currentStep} to ${nextStep}. ` +
+                            `Valid next step: ${getNextStep(currentStep)}. ` +
+                            'Use force=true to override.');
+                    }
+                }
+                // Handle completion
+                if (nextStep === 'complete') {
+                    const updatedItem = await ctx.workItems.update(item.id, {
+                        status: 'completed',
+                        guided_step: null,
+                    });
+                    if (!updatedItem) {
+                        return createErrorResult('Failed to update work item');
+                    }
+                    hooks?.onWorkItemCompleted?.({
+                        id: updatedItem.id,
+                        itemId: updatedItem.itemId,
+                        title: updatedItem.title,
+                    });
+                    return createSuccessResult({
+                        success: true,
+                        item: {
+                            id: updatedItem.id,
+                            itemId: updatedItem.itemId,
+                            type: updatedItem.type,
+                            status: updatedItem.status,
+                            priority: updatedItem.priority,
+                            guidedStep: updatedItem.guidedStep,
+                            title: updatedItem.title,
+                            completedAt: updatedItem.completedAt?.toISOString(),
+                            commitHash: updatedItem.commitHash,
+                        },
+                        previous_step: currentStep,
+                        current_step: null,
+                        message: currentStep
+                            ? `✓ ${input.item_id}: ${formatStepDisplay(currentStep)} → COMPLETED`
+                            : `✓ ${input.item_id}: COMPLETED`,
+                        completed: true,
+                        reason: input.reason,
+                        next_action: 'Work item complete! Use workitem_next to pick the next item from backlog.',
+                    });
+                }
+                // Advance to next step
+                const nextGuidedStep = nextStep;
+                const updatedItem = await ctx.workItems.update(item.id, {
+                    guided_step: nextGuidedStep,
+                });
+                if (!updatedItem) {
+                    return createErrorResult('Failed to update work item');
+                }
+                const nextCriteria = getStepCriteria(nextGuidedStep);
+                return createSuccessResult({
+                    success: true,
+                    item: {
+                        id: updatedItem.id,
+                        itemId: updatedItem.itemId,
+                        type: updatedItem.type,
+                        status: updatedItem.status,
+                        priority: updatedItem.priority,
+                        guidedStep: updatedItem.guidedStep,
+                        title: updatedItem.title,
+                    },
+                    previous_step: currentStep,
+                    current_step: nextGuidedStep,
+                    message: currentStep
+                        ? `✓ ${input.item_id}: ${formatStepDisplay(currentStep)} → ${formatStepDisplay(nextGuidedStep)}`
+                        : `✓ ${input.item_id}: Starting ${formatStepDisplay(nextGuidedStep)}`,
+                    completed: false,
+                    reason: input.reason,
+                    next_action: nextCriteria.nextActionHint,
+                    exit_criteria: nextCriteria.exitCriteria,
+                });
+            }
+            catch (error) {
+                return createErrorResult(`Failed to advance step: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // workitem_claim
+    // ---------------------------------------------------------------------------
+    const workitemClaimTool = defineTool({
+        name: 'workitem_claim',
+        description: 'Claim an unassigned PERSISTENT work item from project backlog. ' +
+            'For session todos in footer, use todo_claim.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                item_id: {
+                    type: 'string',
+                    description: 'Work item ID (e.g., "REQ-001", "BUG-002")',
+                },
+                agent_id: {
+                    type: 'string',
+                    description: 'The agent ID claiming the work item',
+                },
+                project_id: {
+                    type: 'number',
+                    description: 'Project ID (uses active project if not provided)',
+                },
+            },
+            required: ['item_id', 'agent_id'],
+        },
+        execute: async (input) => {
+            try {
+                const projectId = input.project_id ?? ctx.currentProjectId;
+                if (!projectId) {
+                    return createErrorResult('No project specified and no active project.');
+                }
+                const existingItem = await ctx.workItems.getByItemId(projectId, input.item_id);
+                if (!existingItem) {
+                    return createErrorResult(`Work item "${input.item_id}" not found in current project`);
+                }
+                if (existingItem.owner) {
+                    return createErrorResult(`Work item "${input.item_id}" is already owned by "${existingItem.owner}". Use workitem_handoff to transfer ownership.`);
+                }
+                const item = await ctx.workItems.update(existingItem.id, {
+                    owner: input.agent_id,
+                });
+                if (!item) {
+                    return createErrorResult(`Failed to claim work item "${input.item_id}"`);
+                }
+                return createSuccessResult({
+                    success: true,
+                    message: `Work item ${item.itemId} claimed by ${input.agent_id}`,
+                    item: {
+                        id: item.id,
+                        itemId: item.itemId,
+                        type: item.type,
+                        status: item.status,
+                        priority: item.priority,
+                        owner: item.owner,
+                        title: item.title,
+                    },
+                });
+            }
+            catch (error) {
+                return createErrorResult(`Failed to claim work item: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    // ---------------------------------------------------------------------------
+    // workitem_handoff
+    // ---------------------------------------------------------------------------
+    const workitemHandoffTool = defineTool({
+        name: 'workitem_handoff',
+        description: 'Hand off a PERSISTENT work item (from project backlog) to another agent. ' +
+            'For session todos in footer, use todo_handoff.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                item_id: {
+                    type: 'string',
+                    description: 'Work item ID (e.g., "REQ-001", "BUG-002")',
+                },
+                to_agent_id: {
+                    type: 'string',
+                    description: 'The agent ID to hand off to',
+                },
+                notes: {
+                    type: 'string',
+                    description: 'Optional notes about the handoff (context, status, blockers)',
+                },
+                project_id: {
+                    type: 'number',
+                    description: 'Project ID (uses active project if not provided)',
+                },
+            },
+            required: ['item_id', 'to_agent_id'],
+        },
+        execute: async (input) => {
+            try {
+                const projectId = input.project_id ?? ctx.currentProjectId;
+                if (!projectId) {
+                    return createErrorResult('No project specified and no active project.');
+                }
+                const existingItem = await ctx.workItems.getByItemId(projectId, input.item_id);
+                if (!existingItem) {
+                    return createErrorResult(`Work item "${input.item_id}" not found in current project`);
+                }
+                const previousOwner = existingItem.owner;
+                const item = await ctx.workItems.update(existingItem.id, {
+                    owner: input.to_agent_id,
+                });
+                if (!item) {
+                    return createErrorResult(`Failed to hand off work item "${input.item_id}"`);
+                }
+                return createSuccessResult({
+                    success: true,
+                    message: `Work item ${item.itemId} handed off from "${previousOwner ?? 'unassigned'}" to "${input.to_agent_id}"`,
+                    item: {
+                        id: item.id,
+                        itemId: item.itemId,
+                        type: item.type,
+                        status: item.status,
+                        priority: item.priority,
+                        owner: item.owner,
+                        title: item.title,
+                    },
+                    previousOwner,
+                    notes: input.notes,
+                });
+            }
+            catch (error) {
+                return createErrorResult(`Failed to hand off work item: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        },
+    });
+    return [
+        workitemQueryTool,
+        workitemAddTool,
+        workitemUpdateTool,
+        workitemNextTool,
+        workitemDeleteTool,
+        workitemStatusCountsTool,
+        workitemAdvanceStepTool,
+        workitemClaimTool,
+        workitemHandoffTool,
+    ];
+}