@vibescope/mcp-server 0.2.8 → 0.3.0

package/dist/api-client.js

@@ -67,6 +67,11 @@ export class VibescopeApiClient {
             session_id: sessionId
         });
     }
+    async signalIdle(sessionId) {
+        return this.request('POST', '/api/mcp/sessions/idle', {
+            session_id: sessionId
+        });
+    }
     // Project endpoints
     async listProjects() {
         return this.request('GET', '/api/mcp/projects');
@@ -182,6 +187,35 @@ export class VibescopeApiClient {
     async deleteTask(taskId) {
         return this.request('DELETE', `/api/mcp/tasks/${taskId}`);
     }
+    /**
+     * Release a task back to pending status.
+     * Clears session assignment, git branch, and worktree info.
+     */
+    async releaseTask(taskId, params) {
+        return this.proxy('release_task', {
+            task_id: taskId,
+            reason: params?.reason,
+        }, params?.session_id ? {
+            session_id: params.session_id,
+            persona: null,
+            instance_id: '',
+        } : undefined);
+    }
+    /**
+     * Cancel a task with an optional reason.
+     * Task remains visible with cancelled status for historical tracking.
+     */
+    async cancelTask(taskId, params) {
+        return this.proxy('cancel_task', {
+            task_id: taskId,
+            cancelled_reason: params?.cancelled_reason,
+            cancellation_note: params?.cancellation_note,
+        }, params?.session_id ? {
+            session_id: params.session_id,
+            persona: null,
+            instance_id: '',
+        } : undefined);
+    }
     // Progress endpoints
     async logProgress(projectId, params) {
         return this.request('POST', `/api/mcp/projects/${projectId}/progress`, params);

package/dist/cli.d.ts

@@ -27,6 +27,6 @@ export interface VerificationResult {
         session_duration_minutes: number | null;
     };
 }
-export declare function normalizeGitUrl(url: string): string;
+export { normalizeGitUrl } from './utils.js';
 export declare function detectGitUrl(): string | null;
 export declare function verify(gitUrl?: string, projectId?: string): Promise<VerificationResult>;

package/dist/cli.js

@@ -13,6 +13,7 @@
  */
 import { execSync } from 'child_process';
 import { runSetup } from './setup.js';
+import { normalizeGitUrl as normalizeGitUrlFn } from './utils.js';
 // ============================================================================
 // Configuration (read at runtime for testability)
 // ============================================================================
@@ -25,17 +26,8 @@ function getApiUrl() {
 // ============================================================================
 // Git URL Detection
 // ============================================================================
-export function normalizeGitUrl(url) {
-    // Remove .git suffix
-    let normalized = url.replace(/\.git$/, '');
-    // Convert SSH to HTTPS format
-    if (normalized.startsWith('git@')) {
-        normalized = normalized
-            .replace(/^git@/, 'https://')
-            .replace(/:([^/])/, '/$1');
-    }
-    return normalized;
-}
+// Re-export normalizeGitUrl from utils for backwards compatibility with tests
+export { normalizeGitUrl } from './utils.js';
 export function detectGitUrl() {
     try {
         const url = execSync('git config --get remote.origin.url', {
@@ -43,7 +35,7 @@ export function detectGitUrl() {
             timeout: 5000,
             stdio: ['pipe', 'pipe', 'pipe'],
         }).trim();
-        return normalizeGitUrl(url);
+        return normalizeGitUrlFn(url);
     }
     catch {
         return null;
@@ -124,32 +116,32 @@ async function main() {
         }
     }
     else if (command === 'help' || command === '--help' || command === '-h') {
-        console.log(`
-Vibescope CLI - Setup wizard and enforcement verification tool
-
-Usage:
-  vibescope-cli setup                 Interactive setup wizard for your IDE
-  vibescope-cli verify [options]      Check Vibescope compliance before exit
-
-Setup:
-  Configures Vibescope MCP integration for:
-  - Claude Code (CLI)
-  - Claude Desktop
-  - Cursor
-  - Gemini CLI
-
-Verify Options:
-  --git-url <url>       Git repository URL (auto-detected if not provided)
-  --project-id <id>     Vibescope project UUID
-
-Exit Codes (verify):
-  0  Compliant - agent can exit
-  1  Non-compliant - agent should continue work
-  2  Error - allow exit with warning
-
-Environment Variables:
-  VIBESCOPE_API_KEY       Required for verify - Your Vibescope API key
-  VIBESCOPE_API_URL       Optional - API URL (default: https://vibescope.dev)
+        console.log(`
+Vibescope CLI - Setup wizard and enforcement verification tool
+
+Usage:
+  vibescope-cli setup                 Interactive setup wizard for your IDE
+  vibescope-cli verify [options]      Check Vibescope compliance before exit
+
+Setup:
+  Configures Vibescope MCP integration for:
+  - Claude Code (CLI)
+  - Claude Desktop
+  - Cursor
+  - Gemini CLI
+
+Verify Options:
+  --git-url <url>       Git repository URL (auto-detected if not provided)
+  --project-id <id>     Vibescope project UUID
+
+Exit Codes (verify):
+  0  Compliant - agent can exit
+  1  Non-compliant - agent should continue work
+  2  Error - allow exit with warning
+
+Environment Variables:
+  VIBESCOPE_API_KEY       Required for verify - Your Vibescope API key
+  VIBESCOPE_API_URL       Optional - API URL (default: https://vibescope.dev)
 `);
         process.exit(0);
     }

package/dist/handlers/discovery.js

@@ -40,6 +40,7 @@ export const TOOL_CATEGORIES = {
             { name: 'get_token_usage', brief: 'View token stats' },
             { name: 'report_token_usage', brief: 'Report actual Claude API usage' },
             { name: 'heartbeat', brief: 'Maintain active status' },
+            { name: 'signal_idle', brief: 'Signal agent is idle' },
             { name: 'end_work_session', brief: 'End session, release tasks' },
             { name: 'confirm_agent_setup', brief: 'Mark agent setup as complete' },
         ],
@@ -69,6 +70,7 @@ export const TOOL_CATEGORIES = {
             { name: 'complete_task', brief: 'Mark task done' },
             { name: 'delete_task', brief: 'Remove a task' },
             { name: 'cancel_task', brief: 'Cancel task with reason' },
+            { name: 'release_task', brief: 'Unclaim task to pending' },
             { name: 'batch_update_tasks', brief: 'Update multiple tasks' },
             { name: 'batch_complete_tasks', brief: 'Complete multiple tasks' },
             { name: 'add_task_reference', brief: 'Add URL to task' },

package/dist/handlers/roles.js

@@ -63,14 +63,7 @@ export const setSessionRole = async (args, ctx) => {
             result: { error: 'role is required' },
         };
     }
-    const validRoles = ['developer', 'validator', 'deployer', 'reviewer', 'maintainer'];
-    if (!validRoles.includes(role)) {
-        return {
-            result: {
-                error: `Invalid role: ${role}. Must be one of: ${validRoles.join(', ')}`,
-            },
-        };
-    }
+    // Role is now open-ended - any role name accepted
     // Update local session state
     updateSession({ currentRole: role });
     // If there's an active session, update it on the server too

package/dist/handlers/session.d.ts

@@ -26,6 +26,17 @@ export declare const reportTokenUsage: Handler;
  * This marks the agent type as onboarded, so future sessions won't receive setup instructions.
  */
 export declare const confirmAgentSetup: Handler;
+/**
+ * Signal that the agent is idle (no more tasks to work on).
+ * This immediately updates the session status to 'idle', providing real-time
+ * visibility on the dashboard instead of waiting for heartbeat timeout.
+ *
+ * Call this when:
+ * - complete_task returns no next_task
+ * - get_next_task returns no tasks
+ * - There's genuinely no work to do
+ */
+export declare const signalIdle: Handler;
 /**
  * Session handlers registry
  */

package/dist/handlers/session.js

@@ -12,21 +12,20 @@ import os from 'os';
 import { parseArgs, createEnumValidator } from '../validators.js';
 import { getApiClient } from '../api-client.js';
 import { getAgentGuidelinesTemplate, getAgentGuidelinesSummary } from '../templates/agent-guidelines.js';
+import { getFallbackHelpContent, getAvailableHelpTopics } from '../templates/help-content.js';
+import { normalizeGitUrl } from '../utils.js';
 // Auto-detect machine hostname for worktree tracking
 const MACHINE_HOSTNAME = os.hostname();
 const VALID_MODES = ['lite', 'full'];
-const VALID_MODELS = ['opus', 'sonnet', 'haiku'];
-const VALID_ROLES = ['developer', 'validator', 'deployer', 'reviewer', 'maintainer'];
-const VALID_AGENT_TYPES = ['claude', 'gemini', 'cursor', 'windsurf', 'other'];
 // Argument schemas for type-safe parsing
 const startWorkSessionSchema = {
     project_id: { type: 'string' },
     git_url: { type: 'string' },
     mode: { type: 'string', default: 'lite', validate: createEnumValidator(VALID_MODES) },
-    model: { type: 'string', validate: createEnumValidator(VALID_MODELS) },
-    role: { type: 'string', default: 'developer', validate: createEnumValidator(VALID_ROLES) },
+    model: { type: 'string' }, // Open-ended - any model name accepted
+    role: { type: 'string', default: 'developer' }, // Open-ended - any role name accepted
     hostname: { type: 'string' }, // Machine hostname for worktree tracking
-    agent_type: { type: 'string', validate: createEnumValidator(VALID_AGENT_TYPES) }, // Agent type for onboarding
+    agent_type: { type: 'string' }, // Open-ended - any agent type accepted
 };
 const heartbeatSchema = {
     session_id: { type: 'string' },
@@ -43,19 +42,20 @@ export const startWorkSession = async (args, ctx) => {
     const { project_id, git_url, mode, model, role, hostname: providedHostname, agent_type } = parseArgs(args, startWorkSessionSchema);
     // Use auto-detected hostname if not provided - enables machine-aware worktree filtering
     const hostname = providedHostname || MACHINE_HOSTNAME;
+    // Normalize git_url and track if it was changed - helps agents understand URL matching
+    const normalizedGitUrl = git_url ? normalizeGitUrl(git_url) : null;
+    const gitUrlWasNormalized = git_url && normalizedGitUrl && git_url !== normalizedGitUrl;
     const { session, updateSession } = ctx;
     // Reset token tracking for new session with model info
+    // Model is now open-ended - use as-is (normalize Claude model names for consistency)
     const normalizedModel = model ? model.toLowerCase().replace(/^claude[- ]*/i, '') : null;
-    const validModel = normalizedModel && VALID_MODELS.includes(normalizedModel)
-        ? normalizedModel
-        : null;
     updateSession({
         tokenUsage: {
             callCount: 0,
             totalTokens: 0,
             byTool: {},
             byModel: {},
-            currentModel: validModel,
+            currentModel: normalizedModel,
         },
     });
     // Require project_id or git_url
@@ -149,6 +149,19 @@ export const startWorkSession = async (args, ctx) => {
     result.persona = data.persona;
     result.role = data.role;
     result.project = data.project;
+    // Inform agent if git_url was normalized (helps explain URL matching behavior)
+    if (gitUrlWasNormalized) {
+        result.git_url_normalized = {
+            message: 'Your git URL was normalized for project lookup. All URL formats for the same repository resolve to the same project.',
+            original: git_url,
+            normalized: normalizedGitUrl,
+            examples: [
+                'git@github.com:owner/repo.git → https://github.com/owner/repo',
+                'https://GITHUB.COM/Owner/Repo/ → https://github.com/owner/repo',
+                'http://github.com/owner/repo.git → https://github.com/owner/repo',
+            ],
+        };
+    }
     // Add task data
     if (data.next_task) {
         result.next_task = data.next_task;
@@ -209,6 +222,31 @@ export const startWorkSession = async (args, ctx) => {
                 command: `git worktree add ../<project>-<persona>-<task> -b feature/<task-id> ${baseBranch}`,
                 help: 'Run get_help("git") for full instructions',
             };
+            // Add FIRST_TIME_CONNECTION guidance for git-flow
+            if (data.project.git_workflow === 'git-flow') {
+                result.FIRST_TIME_CONNECTION = {
+                    workflow: 'git-flow',
+                    steps: [
+                        `1. git checkout ${data.project.git_develop_branch || 'develop'}`,
+                        `2. git pull origin ${data.project.git_develop_branch || 'develop'}`,
+                        '3. All feature branches must be created from develop',
+                    ],
+                    warning: 'Working from main or stale branches causes merge conflicts.',
+                    base_branch: data.project.git_develop_branch || 'develop',
+                };
+            }
+            else if (data.project.git_workflow === 'github-flow') {
+                result.FIRST_TIME_CONNECTION = {
+                    workflow: 'github-flow',
+                    steps: [
+                        `1. git checkout ${data.project.git_main_branch || 'main'}`,
+                        `2. git pull origin ${data.project.git_main_branch || 'main'}`,
+                        '3. All feature branches must be created from main',
+                    ],
+                    warning: 'Working from stale branches causes merge conflicts.',
+                    base_branch: data.project.git_main_branch || 'main',
+                };
+            }
         }
     }
     // Add agent setup instructions if this is a new agent type for the project
@@ -337,28 +375,23 @@ export const getHelp = async (args, _ctx) => {
     const { topic } = parseArgs(args, getHelpSchema);
     const apiClient = getApiClient();
     const response = await apiClient.getHelpTopic(topic);
-    if (!response.ok) {
-        // If database fetch fails, return error
-        return {
-            result: {
-                error: response.error || `Failed to fetch help topic: ${topic}`,
-            },
-        };
+    // Try database content first
+    if (response.ok && response.data?.content) {
+        return { result: { topic, content: response.data.content } };
     }
-    if (!response.data) {
-        // Topic not found - fetch available topics
-        const topicsResponse = await apiClient.getHelpTopics();
-        const available = topicsResponse.ok && topicsResponse.data
-            ? topicsResponse.data.map(t => t.slug)
-            : ['getting_started', 'tasks', 'validation', 'deployment', 'git', 'blockers', 'milestones', 'fallback', 'session', 'tokens', 'sprints', 'topics'];
-        return {
-            result: {
-                error: `Unknown topic: ${topic}`,
-                available,
-            },
-        };
+    // Fall back to local content if database is empty or unavailable
+    const fallback = getFallbackHelpContent(topic);
+    if (fallback) {
+        return { result: { topic, content: fallback.content } };
     }
-    return { result: { topic, content: response.data.content } };
+    // Topic not found in either source - show available topics
+    const available = getAvailableHelpTopics();
+    return {
+        result: {
+            error: `Unknown topic: ${topic}`,
+            available,
+        },
+    };
 };
 const MODEL_PRICING = {
     standard: {
@@ -479,11 +512,11 @@ export const getTokenUsage = async (_args, ctx) => {
 const reportTokenUsageSchema = {
     input_tokens: { type: 'number', required: true },
     output_tokens: { type: 'number', required: true },
-    model: { type: 'string', validate: createEnumValidator(VALID_MODELS) },
+    model: { type: 'string' }, // Open-ended - any model name accepted
 };
 const confirmAgentSetupSchema = {
     project_id: { type: 'string', required: true },
-    agent_type: { type: 'string', required: true, validate: createEnumValidator(VALID_AGENT_TYPES) },
+    agent_type: { type: 'string', required: true }, // Open-ended - any agent type accepted
 };
 /**
  * Report actual Claude API token usage for accurate cost tracking.
@@ -610,6 +643,64 @@ export const confirmAgentSetup = async (args, _ctx) => {
         },
     };
 };
+const signalIdleSchema = {
+    session_id: { type: 'string' },
+};
+/**
+ * Signal that the agent is idle (no more tasks to work on).
+ * This immediately updates the session status to 'idle', providing real-time
+ * visibility on the dashboard instead of waiting for heartbeat timeout.
+ *
+ * Call this when:
+ * - complete_task returns no next_task
+ * - get_next_task returns no tasks
+ * - There's genuinely no work to do
+ */
+export const signalIdle = async (args, ctx) => {
+    const { session_id } = parseArgs(args, signalIdleSchema);
+    const { session } = ctx;
+    const targetSession = session_id || session.currentSessionId;
+    if (!targetSession) {
+        return {
+            result: {
+                error: 'No active session. Call start_work_session first.',
+            },
+        };
+    }
+    const apiClient = getApiClient();
+    const response = await apiClient.signalIdle(targetSession);
+    if (!response.ok) {
+        return {
+            result: {
+                error: response.error || 'Failed to signal idle',
+            },
+        };
+    }
+    return {
+        result: {
+            success: true,
+            session_id: targetSession,
+            status: 'idle',
+            message: 'Session marked as idle. Dashboard will show you as inactive until you start a new task.',
+            next_steps: [
+                'Wait for new tasks to be added by the user',
+                'Or call start_fallback_activity() to do background work',
+                'Or call end_work_session() if you are done for the session',
+            ],
+            AUTONOMY_RULES: {
+                message: 'Agents must be autonomous. Follow these rules:',
+                rules: [
+                    'Never ask "should I continue?" → Just continue',
+                    'Never ask "should I clear context?" → Just clear it',
+                    'Never say "let me know what to do" → Use get_next_task or fallback activities',
+                    'When context grows large: /clear → start_work_session (don\'t ask, just do it)',
+                ],
+                preferred_activities: ['code_review', 'security_review', 'test_coverage', 'documentation_review', 'dependency_audit'],
+                directive: 'BE PROACTIVE: Start a fallback activity now rather than waiting for user input.',
+            },
+        },
+    };
+};
 /**
  * Session handlers registry
  */
@@ -617,6 +708,7 @@ export const sessionHandlers = {
     start_work_session: startWorkSession,
     heartbeat: heartbeat,
     end_work_session: endWorkSession,
+    signal_idle: signalIdle,
     get_help: getHelp,
     get_token_usage: getTokenUsage,
     report_token_usage: reportTokenUsage,

package/dist/handlers/tasks.d.ts

@@ -12,6 +12,8 @@
  * - update_task
  * - complete_task
  * - delete_task
+ * - release_task
+ * - cancel_task
  * - add_task_reference
  * - remove_task_reference
  * - batch_update_tasks
@@ -39,6 +41,12 @@ export declare const addTask: Handler;
 export declare const updateTask: Handler;
 export declare const completeTask: Handler;
 export declare const deleteTask: Handler;
+/**
+ * Release a task back to pending status.
+ * Use when an agent needs to give up a claimed task (context limits, conflicts, user request).
+ */
+export declare const releaseTask: Handler;
+export declare const cancelTask: Handler;
 export declare const addTaskReference: Handler;
 export declare const removeTaskReference: Handler;
 export declare const batchUpdateTasks: Handler;