@compilr-dev/cli 0.5.0 → 0.5.2

package/dist/tools/delegate.js

@@ -0,0 +1,97 @@
+/**
+ * Delegate Tool - Multi-Agent Task Delegation
+ *
+ * Allows the coordinator to delegate tasks to specialist agents.
+ * Only available to the coordinator (default agent).
+ *
+ * Flow:
+ * 1. Coordinator calls delegate(agentId, task, reason?)
+ * 2. CLI shows approval prompt
+ * 3. If approved: auto-switch to specialist, inject task
+ * 4. If denied: return "User declined" to coordinator
+ */
+import { defineTool } from '@compilr-dev/sdk';
+import { getDelegateHandler } from '../shared-handlers.js';
+// =============================================================================
+// Tool Definition
+// =============================================================================
+export const delegateTool = defineTool({
+    name: 'delegate',
+    description: 'Hand off the conversation to a specialist (foreground switch). ' +
+        'You stop working and the specialist takes over. No status tracking. ' +
+        'Use delegate_background instead if you want to continue working while ' +
+        'the specialist runs in the background (with delegation tracking). ' +
+        'Only available to the coordinator.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            agentId: {
+                type: 'string',
+                description: 'Target agent ID (e.g., "arch", "dev", "qa")',
+            },
+            task: {
+                type: 'string',
+                description: 'Task description for the specialist - be specific and clear',
+            },
+            reason: {
+                type: 'string',
+                description: 'Why this specialist is suited for the task (shown to user)',
+            },
+        },
+        required: ['agentId', 'task'],
+    },
+    execute: async (input) => {
+        try {
+            // Validate input
+            if (!input.agentId || input.agentId.trim().length === 0) {
+                return {
+                    success: false,
+                    error: 'Agent ID is required',
+                };
+            }
+            if (!input.task || input.task.trim().length === 0) {
+                return {
+                    success: false,
+                    error: 'Task description is required',
+                };
+            }
+            // Get the delegate handler from shared-handlers
+            const delegateHandler = getDelegateHandler();
+            if (!delegateHandler) {
+                return {
+                    success: false,
+                    error: 'Delegate handler not initialized. ' +
+                        'This tool requires multi-agent mode with coordinator role.',
+                };
+            }
+            // Execute delegation (shows approval prompt, switches if approved)
+            const result = await delegateHandler({
+                agentId: input.agentId.trim(),
+                task: input.task.trim(),
+                reason: input.reason?.trim(),
+            });
+            if (result.error) {
+                return {
+                    success: false,
+                    error: result.error,
+                };
+            }
+            const output = {
+                delegated: result.success,
+                message: result.declined
+                    ? 'User declined the delegation. Continue handling the task yourself.'
+                    : `Task delegated to $${input.agentId}. They will handle it from here.`,
+            };
+            return {
+                success: true,
+                result: output,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: `Delegation failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    },
+});

package/dist/tools/delegation-status.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Delegation Status Tool - Coordinator Mode
+ *
+ * Read-only tool for the coordinator to query delegation progress.
+ * Queries the DelegationTracker singleton and returns formatted status.
+ */
+interface DelegationStatusInput {
+    /** Specific delegation ID (e.g., "del_abc12345") */
+    delegation_id?: string;
+    /** Filter by target agent (e.g., "dev") */
+    agent_id?: string;
+    /** Filter by status: active (pending+running), completed, failed, all. Default: active */
+    status?: 'active' | 'completed' | 'failed' | 'all';
+}
+export declare const delegationStatusTool: import("@compilr-dev/sdk").Tool<DelegationStatusInput>;
+export {};

package/dist/tools/delegation-status.js

@@ -0,0 +1,128 @@
+/**
+ * Delegation Status Tool - Coordinator Mode
+ *
+ * Read-only tool for the coordinator to query delegation progress.
+ * Queries the DelegationTracker singleton and returns formatted status.
+ */
+import { defineTool } from '@compilr-dev/sdk';
+import { getDelegationTracker } from '../multi-agent/delegation-tracker.js';
+// =============================================================================
+// Helpers
+// =============================================================================
+function formatDuration(from, to) {
+    const endTime = to ?? new Date();
+    const ms = endTime.getTime() - from.getTime();
+    const seconds = Math.floor(ms / 1000);
+    const minutes = Math.floor(seconds / 60);
+    const hours = Math.floor(minutes / 60);
+    if (hours > 0) {
+        return `${String(hours)}h ${String(minutes % 60)}m`;
+    }
+    else if (minutes > 0) {
+        return `${String(minutes)}m ${String(seconds % 60)}s`;
+    }
+    else {
+        return `${String(seconds)}s`;
+    }
+}
+function formatDelegation(d) {
+    const entry = {
+        id: d.id,
+        targetAgent: d.targetAgentId,
+        task: d.task.length > 100 ? d.task.slice(0, 100) + '...' : d.task,
+        status: d.status,
+        duration: formatDuration(d.createdAt, d.completedAt),
+    };
+    if (d.todoIndex !== undefined) {
+        entry.todoIndex = d.todoIndex;
+    }
+    if (d.result) {
+        entry.result = {
+            success: d.result.success,
+            summary: d.result.summary,
+            artifactIds: d.result.artifactIds,
+            ...(d.result.error ? { error: d.result.error } : {}),
+        };
+    }
+    return entry;
+}
+// =============================================================================
+// Tool Definition
+// =============================================================================
+export const delegationStatusTool = defineTool({
+    name: 'delegation_status',
+    description: 'Query the status of tasks delegated via delegate_background. ' +
+        'Returns active delegations by default (pending and running). ' +
+        'Use delegation_id for a specific delegation, agent_id to filter by agent, ' +
+        'or status to see completed/failed/all delegations. ' +
+        'Note: Only tracks delegate_background calls, not foreground delegate.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            delegation_id: {
+                type: 'string',
+                description: 'Specific delegation ID (e.g., "del_abc12345")',
+            },
+            agent_id: {
+                type: 'string',
+                description: 'Filter by target agent (e.g., "dev", "arch")',
+            },
+            status: {
+                type: 'string',
+                enum: ['active', 'completed', 'failed', 'all'],
+                description: 'Filter by status. Default: "active" (pending + running)',
+            },
+        },
+    },
+    execute: async (input) => {
+        const tracker = await Promise.resolve(getDelegationTracker());
+        // Single delegation lookup
+        if (input.delegation_id) {
+            const delegation = tracker.get(input.delegation_id);
+            if (!delegation) {
+                return {
+                    success: false,
+                    error: `Delegation ${input.delegation_id} not found`,
+                };
+            }
+            return {
+                success: true,
+                result: {
+                    delegations: [formatDelegation(delegation)],
+                    stats: tracker.getStats(),
+                },
+            };
+        }
+        // Get all delegations then filter
+        let delegations;
+        if (input.agent_id) {
+            delegations = tracker.getByAgent(input.agent_id);
+        }
+        else {
+            delegations = tracker.getAll();
+        }
+        // Apply status filter
+        const filter = input.status ?? 'active';
+        if (filter !== 'all') {
+            delegations = delegations.filter((d) => {
+                switch (filter) {
+                    case 'active':
+                        return d.status === 'pending' || d.status === 'running';
+                    case 'completed':
+                        return d.status === 'completed';
+                    case 'failed':
+                        return d.status === 'failed';
+                    default:
+                        return true;
+                }
+            });
+        }
+        return {
+            success: true,
+            result: {
+                delegations: delegations.map(formatDelegation),
+                stats: tracker.getStats(),
+            },
+        };
+    },
+});

package/dist/tools/guide-tool.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Compilr Guide Tool
+ *
+ * Provides documentation about the CLI for the AI agent.
+ * The agent can call this tool to answer user questions about how to use the CLI.
+ */
+interface GuideInput {
+    query?: string;
+    list_topics?: boolean;
+}
+export declare const guideTool: import("@compilr-dev/sdk").Tool<GuideInput>;
+export {};

package/dist/tools/guide-tool.js

@@ -0,0 +1,59 @@
+/**
+ * Compilr Guide Tool
+ *
+ * Provides documentation about the CLI for the AI agent.
+ * The agent can call this tool to answer user questions about how to use the CLI.
+ */
+import { defineTool } from '@compilr-dev/sdk';
+import { searchGuide, getGuideTopics } from '../guide/index.js';
+export const guideTool = defineTool({
+    name: 'compilr_guide',
+    description: 'Get documentation about Compilr Dev CLI features and commands. ' +
+        'Use this to answer user questions about how to use the CLI. ' +
+        'Query by topic (e.g., "creating-project", "team-agents") or command (e.g., "/design", "/backlog").',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            query: {
+                type: 'string',
+                description: 'Topic or command to look up. Examples: "creating-project", "/design", "team-agents", "workflow"',
+            },
+            list_topics: {
+                type: 'boolean',
+                description: 'Set to true to list all available topics',
+            },
+        },
+    },
+    execute: (input) => {
+        if (input.list_topics) {
+            const topics = getGuideTopics();
+            return Promise.resolve({
+                success: true,
+                result: { output: `Available guide topics:\n\n${topics.map(t => `- ${t}`).join('\n')}` },
+            });
+        }
+        if (!input.query) {
+            return Promise.resolve({
+                success: true,
+                result: { output: 'Please provide a query (topic or command) or set list_topics=true to see all topics.' },
+            });
+        }
+        const results = searchGuide(input.query);
+        if (results.length === 0) {
+            const topics = getGuideTopics();
+            return Promise.resolve({
+                success: true,
+                result: { output: `No guide found for "${input.query}".\n\nAvailable topics:\n${topics.map(t => `- ${t}`).join('\n')}` },
+            });
+        }
+        // Format results
+        const formatted = results
+            .map((entry) => `## ${entry.title}\n\n${entry.content}\n`)
+            .join('\n---\n\n');
+        return Promise.resolve({
+            success: true,
+            result: { output: formatted },
+        });
+    },
+    silent: true,
+});

