Message Classification System

Every message has a humanInteraction classification that determines visibility and behavior.

Overview

Every message in the Plexus system has a humanInteraction field that determines:

  • UI Visibility: Whether humans see the message
  • Blocking Behavior: Whether execution waits for response
  • Response Expected: Whether human input is required

Classification Values

ValueDescriptionBlocks?UI Visibility
INTERNALAgent reasoning, tool callsNoHidden
CHATHuman message in conversationNoVisible
CHAT_ASSISTANTAI response in conversationNoVisible
NOTIFICATIONWorkflow progress updateNoVisible
ALERT_INFOSystem info alertNoVisible (monitoring)
ALERT_WARNINGSystem warningNoVisible (monitoring)
ALERT_ERRORSystem error alertNoVisible (monitoring)
ALERT_CRITICALCritical system alertNoVisible (monitoring)
PENDING_APPROVALWaiting for yes/noYesVisible (action required)
PENDING_INPUTWaiting for inputYesVisible (action required)
PENDING_REVIEWWaiting for reviewYesVisible (action required)
RESPONSEHuman's responseNoVisible
TIMED_OUTRequest expiredNoVisible
CANCELLEDRequest cancelledNoVisible

Usage Patterns

Procedure Workflow (Mixed Visibility)

1. INTERNAL          Worker.turn() reasoning
2. INTERNAL          Tool call: search(...)
3. INTERNAL          Tool result: [...]
4. NOTIFICATION      "Analysis complete"
5. PENDING_APPROVAL  "Deploy to production?"
6. RESPONSE          "Yes" (from human)
7. NOTIFICATION      "Deploying..."
8. NOTIFICATION      "Deployment complete"

Human sees: 4, 5, 6, 7, 8
System sees: all

Chat Conversation (All Visible)

1. CHAT              "How do I deploy?"
2. CHAT_ASSISTANT    "You can deploy using..."
3. CHAT              "Can you deploy for me?"
4. INTERNAL          (spawns deployment procedure)
5. NOTIFICATION      "Starting deployment"
6. CHAT_ASSISTANT    "I've started the deployment"

Human sees: 1, 2, 3, 5, 6
System sees: all

System Monitoring (Alert Stream)

1. ALERT_INFO        "Batch processing started"
2. ALERT_INFO        "Processing 1000 of 10000"
3. ALERT_WARNING     "High memory usage detected"
4. ALERT_ERROR       "Database connection lost"
5. ALERT_CRITICAL    "Service unavailable"

All visible in monitoring dashboard

UI Filtering

Human Operator Dashboard

Show only user-facing messages:

SELECT * FROM chat_messages
WHERE human_interaction IN (
  'CHAT',
  'CHAT_ASSISTANT',
  'NOTIFICATION',
  'ALERT_WARNING',
  'ALERT_ERROR',
  'ALERT_CRITICAL',
  'PENDING_APPROVAL',
  'PENDING_INPUT',
  'PENDING_REVIEW',
  'RESPONSE'
)

Monitoring Dashboard

Show only alerts:

SELECT * FROM chat_messages
WHERE human_interaction LIKE 'ALERT_%'
ORDER BY created_at DESC

Action Required

Show only messages requiring response:

SELECT * FROM chat_messages
WHERE human_interaction IN (
  'PENDING_APPROVAL',
  'PENDING_INPUT',
  'PENDING_REVIEW'
)
AND status = 'pending'

Design Principles

  • Unified System: One classification covers all use cases
  • Clear Semantics: Name indicates purpose and behavior
  • UI-Friendly: Easy to filter for different views
  • Blocking Explicit: Clear which messages block workflow
  • Monitoring Integration: Alerts work for both procedures and external systems

Best Practices

DO

  • Use INTERNAL for agent work
  • Use NOTIFICATION for progress
  • Use ALERT_* for system events
  • Use PENDING_* sparingly
  • Use CHAT for conversations

DON'T

  • Over-notify (fatigue)
  • Mix alerts and notifications
  • Block for trivial operations
  • Expose internal details

Complete Documentation

Detailed documentation with examples is available at:

/plexus/procedures/docs/message-classification.html