@velaro/mcp-server 1.0.0 → 1.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/mcp-server",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "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

@@ -232,6 +232,65 @@ function execInsightsRange(days) {
 
 const messagingDel   = (path)       => messagingRequest('DELETE', path);
 
+// Visitor link helpers (mirrors cli/lib/visitor-link.js; keep in sync, covered by cli/lib/visitor-link.test.js)
+
+const MAX_TTL_MINUTES = 1440;
+
+function decodeLinkToken(token) {
+  const out = { ok: false, problems: [] };
+  if (typeof token !== 'string' || !token.trim()) { out.problems.push('empty token'); return out; }
+  const parts = token.trim().split('.');
+  if (parts.length !== 3 || parts[0] !== 'vlk1') { out.problems.push('not a vlk1 link token (expected vlk1.<payload>.<signature>)'); return out; }
+  const payload = Buffer.from(parts[1].replace(/-/g, '+').replace(/_/g, '/'), 'base64').toString('utf8');
+  const f = payload.split('|');
+  if (f.length < 6) { out.problems.push('payload has fewer than 6 fields'); return out; }
+  const [siteId, visitorId, conversationBaseId, scope, iat, exp] = f;
+  const toMs = (v) => { const n = Number(v); return Number.isFinite(n) && n > 0 ? (n > 1e12 ? n : n * 1000) : null; };
+  const issuedMs = toMs(iat);
+  const expMs = toMs(exp);
+  Object.assign(out, {
+    ok: true,
+    siteId: Number(siteId) || null,
+    visitorId,
+    conversationBaseId: Number(conversationBaseId) || null,
+    scope,
+    issuedAt: issuedMs ? new Date(issuedMs).toISOString() : null,
+    expiresAt: expMs ? new Date(expMs).toISOString() : null,
+    signaturePresent: parts[2].length > 0,
+  });
+  if (scope !== 'link') out.problems.push(`unexpected scope "${scope}" (v1 only issues "link")`);
+  if (!out.signaturePresent) out.problems.push('signature missing');
+  if (!expMs) out.problems.push('expiry not parseable');
+  return out;
+}
+
+function diagnoseLink({ token, siteId, settings, now = Date.now() }) {
+  const claims = token ? decodeLinkToken(token) : { ok: false, problems: [] };
+  const findings = [...claims.problems];
+  if (claims.ok) {
+    if (siteId && claims.siteId && Number(siteId) !== claims.siteId) findings.push(`token was minted for site ${claims.siteId}, not site ${siteId}: cross-site tokens always fail`);
+    if (claims.expiresAt && Date.parse(claims.expiresAt) <= now) findings.push(`token expired at ${claims.expiresAt}`);
+    if (!claims.conversationBaseId) findings.push('token carries no conversation id (visitor had not started a chat when it was minted)');
+  }
+  if (settings) {
+    if (!settings.enabled) findings.push('visitor linking is OFF for this site: mint returns linking_disabled');
+    if (settings.keyConfigured === false) findings.push('link signing key is not configured on the server: mint and resolve fail closed (503 key_not_configured)');
+  }
+  return { claims, settings: settings ?? null, findings, healthy: findings.length === 0 };
+}
+
+function validateSettingsArgs({ enabled, ttlMinutes }) {
+  if (enabled === undefined && ttlMinutes === undefined) throw new Error('Pass enabled and/or ttlMinutes.');
+  if (ttlMinutes !== undefined && (!Number.isInteger(ttlMinutes) || ttlMinutes < 1 || ttlMinutes > MAX_TTL_MINUTES)) {
+    throw new Error(`ttlMinutes must be a whole number from 1 to ${MAX_TTL_MINUTES}.`);
+  }
+  const body = {};
+  if (enabled !== undefined) body.enabled = !!enabled;
+  if (ttlMinutes !== undefined) body.ttlMinutes = ttlMinutes;
+  return body;
+}
+
+
 // Skill-based routing CRUD helper for SkillRouting/{Skills|Assignments|Requirements}.
 async function skillRoutingCrud(resource, args, fields) {
   const body = Object.fromEntries(Object.entries(fields).filter(([, v]) => v !== undefined));
@@ -823,6 +882,16 @@ const TOOLS = [
     },
   },
 
+  {
+    name: 'skill_usage_site',
+    description: 'Velaro staff only. Per-customer skill and integration usage for the month in one call: the billable counters (AI tool calls, MCP calls, API calls, workflow integration actions, workflow AI calls, bot turns) against the plan limits (same numbers as the customer Billing page), the effective usage-gate rollout mode per metric (Off/Observe/Enforce), calls by surface (MCP gateway, bot, workflow, REST business action, staff, copilot), and LLM cost split platform vs BYOK. BYOK removes LLM cost only; skill usage is counted and capped the same way. Lives in velaro-messaging - requires VELARO_MESSAGING_API.',
+    inputSchema: {
+      type: 'object',
+      properties: { siteId: { type: 'number', description: 'Target site ID (need not be your own)' } },
+      required: ['siteId'],
+    },
+  },
+
   {
     name: 'scraper_verify_token',
     description: "Show the calling site's web-scraper verification header (name + value), the scraper IP, and ready-to-send instructions for allowlisting Velaro's crawler with the customer's web host/WAF. Wraps GET ScraperJobs/VerifyToken. Site comes from auth context, never a parameter.",
@@ -1041,6 +1110,18 @@ const TOOLS = [
     },
   },
 
+  {
+    name: 'csat_override_unapprove_candidate',
+    description: 'Undo an approved Chat Intelligence improvement candidate: returns it to Pending, deactivates the promoted knowledge override and removes any vectorized copy. Requires site manager. Site comes from the key, never an argument.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        candidateId: { type: 'number', description: 'Id of the Approved override candidate' },
+      },
+      required: ['candidateId'],
+    },
+  },
+
   // ── Conversations ─────────────────────────────────────────────────────────
   {
     name: 'conversation_list',
@@ -1761,6 +1842,41 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['message'],
     },
   },
