@velaro/mcp-server 0.6.102 → 0.6.104

package/server.js

@@ -40,7 +40,7 @@
  *   VELARO_MCP_MODE=http PORT=3000 node server.js
  */
 
-import { describeRawMeta, fetchRetry429 } from './log-search.js';
+import { buildRawLogQuery, describeRawMeta, fetchRetry429, resolveLogWindow } from './log-search.js';
 import { Server }            from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import {
@@ -49,6 +49,8 @@ import {
   GetPromptRequestSchema,
   ListPromptsRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js';
+import { withAnnotations } from './tool-annotations.js';
+import { resolveMessagingApi } from './messaging-base.js';
 
 // Default was 'https://help.velaro.com'. Renamed to the recognizable admin API hostname for
 // clarity during the 2026-09-10 Donaldson bot Calendly status investigation
@@ -59,7 +61,7 @@ import {
 // caused that investigation's status/reality contradiction, it was NOT this default resolving to a
 // broken or different host; that theory is disproven. Left as a naming clarity improvement only.
 const API_BASE      = process.env.VELARO_ADMIN_API     || 'https://api-admin-us-east.velaro.com';
-const MESSAGING_API = process.env.VELARO_MESSAGING_API || null;
+const MESSAGING_API = resolveMessagingApi(process.env.VELARO_MESSAGING_API, API_BASE);
 const MCP_KEY       = process.env.VELARO_MCP_KEY;
 const JWT           = process.env.VELARO_JWT;
 
@@ -320,7 +322,7 @@ async function gatewayInit() {
 // Tools served by velaro-messaging's admin-tools gateway (McpAdminGatewayController, POST /mcp/v1/admin-tools/call,
 // no session). The admin /mcp gateway only serves kb_* tools, so these used to fail there.
 const MESSAGING_ADMIN_TOOLS = new Set([
-  'workflow_create', 'workflow_list', 'workflow_get', 'workflow_toggle',
+  'workflow_create', 'workflow_list', 'workflow_get', 'workflow_toggle', 'workflow_run_now',
   'bot_create', 'bot_list', 'bot_get', 'bot_update_prompt', 'bot_set_knowledge',
   'ai_config_attach_index', 'ai_config_set_reply_format', 'call_pop_settings_get', 'call_pop_settings_set',
   'crm_mobile_fields_get', 'crm_mobile_fields_set',
@@ -488,7 +490,7 @@ const TOOLS = [
   },
   {
     name: 'notifications_get',
-    description: "Get the calling agent's own notification/SMS alert settings (new conversation, missed chat, unassign warning, text-alert toggles, SMS phone number).",
+    description: "Get the calling agent's own notification/SMS alert settings (new conversation, missed chat, unassign warning, text-alert toggles, SMS phone number) plus alertRouting: which Channel (web, sms, whatsapp, appleMessages, email, phone) x Handling (mine, unassigned, bot, teammates) x Kind (conversations, tickets, calls, visitors) alerts fire, and ivrBotAlerts (opt-in for inbound IVR bot chats).",
     inputSchema: { type: 'object', properties: {}, required: [] },
   },
   {
@@ -508,6 +510,35 @@ const TOOLS = [
         smsOnUnassignWarning:  { type: 'boolean', description: 'Send an SMS on unassign warning' },
         useProfilePhone:       { type: 'boolean', description: 'Use the profile phone number for SMS alerts' },
         smsAlertPhone:         { type: 'string',  description: 'Phone number for SMS alerts (E.164, e.g. +14155551234)' },
+        alertRouting: {
+          type: 'object',
+          description: 'Alert routing, partial update (omitted keys unchanged). An alert fires only if its channel, handling and kind are all on. Example: {"channels":{"sms":true,"web":false},"handling":{"mine":true,"unassigned":false},"kinds":{"tickets":false},"ivrBotAlerts":true}',
+          properties: {
+            channels: { type: 'object', description: 'Keys: web, sms, whatsapp, appleMessages, email, phone (booleans)' },
+            handling: { type: 'object', description: 'Keys: mine, unassigned, bot, teammates (booleans, multi-select)' },
+            kinds:    { type: 'object', description: 'Keys: conversations, tickets, calls, visitors (booleans)' },
+            ivrBotAlerts: { type: 'boolean', description: 'Alert for inbound IVR / phone bot chats (default off)' },
+          },
+        },
+      },
+    },
+  },
+  {
+    name: 'signature_policy_get',
+    description: "Get the company email signature policy for the calling admin's site: the company-wide row (teamId 0), any per-team overrides, and the suggested legal disclaimer text. Modes: locked (users cannot use personal signatures), company-default (company signature is the default, personal allowed), personal-only (the default when nothing is set). The legal disclaimer is off unless turned on. Admin only.",
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'signature_policy_set',
+    description: "Update the company email signature policy (admin only). Only the fields passed are changed; the current row is read first and merged. teamId 0 (default) is the company-wide policy; a team id sets a per-team override. Pass mode 'default' or null to clear a value back to following the company-wide setting. Use signature_policy_get first.",
+    inputSchema: {
+      type: 'object',
+      properties: {
+        teamId:             { type: 'integer', description: '0 = company-wide (default), otherwise the team id for a per-team override' },
+        mode:               { type: 'string', enum: ['locked', 'company-default', 'personal-only', 'default'], description: 'locked | company-default | personal-only | default (follow company-wide)' },
+        corporateSignature: { type: ['string', 'null'], description: 'Company signature HTML, max 4000 characters. Empty or null clears it.' },
+        disclaimerEnabled:  { type: ['boolean', 'null'], description: 'Turn the legal disclaimer on or off. null follows the company-wide choice. Off by default.' },
+        disclaimerText:     { type: ['string', 'null'], description: 'Legal disclaimer text, max 2000 characters. Empty or null clears it.' },
       },
     },
   },
@@ -1058,6 +1089,18 @@ const TOOLS = [
       required: ['id', 'enabled'],
     },
   },
+  {
+    name: 'workflow_run_now',
+    description: 'Queue an enabled workflow to run now, optionally seeded with a shallow JSON context object (max 50 keys, 4KB) that becomes the run\'s workflow attributes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id:      { type: 'number', description: 'Workflow ID' },
+        context: { type: 'object', description: 'Optional shallow object of values to seed the run, e.g. {"customerId":"123"}' },
+      },
+      required: ['id'],
+    },
+  },
   {
     name: 'workflow_create',
     description: 'Create a new workflow with optional pre-built nodes. Use this to build a workflow for the user from a description. Pass initialNodesBlob as a JSON string of the nodes object (keys are string IDs "1","2","3"..., values are node objects). For integration AI workflows, use 3 nodes: trigger (type:"trigger", trigger:"conversation_opened", overrideRouting:true, channels:[], triggerExpression:null), sendMessage (type:"action", actionType:"sendMessage", text:"greeting", child:3), and the AI node (type:"action", actionType:"dynamicsAI"|"netsuiteAI"|"hubSpotAI"|"shopifyAI"|"bigCommerceAI"|"woocommerceAI", configId fields null, aiConfigId:null, mcpServerIds:[]). The workflow is created disabled — activate it separately with workflow_toggle.',
@@ -1087,6 +1130,8 @@ Key node shapes:
     propName:"myAnswerVar" }                      // variable that stores the result as JSON array string
 • condition:      { type:"action", actionType:"condition", conditionOptions:[...] }
 • transferToAI:   { type:"action", actionType:"transferToAI", aiConfigId:N }
+• sendSurvey:     { type:"action", actionType:"sendSurvey", sendSurveyId:N, surveyDeliveryMode:"conversational"|"form", closeAfterSurvey:true|false, child:N }
+  closeAfterSurvey (optional, default false): when true the chat closes once the visitor completes the survey (use for Unavailable/after-hours surveys that replace a live chat). Omit to keep the old behaviour.
   AI follow-up suggestions ("AI mode"): add suggestFollowUps:true|false (omit = use the account default, set via ai_followups_site_set), suggestFollowUpCount:2-4, suggestFollowUpInstruction:"<=300 chars". After each web-chat bot reply the bot offers short tappable follow-up replies; typing stays available.
 
 For multiSelect dynamic options: the variable named in dynamicOptionsVariable must contain a JSON array like [{"label":"Red","value":"red"},{"label":"Blue","value":"blue"}]. Populate it via an HTTP Request node before the ask node.`,
@@ -1471,6 +1516,18 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['id'],
     },
   },
+  {
+    name: 'copilot_studio_ask',
+    description: 'Live diagnostic: ask a connected Copilot Studio / Azure AI agent a real question and classify the reply as answered, vendor_limit (usage limit / unavailable) or no_answer (fallback topic). Use to prove the agent actually answers, not just that credentials work.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        id: { type: 'number', description: 'Config ID from copilot_studio_list' },
+        question: { type: 'string', description: 'A real data-bound question for the agent' },
+      },
+      required: ['id', 'question'],
+    },
+  },
 
   // ── Monday.com field mapping / CRM search ────────────────────────────────
   {
@@ -1661,6 +1718,11 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
         welcomeMessage: { type: 'string',  description: 'Sent to the Teams user when their message opens a new conversation. Use {{user.name}} for their display name. Max 1000 characters.' },
         teamId:         { type: 'number',  description: 'Route new conversations to this team id (must be a real, non-deleted team on this site)' },
         clearTeamId:    { type: 'boolean', description: 'Clear the team override and fall back to the site default team' },
+        prechatEnabled: { type: 'boolean', description: 'Ask the Teams user prechat questions before a conversation opens' },
+        prechatFields:  { type: 'array', description: 'Replaces the prechat questions (max 6). Key "email" is validated as an email.', items: { type: 'object', properties: { key: { type: 'string' }, label: { type: 'string' }, required: { type: 'boolean' } }, required: ['key', 'label'] } },
+        quickReplies:   { type: 'array', description: 'Replaces the quick-reply buttons (max 6, 40 chars each); empty array clears them', items: { type: 'string' } },
+        postChatEnabled:{ type: 'boolean', description: 'Send postChatMessage when an agent closes the conversation' },
+        postChatMessage:{ type: 'string', description: 'Post-chat text, {{user.name}} = first name, max 1000 chars; empty string clears it' },
       },
       required: [],
     },
@@ -2381,6 +2443,24 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['siteId', 'indexName'],
     },
   },
+  {
+    name: 'index_set_profile',
+    description: 'Velaro staff only. Set the ingestion profile of ONE named index on ANY site (chunk strategy, chunk size/overlap, purpose, search size, excludeFromAllSources). Apply-if-present: only fields you pass change. Changing the profile versions the content hash so the next ingest re-chunks. Wraps PUT KnowledgeSetup/Staff/{siteId}/index-profile (velaro-messaging).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId:                { type: 'number', description: 'Target site ID' },
+        indexName:             { type: 'string', description: 'Index name on that site, e.g. "100140-troubleshooting"' },
+        chunkStrategy:         { type: 'string', enum: ['procedure', 'section'], description: 'Chunk strategy' },
+        chunkSize:             { type: 'number', description: 'Chunk size' },
+        chunkOverlap:          { type: 'number', description: 'Chunk overlap' },
+        purpose:               { type: 'string', enum: ['general', 'troubleshooting', 'catalog'], description: 'Index purpose' },
+        searchSize:            { type: 'number', description: 'Results per search' },
+        excludeFromAllSources: { type: 'boolean', description: 'Keep out of the ["*"] all-sources search' },
+      },
+      required: ['siteId', 'indexName'],
+    },
+  },
   {
     name: 'uploaded_file_reindex',
     description: 'Re-index an already-uploaded AI training file from blob storage — use when a file shows 0 chunks (e.g. PDF uploaded before PDF support was added). Reads from blob and re-runs full ingestion. Use index_status after ~30s to verify chunks appear.',
@@ -2626,6 +2706,29 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['startDate', 'endDate'],
     },
   },
+  {
+    name: 'report_performance_by_country_get',
+    description: 'Performance by Country report (US vs Canada vs Europe vs Other): engagements (handled, missed, abandoned), performance (first response, handle time, bot containment, transfers, service level) and scores (CSAT, sentiment) per country bucket and per agent. attribution: visitor (visitor GeoIP country, default) | agent (country on the agent profile) | group (the site saved group-to-bucket map).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        startDate:   { type: 'string', description: 'ISO 8601 start. Default: 30 days ago' },
+        endDate:     { type: 'string', description: 'ISO 8601 end. Default: now' },
+        attribution: { type: 'string', enum: ['visitor', 'agent', 'group'], description: 'Default: visitor' },
+        channels:    { type: 'array', items: { type: 'string' }, description: 'Optional ConversationSource filter, e.g. ["Web","TwilioSms"]. Default: all channels' },
+      },
+    },
+  },
+  {
+    name: 'report_performance_by_country_set_groups',
+    description: 'Read or set the per-site mapping of Velaro groups (teams) to Performance by Country buckets. With no map, returns the site groups and the current mapping. With map ({"<teamId>": "US|Canada|Europe|any label"}) it REPLACES the mapping; unmapped groups report as Other. Only the site own groups are kept.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        map: { type: 'object', description: 'teamId to bucket label. Omit to just read.', additionalProperties: { type: 'string' } },
+      },
+    },
+  },
   {
     name: 'report_campaign_performance',
     description: 'Email campaign performance: open rate, click rate, delivery rate, complaint rate per campaign + aggregate KPIs.',
@@ -2906,7 +3009,9 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
         platform:      { type: 'string',  enum: ['v10', 'v20', 'admin'], description: 'Filter by platform' },
         environment:   { type: 'string',  enum: ['Production', 'Staging', 'Development'] },
         correlationId: { type: 'string',  description: 'Exact correlation/trace ID filter' },
-        last:          { type: 'string',  description: 'Time window: 30m, 2h, 1d (default: 2h)' },
+        last:          { type: 'string',  description: 'Time window ending at `to`/now: 30m, 2h, 1d (default: 2h)' },
+        from:          { type: 'string',  description: 'Window start: ISO timestamp (2026-10-20T00:00:00Z) or relative (3h). Overrides `last`.' },
+        to:            { type: 'string',  description: 'Window end: ISO timestamp or relative (1h = 1h ago). Default: now.' },
         take:          { type: 'number',  description: 'Max results (default: 50, max: 500)' },
         regex:         { type: 'boolean', description: 'Treat q/logger as a regex pattern (default: false)' },
       },
@@ -3355,11 +3460,11 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   },
   {
     name: 'enterprise_reports',
-    description: 'Enterprise Reports package (enterprise-internal, default OFF; every report returns 403 when the site does not hold that package item). report: program_breakdown (compare websites, teams, platforms, devices or entry pages: volume, missed, transfers, wait, first reply, QA score and coverage, sentiment), agent_scorecard (per agent by name: resolution, transfers, handle time, AI score, supervisor-reviewed score, sentiment impact), qa_coverage (share of resolved chats AI-scored and supervisor-reviewed by week and program), coaching_queue (low-scoring chats nobody reviewed, per agent), sentiment_breakdown (by website, team, agent or topic with change vs prior period), topic_radar (topics by volume, growth, transfer rate), weekly_brief (preview of the Monday brief sections), weekly_brief_send_test (emails this week\'s brief to the signed-in user). Scoped to the caller site.',
+    description: 'Enterprise Reports package (enterprise-internal, default OFF; every report returns 403 when the site does not hold that package item). report: program_breakdown (compare websites, teams, platforms, devices or entry pages: volume, missed, transfers, wait, first reply, QA score and coverage, sentiment), agent_scorecard (per agent by name: resolution, transfers, handle time, AI score, supervisor-reviewed score, sentiment impact), qa_coverage (share of resolved chats AI-scored and supervisor-reviewed by week and program), coaching_queue (low-scoring chats nobody reviewed, per agent), sentiment_breakdown (by website, team, agent or topic with change vs prior period), topic_radar (topics by volume, growth, transfer rate), weekly_brief (preview of the Monday brief sections), weekly_brief_send_test (emails this week\'s brief to the signed-in user), year_in_review (builds the 12-month Year in review document in the background: from/to yyyy-MM-dd inclusive, default the last 12 whole Pacific months, returns a build id; call again with buildId to get status and the download link). Scoped to the caller site.',
     inputSchema: {
       type: 'object',
       properties: {
-        report:       { type: 'string', enum: ['program_breakdown', 'agent_scorecard', 'qa_coverage', 'coaching_queue', 'sentiment_breakdown', 'topic_radar', 'weekly_brief', 'weekly_brief_send_test', 'repeat_contact', 'demand_coverage', 'bot_containment', 'effort_index', 'promise_ledger', 'promise_dismiss'] },
+        report:       { type: 'string', enum: ['program_breakdown', 'agent_scorecard', 'qa_coverage', 'coaching_queue', 'sentiment_breakdown', 'topic_radar', 'weekly_brief', 'weekly_brief_send_test', 'repeat_contact', 'demand_coverage', 'bot_containment', 'effort_index', 'promise_ledger', 'promise_dismiss', 'new_agent_ramp', 'year_in_review'] },
         from:         { type: 'string', description: 'yyyy-MM-dd start (default: 30 days ago).' },
         to:           { type: 'string', description: 'yyyy-MM-dd end, inclusive (default: today).' },
         groupBy:      { type: 'string', description: 'program_breakdown: website|team|platform|device|entrypage. sentiment_breakdown: website|team|agent|theme.' },
@@ -3377,22 +3482,24 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
         lowScore:     { type: 'number', description: 'bot_containment: QA score below which a handed-off chat counts as regret (1-100, default 60).' },
         includeDemo:  { type: 'boolean', description: 'true = show only the seeded sample (demo) data. Default false.' },
         promiseId:    { type: 'string', description: 'promise_dismiss: the promise id to dismiss (managers only).' },
+        buildId:      { type: 'string', description: 'year_in_review: the build id returned by a start call; when given, returns that build\'s status (queued|building|completed|failed) and download link instead of starting a new build.' },
       },
       required: ['report'],
     },
   },
   {
     name: 'report_backfill',
-    description: 'Backfill report data for the caller site. Preview by default (reports "would fill N", writes nothing); apply=true writes. Idempotent. type "csat" fills missing survey ratings (SurveySubmission.Rating) from existing data; it does NOT touch ticket CSAT. Site managers only; scoped to the caller site.',
+    description: 'Backfill report data for the caller site. Preview by default (reports "would fill N", writes nothing); apply=true writes. Idempotent. type "csat" fills missing survey ratings (SurveySubmission.Rating) from existing data; it does NOT touch ticket CSAT. type "csat-demo" adds tagged demo CSAT assigned to the demo agents (allow-listed demo sites only); type "csat-demo-undo" over the same from/to deletes exactly those tagged rows and nothing else. type "history-classification-sample" tags 20 recent conversations and reports the line-of-business and intent mix it found (the proposed tags); type "history-classification" then tags and sentiment-scores past resolved conversations in the range (up to 100 per run, run again to continue) so Enterprise Reports and Year in Review show classified history instead of Unclassified / Insufficient data. For both history types, apply=true is QUEUED (the server returns 202 with a runId and runs it in the background; one run per site at a time, a repeat call returns the active run); pass status=true to read the latest run (queued, running, completed with result, or failed). Site managers only; scoped to the caller site.',
     inputSchema: {
       type: 'object',
       properties: {
-        type:  { type: 'string', description: 'Backfill type, e.g. csat.' },
-        from:  { type: 'string', description: 'yyyy-MM-dd start.' },
-        to:    { type: 'string', description: 'yyyy-MM-dd end.' },
-        apply: { type: 'boolean', description: 'true = write. Default false (preview only).' },
+        type:  { type: 'string', description: 'Backfill type: csat, csat-demo, csat-demo-undo, history-classification-sample or history-classification.' },
+        from:  { type: 'string', description: 'yyyy-MM-dd start (required unless status=true).' },
+        to:    { type: 'string', description: 'yyyy-MM-dd end (required unless status=true).' },
+        apply: { type: 'boolean', description: 'true = write. Default false (preview only). For history types this queues a background run.' },
+        status: { type: 'boolean', description: 'true = return the latest queued/running/finished apply run for this type instead of starting anything.' },
       },
-      required: ['type', 'from', 'to'],
+      required: ['type'],
     },
   },
   // -- Staff: schedule adherence by site + role (SupportTools-style: explicit siteId, never auth-derived) --
@@ -3560,6 +3667,17 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['siteId'],
     },
   },
+  {
+    name: 'avatar_session_readiness',
+    description: 'Velaro staff diagnostic: runs the real avatar session gates for a site (plan, config, provider key, billing authority, concurrency) without claiming a slot or calling the provider, so it costs nothing. Use when a visitor avatar session returns 503 or will not start. Calls velaro-messaging GET /avatar/diagnostics/session-readiness (staff only).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId: { type: 'number', description: 'Site ID to check' },
+      },
+      required: ['siteId'],
+    },
+  },
   {
     name: 'avatar_set_config',
     description: 'Set up or update the AI Video Avatar for a customer site (partial update — only send the fields you want to change). Velaro admin only.',
@@ -3572,11 +3690,13 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
         avatarId:     { type: 'string',  description: 'Avatar ID. For provider "velaro" this is a Velaro Avatar library slug. Other providers: their own face/avatar ID. Omit for provider default.' },
         voiceId:      { type: 'string',  description: 'ElevenLabs voice ID override. Omit to use the site default.' },
         showCallMeOption: { type: 'boolean', description: 'Show the "Call me instead" option (requires EnableClickToCall).' },
+        enabledOnAgentTransfer: { type: 'boolean', description: 'Keep the avatar running after a human agent joins the conversation (default off).' },
         callbackConfirmWindowMinutes: { type: 'number', description: 'Minutes to confirm a callback request before it expires. Default 10.' },
         displayName: { type: 'string', description: 'Visitor-facing avatar name shown on the badge (e.g. "Moshky"). Empty string resets to "AI".' },
         showBadge: { type: 'boolean', description: 'Show the name badge over the avatar video. Default true.' },
         sizePx: { type: 'number', description: 'Max avatar panel width in px (160-640, square). Default 360.' },
         allowVisitorCollapse: { type: 'boolean', description: 'Let visitors hide or collapse the avatar panel (up/down arrow and X). Default true.' },
+        heyGenEnabled: { type: 'boolean', description: 'Grant or revoke the HeyGen provider entitlement (EnableAvatarHeyGen) for this site. Off by default; HeyGen is hidden from the customer UI until granted.' },
         motionLevel: { type: 'string', enum: ['', 'off', 'subtle', 'natural', 'expressive'], description: 'Body motion preset layered over the lip-sync (shoulders, breathing, head, brows). Empty string resets to the platform default (natural). Visitors with reduced-motion enabled always get a still avatar.' },
         motionIntensityPercent: { type: 'integer', minimum: 25, maximum: 150, description: 'Body motion strength, whole percent 25-150 (default 100); multiplies every motion amplitude.' },
         maxAvatarMinutesPerMonth: { type: 'number', description: 'Monthly avatar video minutes cap for the site. Whole number 1-100000; never unlimited (0/negative rejected).' },
@@ -3674,6 +3794,31 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     description: 'Reset ALL group and workflow overrides for the calling site back to the site default.',
     inputSchema: { type: 'object', properties: {} },
   },
+  {
+    name: 'avatar_set_workflow_switch',
+    description: 'Switch the AI avatar on, off, or back to the site rules for ONE workflow of the calling site. mode "on" shows the avatar, "off" hides it, "rules" clears the switch so the site rules decide. Only the switch changes; the rest of the workflow override is kept. Velaro admin or site auth.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        workflowId: { type: 'number', description: 'Workflow id (must belong to the calling site).' },
+        mode: { type: 'string', enum: ['on', 'off', 'rules'], description: 'on | off | rules' },
+      },
+      required: ['workflowId', 'mode'],
+    },
+  },
+  {
+    name: 'avatar_bulk_set_switch',
+    description: 'Set the AI avatar switch (on | off | rules) for many workflows and/or teams of the calling site in one call. Select rows with workflowIds and/or groupIds (at least one; max 500 rows). Each changed row is audited. Velaro admin or site auth.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        mode: { type: 'string', enum: ['on', 'off', 'rules'], description: 'on | off | rules' },
+        workflowIds: { type: 'array', items: { type: 'number' }, description: 'Workflow ids of the calling site.' },
+        groupIds: { type: 'array', items: { type: 'number' }, description: 'Team (group) ids of the calling site.' },
+      },
+      required: ['mode'],
+    },
+  },
 
   // ── Calendly integration management (superadmin) ──────────────────────────
   {
@@ -4027,6 +4172,26 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['shop'],
     },
   },
+  {
+    name: 'shopify_get_write_policy',
+    description: 'Get the Shopify write-tier policy for the site: enableShopifyWrite (master toggle for the 11 Shopify write skills; read skills are unaffected), requireConfirmation, and the effective caps maxRefundAmount, maxDiscountPercent, maxDiscountFixedAmount (defaults filled in: 250 / 20 / 50). Site is resolved server-side from the caller\'s auth context. Lives in velaro-messaging (GET /api/Shopify/WritePolicy) - requires VELARO_MESSAGING_API.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'shopify_set_write_policy',
+    description: 'Update the Shopify write-tier policy for the site (apply-if-present, partial: omitted fields keep their stored value). Pass null for a cap to return it to the default. enableShopifyWrite=false hides the 11 Shopify write skills (refund, discount, etc.) without touching the read skills. Validated server-side. Lives in velaro-messaging (PUT /api/Shopify/WritePolicy) - requires VELARO_MESSAGING_API.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        enableShopifyWrite:     { type: 'boolean', description: 'Master toggle for the Shopify write skills.' },
+        requireConfirmation:    { type: 'boolean', description: 'Require customer confirmation before a write skill executes.' },
+        maxRefundAmount:        { type: ['number', 'null'], description: 'Max refund amount per call. null = default (250).' },
+        maxDiscountPercent:     { type: ['number', 'null'], description: 'Max percentage discount. null = default (20).' },
+        maxDiscountFixedAmount: { type: ['number', 'null'], description: 'Max fixed-amount discount. null = default (50).' },
+      },
+      required: [],
+    },
+  },
   {
     name: 'appointments_manage',
     description: 'Velaro Appointments — reschedules or cancels an existing appointment that was booked via appointments_book. Requires the provider slug and event_id from the original booking. Set intent="reschedule" with a new start (and optional duration) to move it, or intent="cancel" to remove it. Cancel is destructive and is additionally gated by the EnableDestructiveAiSkills subscription flag. Marketing page: /appointments.',
@@ -4219,8 +4384,9 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       properties: {
         storeUrl:    { type: 'string', description: 'Magento store base URL, e.g. "https://mystore.com"' },
         accessToken: { type: 'string', description: 'Magento REST API bearer token (Admin Integration token)' },
+        configId:    { type: 'number', description: 'Test an already-connected store with its stored token instead (storeUrl/accessToken then not needed)' },
       },
-      required: ['storeUrl', 'accessToken'],
+      required: [],
     },
   },
   {
@@ -4295,6 +4461,18 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   },
 
   // ── Business actions + SAP (one definition, many surfaces) ─────────────────────
+  {
+    name: 'salesforce_diagnose',
+    description: 'Run the Salesforce live diagnostic for a site: configuration completeness, OAuth token acquisition and, when deep, a read-only SOQL probe per object the skills use (contacts, leads, accounts, tasks, notes, email history, opportunities, cases, products, orders) with its package tier (Core/Sales/Service/Commerce). Never writes; write capabilities are never reported as verified; secrets are never returned. Calls messaging GET diagnostics/test-salesforce?siteId=<id>&deep=<bool>. Velaro staff only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId: { type: 'number', description: 'Site to diagnose (e.g. 1032)' },
+        deep: { type: 'boolean', description: 'Probe every object (default true). false = configuration + token only.' },
+      },
+      required: ['siteId'],
+    },
+  },
   {
     name: 'sap_diagnose',
     description: 'Run the SAP live diagnostic for a site: configuration completeness, authentication (real HTTP status) and, when deep, a per-capability read-only probe compared with what the capability matrix documents (S/4HANA on-prem/private/public, Business One, ECC via gateway). Never writes; a write capability is never reported as verified; secrets are never returned. Calls messaging GET diagnostics/test-sap?siteId=<id>&deep=<bool>. Velaro staff only.',
@@ -4403,6 +4581,35 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     },
   },
 
+  {
+    name: 'netsuite_suiteapp_download',
+    description: 'Download the NetSuite screen-pop SuiteApp (SDF project zip) to a local file. With includeKey=true (default) a new crm-embed-only key is minted and baked into the zip, so NO NetSuite API Secret and no key paste is needed. With includeKey=false the zip is key-less and the admin must create a NetSuite API Secret: type ID velaro_api_key in the form (NetSuite adds the prefix, giving custsecret_velaro_api_key). Lives in velaro-messaging - requires VELARO_MESSAGING_API.',
+    inputSchema: { type: 'object', properties: { includeKey: { type: 'boolean', description: 'Default true.' }, outputPath: { type: 'string', description: 'Local file path to write (default: temp dir).' } }, required: [] },
+  },
+  {
+    name: 'netsuite_config_delete',
+    description: 'Delete a NetSuite connection (config) from the site. Removes the stored credentials; mappings/workflows referencing it will stop working. Destructive. Lives in velaro-messaging (DELETE Netsuite/Integrations/{id}) - requires VELARO_MESSAGING_API.',
+    inputSchema: {
+      type: 'object',
+      properties: { configId: { type: 'number', description: 'NetSuite config ID (see netsuite_list_configs).' } },
+      required: ['configId'],
+    },
+  },
+  {
+    name: 'netsuite_m2m_clear_legacy',
+    description: 'Disconnect the old consumer-key/token credentials from a NetSuite config that already runs on a saved M2M certificate (explicit, never automatic; the connection row, mappings and workflows are untouched). Fails if M2M is not saved/active. Lives in velaro-messaging (POST NetSuite/M2M/ClearLegacy) - requires VELARO_MESSAGING_API.',
+    inputSchema: {
+      type: 'object',
+      properties: { configId: { type: 'number', description: 'NetSuite config ID (see netsuite_list_configs).' } },
+      required: ['configId'],
+    },
+  },
+  {
+    name: 'netsuite_embed_status',
+    description: 'NetSuite SuiteApp call-pop (CRM embed) status for the site: is a crm_embed API key set, and the last heartbeat (when it last polled, connected or not) per key. Lives in velaro-messaging (GET api/v1/CrmEmbed/embed-status; fields hasEmbedKey, connected, lastPolledAt) - requires VELARO_MESSAGING_API.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+
   {
     name: 'netsuite_m2m_init',
     description: 'Start NetSuite machine-to-machine (OAuth 2.0 Client Credentials) setup: generates the Velaro public certificate PEM to upload in NetSuite (Setup > Integration > Manage Authentication > OAuth 2.0 Client Credentials (M2M) Setup) and returns the steps. Omit configId for a new connection (company then required). Lives in velaro-messaging - requires VELARO_MESSAGING_API.',
@@ -4896,6 +5103,11 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     description: 'Show the Enterprise Reports package (enterprise-internal, default OFF): every item with its feature key, what it builds on, and, when siteId is given, whether it is ON for that site. Superadmin only.',
     inputSchema: { type: 'object', properties: { siteId: { type: 'number', description: 'Optional site ID to show which items are on' } } },
   },
+  {
+    name: 'entitlement_report_packages',
+    description: 'Show the five report category packages (Conversations & Channels, Workforce & Operations, Customer Experience, AI & Intelligence, Business & Executive) nested under the top Enterprise Reports package (default OFF): every report with its package slug and entitlement key and, when siteId is given, whether each report and each whole category is ON for that site. Superadmin only.',
+    inputSchema: { type: 'object', properties: { siteId: { type: 'number', description: 'Optional site ID to show which reports are on' } } },
+  },
   {
     name: 'entitlement_set_override',
     description: 'Set a per-site feature override — enable or disable a specific feature for one site, independent of their plan. Superadmin only. Use entitlement_list_features to find valid featureKey values.',
@@ -5090,11 +5302,11 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   },
   {
     name: 'focus_update_triage_rules',
-    description: 'Enable or disable one or more of the 5 fixed AI triage labels (urgent, needs_reply, offer, fyi, waiting) for this site. Apply-if-present -- only labels included are changed. Rejects any label name outside the fixed set. Disabling all 5 fails safe back to all-enabled server-side rather than breaking triage. Optionally set triageMode: "economy" classifies obvious messages (auto-replies, clear urgency) without an AI call, lowering AI usage; "off" keeps current behavior. Unspecified fields are preserved.',
+    description: 'Enable or disable one or more of the 5 fixed AI triage labels (urgent, needs_reply, offer, fyi, waiting) for this site. Apply-if-present -- only labels included are changed. Rejects any label name outside the fixed set. Disabling all 5 fails safe back to all-enabled server-side rather than breaking triage. Optionally set triageMode: "economy" classifies obvious messages (auto-replies, clear urgency) without an AI call, lowering AI usage; "off" makes this site always use the AI call (platform default is economy). Unspecified fields are preserved.',
     inputSchema: {
       type: 'object',
       properties: {
-        triageMode: { type: 'string', enum: ['off', 'economy'], description: 'Optional. "economy" skips the AI call for obvious messages; "off" (default) keeps current behavior.' },
+        triageMode: { type: 'string', enum: ['off', 'economy'], description: 'Optional. "economy" skips the AI call for obvious messages; "off" makes this site always use the AI call. Unset inherits the platform default, which is economy.' },
         labels: {
           type: 'array',
           description: 'Labels to update.',
@@ -5200,7 +5412,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       type: 'object',
       properties: {
         start: { type: 'string', description: 'ISO 8601 start of range.' },
-        end: { type: 'string', description: 'ISO 8601 end of range. Must be at most 90 days after start.' },
+        end: { type: 'string', description: 'End of range. A plain YYYY-MM-DD date includes that whole day (the server end is exclusive, so it is sent as the start of the next day); a full ISO 8601 datetime is an exact exclusive instant. Must be at most 90 days after start.' },
       },
       required: ['start', 'end'],
     },
@@ -5330,6 +5542,28 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     },
   },
 
+  // -- Apple Pay display settings --
+  // Backend: velaro-messaging ApplePayConfigsController (GET/POST ApplePayConfig, PUT ApplePayConfig/{id}).
+  // Display + test mode only; merchant id / certificate (which affect the charge) are intentionally not settable here.
+  {
+    name: 'apple_pay_get_config',
+    description: 'Get this site\'s Apple Pay settings: enabled, test mode (sandbox: Velaro Stripe test account, no real money, real Wallet cards decline), business name shown on the Apple Pay sheet, whether a custom payment-bubble logo is set, and whether the site uses Velaro\'s platform merchant. id is 0 when the site has no row yet.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'apple_pay_update_config',
+    description: 'Create or update this site\'s Apple Pay DISPLAY settings and test mode. Apply-if-present: omit a field to leave it unchanged. These never affect the charge (the merchant id and certificate do, and are managed by secure Velaro admin provisioning). Creates the row when the site has none.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        merchantDisplayName: { type: 'string', description: 'Business name shown on the Apple Pay sheet' },
+        isTestMode:          { type: 'boolean', description: 'Sandbox mode: Velaro Stripe test account, no real money moves, real Wallet cards decline' },
+        bubbleLogoBase64:    { type: 'string', description: 'PNG/JPEG base64 (max 500 KB) for the payment bubble. Empty string clears it back to the default image.' },
+      },
+      required: [],
+    },
+  },
+
   // -- Recruiting Bot --
   // Backend: server/Velaro.Messaging/Controllers/RecruitingController.cs.
   // [EnableRecruitingBot] gated server-side; siteId always derives from the
@@ -6035,6 +6269,14 @@ function parseBusinessHours(input) {
 
 // ── Tool handlers ─────────────────────────────────────────────────────────────
 
+// Report end params are exclusive server-side: a plain YYYY-MM-DD end means "through that whole
+// day", so send the start of the next day (mirrors cli/lib/report-range.js exclusiveEndParam).
+function exclusiveEnd(raw) {
+  if (raw == null || raw === '') return raw;
+  const d = new Date(raw);
+  if (Number.isNaN(d.getTime()) || !/^\d{4}-\d{2}-\d{2}$/.test(String(raw).trim())) return raw;
+  return new Date(d.getTime() + 24 * 60 * 60 * 1000).toISOString();
+}
 // -- Agent inactivity chain helpers (velaro-messaging PR #1471, v20 ONLY) ------------------------
 // Terminal action ints are persisted by messaging (append-only enum). The API returns/accepts the NAME.
 const TERMINAL_ACTION_NAMES = ['Survey','CreateTicket','SurveyAndCreateTicket','Queue','OfflineMessage','NoOp','EndChat','NotifyManager','RunWorkflow','ReturnToBot'];
@@ -6165,7 +6407,9 @@ async function handleTool(name, args) {
     }
 
     case 'notifications_get': {
-      return JSON.stringify(await messagingGet('/NotificationSettings'), null, 2);
+      const base = await messagingGet('/NotificationSettings');
+      const routing = await messagingGet('/api/v1/alert-routing').catch(() => null);
+      return JSON.stringify({ ...base, alertRouting: routing?.data ?? null }, null, 2);
     }
 
     case 'notifications_set': {
@@ -6179,7 +6423,47 @@ async function handleTool(name, args) {
         if (args[f] !== undefined) current[f] = args[f];
       }
       await messagingPost('/NotificationSettings', current);
-      return JSON.stringify(await messagingGet('/NotificationSettings'), null, 2);
+      if (args.alertRouting && typeof args.alertRouting === 'object') {
+        await messagingPut('/api/v1/alert-routing', args.alertRouting);
+      }
+      const routing = await messagingGet('/api/v1/alert-routing').catch(() => null);
+      return JSON.stringify({ ...(await messagingGet('/NotificationSettings')), alertRouting: routing?.data ?? null }, null, 2);
+    }
+
+    case 'signature_policy_get': {
+      return JSON.stringify(await messagingGet('/Signatures/policy'), null, 2);
+    }
+
+    case 'signature_policy_set': {
+      // PUT replaces the row and silently turns an unknown mode into "follow company-wide", so validate and merge here.
+      // Same rules as cli/lib/signature-policy.js (keep the two in step).
+      const modes = { 'locked': 'admin_locked', 'company-default': 'company_default', 'personal-only': 'personal_only' };
+      const teamId = args.teamId === undefined || args.teamId === null ? 0 : args.teamId;
+      if (!Number.isInteger(teamId) || teamId < 0) throw new Error('teamId must be 0 (company-wide) or a team id');
+      const data = await messagingGet('/Signatures/policy');
+      const cur = (Array.isArray(data?.policies) ? data.policies : []).find((p) => p.teamId === teamId) ?? {};
+      const body = {
+        teamId,
+        mode: cur.mode ?? null,
+        corporateSignature: cur.corporateSignature || null,
+        disclaimerEnabled: cur.disclaimerEnabled ?? null,
+        disclaimerText: cur.disclaimerText || null,
+      };
+      if (args.mode !== undefined) {
+        if (args.mode === null || args.mode === 'default') body.mode = null;
+        else if (modes[args.mode]) body.mode = modes[args.mode];
+        else throw new Error('mode must be locked, company-default, personal-only or default');
+      }
+      if (args.corporateSignature !== undefined) body.corporateSignature = args.corporateSignature || null;
+      if (args.disclaimerEnabled !== undefined) {
+        if (args.disclaimerEnabled !== null && typeof args.disclaimerEnabled !== 'boolean') throw new Error('disclaimerEnabled must be true, false or null');
+        body.disclaimerEnabled = args.disclaimerEnabled;
+      }
+      if (args.disclaimerText !== undefined) body.disclaimerText = args.disclaimerText || null;
+      if (body.corporateSignature && body.corporateSignature.length > 4000) throw new Error('corporateSignature is limited to 4000 characters');
+      if (body.disclaimerText && body.disclaimerText.length > 2000) throw new Error('disclaimerText is limited to 2000 characters');
+      await messagingPut('/Signatures/policy', body);
+      return JSON.stringify(await messagingGet('/Signatures/policy'), null, 2);
     }
 
     case 'admin_startup_diagnostics': {
@@ -6468,7 +6752,7 @@ async function handleTool(name, args) {
     case 'chat_intelligence_themes': {
       const qs = new URLSearchParams();
       if (args.startDate) qs.set('startDate', args.startDate);
-      if (args.endDate)   qs.set('endDate', args.endDate);
+      if (args.endDate)   qs.set('endDate', exclusiveEnd(args.endDate));
       qs.set('groupBy', args.groupBy ?? 'month');
       if (args.deploymentId != null) qs.set('deploymentId', String(args.deploymentId));
       if (args.teamId != null) qs.set('teamId', String(args.teamId));
@@ -6562,6 +6846,8 @@ async function handleTool(name, args) {
 
     case 'workflow_toggle':
       return await rpc('workflow_toggle', args);
+    case 'workflow_run_now':
+      return await rpc('workflow_run_now', args);
 
     case 'workflow_create':
       return await rpc('workflow_create', args);
@@ -6941,6 +7227,13 @@ async function handleTool(name, args) {
       return `Connection test FAILED for agent ${args.id}: ${result?.error ?? 'unknown error'}`;
     }
 
+    case 'copilot_studio_ask': {
+      if (!args.id || !args.question) return 'id and question are required.';
+      const r = await api('POST', '/CopilotStudio/message', { configId: args.id, message: args.question });
+      return `kind: ${r?.kind}
+reply: ${r?.reply}`;
+    }
+
     // ── Monday.com field mapping / CRM search ──────────────────────────────
     // Wired to MondayController.cs actions: GetBoardColumns, GetFieldMapping,
     // UpdateFieldMapping, SearchContacts (routes under /Monday/...).
@@ -7093,7 +7386,7 @@ async function handleTool(name, args) {
 
     case 'teams_channel_config_update': {
       const body = {};
-      for (const k of ['enabled','welcomeMessage','teamId','clearTeamId'])
+      for (const k of ['enabled','welcomeMessage','teamId','clearTeamId','prechatEnabled','prechatFields','quickReplies','postChatEnabled','postChatMessage'])
         if (args[k] !== undefined) body[k] = args[k];
       return await api('PUT', '/TeamsBot/ChannelConfig', body);
     }
@@ -8065,6 +8358,17 @@ async function handleTool(name, args) {
       return `Index ready on site ${args.siteId}: ${idx?.name} (id=${idx?.id}, purpose=${idx?.purpose}, excludeFromAllSources=${!!idx?.excludeFromAllSources}).`;
     }
 
+    case 'index_set_profile': {
+      if (!args.siteId || !args.indexName) return 'siteId and indexName are required.';
+      const body = { indexName: args.indexName };
+      for (const k of ['chunkStrategy', 'chunkSize', 'chunkOverlap', 'purpose', 'searchSize', 'excludeFromAllSources']) {
+        if (args[k] !== undefined) body[k] = args[k];
+      }
+      const idx = await messagingRequest('PUT', `/KnowledgeSetup/Staff/${encodeURIComponent(args.siteId)}/index-profile`, body);
+      if (idx?.error) return `Set index profile error: ${idx.error}`;
+      return `Profile updated on site ${args.siteId}: ${idx?.name} (purpose=${idx?.purpose}, strategy=${idx?.chunkStrategy}, size=${idx?.chunkSize}, overlap=${idx?.chunkOverlap}, searchSize=${idx?.searchSize}, excludeFromAllSources=${!!idx?.excludeFromAllSources}). Re-ingest to apply to existing content.`;
+    }
+
     case 'uploaded_files_list': {
       const files = await messagingRequest('GET', '/uploadedFiles/list/AI');
       if (!Array.isArray(files) || !files.length) return 'No AI training files uploaded for this site.';
@@ -8088,7 +8392,7 @@ async function handleTool(name, args) {
     case 'service_level_report': {
       const qs = [
         args.startDate   ? `startDate=${args.startDate}`     : '',
-        args.endDate     ? `endDate=${args.endDate}`         : '',
+        args.endDate     ? `endDate=${encodeURIComponent(exclusiveEnd(args.endDate))}`         : '',
         args.granularity ? `granularity=${args.granularity}` : '',
       ].filter(Boolean).join('&');
       const r = await api('GET', `/ServiceLevel${qs ? '?' + qs : ''}`);
@@ -8138,7 +8442,7 @@ async function handleTool(name, args) {
     case 'report_agent_utilization': {
       const qs = [
         args.startDate ? `startDate=${args.startDate}` : '',
-        args.endDate   ? `endDate=${args.endDate}`     : '',
+        args.endDate   ? `endDate=${encodeURIComponent(exclusiveEnd(args.endDate))}`     : '',
       ].filter(Boolean).join('&');
       const rows = await api('GET', `/Reports/AgentUtilization${qs ? '?' + qs : ''}`);
       if (!Array.isArray(rows) || !rows.length) return 'No agent utilization data for this period.';
@@ -8259,10 +8563,36 @@ async function handleTool(name, args) {
       return `Export queued (id ${result.exportId}). ${result.message}`;
     }
 
+    case 'report_performance_by_country_get': {
+      const end = args.endDate ? new Date(args.endDate) : new Date();
+      const start = args.startDate ? new Date(args.startDate) : new Date(end.getTime() - 30 * 86400000);
+      if (isNaN(start) || isNaN(end)) return 'Error: startDate/endDate must be valid ISO 8601 dates.';
+      const r = await messagingPost('/reports/performance-by-country/query', {
+        start: start.toISOString(), end: end.toISOString(),
+        attribution: args.attribution || 'visitor', channels: Array.isArray(args.channels) ? args.channels : [],
+      });
+      const f = (v, s = '') => (v == null ? '-' : `${v}${s}`);
+      const row = x => `${(x.agentName || x.bucket).padEnd(24)} eng ${x.engagements} | handled ${x.handled} | missed ${x.missed} | abandoned ${x.abandoned} | bot containment ${f(x.botContainmentPct, '%')} | transfers ${x.transfersToAgent} | 1st resp ${f(x.avgFirstResponseSeconds, 's')} | handle ${f(x.avgHandleTimeMinutes, 'm')} | SL ${f(x.serviceLevelPct, '%')} | CSAT ${f(x.csatAvg)} (${x.csatCount}) | positive ${f(x.sentimentPositivePct, '%')}`;
+      return [`=== Performance by Country (${r.attribution}) ===`, ...(r.buckets || []).map(row), '', 'By agent:',
+        ...((r.agents || []).map(a => row(a) + (a.agentCountryNotSet ? '  [agent country not set]' : '')))].join('\n');
+    }
+
+    case 'report_performance_by_country_set_groups': {
+      const groups = await messagingGet('/reports/performance-by-country/groups');
+      let current;
+      if (args.map && typeof args.map === 'object') {
+        current = await messagingPut('/reports/performance-by-country/group-map', { map: args.map });
+      } else {
+        current = await messagingGet('/reports/performance-by-country/group-map');
+      }
+      const map = current?.map ?? {};
+      return ['Groups:', ...(Array.isArray(groups) ? groups : []).map(g => `  ${g.id} ${g.name} -> ${map[g.id] ?? '(unmapped, reports as Other)'}`)].join('\n');
+    }
+
     case 'call_center_report': {
       const qs = [
         args.startDate ? `start=${args.startDate}` : '',
-        args.endDate   ? `end=${args.endDate}`     : '',
+        args.endDate   ? `end=${encodeURIComponent(exclusiveEnd(args.endDate))}`     : '',
       ].filter(Boolean).join('&');
       const r = await api('GET', `/CallCenterAnalytics/Report${qs ? '?' + qs : ''}`);
       const v = r.volume ?? {};
@@ -8300,7 +8630,7 @@ async function handleTool(name, args) {
     case 'call_center_team_breakdown': {
       const qs = [
         args.startDate ? `start=${args.startDate}` : '',
-        args.endDate   ? `end=${args.endDate}`     : '',
+        args.endDate   ? `end=${encodeURIComponent(exclusiveEnd(args.endDate))}`     : '',
         args.slaThresholdSeconds ? `slaThresholdSeconds=${args.slaThresholdSeconds}` : '',
       ].filter(Boolean).join('&');
       let r;
@@ -8323,7 +8653,7 @@ async function handleTool(name, args) {
     case 'call_center_channel_breakdown': {
       const qs = [
         args.startDate ? `start=${args.startDate}` : '',
-        args.endDate   ? `end=${args.endDate}`     : '',
+        args.endDate   ? `end=${encodeURIComponent(exclusiveEnd(args.endDate))}`     : '',
         args.slaThresholdSeconds ? `slaThresholdSeconds=${args.slaThresholdSeconds}` : '',
       ].filter(Boolean).join('&');
       let r;
@@ -8830,23 +9160,13 @@ async function handleTool(name, args) {
     }
 
     case 'velaro_logs_search': {
-      const from   = new Date(Date.now() - parseDuration(args.last));
-      const params = new URLSearchParams({ from: from.toISOString(), take: String(args.take ?? 50) });
-      if (args.q)             params.set('q',             args.q);
-      if (args.level)         params.set('level',         args.level.toUpperCase());
-      if (args.logger)        params.set('logger',        args.logger);
-      if (args.integration)   params.set('integration',   args.integration);
-      if (args.siteId)        params.set('siteId',        String(args.siteId));
-      if (args.source)        params.set('source',        args.source);
-      if (args.platform)      params.set('platform',      args.platform);
-      if (args.environment)   params.set('environment',   args.environment);
-      if (args.correlationId) params.set('correlationId', args.correlationId);
-      if (args.regex)         params.set('regex',         'true');
+      const { from, to } = resolveLogWindow(args);
+      const params = buildRawLogQuery(args, from, to);
       const resp = await messagingApi(`/superadmin/logs/search?${params}`, { timeoutMs: 40000 });
       const entries = extractLogEntries(resp);
       const meta = describeRawMeta(resp);   // searchPath/scannedRows/truncated: a 0 or short list is never ambiguous
       if (!entries.length) return `No results. ${meta}`;
-      const lines = [`${entries.length} result(s) from ${from.toISOString().slice(0, 16)} UTC. ${meta}\n`];
+      const lines = [`${entries.length} result(s) from ${from.toISOString().slice(0, 16)} to ${to.toISOString().slice(0, 16)} UTC. ${meta}\n`];
       for (const e of entries) {
         const ts    = new Date(e.timestamp ?? e.LogTimestamp).toISOString().replace('T', ' ').slice(0, 19);
         const lvl   = (e.Level ?? e.level ?? '?').padEnd(5);
@@ -9247,14 +9567,41 @@ async function handleTool(name, args) {
         coaching_queue: 'coaching-queue', sentiment_breakdown: 'sentiment-breakdown', topic_radar: 'topic-radar',
         weekly_brief: 'weekly-brief', weekly_brief_send_test: 'weekly-brief/send-test',
         repeat_contact: 'repeat-contact', demand_coverage: 'demand-coverage', bot_containment: 'bot-containment',
-        effort_index: 'effort-index', promise_ledger: 'promise-ledger',
+        effort_index: 'effort-index', promise_ledger: 'promise-ledger', new_agent_ramp: 'new-agent-ramp',
       };
       if (args.report === 'promise_dismiss') {
         if (!args.promiseId) throw new Error('promiseId is required for promise_dismiss');
         return JSON.stringify(await messagingPost('/api/enterprise-reports/promise-ledger/' + encodeURIComponent(String(args.promiseId)) + '/dismiss', {}), null, 2);
       }
+      if (args.report === 'year_in_review') {
+        // POST starts a build (202 {id}); GET .../{id} -> {status, downloadUrl, error}. 403 when EnableEnterpriseReportsYearInReview is off.
+        if (args.buildId) return JSON.stringify(await messagingGet('/api/enterprise-reports/year-in-review/' + encodeURIComponent(String(args.buildId))), null, 2);
+        const zone = 'America/Los_Angeles';
+        const keyRe = /^(\d{4})-(\d{2})-(\d{2})$/;
+        const addDays = (k, n) => { const m = keyRe.exec(k); return new Date(Date.UTC(+m[1], +m[2] - 1, +m[3] + n)).toISOString().slice(0, 10); };
+        const offsetMs = (ms) => {
+          const ps = new Intl.DateTimeFormat('en-US', { timeZone: zone, hourCycle: 'h23', year: 'numeric', month: '2-digit', day: '2-digit', hour: '2-digit', minute: '2-digit', second: '2-digit' }).formatToParts(new Date(ms));
+          const g = (t) => Number(ps.find((p) => p.type === t).value);
+          return Date.UTC(g('year'), g('month') - 1, g('day'), g('hour'), g('minute'), g('second')) - Math.floor(ms / 1000) * 1000;
+        };
+        const midnightIso = (k) => {
+          if (!keyRe.test(k || '')) throw new Error('from/to must be yyyy-MM-dd');
+          const m = keyRe.exec(k);
+          const wall = Date.UTC(+m[1], +m[2] - 1, +m[3]);
+          let t = wall - offsetMs(wall);
+          t = wall - offsetMs(t);
+          return new Date(t).toISOString();
+        };
+        const today = new Intl.DateTimeFormat('en-CA', { timeZone: zone, year: 'numeric', month: '2-digit', day: '2-digit' }).format(new Date());
+        const defFrom = String(Number(today.slice(0, 4)) - 1).padStart(4, '0') + '-' + today.slice(5, 7) + '-01';
+        const defTo = addDays(today.slice(0, 7) + '-01', -1);
+        const f = args.from || defFrom;
+        const t = args.to || defTo;
+        if (f > t) throw new Error('from must be on or before to');
+        return JSON.stringify(await messagingPost('/api/enterprise-reports/year-in-review', { from: midnightIso(f), to: midnightIso(addDays(t, 1)) }), null, 2);
+      }
       const seg = ER_PATHS[args.report];
-      if (!seg) throw new Error('report must be one of: ' + Object.keys(ER_PATHS).join(', '));
+      if (!seg) throw new Error('report must be one of: ' + Object.keys(ER_PATHS).join(', ') + ', promise_dismiss, year_in_review');
       if (args.report === 'weekly_brief_send_test') return JSON.stringify(await messagingPost('/api/enterprise-reports/' + seg, {}), null, 2);
       const qs = new URLSearchParams();
       for (const k of ['from', 'to', 'groupBy', 'deploymentId', 'teamId', 'threshold', 'perAgent', 'limit', 'days', 'windowDays', 'weeks', 'handleMinutes', 'maxConcurrent', 'timeZone', 'lowScore', 'includeDemo']) {
@@ -9297,8 +9644,11 @@ async function handleTool(name, args) {
     }
 
     case 'report_backfill': {
+      if (args.status === true) return JSON.stringify(await messagingGet(`/Reports/backfill/${encodeURIComponent(args.type)}/status`), null, 2);
+      if (!args.from || !args.to) throw new Error('from and to are required (yyyy-MM-dd) unless status=true');
       const qs = new URLSearchParams({ from: String(args.from), to: String(args.to), apply: String(args.apply === true) });
       const r = await messagingPost(`/Reports/backfill/${encodeURIComponent(args.type)}?${qs}`);
+      if (args.apply === true && r && r.runId) return (r.alreadyRunning ? `A run is already ${r.status} for this site; not starting another.\n` : 'Backfill QUEUED (runs in the background; call again with status=true to read progress)\n') + JSON.stringify(r, null, 2);
       return (args.apply === true ? 'Backfill APPLIED\n' : 'Backfill PREVIEW (nothing written; pass apply=true to write)\n') + JSON.stringify(r, null, 2);
     }
 
@@ -9393,15 +9743,25 @@ async function handleTool(name, args) {
       ].join('\n');
     }
 
+    case 'avatar_session_readiness': {
+      const data = await messagingRequest('GET', `/avatar/diagnostics/session-readiness?siteId=${encodeURIComponent(args.siteId)}`);
+      return JSON.stringify(data, null, 2);
+    }
+
     case 'avatar_get_config': {
       const data = await api('GET', `/Avatar/superadmin/status?siteId=${args.siteId}`);
-      if (!data.configured) return `Site ${args.siteId}: AI Video Avatar NOT configured (no saved config).`;
+      let heyGenLine = 'unknown';
+      try { const ent = await api('GET', `/Entitlements/${args.siteId}`); heyGenLine = ent?.features?.EnableAvatarHeyGen ? 'yes' : 'no'; } catch { /* entitlement lookup is best-effort */ }
+      if (!data.configured) return `Site ${args.siteId}: AI Video Avatar NOT configured (no saved config). HeyGen entitled: ${heyGenLine}`;
       return [
         `Site ${args.siteId}: AI Video Avatar ${data.enabled ? 'ENABLED' : 'configured but DISABLED'}`,
         `  Provider:        ${data.providerSlug}`,
         `  Avatar ID:       ${data.avatarId || '(provider default)'}`,
+        `  Face per provider: ${data.avatarIdByProvider && Object.keys(data.avatarIdByProvider).length ? JSON.stringify(data.avatarIdByProvider) : '(none saved)'} (read-only)`,
+        `  Keep running on agent join: ${data.enabledOnAgentTransfer ? 'yes' : 'no'}`,
         `  Voice ID:        ${data.voiceId || '(site default)'}`,
         `  Enabled:         ${data.enabled}`,
+        `  HeyGen entitled: ${heyGenLine}`,
         `  "Call me":       ${data.showCallMeOption}`,
         `  Callback window: ${data.callbackConfirmWindowMinutes} min`,
         `  Display name:    ${data.displayName || '(AI)'}`,
@@ -9418,12 +9778,17 @@ async function handleTool(name, args) {
       if (args.voiceId !== undefined) body.voiceId = args.voiceId;
       if (args.enabled !== undefined) body.enabled = args.enabled;
       if (args.showCallMeOption !== undefined) body.showCallMeOption = args.showCallMeOption;
+      if (args.enabledOnAgentTransfer !== undefined) body.enabledOnAgentTransfer = args.enabledOnAgentTransfer;
       if (args.callbackConfirmWindowMinutes !== undefined) body.callbackConfirmWindowMinutes = args.callbackConfirmWindowMinutes;
       if (args.displayName !== undefined) body.displayName = args.displayName;
       if (args.showBadge !== undefined) body.showBadge = args.showBadge;
       if (args.sizePx !== undefined) body.sizePx = args.sizePx;
       if (args.allowVisitorCollapse !== undefined) body.allowVisitorCollapse = args.allowVisitorCollapse;
+      if (args.heyGenEnabled !== undefined) {
+        await api('POST', `/Entitlements/${args.siteId}/override`, { featureKey: 'EnableAvatarHeyGen', value: args.heyGenEnabled, reason: 'avatar_set_config heyGenEnabled' });
+      }
       if (args.motionLevel !== undefined) body.motionLevel = parseAvatarMotionLevel(args.motionLevel);
+      if (args.heyGenEnabled !== undefined && !Object.keys(body).length && args.motionIntensityPercent === undefined && args.maxAvatarMinutesPerMonth === undefined && args.maxAvatarTtsChars === undefined) return `Site ${args.siteId}: EnableAvatarHeyGen=${args.heyGenEnabled}`;
       if (args.motionIntensityPercent !== undefined) {
         if (!Number.isInteger(args.motionIntensityPercent) || args.motionIntensityPercent < 25 || args.motionIntensityPercent > 150) throw new Error('motionIntensityPercent must be a whole number between 25 and 150.');
         body.motionIntensityPercent = args.motionIntensityPercent;
@@ -9457,6 +9822,22 @@ async function handleTool(name, args) {
       return JSON.stringify(await messagingRequest('PUT', `/avatar/workflows/${Number(args.workflowId)}/override`, avatarOverrideBody(args)), null, 2);
     case 'avatar_reset_workflow':
       return JSON.stringify(await messagingRequest('DELETE', `/avatar/workflows/${Number(args.workflowId)}/override`), null, 2);
+    case 'avatar_set_workflow_switch': {
+      const mode = String(args.mode ?? '').trim().toLowerCase();
+      if (!['on', 'off', 'rules'].includes(mode)) throw new Error('mode must be one of: on, off, rules');
+      const id = Number(args.workflowId);
+      if (!Number.isInteger(id) || id <= 0) throw new Error('workflowId must be a positive whole number');
+      return JSON.stringify(await messagingRequest('PUT', `/avatar/workflows/${id}/enabled`, { mode }), null, 2);
+    }
+    case 'avatar_bulk_set_switch': {
+      const mode = String(args.mode ?? '').trim().toLowerCase();
+      if (!['on', 'off', 'rules'].includes(mode)) throw new Error('mode must be one of: on, off, rules');
+      const workflowIds = (args.workflowIds ?? []).map(Number);
+      const groupIds = (args.groupIds ?? []).map(Number);
+      if (workflowIds.length + groupIds.length === 0) throw new Error('Pass workflowIds and/or groupIds');
+      if (workflowIds.length + groupIds.length > 500) throw new Error('Too many rows in one call (max 500)');
+      return JSON.stringify(await messagingRequest('PUT', '/avatar/overrides/enabled', { mode, workflowIds, groupIds }), null, 2);
+    }
     case 'avatar_reset_all_overrides':
       return JSON.stringify(await messagingRequest('POST', '/avatar/group-overrides/reset-all', {}), null, 2);
 
@@ -9980,7 +10361,11 @@ async function handleTool(name, args) {
     }
 
     case 'magento_test_connection': {
-      const r = await api('POST', '/Magento/Configs/Test', { storeUrl: args.storeUrl, accessToken: args.accessToken });
+      if (!args.configId && (!args.storeUrl || !args.accessToken)) return 'Provide configId, or both storeUrl and accessToken.';
+      const r = args.configId
+        ? await api('POST', `/Magento/Configs/${encodeURIComponent(args.configId)}/Test`)
+        : await api('POST', '/Magento/Configs/Test', { storeUrl: args.storeUrl, accessToken: args.accessToken });
+      if (r && r.valid === false) return `❌ Connection failed: ${r.error}`;
       return `✅ Connected to "${r.storeName}" (${r.edition} ${r.version})`;
     }
 
@@ -10046,6 +10431,13 @@ async function handleTool(name, args) {
     }
 
     // ── Business actions + SAP ────────────────────────────────────────────────
+    case 'salesforce_diagnose': {
+      if (!args.siteId) return 'siteId is required.';
+      const deep = args.deep === false ? 'false' : 'true';
+      const r = await messagingRequest('GET', `/diagnostics/test-salesforce?siteId=${encodeURIComponent(args.siteId)}&deep=${deep}`);
+      return JSON.stringify(r, null, 2);
+    }
+
     case 'sap_diagnose': {
       if (!args.siteId) return 'siteId is required.';
       const deep = args.deep === false ? 'false' : 'true';
@@ -10134,6 +10526,37 @@ async function handleTool(name, args) {
       return `CTI token generated/rotated.\nDial URL: ${urls.dialUrlTemplate}\nScreen-pop URL: ${urls.screenPopUrl}`;
     }
 
+    case 'netsuite_suiteapp_download': {
+      const includeKey = args.includeKey !== false;
+      const r = await messagingGet(`/api/v1/CrmEmbed/suiteapp-package?includeKey=${includeKey}&format=json`);
+      const d = r?.data ?? r;
+      if (!d?.contentBase64) throw new Error('SuiteApp package was not returned.');
+      const { writeFileSync } = await import('node:fs');
+      const { tmpdir } = await import('node:os');
+      const out = args.outputPath || _join(tmpdir(), d.fileName || 'velaro-netsuite-screenpop-suiteapp.zip');
+      writeFileSync(out, Buffer.from(d.contentBase64, 'base64'));
+      return `Saved ${out}. ` + (d.keyIncluded
+        ? 'Your Velaro key is already inside: no NetSuite API Secret and nothing to paste. Deploy with suitecloud (see SETUP.txt in the zip). Keep the zip private.'
+        : `Key-less zip. In NetSuite create an API Secret: type ID ${d.secretFormId} (NetSuite adds the prefix, giving ${d.secretFullId}), paste your crm_embed_ key as Password.`);
+    }
+    case 'netsuite_config_delete': {
+      await messagingDel(`/Netsuite/Integrations/${args.configId}`);
+      return `Deleted NetSuite config ${args.configId} (a missing config is a no-op).`;
+    }
+    case 'netsuite_m2m_clear_legacy': {
+      const r = await messagingPost('/NetSuite/M2M/ClearLegacy', { id: args.configId });
+      return `Legacy consumer secret/token cleared for config ${r?.id ?? args.configId} (authType ${r?.authType ?? 'm2m'}).`;
+    }
+    case 'netsuite_embed_status': {
+      const r = await messagingGet('/api/v1/CrmEmbed/embed-status');
+      const d = r?.data ?? r;
+      if (!d?.hasEmbedKey) return 'No embed key exists for this site yet. The SuiteApp cannot connect until one is created.';
+      if (d.connected) return `SuiteApp connected. Last polled ${d.lastPolledAt}.`;
+      return d.lastPolledAt
+        ? `Embed key exists but the SuiteApp is not connected (last polled ${d.lastPolledAt}, outside the connected window).`
+        : 'Embed key exists but the SuiteApp has not polled yet.';
+    }
+
     case 'netsuite_m2m_init': {
       const r = await messagingPost('/NetSuite/M2M/Init', { id: args.configId ?? null, company: args.company, displayName: args.displayName });
       return `Config ${r.id ?? args.configId ?? 'new'}. Upload this certificate in NetSuite (Setup > Integration > Manage Authentication > OAuth 2.0 Client Credentials (M2M) Setup):\n${r.certificatePem ?? '(none returned)'}\n${Array.isArray(r.steps) ? r.steps.map((x, i) => `${i + 1}. ${x}`).join('\n') : ''}`;
@@ -10182,6 +10605,20 @@ async function handleTool(name, args) {
       return `${result.success ? 'Success' : 'Failed'}: ${result.message ?? '(no message)'}`;
     }
 
+    // ── Shopify write policy (velaro-messaging /api/Shopify/WritePolicy) ───────
+    case 'shopify_get_write_policy': {
+      return JSON.stringify(await messagingGet('/Shopify/WritePolicy'), null, 2);
+    }
+    case 'shopify_set_write_policy': {
+      const body = {};
+      for (const k of ['enableShopifyWrite', 'requireConfirmation', 'maxRefundAmount', 'maxDiscountPercent', 'maxDiscountFixedAmount']) {
+        if (args[k] !== undefined) body[k] = args[k];
+      }
+      if (!Object.keys(body).length) throw new Error('Provide at least one field to change.');
+      const result = await messagingPut('/Shopify/WritePolicy', body);
+      return `Shopify write policy updated.
+${JSON.stringify(result, null, 2)}`;
+    }
     // ── Webflow (config CRUD) ──────────────────────────────────────────────────
     case 'webflow_get_config': {
       if (args.configId) {
@@ -10742,6 +11179,19 @@ async function handleTool(name, args) {
       return lines.join(String.fromCharCode(10));
     }
 
+    case 'entitlement_report_packages': {
+      const q = args && args.siteId ? `?siteId=${encodeURIComponent(args.siteId)}` : '';
+      const pkg = await api('GET', `/Entitlements/report-packages${q}`);
+      const lines = [`${pkg.top.name} (${pkg.top.slug}) - plan ${pkg.plan}, default OFF${pkg.siteId ? `, site ${pkg.siteId}${pkg.top.enabled ? ' [ALL ON]' : ''}` : ''}`, `  ${pkg.top.tagline}`];
+      for (const c of pkg.categories) {
+        lines.push('');
+        lines.push(`${c.name} (${c.slug})${pkg.siteId ? ` [${c.enabled ? 'ON ' : 'off'}] ${c.enabledCount}/${c.reportCount} reports` : ` ${c.reportCount} reports`}`);
+        lines.push(`  ${c.tagline}`);
+        for (const r of c.reports) lines.push(`  ${pkg.siteId ? (r.enabled ? '[ON ] ' : '[off] ') : ''}${r.name} (${r.id}) - package ${r.packageSlug}, key ${r.packageKey}`);
+      }
+      return lines.join(String.fromCharCode(10));
+    }
+
     case 'entitlement_list_features': {
       const features = await api('GET', '/Entitlements/features');
       const byCategory = {};
@@ -10946,7 +11396,12 @@ async function handleTool(name, args) {
           throw new Error('Date range too large. Worked Hours can be queried for at most 90 days at a time.');
         }
       }
-      return await messagingPost('/Reports/worked-hours-breakdown', { Start: args.start, End: args.end });
+      // Server End is exclusive: a date-only end means "through the end of that day".
+      let endValue = args.end;
+      if (/^\d{4}-\d{2}-\d{2}$/.test(String(args.end).trim()) && !Number.isNaN(endMs)) {
+        endValue = new Date(endMs + 24 * 60 * 60 * 1000).toISOString();
+      }
+      return await messagingPost('/Reports/worked-hours-breakdown', { Start: args.start, End: endValue });
     }
 
     // -- Pickup & Reminder Texting --
@@ -10994,6 +11449,25 @@ async function handleTool(name, args) {
       return JSON.stringify(result, null, 2);
     }
 
+    case 'apple_pay_get_config': {
+      const config = await messagingGet('/ApplePayConfig');
+      return JSON.stringify(config, null, 2);
+    }
+
+    case 'apple_pay_update_config': {
+      // Field names must match ApplePayConfigUpdateRequest exactly (apply-if-present: undefined is dropped by JSON).
+      const body = {
+        merchantDisplayName: args.merchantDisplayName,
+        isTestMode:          args.isTestMode,
+        bubbleLogoBase64:    args.bubbleLogoBase64,
+      };
+      const existing = await messagingGet('/ApplePayConfig');
+      const result = existing && existing.id > 0
+        ? await messagingPut(`/ApplePayConfig/${existing.id}`, body)
+        : await messagingPost('/ApplePayConfig', body);
+      return JSON.stringify(result, null, 2);
+    }
+
     // -- Payment Recovery --
     case 'payment_recovery_send': {
       // Field names must match SendPaymentReminderRequest exactly.
@@ -11658,7 +12132,7 @@ const server = new Server(
   { capabilities: { tools: {}, prompts: {} } }
 );
 
-server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS.map(withAnnotations) }));
 
 server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: PROMPTS }));