Nox / Knox Admin Assistant

Nox (internally Knox) is the AI assistant the customer's team uses inside the dashboard: it answers questions about visitors, sessions, calls, and bookings, and takes actions in connected CRMs. It lives in ms-ai's src/knox-agent/ module, with surfaces in frontend (nox* stores) and sync paths in backend (app/lib/msAiKnoxClient.js, Knox cron jobs).

One insight engine. "What Matters Today" / the insight engine is the single source for all Nox surfaces (daily brief, alerts, etc.) — never re-derive per-surface.

Request flow

askQuestion(dto, auth)
  → hydrate prior turns from DB (source of truth)
  → intent classifier  (navigate | analytics | how_to | explain | compare
                         | troubleshoot | action | draft_followup | fallback)
  → dispatch to a specialist sub-agent
  → run tools (grounded in RAG + memory + live data)
  → persist conversation + usage telemetry

knox-agent.service.ts orchestrates; intent/knox-intent-classifier.service.ts routes (and asks a clarifying question rather than guessing when ambiguous).

Sub-agents

Sub-agent	Handles
Navigation	"where do I find X?" UI guidance
Analytics	visitor/session/call metrics
Knowledge	product docs, how-tos, troubleshooting (RAG)
Action	side effects (send SMS, place call, book)
Outreach	draft follow-up emails/SMS as documents
Generalist	fallback with the full toolset

Tools

42 tools in knox-agent/tools/ (registered in knox-tool-registry.ts), including: knox_visitor_search / knox_visitor_profile / knox_visitor_bookings, knox_recent_sessions / knox_session_analysis / knox_stats, knox_call_transcripts (ElevenLabs audio), knox_chat_transcript, knox_knowledge_search (RAG), knox_place_call (now with scheduled_at — max 30 days out, quiet hours defer to next 9am local, fired by ScheduledNoxActionJob every 5 min) / knox_draft_followup / knox_send_followup, knox_person_lookup (now also surfaces CRM-only contacts, flagged crm_only) / knox_enrich_contact, knox_is_visitor_live / knox_presence (live presence from ms-sessions), knox_crm (GHL contact/ opportunity sync), knox_visitor_watch (consolidated notify/engage/list/cancel), the Nox funnel family (knox_funnel, knox_tag_contact, knox_move_pipeline, knox_trigger_workflow, knox_book_meeting, knox_mark_customer, knox_funnel_reconcile, knox_brief_offers) and Agent K's knox_agent_k_weights. Executions are collected by KnoxToolCallCollector and written to knox_action_events / knox_action_audit. Tool results return structured objects for the canvas/citations, but the LLM reads curated markdown (services/knox-tool-markdown.ts); the per-turn model_markdown is persisted and shown in the admin conversation viewer ("Model saw").

Memory

• Admin memory (knox-admin-memory.service.ts) — operator insights and standing rules stored as pgvector chunks (knox_admin_memory), pulled into each turn for context.
• Memory extraction (knox-memory-extraction.service.ts) — fire-and-forget extraction of durable facts from operator questions.

Actions in GHL (the action layer)

Nox can draft-and-approve follow-ups and enrich contacts in GHL. This shipped in two stages: a backend API + central review surface, and an inline-chat approval card (via an ms-ai nox_followup action). A standing-rule / autonomous-send toggle lets some drafts send without per-item approval. Sync is handled by knox-ghl-sync.service.ts with a webhook receiver (knox-ghl-webhook.controller.ts) and nightly KnoxGhlSyncJob (03:00) in backend.

Insight engine & daily brief

knox-insight-engine.service.ts produces proactive insights (behavior patterns, opportunities, visitor watch) and feeds knox-brief-snapshot.service.ts / knox-daily-brief-composer.service.ts. Backend's DailyBriefEmailJob (10-min tick) renders and sends the email once per local day at knox.daily_brief.send_hour (default 9; funnel tenants set 5) — it replaced ReportingEmailJob, which is now unscheduled (and the monthly report defaults off for new companies). Funnel tenants get deterministic funnel blocks (knox-funnel-insights.ts) plus executable offers persisted to brief_offers (~48h validity, actioned via knox_brief_offers) — see Nox Funnel. KnoxBaselineMetricsJob (02:00) refreshes cohort metrics. In the dashboard the brief no longer auto-opens by default — a brief-ready badge appears, and the per-user auto-play preference gates spoken playback.

Visitor watches & auto-engage

Watch/auto-engage directives (KnoxVisitorDirectiveModel, backend PersonWatchService) recognize returns by device signals + exact identifiers, dedupe on create, and fire on real page loads only. Tenants list/cancel their own via GET/DELETE /knox/visitor-watches; super-admins get a cross-company view with diagnostics (last_attempt_at / last_skip_reason — admin-only render). Auto-engage delivery goes through ms-communication POST /nox-auto-engage (endpoint auth deferred), which composes and pushes the widget message.

Nox Live

Full-screen surface (frontend/src/components/knox/NoxLive.vue, mounted from AppLayout.vue): orb + right-hand canvas. Canvas cards are server-declared (services/knox-canvas.ts maps tool results to _canvas cards) and arrive via tool_result SSE events; for voice calls the events fan out over Redis pub/sub (knox-voice/knox-voice-events.service.ts) because the ElevenLabs tool webhook and the browser's SSE subscription land on different pods.

Knowledge grounding

The Knowledge sub-agent and knox-knowledge-search retrieve from the RAG store fed by nox-knowledge-base.

Voice

Nox also has a voice mode (Knox Voice, src/knox-voice/) bridging the same tools into ElevenLabs telephony. A voice call continues the shared Nox conversation (the frontend sends recent turns; knox-voice.service.ts injects a continuity line). White-label: the assistant self-references the tenant's ai_assistant_name and never says "Knock Knock"; agencies can override the TTS voice via agency.nox_voice_id (per-session tts.voiceId override in knox-agent-sync.service.ts). See ms-ai.

Related subsystems

• Nox Funnel — the behaviour-derived lead funnel Nox reads and acts on (backend-owned engine).
• Agent K — the prospecting agent (GHL push pipeline).