Skip to main content

Nox v2 Engine

Audience: Engineering · QA · Support · Where in app: every Nox chat turn, voice hand-over, and proactive run · Plan availability: every company (KNOX_V2_DEFAULT: 'on' in PROD and DEV)

Since the 2026-11-02 launch ("NOX v3 (upgraded v2)", ms-ai 35909ce99 / backend 9fa0694a7 / frontend 7259763b) Nox runs on the knox-v2 engine in ms-ai/src/knox-v2/ (~38k lines). The v1 pipeline described in What is Nox (intent classifier → one specialist sub-agent) is still live code and is the fallback: the browser checks GET /knox-v2/status every turn (cached 60s, frontend/src/repositories/Knox/index.js) and uses /knox-v2/ask when it returns true, /knox-agent/ask otherwise or when the check fails. v2 still borrows v1's intent classifier (bridge.classifier) and its knox_* tools (via adapter/tool.adapter.ts).

Gating​

  • KNOX_V2_DEFAULT (flags/knox-v2-flag.service.ts, code default off) applies to every company without a row in knox_v2_company_flags (company_id, enabled, mode live|shadow — shadow counts as off, updated_by). A row always wins, so enabled=false forces v1 for one company. Cached 30s. Super-admin flip: PUT /knox-v2/admin/companies/:companyId/flag.
  • NOX_ONLY_COMPANY_IDS and the src/core/nox-maintenance interceptor (the production-test allowlist + "Nox is being upgraded" screen) were added and removed inside the launch week (ms-ai 8ee76dba0, frontend 44cd1451, flux 3a54d4d3, 2026-11-03).
  • KNOX_V2_VOICE_AUGMENT is dead: ms-ai 4bbd15677 removed the boot-time augment; the voice sync now always writes the v2-only tool set. DEV still sets the env var; nothing reads it.

