@velaro/mcp-server 2.0.0 → 2.0.2

package/server.js

@@ -40,7 +40,7 @@
  *   VELARO_MCP_MODE=http PORT=3000 node server.js
  */
 
-import { buildRawLogQuery, describeRawMeta, fetchRetry429, resolveLogWindow } from './log-search.js';
+import { fetchRetry429 } from './fetch-retry.js';
 import { Server }            from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import {
@@ -54,51 +54,12 @@ import { loadParity, runParity } from './parity/loader.js';
 import { resolveMessagingApi } from './messaging-base.js';
 import { buildResolvePath, buildTimelinePath, buildOverrideBody, buildValidateBody, buildBannerPath, buildOverrideListPath, tolerant, VALIDATE_PATH, OVERRIDE_PATH } from './workflow-schedule.js';
 
-// Default was 'https://help.velaro.com'. Renamed to the recognizable admin API hostname for
-// clarity during the 2026-09-10 Donaldson bot Calendly status investigation
-// (docs/qa/chatbot-hallucinated-booking-donaldson-bot.md) — but this is NOT a functional fix and
-// does NOT explain that incident: live-verified same day that 'https://help.velaro.com' and
-// 'https://api-admin-us-east.velaro.com' are the SAME deployment (identical /api/health build SHA,
-// and /Calendly/superadmin/status returns 401 — auth-gated, not 404 — on both hosts). Whatever
-// caused that investigation's status/reality contradiction, it was NOT this default resolving to a
-// broken or different host; that theory is disproven. Left as a naming clarity improvement only.
+// Production admin API by default; set VELARO_ADMIN_API to target staging.
 const API_BASE      = process.env.VELARO_ADMIN_API     || 'https://api-admin-us-east.velaro.com';
 const MESSAGING_API = resolveMessagingApi(process.env.VELARO_MESSAGING_API, API_BASE);
 const MCP_KEY       = process.env.VELARO_MCP_KEY;
 const JWT           = process.env.VELARO_JWT;
 
-// 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 —
-// defaulting env-selectable tools to one hardcoded environment while every other tool in this
-// file follows the single global API_BASE would recreate the exact bug being fixed here: an
-// operator configured for one environment would silently get a DIFFERENT environment's answer
-// from just these tools with no indication anything was different.
-const ADMIN_API_HOSTS = {
-  staging:    'https://velaro-admin-staging.azurewebsites.net',
-  production: 'https://api-admin-us-east.velaro.com',
-};
-
-/// Resolves an optional `env` tool argument to a target admin API base. Throws on an unrecognized
-/// value instead of silently falling through to API_BASE (the JS default-parameter behavior of
-/// `api(..., base)` when `base` is `undefined`) — a typo like `env: 'prod'` must not silently run
-/// a DESTRUCTIVE call (calendly_disconnect) against whatever this server defaults to while telling
-/// the caller it targeted a different environment. `hasOwnProperty` (not truthiness) also closes
-/// the prototype-chain edge case (`env: 'constructor'`, `env: 'toString'`, etc.).
-function resolveAdminBase(env) {
-  if (env === undefined || env === null) return API_BASE;
-  if (!Object.prototype.hasOwnProperty.call(ADMIN_API_HOSTS, env)) {
-    throw new Error(`Unknown env "${env}" — use "staging" or "production" (or omit it to use this server's configured default).`);
-  }
-  return ADMIN_API_HOSTS[env];
-}
-
 if (!MCP_KEY && !JWT) {
   process.stderr.write('ERROR: Set VELARO_MCP_KEY=vel_live_... or VELARO_JWT=<token>\n');
   process.exit(1);
@@ -115,15 +76,6 @@ function formatHealthRow(item) {
   return `  ${(item.slug ?? '?').padEnd(14)}  ${(item.status ?? '?').padEnd(14)}  ${ms.padStart(7)}  ${ts}  ${item.detail ?? ''}`.trimEnd();
 }
 
-function parseDuration(s) {
-  const m = /^(\d+)(m|h|d)$/i.exec(String(s ?? '2h').trim());
-  if (!m) return 2 * 3600 * 1000;
-  const n = parseInt(m[1], 10);
-  if (m[2] === 'm') return n * 60 * 1000;
-  if (m[2] === 'h') return n * 3600 * 1000;
-  return n * 24 * 3600 * 1000;
-}
-
 async function messagingApi(path, opts = {}) {  // opts.timeoutMs: log searches pass 40000 (server scan budget 12 s + 6 s AI search)
   if (!MESSAGING_API) throw new Error(
     'VELARO_MESSAGING_API is not configured. Add "VELARO_MESSAGING_API": "https://velaro-messaging-api-staging.azurewebsites.net" to your MCP env config.'
@@ -133,7 +85,6 @@ async function messagingApi(path, opts = {}) {  // opts.timeoutMs: log searches
     method: opts.method ?? 'GET',
     headers: {
       Authorization: authHeader(),
-      'X-Internal-SiteId': '1032',
       ...(opts.body ? { 'Content-Type': 'application/json' } : {}),
     },
     body: opts.body ? JSON.stringify(opts.body) : undefined,
@@ -142,22 +93,11 @@ async function messagingApi(path, opts = {}) {  // opts.timeoutMs: log searches
   const res = (opts.method ?? 'GET') === 'GET' ? await fetchRetry429(`${MESSAGING_API}${path}`, init) : await fetch(`${MESSAGING_API}${path}`, init());
   if (!res.ok) {
     const text = await res.text().catch(() => '');
-    throw new Error(`Velaro Logger ${path} -> ${res.status}: ${text.slice(0, 300)}`);
+    throw new Error(`Messaging API ${path} -> ${res.status}: ${text.slice(0, 300)}`);
   }
   return res.json();
 }
 
-// FIXED 2026-09-24: velaro-messaging's /superadmin/logs/search used to return a bare JSON array
-// for some queries and {entries, nextCursor} for others, depending on which internal code path
-// served the request (see that repo's LogsController.cs ENVELOPE SHAPE comment). It now always
-// returns {entries, nextCursor} -- this helper also accepts a bare array so callers degrade
-// gracefully rather than throwing if ever pointed at an older deploy.
-function extractLogEntries(response) {
-  if (Array.isArray(response)) return response;
-  if (response && Array.isArray(response.entries)) return response.entries;
-  return [];
-}
-
 /** Body for POST/PUT ApplePayPresetOrders: only passed fields; the server computes the total. */
 function applePayPresetBody(args) {
   const body = {};
@@ -334,51 +274,9 @@ async function api(method, path, body, base = API_BASE) {
   return text ? JSON.parse(text) : null;
 }
 
-// ── Livefluence migration helpers ─────────────────────────────────────────────
-
 import { fileURLToPath as _ftu } from 'node:url';
 import { join as _join, dirname as _dirname } from 'node:path';
-import { readFileSync as _readFileSync, existsSync as _existsSync } from 'node:fs';
-
-const _migrationsDir = _join(_dirname(_ftu(import.meta.url)), '..', 'cli', 'lib', 'migrations');
-
-function loadMigrationProfile(slug) {
-  if (!slug) throw new Error('Provide customer slug (azenta, amscro, bluefire, donaldson) or a custom profile object.');
-  const file = _join(_migrationsDir, `${slug}.json`);
-  if (!_existsSync(file)) {
-    throw new Error(`Migration profile "${slug}" not found. Available: azenta, amscro, bluefire, donaldson`);
-  }
-  return JSON.parse(_readFileSync(file, 'utf8'));
-}
-
-function mcpResolveTokens(tokenMap, items, idField, nameField) {
-  const out = {};
-  for (const [token, name] of Object.entries(tokenMap)) {
-    const match = (items ?? []).find(i => i[nameField]?.toLowerCase() === name.toLowerCase());
-    out[`@${token}`] = match ? String(match[idField]) : null;
-  }
-  return out;
-}
-
-function mcpResolveValue(value, aiMap, teamMap) {
-  if (!value) return value;
-  const out = {};
-  for (const [k, v] of Object.entries(value)) {
-    if (typeof v === 'string' && v.startsWith('@')) {
-      out[k] = aiMap[v] ?? teamMap[v] ?? v;
-    } else {
-      out[k] = v;
-    }
-  }
-  return out;
-}
-
-function mcpFindUnresolved(value) {
-  if (!value) return [];
-  return Object.entries(value)
-    .filter(([, v]) => v === null || (typeof v === 'string' && v.startsWith('@')))
-    .map(([k]) => k);
-}
+import { readFileSync as _readFileSync } from 'node:fs';
 
 // The hosted gateway requires an initialized session (Mcp-Session-Id + MCP-Protocol-Version) on
 // every call after "initialize". Cache one per process and re-initialize when it expires (404).
@@ -1067,6 +965,8 @@ Key node shapes:
     propName:"myAnswerVar" }                      // variable that stores the result as JSON array string
 • condition:      { type:"action", actionType:"condition", conditionOptions:[...] }
 • transferToAI:   { type:"action", actionType:"transferToAI", aiConfigId:N }
+• selectPreChat:  { type:"action", actionType:"selectPreChat", surveyId:N, surveyCompact:true|false|null, child:N }
+  surveyCompact (optional tri-state): null/omitted = follow the survey's own compactMode, true = compact, false = regular.
 • sendSurvey:     { type:"action", actionType:"sendSurvey", sendSurveyId:N, surveyDeliveryMode:"conversational"|"form", closeAfterSurvey:true|false, child:N }
   closeAfterSurvey (optional, default false): when true the chat closes once the visitor completes the survey (use for Unavailable/after-hours surveys that replace a live chat). Omit to keep the old behaviour.
   AI follow-up suggestions ("AI mode"): add suggestFollowUps:true|false (omit = use the account default, set via ai_followups_site_set), suggestFollowUpCount:2-4, suggestFollowUpInstruction:"<=300 chars". After each web-chat bot reply the bot offers short tappable follow-up replies; typing stays available.
@@ -1132,13 +1032,14 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   },
   {
     name: 'survey_upsert',
-    description: 'Create (omit id or set id=0) or update (set id) a survey. body must be the full SurveyViewModel JSON shape (id, name, questions[], each question with type/text/options/required/variable/etc.). Use survey_get on an existing survey to fetch this full shape as a template rather than guessing the question schema from scratch. Each question also accepts isThemeAnchor (boolean, default false: this answer sets the Chat Intelligence topic) and themeMapping (string: JSON object mapping answer text to a site topic, e.g. "{\\"Pay my bill\\":\\"Billing Questions\\"}"). Both only take effect when the site has the multi-topic setting on.',
+    description: 'Create (omit id or set id=0) or update (set id) a survey. body must be the full SurveyViewModel JSON shape (id, name, questions[], each question with type/text/options/required/variable/etc.). Use survey_get on an existing survey to fetch this full shape as a template rather than guessing the question schema from scratch. Each question also accepts isThemeAnchor (boolean, default false: this answer sets the Chat Intelligence topic) and themeMapping (string: JSON object mapping answer text to a site topic, e.g. "{\\"Pay my bill\\":\\"Billing Questions\\"}"). Both only take effect when the site has the multi-topic setting on. body.compactMode is tri-state: null/omitted = follow default (regular size), true = compact, false = regular.',
     inputSchema: {
       type: 'object',
       properties: { body: {
         type: 'object',
         description: 'Full SurveyViewModel JSON',
         properties: {
+          compactMode: { type: ['boolean', 'null'], description: 'Tri-state survey size: null/omitted = follow default (regular size), true = compact, false = regular' },
           questions: {
             type: 'array',
             items: {
@@ -1582,6 +1483,28 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     },
   },
 
+  {
+    name: 'agent_force_sign_out',
+    description: 'Security control: force one agent to sign in again. Revokes every active session of that agent now (their existing tokens stop working) and sets them Offline. Administrator only; the agent must belong to your site; audited (who/when/target). You cannot force sign out your own account.',
+    inputSchema: {
+      type: 'object',
+      properties: { userId: { type: 'number', description: 'Agent user id from agent_list' } },
+      required: ['userId'],
+    },
+  },
+  {
+    name: 'agent_set_status',
+    description: 'Set an agent availability status (Available, Busy, Away, Offline). Use Offline or Away to make an agent Unavailable for routing. Site manager only; the agent must belong to your site; audited with the acting admin.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        userId: { type: 'number', description: 'Agent user id from agent_list' },
+        status: { type: 'string', enum: ['Available', 'Busy', 'Away', 'Offline'] },
+      },
+      required: ['userId', 'status'],
+    },
+  },
+
   // ── Dynamics per-team overrides (effective = team override ?? connection default) ──
   {
     name: 'dynamics_team_overrides_get',
@@ -1714,8 +1637,6 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
         },
         buttonLabel: { type: 'string', description: 'Optional action button label' },
         buttonUrl:   { type: 'string', description: 'Optional action button URL (required if buttonLabel is set)' },
-        mentions:    { type: 'array', description: 'People to @mention (real Teams notification). Velaro staff only. Uses the ops Teams sender instead of a webhook.', items: { type: 'object', properties: { user: { type: 'string', description: 'Entra object id or UPN, e.g. andrea@velaro.com' }, name: { type: 'string', description: 'Display name shown in the @mention' } }, required: ['user'] } },
-        destination: { type: 'string', description: 'Named channel in the DevOps team instead of General: prs, workflows, deploys, alerts, qa, general. Velaro staff only; uses the ops Teams sender instead of a webhook.' },
       },
       required: ['title'],
     },
@@ -2061,6 +1982,27 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
       },
     },
   },
+  {
+    name: 'safety_policy_get',
+    description: 'Get the safety controls policy: per control (emergency_self_harm, abuse_ladder, threat_detection, input_jailbreak, output_filter) whether it is on for AI bot and human agent, any overrides, the always-on floor, a warning when anything is off, and the acknowledgement text and version needed to turn a control off. Wraps GET SafetyPolicy.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'safety_policy_set',
+    description: 'Turn a safety control on, off, or back to default. Every control is ON by default. Turning one OFF is refused unless acknowledged=true AND ackTextVersion equals the current acknowledgement version (read it from safety_policy_get and show the acknowledgement text to the account owner first). This tool never accepts the acknowledgement on anyone\'s behalf. Turning on or resetting needs no acknowledgement. Wraps PUT SafetyPolicy.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        control:        { type: 'string', enum: ['emergency_self_harm', 'abuse_ladder', 'threat_detection', 'input_jailbreak', 'output_filter'] },
+        audience:       { type: 'string', enum: ['ai_bot', 'human_agent'] },
+        featureKey:     { type: 'string', description: 'Optional per-feature/channel scope (chat, voice, sms, whatsapp, email). Omit for the whole account.' },
+        enabled:        { type: ['boolean', 'null'], description: 'true = on, false = off, null = clear the override (default on)' },
+        acknowledged:   { type: 'boolean', description: 'Required true when enabled=false: the account owner accepted the acknowledgement text' },
+        ackTextVersion: { type: 'string', description: 'Required when enabled=false: the acknowledgement version from safety_policy_get' },
+      },
+      required: ['control', 'audience', 'enabled'],
+    },
+  },
   {
     name: 'safety_settings_test',
     description: 'Send a test safety alert to the configured recipients. Wraps POST SafetyEvents/settings/test.',
@@ -2561,7 +2503,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     },
   },
 
