@velaro/mcp-server 0.6.54 → 0.6.56

package/README.md

@@ -132,6 +132,11 @@ This works with any MCP client that supports HTTP/SSE transport — including Cl
 | `team_list` | List all teams for this site |
 | `routing_list` | List all routing rules ordered by priority |
 | `routing_get` | Get routing rule details including rule and value JSON |
+| `routing_get_policy` | Site auto-routing policy including reassignment mode and the agent inactivity chain |
+| `routing_update_policy` | Update the policy, reassignment mode and inactivity chain (mode is always sent back) |
+| `routing_simulate_inactivity` | DRY RUN of the inactivity chain for a mocked scenario, nothing is sent |
+| `routing_explain_precedence` | Which routing rule wins when an agent goes silent, plus conflict warnings |
+| `routing_inactivity_transfers` | Count agent inactivity transfers: total, per agent, per day |
 
 ### Site
 | Tool | What It Does |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/mcp-server",
-  "version": "0.6.54",
+  "version": "0.6.56",
   "description": "Velaro MCP server — connect Claude and other AI agents directly to your Velaro account: KB, workflows, bots, conversations, contacts, routing, and more.",
   "type": "module",
   "bin": {
@@ -14,7 +14,8 @@
     "qs": "^6.16.0"
   },
   "overrides": {
-    "qs": "^6.16.0"
+    "qs": "^6.16.0",
+    "hono": "^4.13.5"
   },
   "scripts": {
     "start": "node server.js"
@@ -43,5 +44,8 @@
     "server.js",
     "server.json",
     "README.md"
-  ]
+  ],
+  "devDependencies": {
+    "license-checker-rseidelsohn": "^4.4.2"
+  }
 }

package/server.js

@@ -62,6 +62,12 @@ const MESSAGING_API = process.env.VELARO_MESSAGING_API || null;
 const MCP_KEY       = process.env.VELARO_MCP_KEY;
 const JWT           = process.env.VELARO_JWT;
 
+// mcp/staff-server.js defaults to staging instead -- the two servers' defaults intentionally
+// differ, but a zero-result lookup gives no hint which environment was actually searched
+// either way. See ENV_LABEL in staff-server.js for the incident this class of confusion caused
+// (a real production customer read as "doesn't exist" from a staging-scoped search).
+const ENV_LABEL = API_BASE.includes('staging') ? 'staging' : 'production';
+
 // Known admin API hosts, for tools that let a caller explicitly target one environment
 // regardless of what this server process's own API_BASE is configured to (see the `env` param
 // on the calendly_* superadmin tools below). Deliberately NOT used as a default anywhere —
@@ -561,6 +567,18 @@ const TOOLS = [
     },
   },
 
