Skip to main content

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).

Two engines (2026-11). Every company now runs on the v2 engine (ms-ai/src/knox-v2/, POST /knox-v2/ask) — planner, researcher/writer subagents, guards, proactive triggers, the morning day plan, the job-based voice hand-over. It is documented on its own page: Nox v2 Engine. The request flow, sub-agents and tool registry below are the v1 engine, still live as the fallback (/knox-agent/ask when GET /knox-v2/status is false or fails) and still the source of the knox_* tools v2 adapts. Settings-by-chat, the scheduled-action queue, the canvas contract, activity history, visitor watches and the brief are shared by both.

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 (v1)​

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).

The classifier emits a subject (own_data | product | other) before primary_intent (c6f03b256, 2026-10-05); follow-ups inherit the subject of the turn they continue. applySubjectGuard() (intent/knox-intent.types.ts) rewrites own_data + how_to | explain | compare | troubleshoot to analytics — "organic today vs last Monday" used to land on the docs-only knowledge agent. compare now means product/plan comparisons only. Live classifier eval: npm run eval:knox-intent (eval/knox-intent.eval.ts, 44 cases, hits the real model).

Time windows. Every analytics tool's window enum (utils/tz-windows.ts WINDOW_ENUM) is today | yesterday | last_24h | this_week | this_month | last_7d | last_30d | last_week | last_monday … last_sunday | custom. last_<weekday> = the most recent such day before today (so last_<today's weekday> = same day last week); last_week = previous Mon–Sun. A named window always wins: from/to are ignored unless window: "custom" or no window (models fill every optional field, usually with bad UTC math). resolveDatePhrases() resolves "last monday", "same day last week", "monday last week", "yesterday" in the admin tz and injects them into the analytics/generalist turn context. knox_stats kind: 'baseline' with yesterday / last_week / last_<weekday> runs as a window query (baseline is a dateless rolling-30-day blob), and every knox_stats result leads with a period label.

Sub-agents​

Sub-agentHandles
Navigation"where do I find X?" UI guidance
Analyticsvisitor/session/call metrics
Knowledgeproduct docs, how-tos, troubleshooting (RAG)
Actionside effects (send SMS, place call, book)
Outreachdraft follow-up emails/SMS as documents
Generalistfallback with the full toolset

Gating (2026-08-20 onward)​

Nox is on for every company. 4a0c3e103/frontend 3df9a70a deleted the super-admin "Nox Agent" and "Nox Standup Beta" toggles, nox_standup_enabled, the knox.enabled access gates in KnoxCrmController / KnoxStatsController._loadCompany (403 knox_disabled), KnoxNotificationsController, the ChatController LLM enrichment gate, and the toggleNoxStandup / KnoxSettingsController enable-disable endpoints. ms-ai (e14196817) stopped refusing mode: 'standup' per company.

What still gates:

  • Engine choice — KNOX_V2_DEFAULT (on in PROD/DEV) + the per-company knox_v2_company_flags row decide v2 vs v1; see v2 gating. The launch-week NOX_ONLY_COMPANY_IDS allowlist and its maintenance interceptor were added and removed 2026-11-02/03.

  • Platform switches — nox_quality_check_enabled, nox_voice_server_reports and agency_client_tickets live in the backend settings collection (Admin → Settings → Feature Flags), replacing NOX_QUALITY_ENABLED, NOX_VOICE_SERVER_REPORTS and OPS_AGENCY_CLIENT_TICKETS; see platform switches.

  • knox.enabled (default true, no UI writes it) scopes background jobs only — DailyBriefEmailJob, KnoxBaselineMetricsJob, RecordingBackfillSweeperJob, MsAiHandoffSweeperJob, KnoxGhlSyncJob.

  • KnoxStatsController PLAN_GATED — live_sessions, recorded_sessions, ai_chatbot, auto_connect; FEATURE_COMPANY_FIELDS feeds feature awareness (df3f1f841 / ee28aa341): Nox is told what the tenant has, and refuses unavailable features with the real remedy (plan vs account manager) while entitled-but-unconfigured ones stay available with the missing step.

  • The last two Nox-side super-admin gates went on 2026-09-25 (backend f1d39fb38, frontend 021eae6b, ms-ai 2f15c50f8): nox_config_enabled (settings-by-chat) and nox_activity_enabled (activity history) — fields, PUT /company/:_id/nox-config / …/nox-activity routes and every check deleted. Both are on for every company; the only remaining limit on Nox Activity is the agency client permission pages.nox_activity.