+  {
+    name: 'visitor_link_get_settings',
+    description: 'Get the visitor-linking settings for this site: whether chat visitors can be linked to later form/survey submissions (default off), the link lifetime in minutes, and whether the signing key is configured. Site is resolved server-side.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'visitor_link_set_settings',
+    description: 'Turn visitor linking on or off for this site and/or set the link lifetime (1-1440 minutes). Only fields you pass change. Links are only created for visitors who have chatted and, when the site uses a consent banner, granted functional storage.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        enabled:    { type: 'boolean', description: 'Enable or disable visitor linking' },
+        ttlMinutes: { type: 'number', description: 'Link lifetime in minutes, 1-1440' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'visitor_link_diagnose',
+    description: 'Explain why visitor linking is or is not working for this site. Reads the current settings and, if you pass a vlk1 link token, decodes its claims (site, conversation, expiry) and reports cross-site, expired, missing-conversation and key problems. The signature is not verified here; use visitor_link_resolve for the real server-side check.',
+    inputSchema: {
+      type: 'object',
+      properties: { token: { type: 'string', description: 'Optional vlk1 link token from a form hidden field' } },
+      required: [],
+    },
+  },
+  {
+    name: 'visitor_link_resolve',
+    description: 'Exchange a vlk1 link token for the visitor id, conversation id and contact id (what your own server does when a form arrives). Cross-site and expired tokens fail.',
+    inputSchema: {
+      type: 'object',
+      properties: { token: { type: 'string', description: 'vlk1 link token' } },
+      required: ['token'],
+    },
+  },
   {
     name: 'teams_push_settings_get',
     description: 'Get the Velaro Bot proactive-alert settings for this site: per-alert switches (new chat, missed chat, ticket created, ticket assigned, daily digest), the effective daily cap and the push count for today. Site is resolved server-side.',
@@ -2523,6 +2639,42 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['siteId', 'indexName'],
     },
   },
