252 lines
8.5 KiB
Go
252 lines
8.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 human 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 human 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 human'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 human'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 human's chosen option.
|
|
type PickerRequester interface {
|
|
// RequestChoice shows req and returns the option the human 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)
|
|
}
|
|
|
|
// 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 human 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: human reply was empty")
|
|
|
|
// ErrTextFallbackNotConfigured is returned when a TextFallback is used
|
|
// without both transport halves. It is a construction defect, surfaced
|
|
// rather than panicking inside a turn.
|
|
ErrTextFallbackNotConfigured = errors.New("interactive: text fallback is missing Send or Reply")
|
|
)
|
|
|
|
// ClarifierOf returns sender's ClarifyRequester when it reports the Clarify
|
|
// capability and implements the interface.
|
|
func ClarifierOf(sender any) (ClarifyRequester, bool) {
|
|
if !CapabilitiesOf(sender).Clarify {
|
|
return nil, false
|
|
}
|
|
clarifier, ok := sender.(ClarifyRequester)
|
|
return clarifier, ok
|
|
}
|
|
|
|
// PickerOf returns sender's PickerRequester only when sender reports the
|
|
// Picker capability, with the same capability-over-method-set rule as
|
|
// ClarifierOf.
|
|
func PickerOf(sender any) (PickerRequester, bool) {
|
|
if !CapabilitiesOf(sender).Picker {
|
|
return nil, false
|
|
}
|
|
picker, ok := sender.(PickerRequester)
|
|
return picker, ok
|
|
}
|
|
|
|
// Interactive holds the interaction requesters a channel supports for one
|
|
// turn. The zero value supports none.
|
|
type Interactive struct {
|
|
Clarifier ClarifyRequester
|
|
Picker PickerRequester
|
|
}
|
|
|
|
// Carries reports whether the adapter can carry at least one interaction.
|
|
func (i Interactive) Carries() bool { return i.Clarifier != nil || i.Picker != nil }
|
|
|
|
// InteractiveOf resolves sender into the requesters it can carry, trusting the
|
|
// capability report over the method set through ClarifierOf and PickerOf. A
|
|
// sender that implements a method but denies the capability contributes
|
|
// nothing, so a mis-reporting adapter degrades instead of being called.
|
|
func InteractiveOf(sender any) Interactive {
|
|
clarifier, _ := ClarifierOf(sender)
|
|
picker, _ := PickerOf(sender)
|
|
return Interactive{Clarifier: clarifier, Picker: picker}
|
|
}
|
|
|
|
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 human 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
|
|
}
|
|
|
|
// FormatClarifyText renders a ClarifyRequest as a plain-text prompt for a
|
|
// channel with no native question UI.
|
|
func FormatClarifyText(req ClarifyRequest) string {
|
|
var b strings.Builder
|
|
b.WriteString(strings.TrimSpace(req.Question))
|
|
if len(req.Suggestions) > 0 {
|
|
b.WriteString("\n\nSuggestions:")
|
|
for i, s := range req.Suggestions {
|
|
fmt.Fprintf(&b, "\n%d) %s", i+1, s.Label)
|
|
}
|
|
}
|
|
b.WriteString("\n\nReply with your answer.")
|
|
return b.String()
|
|
}
|
|
|
|
// 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 human'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 human 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
|
|
}
|
|
|
|
// TextFallback asks clarify and picker questions as plain text and reads the
|
|
// typed reply.
|
|
type TextFallback struct {
|
|
Send func(ctx context.Context, text string) error
|
|
Reply func(ctx context.Context) (string, error)
|
|
}
|
|
|
|
// Compile-time guards.
|
|
var (
|
|
_ ClarifyRequester = (*TextFallback)(nil)
|
|
_ PickerRequester = (*TextFallback)(nil)
|
|
)
|
|
|
|
// RequestClarification sends the rendered question and returns the human's
|
|
// trimmed answer.
|
|
func (f *TextFallback) RequestClarification(ctx context.Context, req ClarifyRequest) (string, error) {
|
|
if err := f.ready(); err != nil {
|
|
return "", err
|
|
}
|
|
if err := f.Send(ctx, FormatClarifyText(req)); err != nil {
|
|
return "", err
|
|
}
|
|
answer, err := f.Reply(ctx)
|
|
if err != nil {
|
|
return "", err
|
|
}
|
|
answer = strings.TrimSpace(answer)
|
|
if answer == "" {
|
|
return "", ErrEmptyReply
|
|
}
|
|
return answer, nil
|
|
}
|
|
|
|
// RequestChoice sends the rendered options and returns the option the human
|
|
// selected. A reply that matches no option is an error rather than a
|
|
// zero-value guess.
|
|
func (f *TextFallback) RequestChoice(ctx context.Context, req PickerRequest) (InteractiveChoice, error) {
|
|
if len(req.Options) == 0 {
|
|
return InteractiveChoice{}, ErrNoPickerOptions
|
|
}
|
|
if err := f.ready(); err != nil {
|
|
return InteractiveChoice{}, err
|
|
}
|
|
if err := f.Send(ctx, FormatPickerText(req)); err != nil {
|
|
return InteractiveChoice{}, err
|
|
}
|
|
reply, err := f.Reply(ctx)
|
|
if err != nil {
|
|
return InteractiveChoice{}, err
|
|
}
|
|
choice, ok := ParsePickerReply(req, reply)
|
|
if !ok {
|
|
return InteractiveChoice{}, fmt.Errorf("interactive: reply %q does not match any offered option", strings.TrimSpace(reply))
|
|
}
|
|
return choice, nil
|
|
}
|
|
|
|
// ready reports whether both transport halves are present before any send is
|
|
// attempted, so a half-built fallback fails at the call rather than
|
|
// mid-interaction.
|
|
func (f *TextFallback) ready() error {
|
|
if f == nil || f.Send == nil || f.Reply == nil {
|
|
return ErrTextFallbackNotConfigured
|
|
}
|
|
return nil
|
|
}
|