Request flow​

  1. Start. POST /knox-v2/ask (JWT; 403 without company_id) inserts a knox_v2_runs row and enqueues BullMQ knoxV2RunQueue (jobId = run id, 2 attempts, 2s backoff; resume after a park uses resume:<parkId>). The response streams SSE; GET /knox-v2/runs/:id/events?after= replays the ledger and then streams live, so a disconnect never stops a run (10s heartbeat).
  2. Worker. run/knox-v2-run.processor.ts, concurrency 4 per process, wraps each job in runWithActivity so usage rows carry the run's wallet activity. A retry resumes from the task + event ledger.
  3. Orchestrator (orchestrator/knox-v2-orchestrator.service.ts): load context → classify → plan → researchers in parallel → writers one at a time → synthesize. Every event is written to knox_v2_events first, then published on Redis knox_v2_run:<runId>.
  4. Plans made in code, not by the planner (admin-started runs only): plan questions, code lookups, small talk ("Hi" plans nothing), "cancel job", pasted text, quickLookupPlan (one researcher with its topic's read tools for a plain own-data question — orchestrator/quick-lookup.ts), and bookkeepingPlan (staff / customer / skip / rule requests, the onboarding setup chain).
  5. Planner (orchestrator/planner.ts planTurn): ≤16 researchers, ≤4 writers, ≤24 tasks, 3000 output tokens; workers run KNOX_V2_PARALLEL at a time (default 8, max 16). Approved product notes ride in its context.
  6. Subagents (agents/definitions.ts, agents/subagent-runner.ts): researcher — read-only tools, model role knox_v2_research, 6 steps, 700 output tokens, ≤12 tools, rejected if it made no tool call; writer — the only kind that changes things, model role chat, runs serially. Neither can talk to the admin directly (writers use ask_admin) or spawn agents.
  7. Synthesis and the claim checker before the reply goes out.

Admin interaction mid-run: POST /knox-v2/runs/:id/confirm | input | screen-consent | screen | cancel, GET runs/:id/tasks. A run waiting on a card or question parks (knox_v2_park, 24h TTL, tool+args fingerprint) and frees the worker; trigger runs wait KNOX_V2_PARK_GRACE_MS (5s) in-job first; expired parks resume as "declined".

Run state and budgets​

  • Per-run memo in Redis (core/run-memo.ts, moved from in-process Maps in 3e0abfb4c so multi-pod runs agree): knox_v2_memo:<key>, 25h TTL, memory fallback if Redis fails — receipts:<run>, sends:<run>, notes_reads:<run>, built:<run>, auto_target:<run>, auto_prep:<hash>, auto_changes:<company>. Control keys: knox_v2_control:<run>, knox_v2_decision:<run>:<task> (15 min), knox_v2_screen:<run>:<req> (120s), knox_v2_cancel:<run>, knox_v2_inputreq:<run>:<req>, knox_v2_secret:<run>:<ref>.
  • Run governor (core/run-governor.ts): per run 180s active time (paused while waiting on the admin), 40 tool calls, 5 writes, $0.50, 2 identical calls, 6 retries, 1 replan; cost ceiling by kind (chat 0.5, standup 0.3, weekly_review 0.6, event_batch 0.15, first_login 0.2, adoption_review 0.2); per worker 15 tool calls / 3 writes (8 tool calls for a researcher feeding a writer). Model-call timeouts (core/call-timeout.ts): planner 60s, worker 150s, synthesis 60s, action checker 20s, claim checker 45s.
  • Effects / saga / undo: anything that costs money or reaches a person is recorded in knox_v2_run_effects; an atomic plan rolls back earlier writes newest-first on failure (core/saga.ts, guard/legacy-compensation.ts reverts tags and pipeline moves) and says what couldn't be undone; prior versions are kept 5 days in knox_v2_undo_records.
  • Autonomy (run/knox-v2-confirm-prefs.service.ts, autonomy/policy.ts): default auto — reversible changes are applied and reported with Undo; anything that reaches a person or can't be undone is always the admin's decision. KNOX_V2_AUTONOMY=ask forces cards for everyone; "don't ask again" rows live in knox_v2_confirm_prefs (GET|PUT /knox-v2/autonomy, GET|DELETE confirm-prefs). Agent-coach and Q&A edits always show a card.

Guards​

GuardFileWhat it does
Claim checkerguard/claim-checker.service.tsFresh-context check of a Nox-started message against the run's evidence only (hunter model). On timeout the original goes out and the failure is logged.
Send guardguard/send-guard.service.tsCaps Nox's own actions: 10/company/day, 1/recipient/day, 3/recipient/week; calls/texts 08:00–21:00 local; do-not-contact checks. Admin limits in nox_guard_rules, every decision in nox_guard_log. Card-free action on Nox's own judgement needs KNOX_V2_GUARD_JUDGEMENT=on (off).
Action checkerguard/action-checker.service.tsSees only the admin's words, the rules and the proposed action before a card-free outward action; research model; fails closed.
Intended person / recipientguard/intended-person.ts, guard/recipient.tsRefuses a send when another person found in the run fits better; an email address must come from the admin, a tool result or the conversation.
Authorisation / call timeguard/authorisation.ts, guard/call-time.tsMissing "on whose authority" = ask first; a call with no time when the admin named one is refused.
Contact policycontact/contact-policy.ts CONTACT_CAPSReaching the admin: 5 pings/day, 10-min gap, 5 proactive messages/day, 1 Nox-initiated call/day (2 if allowed), 2 recommendation emails/week; meeting prep and booked call-backs exempt. Decisions logged in nox_contact_log.
Jev shadowjev/jev-shadow.service.tsSide-by-side judge for three word-rule decisions — see Platform switches.

Wake mode — whether a proactive moment pops up silently, speaks, or stays in notifications — defaults to quiet since 8540d0caa (9 Nov). It resolves company knox.wake_voice against agency nox_wake_voice / nox_wake_voice_locked (backend/app/lib/noxIdentity.js resolveNoxWakeVoice; a company save returns 403 when locked). See Settings — Nox.

Tools​

Tools are grouped into domains (tools/domains.ts: pipeline, knowledge, agentk, setup, conversations, contact, admin, nox, email, billing, crm_external, product_api, web, agents, automations) — each with one code-owned "use for / not for" line the planner reads. There are 48 native tools in tools/native/ plus the adapted v1 knox_* tools. See Tools.

Triggers and the day plan​

trigger/nox-scheduler.service.ts ticks every minute on one pod (Redis lock nox_scheduler_tick_lock; NOX_SCHEDULER=off disables):

  1. Due schedules — per-admin nox_schedule rows in local time. The standup schedule starts the day plan hunt at HUNT_AT = 05:30 local (NOX_DAY_PLAN=off reverts to the standup run); weekly_review (Mondays, time from the check-ins card); adoption_review on cadence_days.
  2. Events — new nox_event rows become one event_batch run per company (a "moment" gets its own run; some kinds go straight to the admin). Budget NOX_EVENT_RUNS_PER_DAY (20) and NOX_EVENT_SPEND_PER_DAY_USD ($1). Intake (POST /knox-v2/internal/events, trigger/nox-event-intake.service.ts) is idempotent on (company, source, source_event_id); GHL webhooks map via trigger/ghl-events.ts and skip Nox's own writes. The backend retries undelivered events from nox_event_outbox (NoxEventOutboxJob, every minute, backoff) and feeds Agent K activity in from NoxAgentKEventsJob (cursor nox_agentk_events_cursor in settings).
  3. Email queue — emailQueue.sendDue (below).
  4. Expired parks.

nox-trigger.service.ts turns a trigger into exactly one run (unique company + kind + natural_key in nox_trigger), checks the v2 flag, admin membership, and credits (trigger/credit-preflight.ts; with no credits it skips and tells the admin once per 24h; NOX_PREFLIGHT_CREDITS=off skips the check).

The day plan ("Nox the hunter"). trigger/nox-hunter.service.ts makes one model judgement over pipelines, the funnel, missed meetings, overnight mail and the call agents, after running dormant (weekly — why quiet deals stalled), learn (team chat replies → proposed lessons) and win/loss (every 7 days, ≥3 deals) in parallel. Nothing is sent to anyone. The ranked plan and spoken rundown are held in backend Mongo nox_days / nox_plan_items (NoxDayPlanController, /internal/knox/day/*) until the admin opens the app: POST /knox-v2/day/start (first open) starts the hunt if no plan exists and re-claims one stuck in "preparing" > 15 min. POST /knox-v2/day/redo → backend POST /internal/knox/day/reset is the tenant's Run my morning brief now. The plan also tops the morning email (backend/app/lib/noxPlanEmail.js; see Daily Brief). ensureStandup creates the per-admin 09:00 check-in schedule on first login (internal/triggers/first-login), on day/start, or when an event names an admin without one.

Upgrade intro. NoxDayPlanController sends the one-time "I've had a big upgrade" intro only to users created before NOX_V3_LAUNCH = 2026-11-01T00:00+13:00 who lack nox_rapport.v3_intro_at (f7aa072e6).

Nox email queue. nox_email_queue (TypeORM entity + repository, 43ee743c8; trigger/nox-email-queue.service.ts) holds group emails until the recipients' quiet hours end or the admin's named time; rows claimed FOR UPDATE SKIP LOCKED, 40 per tick, give up after 3 attempts or 36h, re-claimed if stuck > 10 min. Results of group sends are reported back by backend NoxGroupResultsJob. Not to be confused with backend NOX_EMAIL_KEY (AES-256-GCM encryption of business-email bodies at rest, backend/app/lib/noxEmailCrypto.js) — set in the backend and schedular secrets.

Other crons: run/knox-v2-reconcile.job.ts (17 * * * *, purges undo records + reconciles cost, KNOX_V2_RECONCILE=off), voice/nox-call-back.sweep.ts (every 30s, see Voice), quality check (7 * * * *). Backend: NoxMeetingPrepJob (every 2 min — meeting_soon event → spoken brief ~10 min before a meeting), NoxCallRetryJob (every 15 min, once per company-local day — the "call the voicemails again tomorrow at 10" standing rule), NoxLessonResultsJob, NoxEmailHealthJob (Unipile mailbox health).

Data​

ms-ai Postgres (src/knox-v2/entities/*.entity.ts unless noted):

TablePurpose
knox_v2_company_flagsPer-company v2 on/off + mode
knox_v2_runsOne turn or trigger run: request (incl. voice_call_id, job_ref, quick_only, call_back), plan, status, usage, stamps, told_at
knox_v2_tasks / knox_v2_events / knox_v2_run_notesPlanned work items · append-only event ledger (SSE replay) · notes shared by one run's workers (deleted at run end)
knox_v2_run_effects / knox_v2_undo_recordsWhat a run did that costs money or reaches someone · prior versions (5 days)
knox_v2_park / knox_v2_confirm_prefs / knox_v2_screen_consentPaused cards and questions · "don't ask again" + autonomy · per-admin screen consent
knox_v2_escalationsHand-offs to humans
nox_trigger / nox_schedule / nox_event / nox_email_queueExactly-once proactive runs · per-admin wake time + cadence · events Nox may judge · delayed group emails
nox_contact_log / nox_guard_rules / nox_guard_logEvery reach-the-admin decision · enforced admin limits · every guard decision
nox_rule (+ nox_rule_event) / nox_case (+ nox_case_event) / nox_goalRulebook in the admin's words · matters Nox is following · goals
nox_standup_item / nox_thread_summary / nox_business_profile / nox_conversation_outcomeStandup items + reactions · rolling summary of older turns · versioned business profile · what happened after conversations
nox_product_notesLearned "where is X" notes; only approved ones reach Nox
nox_jev_shadow (jev/), nox_quality_runs (quality/)Jev shadow judgements · daily quality checks

Backend Mongo (new in the window): nox_days, nox_plan_items (day plan), nox_rapport (per-user style: call_me, talk rules, greet_listen, v3_intro_at), nox_email_accounts / nox_email_messages (business mailbox; also carry triggered_by), nox_tasks, nox_group_followups, nox_admin_calls, nox_contact_notes, nox_stalls, nox_event_outbox, nox_invoke_keys, nox_suggestion_decisions, nox_agentk_changes, nox_agent_lessons, nox_reply_lessons, nox_sales_lessons, sales_reply_drafts. The backend side of v2 is KnoxV2InternalController + lib/knoxV2NamedQueries.js (~100 /internal/knox/* routes in routes/internalKnoxRoutes.js).

Named queries (GET /internal/knox/query, read by the knox_query tool) include agentk_setup (outreach mode, mailbox routing, auto-push, offer, sending hours, and why Agent K is or isn't emailing — ec176dbb5), leads (Leads Attribution: filters on triggered_by, channel, outcome, when, stage, source — 3483c879f), pipeline_deals, call_agents_report, weekly_numbers, win_loss, speed_to_lead, and ~30 more. Nox's own sends (drafts, calls, SMS, mailbox and group emails) are stamped triggered_by category nox_instructed, shown on the Leads page as "Nox Growth Officer (instructed)" (backend/app/lib/touchAttribution.js).

Billing facts (/internal/knox/billing-facts) carry connection_fees: a connected Nox business mailbox bills like a LinkedIn connection (the admin unipile seat price; wallet lines nox_mailbox_connect / nox_mailbox_renewal, monthly via SalesRepliesMailboxFeeJob — unpaid releases the mailbox and emails the owner; 7b92facf3).

Models and cost​

  • v2 models are knox_ai_models rows resolved by adapter/legacy-bridge.service.ts: role chat (planner, writer, synthesis, standup items, thread summaries), knox_v2_research (researchers, action checker, customer-pick, meeting notes; falls back to chat — set via PUT /knox-v2/admin/research-model), knox_v2_hunter → narration → chat (hunter, dormant, learn, win/loss, claim checker, automation judge). The ids in those rows are prod data (set by runbook SQL in f7e6a053e), not code.
  • Claude Sonnet 5.5 / Haiku 5.5 support + prices landed in f7e6a053e (8 Nov). The voice LLM is KNOX_VOICE_LLM: 'claude-sonnet-5-5' (PROD; was custom-llm, then claude-haiku-4-5); ANTHROPIC_API_KEY is in the PROD ms-ai secret. gpt-4o-mini is hard-coded for web_research, agent_review, agent_coach.
  • Every v2 LLM call writes usage_event / usage_charge (agent knox, external id knoxv2:<run>:<label>:<uuid>; run/knox-v2-cost.service.ts). Aborted calls are estimated and booked to PLATFORM_COMPANY_ID. Wallet activity (core/stamps.ts): a run delegated from a live call (voice_call_id) bills to nox_voice:<callId> ("Nox voice call"), chat to nox_chat:<thread>, triggers to nox_standup / nox_event / nox_review / nox_intro / nox_adoption ("Nox: Morning Standup", "Nox: Something Happened", "Nox: Weekly Review", "Nox: First Hello", "Nox: A Tip For Your Setup" — backend/app/lib/activityLabels.js).

Platform switches and env flags​

Three platform switches moved from env vars to Admin → Settings → Feature Flags (backend settings collection, SettingModel {key, value}; written via POST /settings / PUT /settings/:id, super-admin only). A switch is on only when value === true; off until set. The backend reads them through app/lib/platformSwitch.js switchOn(key); ms-ai reads GET /internal/knox/platform-flags (KnoxV2InternalController.platformFlags) via flags/nox-platform-flags.service.ts. Both sides cache 60s and keep the last answer when the read fails (off before the first answer).

KeyLabelReplacesEffect
nox_quality_check_enabledNox daily quality checkNOX_QUALITY_ENABLED (ms-ai)Daily grading of production Nox calls and chats
nox_voice_server_reportsServer-written call reportsNOX_VOICE_SERVER_REPORTS (ms-ai)ms-ai writes a call's job progress/result reports (Voice); next call
agency_client_ticketsAgency client ticketsOPS_AGENCY_CLIENT_TICKETS (backend)Managed clients' tickets and Nox hand-offs go to their agency

Jev shadow mode stays an env flag: NOX_JEV_SHADOW=on and TYPESAFE_API_KEY (ms-ai; PROD configmap sets on, the key is in Apps/PROD/ms-ai/secret.sops.yaml). Nox's word rules keep deciding; Jev (https://api.typesafe.ai/v1/systemone, model jev-latest, 4s timeout) judges the same text on the side for same_request, day_overview and claims_done, fire-and-forget, after scrubbing (jev/jev-scrub.ts: emails/phones/URLs → placeholders, names → Person1…). Both answers land in nox_jev_shadow. The frontend asks GET /knox-v2/jev-shadow and posts its duplicate-guard and done-claim decisions to POST /knox-v2/jev-shadow only when it's on. Report: ms-ai/scripts/jev-shadow-report.ts [days=7] (read-only SELECT, local only).

Quality, learning and hand-offs​

  • Daily quality check (quality/nox-quality.service.ts, moved from a Mac launchd job on 9 Nov): hourly tick, runs once per NZ day after 05:00 NZ on one replica (PG advisory lock 4823201) when nox_quality_check_enabled is on. Window = since the last run (12h–168h). Grades ElevenLabs voice calls (ELEVENLABS_API_KEY) and v2 chats (knox_v2_runs/tasks/events): transcript audit, outcome grade by failure type with friction, and a morning note from NOX_GRADE_MODEL (default claude-sonnet-5-5, ANTHROPIC_API_KEY). A conversation graded once is not graded again. Stored in nox_quality_runs; super-admin endpoints knox-agent/admin/quality/runs, runs/:id, runs/:id/export (transcripts + engine runs + tool calls), POST run (202). UI: Nox / Knox Admin → Quality.
  • Product notes. learning/product-learning.ts merges findings from calls into nox_product_notes; resolved support tickets become candidates too (backend OpsTicketService.learnFromResolved → POST /knox-v2/internal/product-notes/from-ticket, team-handled tickets with both customer and team messages, last 12; key ticket|KK-n). Only approved notes (super-admin, Admin → Knox → App Learning) reach Nox: up to 60, cached 5 min (learning/approved-notes.ts), fed to the planner, claim checker, every get_page_guide result and the voice brief.
  • Hand-offs open a support ticket (ms-ai 76da7c910, backend 4a706284f). tools/native/nox-escalate.tool.ts → POST /internal/knox/escalations → an ops ticket with channel: 'nox' (context {source:'nox', reason, urgency, reference, thread_id}; billing_dispute/refund → billing, account_deletion → account, high urgency → P2). It goes to the agency when agency_client_tickets is on, the company is a managed client, and the agency's client_support.mode is agency; otherwise to the support queue. Nox quotes the ticket number (null when agency-handled) and never names the agency or Knock Knock. Ticket-create failure falls back to email (NOX_ESCALATION_EMAIL, default support). Rows also land in knox_v2_escalations. cases/ is only Nox's own bookkeeping of matters it follows.
  • Also in learning/: discovery.ts (getting-to-know-the-business questions on calls), reflector.ts (counts patterns into proposed rules, no model call), nox-business-profile.service.ts.

Env vars (ms-ai unless noted)​

VarMeaningDefault
KNOX_V2_DEFAULTv2 for companies with no flag rowoff (PROD/DEV on)
KNOX_V2_AUTONOMYask forces cards for everyoneauto
KNOX_V2_GUARD_JUDGEMENTon allows card-free action on Nox's own judgementoff
KNOX_V2_PARK_GRACE_MSTrigger run's in-job wait before parking5000
KNOX_V2_PARALLELWorkers at once8 (max 16)
KNOX_V2_BUDGET_*, KNOX_V2_BUDGET_COST_USD_<KIND>, KNOX_V2_WORKER_*, KNOX_V2_FEEDER_TOOL_CALLS, KNOX_V2_TIMEOUT_*_MSRun governor budgets and model timeoutssee above
KNOX_V2_RECONCILEHourly cost reconcile + undo purgeon
KNOX_ENV / KNOX_ENV_GUARDBlocks boot on mixed local/staging/prod targets (DEV sets staging) / off overridesunset = guard off
NOX_SCHEDULER, NOX_DAY_PLAN, NOX_PREFLIGHT_CREDITS, NOX_CALL_BACK_SWEEPKill switcheson
NOX_EVENT_RUNS_PER_DAY / NOX_EVENT_SPEND_PER_DAY_USDEvent budget per company20 / 1
NOX_WEB_RESEARCH_DAILY_CAPWeb lookups per company per day20
NOX_JEV_SHADOW + TYPESAFE_API_KEYJev shadow modeoff
NOX_GRADE_MODEL, ANTHROPIC_API_KEYQuality grader / morning noteclaude-sonnet-5-5
NOX_SETUP_ACTIONS_ENABLEDSetup actions (screen/abilities.ts)off
BACKEND_BASE_URL / BACKEND_API_KEY, FRONTEND_URLBackend client, dashboard links—
NOX_EMAIL_KEY (backend and schedular secrets)Encrypts business-email bodies at restunset = envelope only
NOX_ESCALATION_EMAIL (backend)Fallback when a hand-off ticket can't be createdsupport address