+  {
+    name: 'knowledge_clinical_text_get',
+    description: 'Read the Emergency and Safety Messages for a site: per-channel and per-language emergency/referral overrides (keys like chat, es, es.voice), the effective English wording, supportedLanguages, limits, and the read-only emergencyServiceMode. Customer: own site. Velaro staff: pass siteId. Wraps GET KnowledgeSetup/state (clinicalText).',
+    inputSchema: {
+      type: 'object',
+      properties: { siteId: { type: 'number', description: 'Velaro staff only: target site ID. Omit for your own site.' } },
+    },
+  },
+  {
+    name: 'knowledge_clinical_text_set',
+    description: 'Set the Emergency and Safety Messages. The server replaces the stored override set, so pass every override to keep (read first with knowledge_clinical_text_get). Keys: default, chat, voice, sms, whatsapp, email, a language code (es fr de pt it nl zh ja ko vi ru ar hi pl) or language.channel (es.voice). Each text 20-600 chars; emergency text must contain {emergencyNumber}; "hang up" only in voice wording. null value clears an entry. Wraps PUT KnowledgeSetup/clinical-text.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId:          { type: 'number', description: 'Velaro staff only: target site ID. Omit for your own site.' },
+        emergency:       { type: 'object', description: 'Map of key to emergency wording', additionalProperties: { type: ['string', 'null'] } },
+        referral:        { type: 'object', description: 'Map of key to referral wording', additionalProperties: { type: ['string', 'null'] } },
+        emergencyNumber: { type: 'string', description: 'Replaces {emergencyNumber}; omit for the default' },
+        resetToDefault:  { type: 'boolean', description: 'Clear all custom wording' },
+      },
+    },
+  },
+  {
+    name: 'knowledge_emergency_service_mode_set',
+    description: 'Velaro staff only. Turn emergency-service mode on/off for a site that IS the emergency line: its own required text replaces the built-in emergency instruction (never the referral). Turning on needs confirm=true and text of 20-600 chars. Wraps PUT KnowledgeSetup/Staff/{siteId}/clinical-text (emergencyServiceMode); existing wording is left untouched.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        siteId:  { type: 'number', description: 'Target site ID' },
+        enabled: { type: 'boolean' },
+        text:    { type: 'string', description: 'Required emergency text (20-600 chars)' },
+        confirm: { type: 'boolean', description: 'Must be true to turn the mode on' },
+      },
+      required: ['siteId'],
+    },
+  },
   {
     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).',
@@ -3194,6 +3346,50 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['id'],
     },
   },
+  // ── Visitor Monitor (session-scoped: SiteId comes from the caller's JWT, never an arg) ──
+  {
+    name: 'visitor_monitor_active',
+    description: 'List live visitors on this site (Visitor Monitor). Returns sessions (with region/city/ipTruncated when Store Location Detail is on), activeWindowMinutes, locationDetailEnabled, visitor limit and counts.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'visitor_monitor_preferences_get',
+    description: 'Get the calling user\'s saved Visitor Monitor view (columns, groupBy, sortBy, sortDir, regionGrouping). Per user, follows them across browsers.',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'visitor_monitor_preferences_set',
+    description: 'Save the calling user\'s Visitor Monitor view. Replaces the saved view: send the full set of fields you want kept.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        columns:        { type: 'array', items: { type: 'string' }, description: 'Ordered column keys, e.g. ["visitor","status","region","city"]' },
+        groupBy:        { type: 'string', description: 'Group the list by this key (e.g. "region", "city", "none")' },
+        sortBy:         { type: 'string', description: 'Sort key, e.g. "lastSeen"' },
+        sortDir:        { type: 'string', enum: ['asc', 'desc'], description: 'Sort direction' },
+        regionGrouping: { type: 'string', description: 'Region grouping granularity: "region" or "city"' },
+      },
+      required: [],
+    },
+  },
+  {
+    name: 'visitor_monitor_settings_get',
+    description: 'Get this site\'s Visitor Monitor settings: storeLocationDetail and activeWindowMinutes (how long a visitor stays listed after leaving; default 30).',
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'visitor_monitor_settings_set',
+    description: 'Update this site\'s Visitor Monitor settings (partial update). activeWindowMinutes must be 5-240; above 30 and storeLocationDetail need the Visitor Insights Advanced plan flag, otherwise the API returns 403 feature_not_in_plan.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        storeLocationDetail: { type: 'boolean', description: 'Store visitor region/city and a truncated IP on new sessions (Advanced plan)' },
+        activeWindowMinutes: { type: 'number', description: 'Minutes a visitor stays in the monitor after last activity (5-240; above 30 needs Advanced)' },
+      },
+      required: [],
+    },
+  },
+
   // ── Page Widget Containers ────────────────────────────────────────────────
   {
     name: 'widget_container_list',
@@ -3544,7 +3740,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     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', 'new_agent_ramp', 'year_in_review'] },
+        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', 'bonus_insights', 'operations_briefing', 'entitled'] },
         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.' },
@@ -3561,6 +3757,13 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
         timeZone:     { type: 'string', description: 'demand_coverage: IANA time zone (default America/Los_Angeles).' },
         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.' },
+        name:         { type: 'string', description: 'bonus_insights: which analysis: coverage_gap|next_best_fix|escalation_risk|skill_gap_matrix|handle_quality_outliers|abandon_causes.' },
+        narrative:    { type: 'boolean', description: 'operations_briefing: include the cached AI narrative (default true).' },
+        minutesPerReview: { type: 'number', description: 'bonus_insights: assumed minutes per manual review (0-240).' },
+        hourlyCost:   { type: 'number', description: 'bonus_insights: assumed reviewer hourly cost (0-1000).' },
+        deflectionPct: { type: 'number', description: 'bonus_insights: assumed deflection percent (0-100).' },
+        costPerChat:  { type: 'number', description: 'bonus_insights: assumed cost per chat (0-1000).' },
+        waitMinutes:  { type: 'number', description: 'bonus_insights: wait minutes that counts as abandoned (1-1440).' },
         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.' },
       },
