@hailer/mcp 1.1.11 → 1.1.13

package/dist/mcp/tools/company.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Company Tools
+ *
+ * Tools for managing workspace-level company settings in Hailer:
+ * - Set user role (owner, admin, guest, inviter, feedAdmin, customRole)
+ */
+import { Tool } from '../tool-registry';
+export declare const setUserRoleTool: Tool;
+//# sourceMappingURL=company.d.ts.map

package/dist/mcp/tools/company.js

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * Company Tools
+ *
+ * Tools for managing workspace-level company settings in Hailer:
+ * - Set user role (owner, admin, guest, inviter, feedAdmin, customRole)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setUserRoleTool = void 0;
+const zod_1 = require("zod");
+const tool_registry_1 = require("../tool-registry");
+const index_1 = require("../utils/index");
+const tool_helpers_1 = require("../utils/tool-helpers");
+const request_logger_1 = require("../../lib/request-logger");
+const logger = (0, index_1.createLogger)({ component: 'company-tools' });
+// ============================================================================
+// TOOL 1: SET USER ROLE
+// ============================================================================
+const roleSections = ['owner', 'admin', 'guest', 'inviter', 'feedAdmin', 'customRole'];
+const setUserRoleDescription = `Set a user's role in the workspace.
+
+Sections:
+- owner: Transfer/revoke workspace ownership (owner only)
+- admin: Grant/revoke admin role (value: true/false)
+- guest: Grant/revoke guest role (value: true/false)
+- inviter: Grant/revoke inviter role (value: true/false)
+- feedAdmin: Grant/revoke feed admin role (value: true/false)
+- customRole: Assign/remove a custom role (value: customRole ID string)
+
+Required permissions:
+- owner: only the workspace owner can change
+- admin/guest/feedAdmin: must be admin
+- customRole: must be admin or owner`;
+exports.setUserRoleTool = {
+    name: 'set_user_role',
+    group: tool_registry_1.ToolGroup.WRITE,
+    description: setUserRoleDescription,
+    schema: zod_1.z.object({
+        section: zod_1.z
+            .enum(roleSections)
+            .describe('Which role to change: owner, admin, guest, inviter, feedAdmin, or customRole'),
+        uid: zod_1.z
+            .string()
+            .describe('Target user ID'),
+        value: zod_1.z
+            .union([zod_1.z.coerce.boolean(), zod_1.z.string()])
+            .describe('true/false to grant/revoke the role, or a custom role ID string for customRole section'),
+        workspaceId: zod_1.z
+            .string()
+            .optional()
+            .describe('Workspace ID. Defaults to the current session workspace.'),
+    }),
+    async execute(args, context) {
+        logger.debug('Setting user role', {
+            section: args.section,
+            uid: args.uid,
+            value: args.value,
+            apiKey: context.apiKey.substring(0, 8) + '...',
+        });
+        try {
+            const workspaceId = (0, tool_helpers_1.getResolvedWorkspaceId)(args, context);
+            const payload = {
+                section: args.section,
+                uid: args.uid,
+                value: args.value,
+            };
+            if (workspaceId) {
+                payload.workspaceId = workspaceId;
+            }
+            const result = await context.hailer.request('company.set_user_data', [payload]);
+            return (0, index_1.textResponse)(JSON.stringify({
+                success: true,
+                section: args.section,
+                uid: args.uid,
+                value: args.value,
+                workspaceId,
+                result,
+            }, null, 2));
+        }
+        catch (error) {
+            if (!request_logger_1.RequestLogger.getCurrent())
+                logger.error('Error setting user role', error);
+            const msg = error?.msg || error?.message || (0, index_1.getErrorMessage)(error);
+            return (0, index_1.errorResponse)(`Error setting user role: ${msg}`);
+        }
+    },
+};
+//# sourceMappingURL=company.js.map

package/dist/mcp/tools/discussion.js

