Skip to main content

Architecture Decision Record (ADR) / RFC: Auri Reverse Control Flow

RFC Number: RFC-004
Title: Auri Proactive Copilot — Reverse Control Flow & Autonomous Task Delegation
Author: AI & Core Platform Engineering Team
Status: Proposed
Date: 2026-10-31


1. Context & Problem Statement​

1.1 Current State (Reactive / Pull-Only)​

Currently, Auri functions purely as a reactive assistant:

User Prompt → Auri ReAct Loop (using User's Token & Role Tools) → Tool Execution / Proposal Card

Users must explicitly notice an operational issue, open the Auri chat drawer, and prompt Auri to analyze or act.

1.2 Pain Points & Drivers​

  • Manual Overhead for Supervisors & Managers: In a fast-paced contact center, supervisors cannot manually listen to dozens of concurrent calls or constantly refresh queue and SLA dashboards.
  • Delayed Intervention: When a customer is frustrated, repeatedly encountering payment failures, or requesting escalation, by the time a supervisor notices, the call may have already ended or churned.
  • Untapped Existing Capabilities: UniConnect already possesses real-time speech-to-text (sttStream), PBX supervisor controls (barge-in, whisper, silent monitor), a workflow automation engine, role-scoped MCP tools, and a Human-in-the-Loop proposal system. However, they lack an autonomous, proactive connective tissue.

1.3 The Goal​

Transform Auri into a proactive (reverse control flow) copilot inspired by CopilotKit/OpenDuet:

  • Instead of the user asking Auri to do something, the user (or system role) delegates a background monitoring goal to Auri.
  • Auri observes real-time system events, streaming transcripts, and background schedules.
  • When an anomaly or actionable opportunity is detected, Auri evaluates it against the user's role and permissions, pushing an actionable alert to the Auri Mascot with one-click remediations (e.g., Barge-In, Whisper, Internal Chat, Approve Action) executed under the user's authentic identity.

2. Proposed Architecture & Solution​

2.1 Core Principle: Zero Duplication of Engines​

Rather than building an isolated daemon or separate tool executor, the reverse control flow connects UniConnect's existing proven subsystems:

  1. Triggers & Event Source: Unified domain event bus & workflow triggers (Workflow + WorkflowSchedule + sttStream live audio transcription).
  2. AI Reasoning & Tool Catalog: Moleculer AI services (copilot.service.js, mcp.getToolsForRole, llmJson.js).
  3. HITL Proposal & Audit Engine: CopilotProposal entity in PostgreSQL (copilot_proposals).
  4. Push & Execution Layer: Real-time WebSocket gateway (websocket.service.js) and the frontend AuriMascotAlert + AuriUIBridge + callMonitoring.ts.

2.2 End-to-End Architecture Flow​


2.3 Detailed Component Specifications​

A. Watcher Definition & Workflow Integration​

A Watcher is represented as a standard workflow node or pre-configured system routine:

  • Node Action: copilot.evaluateWatchdog (registered in WorkflowRegistry).
  • Configuration Schema:
{
"watcherType": "live_call_stream | workflow_event | scheduled_brief",
"goalPrompt": "Monitor live calls for customer frustration, repeated gateway timeouts, or manager requests.",
"severityRule": "auto",
"targetAudience": {
"mode": "role | user | record_owner_supervisor",
"roleIds": [2],
"requiredPermissions": ["CALL_BARGE_IN", "CALL_WHISPER", "CALL_SILENT_MONITOR"],
"respectAccessGroups": true,
"onlineOnly": true
},
"allowedActionCategories": ["call_supervision", "internal_chat", "crm_tools", "ui_navigation"],
"cooldownSeconds": 120,
"dedupeKeyTemplate": "call:{{call_id}}"
}

B. Live Call Stream Anomaly Detection (Supervisor Case)​

  • Ring Buffer in sttStream.service.js: Maintains a rolling transcript window per call_id (e.g., last 6 turns / 30 seconds) with stereo channel separation (agent vs. customer).
  • Two-Tier Cost/Latency Gating:
    • Tier 1 (Heuristic Gate): Runs locally on every final transcript segment. Checks negative sentiment dictionary, interruption frequency, or escalation triggers ("supervisor", "manager", "cancel subscription", "unacceptable"). Verifies Redis cooldown key watchdog:cooldown:${watcherId}:${callId}.
    • Tier 2 (LLM Evaluation): Triggers copilot.evaluateWatchdog asynchronously with rolling transcript and call participant metadata. Produces structured output: { shouldAlert: boolean, severity: "critical" | "warning" | "info", title: string, message: string, suggestedActions: [] }.

C. Role Scoping & User-Token Security Boundary​

The detection phase runs read-only without executing mutating tools. When the alert is generated, each suggested action is executed strictly under the authenticated user's session:

Action CategoryTarget ExecutionAuthentication / Permission Scope
PBX Supervisionbarge_in, whisper, silent_monitor, force_transferExecuted directly via frontend requestSupervisorMonitoring() using the user's JWT and extension.
Internal Coachinginternal_chat with the assigned agentOpens direct internal chat or sends pre-filled coaching suggestion as the supervisor.
MCP Tool ProposalDatabase changes, Ticket creation, CRM updatesCreated as an approval-gated CopilotProposal. Approved via POST /copilot/proposals/:id/approve using the user's JWT.
Conversational Hand-offAsk Auri buttonOpens AuriSider focused on the alert context, allowing interactive questioning.

D. Frontend: Auri Mascot Alert UX (AuriMascotAlert.tsx)​

  • Visual Mascot States: idle (floating breath), alert (expressive wide eyes, animated bounce), acting (spinning loader), happy (success bounce).
  • Multi-Alert Queue: Supports queue badges when multiple anomalies occur simultaneously, with pagination/cycling controls.
  • Multi-Action Buttons: Renders immediate primary actions (e.g. Barge-In, Whisper, Release Hold) alongside Ask Auri.
  • Sync & Resolution: Emits resolution updates across tabs and fellow supervisors so actions aren't duplicated.

3. Alternatives Considered​

AlternativeProsConsVerdict
1. Standalone Python/LangGraph Daemon (OpenDuet exact clone)Pre-built agent framework, isolated process.Duplicates UniConnect's Moleculer services, requires extra containers, doesn't integrate natively with Redis/Prisma or active WebSocket connections.Rejected
2. Continuous Polling by Frontend ClientsSimple client-side timers.Immense backend load, high latency, wastes LLM quota polling static state.Rejected
3. Workflow Engine + Copilot Proposal Integration (Proposed)100% reuses existing event engine, WebSocket gateway, role tools, and proposal UI. Zero DB migrations needed.Requires careful rate-limiting on high-frequency audio streams.Accepted

4. Implementation Phases​

Phase 1: Generic Watchdog Evaluator (uc-enterprise-core)​

  • Implement copilot.evaluateWatchdog action in services/channels/AI/copilot/watchdog/.
  • Handle role, permission, and group-scoped audience filtering using websocket.getConnections and userGroupCache.
  • Register the Proactive Auri Alert action in WorkflowRegistry.
  • Add unit tests under test/unit/services/copilot/watchdog.spec.js.

Phase 2: Live Call Stream Anomaly Integration (uc-enterprise-core)​

  • Add stereo transcript buffer and Tier-1 escalation filter in sttStream.service.js.
  • Construct pre-configured supervisor actions (barge_in, whisper, silent_monitor, force_transfer, internal_chat).
  • Add unit tests for transcript buffering and triggering.

Phase 3: Mascot Alert Queue & Execution (uc-enterprise-web)​

  • Refactor AuriMascotAlert.tsx to handle an alert queue, multi-action chips, and real-time WebSocket state synchronization.
  • Implement concrete execution dispatchers for PBX supervisor actions, proposal approvals, and UI navigation.
  • Mount globally in Home.page.tsx and integrate seamless handoff to AuriSider.tsx.
  • Add Vitest tests under test/components/Auri/AuriMascotAlert.test.tsx.

Phase 4: Conversational Delegation & Active Watchers UI​

  • Allow users to delegate tasks directly in chat ("Auri, monitor queue wait times and alert me if wait exceeds 5 minutes").
  • Add an "Active Watchers" panel inside AuriSider for viewing, pausing, and resuming active automations.

5. Risks & Mitigations​

  1. LLM Cost & Token Storms on Audio Streams:
    • Risk: Evaluating every utterance of hundreds of concurrent calls would exceed LLM rate limits and budgets.
    • Mitigation: Two-tier evaluation. Tier 1 executes low-cost deterministic heuristic checks (lexicon matching, sentiment flags, silence timers) and enforces strict per-call Redis cooldowns (e.g. 120s) before any LLM evaluation is invoked.
  2. Alert Fatigue:
    • Risk: Too many low-priority popups causing supervisors to dismiss or ignore the mascot.
    • Mitigation: Severity categorization (critical, warning, info) with visual distinction; auto-batching in the mascot alert queue; user-level configuration of minimum alerting severity.
  3. Execution Permissions & Security:
    • Risk: An alert executing an action the current user does not have permission to perform.
    • Mitigation: Audience filtering guarantees alerts are only delivered to users holding governing permissions. Actions execute client-side through validated APIs using the user's personal JWT.