@compilr-dev/cli 0.5.0 → 0.5.1

package/dist/tools/workitem-db.js

@@ -3,16 +3,20 @@
  *
  * Tools for managing work items (backlog items, tasks, bugs) in the database.
  */
-import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/agents';
+import { defineTool, createSuccessResult, createErrorResult } from '@compilr-dev/sdk';
 import { workItemRepository } from '../db/repositories/index.js';
 import { getActiveProject } from './project-db.js';
 import { getNextStep, isValidTransition, getStepCriteria, formatStepDisplay, STEP_ORDER, } from '../workflow/index.js';
+import { awardWorkItemCompletion } from '../games/coins.js';
+import { getActiveSharedContext } from '../multi-agent/activity.js';
 /**
  * workitem_query - Query work items with filters
  */
 export const workitemQueryTool = defineTool({
     name: 'workitem_query',
-    description: 'Query work items from the backlog. Supports filtering by status, type, priority, and search. Returns paginated results.',
+    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: {
@@ -35,6 +39,10 @@ export const workitemQueryTool = defineTool({
                 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',
@@ -57,11 +65,30 @@ export const workitemQueryTool = defineTool({
             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
+            // TODO(Phase 3): This uses the FOREGROUND agent's ID from SharedContext.
+            // When background agents are implemented, each agent session needs its own
+            // identity. The tool execution context should include the caller's agent ID,
+            // so background agents can correctly resolve "self" to their own ID.
+            // See: background-agents-spec.md - Tool Execution Context section
+            let resolvedOwner = input.owner;
+            if (input.owner === 'self') {
+                const sharedContext = getActiveSharedContext();
+                const activeAgent = sharedContext?.getTeam().activeAgent;
+                if (activeAgent && activeAgent !== 'default') {
+                    resolvedOwner = activeAgent;
+                }
+                else {
+                    // No active team agent, treat as "all" or return empty
+                    resolvedOwner = 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,
@@ -73,6 +100,7 @@ export const workitemQueryTool = defineTool({
                 type: item.type,
                 status: item.status,
                 priority: item.priority,
+                owner: item.owner,
                 guidedStep: item.guidedStep,
                 title: item.title,
                 description: item.description,
@@ -99,7 +127,8 @@ export const workitemQueryTool = defineTool({
  */
 export const workitemAddTool = defineTool({
     name: 'workitem_add',
-    description: 'Add a new work item (feature, bug, tech-debt, or chore) to the backlog.',
+    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: {
@@ -130,6 +159,10 @@ export const workitemAddTool = defineTool({
                 enum: ['low', 'medium', 'high'],
                 description: 'Estimated effort',
             },
+            owner: {
+                type: 'string',
+                description: 'Owner agent ID (e.g., "dev", "pm", "arch"). Omit for unassigned.',
+            },
         },
         required: ['type', 'title'],
     },
@@ -147,17 +180,19 @@ export const workitemAddTool = defineTool({
                 description: input.description,
                 priority: input.priority,
                 estimated_effort: input.estimated_effort,
+                owner: input.owner,
             };
             const item = workItemRepository.create(createInput);
             return createSuccessResult({
                 success: true,
-                message: `Work item ${item.itemId} created: "${item.title}"`,
+                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,
                 },
             });
@@ -172,7 +207,8 @@ export const workitemAddTool = defineTool({
  */
 export const workitemUpdateTool = defineTool({
     name: 'workitem_update',
-    description: 'Update an existing work item. Can update status, priority, title, description, guided step, and more.',
+    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: {
@@ -194,6 +230,10 @@ export const workitemUpdateTool = defineTool({
                 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'],
@@ -231,6 +271,10 @@ export const workitemUpdateTool = defineTool({
                 updateInput.status = input.status;
             if (input.priority)
                 updateInput.priority = input.priority;
+            if (input.owner !== undefined) {
+                // Empty string means unassign
+                updateInput.owner = input.owner === '' ? null : input.owner;
+            }
             if (input.guided_step !== undefined)
                 updateInput.guided_step = input.guided_step;
             if (input.title)
@@ -243,6 +287,10 @@ export const workitemUpdateTool = defineTool({
             if (!item) {
                 return createErrorResult(`Failed to update work item "${input.item_id}"`);
             }
+            // Award coin if work item was just completed
+            if (input.status === 'completed' && existingItem.status !== 'completed') {
+                awardWorkItemCompletion();
+            }
             return createSuccessResult({
                 success: true,
                 message: `Work item ${item.itemId} updated`,
@@ -252,6 +300,7 @@ export const workitemUpdateTool = defineTool({
                     type: item.type,
                     status: item.status,
                     priority: item.priority,
+                    owner: item.owner,
                     guidedStep: item.guidedStep,
                     title: item.title,
                     completedAt: item.completedAt?.toISOString(),
@@ -474,6 +523,8 @@ The agent should explicitly call this to advance - it provides visibility and au
                 if (!updatedItem) {
                     return createErrorResult('Failed to update work item');
                 }
+                // Award coin for completing work item
+                awardWorkItemCompletion();
                 return createSuccessResult({
                     success: true,
                     item: {
@@ -535,6 +586,134 @@ The agent should explicitly call this to advance - it provides visibility and au
         }
     },
 });
+/**
+ * workitem_claim - Claim an unassigned work item
+ */
+export 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) => {
+        await Promise.resolve();
+        try {
+            const projectId = input.project_id || getActiveProject()?.id;
+            if (!projectId) {
+                return createErrorResult('No project specified and no active project.');
+            }
+            const existingItem = workItemRepository.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 = workItemRepository.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 - Hand off a work item to another agent
+ */
+export 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) => {
+        await Promise.resolve();
+        try {
+            const projectId = input.project_id || getActiveProject()?.id;
+            if (!projectId) {
+                return createErrorResult('No project specified and no active project.');
+            }
+            const existingItem = workItemRepository.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 = workItemRepository.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)}`);
+        }
+    },
+});
 /**
  * All work item tools
  */
@@ -546,4 +725,6 @@ export const workitemDbTools = [
     workitemDeleteTool,
     workitemStatusCountsTool,
     workitemAdvanceStepTool,
+    workitemClaimTool,
+    workitemHandoffTool,
 ];

package/dist/tools.d.ts

@@ -1,15 +1,80 @@
 /**
  * Tool Registry Setup
  *
- * Configures all available tools from @compilr-dev/agents
- * and @compilr-dev/agents-coding packages.
+ * Configures all available tools from @compilr-dev/sdk
+ * (which re-exports from @compilr-dev/agents and @compilr-dev/agents-coding).
+ *
+ * ARCHITECTURE (Meta-Tools):
+ * - DIRECT TOOLS: Always available, called by name (most common operations)
+ * - META-REGISTRY TOOLS: Available via use_tool() (specialized operations)
+ *
+ * This reduces token overhead from ~15K to ~2K per request.
+ *
+ * SINGLE SOURCE OF TRUTH:
+ * Tool names are defined in tool-names.ts (a dependency-free module).
+ * This file re-exports them for convenience. Import from here or tool-names.ts.
  */
+export { TOOL_NAMES, type ToolName, DIRECT_TOOL_NAMES, META_TOOL_NAMES, META_REGISTRY_TOOL_NAMES, getAllToolNames, } from './tool-names.js';
+import { TodoStore, type Tool } from '@compilr-dev/sdk';
+export declare const todoStore: TodoStore;
+import { setMetaToolFilter, getRegisteredMetaTools } from './tools/meta-tools.js';
+export { setMetaToolFilter, getRegisteredMetaTools };
 /**
  * Creates the tool registry with all available tools.
  * Returns tools as-is - the Agent.registerTools() method handles typing.
+ *
+ * @deprecated Use createDirectToolRegistry() + initializeMetaTools() instead
  */
 export declare function createToolRegistry(): unknown[];
 /**
  * Returns a minimal set of tools for basic testing.
  */
 export declare function createMinimalToolRegistry(): unknown[];
+/**
+ * Get direct tools that are always available.
+ * These are declared normally and can be called by name.
+ */
+export declare function getDirectTools(): Tool[];
+/**
+ * Get meta-tools for agent registration.
+ * Only get_tool_info is kept as a direct tool — use_tool and list_tools
+ * are no longer needed since the fallback handler routes calls transparently.
+ */
+export declare function getMetaTools(): Tool[];
+/**
+ * Create a fallback handler for the tool registry.
+ * When the agent calls a tool not in the direct registry, this handler
+ * checks the meta-registry and executes it transparently.
+ */
+export declare function createToolFallback(): (name: string, input: Record<string, unknown>) => Promise<import('@compilr-dev/sdk').ToolExecutionResult | null>;
+/**
+ * Initialize the meta-tool registry with specialized tools.
+ * Call this once at startup.
+ */
+export declare function initializeMetaTools(): void;
+/**
+ * Get the tool index for the system prompt.
+ * This lists all meta-registry tools with their signatures.
+ */
+export declare function getToolIndexForSystemPrompt(): string;
+/**
+ * Get count of meta-registry tools.
+ */
+export declare function getMetaToolsCount(): number;
+/**
+ * Check if meta-tools mode is enabled.
+ * Returns true if the meta-tool registry has been initialized.
+ */
+export declare function isMetaToolsEnabled(): boolean;
+/**
+ * Get tool statistics for debugging/display.
+ */
+export declare function getToolStats(): {
+    directTools: number;
+    metaRegistryTools: number;
+    totalTools: number;
+    estimatedDirectTokens: number;
+    estimatedMetaTokens: number;
+    estimatedLegacyTokens: number;
+    tokenSavings: number;
+};