444 lines
14 KiB
Go
444 lines
14 KiB
Go
// Package clarification provides types and services for agent clarification requests.
|
|
package clarification
|
|
|
|
import (
|
|
"context"
|
|
"errors"
|
|
"fmt"
|
|
"net/http"
|
|
|
|
"github.com/gin-gonic/gin"
|
|
"github.com/kandev/kandev/internal/common/logger"
|
|
"github.com/kandev/kandev/internal/events"
|
|
"github.com/kandev/kandev/internal/events/bus"
|
|
taskmodels "github.com/kandev/kandev/internal/task/models"
|
|
wsmsg "github.com/kandev/kandev/pkg/websocket"
|
|
"go.uber.org/zap"
|
|
)
|
|
|
|
// messageStore is the minimal task repository interface required by clarification handlers.
|
|
type messageStore interface {
|
|
GetTaskSession(ctx context.Context, id string) (*taskmodels.TaskSession, error)
|
|
FindMessageByPendingID(ctx context.Context, pendingID string) (*taskmodels.Message, error)
|
|
UpdateMessage(ctx context.Context, message *taskmodels.Message) error
|
|
}
|
|
|
|
// Broadcaster interface for sending WebSocket notifications
|
|
type Broadcaster interface {
|
|
BroadcastToSession(sessionID string, msg *wsmsg.Message)
|
|
}
|
|
|
|
// MessageCreator interface for creating messages in the database
|
|
type MessageCreator interface {
|
|
// CreateClarificationRequestMessage creates a message for a clarification request
|
|
CreateClarificationRequestMessage(ctx context.Context, taskID, sessionID, pendingID string, question Question, clarificationContext string) (string, error)
|
|
// UpdateClarificationMessage updates a clarification message's status and response
|
|
UpdateClarificationMessage(ctx context.Context, sessionID, pendingID, status string, answer *Answer) error
|
|
}
|
|
|
|
// EventBus interface for publishing events.
|
|
type EventBus interface {
|
|
Publish(ctx context.Context, topic string, event *bus.Event) error
|
|
}
|
|
|
|
// Handlers provides HTTP handlers for clarification requests.
|
|
type Handlers struct {
|
|
store *Store
|
|
hub Broadcaster
|
|
messageCreator MessageCreator
|
|
repo messageStore
|
|
eventBus EventBus
|
|
logger *logger.Logger
|
|
}
|
|
|
|
// NewHandlers creates new clarification handlers.
|
|
func NewHandlers(store *Store, hub Broadcaster, messageCreator MessageCreator, repo messageStore, eventBus EventBus, log *logger.Logger) *Handlers {
|
|
return &Handlers{
|
|
store: store,
|
|
hub: hub,
|
|
messageCreator: messageCreator,
|
|
repo: repo,
|
|
eventBus: eventBus,
|
|
logger: log.WithFields(zap.String("component", "clarification-handlers")),
|
|
}
|
|
}
|
|
|
|
// RegisterRoutes registers clarification HTTP routes.
|
|
func RegisterRoutes(router *gin.Engine, store *Store, hub Broadcaster, messageCreator MessageCreator, repo messageStore, eventBus EventBus, log *logger.Logger) {
|
|
h := NewHandlers(store, hub, messageCreator, repo, eventBus, log)
|
|
api := router.Group("/api/v1/clarification")
|
|
api.POST("/request", h.httpCreateRequest)
|
|
api.GET("/:id", h.httpGetRequest)
|
|
api.GET("/:id/wait", h.httpWaitForResponse)
|
|
api.POST("/:id/respond", h.httpRespond)
|
|
}
|
|
|
|
// CreateRequestBody is the request body for creating a clarification request.
|
|
type CreateRequestBody struct {
|
|
SessionID string `json:"session_id" binding:"required"`
|
|
TaskID string `json:"task_id"`
|
|
Question Question `json:"question" binding:"required"`
|
|
Context string `json:"context"`
|
|
}
|
|
|
|
// CreateRequestResponse is the response for creating a clarification request.
|
|
type CreateRequestResponse struct {
|
|
PendingID string `json:"pending_id"`
|
|
}
|
|
|
|
func (h *Handlers) httpCreateRequest(c *gin.Context) {
|
|
var body CreateRequestBody
|
|
if err := c.ShouldBindJSON(&body); err != nil {
|
|
c.JSON(http.StatusBadRequest, gin.H{"error": "invalid payload: " + err.Error()})
|
|
return
|
|
}
|
|
|
|
// Validate question has ID, generate if missing
|
|
if body.Question.ID == "" {
|
|
body.Question.ID = "q1"
|
|
}
|
|
// Validate options have IDs
|
|
for j := range body.Question.Options {
|
|
if body.Question.Options[j].ID == "" {
|
|
body.Question.Options[j].ID = generateOptionID(0, j)
|
|
}
|
|
}
|
|
|
|
// Look up the task ID for this session
|
|
sessionID := body.SessionID
|
|
taskID := body.TaskID
|
|
if taskID == "" {
|
|
session, err := h.repo.GetTaskSession(c.Request.Context(), sessionID)
|
|
if err != nil {
|
|
h.logger.Warn("failed to look up session",
|
|
zap.String("session_id", sessionID),
|
|
zap.Error(err))
|
|
} else {
|
|
taskID = session.TaskID
|
|
}
|
|
}
|
|
|
|
req := &Request{
|
|
SessionID: sessionID,
|
|
TaskID: taskID,
|
|
Question: body.Question,
|
|
Context: body.Context,
|
|
}
|
|
|
|
pendingID := h.store.CreateRequest(req)
|
|
|
|
// Create a message in the database for the clarification request.
|
|
// This triggers the session.message.added WebSocket event which the frontend listens to.
|
|
if h.messageCreator != nil {
|
|
_, err := h.messageCreator.CreateClarificationRequestMessage(
|
|
c.Request.Context(),
|
|
taskID,
|
|
sessionID,
|
|
pendingID,
|
|
body.Question,
|
|
body.Context,
|
|
)
|
|
if err != nil {
|
|
h.logger.Error("failed to create clarification request message",
|
|
zap.String("pending_id", pendingID),
|
|
zap.String("session_id", sessionID),
|
|
zap.Error(err))
|
|
// Don't fail the request - the clarification is still created in the store
|
|
}
|
|
}
|
|
|
|
c.JSON(http.StatusOK, CreateRequestResponse{PendingID: pendingID})
|
|
}
|
|
|
|
func (h *Handlers) httpGetRequest(c *gin.Context) {
|
|
pendingID := c.Param("id")
|
|
|
|
req, ok := h.store.GetRequest(pendingID)
|
|
if !ok {
|
|
c.JSON(http.StatusNotFound, gin.H{"error": "clarification request not found"})
|
|
return
|
|
}
|
|
|
|
c.JSON(http.StatusOK, req)
|
|
}
|
|
|
|
func (h *Handlers) httpWaitForResponse(c *gin.Context) {
|
|
pendingID := c.Param("id")
|
|
resp, err := h.store.WaitForResponse(c.Request.Context(), pendingID)
|
|
if err != nil {
|
|
c.JSON(http.StatusGatewayTimeout, gin.H{"error": err.Error()})
|
|
return
|
|
}
|
|
|
|
c.JSON(http.StatusOK, resp)
|
|
}
|
|
|
|
// RespondBody is the request body for responding to a clarification request.
|
|
type RespondBody struct {
|
|
Answers []Answer `json:"answers"` // Keep as array for frontend compatibility, but only first is used
|
|
Rejected bool `json:"rejected"`
|
|
RejectReason string `json:"reject_reason"`
|
|
}
|
|
|
|
func (h *Handlers) httpRespond(c *gin.Context) {
|
|
pendingID := c.Param("id")
|
|
|
|
var body RespondBody
|
|
if err := c.ShouldBindJSON(&body); err != nil {
|
|
c.JSON(http.StatusBadRequest, gin.H{"error": "invalid payload: " + err.Error()})
|
|
return
|
|
}
|
|
|
|
// Extract the single answer (first one if provided)
|
|
var answer *Answer
|
|
if len(body.Answers) > 0 {
|
|
answer = &body.Answers[0]
|
|
}
|
|
|
|
// Build the response object
|
|
resp := &Response{
|
|
PendingID: pendingID,
|
|
Answer: answer,
|
|
Rejected: body.Rejected,
|
|
RejectReason: body.RejectReason,
|
|
}
|
|
|
|
// Try the primary path: deliver via channel to blocking WaitForResponse.
|
|
// If the agent is still waiting, this unblocks the MCP handler and the
|
|
// answer is returned within the same agent turn (no extra cost).
|
|
err := h.store.Respond(pendingID, resp)
|
|
|
|
if err == nil {
|
|
// Primary path succeeded — agent will receive the answer directly.
|
|
h.updateClarificationMessage(c, pendingID, body.Rejected, answer)
|
|
h.publishPrimaryAnsweredEvent(c, pendingID, answer, body.Rejected, body.RejectReason)
|
|
h.logger.Info("clarification answered via primary path (same turn)",
|
|
zap.String("pending_id", pendingID))
|
|
c.JSON(http.StatusOK, gin.H{"success": true})
|
|
return
|
|
}
|
|
|
|
// Duplicate response — someone clicked twice quickly.
|
|
if errors.Is(err, ErrAlreadyResponded) {
|
|
h.logger.Warn("duplicate response attempt",
|
|
zap.String("pending_id", pendingID))
|
|
c.JSON(http.StatusConflict, gin.H{"error": "response already submitted"})
|
|
return
|
|
}
|
|
|
|
// Fallback path: entry not found (agent timed out, entry was cleaned up).
|
|
// If the user rejected (clicked X to dismiss), they're discarding a stale
|
|
// overlay — not continuing the conversation. Treat as a no-op so we don't
|
|
// surprise them by resuming the agent with "User declined to answer".
|
|
// The message status is already "expired" (set by the canceller), so the
|
|
// chat history will keep rendering the "Timed out" entry.
|
|
if body.Rejected {
|
|
h.logger.Info("clarification rejected after agent moved on; no-op",
|
|
zap.String("pending_id", pendingID))
|
|
c.JSON(http.StatusOK, gin.H{"success": true})
|
|
return
|
|
}
|
|
|
|
// User is providing an affirmative answer after the agent moved on. Update
|
|
// the clarification record and publish an event so the orchestrator resumes
|
|
// the agent with a new turn containing the answer.
|
|
h.logger.Info("clarification entry not found, using event fallback",
|
|
zap.String("pending_id", pendingID),
|
|
zap.String("error", err.Error()))
|
|
|
|
h.updateClarificationMessage(c, pendingID, body.Rejected, answer)
|
|
h.respondViaEventFallback(c, pendingID, answer, body.Rejected, body.RejectReason)
|
|
|
|
c.JSON(http.StatusOK, gin.H{"success": true})
|
|
}
|
|
|
|
// updateClarificationMessage updates the message in the database with status and answer.
|
|
func (h *Handlers) updateClarificationMessage(c *gin.Context, pendingID string, rejected bool, answer *Answer) {
|
|
if h.messageCreator == nil {
|
|
return
|
|
}
|
|
sessionID := h.lookupSessionForPending(c, pendingID)
|
|
status := "answered"
|
|
if rejected {
|
|
status = "rejected"
|
|
}
|
|
if err := h.messageCreator.UpdateClarificationMessage(c.Request.Context(), sessionID, pendingID, status, answer); err != nil {
|
|
h.logger.Warn("failed to update clarification message",
|
|
zap.String("pending_id", pendingID),
|
|
zap.Error(err))
|
|
}
|
|
}
|
|
|
|
// respondViaEventFallback publishes a ClarificationAnswered event for the orchestrator
|
|
// to resume the agent with a new turn. Used when the agent timed out.
|
|
func (h *Handlers) respondViaEventFallback(c *gin.Context, pendingID string, answer *Answer, rejected bool, rejectReason string) {
|
|
if h.eventBus == nil {
|
|
return
|
|
}
|
|
|
|
clarificationCtx, err := h.resolveClarificationEventContext(c.Request.Context(), pendingID)
|
|
if err != nil {
|
|
h.logger.Error("failed to resolve context for clarification fallback event",
|
|
zap.String("pending_id", pendingID),
|
|
zap.Error(err))
|
|
return
|
|
}
|
|
if clarificationCtx.SessionID == "" || clarificationCtx.TaskID == "" {
|
|
h.logger.Error("missing session/task for clarification fallback event",
|
|
zap.String("pending_id", pendingID),
|
|
zap.String("session_id", clarificationCtx.SessionID),
|
|
zap.String("task_id", clarificationCtx.TaskID))
|
|
return
|
|
}
|
|
|
|
answerText := buildAnswerText(answer, rejected, rejectReason)
|
|
|
|
eventData := map[string]any{
|
|
"session_id": clarificationCtx.SessionID,
|
|
"task_id": clarificationCtx.TaskID,
|
|
"pending_id": pendingID,
|
|
"question": clarificationCtx.Question,
|
|
"answer_text": answerText,
|
|
"rejected": rejected,
|
|
"reject_reason": rejectReason,
|
|
}
|
|
if err := h.eventBus.Publish(c.Request.Context(), events.ClarificationAnswered, bus.NewEvent(
|
|
events.ClarificationAnswered,
|
|
"clarification-handlers",
|
|
eventData,
|
|
)); err != nil {
|
|
h.logger.Error("failed to publish clarification answered event",
|
|
zap.String("pending_id", pendingID),
|
|
zap.String("session_id", clarificationCtx.SessionID),
|
|
zap.Error(err))
|
|
}
|
|
|
|
h.logger.Info("clarification answered via event fallback (new turn)",
|
|
zap.String("pending_id", pendingID),
|
|
zap.String("session_id", clarificationCtx.SessionID),
|
|
zap.String("task_id", clarificationCtx.TaskID))
|
|
}
|
|
|
|
// lookupSessionForPending returns the session ID for a pending clarification.
|
|
// Falls back to finding it from the database message.
|
|
func (h *Handlers) lookupSessionForPending(c *gin.Context, pendingID string) string {
|
|
// Try the in-memory store first
|
|
if req, ok := h.store.GetRequest(pendingID); ok {
|
|
return req.SessionID
|
|
}
|
|
// Fall back to database
|
|
msg, err := h.repo.FindMessageByPendingID(c.Request.Context(), pendingID)
|
|
if err != nil {
|
|
return ""
|
|
}
|
|
return msg.TaskSessionID
|
|
}
|
|
|
|
func (h *Handlers) publishPrimaryAnsweredEvent(c *gin.Context, pendingID string, answer *Answer, rejected bool, rejectReason string) {
|
|
if h.eventBus == nil {
|
|
return
|
|
}
|
|
clarificationCtx, err := h.resolveClarificationEventContext(c.Request.Context(), pendingID)
|
|
if err != nil {
|
|
h.logger.Warn("failed to resolve context for primary clarification event",
|
|
zap.String("pending_id", pendingID),
|
|
zap.Error(err))
|
|
return
|
|
}
|
|
if clarificationCtx.SessionID == "" || clarificationCtx.TaskID == "" {
|
|
h.logger.Warn("missing session/task for primary clarification event",
|
|
zap.String("pending_id", pendingID),
|
|
zap.String("session_id", clarificationCtx.SessionID),
|
|
zap.String("task_id", clarificationCtx.TaskID))
|
|
return
|
|
}
|
|
|
|
answerText := buildAnswerText(answer, rejected, rejectReason)
|
|
eventData := map[string]any{
|
|
"session_id": clarificationCtx.SessionID,
|
|
"task_id": clarificationCtx.TaskID,
|
|
"pending_id": pendingID,
|
|
"question": clarificationCtx.Question,
|
|
"answer_text": answerText,
|
|
"rejected": rejected,
|
|
"reject_reason": rejectReason,
|
|
}
|
|
if err := h.eventBus.Publish(c.Request.Context(), events.ClarificationPrimaryAnswered, bus.NewEvent(
|
|
events.ClarificationPrimaryAnswered,
|
|
"clarification-handlers",
|
|
eventData,
|
|
)); err != nil {
|
|
h.logger.Warn("failed to publish primary clarification event",
|
|
zap.String("pending_id", pendingID),
|
|
zap.String("session_id", clarificationCtx.SessionID),
|
|
zap.Error(err))
|
|
}
|
|
}
|
|
|
|
type clarificationEventContext struct {
|
|
SessionID string
|
|
TaskID string
|
|
Question string
|
|
}
|
|
|
|
func (h *Handlers) resolveClarificationEventContext(ctx context.Context, pendingID string) (clarificationEventContext, error) {
|
|
var out clarificationEventContext
|
|
|
|
if req, ok := h.store.GetRequest(pendingID); ok && req != nil {
|
|
out.SessionID = req.SessionID
|
|
out.TaskID = req.TaskID
|
|
out.Question = req.Question.Prompt
|
|
}
|
|
|
|
if out.SessionID != "" && out.TaskID != "" && out.Question != "" {
|
|
return out, nil
|
|
}
|
|
if h.repo == nil {
|
|
return out, fmt.Errorf("message repository unavailable")
|
|
}
|
|
|
|
msg, err := h.repo.FindMessageByPendingID(ctx, pendingID)
|
|
if err != nil {
|
|
return out, err
|
|
}
|
|
if out.SessionID == "" {
|
|
out.SessionID = msg.TaskSessionID
|
|
}
|
|
if out.TaskID == "" {
|
|
out.TaskID = msg.TaskID
|
|
}
|
|
if out.Question == "" && msg.Metadata != nil {
|
|
if qData, ok := msg.Metadata["question"].(map[string]interface{}); ok {
|
|
if q, ok := qData["prompt"].(string); ok {
|
|
out.Question = q
|
|
}
|
|
}
|
|
}
|
|
|
|
return out, nil
|
|
}
|
|
|
|
// buildAnswerText constructs a human-readable answer text from the response.
|
|
func buildAnswerText(answer *Answer, rejected bool, rejectReason string) string {
|
|
if rejected {
|
|
if rejectReason != "" {
|
|
return fmt.Sprintf("User declined to answer. Reason: %s", rejectReason)
|
|
}
|
|
return "User declined to answer."
|
|
}
|
|
if answer == nil {
|
|
return "User provided no specific answer."
|
|
}
|
|
if answer.CustomText != "" {
|
|
return fmt.Sprintf("User answered: %s", answer.CustomText)
|
|
}
|
|
if len(answer.SelectedOptions) > 0 {
|
|
return fmt.Sprintf("User selected: %v", answer.SelectedOptions)
|
|
}
|
|
return "User provided no specific answer."
|
|
}
|
|
|
|
func generateOptionID(questionIndex, optionIndex int) string {
|
|
return fmt.Sprintf("q%d_opt%d", questionIndex+1, optionIndex+1)
|
|
}
|