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 defaultoff) applies to every company without a row inknox_v2_company_flags(company_id,enabled,modelive|shadow— shadow counts as off,updated_by). A row always wins, soenabled=falseforces v1 for one company. Cached 30s. Super-admin flip:PUT /knox-v2/admin/companies/:companyId/flag.NOX_ONLY_COMPANY_IDSand thesrc/core/nox-maintenanceinterceptor (the production-test allowlist + "Nox is being upgraded" screen) were added and removed inside the launch week (ms-ai8ee76dba0, frontend44cd1451, flux3a54d4d3, 2026-11-03).KNOX_V2_VOICE_AUGMENTis dead: ms-ai4bbd15677removed 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
- Start.
POST /knox-v2/ask(JWT; 403 withoutcompany_id) inserts aknox_v2_runsrow and enqueues BullMQknoxV2RunQueue(jobId = run id, 2 attempts, 2s backoff; resume after a park usesresume:<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). - Worker.
run/knox-v2-run.processor.ts, concurrency 4 per process, wraps each job inrunWithActivityso usage rows carry the run's wallet activity. A retry resumes from the task + event ledger. - Orchestrator (
orchestrator/knox-v2-orchestrator.service.ts): load context → classify → plan → researchers in parallel → writers one at a time → synthesize. Every event is written toknox_v2_eventsfirst, then published on Redisknox_v2_run:<runId>. - 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), andbookkeepingPlan(staff / customer / skip / rule requests, the onboarding setup chain). - Planner (
orchestrator/planner.tsplanTurn): ≤16 researchers, ≤4 writers, ≤24 tasks, 3000 output tokens; workers runKNOX_V2_PARALLELat a time (default 8, max 16). Approved product notes ride in its context. - Subagents (
agents/definitions.ts,agents/subagent-runner.ts): researcher — read-only tools, model roleknox_v2_research, 6 steps, 700 output tokens, ≤12 tools, rejected if it made no tool call; writer — the only kind that changes things, model rolechat, runs serially. Neither can talk to the admin directly (writers useask_admin) or spawn agents. - 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 in3e0abfb4cso 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.tsreverts tags and pipeline moves) and says what couldn't be undone; prior versions are kept 5 days inknox_v2_undo_records. - Autonomy (
run/knox-v2-confirm-prefs.service.ts,autonomy/policy.ts): defaultauto— 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=askforces cards for everyone; "don't ask again" rows live inknox_v2_confirm_prefs(GET|PUT /knox-v2/autonomy,GET|DELETE confirm-prefs). Agent-coach and Q&A edits always show a card.
Guards
| Guard | File | What it does |
|---|---|---|
| Claim checker | guard/claim-checker.service.ts | Fresh-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 guard | guard/send-guard.service.ts | Caps 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 checker | guard/action-checker.service.ts | Sees only the admin's words, the rules and the proposed action before a card-free outward action; research model; fails closed. |
| Intended person / recipient | guard/intended-person.ts, guard/recipient.ts | Refuses 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 time | guard/authorisation.ts, guard/call-time.ts | Missing "on whose authority" = ask first; a call with no time when the admin named one is refused. |
| Contact policy | contact/contact-policy.ts CONTACT_CAPS | Reaching 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 shadow | jev/jev-shadow.service.ts | Side-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):
- Due schedules — per-admin
nox_schedulerows in local time. The standup schedule starts the day plan hunt atHUNT_AT = 05:30local (NOX_DAY_PLAN=offreverts to the standup run);weekly_review(Mondays, time from the check-ins card);adoption_reviewoncadence_days. - Events — new
nox_eventrows become oneevent_batchrun per company (a "moment" gets its own run; some kinds go straight to the admin). BudgetNOX_EVENT_RUNS_PER_DAY(20) andNOX_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 viatrigger/ghl-events.tsand skip Nox's own writes. The backend retries undelivered events fromnox_event_outbox(NoxEventOutboxJob, every minute, backoff) and feeds Agent K activity in fromNoxAgentKEventsJob(cursornox_agentk_events_cursorinsettings). - Email queue —
emailQueue.sendDue(below). - 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):
| Table | Purpose |
|---|---|
knox_v2_company_flags | Per-company v2 on/off + mode |
knox_v2_runs | One 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_notes | Planned 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_records | What a run did that costs money or reaches someone · prior versions (5 days) |
knox_v2_park / knox_v2_confirm_prefs / knox_v2_screen_consent | Paused cards and questions · "don't ask again" + autonomy · per-admin screen consent |
knox_v2_escalations | Hand-offs to humans |
nox_trigger / nox_schedule / nox_event / nox_email_queue | Exactly-once proactive runs · per-admin wake time + cadence · events Nox may judge · delayed group emails |
nox_contact_log / nox_guard_rules / nox_guard_log | Every reach-the-admin decision · enforced admin limits · every guard decision |
nox_rule (+ nox_rule_event) / nox_case (+ nox_case_event) / nox_goal | Rulebook in the admin's words · matters Nox is following · goals |
nox_standup_item / nox_thread_summary / nox_business_profile / nox_conversation_outcome | Standup items + reactions · rolling summary of older turns · versioned business profile · what happened after conversations |
nox_product_notes | Learned "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_modelsrows resolved byadapter/legacy-bridge.service.ts: rolechat(planner, writer, synthesis, standup items, thread summaries),knox_v2_research(researchers, action checker, customer-pick, meeting notes; falls back to chat — set viaPUT /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 inf7e6a053e), not code. - Claude Sonnet 5.5 / Haiku 5.5 support + prices landed in
f7e6a053e(8 Nov). The voice LLM isKNOX_VOICE_LLM: 'claude-sonnet-5-5'(PROD; wascustom-llm, thenclaude-haiku-4-5);ANTHROPIC_API_KEYis in the PROD ms-ai secret.gpt-4o-miniis hard-coded forweb_research,agent_review,agent_coach. - Every v2 LLM call writes
usage_event/usage_charge(agentknox, external idknoxv2:<run>:<label>:<uuid>;run/knox-v2-cost.service.ts). Aborted calls are estimated and booked toPLATFORM_COMPANY_ID. Wallet activity (core/stamps.ts): a run delegated from a live call (voice_call_id) bills tonox_voice:<callId>("Nox voice call"), chat tonox_chat:<thread>, triggers tonox_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).
| Key | Label | Replaces | Effect |
|---|---|---|---|
nox_quality_check_enabled | Nox daily quality check | NOX_QUALITY_ENABLED (ms-ai) | Daily grading of production Nox calls and chats |
nox_voice_server_reports | Server-written call reports | NOX_VOICE_SERVER_REPORTS (ms-ai) | ms-ai writes a call's job progress/result reports (Voice); next call |
agency_client_tickets | Agency client tickets | OPS_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) whennox_quality_check_enabledis 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 fromNOX_GRADE_MODEL(defaultclaude-sonnet-5-5,ANTHROPIC_API_KEY). A conversation graded once is not graded again. Stored innox_quality_runs; super-admin endpointsknox-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.tsmerges findings from calls intonox_product_notes; resolved support tickets become candidates too (backendOpsTicketService.learnFromResolved→POST /knox-v2/internal/product-notes/from-ticket, team-handled tickets with both customer and team messages, last 12; keyticket|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, everyget_page_guideresult and the voice brief. - Hand-offs open a support ticket (ms-ai
76da7c910, backend4a706284f).tools/native/nox-escalate.tool.ts→POST /internal/knox/escalations→ an ops ticket withchannel: 'nox'(context{source:'nox', reason, urgency, reference, thread_id}; billing_dispute/refund →billing, account_deletion →account, high urgency → P2). It goes to the agency whenagency_client_ticketsis on, the company is a managed client, and the agency'sclient_support.modeisagency; 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 inknox_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)
| Var | Meaning | Default |
|---|---|---|
KNOX_V2_DEFAULT | v2 for companies with no flag row | off (PROD/DEV on) |
KNOX_V2_AUTONOMY | ask forces cards for everyone | auto |
KNOX_V2_GUARD_JUDGEMENT | on allows card-free action on Nox's own judgement | off |
KNOX_V2_PARK_GRACE_MS | Trigger run's in-job wait before parking | 5000 |
KNOX_V2_PARALLEL | Workers at once | 8 (max 16) |
KNOX_V2_BUDGET_*, KNOX_V2_BUDGET_COST_USD_<KIND>, KNOX_V2_WORKER_*, KNOX_V2_FEEDER_TOOL_CALLS, KNOX_V2_TIMEOUT_*_MS | Run governor budgets and model timeouts | see above |
KNOX_V2_RECONCILE | Hourly cost reconcile + undo purge | on |
KNOX_ENV / KNOX_ENV_GUARD | Blocks boot on mixed local/staging/prod targets (DEV sets staging) / off overrides | unset = guard off |
NOX_SCHEDULER, NOX_DAY_PLAN, NOX_PREFLIGHT_CREDITS, NOX_CALL_BACK_SWEEP | Kill switches | on |
NOX_EVENT_RUNS_PER_DAY / NOX_EVENT_SPEND_PER_DAY_USD | Event budget per company | 20 / 1 |
NOX_WEB_RESEARCH_DAILY_CAP | Web lookups per company per day | 20 |
NOX_JEV_SHADOW + TYPESAFE_API_KEY | Jev shadow mode | off |
NOX_GRADE_MODEL, ANTHROPIC_API_KEY | Quality grader / morning note | claude-sonnet-5-5 |
NOX_SETUP_ACTIONS_ENABLED | Setup actions (screen/abilities.ts) | off |
BACKEND_BASE_URL / BACKEND_API_KEY, FRONTEND_URL | Backend client, dashboard links | — |
NOX_EMAIL_KEY (backend and schedular secrets) | Encrypts business-email bodies at rest | unset = envelope only |
NOX_ESCALATION_EMAIL (backend) | Fallback when a hand-off ticket can't be created | support address |
Related
- What is Nox · Voice · Tools · Daily Brief
- Nox / Knox Admin Assistant — v1 internals, settings-by-chat, scheduled-action queue, canvas
- Nox / Knox Admin — Quality, App Learning, Conversations
- Settings — Nox · ms-ai