Suggestion System

Last Updated: 2025-01-16
Primary Source: docs/project_status.md
Service Files: backend/src/services/suggestionCore.service.ts, backend/src/services/suggestionStorage.service.ts, backend/src/services/proactiveSuggestion.service.ts, backend/src/services/suggestionHistory.service.ts
Adapters: backend/src/services/suggestionAdapters/

---

Overview

The Suggestion System provides client-agnostic proactive suggestions that guide users through workflows. It analyzes conversation context, generates actionable suggestions, stores them for retrieval, and tracks user interactions for analytics. The system is designed to work across all clients (Discord, Web Portal, API, etc.) using abstract context IDs.

---

Architecture

Suggestion System Flow

---

Core Components

1. Suggestion Core Service

File: backend/src/services/suggestionCore.service.ts

Purpose: Core suggestion types, action definitions, and safety policies

Key Types:

SuggestionType (Enum)

• BREAK_DOWN_TASKS - Break down tasks
• RUN_ORCHESTRATOR - Run orchestrator
• VIEW_ARTIFACTS - View artifacts
• TRANSITION_STATE - Transition state
• APPROVE_GUARD - Approve guard
• ATTACH_EVIDENCE - Attach evidence
• REVIEW_ARTIFACT - Review artifact
• SELECT_PROTOCOL - Select protocol
• CREATE_STATE_MACHINE - Create state machine
• GENERATE_DOCUMENTATION - Generate documentation
• SUGGEST_NEXT_STEP - Suggest next step
• NONE - No suggestion

ActionType (Enum)

• EXECUTE - Execute action
• VIEW - View information (read-only)
• APPROVE - Approve guard/transition
• CANCEL - Cancel suggestion
• SHOW_STATUS - Show flow status
• ASK_QUESTIONS - Ask clarifying questions
• TRANSITION - Transition state
• ATTACH_EVIDENCE - Attach evidence
• REVIEW - Review artifact

ActionSafety (Enum)

• SAFE - Safe to auto-execute
• REQUIRES_CONFIRMATION - Optional auto-execute
• NEVER_AUTO - Never auto-execute

ActionSuggestion (Interface)

interface ActionSuggestion {
  id: string;
  type: SuggestionType;
  message: string;
  confidence: number; // 0.0 to 1.0
  metadata: Record<string, any>;
  actions: ActionableAction[];
  timestamp: string;
  ttl: number; // Time to live in seconds
  priority: number; // Higher = higher priority
  context?: {
    contextId?: string;
    instanceId?: string;
    channelId?: string; // Backward compatibility
    userId?: number;
    protocolId?: string;
    state?: string;
  };
}

AutoExecutionConfig (Interface)

interface AutoExecutionConfig {
  autoRunOrchestrator: boolean;
  autoTransitionOnGuard: boolean;
  autoSuggestNextStep: boolean;
  requireConfirmationFor: ActionType[];
  neverAutoExecute: ActionType[];
  undoWindowMinutes: number;
}

Key Functions:

canAutoExecute(action, config)

• Checks if action can be auto-executed
• Considers safety classification
• Respects configuration settings

isSuggestionExpired(suggestion)

• Checks if suggestion has expired
• Based on TTL and timestamp

prioritizeSuggestions(suggestions)

• Sorts suggestions by priority, confidence, timestamp
• Returns prioritized list

2. Suggestion Storage Service

File: backend/src/services/suggestionStorage.service.ts

Purpose: Client-agnostic suggestion storage and retrieval

Key Functions:

storeSuggestion(contextId, suggestion, options)

• Stores suggestion using appropriate backend
• Converts ProactiveSuggestion to ActionSuggestion if needed
• Enhances with context and metadata
• Returns suggestion ID

getActiveSuggestions(contextId)

• Retrieves active, non-expired suggestions
• Filters by status and expiration
• Sorts by priority and timestamp
• Returns top 10 suggestions

clearSuggestions(contextId, suggestionId?)

• Clears all suggestions or specific suggestion
• Marks suggestions as executed/expired
• Updates storage backend

updateSuggestion(contextId, suggestionId, updates)

• Updates specific suggestion
• Supports status, priority, and custom fields

Storage Backends:

• DiscordStorageBackend - Stores in DiscordChannelConfig metadata
• Future: PortalStorageBackend, SlackStorageBackend, etc.

3. Proactive Suggestion Service

File: backend/src/services/proactiveSuggestion.service.ts

Purpose: Analyzes conversation and generates proactive suggestions

Key Functions:

analyzeConversationForProactiveSuggestions(contextId, userId, messageContent, ...)

• Analyzes conversation context
• Checks for state machine/protocol
• Generates appropriate suggestions
• Returns ActionSuggestion

Suggestion Logic:

1. No State Machine/Protocol:

   • Uses intent analysis
   • Suggests protocol selection if development intent detected

2. Has State Machine:

   • Checks current state
   • Suggests orchestrator, artifacts, transitions based on context

