@velaro/mcp-server 0.6.54 → 0.6.55

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.55",
   "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": {

package/server.js

@@ -1446,7 +1446,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 +1476,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?"',
@@ -4248,6 +4297,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': {
@@ -5179,9 +5256,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 +5284,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 +5301,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 +5371,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}` : '';