@@ -4706,6 +4909,15 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     },
   },
 
+  {
+    name: 'netsuite_rollback_auth',
+    description: 'Undo a NetSuite connection-type switch: sets a connection that was moved to OAuth 2.0 / M2M back to the legacy OAuth 1.0a credentials. Refused (409) once the old credentials were cleared. Nothing is deleted. Administrator only, audited. Lives in velaro-messaging - requires VELARO_MESSAGING_API.',
+    inputSchema: {
+      type: 'object',
+      properties: { configId: { type: 'number', description: 'NetSuite config ID (see netsuite_list_configs).' } },
+      required: ['configId'],
+    },
+  },
   {
     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.',
@@ -4782,7 +4994,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   },
   {
     name: 'teams_phone_test_config',
-    description: 'Test the Teams Phone connection by creating (or renewing) the Graph /communications/calls subscription — the real connectivity check. Surfaces the actual Graph error if the customer tenant hasn\'t admin-consented Calls.AccessMedia.All + Calls.Initiate.All, or the resource account isn\'t provisioned, rather than only being discovered when a call is missed. Lives in velaro-messaging — requires VELARO_MESSAGING_API.',
+    description: 'Run the Teams Phone readiness checks and return each check (name, ok, message) plus callingReady. Surfaces what is missing (admin consent, resource account, Graph reachability) rather than only being discovered when a call is missed. Lives in velaro-messaging — requires VELARO_MESSAGING_API.',
     inputSchema: { type: 'object', properties: {}, required: [] },
   },
 
@@ -5013,6 +5225,21 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   // Distinct from the reusable coupon-CODE catalog, which lives in velaro-messaging
   // (superadmin/billing/coupons). Pass couponCode here only to record which catalog code a grant
   // corresponds to.
+  {
+    name: 'sign_versions_list',
+    description: 'Velaro Sign: list every uploaded document version of a contract (owner-only; signers never see old versions). Newest first with sha256, pages, uploader, note.',
+    inputSchema: { type: 'object', properties: { contractId: { type: 'number', description: 'Contract ID' } }, required: ['contractId'] },
+  },
+  {
+    name: 'sign_versions_diff',
+    description: 'Velaro Sign: text diff between two document versions of a contract (changed blocks only: removed vs added lines). Owner-only.',
+    inputSchema: { type: 'object', properties: { contractId: { type: 'number' }, from: { type: 'number', description: 'Older version number' }, to: { type: 'number', description: 'Newer version number' } }, required: ['contractId', 'from', 'to'] },
+  },
+  {
+    name: 'sign_versions_upload',
+    description: 'Velaro Sign: upload a new PDF version of a contract document from a local file path. Allowed only while the contract is a draft; after send/sign, void and re-send.',
+    inputSchema: { type: 'object', properties: { contractId: { type: 'number' }, filePath: { type: 'string', description: 'Local path of the PDF' }, note: { type: 'string', description: 'Change note' } }, required: ['contractId', 'filePath'] },
+  },
   {
     name: 'coupon_grant_list',
     description: 'List per-account Stripe discount grants. Velaro billing staff only. Shows which accounts currently have a discount and its status.',
@@ -5138,6 +5365,10 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       required: ['id'],
     },
   },