-  // ── Integration Diagnostics (Velaro staff) ────────────────────────────────
+  // ── Integration Diagnostics ────────────────────────────────
   {
     name: 'integration_activity_list',
     description: 'List integration activity log entries (auth events, rate limits, config errors, AI skill calls). Fastest way to diagnose why a specific integration is failing — check this before App Insights.',
@@ -3231,7 +3173,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   },
   {
     name: 'velaro_diagnostic_start',
-    description: 'START HERE for any "broken", "fix", "not working", "error", or "why is X failing" request. Returns the Velaro diagnostic runbook: which log tool to check first, query patterns for common symptoms (exceptions, AI skill errors, Hangfire failures, SignalR hub down, campaign issues), and the rule "check logs before reading code." Call this before touching any source file.',
+    description: 'START HERE for any "broken", "not working", "error", or "why is X failing" request about your Velaro site. Returns the diagnostic runbook: which activity log, health and report tools to check first for integration, channel, bot and routing problems.',
     inputSchema: { type: 'object', properties: {}, required: [] },
   },
 
@@ -3314,6 +3256,34 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   },
 
 
+  {
+    name: 'magento_get_sidebar_fields',
+    description: 'Get the Magento fields shown in the agent sidebar panel for the authenticated site (empty list = out-of-box defaults). Calls messaging GET Magento/data/sidebar-fields. Site comes from the bearer token only. Read-only.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'magento_set_sidebar_fields',
+    description: 'Set the Magento fields shown in the agent sidebar panel for the authenticated site. Partial update: omit fields to leave the saved list untouched; an empty array clears it. Site comes from the bearer token only. Calls messaging PUT Magento/data/sidebar-fields.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fields: {
+          type: 'array',
+          description: 'Sidebar fields to show, in order',
+          items: {
+            type: 'object',
+            properties: {
+              fieldName: { type: 'string', description: 'Magento field name, e.g. "email"' },
+              entity:    { type: 'string', description: 'Entity the field belongs to, e.g. "customer" or "order"' },
+              label:     { type: 'string', description: 'Optional display label' },
+            },
+            required: ['fieldName'],
+          },
+        },
+      },
+    },
+  },
+
   {
     name: 'business_action_list',
     description: 'List the shared business actions registered on the messaging API (e.g. get_customer_pricing, create_quote): name, whether it is a write, data class, freshness window, request JSON schema and the AI skill tool names that project it. One definition is served by the Velaro catalog or a connected ERP (SAP) beneath it. Site scope comes from the caller\'s auth context. Calls GET /BusinessActions.',
@@ -3480,6 +3450,29 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     inputSchema: { type: 'object', properties: {}, required: [] },
   },
 
