@hailer/mcp 1.2.1 → 2.0.0-beta.3

package/dist/mcp/tools/activity.js

@@ -98,7 +98,7 @@ function convertActivityFilters(mcpToolActivityListFilters) {
     let malformatFilterErrorMessage = undefined;
     for (const [fieldId, filterConfig] of Object.entries(mcpToolActivityListFilters)) {
         switch (filterConfig.operator) {
-            case "text_search":
+            case 'text_search':
                 if (filterConfig.value !== undefined) {
                     apiActivityFilters.and.push({ [fieldId]: { textSearch: filterConfig.value } });
                 }
@@ -106,7 +106,7 @@ function convertActivityFilters(mcpToolActivityListFilters) {
                     malformatFilterErrorMessage = 'text_search filter requires a value';
                 }
                 break;
-            case "equals":
+            case 'equals':
                 if (filterConfig.value !== undefined) {
                     apiActivityFilters.and.push({ [fieldId]: { equalTo: filterConfig.value } });
                 }
@@ -114,7 +114,7 @@ function convertActivityFilters(mcpToolActivityListFilters) {
                     malformatFilterErrorMessage = 'equals filter requires a value';
                 }
                 break;
-            case "not_equals":
+            case 'not_equals':
                 if (filterConfig.value !== undefined) {
                     apiActivityFilters.and.push({ [fieldId]: { notEqualTo: filterConfig.value } });
                 }
@@ -122,7 +122,7 @@ function convertActivityFilters(mcpToolActivityListFilters) {
                     malformatFilterErrorMessage = 'not_equals filter requires a value';
                 }
                 break;
-            case "contains":
+            case 'contains':
                 if (filterConfig.value !== undefined) {
                     apiActivityFilters.and.push({ [fieldId]: { contains: filterConfig.value } });
                 }
@@ -130,7 +130,7 @@ function convertActivityFilters(mcpToolActivityListFilters) {
                     malformatFilterErrorMessage = 'contains filter requires a value';
                 }
                 break;
-            case "greater_than":
+            case 'greater_than':
                 if (filterConfig.value !== undefined && typeof filterConfig.value === 'number') {
                     apiActivityFilters.and.push({ [fieldId]: { greaterThan: filterConfig.value } });
                 }
@@ -138,7 +138,7 @@ function convertActivityFilters(mcpToolActivityListFilters) {
                     malformatFilterErrorMessage = 'greater_than filter requires a numeric value';
                 }
                 break;
-            case "greater_than_or_equal":
+            case 'greater_than_or_equal':
                 if (filterConfig.value !== undefined && typeof filterConfig.value === 'number') {
                     apiActivityFilters.and.push({ [fieldId]: { greaterThanOrEqual: filterConfig.value } });
                 }
@@ -146,7 +146,7 @@ function convertActivityFilters(mcpToolActivityListFilters) {
                     malformatFilterErrorMessage = 'greater_than_or_equal filter requires a numeric value';
                 }
                 break;
-            case "less_than":
+            case 'less_than':
                 if (filterConfig.value !== undefined && typeof filterConfig.value === 'number') {
                     apiActivityFilters.and.push({ [fieldId]: { lessThan: filterConfig.value } });
                 }
@@ -154,7 +154,7 @@ function convertActivityFilters(mcpToolActivityListFilters) {
                     malformatFilterErrorMessage = 'less_than filter requires a numeric value';
                 }
                 break;
-            case "less_than_or_equal":
+            case 'less_than_or_equal':
                 if (filterConfig.value !== undefined && typeof filterConfig.value === 'number') {
                     apiActivityFilters.and.push({ [fieldId]: { lessThanOrEqual: filterConfig.value } });
                 }
@@ -162,7 +162,7 @@ function convertActivityFilters(mcpToolActivityListFilters) {
                     malformatFilterErrorMessage = 'less_than_or_equal filter requires a numeric value';
                 }
                 break;
-            case "range":
+            case 'range':
                 if (!filterConfig.start || !filterConfig.end) {
                     malformatFilterErrorMessage = 'Incorrect filter format, either start or end not provided for range';
                     break;
@@ -205,7 +205,7 @@ function formatActivityListResponseWithPagination(activityData, workflow, init,
     return {
         content: [
             {
-                type: "text",
+                type: 'text',
                 text: responseText,
             },
         ],
@@ -232,11 +232,13 @@ function formatFilteredActivityListResponse(activityData, workflow, init, args)
     for (const [fieldId, filter] of Object.entries(args.filters || {})) {
         const filterConfig = filter;
         responseText += `- Field \`${fieldId}\`: ${filterConfig.operator}`;
-        if (filterConfig.value !== undefined)
+        if (filterConfig.value !== undefined) {
             responseText += ` = "${filterConfig.value}"`;
-        if (filterConfig.start !== undefined)
+        }
+        if (filterConfig.start !== undefined) {
             responseText += ` from ${filterConfig.start} to ${filterConfig.end}`;
-        responseText += "\n";
+        }
+        responseText += '\n';
     }
     if (args.search) {
         responseText += `- Text search: "${args.search}"\n`;
@@ -257,7 +259,7 @@ function formatFilteredActivityListResponse(activityData, workflow, init, args)
         responseText += `- Call get_workflow_schema to verify field IDs are correct\n`;
         responseText += `- Use list_activities without filters to see all activities`;
         return {
-            content: [{ type: "text", text: responseText }],
+            content: [{ type: 'text', text: responseText }],
         };
     }
     responseText += `\n` + (0, index_1.formatActivityListResponse)(filteredActivities, workflow, undefined);
@@ -270,19 +272,164 @@ function formatFilteredActivityListResponse(activityData, workflow, init, args)
     return {
         content: [
             {
-                type: "text",
+                type: 'text',
                 text: responseText,
             },
         ],
     };
 }
+/**
+ * countOnly fast path for list_activities — preserved verbatim from the retired
+ * count_activities tool. O(1): calls v3.activity.count, never fetches activities.
+ */
+async function executeActivityCount(workflowId, context) {
+    logger.debug('Counting activities', {
+        workflowId,
+        apiKey: context.apiKey.substring(0, 8) + '...',
+    });
+    try {
+        // Get workflow name from cached data (matches by _id or key)
+        const workflow = (context.init.processes || []).find((proc) => proc._id === workflowId || proc.key === workflowId);
+        if (!workflow) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `❌ Workflow "${workflowId}" not found`,
+                    }],
+            };
+        }
+        logger.debug('Calling v3.activity.count', {
+            workflowId,
+            workflowName: workflow.name,
+        });
+        // Call v3.activity.count endpoint
+        // Returns object with phase IDs as keys and counts as values
+        const result = await context.hailer.request('v3.activity.count', [workflowId]);
+        logger.debug('Activity count retrieved', {
+            result: JSON.stringify(result),
+        });
+        // Sum all counts across phases
+        const count = Object.values(result).reduce((sum, phaseCount) => sum + phaseCount, 0);
+        let responseText = `🔢 **Activity Count for "${workflow.name}"**\n\n`;
+        responseText += `**Workflow ID:** \`${workflowId}\`\n`;
+        responseText += `**Total Activities:** ${count}\n\n`;
+        if (count === 0) {
+            responseText += `💡 This workflow has no activities yet. Use \`create_activity\` to add one.\n`;
+            return {
+                content: [{ type: 'text', text: responseText }],
+            };
+        }
+        responseText += `💡 **Next Steps:**\n`;
+        responseText += `- Use \`list_activities\` to see the activities\n`;
+        responseText += `- Use \`get_workflow_schema\` to see workflow structure\n`;
+        return {
+            content: [{ type: 'text', text: responseText }],
+        };
+    }
+    catch (error) {
+        if (!request_logger_1.RequestLogger.getCurrent()) {
+            logger.error('Error counting activities', error);
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: `❌ Error counting activities: ${error instanceof Error ? error.message : String(error)}\n\n**Tips:**\n` +
+                        '- Check that workflow ID is valid (24 characters)\n- Use `list_workflows` to find workflow IDs',
+                }],
+        };
+    }
+}
+/**
+ * Validate the keys of a fields object against a workflow's field definitions.
+ * The server silently ignores unknown keys (e.g. field NAMES instead of IDs) and
+ * reports success — the #1 documented footgun — so we error out before the API call.
+ *
+ * ORDERING: in both create_activity and update_activity this runs AFTER the
+ * date/activitylink auto-fixups and immediately before the API call. The fixups
+ * rewrite values only, never keys, so the validated key set is identical either way.
+ *
+ * Accepts field IDs and field keys (the API resolves both).
+ * Returns error text for unknown keys, or undefined when all keys are known.
+ */
+function validateFieldKeys(fields, workflowFields) {
+    const knownKeys = new Set();
+    const labelToId = new Map();
+    for (const [fieldId, fieldDef] of Object.entries(workflowFields)) {
+        const def = fieldDef;
+        knownKeys.add(fieldId);
+        if (def.key) {
+            knownKeys.add(def.key);
+        }
+        if (def.label) {
+            labelToId.set(String(def.label).toLowerCase(), fieldId);
+        }
+    }
+    const unknownKeys = Object.keys(fields).filter((key) => !knownKeys.has(key));
+    if (unknownKeys.length === 0) {
+        return undefined;
+    }
+    const lines = [];
+    let needsFieldList = false;
+    for (const key of unknownKeys) {
+        const labelMatchId = labelToId.get(key.toLowerCase());
+        if (labelMatchId) {
+            const label = workflowFields[labelMatchId].label;
+            lines.push(`Field "${key}" must be referenced by ID: use "${labelMatchId}" (label: "${label}")`);
+            continue;
+        }
+        lines.push(`Unknown field key "${key}".`);
+        needsFieldList = true;
+    }
+    if (needsFieldList) {
+        const available = Object.entries(workflowFields)
+            .slice(0, 20)
+            .map(([fid, def]) => `- "${fid}" (label: "${def.label || def.key || fid}")`);
+        lines.push('', 'Available field IDs:', ...available);
+    }
+    return lines.join('\n');
+}
+/**
+ * update_activity field-key validation: resolves the activity's workflow (the
+ * workflowId is not a tool param) via fetchActivityById → activity.process, then
+ * validates the fields object's keys. Fail-open on resolution problems (broken
+ * function fields, deleted activity, workflow missing from init) — those must not
+ * block updates; unknown keys in a resolved workflow still hard-error.
+ * Returns formatted error text, or undefined when valid or unresolvable.
+ */
+async function validateUpdateFieldKeys(activityId, fields, context) {
+    if (Object.keys(fields).length === 0) {
+        return undefined;
+    }
+    let workflowFields;
+    try {
+        const activity = await context.hailer.fetchActivityById(activityId);
+        const workflow = context.init.processes?.find((proc) => proc._id === activity?.process);
+        workflowFields = workflow?.fields;
+    }
+    catch (error) {
+        logger.warn('Skipping field-key validation - could not resolve workflow for activity', {
+            activityId,
+            error: (0, tool_helpers_1.extractErrorMessage)(error),
+        });
+        return undefined;
+    }
+    if (!workflowFields) {
+        return undefined;
+    }
+    const keyError = validateFieldKeys(fields, workflowFields);
+    if (!keyError) {
+        return undefined;
+    }
+    return `❌ Invalid field keys for activity ${activityId} — nothing was updated.\n\n${keyError}`;
+}
 /** Auto-fix date fields: convert ISO date strings to Unix timestamps (ms).
  *  If workspaceCache is available, only converts confirmed date/datetime/time fields.
  *  If not available, converts any value matching ISO date format (safe — non-date fields won't have date strings). */
 function autoFixDateFields(fields, context) {
     for (const [fieldId, fieldValue] of Object.entries(fields)) {
-        if (typeof fieldValue !== 'string' || !/^\d{4}-\d{2}-\d{2}/.test(fieldValue))
+        if (typeof fieldValue !== 'string' || !/^\d{4}-\d{2}-\d{2}/.test(fieldValue)) {
             continue;
+        }
         // Try to confirm field type from cache
         let fieldType;
         if (context.workspaceCache) {
@@ -297,15 +444,16 @@ function autoFixDateFields(fields, context) {
         // Convert if confirmed date type, OR if no cache (assume date — non-date fields won't have ISO date strings)
         if (!fieldType || fieldType === 'date' || fieldType === 'datetime' || fieldType === 'time') {
             const parsed = new Date(fieldValue.length === 10 ? fieldValue + 'T12:00:00' : fieldValue).getTime();
-            if (!isNaN(parsed))
+            if (!isNaN(parsed)) {
                 fields[fieldId] = parsed;
+            }
         }
     }
 }
 /** Build activity update object */
 function buildActivityUpdate(args, context) {
     let parsedFields = args.fields;
-    if (typeof args.fields === "string") {
+    if (typeof args.fields === 'string') {
         try {
             parsedFields = JSON.parse(args.fields);
         }
@@ -314,25 +462,25 @@ function buildActivityUpdate(args, context) {
         }
     }
     // Auto-fix activitylink fields: if LLM passes an object instead of just the ID string
-    if (parsedFields && typeof parsedFields === "object") {
+    if (parsedFields && typeof parsedFields === 'object') {
         for (const [fieldId, fieldValue] of Object.entries(parsedFields)) {
-            if (fieldValue && typeof fieldValue === "object" && !Array.isArray(fieldValue)) {
+            if (fieldValue && typeof fieldValue === 'object' && !Array.isArray(fieldValue)) {
                 const obj = fieldValue;
                 let extractedId = null;
                 // Case 1: {type: "activitylink", value: {_id: "...", name: "..."}}
-                if (obj.type && obj.value && typeof obj.value === "object" && obj.value._id) {
+                if (obj.type && obj.value && typeof obj.value === 'object' && obj.value._id) {
                     extractedId = obj.value._id;
                 }
                 // Case 2: {_id: "...", name: "..."}
-                else if (obj._id && typeof obj._id === "string") {
+                if (!extractedId && obj._id && typeof obj._id === 'string') {
                     extractedId = obj._id;
                 }
                 // Case 3: {value: "..."} where value is the ID string
-                else if (obj.value && typeof obj.value === "string" && /^[a-f0-9]{24}$/i.test(obj.value)) {
+                if (!extractedId && obj.value && typeof obj.value === 'string' && /^[a-f0-9]{24}$/i.test(obj.value)) {
                     extractedId = obj.value;
                 }
                 if (extractedId) {
-                    logger.warn("Auto-fixing activitylink field - extracting ID from object", {
+                    logger.warn('Auto-fixing activitylink field - extracting ID from object', {
                         fieldId,
                         original: JSON.stringify(fieldValue),
                         extracted: extractedId,
@@ -343,20 +491,21 @@ function buildActivityUpdate(args, context) {
         }
     }
     // Field-type aware validation and auto-fix
-    if (parsedFields && typeof parsedFields === "object" && context.workspaceCache) {
+    if (parsedFields && typeof parsedFields === 'object' && context.workspaceCache) {
         autoFixDateFields(parsedFields, context);
         const invalidUsers = [];
         for (const [fieldId, fieldValue] of Object.entries(parsedFields)) {
             // Only check string values that look like IDs
-            if (typeof fieldValue !== "string" || !/^[a-f0-9]{24}$/i.test(fieldValue)) {
+            if (typeof fieldValue !== 'string' || !/^[a-f0-9]{24}$/i.test(fieldValue)) {
                 continue;
             }
             // Find the field definition to check its type
             let fieldType;
             for (const workflow of context.workspaceCache.rawInit.processes) {
                 const workflowFields = workflow.fields;
-                if (!workflowFields)
+                if (!workflowFields) {
                     continue;
+                }
                 const field = workflowFields[fieldId];
                 if (field) {
                     fieldType = field.type;
@@ -373,14 +522,14 @@ function buildActivityUpdate(args, context) {
             // Skip validation for 'activitylink' and other field types
         }
         if (invalidUsers.length > 0) {
-            throw new Error(`Invalid user IDs in user fields: ${invalidUsers.join(", ")}. Use search_workspace_users to find valid user IDs.`);
+            throw new Error(`Invalid user IDs in user fields: ${invalidUsers.join(', ')}. Use search_workspace_users to find valid user IDs.`);
         }
     }
     return {
         _id: args.activityId,
         ...(args.name && { name: args.name }),
         ...(parsedFields &&
-            typeof parsedFields === "object" && {
+            typeof parsedFields === 'object' && {
             fields: parsedFields,
         }),
         ...(args.phaseId && { phaseId: args.phaseId }),
@@ -391,22 +540,115 @@ function buildActivityUpdate(args, context) {
  */
 function formatUpdateActivityResponse(args, result) {
     const changesText = [
-        args.name ? `- Name: "${args.name}"` : "",
-        args.fields ? `- Fields: ${JSON.stringify(args.fields, null, 2)}` : "",
-        args.phaseId ? `- Moved to phase: ${args.phaseId}` : "",
+        args.name ? `- Name: "${args.name}"` : '',
+        args.fields ? `- Fields: ${JSON.stringify(args.fields, null, 2)}` : '',
+        args.phaseId ? `- Moved to phase: ${args.phaseId}` : '',
     ]
         .filter(Boolean)
-        .join("\n");
+        .join('\n');
     const responseText = `✅ Successfully updated activity ${args.activityId}!\n\n📝 Changes applied:\n${changesText}\n\n💡 The activity has been updated in your Hailer workspace.\n\nAPI Response:\n${JSON.stringify(result, null, 2)}`;
     return {
         content: [
             {
-                type: "text",
+                type: 'text',
                 text: responseText,
             },
         ],
     };
 }
+/** Bulk-mode body of update_activity — extracted so the per-item field-key validation keeps flat control flow. */
+async function executeBulkUpdate(activities, context) {
+    logger.debug('Bulk update mode', {
+        activityCount: activities.length,
+        activities: JSON.stringify(activities, null, 2)
+    });
+    // Auto-fix common parameter name mistakes
+    for (const activity of activities) {
+        // Fix activityId -> _id
+        if (!activity._id && activity.activityId) {
+            logger.warn('Auto-fixing: activityId -> _id', { activityId: activity.activityId });
+            activity._id = activity.activityId;
+            delete activity.activityId;
+        }
+        // Fix fieldsAndValues -> fields
+        if (!activity.fields && activity.fieldsAndValues) {
+            logger.warn('Auto-fixing: fieldsAndValues -> fields', { activityId: activity._id });
+            activity.fields = activity.fieldsAndValues;
+            delete activity.fieldsAndValues;
+        }
+    }
+    // Validate that all activities have _id
+    const invalidActivities = activities.filter((act) => !act._id || typeof act._id !== 'string' || act._id.length < 24);
+    if (invalidActivities.length > 0) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `❌ **Error: Invalid bulk update request**\n\nEach activity in the "activities" array MUST have a valid "_id" field (24-character activity ID).\n\n**What you sent:** ${JSON.stringify(activities, null, 2)}\n\n**Correct format:**\n\`\`\`json\n{\n  "activities": [\n    { "_id": "691ffe654217e9e8434e577c", "fields": { "fieldId": "value" } },\n    { "_id": "691ffe654217e9e8434e5774", "name": "New Name" }\n  ]\n}\n\`\`\`\n\n**Tip:** First use list_activities to get the activity IDs, then pass them in the _id field.`,
+                }],
+        };
+    }
+    // Build updates for each activity
+    const updates = activities.map((activity) => {
+        const activityUpdate = { _id: activity._id };
+        if (activity.name) {
+            activityUpdate.name = activity.name;
+        }
+        if (activity.fields) {
+            // Parse fields if string
+            const parsedFields = typeof activity.fields === 'string'
+                ? JSON.parse(activity.fields)
+                : activity.fields;
+            // Auto-fix activitylink fields: if LLM passes object with _id, extract just the ID
+            if (parsedFields && typeof parsedFields === 'object') {
+                for (const [fieldId, fieldValue] of Object.entries(parsedFields)) {
+                    if (fieldValue &&
+                        typeof fieldValue === 'object' &&
+                        !Array.isArray(fieldValue) &&
+                        '_id' in fieldValue &&
+                        typeof fieldValue._id === 'string') {
+                        logger.warn('Auto-fixing activitylink field in bulk mode', {
+                            activityId: activity._id,
+                            fieldId,
+                            extracted: fieldValue._id,
+                        });
+                        parsedFields[fieldId] = fieldValue._id;
+                    }
+                }
+            }
+            autoFixDateFields(parsedFields, context);
+            activityUpdate.fields = parsedFields;
+        }
+        return activityUpdate;
+    });
+    // Per-item field-key validation — runs AFTER the auto-fixups above
+    // (values only, keys unchanged; see validateFieldKeys). Resolves each
+    // activity's workflow first; unknown keys silently no-op server-side otherwise.
+    for (const update of updates) {
+        const keyError = update.fields ? await validateUpdateFieldKeys(update._id, update.fields, context) : undefined;
+        if (keyError) {
+            return {
+                content: [{ type: 'text', text: keyError }],
+            };
+        }
+    }
+    // Collect unique phase IDs (most activities will have the same phase)
+    const phaseIds = activities
+        .map((act) => act.phaseId)
+        .filter((pid) => pid);
+    const commonPhaseId = phaseIds.length > 0 ? phaseIds[0] : undefined;
+    // Call API with all updates
+    const options = commonPhaseId ? { phaseId: commonPhaseId } : undefined;
+    await context.hailer.updateActivities(updates, options);
+    // Format bulk response
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `🎉 Successfully updated ${activities.length} activities!\n\n📊 **Bulk Update Summary:**\n- **Total Updated**: ${activities.length} activities\n- **Status**: All activities updated successfully\n\n✅ All activities have been updated in your Hailer workspace!`,
+            },
+        ],
+    };
+}
 const listActivitiesDescription = `List activities (items/records/tasks) from a workflow phase.
 
 **Prerequisites:** You need workflowId, phaseId, and field IDs. Get them via:
@@ -416,18 +658,17 @@ const listActivitiesDescription = `List activities (items/records/tasks) from a
 
 **Required params:** workflowId, phaseId, fields[] (array of field IDs to return)
 
-**Example flow:** User says "show my tasks" →
-1. list_workflows_minimal → find "Tasks" workflow
-2. list_workflow_phases → find "Open" phase
-3. get_workflow_schema → get field IDs
-4. list_activities with those IDs`;
+**Fast path:** \`countOnly: true\` returns only the workflow's total activity count (O(1), needs just workflowId — no phaseId/fields).`;
 exports.listActivitiesTool = {
     name: 'list_activities',
     group: tool_registry_1.ToolGroup.READ,
     description: listActivitiesDescription,
     schema: zod_1.z.object({
-        workflowId: zod_1.z.string().describe("Workflow ID or key to list activities from"),
-        phaseId: zod_1.z.string().describe("Phase ID or key to filter activities (required - use list_workflow_phases to get available phases)"),
+        workflowId: zod_1.z.string().describe('Workflow ID or key to list activities from'),
+        phaseId: zod_1.z.string().optional()
+            .describe('Phase ID or key to filter activities. Required unless countOnly=true. Use list_workflow_phases for phases'),
+        countOnly: zod_1.z.coerce.boolean().optional().default(false).describe('Fast path: return only the total activity count for the workflow (O(1) v3.activity.count). ' +
+            'Needs just workflowId; phaseId/fields/filters are ignored.'),
         fields: zod_1.z.preprocess((val) => {
             if (typeof val === 'string') {
                 try {
@@ -440,31 +681,35 @@ exports.listActivitiesTool = {
                 }
             }
             return val;
-        }, zod_1.z.array(zod_1.z.string()).optional()).describe("Array of field IDs or keys to return (use get_workflow_schema to see available fields). Select the fields needed for the task - use fewer fields for listings (name, status, etc.) and more fields when detailed information is required. If not provided, you must call get_workflow_schema first."),
+        }, zod_1.z.array(zod_1.z.string()).optional()).describe('Array of field IDs or keys to return (use get_workflow_schema to see available fields). Select the fields needed for the task - use fewer fields for listings (name, status, etc.) and more fields when detailed information is required. If not provided, you must call get_workflow_schema first.'),
         filters: zod_1.z.record(zod_1.z.object({
             operator: zod_1.z.enum([
-                "text_search",
-                "equals",
-                "not_equals",
-                "contains",
-                "greater_than",
-                "greater_than_or_equal",
-                "less_than",
-                "less_than_or_equal",
-                "range",
-            ]).describe("Filter operator: text_search for partial text match in field (BEST for filtering by text in relationship fields when you only have a name), equals for exact match (requires activity ID), range for date/number ranges, contains for partial text, comparison operators for numbers/dates"),
-            value: zod_1.z.union([zod_1.z.string(), zod_1.z.number()]).optional().describe("Value to filter by - REQUIRED for text_search, equals, not_equals, contains, greater_than, less_than operators. NOT USED for range operator (use start/end instead). For text_search: use the text/name to search for. For equals: use the entity ID."),
+                'text_search',
+                'equals',
+                'not_equals',
+                'contains',
+                'greater_than',
+                'greater_than_or_equal',
+                'less_than',
+                'less_than_or_equal',
+                'range',
+            ]).describe('Filter operator: text_search for partial text match in field (BEST for filtering by text in relationship fields when you only have a name), equals for exact match (requires activity ID), range for date/number ranges, contains for partial text, comparison operators for numbers/dates'),
+            value: zod_1.z.union([zod_1.z.string(), zod_1.z.number()]).optional().describe('Value to filter by - REQUIRED for text_search, equals, not_equals, contains, greater_than, less_than operators. NOT USED for range operator (use start/end instead). For text_search: use the text/name to search for. For equals: use the entity ID.'),
             start: zod_1.z.coerce.number().optional().describe("Start value - ONLY for range operator (NOT in 'value' field). Unix timestamp in milliseconds for date ranges. NOT nested in 'value'."),
             end: zod_1.z.coerce.number().optional().describe("End value - ONLY for range operator (NOT in 'value' field). Unix timestamp in milliseconds for date ranges. Example: for June 2025 date range, use end=1719791999000 directly here, NOT nested in 'value'."),
         })).optional().describe("Filter by field values. STRUCTURE: {\"fieldId\": {\"operator\": \"...\", \"value\": \"...\"}}. EXAMPLE: To find player named 'Harry Kane', use: {\"691ffdf84217e9e8434e5694\": {\"operator\": \"text_search\", \"value\": \"Harry Kane\"}}. WRONG: {\"playerName\": \"Harry Kane\"} or {\"fieldId\": \"Harry Kane\"}. Operators: text_search (partial text match), equals (exact ID match), range (use start/end instead of value)."),
-        search: zod_1.z.string().optional().describe("Text search across activity content - USE FILTERS INSTEAD when possible for reliable results. Only use search for truly exploratory queries."),
-        limit: zod_1.z.coerce.number().optional().default(50).describe("Maximum number of activities to return (default: 50, max: 20000)"),
-        page: zod_1.z.coerce.number().optional().default(0).describe("Page number for pagination (0-based)"),
-        sortBy: zod_1.z.enum(["name", "created", "updated", "priority"]).optional().default("updated").describe("Field to sort by"),
-        sortOrder: zod_1.z.enum(["asc", "desc"]).optional().default("desc").describe("Sort direction"),
-        includeStats: zod_1.z.coerce.boolean().optional().default(true).describe("Include total count and pagination metadata"),
+        search: zod_1.z.string().optional().describe('Text search across activity content - USE FILTERS INSTEAD when possible for reliable results. Only use search for truly exploratory queries.'),
+        limit: zod_1.z.coerce.number().optional().default(50).describe('Maximum number of activities to return (default: 50, max: 20000)'),
+        page: zod_1.z.coerce.number().optional().default(0).describe('Page number for pagination (0-based)'),
+        sortBy: zod_1.z.enum(['name', 'created', 'updated', 'priority']).optional().default('updated').describe('Field to sort by'),
+        sortOrder: zod_1.z.enum(['asc', 'desc']).optional().default('desc').describe('Sort direction'),
+        includeStats: zod_1.z.coerce.boolean().optional().default(true).describe('Include total count and pagination metadata'),
     }),
     async execute(args, context) {
+        // countOnly fast path — dispatches to the retired count_activities body (own error handling)
+        if (args.countOnly) {
+            return executeActivityCount(args.workflowId, context);
+        }
         try {
             const workflow = validateAndGetWorkflow(args.workflowId, context.init);
             const phaseId = await resolvePhaseForListing(workflow, args, context.init);
@@ -472,7 +717,7 @@ exports.listActivitiesTool = {
                 return {
                     content: [
                         {
-                            type: "text",
+                            type: 'text',
                             text: `❌ **Fields parameter required**: You must specify which fields to return to avoid huge responses.\n\n` +
                                 `📋 **Next steps:**\n` +
                                 `1. Call \`get_workflow_schema\` with workflowId: "${args.workflowId}" and phaseId: "${phaseId}" to see available fields\n` +
@@ -502,7 +747,7 @@ exports.listActivitiesTool = {
                     return {
                         content: [
                             {
-                                type: "text",
+                                type: 'text',
                                 text: `❌ **Filter Error:** ${filterErrorMessage}\n\n` +
                                     `💡 **Valid operators:** equals, not_equals, contains, text_search, greater_than, less_than, range\n` +
                                     `📋 Call \`get_workflow_schema\` to see available field IDs and types`,
@@ -542,12 +787,13 @@ exports.listActivitiesTool = {
             return response;
         }
         catch (error) {
-            if (!request_logger_1.RequestLogger.getCurrent())
-                logger.error("Failed to list activities", error);
+            if (!request_logger_1.RequestLogger.getCurrent()) {
+                logger.error('Failed to list activities', error);
+            }
             return {
                 content: [
                     {
-                        type: "text",
+                        type: 'text',
                         text: `❌ Failed to list activities: ${(0, tool_helpers_1.extractErrorMessage)(error)}`,
                     },
                 ],
@@ -567,37 +813,38 @@ exports.showActivityByIdTool = {
     group: tool_registry_1.ToolGroup.READ,
     description: showActivityByIdDescription,
     schema: zod_1.z.object({
-        activityId: zod_1.z.string().describe("Activity ID to load"),
+        activityId: zod_1.z.string().describe('Activity ID to load'),
     }),
     async execute(args, context) {
         // Validate: reject known non-activity ID patterns
         const id = args.activityId;
         if (!id || typeof id !== 'string' || id.length < 24) {
             return {
-                content: [{ type: "text", text: `❌ Invalid activity ID: "${id}". Activity IDs are 24-character hex strings from list_activities results. Do NOT use workflow IDs, field IDs, phase IDs, or discussion IDs.` }],
+                content: [{ type: 'text', text: `❌ Invalid activity ID: "${id}". Activity IDs are 24-character hex strings from list_activities results. Do NOT use workflow IDs, field IDs, phase IDs, or discussion IDs.` }],
             };
         }
         try {
             const activity = await context.hailer.fetchActivityById(args.activityId);
-            let responseText = `✅ Loaded activity with ID "${activity._id}":\n\n${JSON.stringify(activity, null, 2)}`;
+            const responseText = `✅ Loaded activity with ID "${activity._id}":\n\n${JSON.stringify(activity, null, 2)}`;
             return {
                 content: [
                     {
-                        type: "text",
+                        type: 'text',
                         text: responseText,
                     },
                 ],
             };
         }
         catch (error) {
-            if (!request_logger_1.RequestLogger.getCurrent())
-                logger.error("Failed to load activity", error, {
+            if (!request_logger_1.RequestLogger.getCurrent()) {
+                logger.error('Failed to load activity', error, {
                     activityId: args.activityId,
                 });
+            }
             return {
                 content: [
                     {
-                        type: "text",
+                        type: 'text',
                         text: `❌ Failed to load activity "${args.activityId}": ${(0, tool_helpers_1.extractErrorMessage)(error)}\n\n⚠️ Make sure this is an ACTIVITY ID (from list_activities or activity._id), NOT a workflow ID, field ID, phase ID, or discussion ID.`,
                     },
                 ],
@@ -633,38 +880,38 @@ exports.createActivityTool = {
     schema: zod_1.z.object({
         workflowId: zod_1.z
             .string()
-            .describe("The workflow ID or key where to create the activity/activities. Find this in any list_* tool results"),
+            .describe('The workflow ID or key where to create the activity/activities. Find this in any list_* tool results'),
         // BULK CREATION (optional - takes precedence over single parameters)
         activities: zod_1.z
             .array(zod_1.z.object({
-            name: zod_1.z.string().min(1, "Activity name cannot be empty").describe("Activity name/title"),
-            fields: zod_1.z.union([zod_1.z.record(zod_1.z.any()), zod_1.z.string()]).optional().describe("Custom field values (field keys or IDs)"),
-            phaseId: zod_1.z.string().optional().describe("Phase ID or key for this activity"),
-            teamId: zod_1.z.string().optional().describe("Team ID for this activity"),
-            discussionId: zod_1.z.string().optional().describe("Link to existing discussion"),
-            followerIds: zod_1.z.union([zod_1.z.array(zod_1.z.string()), zod_1.z.string()]).optional().describe("User IDs to invite"),
-            fileIds: zod_1.z.union([zod_1.z.array(zod_1.z.string()), zod_1.z.string()]).optional().describe("File IDs to attach"),
+            name: zod_1.z.string().min(1, 'Activity name cannot be empty').describe('Activity name/title'),
+            fields: zod_1.z.union([zod_1.z.record(zod_1.z.any()), zod_1.z.string()]).optional().describe('Custom field values (field keys or IDs)'),
+            phaseId: zod_1.z.string().optional().describe('Phase ID or key for this activity'),
+            teamId: zod_1.z.string().optional().describe('Team ID for this activity'),
+            discussionId: zod_1.z.string().optional().describe('Link to existing discussion'),
+            followerIds: zod_1.z.union([zod_1.z.array(zod_1.z.string()), zod_1.z.string()]).optional().describe('User IDs to invite'),
+            fileIds: zod_1.z.union([zod_1.z.array(zod_1.z.string()), zod_1.z.string()]).optional().describe('File IDs to attach'),
         }))
             .optional()
-            .describe("BULK: Array of activities. Example: [{\"name\": \"Task 1\", \"fields\": {...}}, {\"name\": \"Task 2\"}]. If provided, single parameters are ignored."),
+            .describe('BULK: Array of activities. Example: [{"name": "Task 1", "fields": {...}}, {"name": "Task 2"}]. If provided, single parameters are ignored.'),
         // SINGLE CREATION (used when 'activities' is not provided)
         name: zod_1.z
             .string()
-            .min(1, "Activity name cannot be empty")
+            .min(1, 'Activity name cannot be empty')
             .optional()
             .describe("SINGLE: The activity name/title (e.g. '🤖 AI Analysis Bot', 'Customer Research Task')"),
         description: zod_1.z
             .string()
             .optional()
-            .describe("SINGLE: Optional detailed description"),
+            .describe('SINGLE: Optional detailed description'),
         phaseId: zod_1.z
             .string()
             .optional()
-            .describe("SINGLE: Optional phase/category ID or key. If not specified, uses the default phase"),
+            .describe('SINGLE: Optional phase/category ID or key. If not specified, uses the default phase'),
         teamId: zod_1.z
             .string()
             .optional()
-            .describe("SINGLE: Optional team ID for team-specific activities"),
+            .describe('SINGLE: Optional team ID for team-specific activities'),
         fields: zod_1.z
             .union([zod_1.z.record(zod_1.z.any()), zod_1.z.string()])
             .optional()
@@ -672,20 +919,20 @@ exports.createActivityTool = {
         discussionId: zod_1.z
             .string()
             .optional()
-            .describe("SINGLE: Optional discussion ID to link to existing conversation"),
+            .describe('SINGLE: Optional discussion ID to link to existing conversation'),
         followerIds: zod_1.z
             .union([zod_1.z.array(zod_1.z.string()), zod_1.z.string()])
             .optional()
-            .describe("SINGLE: Optional array of user IDs to invite"),
+            .describe('SINGLE: Optional array of user IDs to invite'),
         fileIds: zod_1.z
             .union([zod_1.z.array(zod_1.z.string()), zod_1.z.string()])
             .optional()
-            .describe("SINGLE: Optional array of file IDs to attach"),
+            .describe('SINGLE: Optional array of file IDs to attach'),
     }),
     async execute(args, context) {
         try {
             // DEBUG: Log raw input to diagnose LLM tool calling issues
-            logger.debug("create_activity called", {
+            logger.debug('create_activity called', {
                 hasName: !!args.name,
                 hasActivities: !!args.activities,
                 activitiesType: typeof args.activities,
@@ -701,7 +948,7 @@ exports.createActivityTool = {
                 };
                 if (activityData.fields) {
                     let parsedFields = activityData.fields;
-                    if (typeof activityData.fields === "string" && activityData.fields.trim() !== "") {
+                    if (typeof activityData.fields === 'string' && activityData.fields.trim() !== '') {
                         try {
                             parsedFields = JSON.parse(activityData.fields);
                         }
@@ -710,22 +957,22 @@ exports.createActivityTool = {
                         }
                     }
                     if (parsedFields &&
-                        typeof parsedFields === "object" &&
+                        typeof parsedFields === 'object' &&
                         Object.keys(parsedFields).length > 0) {
                         autoFixDateFields(parsedFields, context);
                         activity.fields = parsedFields;
                     }
                 }
-                if (activityData.phaseId && activityData.phaseId.trim() !== "") {
+                if (activityData.phaseId && activityData.phaseId.trim() !== '') {
                     activity.phaseId = activityData.phaseId;
                 }
-                if (activityData.teamId && activityData.teamId.trim() !== "") {
+                if (activityData.teamId && activityData.teamId.trim() !== '') {
                     activity.teamId = activityData.teamId;
                 }
                 if (activityData.followerIds) {
                     let parsedFollowerIds = activityData.followerIds;
-                    if (typeof activityData.followerIds === "string" &&
-                        activityData.followerIds.trim() !== "") {
+                    if (typeof activityData.followerIds === 'string' &&
+                        activityData.followerIds.trim() !== '') {
                         try {
                             parsedFollowerIds = JSON.parse(activityData.followerIds);
                         }
@@ -744,7 +991,7 @@ exports.createActivityTool = {
                                 }
                             }
                             if (invalidUsers.length > 0) {
-                                throw new Error(`Invalid user IDs in followerIds: ${invalidUsers.join(", ")}. Use search_workspace_users to find valid user IDs.`);
+                                throw new Error(`Invalid user IDs in followerIds: ${invalidUsers.join(', ')}. Use search_workspace_users to find valid user IDs.`);
                             }
                         }
                         activity.followerIds = parsedFollowerIds;
@@ -752,8 +999,8 @@ exports.createActivityTool = {
                 }
                 if (activityData.fileIds) {
                     let parsedFileIds = activityData.fileIds;
-                    if (typeof activityData.fileIds === "string" &&
-                        activityData.fileIds.trim() !== "") {
+                    if (typeof activityData.fileIds === 'string' &&
+                        activityData.fileIds.trim() !== '') {
                         try {
                             parsedFileIds = JSON.parse(activityData.fileIds);
                         }
@@ -791,7 +1038,7 @@ exports.createActivityTool = {
                 }
             }
             let activitiesToCreate;
-            let options = {
+            const options = {
                 returnDocument: true,
             };
             if (isBulk) {
@@ -810,7 +1057,7 @@ exports.createActivityTool = {
                     return activity;
                 });
                 // Check for common discussionId in bulk
-                if (args.discussionId && args.discussionId.trim() !== "") {
+                if (args.discussionId && args.discussionId.trim() !== '') {
                     options.discussionId = args.discussionId;
                 }
             }
@@ -819,7 +1066,7 @@ exports.createActivityTool = {
                 if (!args.name) {
                     throw new Error("Either 'activities' array or 'name' parameter is required");
                 }
-                logger.debug("Creating single activity", {
+                logger.debug('Creating single activity', {
                     workflowId: args.workflowId,
                     name: args.name,
                     defaultTeamId: defaultTeamId,
@@ -830,12 +1077,29 @@ exports.createActivityTool = {
                     activity.teamId = defaultTeamId;
                 }
                 activitiesToCreate = [activity];
-                if (args.discussionId && args.discussionId.trim() !== "") {
+                if (args.discussionId && args.discussionId.trim() !== '') {
                     options.discussionId = args.discussionId;
                 }
             }
+            // Pre-validate field keys before API call — runs AFTER processActivity's
+            // auto-fixups (values only, keys unchanged; see validateFieldKeys).
+            // Unknown keys (e.g. field NAMES) silently no-op server-side.
+            const workflow = context.init.processes?.find((proc) => proc._id === args.workflowId);
+            const workflowFieldDefs = workflow?.fields;
+            for (let i = 0; i < activitiesToCreate.length; i++) {
+                const item = activitiesToCreate[i];
+                const keyError = workflowFieldDefs && item.fields ? validateFieldKeys(item.fields, workflowFieldDefs) : undefined;
+                if (keyError) {
+                    const itemName = item.name || `Activity ${i + 1}`;
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `❌ Invalid field keys in "${itemName}" — nothing was created.\n\n${keyError}`,
+                            }],
+                    };
+                }
+            }
             // Pre-validate required fields before API call
-            const workflow = context.init.processes?.find((p) => p._id === args.workflowId);
             if (workflow?.fields) {
                 const requiredFields = [];
                 for (const [fieldId, field] of Object.entries(workflow.fields)) {
@@ -864,7 +1128,7 @@ exports.createActivityTool = {
                         const fieldList = requiredFields.map(f => `- ${f.label} (key: ${f.key}, id: ${f.id})`).join('\n');
                         return {
                             content: [{
-                                    type: "text",
+                                    type: 'text',
                                     text: `❌ Missing required fields - cannot create activities.\n\n**Required fields for this workflow:**\n${fieldList}\n\n**Activities with missing fields:**\n${missingByActivity.map(m => `- ${m}`).join('\n')}\n\n💡 Add the missing fields to each activity's \`fields\` object using either the field key or ID.`,
                                 }],
                         };
@@ -891,7 +1155,7 @@ exports.createActivityTool = {
                 return {
                     content: [
                         {
-                            type: "text",
+                            type: 'text',
                             text: responseText,
                         },
                     ],
@@ -922,7 +1186,7 @@ exports.createActivityTool = {
                 return {
                     content: [
                         {
-                            type: "text",
+                            type: 'text',
                             text: responseText,
                         },
                     ],
@@ -930,11 +1194,12 @@ exports.createActivityTool = {
             }
         }
         catch (error) {
-            if (!request_logger_1.RequestLogger.getCurrent())
-                logger.error("Failed to create activity/activities", error, {
+            if (!request_logger_1.RequestLogger.getCurrent()) {
+                logger.error('Failed to create activity/activities', error, {
                     workflowId: args.workflowId,
                     isBulk: !!(args.activities && args.activities.length > 0),
                 });
+            }
             const errorMessage = error instanceof Error
                 ? error.message
                 : (typeof error === 'object' && error !== null)
@@ -943,7 +1208,7 @@ exports.createActivityTool = {
             return {
                 content: [
                     {
-                        type: "text",
+                        type: 'text',
                         text: `❌ Error creating activity: ${errorMessage}\n\n💡 Troubleshooting Tips:\n- Verify the workflowId exists and is accessible\n- Check that you have permission to create activities in this workflow\n- Ensure field IDs in the fields object match the workflow's field definitions\n- Use search_workspace_users to find valid user IDs for assignment\n- Verify user IDs in followerIds exist and are accessible`,
                     },
                 ],
@@ -976,9 +1241,9 @@ exports.updateActivityTool = {
     schema: zod_1.z.object({
         // BULK: Array of activities to update
         activities: zod_1.z
-            .preprocess((val) => (typeof val === "string" ? JSON.parse(val) : val), zod_1.z
+            .preprocess((val) => (typeof val === 'string' ? JSON.parse(val) : val), zod_1.z
             .array(zod_1.z.object({
-            _id: zod_1.z.string().min(24, "Activity ID must be at least 24 characters"),
+            _id: zod_1.z.string().min(24, 'Activity ID must be at least 24 characters'),
             name: zod_1.z.string().optional(),
             fields: zod_1.z.record(zod_1.z.any()).optional(),
             phaseId: zod_1.z.string().optional(),
@@ -989,10 +1254,10 @@ exports.updateActivityTool = {
         // SINGLE: Individual activity parameters
         activityId: zod_1.z
             .string()
-            .min(24, "Activity ID must be at least 24 characters")
+            .min(24, 'Activity ID must be at least 24 characters')
             .optional()
-            .describe("SINGLE: The unique ID of the activity to update (works for any workflow)"),
-        name: zod_1.z.string().optional().describe("SINGLE: New activity title/name"),
+            .describe('SINGLE: The unique ID of the activity to update (works for any workflow)'),
+        name: zod_1.z.string().optional().describe('SINGLE: New activity title/name'),
         fields: zod_1.z
             .union([zod_1.z.record(zod_1.z.any()), zod_1.z.string()])
             .optional()
@@ -1000,97 +1265,20 @@ exports.updateActivityTool = {
         phaseId: zod_1.z
             .string()
             .optional()
-            .describe("SINGLE: Optional phase ID or key to move the activity to"),
+            .describe('SINGLE: Optional phase ID or key to move the activity to'),
     }),
     async execute(args, context) {
         try {
             // BULK MODE: Update multiple activities
             if (args.activities && Array.isArray(args.activities)) {
-                logger.debug("Bulk update mode", {
-                    activityCount: args.activities.length,
-                    activities: JSON.stringify(args.activities, null, 2)
-                });
-                // Auto-fix common parameter name mistakes
-                for (const activity of args.activities) {
-                    // Fix activityId -> _id
-                    if (!activity._id && activity.activityId) {
-                        logger.warn("Auto-fixing: activityId -> _id", { activityId: activity.activityId });
-                        activity._id = activity.activityId;
-                        delete activity.activityId;
-                    }
-                    // Fix fieldsAndValues -> fields
-                    if (!activity.fields && activity.fieldsAndValues) {
-                        logger.warn("Auto-fixing: fieldsAndValues -> fields", { activityId: activity._id });
-                        activity.fields = activity.fieldsAndValues;
-                        delete activity.fieldsAndValues;
-                    }
-                }
-                // Validate that all activities have _id
-                const invalidActivities = args.activities.filter((a) => !a._id || typeof a._id !== 'string' || a._id.length < 24);
-                if (invalidActivities.length > 0) {
-                    return {
-                        content: [{
-                                type: "text",
-                                text: `❌ **Error: Invalid bulk update request**\n\nEach activity in the "activities" array MUST have a valid "_id" field (24-character activity ID).\n\n**What you sent:** ${JSON.stringify(args.activities, null, 2)}\n\n**Correct format:**\n\`\`\`json\n{\n  "activities": [\n    { "_id": "691ffe654217e9e8434e577c", "fields": { "fieldId": "value" } },\n    { "_id": "691ffe654217e9e8434e5774", "name": "New Name" }\n  ]\n}\n\`\`\`\n\n**Tip:** First use list_activities to get the activity IDs, then pass them in the _id field.`,
-                            }],
-                    };
-                }
-                // Build updates for each activity
-                const updates = args.activities.map((activity) => {
-                    const activityUpdate = { _id: activity._id };
-                    if (activity.name)
-                        activityUpdate.name = activity.name;
-                    if (activity.fields) {
-                        // Parse fields if string
-                        let parsedFields = typeof activity.fields === 'string'
-                            ? JSON.parse(activity.fields)
-                            : activity.fields;
-                        // Auto-fix activitylink fields: if LLM passes object with _id, extract just the ID
-                        if (parsedFields && typeof parsedFields === "object") {
-                            for (const [fieldId, fieldValue] of Object.entries(parsedFields)) {
-                                if (fieldValue &&
-                                    typeof fieldValue === "object" &&
-                                    !Array.isArray(fieldValue) &&
-                                    "_id" in fieldValue &&
-                                    typeof fieldValue._id === "string") {
-                                    logger.warn("Auto-fixing activitylink field in bulk mode", {
-                                        activityId: activity._id,
-                                        fieldId,
-                                        extracted: fieldValue._id,
-                                    });
-                                    parsedFields[fieldId] = fieldValue._id;
-                                }
-                            }
-                        }
-                        autoFixDateFields(parsedFields, context);
-                        activityUpdate.fields = parsedFields;
-                    }
-                    return activityUpdate;
-                });
-                // Collect unique phase IDs (most activities will have the same phase)
-                const phaseIds = args.activities
-                    .map((a) => a.phaseId)
-                    .filter((p) => p);
-                const commonPhaseId = phaseIds.length > 0 ? phaseIds[0] : undefined;
-                // Call API with all updates
-                const options = commonPhaseId ? { phaseId: commonPhaseId } : undefined;
-                await context.hailer.updateActivities(updates, options);
-                // Format bulk response
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: `🎉 Successfully updated ${args.activities.length} activities!\n\n📊 **Bulk Update Summary:**\n- **Total Updated**: ${args.activities.length} activities\n- **Status**: All activities updated successfully\n\n✅ All activities have been updated in your Hailer workspace!`,
-                        },
-                    ],
-                };
+                return await executeBulkUpdate(args.activities, context);
             }
             // SINGLE MODE: Update one activity
             // Validate activityId is provided for single mode
             if (!args.activityId || typeof args.activityId !== 'string' || args.activityId.length < 24) {
                 return {
                     content: [{
-                            type: "text",
+                            type: 'text',
                             text: `❌ **Error: Missing or invalid activityId**\n\nFor single activity updates, you must provide a valid "activityId" (24-character hex string).\n\n**What you sent:** activityId = ${JSON.stringify(args.activityId)}\n\n**Correct format:**\n\`\`\`json\n{\n  "activityId": "691ffe654217e9e8434e577c",\n  "name": "New Name",\n  "fields": { "fieldId": "value" }\n}\n\`\`\`\n\n**For bulk updates (3+ activities), use:**\n\`\`\`json\n{\n  "activities": [\n    { "_id": "activity-id-1", "fields": {...} },\n    { "_id": "activity-id-2", "name": "New Name" }\n  ]\n}\n\`\`\`\n\n**Tip:** Use list_activities or show_activity_by_id to find activity IDs first.`,
                         }],
                 };
@@ -1099,32 +1287,44 @@ exports.updateActivityTool = {
             if (!args.name && !args.fields && !args.phaseId) {
                 return {
                     content: [{
-                            type: "text",
+                            type: 'text',
                             text: `❌ **Error: No update data provided**\n\nYou called update_activity with activityId="${args.activityId}" but didn't provide any data to update.\n\n**You must provide at least one of:**\n- "name" - to update the activity name\n- "fields" - to update field values\n- "phaseId" - to move to a different phase\n\n**Example:**\n\`\`\`json\n{\n  "activityId": "${args.activityId}",\n  "fields": {\n    "fieldId123": "new value"\n  }\n}\n\`\`\``,
                         }],
                 };
             }
-            logger.debug("Single update mode", {
+            logger.debug('Single update mode', {
                 activityId: args.activityId,
                 name: args.name,
                 fields: JSON.stringify(args.fields, null, 2),
                 phaseId: args.phaseId
             });
             const updates = buildActivityUpdate(args, context);
+            // Field-key validation — runs AFTER buildActivityUpdate's auto-fixups
+            // (values only, keys unchanged; see validateFieldKeys), right before the
+            // API call. Unknown keys (e.g. field NAMES) silently no-op server-side.
+            const singleKeyError = updates.fields
+                ? await validateUpdateFieldKeys(args.activityId, updates.fields, context)
+                : undefined;
+            if (singleKeyError) {
+                return {
+                    content: [{ type: 'text', text: singleKeyError }],
+                };
+            }
             const options = args.phaseId ? { phaseId: args.phaseId } : undefined;
             const result = await context.hailer.updateActivities([updates], options);
             return formatUpdateActivityResponse(args, result);
         }
         catch (error) {
-            if (!request_logger_1.RequestLogger.getCurrent())
-                logger.error("Failed to update activity", error, {
+            if (!request_logger_1.RequestLogger.getCurrent()) {
+                logger.error('Failed to update activity', error, {
                     activityId: args.activityId || 'bulk',
                     activityCount: args.activities?.length,
                 });
+            }
             return {
                 content: [
                     {
-                        type: "text",
+                        type: 'text',
                         text: `❌ Error updating ${args.activities ? 'activities' : 'activity'}: ${error instanceof Error ? error.message : String(error)}`,
                     },
                 ],