Files
archie/internal/domain/messaging/interactive.go
T
sam c5f24ec914 chore: delete code no binary reaches
Removes the Kit task-tool result shim (and with it the MCP go-sdk
dependency), the messaging enable/disable/restart helpers and channel
rebuild closures nothing calls since channels became extensions, the
unused messaging capability, ephemeral and text-fallback types, and
single stragglers in telemetry, releaseupdate, skill, storepkg and
webui. The egress sandbox relay stays for #1867.
2026-11-13 03:33:32 +11:00

224 lines
7.5 KiB
Go

package messaging
import (
"context"
"errors"
"fmt"
"strconv"
"strings"
)
// InteractiveChoice is one option in a clarify or picker prompt. Callers
// match on ID.
type InteractiveChoice struct {
ID string
Label string
}
// ClarifyRequest asks a user a question the agent cannot answer itself.
// Suggestions are optional quick replies; a channel with no button UI may
// render them as hint text and accept a typed answer instead.
type ClarifyRequest struct {
Question string
Suggestions []InteractiveChoice
}
// PickerRequest asks a user to select exactly one of Options.
type PickerRequest struct {
Prompt string
Options []InteractiveChoice
}
// ClarifyRequester is the optional interface an adapter implements to pose a
// clarifying question and block for the user's answer. It is the interactive
// counterpart of ApprovalRequester: an adapter that cannot render a native
// question UI fulfils it with the text fallback rather than failing the turn.
type ClarifyRequester interface {
// RequestClarification shows req and returns the user's free-text
// answer. The returned string is the trimmed answer, never empty when
// err is nil.
RequestClarification(ctx context.Context, req ClarifyRequest) (string, error)
}
// PickerRequester is the optional interface an adapter implements to present
// a single-choice selection and block for the user's chosen option.
type PickerRequester interface {
// RequestChoice shows req and returns the option the user picked. A
// request with no options cannot be answered and returns
// ErrNoPickerOptions rather than an empty choice.
RequestChoice(ctx context.Context, req PickerRequest) (InteractiveChoice, error)
}
// QuestionChoice is one option of a Question. Callers match on Value.
type QuestionChoice struct {
Value string
Label string
Description string
}
// Question is one step of a questionnaire. Choices may be empty, which makes
// it a free-text question; AllowOther lets the user answer outside Choices.
type Question struct {
Name string
Title string
Description string
Multiple bool
Required bool
AllowOther bool
Choices []QuestionChoice
}
// QuestionnaireRequest asks a user several questions in one interaction.
type QuestionnaireRequest struct {
Questions []Question
}
// QuestionnaireAnswers maps a question name to the values the user gave. A
// question the user skipped is absent.
type QuestionnaireAnswers map[string][]string
// QuestionnaireRequester is the optional interface an adapter implements to
// pose a questionnaire and block for the user's answers.
type QuestionnaireRequester interface {
// RequestAnswers shows req and returns the validated answers, which are
// checked with CheckAnswers before they leave the adapter.
RequestAnswers(ctx context.Context, req QuestionnaireRequest) (QuestionnaireAnswers, error)
}
// CheckAnswers returns raw as the questionnaire's answers when they are ones
// req could have produced: only its question names, one value for a question
// that is not multiple, a value outside Choices only where AllowOther, and
// none missing for a required question. Empty values are dropped, so a skipped
// question is absent.
func CheckAnswers(req QuestionnaireRequest, raw map[string][]string) (QuestionnaireAnswers, error) {
known := make(map[string]Question, len(req.Questions))
for _, q := range req.Questions {
known[q.Name] = q
}
for name := range raw {
if _, ok := known[name]; !ok {
return nil, fmt.Errorf("interactive: answer for unknown question %q", name)
}
}
out := QuestionnaireAnswers{}
for _, q := range req.Questions {
var values []string
for _, v := range raw[q.Name] {
if v = strings.TrimSpace(v); v != "" {
values = append(values, v)
}
}
if len(values) == 0 {
if q.Required {
return nil, fmt.Errorf("interactive: question %q is required", q.Name)
}
continue
}
if len(values) > 1 && !q.Multiple {
return nil, fmt.Errorf("interactive: question %q takes one answer", q.Name)
}
for _, v := range values {
if !q.AllowOther && len(q.Choices) > 0 && !hasChoice(q.Choices, v) {
return nil, fmt.Errorf("interactive: %q is not a choice of question %q", v, q.Name)
}
}
out[q.Name] = values
}
return out, nil
}
func hasChoice(choices []QuestionChoice, value string) bool {
for _, c := range choices {
if c.Value == value {
return true
}
}
return false
}
// Interactive sentinel errors, matched with errors.Is.
var (
// ErrNoPickerOptions is returned when a picker is asked to present an
// empty option set: there is nothing to select, so the caller must
// decide what to do (fall back, or ask a different question) rather
// than receive a zero InteractiveChoice that looks like a valid answer.
ErrNoPickerOptions = errors.New("interactive: picker has no options")
// ErrEmptyReply is returned when a user submits no answer. An empty
// string is not an answer to a question, so it must not be mistaken
// for one by a caller that only checks err.
ErrEmptyReply = errors.New("interactive: reply was empty")
)
// Interactive holds the interaction requesters a channel supports for one
// turn. The zero value supports none.
type Interactive struct {
Clarifier ClarifyRequester
Picker PickerRequester
Questioner QuestionnaireRequester
}
// Carries reports whether the adapter can carry at least one interaction.
func (i Interactive) Carries() bool {
return i.Clarifier != nil || i.Picker != nil || i.Questioner != nil
}
type interactiveCtxKey struct{}
// WithInteractive stores a channel's interactive requesters on ctx for one
// turn, the way WithApprovalRequester stores consent. The gateway turn reads
// it to know whether it can ask the user a question.
func WithInteractive(ctx context.Context, i Interactive) context.Context {
return context.WithValue(ctx, interactiveCtxKey{}, i)
}
// InteractiveFromContext returns the requesters stored on ctx, or the zero
// value when the turn's channel cannot carry an interaction.
func InteractiveFromContext(ctx context.Context) Interactive {
i, _ := ctx.Value(interactiveCtxKey{}).(Interactive)
return i
}
// FormatPickerText renders a PickerRequest as a numbered plain-text prompt
// for a channel with no native selection UI.
func FormatPickerText(req PickerRequest) string {
var b strings.Builder
b.WriteString(strings.TrimSpace(req.Prompt))
if len(req.Options) == 0 {
b.WriteString("\n\nNo options were offered.")
return b.String()
}
b.WriteString("\n")
for i, o := range req.Options {
fmt.Fprintf(&b, "\n%d) %s", i+1, o.Label)
}
b.WriteString("\n\nReply with the number of your choice.")
return b.String()
}
// ParsePickerReply maps a user's typed reply to one of req's options. It
// accepts a 1-based index or an exact ID or Label, case-insensitively.
// ok is false when the reply matches nothing, so the caller re-prompts rather
// than guessing an option the user did not choose.
func ParsePickerReply(req PickerRequest, reply string) (InteractiveChoice, bool) {
trimmed := strings.TrimSpace(reply)
if trimmed == "" {
return InteractiveChoice{}, false
}
if n, err := strconv.Atoi(trimmed); err == nil {
if n >= 1 && n <= len(req.Options) {
return req.Options[n-1], true
}
// A numeric reply is an index and nothing else: a label that
// happens to look like a number must not rescue an out-of-range
// selection.
return InteractiveChoice{}, false
}
for _, opt := range req.Options {
if strings.EqualFold(opt.ID, trimmed) || strings.EqualFold(opt.Label, trimmed) {
return opt, true
}
}
return InteractiveChoice{}, false
}