+  {
+    name: 'site_scraper_usage',
+    description: 'Velaro staff only. Scraper/upload/chunk consumption for ANY site in one call: pages this month vs budget (both the admin and messaging ledgers), upload pages, OCR pages, jobs today vs daily cap, and chunks indexed vs MaxIndexedChunkTotal with chunks grouped by index name. Wraps GET ScraperJobs/StaffUsage/{siteId} (IsVelaroAdminAsync + super-admin enforced server-side). Read-only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId: { type: 'number', description: 'Target site ID (need not be your own)' },
+      },
+      required: ['siteId'],
+    },
+  },
+
   // ── Startup migration diagnostics (AdminStartupDiagnostics canary table) ──
   {
     name: 'admin_startup_diagnostics',
@@ -1446,7 +1464,21 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
         preferPreviousAgentOnTimeout:     { type: 'boolean', description: 'On timeout, prefer agent from visitor\'s prior session (loyalty routing)' },
         agentFollowUpFlagEnabled:         { type: 'boolean', description: 'Flag conversations that required multiple reroutes' },
         queueUnavailableGracePeriodSeconds: { type: 'number', description: 'Wait before returning unavailable when agents are transiently busy (seconds)' },
-        terminalActionOverride:           { type: 'number',  description: 'Terminal action: 0=Survey 1=CreateTicket 2=SurveyAndCreateTicket 3=Queue 4=OfflineMessage 5=NoOp. Null = default (Survey).' },
+        terminalActionOverride:           { type: 'number',  description: 'Terminal action: 0=Survey 1=CreateTicket 2=SurveyAndCreateTicket 3=Queue 4=OfflineMessage 5=NoOp 6=EndChat 7=NotifyManager 8=RunWorkflow (needs inactivityTerminalWorkflowId). Null = default (Survey).' },
+        exhaustionMessageTemplate:        { type: 'string',  description: 'Message sent to the visitor with the final action (max 500 characters).' },
+        reassignmentMode:                 { type: 'string',  enum: ['Observe','QueueOnly','Reassign'], description: "Observe (default) only records what would happen; QueueOnly returns a silent agent's chat to the group queue; Reassign hands it to the next agent. Backup group and no-agent-available steps need Reassign." },
+        inactivityChainEnabled:           { type: 'boolean', description: 'Master switch for the agent inactivity fallback chain. Off by default.' },
+        inactivityBackupTeamId:           { type: 'number',  description: "Backup group to try when nobody in the chat's own group is available." },
+        inactivityBackupTeamAfterSeconds: { type: 'number',  description: 'Seconds with no available agent before the backup group is tried (0-7200).' },
+        inactivityNoAgentActionAfterSeconds: { type: 'number', description: 'Seconds with no available agent before the final action runs (0-14400).' },
+        inactivityTerminalWorkflowId:     { type: 'number',  description: 'Workflow to run when terminalActionOverride is 8.' },
+        rerouteOnAgentUnavailable:        { type: 'boolean', description: 'Presence trigger: also treat a chat as inactive when its agent is no longer Available.' },
+        alertAvailableAgentsOnRelease:    { type: 'boolean', description: 'Alert available agents when an inactive chat returns to the queue.' },
+        notifyManagersOnInactivity:       { type: 'boolean', description: 'Alert managers about inactive chats.' },
+        rerouteCooldownSeconds:           { type: 'number',  description: 'Cooldown between moves of the same chat (0-3600).' },
+        queueEscalationAfterMinutes:      { type: 'number',  description: 'Widen the queue alert to backup group and managers after this many minutes (1-240).' },
+        inactivityVisitorText:            { type: 'string',  description: 'Message the visitor sees when the chat is moved (max 500 characters).' },
+        inactivityAgentText:              { type: 'string',  description: 'Message agents see on a re-queued chat (max 500 characters).' },
       },
       required: [],
     },
@@ -1462,6 +1494,41 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['conversationId'],
     },
   },
+  {
+    name: 'routing_simulate_inactivity',
+    description: 'DRY RUN: simulate what the agent inactivity chain would do for a mocked scenario, using the saved routing settings. Answers "what would happen if an agent goes silent and nobody is available for N minutes". Returns which rule applies, the safety-gate result (cooldown, duplicate, hop cap), the decision, the exact visitor and agent messages, and the rules that also matched but lost. Sends nothing and touches no live chat. Uses the same decision code the timer job runs.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        teamId:                    { type: 'number',  description: 'Group id whose own policy to simulate. Omit for the site default.' },
+        noAgentSeconds:            { type: 'number',  description: 'Seconds nobody has been available (0 = just now). Default 0.' },
+        attemptsUsed:              { type: 'number',  description: 'Moves already used on the chat. Default 0.' },
+        inactivityStep:            { type: 'number',  description: '0 = nothing tried, 1 = offered to backup group, 2 = final action applied. Default 0.' },
+        secondsSinceLastTransfer:  { type: 'number',  description: 'Seconds since the chat was last moved. Omit if never moved.' },
+        sameEpisodeAlreadyHandled: { type: 'boolean', description: 'True to simulate the same silence being delivered twice (duplicate guard).' },
+        fromAgentName:             { type: 'string',  description: 'Name of the silent agent, used in the alert text.' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'routing_explain_precedence',
+    description: 'Explain which routing rule wins when an agent goes silent: the fixed evaluation order (group policy over site default, kill switch, reassignment mode, detector, safety gate, same-group agents, backup group, final action, and the other mechanisms this policy does not control), plus warnings where one policy shadows or contradicts another. Use for "why did the site default not apply to team X" or "which rule wins".',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'routing_inactivity_transfers',
+    description: 'Count and break down "agent inactivity transfers" (chats taken from an agent who stopped responding) for your site: total, per agent, per day. Pass agentName (display name contains) or agentId to answer "how many inactivity transfers for agent X". Days 1 to 92, default 30.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        days:      { type: 'number', description: 'Lookback in days (1-92). Default 30.' },
+        agentName: { type: 'string', description: 'Agent display name (partial match) to filter to.' },
+        agentId:   { type: 'number', description: 'Exact agent id to filter to.' },
+      },
+      required: [],
+    },
+  },
   {
     name: 'routing_explain_decision',
     description: 'Plain-English explanation of every routing step for a conversation. Returns a human-readable summary ("10:32 AM: Warning sent to visitor… 10:37 AM: Rerouted from Alex → Sarah…"), the policy settings that were active, and enriched events with agent names resolved. Use to answer "why did this chat route to X?" or "why was this chat missed?"',
@@ -1544,6 +1611,120 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     description: 'Show what is currently indexed for the site: document counts per source type (kb_article, scraper_page, bigcommerce_product, etc). Use to verify ingestion completed and data is present.',
     inputSchema: { type: 'object', properties: {} },
   },
