Implement HITL Message Classifications

[endymion]

Summary

The specification documents a comprehensive message classification system for chat messages, but the current implementation only supports a subset of the required classifications.

Current State

The ChatMessage model currently has a human_interaction_type field that uses HITLRequestType enum with these values:

• APPROVAL (approval)
• INPUT (input)
• REVIEW (review)
• ESCALATION (escalation)
• NOTIFICATION (notification)

Missing Classifications

According to SPECIFICATION.md (lines 858-877), the following classifications are missing:

Internal Messages

• INTERNAL - Agent-only messages, hidden from human UI (LLM reasoning, tool calls, intermediate steps)

Chat Messages

• CHAT - Normal human-AI conversation
• CHAT_ASSISTANT - AI response in conversation

Response Messages

• RESPONSE - Human's response to a pending request

Alert Messages

• ALERT_INFO - System info alert
• ALERT_WARNING - System warning alert
• ALERT_ERROR - System error alert
• ALERT_CRITICAL - System critical alert

Lifecycle States

• TIMED_OUT - Request expired without response
• CANCELLED - Request was cancelled

Value

Implementing the full classification system provides:

1. Better UI Filtering - UIs can filter messages by type (e.g., hide INTERNAL messages, show only ALERT_* messages)
2. Audit Trails - Clear separation between user-facing messages and internal agent operations
3. Separation of Concerns - Distinguish between:
   • Procedure internals (INTERNAL)
   • Human-AI chat (CHAT/CHAT_ASSISTANT)
   • Procedure notifications (NOTIFICATION)
   • System monitoring (ALERT_*)
   • Interactive requests (PENDING_*)

Implementation Notes

1. Extend Enum or Create New: Decide whether to extend HITLRequestType or create a new MessageClassification enum that encompasses all types
2. Backwards Compatibility: The current human_interaction_type field should continue to work, but may need to map to the broader classification system
3. Message Creation: Update all places where ChatMessage objects are created to set appropriate classifications:
   • Agent reasoning/tool calls → INTERNAL
   • Normal conversation → CHAT / CHAT_ASSISTANT
   • Human responses → RESPONSE
   • System alerts → ALERT_*
4. UI Integration: Ensure the IDE and any UI components can filter/display messages based on classification

Related Documentation

• SPECIFICATION.md lines 858-886
• TECHNICAL_DEBT.md "HITL Message Classifications" section (Category 3)
• Current implementation: tactus/protocols/models.py ChatMessage and HITLRequestType

Acceptance Criteria

• All message classifications from the spec are supported
• Messages are automatically classified based on their context (agent reasoning → INTERNAL, etc.)
• Backwards compatibility is maintained for existing human_interaction_type usage
• UI components can filter messages by classification
• Tests verify classification behavior
• Documentation updated to reflect implementation

[endymion]

Groundwork for issue #3 is on branch fix/issue-3-hitl-interaction-type.

Changes:

• Introduce HITLRequestType enum and validate HITLRequest.request_type
• Add ChatMessage.human_interaction_type (aliases: human_interaction, humanInteraction) limited to supported Human.* primitive types
• Update Human.* primitives to use typed request enums
• Add tests for aliases + validation

Remaining work (keeping issue open):

• Runtime/IDE still don’t emit or persist ChatMessage objects, so a host UI can’t render different HITL message UIs yet
• Spec-level classification set (INTERNAL/CHAT/PENDING_/RESPONSE/ALERT_) is not implemented
• Need a ChatRecorder implementation + instrumentation points (agent turns, tool calls, HITL pending/response, notifications/alerts)