@sendinel/mcp-server 1.0.188 → 1.0.190

package/build/lib/how-to-recipes.js

@@ -1,5 +1,6 @@
 /** Hand-written workflows, checked against the registered schemas in CI (#4061). */
 import { SEGMENT_OPERATORS_DESCRIPTION } from '@sendinel/domain';
+import { ADMIN_TOOLS } from './admin-tools.js';
 import { rankTools, scoreTool, tokenize, TOOL_ALIASES } from '../tools/tool-search.js';
 const approval = { required: true, how: 'returns approve_url; re-call with approval_id' };
 const from = (n, field) => `<from step ${n}: ${field}>`;
@@ -244,7 +245,9 @@ export function matchRecipes(goal, limit = 3, available = HOW_TO_RECIPES, tools
         .filter(({ score }) => score > 0).sort((a, b) => b.score - a.score || a.order - b.order);
     const selected = scored.slice(0, Math.max(1, Math.min(10, Math.trunc(limit))));
     const returned = new Set(selected.map(({ entry }) => entry.name));
-    const candidates = [...entries.filter((e) => !returned.has(e.name)), ...tools];
+    const allowAdminTools = selected.some(({ entry: { recipe } }) => recipe.requires.scopes.includes('admin'));
+    const candidateTools = allowAdminTools ? tools : tools.filter((tool) => !ADMIN_TOOLS.has(tool.name));
+    const candidates = [...entries.filter((e) => !returned.has(e.name)), ...candidateTools];
     const suggestions = rankTools(candidates, goal, { aliases: { ...TOOL_ALIASES, ...aliases }, nearestLimit: 5 });
     const also_try = [...new Set([...suggestions.matches, ...suggestions.nearest].map(({ entry }) => entry.name))].slice(0, 5);
     if (!also_try.length && !selected.length)

package/build/tools/ai-work.js

@@ -1,8 +1,9 @@
 import { createHash } from 'node:crypto';
 import { z } from 'zod';
+import { AI_WORK_ITEM_STATUSES } from '@sendinel/domain';
 import { db } from '../db.js';
 import { getProjectId } from '../project.js';
-import { dbToolError } from '../lib/db-error.js';
+import { dbToolError, toolError } from '../lib/db-error.js';
 const txt = (text) => ({ content: [{ type: 'text', text }] });
 const j = (data) => txt(JSON.stringify(data, null, 2));
 const workItemSelect = [
@@ -47,32 +48,67 @@ const proposalSelect = [
     'generated_by',
     'llm_model',
 ].join(', ');
-const workStatusSchema = z.enum(['new', 'seen', 'accepted', 'dismissed', 'snoozed', 'resolved', 'failed']);
 const activeStatuses = ['new', 'seen', 'snoozed'];
 const contextEventTypes = ['strategic_segment_intent', 'business_priority', 'customer_journey_signal', 'campaign_opportunity', 'risk_signal'];
 const contextEventInput = {
-    workspace_id: z.string().min(1).max(255),
+    workspace_id: z.string().trim().min(1).max(255),
     event_type: z.enum(contextEventTypes),
-    title: z.string().min(1).max(255),
-    detail: z.string().min(1).max(4000),
+    title: z.string().trim().min(1).max(255),
+    detail: z.string().trim().min(1).max(4000),
     evidence: z.record(z.string(), z.unknown()).optional(),
     suggested_actions: z.array(z.record(z.string(), z.unknown())).optional(),
-    idempotency_key: z.string().min(1).max(255),
+    idempotency_key: z.string().trim().min(1).max(255),
 };
 function parseStatuses(status) {
-    if (!status)
-        return [...activeStatuses];
-    const requested = status.split(',').map((item) => item.trim()).filter(Boolean);
-    const valid = requested.filter((item) => workStatusSchema.safeParse(item).success);
-    return valid.length ? valid : [...activeStatuses];
+    if (status === undefined)
+        return { statuses: [...activeStatuses] };
+    const rawParts = status.split(',').map((item) => item.trim());
+    if (rawParts.length === 0 || (rawParts.length === 1 && rawParts[0] === '')) {
+        return {
+            error: {
+                code: 'validation_failed',
+                error: `Invalid status "${status}". Allowed values: ${AI_WORK_ITEM_STATUSES.join(', ')}`,
+            },
+        };
+    }
+    const invalid = rawParts.filter((item) => !AI_WORK_ITEM_STATUSES.includes(item));
+    if (invalid.length > 0) {
+        return {
+            error: {
+                code: 'validation_failed',
+                error: `Invalid status "${invalid.join(', ')}". Allowed values: ${AI_WORK_ITEM_STATUSES.join(', ')}`,
+            },
+        };
+    }
+    return { statuses: [...new Set(rawParts)] };
 }
 async function updateWorkItemStatus(id, status, snoozedUntil) {
+    const { data: existing, error: existingErr } = await db()
+        .from('ai_work_items')
+        .select(workItemSelect)
+        .eq('project_id', getProjectId())
+        .eq('id', id)
+        .maybeSingle();
+    if (existingErr)
+        return toolError(dbToolError(existingErr));
+    if (!existing)
+        return toolError({ code: 'not_found', error: 'AI work item not found.' });
+    if (status === 'seen') {
+        // #4558: a read receipt must not undo a dismissal or other non-new status
+        if (existing.status !== 'new') {
+            return j({ work_item: existing });
+        }
+    }
     const updates = { status };
     if (status === 'dismissed')
         updates.dismissed_at = new Date().toISOString();
     if (status === 'snoozed') {
         if (!snoozedUntil)
-            return { error: 'snoozed_until is required.' };
+            return toolError({ code: 'validation_failed', error: 'snoozed_until is required.' });
+        const snoozedTime = new Date(snoozedUntil).getTime();
+        if (!Number.isFinite(snoozedTime) || snoozedTime <= Date.now()) {
+            return toolError({ code: 'validation_failed', error: 'snoozed_until must be in the future.' });
+        }
         updates.snoozed_until = snoozedUntil;
     }
     else {
@@ -86,10 +122,10 @@ async function updateWorkItemStatus(id, status, snoozedUntil) {
         .select(workItemSelect)
         .maybeSingle();
     if (error)
-        return { ...dbToolError(error) };
+        return toolError(dbToolError(error));
     if (!data)
-        return { error: 'AI work item not found.' };
-    return { work_item: data };
+        return toolError({ code: 'not_found', error: 'AI work item not found.' });
+    return j({ work_item: data });
 }
 function stableUuid(input) {
     const hex = createHash('sha256').update(input).digest('hex').slice(0, 32);
@@ -121,33 +157,87 @@ function segmentActionFromContext(eventType, suggestedActions, title, detail) {
         rules: action.rules,
     };
 }
+function isSameContextEventPayload(existing, input) {
+    if (existing.workspace_id !== input.workspace_id.trim())
+        return false;
+    if (existing.event_type !== input.event_type)
+        return false;
+    if (existing.title !== input.title.trim())
+        return false;
+    if (existing.detail !== input.detail.trim())
+        return false;
+    const existingEvidence = existing.evidence && typeof existing.evidence === 'object' ? existing.evidence : {};
+    const inputEvidence = input.evidence && typeof input.evidence === 'object' ? input.evidence : {};
+    if (JSON.stringify(existingEvidence) !== JSON.stringify(inputEvidence))
+        return false;
+    const existingActions = Array.isArray(existing.suggested_actions) ? existing.suggested_actions : [];
+    const inputActions = Array.isArray(input.suggested_actions) ? input.suggested_actions : [];
+    if (JSON.stringify(existingActions) !== JSON.stringify(inputActions))
+        return false;
+    return true;
+}
+async function buildContextReplay(projectId, event) {
+    let workItem = null;
+    if (event.work_item_id) {
+        const { data } = await db()
+            .from('ai_work_items')
+            .select(workItemSelect)
+            .eq('project_id', projectId)
+            .eq('id', event.work_item_id)
+            .maybeSingle();
+        if (data)
+            workItem = data;
+    }
+    let proposals = [];
+    if (Array.isArray(event.proposal_ids) && event.proposal_ids.length) {
+        const { data } = await db()
+            .from('agent_proposals')
+            .select(proposalSelect)
+            .eq('project_id', projectId)
+            .in('id', event.proposal_ids);
+        if (data)
+            proposals = data;
+    }
+    return j({ context_event: event, work_item: workItem, proposals, idempotent: true });
+}
 async function submitContextEvent(input) {
     const projectId = getProjectId();
+    const normalizedKey = input.idempotency_key.trim();
     const existing = await db()
         .from('ai_context_events')
         .select('*')
         .eq('project_id', projectId)
         .eq('source', 'synchronex')
-        .eq('idempotency_key', input.idempotency_key)
+        .eq('idempotency_key', normalizedKey)
         .maybeSingle();
     if (existing.error)
-        return { ...dbToolError(existing.error) };
-    if (existing.data)
-        return { context_event: existing.data, work_item: null, proposals: [], idempotent: true };
-    const orgId = await getOrgIdForProject(projectId);
+        return toolError(dbToolError(existing.error));
+    if (existing.data) {
+        if (!isSameContextEventPayload(existing.data, input)) {
+            return toolError({ code: 'conflict', error: 'idempotency_key was already used with different content' });
+        }
+        return buildContextReplay(projectId, existing.data);
+    }
+    let orgId;
+    try {
+        orgId = await getOrgIdForProject(projectId);
+    }
+    catch (err) {
+        return toolError(dbToolError(err));
+    }
     const inserted = await db()
         .from('ai_context_events')
         .insert({
         org_id: orgId,
         project_id: projectId,
-        workspace_id: input.workspace_id,
+        workspace_id: input.workspace_id.trim(),
         source: 'synchronex',
         event_type: input.event_type,
-        title: input.title,
-        detail: input.detail,
+        title: input.title.trim(),
+        detail: input.detail.trim(),
         evidence: input.evidence ?? {},
         suggested_actions: input.suggested_actions ?? [],
-        idempotency_key: input.idempotency_key,
+        idempotency_key: normalizedKey,
     })
         .select('*')
         .single();
@@ -157,17 +247,21 @@ async function submitContextEvent(input) {
             .select('*')
             .eq('project_id', projectId)
             .eq('source', 'synchronex')
-            .eq('idempotency_key', input.idempotency_key)
+            .eq('idempotency_key', normalizedKey)
             .maybeSingle();
         if (duplicate.error)
-            return { ...dbToolError(duplicate.error) };
-        if (duplicate.data)
-            return { context_event: duplicate.data, work_item: null, proposals: [], idempotent: true };
+            return toolError(dbToolError(duplicate.error));
+        if (duplicate.data) {
+            if (!isSameContextEventPayload(duplicate.data, input)) {
+                return toolError({ code: 'conflict', error: 'idempotency_key was already used with different content' });
+            }
+            return buildContextReplay(projectId, duplicate.data);
+        }
     }
     if (inserted.error)
-        return { ...dbToolError(inserted.error) };
+        return toolError(dbToolError(inserted.error));
     const event = inserted.data;
-    const segmentAction = segmentActionFromContext(input.event_type, input.suggested_actions, input.title, input.detail);
+    const segmentAction = segmentActionFromContext(input.event_type, input.suggested_actions, input.title.trim(), input.detail.trim());
     const proposals = [];
     if (segmentAction) {
         const targetId = stableUuid(`synchronex-context:${projectId}:${event.id}:segment`);
@@ -190,7 +284,7 @@ async function submitContextEvent(input) {
                 sample_contact_ids: [],
                 recommendation_kind: 'synchronex_context',
             },
-            reasoning: input.detail,
+            reasoning: input.detail.trim(),
             source_data_refs: [{ table: 'email.ai_context_events', ids: [event.id] }],
             confidence: typeof input.evidence?.confidence === 'number' ? Math.max(0, Math.min(100, Math.trunc(input.evidence.confidence))) : 75,
             status: 'pending',
@@ -201,7 +295,7 @@ async function submitContextEvent(input) {
             .select(proposalSelect)
             .single();
         if (error)
-            return { ...dbToolError(error) };
+            return toolError(dbToolError(error));
         proposals.push(proposal);
     }
     const proposalIds = proposals.map((proposal) => proposal.id);
@@ -215,21 +309,21 @@ async function submitContextEvent(input) {
         severity: input.event_type === 'risk_signal' ? 'medium' : 'info',
         confidence: typeof input.evidence?.confidence === 'number' ? Math.max(0, Math.min(100, Math.trunc(input.evidence.confidence))) : null,
         source: 'synchronex',
-        title: input.title,
-        why_now: input.detail,
-        evidence: { ...(input.evidence ?? {}), context_event_id: event.id, synchronex_workspace_id: input.workspace_id, event_type: input.event_type },
+        title: input.title.trim(),
+        why_now: input.detail.trim(),
+        evidence: { ...(input.evidence ?? {}), context_event_id: event.id, synchronex_workspace_id: input.workspace_id.trim(), event_type: input.event_type },
         recommended_actions: proposalIds.length
             ? proposalIds.map((proposalId) => ({ type: 'review_proposal', label: 'Review recommended segment', proposal_id: proposalId, risk: 'low' }))
             : [{ type: 'review_context', label: 'Review Synchronex context', risk: 'low' }],
         surfaces: proposalIds.length ? ['overview', 'segments'] : ['overview'],
         proposal_ids: proposalIds,
-        dedupe_key: `synchronex:${input.workspace_id}:${input.idempotency_key}`,
+        dedupe_key: `synchronex:${input.workspace_id.trim()}:${normalizedKey}`,
         cooldown_until: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(),
     })
         .select(workItemSelect)
         .single();
     if (workError)
-        return { ...dbToolError(workError) };
+        return toolError(dbToolError(workError));
     const { data: updatedEvent, error: updateError } = await db()
         .from('ai_context_events')
         .update({ work_item_id: workItem.id, proposal_ids: proposalIds })
@@ -238,8 +332,8 @@ async function submitContextEvent(input) {
         .select('*')
         .single();
     if (updateError)
-        return { ...dbToolError(updateError) };
-    return { context_event: updatedEvent, work_item: workItem, proposals, idempotent: false };
+        return toolError(dbToolError(updateError));
+    return j({ context_event: updatedEvent, work_item: workItem, proposals, idempotent: false });
 }
 export function registerAiWorkTools(server) {
     server.registerTool('list_ai_work_items', {
@@ -257,18 +351,21 @@ export function registerAiWorkTools(server) {
             limit: z.number().int().min(1).max(100).optional().default(25),
         },
     }, async ({ status, surface, limit }) => {
+        const parsed = parseStatuses(status);
+        if ('error' in parsed)
+            return toolError(parsed.error);
         let query = db()
             .from('ai_work_items')
             .select(workItemSelect)
             .eq('project_id', getProjectId())
-            .in('status', parseStatuses(status))
+            .in('status', parsed.statuses)
             .order('generated_at', { ascending: false })
             .limit(limit ?? 25);
         if (surface)
             query = query.contains('surfaces', [surface]);
         const { data, error } = await query;
         if (error)
-            return txt(`Error: ${dbToolError(error).error}`);
+            return toolError(dbToolError(error));
         return j({ work_items: data ?? [] });
     });
     server.registerTool('get_ai_work_item', {
@@ -291,9 +388,9 @@ export function registerAiWorkTools(server) {
             .eq('id', work_item_id)
             .maybeSingle();
         if (error)
-            return txt(`Error: ${dbToolError(error).error}`);
+            return toolError(dbToolError(error));
         if (!data)
-            return txt('AI work item not found.');
+            return toolError({ code: 'not_found', error: 'AI work item not found.' });
         return j({ work_item: data });
     });
     server.registerTool('list_recommended_segments', {
@@ -310,16 +407,19 @@ export function registerAiWorkTools(server) {
             limit: z.number().int().min(1).max(100).optional().default(25),
         },
     }, async ({ status, limit }) => {
+        const parsed = parseStatuses(status);
+        if ('error' in parsed)
+            return toolError(parsed.error);
         const { data: workItems, error } = await db()
             .from('ai_work_items')
             .select(workItemSelect)
             .eq('project_id', getProjectId())
             .eq('kind', 'segment_recommendation')
-            .in('status', parseStatuses(status))
+            .in('status', parsed.statuses)
             .order('generated_at', { ascending: false })
             .limit(limit ?? 25);
         if (error)
-            return txt(`Error: ${dbToolError(error).error}`);
+            return toolError(dbToolError(error));
         const proposalIds = [...new Set((workItems ?? []).flatMap((item) => Array.isArray(item.proposal_ids) ? item.proposal_ids : []))];
         let proposals = [];
         if (proposalIds.length) {
@@ -329,7 +429,7 @@ export function registerAiWorkTools(server) {
                 .eq('project_id', getProjectId())
                 .in('id', proposalIds);
             if (proposalResult.error)
-                return txt(`Error: ${dbToolError(proposalResult.error).error}`);
+                return toolError(dbToolError(proposalResult.error));
             proposals = proposalResult.data ?? [];
         }
         return j({ work_items: workItems ?? [], proposals });
@@ -347,8 +447,7 @@ export function registerAiWorkTools(server) {
             work_item_id: z.string().uuid(),
         },
     }, async ({ work_item_id }) => {
-        const result = await updateWorkItemStatus(work_item_id, 'seen');
-        return 'error' in result ? txt(`Error: ${result.error}`) : j(result);
+        return updateWorkItemStatus(work_item_id, 'seen');
     });
     server.registerTool('snooze_ai_work_item', {
         title: 'Snooze AI Work Item',
@@ -364,8 +463,11 @@ export function registerAiWorkTools(server) {
             snoozed_until: z.string().datetime(),
         },
     }, async ({ work_item_id, snoozed_until }) => {
-        const result = await updateWorkItemStatus(work_item_id, 'snoozed', snoozed_until);
-        return 'error' in result ? txt(`Error: ${result.error}`) : j(result);
+        const snoozedTime = new Date(snoozed_until).getTime();
+        if (!Number.isFinite(snoozedTime) || snoozedTime <= Date.now()) {
+            return toolError({ code: 'validation_failed', error: 'snoozed_until must be in the future.' });
+        }
+        return updateWorkItemStatus(work_item_id, 'snoozed', snoozed_until);
     });
     server.registerTool('dismiss_ai_work_item', {
         title: 'Dismiss AI Work Item',
@@ -380,8 +482,7 @@ export function registerAiWorkTools(server) {
             work_item_id: z.string().uuid(),
         },
     }, async ({ work_item_id }) => {
-        const result = await updateWorkItemStatus(work_item_id, 'dismissed');
-        return 'error' in result ? txt(`Error: ${result.error}`) : j(result);
+        return updateWorkItemStatus(work_item_id, 'dismissed');
     });
     server.registerTool('submit_ai_context_event', {
         title: 'Submit AI Context Event',
@@ -394,8 +495,7 @@ export function registerAiWorkTools(server) {
         description: 'Submit Synchronex strategic context into Sendinel AI work queue without directly mutating email state.',
         inputSchema: contextEventInput,
     }, async (input) => {
-        const result = await submitContextEvent({ ...input, source: 'synchronex' });
-        return 'error' in result ? txt(`Error: ${result.error}`) : j(result);
+        return submitContextEvent(input);
     });
     server.registerTool('list_agent_proposals', {
         title: 'List Agent Proposals',
@@ -410,7 +510,7 @@ export function registerAiWorkTools(server) {
             status: z.enum(['pending', 'applied', 'auto_applied', 'dismissed', 'disputed', 'stale', 'failed', 'expired']).optional(),
             type: z.string().min(1).max(96).optional(),
             target_table: z.string().min(1).max(96).optional(),
-            target_id: z.string().optional(),
+            target_id: z.string().uuid().optional(),
             limit: z.number().int().min(1).max(100).optional().default(25),
         },
     }, async ({ status, type, target_table, target_id, limit }) => {
@@ -430,7 +530,7 @@ export function registerAiWorkTools(server) {
             query = query.eq('target_id', target_id);
         const { data, error } = await query;
         if (error)
-            return txt(`Error: ${dbToolError(error).error}`);
+            return toolError(dbToolError(error));
         return j({ proposals: data ?? [] });
     });
     server.registerTool('get_agent_proposal', {
@@ -453,9 +553,9 @@ export function registerAiWorkTools(server) {
             .eq('id', proposal_id)
             .maybeSingle();
         if (error)
-            return txt(`Error: ${dbToolError(error).error}`);
+            return toolError(dbToolError(error));
         if (!data)
-            return txt('Agent proposal not found.');
+            return toolError({ code: 'not_found', error: 'Agent proposal not found.' });
         return j({ proposal: data });
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sendinel/mcp-server",
-  "version": "1.0.188",
+  "version": "1.0.190",
   "description": "AI-controlled email operations control plane for campaigns, contacts, segments, analytics, and multi-provider sending via MCP.",
   "mcpName": "ai.sendinel/mcp-server",
   "type": "module",