+  {
+    name: 'usage_alerts',
+    description: 'Plan-limit alerts for the authenticated site: every metered resource at or above its warning threshold (80%+), with used/limit, percent, level (warning | critical | limit) and whether overage is billed. Same rules as the usage-limit emails and the dashboard banner. Use to answer "are they near a limit?" or "why did they get a usage email?". Read-only. To raise a limit, a customer uses Billing > Contact Account Manager; staff use support_set_limit.',
+  },
   {
     name: 'billing_notify_settings_get',
     description: 'Billing notifications: the global settings (receipts.card, receipts.ach, receipts.other, invoices.bcc, digest.recipients). Staff only.',
@@ -6400,7 +6631,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   {"name":"skill_routing_assignments","description":"Skill-based routing: assign skills to agents with proficiency 1-5. action = list | create | update | delete.","inputSchema":{"type":"object","properties":{"action":{"type":"string"},"id":{"type":"number"},"workspaceUserId":{"type":"number"},"agentSkillId":{"type":"number"},"proficiency":{"type":"number"}},"required":["action"]}},
   {"name":"skill_routing_requirements","description":"Skill-based routing: required/preferred skills per deployment and/or team. action = list | create | update | delete. Update is partial. Requirements are disabled by default; set isEnabled true to turn on.","inputSchema":{"type":"object","properties":{"action":{"type":"string"},"id":{"type":"number"},"deploymentId":{"type":"number"},"teamId":{"type":"number"},"requiredSkillIds":{"type":"array","items":{"type":"number"}},"preferredSkillIds":{"type":"array","items":{"type":"number"}},"overflowWaitSeconds":{"type":"number"},"isEnabled":{"type":"boolean"}},"required":["action"]}},
   {"name":"skill_routing_simulate","description":"Dry-run skill routing for a team: shows which agents would be narrowed to and why. Never assigns a conversation or writes the decision log.","inputSchema":{"type":"object","properties":{"teamId":{"type":"number"},"waitedSeconds":{"type":"number"}}}},
-  {"name":"qa_rubric","description":"Conversation Quality QA rubrics. action = list | get | default | create | update | delete. Pass rubric fields in \"rubric\". Requires EnableConversationQuality.","inputSchema":{"type":"object","properties":{"action":{"type":"string"},"id":{"type":"number"},"rubric":{"type":"object"}},"required":["action"]}},
+  {"name":"qa_rubric","description":"Conversation Quality QA rubrics. action = list | get | default | starter (create the starter rubric if the site has none) | create | update | clone (inactive copy; optional rubric.name) | activate | deactivate | rescore (re-score recent chats against the active rubric; pass days 1-90 and limit 1-500) | delete. Pass rubric fields in \"rubric\". Weights are relative and shown as percents; max 20 criteria. Requires EnableConversationQuality and the Administrator role for writes.","inputSchema":{"type":"object","properties":{"action":{"type":"string"},"id":{"type":"number"},"rubric":{"type":"object"},"days":{"type":"number"},"limit":{"type":"number"}},"required":["action"]}},
   {"name":"qa_low_scores","description":"Conversations scoring below the rubric threshold, for QA review.","inputSchema":{"type":"object","properties":{"threshold":{"type":"number"},"days":{"type":"number"},"agentId":{"type":"number"},"skip":{"type":"number"},"take":{"type":"number"}}}},
   {"name":"ai_field_extraction_get_config","description":"Get the AI field extraction config (opt-in, default off; monthly cap). Requires the ai_field_extraction entitlement.","inputSchema":{"type":"object","properties":{}}},
   {"name":"ai_field_extraction_update_config","description":"Update AI field extraction config (partial). enabled, monthlyCap (null = 500 default, hard ceiling 50000), createThemeTags.","inputSchema":{"type":"object","properties":{"enabled":{"type":"boolean"},"monthlyCap":{"type":"number"},"createThemeTags":{"type":"boolean"}}}},
@@ -6921,6 +7152,11 @@ async function handleTool(name, args) {
       return JSON.stringify(result, null, 2);
     }
 
+    case 'skill_usage_site': {
+      const usage = await messagingGet(`/SupportTools/sites/${args.siteId}/skill-usage`);
+      return JSON.stringify(usage, null, 2);
+    }
+
     case 'apple_health': {
       const h = await messagingGet(`/SupportTools/sites/${args.siteId}/apple/health`);
       return JSON.stringify(h, null, 2);
@@ -7030,6 +7266,12 @@ async function handleTool(name, args) {
         { dismissed: args.dismissed !== false }
       );
 
+    case 'csat_override_unapprove_candidate': {
+      const cid = Number(args.candidateId);
+      if (!Number.isInteger(cid) || cid <= 0) throw new Error('candidateId must be a positive integer');
+      return await messagingPost(`/api/intelligence/csat-override-candidates/${cid}/unapprove`, {});
+    }
+
     // ── Conversations ──────────────────────────────────────────────────────
     case 'conversation_list':
       return await rpc('conversation_list', args);
@@ -7584,6 +7826,20 @@ reply: ${r?.reply}`;
       return `Sent to Teams webhook "${webhook.name}".`;
     }
 
+    case 'visitor_link_get_settings':
+      return await messagingGet('/SiteSettings/visitor-linking');
+
+    case 'visitor_link_set_settings':
+      return await messagingPut('/SiteSettings/visitor-linking', validateSettingsArgs({ enabled: args.enabled, ttlMinutes: args.ttlMinutes }));
+
+    case 'visitor_link_diagnose': {
+      const settings = await messagingGet('/SiteSettings/visitor-linking');
+      return diagnoseLink({ token: args.token, settings });
+    }
+
+    case 'visitor_link_resolve':
+      return await messagingPost('/api/v1/visitor-links/resolve', { token: args.token });
+
     case 'teams_push_settings_get':
       return await api('GET', '/TeamsBot/PushSettings');
 
@@ -8584,6 +8840,34 @@ reply: ${r?.reply}`;
       return `Index ready on site ${args.siteId}: ${idx?.name} (id=${idx?.id}, purpose=${idx?.purpose}, excludeFromAllSources=${!!idx?.excludeFromAllSources}).`;
     }
 
+    case 'knowledge_clinical_text_get': {
+      const base = args.siteId ? `/KnowledgeSetup/Staff/${encodeURIComponent(args.siteId)}` : '/KnowledgeSetup';
+      const st = await messagingRequest('GET', `${base}/state`);
+      return JSON.stringify(st?.clinicalText ?? { error: 'state did not include clinicalText' }, null, 2);
+    }
+
+    case 'knowledge_clinical_text_set': {
+      const base = args.siteId ? `/KnowledgeSetup/Staff/${encodeURIComponent(args.siteId)}` : '/KnowledgeSetup';
+      const body = args.resetToDefault ? { resetToDefault: true } : {};
+      if (!args.resetToDefault) {
+        if (args.emergency !== undefined) body.emergency = args.emergency;
+        if (args.referral !== undefined) body.referral = args.referral;
+        if (args.emergencyNumber !== undefined) body.emergencyNumber = args.emergencyNumber;
+      }
+      const r = await messagingRequest('PUT', `${base}/clinical-text`, body);
+      return JSON.stringify(r, null, 2);
+    }
+
+    case 'knowledge_emergency_service_mode_set': {
+      if (!args.siteId) return 'siteId is required.';
+      const mode = {};
+      if (args.enabled !== undefined) mode.enabled = args.enabled;
+      if (args.text !== undefined) mode.text = args.text;
+      if (args.confirm) mode.confirm = true;
+      const r = await messagingRequest('PUT', `/KnowledgeSetup/Staff/${encodeURIComponent(args.siteId)}/clinical-text`, { emergencyServiceMode: mode });
+      return JSON.stringify(r, null, 2);
+    }
+
     case 'index_set_profile': {
       if (!args.siteId || !args.indexName) return 'siteId and indexName are required.';
       const body = { indexName: args.indexName };
@@ -9476,6 +9760,25 @@ reply: ${r?.reply}`;
       return `Widget ${args.id} ${args.isEnabled ? 'enabled' : 'disabled'}.`;
     }
 
+    // ── Visitor Monitor ───────────────────────────────────────────────────
+    case 'visitor_monitor_active':
+      return JSON.stringify(await messagingGet('/Visitor/active'), null, 2);
+    case 'visitor_monitor_preferences_get':
+      return JSON.stringify(await messagingGet('/Visitor/preferences'), null, 2);
+    case 'visitor_monitor_preferences_set': {
+      const body = {};
+      for (const k of ['columns', 'groupBy', 'sortBy', 'sortDir', 'regionGrouping']) if (args[k] !== undefined) body[k] = args[k];
+      return JSON.stringify(await messagingPut('/Visitor/preferences', body), null, 2);
+    }
+    case 'visitor_monitor_settings_get':
+      return JSON.stringify(await messagingGet('/Visitor/settings'), null, 2);
+    case 'visitor_monitor_settings_set': {
+      const body = {};
+      if (args.storeLocationDetail !== undefined) body.storeLocationDetail = args.storeLocationDetail;
+      if (args.activeWindowMinutes !== undefined) body.activeWindowMinutes = args.activeWindowMinutes;
+      return JSON.stringify(await messagingPut('/Visitor/settings', body), null, 2);
+    }
+
     // ── Page Widget Containers ────────────────────────────────────────────────
     case 'widget_container_list': {
       const data = await api('GET', '/PageWidgetContainers');
@@ -9794,6 +10097,7 @@ reply: ${r?.reply}`;
         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', new_agent_ramp: 'new-agent-ramp',
+        bonus_insights: 'bonus', operations_briefing: 'operations-briefing', entitled: 'entitled',
       };
       if (args.report === 'promise_dismiss') {
         if (!args.promiseId) throw new Error('promiseId is required for promise_dismiss');
@@ -9826,11 +10130,15 @@ reply: ${r?.reply}`;
         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];
+      let seg = ER_PATHS[args.report];
       if (!seg) throw new Error('report must be one of: ' + Object.keys(ER_PATHS).join(', ') + ', promise_dismiss, year_in_review');
+      if (args.report === 'bonus_insights') {
+        if (!args.name) throw new Error('name is required for bonus_insights (coverage_gap|next_best_fix|escalation_risk|skill_gap_matrix|handle_quality_outliers|abandon_causes)');
+        seg = 'bonus/' + encodeURIComponent(String(args.name).replace(/-/g, '_'));
+      }
       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']) {
+      for (const k of ['from', 'to', 'groupBy', 'deploymentId', 'teamId', 'threshold', 'perAgent', 'limit', 'days', 'windowDays', 'weeks', 'handleMinutes', 'maxConcurrent', 'timeZone', 'lowScore', 'includeDemo', 'narrative', 'minutesPerReview', 'hourlyCost', 'deflectionPct', 'costPerChat', 'waitMinutes']) {
         if (args[k] != null && args[k] !== '') qs.set(k, String(args[k]));
       }
       const q = qs.toString();
@@ -10791,6 +11099,10 @@ reply: ${r?.reply}`;
         ? `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_rollback_auth': {
+      const r = await messagingPost('/NetSuite/Auth/RollbackAuthType', { id: args.configId });
+      return `Config ${r?.id ?? args.configId} switched back to ${r?.authType ?? 'oauth1'}. Run a connection test to confirm.`;
+    }
 
     case 'netsuite_m2m_init': {
       const r = await messagingPost('/NetSuite/M2M/Init', { id: args.configId ?? null, company: args.company, displayName: args.displayName });
@@ -10837,7 +11149,12 @@ reply: ${r?.reply}`;
     }
     case 'teams_phone_test_config': {
       const result = await messagingPost('/TeamsPhone/Config/Test', {});
-      return `${result.success ? 'Success' : 'Failed'}: ${result.message ?? '(no message)'}`;
+      const lines = [`${result.success ? 'Success' : 'Failed'}: ${result.message ?? '(no message)'}`];
+      if (typeof result.callingReady === 'boolean') lines.push(`Inbound calling ready: ${result.callingReady}`);
+      if (Array.isArray(result.checks)) {
+        for (const ck of result.checks) lines.push(`${ck?.ok ? 'PASS' : 'FAIL'} ${ck?.name ?? ''}${ck?.message ? ': ' + ck.message : ''}`);
+      }
+      return lines.join(String.fromCharCode(10));
     }
 
     // ── Shopify write policy (velaro-messaging /api/Shopify/WritePolicy) ───────
@@ -11182,6 +11499,31 @@ ${JSON.stringify(result, null, 2)}`;
     }
 
     // ── Stripe discount grants ────────────────────────────────────────────────────
+    case 'sign_versions_list': {
+      const r = await api('GET', `/api/Contract/${args.contractId}/versions`);
+      const rows = r.versions || [];
+      if (!rows.length) return `Contract ${args.contractId}: no document versions yet.`;
+      return rows.map(v => `v${v.versionNumber} ${String(v.uploadedAt||'').slice(0,19)} ${v.uploadedBy||'-'} ${v.fileName||'-'} ${v.pageCount??'?'}p sha256:${String(v.sha256||'').slice(0,12)}${v.note ? ' note: '+v.note : ''}`).join('\n');
+    }
+
+    case 'sign_versions_diff': {
+      const r = await api('GET', `/api/Contract/${args.contractId}/diff?from=${args.from}&to=${args.to}`);
+      if (r.identical) return `v${r.from} and v${r.to} are byte-identical.`;
+      return (r.blocks || []).map(b => [...(b.removed||[]).map(x => '- '+x), ...(b.added||[]).map(x => '+ '+x)].join('\n')).join('\n\n') || 'No text differences.';
+    }
+
+    case 'sign_versions_upload': {
+      const buf = _readFileSync(args.filePath);
+      if (buf.subarray(0, 5).toString('latin1') !== '%PDF-') throw new Error('Only PDF files can be uploaded as a contract version.');
+      const form = new FormData();
+      form.append('file', new Blob([buf], { type: 'application/pdf' }), String(args.filePath).split(/[\/]/).pop());
+      if (args.note) form.append('note', args.note);
+      const res = await fetch(`${API_BASE}/api/Contract/${args.contractId}/document`, { method: 'POST', headers: { Authorization: authHeader() }, body: form, signal: AbortSignal.timeout(60000) });
+      const t = await res.text();
+      if (!res.ok) throw new Error(`Upload failed ${res.status}: ${t.slice(0,300)} (new versions only while draft; after send/sign void and re-send)`);
+      return `Uploaded new version for contract ${args.contractId}.`;
+    }
+
     case 'coupon_grant_list': {
       const qs = new URLSearchParams();
       if (args.siteId !== undefined) qs.set('siteId', String(args.siteId));
@@ -11284,6 +11626,11 @@ ${JSON.stringify(result, null, 2)}`;
       return `✅ Billing contact ${args.id} removed.`;
     }
 
