Skip to main content

Imported from api/docs/PROJECT_SUMMARY.md. Edit source file, then re-run sync.

Nova Platform — Project Summary

Last updated: 2026-03-10

1. What Nova Is​

Nova is an agentic operations assistant for inbox, calendar, and contacts workflows. It accepts natural-language user requests (API and Telegram), plans actions, executes safe read/mutate tools, and keeps auditable run state.

Core product outcomes:

  • answer user inquiries naturally (not command-only)
  • execute real tasks across email/calendar/contacts
  • enforce approvals for mutating operations
  • preserve traceability for every run/step/tool action

2. Current System Architecture​

Runtime model​

  • AgentRuntimeService is the single execution entrypoint for assistant instructions.
  • OrchestratorPlannerService maps instruction -> planned action/tool.
  • AgentToolExecutorService handles admission, approval gates, execution, and persistence.
  • ApprovalService resolves approve/reject and deterministic resume.

Layering (implemented)​

  • Transport: controllers/webhooks/telegram handlers.
  • Application: runtime orchestration + use-case services.
  • Domain: contracts, policies, tool admission modes.
  • Infrastructure: Mongo repositories, MCP gateway/transports, provider adapters.

Persistence model (Mongo)​

  • agent_runs
  • agent_steps
  • tool_executions
  • pending_approvals
  • calendar_events (normalized events + semantic embedding metadata)
  • calendar_action_runs (proposal/confirm/complete lifecycle)

Integrations and protocol path​

  • MCP gateway with connector discovery and invocation.
  • MCP transport adapters:
    • remote HTTP
    • local stdio
  • Runtime calls MCP first for calendar/email/contacts tools; controlled local fallback for unavailable/timeout classes.
  • Telegram approval callbacks are replay-safe with one-time Redis consume tokens.
  • Current production integration mode is OAuth-first for Google:
    • dashboard/telegram connect flow requests Gmail + Calendar scopes via Google OAuth
    • actor-scoped grants and connection sync are the primary path for user email/calendar access
    • GWS CLI/MCP credential-file mode is optional and not required for this OAuth-first path

3. Is This Industry Standard?​

Short answer: yes, with the right caveat.

Implemented patterns are aligned with proven production approaches:

  • orchestrator + sub-agent/collaborator separation
  • policy-based tool admission (auto, approval_required, blocked)
  • repository-owned state writes (auditability + consistency)
  • idempotency keys for mutating resume paths
  • API + chat-channel approval workflows
  • CI quality gates (typecheck, lint, prettier, tests)

Caveat:

  • MCP execution is implemented and operational, but still needs deeper protocol-hardening/E2E breadth before claiming "fully mature" enterprise reliability across all failure modes.

4. What Is Completed​

  • Agent runtime is the primary execution path for assistant instructions.
  • Generic approval API is implemented:
    • GET /v1/agent-runtime/approvals
    • POST /v1/agent-runtime/approvals/:approvalId/approve
    • POST /v1/agent-runtime/approvals/:approvalId/reject
  • Telegram approval callback is generic:
    • approval_confirm:<approvalId>
    • approval_reject:<approvalId>
  • Telegram callbacks enforce:
    • strict payload/ObjectId validation
    • ownership checks
    • distributed throttling
    • one-time replay consume guard
  • Conversational confirmation is supported:
    • natural language yes|confirm|approve|do it|go ahead|proceed|execute it
    • auto-executes only when exactly one pending approval exists
    • returns explicit disambiguation when multiple approvals exist
  • Telegram conversational fallback is natural-language-first:
    • assistant intent fallback now delegates to conversational generation (no static repeated command-style canned response loop).
    • successful chat_response outputs with nextAction=connect_google trigger contextual OAuth guidance in-chat.
  • MCP gateway supports tool discovery + invocation and normalized error categories.
  • Runtime quality gates and unit/integration coverage are active and passing.
  • Infra E2E coverage includes Telegram NL behavior:
    • api/test/telegram-natural-language.e2e-spec.ts (conversation response, connect guidance, /inbox compatibility).
  • Infra critical E2E suite now includes Telegram NL by default and passes with the current baseline.
  • Reprocessing correctness fix:
    • contact-knowledge retry resolves message ID robustly from lean-query results (id or _id) to prevent malformed job IDs.
  • Raw-message linkage correctness fix:
    • raw messages now allow nullable normalizedMessageId during two-phase ingest, then update after normalized message creation.
  • Legacy calendar-specific confirm callback path has been removed from active runtime flow.
  • Calendar resolver supports hybrid retrieval:
    • bounded lexical retrieval
    • vector retrieval (feature-flagged)
    • merged scoring + LLM rerank
    • deterministic fallback when vector path is unavailable
  • Calendar mutations write immutable audit trail events across proposal/confirm/execution.
  • Calendar reads now resolve timezone with fallback chain:
    • user profile timezone
    • runtime/chat context timezone (if provided)
    • workspace settings timezone
    • UTC fallback
  • Chat API now enqueues deterministic async completion jobs (PROCESS_CHAT_MESSAGE) instead of TODO placeholders.
  • Usage quota storage now computes bytes from normalized message attachments + raw payload storage.
  • Workspace invites now attempt immediate email dispatch via active workspace sender with explicit delivery status fallback (queued|no_sender|failed).
  • Production deploy now propagates calendar/telegram replay/perf env vars with deploy-time sanity checks.
  • Source-of-truth env matrix is documented in api/docs/ENVIRONMENT_MATRIX.md.
  • Mailcow/generic inbox ingest is production-wired:
    • managed Mailcow mailbox provisioning creates smtp_generic connections with IMAP credentials.
    • generic IMAP sync now supports both smtp_generic and imap_generic providers.
    • recurring fallback poll keeps inbound inbox sync running for provisioned and user-connected generic inboxes.

5. What Is Not Yet Fully Complete​

  • Full MCP protocol-hardening depth:
    • broader failure-injection integration tests
    • stronger connector runtime config/ops validation in production
  • Final production SLO calibration for perf-gate thresholds in CI (p95 + error rate).
  • Full semantic retrieval rollout operations:
    • Atlas vector index rollout validation
    • embedding backfill completion

6. Strategic Direction (Current)​

Nova is now on the correct architecture path for a real-world agentic system:

  • keep runtime as the single source of execution truth
  • keep MCP as primary integration boundary
  • keep approvals/idempotency mandatory for mutating actions
  • enforce replay-safe confirmations and explicit partial outcomes
  • keep semantic retrieval behind feature flags with deterministic fallback

This is the correct foundation for scaling to multi-agent delegation and richer tool ecosystems without reintroducing legacy intent-switch logic.