+  {
+    name: 'teams_phone_list_agents',
+    description: "List the site's agents with their Microsoft Teams user Object ID mapping (agent -> Entra user), used to route inbound Teams Phone calls to the right agent. Admin only. Lives in velaro-messaging — requires VELARO_MESSAGING_API.",
+    inputSchema: { type: 'object', properties: {}, required: [] },
+  },
+  {
+    name: 'teams_phone_set_agent',
+    description: 'Map one Velaro agent (workspace user id) to a Microsoft Entra user Object ID (GUID) so inbound Teams Phone calls reach them. Upsert; pass "" to clear. Must be unique per site. Lives in velaro-messaging — requires VELARO_MESSAGING_API.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        agentId:     { type: 'number', description: 'Velaro agent (workspace user) id from teams_phone_list_agents.' },
+        teamsUserId: { type: 'string', description: 'Entra user Object ID (GUID). "" clears the mapping.' },
+      },
+      required: ['agentId', 'teamsUserId'],
+    },
+  },
+  {
+    name: 'teams_phone_delete_agent',
+    description: "Clear one agent's Teams user mapping. Calls to that Teams user will no longer route to the agent.",
+    inputSchema: { type: 'object', properties: { agentId: { type: 'number', description: 'Velaro agent (workspace user) id.' } }, required: ['agentId'] },
+  },
+
   // ── Webflow (config CRUD) ──────────────────────────────────────────────────
   // Lives in velaro-admin's own WebflowController.cs (this API), not velaro-messaging.
   // The other 6 Webflow AI skills (webflow_list_sites, webflow_get_site,
