@troykelly/openclaw-projects 0.0.11 → 0.0.13

package/dist/tools/todo-search.js

@@ -0,0 +1,164 @@
+/**
+ * todo_search tool implementation.
+ * Provides semantic search through work items (todos and projects).
+ * Uses the unified search API with work_item type filter.
+ * Geo-contextual ranking added in Issue #1218.
+ *
+ * Part of Issue #1216.
+ */
+import { z } from 'zod';
+import { sanitizeErrorMessage } from '../utils/sanitize.js';
+import { reverseGeocode } from '../utils/nominatim.js';
+/** Parameters for todo_search tool */
+export const TodoSearchParamsSchema = z.object({
+    query: z.string().min(1, 'Query cannot be empty').max(1000, 'Query must be 1000 characters or less'),
+    limit: z.number().int().min(1).max(50).optional(),
+    kind: z.enum(['task', 'project', 'initiative', 'epic', 'issue']).optional(),
+    status: z.string().max(50).optional(),
+    location: z.object({
+        lat: z.number().min(-90).max(90),
+        lng: z.number().min(-180).max(180),
+    }).optional(),
+});
+/**
+ * Sanitize query input to prevent injection and remove control characters.
+ */
+function sanitizeQuery(query) {
+    return query.replace(/[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]/g, '').trim();
+}
+/**
+ * Creates the todo_search tool.
+ */
+export function createTodoSearchTool(options) {
+    const { client, logger, config, userId } = options;
+    return {
+        name: 'todo_search',
+        description: 'Search todos and work items by natural language query. Uses semantic and text search to find relevant items. ' +
+            'Optionally filter by kind (task, project, initiative, epic, issue) or status. ' +
+            'Provide location (lat/lng) to boost results relevant to the current location.',
+        parameters: TodoSearchParamsSchema,
+        async execute(params) {
+            const parseResult = TodoSearchParamsSchema.safeParse(params);
+            if (!parseResult.success) {
+                const errorMessage = parseResult.error.errors.map((e) => `${e.path.join('.')}: ${e.message}`).join(', ');
+                return { success: false, error: errorMessage };
+            }
+            const { query, limit = 10, kind, status, location } = parseResult.data;
+            const sanitizedQuery = sanitizeQuery(query);
+            if (sanitizedQuery.length === 0) {
+                return { success: false, error: 'Query cannot be empty after sanitization' };
+            }
+            logger.info('todo_search invoked', {
+                userId,
+                queryLength: sanitizedQuery.length,
+                limit,
+                kind: kind ?? 'all',
+                status: status ?? 'all',
+                hasLocation: !!location,
+            });
+            try {
+                // Augment query with location context for geo-contextual ranking (Issue #1218)
+                let searchQuery = sanitizedQuery;
+                if (location && config.nominatimUrl) {
+                    try {
+                        const geo = await reverseGeocode(location.lat, location.lng, config.nominatimUrl);
+                        if (geo?.placeLabel) {
+                            const augmented = `${sanitizedQuery} near ${geo.placeLabel}`;
+                            if (augmented.length <= 1000) {
+                                searchQuery = augmented;
+                            }
+                        }
+                    }
+                    catch {
+                        logger.warn('Reverse geocode failed, proceeding without location augmentation', { userId });
+                    }
+                }
+                // Over-fetch by 3x to compensate for client-side kind/status filtering (Issue #1216 review fix)
+                const fetchLimit = (kind || status || location) ? Math.min(limit * 3, 50) : limit;
+                const queryParams = new URLSearchParams({
+                    q: searchQuery,
+                    types: 'work_item',
+                    limit: String(fetchLimit),
+                    semantic: 'true',
+                    user_email: userId, // Issue #1216: scope results to current user
+                });
+                const response = await client.get(`/api/search?${queryParams.toString()}`, { userId });
+                if (!response.success) {
+                    logger.error('todo_search API error', {
+                        userId,
+                        status: response.error.status,
+                        code: response.error.code,
+                    });
+                    return {
+                        success: false,
+                        error: response.error.message || 'Failed to search work items',
+                    };
+                }
+                let results = response.data.results ?? [];
+                // Client-side filtering by kind and status if specified, then truncate to requested limit
+                if (kind) {
+                    results = results.filter((r) => r.metadata?.kind === kind);
+                }
+                if (status) {
+                    results = results.filter((r) => r.metadata?.status === status);
+                }
+                results = results.slice(0, limit);
+                const items = results.map((r) => ({
+                    id: r.id,
+                    title: r.title,
+                    snippet: r.snippet,
+                    score: r.score,
+                    kind: r.metadata?.kind,
+                    status: r.metadata?.status,
+                }));
+                if (items.length === 0) {
+                    return {
+                        success: true,
+                        data: {
+                            content: 'No matching work items found.',
+                            details: {
+                                count: 0,
+                                results: [],
+                                searchType: response.data.search_type,
+                                userId,
+                            },
+                        },
+                    };
+                }
+                const content = items
+                    .map((item) => {
+                    const kindStr = item.kind ? `[${item.kind}]` : '';
+                    const statusStr = item.status ? ` (${item.status})` : '';
+                    const snippetStr = item.snippet ? ` - ${item.snippet}` : '';
+                    return `- ${kindStr} **${item.title}**${statusStr}${snippetStr}`;
+                })
+                    .join('\n');
+                logger.debug('todo_search completed', {
+                    userId,
+                    resultCount: items.length,
+                    searchType: response.data.search_type,
+                });
+                return {
+                    success: true,
+                    data: {
+                        content,
+                        details: {
+                            count: items.length,
+                            results: items,
+                            searchType: response.data.search_type,
+                            userId,
+                        },
+                    },
+                };
+            }
+            catch (error) {
+                logger.error('todo_search failed', {
+                    userId,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+                return { success: false, error: sanitizeErrorMessage(error) };
+            }
+        },
+    };
+}
+//# sourceMappingURL=todo-search.js.map

package/dist/tools/todo-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"todo-search.js","sourceRoot":"","sources":["../../src/tools/todo-search.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB,OAAO,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAC5D,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAEvD,sCAAsC;AACtC,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC7C,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,uBAAuB,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,uCAAuC,CAAC;IACpG,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;IACjD,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,SAAS,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,QAAQ,EAAE;IAC3E,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,QAAQ,EAAE;IACrC,QAAQ,EAAE,CAAC,CAAC,MAAM,CAAC;QACjB,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;QAChC,GAAG,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC;KACnC,CAAC,CAAC,QAAQ,EAAE;CACd,CAAC,CAAC;AAmDH;;GAEG;AACH,SAAS,aAAa,CAAC,KAAa;IAClC,OAAO,KAAK,CAAC,OAAO,CAAC,mCAAmC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AACvE,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAA8B;IACjE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;IAEnD,OAAO;QACL,IAAI,EAAE,aAAa;QACnB,WAAW,EACT,+GAA+G;YAC/G,gFAAgF;YAChF,+EAA+E;QACjF,UAAU,EAAE,sBAAsB;QAElC,KAAK,CAAC,OAAO,CAAC,MAAwB;YACpC,MAAM,WAAW,GAAG,sBAAsB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;YAC7D,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,CAAC;gBACzB,MAAM,YAAY,GAAG,WAAW,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;gBACzG,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,CAAC;YACjD,CAAC;YAED,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,WAAW,CAAC,IAAI,CAAC;YAEvE,MAAM,cAAc,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;YAC5C,IAAI,cAAc,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAChC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,0CAA0C,EAAE,CAAC;YAC/E,CAAC;YAED,MAAM,CAAC,IAAI,CAAC,qBAAqB,EAAE;gBACjC,MAAM;gBACN,WAAW,EAAE,cAAc,CAAC,MAAM;gBAClC,KAAK;gBACL,IAAI,EAAE,IAAI,IAAI,KAAK;gBACnB,MAAM,EAAE,MAAM,IAAI,KAAK;gBACvB,WAAW,EAAE,CAAC,CAAC,QAAQ;aACxB,CAAC,CAAC;YAEH,IAAI,CAAC;gBACH,+EAA+E;gBAC/E,IAAI,WAAW,GAAG,cAAc,CAAC;gBACjC,IAAI,QAAQ,IAAI,MAAM,CAAC,YAAY,EAAE,CAAC;oBACpC,IAAI,CAAC;wBACH,MAAM,GAAG,GAAG,MAAM,cAAc,CAAC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;wBAClF,IAAI,GAAG,EAAE,UAAU,EAAE,CAAC;4BACpB,MAAM,SAAS,GAAG,GAAG,cAAc,SAAS,GAAG,CAAC,UAAU,EAAE,CAAC;4BAC7D,IAAI,SAAS,CAAC,MAAM,IAAI,IAAI,EAAE,CAAC;gCAC7B,WAAW,GAAG,SAAS,CAAC;4BAC1B,CAAC;wBACH,CAAC;oBACH,CAAC;oBAAC,MAAM,CAAC;wBACP,MAAM,CAAC,IAAI,CAAC,kEAAkE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;oBAC9F,CAAC;gBACH,CAAC;gBAED,gGAAgG;gBAChG,MAAM,UAAU,GAAG,CAAC,IAAI,IAAI,MAAM,IAAI,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC;gBAElF,MAAM,WAAW,GAAG,IAAI,eAAe,CAAC;oBACtC,CAAC,EAAE,WAAW;oBACd,KAAK,EAAE,WAAW;oBAClB,KAAK,EAAE,MAAM,CAAC,UAAU,CAAC;oBACzB,QAAQ,EAAE,MAAM;oBAChB,UAAU,EAAE,MAAM,EAAE,6CAA6C;iBAClE,CAAC,CAAC;gBAEH,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,GAAG,CAW9B,eAAe,WAAW,CAAC,QAAQ,EAAE,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC,CAAC;gBAExD,IAAI,CAAC,QAAQ,CAAC,OAAO,EAAE,CAAC;oBACtB,MAAM,CAAC,KAAK,CAAC,uBAAuB,EAAE;wBACpC,MAAM;wBACN,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,MAAM;wBAC7B,IAAI,EAAE,QAAQ,CAAC,KAAK,CAAC,IAAI;qBAC1B,CAAC,CAAC;oBACH,OAAO;wBACL,OAAO,EAAE,KAAK;wBACd,KAAK,EAAE,QAAQ,CAAC,KAAK,CAAC,OAAO,IAAI,6BAA6B;qBAC/D,CAAC;gBACJ,CAAC;gBAED,IAAI,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;gBAE1C,0FAA0F;gBAC1F,IAAI,IAAI,EAAE,CAAC;oBACT,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,IAAI,KAAK,IAAI,CAAC,CAAC;gBAC7D,CAAC;gBACD,IAAI,MAAM,EAAE,CAAC;oBACX,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,CAAC,CAAC;gBACjE,CAAC;gBACD,OAAO,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;gBAElC,MAAM,KAAK,GAAqB,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;oBAClD,EAAE,EAAE,CAAC,CAAC,EAAE;oBACR,KAAK,EAAE,CAAC,CAAC,KAAK;oBACd,OAAO,EAAE,CAAC,CAAC,OAAO;oBAClB,KAAK,EAAE,CAAC,CAAC,KAAK;oBACd,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,IAAI;oBACtB,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM;iBAC3B,CAAC,CAAC,CAAC;gBAEJ,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;oBACvB,OAAO;wBACL,OAAO,EAAE,IAAI;wBACb,IAAI,EAAE;4BACJ,OAAO,EAAE,+BAA+B;4BACxC,OAAO,EAAE;gCACP,KAAK,EAAE,CAAC;gCACR,OAAO,EAAE,EAAE;gCACX,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,WAAW;gCACrC,MAAM;6BACP;yBACF;qBACF,CAAC;gBACJ,CAAC;gBAED,MAAM,OAAO,GAAG,KAAK;qBAClB,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;oBACZ,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;oBAClD,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;oBACzD,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;oBAC5D,OAAO,KAAK,OAAO,MAAM,IAAI,CAAC,KAAK,KAAK,SAAS,GAAG,UAAU,EAAE,CAAC;gBACnE,CAAC,CAAC;qBACD,IAAI,CAAC,IAAI,CAAC,CAAC;gBAEd,MAAM,CAAC,KAAK,CAAC,uBAAuB,EAAE;oBACpC,MAAM;oBACN,WAAW,EAAE,KAAK,CAAC,MAAM;oBACzB,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,WAAW;iBACtC,CAAC,CAAC;gBAEH,OAAO;oBACL,OAAO,EAAE,IAAI;oBACb,IAAI,EAAE;wBACJ,OAAO;wBACP,OAAO,EAAE;4BACP,KAAK,EAAE,KAAK,CAAC,MAAM;4BACnB,OAAO,EAAE,KAAK;4BACd,UAAU,EAAE,QAAQ,CAAC,IAAI,CAAC,WAAW;4BACrC,MAAM;yBACP;qBACF;iBACF,CAAC;YACJ,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,CAAC,KAAK,CAAC,oBAAoB,EAAE;oBACjC,MAAM;oBACN,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;iBAC9D,CAAC,CAAC;gBACH,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,oBAAoB,CAAC,KAAK,CAAC,EAAE,CAAC;YAChE,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/types/openclaw-api.d.ts

@@ -125,6 +125,21 @@ export interface PluginHookBeforeAgentStartResult {
     /** Prepend to conversation context */
     prependContext?: string;
 }
+/** Event payload for message_received hook (Issue #1223) */
+export interface PluginHookMessageReceivedEvent {
+    /** Thread ID for the message */
+    threadId?: string;
+    /** Sender identifier (email or phone) */
+    sender?: string;
+    /** Sender email address */
+    senderEmail?: string;
+    /** Sender phone number */
+    senderPhone?: string;
+    /** Message body content */
+    content?: string;
+    /** Channel the message was received on (sms, email, etc.) */
+    channel?: string;
+}
 /** Event payload for agent_end hook */
 export interface PluginHookAgentEndEvent {
     /** Full conversation messages */

package/dist/types/openclaw-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"openclaw-api.d.ts","sourceRoot":"","sources":["../../src/types/openclaw-api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C,sCAAsC;AACtC,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAChD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,CAAC,EAAE,OAAO,GAAG,UAAU,CAAC;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,UAAU,GAAG,kBAAkB,CAAC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;IAChD,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,6BAA6B;AAC7B,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,+DAA+D;AAC/D,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE;QACL,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC,CAAC;IACF,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAChD;AAED;;;;;;;GAOG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CAC1D,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,CAAC,EACT,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,KAClC,OAAO,CAAC,eAAe,CAAC,CAAC;AAE9B;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,6BAA6B;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,iDAAiD;IACjD,WAAW,EAAE,MAAM,CAAC;IACpB,sCAAsC;IACtC,UAAU,EAAE,UAAU,CAAC;IACvB,2DAA2D;IAC3D,OAAO,EAAE,gBAAgB,CAAC;CAC3B;AASD;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB,oBAAoB,GACpB,WAAW,GACX,mBAAmB,GACnB,kBAAkB,GAClB,kBAAkB,GAClB,iBAAiB,GACjB,cAAc,GACd,kBAAkB,GAClB,iBAAiB,GACjB,qBAAqB,GACrB,eAAe,GACf,aAAa,GACb,eAAe,GACf,cAAc,CAAC;AAEnB,gDAAgD;AAChD,MAAM,WAAW,+BAA+B;IAC9C,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,QAAQ,CAAC,EAAE,OAAO,EAAE,CAAC;CACtB;AAED,yDAAyD;AACzD,MAAM,WAAW,sBAAsB;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,gDAAgD;AAChD,MAAM,WAAW,gCAAgC;IAC/C,kCAAkC;IAClC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,sCAAsC;IACtC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,uCAAuC;AACvC,MAAM,WAAW,uBAAuB;IACtC,iCAAiC;IACjC,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAID,0CAA0C;AAC1C,MAAM,MAAM,SAAS,GACjB,kBAAkB,GAClB,iBAAiB,GACjB,gBAAgB,GAChB,UAAU,GACV,gBAAgB,GAChB,eAAe,GACf,iBAAiB,GACjB,aAAa,CAAC;AAElB,mCAAmC;AACnC,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,OAAO,IAAI,CAAC,KAAK,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;AAEnF,gCAAgC;AAChC,MAAM,WAAW,sBAAsB;IACrC,iCAAiC;IACjC,OAAO,EAAE;QACP,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;YACzB,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK;gBAC7B,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;gBACjD,MAAM,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC;aAC5E,CAAC;SACH,CAAC;KACH,CAAC;CACH;AAED,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,EAAE,sBAAsB,KAAK,IAAI,CAAC;AAEhF,kDAAkD;AAClD,MAAM,WAAW,iBAAiB;IAChC,wBAAwB;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,gCAAgC;IAChC,KAAK,EAAE,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,+BAA+B;IAC/B,IAAI,EAAE,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACxD;AAED,8CAA8C;AAC9C,MAAM,WAAW,iBAAiB;IAChC,0CAA0C;IAC1C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEhC,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAEvC,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IAEf,gBAAgB;IAChB,QAAQ,EAAE,MAAM,CAAC;IAEjB,wBAAwB;IACxB,OAAO,CAAC,EAAE;QACR,GAAG,CAAC,EAAE;YACJ,qBAAqB,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE;gBAAE,KAAK,CAAC,EAAE,MAAM,CAAA;aAAE,KAAK,OAAO,CAAC;gBAAE,GAAG,EAAE,MAAM,CAAC;gBAAC,UAAU,EAAE,MAAM,CAAA;aAAE,CAAC,CAAC;SACrH,CAAC;KACH,CAAC;IAEF;;;OAGG;IACH,YAAY,EAAE,CAAC,IAAI,EAAE,cAAc,KAAK,IAAI,CAAC;IAE7C;;;;;;;;OAQG;IACH,EAAE,CAAC,EAAE,CAAC,CAAC,SAAS,cAAc,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,OAAO,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAC;IAE7H;;;;;OAKG;IACH,YAAY,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;IAE/E;;;OAGG;IACH,WAAW,EAAE,CAAC,QAAQ,EAAE,uBAAuB,KAAK,IAAI,CAAC;IAEzD;;;OAGG;IACH,eAAe,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,IAAI,CAAC;IAEtD;;;OAGG;IACH,qBAAqB,EAAE,CAAC,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;CACnH;AAED,+CAA+C;AAC/C,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,iBAAiB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEjF,sEAAsE;AACtE,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B,QAAQ,EAAE,iBAAiB,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,iBAAiB,CAAC"}
+{"version":3,"file":"openclaw-api.d.ts","sourceRoot":"","sources":["../../src/types/openclaw-api.ts"],"names":[],"mappings":"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"}

package/dist/utils/auto-linker.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Auto-linker utility for inbound messages (Issue #1223).
+ *
+ * Automatically creates entity links when inbound SMS/email arrives:
+ * 1. Sender -> Contact matching: matches sender email/phone to existing contacts
+ * 2. Content -> Project/Todo matching: semantic search for related work items
+ *    (only runs when sender is a known contact — safety decision to prevent
+ *    untrusted senders from creating spurious links)
+ *
+ * Links are created via the skill_store API using the same pattern as
+ * entity-links.ts tools. All operations are failure-isolated so that
+ * auto-linking never crashes inbound message processing.
+ */
+import type { ApiClient } from '../api-client.js';
+import type { Logger } from '../logger.js';
+/** Default similarity threshold for content matching */
+export declare const DEFAULT_SIMILARITY_THRESHOLD = 0.75;
+/** Inbound message data for auto-linking */
+export interface AutoLinkMessage {
+    /** Thread ID (UUID) for the inbound message thread */
+    threadId: string;
+    /** Sender email address, if known */
+    senderEmail?: string;
+    /** Sender phone number, if known */
+    senderPhone?: string;
+    /** Message body content */
+    content: string;
+}
+/** Options for the auto-link function */
+export interface AutoLinkOptions {
+    /** API client for backend calls */
+    client: ApiClient;
+    /** Logger instance */
+    logger: Logger;
+    /** User ID for scoping API calls */
+    userId: string;
+    /** Inbound message data */
+    message: AutoLinkMessage;
+    /** Similarity threshold for content matching (default: 0.75) */
+    similarityThreshold?: number;
+}
+/** Result of auto-linking */
+export interface AutoLinkResult {
+    /** Number of entity links created */
+    linksCreated: number;
+    /** IDs of matched entities by type */
+    matches: {
+        contacts: string[];
+        projects: string[];
+        todos: string[];
+    };
+}
+/**
+ * Auto-link an inbound message to related entities.
+ *
+ * Performs sender matching first. Content matching only runs when at least
+ * one contact matched — this prevents untrusted/unknown senders from
+ * creating spurious links to projects and todos.
+ *
+ * Never throws - all errors are caught and logged.
+ *
+ * @param options - Auto-link configuration and message data
+ * @returns Summary of links created and entities matched
+ */
+export declare function autoLinkInboundMessage(options: AutoLinkOptions): Promise<AutoLinkResult>;
+//# sourceMappingURL=auto-linker.d.ts.map

package/dist/utils/auto-linker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-linker.d.ts","sourceRoot":"","sources":["../../src/utils/auto-linker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAM3C,wDAAwD;AACxD,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAmBjD,4CAA4C;AAC5C,MAAM,WAAW,eAAe;IAC9B,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,qCAAqC;IACrC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oCAAoC;IACpC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,yCAAyC;AACzC,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,MAAM,EAAE,SAAS,CAAC;IAClB,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,oCAAoC;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,2BAA2B;IAC3B,OAAO,EAAE,eAAe,CAAC;IACzB,gEAAgE;IAChE,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,6BAA6B;AAC7B,MAAM,WAAW,cAAc;IAC7B,qCAAqC;IACrC,YAAY,EAAE,MAAM,CAAC;IACrB,sCAAsC;IACtC,OAAO,EAAE;QACP,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,KAAK,EAAE,MAAM,EAAE,CAAC;KACjB,CAAC;CACH;AA+XD;;;;;;;;;;;GAWG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CA6F9F"}

package/dist/utils/auto-linker.js

@@ -0,0 +1,354 @@
+/**
+ * Auto-linker utility for inbound messages (Issue #1223).
+ *
+ * Automatically creates entity links when inbound SMS/email arrives:
+ * 1. Sender -> Contact matching: matches sender email/phone to existing contacts
+ * 2. Content -> Project/Todo matching: semantic search for related work items
+ *    (only runs when sender is a known contact — safety decision to prevent
+ *    untrusted senders from creating spurious links)
+ *
+ * Links are created via the skill_store API using the same pattern as
+ * entity-links.ts tools. All operations are failure-isolated so that
+ * auto-linking never crashes inbound message processing.
+ */
+import { sanitizeExternalMessage } from './injection-protection.js';
+import { sanitizeErrorMessage } from './sanitize.js';
+// ==================== Constants ====================
+/** Default similarity threshold for content matching */
+export const DEFAULT_SIMILARITY_THRESHOLD = 0.75;
+/** Skill ID for entity link storage (matches entity-links.ts) */
+const SKILL_ID = 'entity-links';
+/** Collection name for entity links (matches entity-links.ts) */
+const COLLECTION = 'entity_links';
+/** Maximum content length to send to search API */
+const MAX_SEARCH_QUERY_LENGTH = 500;
+/** Work item kinds that map to "project" in results */
+const PROJECT_KINDS = new Set(['project']);
+/** Work item kinds that map to "todo" in results */
+const TODO_KINDS = new Set(['task', 'issue', 'epic', 'initiative']);
+// ==================== Helpers ====================
+/**
+ * Build a URI-style thread reference for use as target_ref.
+ * Uses 'url' entity type since the entity-links schema has a fixed enum
+ * and does not yet include a 'message_thread' type.
+ * TODO(#1223): Add a proper 'message_thread' entity type to entity-links schema.
+ */
+function buildThreadRef(threadId) {
+    return `thread:${threadId}`;
+}
+/**
+ * Build a composite key for a link (matches entity-links.ts pattern).
+ */
+function buildLinkKey(sourceType, sourceRef, targetType, targetRef) {
+    return `${sourceType}:${sourceRef}:${targetType}:${targetRef}`;
+}
+/**
+ * Build a tag for source-entity lookup (matches entity-links.ts pattern).
+ */
+function buildSourceTag(entityType, entityRef) {
+    return `src:${entityType}:${entityRef}`;
+}
+/**
+ * Create a bidirectional entity link via skill_store.
+ * Returns true if both directions were created successfully.
+ */
+async function createEntityLink(client, userId, logger, sourceType, sourceId, targetType, targetRef, label) {
+    const now = new Date().toISOString();
+    const forwardKey = buildLinkKey(sourceType, sourceId, targetType, targetRef);
+    const reverseKey = buildLinkKey(targetType, targetRef, sourceType, sourceId);
+    const forwardData = {
+        source_type: sourceType,
+        source_id: sourceId,
+        target_type: targetType,
+        target_ref: targetRef,
+        label: label ?? null,
+        created_at: now,
+        auto_linked: true,
+    };
+    const reverseData = {
+        source_type: targetType,
+        source_id: targetRef,
+        target_type: sourceType,
+        target_ref: sourceId,
+        label: label ?? null,
+        created_at: now,
+        auto_linked: true,
+    };
+    // Create forward link
+    const forwardResponse = await client.post('/api/skill-store/items', {
+        skill_id: SKILL_ID,
+        collection: COLLECTION,
+        key: forwardKey,
+        data: forwardData,
+        tags: [buildSourceTag(sourceType, sourceId)],
+    }, { userId });
+    if (!forwardResponse.success) {
+        logger.error('auto-linker: forward link creation failed', {
+            userId,
+            sourceType,
+            targetType,
+            status: forwardResponse.error.status,
+        });
+        return false;
+    }
+    // Create reverse link
+    const reverseResponse = await client.post('/api/skill-store/items', {
+        skill_id: SKILL_ID,
+        collection: COLLECTION,
+        key: reverseKey,
+        data: reverseData,
+        tags: [buildSourceTag(targetType, targetRef)],
+    }, { userId });
+    if (!reverseResponse.success) {
+        logger.error('auto-linker: reverse link creation failed', {
+            userId,
+            sourceType,
+            targetType,
+            status: reverseResponse.error.status,
+        });
+        // Best-effort rollback of orphaned forward link
+        const rollbackResponse = await client.delete(`/api/skill-store/items/${forwardResponse.data.id}`, { userId });
+        if (!rollbackResponse.success) {
+            logger.error('auto-linker: rollback of orphaned forward link failed — partial state', {
+                userId,
+                forwardId: forwardResponse.data.id,
+                rollbackStatus: rollbackResponse.error.status,
+            });
+        }
+        return false;
+    }
+    return true;
+}
+// ==================== Sender matching ====================
+/**
+ * Search for contacts matching the sender's email and/or phone.
+ * Searches both identifiers separately when both are present,
+ * then deduplicates matched contact IDs.
+ * Returns matched contact IDs and creates links for each match.
+ */
+async function matchSenderToContacts(client, logger, userId, threadId, senderEmail, senderPhone) {
+    if (!senderEmail && !senderPhone) {
+        return [];
+    }
+    // Search both email and phone separately to catch all matches
+    const searchQueries = [];
+    if (senderEmail)
+        searchQueries.push(senderEmail);
+    if (senderPhone)
+        searchQueries.push(senderPhone);
+    // Collect all contacts from all searches
+    const allContacts = [];
+    for (const searchQuery of searchQueries) {
+        const queryParams = new URLSearchParams({
+            search: searchQuery,
+            limit: '5',
+            user_email: userId,
+        });
+        const response = await client.get(`/api/contacts?${queryParams.toString()}`, { userId });
+        if (!response.success) {
+            logger.error('auto-linker: contact search failed', {
+                userId,
+                status: response.error.status,
+                code: response.error.code,
+            });
+            continue;
+        }
+        const contacts = response.data.contacts ?? response.data.items ?? [];
+        allContacts.push(...contacts);
+    }
+    if (allContacts.length === 0) {
+        return [];
+    }
+    // Filter to exact matches on email or phone, deduplicate by ID
+    const seen = new Set();
+    const matchedContacts = [];
+    for (const c of allContacts) {
+        if (seen.has(c.id))
+            continue;
+        const emailMatch = senderEmail != null && c.email?.toLowerCase() === senderEmail.toLowerCase();
+        const phoneMatch = senderPhone != null && c.phone === senderPhone;
+        if (emailMatch || phoneMatch) {
+            seen.add(c.id);
+            matchedContacts.push(c);
+        }
+    }
+    const threadRef = buildThreadRef(threadId);
+    const linkedContactIds = [];
+    for (const contact of matchedContacts) {
+        try {
+            // Use 'url' type with thread: URI since entity-links schema does not have
+            // a 'message_thread' type yet. See buildThreadRef() for details.
+            const linked = await createEntityLink(client, userId, logger, 'contact', contact.id, 'url', threadRef, 'inbound-message-sender');
+            if (linked) {
+                linkedContactIds.push(contact.id);
+            }
+        }
+        catch (error) {
+            logger.error('auto-linker: failed to create contact link', {
+                userId,
+                contactId: contact.id,
+                error: sanitizeErrorMessage(error),
+            });
+        }
+    }
+    return linkedContactIds;
+}
+// ==================== Content matching ====================
+/**
+ * Search for projects and todos matching the message content.
+ * Returns matched entity IDs by type and creates links for each match.
+ */
+async function matchContentToWorkItems(client, logger, userId, threadId, content, similarityThreshold) {
+    // Sanitize external content before using it in search queries.
+    // Removes control characters, unicode invisibles, and potential injection payloads.
+    const sanitizedContent = sanitizeExternalMessage(content);
+    if (sanitizedContent.length === 0) {
+        return { projects: [], todos: [] };
+    }
+    // Truncate for search
+    const searchQuery = sanitizedContent.substring(0, MAX_SEARCH_QUERY_LENGTH);
+    const queryParams = new URLSearchParams({
+        q: searchQuery,
+        types: 'work_item',
+        limit: '10',
+        semantic: 'true',
+        user_email: userId,
+    });
+    const response = await client.get(`/api/search?${queryParams.toString()}`, { userId });
+    if (!response.success) {
+        logger.error('auto-linker: content search failed', {
+            userId,
+            status: response.error.status,
+            code: response.error.code,
+        });
+        return { projects: [], todos: [] };
+    }
+    const results = response.data.results ?? [];
+    // Filter to items above the similarity threshold
+    const highConfidenceResults = results.filter((r) => r.score >= similarityThreshold);
+    if (highConfidenceResults.length === 0) {
+        logger.debug('auto-linker: no content matches above threshold', {
+            userId,
+            threshold: similarityThreshold,
+            totalResults: results.length,
+            topScore: results[0]?.score ?? 0,
+        });
+        return { projects: [], todos: [] };
+    }
+    const threadRef = buildThreadRef(threadId);
+    const linkedProjects = [];
+    const linkedTodos = [];
+    for (const item of highConfidenceResults) {
+        const kind = item.metadata?.kind;
+        const isProject = kind !== undefined && PROJECT_KINDS.has(kind);
+        const isTodo = kind !== undefined && TODO_KINDS.has(kind);
+        if (!isProject && !isTodo) {
+            continue;
+        }
+        const sourceType = isProject ? 'project' : 'todo';
+        try {
+            // Use 'url' type with thread: URI since entity-links schema does not have
+            // a 'message_thread' type yet. See buildThreadRef() for details.
+            const linked = await createEntityLink(client, userId, logger, sourceType, item.id, 'url', threadRef, `auto-linked:${item.title.substring(0, 50)}`);
+            if (linked) {
+                if (isProject) {
+                    linkedProjects.push(item.id);
+                }
+                else {
+                    linkedTodos.push(item.id);
+                }
+            }
+        }
+        catch (error) {
+            logger.error('auto-linker: failed to create work item link', {
+                userId,
+                itemId: item.id,
+                itemKind: kind,
+                error: sanitizeErrorMessage(error),
+            });
+        }
+    }
+    return { projects: linkedProjects, todos: linkedTodos };
+}
+// ==================== Main function ====================
+/**
+ * Auto-link an inbound message to related entities.
+ *
+ * Performs sender matching first. Content matching only runs when at least
+ * one contact matched — this prevents untrusted/unknown senders from
+ * creating spurious links to projects and todos.
+ *
+ * Never throws - all errors are caught and logged.
+ *
+ * @param options - Auto-link configuration and message data
+ * @returns Summary of links created and entities matched
+ */
+export async function autoLinkInboundMessage(options) {
+    const { client, logger, userId, message, similarityThreshold = DEFAULT_SIMILARITY_THRESHOLD, } = options;
+    const emptyResult = {
+        linksCreated: 0,
+        matches: { contacts: [], projects: [], todos: [] },
+    };
+    try {
+        logger.info('auto-linker: processing inbound message', {
+            userId,
+            threadId: message.threadId,
+            hasSenderEmail: !!message.senderEmail,
+            hasSenderPhone: !!message.senderPhone,
+            contentLength: message.content.length,
+        });
+        // Step 1: Sender matching — always runs when sender info is available
+        const contactMatches = await matchSenderToContacts(client, logger, userId, message.threadId, message.senderEmail, message.senderPhone).catch((error) => {
+            logger.error('auto-linker: sender matching failed', {
+                userId,
+                error: sanitizeErrorMessage(error),
+            });
+            return [];
+        });
+        // Step 2: Content matching — only runs when sender is a known contact.
+        // Safety decision: untrusted/unknown senders should not trigger content-based
+        // linking to prevent spam or malicious messages from creating spurious links
+        // to the user's projects and todos.
+        let contentMatches = { projects: [], todos: [] };
+        if (contactMatches.length > 0) {
+            contentMatches = await matchContentToWorkItems(client, logger, userId, message.threadId, message.content, similarityThreshold).catch((error) => {
+                logger.error('auto-linker: content matching failed', {
+                    userId,
+                    error: sanitizeErrorMessage(error),
+                });
+                return { projects: [], todos: [] };
+            });
+        }
+        else {
+            logger.debug('auto-linker: skipping content matching — no known sender contact', {
+                userId,
+                threadId: message.threadId,
+            });
+        }
+        const result = {
+            linksCreated: contactMatches.length + contentMatches.projects.length + contentMatches.todos.length,
+            matches: {
+                contacts: contactMatches,
+                projects: contentMatches.projects,
+                todos: contentMatches.todos,
+            },
+        };
+        logger.info('auto-linker: completed', {
+            userId,
+            threadId: message.threadId,
+            linksCreated: result.linksCreated,
+            contactMatches: result.matches.contacts.length,
+            projectMatches: result.matches.projects.length,
+            todoMatches: result.matches.todos.length,
+        });
+        return result;
+    }
+    catch (error) {
+        logger.error('auto-linker: unexpected failure', {
+            userId,
+            error: sanitizeErrorMessage(error),
+        });
+        return emptyResult;
+    }
+}
+//# sourceMappingURL=auto-linker.js.map