package/dist/tools/handoff.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Handoff Tool - Multi-Agent Task Handoff
+ *
+ * Allows any agent to hand off the current task to another agent.
+ * Available to all agents (specialists and coordinator).
+ *
+ * Flow:
+ * 1. Agent calls handoff(agentId, task, reason?)
+ * 2. CLI shows approval prompt (unless auto-approve is enabled)
+ * 3. If approved: auto-switch to target agent, inject task
+ * 4. If denied: return "User declined" to current agent
+ *
+ * One-hop rule: If this agent was itself handed a task, it cannot
+ * re-hand it off (except back to the coordinator/default).
+ */
+interface HandoffInput {
+    /** Target agent ID (e.g., 'arch', 'dev', 'qa', 'default') */
+    agentId: string;
+    /** Task description for the target agent */
+    task: string;
+    /** Optional reason for handoff (shown to user for context) */
+    reason?: string;
+}
+export declare const handoffTool: import("@compilr-dev/sdk").Tool<HandoffInput>;
+export {};

package/dist/tools/handoff.js

@@ -0,0 +1,99 @@
+/**
+ * Handoff Tool - Multi-Agent Task Handoff
+ *
+ * Allows any agent to hand off the current task to another agent.
+ * Available to all agents (specialists and coordinator).
+ *
+ * Flow:
+ * 1. Agent calls handoff(agentId, task, reason?)
+ * 2. CLI shows approval prompt (unless auto-approve is enabled)
+ * 3. If approved: auto-switch to target agent, inject task
+ * 4. If denied: return "User declined" to current agent
+ *
+ * One-hop rule: If this agent was itself handed a task, it cannot
+ * re-hand it off (except back to the coordinator/default).
+ */
+import { defineTool } from '@compilr-dev/sdk';
+import { getHandoffHandler } from '../shared-handlers.js';
+// =============================================================================
+// Tool Definition
+// =============================================================================
+export const handoffTool = defineTool({
+    name: 'handoff',
+    description: 'Hand off the current task to another team agent. ' +
+        'Use this when a task is outside your expertise or would benefit from another specialist. ' +
+        'The user will be asked to approve the handoff before switching. ' +
+        'Example: hand off architecture questions to $arch, implementation to $dev, testing to $qa.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            agentId: {
+                type: 'string',
+                description: 'Target agent ID (e.g., "arch", "dev", "qa", "default")',
+            },
+            task: {
+                type: 'string',
+                description: 'Task description for the target agent - be specific and clear',
+            },
+            reason: {
+                type: 'string',
+                description: 'Why this agent is better suited for the task (shown to user)',
+            },
+        },
+        required: ['agentId', 'task'],
+    },
+    execute: async (input) => {
+        try {
+            // Validate input
+            if (!input.agentId || input.agentId.trim().length === 0) {
+                return {
+                    success: false,
+                    error: 'Agent ID is required',
+                };
+            }
+            if (!input.task || input.task.trim().length === 0) {
+                return {
+                    success: false,
+                    error: 'Task description is required',
+                };
+            }
+            // Get the handoff handler from shared-handlers
+            const handoffHandler = getHandoffHandler();
+            if (!handoffHandler) {
+                return {
+                    success: false,
+                    error: 'Handoff handler not initialized. ' +
+                        'This tool requires multi-agent mode with a team.',
+                };
+            }
+            // Execute handoff (shows approval prompt, switches if approved)
+            const result = await handoffHandler({
+                agentId: input.agentId.trim(),
+                task: input.task.trim(),
+                reason: input.reason?.trim(),
+            });
+            if (result.error) {
+                return {
+                    success: false,
+                    error: result.error,
+                };
+            }
+            const output = {
+                handedOff: result.success,
+                message: result.declined
+                    ? 'User declined the handoff. Continue handling the task yourself.'
+                    : `Task handed off to $${input.agentId}. They will handle it from here.`,
+            };
+            return {
+                success: true,
+                result: output,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: `Handoff failed: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    },
+});

package/dist/tools/meta-tools.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Meta-Tools for Dynamic Tool Loading
+ *
+ * Thin singleton wrapper over @compilr-dev/sdk's MetaToolsRegistry.
+ * Provides the same module-level API used by the CLI while delegating
+ * all logic to the SDK's class-based implementation.
+ *
+ * Instead of declaring all 49 tools (~15K tokens), we declare:
+ * 1. A small set of "direct" tools (always available)
+ * 2. A get_tool_info meta-tool (always available)
+ * 3. A tool index in the system prompt
+ * 4. A transparent fallback handler that routes calls to the registry
+ */
+import { type Tool, type ToolExecutionResult } from '@compilr-dev/sdk';
+export declare function setMetaToolFilter(filter: string[] | null | undefined): void;
+export declare function getMetaToolFilter(): Set<string> | null;
+export declare function initializeMetaToolRegistry(tools: Tool[]): void;
+export declare function getRegisteredMetaTools(): Tool[];
+export declare function getMetaToolCount(): number;
+export declare function generateToolIndex(): string;
+export declare const listToolsTool: Tool<object>;
+export declare const getToolInfoTool: Tool<object>;
+export declare const useToolTool: Tool<object>;
+export declare const metaTools: Tool<object>[];
+export declare function createMetaToolFallback(): (name: string, input: Record<string, unknown>) => Promise<ToolExecutionResult | null>;
+export declare const META_TOOLS_SYSTEM_PROMPT_PREFIX = "\n## Tool Index (Specialized Tools)\n\nThese tools are called **exactly like direct tools** \u2014 just use the tool name with parameters. No special syntax or wrapper needed. The system routes them automatically.\n\n**IMPORTANT \u2014 These are CLI system tools, NOT your project's backend. Never use localhost/curl to access them.**\n\n**Parameter Rules:**\n- For **zero-parameter calls**: call the tool directly (e.g., `workitem_query()`, `git_status()`).\n- For **calls WITH parameters**: you MUST call `get_tool_info(\"tool_name\")` first to get parameter details. The signatures below are summaries only \u2014 do NOT guess parameter structure from them.\n- After a failed tool call, always call `get_tool_info()` before retrying.\n\n";

package/dist/tools/meta-tools.js

@@ -0,0 +1,47 @@
+/**
+ * Meta-Tools for Dynamic Tool Loading
+ *
+ * Thin singleton wrapper over @compilr-dev/sdk's MetaToolsRegistry.
+ * Provides the same module-level API used by the CLI while delegating
+ * all logic to the SDK's class-based implementation.
+ *
+ * Instead of declaring all 49 tools (~15K tokens), we declare:
+ * 1. A small set of "direct" tools (always available)
+ * 2. A get_tool_info meta-tool (always available)
+ * 3. A tool index in the system prompt
+ * 4. A transparent fallback handler that routes calls to the registry
+ */
+import { MetaToolsRegistry, createMetaTools, META_TOOLS_SYSTEM_PROMPT_PREFIX as SDK_META_TOOLS_SYSTEM_PROMPT_PREFIX, } from '@compilr-dev/sdk';
+// Singleton registry for the CLI process
+const registry = new MetaToolsRegistry();
+const metaToolSet = createMetaTools(registry);
+// =============================================================================
+// Module-level API (same signatures as before)
+// =============================================================================
+export function setMetaToolFilter(filter) {
+    registry.setFilter(filter);
+}
+export function getMetaToolFilter() {
+    return registry.getFilter();
+}
+export function initializeMetaToolRegistry(tools) {
+    registry.initialize(tools);
+}
+export function getRegisteredMetaTools() {
+    return registry.getRegisteredTools();
+}
+export function getMetaToolCount() {
+    return registry.getToolCount();
+}
+export function generateToolIndex() {
+    return registry.generateToolIndex();
+}
+// Re-export tool instances
+export const listToolsTool = metaToolSet.listToolsTool;
+export const getToolInfoTool = metaToolSet.getToolInfoTool;
+export const useToolTool = metaToolSet.useToolTool;
+export const metaTools = [listToolsTool, getToolInfoTool, useToolTool];
+export function createMetaToolFallback() {
+    return metaToolSet.createFallback();
+}
+export const META_TOOLS_SYSTEM_PROMPT_PREFIX = SDK_META_TOOLS_SYSTEM_PROMPT_PREFIX;

package/dist/tools/platform-adapter.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Platform Adapter
+ *
+ * Thin adapter that wraps the CLI's synchronous repositories and services as async
+ * implementations of the SDK's platform interfaces, wires CLI-specific hooks,
+ * and delegates all 32 platform tool definitions to the SDK.
+ *
+ * This replaces ~2,900+ lines of duplicated tool logic that previously lived in:
+ * - project-db.ts (4 tools)
+ * - workitem-db.ts (9 tools)
+ * - document-db.ts (4 tools)
+ * - plan-tools.ts (5 tools)
+ * - backlog-wrappers.ts (2 tools)
+ * - anchor-tools.ts (3 tools)
+ * - artifact-tools.ts (4 tools)
+ * - recall-work-tool.ts (1 tool)
+ */
+/**
+ * All 32 platform tools from the SDK:
+ * - 4 project tools (project_get, project_create, project_update, project_list)
+ * - 9 workitem tools (query, add, update, next, delete, status_counts, advance_step, claim, handoff)
+ * - 4 document tools (add, get, list, delete)
+ * - 5 plan tools (create, update, get, list, delete)
+ * - 2 backlog tools (backlog_read, backlog_write)
+ * - 3 anchor tools (anchor_add, anchor_remove, anchor_list)
+ * - 4 artifact tools (artifact_save, artifact_get, artifact_list, artifact_delete)
+ * - 1 episode tool (recall_work)
+ */
+export declare const allPlatformTools: import("@compilr-dev/sdk").Tool<never>[];
+/**
+ * All 5 factory tools from @compilr-dev/factory:
+ * - 3 model tools (app_model_get, app_model_update, app_model_validate)
+ * - 2 factory tools (factory_scaffold, factory_list_toolkits)
+ */
+export declare const allFactoryTools: import("@compilr-dev/sdk").Tool<never>[];