Tools​

57 tools in knox-agent/tools/ (registered in knox-tool-registry.ts; was 45 before 2026-08-11), 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 (with scheduled_at — max 30 days out, quiet hours defer to next 9am local, fired at the exact time by the scheduled-action queue) / knox_schedule_sms / knox_list_scheduled_actions (renamed from the transient knox_list_scheduled_calls) / knox_draft_followup / knox_send_followup, knox_engage_visitor (message a LIVE visitor's widget now — confirmed gate, dry_run, delivery receipt via ms-comm relay + backend POST /internal/engage-receipt), knox_person_lookup (surfaces CRM-only contacts flagged crm_only; result rows carry pid:<person_id>; fuzzy name matching tolerates one substituted character for STT mishears — backend 864d3c0ae) / knox_enrich_contact, knox_is_visitor_live / knox_presence (live presence from ms-sessions), knox_crm (GHL contact/ opportunity sync — BackendCrmClient passes provider through for all four CRMs via one CRM_PROVIDERS allowlist, ghl | hubspot | jobber | salesforce; before 89cd65251 Jobber/Salesforce results arrived as provider: null. The analytics prompt tells it Salesforce searches Leads and Contacts and shows one "Opportunities" pipeline falling back to Lead.Status, and that HubSpot is the only CRM that can't search by phone or name), 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 (→ manual terminal Won stage), knox_funnel_reconcile, knox_brief_offers (offer registry, ~48h validity)), Agent K's knox_agent_k_weights and knox_agent_k_pipeline (queue counts / pending by source and signal / released today — GET /internal/knox/agent-k/pipeline), and the families added this window: config (knox_config_describe / knox_config_apply / knox_config_invoke), standup (knox_standup_tasks, knox_confirm_run, knox_cancel_task, knox_approve_task, knox_resolve_reference), knox_visitor_forms (/internal/knox/people/forms — real form submissions, so "did X fill in a form?" is never a guess), knox_call_status (/internal/knox/calls/status — added after an optimistic queued hid a failed dial; the same commit fixed phone-resolution precedence for call/SMS tools), and knox_discard_followup. knox_schedule_sms gained a GHL route for tenants with no SMS agent (exact text only, feature-gate checked; 8e53d7f4b / backend 68cd08b25). knox_person_lookup defers its full-text scans to a total miss and the backend bounds chat-mention scans (51f48cd84 / e7fd5ca32). 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) — with custom renderers for transcript/session/facts/action-feed tools, because the generic renderer only walked scalar fields and silently dropped nested messages[] / conversations[] / facts[]; 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.

  • Email signature — drafts end on the last sentence (no hand-written sign-off from the LLM); backend NoxGhlActionService._send deterministically appends the tenant signature (rich HTML from the Quill editor, or legacy plain text) if the body doesn't already contain it. The setting moved from Agent K settings to Nox settings (views/settings/nox/Index.vue, email_signature).
  • Cancelled GHL appointments — cancels are mirrored onto the booking copies (status: 'cancelled' + cancelled_at on user_sessions.bookings[] / person_profiles), so Nox stops reporting them; reschedules sync by ghl_appointment_id. Requires the AppointmentUpdate/Delete webhook subscription — verify it on the GHL app.

Settings-by-chat (Nox config)​

