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:
- Triggers & Event Source: Unified domain event bus & workflow triggers (
Workflow+WorkflowSchedule+sttStreamlive audio transcription). - AI Reasoning & Tool Catalog: Moleculer AI services (
copilot.service.js,mcp.getToolsForRole,llmJson.js). - HITL Proposal & Audit Engine:
CopilotProposalentity in PostgreSQL (copilot_proposals). - Push & Execution Layer: Real-time WebSocket gateway (
websocket.service.js) and the frontendAuriMascotAlert+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 inWorkflowRegistry). - 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 percall_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.evaluateWatchdogasynchronously with rolling transcript and call participant metadata. Produces structured output:{ shouldAlert: boolean, severity: "critical" | "warning" | "info", title: string, message: string, suggestedActions: [] }.
- 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
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 Category | Target Execution | Authentication / Permission Scope |
|---|---|---|
| PBX Supervision | barge_in, whisper, silent_monitor, force_transfer | Executed directly via frontend requestSupervisorMonitoring() using the user's JWT and extension. |
| Internal Coaching | internal_chat with the assigned agent | Opens direct internal chat or sends pre-filled coaching suggestion as the supervisor. |
| MCP Tool Proposal | Database changes, Ticket creation, CRM updates | Created as an approval-gated CopilotProposal. Approved via POST /copilot/proposals/:id/approve using the user's JWT. |
| Conversational Hand-off | Ask Auri button | Opens 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
| Alternative | Pros | Cons | Verdict |
|---|---|---|---|
| 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 Clients | Simple 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.evaluateWatchdogaction inservices/channels/AI/copilot/watchdog/. - Handle role, permission, and group-scoped audience filtering using
websocket.getConnectionsanduserGroupCache. - Register the
Proactive Auri Alertaction inWorkflowRegistry. - 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.tsxto 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.tsxand integrate seamless handoff toAuriSider.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
AuriSiderfor viewing, pausing, and resuming active automations.
5. Risks & Mitigations
- 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.
- 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.
- 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.