+  {
+    name: 'index_move_preview',
+    description: 'Preview moving (or copying) documents between two knowledge indexes on the site. Writes nothing. Returns document/chunk/page counts, per-document method (copy_vectors, rechunk, already_in_target, blocked), quota effect, and whether it can run. No rescan and no OCR is ever needed. Moving into a troubleshooting index needs the EnableTroubleshootingKnowledge entitlement. Wraps POST IndexMove/Preview (velaro-messaging); the site comes from the caller auth, never an argument.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fromIndex: { type: 'string', description: 'Source index name' },
+        toIndex:   { type: 'string', description: 'Target index name' },
+        kind:      { type: 'string', enum: ['move', 'copy'], description: 'Default move' },
+        skipBlocked: { type: 'boolean', description: 'Leave blocked documents in place and move the rest' },
+        selector: {
+          type: 'object',
+          description: 'What to move. Needs at least one field or all:true. Fields: all (bool), jobId, urlPrefix, sourceIds[], fileNames[], docIds[] (numbers), sourceType (website_page | video_transcript | uploaded_document | onedrive_file | custom_content).',
+        },
+      },
+      required: ['fromIndex', 'toIndex', 'selector'],
+    },
+  },
+  {
+    name: 'index_move_execute',
+    description: 'Run a move/copy between knowledge indexes. Always call index_move_preview first and check canExecute. Write-then-delete and resumable: content is never missing from both indexes. Returns a moveId; poll index_move_status. Wraps POST IndexMove/Execute.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fromIndex: { type: 'string' },
+        toIndex:   { type: 'string' },
+        kind:      { type: 'string', enum: ['move', 'copy'] },
+        skipBlocked: { type: 'boolean' },
+        selector: {
+          type: 'object',
+          description: 'What to move. Needs at least one field or all:true. Fields: all (bool), jobId, urlPrefix, sourceIds[], fileNames[], docIds[] (numbers), sourceType (website_page | video_transcript | uploaded_document | onedrive_file | custom_content).',
+        },
+      },
+      required: ['fromIndex', 'toIndex', 'selector'],
+    },
+  },
+  {
+    name: 'index_split_preview',
+    description: 'Detect manual-like documents in a general index and preview moving them into an existing troubleshooting-purpose index. Writes nothing. Wraps POST IndexMove/Split/Preview. Use index_split_execute to run it.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fromIndex: { type: 'string' },
+        toIndex:   { type: 'string', description: 'Existing troubleshooting-purpose index' },
+        docIds:    { type: 'array', items: { type: 'number' }, description: 'Only these documents (default: every detected manual)' },
+        skipBlocked: { type: 'boolean' },
+      },
+      required: ['fromIndex', 'toIndex'],
+    },
+  },
+  {
+    name: 'index_split_execute',
+    description: 'Run a split: move detected manuals from a general index into an existing troubleshooting-purpose index. Call index_split_preview first. Resumable and undoable via index_move_control. Wraps POST IndexMove/Split/Execute.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fromIndex: { type: 'string' },
+        toIndex:   { type: 'string' },
+        docIds:    { type: 'array', items: { type: 'number' } },
+        skipBlocked: { type: 'boolean' },
+      },
+      required: ['fromIndex', 'toIndex'],
+    },
+  },
+  {
+    name: 'index_move_status',
+    description: 'Status of one move (moveId) or the recent moves (omit moveId): status, per-document progress, canResume/canAbort/canUndo. Wraps GET IndexMove/Moves[/{id}].',
+    inputSchema: {
+      type: 'object',
+      properties: { moveId: { type: 'string' } },
+    },
+  },
+  {
+    name: 'index_move_control',
+    description: 'Resume a stopped move, abort a queued/failed move that has not started removing content, or undo a completed move. Wraps POST IndexMove/Moves/{id}/Resume|Abort|Undo.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        moveId: { type: 'string' },
+        action: { type: 'string', enum: ['resume', 'abort', 'undo'] },
+      },
+      required: ['moveId', 'action'],
+    },
+  },
+  {
+    name: 'index_mixed_content',
+    description: 'Check whether a general index holds manual-like documents that belong in a Troubleshooting Assistant index. Read-only. Wraps GET IndexMove/MixedContent.',
+    inputSchema: {
+      type: 'object',
+      properties: { indexName: { type: 'string' } },
+      required: ['indexName'],
+    },
+  },
+  {
+    name: 'index_integrity_check',
+    description: 'Read-only integrity report for a knowledge index: orphan chunks, records without chunks, count mismatches, duplicate records. Wraps GET IndexMove/Integrity.',
+    inputSchema: {
+      type: 'object',
+      properties: { indexName: { type: 'string' } },
+      required: ['indexName'],
+    },
+  },
+  {
+    name: 'index_integrity_repair',
+    description: 'Repair a knowledge index. Additive and idempotent: corrects counts and adopts orphan chunks into tracking rows, never deletes vectors. removeDuplicateRecords also removes duplicate tracking rows. Run index_integrity_check first. Wraps POST IndexMove/Integrity/Repair.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        indexName: { type: 'string' },
+        removeDuplicateRecords: { type: 'boolean' },
+      },
+      required: ['indexName'],
+    },
+  },
   {
     name: 'index_ingest',
     description: 'Trigger ingestion of a scraper job into the knowledge index. Fires in the background; use index_status after ~2 minutes to verify chunks appeared.',
@@ -2282,6 +2463,17 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['siteId'],
     },
   },