Nox can read and change tenant settings. The registry lives in ms-ai src/knox-agent/config-registry/; the truth about fields lives in backend.

  • Operation shape (config-operation.types.ts): id (must equal the backend op), kind (set | invoke | read | blocked), domain (14 values), label, aliases[] (the retrieval surface), fields[], riskTier (safe | confirm | human_only), voiceSafe, reversible, requiredEntitlement, requiredRole, blockedReason / navigateTo, requiresSync. Fields carry longText (forces text_edits) and voiceCodec: 'schedule' — the delta codec for working hours ("Saturday off; Monday 08:00-18:00": unmentioned days keep their hours, the server merges). 56 ops across 12 files (19 blocked, 9 invoke, ~28 set). The header comment's "211 operations" is the portal surface, not the registry size.
  • Backend owns field truth. catalog-resolver.ts resolves every set op against backend-catalog.json (93 company + 13 user fields over 30 ops). A declared field the backend doesn't whitelist fails boot; a backend field nobody declared is included as-is; an undeclared backend op is auto-registered voice-unsafe/confirm. Regenerate the snapshot with npm run nox:catalog:sync; at runtime GET /internal/nox/config/catalog (internalNoxConfigRoutes.js) is polled every 5 min and a failed refresh keeps the current registry.
  • Retrieval is lexical on purpose (search()): IDF-weighted tokens, alias containment bonus, an evidence gate (≥2 distinct tokens, a unique token, or a verbatim alias) and a strong flag that turns weak matches into "did you mean?". Possessive pronouns are not stopwords — they disambiguate org vs user scope.
  • Apply flow (knox-config-apply.tool.ts): the op must exist; a real apply needs a preview_token from a dry run bound to (company, op, exact values), single-use and Redis-backed (knox:config:preview:<token>, 2c422a9d0) so it redeems on any pod; human_only / blocked refused in code. Backend applies a field-level CAS — every change carries the before it was previewed against; mismatch → 409 conflicts[] → the tool reports status: 'conflict' ("Someone changed this setting while you were confirming"). Effective values are read back from the DB, never echoed; partial, mismatched, and sync_pending are distinct honesty states. The feature_disabled branch (0da8bf7ee) was deleted with the per-company gate (2f15c50f8).
  • Revert + audit: revert_audit_id reads the prior knox_action_audit row and re-applies its stored before. auditCritical (243adfcba) makes audit writes best-effort except for knox_config_apply, whose row is load-bearing — without it the admin gets an undo that can't work. suppressed_reason: 'duplicate' | 'concurrent' was added and dedup lookups degrade to the Redis claim on DB failure.
  • Authorization mirrors the portal, not a role hierarchy. backend/app/lib/noxConfigPermissions.js is an exact port of the frontend memberHasPermission over the 16 member flags, with a domain→flag table (org/funnel/onboarding → settings.organization, widget → settings.widget, calls → settings.calls, knowledge/agents → settings.ai, integrations → settings.integrations, access → users.update) and per-op overrides for team/branch create/delete. Flags gate reads too — read and navigateHint refuse without the flag. (_authorize no longer checks a company flag.) ai_agent_authentication* keys sit in noxConfigFieldMap.js FORBIDDEN_PREFIXES so Nox can never write them.
  • Owner notification — _notifyOwnerOfMemberChange fires a low-priority in-app "Nox changed a setting" to company.user_id when a non-owner drove the write; fire-and-forget.
  • Navigation hints — POST /internal/nox/config/navigate-hint, socket-only to the acting user's own sessions; the destination is deterministic from navigate-routes.ts (routeForOp: op navigateTo → op sub-page → domain landing), never model-authored. Apply emits a hint too, because the prompt calls describe once per request. Frontend listens on nox-config-applied, nox-user-config-applied, nox-config-navigate (AppLayout.vue), ignores same-page hints, and validates the path.
  • Card contract — action_type: 'nox_config' → KnoxConfigCard.vue: per-field before → after (never raw JSON), toned applied / blocked / conflict, explicit copy for sync_pending, partial (+ mismatched[]).

