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-13

What Nova Is​

Nova is an agentic operations assistant for inbox, calendar, contacts, and follow-up workflows. It is now organized around task-orchestrated execution: user instructions create or mutate tasks, tasks own lifecycle/thread state, and agent-v2 executes tool-grounded actions.

Runtime Architecture (Current)​

  • Orchestration truth: TaskOrchestratorService
  • Execution kernel collaborator: AgentKernelService (agent-v2, OpenAI Agents SDK)
  • Knowledge read model: KnowledgeHubService (profile/life/contact/task context for orchestration)
  • Task lifecycle and audit state (Mongo):
    • tasks
    • task_thread_entries
    • task_links
    • async_operations
    • task_digests
    • notification_queue_items
    • notification_logs
    • user_notification_settings
  • Kernel run state (Mongo):
    • agent_runs_v2
    • agent_turns_v2
    • agent_tool_calls_v2
    • agent_approvals_v2
    • agent_memory_summaries_v2

Path Matrix (Double-Checked)​

  • POST /v2/agent/runs -> orchestrator-backed execution with backward-compatible response shape plus runMode and task linkage metadata in details.
  • POST /v2/task-orchestrator/runs -> explicit orchestration endpoint.
  • POST /v1/telegram/app/webhook -> Telegram NL routing through orchestrator, with deferred queue handoff for async/timeout-prone instructions.
  • Dashboard chat worker PROCESS_CHAT_MESSAGE -> orchestrator-backed run path.
  • POST /v1/assistants/:id/instruct -> AgentActionsService delegates to orchestrator.

Real-Journey E2E Coverage (Current)​

  • Infra E2E now includes an explicit task-orchestrated journey suite:
    • dashboard chat message -> task/thread/link metadata persistence
    • inbound external reply -> waiting task reconciliation
    • digest generation -> Telegram dispatch + notification queue/log audit
    • digest spam guard -> empty digests suppressed + per-digest and per-content delivery dedupe
    • digest scheduler guard -> user-local window/catch-up + minimum interval throttle (AGENT_DIGEST_MIN_INTERVAL_MINUTES)
    • digest narrator -> agentic/LLM narrative copy (fallback-safe), highlighting actionable items first
    • async callback success -> task completion + Telegram notification
    • async callback failure -> task failure + remediation notification
  • Telegram NL E2E includes deferred-ack path validation (tell me when it's done -> immediate ack + background queue handoff).
  • Dashboard browser E2E now covers assistant chat send flow and pending-approval confirmation flow (Playwright, CI-enforced).
  • CI critical infra pattern includes this suite by default.
  • Queue E2E regression is fixed for BullMQ-safe incremental sync job IDs (minute-epoch dedupe bucket).
  • Infra test runner now flushes Redis and supports profile split:
    • npm run test:e2e:infra (critical)
    • npm run test:e2e:infra:all (full)

Safety Model​

  • Confirm-before-write for mutating actions.
  • Risk classification present (standard, broadcast, destructive, bulk) with impact preview payload.
  • High-risk actions require double-confirm semantics.
  • Approval outcomes and high-risk decisions are captured in task-thread audit entries.
  • Telegram callbacks remain ownership-scoped, replay-safe, and rate-limited.

Delivery/Operations Model​

  • Existing queue/worker stack remains the backbone.
  • Scheduler tasks run as jobs (lifecycle ticks, backfill, digest, notification dispatch).
  • Deferred/background outcomes are reconciled through TaskCallbackService from async_operations callbacks.
  • Notifications deliver through concrete adapters:
    • Telegram
    • in-app websocket
  • Notification dispatcher enforces quiet-hours deferral and bounded retry backoff for failed deliveries.
  • Backfill is online/lazy and idempotent (no downtime migration required).

Known Gaps (Audit)​

  1. Full infra E2E is stable, but negative-path tests still produce intentional worker error logs that can obscure signal while debugging failures.

Positioning​

Nova now operates as a task-centric orchestration platform rather than a command bot. The architecture is orchestrator + collaborators, lifecycle-deterministic, and audit-first, while preserving compatibility for existing API and dashboard consumers during migration.