@@ -304,6 +304,32 @@ exports.fetchDiscussionMessagesTool = {
             const messageCount = messages.length;
             const userMessages = messages.filter((m) => m.type === "user");
             const recentMessage = messages[0];
+            function extractForwardedMessage(fwd, depth = 0) {
+                if (depth > 10)
+                    return null;
+                const fwdUserInfo = (0, workspace_cache_1.getUserById)(context.workspaceCache, fwd.uid);
+                let fwdUsername = `User ${fwd.uid}`;
+                if (fwdUserInfo) {
+                    const fullName = `${fwdUserInfo.firstname || ''} ${fwdUserInfo.lastname || ''}`.trim();
+                    fwdUsername = fullName || fwdUserInfo.fullName || `User ${fwd.uid}`;
+                }
+                const extracted = {
+                    _id: fwd._id,
+                    uid: fwd.uid,
+                    username: fwdUsername,
+                    created: new Date(fwd.created).toLocaleString(),
+                    msg: fwd.msg || '',
+                    type: fwd.type
+                };
+                if (fwd.forwardMessageId)
+                    extracted.forwardMessageId = fwd.forwardMessageId;
+                if (fwd.forwardMessage) {
+                    const nested = extractForwardedMessage(fwd.forwardMessage, depth + 1);
+                    if (nested)
+                        extracted.forwardMessage = nested;
+                }
+                return extracted;
+            }
             const optimizedMessages = messages.map((msg) => {
                 let cleanMsg = msg.msg || '';
                 if (cleanMsg) {
@@ -333,6 +359,14 @@ exports.fetchDiscussionMessagesTool = {
                 if (msg.replyTo) {
                     optimizedMsg.replyTo = msg.replyTo;
                 }
+                if (msg.forwardMessageId) {
+                    optimizedMsg.forwardMessageId = msg.forwardMessageId;
+                }
+                if (msg.forwardMessage) {
+                    const forwarded = extractForwardedMessage(msg.forwardMessage, 0);
+                    if (forwarded)
+                        optimizedMsg.forwardMessage = forwarded;
+                }
                 return optimizedMsg;
             });
             const optimizedResult = {
@@ -434,6 +468,32 @@ exports.fetchPreviousDiscussionMessagesTool = {
             const messageCount = messages.length;
             const userMessages = messages.filter((m) => m.type === "user");
             const oldestMessage = messages.length > 0 ? messages[messages.length - 1] : null;
+            function extractForwardedMessage(fwd, depth = 0) {
+                if (depth > 10)
+                    return null;
+                const fwdUserInfo = (0, workspace_cache_1.getUserById)(context.workspaceCache, fwd.uid);
+                let fwdUsername = `User ${fwd.uid}`;
+                if (fwdUserInfo) {
+                    const fullName = `${fwdUserInfo.firstname || ''} ${fwdUserInfo.lastname || ''}`.trim();
+                    fwdUsername = fullName || fwdUserInfo.fullName || `User ${fwd.uid}`;
+                }
+                const extracted = {
+                    _id: fwd._id,
+                    uid: fwd.uid,
+                    username: fwdUsername,
+                    created: new Date(fwd.created).toLocaleString(),
+                    msg: fwd.msg || '',
+                    type: fwd.type
+                };
+                if (fwd.forwardMessageId)
+                    extracted.forwardMessageId = fwd.forwardMessageId;
+                if (fwd.forwardMessage) {
+                    const nested = extractForwardedMessage(fwd.forwardMessage, depth + 1);
+                    if (nested)
+                        extracted.forwardMessage = nested;
+                }
+                return extracted;
+            }
             const optimizedMessages = messages.map((msg) => {
                 let cleanMsg = msg.msg || '';
                 if (cleanMsg) {
@@ -456,6 +516,14 @@ exports.fetchPreviousDiscussionMessagesTool = {
                 if (msg.replyTo) {
                     optimizedMsg.replyTo = msg.replyTo;
                 }
+                if (msg.forwardMessageId) {
+                    optimizedMsg.forwardMessageId = msg.forwardMessageId;
+                }
+                if (msg.forwardMessage) {
+                    const forwarded = extractForwardedMessage(msg.forwardMessage, 0);
+                    if (forwarded)
+                        optimizedMsg.forwardMessage = forwarded;
+                }
                 return optimizedMsg;
             });
             const optimizedResult = {

package/dist/mcp/tools/workflow-permissions.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Workflow Permission Tools
+ *
+ * Tools for managing workflow member permissions in Hailer workspaces:
+ * - List members and their permission levels
+ * - Grant user or team access with a specific permission level
+ * - Revoke user or team access
+ * - Check what permissions a specific user has
+ */
+import { Tool } from '../tool-registry';
+export declare const listWorkflowPermissionsTool: Tool;
+export declare const grantWorkflowPermissionTool: Tool;
+export declare const revokeWorkflowPermissionTool: Tool;
+export declare const checkUserPermissionsTool: Tool;
+//# sourceMappingURL=workflow-permissions.d.ts.map

package/dist/mcp/tools/workflow-permissions.js

@@ -0,0 +1,204 @@
+"use strict";
+/**
+ * Workflow Permission Tools
+ *
+ * Tools for managing workflow member permissions in Hailer workspaces:
+ * - List members and their permission levels
+ * - Grant user or team access with a specific permission level
+ * - Revoke user or team access
+ * - Check what permissions a specific user has
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkUserPermissionsTool = exports.revokeWorkflowPermissionTool = exports.grantWorkflowPermissionTool = exports.listWorkflowPermissionsTool = void 0;
+const zod_1 = require("zod");
+const tool_registry_1 = require("../tool-registry");
+const index_1 = require("../utils/index");
+const tool_helpers_1 = require("../utils/tool-helpers");
+const request_logger_1 = require("../../lib/request-logger");
+const logger = (0, index_1.createLogger)({ component: 'workflow-permissions-tools' });
+/** Ensure memberId has the required prefix (user_, team_, network_, group_) */
+function ensureMemberPrefix(memberId) {
+    if (memberId.startsWith('user_') || memberId.startsWith('team_') ||
+        memberId.startsWith('network_') || memberId.startsWith('group_')) {
+        return memberId;
+    }
+    return `user_${memberId}`;
+}
+// ============================================================================
+// TOOL 1: LIST WORKFLOW PERMISSIONS
+// ============================================================================
+exports.listWorkflowPermissionsTool = {
+    name: 'list_workflow_permissions',
+    group: tool_registry_1.ToolGroup.READ,
+    description: 'List members and their permission levels for a workflow',
+    schema: zod_1.z.object({
+        workflowId: zod_1.z
+            .string()
+            .describe('The workflow ID to list permissions for'),
+    }),
+    async execute(args, context) {
+        logger.debug('Listing workflow permissions', {
+            workflowId: args.workflowId,
+            apiKey: context.apiKey.substring(0, 8) + '...',
+        });
+        try {
+            const result = await context.hailer.request('v2.process.member.list', [args.workflowId]);
+            return (0, index_1.textResponse)(JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            if (!request_logger_1.RequestLogger.getCurrent())
+                logger.error('Error listing workflow permissions', error);
+            const msg = error?.msg || error?.message || (0, index_1.getErrorMessage)(error);
+            return (0, index_1.errorResponse)(`Error listing workflow permissions: ${msg}`);
+        }
+    },
+};
+// ============================================================================
+// TOOL 2: GRANT WORKFLOW PERMISSION
+// ============================================================================
+const permissionLevels = ['admin', 'any', 'ownteam', 'own'];
+exports.grantWorkflowPermissionTool = {
+    name: 'grant_workflow_permission',
+    group: tool_registry_1.ToolGroup.WRITE,
+    description: 'Grant a user or team access to a workflow with a specific permission level',
+    schema: zod_1.z.object({
+        workflowId: zod_1.z
+            .string()
+            .describe('The workflow ID to grant permission on'),
+        memberId: zod_1.z
+            .string()
+            .describe('The user ID or team ID to grant access to'),
+        level: zod_1.z
+            .enum(permissionLevels)
+            .describe('Permission level: admin (full access), any (all activities), ownteam (own team activities), own (own activities only)'),
+    }),
+    async execute(args, context) {
+        logger.debug('Granting workflow permission', {
+            workflowId: args.workflowId,
+            memberId: args.memberId,
+            level: args.level,
+            apiKey: context.apiKey.substring(0, 8) + '...',
+        });
+        try {
+            const prefixedMemberId = ensureMemberPrefix(args.memberId);
+            // Step 1: Add as member first (may fail if already a member — that's OK)
+            try {
+                await context.hailer.request('v2.process.member.add', [args.workflowId, prefixedMemberId]);
+            }
+            catch (addError) {
+                logger.debug('member.add failed (possibly already a member), continuing to grant', {
+                    error: (0, index_1.getErrorMessage)(addError),
+                });
+            }
+            // Step 2: Set the permission level
+            const result = await context.hailer.request('v2.process.permissions.grant', [
+                args.workflowId,
+                prefixedMemberId,
+                args.level,
+            ]);
+            return (0, index_1.textResponse)(JSON.stringify({
+                success: true,
+                workflowId: args.workflowId,
+                memberId: prefixedMemberId,
+                level: args.level,
+                result,
+            }, null, 2));
+        }
+        catch (error) {
+            if (!request_logger_1.RequestLogger.getCurrent())
+                logger.error('Error granting workflow permission', error);
+            const msg = error?.msg || error?.message || (0, index_1.getErrorMessage)(error);
+            return (0, index_1.errorResponse)(`Error granting workflow permission: ${msg}`);
+        }
+    },
+};
+// ============================================================================
+// TOOL 3: REVOKE WORKFLOW PERMISSION
+// ============================================================================
+exports.revokeWorkflowPermissionTool = {
+    name: 'revoke_workflow_permission',
+    group: tool_registry_1.ToolGroup.WRITE,
+    description: "Remove a user or team's access to a workflow",
+    schema: zod_1.z.object({
+        workflowId: zod_1.z
+            .string()
+            .describe('The workflow ID to revoke permission on'),
+        memberId: zod_1.z
+            .string()
+            .describe('The user ID or team ID to remove access from'),
+    }),
+    async execute(args, context) {
+        logger.debug('Revoking workflow permission', {
+            workflowId: args.workflowId,
+            memberId: args.memberId,
+            apiKey: context.apiKey.substring(0, 8) + '...',
+        });
+        try {
+            const prefixedMemberId = ensureMemberPrefix(args.memberId);
+            // Step 1: Deny permissions (may fail if no explicit grant — that's OK)
+            try {
+                await context.hailer.request('v2.process.permissions.deny', [args.workflowId, prefixedMemberId]);
+            }
+            catch (denyError) {
+                logger.debug('permissions.deny failed (possibly no explicit grant), continuing to remove', {
+                    error: (0, index_1.getErrorMessage)(denyError),
+                });
+            }
+            // Step 2: Remove from members
+            const result = await context.hailer.request('v2.process.member.remove', [
+                args.workflowId,
+                prefixedMemberId,
+            ]);
+            return (0, index_1.textResponse)(JSON.stringify({
+                success: true,
+                workflowId: args.workflowId,
+                memberId: prefixedMemberId,
+                result,
+            }, null, 2));
+        }
+        catch (error) {
+            if (!request_logger_1.RequestLogger.getCurrent())
+                logger.error('Error revoking workflow permission', error);
+            const msg = error?.msg || error?.message || (0, index_1.getErrorMessage)(error);
+            return (0, index_1.errorResponse)(`Error revoking workflow permission: ${msg}`);
+        }
+    },
+};
+// ============================================================================
+// TOOL 4: CHECK USER PERMISSIONS
+// ============================================================================
+exports.checkUserPermissionsTool = {
+    name: 'check_user_permissions',
+    group: tool_registry_1.ToolGroup.READ,
+    description: 'Check what permissions a specific user has in the workspace',
+    schema: zod_1.z.object({
+        userId: zod_1.z
+            .string()
+            .describe('The user ID to check permissions for'),
+        workspaceId: zod_1.z
+            .string()
+            .optional()
+            .describe('The workspace ID to check permissions in. Defaults to the current workspace.'),
+    }),
+    async execute(args, context) {
+        logger.debug('Checking user permissions', {
+            userId: args.userId,
+            apiKey: context.apiKey.substring(0, 8) + '...',
+        });
+        try {
+            const workspaceId = (0, tool_helpers_1.getResolvedWorkspaceId)(args, context);
+            const result = await context.hailer.request('v3.user.permissions', [
+                args.userId,
+                workspaceId,
+            ]);
+            return (0, index_1.textResponse)(JSON.stringify(result, null, 2));
+        }
+        catch (error) {
+            if (!request_logger_1.RequestLogger.getCurrent())
+                logger.error('Error checking user permissions', error);
+            const msg = error?.msg || error?.message || (0, index_1.getErrorMessage)(error);
+            return (0, index_1.errorResponse)(`Error checking user permissions: ${msg}`);
+        }
+    },
+};
+//# sourceMappingURL=workflow-permissions.js.map

package/dist/mcp/tools/workflow.js

@@ -54,7 +54,13 @@ function parseErrorType(errorMessage) {
 // ============================================================================
 // READ TOOLS - Workflow Schema and Information
 // ============================================================================
-const getWorkflowSchemaDescription = `📋 Get workflow field schema and structure - REQUIRED before using list_activities to understand available fields. Shows all field IDs, labels, types, and options. Requires both workflowId and phaseId (use list_workflow_phases first).`;
+const getWorkflowSchemaDescription = `Get workflow field structure - CALL THIS BEFORE create_activity or update_activity.
+
+**Hailer Concept:** Shows all fields (columns) in a workflow with their IDs, types, and options. You MUST know field IDs to create or update activities.
+
+**Returns:** Field IDs, labels, types (text, numeric, date, dropdown, user, activitylink), required status, dropdown options.
+
+**Critical:** Never guess field IDs - always get them from this tool first.`;
 exports.getWorkflowSchemaTool = {
     name: 'get_workflow_schema',
     group: tool_registry_1.ToolGroup.READ,
@@ -179,7 +185,13 @@ exports.getWorkflowSchemaTool = {
         }
     },
 };
-const listWorkflowPhasesDescription = `📊 List available phases in a workflow - Required before using list_activities to get phase IDs. Use this first to see all phases, then call list_activities for each phase to get complete workflow overview. TIP: Also call get_workflow_schema to understand field structure.`;
+const listWorkflowPhasesDescription = `List phases (stages/statuses) in a workflow - REQUIRED to get phase IDs.
+
+**Hailer Concept:** Phases are stages like "New" → "In Progress" → "Done". Activities move through phases as work progresses.
+
+**When to use:** Before list_activities (need phaseId), before create_activity (need initial phase), before update_activity (to move to new phase).
+
+**Returns:** Phase names, IDs, which phase is initial (for new items), which is endpoint (completed).`;
 exports.listWorkflowPhasesTool = {
     name: 'list_workflow_phases',
     group: tool_registry_1.ToolGroup.READ,
@@ -258,7 +270,15 @@ exports.listWorkflowPhasesTool = {
         }
     },
 };
-const listWorkflowsDescription = `List workflows - Get workflow info with optional detailed data`;
+const listWorkflowsDescription = `List workflows (processes/pipelines) in the Hailer workspace.
+
+**Hailer Concept:** A Workflow is like a database table or Kanban board - it defines a process with fields (columns) and phases (stages). Examples: "Sales Pipeline", "Customer Database", "Project Tasks".
+
+**When to use:** To see all available workflows, find workflow IDs, or understand the workspace structure.
+
+**Returns:** Workflow names, IDs, activity counts, and relationships between workflows.
+
+**Next steps:** Use \`list_workflow_phases\` to see stages, then \`get_workflow_schema\` for field structure.`;
 exports.listWorkflowsTool = {
     name: 'list_workflows',
     group: tool_registry_1.ToolGroup.READ,
@@ -1069,23 +1089,15 @@ ${errorMessage}
 // ============================================================================
 // TOOL 5: LIST WORKFLOWS MINIMAL
 // ============================================================================
-const listWorkflowsMinimalDescription = `🧪 [PLAYGROUND] List workflows with minimal output - Returns only id and name to avoid token limits
+const listWorkflowsMinimalDescription = `Quick list of all workflows - START HERE to find workflow IDs.
 
-**⚡ PERFORMANCE ADVANTAGE:**
-- Uses cached data from init (v2.core.init) - **ZERO extra API calls**
-- Returns activity counts for ALL workflows in one call
-- **Preferred method for getting bulk workflow counts**
-- Much faster and more efficient than calling \`count_activities\` for each workflow
+**Hailer Concept:** Returns all workflows (processes/boards) with their IDs and names. This is usually your FIRST CALL to discover what's available.
 
-**When to use this vs count_activities:**
-- ✅ Use \`list_workflows_minimal\` for: Bulk counts, workflow discovery, listing all workflows with counts
-- ❌ Use \`count_activities\` for: Phase-level breakdown, real-time count for single workflow
+**When to use:** User asks "show my tasks", "what workflows do I have", "find customers" - use this to locate the right workflow ID.
 
-**Response includes**:
-- Workflow ID and name
-- Activity count (from cached init data)
-- Starred status
-- Workspace ID`;
+**Returns:** Workflow name, ID, activity count. Use the ID in subsequent calls.
+
+**Typical flow:** list_workflows_minimal → list_workflow_phases → get_workflow_schema → list_activities`;
 const listWorkflowsMinimalSchema = zod_1.z.object({
     workspace: zod_1.z.string().optional().describe("Optional workspace ID or name"),
     limit: zod_1.z.coerce.number().optional().describe("Maximum number of workflows to return"),
@@ -1313,7 +1325,34 @@ const updateWorkflowPhaseSchema = zod_1.z.object({
 // ============================================================================
 // CORE INIT TOOL - Workspace overview for terminal Claude Code sessions
 // ============================================================================
-const coreInitDescription = `Load workspace context - call once at session start to get workflows, phases, teams with IDs`;
+const coreInitDescription = `🚀 START HERE - Load workspace context and learn how to use Hailer tools.
+
+## What is Hailer?
+Hailer is a workspace platform. Key concepts:
+- **Workflow** = process/board (like "Tasks", "Customers", "Sales Pipeline")
+- **Activity** = item/record/card in a workflow
+- **Phase** = stage/status (like "New" → "In Progress" → "Done")
+- **Field** = property/column on an activity (name, date, priority, etc.)
+
+## How to use these tools:
+
+**Step 1 - Find workflow:** \`list_workflows_minimal\` → get workflow ID
+**Step 2 - Get phases:** \`list_workflow_phases(workflowId)\` → get phase IDs
+**Step 3 - Get fields:** \`get_workflow_schema(workflowId, phaseId)\` → get field IDs
+**Step 4 - Read/Write:**
+- \`list_activities\` - see items (requires workflowId, phaseId, fields[])
+- \`create_activity\` - create item (requires workflowId, use field IDs from schema)
+- \`update_activity\` - update item (requires activityId, use field IDs)
+
+## Field value formats:
+- Text: \`"value"\`
+- Number: \`42\`
+- Date: Unix timestamp in ms \`1730937600000\`
+- Dropdown: exact option string \`"High"\`
+- User: user ID string \`"5f8a1b2c..."\`
+
+## This tool returns:
+All workflows, phases, fields, and teams with IDs. Reference this data for all other calls.`;
 exports.coreInitTool = {
     name: 'core_init',
     group: tool_registry_1.ToolGroup.READ,

package/dist/mcp/utils/index.d.ts

@@ -12,5 +12,7 @@ export { transformActivity, transformActivities, transformFields, transformField
 export { textResponse, errorResponse, successResponse, jsonResponse, paginatedResponse, listResponse, getErrorMessage, withErrorHandling, isErrorResponse } from './response-builder';
 export { normalizePagination, calculatePaginationMeta, formatPaginationText } from './pagination';
 export type { PaginationMeta, PaginationOptions } from './pagination';
+export { deriveUserRole, getAllowedGroups, findCurrentUserMember, extractWorkspaceRoles, getAllowedGroupsForWorkspace, getMaxRole, checkWorkspaceAccess } from './role-utils';
 export type * from './types';
+export { normalizeInitProcesses } from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/mcp/utils/index.js

@@ -4,7 +4,7 @@
  * Provides centralized access to all utility functions and types
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.formatPaginationText = exports.calculatePaginationMeta = exports.normalizePagination = exports.isErrorResponse = exports.withErrorHandling = exports.getErrorMessage = exports.listResponse = exports.paginatedResponse = exports.jsonResponse = exports.successResponse = exports.errorResponse = exports.textResponse = exports.formatActivityListResponse = exports.formatUserName = exports.formatTimestamp = exports.transformWorkflowFields = exports.transformPhases = exports.transformWorkflow = exports.findFieldByKey = exports.transformFieldValue = exports.transformFields = exports.transformActivities = exports.transformActivity = exports.HailerApiClient = exports.createSuccessResponse = exports.createErrorResponse = exports.handleApiResponse = exports.makeApiCall = exports.HailerApiError = exports.LogTag = exports.LogLevel = exports.logger = exports.createLogger = void 0;
+exports.normalizeInitProcesses = exports.checkWorkspaceAccess = exports.getMaxRole = exports.getAllowedGroupsForWorkspace = exports.extractWorkspaceRoles = exports.findCurrentUserMember = exports.getAllowedGroups = exports.deriveUserRole = exports.formatPaginationText = exports.calculatePaginationMeta = exports.normalizePagination = exports.isErrorResponse = exports.withErrorHandling = exports.getErrorMessage = exports.listResponse = exports.paginatedResponse = exports.jsonResponse = exports.successResponse = exports.errorResponse = exports.textResponse = exports.formatActivityListResponse = exports.formatUserName = exports.formatTimestamp = exports.transformWorkflowFields = exports.transformPhases = exports.transformWorkflow = exports.findFieldByKey = exports.transformFieldValue = exports.transformFields = exports.transformActivities = exports.transformActivity = exports.HailerApiClient = exports.createSuccessResponse = exports.createErrorResponse = exports.handleApiResponse = exports.makeApiCall = exports.HailerApiError = exports.LogTag = exports.LogLevel = exports.logger = exports.createLogger = void 0;
 // Logging utilities
 var logger_1 = require("../../lib/logger");
 Object.defineProperty(exports, "createLogger", { enumerable: true, get: function () { return logger_1.createLogger; } });
@@ -50,4 +50,15 @@ var pagination_1 = require("./pagination");
 Object.defineProperty(exports, "normalizePagination", { enumerable: true, get: function () { return pagination_1.normalizePagination; } });
 Object.defineProperty(exports, "calculatePaginationMeta", { enumerable: true, get: function () { return pagination_1.calculatePaginationMeta; } });
 Object.defineProperty(exports, "formatPaginationText", { enumerable: true, get: function () { return pagination_1.formatPaginationText; } });
+// Role-based access control
+var role_utils_1 = require("./role-utils");
+Object.defineProperty(exports, "deriveUserRole", { enumerable: true, get: function () { return role_utils_1.deriveUserRole; } });
+Object.defineProperty(exports, "getAllowedGroups", { enumerable: true, get: function () { return role_utils_1.getAllowedGroups; } });
+Object.defineProperty(exports, "findCurrentUserMember", { enumerable: true, get: function () { return role_utils_1.findCurrentUserMember; } });
+Object.defineProperty(exports, "extractWorkspaceRoles", { enumerable: true, get: function () { return role_utils_1.extractWorkspaceRoles; } });
+Object.defineProperty(exports, "getAllowedGroupsForWorkspace", { enumerable: true, get: function () { return role_utils_1.getAllowedGroupsForWorkspace; } });
+Object.defineProperty(exports, "getMaxRole", { enumerable: true, get: function () { return role_utils_1.getMaxRole; } });
+Object.defineProperty(exports, "checkWorkspaceAccess", { enumerable: true, get: function () { return role_utils_1.checkWorkspaceAccess; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "normalizeInitProcesses", { enumerable: true, get: function () { return types_1.normalizeInitProcesses; } });
 //# sourceMappingURL=index.js.map

package/dist/mcp/utils/role-utils.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Role-Based Access Control Utilities
+ *
+ * Derives user role from workspace member flags and maps roles to ToolGroups.
+ * Used by UserContextCache to determine tool access at context creation time.
+ */
+import { ToolGroup } from '../tool-registry';
+import { UserRole, WorkspaceMember, WorkspaceInfo } from './types';
+/**
+ * Derive user role from workspace member flags
+ * Priority: owner > admin > guest > member
+ *
+ * @param member - Workspace member from v2.core.init
+ * @returns UserRole - 'owner' | 'admin' | 'guest' | 'member'
+ */
+export declare function deriveUserRole(member: WorkspaceMember): UserRole;
+/**
+ * Map user role to allowed ToolGroups
+ *
+ * @param role - User role derived from workspace member
+ * @param enableNuclear - Optional override to disable NUCLEAR even for owners
+ * @returns Array of ToolGroups the user can access
+ */
+export declare function getAllowedGroups(role: UserRole, enableNuclear?: boolean): ToolGroup[];
+/**
+ * Find current user in workspace members array
+ *
+ * @param members - Array of workspace members from init.network.members
+ * @param currentUserId - Current user's ID
+ * @returns WorkspaceMember if found, undefined otherwise
+ */
+export declare function findCurrentUserMember(members: WorkspaceMember[], currentUserId: string): WorkspaceMember | undefined;
+/**
+ * Extract user roles from all workspaces
+ * Returns a map of workspaceId → UserRole
+ *
+ * @param networks - Record of workspace ID to WorkspaceInfo from init.networks
+ * @param currentUserId - Current user's ID
+ * @returns Record mapping workspace IDs to UserRoles
+ */
+export declare function extractWorkspaceRoles(networks: Record<string, WorkspaceInfo>, currentUserId: string): Record<string, UserRole>;
+/**
+ * Get allowed groups for a specific workspace
+ *
+ * @param workspaceRoles - Map of workspace IDs to UserRoles
+ * @param workspaceId - Target workspace ID
+ * @param enableNuclear - Optional override to disable NUCLEAR even for owners
+ * @returns Array of ToolGroups the user can access in the specified workspace
+ */
+export declare function getAllowedGroupsForWorkspace(workspaceRoles: Record<string, UserRole>, workspaceId: string, enableNuclear?: boolean): ToolGroup[];
+/**
+ * Get the highest role across all workspaces
+ * Used to determine which tools to show at startup (max potential access)
+ *
+ * @param workspaceRoles - Map of workspace IDs to UserRoles
+ * @returns Highest UserRole across all workspaces
+ */
+export declare function getMaxRole(workspaceRoles: Record<string, UserRole>): UserRole;
+/**
+ * Check if user has access to a specific ToolGroup in a workspace
+ * Used for runtime permission validation when tools are called with workspaceId
+ *
+ * @param workspaceRoles - Map of workspace IDs to UserRoles
+ * @param currentWorkspaceId - Current default workspace ID
+ * @param targetWorkspaceId - Target workspace ID (or undefined to use current)
+ * @param requiredGroup - ToolGroup required for the operation
+ * @param enableNuclear - Optional override to disable NUCLEAR even for owners
+ * @returns Object with allowed boolean and optional reason string
+ */
+export declare function checkWorkspaceAccess(workspaceRoles: Record<string, UserRole>, currentWorkspaceId: string, targetWorkspaceId: string | undefined, requiredGroup: ToolGroup, enableNuclear?: boolean): {
+    allowed: boolean;
+    reason?: string;
+};
+//# sourceMappingURL=role-utils.d.ts.map