Morning Standup (P9) and the task lifecycle​

Retired in the UI (2026-10-29). The Nox Live Standup pill is hidden (frontend/src/components/knox/live/legacyStandup.js LEGACY_STANDUP_ENABLED = false; flip it to bring the mode back). The v2 morning day plan replaced it. The task model, /knox/actions/* API, StandupRunLifecycleJob and EveningRecapJob below are still deployed — the task queue is the scheduled-action queue every Nox call/text/ reminder uses. Since backend d99b13fa9 (16 Nov) reminder and standup pushes go only to the person who set them (lib/noxRecipient.js noxRowRecipient: created_by user:<id> → payload.admin_user_id → the admin in standup:<co>:<admin>:<day>; no recipient = inbox only, no push).

Plan docs: NOX_STANDUP_PLAN.md, nox-standup-scope-v0.2.md, NOX_LIVE_CANVAS_PLAN.md (repo root).

  • Agent — agents/knox-standup.agent.ts, routed by dto.mode === 'standup' and never by intent (handles = ['*']); allowlist STANDUP_TOOL_NAMES (standup tools + person lookup, crm, visitor profile, list scheduled, brief offers, visitor watch), maxSteps: 10, maxOutputTokens: 400.
  • Run identity — runIdFor() = standup:<company>:<admin>:<YYYY-MM-DD in admin tz>: one run per admin per local day across chat and voice, deliberately not thread-keyed (turn 1 of a fresh thread has no conversation_id, which split runs and wiped the canvas list). No run table — transcripts stay in knox_agent_conversations, utterance_ref links a task to its clause; reference state (presented list / mentions / last_task / acted) is Redis knox:run-state: with a 2h TTL (services/knox-run-state.store.ts).
  • ScheduledNoxActionModel grew into the task queue. Kinds: ai_call, sms, email, stage_move, note, enrich, reminder. Statuses: pending_confirm → scheduled → fired → done, plus cancelled, failed, expired, and blocked (a dependency died — blockDependents(id, cause) with dependency_failed | cancelled | expired). Standup fields: run_id, depends_on[], condition {if_no_reply_by}, attempts/max_attempts, created_from, utterance_ref, result, override, advisory {reason, overridable}, requires_approval, expires_at.
  • Draft-then-execute (cb251f62b, 021fc0846): bodies exist before the go; time-windowed irreversible tasks die 4h past their window; a second instruction for the same run+person+channel merges into one task and the merge must be stated at readback. knox_confirm_run without confirmed returns readback data + live_now (the live-visitor exception: run_immediately releases one task alone and kicks the executor but never bypasses a requires_approval hold); with confirmed: true it expires stale tasks and re-runs the outbound gates, returning expired[] and gate_blocked[] rather than failing silently later. StandupRunLifecycleJob (10-min tick) sends one "still waiting on your go" ping per run at 60 min and expires at company-local end of day. EveningRecapJob runs 17:30 company-local, once a day, scoped to companies with a run_id in the last 36h.
  • Tenant API (89679bd7d, NoxActionUserController): BOOKABLE_KINDS = all seven; POST /knox/actions/schedule-call books any kind (CRM kinds resolve their contact at booking time), PATCH /knox/actions/scheduled/:id reschedules/rewords/retargets (status filter is the guard), POST …/:id/cancel, POST …/:id/approve (releases a held task), GET /knox/actions/scheduled (+ by-call-sids, now carrying call_status / call_outcome / duration; ?id= returns one task of any kind/status so the Chats ?scheduled= pane can reopen it; sort=desc for history lists), GET /knox/contacts/search, GET /knox/crm/pipelines. Internal: /internal/knox/tasks, /tasks/batch, /tasks/confirm, /tasks/live-now. The frontend ScheduleCallDialog sends ai_call as kind: undefined (the backend default). GET /knox/brief (knoxBriefUserRoutes.js, passport) serves the mobile app's native brief.

Scheduled-action queue​

544ab4fc1 (2026-09-24) replaced the 5-minute ScheduledNoxActionJob cron tick (up to 5 min late):

  • app/services/ScheduledActionQueueService.js — BullMQ queue scheduled-nox-actions, loaded in hooks.js as global.scheduledActions when Redis is configured; the worker runs in every process (API pods and schedular), concurrency 5, shown in Bull Board. Each task is a delayed job with jobId = <task _id>-<scheduled_at ms>, so re-adding is a no-op. _process waits out an early arrival under 60 s (Redis vs pod clock), calls ScheduledNoxActionJob.run({ id }) (its atomic scheduled → fired claim guards duplicates), then re-enqueues if the task came back scheduled at a new time (deferred or retried). BullMQ attempts: 1 — retries are the task's own max_attempts.
  • ScheduledNoxActionEnqueueJob — schedular cron every minute; only queues rows with status: 'scheduled' and scheduled_at <= now + 5 min (batch 1000). Without Redis it falls back to firing due rows directly. "Now" work (live-visitor calls, approvals, send-now) is queued with no delay via ScheduledNoxActionJob.fireSoon.
  • Quiet hours — a fail-closed task whose contact had no timezone was always "quiet", deferred to 9am company time and re-deferred forever. Contactless targets are now judged in the recipient's zone from the number (phoneNumberToTimezone, then the company zone) and deferred to that zone's morning.
  • Reminders (2f087c1cb) — kind: 'reminder' fired, then failed schema validation because nox-reminder wasn't a notification type, so none was ever delivered. NotificationHelper.NOTIFICATION_TYPES.NOX_REMINDER, push tier 1 (cap-exempt; still quiet-hours gated), group other, title "Reminder".
  • Sent texts keep their words (c9ee8c399) — a fired SMS stores result.body (what the SMS agent actually wrote — for an AI text it existed nowhere before) and result.from (sending number). Agent K texts/calls carry payload.lead_action_id. ms-communication b08c7fc names outbound calls from this: InboundOutboundCallController._leadsFor looks up scheduled_nox_actions by call_sid and attaches lead { name, company, lead_action_id } to list/show rows (the call record only holds the number).
  • Why a time moved — frontend components/scheduledText.js textMoved() maps the task's error: quiet_hours_deferred (+ requested_at "moved from"), cooldown_deferred (45-min gap after the last message to the contact), call_concurrency_deferred, and a retry (attempts > 0) with the failure via automationReason. Shown in the SMS agent's Scheduled tab, the Chats Scheduled list, and ScheduledTextDetail.vue.

Deploy note: restart API pods and schedular; no migration — the first sweep queues whatever is due.

Nox Live canvas contract​

  • Per-turn action registry — KnoxActionRegistry (MAX_PROPOSED_ACTIONS_PER_TURN = 1, dedupe by URL, ids A<n>). Voice keeps seed 1 and round-trips nextId through its Redis snapshot; chat seeds from a timestamp (fa501aaff) because a fresh registry per turn minted A1 every time — the 2026-09 prod bug where navigation fired once per conversation and never again. beginTurn() clears actions but keeps nextId monotonic.
  • Server-declared cards (services/knox-canvas.ts canvasForTool()): knox_daily_brief, knox_funnel, knox_crm, knox_recent_bookings map to typed kinds priorities, stage_contacts, meetings, pipelines, opportunities; unmapped tools fall back to frontend inference. MAX_ROWS = 8, STAGE_CARD_MAX_ROWS = 10.
  • Ordinal contract — stageCardEntries() is the exact rendered slice, and knox_crm registers that same slice as the run's presented list (skipped for single-contact lookups), so "call 1 and 3" resolves against what the admin sees; CRM rows key run-state identity by ghl_contact_id.
  • Append-only + promotion — frontend/src/components/knox/live/canvasOrder.js upsertInto(): insert new, upsert by key, and a card a live tool call refreshed moves to the end; replays and background polls pass promote: false so the canvas doesn't rearrange itself while nobody is talking about it. Once-watchers arm with expires_at = the admin's next local midnight (tzDayWindow); recurring watchers stand.

Activity history & threads​

  • Backend NoxActivityController (app/routes/noxActivityRoutes.js): GET /nox/activity, …/export (CSV), …/report (JWT-guarded data for the client-rendered/printed report — the tokenized public share link and its NoxReportTokenModel were removed; no public links). On for every company since 2026-09-25 (the nox_activity_enabled gate and its "not enabled" screen were removed). Merges three producers chronologically: Mongo lead_lifecycle_events, Mongo nox_actions, and ms-ai Postgres knox_action_events via GET /internal/knox/action-events (knox-ghl-webhook.controller.ts; nox_write rows skipped there — nox_actions is authoritative).
  • White-label (b5ce7ec13 / frontend 8fe0e96c / ms-ai 1c91cbd53): the CSV export rewrites Nox / Agent K to the agency's nox_name / agent_k_name server-side (_rebrand); the timeline and report run events through rebrandNoxDeep. nox_action rows (the message exactly as the lead got it) are never rewritten. Vendor wording is gone from summaries: Lead pushed to CRM, step label push to CRM, ms-ai knox-ghl-sync.service.ts writes CRM automation: … (legacy GHL automation: rows are rewritten on read), and summary-less ms-ai events fall back to the humanised action_kind, never <source>: <kind>. CSV filename activity-<date>.csv. The report header shows the agency logo on a useLogoBackdrop box with print-color-adjust: exact (the white default logo vanished on print).
  • Tenant thread reads on ms-ai: GET /knox-agent/conversations and GET /knox-agent/conversations/:threadId.
  • Session narration: ms-ai GET /internal/recording/narration (recording-api.controller.ts; narration prose lives only in ms-ai Postgres) + backend proxy GET /user-session/:_id/narration.

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. The dashboard briefing strip was removed — the brief lives on the Nox surfaces (badge + email), and the per-user auto-play preference gates spoken playback. The engine also emits conversation-signal cards (rank 2.5, max 2 per brief) from GET /internal/knox/conversation-signals — positive outcomes ("chat captured a lead") as win cards, negative as needs-a-look; knox_aggregate gained the matching recent_conversations metric.

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.

Presence is a Redis heartbeat, not a DB timestamp: backend app/lib/sessionPresence.js reads heartbeat_status:<session> (widget heartbeat, 5-min TTL; falls back to the durable activity_status mirror) — this replaced nox_live_at. 'active' = tab focused (widget will render); 'away' = connected but hidden, present-but-not-deliverable.

Nox Live​

Full-screen surface (frontend/src/components/knox/NoxLive.vue, mounted from AppLayout.vue), redesigned for the v3 launch (90536353): a dark voice area on the left, and on the right the Today home (NoxToday.vue — tiles, starters from noxStarters.js, today's plan) that turns into the canvas once results arrive. The launcher bubble and Cmd/Ctrl+K open the docked window (KnoxAssistant.vue, NoxHomeView.vue with Call / Chat); Nox Live opens from its expand button. Escape peels one layer at a time and never ends a call. 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. See the canvas contract for ordering and ids. Routes went brand-neutral with the old paths as aliases (/settings/assistant, /settings/funnel, /activity); document.title swaps \bNox\b for the white-label name at the single router guard.

Prompt caching​

61cc60517 (2026-09-16): the Anthropic cache marker never reached the API — providerOptions.anthropic.cacheControl at the streamText/generateText call level serialises as an ignored top-level cache_control; it only lands on the system message's own providerOptions. And the marked prefix must be stable: composeSystemPrompt is now stable instructions only, and a perTurnContext() hook carries everything that moves (clock, page, intent, memory recall, referenced entities) as a second, unmarked system block. Coverage: analytics 97%, config 99%, action 93%, generalist 87%. The ~4.8k-token intent-classifier prompt is cached too; markers on prompts under Anthropic's 1024-token minimum (knox-signals, quality-scorer, recording-api) were removed. knox-prompt-caching.spec.ts asserts the wire shape and a byte-identical cached block across a real second turn for all 8 agents. Same commit cut the ms-ai body limit 2gb → 20mb.

Knowledge grounding​

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

Voice​

Current architecture (one brain: the voice agent delegates to v2 jobs with nox_delegate; job inbox, server-written reports, call-backs, rating, screen sharing) is on Voice Nox. The notes below are the pre-v2 history that still applies to the session plumbing.

Nox also has a voice mode (Knox Voice, src/knox-voice/) on ElevenLabs. A voice call continues the shared Nox conversation (the frontend sends recent turns; knox-voice.service.ts injects a continuity line). Hygiene fixes (2026-07): one spoken acknowledgement per user turn (not one per tool call); spelled-out letters win over the STT rendition when searching names ("N-E-C-O"); post-call persistence strips leaked <think> tags (cleanAgentMessage, incl. orphan </think>); id fabrication is rejected — session/profile tools return an explicit "id may be invented" not-found note and error envelopes are structured so the model reports failure honestly instead of inventing data. 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; KnoxVoiceService also takes a per-session voice_id). The agency's Agent K name (ded448b83) rides the admin context as agentKName (backend agent_k_name, default "Agent K"): chat gets a prompt section, voice a per-call line (no ElevenLabs re-sync), tool-status labels and the daily brief rename both names in one rebrandNamesDeep pass, and voice brief/standup decks write the names into the template copy so a rename never runs over lead or company names. See ms-ai.

2026-08/09 voice hardening:

  • No tool call fails silently (9f31f70e3 + fb249afed, 55cde823c, cd3b9a893): assertVoiceCallable() runs in agent sync over every advertised schema — a nested object / object-array throws the sync instead of shipping an unfillable tool; the standup allowlist is enforced in the tool webhook (KnoxVoiceToolsService.invoke) because one ElevenLabs agent holds every tool; post-call marks a server-side tool with no execution/result/latency as error "Never executed" (it used to persist as ok); tool-status labels ship on the signed-URL response. Typed text during a live call goes into the call.
  • Voice LLM — PROD KNOX_VOICE_LLM is claude-sonnet-5-5 (flux 56c5c72c; briefly claude-haiku-4-5), the code default since ms-ai f7e6a053e. It used to be custom-llm (Z.ai GLM via the ElevenLabs custom-LLM path, see Telephony); knox-agent-sync.service.ts still errors loudly if it's custom-llm but the agent has no custom-LLM block.
  • Dictated times resolve in the admin's zone, never as a bare instant (182d8f925); a ringing call is not a failed one and a number already ringing is never redialled (ead1ca7dc / backend ccd799a94).

Push notifications​

Backend e5ed166bb (15 Nov): NotificationHelper.NOX_ALERT_TYPES (nox-reminder, nox-standup-nogo, nox-callback) push by default unless quiet or priority low; pushData carries a deep-link route (nox_thread > nox_run > nox_task > contact > nox_inbox; call-backs always nox_callback) and lock-screen-safe push_title / push_body. nox-standup-nogo joined NOTIFICATION_TYPES (the enum used to reject it). ScheduledNoxActionJob and StandupRunLifecycleJob set send_push_notification: true. Time zone for the push gate and NoxAvailabilityController: user → company → Pacific/Auckland (lib/adminTimezone.js). Call-back push: see Voice Nox.