3. Has Protocol:

   • Analyzes protocol context
   • Generates protocol-specific suggestions

generateFollowUpSuggestion(contextId, userId, previousType, result, ...)

• Generates follow-up suggestion after action execution
• Context-aware based on previous action
• Returns ActionSuggestion

4. Suggestion History Service

File: backend/src/services/suggestionHistory.service.ts

Purpose: Tracks suggestions for analytics and debugging

Key Functions:

recordSuggestion(payload)

• Records new suggestion in history
• Stores metadata and context
• Returns SuggestionHistory record

recordSuggestionResponse(payload)

• Records user response to suggestion
• Tracks response time
• Updates status (accepted/declined/expired)

recordSuggestionExecution(payload)

• Records action execution result
• Tracks execution time and errors
• Updates status to executed

getSuggestionHistory(channelId, limit)

• Retrieves suggestion history for channel
• Returns recent suggestions

---

Suggestion Types

Workflow Suggestions

1. Break Down Tasks

   • Suggests breaking down request into tasks
   • Triggered in intake state
   • Action: Execute task breakdown

2. Run Orchestrator

   • Suggests running orchestrator for pending tasks
   • Triggered when tasks are pending
   • Action: Execute orchestrator

3. View Artifacts

   • Suggests viewing artifacts
   • Triggered when artifacts exist
   • Action: View artifacts (auto-executable)

4. Transition State

   • Suggests state transition
   • Triggered when guards satisfied
   • Action: Transition state (requires confirmation)

5. Approve Guard

   • Suggests approving guard
   • Triggered when guard required
   • Action: Approve guard

6. Attach Evidence

   • Suggests attaching evidence
   • Triggered when evidence required
   • Action: Attach evidence

7. Review Artifact

   • Suggests reviewing artifact
   • Triggered when artifacts pending review
   • Action: Review artifact

Setup Suggestions

1. Select Protocol

   • Suggests selecting protocol
   • Triggered when no protocol configured
   • Action: Select protocol

2. Create State Machine

   • Suggests creating state machine
   • Triggered when protocol selected but no machine
   • Action: Create state machine

---

Action Safety

Safety Classification

Safe Actions (Auto-executable):

• VIEW - View information
• SHOW_STATUS - Show status

Requires Confirmation:

• APPROVE - Approve guard
• TRANSITION - Transition state
• REVIEW - Review artifact
• ASK_QUESTIONS - Ask questions

Never Auto-execute:

• EXECUTE - Execute action
• CANCEL - Cancel suggestion
• ATTACH_EVIDENCE - Attach evidence

Auto-Execution Rules

1. Check neverAutoExecute list
2. Check action safety classification
3. Check requireConfirmationFor list
4. Check autoExecutable flag
5. Return boolean result

---

Data Flow

---

Client Adapters

Location: backend/src/services/suggestionAdapters/

Purpose: Translate between client-specific formats and core suggestion format

Adapters:

• discordAdapter.service.ts - Discord-specific formatting
• apiAdapter.service.ts - API-specific formatting
• migrationHelper.service.ts - Migration between formats

---

Integration Points

Auto-Flow Integration

• Uses suggestions for auto-execution
• Checks safety before executing
• Records execution in history

State Machine Integration

• Generates suggestions based on state
• Suggests transitions when guards satisfied
• Suggests orchestrator when tasks pending

Coder Orchestrator Integration

• Suggests running orchestrator
• Suggests viewing artifacts
• Suggests reviewing artifacts

---

API Endpoints

Suggestion Management

• GET /api/suggestions/:contextId - Get active suggestions
• POST /api/suggestions/:contextId/execute - Execute suggestion
• POST /api/suggestions/:contextId/clear - Clear suggestions
• PUT /api/suggestions/:contextId/:id - Update suggestion

Suggestion History

• GET /api/suggestions/history/:channelId - Get suggestion history
• GET /api/suggestions/history/user/:userId - Get user history
• GET /api/suggestions/history/instance/:instanceId - Get instance history

---

Source Files

Primary Sources:

• backend/src/services/suggestionCore.service.ts - Core types and functions
• backend/src/services/suggestionStorage.service.ts - Storage and retrieval
• backend/src/services/proactiveSuggestion.service.ts - Suggestion generation
• backend/src/services/suggestionHistory.service.ts - History tracking

Adapters:

• backend/src/services/suggestionAdapters/discordAdapter.service.ts - Discord adapter
• backend/src/services/suggestionAdapters/apiAdapter.service.ts - API adapter
• backend/src/services/suggestionAdapters/migrationHelper.service.ts - Migration helper

Related Files:

• backend/src/services/autoFlow.service.ts - Auto-execution
• backend/src/services/actionExecutor.service.ts - Action execution
• backend/src/models/suggestionHistory.model.ts - History model

---

Related Documentation

• Auto-Flow System - Workflow intelligence
• State Machine System - Workflow management
• Coder Orchestrator System - Task execution
• Context Services - Client-agnostic context
• 00-OVERVIEW.md - Complete system overview