+    case 'usage_alerts': {
+      const r = await messagingApi('/Usage/alerts');
+      if (!r.alerts?.length) return 'No plan-limit alerts. Every metered resource is under its warning threshold.';
+      return r.alerts.map(a => `[${a.level.toUpperCase()}] ${a.displayName}: ${a.current} of ${a.limit} (${a.percent}%)${a.softLimit ? ' - overage is billed' : ''}`).join(' | ');
+    }
     case 'billing_notify_settings_get': {
       const all = await api('GET', '/api/BillingNotifications/settings');
       return Object.entries(all).map(([k, v]) => `${k}: ${v ?? '(not set: code default)'}`).join('\n');
@@ -12350,7 +12697,12 @@ ${JSON.stringify(result, null, 2)}`;
       if (a === 'create') return await messagingPost('/api/admin/QualityQa/rubrics', args.rubric ?? {});
       if (a === 'update') return await messagingPut('/api/admin/QualityQa/rubrics/' + args.id, args.rubric ?? {});
       if (a === 'delete') return await messagingDel('/api/admin/QualityQa/rubrics/' + args.id);
-      throw new Error('action must be list|get|default|create|update|delete');
+      if (a === 'starter') return await messagingPost('/api/admin/QualityQa/rubrics/starter', {});
+      if (a === 'clone') return await messagingPost('/api/admin/QualityQa/rubrics/' + args.id + '/clone', args.rubric ?? {});
+      if (a === 'activate') return await messagingPut('/api/admin/QualityQa/rubrics/' + args.id, { isActive: true });
+      if (a === 'deactivate') return await messagingPut('/api/admin/QualityQa/rubrics/' + args.id, { isActive: false });
+      if (a === 'rescore') return await messagingPost('/api/admin/QualityQa/rescore?days=' + encodeURIComponent(args.days ?? 30) + '&limit=' + encodeURIComponent(args.limit ?? 200), {});
+      throw new Error('action must be list|get|default|starter|create|update|clone|activate|deactivate|rescore|delete');
     }
     case 'qa_low_scores': {
       const qs = new URLSearchParams({ days: String(args.days ?? 30), skip: String(args.skip ?? 0), take: String(args.take ?? 50) });