+  {
+    name: 'tour_insights',
+    description: 'Moshky setup-tour funnel and feedback (Velaro staff only). Without siteId: per-tour, per-step counts of offered/opened/step_viewed/arrived/stuck/completed/dismissed/load_error over the last N days plus recent scrubbed feedback. With siteId: that one site\'s tour event timeline and feedback. Feedback comments are PII-scrubbed and for staff eyes only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId: { type: 'number', description: 'Optional. When set, returns that site\'s tour timeline instead of the cross-site funnel.' },
+        days:   { type: 'number', description: 'Look-back window in days (default 30, max 365)' },
+      },
+    },
+  },
   {
     name: 'support_extend_subscription',
     description: 'Extend a customer site\'s subscription expiration by N days. SuperAdmin only.',
@@ -2886,6 +3078,18 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     },
   },
 
+  {
+    name: 'magento_diagnose',
+    description: 'Run the Magento live-connection diagnostic for a site: config present, access token valid, /rest/V1 reachability, store code/base URL, and ACL scope probes. Calls messaging GET diagnostics/test-magento?siteId=<id>. Read-only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId: { type: 'number', description: 'Site to diagnose (e.g. 1032)' },
+      },
+      required: ['siteId'],
+    },
+  },
+
   // ── CallRail Attribution ──────────────────────────────────────────────────────
   {
     name: 'callrail_get_attributions',
@@ -4248,6 +4452,34 @@ function parseBusinessHours(input) {
 
 // ── Tool handlers ─────────────────────────────────────────────────────────────
 
+// -- 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'];
+function terminalActionLabel(v) {
+  if (v === null || v === undefined || v === '') return 'Default (Survey)';
+  if (typeof v === 'number') return TERMINAL_ACTION_NAMES[v] ?? String(v);
+  return String(v);
+}
+function terminalActionForSave(v) {
+  if (v === null || v === undefined || v === '') return null;
+  const valid = TERMINAL_ACTION_NAMES.map((n, i) => `${i}=${n}`).join(' ');
+  // Numeric strings ("7") count as ints, the same as the CLI.
+  if (typeof v === 'string' && /^\d+$/.test(v.trim())) v = Number(v.trim());
+  if (typeof v === 'number') {
+    const name = Number.isInteger(v) ? TERMINAL_ACTION_NAMES[v] : undefined;
+    if (!name) throw new Error(`Unknown terminal action ${v}. Use 0-${TERMINAL_ACTION_NAMES.length - 1}: ${valid}`);
+    return name;
+  }
+  const hit = TERMINAL_ACTION_NAMES.find((n) => n.toLowerCase() === String(v).toLowerCase());
+  if (!hit) throw new Error(`Unknown terminal action "${v}". Use one of: ${valid}`);
+  return hit;
+}
+const CHAIN_FIELDS = [
+  'enabled','backupTeamId','backupTeamAfterSeconds','noTargetActionAfterSeconds','rerouteOnAgentUnavailable',
+  'alertAvailableAgentsOnRelease','notifyManagersOnInactivity','rerouteCooldownSeconds','queueEscalationAfterMinutes',
+  'terminalWorkflowId','visitorStatusText','agentStatusText',
+];
+
 async function handleTool(name, args) {
   switch (name) {
     case 'case_list_types': {
@@ -4506,6 +4738,11 @@ async function handleTool(name, args) {
       return JSON.stringify(result, null, 2);
     }
 
+    case 'site_scraper_usage': {
+      const result = await api('GET', `ScraperJobs/StaffUsage/${encodeURIComponent(args.siteId)}`);
+      return JSON.stringify(result, null, 2);
+    }
+
     case 'apple_health': {
       const h = await messagingGet(`/SupportTools/sites/${args.siteId}/apple/health`);
       return JSON.stringify(h, null, 2);
@@ -5179,9 +5416,23 @@ async function handleTool(name, args) {
 
     case 'routing_get_policy': {
       const p = await messagingGet('/AutoRoutingPolicy');
-      const terminalLabel = p.terminalActionOverride != null
-        ? ['Survey','CreateTicket','SurveyAndCreateTicket','Queue','OfflineMessage','NoOp'][p.terminalActionOverride] ?? String(p.terminalActionOverride)
-        : 'Default (Survey)';
+      const terminalLabel = terminalActionLabel(p.terminalActionOverride);
+      const chain = p.inactivityChain;
+      const chainLines = chain ? [
+        '',
+        `Reassignment mode:           ${p.reassignmentMode ?? 'Observe'}`,
+        `Inactivity chain:            ${chain.enabled ? 'ON' : 'off'}`,
+        ...(chain.enabled ? [
+          `  Backup group:              ${chain.backupTeamId ?? 'none'}${chain.backupTeamId != null ? ` after ${chain.backupTeamAfterSeconds}s` : ''}`,
+          `  Final action after:        ${chain.noTargetActionAfterSeconds != null ? `${chain.noTargetActionAfterSeconds}s with no agent available` : 'only when the hop cap is used up'}`,
+          `  Cooldown between moves:    ${chain.rerouteCooldownSeconds}s`,
+          `  Presence trigger:          ${chain.rerouteOnAgentUnavailable}`,
+          `  Alert agents on release:   ${chain.alertAvailableAgentsOnRelease}`,
+          `  Notify managers:           ${chain.notifyManagersOnInactivity}`,
+          `  Queue escalation:          ${chain.queueEscalationAfterMinutes != null ? `${chain.queueEscalationAfterMinutes} min` : 'never'}`,
+          `  Terminal workflow:         ${chain.terminalWorkflowId ?? 'none'}`,
+        ] : []),
+      ] : ['', '(This messaging build does not report the inactivity chain.)'];
       return [
         `Enabled:                     ${p.enabled}`,
         `Initial response timeout:    ${p.initialResponseTimeoutSeconds}s`,
@@ -5193,6 +5444,7 @@ async function handleTool(name, args) {
         `Agent follow-up flag:        ${p.agentFollowUpFlagEnabled}`,
         `Queue unavailable grace:     ${p.queueUnavailableGracePeriodSeconds}s`,
         `Terminal action:             ${terminalLabel}`,
+        ...chainLines,
       ].join('\n');
     }
 
@@ -5209,8 +5461,46 @@ async function handleTool(name, args) {
       for (const f of fields) {
         if (args[f] !== undefined) merged[f] = args[f];
       }
-      const saved = await messagingPut('/AutoRoutingPolicy', merged);
-      return `Routing policy updated. Initial timeout: ${saved.initialResponseTimeoutSeconds}s, Idle timeout: ${saved.idleAfterResponseTimeoutSeconds}s, Max reroutes: ${saved.maxRerouteAttempts}.`;
+      // Terminal action travels as the enum name; the API returns the name too, so normalize either way.
+      merged.terminalActionOverride = terminalActionForSave(merged.terminalActionOverride);
+      // RunWorkflow needs a workflow whatever the chain switch says: the final action also runs at the hop cap.
+      // An explicit null clears the workflow, so it must fail the guard (?? would have fallen back to the saved one).
+      const effectiveWorkflowId = args.inactivityTerminalWorkflowId !== undefined
+        ? args.inactivityTerminalWorkflowId
+        : current.inactivityChain?.terminalWorkflowId;
+      if (merged.terminalActionOverride === 'RunWorkflow' && effectiveWorkflowId == null) {
+        throw new Error('Terminal action 8 (RunWorkflow) needs inactivityTerminalWorkflowId.');
+      }
+      // Actions 6-8 exist only on a messaging build with the inactivity chain; an older one would store a different value.
+      if (['EndChat', 'NotifyManager', 'RunWorkflow'].includes(merged.terminalActionOverride) && !('inactivityChain' in current)) {
+        throw new Error(`Terminal action ${merged.terminalActionOverride} needs a messaging build with the agent inactivity chain; this one does not report it. Use 0-5.`);
+      }
+      if (args.exhaustionMessageTemplate !== undefined) merged.exhaustionMessageTemplate = args.exhaustionMessageTemplate;
+      // Always send the mode back: an absent value is treated as Observe by the API.
+      merged.reassignmentMode = args.reassignmentMode ?? current.reassignmentMode ?? 'Observe';
+      const chainPatch = {
+        enabled: args.inactivityChainEnabled,
+        backupTeamId: args.inactivityBackupTeamId,
+        backupTeamAfterSeconds: args.inactivityBackupTeamAfterSeconds,
+        noTargetActionAfterSeconds: args.inactivityNoAgentActionAfterSeconds,
+        terminalWorkflowId: args.inactivityTerminalWorkflowId,
+        rerouteOnAgentUnavailable: args.rerouteOnAgentUnavailable,
+        alertAvailableAgentsOnRelease: args.alertAvailableAgentsOnRelease,
+        notifyManagersOnInactivity: args.notifyManagersOnInactivity,
+        rerouteCooldownSeconds: args.rerouteCooldownSeconds,
+        queueEscalationAfterMinutes: args.queueEscalationAfterMinutes,
+        visitorStatusText: args.inactivityVisitorText,
+        agentStatusText: args.inactivityAgentText,
+      };
+      if (current.inactivityChain || Object.values(chainPatch).some((v) => v !== undefined)) {
+        const chain = { ...(current.inactivityChain ?? {}) };
+        for (const f of CHAIN_FIELDS) if (chainPatch[f] !== undefined) chain[f] = chainPatch[f];
+        merged.inactivityChain = chain;
+      }
+      await messagingPut('/AutoRoutingPolicy', merged);
+      // PUT answers { updated: true }, not the policy: re-read so the reply reports what is really stored.
+      const saved = await messagingGet('/AutoRoutingPolicy');
+      return `Routing policy updated. Initial timeout: ${saved.initialResponseTimeoutSeconds}s, Idle timeout: ${saved.idleAfterResponseTimeoutSeconds}s, Max reroutes: ${saved.maxRerouteAttempts}, Reassignment mode: ${saved.reassignmentMode ?? 'n/a'}, Inactivity chain: ${saved.inactivityChain?.enabled ? 'ON' : 'off'}, Terminal action: ${terminalActionLabel(saved.terminalActionOverride)}.`;
     }
 
     case 'routing_get_decision_log': {
@@ -5241,13 +5531,81 @@ async function handleTool(name, args) {
       if (result.policySnapshot) {
         const p = result.policySnapshot;
         lines.push('');
-        lines.push(`Policy settings: initial timeout ${p.initialResponseTimeoutSeconds}s, idle timeout ${p.idleAfterResponseTimeoutSeconds}s, max reroutes ${p.maxRerouteAttempts}, terminal action ${p.terminalActionOverride ?? 'default (Survey)'}`);
+        lines.push(`Policy settings: initial timeout ${p.initialResponseTimeoutSeconds}s, idle timeout ${p.idleAfterResponseTimeoutSeconds}s, max reroutes ${p.maxRerouteAttempts}, terminal action ${terminalActionLabel(p.terminalActionOverride)}`);
         if (!p.allowBounceBack) lines.push('Anti-bounce is ON — timed-out agents are excluded from re-routing for this conversation.');
         if (p.preferPreviousAgentOnTimeout) lines.push('Loyalty preference is ON — on timeout, the engine prefers the agent from a prior session.');
       }
       return lines.join('\n');
     }
 
+    case 'routing_simulate_inactivity': {
+      const body = {
+        teamId: args.teamId ?? null,
+        noAgentSeconds: args.noAgentSeconds ?? 0,
+        attemptsUsed: args.attemptsUsed ?? 0,
+        inactivityStep: args.inactivityStep ?? 0,
+        secondsSinceLastTransfer: args.secondsSinceLastTransfer ?? null,
+        sameEpisodeAlreadyHandled: args.sameEpisodeAlreadyHandled ?? false,
+        fromAgentName: args.fromAgentName ?? null,
+      };
+      const r = await messagingPost('/Routing/Inactivity/simulate', body);
+      const gate = {
+        NotEnabled: "The inactivity chain is off for this rule, so today's behavior applies and nothing new happens.",
+        Proceed: 'Allowed to move the chat.',
+        SkipDedupe: 'Blocked: this exact silence was already handled (double-transfer guard).',
+        SkipCooldown: 'Blocked: the chat was moved too recently (cooldown).',
+        HopCapReached: 'Hop cap reached: no more moves, so the final action applies.',
+      }[r.gate] ?? r.gate;
+      const action = {
+        LegacyDefer: 'Nothing new is configured, so the chat stays with its current owner.',
+        Hold: 'Still inside the wait window, nothing happens yet.',
+        WidenToBackupTeam: 'The chat is offered to the backup group.',
+        ApplyTerminal: 'The final action runs.',
+      }[r.noTargetAction] ?? r.noTargetAction;
+      const lines = [
+        'DRY RUN (nothing sent, no live chat touched)',
+        `Settings used: ${r.ruleSource}`,
+        `Safety gate: ${gate}`,
+        `Decision: ${action}`,
+        r.explanation ? `Why: ${r.explanation}` : null,
+        r.nextStepAtSeconds != null ? `Next step after ${r.nextStepAtSeconds}s with no agent available.` : null,
+        `Visitor would see: "${r.visitorMessage}"`,
+        `Agents would see: "${r.queueAlert || r.agentStatus}"`,
+      ].filter(Boolean);
+      for (const l of r.otherRulesThatMatchedButLost ?? []) lines.push(`Also matched but lost: ${l.rule} (${l.reason})`);
+      return lines.join('\n');
+    }
+
+    case 'routing_explain_precedence': {
+      const [defaults, conflicts] = await Promise.all([
+        messagingGet('/Routing/Inactivity/defaults'),
+        messagingGet('/Routing/Inactivity/conflicts'),
+      ]);
+      const lines = ['Evaluation order (top to bottom):', ...(defaults.precedence ?? []).map((p) => `  ${p}`), ''];
+      const list = conflicts.conflicts ?? [];
+      if (!list.length) lines.push('Warnings: none. No group policy cancels out the site default.');
+      else {
+        lines.push('Warnings:');
+        for (const c of list) lines.push(`  [${String(c.severity).toUpperCase()}] ${c.teamId != null ? `group ${c.teamId}` : 'site default'}: ${c.message}`);
+      }
+      return lines.join('\n');
+    }
+
+    case 'routing_inactivity_transfers': {
+      let path = `/RoutingDiagnostics/inactivity-transfers?days=${args.days ?? 30}`;
+      if (args.agentId != null) path += `&agentId=${args.agentId}`;
+      if (args.agentName) path += `&agentName=${encodeURIComponent(args.agentName)}`;
+      const r = await api('GET', path);
+      if (r.note && !r.total && !(r.byAgent ?? []).length) return r.note;
+      const lines = [`Agent inactivity transfers, last ${r.days} days: ${r.total}${r.capped ? ' (capped at 5000)' : ''}`];
+      if (r.note) lines.push(r.note);
+      if (r.matchedAgentsCapped) lines.push('The name matched more agents than are counted here. Use a longer name or agentId.');
+      for (const a of r.byAgent ?? []) lines.push(`  ${a.name}: ${a.count}`);
+      if ((r.byDay ?? []).length) lines.push('', 'By day (Pacific): ' + r.byDay.map((d) => `${d.date}=${d.count}`).join(', '));
+      if (!r.total) lines.push('None. Check that the inactivity chain is on and reassignment mode is not Observe.');
+      return lines.join('\n');
+    }
+
     // ── Livefluence Migration ──────────────────────────────────────────────
     case 'livefluence_export': {
       const qs = args.v20_site_id ? `?v20SiteId=${args.v20_site_id}` : '';
@@ -5650,6 +6008,53 @@ async function handleTool(name, args) {
       return lines.join('\n');
     }
 
+    case 'index_move_preview': {
+      const { fromIndex, toIndex, kind, skipBlocked, selector } = args;
+      const r = await messagingPost('/IndexMove/Preview', { fromIndex, toIndex, kind, skipBlocked, selector });
+      return JSON.stringify(r, null, 2);
+    }
+    case 'index_move_execute': {
+      const { fromIndex, toIndex, kind, skipBlocked, selector } = args;
+      const r = await messagingPost('/IndexMove/Execute', { fromIndex, toIndex, kind, skipBlocked, selector });
+      return JSON.stringify(r, null, 2);
+    }
+    case 'index_split_preview': {
+      const body = { fromIndex: args.fromIndex, toIndex: args.toIndex, docIds: args.docIds, skipBlocked: args.skipBlocked };
+      const r = await messagingPost('/IndexMove/Split/Preview', body);
+      return JSON.stringify(r, null, 2);
+    }
+    case 'index_split_execute': {
+      const body = { fromIndex: args.fromIndex, toIndex: args.toIndex, docIds: args.docIds, skipBlocked: args.skipBlocked };
+      const r = await messagingPost('/IndexMove/Split/Execute', body);
+      return JSON.stringify(r, null, 2);
+    }
+    case 'index_move_status': {
+      const r = await messagingGet(args.moveId
+        ? `/IndexMove/Moves/${encodeURIComponent(args.moveId)}`
+        : '/IndexMove/Moves?take=25');
+      return JSON.stringify(r, null, 2);
+    }
+    case 'index_move_control': {
+      const verb = { resume: 'Resume', abort: 'Abort', undo: 'Undo' }[args.action];
+      if (!verb) throw new Error('action must be resume, abort or undo');
+      const r = await messagingPost(`/IndexMove/Moves/${encodeURIComponent(args.moveId)}/${verb}`);
+      return JSON.stringify(r, null, 2);
+    }
+    case 'index_mixed_content': {
+      const r = await messagingGet(`/IndexMove/MixedContent?index=${encodeURIComponent(args.indexName)}`);
+      return JSON.stringify(r, null, 2);
+    }
+    case 'index_integrity_check': {
+      const r = await messagingGet(`/IndexMove/Integrity?index=${encodeURIComponent(args.indexName)}`);
+      return JSON.stringify(r, null, 2);
+    }
+    case 'index_integrity_repair': {
+      const r = await messagingPost('/IndexMove/Integrity/Repair', {
+        indexName: args.indexName,
+        removeDuplicateRecords: !!args.removeDuplicateRecords,
+      });
+      return JSON.stringify(r, null, 2);
+    }
     case 'index_status': {
       const sources = await api('GET', '/AzureIndexes/IntegrationSources');
       if (!Array.isArray(sources) || !sources.length) return 'No indexed sources found. Run index_ingest to populate.';
@@ -6539,7 +6944,7 @@ async function handleTool(name, args) {
 
     case 'support_user_lookup': {
       const users = await api('GET', `/SupportTools/users/search?q=${encodeURIComponent(args.query)}`);
-      if (!Array.isArray(users) || !users.length) return `No users found matching "${args.query}".`;
+      if (!Array.isArray(users) || !users.length) return `No users found matching "${args.query}" in ${ENV_LABEL}. If this looks like a real customer, re-run with VELARO_ADMIN_API set to the other environment before concluding they don't exist.`;
       return users.map(u => {
         const roles = u.sites?.map(s =>
           `  site ${s.siteId} (${s.companyName}) — ${s.isAdministrator ? 'Admin' : s.isManager ? 'Manager' : 'Agent'}${s.isActive === false ? ' INACTIVE' : ''}`
@@ -6555,7 +6960,7 @@ async function handleTool(name, args) {
 
     case 'support_site_lookup': {
       const sites = await api('GET', `/SupportTools/sites/search?q=${encodeURIComponent(args.query)}`);
-      if (!Array.isArray(sites) || !sites.length) return `No sites found matching "${args.query}".`;
+      if (!Array.isArray(sites) || !sites.length) return `No sites found matching "${args.query}" in ${ENV_LABEL}. If this looks like a real customer, re-run with VELARO_ADMIN_API set to the other environment before concluding they don't exist.`;
       return sites.map(s => {
         const admins = s.admins?.map(a => `  ${a.userName} (${a.firstName} ${a.lastName})`).join('\n') ?? 'none';
         return `[siteId=${s.siteId}] ${s.companyName}${s.isTestSite ? ' [TEST]' : ''}\n  URL: ${s.companyURL ?? '—'} | Created: ${s.dateCreated ? s.dateCreated.slice(0,10) : '—'}\n  Admins:\n${admins}`;
@@ -6652,6 +7057,14 @@ async function handleTool(name, args) {
       return lines.join('\n');
     }
 
+    case 'tour_insights': {
+      const days = Math.min(365, Math.max(1, args.days ?? 30));
+      const path = args.siteId
+        ? `/SupportTools/sites/${args.siteId}/tour-events?days=${days}`
+        : `/SupportTools/tour-insights?days=${days}`;
+      return JSON.stringify(await api('GET', path), null, 2);
+    }
+
     case 'support_extend_subscription': {
       const res = await api('POST', `/SupportTools/sites/${args.siteId}/extend-subscription`, { days: args.days });
       return res?.success
@@ -7231,6 +7644,12 @@ async function handleTool(name, args) {
       return lines.join('\n');
     }
 
+    case 'magento_diagnose': {
+      if (!args.siteId) return 'siteId is required.';
+      const r = await api('GET', `/diagnostics/test-magento?siteId=${encodeURIComponent(args.siteId)}`);
+      return JSON.stringify(r, null, 2);
+    }
+
     // ── CallRail Attribution ──────────────────────────────────────────────────
     case 'callrail_get_attributions': {
       const limit = Math.min(100, args.limit ?? 25);