848 lines
28 KiB
Go
848 lines
28 KiB
Go
// Package clarification provides types and services for agent clarification requests.
|
|
package clarification
|
|
|
|
import (
|
|
"context"
|
|
"errors"
|
|
"fmt"
|
|
"net/http"
|
|
"sort"
|
|
"strings"
|
|
|
|
"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"
|
|
)
|
|
|
|
// Metadata key constants used when constructing event payloads and reading
|
|
// per-message clarification metadata. Pulled out so goconst stays happy and
|
|
// renames stay safe.
|
|
const (
|
|
metaQuestionKey = "question"
|
|
metaQuestionIDKey = "question_id"
|
|
)
|
|
|
|
// 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)
|
|
FindMessagesByPendingID(ctx context.Context, pendingID string) ([]*taskmodels.Message, error)
|
|
FindPendingClarificationMessagesBySessionID(ctx context.Context, sessionID 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 {
|
|
// CreateClarificationRequestMessages creates one chat message per question in
|
|
// a multi-question clarification request, all sharing the given pending_id.
|
|
// Only the last message returned should set RequestsInput=true so the chat
|
|
// scrolls to the bottom of the group. Returns the created message IDs in the
|
|
// same order as the input questions.
|
|
CreateClarificationRequestMessages(ctx context.Context, taskID, sessionID, pendingID string, questions []Question, clarificationContext string) ([]string, error)
|
|
// UpdateClarificationMessage updates the per-question clarification message's
|
|
// status (and stores the matching answer if any) for a (pending_id, question_id)
|
|
// pair within the session.
|
|
UpdateClarificationMessage(ctx context.Context, sessionID, pendingID, questionID, 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)
|
|
api.POST("/:id/cancel", h.httpCancelRequest)
|
|
}
|
|
|
|
// CreateRequestBody is the request body for creating a clarification request.
|
|
// A single request may bundle 1..N questions; the bundle is gated on the user
|
|
// answering every question (or rejecting the bundle as a whole).
|
|
type CreateRequestBody struct {
|
|
SessionID string `json:"session_id" binding:"required"`
|
|
TaskID string `json:"task_id"`
|
|
Questions []Question `json:"questions" binding:"required,min=1,dive"`
|
|
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
|
|
}
|
|
|
|
if errMsg := NormalizeAndValidateQuestions(body.Questions); errMsg != "" {
|
|
c.JSON(http.StatusBadRequest, gin.H{"error": errMsg})
|
|
return
|
|
}
|
|
|
|
// 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,
|
|
Questions: body.Questions,
|
|
Context: body.Context,
|
|
}
|
|
|
|
pendingID, isNew := h.store.CreateRequest(req)
|
|
|
|
// Create one message per question in the database; all share the same
|
|
// pending_id and are rendered as a stacked group on the frontend. The
|
|
// session.message.added WebSocket event fires per message. On failure we
|
|
// also cancel the in-store pending entry so any blocking WaitForResponse
|
|
// caller unblocks immediately rather than waiting for the MCP timeout.
|
|
// When dedup fires (isNew=false) the messages already exist, so skip creation.
|
|
if isNew && h.messageCreator != nil {
|
|
_, err := h.messageCreator.CreateClarificationRequestMessages(
|
|
c.Request.Context(),
|
|
taskID,
|
|
sessionID,
|
|
pendingID,
|
|
body.Questions,
|
|
body.Context,
|
|
)
|
|
if err != nil {
|
|
h.logger.Error("failed to create clarification request messages",
|
|
zap.String("pending_id", pendingID),
|
|
zap.String("session_id", sessionID),
|
|
zap.Error(err))
|
|
h.store.CancelRequest(pendingID)
|
|
c.JSON(http.StatusInternalServerError, gin.H{
|
|
"error": "failed to create clarification messages: " + err.Error(),
|
|
})
|
|
return
|
|
}
|
|
}
|
|
|
|
c.JSON(http.StatusOK, CreateRequestResponse{PendingID: pendingID})
|
|
}
|
|
|
|
// NormalizeAndValidateQuestions is the single source of truth for clarification
|
|
// bundle validation. It mutates `questions` to assign missing IDs (q1, q2, ...)
|
|
// and option IDs, and enforces:
|
|
// - 1..4 questions per bundle
|
|
// - unique question IDs (rejects duplicates)
|
|
// - non-empty prompt
|
|
// - 2..6 options per question
|
|
//
|
|
// Both the HTTP handler (httpCreateRequest) and the WebSocket-side MCP handler
|
|
// (handleAskUserQuestion) call this so validation never drifts between paths.
|
|
// Returns "" on success or an error message describing the first failure.
|
|
func NormalizeAndValidateQuestions(questions []Question) string {
|
|
if len(questions) == 0 {
|
|
return "questions must contain at least 1 question"
|
|
}
|
|
if len(questions) > 4 {
|
|
return "questions must contain at most 4 questions"
|
|
}
|
|
seen := map[string]bool{}
|
|
for i := range questions {
|
|
if questions[i].ID == "" {
|
|
questions[i].ID = fmt.Sprintf("q%d", i+1)
|
|
}
|
|
if seen[questions[i].ID] {
|
|
return fmt.Sprintf("duplicate question id %q", questions[i].ID)
|
|
}
|
|
seen[questions[i].ID] = true
|
|
if questions[i].Prompt == "" {
|
|
return fmt.Sprintf("question %d is missing required 'prompt'", i+1)
|
|
}
|
|
if len(questions[i].Options) < 2 {
|
|
return fmt.Sprintf("question %d must have at least 2 options", i+1)
|
|
}
|
|
if len(questions[i].Options) > 6 {
|
|
return fmt.Sprintf("question %d must have at most 6 options", i+1)
|
|
}
|
|
for j := range questions[i].Options {
|
|
if questions[i].Options[j].ID == "" {
|
|
questions[i].Options[j].ID = generateOptionID(i, j)
|
|
}
|
|
}
|
|
}
|
|
return ""
|
|
}
|
|
|
|
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.
|
|
// The frontend posts every answer at once when the user finishes the bundle
|
|
// (decision A: per-question commit collected in the hook, batched on the wire).
|
|
// Answers must contain exactly one entry per question in the original request,
|
|
// or be empty when Rejected=true.
|
|
type RespondBody struct {
|
|
Answers []Answer `json:"answers"`
|
|
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
|
|
}
|
|
|
|
// Gate: when not rejecting, the user must have answered every question and
|
|
// each answer must reference a question id from the original bundle (no
|
|
// duplicates, no fabricated ids). We compare against the in-store request
|
|
// first; if the entry is gone (agent already moved on), fall back to the
|
|
// persisted messages so we still validate even after the in-memory cleanup.
|
|
if !body.Rejected {
|
|
if errMsg := h.validateRespondAnswers(c.Request.Context(), pendingID, body.Answers); errMsg != "" {
|
|
c.JSON(http.StatusBadRequest, gin.H{"error": errMsg})
|
|
return
|
|
}
|
|
}
|
|
|
|
resp := &Response{
|
|
PendingID: pendingID,
|
|
Answers: body.Answers,
|
|
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 answers directly.
|
|
h.applyAnswersToMessages(c, pendingID, body.Rejected, body.Answers)
|
|
h.publishPrimaryAnsweredEvent(c, pendingID, body.Answers, body.Rejected, body.RejectReason)
|
|
h.logger.Info("clarification answered via primary path (same turn)",
|
|
zap.String("pending_id", pendingID),
|
|
zap.Int("answers", len(body.Answers)),
|
|
zap.Bool("rejected", body.Rejected))
|
|
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 overlay is already detached (agent_disconnected, still pending), so
|
|
// dismissing it must not resume the agent with "User declined to answer".
|
|
// We still need to mark the bundle rejected in the DB; otherwise the durable
|
|
// pending-clarification guard would keep blocking future workflow transitions.
|
|
if body.Rejected {
|
|
writeCtx := context.WithoutCancel(c.Request.Context())
|
|
h.applyAnswersToMessages(c, pendingID, true, nil)
|
|
h.publishStaleDismissedEvent(writeCtx, pendingID)
|
|
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.applyAnswersToMessages(c, pendingID, body.Rejected, body.Answers)
|
|
h.respondViaEventFallback(c, pendingID, body.Answers, body.Rejected, body.RejectReason)
|
|
|
|
c.JSON(http.StatusOK, gin.H{"success": true})
|
|
}
|
|
|
|
// validateRespondAnswers enforces the all-required gate **and** the question-id
|
|
// invariant: every answer must target a real question in the bundle, every
|
|
// question must have an answer, and no question id may be answered twice.
|
|
// Returns "" on success or an error message describing the first failure.
|
|
//
|
|
// The expected question ids come from the in-store request; if the in-memory
|
|
// entry has already been cleaned up (agent timed out before user responded),
|
|
// the persisted messages serve as fallback so the late-respond path is
|
|
// validated the same way as the primary path.
|
|
func (h *Handlers) validateRespondAnswers(ctx context.Context, pendingID string, answers []Answer) string {
|
|
expected := h.expectedQuestionIDs(ctx, pendingID)
|
|
if len(expected) == 0 {
|
|
// Couldn't determine the expected set — fall back to permissive (the
|
|
// primary-path Respond will still error sensibly if the bundle is gone).
|
|
return ""
|
|
}
|
|
expectedSet := make(map[string]bool, len(expected))
|
|
for _, id := range expected {
|
|
expectedSet[id] = true
|
|
}
|
|
|
|
if len(answers) != len(expected) {
|
|
return fmt.Sprintf("expected %d answers, got %d", len(expected), len(answers))
|
|
}
|
|
|
|
seen := make(map[string]bool, len(answers))
|
|
for i, a := range answers {
|
|
if a.QuestionID == "" {
|
|
return fmt.Sprintf("answer %d is missing question_id", i+1)
|
|
}
|
|
if !expectedSet[a.QuestionID] {
|
|
return fmt.Sprintf("answer %d references unknown question id %q", i+1, a.QuestionID)
|
|
}
|
|
if seen[a.QuestionID] {
|
|
return fmt.Sprintf("answer %d duplicates question id %q", i+1, a.QuestionID)
|
|
}
|
|
seen[a.QuestionID] = true
|
|
}
|
|
return ""
|
|
}
|
|
|
|
// expectedQuestionIDs returns the ordered question ids the user is expected to
|
|
// answer for the given pending bundle. Falls back to the persisted messages if
|
|
// the in-store request has been cleaned up.
|
|
func (h *Handlers) expectedQuestionIDs(ctx context.Context, pendingID string) []string {
|
|
if req, ok := h.store.GetRequest(pendingID); ok && req != nil {
|
|
ids := make([]string, 0, len(req.Questions))
|
|
for _, q := range req.Questions {
|
|
ids = append(ids, q.ID)
|
|
}
|
|
return ids
|
|
}
|
|
if h.repo == nil {
|
|
return nil
|
|
}
|
|
msgs, err := h.repo.FindMessagesByPendingID(ctx, pendingID)
|
|
if err != nil || len(msgs) == 0 {
|
|
return nil
|
|
}
|
|
ids := make([]string, 0, len(msgs))
|
|
for _, m := range msgs {
|
|
if id := stringFromMetadata(m.Metadata, metaQuestionIDKey); id != "" {
|
|
ids = append(ids, id)
|
|
}
|
|
}
|
|
return ids
|
|
}
|
|
|
|
func (h *Handlers) httpCancelRequest(c *gin.Context) {
|
|
pendingID := c.Param("id")
|
|
req, ok := h.store.GetRequest(pendingID)
|
|
if !ok || req == nil {
|
|
c.JSON(http.StatusNotFound, gin.H{"error": "clarification request not found"})
|
|
return
|
|
}
|
|
if !h.store.CancelRequest(pendingID) {
|
|
c.JSON(http.StatusNotFound, gin.H{"error": "clarification request not found"})
|
|
return
|
|
}
|
|
|
|
if h.messageCreator != nil {
|
|
for _, q := range req.Questions {
|
|
if err := h.messageCreator.UpdateClarificationMessage(
|
|
c.Request.Context(),
|
|
req.SessionID,
|
|
pendingID,
|
|
q.ID,
|
|
string(StatusCancelled),
|
|
nil,
|
|
); err != nil {
|
|
h.logger.Warn("failed to mark clarification cancelled",
|
|
zap.String("pending_id", pendingID),
|
|
zap.String("question_id", q.ID),
|
|
zap.Error(err))
|
|
}
|
|
}
|
|
}
|
|
h.publishCancelledEvent(c, pendingID, req)
|
|
h.logger.Info("clarification cancelled by operator",
|
|
zap.String("pending_id", pendingID),
|
|
zap.String("session_id", req.SessionID),
|
|
zap.String("task_id", req.TaskID))
|
|
c.JSON(http.StatusOK, gin.H{"success": true})
|
|
}
|
|
|
|
// applyAnswersToMessages flips per-question status (answered/rejected) on every
|
|
// message that belongs to the bundle. When rejected, every question is marked
|
|
// rejected; when answered, each answer updates the matching question's row.
|
|
func (h *Handlers) applyAnswersToMessages(c *gin.Context, pendingID string, rejected bool, answers []Answer) {
|
|
if h.messageCreator == nil {
|
|
return
|
|
}
|
|
// Durable status writes must complete even if the HTTP request context is canceled.
|
|
writeCtx := context.WithoutCancel(c.Request.Context())
|
|
sessionID := h.lookupSessionForPendingCtx(writeCtx, pendingID)
|
|
|
|
if rejected {
|
|
// Mark every question in the bundle as rejected. Guard h.repo for
|
|
// parity with the sibling expectedQuestionIDs path; production wires
|
|
// both, but unit tests sometimes pass a nil repo.
|
|
if h.repo == nil {
|
|
return
|
|
}
|
|
msgs, err := h.repo.FindMessagesByPendingID(writeCtx, pendingID)
|
|
if err != nil || len(msgs) == 0 {
|
|
h.logger.Debug("rejected clarification: no messages to update",
|
|
zap.String("pending_id", pendingID),
|
|
zap.Error(err))
|
|
return
|
|
}
|
|
for _, msg := range msgs {
|
|
questionID := stringFromMetadata(msg.Metadata, "question_id")
|
|
if questionID == "" {
|
|
continue
|
|
}
|
|
if err := h.messageCreator.UpdateClarificationMessage(writeCtx, sessionID, pendingID, questionID, "rejected", nil); err != nil {
|
|
h.logger.Warn("failed to mark clarification question rejected",
|
|
zap.String("pending_id", pendingID),
|
|
zap.String("question_id", questionID),
|
|
zap.Error(err))
|
|
}
|
|
}
|
|
return
|
|
}
|
|
|
|
for i := range answers {
|
|
ans := answers[i]
|
|
if ans.QuestionID == "" {
|
|
continue
|
|
}
|
|
if err := h.messageCreator.UpdateClarificationMessage(writeCtx, sessionID, pendingID, ans.QuestionID, "answered", &ans); err != nil {
|
|
h.logger.Warn("failed to update clarification question",
|
|
zap.String("pending_id", pendingID),
|
|
zap.String("question_id", ans.QuestionID),
|
|
zap.Error(err))
|
|
}
|
|
}
|
|
}
|
|
|
|
func stringFromMetadata(meta map[string]any, key string) string {
|
|
if meta == nil {
|
|
return ""
|
|
}
|
|
if v, ok := meta[key].(string); ok {
|
|
return v
|
|
}
|
|
return ""
|
|
}
|
|
|
|
// 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, answers []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 := buildAnswerSummary(clarificationCtx.Questions, answers, rejected, rejectReason)
|
|
|
|
eventData := map[string]any{
|
|
"session_id": clarificationCtx.SessionID,
|
|
"task_id": clarificationCtx.TaskID,
|
|
"pending_id": pendingID,
|
|
metaQuestionKey: clarificationCtx.QuestionSummary,
|
|
"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))
|
|
}
|
|
|
|
func (h *Handlers) publishCancelledEvent(c *gin.Context, pendingID string, req *Request) {
|
|
if h.eventBus == nil || req == nil {
|
|
return
|
|
}
|
|
prompt := ""
|
|
if len(req.Questions) > 0 {
|
|
prompt = req.Questions[0].Prompt
|
|
}
|
|
eventData := map[string]any{
|
|
"session_id": req.SessionID,
|
|
"task_id": req.TaskID,
|
|
"pending_id": pendingID,
|
|
"question": prompt,
|
|
"answer_text": "The pending clarification question was cancelled by the operator.",
|
|
"rejected": true,
|
|
"reject_reason": "cancelled",
|
|
}
|
|
if err := h.eventBus.Publish(c.Request.Context(), events.ClarificationCancelled, bus.NewEvent(
|
|
events.ClarificationCancelled,
|
|
"clarification-handlers",
|
|
eventData,
|
|
)); err != nil {
|
|
h.logger.Error("failed to publish clarification cancelled event",
|
|
zap.String("pending_id", pendingID),
|
|
zap.String("session_id", req.SessionID),
|
|
zap.Error(err))
|
|
}
|
|
}
|
|
|
|
// lookupSessionForPendingCtx returns the session ID for a pending clarification.
|
|
// Falls back to finding it from the database message.
|
|
func (h *Handlers) lookupSessionForPendingCtx(ctx context.Context, pendingID string) string {
|
|
if req, ok := h.store.GetRequest(pendingID); ok {
|
|
return req.SessionID
|
|
}
|
|
if h.repo == nil {
|
|
return ""
|
|
}
|
|
msg, err := h.repo.FindMessageByPendingID(ctx, pendingID)
|
|
if err != nil {
|
|
return ""
|
|
}
|
|
return msg.TaskSessionID
|
|
}
|
|
|
|
func (h *Handlers) publishStaleDismissedEvent(ctx context.Context, pendingID string) {
|
|
if h.eventBus == nil {
|
|
return
|
|
}
|
|
clarificationCtx, err := h.resolveClarificationEventContext(ctx, pendingID)
|
|
if err != nil || clarificationCtx.SessionID == "" || clarificationCtx.TaskID == "" {
|
|
h.logger.Warn("failed to resolve context for stale-dismissed clarification event",
|
|
zap.String("pending_id", pendingID),
|
|
zap.Error(err))
|
|
return
|
|
}
|
|
eventData := map[string]any{
|
|
"session_id": clarificationCtx.SessionID,
|
|
"task_id": clarificationCtx.TaskID,
|
|
"pending_id": pendingID,
|
|
}
|
|
if err := h.eventBus.Publish(ctx, events.ClarificationStaleDismissed, bus.NewEvent(
|
|
events.ClarificationStaleDismissed,
|
|
"clarification-handlers",
|
|
eventData,
|
|
)); err != nil {
|
|
h.logger.Warn("failed to publish stale-dismissed clarification event",
|
|
zap.String("pending_id", pendingID),
|
|
zap.String("session_id", clarificationCtx.SessionID),
|
|
zap.Error(err))
|
|
}
|
|
}
|
|
|
|
func (h *Handlers) publishPrimaryAnsweredEvent(c *gin.Context, pendingID string, answers []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 := buildAnswerSummary(clarificationCtx.Questions, answers, rejected, rejectReason)
|
|
eventData := map[string]any{
|
|
"session_id": clarificationCtx.SessionID,
|
|
"task_id": clarificationCtx.TaskID,
|
|
"pending_id": pendingID,
|
|
metaQuestionKey: clarificationCtx.QuestionSummary,
|
|
"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
|
|
Questions []Question // Source-of-truth questions used to label answers; falls back to a single synthetic Question when only metadata is available.
|
|
QuestionSummary string // Pre-formatted multi-line "Q1: ...\nQ2: ..." used by the orchestrator resume prompt.
|
|
}
|
|
|
|
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.Questions = req.Questions
|
|
out.QuestionSummary = formatQuestionSummary(req.Questions)
|
|
if out.SessionID != "" && out.TaskID != "" && len(out.Questions) > 0 {
|
|
return out, nil
|
|
}
|
|
}
|
|
|
|
if h.repo == nil {
|
|
return out, fmt.Errorf("message repository unavailable")
|
|
}
|
|
|
|
msgs, err := h.repo.FindMessagesByPendingID(ctx, pendingID)
|
|
if err != nil {
|
|
return out, err
|
|
}
|
|
if len(msgs) == 0 {
|
|
return out, fmt.Errorf("no messages for pending_id %s", pendingID)
|
|
}
|
|
|
|
if out.SessionID == "" {
|
|
out.SessionID = msgs[0].TaskSessionID
|
|
}
|
|
if out.TaskID == "" {
|
|
out.TaskID = msgs[0].TaskID
|
|
}
|
|
if len(out.Questions) == 0 {
|
|
out.Questions = questionsFromMessages(msgs)
|
|
out.QuestionSummary = formatQuestionSummary(out.Questions)
|
|
}
|
|
|
|
return out, nil
|
|
}
|
|
|
|
// questionsFromMessages reconstructs a Question slice from persisted clarification
|
|
// messages, ordered by metadata.question_index so the rebuilt summary matches
|
|
// the bundle the agent originally sent. Used as a fallback when the in-store
|
|
// request has been cleaned up but the persisted metadata still carries the
|
|
// original question text.
|
|
func questionsFromMessages(msgs []*taskmodels.Message) []Question {
|
|
sorted := make([]*taskmodels.Message, len(msgs))
|
|
copy(sorted, msgs)
|
|
sort.SliceStable(sorted, func(i, j int) bool {
|
|
return questionIndexFromMetadata(sorted[i].Metadata) < questionIndexFromMetadata(sorted[j].Metadata)
|
|
})
|
|
out := make([]Question, 0, len(sorted))
|
|
for _, m := range sorted {
|
|
out = append(out, questionFromMessageMetadata(m.Metadata))
|
|
}
|
|
return out
|
|
}
|
|
|
|
func questionIndexFromMetadata(meta map[string]any) int {
|
|
if meta == nil {
|
|
return 0
|
|
}
|
|
switch v := meta["question_index"].(type) {
|
|
case int:
|
|
return v
|
|
case int64:
|
|
return int(v)
|
|
case float64:
|
|
return int(v)
|
|
}
|
|
return 0
|
|
}
|
|
|
|
func questionFromMessageMetadata(meta map[string]any) Question {
|
|
q := Question{ID: stringFromMetadata(meta, metaQuestionIDKey)}
|
|
qData, ok := meta[metaQuestionKey].(map[string]any)
|
|
if !ok {
|
|
return q
|
|
}
|
|
if v, ok := qData["prompt"].(string); ok {
|
|
q.Prompt = v
|
|
}
|
|
if v, ok := qData["title"].(string); ok {
|
|
q.Title = v
|
|
}
|
|
if q.ID == "" {
|
|
if v, ok := qData["id"].(string); ok {
|
|
q.ID = v
|
|
}
|
|
}
|
|
return q
|
|
}
|
|
|
|
func formatQuestionSummary(questions []Question) string {
|
|
if len(questions) == 0 {
|
|
return ""
|
|
}
|
|
if len(questions) == 1 {
|
|
return questions[0].Prompt
|
|
}
|
|
parts := make([]string, 0, len(questions))
|
|
for i, q := range questions {
|
|
parts = append(parts, fmt.Sprintf("Q%d: %s", i+1, q.Prompt))
|
|
}
|
|
return strings.Join(parts, "\n")
|
|
}
|
|
|
|
// buildAnswerSummary constructs a human-readable summary of the user's response
|
|
// across every question in the bundle. Used in the orchestrator resume prompt
|
|
// and for chat history rendering.
|
|
func buildAnswerSummary(questions []Question, answers []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 len(answers) == 0 {
|
|
return "User provided no specific answer."
|
|
}
|
|
if len(questions) <= 1 && len(answers) == 1 {
|
|
return formatSingleAnswer(answers[0])
|
|
}
|
|
|
|
answersByID := make(map[string]Answer, len(answers))
|
|
for _, a := range answers {
|
|
answersByID[a.QuestionID] = a
|
|
}
|
|
|
|
parts := make([]string, 0, len(answers))
|
|
for i, q := range questions {
|
|
ans, ok := answersByID[q.ID]
|
|
if !ok {
|
|
continue
|
|
}
|
|
parts = append(parts, fmt.Sprintf("A%d: %s", i+1, formatAnswerBody(ans)))
|
|
}
|
|
if len(parts) == 0 {
|
|
// No matches by id — fall back to positional formatting so we still
|
|
// surface the answers rather than silently dropping them.
|
|
for i, a := range answers {
|
|
parts = append(parts, fmt.Sprintf("A%d: %s", i+1, formatAnswerBody(a)))
|
|
}
|
|
}
|
|
return strings.Join(parts, "\n")
|
|
}
|
|
|
|
func formatSingleAnswer(a Answer) string {
|
|
if a.CustomText != "" {
|
|
return fmt.Sprintf("User answered: %s", a.CustomText)
|
|
}
|
|
if len(a.SelectedOptions) > 0 {
|
|
return fmt.Sprintf("User selected: %v", a.SelectedOptions)
|
|
}
|
|
return "User provided no specific answer."
|
|
}
|
|
|
|
func formatAnswerBody(a Answer) string {
|
|
if a.CustomText != "" {
|
|
return a.CustomText
|
|
}
|
|
if len(a.SelectedOptions) > 0 {
|
|
return fmt.Sprintf("%v", a.SelectedOptions)
|
|
}
|
|
return "(no answer)"
|
|
}
|
|
|
|
func generateOptionID(questionIndex, optionIndex int) string {
|
|
return fmt.Sprintf("q%d_opt%d", questionIndex+1, optionIndex+1)
|
|
}
|