@@ -3700,7 +3693,7 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
   },
   {
     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.',
+    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, use Billing > Contact Account Manager.',
   },
   {
     name: 'billing_contacts_list',
@@ -3827,6 +3820,8 @@ For multiSelect dynamic options: the variable named in dynamicOptionsVariable mu
     },
   },
 
+  // ── Billing agents + package builder (staff; docs/architecture/billing-agents-and-package-builder.md) ──
+  { name: 'package_builder_my', description: 'Customer-safe: the caller\'s own package name and what it includes. No prices or staff data.', inputSchema: { type: 'object', properties: {} } },
   // ── Pricing Catalog ───────────────────────────────────────────────────────
   {
     name: 'pricing_catalog_list',
@@ -5333,12 +5328,12 @@ async function handleTool(name, args) {
       return await rpc('workflow_update_node', args);
 
     // ── Surveys ──────────────────────────────────────────────────────────
-    // Direct messagingGet/Post/Del calls (like notifications_get/ai_config_staff_get above) —
+    // Direct messagingGet/Post/Del calls (like notifications_get above) —
     // site isolation is enforced server-side by SurveysController's [Authorize]-scoped SiteId
     // (ClientControllerBase), never passed by the client. Note: SurveysController's global
     // [Authorize] does not accept vel_live_* service keys (only a handful of controllers opt
     // into that manually) — these tools need VELARO_JWT, same requirement as the existing
-    // notifications_get/ai_config_staff_get tools they're modeled on.
+    // notifications_get tool they're modeled on.
     case 'ai_followups_site_get': {
       const r = await messagingGet('/SiteSettings/AiFollowUps');
       return JSON.stringify({ enabled: r?.enabled ?? null }, null, 2);
@@ -5809,6 +5804,19 @@ reply: ${r?.reply}`;
     case 'agent_list':
       return await rpc('agent_list', args);
 
+    case 'agent_force_sign_out': {
+      if (!Number.isInteger(args.userId) || args.userId <= 0) return 'userId is required (positive integer).';
+      await messagingPost(`/Users/${args.userId}/ForceSignOut`, {});
+      return `Agent ${args.userId} was signed out of every session and set to Offline. They must sign in again.`;
+    }
+
+    case 'agent_set_status': {
+      if (!Number.isInteger(args.userId) || args.userId <= 0) return 'userId is required (positive integer).';
+      if (!['Available', 'Busy', 'Away', 'Offline'].includes(args.status)) return 'status must be Available, Busy, Away or Offline.';
+      await messagingPost('/UserStatus/admin', { userId: args.userId, status: args.status });
+      return `Agent ${args.userId} set to ${args.status}.`;
+    }
+
     // ── Teams ──────────────────────────────────────────────────────────────
     case 'team_list':
       return await rpc('team_list', args);
@@ -5883,16 +5891,6 @@ reply: ${r?.reply}`;
     }
 
     case 'teams_notify_card': {
-      if ((args.mentions && args.mentions.length) || args.destination) {
-        const r = await api('POST', '/TeamsMessaging/Card', {
-          title: args.title,
-          facts: (args.fields || []).map(f => ({ label: f.label, value: f.value })),
-          actionUrl: args.buttonUrl, actionLabel: args.buttonLabel,
-          destination: args.destination,
-          mentions: (args.mentions || []).map(m => ({ user: m.user, name: m.name })),
-        });
-        return r?.sent ? `Card sent via ${r.path}${r.warnings?.length ? ' (' + r.warnings.join('; ') + ')' : ''}.` : `Send failed: ${r?.error || 'unknown error'}`;
-      }
       const webhooks = await api('GET', '/TeamsNotification');
       if (!Array.isArray(webhooks) || !webhooks.length)
         return 'No Teams webhooks configured. Go to Integrations → Microsoft Teams to add one, or call velaro teams create <name> <webhookUrl> via CLI.';
@@ -6386,6 +6384,21 @@ reply: ${r?.reply}`;
       }
       return JSON.stringify(await messagingPut('/SafetyEvents/settings', next), null, 2);
     }
+    case 'safety_policy_get':
+      return JSON.stringify(await messagingGet('/SafetyPolicy'), null, 2);
+    case 'safety_policy_set': {
+      if (args.enabled === false && (args.acknowledged !== true || !args.ackTextVersion)) {
+        throw new Error('Turning a safety control off requires acknowledged=true and ackTextVersion (from safety_policy_get). This tool never accepts the acknowledgement automatically.');
+      }
+      const body = {
+        control: args.control,
+        audience: args.audience,
+        featureKey: args.featureKey ?? null,
+        enabled: args.enabled === undefined ? null : args.enabled,
+        ...(args.enabled === false ? { acknowledged: true, ackTextVersion: args.ackTextVersion } : {}),
+      };
+      return JSON.stringify(await messagingPut('/SafetyPolicy', body), null, 2);
+    }
     case 'safety_settings_test':
       return JSON.stringify(await messagingPost('/SafetyEvents/settings/test'), null, 2);
     case 'safety_need_help':
@@ -7262,7 +7275,9 @@ reply: ${r?.reply}`;
     }
 
     case 'report_explain': {
-      const all = JSON.parse(_readFileSync(_join(_dirname(_ftu(import.meta.url)), '..', 'cli', 'lib', 'report-explain.json'), 'utf8'));
+      // Packaged copy (mcp/report-explain.json, kept identical to cli/lib/report-explain.json by
+      // scripts/validate-cli-mcp-syntax.js). The old '../cli/lib' path does not exist in a package install.
+      const all = JSON.parse(_readFileSync(_join(_dirname(_ftu(import.meta.url)), 'report-explain.json'), 'utf8'));
       const key = String(args.report ?? '').trim().toLowerCase();
       if (!key) return Object.entries(all).map(([k, r]) => `${k}: ${r.name}`).join('\n');
       const r = all[key];
@@ -7577,6 +7592,21 @@ reply: ${r?.reply}`;
       return lines.join('\n');
     }
 
+    case 'magento_get_sidebar_fields': {
+      const r = await messagingRequest('GET', '/Magento/data/sidebar-fields');
+      return JSON.stringify(r, null, 2);
+    }
+
+    case 'magento_set_sidebar_fields': {
+      const body = {};
+      if (args.fields !== undefined) {
+        if (!Array.isArray(args.fields)) return 'fields must be an array.';
+        body.fields = args.fields;
+      }
+      const r = await messagingRequest('PUT', '/Magento/data/sidebar-fields', body);
+      return JSON.stringify(r, null, 2);
+    }
+
     case 'business_action_list': {
       const r = await messagingRequest('GET', '/BusinessActions');
       return JSON.stringify(r, null, 2);
@@ -7730,6 +7760,20 @@ reply: ${r?.reply}`;
       return lines.join(String.fromCharCode(10));
     }
 
+    case 'teams_phone_list_agents': {
+      const agents = await messagingGet('/TeamsPhone/Agents');
+      if (!Array.isArray(agents) || agents.length === 0) return 'No agents found.';
+      return agents.map(a => `${a.id}  ${`${a.firstName ?? ''} ${a.lastName ?? ''}`.trim()}  ${a.email ?? ''}  ${a.teamsUserId || '(unmapped)'}`).join(String.fromCharCode(10));
+    }
+    case 'teams_phone_set_agent': {
+      const r = await messagingPut(`/TeamsPhone/Agents/${encodeURIComponent(args.agentId)}`, { teamsUserId: args.teamsUserId });
+      return r?.configured ? `Agent ${args.agentId} mapped to Teams user ${r.teamsUserId}.` : `Agent ${args.agentId} mapping cleared.`;
+    }
+    case 'teams_phone_delete_agent': {
+      await messagingDel(`/TeamsPhone/Agents/${encodeURIComponent(args.agentId)}`);
+      return `Agent ${args.agentId} mapping cleared.`;
+    }
+
     // ── Shopify write policy (velaro-messaging /api/Shopify/WritePolicy) ───────
     case 'shopify_get_write_policy': {
       return JSON.stringify(await messagingGet('/Shopify/WritePolicy'), null, 2);
@@ -8149,11 +8193,13 @@ ${JSON.stringify(result, null, 2)}`;
         lines.push('Recent payments:');
         s.recentSessions.forEach(p => lines.push(`  ${(p.amountCents/100).toFixed(2)}  ${p.status}  ${p.createdAt?.slice(0,10)}`));
       }
-      // Note: QB sync, deferred revenue, and internal accounting details are omitted here.
-      // Use billing_plan_status_internal in staff-server.js for those.
+      // QB sync, deferred revenue, and internal accounting details are intentionally omitted.
       return lines.join('\n');
     }
 
+    // ── Billing agents + package builder ──────────────────────────────────────
+    case 'package_builder_my': return JSON.stringify(await api('GET', '/PackageBuilder/my'), null, 2);
+
     // ── Pricing Catalog ───────────────────────────────────────────────────────
     case 'pricing_catalog_list': {
       const pkgs = await api('GET', '/Pricing/catalog');
@@ -8961,41 +9007,21 @@ ${JSON.stringify(result, null, 2)}`;
 
 const DIAGNOSTIC_RUNBOOK = `# Velaro Diagnostic Runbook
 
-## ALWAYS DO THIS FIRST before reading any code on a "broken" / "fix" / "not working" request
-
-### Step 0 — Start here every time
-1. \`logs_appinsights_query\` env=staging → \`exceptions | where timestamp > ago(1h) | take 20\`
-2. \`logs_loggly_search\` → \`tag:velaro-messaging-Staging ERROR\` (last 1h)
-3. \`mcp__velaro__get_diagnostic\` or \`velaro ops\` for Hangfire queue / deploy version
-
-Reading code without checking logs first = debugging blind.
-
-### Step 1 — Pick the right log source
-| Symptom | Tool | Query pattern |
-|---|---|---|
-| Exceptions / 500s in admin | logs_appinsights_query env=staging | exceptions \| where timestamp > ago(1h) \| take 20 |
-| Exceptions / 500s in messaging | logs_appinsights_query env=messaging-production | exceptions \| where timestamp > ago(1h) \| take 20 |
-| AI skill errors | logs_loggly_search | tag:velaro-messaging-Staging SkillInvoked |
-| Campaign / Hangfire failures | logs_loggly_search | tag:velaro-messaging-Staging Hangfire |
-| IVR / SignalR hub down | signalr_diagnostics instance=both hub=MessengerHub |
-| Prod exceptions | logs_appinsights_query env=production | exceptions \| take 20 |
-| Secure forms errors | logs_appinsights_query env=secure-forms | exceptions \| take 20 |
-| Scraper / automation errors | logs_appinsights_query env=automation-production | exceptions \| take 20 |
-
-### Step 2 — SignalR alerts
-Alerts: SignalR-CapSaturation-PAGE, SignalR-ServiceError-PAGE, SignalR-Quota95-PAGE are wired to velaro-ci-runners (Partner Success Core Benefits sub).
-Use \`signalr_diagnostics hub=MessengerHub\` or \`hub=EngagementHub\` to check live connection counts.
+Check what Velaro already recorded before changing any configuration.
 
-### Step 3 — Integration issues
-Use \`mcp__velaro__get_conversations\` or activity log endpoint \`/Integration/Logs/{slug}?severity=Error\` before digging into skill files.
+1. Integration failures: \`integration_activity_list\` with severity=Error (filter by integration slug), then
+   \`integration_skill_logs\` for AI skill calls that failed.
+2. Channel or integration connectivity: \`integration_health\` (pass run=true with a slug to probe now).
+3. Bot problems: \`bot_recent_errors\` and \`bot_skill_usage\`.
+4. Volume or service-level changes: \`kpi_snapshot\` and \`service_level_report\`.
+5. Routing questions: \`routing_explain_decision\` / \`routing_get_decision_log\`.
 
-### Step 4 — Only read code if logs are clean
-If all log sources are quiet → then read source code to find the bug.`;
+If these show nothing unusual, contact Velaro support with the time window and conversation ids you checked.`;
 
 const PROMPTS = [
   {
     name: 'diagnostic_runbook',
-    description: 'Velaro diagnostic runbook — which log tool to use first, query patterns for common symptoms, SignalR alert reference. ALWAYS consult this before reading code on any "broken" or "fix" request.',
+    description: 'Velaro diagnostic runbook: which activity log, health and report tools to check first when something on your site is not working.',
     arguments: [],
   },
 ];