@troykelly/openclaw-projects 0.0.23 → 0.0.25

package/dist/register-openclaw.js

@@ -500,28 +500,161 @@ const contactGetSchema = {
 const contactCreateSchema = {
     type: 'object',
     properties: {
-        name: {
+        display_name: {
             type: 'string',
-            description: 'Contact name',
-            minLength: 1,
+            description: 'Full display name (required for organizations/groups, optional for persons if given_name or family_name provided)',
             maxLength: 200,
         },
+        given_name: {
+            type: 'string',
+            description: 'Given (first) name',
+            maxLength: 100,
+        },
+        family_name: {
+            type: 'string',
+            description: 'Family (last) name',
+            maxLength: 100,
+        },
+        nickname: {
+            type: 'string',
+            description: 'Nickname or short name',
+            maxLength: 100,
+        },
+        contact_kind: {
+            type: 'string',
+            description: 'Contact type',
+            enum: ['person', 'organisation', 'group', 'agent'],
+            default: 'person',
+        },
         email: {
             type: 'string',
-            description: 'Contact email address',
+            description: 'Primary email address (creates an email endpoint)',
             format: 'email',
         },
         phone: {
             type: 'string',
-            description: 'Contact phone number',
+            description: 'Primary phone number (creates a phone endpoint)',
         },
         notes: {
             type: 'string',
             description: 'Notes about the contact',
             maxLength: 5000,
         },
+        tags: {
+            type: 'array',
+            description: 'Tags to assign to the contact (max 20)',
+            items: { type: 'string', maxLength: 100 },
+        },
+    },
+    required: [],
+};
+/**
+ * Contact update tool JSON Schema (#1600)
+ */
+const contactUpdateSchema = {
+    type: 'object',
+    properties: {
+        contact_id: {
+            type: 'string',
+            description: 'ID of the contact to update',
+            format: 'uuid',
+        },
+        display_name: {
+            type: 'string',
+            description: 'Updated display name',
+            maxLength: 200,
+        },
+        given_name: { type: 'string', maxLength: 100 },
+        family_name: { type: 'string', maxLength: 100 },
+        nickname: { type: 'string', maxLength: 100 },
+        notes: { type: 'string', maxLength: 5000 },
+        tags: {
+            type: 'array',
+            description: 'Replace all tags (empty array removes all)',
+            items: { type: 'string', maxLength: 100 },
+        },
+    },
+    required: ['contact_id'],
+};
+/**
+ * Contact merge tool JSON Schema (#1600)
+ */
+const contactMergeSchema = {
+    type: 'object',
+    properties: {
+        survivor_id: {
+            type: 'string',
+            description: 'ID of the contact to keep (survivor)',
+            format: 'uuid',
+        },
+        loser_id: {
+            type: 'string',
+            description: 'ID of the contact to merge into the survivor (will be soft-deleted)',
+            format: 'uuid',
+        },
+    },
+    required: ['survivor_id', 'loser_id'],
+};
+/**
+ * Contact tag add tool JSON Schema (#1600)
+ */
+const contactTagAddSchema = {
+    type: 'object',
+    properties: {
+        contact_id: {
+            type: 'string',
+            description: 'Contact ID',
+            format: 'uuid',
+        },
+        tags: {
+            type: 'array',
+            description: 'Tags to add (1–20 tags)',
+            items: { type: 'string', maxLength: 100 },
+        },
+    },
+    required: ['contact_id', 'tags'],
+};
+/**
+ * Contact tag remove tool JSON Schema (#1600)
+ */
+const contactTagRemoveSchema = {
+    type: 'object',
+    properties: {
+        contact_id: {
+            type: 'string',
+            description: 'Contact ID',
+            format: 'uuid',
+        },
+        tag: {
+            type: 'string',
+            description: 'Tag to remove',
+            maxLength: 100,
+        },
+    },
+    required: ['contact_id', 'tag'],
+};
+/**
+ * Contact resolve tool JSON Schema (#1601)
+ * Resolves a sender identity (phone, email, name) to a contact match.
+ */
+const contactResolveSchema = {
+    type: 'object',
+    properties: {
+        phone: {
+            type: 'string',
+            description: 'Sender phone number to resolve',
+        },
+        email: {
+            type: 'string',
+            description: 'Sender email address to resolve',
+            format: 'email',
+        },
+        name: {
+            type: 'string',
+            description: 'Sender name for fuzzy matching',
+            maxLength: 200,
+        },
     },
-    required: ['name'],
 };
 /**
  * SMS send tool JSON Schema
@@ -1316,7 +1449,7 @@ export async function refreshNamespacesAsync(state) {
         return;
     state.refreshInFlight = true;
     try {
-        const response = await state.apiClient.get('/api/namespaces', { user_id: state.user_id });
+        const response = await state.apiClient.get('/api/namespaces', { user_id: state.user_id, user_email: state.user_email });
         if (!response.success) {
             state.logger.warn('Namespace discovery failed, keeping cached list', { error: response.error.message });
             // Do NOT update timestamp on failure — let the next check retry sooner
@@ -1354,7 +1487,9 @@ export async function refreshNamespacesAsync(state) {
  * Create tool execution handlers
  */
 function createToolHandlers(state) {
-    const { config, logger, apiClient, user_id, resolvedNamespace } = state;
+    const { config, logger, apiClient, user_id, user_email, resolvedNamespace } = state;
+    /** Build RequestOptions with user_id and user_email for identity resolution (#1567) */
+    const reqOpts = () => ({ user_id, user_email });
     /**
      * Get the effective namespace for a store/create operation.
      * Uses explicit tool param if provided, otherwise falls back to config default.
@@ -1398,7 +1533,7 @@ function createToolHandlers(state) {
                 const ns = getRecallNamespaces(params);
                 if (ns.length > 0)
                     queryParams.set('namespaces', ns.join(','));
-                const response = await apiClient.get(`/api/memories/search?${queryParams}`, { user_id });
+                const response = await apiClient.get(`/api/memories/search?${queryParams}`, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message };
                 }
@@ -1484,7 +1619,7 @@ function createToolHandlers(state) {
                     if (location.place_label)
                         payload.place_label = location.place_label;
                 }
-                const response = await apiClient.post('/api/memories/unified', payload, { user_id });
+                const response = await apiClient.post('/api/memories/unified', payload, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message };
                 }
@@ -1505,7 +1640,7 @@ function createToolHandlers(state) {
             const { memory_id, query } = params;
             try {
                 if (memory_id) {
-                    const response = await apiClient.delete(`/api/memories/${memory_id}`, { user_id });
+                    const response = await apiClient.delete(`/api/memories/${memory_id}`, reqOpts());
                     if (!response.success) {
                         return { success: false, error: response.error.message };
                     }
@@ -1521,7 +1656,7 @@ function createToolHandlers(state) {
                     const forgetNs = getRecallNamespaces(params);
                     if (forgetNs.length > 0)
                         forgetQp.set('namespaces', forgetNs.join(','));
-                    const searchResponse = await apiClient.get(`/api/memories/search?${forgetQp}`, { user_id });
+                    const searchResponse = await apiClient.get(`/api/memories/search?${forgetQp}`, reqOpts());
                     if (!searchResponse.success) {
                         return { success: false, error: searchResponse.error.message };
                     }
@@ -1534,7 +1669,7 @@ function createToolHandlers(state) {
                     }
                     // Single high-confidence match → auto-delete
                     if (matches.length === 1 && (matches[0].similarity ?? 0) > 0.9) {
-                        const delResponse = await apiClient.delete(`/api/memories/${matches[0].id}`, { user_id });
+                        const delResponse = await apiClient.delete(`/api/memories/${matches[0].id}`, reqOpts());
                         if (!delResponse.success) {
                             return { success: false, error: delResponse.error.message };
                         }
@@ -1574,7 +1709,7 @@ function createToolHandlers(state) {
                 const projListNs = getRecallNamespaces(params);
                 if (projListNs.length > 0)
                     queryParams.set('namespaces', projListNs.join(','));
-                const response = await apiClient.get(`/api/work-items?${queryParams}`, { user_id });
+                const response = await apiClient.get(`/api/work-items?${queryParams}`, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message };
                 }
@@ -1593,7 +1728,7 @@ function createToolHandlers(state) {
         async project_get(params) {
             const { project_id } = params;
             try {
-                const response = await apiClient.get(`/api/work-items/${project_id}?user_email=${encodeURIComponent(user_id)}`, { user_id });
+                const response = await apiClient.get(`/api/work-items/${project_id}?user_email=${encodeURIComponent(user_id)}`, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message };
                 }
@@ -1614,7 +1749,7 @@ function createToolHandlers(state) {
         async project_create(params) {
             const { name, description, status = 'active', } = params;
             try {
-                const response = await apiClient.post('/api/work-items', { title: name, description, item_type: 'project', status, user_email: user_id, namespace: getStoreNamespace(params) }, { user_id });
+                const response = await apiClient.post('/api/work-items', { title: name, description, item_type: 'project', status, user_email: user_id, namespace: getStoreNamespace(params) }, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message };
                 }
@@ -1649,7 +1784,7 @@ function createToolHandlers(state) {
                 const todoListNs = getRecallNamespaces(params);
                 if (todoListNs.length > 0)
                     queryParams.set('namespaces', todoListNs.join(','));
-                const response = await apiClient.get(`/api/work-items?${queryParams}`, { user_id });
+                const response = await apiClient.get(`/api/work-items?${queryParams}`, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message };
                 }
@@ -1686,7 +1821,7 @@ function createToolHandlers(state) {
                     body.parent_work_item_id = project_id;
                 if (dueDate)
                     body.not_after = dueDate;
-                const response = await apiClient.post('/api/work-items', body, { user_id });
+                const response = await apiClient.post('/api/work-items', body, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message };
                 }
@@ -1706,7 +1841,7 @@ function createToolHandlers(state) {
         async todo_complete(params) {
             const { todoId } = params;
             try {
-                const response = await apiClient.patch(`/api/work-items/${todoId}/status?user_email=${encodeURIComponent(user_id)}`, { status: 'completed' }, { user_id });
+                const response = await apiClient.patch(`/api/work-items/${todoId}/status?user_email=${encodeURIComponent(user_id)}`, { status: 'completed' }, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message };
                 }
@@ -1739,7 +1874,7 @@ function createToolHandlers(state) {
                 const todoSearchNs = getRecallNamespaces(params);
                 if (todoSearchNs.length > 0)
                     queryParams.set('namespaces', todoSearchNs.join(','));
-                const response = await apiClient.get(`/api/search?${queryParams}`, { user_id });
+                const response = await apiClient.get(`/api/search?${queryParams}`, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message };
                 }
@@ -1829,7 +1964,7 @@ function createToolHandlers(state) {
         async contact_get(params) {
             const { contact_id } = params;
             try {
-                const response = await apiClient.get(`/api/contacts/${contact_id}?user_email=${encodeURIComponent(user_id)}`, { user_id });
+                const response = await apiClient.get(`/api/contacts/${contact_id}?user_email=${encodeURIComponent(user_id)}`, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message };
                 }
@@ -1852,10 +1987,37 @@ function createToolHandlers(state) {
             }
         },
         async contact_create(params) {
-            const { name, notes } = params;
+            const { display_name, given_name, family_name, nickname, contact_kind, email, phone, notes, tags } = params;
+            // Must have display_name or at least given_name/family_name
+            const name = display_name || [given_name, family_name].filter(Boolean).join(' ');
+            if (!name) {
+                return { success: false, error: 'Either display_name or given_name/family_name is required' };
+            }
             try {
-                // API requires display_name, not name. Email/phone are stored as separate contact_endpoint records.
-                const response = await apiClient.post('/api/contacts', { display_name: name, notes, user_email: user_id, namespace: getStoreNamespace(params) }, { user_id });
+                const body = {
+                    user_email: user_id,
+                    namespace: getStoreNamespace(params),
+                    notes,
+                    contact_kind: contact_kind ?? 'person',
+                    tags,
+                };
+                if (display_name)
+                    body.display_name = display_name;
+                if (given_name)
+                    body.given_name = given_name;
+                if (family_name)
+                    body.family_name = family_name;
+                if (nickname)
+                    body.nickname = nickname;
+                // Build endpoints array from convenience fields
+                const endpoints = [];
+                if (email)
+                    endpoints.push({ type: 'email', value: email });
+                if (phone)
+                    endpoints.push({ type: 'phone', value: phone });
+                if (endpoints.length > 0)
+                    body.endpoints = endpoints;
+                const response = await apiClient.post('/api/contacts', body, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message };
                 }
@@ -1863,7 +2025,7 @@ function createToolHandlers(state) {
                     success: true,
                     data: {
                         content: `Contact "${name}" created successfully (ID: ${response.data.id})`,
-                        details: { id: response.data.id },
+                        details: { id: response.data.id, display_name: response.data.display_name ?? name },
                     },
                 };
             }
@@ -1872,6 +2034,147 @@ function createToolHandlers(state) {
                 return { success: false, error: 'Failed to create contact' };
             }
         },
+        async contact_update(params) {
+            const { contact_id, ...updates } = params;
+            if (!contact_id)
+                return { success: false, error: 'contact_id is required' };
+            try {
+                const body = { namespace: getStoreNamespace(params) };
+                for (const [k, v] of Object.entries(updates)) {
+                    if (k !== 'namespace' && v !== undefined)
+                        body[k] = v;
+                }
+                const response = await apiClient.patch(`/api/contacts/${contact_id}`, body, reqOpts());
+                if (!response.success) {
+                    return { success: false, error: response.error.message };
+                }
+                return {
+                    success: true,
+                    data: {
+                        content: `Contact ${contact_id} updated successfully`,
+                        details: { id: contact_id, display_name: response.data.display_name },
+                    },
+                };
+            }
+            catch (error) {
+                logger.error('contact_update failed', { error });
+                return { success: false, error: 'Failed to update contact' };
+            }
+        },
+        async contact_merge(params) {
+            const { survivor_id, loser_id } = params;
+            if (!survivor_id || !loser_id)
+                return { success: false, error: 'survivor_id and loser_id are required' };
+            try {
+                const response = await apiClient.post('/api/contacts/merge', { survivor_id, loser_id, namespace: getStoreNamespace(params) }, reqOpts());
+                if (!response.success) {
+                    return { success: false, error: response.error.message };
+                }
+                return {
+                    success: true,
+                    data: {
+                        content: `Contacts merged successfully. Survivor: ${survivor_id}`,
+                        details: response.data,
+                    },
+                };
+            }
+            catch (error) {
+                logger.error('contact_merge failed', { error });
+                return { success: false, error: 'Failed to merge contacts' };
+            }
+        },
+        async contact_tag_add(params) {
+            const { contact_id, tags } = params;
+            if (!contact_id || !tags?.length)
+                return { success: false, error: 'contact_id and tags are required' };
+            try {
+                const response = await apiClient.post(`/api/contacts/${contact_id}/tags`, { tags }, reqOpts());
+                if (!response.success) {
+                    return { success: false, error: response.error.message };
+                }
+                return {
+                    success: true,
+                    data: {
+                        content: `Added ${tags.length} tag(s) to contact ${contact_id}: ${tags.join(', ')}`,
+                        details: { contact_id, tags },
+                    },
+                };
+            }
+            catch (error) {
+                logger.error('contact_tag_add failed', { error });
+                return { success: false, error: 'Failed to add tags' };
+            }
+        },
+        async contact_tag_remove(params) {
+            const { contact_id, tag } = params;
+            if (!contact_id || !tag)
+                return { success: false, error: 'contact_id and tag are required' };
+            try {
+                const response = await apiClient.delete(`/api/contacts/${contact_id}/tags/${encodeURIComponent(tag)}`, reqOpts());
+                if (!response.success) {
+                    return { success: false, error: response.error.message };
+                }
+                return {
+                    success: true,
+                    data: {
+                        content: `Removed tag "${tag}" from contact ${contact_id}`,
+                        details: { contact_id, tag },
+                    },
+                };
+            }
+            catch (error) {
+                logger.error('contact_tag_remove failed', { error });
+                return { success: false, error: 'Failed to remove tag' };
+            }
+        },
+        async contact_resolve(params) {
+            const { phone, email, name } = params;
+            if (!phone && !email && !name) {
+                return { success: false, error: 'At least one of phone, email, or name is required' };
+            }
+            try {
+                const queryParams = new URLSearchParams();
+                if (phone)
+                    queryParams.set('phone', phone);
+                if (email)
+                    queryParams.set('email', email);
+                if (name)
+                    queryParams.set('name', name);
+                const response = await apiClient.get(`/api/contacts/suggest-match?${queryParams}`, reqOpts());
+                if (!response.success) {
+                    return { success: false, error: response.error.message };
+                }
+                const matches = response.data.matches ?? [];
+                if (matches.length === 0) {
+                    return {
+                        success: true,
+                        data: {
+                            content: 'No matching contacts found for the provided sender information.',
+                            details: { matches: [], resolved: false },
+                        },
+                    };
+                }
+                const best = matches[0];
+                const content = matches
+                    .map((m) => `- ${m.display_name} (${Math.round(m.confidence * 100)}% match, ID: ${m.contact_id})`)
+                    .join('\n');
+                return {
+                    success: true,
+                    data: {
+                        content: `Found ${matches.length} matching contact(s):\n${content}`,
+                        details: {
+                            matches,
+                            resolved: best.confidence >= 0.8,
+                            best_match: best,
+                        },
+                    },
+                };
+            }
+            catch (error) {
+                logger.error('contact_resolve failed', { error });
+                return { success: false, error: 'Failed to resolve sender identity' };
+            }
+        },
         async sms_send(params) {
             const { to, body, idempotency_key } = params;
             // Check Twilio configuration
@@ -1908,7 +2211,7 @@ function createToolHandlers(state) {
                 hasIdempotencyKey: !!idempotency_key,
             });
             try {
-                const response = await apiClient.post('/api/twilio/sms/send', { to, body, idempotency_key }, { user_id });
+                const response = await apiClient.post('/api/twilio/sms/send', { to, body, idempotency_key }, reqOpts());
                 if (!response.success) {
                     logger.error('sms_send API error', {
                         user_id,
@@ -1989,7 +2292,7 @@ function createToolHandlers(state) {
                 hasIdempotencyKey: !!idempotency_key,
             });
             try {
-                const response = await apiClient.post('/api/postmark/email/send', { to, subject, body, html_body, thread_id, idempotency_key }, { user_id });
+                const response = await apiClient.post('/api/postmark/email/send', { to, subject, body, html_body, thread_id, idempotency_key }, reqOpts());
                 if (!response.success) {
                     logger.error('email_send API error', {
                         user_id,
@@ -2064,7 +2367,7 @@ function createToolHandlers(state) {
                     queryParams.set('include_thread', 'true');
                 }
                 // Unified search API: returns { results: [{ type, id, title, snippet, score, metadata }], total }
-                const response = await apiClient.get(`/api/search?${queryParams}`, { user_id });
+                const response = await apiClient.get(`/api/search?${queryParams}`, reqOpts());
                 if (!response.success) {
                     logger.error('message_search API error', {
                         user_id,
@@ -2177,7 +2480,7 @@ function createToolHandlers(state) {
                 if (contact_id) {
                     queryParams.set('contact_id', contact_id);
                 }
-                const response = await apiClient.get(`/api/search?${queryParams}`, { user_id });
+                const response = await apiClient.get(`/api/search?${queryParams}`, reqOpts());
                 if (!response.success) {
                     logger.error('thread_list API error', {
                         user_id,
@@ -2254,7 +2557,7 @@ function createToolHandlers(state) {
             try {
                 const queryParams = new URLSearchParams();
                 queryParams.set('limit', String(message_limit));
-                const response = await apiClient.get(`/api/threads/${thread_id}/history?${queryParams}`, { user_id });
+                const response = await apiClient.get(`/api/threads/${thread_id}/history?${queryParams}`, reqOpts());
                 if (!response.success) {
                     logger.error('thread_get API error', {
                         user_id,
@@ -2362,7 +2665,7 @@ function createToolHandlers(state) {
                 if (notes) {
                     body.notes = notes;
                 }
-                const response = await apiClient.post('/api/relationships/set', body, { user_id });
+                const response = await apiClient.post('/api/relationships/set', body, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message };
                 }
@@ -2413,7 +2716,7 @@ function createToolHandlers(state) {
                 else {
                     // Search for contact by name (Issue #1172: scope by user_email)
                     const searchParams = new URLSearchParams({ search: contact, limit: '1', user_email: user_id });
-                    const searchResponse = await apiClient.get(`/api/contacts?${searchParams}`, { user_id });
+                    const searchResponse = await apiClient.get(`/api/contacts?${searchParams}`, reqOpts());
                     if (!searchResponse.success) {
                         return { success: false, error: searchResponse.error.message };
                     }
@@ -2424,7 +2727,7 @@ function createToolHandlers(state) {
                     contact_id = contacts[0].id;
                 }
                 // Use graph traversal endpoint which returns related_contacts
-                const response = await apiClient.get(`/api/contacts/${contact_id}/relationships?user_email=${encodeURIComponent(user_id)}`, { user_id });
+                const response = await apiClient.get(`/api/contacts/${contact_id}/relationships?user_email=${encodeURIComponent(user_id)}`, reqOpts());
                 if (!response.success) {
                     if (response.error.code === 'NOT_FOUND') {
                         return { success: false, error: 'Contact not found.' };
@@ -2492,7 +2795,7 @@ function createToolHandlers(state) {
                 if (maxDownloads !== undefined) {
                     body.max_downloads = maxDownloads;
                 }
-                const response = await apiClient.post(`/api/files/${fileId}/share`, body, { user_id });
+                const response = await apiClient.post(`/api/files/${fileId}/share`, body, reqOpts());
                 if (!response.success) {
                     logger.error('file_share API error', {
                         user_id,
@@ -2604,7 +2907,7 @@ function createToolHandlers(state) {
                 const queryParams = new URLSearchParams({ limit: String(limit), offset: String(offset) });
                 if (channel_type)
                     queryParams.set('channel_type', channel_type);
-                const response = await apiClient.get(`/api/prompt-templates?${queryParams.toString()}`, { user_id });
+                const response = await apiClient.get(`/api/prompt-templates?${queryParams.toString()}`, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message || 'Failed to list prompt templates' };
                 }
@@ -2622,7 +2925,7 @@ function createToolHandlers(state) {
         async prompt_template_get(params) {
             const { id } = params;
             try {
-                const response = await apiClient.get(`/api/prompt-templates/${id}`, { user_id });
+                const response = await apiClient.get(`/api/prompt-templates/${id}`, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message || 'Prompt template not found' };
                 }
@@ -2637,7 +2940,7 @@ function createToolHandlers(state) {
         async prompt_template_create(params) {
             const { label, content, channel_type, is_default } = params;
             try {
-                const response = await apiClient.post('/api/prompt-templates', { label, content, channel_type, is_default }, { user_id });
+                const response = await apiClient.post('/api/prompt-templates', { label, content, channel_type, is_default }, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message || 'Failed to create prompt template' };
                 }
@@ -2651,7 +2954,7 @@ function createToolHandlers(state) {
         async prompt_template_update(params) {
             const { id, ...updates } = params;
             try {
-                const response = await apiClient.put(`/api/prompt-templates/${id}`, updates, { user_id });
+                const response = await apiClient.put(`/api/prompt-templates/${id}`, updates, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message || 'Failed to update prompt template' };
                 }
@@ -2665,7 +2968,7 @@ function createToolHandlers(state) {
         async prompt_template_delete(params) {
             const { id } = params;
             try {
-                const response = await apiClient.delete(`/api/prompt-templates/${id}`, { user_id });
+                const response = await apiClient.delete(`/api/prompt-templates/${id}`, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message || 'Failed to delete prompt template' };
                 }
@@ -2689,7 +2992,7 @@ function createToolHandlers(state) {
                     queryParams.set('limit', String(limit));
                 if (offset !== undefined)
                     queryParams.set('offset', String(offset));
-                const response = await apiClient.get(`/api/inbound-destinations?${queryParams.toString()}`, { user_id });
+                const response = await apiClient.get(`/api/inbound-destinations?${queryParams.toString()}`, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message || 'Failed to list inbound destinations' };
                 }
@@ -2707,7 +3010,7 @@ function createToolHandlers(state) {
         async inbound_destination_get(params) {
             const { id } = params;
             try {
-                const response = await apiClient.get(`/api/inbound-destinations/${id}`, { user_id });
+                const response = await apiClient.get(`/api/inbound-destinations/${id}`, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message || 'Inbound destination not found' };
                 }
@@ -2731,7 +3034,7 @@ function createToolHandlers(state) {
         async inbound_destination_update(params) {
             const { id, ...updates } = params;
             try {
-                const response = await apiClient.put(`/api/inbound-destinations/${id}`, updates, { user_id });
+                const response = await apiClient.put(`/api/inbound-destinations/${id}`, updates, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message || 'Failed to update inbound destination' };
                 }
@@ -2745,7 +3048,7 @@ function createToolHandlers(state) {
         // ── Channel Default tools (Issue #1501) ──────────────────
         async channel_default_list() {
             try {
-                const response = await apiClient.get('/api/channel-defaults', { user_id });
+                const response = await apiClient.get('/api/channel-defaults', reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message || 'Failed to list channel defaults' };
                 }
@@ -2763,7 +3066,7 @@ function createToolHandlers(state) {
         async channel_default_get(params) {
             const { channel_type } = params;
             try {
-                const response = await apiClient.get(`/api/channel-defaults/${channel_type}`, { user_id });
+                const response = await apiClient.get(`/api/channel-defaults/${channel_type}`, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message || 'Channel default not found' };
                 }
@@ -2783,7 +3086,7 @@ function createToolHandlers(state) {
         async channel_default_set(params) {
             const { channel_type, agent_id, prompt_template_id, context_id } = params;
             try {
-                const response = await apiClient.put(`/api/channel-defaults/${channel_type}`, { agent_id, prompt_template_id, context_id }, { user_id });
+                const response = await apiClient.put(`/api/channel-defaults/${channel_type}`, { agent_id, prompt_template_id, context_id }, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message || 'Failed to set channel default' };
                 }
@@ -2797,7 +3100,7 @@ function createToolHandlers(state) {
         // ── Namespace management handlers (Issue #1536) ──────────────
         async namespace_list() {
             try {
-                const response = await apiClient.get('/api/namespaces', { user_id });
+                const response = await apiClient.get('/api/namespaces', reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message || 'Failed to list namespaces' };
                 }
@@ -2827,7 +3130,7 @@ function createToolHandlers(state) {
         async namespace_create(params) {
             const { name } = params;
             try {
-                const response = await apiClient.post('/api/namespaces', { name }, { user_id });
+                const response = await apiClient.post('/api/namespaces', { name }, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message || 'Failed to create namespace' };
                 }
@@ -2841,7 +3144,7 @@ function createToolHandlers(state) {
         async namespace_grant(params) {
             const { namespace, email, role, is_default } = params;
             try {
-                const response = await apiClient.post(`/api/namespaces/${encodeURIComponent(namespace)}/grants`, { email, role: role || 'member', is_default: is_default ?? false }, { user_id });
+                const response = await apiClient.post(`/api/namespaces/${encodeURIComponent(namespace)}/grants`, { email, role: role || 'member', is_default: is_default ?? false }, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message || 'Failed to grant namespace access' };
                 }
@@ -2856,7 +3159,7 @@ function createToolHandlers(state) {
         async namespace_members(params) {
             const { namespace } = params;
             try {
-                const response = await apiClient.get(`/api/namespaces/${encodeURIComponent(namespace)}`, { user_id });
+                const response = await apiClient.get(`/api/namespaces/${encodeURIComponent(namespace)}`, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message || 'Failed to list namespace members' };
                 }
@@ -2875,7 +3178,7 @@ function createToolHandlers(state) {
         async namespace_revoke(params) {
             const { namespace, grant_id } = params;
             try {
-                const response = await apiClient.delete(`/api/namespaces/${encodeURIComponent(namespace)}/grants/${encodeURIComponent(grant_id)}`, { user_id });
+                const response = await apiClient.delete(`/api/namespaces/${encodeURIComponent(namespace)}/grants/${encodeURIComponent(grant_id)}`, reqOpts());
                 if (!response.success) {
                     return { success: false, error: response.error.message || 'Failed to revoke namespace access' };
                 }
@@ -2945,8 +3248,12 @@ export const registerOpenClaw = (api) => {
         recallNamespaces: resolvedNamespace.recall,
         hasStaticRecall,
     });
+    // Extract user email from runtime context for identity resolution (#1567).
+    // The agent ID (user_id) may be a short name like "troy" which doesn't match
+    // user_setting.email. The email is needed for FK-constrained operations.
+    const user_email = context.user?.email;
     // Store plugin state
-    const state = { config, logger, apiClient, user_id, resolvedNamespace, hasStaticRecall, lastNamespaceRefreshMs: 0, refreshInFlight: false };
+    const state = { config, logger, apiClient, user_id, user_email, resolvedNamespace, hasStaticRecall, lastNamespaceRefreshMs: 0, refreshInFlight: false };
     // Create tool handlers
     const handlers = createToolHandlers(state);
     // Register all 30 tools with correct OpenClaw Gateway execute signature
@@ -3080,13 +3387,58 @@ export const registerOpenClaw = (api) => {
         },
         {
             name: 'contact_create',
-            description: 'Create a new contact. Use when the user mentions someone new to track.',
+            description: 'Create a new contact. Supports structured names (given_name, family_name) or display_name. Optionally include email, phone, tags.',
             parameters: withNamespace(contactCreateSchema),
             execute: async (_toolCallId, params, _signal, _onUpdate) => {
                 const result = await handlers.contact_create(params);
                 return toAgentToolResult(result);
             },
         },
+        {
+            name: 'contact_update',
+            description: 'Update an existing contact. Can change name, notes, tags, and other fields.',
+            parameters: withNamespace(contactUpdateSchema),
+            execute: async (_toolCallId, params, _signal, _onUpdate) => {
+                const result = await handlers.contact_update(params);
+                return toAgentToolResult(result);
+            },
+        },
+        {
+            name: 'contact_merge',
+            description: 'Merge two contacts into one. The survivor keeps all data; the loser is soft-deleted. Use when duplicate contacts are detected.',
+            parameters: withNamespace(contactMergeSchema),
+            execute: async (_toolCallId, params, _signal, _onUpdate) => {
+                const result = await handlers.contact_merge(params);
+                return toAgentToolResult(result);
+            },
+        },
+        {
+            name: 'contact_tag_add',
+            description: 'Add tags to a contact for categorization.',
+            parameters: withNamespace(contactTagAddSchema),
+            execute: async (_toolCallId, params, _signal, _onUpdate) => {
+                const result = await handlers.contact_tag_add(params);
+                return toAgentToolResult(result);
+            },
+        },
+        {
+            name: 'contact_tag_remove',
+            description: 'Remove a tag from a contact.',
+            parameters: withNamespace(contactTagRemoveSchema),
+            execute: async (_toolCallId, params, _signal, _onUpdate) => {
+                const result = await handlers.contact_tag_remove(params);
+                return toAgentToolResult(result);
+            },
+        },
+        {
+            name: 'contact_resolve',
+            description: 'Resolve a sender identity (phone, email, or name) to an existing contact. Use when an inbound message arrives and you need to identify who sent it.',
+            parameters: withNamespaces(contactResolveSchema),
+            execute: async (_toolCallId, params, _signal, _onUpdate) => {
+                const result = await handlers.contact_resolve(params);
+                return toAgentToolResult(result);
+            },
+        },
         {
             name: 'sms_send',
             description: 'Send an SMS message to a phone number. Use when you need to notify someone via text message. Requires the recipient phone number in E.164 format (e.g., +15551234567).',
@@ -3598,7 +3950,7 @@ export const registerOpenClaw = (api) => {
             .description('Show plugin status and statistics')
             .action(async () => {
             try {
-                const response = await apiClient.get('/api/health', { user_id });
+                const response = await apiClient.get('/api/health', { user_id, user_email });
                 if (response.success) {
                     console.log('Plugin Status: Connected');
                 }
@@ -3670,6 +4022,11 @@ export const schemas = {
     contactSearch: withNamespaces(contactSearchSchema),
     contactGet: withNamespaces(contactGetSchema),
     contactCreate: withNamespace(contactCreateSchema),
+    contactUpdate: withNamespace(contactUpdateSchema),
+    contactMerge: withNamespace(contactMergeSchema),
+    contactTagAdd: withNamespace(contactTagAddSchema),
+    contactTagRemove: withNamespace(contactTagRemoveSchema),
+    contactResolve: withNamespaces(contactResolveSchema),
     smsSend: smsSendSchema,
     emailSend: emailSendSchema,
     messageSearch: withNamespaces(messageSearchSchema),